@netforge/template-cards 0.0.0-stage → 0.1.0

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,47 @@
-# Temporary Holding Version
+# INKWRIT (card battler template)
 
-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.
+Scribes duel in a lamplit study. Every card is an inked creature or a
+spell written on a page. One against one, a person against a person or
+against the gauntlet's AI scribes; a run is four duels with a draft of one
+of three cards after each.
+
+A board genre (`packages/engine/src/rules/cards.ts`) on the room server's
+SimAdapter seam, drawn with `@netforge/tabletop`.
+
+| Path | What |
+|---|---|
+| `src/game.ts` | The game, as the model writes it (declarations only). |
+| `src/manifest.ts` | Loads it; `cardsAdapter()` for the room server and client. Room template `cards` (two seats). |
+| `src/store.ts` | Coin prices the client is wired to, the template's own coin (INK). |
+| `client/` | The desk, creatures on their cards, piles, quills, the hand, targeting, the draft. |
+| `test/` | Playtest bots and the store. |
+| `llms.txt` | How to change the game (for agents). |
+
+## How it plays on the server
+
+- Server-authoritative 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, the card in that slot, ink, 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 (`SimAdapter.infoFor`). Snapshots carry the quills only.
+  The room server's tests check it every few ticks of a run.
+- A person alone for 3 s gets a seat bot (an AI scribe of the gauntlet's
+  tier); it leaves when a second person joins (that duel is called off).
+- Earn (the room is the referee): duels won against a person (never a
+  forfeit), AI scribes beaten. The AI never earns. Pots stay off.
+
+## Run it
+
+This template runs on your own computer with play money through
+`kit play` (`@netforge/kit-play`). From the repository root:
+
+```sh
+pnpm install --frozen-lockfile && pnpm build
+mkdir -p play-cards/src && cp packages/template-cards/src/game.ts play-cards/src/
+echo '{"template":"cards"}' > play-cards/netnet.json
+node packages/kit-play/dist/cli.js play-cards       # opens http://127.0.0.1:4663
+```
+
+Edit `play-cards/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.

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>

package/client/main.ts

@@ -0,0 +1,688 @@
+/**
+ * INKWRIT client: a duel at a scribe's desk. Your hand is at the bottom
+ * (only you and the room ever see it), your inked creatures stand on their
+ * cards on your side of the desk, the other scribe's on theirs. Click a
+ * card to play it (spells that aim ask for a target), click one of your
+ * ready creatures and then a target to attack, End turn passes. Between
+ * duels you draft one of three new cards. Alone, an AI scribe of the
+ * gauntlet takes the other seat. The room decides every draw, hit and win.
+ *
+ * URL parameters: see @netforge/tabletop boot.ts.
+ */
+import { BoxGeometry, CanvasTexture, Color, ConeGeometry, CylinderGeometry, Group, Mesh, MeshStandardMaterial, PlaneGeometry, SRGBColorSpace } from "three/webgpu";
+import type { InterpolatedEntity } from "@netforge/engine/net";
+import { CardAct, RF, RulesKind, Target, UNITS } from "@netforge/engine/rules";
+import type { RulesInput } from "@netforge/engine/rules";
+import { bootBoard, cssColor, type BoardView, type Placed } from "@netforge/tabletop";
+import { cardsAdapter, cardsGame, cardsManifest, COSMETICS, GAME_VERSION, PLACE, TEMPLATE } from "../src/manifest.js";
+import { INKWRIT_COIN } from "../src/store.js";
+import { LAMP_MODEL, SHELF_MODELS } from "./decor.js";
+import { KEEPER_COLORS, RULE_NAMES, SKU_NAMES, TITLE, UPGRADE_NAMES, WEAPON_NAMES } from "./names.js";
+
+interface UnitV {
+  readonly type: number;
+  readonly attack: number;
+  readonly health: number;
+  readonly maxHealth: number;
+  readonly guard: boolean;
+  readonly ready: boolean;
+}
+interface SideV {
+  readonly player: number;
+  readonly hero: number;
+  readonly heroMax: number;
+  readonly mana: number;
+  readonly maxMana: number;
+  readonly hand: number;
+  readonly deck: number;
+  readonly board: readonly UnitV[];
+}
+interface CardsView extends BoardView {
+  readonly stage: "waiting" | "duel" | "draft" | "done";
+  readonly duelNo: number;
+  readonly duels: number;
+  readonly countdown: number;
+  readonly duel: { readonly turn: number; readonly turnNo: number; readonly timer: number; readonly tier: number; readonly sides: readonly SideV[] } | null;
+  readonly log: readonly { p: number; kind: string; card: number; target: number }[];
+  readonly players: readonly { id: number; bot: boolean; wins: number; losses: number; draws: number; deck: number }[];
+  readonly hand?: readonly number[];
+  readonly offer?: readonly number[] | null;
+  readonly list?: readonly number[];
+}
+
+const genre = cardsGame();
+const g = genre.game;
+const manifest = cardsManifest();
+const FINISH = [0x2b2b2b, 0xb2382e, 0xd4af37];
+const W = 18;
+const H = 13;
+const cardName = (type: number) => WEAPON_NAMES[g.cards[type]?.id ?? ""]?.name ?? g.cards[type]?.id ?? "?";
+const cardLine = (type: number) => WEAPON_NAMES[g.cards[type]?.id ?? ""]?.line ?? "";
+
+let lastView: CardsView | null = null;
+let selfId = 0;
+
+/** The browser's autopilot (?autopilot=1): draft the first offer; on our turn play what we can afford, attack, end. */
+const autopilot = (tick: number): RulesInput | null => {
+  const v = lastView;
+  if (!v || tick % 12 !== 0) return null;
+  const go = (act: number, a = 0, b = 0, c = 0): RulesInput => ({ mx: 0, mz: 0, cx: 0, cz: 0, act, a, b, c });
+  if (v.stage === "draft" && v.offer) return go(CardAct.Draft, 0);
+  const d = v.duel;
+  if (!d || d.turn !== selfId) return null;
+  const me = d.sides.find((s) => s.player === selfId);
+  const foe = d.sides.find((s) => s.player !== selfId);
+  if (!me || !foe) return null;
+  const guards = foe.board.map((u, i) => ({ u, i })).filter((x) => x.u.guard);
+  const hand = v.hand ?? [];
+  for (let i = 0; i < hand.length; i++) {
+    const c = hand[i] as number;
+    const def = g.cards[c]?.def;
+    if (!def || def.cost > me.mana || (def.kind === "unit" && me.board.length >= g.table.boardMax)) continue;
+    let target: number = Target.None;
+    const fx = def.effect;
+    if (fx?.target === "enemy") target = guards[0] ? Target.EnemyUnit + guards[0].i : Target.EnemyHero;
+    if (fx?.target === "own_unit") {
+      if (me.board.length === 0) continue;
+      target = Target.OwnUnit;
+    }
+    return go(CardAct.Play, i, target, c);
+  }
+  const ready = me.board.findIndex((u) => u.ready && u.attack > 0);
+  if (ready >= 0) return go(CardAct.Attack, ready, guards[0] ? Target.EnemyUnit + guards[0].i : Target.EnemyHero);
+  return go(CardAct.End);
+};
+
+async function main(): Promise<void> {
+  const app = await bootBoard({
+    adapter: cardsAdapter(),
+    manifest,
+    template: TEMPLATE,
+    place: PLACE,
+    version: GAME_VERSION,
+    labels: {
+      title: TITLE,
+      rules: RULE_NAMES,
+      skus: SKU_NAMES,
+      upgrades: UPGRADE_NAMES,
+      loading: "Mixing the ink",
+      help: "Click a card to play · click your creature, then a target, to attack · E or Enter ends the turn · Esc cancels",
+    },
+    theme: {
+      accent: "#e8c872",
+      gold: "#f2d48b",
+      ink: "#f3ead6",
+      dim: "#b3a68a",
+      panel: "rgba(28, 22, 18, 0.88)",
+      bg: "#17120e",
+      font: '"Palatino Linotype", Palatino, "Book Antiqua", Georgia, serif',
+      display: '"Palatino Linotype", Palatino, Georgia, serif',
+      radius: 3,
+    },
+    coin: INKWRIT_COIN,
+    cosmetics: COSMETICS,
+    swatch: (c) => `linear-gradient(135deg, ${cssColor(FINISH[c] ?? 0x2b2b2b)}, #120c08)`,
+    ground: { w: W, h: H },
+    preset: "studio",
+    theme3d: "study",
+    groundColor: 0x3a2a1c,
+    pitch: 1.12,
+    // The duel is on a desk: no voxel meadow growing through the mat.
+    field: false,
+    autopilot,
+    soundKey: "inkwrit:sound",
+  });
+  selfId = app.self;
+  const { stage, hud, clock, sfx } = app;
+  sfx.define("flip", { wave: "noise", f0: 3000, f1: 900, ms: 70, gain: 0.3 }, { minGapMs: 40, voices: 3 });
+  sfx.define("quill", { wave: "triangle", f0: 1500, f1: 900, ms: 60, gain: 0.25 }, { minGapMs: 40, voices: 2 });
+
+  // ---- The desk: a wooden top with a felt mat, the piles, the lamp and the study's clutter beyond.
+  const desk = new Mesh(new BoxGeometry(W, 0.4, H), new MeshStandardMaterial({ color: 0x5a3a22, roughness: 0.7, metalness: 0.05 }));
+  desk.position.y = -0.2;
+  desk.receiveShadow = true;
+  stage.add(desk);
+  const mat = new Mesh(new PlaneGeometry(W - 2, H - 2), new MeshStandardMaterial({ map: matTexture(), roughness: 1 }));
+  mat.rotation.x = -Math.PI / 2;
+  mat.position.y = 0.01;
+  mat.receiveShadow = true;
+  stage.add(mat);
+  // The hand sits over the bottom of the screen: frame the desk a little lower.
+  stage.frameRect(0, 1.4, W, H + 2.5);
+  const lamp = stage.model(LAMP_MODEL, 0.8, 0xffb347, 1.4);
+  lamp.root.position.set(W / 2 - 1.4, 0, -H / 2 + 1.3);
+  stage.add(lamp.root);
+  SHELF_MODELS.forEach((id, i) => {
+    const m = stage.model(id, 1.6 + (i % 2) * 0.6, 0x7a5a3a, 1.8);
+    m.root.position.set(-W / 2 - 2 - (i % 2) * 1.5, 0, -H / 2 + 2 + i * 2.8);
+    stage.add(m.root);
+  });
+
+  // Card meshes: face-down piles (decks) and the other scribe's hand, a face-up plinth under each creature.
+  const back = cardBackTexture();
+  const cardGeo = new BoxGeometry(1.5, 0.04, 2.1);
+  const backMat = new MeshStandardMaterial({ map: back, roughness: 0.8 });
+  const edgeMat = new MeshStandardMaterial({ color: 0xe8dcc0, roughness: 0.9 });
+  const cardMats = [edgeMat, edgeMat, backMat, backMat, edgeMat, edgeMat];
+  const piles: Group[] = [];
+  for (const z of [3.4, -3.4]) {
+    const pile = new Group();
+    pile.position.set(W / 2 - 2.2, 0.02, z);
+    stage.add(pile);
+    piles.push(pile);
+  }
+  const foeHand = new Group();
+  foeHand.position.set(1, 0.03, -5.2);
+  stage.add(foeHand);
+  const faceCache = new Map<number, CanvasTexture>();
+  const faceOf = (type: number) => {
+    let t = faceCache.get(type);
+    if (!t) faceCache.set(type, (t = cardFaceTexture(type)));
+    return t;
+  };
+
+  // ---- Creatures on the board: a library model standing on its card, with a DOM badge (attack and health, and a button).
+  const units = new Map<string, { root: Group; model: Placed; type: number; card: Mesh; hp: number }>();
+  const heroes = new Map<number, { root: Group; hp: number }>();
+  const quills = new Map<number, Group>();
+  const overlay = document.createElement("div");
+  overlay.className = "hud";
+  overlay.style.inset = "0";
+  document.body.append(overlay);
+  const style = document.createElement("style");
+  style.textContent = `
+.badge { position: absolute; transform: translate(-50%, -50%); pointer-events: auto; display: flex; gap: 3px; align-items: center; font: 800 13px var(--display, serif); cursor: pointer; }
+.badge i { font-style: normal; min-width: 20px; height: 20px; border-radius: 50%; display: grid; place-items: center; color: #fff; text-shadow: 0 1px 0 #000; border: 1px solid rgba(0,0,0,0.5); }
+.badge i.a { background: #b8862f; }
+.badge i.h { background: #a2312a; }
+.badge.ready { filter: drop-shadow(0 0 6px #9dff7a); }
+.badge.guard i.h { box-shadow: 0 0 0 2px #cfd8e3; }
+.badge.target { filter: drop-shadow(0 0 7px #ff6a4a); animation: pulse 0.8s infinite alternate; }
+.badge.picked { filter: drop-shadow(0 0 8px #f2d48b); transform: translate(-50%, -60%) scale(1.15); }
+.hero { position: absolute; transform: translate(-50%, -50%); pointer-events: auto; text-align: center; font: 700 12px var(--display, serif); cursor: pointer; padding: 3px 9px; border-radius: 4px; background: var(--panel); border: 1px solid rgba(232, 200, 114, 0.4); }
+.hero b { display: block; font-size: 20px; color: #ffb0a0; }
+.hero.target { border-color: #ff6a4a; box-shadow: 0 0 12px #ff6a4a; }
+@keyframes pulse { to { filter: drop-shadow(0 0 2px #ff6a4a); } }
+#hand { position: fixed; left: 50%; bottom: max(8px, env(safe-area-inset-bottom)); transform: translateX(-50%); display: flex; gap: 6px; z-index: 6; }
+.card { pointer-events: auto; width: min(112px, 13vw); aspect-ratio: 5 / 7; border-radius: 6px; padding: 6px; box-sizing: border-box; display: flex; flex-direction: column; gap: 3px; background: linear-gradient(#efe4c8, #dccaa0); color: #2a1d12; border: 2px solid #3a2a1c; cursor: pointer; transition: transform 120ms; text-align: left; font: 13px var(--display, serif); }
+.card:hover, .card.picked { transform: translateY(-14px); }
+.card.poor { filter: grayscale(0.7) brightness(0.8); }
+.card .cost { align-self: flex-start; width: 22px; height: 22px; border-radius: 50%; background: #1f3550; color: #fff; display: grid; place-items: center; font-weight: 800; }
+.card b { font-size: 13px; line-height: 1.05; }
+.card small { font-size: 11px; color: #5a4632; flex: 1; }
+.card .stats { display: flex; justify-content: space-between; font-weight: 800; }
+#endturn { position: fixed; right: 14px; bottom: max(100px, calc(env(safe-area-inset-bottom) + 90px)); z-index: 6; pointer-events: auto; min-width: 118px; font-weight: 800; }
+#mana { position: fixed; right: 14px; bottom: max(150px, calc(env(safe-area-inset-bottom) + 140px)); z-index: 6; font: 800 14px var(--display, serif); color: #9fd0ff; text-shadow: 0 1px 0 #000; }
+#banner2 { left: 50%; top: 40%; transform: translate(-50%, -50%); font: 900 38px var(--display, serif); letter-spacing: 0.18em; color: var(--accent); text-shadow: 0 2px 0 #000; opacity: 0; transition: opacity 300ms; }
+#banner2.show { opacity: 1; }
+#draft { position: fixed; inset: 0; z-index: 7; display: none; place-items: center; background: rgba(0,0,0,0.45); }
+#draft.show { display: grid; }
+#draft .row { display: flex; gap: 14px; }
+#draft .card { width: 140px; }
+#draft h2 { text-align: center; font: 900 20px var(--display, serif); letter-spacing: 0.2em; color: var(--accent); margin: 0 0 12px; }
+#loglines { position: fixed; top: max(12px, env(safe-area-inset-top)); left: 50%; transform: translateX(-50%); z-index: 5; font-size: 12px; color: var(--dim); text-align: center; }
+@media (max-height: 500px) { .card { width: 78px; padding: 4px; font-size: 11px; } .card small { display: none; } #endturn { bottom: 90px; min-width: 90px; } #mana { bottom: 130px; } }
+`;
+  document.head.append(style);
+  const handEl = document.createElement("div");
+  handEl.id = "hand";
+  document.body.append(handEl);
+  const endBtn = document.createElement("button");
+  endBtn.id = "endturn";
+  endBtn.className = "go";
+  endBtn.textContent = "End turn";
+  document.body.append(endBtn);
+  const manaEl = document.createElement("div");
+  manaEl.id = "mana";
+  document.body.append(manaEl);
+  const banner = document.createElement("div");
+  banner.id = "banner2";
+  banner.className = "hud";
+  document.body.append(banner);
+  const draftEl = document.createElement("div");
+  draftEl.id = "draft";
+  document.body.append(draftEl);
+  const logEl = document.createElement("div");
+  logEl.id = "loglines";
+  logEl.className = "hud";
+  document.body.append(logEl);
+
+  // ---- Choosing: a card to play or a creature to attack with, then (when it aims) a target.
+  type Pick = { kind: "play"; slot: number; type: number } | { kind: "attack"; from: number } | null;
+  let picked: Pick = null;
+  const myTurn = () => lastView?.duel?.turn === app.self && lastView.stage === "duel";
+  const sides = () => {
+    const d = lastView?.duel;
+    return { me: d?.sides.find((s) => s.player === app.self), foe: d?.sides.find((s) => s.player !== app.self) };
+  };
+  const send = (act: number, a = 0, b = 0, c = 0) => {
+    clock.act(act, a, b, c);
+    sfx.play("quill");
+  };
+  const target = (t: number) => {
+    const p = picked;
+    if (!p || !myTurn()) return;
+    if (p.kind === "play") send(CardAct.Play, p.slot, t, p.type);
+    else send(CardAct.Attack, p.from, t);
+    picked = null;
+  };
+  endBtn.addEventListener("click", () => {
+    if (!myTurn()) return;
+    picked = null;
+    send(CardAct.End);
+  });
+  addEventListener("keydown", (e) => {
+    if (e.code === "Escape") picked = null;
+    if ((e.code === "KeyE" || e.code === "Enter") && myTurn()) {
+      picked = null;
+      send(CardAct.End);
+    }
+  });
+  app.canvas.addEventListener("pointermove", (e) => {
+    const p = stage.pick(e.clientX, e.clientY, app.canvas.getBoundingClientRect());
+    if (p) clock.cursor(p.x, p.z);
+  });
+  app.canvas.addEventListener("pointerdown", () => {
+    picked = null;
+  });
+
+  const unitX = (i: number, n: number) => 1 + (i - (n - 1) / 2) * 2.2;
+  const sideZ = (mine: boolean) => (mine ? 1.9 : -1.9);
+  const heroZ = (mine: boolean) => (mine ? 2.6 : -2.6);
+
+  let handKey = "";
+  let draftKey = "";
+  let lastTurn = -1;
+  let lastStage = "";
+  let lastLog = "";
+  let bannerTimer = 0;
+  const showBanner = (text: string) => {
+    banner.textContent = text;
+    banner.classList.add("show");
+    clearTimeout(bannerTimer);
+    bannerTimer = window.setTimeout(() => banner.classList.remove("show"), 1300);
+  };
+  const badges = new Map<string, HTMLElement>();
+  const heroTags = new Map<number, HTMLElement>();
+
+  app.loop((dt, now) => {
+    const v = app.view<CardsView>();
+    lastView = v;
+    const t = now / 1000;
+    const view = app.conn().net.render(now);
+    const wpx = app.canvas.clientWidth;
+    const hpx = app.canvas.clientHeight;
+    const proj = (x: number, y: number, z: number) => stage.project(x, y, z, wpx, hpx);
+
+    // Quills: ours predicted, the other scribe's interpolated.
+    const seen = new Set<number>();
+    const placeQuill = (e: InterpolatedEntity | undefined, owner: number) => {
+      if (!e) return;
+      seen.add(owner);
+      let q = quills.get(owner);
+      if (!q) {
+        q = quill(KEEPER_COLORS[(owner - 1) % KEEPER_COLORS.length] ?? 0x2f5d8a, FINISH[Math.round(e.values[RF.value] ?? 0)]);
+        quills.set(owner, q);
+        stage.add(q);
+      }
+      q.position.set((e.values[RF.x] ?? 0) / UNITS, 1.2 + Math.sin(t * 2.4 + owner) * 0.08, (e.values[RF.z] ?? 0) / UNITS);
+    };
+    placeQuill(view.self, app.self);
+    for (const e of view.others) if (e.kind === RulesKind.Avatar) placeQuill(e, e.owner);
+    for (const [o, q] of quills) {
+      if (seen.has(o)) continue;
+      stage.scene.remove(q);
+      quills.delete(o);
+    }
+    if (!v) return;
+    const d = v.duel;
+    const { me, foe } = sides();
+
+    // Creatures.
+    const want = new Set<string>();
+    for (const side of d?.sides ?? []) {
+      const mine = side.player === app.self;
+      side.board.forEach((u, i) => {
+        const key = `${side.player}:${i}:${u.type}`;
+        want.add(key);
+        const x = unitX(i, side.board.length);
+        const z = sideZ(mine);
+        let un = units.get(key);
+        if (!un) {
+          const root = new Group();
+          const c = new Mesh(cardGeo, [edgeMat, edgeMat, new MeshStandardMaterial({ map: faceOf(u.type), roughness: 0.85 }), backMat, edgeMat, edgeMat]);
+          c.position.y = 0.03;
+          root.add(c);
+          const model = stage.model(g.cards[u.type]?.def.model ?? "style.lowpoly.imp", 1.15, KEEPER_COLORS[(side.player - 1) % KEEPER_COLORS.length], 1.7);
+          model.root.position.y = 0.05;
+          if (!mine) model.root.rotation.y = Math.PI;
+          root.add(model.root);
+          root.position.set(x, 0, z);
+          stage.add(root);
+          un = { root, model, type: u.type, card: c, hp: u.health };
+          units.set(key, un);
+          stage.burst("magic", x, 0.6, z, 0x6fa8dc, 16);
+          sfx.play("flip");
+        }
+        un.root.position.x += (x - un.root.position.x) * Math.min(1, dt * 10);
+        if (u.health < un.hp) {
+          stage.burst("hitSpark", un.root.position.x, 0.8, z, 0xffd27a, 10);
+          sfx.play("hit");
+          floatText(proj(un.root.position.x, 1.8, z), `-${un.hp - u.health}`);
+        }
+        un.hp = u.health;
+        un.model.root.position.y = 0.05 + (u.ready && mine ? Math.abs(Math.sin(t * 4)) * 0.08 : 0);
+        // Its badge: attack and health, the button that picks it (yours) or aims at it (theirs).
+        let b = badges.get(key);
+        if (!b) {
+          b = document.createElement("div");
+          b.className = "badge";
+          b.innerHTML = `<i class="a"></i><i class="h"></i>`;
+          const idx = i;
+          b.addEventListener("pointerdown", (ev) => {
+            ev.stopPropagation();
+            sfx.unlock();
+            if (mine) {
+              if (picked?.kind === "play" && g.cards[picked.type]?.def.effect?.target === "own_unit") return target(Target.OwnUnit + idx);
+              if (myTurn()) picked = { kind: "attack", from: idx };
+            } else target(Target.EnemyUnit + idx);
+          });
+          overlay.append(b);
+          badges.set(key, b);
+        }
+        const p = proj(un.root.position.x, 0.2, z + (mine ? 1.2 : -1.2));
+        b.style.left = `${p.x}px`;
+        b.style.top = `${p.y}px`;
+        (b.firstChild as HTMLElement).textContent = String(u.attack);
+        (b.lastChild as HTMLElement).textContent = String(u.health);
+        b.classList.toggle("ready", mine && u.ready && myTurn());
+        b.classList.toggle("guard", u.guard);
+        b.classList.toggle("picked", mine && picked?.kind === "attack" && picked.from === i);
+        b.classList.toggle("target", !mine && picked !== null && (!foe?.board.some((x) => x.guard) || u.guard || picked.kind === "play"));
+      });
+    }
+    for (const [key, un] of units) {
+      if (want.has(key)) continue;
+      stage.burst("kill", un.root.position.x, 0.6, un.root.position.z, 0x1f1a30, 22);
+      stage.scene.remove(un.root);
+      units.delete(key);
+      badges.get(key)?.remove();
+      badges.delete(key);
+    }
+
+    // Heroes: the scribes themselves at each end of the desk, with their health as the target button.
+    const heroSeen = new Set<number>();
+    for (const side of d?.sides ?? []) {
+      const mine = side.player === app.self;
+      heroSeen.add(side.player);
+      let h = heroes.get(side.player);
+      if (!h) {
+        const root = new Group();
+        const m = stage.model(manifest.game.players.prefab, 2.2, KEEPER_COLORS[(side.player - 1) % KEEPER_COLORS.length]);
+        if (!mine) m.root.rotation.y = Math.PI;
+        root.add(m.root);
+        root.position.set(-W / 2 + 1.6, 0, heroZ(mine));
+        stage.add(root);
+        h = { root, hp: side.hero };
+        heroes.set(side.player, h);
+      }
+      if (side.hero < h.hp) {
+        stage.burst("burst", h.root.position.x, 1.4, h.root.position.z, 0xff6a4a, 18);
+        stage.kick(0.25);
+        sfx.play(mine ? "hurt" : "impact");
+        floatText(proj(h.root.position.x, 2.6, h.root.position.z), `-${h.hp - side.hero}`);
+      }
+      h.hp = side.hero;
+      let tag = heroTags.get(side.player);
+      if (!tag) {
+        tag = document.createElement("div");
+        tag.className = "hero";
+        tag.addEventListener("pointerdown", (ev) => {
+          ev.stopPropagation();
+          target(mine ? Target.OwnHero : Target.EnemyHero);
+        });
+        overlay.append(tag);
+        heroTags.set(side.player, tag);
+      }
+      const p = proj(h.root.position.x, 0, h.root.position.z + (mine ? 1.3 : -1.0));
+      tag.style.left = `${p.x}px`;
+      tag.style.top = `${p.y}px`;
+      const who = mine ? "You" : v.players.find((x) => x.id === side.player)?.bot ? `AI scribe, tier ${d ? d.tier + 1 : 1}` : `P${side.player}`;
+      tag.innerHTML = `<b>${side.hero}</b>${who}`;
+      tag.classList.toggle("target", !mine && picked !== null && !foe?.board.some((x) => x.guard));
+    }
+    for (const [p, h] of heroes) {
+      if (heroSeen.has(p)) continue;
+      stage.scene.remove(h.root);
+      heroes.delete(p);
+      heroTags.get(p)?.remove();
+      heroTags.delete(p);
+    }
+
+    // Piles and the other scribe's face-down hand.
+    const stack = (pile: Group, n: number) => {
+      while (pile.children.length < Math.min(30, n)) {
+        const c = new Mesh(cardGeo, cardMats);
+        c.position.y = pile.children.length * 0.045;
+        c.rotation.y = (pile.children.length % 3) * 0.02;
+        pile.add(c);
+      }
+      while (pile.children.length > Math.min(30, n)) pile.remove(pile.children[pile.children.length - 1] as Mesh);
+    };
+    stack(piles[0] as Group, me?.deck ?? 0);
+    stack(piles[1] as Group, foe?.deck ?? 0);
+    const fh = foe?.hand ?? 0;
+    while (foeHand.children.length < fh) foeHand.add(new Mesh(cardGeo, cardMats));
+    while (foeHand.children.length > fh) foeHand.remove(foeHand.children[foeHand.children.length - 1] as Mesh);
+    foeHand.children.forEach((c, i) => {
+      const k = i - (fh - 1) / 2;
+      c.position.set(k * 0.9, 0.02 + i * 0.01, Math.abs(k) * 0.12);
+      c.rotation.y = -k * 0.08;
+    });
+
+    // Your hand (DOM): only your view carries it.
+    const hand = v.hand ?? [];
+    const key = `${hand.join(",")}|${me?.mana ?? 0}|${myTurn()}|${picked?.kind === "play" ? picked.slot : -1}`;
+    if (key !== handKey) {
+      handKey = key;
+      handEl.innerHTML = "";
+      hand.forEach((type, slot) => {
+        const def = g.cards[type]?.def;
+        const el = cardEl(type);
+        if (!def || def.cost > (me?.mana ?? 0) || !myTurn()) el.classList.add("poor");
+        if (picked?.kind === "play" && picked.slot === slot) el.classList.add("picked");
+        el.addEventListener("click", (ev) => {
+          ev.stopPropagation();
+          sfx.unlock();
+          if (!myTurn() || !def) return;
+          if (def.cost > (me?.mana ?? 0)) return hud.toast("Not enough ink");
+          const aim = def.effect?.target;
+          if (aim === "enemy" || (aim === "own_unit" && (me?.board.length ?? 0) > 0)) {
+            picked = { kind: "play", slot, type };
+            handKey = "";
+            return;
+          }
+          picked = null;
+          send(CardAct.Play, slot, Target.None, type);
+        });
+        handEl.append(el);
+      });
+    }
+    // The draft between duels: three cards, only you see yours.
+    const offer = v.stage === "draft" ? (v.offer ?? null) : null;
+    const dk = offer ? offer.join(",") : "";
+    if (dk !== draftKey) {
+      draftKey = dk;
+      draftEl.innerHTML = "";
+      draftEl.classList.toggle("show", offer !== null && !app.preview);
+      if (offer) {
+        const box = document.createElement("div");
+        box.innerHTML = `<h2>DRAFT A CARD</h2><div class="row"></div>`;
+        offer.forEach((type, i) => {
+          const el = cardEl(type);
+          el.addEventListener("click", () => send(CardAct.Draft, i));
+          (box.lastChild as HTMLElement).append(el);
+        });
+        draftEl.append(box);
+      }
+    }
+
+    // Turn changes, results, the log.
+    if (d && d.turnNo !== lastTurn) {
+      lastTurn = d.turnNo;
+      if (d.turn === app.self) {
+        showBanner("YOUR TURN");
+        sfx.play("pick");
+      }
+    }
+    if (v.stage !== lastStage) {
+      if (v.stage === "draft" || v.stage === "done") {
+        const lastWin = v.log.filter((l) => l.kind === "win" || l.kind === "draw").at(-1);
+        if (lastWin) {
+          const won = lastWin.kind === "win" && lastWin.p === app.self;
+          showBanner(lastWin.kind === "draw" ? "DRAWN" : won ? "VICTORY" : "DEFEAT");
+          sfx.play(won ? "levelUp" : "hurt");
+        }
+      }
+      lastStage = v.stage;
+    }
+    const lk = v.log.map((l) => `${l.p}${l.kind}${l.card}${l.target}`).join("|");
+    if (lk !== lastLog) {
+      lastLog = lk;
+      const l = v.log.at(-1);
+      logEl.textContent = l ? `${l.p === app.self ? "You" : "They"} ${l.kind === "play" ? `played ${cardName(l.card)}` : l.kind === "attack" ? `attacked with ${cardName(l.card)}` : l.kind === "end" ? "ended the turn" : l.kind === "win" ? "won the duel" : "drew"}` : "";
+    }
+    const mine = v.players.find((p) => p.id === app.self);
+    hud.status([
+      ["DUEL", `${Math.max(1, v.duelNo)} / ${v.duels}`],
+      ["RECORD", `${mine?.wins ?? 0}-${mine?.losses ?? 0}`],
+      v.stage === "duel" && d ? [d.turn === app.self ? "YOUR TURN" : "THEIR TURN", `${d.timer}s`] : v.stage === "waiting" ? ["WAITING", "for a scribe"] : v.stage === "draft" ? ["DRAFT", `${v.countdown}s`] : ["RUN", "over"],
+      ["DECK", `${mine?.deck ?? 0} cards`],
+    ]);
+    manaEl.textContent = me ? `INK ${me.mana} / ${me.maxMana}` : "";
+    endBtn.disabled = !myTurn();
+    endBtn.style.visibility = d ? "visible" : "hidden";
+    const won = (mine?.wins ?? 0) > (mine?.losses ?? 0);
+    hud.end(v.phase === "ended", won ? "THE PAGE IS YOURS" : "BLOTTED OUT", `${mine?.wins ?? 0} won, ${mine?.losses ?? 0} lost`, v.endsIn ?? null);
+  });
+  app.extraStats(() => ({ units: units.size, hand: lastView?.hand?.length ?? 0, duel: lastView?.duelNo ?? 0, stage: lastView?.stage ?? "" }));
+
+  function floatText(p: { x: number; y: number }, text: string): void {
+    const el = document.createElement("div");
+    el.className = "hud";
+    el.textContent = text;
+    el.style.cssText = `left:${p.x}px;top:${p.y}px;font:900 22px var(--display, serif);color:#ff8a6a;text-shadow:0 2px 0 #000;transform:translate(-50%,-50%);transition:transform 700ms ease-out, opacity 700ms;`;
+    document.body.append(el);
+    requestAnimationFrame(() => {
+      el.style.transform = "translate(-50%, -160%)";
+      el.style.opacity = "0";
+    });
+    setTimeout(() => el.remove(), 800);
+  }
+}
+
+/** A hand or draft card as DOM: cost, name, its line, attack and health for a creature. */
+function cardEl(type: number): HTMLButtonElement {
+  const def = g.cards[type]?.def;
+  const el = document.createElement("button");
+  el.className = "card";
+  el.innerHTML = `<span class="cost"></span><b></b><small></small><span class="stats"><span></span><span></span></span>`;
+  (el.querySelector(".cost") as HTMLElement).textContent = String(def?.cost ?? 0);
+  (el.querySelector("b") as HTMLElement).textContent = cardName(type);
+  (el.querySelector("small") as HTMLElement).textContent = `${def?.kind === "spell" ? "Spell. " : def?.guard ? "Guard. " : def?.rush ? "Rush. " : ""}${cardLine(type)}`;
+  const st = el.querySelectorAll(".stats span");
+  if (def?.kind === "unit") {
+    (st[0] as HTMLElement).textContent = `⚔ ${def.attack}`;
+    (st[1] as HTMLElement).textContent = `♥ ${def.health}`;
+  }
+  return el;
+}
+
+/** The quill each scribe points with: a feather on a nib, in the player's colour (a finish recolours the nib). */
+function quill(color: number, finish: number | undefined): Group {
+  const q = new Group();
+  const vane = new Mesh(new ConeGeometry(0.16, 1.3, 6), new MeshStandardMaterial({ color: new Color(0xf2ead8), roughness: 0.8 }));
+  vane.position.y = 0.7;
+  const nib = new Mesh(new CylinderGeometry(0.04, 0.0, 0.35, 6), new MeshStandardMaterial({ color: finish ?? color, metalness: 0.6, roughness: 0.3, emissive: new Color(color), emissiveIntensity: 0.25 }));
+  nib.position.y = -0.05;
+  q.add(vane, nib);
+  q.rotation.z = 0.5;
+  return q;
+}
+
+function canvasTexture(w: number, h: number, draw: (g: CanvasRenderingContext2D) => void): CanvasTexture {
+  const c = document.createElement("canvas");
+  c.width = w;
+  c.height = h;
+  const ctx = c.getContext("2d");
+  if (!ctx) throw new Error("no 2d canvas");
+  draw(ctx);
+  const t = new CanvasTexture(c);
+  t.colorSpace = SRGBColorSpace;
+  return t;
+}
+
+function matTexture(): CanvasTexture {
+  return canvasTexture(512, 360, (c) => {
+    c.fillStyle = "#1f3a2e";
+    c.fillRect(0, 0, 512, 360);
+    let s = 9;
+    const r = () => ((s = (s * 16807) % 2147483647) / 2147483647);
+    for (let i = 0; i < 4000; i++) {
+      c.fillStyle = `rgba(${r() > 0.5 ? 40 : 20}, ${60 + r() * 20}, ${45 + r() * 15}, 0.5)`;
+      c.fillRect(r() * 512, r() * 360, 2, 2);
+    }
+    c.strokeStyle = "rgba(232, 200, 114, 0.55)";
+    c.lineWidth = 3;
+    c.strokeRect(14, 14, 484, 332);
+    c.setLineDash([6, 6]);
+    c.beginPath();
+    c.moveTo(30, 180);
+    c.lineTo(482, 180);
+    c.stroke();
+  });
+}
+
+function cardBackTexture(): CanvasTexture {
+  return canvasTexture(150, 210, (c) => {
+    c.fillStyle = "#1f3550";
+    c.fillRect(0, 0, 150, 210);
+    c.strokeStyle = "#e8c872";
+    c.lineWidth = 6;
+    c.strokeRect(8, 8, 134, 194);
+    c.fillStyle = "#e8c872";
+    c.beginPath();
+    c.moveTo(75, 60);
+    c.quadraticCurveTo(110, 110, 75, 150);
+    c.quadraticCurveTo(40, 110, 75, 60);
+    c.fill();
+  });
+}
+
+function cardFaceTexture(type: number): CanvasTexture {
+  const def = g.cards[type]?.def;
+  return canvasTexture(150, 210, (c) => {
+    c.fillStyle = "#efe4c8";
+    c.fillRect(0, 0, 150, 210);
+    c.strokeStyle = "#3a2a1c";
+    c.lineWidth = 6;
+    c.strokeRect(5, 5, 140, 200);
+    c.fillStyle = "#1f3550";
+    c.beginPath();
+    c.arc(26, 26, 16, 0, Math.PI * 2);
+    c.fill();
+    c.fillStyle = "#fff";
+    c.font = "bold 20px serif";
+    c.textAlign = "center";
+    c.fillText(String(def?.cost ?? 0), 26, 33);
+    c.fillStyle = "#2a1d12";
+    c.font = "bold 15px serif";
+    c.fillText(cardName(type), 75, 190);
+  });
+}
+
+main().catch((e: unknown) => {
+  const t = document.getElementById("banner-text");
+  if (t) t.textContent = `Could not start: ${e instanceof Error ? e.message : String(e)}`;
+  console.error(e);
+});

