@netforge/template-tower 0.0.0-stage → 0.2.0

package/AGENTS.md

@@ -0,0 +1,66 @@
+# Extending COGSPIRE
+
+COGSPIRE is the tower defense 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. src/names.json holds the title and every label players read. Towers go in "weapons" ({ name, line }), creeps in "enemies", plus upgrades, earn rules and store items. 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 { earn, game, prefab, store, tower, towerBoard, upgrade, waves } from "@netforge/engine";
+```
+
+Also available for this genre: `economy`. `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: "tower-defense", style, places, players: { prefab, max } })` with `players.max` at most 4.
+- Exactly one `towerBoard(...)` and one `waves(...)`; 1 to 8 `tower(...)`s.
+- The road is tile waypoints in `towerBoard({ path })`: each step changes x or y, never both, and it starts and ends on the board's edge. `blocked` tiles are rocks nobody builds on.
+- Every waves group names a declared creep prefab, not a pickup.
+- Tower kinds are "bolt", "splash", "frost" or "chain". Upgrades read four stats only: might, haste, area and maxHealth.
+- No `weapon(...)`: a tower defense game declares `tower(...)`.
+- `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: overclock, tempered_brass, spyglass, spare_bell, skin_verdigris, skin_gilt and the brass_gear 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/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 * 240, bots: 4 })`. It reports kills, wave reached, runs won and lost, leaks (as deaths), earned by rule, softlock, ms per tick, and the genre's own checks under rules.checks.
+
+## Play locally
+
+```sh
+mkdir -p my-game/src && cd my-game
+npm init -y && npm install @netforge/kit-play @netforge/engine @netforge/template-tower
+cp node_modules/@netforge/template-tower/src/game.ts src/
+echo '{"template":"tower-defense"}' > 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 write targeting or pathing code; towers and creeps are declared and the rules module runs them.
+
+## Docs
+
+https://forge.netnet.capital/docs/templates/tower

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/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,28 @@
+@netforge/template-tower (COGSPIRE)
+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 (Space Kit turrets, Nature Kit, monsters, robots), 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 tower defense genre's general mechanics (a fixed road, waves, towers
+  that target and upgrade, a bounty economy, lives). Mechanics, not
+  expression; no map, tower, creep, character or text was copied from any
+  game.

package/README.md

@@ -1,3 +1,81 @@
-# Temporary Holding Version
+# @netforge/template-tower
 
-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 co-op tower defense game template for Net Forge: up to 4 players on one shared board (COGSPIRE).
+
+Rust swarms crawl an old rail road toward a brass clockwork spire in waves. Each tinker builds and upgrades towers with their own gold, every kill pays its builder a bounty and a share to the rest, and the team shares the spire's bells. Hold twenty waves to keep the spire.
+
+It is a board genre: a deterministic rules module runs on the room host at 30 Hz behind the same adapter seam as the action templates. Your tinker (the cursor) is predicted; builds, upgrades, sells and the ready vote are actions the room validates (gold, tile, ownership). The client kit is `@netforge/tabletop`.
+
+Towers aim at the creep furthest along the road in range. Splash hits a radius, frost slows, chain jumps. A leak costs the creep's damage in bells, and zero bells loses the run.
+
+Earn: three waves, ten waves, the first boss and sixty kills. A player who joins mid-run is not paid for waves cleared before their run started.
+
+## Install
+
+```sh
+npm install @netforge/template-tower
+```
+
+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-tower
+cp node_modules/@netforge/template-tower/src/game.ts src/
+echo '{"template":"tower-defense"}' > 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
+
+The bolt post is the cheap first tower. Make it cheaper and give it more reach:
+
+```ts
+tower("bolt_post", {
+  model: "style.lowpoly.turret",
+  kind: "bolt",
+  cost: 35,
+  damage: 8,
+  rate: 1.5,
+  range: 3.5,
+  // levels stay as they are
+});
+```
+
+Save `src/game.ts` and run `npx kit-play` again.
+
+## Files
+
+| Path | What |
+|---|---|
+| `src/game.ts` | The game, declarations only: the board and road, towers, creeps, waves, upgrades, earn, store. |
+| `src/manifest.ts` | Loads the game; `towerAdapter()` and `towerManifest()` for the room host and the client. |
+| `src/store.ts` | The coin prices the client is wired to. |
+| `client/` | The browser client: the board, towers, creeps, tracers, the build bar and the tower panel. |
+| `test/` | Playtest bots through `engine.test.run`, and the store. |
+| `llms.txt` | How to change the game, for agents. |
+
+## Controls
+
+Click a tile to build the tower picked in the bar (keys 1 to 4), click a tower to upgrade or sell it, Space calls the next wave. Touch: tap a tile to aim, tap again to build. The backquote key shows stats.
+
+## 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/tower
+- `llms.txt` and `llms-full.txt` in this package (also exported as `@netforge/template-tower/llms.txt` and `@netforge/template-tower/llms-full.txt`)
+
+## License
+
+MIT. See `LICENSE` and `NOTICE`.

package/client/decor.ts

@@ -0,0 +1,11 @@
+/**
+ * Library models the scene draws on its own (not named in game.ts): the
+ * spire, the gate, the moor's trees and rocks. The build copies these into
+ * ./library next to the page, in every art style (?style= may draw any).
+ */
+export const SPIRE_MODEL = "style.lowpoly.obelisk";
+export const GATE_MODEL = "style.lowpoly.column_broken";
+export const ROCK_MODEL = "style.lowpoly.rock_large";
+export const TREE_MODELS = ["style.lowpoly.tree_pine", "style.lowpoly.tree_autumn", "style.lowpoly.tree_fat", "style.lowpoly.bush"] as const;
+export const SMALL_DECOR = ["style.lowpoly.rock_small", "style.lowpoly.mushroom_red", "style.lowpoly.stump", "style.lowpoly.flower_red"] as const;
+export const SCENE_MODELS: readonly string[] = [SPIRE_MODEL, GATE_MODEL, ROCK_MODEL, ...TREE_MODELS, ...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>Cogspire</title>
+  </head>
+  <body>
+    <script type="module" src="./main.ts"></script>
+  </body>
+</html>