Skip to article Developer portalAdd your game

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

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:

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):

  1. Generate a rough model from a concept image with one of those tools.
  2. Import it into the Godot project as a reference only.
  3. Have the agent build a new model next to it in Godot itself, from CSG shapes or a SurfaceTool/ArrayMesh in code, adding the details and proportions you need. No Blender, no plugin or MCP is required.
  4. Render it with --shot from 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.

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

  1. Register the game in the developer portal and create a publish key. Save it as the GAMENIGHT_API_TOKEN secret of the repository. The first stable release needs GameNight's distribution approval.
  2. Run the CI workflow by hand with release set to v0.1.0. It tests, exports Windows, publishes the GitHub release and fills the store page.
  3. 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