@netforge/template-party 0.1.0 → 0.2.0

package/AGENTS.md

@@ -0,0 +1,63 @@
+# Extending ROMPHOUSE
+
+ROMPHOUSE is the party co-op template of the Net Forge game engine. This file tells a coding agent how to change the game safely. `llms.txt` in this package has the full recipe book for this genre, and `llms-full.txt` adds the whole `src/game.ts` as a worked example.
+
+## The one file to edit
+
+Change the game by editing `src/game.ts` only. It holds declarations, not engine code. client/names.ts holds the display labels for weapon, upgrade and earn ids. In a downloaded game folder, labels players read live in src/names.json. Everything else (the client, the manifest, the store hooks, the simulation, the netcode) is template machinery.
+
+## Import only @netforge/engine
+
+`src/game.ts` imports from `@netforge/engine` and nothing else. The template's game imports:
+
+```ts
+import { achievement, earn, game, keeper, mission, prefab, store, system, title, upgrade, weapon } from "@netforge/engine";
+```
+
+Also available for this genre: `economy`, `metaUpgrade`. `earn` has `earn.rule(...)` and `earn.stake(...)`; `store` has `store.sku(...)`. `system(id, ctx => ...)` gets the systems API described in `llms.txt`. The renderer, input, netcode and physics live elsewhere and are not reachable from game code.
+
+## Rules the build enforces
+
+- Ids are lower_snake_case.
+- Every game declares at least one `earn.rule(...)` (mandatory earn) and one `earn.stake(...)` (the buy-in run), on one top-level line. A game without either does not build.
+- Asset ids are library ids such as `style.lowpoly.turret`, never URLs or file paths, and must exist in the asset library.
+- `game({ template: "party" })` with one room in `game({ field })`: a floor and four walls.
+- A party game needs one enemy prefab, one weapon and `players.weapon` (or keepers).
+- Drops must be pickup prefabs. At most 15 weapons (evolutions count) and 8 upgrades.
+- `game({ style })` is the art style the creator picked (lowpoly, toon, ps1, pixel, voxel or handdrawn). Keep it.
+- Keep the store SKUs the client is wired to, at their prices: revive, skin_disco and the lucky_charm gear. "stake" is reserved and is never a SKU id.
+
+## Validate
+
+- With the MCP server (`npx -y @netforge/mcp`, bin `netforge-mcp`): call `netforge_validate_game` on the game. It returns one line per problem.
+- In this package: `npx vitest run` runs `test/harness.test.ts`, `test/host.test.ts`, `test/store.test.ts`. A bad declaration throws `GameDefinitionError` with a line you can act on.
+
+## Playtest
+
+- With the MCP server: call `netforge_run_playtest`.
+- In code: `import { engine } from "@netforge/engine"` and run `engine.test.run({ ticks: 30 * 180, bots: 4, assert: [] })`. It reports kills, wave (1 plus the rounds played), maxLevel, earned by rule, deaths, runs won and lost, softlock and ms per tick. With `bot: "human"` a human-like bot plays and `report.fun` holds the fun metrics the gate scores.
+
+## Play locally
+
+```sh
+mkdir -p my-game/src && cd my-game
+npm init -y && npm install @netforge/kit-play @netforge/engine @netforge/template-party
+cp node_modules/@netforge/template-party/src/game.ts src/
+echo '{"template":"party"}' > netnet.json
+npx kit-play        # opens http://127.0.0.1:4663
+```
+
+The MCP tool `netforge_play_locally` does the same. Coins are play money; nothing pays out and no chain or wallet is involved. Edit `src/game.ts` and run it again to try a change.
+
+## What not to do
+
+- Do not write renderers, netcode, physics or bot AI. The template already has them.
+- Do not use asset URLs or file paths. Use library ids.
+- Do not import anything other than `@netforge/engine` in `src/game.ts`.
+- Do not edit `client/`, `src/manifest.ts` or `src/store.ts`.
+- Do not rename or reprice the store SKUs the client is wired to.
+- Do not remove the `show` system's breather or the finale; add minigames to its list instead.
+
+## Docs
+
+https://forge.netnet.capital/docs/templates/party

package/CLAUDE.md

@@ -0,0 +1,11 @@
+# CLAUDE.md
+
+Read AGENTS.md before changing this game.
+
+The five hard rules:
+
+1. Edit only `src/game.ts`.
+2. Import only `@netforge/engine`.
+3. Ids are lower_snake_case.
+4. Declare at least one `earn.rule(...)` and exactly one `earn.stake(...)`.
+5. No renderers, netcode, physics or asset URLs.

package/README.md

@@ -1,51 +1,75 @@
-# ROMPHOUSE (party co-op)
+# @netforge/template-party
 
-Two to eight friends in one big playroom, five quick rounds a show. Each
-round is a minigame with one goal for the whole team: pop the party
-poppers before the timer, crash every gift box, catch the runaway pup, hold
-the floor against a tide, and as the finale burst the Big Balloon. Win
-three and the show is a hit. Weapons fire by themselves, so every round is
-about where you stand and who you help up.
+A party game template for Net Forge: 2 to 8 friends in one playroom, five quick minigame rounds a show (ROMPHOUSE).
 