package/client/names.ts

@@ -0,0 +1,58 @@
+/**
+ * Display names for the template's content ids. Labels only; the rules are
+ * in src/game.ts. A Net Forge game generated on this template ships its own
+ * table (the model writes src/names.json; the build turns it into this
+ * module). Cards are the "weapons" table ({ name, line }).
+ */
+export const TITLE = "Inkwrit";
+
+export const WEAPON_NAMES: Readonly<Record<string, { name: string; line: string }>> = {
+  blot_imp: { name: "Blot Imp", line: "Small and spiteful" },
+  quill_sprite: { name: "Quill Sprite", line: "Strikes at once" },
+  ink_frog: { name: "Ink Frog", line: "Sturdy for its cost" },
+  margin_bat: { name: "Margin Bat", line: "Strikes at once" },
+  ledger_crab: { name: "Ledger Crab", line: "Guards your hero" },
+  serif_fox: { name: "Serif Fox", line: "Draws a card" },
+  gloss_wolf: { name: "Gloss Wolf", line: "A solid hunter" },
+  stamp_golem: { name: "Stamp Golem", line: "A wall of ink" },
+  folio_wyrm: { name: "Folio Wyrm", line: "Scorches every foe" },
+  grand_errata: { name: "Grand Errata", line: "The last word" },
+  splash: { name: "Splash", line: "2 damage" },
+  blotting_sand: { name: "Blotting Sand", line: "Heal your hero 5" },
+  underline: { name: "Underline", line: "+2/+2 to a unit" },
+  second_draft: { name: "Second Draft", line: "Draw two cards" },
+  ink_storm: { name: "Ink Storm", line: "2 to every foe" },
+  final_word: { name: "Final Word", line: "5 damage" },
+};
+
+export const UPGRADE_NAMES: Readonly<Record<string, { name: string; line: string }>> = {
+  thick_vellum: { name: "Thick Vellum", line: "+5 hero health" },
+  sharp_nib: { name: "Sharp Nib", line: "+1 attack on your units" },
+  quick_ink: { name: "Quick Ink", line: "+1 mana in your first turn" },
+  spare_page: { name: "Spare Page", line: "+1 card in your first hand" },
+};
+
+// Creatures by prefab id (the duel has none; a game that adds them labels them here).
+export const ENEMY_NAMES: Readonly<Record<string, string>> = {
+};
+
+export const RULE_NAMES: Readonly<Record<string, string>> = {
+  first_ink: "First Ink",
+  full_gauntlet: "Full Gauntlet",
+  inked_duel: "Inked Duel",
+  signed_and_sealed: "Signed and Sealed",
+};
+
+export const SKU_NAMES: Readonly<Record<string, string>> = {
+  thick_vellum: "Thick Vellum",
+  sharp_nib: "Sharp Nib",
+  quick_ink: "Quick Ink",
+  spare_page: "Spare Page",
+  skin_vermilion: "Vermilion quill",
+  skin_gold_leaf: "Gold leaf quill",
+  bound_folio: "Bound folio",
+};
+
+/** Player colours by slot, and a highlight palette (the generated names module carries both). */
+export const KEEPER_COLORS = [0x2f5d8a, 0xb2382e, 0x3f7a4a, 0x8a5a2b, 0x6b4a8a, 0xc9a227, 0x2a7a7a, 0x8a2a5a];
+export const AURORA = { body: 0x3cf2c4, glow: 0xa77bff };

