@netforge/template-collector 0.1.0 → 0.2.0

package/AGENTS.md

@@ -0,0 +1,73 @@
+# Extending MOSSBOUND
+
+MOSSBOUND is the monster collector template of the Net Forge game engine. The template already has walking and collision, encounters, turn order, damage, the element cycle, snaring, team swaps, XP and levels, the camp, the warden fight, dusk, netcode, rendering, touch controls, earn and the store. You change the game by changing declarations. Read `llms.txt` for every field, and `llms-full.txt` for the complete worked example.
+
+## The one file to edit
+
+- `src/game.ts` is the whole game. Change declarations in place.
+- `src/names.json`, next to it, holds the title and every label players read. Creatures go in `"weapons"` (`{ name, line }`), the warden in `"enemies"`, plus upgrades, earn rules and store items. Moves are shown from their ids (`leaf_lash` reads "Leaf Lash").
+- Everything else (`src/manifest.ts`, `src/store.ts`, `client/`, `test/`, `scripts/`) is template machinery. Do not edit it.
+
+## Imports
+
+`src/game.ts` imports only from `@netforge/engine`. The shipped game uses:
+
+```ts
+import { creature, earn, game, marsh, move, store, upgrade } from "@netforge/engine";
+```
+
+## Declarations
+
+- `game({ template: "collector", style, places, players: { prefab, max } })`.
+- `marsh({ size, camp, starters, starterLevel, water, blocked, grass, warden, dusk, snares })`, exactly one. Rects are `[x, y, width, height]` in 2 m tiles.
+- `creature(id, { model, element, hp, atk, def, spd, moves, catchRate?, boss?, size? })`, 1 to 24 of them. Base stats are at level 1 and grow 12% a level.
+- `move(id, { element, power, accuracy?, effect?, amount? })`, at most 48. Effects are `"drain"`, `"heal"` and `"guard"`.
+- `upgrade(id, { stat, step, maxLevel })` with stat `might`, `maxHealth`, `armor`, `amount` or `regen` only.
+- `earn.rule(id, { when, n, pay, oncePer: "run" })`. Events: `creature.caught`, `creature.defeated`, `creature.levelup`, `level.five`, `level.ten`, `warden.defeated` and `run.won`.
+- `earn.stake({ min, max, multiple })`, exactly one, on one top-level line.
+- `store.sku(id, { coins, grants? })`.
+
+## Rules the build enforces
+
+- Ids are lower_snake_case.
+- Every game declares at least one `earn.rule` and exactly one `earn.stake`. `"stake"` is reserved.
+- Every creature's moves are declared moves, 1 to 4 each.
+- Starters and grass pools name declared creatures that are not bosses. The warden names a creature with `boss: true`.
+- The camp and the warden stand inside the marsh on tiles that are not blocked. Grass and blocked rects stay inside the marsh. Leave a walkable way from camp to every grass zone and to the warden.
+- Elements are `root`, `tide`, `spark` and `stone`, a cycle where each beats the next.
+- No `weapon(...)` in a collector game.
+- Asset ids are library ids such as `"style.lowpoly.frog"`, never URLs or paths, and must exist in the asset library. Keep `game({ style })` as the creator picked it.
+- Four playtest keepers must win battles, catch creatures and fire an earn rule in 4 minutes, and must not lose their whole team more than twice each.
+- Keep the SKUs the client is wired to at their prices: `thornbark`, `mossmail`, `spare_snares`, `fen_tonic`, `skin_lichen`, `skin_amber` and `lucky_reed`.
+
+## Validate
+
+- With the MCP server (`npx -y @netforge/mcp`), call `netforge_validate_game` on `src/game.ts`. It returns one actionable line per problem.
+- In this package, run the tests with vitest: `test/harness.test.ts` and `test/store.test.ts`.
+
+## Playtest
+
+- With the MCP server, call `netforge_run_playtest`.
+- In code, import the game module and run the headless harness:
+
+```ts
+import { engine } from "@netforge/engine";
+import "./src/game.js";
+
+const report = await engine.test.run({ ticks: 30 * 240, bots: 4, seed: 1 });
+console.log(report.kills, report.deaths, report.earned, report.rules?.checks);
+```
+
+The report has battles won plus catches (kills), team wipes (deaths), earn by rule, softlock, ms per tick and the genre's checks under `rules.checks`.
+
+## Play locally
+
+In a folder with `netnet.json` (`{"template":"collector"}`) and `src/game.ts`, with `@netforge/kit-play` and `@netforge/engine` installed, run `npx kit-play`. It opens http://127.0.0.1:4663 with play money. The MCP tool `netforge_play_locally` gives the same steps.
+
+## Do not
+
+- Do not write renderers, netcode, physics or battle AI. The template has them.
+- Do not reference assets by URL or file path.
+- 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 SKUs the client is wired to.

