GAMENIGHT / DOCUMENTATION
Game playbook
How to go from an idea to a game in the GameNight store quickly. It is written for AI coding agents as much as for people: every step can run headless, from the command line, without someone watching the screen.
Start from the template
git clone https://github.com/ontola/gamenight
python3 gamenight/scripts/new-godot-game.py my-game my-game "My Game"
cd my-game && git init && git add -A && git commit -m "Start My Game"
You get a small, working Godot 4 couch game with:
| Part | What it does |
|---|---|
main.gd |
the game: GameNight lifecycle, seats, faces, settings and a Start menu, bots, dev flags |
gamenight.json |
the game's metadata: title, tagline, developer, players, tags; the only place you edit them |
tests/lifecycle.py |
a fake GameNight host drives prepare, start, controller input, pause, resume, dispose |
tools/capture_preview.sh, tools/encode_preview.py |
the five-second store clip, frame by frame |
.github/workflows/ci.yml |
tests, Windows export, release, store page |
AGENTS.md |
the commands and rules for whoever works on it next |
The GameNight addon is installed from the SDK. CI fails when your copy falls
behind; run python3 gamenight/sdk/godot/sync.py my-game to update it.
Keep one repository per game.
Replace the orb game with yours one step at a time, and keep the tests green after every step. Other engines work too (see Engine support), but only the Godot template exists so far.
The loop
Run all three after every change:
godot --headless --import # parse errors
godot --headless --fixed-fps 60 --path . -- --sim 4000 --seed 1 # bots play a round
python3 tests/lifecycle.py --godot godot # GameNight host
- Import first. A GDScript parse error makes later headless runs hang
instead of failing. Look for
SCRIPT ERRORorParse Error. - Bots play the real game. The sim counts what happened (dashes, pickups, rounds) and fails when something never did. Add a counter for every mechanic you build, so a broken mechanic fails CI.
- The fake host checks what players notice. Extend
tests/lifecycle.pyfor each control: send controller frames, wait for the trace line.
Put rules that need many cases (damage tables, combinations) in plain
scripts and test them with godot --headless --script.
Make it deterministic from day one
Seed the global RNG once from --seed and move the simulation only in
_physics_process. With --fixed-fps, the same seed then replays the same
run: the template's sim prints a state hash, and its store clip comes out
bit for bit the same. A second unseeded RandomNumberGenerator, or gameplay
that reads the clock, breaks this quietly. Retrofitting it into a big game is
much harder than starting with it.
See the game without a person
Build flags for everything you would otherwise set up by hand:
--shot out.png --frames 90: bots play and frame 90 is saved. Render underxvfb-runfor a real GPU path.--players N,--seed N, and as the game grows: where to start (a level, metres along a path), what to spawn round the players, a closer camera.GAME_TRACE=1prints what happens, for tests and for debugging.
Look at the screenshots yourself after visual changes. Text over characters and HUD clutter read badly on a TV; let shapes and colour carry the state.
Make 3D models
Image-to-3D tools (Tripo, Meshy, Hunyuan3D, Hyper3D) give a quick first shape but rarely exactly what you want, and an agent driving Blender tends to lose detail. What works better for hard-surface models (props, vehicles, buildings):
- Generate a rough model from a concept image with one of those tools.
- Import it into the Godot project as a reference only.
- Have the agent build a new model next to it in Godot itself, from CSG
shapes or a
SurfaceTool/ArrayMeshin code, adding the details and proportions you need. No Blender, no plugin or MCP is required. - Render it with
--shotfrom a few angles, compare it with the reference and iterate. A second agent that only reviews the screenshots catches more than the builder checking its own work.
Bake CSG into a plain mesh (CSGShape3D.bake_static_mesh()) before it ships:
CSG is slow at runtime. Code-built meshes need no baking and stay easy to
change; most of our games already build their models this way. Rigged
characters (bones, weight painting) still need a real modelling tool.
From an r/aigamedev workflow post, October 2026.
Design for the couch
Players sit on a sofa, a few metres from the TV, holding controllers, and switch games often. The template does all of this; keep it as you build.
- Start playing at once. No title screen, no setup screen before the first round. The lobby already picked the game and the players.
- Settings live in the Start menu, and in GameNight. Declare every
option with
GameNight.declare_settingsand applysetting_changed, so players can change them from the GameNight app, the lobby, or by asking an LLM. Show the same settings in a small menu on Start. Apply a change from the next round when changing it mid-round would be unfair. The menu sends its changes withGameNight.set_setting, so the app shows them too. - The Start menu follows one layout. The game's name heads it every time Start opens it, also mid-game, so everyone in the room learns what they are playing. Then Resume, then New round (apply options), then the settings. No button hints in the menu (choose, change, select, resume): a highlighted row and ‹ › around its value speak for themselves.
- Leave Back alone. Back (Select) returns to the party; GameNight handles it and pauses your game. Never bind it to anything in the game.
- Use the players' colours, names and faces. Each player picks them once
in GameNight. Colour the player's character, draw their face on it with the
SDK's
face.gd, and name them where it matters, such as the results screen. - Don't flood the screen. No text over characters, no labels on every thing. A clock, a score per player and clear shapes and colours read from the sofa; menus and explanations do not. No control hints during play either: players figure out A and B in seconds.
- Rounds keep going. Show the result briefly, call
notify_finished, then start the next round. Players leave with Back, not with a game over screen. Let players keep moving while the result shows. - A calm camera. Everyone shares one screen: keep the camera still or slow, keep players leashed together so nobody leaves the frame, and snap (don't glide) when someone teleports or respawns.
- Punish the failure, not the action. Trying something should never hurt; missing it may. Keep the visible causes of failure to a few that everyone can read at a glance.
- Fewer, clearer mechanics. Cut mechanics that look alike but behave differently; simple spatial rules win.
- Start sparse. Effects, screen shake and audio beds were toned down in every playtest. Add spectacle when a playtest asks for it.
- Asymmetric games: private information goes to each player's phone (see Phone screens in the protocol), shared state stays on the TV, and the TV shows what the phone players chose.
- Bots fill empty seats. The host can seat AI players, so a game works with one person. The same bots run your sim and your store clip.
- Controllers follow seats. Read
GameNight.frame_for_seat(seat)when GameNight launched the game, never joystick indices. - Prepare quietly. Load everything in Prepare while hidden, then call
notify_ready. Start shows it; Pause freezes play, timers and audio.
More detail: Game lifecycle, Controllers & players, Faces & colours and Game settings.
The store clip
The store needs a five-second clip of real gameplay. Read the gameplay preview guide: quick, varied, readable cuts.
GODOT=godot tools/capture_preview.sh /tmp/takes
python3 tools/encode_preview.py /tmp/takes assets/gamenight
Each take is the real game with bots, rendered with --write-movie at a
fixed 30 FPS, so it is slow to record but exact. The cut list in
encode_preview.py is the whole edit, and encoding is bit-exact. Write down
the seeds and commit next to the clip, so anyone can make it again.
Add cover.png (portrait 360x480), icon.png (128x128) and gameplay.png
(16:9) to assets/gamenight/.
Release and store page
- Register the game in the developer portal and create a
publish key. Save it as the
GAMENIGHT_API_TOKENsecret of the repository. The first stable release needs GameNight's distribution approval. - Run the CI workflow by hand with
releaseset tov0.1.0. It tests, exports Windows, publishes the GitHub release and fills the store page. - Or fill the store page from your machine:
GAMENIGHT_API_TOKEN=gn_pub_... python3 gamenight-publish.py store
It reads gamenight.json and uploads what is in assets/gamenight/. See
Publish a game for builds, channels and review.
Everything players see lives in GameNight production, filled from your
repository by these commands. Do not add the game to ontola/gamenight's
catalog/games or to any store file in another repository: installed hosts
get stable releases from the hosted catalog. Store visibility (listed or
hidden) is a GameNight staff setting.
Pitfalls we hit
- Game data copied into other repositories drifts. Bombing Bugs ended up with
its tagline in three places. Edit
gamenight.jsonandassets/gamenight/only, and let the publish commands carry them to production. - Headless Godot hangs on a parse error; untyped values from arrays and
dictionaries are the usual cause. Give them a type (
var c: Vector3 = ...). - Agents often cannot push git tags. Release with the workflow input instead.
- Never run a downloaded script with your publish key in CI. Check out a
pinned copy of
ontola/gamenightand run itsscripts/gamenight-publish.py. - The first frames of a
--write-movietake can show the engine warming up. Start cuts at frame 20 or later. - A big level needs the camera close enough to read on a phone; check the clip at phone size.
- Test the exported build, not only the project: files under
tests/are left out of exports, and game code that loads them breaks only there. The template's CI runs the lifecycle test against the exported pack. - On Windows, a test host that reads Godot through
stdout=PIPEcan stall the game once the pipe fills. Write the output to a file (the template does), and pick a free port instead of a fixed one. secrets: inheritdoes not pass secrets to a reusable workflow in another organisation. Pass each secret by name.- Build versions are immutable: give every preview upload a unique version, such as one with the CI run id.
- TVs often run at 120 Hz: turn on physics interpolation
(
physics/common/physics_interpolation), or motion judders. - Prewarm shaders and particles during Prepare, before
notify_ready, so the first seconds of play don't stutter.