package/llms.txt

@@ -0,0 +1,94 @@
+# INKWRIT: the card battler template (NetNet game runtime, board genre)
+
+> A one-against-one card battler. Two scribes duel at a desk: heroes with
+> health, ink (mana) that rises each turn, a hand drawn from a shuffled
+> deck, inked creatures on the board, spells. A run is a gauntlet of
+> duels; after each one, every player drafts one of three cards into
+> their deck. Alone, an AI scribe of the gauntlet takes the other seat.
+> You change the game by editing src/game.ts only. The template already has
+> the duel, turns and the turn timer, the shuffle (on the server), hidden
+> hands, guards, rush, the draft, the AI, netcode, rendering, touch,
+> earn and the store. Do not write renderers, netcode or AI.
+
+## Files
+
+- src/game.ts: THE GAME. Declarations against @netforge/engine:
+  game(), cardTable(), card(), upgrade(), earn.rule(), earn.stake(), store.sku().
+- src/names.json: the title and every label players read. Cards go in
+  "weapons" ({ name, line }), plus upgrades, earn rules and store items.
+- Everything else is template machinery.
+
+## Rules the build enforces
+
+- game({ template: "cards", style, places, players: { prefab, max } }), players.max at most 2.
+- Exactly one cardTable(...); 4 to 40 card(...)s. The starter deck (8 to 30
+  cards) names declared cards, holds at least one unit and cards costing 2
+  or less. ai is 1 to 12 tiers { health, smart }.
+- A unit has health 1 or more; a spell has an effect.
+- Effects: kind "damage", "heal", "draw" or "buff"; target "enemy" (the
+  player picks an enemy unit or the hero), "enemy_hero", "all_enemies",
+  "own_hero", "own_unit" (the player picks one of theirs) or "all_own".
+- Upgrades read four stats only: maxHealth (hero health), might (+attack on
+  the buyer's units), haste (+ink in the first turn), amount (+cards in
+  the first hand).
+- No weapon(...). Asset ids look like "style.lowpoly.frog"; keep game({ style }).
+- 2 playtest players must decide duels and fire an earn rule within 4 minutes.
+
+## Units
+
+Health and attack in points, cost in ink (0 to 10), seconds for timers.
+Tick rate 30 Hz.
+
+## The loop
+
+A duel: a coin decides who goes first; the second player draws one extra
+card. Each turn: +1 ink (up to manaMax), draw a card (an empty deck hurts
+more each time), play cards, attack with ready units (a unit is ready the
+turn after it lands, or at once with rush; guard units must be attacked
+first), end the turn (or the timer ends it). A hero at 0 loses; turnCap
+turns is a draw. After each duel but the last, a draft: one of three.
+
+## Common changes
+
+### A new card
+card("mirror_moth", { model: "style.lowpoly.jelly_flyer", kind: "unit", cost: 3, attack: 2, health: 2, effect: { kind: "damage", amount: 1, target: "all_enemies" } });
+Add its label to names.json weapons. The draft offers every card unless cardTable pool lists some.
+
+### Tune the table
+cardTable({ health: 25, duels: 5, turnSeconds: 40, ... }). Lower health
+makes faster duels; more duels make longer runs.
+
+### Harder or easier AI
+ai: [{ health: 14, smart: 0.3 }, ...]: duel n against the AI uses tier n;
+raise health and smart for a harder gauntlet.
+
+### Earn rules
+earn.rule("ink_master", { when: "ai.beaten", n: 3, pay: 15, oncePer: "run" });
+Events: duel.won (a duel won against a person; never against the AI, never
+a forfeit), ai.beaten (a gauntlet AI scribe beaten; a forfeit pays
+nothing), run.won (more duels won than lost in the run). Each rule pays
+once per run per player, in coins; the room server is the referee; the AI
+scribe never earns.
+
+### The buy-in run (required)
+earn.stake({ min: 10, max: 100, multiple: 2 }); one top-level line. "stake" is reserved.
+
+### Coins: earn and the store
+store.sku("thick_vellum", { coins: 40 });                            // one level of the upgrade for the run
+store.sku("skin_gold_leaf", { coins: 500, grants: { cosmetic: 2 } }); // a finish for your quill, owned for good
+store.sku("bound_folio", { coins: 120, grants: { gear: "thick_vellum", loseBelow: 0.25 } }); // losable gear
+Keep the SKUs the client is wired to (thick_vellum, sharp_nib, quick_ink,
+spare_page, skin_vermilion, skin_gold_leaf, bound_folio) at their prices.
+
+## Hidden information
+
+Decks are shuffled on the room server and their order never leaves it; a
+hand and a draft offer are sent only to their owner. Nothing in game.ts
+can change that.
+
+## Test
+
+engine.test.run({ ticks: 30 * 240, bots: 2 }) plays duels between two
+players (bots: 1 plays one person against the AI) and reports duels won
+(kills) and lost (deaths), the duel reached (wave), runs, earned by rule,
+softlock, ms per tick and the genre's checks under rules.checks.

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "@netforge/template-cards",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "INKWRIT: the card battler template of the NetNet game runtime, one against one or against the AI, a gauntlet of duels with a draft between them, server-side shuffle and hidden hands. The game module, its browser client and its playtest bots.",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": "./src/manifest.ts",
+    "./store": "./src/store.ts"
+  },
+  "files": [
+    "src",
+    "client",
+    "!client/vite.config.ts",
+    "llms.txt",
+    "README.md",
+    "NOTICE",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/netnetdev/net-forge.git",
+    "directory": "packages/template-cards"
+  },
+  "homepage": "https://github.com/netnetdev/net-forge/tree/main/packages/template-cards#readme",
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "three": "0.186.1",
+    "@netforge/asset-library": "0.1.0",
+    "@netforge/tabletop": "0.1.0",
+    "@netforge/engine": "0.1.0",
+    "@netforge/engine-sim": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "22.20.1",
+    "@types/three": "0.186.0",
+    "tsx": "4.23.0",
+    "typescript": "5.8.3",
+    "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",
+    "test": "vitest run",
+    "dev": "vite --config client/vite.config.ts",
+    "preview": "vite preview --config client/vite.config.ts"
+  }
 }

