@netforge/template-collector 0.0.0-stage → 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/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NetNet Capital Management
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,29 @@
+@netforge/template-collector (MOSSBOUND)
+Copyright (c) 2026 NetNet Capital Management
+
+An original game. No names, characters, maps, models, sounds or code from
+any other game or franchise.
+
+Art and sound
+- Models come from the per-style asset library
+  (@netforge/asset-library): CC0 1.0 models by Kenney and
+  Quaternius (animals, monsters, Nature Kit), each pack listed with its
+  source URL and licence verification in that package's NOTICE and
+  manifest/packs.json. The files are fetched and built, never committed
+  here; the build copies only the models this game uses.
+- Fallback shapes (@netforge/tabletop stage.ts) are generated from three.js
+  primitives; all textures are drawn on a canvas at load; sounds are the
+  library's CC0 samples with WebAudio synth fallbacks.
+
+Dependencies (unmodified, via npm)
+- three.js 0.186.1 (https://github.com/mrdoob/three.js), MIT.
+- @netforge/engine and @netforge/engine-sim (this repository);
+  see their NOTICE files (bitECS MPL-2.0, Rapier Apache-2.0, Colyseus MIT,
+  zod MIT).
+
+Patterns (ideas only)
+- The creature-collecting RPG genre's general mechanics (meeting creatures
+  in tall grass, turn-based battles, a small team, catching, levels).
+  Mechanics, not expression: the creatures, names, elements, items, map
+  and text are original, and no creature, design, type chart or item was
+  copied from any game.

package/README.md

@@ -1,3 +1,82 @@
-# Temporary Holding Version
+# @netforge/template-collector
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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).
+
+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.
+
+## 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
+
+- 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.
+
+## 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. |
+
+## 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
+npx -y @netforge/mcp
+```
+
+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/client/decor.ts

@@ -0,0 +1,13 @@
+/**
+ * Library models the scene draws on its own (not named in game.ts): the
+ * camp, the reeds, the rocks and trees of the marsh, the warden's mound.
+ * The build copies these into ./library, in every art style.
+ */
+export const TENT_MODEL = "style.lowpoly.tent";
+export const FIRE_MODEL = "style.lowpoly.campfire";
+export const REED_MODEL = "style.lowpoly.bush";
+export const ROCK_MODEL = "style.lowpoly.rock_tall";
+export const TREE_MODELS = ["style.lowpoly.tree_pine", "style.lowpoly.tree_dark", "style.lowpoly.tree_fat"] as const;
+export const MOUND_MODEL = "style.lowpoly.column_broken";
+export const SMALL_DECOR = ["style.lowpoly.mushroom_red", "style.lowpoly.flower_red", "style.lowpoly.stump", "style.lowpoly.log"] as const;
+export const SCENE_MODELS: readonly string[] = [TENT_MODEL, FIRE_MODEL, REED_MODEL, ROCK_MODEL, ...TREE_MODELS, MOUND_MODEL, ...SMALL_DECOR];

package/client/index.html

@@ -0,0 +1,11 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover, user-scalable=no" />
+    <title>Mossbound</title>
+  </head>
+  <body>
+    <script type="module" src="./main.ts"></script>
+  </body>
+</html>