package/CLAUDE.md

@@ -0,0 +1,11 @@
+# CLAUDE.md
+
+This package is MOSSBOUND, a Net Forge game template. Read AGENTS.md before changing this game. It lists the declarations this genre has, the rules the build enforces, and how to validate, playtest and play the game locally.
+
+The five hard rules:
+
+1. Edit only src/game.ts (and src/names.json for the labels players read).
+2. Import only from @netforge/engine.
+3. Ids are lower_snake_case.
+4. Declare at least one earn.rule and exactly one earn.stake.
+5. Never write renderers, netcode, physics or bot AI, and never reference assets by URL or file path (use library ids such as "style.lowpoly.frog").

package/README.md

@@ -1,50 +1,82 @@
-# MOSSBOUND (monster collector template)
+# @netforge/template-collector
 
-Fen spirits live in the tall grass of a flooded marsh. Each keeper picks a
-starter at camp, walks the reeds, meets wild spirits in the grass and
-battles them turn by turn with a team of three, snaring the ones worth
-keeping in a reed lantern. At the far end of the marsh the Fenwarden waits:
-every keeper in the marsh wears down the same warden, and it must fall
-before dusk.
+A monster collector game template for Net Forge: a shared marsh for up to 8 keepers who catch creatures, battle turn by turn and bring down one warden together (MOSSBOUND).
 
-A board genre (`packages/engine/src/rules/collector.ts`) on the room
-server at 30 Hz behind the same SimAdapter seam as every template. The
-client kit is `@netforge/tabletop`.
+Fen spirits live in the tall grass of a flooded marsh. Each keeper picks a starter at camp, walks the reeds, meets wild spirits in the grass and battles them with a team of three, snaring the ones worth keeping in a reed lantern. At the far end of the marsh the Fenwarden waits. Every keeper wears down the same warden, and it must fall before dusk.
 
-| Path | What |
-|---|---|
-| `src/game.ts` | The game, as the model writes it (declarations only). |
-| `src/manifest.ts` | Loads it; `collectorAdapter()` for the room server and client. Room template `collector`. |
-| `src/store.ts` | Coin prices the client is wired to, the template's own coin (MOSS). |
-| `client/` | The browser client: the marsh, keepers, companions, the battle panel, the starter pick. |
-| `test/` | Playtest bots through `engine.test.run`, and the store. |
-| `llms.txt` | How to change the game (for agents). |
+## Install
+
+```sh
+npm install @netforge/template-collector
+```
+
+You rarely import this package directly. kit play (`@netforge/kit-play`) and the Net Forge MCP server use it to build and run a game whose `src/game.ts` you write.
+
+## Play it locally
+
+```sh
+mkdir -p my-game/src && cd my-game
+npm init -y && npm install @netforge/kit-play @netforge/engine @netforge/template-collector
+cp node_modules/@netforge/template-collector/src/game.ts src/
+echo '{"template":"collector"}' > netnet.json
+npx kit-play        # opens http://127.0.0.1:4663
+```
+
+Open the link in more tabs for more keepers. Coins are play money. Real-token earning, stakes and claims run only on the hosted Net Forge server.
+
+## Change the game
+
+Edit `src/game.ts` and run `npx kit-play` again. For example, make the warden tougher and give keepers more time and snares in `marsh({ ... })`:
+
+```ts
+warden: { creature: "fenwarden", at: [27, 10], level: 10, hp: 900 },
+dusk: 720,
+snares: 8,
+```
+
+Or add a creature and a move, then put the creature in a grass pool and its label in `src/names.json` under `weapons`:
+
+```ts
+creature("thistlehog", { model: "style.lowpoly.fox", element: "root", hp: 50, atk: 52, def: 48, spd: 46, moves: ["leaf_lash", "thorn_curl"], catchRate: 0.7 });
+move("thorn_curl", { element: "root", power: 0, effect: "guard" });
+```
 
 ## How it plays on the server
 