package/src/game.ts

@@ -0,0 +1,86 @@
+/**
+ * INKWRIT: the card battler template (play style:
+ * card battler).
+ *
+ * Scribes duel in a lamplit study. Every card is an inked creature or a
+ * spell written on a page: blot imps, ledger crabs, folio wyrms, a splash
+ * of ink. One against one, a person against a person or against the
+ * gauntlet's AI scribes. A run is four duels; after each, you draft one of
+ * three new cards into your deck.
+ *
+ * This file is the whole game as the model writes it: declarations only,
+ * against the typed API in @netforge/engine. The duel, the draft, the
+ * shuffle, hidden hands, the AI, netcode, renderer and referee are the
+ * template's machinery.
+ */
+import { card, cardTable, earn, game, store, upgrade } from "@netforge/engine";
+
+export default game({
+  template: "cards",
+  style: "lowpoly",
+  places: { study: { chunks: "places/study", spawn: [0, 0, 0] } },
+  players: { prefab: "style.lowpoly.hooded_adventurer", max: 2 },
+});
+
+// The table: hero health, hands, the board, the gauntlet and its AI scribes (tier n plays duel n against the AI).
+cardTable({
+  health: 20,
+  startHand: 3,
+  handMax: 7,
+  boardMax: 5,
+  manaMax: 10,
+  turnSeconds: 30,
+  draftSeconds: 15,
+  duels: 4,
+  starter: ["blot_imp", "blot_imp", "quill_sprite", "quill_sprite", "ink_frog", "ink_frog", "margin_bat", "ledger_crab", "serif_fox", "splash", "splash", "blotting_sand"],
+  ai: [
+    { health: 14, smart: 0.3 },
+    { health: 16, smart: 0.55 },
+    { health: 20, smart: 0.75 },
+    { health: 24, smart: 0.9 },
+  ],
+});
+
+// Units: cost in mana, attack and health. guard units must be attacked first; rush units attack the turn they land.
+card("blot_imp", { model: "style.lowpoly.imp", kind: "unit", cost: 1, attack: 2, health: 1 });
+card("quill_sprite", { model: "style.lowpoly.bee", kind: "unit", cost: 1, attack: 1, health: 2, rush: true });
+card("ink_frog", { model: "style.lowpoly.frog", kind: "unit", cost: 2, attack: 2, health: 3 });
+card("margin_bat", { model: "style.lowpoly.bat", kind: "unit", cost: 2, attack: 3, health: 1, rush: true });
+card("ledger_crab", { model: "style.lowpoly.crab", kind: "unit", cost: 3, attack: 2, health: 5, guard: true });
+card("serif_fox", { model: "style.lowpoly.fox", kind: "unit", cost: 3, attack: 3, health: 3, effect: { kind: "draw", amount: 1 } });
+card("gloss_wolf", { model: "style.lowpoly.wolf", kind: "unit", cost: 4, attack: 4, health: 4 });
+card("stamp_golem", { model: "style.lowpoly.yeti", kind: "unit", cost: 5, attack: 4, health: 7, guard: true });
+card("folio_wyrm", { model: "style.lowpoly.dragon_whelp", kind: "unit", cost: 6, attack: 5, health: 5, effect: { kind: "damage", amount: 2, target: "all_enemies" } });
+card("grand_errata", { model: "style.lowpoly.dragon", kind: "unit", cost: 8, attack: 8, health: 8 });
+// Spells: an effect only. "enemy" lets the player pick an enemy unit or the hero.
+card("splash", { model: "style.lowpoly.crystal", kind: "spell", cost: 1, effect: { kind: "damage", amount: 2, target: "enemy" } });
+card("blotting_sand", { model: "style.lowpoly.gem_mid", kind: "spell", cost: 2, effect: { kind: "heal", amount: 5, target: "own_hero" } });
+card("underline", { model: "style.lowpoly.gem_pink", kind: "spell", cost: 2, effect: { kind: "buff", amount: 2, target: "own_unit" } });
+card("second_draft", { model: "style.lowpoly.chest", kind: "spell", cost: 3, effect: { kind: "draw", amount: 2 } });
+card("ink_storm", { model: "style.lowpoly.meteor", kind: "spell", cost: 4, effect: { kind: "damage", amount: 2, target: "all_enemies" } });
+card("final_word", { model: "style.lowpoly.crystal_rock", kind: "spell", cost: 5, effect: { kind: "damage", amount: 5, target: "enemy" } });
+
+// Store upgrades: one level each, for the rest of the run (hero health, unit attack, first-turn mana, starting hand).
+upgrade("thick_vellum", { stat: "maxHealth", step: 5, maxLevel: 1 });
+upgrade("sharp_nib", { stat: "might", step: 1, maxLevel: 1 });
+upgrade("quick_ink", { stat: "haste", step: 1, maxLevel: 1 });
+upgrade("spare_page", { stat: "amount", step: 1, maxLevel: 1 });
+
+// Earn (mandatory). Pays the game's coins (1 coin = 1 token), once per run each. Values are PLACEHOLDER.
+// duel.won counts duels won against a person (never against the AI, never a forfeit); ai.beaten counts gauntlet AI scribes beaten.
+earn.rule("first_ink", { when: "ai.beaten", n: 1, pay: 5, oncePer: "run" });
+earn.rule("full_gauntlet", { when: "ai.beaten", n: 4, pay: 20, oncePer: "run" });
+earn.rule("inked_duel", { when: "duel.won", n: 1, pay: 12, oncePer: "run" });
+earn.rule("signed_and_sealed", { when: "duel.won", n: 3, pay: 25, oncePer: "run" });
+// Buy-in run (the mandatory sink loop): stake coins at run start to earn above free play. Values are PLACEHOLDER.
+earn.stake({ min: 10, max: 100, multiple: 2 });
+
+// Store (the Kit), priced in coins: four run upgrades and two finishes for your quill, owned for good.
+store.sku("thick_vellum", { coins: 40 });
+store.sku("sharp_nib", { coins: 60 });
+store.sku("quick_ink", { coins: 40 });
+store.sku("spare_page", { coins: 50 });
+store.sku("skin_vermilion", { coins: 300, grants: { cosmetic: 1 } });
+store.sku("skin_gold_leaf", { coins: 500, grants: { cosmetic: 2 } });
+// Losable gear: one level of its upgrade in every staked run, lost when that run makes under loseBelow of its most earn. PLACEHOLDER.
+store.sku("bound_folio", { coins: 120, grants: { gear: "thick_vellum", loseBelow: 0.25 } });

