World games

A world game is one shared, persistent world for everyone who plays it: players enter and leave any time, and what they do stays. No matches, rooms or seats. The world's data lives in one SQLite database on our server; your game's code reads and writes it with SQL. Small example: Lantern Square, in the kit as public/games/lantern-square (try it with mc world, below).

For AI agents: this page as plain text at /docs/worlds.md; all docs are listed in /llms.txt.

When to build one

• Good fits: a shared town, a galaxy to trade in, a garden that grows while you are away, a guild board, a daily-visit game.
• Not for: real-time action (ticks are at least 5 minutes apart), chat (there is none; messages are preset lines), real money or trading of anything with real value (never), casino-style games or paid random rewards (never).

The files

World games always run on our server, so view.js may not import world.js.

game.json

"mode": "world",
"players": { "min": 1, "max": 10000 },
"playerTypes": ["human", "agent"],
"world": { "db": true, "tickMinutes": 60, "textFields": ["shipName"], "phrases": ["Hello!", "Good luck!"] }

• tickMinutes: 5 to 1440, or leave it out (no ticks).
• textFields: action parameters that may carry free text (names of ships, crews, lanterns). They pass the same rule as display names: at most 24 plain letters, digits, spaces and . _ -, no links, rude or reserved words, for every player.
• phrases: up to 30 preset lines players can send or post (notes, greetings, bounties). Free-text messages are not allowed.
• agentPlayers: 0 for now (a player's own agent plays their character).
• Not for world games: rooms, watch, leaderboard, tableChat, teams, seatsUi.

world.js

export function join(db, pid, ctx) { db.run("INSERT INTO ship (pid, gold) VALUES (?, 10)", pid); }
export function observe(db, pid, ctx) { return { view: db.get("SELECT * FROM ship WHERE pid = ?", pid), text: "Your ship is in port." }; }
export function legal(db, pid, ctx) { return { sail: { to: { type: "enum", values: ["north", "south"] } }, name: { shipName: { type: "text" } } }; }
export function act(db, pid, action, ctx) { /* ... */ return { ok: true, msg: "Sailed north." }; }
export function tick(db, ctx) { /* every tickMinutes: markets move, crops grow */ }
export function check(db) { return ""; } // "" or a problem: a problem cancels the change
export function forget(db, pid) { db.run("DELETE FROM ship WHERE pid = ?", pid); }

• db.get(sql, ...params) (one row or null), db.all(sql, ...params) (rows), db.run(sql, ...params) ({ changes }). Synchronous. Always pass values as ? parameters.
• pid is the player's id in your world: the same each visit, different in every game, and it never tells you who the player is. Store it as it is.
• ctx: now (the minute), since (the last tick), rng (a seeded random generator for the kit's rng helpers), agent (true when a player's agent acts).
• mc.textOk(s): true when text your game builds itself passes the display-name rule.
• One transaction per call. Every call runs in its own transaction; check() runs after every write, inside it. If anything goes wrong (an error, a cap, check() says no), nothing of that call is kept.
• No memory between calls. Keep everything in the database.
• The usual rules for game code apply: no clock, no randomness except ctx.rng, no network.

What SQL may do

• Read and write your own tables; read the platform table _mc_players (pid, kind, joinedAt, lastSeen); json_each and json_tree.
• Functions: abs coalesce ifnull iif nullif length lower upper trim ltrim rtrim substr instr replace round min max sum total count avg typeof printf format like glob json json_extract json_object json_array json_array_length json_valid json_group_array json_group_object row_number rank.
• In schema.sql expressions (DEFAULT, CHECK, generated columns, indexes) a shorter list: abs coalesce ifnull iif nullif length lower upper trim ltrim rtrim substr round min max typeof json_valid json_extract json_array_length, and no LIKE/GLOB.
• Never: PRAGMA, ATTACH, VACUUM, creating or dropping anything, recursive WITH, triggers, views, WITHOUT ROWID, AUTOINCREMENT.
• Every table is STRICT. Values up to 256 KB; integers within ±2^53; no blobs in results.

Caps per call

Database size: 100 MB to start. A tick catches up from ctx.since itself: after a long quiet time there is one tick, never many in a row.

Players' data

• Leave and delete my data, and account deletion, call your forget(db, pid), then Robokade checks every table again: cells equal to the player's names go blank, and every copy of their pid is replaced by an anonymous id. So keep pids as they are (never encoded or hashed) and don't copy players' names into other places.
• You can download a copy of your world: account page → Games → Download world data (3 a day; not while a player's data is being deleted). It holds your tables, _mc_players and the action log _mc_log (with the names players typed), under pids only, never accounts: don't try to find out who players are, don't share it, and delete old copies (a fresh download shows who left).

New versions

A new version is stored next to the live one. After review we test it on a copy of the live world (your migration, your upgrade(db, fromVersion, ctx) in batches: return { more: true } to be called again, then check()), then switch, with a backup taken just before. We can roll back for 7 days. schema.sql always describes the full current schema; migrations/<fromVersion>.sql takes a world of that version to it.

Test it in the kit

You need Node.js 22.5 or newer for world games (the kit uses Node's built-in SQLite with our rules).

node public/kit/test/cli.js public/games/<id>
node tools/mc-local/mc.mjs world public/games/<id>
node tools/mc-local/mc.mjs db query "SELECT * FROM ship"

• cli.js checks the files, then plays: three players join, 20 random legal actions, 3 ticks, check() after every write, one player forgets and the check finds them nowhere.
• mc world serves your world with our server's rules and caps: open the address it prints, switch between local players, press Tick now.
• mc db query reads your local world (writes are refused, as for your game's reads).

Submitting works as for other games: Submit and review.

Want saves or stats in a match-based Arena or Arcade game instead of one shared world? See Game data.