-- Your keeper walks with a stick (WASD, arrows, or the left thumb) and is
-  predicted with the same tile collision the room runs, so walking never
-  waits. Every roll (encounters, accuracy, damage spread, snares, the foe's
-  move) is the room's PRNG, so a run replays exactly from its inputs.
-- Battles are private: your team, your foe and the battle log reach only
-  you (SimAdapter.infoFor). Others see the creature beside you.
-- The warden's health is one pool for the whole marsh; when it falls,
-  everyone who hurt it is paid. Dusk ends the run.
-- Earn (the room is the referee): the first catch, three catches, the
-  warden, a creature at level 5. All are a player's own acts except the
-  warden, which pays only those who hurt it.
+- A board genre on the engine's rules runtime (`@netforge/engine/rules`) at 30 Hz, drawn with `@netforge/tabletop`.
+- Your keeper walks with a stick (WASD, arrows or the left thumb) and is predicted with the same tile collision the room runs. Every roll (encounters, accuracy, damage spread, snares, the foe's move) comes from the room's PRNG, so a run replays exactly from its inputs.
+- Battles are private: your team, your foe and the battle log reach only you. Others see the creature beside you.
+- The warden's health is one pool for the whole marsh. When it falls, everyone who hurt it is paid. Dusk ends the run.
+- Earn: the first catch, three catches, the warden and a creature at level 5. The room server is the referee.
 
-## Run it
+## Files
+
+| Path | What |
+|---|---|
+| `src/game.ts` | The game, as declarations only. This is the file you edit. |
+| `src/manifest.ts` | Loads the game; `collectorAdapter()` for the room host and the client. |
+| `src/store.ts` | Coin prices the client is wired to. |
+| `client/` | The marsh, keepers, companions, the battle panel and the starter pick. |
+| `test/` | Playtest bots through `engine.test.run`, and the store test. |
+| `llms.txt`, `llms-full.txt` | How to change the game, for agents. |
 
-This template runs on your own computer with play money through
-`kit play` (`@netforge/kit-play`). From the repository root:
+## For AI agents
+
+Read `AGENTS.md` and `llms.txt` before editing. The Net Forge MCP server gives a coding agent the templates, the API and a playtest loop:
 
 ```sh
-pnpm install --frozen-lockfile && pnpm build
-mkdir -p play-collector/src && cp packages/template-collector/src/game.ts play-collector/src/
-echo '{"template":"collector"}' > play-collector/netnet.json
-node packages/kit-play/dist/cli.js play-collector       # opens http://127.0.0.1:4663
+npx -y @netforge/mcp
 ```
 
-Edit `play-collector/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.
+The package is `@netforge/mcp` and its bin is `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/collector
+- `llms.txt` and `llms-full.txt` in this package. The full file includes the complete `src/game.ts` and the validate and playtest steps.
+
+## License
+
+MIT. See LICENSE and NOTICE.

package/llms-full.txt

@@ -0,0 +1,277 @@
+# Net Forge monster collector template (MOSSBOUND)
+
+> A shared marsh for up to 8 keepers. Each picks one of the starters at
+> camp, walks the marsh, meets wild creatures in tall grass and battles them
+> turn by turn with a team of three, snaring the ones worth keeping. Every
+> keeper in the marsh wears down the same warden; it must fall before dusk.
+> You change the game by editing src/game.ts only. The template already has
+> walking and collision, encounters, turn order, damage, the element cycle,
+> snaring, team swaps, XP and levels, the camp, the warden fight, dusk,
+> netcode, rendering, touch controls, earn and the store. Do not write
+> renderers, netcode or battle AI.
+
+## Files
+
+- src/game.ts: THE GAME. Declarations against @netforge/engine:
+  game(), marsh(), creature(), move(), upgrade(), earn.rule(), earn.stake(), store.sku().
+- src/names.json: the title and every label players read. Creatures go in
+  "weapons" ({ name, line }), the warden in "enemies", plus upgrades, earn
+  rules and store items. Moves are shown from their ids ("leaf_lash" reads
+  "Leaf Lash"), so name moves the way players should read them.
+- Everything else is template machinery.
+
+## Rules the build enforces
+
+- game({ template: "collector", style, places, players: { prefab, max } }).
+- Exactly one marsh(...); 1 to 24 creature(...)s; at most 48 move(...)s.
+- Every creature's moves are declared moves (1 to 4 each).
+- marsh starters and grass pools name declared creatures that are not
+  bosses; the warden names a creature with boss: true.
+- The camp and the warden stand inside the marsh on tiles that are not
+  blocked; grass and blocked rects stay inside the marsh.
+- Elements are "root", "tide", "spark", "stone": a cycle where each beats
+  the next (root soaks tide, tide shorts spark, spark cracks stone, stone
+  crushes root). Strong hits deal 1.5x, weak ones 0.67x.
+- Upgrades read five stats only: might (team attack), maxHealth (team
+  health, a fraction: 0.15 is +15%), armor (team defence), amount (extra
+  snares) and regen (share of max health healed each second out of battle).
+- No weapon(...): a collector game declares creature(...) and move(...).
+- Asset ids look like "style.lowpoly.frog", 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.
+- 4 playtest keepers must win battles, catch creatures and fire an earn rule
+  in 4 minutes, and must not lose their whole team more than twice each.
+
+## Units
+
+A tile is 2 m; marsh rects are [x, y, width, height] in tiles. Stats are
+base values at level 1 and grow 12% a level. power 40 is a plain hit.
+Walking speed is metres a second. Tick rate 30 Hz.
+
+## The loop
+
+A keeper picks a starter at camp (starterLevel). Every step into a new tile
+of tall grass rolls the zone's rate; a hit starts a battle with a creature
+from the zone's pool at a level in its range. A turn: you pick a move, a
+swap, a snare or flee; the faster creature acts first; the foe answers
+with its best move. A beaten foe gives XP (the active creature full, the
+rest half). A snare's chance is catchRate x (0.25 + 0.75 x the foe's
+missing health); a caught creature joins the team (three at most; more go
+into the lantern). Wild creatures hit at 80%. If your whole team faints you
+are sent to camp with half health; standing at camp heals. Near the
+warden, Challenge starts the warden fight: its health is one pool for the
+whole marsh, it hits at full strength, and when it falls everyone who hurt
+it shares the win. At dusk the run is lost.
+
+## Common changes
+
+### A new creature
+creature("thistlehog", { model: "style.lowpoly.fox", element: "root", hp: 50, atk: 52, def: 48, spd: 46, moves: ["leaf_lash", "thorn_curl"], catchRate: 0.7 });
+move("thorn_curl", { element: "root", power: 0, effect: "guard" });
+Then put it in a grass pool, and its label in names.json weapons.
+
+### Moves
+move("tide_crash", { element: "tide", power: 70, accuracy: 0.8 });
+effect "drain" heals half the damage dealt; "heal" (power 0) restores
+amount of max health; "guard" halves the next hit taken.
+
+### The map
+marsh({ size: [30, 20], camp: [2, 10], water: [[11, 0, 2, 6]], blocked: [[19, 0, 1, 8]],
+  grass: [{ at: [4, 2, 6, 5], rate: 0.22, pool: [{ creature: "sporecap", weight: 3, level: [2, 3] }] }], ... });
+Put weak creatures near camp and stronger ones toward the warden. Leave a
+walkable way from camp to every grass zone and to the warden.
+
+### Harder or easier
+Raise pool levels, the warden's level or hp, or lower snares and grass
+rates. "Longer": a later dusk. "More catching": higher catchRate and snares.
+
+### Add an earn rule
+earn.rule("ten_wins", { when: "creature.defeated", n: 10, pay: 15, oncePer: "run" });
+Events: creature.caught, creature.defeated, creature.levelup, level.five
+and level.ten (each credits the keeper), warden.defeated (everyone who hurt
+it), run.won (everyone in the marsh). 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 });
+One top-level line; a game without it does not build. "stake" is reserved.
+
+### Coins: earn and the store
+Every game has coins: 1 coin = 1 of the game's own token, shown under the
+token's own name, symbol and logo.
+store.sku("thornbark", { coins: 40 });                                  // one level of the "thornbark" upgrade for the run
+store.sku("skin_amber", { coins: 500, grants: { cosmetic: 2 } });       // a keeper's cloak, owned for good
+store.sku("lucky_reed", { coins: 150, grants: { gear: "thornbark", loseBelow: 0.25 } }); // losable gear
+Keep the SKUs the client is wired to (thornbark, mossmail, spare_snares,
+fen_tonic, skin_lichen, skin_amber, lucky_reed) at their prices.
+
+## Test
+
+engine.test.run({ ticks: 30 * 240, bots: 4 }) plays the marsh with 4
+keepers and reports battles won plus catches (kills), 1 + catches (wave),
+the highest level, team wipes (deaths), earned by rule, softlock, ms per
+tick, and the genre's own checks under rules.checks.
+
+## Worked example: src/game.ts
+
+This is the template's complete src/game.ts as it ships. A new game on this
+template starts from this file and changes declarations in place.
+
+```ts
+/**
+ * MOSSBOUND: the monster collector template (play style: monster-collector RPG).
+ *
+ * Fen spirits live in the tall grass of a flooded marsh. Each keeper picks
+ * one of three starters at camp, walks the reeds, meets wild spirits in the
+ * grass and battles them turn by turn with a team of three, snaring the
+ * ones worth keeping in a reed lantern. At the far end of the marsh the
+ * Fenwarden waits: every keeper in the marsh wears down the same warden,
+ * and it must fall before dusk.
+ *
+ * This file is the whole game as the model writes it: declarations only,
+ * against the typed API in @netforge/engine. Walking, encounters,
+ * battles, catching, levels, netcode, renderer and referee are the
+ * template's machinery.
+ */
+import { creature, earn, game, marsh, move, store, upgrade } from "@netforge/engine";
+
+export default game({
+  template: "collector",
+  style: "lowpoly",
+  places: { fen: { chunks: "places/fen", spawn: [0, 0, 0] } },
+  players: { prefab: "style.lowpoly.hooded_adventurer", max: 8 },
+});
+
+// The marsh: 30 x 20 tiles of 2 m. Camp in the west, the warden's mound in the east, water and rocks between.
+marsh({
+  size: [30, 20],
+  camp: [2, 10],
+  starters: ["mossling", "cindertail", "puddlewump"],
+  starterLevel: 4,
+  water: [
+    [11, 0, 2, 6],
+    [11, 14, 2, 6],
+    [24, 0, 3, 3],
+  ],
+  blocked: [
+    [19, 0, 1, 8],
+    [19, 12, 1, 8],
+    [8, 9, 1, 2],
+    [15, 2, 1, 1],
+    [16, 16, 1, 1],
+  ],
+  grass: [
+    { at: [4, 2, 6, 5], rate: 0.22, pool: [{ creature: "sporecap", weight: 3, level: [2, 3] }, { creature: "voltmoth", weight: 2, level: [2, 3] }, { creature: "reedcrab", weight: 1, level: [2, 4] }] },
+    { at: [4, 13, 6, 5], rate: 0.22, pool: [{ creature: "reedcrab", weight: 2, level: [2, 4] }, { creature: "sporecap", weight: 1, level: [3, 4] }, { creature: "pebblewing", weight: 1, level: [3, 4] }] },
+    { at: [14, 7, 4, 6], rate: 0.2, pool: [{ creature: "pebblewing", weight: 2, level: [4, 6] }, { creature: "voltmoth", weight: 2, level: [4, 6] }, { creature: "bogling", weight: 1, level: [5, 6] }] },
+    { at: [21, 4, 4, 12], rate: 0.18, pool: [{ creature: "bogling", weight: 2, level: [6, 8] }, { creature: "pebblewing", weight: 1, level: [6, 8] }, { creature: "reedcrab", weight: 1, level: [6, 8] }] },
+  ],
+  warden: { creature: "fenwarden", at: [27, 10], level: 9, hp: 700 },
+  dusk: 600,
+  snares: 6,
+});
+
+// Creatures. Base stats at level 1 (each grows 12% a level); catchRate scales every snare.
+creature("mossling", { model: "style.lowpoly.frog", element: "root", hp: 46, atk: 48, def: 50, spd: 44, moves: ["leaf_lash", "sap_drink"] });
+creature("cindertail", { model: "style.lowpoly.fox", element: "spark", hp: 40, atk: 54, def: 42, spd: 58, moves: ["ember_nip", "static_dash"] });
+creature("puddlewump", { model: "style.lowpoly.slime_drop", element: "tide", hp: 52, atk: 44, def: 52, spd: 40, moves: ["splash_jab", "bubble_ward"] });
+creature("sporecap", { model: "style.lowpoly.mushroom_imp", element: "root", hp: 42, atk: 46, def: 46, spd: 38, moves: ["spore_puff", "leaf_lash"], catchRate: 0.9 });
+creature("voltmoth", { model: "style.lowpoly.bee", element: "spark", hp: 36, atk: 50, def: 38, spd: 64, moves: ["static_dash", "ember_nip"], catchRate: 0.85 });
+creature("reedcrab", { model: "style.lowpoly.crab", element: "tide", hp: 48, atk: 50, def: 60, spd: 36, moves: ["splash_jab", "shell_up"], catchRate: 0.8 });
+creature("pebblewing", { model: "style.lowpoly.pebble_flyer", element: "stone", hp: 44, atk: 48, def: 56, spd: 50, moves: ["gravel_toss", "shell_up"], catchRate: 0.7 });
+creature("bogling", { model: "style.lowpoly.blob_orc", element: "stone", hp: 60, atk: 52, def: 54, spd: 30, moves: ["gravel_toss", "mire_slam"], catchRate: 0.6, size: 1.3 });
+creature("fenwarden", { model: "style.lowpoly.mushroom_king", element: "stone", hp: 120, atk: 66, def: 64, spd: 40, moves: ["mire_slam", "gravel_toss", "sap_drink"], boss: true, size: 3.4 });
+
+// Moves. power 40 is a plain hit; drain heals half the damage, heal restores a share of max health, guard halves the next hit.
+move("leaf_lash", { element: "root", power: 40 });
+move("sap_drink", { element: "root", power: 30, effect: "drain" });
+move("spore_puff", { element: "root", power: 45, accuracy: 0.9 });
+move("ember_nip", { element: "spark", power: 40 });
+move("static_dash", { element: "spark", power: 55, accuracy: 0.85 });
+move("splash_jab", { element: "tide", power: 40 });
+move("bubble_ward", { element: "tide", power: 0, effect: "heal", amount: 0.3 });
+move("gravel_toss", { element: "stone", power: 40 });
+move("shell_up", { element: "stone", power: 0, effect: "guard" });
+move("mire_slam", { element: "stone", power: 70, accuracy: 0.8 });
+
+// Store upgrades: one level each, for the rest of the run, on the buyer's own team.
+upgrade("thornbark", { stat: "might", step: 0.15, maxLevel: 1 });
+upgrade("mossmail", { stat: "armor", step: 0.15, maxLevel: 1 });
+upgrade("spare_snares", { stat: "amount", step: 3, maxLevel: 1 });
+upgrade("fen_tonic", { stat: "regen", step: 0.03, maxLevel: 1 });
+
+// Earn (mandatory). Pays the game's coins (1 coin = 1 token), once per run each. Values are PLACEHOLDER.
+earn.rule("first_snare", { when: "creature.caught", n: 1, pay: 5, oncePer: "run" });
+earn.rule("full_lantern", { when: "creature.caught", n: 3, pay: 20, oncePer: "run" });
+earn.rule("warden_breaker", { when: "warden.defeated", n: 1, pay: 50, oncePer: "run" });
+earn.rule("seasoned", { when: "level.five", n: 1, pay: 5, oncePer: "run" });
+// Buy-in run (the mandatory sink loop): stake coins at run start to earn above free play.
+// A staked run also pays up to stake x multiple, by the share of this run's earn the player makes. Values are PLACEHOLDER.
+earn.stake({ min: 20, max: 200, multiple: 2 });
+
+// Store (the Kit), priced in coins: four run upgrades and two keeper finishes owned for good (kept in the profile).
+store.sku("thornbark", { coins: 40 });
+store.sku("mossmail", { coins: 40 });
+store.sku("spare_snares", { coins: 60 });
+store.sku("fen_tonic", { coins: 50 });
+store.sku("skin_lichen", { coins: 300, grants: { cosmetic: 1 } });
+store.sku("skin_amber", { coins: 500, grants: { cosmetic: 2 } });
+// Losable gear: owned for good until lost. It brings one level of its upgrade into every staked run,
+// and is lost when that run makes less than loseBelow of its most earn. Values are PLACEHOLDER.
+store.sku("lucky_reed", { coins: 150, grants: { gear: "thornbark", loseBelow: 0.25 } });
+```
+
+## Validate and playtest
+
+### With the MCP server
+
+Run `npx -y @netforge/mcp` (package @netforge/mcp, bin netforge-mcp) and
+connect it to your coding agent. 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.
+
+- netforge_validate_game checks src/game.ts against the engine's schemas and this
+  template's rules, and returns one actionable line per problem.
+- netforge_run_playtest plays the game headless with bots and returns the report.
+- netforge_play_locally gives the steps to open the game in a browser with kit play.
+
+### In code
+
+Import the game module first so its declarations register, then run the
+headless harness. This plays 4 keepers for 4 minutes at 30 Hz.
+
+```ts
+import { engine } from "@netforge/engine";
+import "./src/game.js";
+
+const report = await engine.test.run({
+  ticks: 30 * 240,
+  bots: 4,
+  seed: 1,
+  assert: [
+    { name: "earn fired", check: (r) => r.earnEmitted > 0 },
+    { name: "no softlock", check: (r) => !r.softlock },
+  ],
+});
+if (report.failed.length > 0) throw new Error(report.failed.join("\n"));
+```
+
+The report has battles won plus catches (kills), team wipes (deaths), earned by rule, softlock, ms per tick and the genre's checks under rules.checks.
+
+The template's own tests (vitest) are the reference checks:
+
+- test/harness.test.ts
+- test/store.test.ts
+
+### Play it locally
+
+In a folder with netnet.json and src/game.ts:
+
+```sh
+npm install @netforge/kit-play @netforge/engine @netforge/template-collector
+echo '{"template":"collector"}' > netnet.json
+npx kit-play        # opens http://127.0.0.1:4663
+```
+
+kit play builds the template client with your src/game.ts and runs a local
+room host with play money. No wallet, no chain and no hosted servers are
+involved. Open the link in more tabs for more players.