package/src/manifest.ts

@@ -0,0 +1,44 @@
+/**
+ * Loads the game module once per process and compiles it. The room server,
+ * the client, the bots and the tests all start here.
+ */
+import { collectManifest } from "@netforge/engine/game";
+import type { GameManifest } from "@netforge/engine";
+import { rulesAdapter, cardsGenre } from "@netforge/engine/rules";
+import type { RulesInput, RulesWorld, CardsState } from "@netforge/engine/rules";
+import type { SimAdapter } from "@netforge/engine/net";
+import "./game.js";
+
+/** Content version: bump with any change to game.ts (hot swap compares it). */
+export const GAME_VERSION = "inkwrit-0.1.0";
+export const GAME_NAME = "inkwrit";
+/** Room template (as the Net Forge room server names it) and place used by the client and the bots. */
+export const TEMPLATE = "cards";
+export const PLACE = "study";
+
+/**
+ * Collected as soon as the module is imported: one process may load more
+ * than one game module (the room server hosts every template), and each
+ * manifest takes its own game before the next module declares.
+ */
+const MANIFEST = collectManifest();
+let genre: ReturnType<typeof cardsGenre> | null = null;
+
+/** The game's manifest (every declaration). */
+export function cardsManifest(): GameManifest {
+  return MANIFEST;
+}
+
+/** The compiled card battler genre (table, cards, AI). */
+export function cardsGame(): ReturnType<typeof cardsGenre> {
+  genre ??= cardsGenre(MANIFEST);
+  return genre;
+}
+
+/** The SimAdapter the room server and the client both run. */
+export function cardsAdapter(): SimAdapter<RulesWorld<CardsState>, RulesInput> {
+  return rulesAdapter(cardsGame(), MANIFEST, { name: GAME_NAME, version: GAME_VERSION });
+}
+
+/** Cosmetic ids for store SKUs (0 is the default finish). */
+export const COSMETICS: Readonly<Record<string, number>> = { skin_vermilion: 1, skin_gold_leaf: 2 };