-| Path | What |
-|---|---|
-| `src/game.ts` | The game, as the model writes it (declarations only): the playroom, the party crowd, weapons, the show system with its ROUNDS list, earn, store. |
-| `src/manifest.ts` | Loads and compiles it; `partyAdapter()` for the room server and client. Room template `party`. |
-| `src/store.ts` | Store hooks on the Kit's API names (`kit.coins.*`, `kit.store.*`): a revive (50 coins), a cosmetic (300 coins) and the lucky charm (losable gear, 150 coins), shown under the token's own symbol and logo; mock until the token is live. |
-| `client/` | The browser client: three.js scene, the playroom (`client/stage.ts`: a checkered dance floor, candy-striped walls, a ring of party lights, an x-ray cut so a wall never hides you), HUD (ROUND n and the round's clock), input (keys, gamepad, touch), game feel. |
-| `test/` | Playtest bots through `engine.test.run`, and the store. |
-| `llms.txt` | How to change the game (for agents). |
-
-## How it plays on the server
-
-- Server-authoritative at 30 Hz on the survivor machinery (auto-firing
-  weapons, stars and level-up cards, co-op downs and revives, keepers, a
-  boss with telegraphed attacks). Your own player is predicted.
-- One room: a floor and four walls in the sim (engine `field.floors` and
-  `field.walls`), bigger than the screen so every crowd arrives off screen.
-- The show is a system in game.ts the model can read and change: a list of
-  minigames (start, won, lastsOut), shuffled each show with the finale
-  last, a breather between rounds that clears the floor and brings back
-  anyone who is out.
-- Earn: a round won, four rounds won, a clean sweep, and 70 kills by one player, once
-  per show each, on the same pay structure as EMBERWATCH. The room server
-  is the referee.
-
-## Run it
-
-This template runs on your own computer with play money through
-`kit play` (`@netforge/kit-play`). From the repository root:
+Each round is a minigame with one goal for the whole team: pop the party poppers before the timer, crash every gift box, catch the runaway pup, hold the floor against a tide, and, as the finale, burst the Big Balloon. Win three and the show is a hit. Weapons fire by themselves, so every round is about where you stand and who you help up.
+
+The room server is authoritative at 30 Hz on the survivor machinery (auto-firing weapons, stars and level-up cards, co-op downs and revives, keepers, a boss with telegraphed attacks). Your own player is predicted. The playroom is one floor and four walls, bigger than the screen, so every crowd arrives off screen.
+
+The show is the `show` system in `src/game.ts`: a list of minigames (start, won, lastsOut), shuffled each show with the finale last, with a breather between rounds that clears the floor and brings back anyone who is out.
+
+Earn: a round won, four rounds won, a clean sweep, and 70 kills by one player, once per show each. Seat stakes and real-token earn run only on the hosted Net Forge server.
+
+## Install
 
 ```sh
-pnpm install --frozen-lockfile && pnpm build
-mkdir -p play-party/src && cp packages/template-party/src/game.ts play-party/src/
-echo '{"template":"party"}' > play-party/netnet.json
-node packages/kit-play/dist/cli.js play-party       # opens http://127.0.0.1:4663
+npm install @netforge/template-party
 ```
 
-Edit `play-party/src/game.ts` and run it again to try a change. Real-token
-earning, stakes and claims run only on the hosted Net Forge server.
+You normally do not import this package yourself. `kit play` runs it on your own computer, and the Net Forge MCP server and studio copy its `src/game.ts` as the starting point for a new game.
+
+## Play it locally
+
+```sh
+mkdir -p my-game/src && cd my-game
+npm init -y && npm install @netforge/kit-play @netforge/engine @netforge/template-party
+cp node_modules/@netforge/template-party/src/game.ts src/
+echo '{"template":"party"}' > netnet.json
+npx kit-play        # opens http://127.0.0.1:4663
+```
+
+Coins are play money and nothing pays out. Real-token earning, stakes and claims run only on the hosted Net Forge server.
+
+## Change the game
+
+Rounds run 40 seconds and three wins make the show a hit. Give each round more time and ask for four wins:
+
+```ts
+const ROUND_SECONDS = 50;
+const BREATHER = 6;
+const HIT_AT = 4;
+```
+
+Save `src/game.ts` and run `npx kit-play` again.
+
+## Files
+
+| Path | What |
+|---|---|
+| `src/game.ts` | The game, declarations only: the playroom, the party crowd, weapons, the `show` system with its rounds, earn, store. |
+| `src/manifest.ts` | Loads and compiles the game; `partyAdapter()` and `partyGame()` for the room host and the client. |
+| `src/store.ts` | Store hooks on the Kit's names: a revive (50 coins), a cosmetic (300 coins) and the lucky charm gear (150 coins). |
+| `client/` | The browser client: three.js scene, the playroom stage, HUD, input (keys, gamepad, touch), game feel. `client/names.ts` holds display labels. |
+| `test/` | Playtest bots through `engine.test.run`, the local host and the store. |
+| `llms.txt` | How to change the game, for agents. |
+
+## Controls
+
+Keys: WASD or arrows move, Space dash, 1 2 3 pick a card. Touch: drag on the left half, the DASH button, tap a card. The backquote key shows stats. Open the Invite link in another tab or on a phone on the same network to play together (`?room=<id>`).
+
+## For AI agents
+
+Read `AGENTS.md` and `llms.txt` in this package before changing the game. `llms-full.txt` adds the whole `src/game.ts` as a worked example.
+
+Agents can also drive this template through the Net Forge MCP server: run `npx -y @netforge/mcp` (package `@netforge/mcp`, bin `netforge-mcp`). Its tools are `netforge_list_templates`, `netforge_create_game`, `netforge_explain_api`, `netforge_search_docs`, `netforge_validate_game`, `netforge_run_playtest` and `netforge_play_locally`.
+
+To set up a coding agent in a game project, run `npx netforge setup agent`. It writes AGENTS.md, CLAUDE.md, Cursor rules and `.mcp.json` into the project. In Claude Code you can also add the server directly with `claude mcp add netforge -- npx -y @netforge/mcp`.
+
+## Docs
+
+- https://forge.netnet.capital/docs/templates/party
+- `llms.txt` and `llms-full.txt` in this package (also exported as `@netforge/template-party/llms.txt` and `@netforge/template-party/llms-full.txt`)
+
+## License
 
-Open the Invite link in another tab or on a phone on the same network to
-play together (`?room=<id>`). Keys: WASD or arrows, Space dash, 1 2 3 pick.
-Touch: drag on the left half, DASH button, tap a card. ` shows stats.
+MIT. See `LICENSE` and `NOTICE`.

package/client/main.ts

@@ -160,7 +160,7 @@ async function main(): Promise<void> {
   const joinMs = performance.now() - joinStart;
   if (friendRoomId && conn.roomId !== friendRoomId) setTimeout(() => hud.toast("That room was full, started a new one"), 500);
   if (conn.welcome.version !== GAME_VERSION) setTimeout(() => hud.toast("A new version is live. Reload to update."), 800);
-  history.replaceState(null, "", `${location.pathname}?room=${conn.roomId}${place !== PLACE ? `&place=${encodeURIComponent(place)}` : ""}${params.has("server") ? `&server=${encodeURIComponent(endpoint)}` : ""}${autopilot ? "&autopilot=1" : ""}${params.has("webgl") ? "&webgl=1" : ""}${params.has("stats") ? "&stats=1" : ""}${params.has("style") ? `&style=${encodeURIComponent(params.get("style") ?? "")}` : ""}`);
+  history.replaceState(null, "", `${location.pathname}?room=${conn.roomId}${place !== PLACE ? `&place=${encodeURIComponent(place)}` : ""}${params.has("server") ? `&server=${encodeURIComponent(endpoint)}` : ""}${params.has("game") ? `&game=${encodeURIComponent(params.get("game") ?? "")}` : ""}${autopilot ? "&autopilot=1" : ""}${params.has("webgl") ? "&webgl=1" : ""}${params.has("stats") ? "&stats=1" : ""}${params.has("style") ? `&style=${encodeURIComponent(params.get("style") ?? "")}` : ""}`);
 
   // The engine's feel kit: hit-stop clock, trauma shake, flash, knockback, numbers, sound, rumble.
   const feelParam = params.get("feel");
@@ -233,7 +233,7 @@ async function main(): Promise<void> {
     revive: () => void paidRevive(),
     getUp: () => input.getUp(),
     invite: () => {
-      const url = `${location.origin}${location.pathname}?room=${conn.roomId}${place !== PLACE ? `&place=${encodeURIComponent(place)}` : ""}${params.has("server") ? `&server=${encodeURIComponent(endpoint)}` : ""}`;
+      const url = `${location.origin}${location.pathname}?room=${conn.roomId}${place !== PLACE ? `&place=${encodeURIComponent(place)}` : ""}${params.has("server") ? `&server=${encodeURIComponent(endpoint)}` : ""}${params.has("game") ? `&game=${encodeURIComponent(params.get("game") ?? "")}` : ""}`;
       void navigator.clipboard?.writeText(url).then(
         () => hud.toast("Invite link copied"),
         () => hud.toast(url),

package/llms-full.txt

@@ -0,0 +1,716 @@
+# Net Forge party co-op template (ROMPHOUSE)
+
+> A party game for 2 to 8 friends in one big playroom: a show of five
+> quick rounds, each a different minigame with one goal for the whole
+> team. Win three and the show is a hit. You change the game by editing
+> src/game.ts only. The template already has the playroom (floor and
+> walls), weapons that fire by themselves, XP stars, level-ups, the boss
+> machinery, co-op revive, netcode, rendering, touch controls, earn and the
+> store. Do not write renderers, netcode or physics.
+
+## Files
+
+- src/game.ts: THE GAME. Declarations against @netforge/engine:
+  game(), prefab(), weapon(), upgrade(), system(), earn.rule(),
+  earn.stake(), store.sku(), keeper(), achievement(), mission(), title().
+- packages/engine/GAME-DESIGN.md: the design rules the playtest gate scores
+  (a readable opening, off-screen spawns, i-frames, telegraphs, fast levels).
+- client/names.ts: display names for weapon, upgrade and earn ids (labels).
+- Models come from the asset library (real CC0 models; the full list of ids is in your instructions). client/library.ts holds the fallback shapes drawn until a model loads.
+- Everything else is template machinery.
+
+## Rules the build enforces
+
+- Asset ids look like "style.lowpoly.slime_pink", never URLs or paths, and must be in the asset library.
+- game({ style }) is the art style the creator picked: lowpoly, toon, ps1, pixel, voxel or handdrawn. Keep it. The template draws everything in it, and a "style.lowpoly.<name>" id draws as that style's own model of the same name when the style has one.
+- game({ template: "party" }) and one room in game({ field }): a floor and four walls.
+- Ids are lower_snake_case.
+- Every game declares at least one earn.rule (mandatory earn) and one earn.stake (the buy-in run).
+- A party game needs one enemy prefab, one weapon and players.weapon (or keepers).
+- Drops must be pickup prefabs. At most 15 weapons (evolutions count) and 8 upgrades.
+- Run `pnpm --filter @netforge/template-party test` (playtest bots).
+
+## Units
+
+Seconds, metres, metres per second, hit points. Tick rate 30 Hz. Players
+run at 7 m/s; keep chasers at 3-4 m/s and fast ones under 6.
+
+## The playroom (game({ field }))
+
+const ROOM = 30;
+field: {
+  halfSize: ROOM + 2,
+  pillars: [[12, 12, 1.6], ...],                       // party tables: [x, z, radius]
+  floors: [[0, 0, ROOM, ROOM]],                        // the floor: [x, z, halfX, halfZ]
+  walls: [[0, ROOM + 1, ROOM + 2, 1], ...],            // the four walls: [x, z, halfX, halfZ]
+}
+The room is bigger than the screen (60 m across against about 40 m in
+view), so spawnEdge can always bring a crowd in just off screen. Players
+start at [0, 0]. Walls and tables stop players, enemies and bolts.
+
+## The show (the "show" system in game.ts)
+
+The show is a system you can read and change:
+
+- ROUNDS is a list of minigames: { name, seconds, start(), won(), lastsOut }.
+  start() runs as the round opens (spawn its crowd, scatter its props,
+  start a trickle with every(...)). won() is checked every half second, and
+  true ends the round early as won. At the bell the round is won if won()
+  holds, or, for lastsOut rounds, if nobody went down.
+- The first four rounds are shuffled on the sim's random each show; the
+  last (the Big Balloon) is always the finale.
+- Every won round emits round.won (earn rules count it); every round's end
+  emits wave.cleared (the HUD's ROUND n); a clean sweep emits show.perfect.
+  Between rounds (BREATHER seconds) the leftovers are cleared and anyone
+  who is out comes back.
+- HIT_AT rounds won make the show a hit (end("won")); fewer, it ends
+  "lost". Either way the end screen shows and the next show starts.
+- Something must happen every few seconds in every round: a round with 30
+  quiet seconds fails the playtest (softlock). Give each round a trickle.
+
+### Add a minigame
+{
+  name: "DODGEBALL",
+  seconds: 35,
+  lastsOut: true,                       // won if nobody goes down
+  start: () => {
+    spawnEdge("spritzer", { count: 6 + party() });
+    every(4, () => { if (current === 5) spawnEdge("spritzer", { count: 2 }); });
+  },
+  won: () => false,
+},
+Append it to ROUNDS (its index is its `current` value) and include it in the
+shuffle (the shuffle leaves the last entry, the finale, where it is).
+Counters you can use: kills (enemy kills this round), downs (players down
+this round), alive("prefab"), and on("<prefab>.killed") or
+on("miniboss.killed") for a flag.
+
+## Going down
+
+players: { downed: { seconds: 8, crawl: 0.5, selfRevives: 2, respawn: 3 } }
+A party forgives: a short down, a crawl, two free get-ups a show (Space),
+then back in 3 s beside a friend. Everyone out returns between rounds.
+
+## Common changes
+
+### Make it harder or easier
+Change a round's goal (poppers(), the scatter count), its seconds, the
+trickle sizes, or HIT_AT. Easier also: players.hitIframes (0.8 s),
+players.magnet, more selfRevives.
+
+### A longer or shorter show
+Add or remove ROUNDS entries (keep 3 to 8). ROUND_SECONDS sets the default
+length; each round may set its own.
+
+### Add an enemy
+prefab("jester", { model: "style.lowpoly.blob_wizard", health: 30, speed: 3.2, radius: 0.4, damage: 6, ai: "chase", drops: ["star_small"] });
+then bring it into a round's start() with spawnEdge("jester", { count: 8 }),
+and add its id to the sweep list so it is cleared between rounds.
+ai is the enemy's role. Every big hit is telegraphed on the ground first:
+- "chase" (default), "tank" (a chaser; give it mass), "idle"/"none" (stands still)
+- "runner": aims where you will be. Fast, fragile.
+- "charger": stops inside 6 m, shows a lane 0.55 s, then charges along it.
+- "ranged": keeps its distance, shows an aim line, fires a slow dodgeable shot
+  (only with a clear line: walls and tables are cover).
+- "bomber": walks up, arms a 1 s fuse circle, explodes (hurts enemies too).
+- "shielder" / "healer": every few seconds shields or heals nearby allies.
+- "summoner": keeps away and calls adds: attack: { summon: "fizz", count: 2 }.
+- "flee" (a carrier to catch, like the party pup), "wander".
+
+### Add elites
+An elite is x6 health, x1.5 damage, x5 XP and a gold rim, and drops a chest:
+spawnEdge("wobbler", { count: 1, elite: true }) in a round's start().
+
+### Add a weapon
+weapon("frost_ring", {
+  kind: "nova", damage: 6, cooldown: 0.8, range: 5, knockback: 8,
+  levels: [{ damage: "+30%" }, { range: "+15%" }, { cooldown: "-15%" }, { damage: "+30%" }, { knockback: 3 }],
+});
+kinds:
+- "nova": a burst in range; "aura": a field that burns what is inside, every cooldown
+- "bolt": count projectiles at the nearest enemy (speed, pierce)
+- "orbit": count blades at range metres, speed rad/s
+- "cone": a sweep of spread degrees where the keeper faces (360: all around)
+- "chain": strikes the nearest, then jumps count times, each within speed m
+- "meteor": count circles of blast m land on enemies in range, 0.6 s after showing
+- "boomerang": flies out range m and back, hitting everything both ways
+levels: what each level changes from the one before (5-8 levels). A number
+adds (count: 1, pierce: 2, cooldown: -0.1 s), a percent scales ("+40%").
+Cards show these changes ("+1 projectile, -20% cooldown"). It is offered at
+level-up automatically. Add a label in client/names.ts.
+
+### Add an evolution
+weapon("frost_ring", { ..., evolve: { into: "blizzard", requires: "iron_skin" } });
+weapon("blizzard", { kind: "nova", damage: 20, cooldown: 0.6, range: 9, knockback: 12 });
+At max level, with the passive "iron_skin" taken, the "blizzard" card always
+shows; it replaces frost_ring in its slot. Evolutions are never offered on
+their own. Give them about x1.7 damage and a new shape (360 degrees, double
+radius, more count). Pair each base weapon with a different passive.
+
+### Add a passive
+upgrade("iron_skin", { stat: "armor", step: 1, maxLevel: 4 });
+stats: speed, maxHealth, magnet, might, haste, regen, armor, area (bigger
+novas, auras, cones, meteors and orbits), amount (more projectiles, blades,
+jumps and meteors). Up to 8. maxLevel caps how often it is offered.
+
+### Add pickups and loot
+prefab("cake_slice", { model: "style.lowpoly.cell_heal", health: 1, speed: 0, kind: "pickup", pickup: { effect: "heal", amount: 0.3 } });
+A boss's hoard: pickup: { effect: "chest", amount: 3, evolve: true }. Bosses
+drop it instead of the plain chest. If the player holds a weapon and already
+has its paired passive, that weapon jumps to max level, so its evolution is
+on the cards.
+effects: heal (amount: fraction of max health, or hit points above 1),
+vacuum (every gem on the floor comes to you), bomb (clears the screen's
+non-boss enemies), chest (amount card picks; a ready evolution shows first).
+Drop them with a chance: drops: ["star_small", { id: "cake_slice", chance: 0.02 }].
+Elites always drop the game's chest; bosses drop a heal, a vacuum and a chest.
+Above 300 gems on the floor, new gems merge into the nearest one.
+
+### Add props (breakables)
+prefab("gift_box", { model: "style.lowpoly.crate", health: 30, speed: 0, radius: 0.55, prop: true, drops: ["star_mid", { id: "cake_slice", chance: 0.2 }] });
+then scatter("gift_box", 20) from a round's start() (props land on the floor, off every screen). Props never move, never hurt
+and never count as enemies.
+
+### Add events and moments
+In a round's start() or the show's next()/finish():
+on("round.won", () => { if (random() < 0.3) { announce("ENCORE", { tone: "reward" }); xpBoost(2, 15); } });
+announce tones: info, danger, reward. Events you can key on (and earn rules
+too): round.won, show.perfect, miniboss.killed, player.downed,
+player.revived, chest.collected, "<prefab>.killed". clear("popper")
+removes a prefab at once (no kills or drops).
+
+### Cards
+Weighted: an owned weapon's next level 8, a new weapon 10 (while a slot is
+free), a passive 4 (7 once weapon slots are full); a ready evolution always
+shows. players.rerolls (default 1) rerolls per run (R); Skip (X) trades the
+cards for a small heal. When everything is maxed, a level heals and gives
+teammates a little XP.
+
+### Add a boss
+prefab("disco_dragon", {
+  model: "style.lowpoly.dragon_whelp", appearance: { tint: "#c9a7ff", scale: 1.4 }, health: 800, speed: 2.4, radius: 1.3, damage: 14,
+  boss: { attacks: ["slam", "leap"], rank: "mini" },
+  drops: ["star_large"],
+});
+Spawn it in a round's start() with spawnEdge("disco_dragon", { count: 1 }) and
+win the round on on("miniboss.killed"). Attacks (all telegraphed): slam
+(circle around it), dash (11 m lane), leap (lands on a circle at you), rain
+(circles near players), ring (14 shots outward), fan (7 shots at you), summon
+(adds). Near attacks (slam, leap) keep it after the players; a boss that only
+throws from afar can be ignored by a party that will not chase it. Boss
+health scales with players present (players.bossHealthPerPlayer, 0.35 here).
+
+### Add an earn rule
+earn.rule("three_wins", { when: "round.won", n: 3, pay: 10, oncePer: "run" });
+A run is one show. Events: round.won and show.perfect (the show emits them), enemy.killed (credits the killer),
+boss.killed (everyone present), player.downed, player.revived (credits the
+reviver), player.levelup, run.won, run.lost, and anything you emit().
+Each rule pays once per run per player, in coins; the room server is the referee.
+
+### The buy-in run (required)
+earn.stake({ min: 20, max: 200, multiple: 2 });
+Every game declares one, on one top-level line; a game without it does not
+build. A player stakes coins at the start of a run (the Kit spends them as
+coins.spend(amount, "stake"), then the client calls conn.stake()). The room
+fixes the stake when the next run starts. A staked run pays its normal earn
+plus a share of stake x multiple: the share is the part of the run's most
+earn the player makes. What it does not win back stays in the reward pool.
+multiple is 1 to 2. "stake" is reserved: never a SKU or meta upgrade id.
+
+### Losable gear (optional)
+store.sku("lucky_charm", { coins: 150, grants: { gear: "lucky_sock", loseBelow: 0.25 } });
+Gear is owned in the player's profile and sells for coins only. It brings one
+level of its declared upgrade into every staked run, and is lost when that run
+makes less than loseBelow of its most earn. Its coins stay in the reward pool.
+
+### Coins: earn and the store
+
+Every game has coins: 1 coin = 1 of the game's own token, and players see
+them under the token's own name, symbol and logo (never "coins" or "tokens"
+as a label). Earn rules pay coins (`pay` is whole coins). The recommended
+coin model (the default, no declaration) sells cosmetics, unlocks and
+in-run consumables, never permanent stat power:
+
+store.sku("revive", { coins: 50 });                                   // in-run: used while downed
+store.sku("skin_disco", { coins: 300, grants: { cosmetic: 1 } });    // a look, owned for good
+
+Keep them and the lucky_charm gear exactly: the client is wired to them (price, look id and gear). Owned
+looks and unlocks are saved on the room server in the player's profile. Players spend
+earned coins first (instantly, no wallet prompt), then their wallet. Before
+the game launches coins are play money; the Kit switches by itself, so
+nothing in game.ts depends on it. Price in coins against what a run pays
+(the four rules here pay up to 80 a run): a revive is under a run, a
+cosmetic a few runs.
+
+### Sell a keeper unlock (a character, a starting loadout, a sidegrade)
+keeper("mc", { name: "MC", text: "Streamers and a party hat.", weapon: "streamer", passive: "party_hat" });   // no unlock
+store.sku("unlock_mc", { coins: 400, grants: { keeper: "mc" } });
+A keeper is earned (unlock: an achievement) or bought (a SKU), never both:
+the build refuses a sold keeper that also declares an unlock. Never sell
+the first keeper (everyone's free default). An unlock is a different way to
+play, never more power. Before launch coins are play money and buy only
+in-run items; looks and unlocks open at launch.
+
+### Cosmetics only ("no pay to win")
+economy({ store: "cosmetics" });
+Then every SKU must be a look (grants: { cosmetic: n }); drop revive.
+
+### Permanent upgrades for coins (opt-in meta upgrades)
+economy({ metaUpgrades: true });
+metaUpgrade("hearth", { stat: "maxHealth", step: 0.05, levels: 3, cost: 120, growth: 2 });  // 120, 240, 480 coins
+metaUpgrade("stride", { stat: "speed", step: 0.03, levels: 3, cost: 100, growth: 1.8 });
+Only when the creator asks for permanent upgrades. Stats: speed, maxHealth,
+magnet, might, haste, area. The engine refuses more than +15% to one stat
+or +30% in all, more than 5 levels, or growth under 1.5, and applies a
+player's levels at the start of every run. The store shows each level.
+
+### Add a keeper (a playable character)
+keeper("juggler", { name: "Juggler", text: "Spinning plates and a wider spin.", model: "style.lowpoly.blocky_k", tint: "#7ad7ff", weapon: "spinning_plates", passive: "disco_ball", unlock: "first_hit" });
+A keeper starts every run with its weapon and its passive at level 1;
+players pick one before their first level and on the end screen. At most
+15; the first declared keeper is everyone's default, and at least one
+keeper has no unlock (declare a free one first). Keepers unlock with
+achievements, or with coins through a SKU with grants: { keeper }. The room
+server checks every pick against the player's saved unlocks.
+With keepers declared, players.weapon is optional.
+
+### Add achievements, daily goals and end-screen titles
+achievement("evolver", { title: "Evolved", text: "Evolve a weapon.", when: "player.evolved" });
+mission("elite", { text: "Kill an elite", when: "elite.killed" });
+title("butcher", { text: "The Butcher", most: "kills" });
+Achievements and missions count a game event per player in one run (n
+times) and pay nothing (coins come only from earn rules). The room server
+grants them from the run and saves them per player (wallet, or guest until
+sign-in), so they follow the player to every device. The HUD shows
+three missions a day. Titles rank players at the end of a run by most or
+least of: kills, damage, revives, downs, level, pickups. Events to count:
+anything you emit, "<prefab>.killed" ("party_pup.killed"),
+"elite.killed", "player.evolved", "player.revived", "chest.collected",
+"miniboss.killed", "round.won", "show.perfect".
+
+### Co-op that feels shared
+players: { share: "nearby" }        // default: half of each gem to teammates within 20 m
+players: { share: "all" }           // or "collector", or { mode, fraction, radius }
+players: { reviveBuff: { seconds: 5, damage: 1.3, speed: 1.15 } }  // the reviver burns hotter
+players: { downed: { seconds: 8, crawl: 0.5, selfRevives: 2, respawn: 3 } }  // this game: forgiving
+players: { lateJoinBehind: 2 }      // a late joiner starts 2 levels under the team, cards waiting
+players: { crit: { chance: 0.08, multiplier: 2 } }  // crits show as gold numbers
+The end screen votes "Play again" (everyone ready starts the next run; it
+starts by itself after 10 s) and shows each keeper's build, damage per
+weapon, what downed them, coins and titles.
+
+### Players per room
+players.max is 8 here, the most the hosted Net Forge room server seats
+in a party room. Fewer is fine; more is refused.
+
+## Models and appearances (the asset library)
+
+Every model is a real CC0 model from the asset library, by id. Enemies are
+drawn about 3.2 hit radii tall, keepers 1.8 m; animated ones walk, run and
+die by themselves. An appearance dresses a model into your own original:
+appearance: { tint: "#rrggbb", accent: "#rrggbb", scale: 0.4 to 3, parts: up to 4 }.
+
+### Make the crowd look like robots
+prefab("popper", { model: "style.lowpoly.robot_walker", ... });
+prefab("fizz", { model: "style.lowpoly.robot_flyer", ... });
+Keep the ids or rename them everywhere (ROUNDS and the sweep list too), and
+retell it in names.json.
+
+### A hero described by the creator
+players: { prefab: "style.lowpoly.worker", appearance: { tint: "#2e7d32", accent: "#3b2a1a", parts: ["mustache", "hat_cap"] }, ... }
+Name it something new in names.json. A creature the library lacks: the
+nearest base plus parts, e.g. model "style.lowpoly.shiba" with
+appearance { tint: "#5ec8ff", parts: ["antenna", "tail_bolt"] }.
+
+## Look and feel (engine render stack and feel kit)
+
+How the game looks and how hits feel are declarations too. They are
+presentation only (never the simulation), so tune them freely. The full
+reference is packages/engine/llms.txt.
+
+### Change the look
+game({ ..., look: { preset: "dusk", bloom: 1.4, fog: 0.3, tint: "#ffd9a0" } });
+presets: "night" (default), "dusk", "day", "studio". Also shadows (off here unless
+look.shadows is true), outline,
+exposure, saturation, contrast, vignette.
+
+### Make a death or a hit feel bigger
+prefab("brute", { ..., feel: { particles: "burst", decal: "scorch", sound: "boom", shake: 0.5, hitStop: 0.06, color: "#ff4d5e" } });
+Without feel, big enemies (bosses, radius 0.5 m or more) burst, scorch and
+shake, and small ones burst, splat and crunch.
+
+### Make a weapon's impacts feel different
+weapon("frost_ring", { ..., feel: { particles: "magic", decal: "ring", color: "#7ad7ff", shake: 0.1 } });
+Novas use it when they go off; bolts and lances when they hit.
+
+### Heavier or lighter knockback
+weapon knockback (m/s) pushes enemies, divided by their mass. Knocked
+enemies stagger, slide, bounce off walls and pillars and shove the
+enemies behind them. Bolts stop at walls and pillars.
+
+## Systems API
+
+every(seconds, n => ...), after(seconds, fn), onTick(fn), spawn(prefab, [x,y,z], { elite? }),
+spawnPickup(prefab, [x,y,z]), announce(text, { tone }), bossAlive(),
+pauseDirector(seconds), surge(multiplier, seconds), xpBoost(multiplier, seconds),
+scatter(prefab, count), clear(prefab), upcoming(label, seconds) (a HUD countdown:
+upcoming("THE BELL WARDEN", 240)),
+spawnEdge(prefab, { count, around?, side?, spread?, scale? }) (just off screen;
+side: "any" | "ahead" | "behind" | "north" | "south" | "east" | "west"),
+spawnRing(prefab, { count, radius, around? }), alive(prefab?), players(),
+emit(event), on(event, players => ...), respawnDead(), end("won" | "lost"),
+onScreen(x, z) (true when a player who is up can see that ground point),
+random(), tick(), time().
+
+## Test
+
+engine.test.run({ ticks: 30 * 180, bots: 4, assert: [...] }) plays the game
+on the server sim with bots and reports kills, wave, maxLevel, earned by
+rule, deaths, runs won and lost, softlock and ms per tick (wave is
+1 + rounds played). With
+bot: "human" a human-like bot plays (200 ms reactions, kiting, a second per
+card) and report.fun has the fun metrics: first threat, first level,
+level at 1/3/6/9 minutes, downs before 1:00, enemies on screen at 0:30,
+touches in minute 1, spawns on screen, survival. Net Forge's gate scores
+them; `pnpm --filter @netforge/template-party fun` prints the table.
+
+## Worked example: src/game.ts
+
+The whole game as the template ships it. Every change starts from this file.
+
+```ts
+/**
+ * ROMPHOUSE: the party co-op template ("party co-op").
+ *
+ * Two to eight friends in one big playroom, five quick rounds a show. Each
+ * round is a different minigame with one goal for the whole team: pop the
+ * party poppers before the timer, crash every gift box, catch the runaway
+ * pup, hold the floor against a tide, and as the finale burst the Big
+ * Balloon. Win three of five and the show is a hit. Weapons fire by themselves, so every round
+ * is about where you stand and who you help up.
+ *
+ * This file is the whole game as the model writes it: declarations only,
+ * against the typed API in @netforge/engine. The rounds are the "show"
+ * system below: a list of minigames, each a few lines of start, check and
+ * finish. Everything else (sim, netcode, renderer, referee) is the
+ * template's machinery. Design rules: packages/engine/GAME-DESIGN.md.
+ */
+import { achievement, earn, game, keeper, mission, prefab, store, system, title, upgrade, weapon } from "@netforge/engine";
+
+/** The playroom: one 60 m room (its floor and four walls), with party tables to dodge round. */
+const ROOM = 30;
+
+export default game({
+  template: "party",
+  style: "lowpoly",
+  places: { playroom: { chunks: "places/playroom", spawn: [0, 1, 0] } },
+  field: {
+    halfSize: ROOM + 2,
+    pillars: [
+      [12, 12, 1.6], [-12, 12, 1.6], [12, -12, 1.6], [-12, -12, 1.6],
+      [0, 21, 2], [0, -21, 2], [21, 0, 2], [-21, 0, 2],
+    ],
+    floors: [[0, 0, ROOM, ROOM]],
+    walls: [[0, ROOM + 1, ROOM + 2, 1], [0, -ROOM - 1, ROOM + 2, 1], [ROOM + 1, 0, 1, ROOM], [-ROOM - 1, 0, 1, ROOM]],
+  },
+  look: { preset: "studio", bloom: 1.1, saturation: 1.2, vignette: 0.25 },
+  players: {
+    prefab: "style.lowpoly.blocky_c",
+    max: 8,
+    weapon: "confetti_pop",
+    xp: { base: 2, growth: 2, exponent: 2 },
+    magnet: 4.5,
+    hitIframes: 0.8,
+    share: "all",
+    crit: { chance: 0.1, multiplier: 2 },
+    reviveBuff: { seconds: 5, damage: 1.3, speed: 1.2 },
+    bossHealthPerPlayer: 0.35,
+    // A party forgives: a short down, two free get-ups a show, back in 3 s.
+    downed: { seconds: 8, crawl: 0.5, selfRevives: 2, respawn: 3 },
+  },
+});
+
+// The party crowd. Health in hit points, speed in m/s (players run at 7), damage per touch.
+const GIFT = [{ id: "cake_slice", chance: 0.02 }, { id: "party_magnet", chance: 0.01 }];
+prefab("popper", { model: "style.lowpoly.slime_pink", appearance: { tint: "#ff7ab8" }, health: 16, speed: 3.6, radius: 0.4, damage: 5, ai: "chase", drops: ["star_small", ...GIFT] });
+prefab("fizz", { model: "style.lowpoly.bee", appearance: { tint: "#7affd4" }, health: 8, speed: 5.4, radius: 0.28, damage: 3, ai: "runner", drops: ["star_small", ...GIFT] });
+prefab("wobbler", { model: "style.lowpoly.blob_ninja", appearance: { tint: "#c9a7ff" }, health: 50, speed: 2.5, radius: 0.55, damage: 9, ai: "tank", mass: 3, drops: ["star_mid"] });
+prefab("spritzer", { model: "style.lowpoly.frog", appearance: { tint: "#5ec8ff", scale: 0.45 }, health: 20, speed: 2.8, radius: 0.4, damage: 4, ai: "ranged", attack: { damage: 7, range: 9, speed: 7 }, drops: ["star_small"] });
+prefab("party_pup", { model: "style.lowpoly.pug", appearance: { tint: "#ffd36b" }, health: 70, speed: 6, radius: 0.45, damage: 0, ai: "flee", drops: [{ id: "party_chest", chance: 1 }] });
+prefab("gift_box", { model: "style.lowpoly.crate", appearance: { tint: "#ff5a7a", accent: "#ffe066" }, health: 30, speed: 0, radius: 0.55, damage: 0, prop: true, drops: ["star_mid", { id: "cake_slice", chance: 0.2 }] });
+// The Big Balloon: the show's boss round. Two telegraphed attacks and a burst of prizes.
+prefab("big_balloon", {
+  model: "style.lowpoly.jelly_flyer",
+  appearance: { tint: "#ff5a7a", accent: "#ffe066", scale: 1.4 },
+  health: 650,
+  speed: 2.4,
+  radius: 1.3,
+  damage: 12,
+  // It bounces after you: a slam ring around it, and a leap that lands on a circle at you.
+  boss: { attacks: ["slam", "leap"], rank: "mini" },
+  drops: ["star_large"],
+});
+
+// Prizes: stars are XP; cake heals, the magnet pulls every star, the chest is a pick.
+prefab("cake_slice", { model: "style.lowpoly.cell_heal", appearance: { tint: "#ffd1e8" }, health: 1, speed: 0, kind: "pickup", pickup: { effect: "heal", amount: 0.3 } });
+prefab("party_magnet", { model: "style.lowpoly.crystal", appearance: { tint: "#7ad7ff" }, health: 1, speed: 0, kind: "pickup", pickup: { effect: "vacuum" } });
+prefab("party_chest", { model: "style.lowpoly.chest", appearance: { tint: "#ffcf5a" }, health: 1, speed: 0, kind: "pickup", pickup: { effect: "chest", amount: 1 } });
+prefab("prize_hoard", { model: "style.lowpoly.chest", appearance: { tint: "#ff7ab8", scale: 1.5 }, health: 1, speed: 0, kind: "pickup", pickup: { effect: "chest", amount: 2, evolve: true } });
+prefab("star_small", { model: "style.lowpoly.gem_small", appearance: { tint: "#ffe066" }, health: 1, speed: 0, kind: "pickup", value: 1 });
+prefab("star_mid", { model: "style.lowpoly.gem_mid", appearance: { tint: "#ffb347" }, health: 1, speed: 0, kind: "pickup", value: 6 });
+prefab("star_large", { model: "style.lowpoly.gem_large", appearance: { tint: "#ff7ab8" }, health: 1, speed: 0, kind: "pickup", value: 40 });
+
+// Weapons fire by themselves. Cooldowns in seconds, ranges in metres.
+weapon("confetti_pop", {
+  kind: "nova", damage: 12, cooldown: 1, range: 3.6, knockback: 3,
+  levels: [{ damage: "+30%" }, { range: "+15%" }, { cooldown: "-15%" }, { damage: "+30%" }, { range: "+15%" }],
+  evolve: { into: "confetti_cannon", requires: "sugar_rush" },
+});
+weapon("streamer", {
+  kind: "bolt", damage: 13, cooldown: 0.6, range: 13, speed: 24, pierce: 1, knockback: 2,
+  levels: [{ count: 1 }, { damage: "+40%" }, { cooldown: "-20%" }, { pierce: 1 }, { count: 1 }],
+  evolve: { into: "streamer_storm", requires: "party_hat" },
+});
+weapon("spinning_plates", {
+  kind: "orbit", damage: 8, cooldown: 0.1, range: 2.4, count: 2, speed: 3.8, knockback: 3,
+  levels: [{ count: 1 }, { damage: "+30%" }, { range: "+20%" }, { count: 1 }, { damage: "+40%" }],
+  evolve: { into: "plate_carousel", requires: "disco_ball" },
+});
+weapon("pie_toss", {
+  kind: "meteor", damage: 34, cooldown: 2, range: 11, count: 1, blast: 1.8, knockback: 6,
+  levels: [{ count: 1 }, { damage: "+40%" }, { cooldown: "-20%" }, { count: 1 }, { damage: "+40%" }],
+});
+weapon("limbo_bar", {
+  kind: "cone", damage: 16, cooldown: 1.1, range: 4, spread: 110, knockback: 6,
+  levels: [{ damage: "+30%" }, { spread: 40 }, { range: "+20%" }, { cooldown: "-20%" }, { damage: "+40%" }],
+});
+weapon("kazoo_chain", {
+  kind: "chain", damage: 15, cooldown: 1.3, range: 9, count: 2, speed: 4, knockback: 1,
+  levels: [{ count: 1 }, { damage: "+35%" }, { count: 1 }, { cooldown: "-20%" }, { count: 2 }],
+});
+
+// Evolutions: about x1.7 damage and a new shape. Never offered on their own.
+weapon("confetti_cannon", { kind: "nova", damage: 36, cooldown: 0.8, range: 8, knockback: 9 });
+weapon("streamer_storm", { kind: "bolt", damage: 30, cooldown: 0.4, range: 15, speed: 28, count: 6, pierce: 3, knockback: 3 });
+weapon("plate_carousel", { kind: "orbit", damage: 18, cooldown: 0.1, range: 3.6, count: 6, speed: 4.6, knockback: 4 });
+
+// Passive upgrades offered at level-up. Each evolution pairs with one.
+upgrade("dance_shoes", { stat: "speed", step: 0.07, maxLevel: 5 });
+upgrade("second_helping", { stat: "maxHealth", step: 20, maxLevel: 5 });
+upgrade("party_hat", { stat: "amount", step: 1, maxLevel: 2 });
+upgrade("sugar_rush", { stat: "haste", step: 0.06, maxLevel: 5 });
+upgrade("disco_ball", { stat: "area", step: 0.1, maxLevel: 5 });
+upgrade("lucky_sock", { stat: "might", step: 0.1, maxLevel: 5 });
+upgrade("goodie_bag", { stat: "magnet", step: 0.8, maxLevel: 4 });
+
+/** Seconds a round runs, the breather between rounds, and the rounds won that make the show a hit. */
+const ROUND_SECONDS = 40;
+const BREATHER = 6;
+const HIT_AT = 3;
+const SIDES = ["north", "south", "east", "west"] as const;
+/** Everything a round brings in: cleared off the floor between rounds. */
+const SWEEP = ["popper", "fizz", "wobbler", "spritzer", "party_pup", "gift_box", "big_balloon"];
+
+system("show", ({ every, after, onTick, tick, players, spawnEdge, scatter, alive, clear, emit, announce, upcoming, respawnDead, random, on, end }) => {
+  // The five minigames, shuffled each show. start() runs as the round opens; won() is checked every half second
+  // (true ends it early), and at the bell the round is won if won() holds or `lastsOut` (nobody fell).
+  let kills = 0;
+  let downs = 0;
+  let pupCaught = false;
+  let balloonBurst = false;
+  const party = () => Math.max(1, players().length);
+  const poppers = () => 40 + 12 * (party() - 1);
+  interface Round {
+    readonly name: string;
+    readonly seconds: number;
+    start(): void;
+    won(): boolean;
+    readonly lastsOut?: boolean;
+  }
+  const ROUNDS: Round[] = [
+    {
+      name: "POP THE PARTY",
+      seconds: ROUND_SECONDS,
+      start: () => {
+        spawnEdge("popper", { count: 10 });
+        every(2, () => {
+          if (current === 0) spawnEdge(random() < 0.25 ? "fizz" : "popper", { count: 4 + party() });
+        });
+      },
+      won: () => kills >= poppers(),
+    },
+    {
+      name: "CRATE CRASH",
+      seconds: 40,
+      start: () => {
+        scatter("gift_box", 14 + 3 * party());
+        spawnEdge("popper", { count: 6 });
+        every(5, () => {
+          if (current === 1) spawnEdge("popper", { count: 3 + party() });
+        });
+      },
+      won: () => alive("gift_box") === 0,
+    },
+    {
+      name: "CATCH THE PUP",
+      seconds: 30,
+      start: () => {
+        spawnEdge("party_pup", { count: 1, side: "ahead", spread: 90 });
+        spawnEdge("wobbler", { count: 2 + Math.floor(party() / 2) });
+        // The pup's friends keep getting in the way.
+        every(5, () => {
+          if (current === 2) spawnEdge("fizz", { count: 2 + Math.floor(party() / 2) });
+        });
+      },
+      won: () => pupCaught,
+    },
+    {
+      name: "HOLD THE FLOOR",
+      seconds: 35,
+      lastsOut: true,
+      start: () => {
+        const tide = () => {
+          if (current !== 3) return;
+          const side = SIDES[Math.floor(random() * SIDES.length)] ?? "north";
+          spawnEdge("popper", { count: 18 + 4 * party(), side, spread: 80 });
+          spawnEdge("spritzer", { count: 2, side, spread: 60 });
+        };
+        tide();
+        every(9, tide);
+      },
+      won: () => false,
+    },
+    {
+      name: "BURST THE BIG BALLOON",
+      seconds: 60,
+      start: () => {
+        spawnEdge("big_balloon", { count: 1 });
+        spawnEdge("fizz", { count: 6 });
+        // Its fizz keep coming while it floats.
+        every(6, () => {
+          if (current === 4) spawnEdge("fizz", { count: 2 + Math.floor(party() / 2) });
+        });
+      },
+      won: () => balloonBurst,
+    },
+  ];
+  // The show's order: the first four shuffled on the sim's random, so every show plays differently;
+  // the Big Balloon is always the finale.
+  const order = ROUNDS.map((_, i) => i);
+  for (let i = order.length - 2; i > 0; i--) {
+    const j = Math.floor(random() * (i + 1));
+    [order[i], order[j]] = [order[j] ?? 0, order[i] ?? 0];
+  }
+  let step = -1;
+  let current = -1;
+  let endsAt = 0;
+  let wins = 0;
+  const sweep = () => {
+    for (const id of SWEEP) clear(id);
+  };
+  const next = () => {
+    step++;
+    if (step >= order.length) {
+      const score = wins + " OF " + order.length;
+      announce(wins >= HIT_AT ? "A HIT · " + score : "THE SHOW IS OVER · " + score, { tone: wins >= HIT_AT ? "reward" : "info" });
+      if (wins === order.length) emit("show.perfect");
+      after(3, () => end(wins >= HIT_AT ? "won" : "lost"));
+      return;
+    }
+    const r = ROUNDS[order[step] ?? 0] as Round;
+    current = order[step] ?? 0;
+    kills = 0;
+    downs = 0;
+    pupCaught = false;
+    balloonBurst = false;
+    announce("ROUND " + (step + 1) + " · " + r.name, { tone: "info" });
+    upcoming(r.name, r.seconds);
+    endsAt = tick() + r.seconds * 30;
+    r.start();
+  };
+  const finish = (won: boolean) => {
+    const r = ROUNDS[current];
+    current = -1;
+    if (won) {
+      wins++;
+      emit("round.won");
+      announce((r?.name ?? "ROUND") + " · WON", { tone: "reward" });
+    } else announce((r?.name ?? "ROUND") + " · MISSED", { tone: "danger" });
+    emit("wave.cleared");
+    // The round's clock gives way to the breather's (the last round has none: the show ends).
+    if (step + 1 < order.length) upcoming("NEXT ROUND", BREATHER);
+    after(1.5, sweep);
+    after(2, () => respawnDead());
+    after(BREATHER, next);
+  };
+  on("enemy.killed", (ids) => {
+    if (current >= 0) kills += Math.max(1, ids.length);
+  });
+  on("player.downed", () => {
+    if (current >= 0) downs++;
+  });
+  on("party_pup.killed", () => {
+    pupCaught = true;
+  });
+  on("miniboss.killed", () => {
+    balloonBurst = true;
+  });
+  onTick(() => {
+    if (current < 0 || tick() % 15 !== 0) return;
+    const r = ROUNDS[current] as Round;
+    if (r.won()) finish(true);
+    else if (tick() >= endsAt) finish(r.lastsOut === true && downs === 0);
+  });
+  // Doors open: a few poppers wander in while the first round is announced.
+  after(0.5, () => spawnEdge("popper", { count: 4 + party() }));
+  after(2, next);
+});
+
+// Keepers: pick one before your first level. New keepers unlock with achievements, never with coins.
+keeper("host", { name: "Host", text: "Confetti all round and quick on the feet.", weapon: "confetti_pop", passive: "dance_shoes" });
+keeper("juggler", { name: "Juggler", text: "Spinning plates and a wider spin.", model: "style.lowpoly.blocky_k", tint: "#7ad7ff", weapon: "spinning_plates", passive: "disco_ball", unlock: "first_hit" });
+keeper("pie_chef", { name: "Pie Chef", text: "Pies from on high, and seconds.", model: "style.lowpoly.blocky_f", tint: "#ffb347", weapon: "pie_toss", passive: "second_helping", unlock: "balloon_popper" });
+
+// Achievements (counted in a show; they unlock keepers and pay nothing).
+achievement("first_hit", { title: "Crowd Pleaser", text: "Win three rounds in one show.", when: "round.won", n: 3 });
+achievement("balloon_popper", { title: "Pop Goes", text: "Burst the Big Balloon.", when: "miniboss.killed" });
+achievement("perfect_show", { title: "Standing Ovation", text: "Win every round of a show.", when: "show.perfect" });
+
+// Daily goals: the HUD shows three a day. They pay nothing.
+mission("rounds", { text: "Win 3 rounds", when: "round.won", n: 3 });
+mission("pup", { text: "Catch the pup", when: "party_pup.killed" });
+mission("revive", { text: "Help a friend up", when: "player.revived" });
+mission("chest", { text: "Open 2 chests", when: "chest.collected", n: 2 });
+mission("balloon", { text: "Burst the Big Balloon", when: "miniboss.killed" });
+
+// End-screen titles: who stole the show at what.
+title("life_of_party", { text: "Life of the Party", most: "kills" });
+title("showstopper", { text: "Showstopper", most: "damage" });
+title("good_friend", { text: "Good Friend", most: "revives" });
+title("on_their_feet", { text: "On Their Feet", least: "downs" });
+title("snacker", { text: "Snacker", most: "pickups" });
+
+// Earn (mandatory). Pays the game's coins (1 coin = 1 token), once per show each.
+// Pay amounts copy EMBERWATCH's (5, 20, 50, 5) until ROMPHOUSE's own are set: PLACEHOLDER.
+earn.rule("first_win", { when: "round.won", n: 1, pay: 5, oncePer: "run" });
+earn.rule("crowd_favourite", { when: "round.won", n: 4, pay: 20, oncePer: "run" });
+earn.rule("full_house", { when: "show.perfect", n: 1, pay: 50, oncePer: "run" });
+earn.rule("confetti_storm", { when: "enemy.killed", n: 70, pay: 5, oncePer: "run" });
+// Buy-in run (the mandatory sink loop): stake coins at the start of a show to earn above free play.
+// Values are PLACEHOLDER.
+earn.stake({ min: 20, max: 200, multiple: 2 });
+
+// Store (the Kit), priced in coins (the default coin model). Prices copy EMBERWATCH's: PLACEHOLDER.
+store.sku("revive", { coins: 50 });
+store.sku("skin_disco", { coins: 300, grants: { cosmetic: 1 } });
+// Losable gear: owned for good until lost in a staked show that makes less than loseBelow of its most earn.
+store.sku("lucky_charm", { coins: 150, grants: { gear: "lucky_sock", loseBelow: 0.25 } });
+```
+
+## Validate and playtest
+
+- Validate: the MCP tool `netforge_validate_game` builds `src/game.ts` and returns one actionable line per problem (an unknown asset id, a missing earn.stake, a bad id). The same checks throw `GameDefinitionError` when the module is imported.
+- Playtest: the MCP tool `netforge_run_playtest`, or in code `engine.test.run({ ticks: 30 * 180, bots: 4, assert: [] })`. It reports kills, wave (1 plus the rounds played), maxLevel, earned by rule, deaths, runs won and lost, softlock and ms per tick. With `bot: "human"` a human-like bot plays and `report.fun` holds the fun metrics the gate scores.
+- Template tests: test/harness.test.ts, test/host.test.ts, test/store.test.ts, run with `npx vitest run` in this package.
+- Play locally: put `src/game.ts` and a `netnet.json` of `{"template":"party"}` in a folder, install `@netforge/kit-play` and `@netforge/engine`, and run `npx kit-play` (or the MCP tool `netforge_play_locally`). It opens http://127.0.0.1:4663 with play money.
+- Docs: https://forge.netnet.capital/docs/templates/party

package/llms.txt

@@ -1,4 +1,4 @@
-# ROMPHOUSE: the party co-op template (NetNet game runtime)
+# Net Forge party co-op template (ROMPHOUSE)
 
 > A party game for 2 to 8 friends in one big playroom: a show of five
 > quick rounds, each a different minigame with one goal for the whole

package/package.json

@@ -1,12 +1,29 @@
 {
   "name": "@netforge/template-party",
-  "version": "0.1.0",
-  "description": "ROMPHOUSE: a party co-op template on the NetNet game runtime: 2 to 8 friends in one playroom, five quick minigame rounds a show. The game module, its browser client and its playtest bots.",
+  "version": "0.2.0",
+  "description": "Party game template for Net Forge: 2 to 8 friends in one playroom, five quick minigame rounds a show (ROMPHOUSE).",
+  "keywords": [
+    "game-template",
+    "multiplayer",
+    "browser-game",
+    "html5-game",
+    "threejs",
+    "game-engine",
+    "typescript",
+    "gamedev",
+    "ai-agents",
+    "mcp",
+    "net-forge",
+    "party-game"
+  ],
   "license": "MIT",
   "type": "module",
   "exports": {
     ".": "./src/manifest.ts",
-    "./store": "./src/store.ts"
+    "./store": "./src/store.ts",
+    "./package.json": "./package.json",
+    "./llms.txt": "./llms.txt",
+    "./llms-full.txt": "./llms-full.txt"
   },
   "files": [
     "src",
@@ -15,26 +32,37 @@
     "llms.txt",
     "README.md",
     "NOTICE",
-    "LICENSE"
+    "LICENSE",
+    "llms-full.txt",
+    "AGENTS.md",
+    "CLAUDE.md"
+  ],
+  "sideEffects": [
+    "./src/game.ts",
+    "./src/manifest.ts",
+    "./client/**"
   ],
   "publishConfig": {
     "access": "public"
   },
+  "homepage": "https://forge.netnet.capital/docs/templates/party",
+  "bugs": {
+    "url": "https://github.com/netnetdev/net-forge/issues"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/netnetdev/net-forge.git",
     "directory": "packages/template-party"
   },
-  "homepage": "https://github.com/netnetdev/net-forge/tree/main/packages/template-party#readme",
   "engines": {
     "node": ">=20"
   },
   "dependencies": {
     "nipplejs": "1.0.4",
     "three": "0.186.1",
-    "@netforge/asset-library": "0.1.0",
-    "@netforge/engine-sim": "0.1.0",
-    "@netforge/engine": "0.1.0"
+    "@netforge/asset-library": "0.2.0",
+    "@netforge/engine-sim": "0.2.0",
+    "@netforge/engine": "0.2.0"
   },
   "devDependencies": {
     "@types/node": "22.20.1",
@@ -44,9 +72,6 @@
     "vite": "6.4.3",
     "vitest": "3.2.7"
   },
-  "bugs": {
-    "url": "https://github.com/netnetdev/net-forge/issues"
-  },
   "scripts": {
     "build": "node ../engine/scripts/fresh-dist.mjs && vite build --config client/vite.config.ts",
     "typecheck": "tsc -p tsconfig.json",