package/llms.txt

@@ -1,4 +1,4 @@
-# MOSSBOUND: the monster collector template (NetNet game runtime, board genre)
+# Net Forge monster collector template (MOSSBOUND)
 
 > A shared marsh for up to 8 keepers. Each picks one of the starters at
 > camp, walks the marsh, meets wild creatures in tall grass and battles them

package/package.json

@@ -1,12 +1,34 @@
 {
   "name": "@netforge/template-collector",
-  "version": "0.1.0",
-  "description": "MOSSBOUND: the monster collector template of the NetNet game runtime, a shared marsh where keepers catch fen spirits, battle turn by turn with a team of three and bring down the warden before dusk. The game module, its browser client and its playtest bots.",
+  "version": "0.2.0",
+  "description": "Monster collector game template for Net Forge: a shared marsh where players catch creatures and battle turn by turn with a team of three (MOSSBOUND).",
+  "keywords": [
+    "game-template",
+    "multiplayer",
+    "browser-game",
+    "html5-game",
+    "threejs",
+    "game-engine",
+    "typescript",
+    "gamedev",
+    "ai-agents",
+    "mcp",
+    "net-forge",
+    "monster-collector"
+  ],
   "license": "MIT",
   "type": "module",
+  "sideEffects": [
+    "./src/game.ts",
+    "./src/manifest.ts",
+    "./client/**"
+  ],
   "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 +37,32 @@
     "llms.txt",
     "README.md",
     "NOTICE",
-    "LICENSE"
+    "LICENSE",
+    "llms-full.txt",
+    "AGENTS.md",
+    "CLAUDE.md"
   ],
   "publishConfig": {
     "access": "public"
   },
+  "homepage": "https://forge.netnet.capital/docs/templates/collector",
+  "bugs": {
+    "url": "https://github.com/netnetdev/net-forge/issues"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/netnetdev/net-forge.git",
     "directory": "packages/template-collector"
   },
-  "homepage": "https://github.com/netnetdev/net-forge/tree/main/packages/template-collector#readme",
   "engines": {
     "node": ">=20"
   },
   "dependencies": {
     "three": "0.186.1",
-    "@netforge/asset-library": "0.1.0",
-    "@netforge/engine-sim": "0.1.0",
-    "@netforge/tabletop": "0.1.0",
-    "@netforge/engine": "0.1.0"
+    "@netforge/asset-library": "0.2.0",
+    "@netforge/engine": "0.2.0",
+    "@netforge/engine-sim": "0.2.0",
+    "@netforge/tabletop": "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",