package/src/store.ts

@@ -0,0 +1,24 @@
+/**
+ * Store hooks (the Coins model): every
+ * game has coins, 1 coin = 1 game token, shown under the token's own name,
+ * symbol and logo. INKWRIT sells four run upgrades (a store command named
+ * after the upgrade grants one level for the rest of the run), two quill
+ * finishes (permanent) and one piece of losable gear, all priced in coins.
+ * The Kit bridge and its in-memory stand-in live in @netforge/tabletop.
+ */
+export { mockKit } from "@netforge/tabletop";
+export type { KitStoreBridge, MockKit, SkuPrice } from "@netforge/tabletop";
+
+/** Coin prices the client is wired to (they match store.sku(...) in game.ts; the generator's gate keeps them). */
+export const COIN_PRICES = { thick_vellum: 40, sharp_nib: 60, quick_ink: 40, spare_page: 50, skin_vermilion: 300, skin_gold_leaf: 500, bound_folio: 120 } as const;
+/** Run upgrades: spent, applied by the room for the rest of the run. */
+export const UPGRADE_SKUS = ["thick_vellum", "sharp_nib", "quick_ink", "spare_page"] as const;
+/** Cosmetic finishes: bought once, owned for good. */
+export const COSMETIC_SKUS = ["skin_vermilion", "skin_gold_leaf"] as const;
+
+/** The template's own coin, as its token metadata names it until a creator renames it. */
+export const INKWRIT_COIN = {
+  name: "Ink",
+  symbol: "INK",
+  logo: "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 32 32'%3E%3Ccircle cx='16' cy='16' r='15' fill='%231f3550'/%3E%3Cpath d='M16 5c4 6 7 10 7 14a7 7 0 0 1-14 0c0-4 3-8 7-14z' fill='%23e8dcc0'/%3E%3C/svg%3E",
+} as const;