You need Git, Rokit and Roblox Studio. Rokit installs every other tool at its pinned version; four commands later the Template is running in Studio. Code is never edited in Studio: Rojo overwrites Studio's copy of every script from src/, so an edit made there is lost on the next sync. The place itself (the map, lighting, models built by hand) does live in Studio.
What to install once
- Git
From git-scm.com.
- Rokit
Installs every other tool, from github.com/rojo-rbx/rokit.
- Roblox Studio
From create.roblox.com, with the Rojo plugin (installed below).
- VS Code
Opens with the right extensions suggested (
.vscode/extensions.json). Format on save is on.- Obsidian
Optional, for the
docs/vault; Markdown reads anywhere.- GitHub CLI (gh)
Optional, for opening pull requests from the terminal.
- Python 3 with Pillow and NumPy
Optional, only to regenerate the brand sprites, placeholder icons, and the interface and effect sounds and images in
tools/.
From a fresh clone to Play
Install the tools
From the repository root,
rokit install. It installs everything pinned inrokit.toml: rojo, wally, lune, asphalt, stylua, selene, luau-lsp, wally-package-types, rbxcloud, luau, gitleaks and actionlint.Install the packages
lune run install: the Wally packages, the sourcemap and the package types. It also switches on.githooks, whosecommit-msghook checks every commit message.Ask doctor what is missing
lune run doctorprints one line per check (every tool inrokit.toml, git, the GitHub CLI and the commit message hook, generated files, secrets, the game's ids, and in a game whether a newer Template release is out) as ok, warn or FAIL, and exits non-zero when something required is missing.Install the Studio plugin
rojo plugin installinstalls the Rojo plugin that matches the pinned Rojo.Serve the project
rojo serve. Then in Studio open the development place (or a blank baseplate), choose Plugins, Rojo, Connect, and press Play.Check the stack works
The loading screen shows the brand, then the HUD. Pressing Tap for a coin exercises the whole stack (Rojo, packages, remotes, saving, sync, Fusion, toasts). The full smoke test is the Template's
docs/testing/Playtest Checklist.md.
rokit install # every tool, pinned in rokit.tomllune run install # Wally packages and their types; switches on .githookslune run doctor # tells you what is still missingrojo plugin install # the Studio plugin, matching the pinned Rojorojo serve # then Rojo, Connect in Studio, and press PlayWhat you can do in Studio on the first Play
In Studio everyone gets the role in Config/Admin.studioRole (developer by default), so the staff tools work without a group rank: press ; for the admin console, or click the red shield in the top bar for the admin panel.
To open a place other than the start place, build it (lune run build training, then open build/game-training.rbxl) or serve its project (rojo serve training.project.json). Teleports do not work in Studio; TravelService refuses with reason studio.
The commands you use every day
| Command | Does |
|---|---|
rojo serve | Syncs src/ into Studio while you work |
lune run check | The whole verification pass, the same one CI runs |
lune run test [pattern] [flags] | Only the specs; flags such as --changed, --tag and --bail |
lune run format | Formats all Luau |
lune run build · lune run tree | Builds every place and checks its streaming rules · prints a build's instance tree |
lune run new -- <kind> <Name> | Scaffolds a module in the house pattern |
lune run install · rokit install | Again after wally.toml or rokit.toml changes |
Every command is on Testing and tooling.
Starting a new game from the Template
A new game is a copy of the repository, renamed and filled in once. From a checkout of the Template, one command does most of it:
lune run new-game -- --name "Rocket Run" --slug rocket-runIt creates the game's private repository from the Template with gh, clones it to ../rocket-run, names it, writes any Roblox ids you pass (--universe, --live, --testing), runs install and check, commits and pushes, creates the labels, offers to set the ROBLOX_API_KEY secret and to protect main, runs doctor, and numbers what only a person can still do. Run it again with the ids once the places exist: finished steps are skipped, and a failure says which step stopped and the command to resume.
The new-game skill is the full procedure; these are its steps by hand.
Name it
lune run init, orlune run init -- --name "My Game" --slug my-game --scope blockoutgames. It refuses to run while the checkout'soriginis the Template itself. It renames the Rojo project, the Wally package, the game's name (inConfig/Overrides/Game.luau) and the titles ofREADME.mdanddocs/Home.md, and starts the game's own release history: an emptyCHANGELOG.md, version 0.0.0 inConfig/Overrides/Game.luauwith release-please's marker,release-please-config.jsonpointed there and the Template's pinnedrelease-asremoved, so the game's first release is 0.1.0. It records the Template release the game started from in.template-version, the base of every later update (below), with a second line,tree <sha>, for the tree of a fresh one-commit copy. The Template ships an empty board and no cards, plans or decision records; init writes the starter board (its setup lines in Backlog) and theTemplate adoptedcard, and drops the Template-only Handbook section from the pull request template. System and engineering notes and skills stay. The Template's decisions are one line each inARCHITECTURE.mdDecisions; the game's own records go indocs/decisions/, numbered from001. Running it again never touches the game's own changelog, board or cards. Thenlune run install, sowally.lockmatches the new package name.Say what the game is
Fill
docs/product/Game Overview.md(the loop, the player, why it is fun) anddocs/product/MVP Scope.md(what V1 contains and does not). Agents do not invent product decisions.Create the experience on Roblox
A person, in the Creator Dashboard: the experience (group-owned when possible), a live place and a testing place. Their ids go in the game's
Config/Overrides/Game.luau(places.main.liveandplaces.main.testing), the universe id inuniverseId;lune run new-gamewrites them. Once a place exists, addservePlaceIdsto its project file so Rojo refuses to sync into any other place.Choose the systems
Turn on the systems the game uses in its
Config/Overrides/Features.luau;lune run modules -- --enable <name>previews a selection and names what it also needs. See Config and features.Sync the assets
Put the studio's Asphalt key in a git-ignored
.env(ASPHALT_API_KEY=...), runlune run assets -- sync, and commitasphalt.lock.tomland the regeneratedsrc/core/shared/assets.luau. The loading screen switches from the 3D fallback cube to the rendered sprite sheets once they have ids.Set up the repository
Push to a new GitHub repository.
maintakes pull requests only, squash-merged with thecheckworkflow green; protect it where GitHub allows (a public repository, or a paid plan for a private one), and elsewhere the process and the hooks hold the rule. No approval count is needed: a solo developer reviews their own pull request with the reviewer agents. AddROBLOX_API_KEYandASPHALT_API_KEYas Actions secrets when publishing from CI is wanted; a locallune run publishreadsROBLOX_API_KEYfrom the environment or the git-ignored.env.Do the first card
docs/Board.mdstarts with the Template adopted card. What the game inherits isARCHITECTURE.mdDecisions; the game's own records start at001indocs/decisions/, each a row in itsREADME.md(theadrskill), and one that changes an inherited decision also updates its line in Decisions.Check
lune run doctor, thenlune run checkandlune run buildmust pass before the first commit.
More than one place (a lobby and an arena)? lune run new -- place <Name> for each, an entry in Game.places, and ids on both tiers. A game with one place turns Features.travel off. Each of these is the game's own setting, in its Config/Overrides/ (Config and features).
Taking Template updates
A game is a copy of the Template, not a fork, so new Template releases come in with one command. lune run doctor says when one is out.
lune run template-update # the newest releaselune run template-update -- 0.4.0 # or one releaseIt prints the Template's changelog since the version in .template-version: breaking changes first, each with the steps from its note in the Template's docs/upgrading/, then everything else. Then it merges the Template's changes between the two releases on a new chore/template-<version> branch and commits them. It is a three-way merge whose base is the recorded release, so the game's own edits stay. A game's first update merges from the Template commit whose tree matches the tree line init wrote, then the record holds only the release. The Template's changes to paths the game owns (CHANGELOG.md, the board, cards, planning, product and release notes, and its settings in Config/Overrides/, the game's version among them) are skipped. A file the game deleted (the demo, after delete-demo) stays deleted: the Template's changes to it, and new files inside a folder the game removed, are left out and counted. A new Config module's empty overrides file arrives with it.
A game that started before v1.0.0 follows the Template's docs/upgrading/v1.0.0.md once: renamed modules (Rules/Currencies, Device, Util/Scheduler), Http, MemoryStore and MessagingBus moved to server/Roblox/, its version moved into Config/Overrides/Game.luau, the Template's decision records removed (each now a line in ARCHITECTURE.md Decisions), one reward shape, products granted from config with a Robux store, server-only anti-cheat, staff guard and referral settings, live config listing no key, the admin suite moved to src/core/admin/, player reports removed, and Feedback opened from the top bar.
A conflict is listed by path with the side that owns it. A template path (src/core/ but the overrides, .lune/, .github/, skills, engineering notes) usually takes the Template's side; a shared path (the README, the game's own code) keeps the game's values and the Template's new parts. Resolve, git add, commit with the message it prints, do the breaking changes' steps, then lune run install, lune run check, play it and open a pull request.
A game that predates the command has no .template-version: write the Template version it started from (the top of the Template's CHANGELOG.md when it was copied) into it and commit.
Fixing a setup that does not work
| Symptom | Fix |
|---|---|
rokit, rojo or lune: command not found | Rokit's bin folder is not on PATH yet: open a new terminal |
Failed to find tool 'rojo' in any project manifest | Run commands from the repository root, after rokit install |
| Studio refuses to connect: version mismatch | rojo plugin install, delete any other Rojo.rbxm in the plugins folder, restart Studio |
Red squiggles on require(ReplicatedStorage.Packages…) | lune run install (packages, sourcemap, package types) |
Unknown type 'Fusion.Scope' in lune run check | The same: the package types were not generated |
| The loading screen cube has no edge highlights | It is the 3D fallback; the sprite sheets are not uploaded yet: lune run assets -- sync |
[Loader] X.init yielded | Move the waiting into start() (Services) |
Where each kind of code goes, and why.
Write your first service.
Updated