@netforge/template-cards 0.0.0-stage → 0.2.0

package/AGENTS.md

@@ -0,0 +1,71 @@
+# Extending INKWRIT
+
+INKWRIT is the card battler template of the Net Forge game engine. The template already has the duel, turns and the turn timer, the server-side shuffle, hidden hands, guards, rush, the draft, the AI, 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. Cards go in `"weapons"` (`{ name, line }`), plus upgrades, earn rules and store items.
+- 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 { card, cardTable, earn, game, store, upgrade } from "@netforge/engine";
+```
+
+## Declarations
+
+- `game({ template: "cards", style, places, players: { prefab, max } })`, with `players.max` at most 2.
+- `cardTable({ health, startHand, handMax, boardMax, manaMax, turnSeconds, draftSeconds, duels, starter, ai })`, exactly one. `ai` is 1 to 12 tiers of `{ health, smart }`; duel n against the AI uses tier n.
+- `card(id, { model, kind: "unit" | "spell", cost, attack, health, guard?, rush?, effect? })`, 4 to 40 of them. Effects have kind `"damage"`, `"heal"`, `"draw"` or `"buff"` and target `"enemy"`, `"enemy_hero"`, `"all_enemies"`, `"own_hero"`, `"own_unit"` or `"all_own"`.
+- `upgrade(id, { stat, step, maxLevel })` with stat `maxHealth`, `might`, `haste` or `amount` only.
+- `earn.rule(id, { when, n, pay, oncePer: "run" })`. Events: `duel.won` (against a person, never a forfeit), `ai.beaten` 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.
+- The starter deck has 8 to 30 cards, names declared cards, and holds at least one unit and cards costing 2 or less.
+- A unit has health 1 or more. A spell has an effect.
+- No `weapon(...)` in a card game.
+- Asset ids are library ids such as `"style.lowpoly.frog"`, never URLs or paths. Keep `game({ style })` as the creator picked it.
+- Two playtest players must decide duels and fire an earn rule within 4 minutes.
+- Keep the SKUs the client is wired to at their prices: `thick_vellum`, `sharp_nib`, `quick_ink`, `spare_page`, `skin_vermilion`, `skin_gold_leaf` and `bound_folio`.
+- Nothing in `src/game.ts` can reveal deck order or another player's hand.
+
+## 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: 2, seed: 1 });
+console.log(report.kills, report.deaths, report.earned, report.rules?.checks);
+```
+
+`bots: 2` plays two people; `bots: 1` plays one person against the AI. The report has duels won (kills) and lost (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":"cards"}`) 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 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 INKWRIT, 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,28 @@
+@netforge/template-cards (INKWRIT)
+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 (monsters, animals, props), 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 collectible card battler genre's general mechanics (mana that rises
+  each turn, units and spells, guards, drafting between matches). Mechanics, not
+  expression; no card, rule text, character or art was copied from any
+  game.

package/README.md

@@ -1,3 +1,83 @@
-# Temporary Holding Version
+# @netforge/template-cards
 
-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 card battler game template for Net Forge: one against one, a person against a person or against a gauntlet of AI scribes (INKWRIT).
+
+Scribes duel in a lamplit study. Every card is an inked creature or a spell written on a page. A run is four duels, and after each one every player drafts one of three new cards into their deck. The room shuffles on the server and keeps hands hidden.
+
+## Install
+
+```sh
+npm install @netforge/template-cards
+```
+
+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-cards
+cp node_modules/@netforge/template-cards/src/game.ts src/
+echo '{"template":"cards"}' > netnet.json
+npx kit-play        # opens http://127.0.0.1:4663
+```
+
+Open the link in a second tab to duel yourself, or play alone against the AI. 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, give the heroes more health and add a fifth duel to the gauntlet:
+
+```ts
+cardTable({
+  health: 25,
+  duels: 5,
+  // ...the rest of the table as shipped, with a fifth ai tier
+});
+```
+
+Or add a card and put its label in `src/names.json` under `weapons`:
+
+```ts
+card("mirror_moth", { model: "style.lowpoly.jelly_flyer", kind: "unit", cost: 3, attack: 2, health: 2, effect: { kind: "damage", amount: 1, target: "all_enemies" } });
+```
+
+## How it plays on the server
+
+- A board genre on the engine's rules runtime (`@netforge/engine/rules`), drawn with `@netforge/tabletop`, at 30 Hz.
+- Your quill (the cursor) is predicted. A play, an attack, an end of turn and a draft pick are actions the room validates: whose turn it is, the card in that slot, ink and guards.
+- Hidden information: the room shuffles from its seeded PRNG and keeps the deck order to itself. A hand and a draft offer go only to their owner.
+- A person alone for 3 s gets a seat bot (an AI scribe of the gauntlet's tier), which leaves when a second person joins.
+- Earn: duels won against a person (never a forfeit) and AI scribes beaten. The AI never earns. 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; `cardsAdapter()` for the room host and the client (two seats). |
+| `src/store.ts` | Coin prices the client is wired to. |
+| `client/` | The desk, creatures on their cards, piles, quills, the hand, targeting and the draft. |
+| `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/cards
+- `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,8 @@
+/**
+ * Library models the scene draws on its own (not named in game.ts): the
+ * study around the table. The build copies these into ./library in every
+ * art style (?style= may draw any).
+ */
+export const LAMP_MODEL = "style.lowpoly.campfire";
+export const SHELF_MODELS = ["style.lowpoly.barrels", "style.lowpoly.crate", "style.lowpoly.chest", "style.lowpoly.column"] as const;
+export const SCENE_MODELS: readonly string[] = [LAMP_MODEL, ...SHELF_MODELS];

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>Inkwrit</title>
+  </head>
+  <body>
+    <script type="module" src="./main.ts"></script>
+  </body>
+</html>