Getting started with the Template

From a fresh clone of the Roblox Template to pressing Play in Studio, then turning the copy into a new game with lune run init, the new-game skill and its feature switches.

Roblox Template / The Roblox Template

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

  1. Install the tools

    From the repository root, rokit install. It installs everything pinned in rokit.toml: rojo, wally, lune, asphalt, stylua, selene, luau-lsp, wally-package-types, rbxcloud, luau, gitleaks and actionlint.

  2. Install the packages

    lune run install: the Wally packages, the sourcemap and the package types. It also switches on .githooks, whose commit-msg hook checks every commit message.

  3. Ask doctor what is missing

    lune run doctor prints one line per check (every tool in rokit.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.

  4. Install the Studio plugin

    rojo plugin install installs the Rojo plugin that matches the pinned Rojo.

  5. Serve the project

    rojo serve. Then in Studio open the development place (or a blank baseplate), choose Plugins, Rojo, Connect, and press Play.

  6. 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.

Shell
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 Play
From a fresh clone to Play. rokit install puts every pinned tool on the machine. lune run install fetches the Wally packages, writes the sourcemap and package types and switches on the commit hook. lune run doctor reports anything still missing. rojo plugin install adds the matching Studio plugin. rojo serve syncs src into Studio, where Rojo Connect and Play start the game.

What 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

CommandDoes
rojo serveSyncs src/ into Studio while you work
lune run checkThe 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 formatFormats all Luau
lune run build · lune run treeBuilds 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 installAgain 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:

Shell
lune run new-game -- --name "Rocket Run" --slug rocket-run

It 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.

  1. Name it

    lune run init, or lune run init -- --name "My Game" --slug my-game --scope blockoutgames. It refuses to run while the checkout's origin is the Template itself. It renames the Rojo project, the Wally package, the game's name (in Config/Overrides/Game.luau) and the titles of README.md and docs/Home.md, and starts the game's own release history: an empty CHANGELOG.md, version 0.0.0 in Config/Overrides/Game.luau with release-please's marker, release-please-config.json pointed there and the Template's pinned release-as removed, 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 the Template adopted card, 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 in ARCHITECTURE.md Decisions; the game's own records go in docs/decisions/, numbered from 001. Running it again never touches the game's own changelog, board or cards. Then lune run install, so wally.lock matches the new package name.

  2. Say what the game is

    Fill docs/product/Game Overview.md (the loop, the player, why it is fun) and docs/product/MVP Scope.md (what V1 contains and does not). Agents do not invent product decisions.

  3. 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.live and places.main.testing), the universe id in universeId; lune run new-game writes them. Once a place exists, add servePlaceIds to its project file so Rojo refuses to sync into any other place.

  4. 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.

  5. Sync the assets

    Put the studio's Asphalt key in a git-ignored .env (ASPHALT_API_KEY=...), run lune run assets -- sync, and commit asphalt.lock.toml and the regenerated src/core/shared/assets.luau. The loading screen switches from the 3D fallback cube to the rendered sprite sheets once they have ids.

  6. Set up the repository

    Push to a new GitHub repository. main takes pull requests only, squash-merged with the check workflow 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. Add ROBLOX_API_KEY and ASPHALT_API_KEY as Actions secrets when publishing from CI is wanted; a local lune run publish reads ROBLOX_API_KEY from the environment or the git-ignored .env.

  7. Do the first card

    docs/Board.md starts with the Template adopted card. What the game inherits is ARCHITECTURE.md Decisions; the game's own records start at 001 in docs/decisions/, each a row in its README.md (the adr skill), and one that changes an inherited decision also updates its line in Decisions.

  8. Check

    lune run doctor, then lune run check and lune run build must 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.

Shell
lune run template-update           # the newest releaselune run template-update -- 0.4.0  # or one release

It 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

SymptomFix
rokit, rojo or lune: command not foundRokit's bin folder is not on PATH yet: open a new terminal
Failed to find tool 'rojo' in any project manifestRun commands from the repository root, after rokit install
Studio refuses to connect: version mismatchrojo 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 checkThe same: the package types were not generated
The loading screen cube has no edge highlightsIt is the 3D fallback; the sprite sheets are not uploaded yet: lune run assets -- sync
[Loader] X.init yieldedMove the waiting into start() (Services)

Updated