@netforge/engine 0.0.0-stage → 0.2.0

package/GAME-DESIGN.md

@@ -0,0 +1,195 @@
+# Game design playbook
+
+Rules every game on this engine follows. They come from measured play: the
+first survivor build killed every player in 12 seconds, and a fun one kept
+the same bot alive for minutes. The playtest gate measures most of them, and
+a game that breaks them scores low.
+
+## Every genre
+
+1. **A readable opening, with real danger by 0:30.** The first threats
+   reach the player by about 0:20, and health moves by 0:30 to 0:45. The
+   first elite comes at about 0:45 and a mini-boss by 1:30 to 2:00. Nobody
+   dies in the first minute. (The first cut's playtest found no danger for
+   three minutes and scored 4/10. A quiet opening is not an empty one.)
+2. **Reward fast.** The first reward (a level, a kill, a pickup) comes within
+   about 10 seconds, then every 6 to 10 seconds for the first minute.
+3. **Never spawn on screen.** Enemies arrive from just off screen:
+   `director(...)` or `spawnEdge(prefab, { count })`, never `spawn()` or
+   `spawnRing()` at short radii. Pressure follows a moving player, because
+   stragglers far behind are recycled ahead of them.
+4. **Hits are survivable.** Contact damage gives i-frames
+   (`players.hitIframes`, 0.5 s). Twenty enemies touching you means one hit,
+   not twenty.
+5. **Slower than the player unless telegraphed.** Players run at 7 m/s.
+   Fodder moves at 45 to 60% of that, and fast runners up to 85% but fragile.
+   Anything faster or harder-hitting shows a telegraph first.
+6. **Telegraph every big hit.** Charges, slams, blasts and boss patterns
+   show a ground marker for 0.5 to 1 s, using shape and fill and not only
+   red. Over half of late deaths should be telegraphed ones, which means the
+   player misread the threat rather than the game being unfair.
+7. **Death is not a waiting room.** A downed player bleeds for about 10 s
+   and can crawl toward help. Each player gets one free self-revive per run.
+   A player who is out comes back beside a teammate within seconds
+   (`players.downed`), never "out until the next wave".
+8. **A run has a timeline.** It plays like a story with moments: new enemy
+   roles join one at a time, then elites, a mini-boss, an event, a flood, and
+   a final boss. Announce each moment so players always know what just
+   happened and where to go.
+9. **Bosses are moments.** A boss has a silhouette no mob shares and one or
+   two telegraphed attacks to learn. The first fight is short (about 45 s
+   solo), and the reward pops: a hoard chest that brings an evolution onto
+   the cards (`pickup: { effect: "chest", evolve: true }`).
+10. **Tougher, not more.** Past the crowd cap, the director makes new enemies
+   tougher instead of adding bodies. A boss alive halves the spawn rate, and
+   bosses scale with players present.
+11. **Builds have a goal.** Upgrades have numbers players can read ("+1 bolt",
+   "-20% cooldown"). Each weapon pairs with a passive toward an evolution.
+   Solo cards pause the game. Co-op cards do not pause, but they shove
+   enemies back.
+12. **Measure fun with bots.** The gate's human-like bot reacts 200 ms late,
+    kites, and reads cards for a second. Fix what it reports before
+    shipping.
+
+## Horde (survivor-like) targets
+
+| Metric | Target |
+|---|---|
+| First level | 4-10 s |
+| First damage taken | 15-45 s |
+| First elite / first mini-boss | ~0:45 / 1:30-2:00 |
+| First mini-boss fight, solo | ~45 s |
+| Level at 1:00 / 3:00 / 6:00 | ~5 / ~10 / ~15 |
+| Deaths before 1:00 | 0 |
+| Enemies on screen at 0:30 | 30-50 (wave-3 density in minute 1) |
+| Touches taken in minute 1 | 1-3 |
+| Spawns on screen | 0% |
+| Time spent downed or out | under 10% |
+| Solo survival, random picks | 4-7 min |
+
+A good curve is `director({ alive: [[0, 20], [30, 55], [60, 100], [180, 220], [300, 560], [540, 1900]], rate: [[0, 2], [30, 4], [60, 5], [180, 8], [300, 16], [540, 64]], speed: [[0, 1], [240, 1], [600, 1.6]], elites: { from: 45, every: [40, 55] } })`.
+Health and damage curves grow roughly ×1.35 per minute early and flatten
+later. Early gems are worth a little less (`xp` 0.7 at first), so the dense
+first minute does not run the levels hot. Late `speed` keeps endless
+kiting from working. The 2,000-enemy crowd is a late-run payoff, not an
+opening wall.
+
+## Arena shooter
+
+1. **First kill or pickup within about 20 s.** Spawns should be close enough
+   to find a fight, and pickups worth walking to.
+2. **Spawn safety.** No damage in the first 2 s after spawning, and under a
+   quarter of deaths within 3 s of spawning. Spawn points sit out of sight
+   lines, away from the middle.
+3. **Contest the map.** Heals, power weapons and high ground make places
+   worth fighting over. Put them in the open between spawns.
+4. **Readable hits.** Hits flash, kills pop, the feed names who killed whom,
+   and your own shot shows instantly on your screen, before the server
+   agrees.
+5. **Moments.** Announce streaks, put a bounty on the leader, and run a
+   late-round event, so the lead changes hands. When one player has 3x the
+   average kills, a weapon or a position dominates.
+6. **Bots that ramp.** Seat bots fill rooms, play below a new player's level
+   at first and get sharper as people win. They never stomp a newcomer.
+   They never earn, and they are never a coin source: killing a bot scores
+   but pays no earn rule, and "round.top" pays only with another person in
+   the round. Earn comes from beating people.
+
+## How a change request maps to the API
+
+- **"Harder"**: raise the director's `alive`, `rate`, `health` or `damage`
+  keyframes late in the run, never at 0 s.
+- **"Easier"**: lower them, raise `players.hitIframes` or `magnet`, or give
+  the starting weapon more range.
+- **"More enemy types"**: add a prefab and a pool entry with `from: <seconds>`,
+  one new idea at a time. Use `group: [8, 12]` for streams.
+- **"Add a boss"**: add a prefab with `boss: { attacks: [...], rank }` and
+  spawn it with `spawnEdge(id, { count: 1 })` from `after(seconds, ...)`.
+  Give mini-bosses 3 attacks and the final boss 4. Its health scales with
+  players present.
+- **"Smarter" or "trickier enemies"**: give prefabs roles (`ai: "charger"`,
+  `"ranged"`, `"bomber"`, `"shielder"`, `"summoner"`), or add elites.
+- **"Add events" or "waves"**: use `every` or `after` in a system, with
+  `spawnEdge(id, { count, side: "north" })` for a tide from one side,
+  `xpBoost`, `surge` or a fleeing carrier with a chest. `announce` each one,
+  never repeat the same event twice in a row, and skip events while
+  `bossAlive()`.
+- **"More loot" or "a map worth exploring"**: special pickups (heal,
+  vacuum, bomb, chest) as rare drops, props to `scatter`, and a bigger `field`.
+- **"Longer or shorter run"**: move the boss's `after(...)` and stretch the
+  curves' keyframe times.
+- **"More weapons" or "better builds"**: declare 5-8 `levels` per weapon
+  (each a readable change), pair weapons with passives through `evolve`, and
+  give evolutions a new shape. Keep weapons + evolutions within 15.
+- **"Add a character" or "more heroes"**: `keeper(id, { weapon, passive,
+  unlock })`, unlocked by an `achievement`, or declared without an unlock
+  and sold (`store.sku(id, { coins, grants: { keeper: id } })`): earned or
+  bought, never both. A keeper is a different way to play, never a stronger
+  one, and the first keeper is always free.
+- **"Reasons to come back"**: `achievement`s that unlock keepers,
+  `mission`s for daily goals, `title`s for the end screen. None pay coins;
+  coin rewards are earn rules, which are an economy decision. The room
+  server grants them from the run and saves them per player, so they follow
+  the player to every device.
+- **"Sell character unlocks"**: a SKU per keeper with `grants: { keeper }`,
+  on keepers declared without an `unlock`.
+- **"Cosmetics only" or "no pay to win"**: `economy({ store: "cosmetics" })`
+  and only SKUs with `grants: { cosmetic: n }`.
+- **"Let players buy permanent upgrades with coins"**:
+  `economy({ metaUpgrades: true })` and a few `metaUpgrade(...)`s (below).
+- **"Better co-op"**: `players.share` ("nearby" is the default), a
+  `reviveBuff`, `lateJoinBehind`, and `upcoming(...)` countdowns everyone
+  sees.
+
+## The recommended coin model, and why
+
+Every game has coins (1 coin = 1 of the game's own token). How they are
+spent decides whether the game stays fair to the player who never pays, and
+whether a token holder can buy a win. The engine ships one recommended
+model and makes the alternatives declarations, so a
+change request is a one-line change, never new code.
+
+**The default (no declaration; every template uses it).** Coins buy:
+
+- **Cosmetics**: a look owned for good,
+  `store.sku("skin_aurora", { coins: 300, grants: { cosmetic: 1 } })`.
+- **Unlocks**: a keeper (a character, a starting loadout, a sidegrade)
+  declared without an `unlock`,
+  `store.sku("unlock_tinker", { coins: 400, grants: { keeper: "tinker" } })`.
+  An unlock is a different way to play at the same power as the keepers
+  anyone can earn by playing. A keeper is earned (by an achievement) or
+  bought, never both, so a sold keeper cannot be opened another way.
+- **In-run consumables**: used once, inside one run,
+  `store.sku("revive", { coins: 50 })` (no `grants`).
+
+Coins never buy permanent stat power by default. A run is decided by how it
+was played, and a newcomer next to a long-time holder plays the same game.
+
+**Cosmetics only (opt-in):** `economy({ store: "cosmetics" })`. The build
+refuses any SKU that is not a look.
+
+**Meta upgrades (opt-in, never the default):** permanent stat upgrades
+bought with coins, the way many survivor-likes do between runs.
+
+```ts
+economy({ metaUpgrades: true });
+metaUpgrade("hearth", { stat: "maxHealth", step: 0.05, levels: 3, cost: 120, growth: 2 });  // +5% a level: 120, 240, 480
+metaUpgrade("stride", { stat: "speed", step: 0.03, levels: 3, cost: 100, growth: 1.8 });
+```
+
+The engine enforces hard caps that no game can raise: +15% to any one stat
+from meta upgrades, +30% across all of them, at most 5 levels each and 8 per
+game, and geometric costs (each level at least 1.5 times the last). The
+room server applies a player's levels at the start of every run, capped
+again, and the store shows each level's bonus and price. Use them only when
+the creator asks for permanent upgrades, and keep steps small (3-5%).
+
+**Before launch** coins are play money, and play money buys only in-run
+items. Looks, unlocks and meta levels need real coins, so they open at
+launch; nothing bought with play money persists or carries over.
+
+**Where it is enforced.** Prices come from the manifest, never the client.
+A purchase is a coin spend (earned coins first, then the wallet) that the
+room server checks against that price before the item is owned, and the
+item is saved in the player's profile on the server. Spent coins recycle
+to the reward pool for other players, as every coin spend does.

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,30 @@
+@netforge/engine
+Copyright (c) 2026 NetNet Capital Management
+
+This package depends on, or takes patterns from, the following works.
+No source was copied from copyleft (GPL/AGPL) projects. The demo uses
+only generated primitives; no third-party art, models, sounds or fonts.
+
+Dependencies (unmodified, via npm)
+- three.js 0.186.1 (https://github.com/mrdoob/three.js), MIT. Includes the
+  GLTFLoader, KTX2Loader and meshopt decoder addons it ships.
+- meshoptimizer decoder (bundled with three.js addons), MIT, Arseny Kapoulkine.
+- Basis Universal transcoder (bundled with three.js addons), Apache-2.0, Binomial LLC.
+- nipplejs 1.0.4 (https://github.com/yoannmoinet/nipplejs), MIT.
+- zod 4.4.3 (https://github.com/colinhacks/zod), MIT.
+- @colyseus/sdk 0.18.5 (https://github.com/colyseus/colyseus), MIT, Endel Dreyer.
+  Used by src/net/room-client.ts.
+- @netforge/engine-sim (this repository); see its NOTICE for bitECS
+  (MPL-2.0) and Rapier (Apache-2.0).
+
+Patterns
+- src/net: client prediction and server
+  reconciliation after Gabriel Gambetta's articles; snapshot interpolation
+  and delta compression after Valve's Source networking write-ups, Glenn
+  Fiedler's snapshot compression articles and the Quake 3 model (GPL,
+  ideas only, no code); clock sync for one-input-per-tick play after the
+  Overwatch GDC netcode talk (idea only).
+- Render interpolation between fixed ticks after Glenn Fiedler, "Fix Your
+  Timestep!"; idea only.
+- Writing instance matrices directly into InstancedMesh.instanceMatrix
+  follows the three.js instancing examples (MIT).

package/README.md

@@ -1,3 +1,101 @@
-# Temporary Holding Version
+# @netforge/engine
 
-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.
+The Net Forge game engine client: a typed, declarative game API and a three.js renderer (WebGPU with a WebGL2 fallback) for multiplayer browser games.
+
+One simulation is shared by client and server (an ECS with Rapier physics, a fixed tick and snapshots, in `@netforge/engine-sim`), ten finished multiplayer games ship as templates (`@netforge/template-*`), and the whole API is built to be written by your own coding agent.
+
+## Install
+
+```sh
+npm install @netforge/engine
+```
+
+Node 20 or later. The package ships ES modules with TypeScript types.
+
+## Example
+
+A game is one file, `src/game.ts`, that declares what the game is. It imports only `@netforge/engine` and never touches the renderer, the netcode or the physics. This is a cut-down version of the arena shooter template:
+
+```ts
+import { earn, game, prefab, store, weapon } from "@netforge/engine";
+
+export default game({
+  template: "arena",
+  style: "lowpoly",
+  places: { yard: { chunks: "places/yard", spawn: [0, 1, 0] } },
+  players: { prefab: "style.lowpoly.mini_male_f", max: 16, loadout: ["arc_rifle"], bots: 6, respawn: 3, drop: "volt_cell" },
+  arena: { halfSize: 26, pillars: [[0, 0, 2.6]], spawns: [[22, 22], [-22, -22], [22, -22], [-22, 22]] },
+  round: { seconds: 180, frags: 25 },
+});
+prefab("volt_cell", { model: "style.lowpoly.cell_heal", health: 1, speed: 0, kind: "pickup", value: 35 });
+weapon("arc_rifle", { kind: "blaster", damage: 12, cooldown: 0.15, range: 26, speed: 44 });
+earn.rule("live_wire", { when: "opponent.killed", n: 3, pay: 4, oncePer: "run" });
+earn.stake({ min: 10, max: 100, multiple: 2 });
+store.sku("skin_neon", { coins: 300, grants: { cosmetic: 1 } });
+```
+
+Then play it headless with bots and check it:
+
+```ts
+import { engine } from "@netforge/engine";
+
+const report = await engine.test.run({
+  ticks: 60 * 240,
+  bots: 4,
+  assert: [{ name: "someone scores", check: (r) => r.kills > 0 }],
+});
+console.log(report.kills, report.earned, report.softlock, report.msPerTick);
+```
+
+Bad declarations throw `GameDefinitionError` with one actionable line per issue, for example `model: reference assets by library id (e.g. "style.lowpoly.bat"), never by URL or path`.
+
+## Entry points
+
+| Import | Who uses it | What it holds |
+|---|---|---|
+| `@netforge/engine` | game code (`src/game.ts`) | `game`, `prefab`, `weapon`, `upgrade`, `system`, `director`, `earn`, `store`, `keeper`, `achievement`, `mission`, `title`, `economy`, `metaUpgrade`, `dungeon`, the board genre declarations (`towerBoard`, `tower`, `waves`, `saltFlat`, `plant`, `marsh`, `creature`, `move`, `card`, `cardTable`), and `engine.test.run`. Declarative, Zod-validated, no DOM. |
+| `@netforge/engine/runtime` | template clients | the three.js renderer (`createRenderer`), `createRenderStack`, `CameraRig`, `InputController` (keyboard, mouse, gamepad, touch), `AssetLoader` (glTF, meshopt, KTX2), `FeelKit` and its parts, `SoundPlayer`, `ArenaClient`, `SystemScheduler`, `collectManifest`. |
+| `@netforge/engine/game` | templates, room hosts, tests | `compileGame`, `collectManifest`, `GameRunner`, `EarnTracker`, `engineSimAdapter` (the SimAdapter on `@netforge/engine-sim`). |
+| `@netforge/engine/net` | template clients | the client half of the netcode: prediction and reconciliation, interpolation, delta snapshots, input packets, clock adjustment and the room client. |
+| `@netforge/engine/rules` | board genres | `rulesAdapter`, `playRules` and the genre modules: deterministic rules (tower defense, idle, cards, collector) behind the same SimAdapter seam. |
+| `@netforge/engine/voxel` | template clients | the voxel style's core. |
+| `@netforge/engine/earn-source` | tools | reads and rewrites the `earn.rule(...)` lines of a `src/game.ts` as source text. |
+
+Game code imports only the root. Everything else is template machinery.
+
+## What the root API covers
+
+- **Templates**: `TEMPLATES` lists them: `survivor`, `arena`, `dungeon`, `racer`, `platformer`, `tower-defense`, `party`, `idle`, `cards` and `collector`.
+- **Art**: `game({ style })` picks one of `STYLES`: `pixel`, `lowpoly`, `toon`, `voxel`, `ps1` or `handdrawn`. Models are asset library ids such as `"style.lowpoly.ghost"`, never URLs or file paths.
+- **Look and feel**: `game({ look })`, `prefab({ feel })` and `weapon({ feel })` are presentation only and never change the simulation.
+- **Earn**: every game declares at least one `earn.rule(...)` and exactly one `earn.stake({ min, max, multiple })`. The build fails without them. Ids are lower_snake_case.
+- **Coins and the store**: `store.sku(...)` sells in-run consumables, cosmetics and unlocks by default. Permanent stat upgrades are opt-in through `economy({ metaUpgrades: true })` and `metaUpgrade(...)`, capped by the engine (`META_MAX_PER_STAT`, `META_MAX_TOTAL`).
+- **Systems**: `system(id, ctx => ...)` gets `every`, `after`, `on`, `emit`, `spawn`, `spawnEdge`, `players`, `end` and a seeded `random`, on a tick clock.
+- **Playtest**: `engine.test.run({ ticks, bots, seed?, enemies?, bot?, assert? })` plays the game on the server sim and reports kills, deaths, waves, runs, earn by rule, softlocks, ms per tick and fun metrics.
+
+`GAME-DESIGN.md` holds the design rules the playtest gate measures (a readable opening, fast rewards, no on-screen spawns) and the recommended coin model.
+
+## For AI agents
+
+- Read `llms.txt` (look, feel, physics and rendering) and `llms-full.txt` (`llms.txt`, `GAME-DESIGN.md` and the API reference in one file).
+- Each template package (`@netforge/template-*`) ships its own `llms.txt`, `llms-full.txt` and `AGENTS.md` for its genre.
+- The Net Forge MCP server gives an agent the same tools over stdio: `npx -y @netforge/mcp` (package `@netforge/mcp`, bin `netforge-mcp`). Tools: `netforge_list_templates`, `netforge_create_game`, `netforge_explain_api`, `netforge_search_docs`, `netforge_validate_game`, `netforge_run_playtest`, `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 add the server with `claude mcp add netforge -- npx -y @netforge/mcp`. Any other MCP client takes this config:
+
+```json
+{ "mcpServers": { "netforge": { "command": "npx", "args": ["-y", "@netforge/mcp"] } } }
+```
+
+## Play a game locally
+
+`@netforge/kit-play` runs a game folder (`netnet.json` plus `src/game.ts`) on your own computer with play money. See its README.
+
+## Docs
+
+- https://forge.netnet.capital/docs/packages/engine
+- `llms.txt`, `llms-full.txt` and `GAME-DESIGN.md` in this package
+
+## License
+
+MIT. See `LICENSE` and `NOTICE`.

package/dist/api/appearance.d.ts

@@ -0,0 +1,37 @@
+import { z } from "zod";
+/**
+ * APPEARANCE (asset library section). An appearance
+ * dresses a library model so one base makes many distinct originals: a
+ * body colour, an accent colour, a size, and up to four attachments from a
+ * fixed list. The model writes appearances; it never writes geometry. The
+ * same recipe draws the same character on every client.
+ *
+ * Not to be confused with game({ look }), the scene's render look.
+ * Kept in its own file so schema changes elsewhere rebase mechanically.
+ */
+/** Attachments an appearance can add. Each sits on an anchor the body plan has (head, face, back, tail, body, wheels). */
+export declare const APPEARANCE_PARTS: readonly ["horns", "ears_long", "ears_round", "antenna", "crown", "hat_cap", "hat_top", "mustache", "tail", "tail_bolt", "wings", "armor", "backpack", "big_wheels"];
+export declare const appearanceSchema: z.ZodObject<{
+    tint: z.ZodOptional<z.ZodString>;
+    accent: z.ZodOptional<z.ZodString>;
+    scale: z.ZodOptional<z.ZodNumber>;
+    parts: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+        horns: "horns";
+        ears_long: "ears_long";
+        ears_round: "ears_round";
+        antenna: "antenna";
+        crown: "crown";
+        hat_cap: "hat_cap";
+        hat_top: "hat_top";
+        mustache: "mustache";
+        tail: "tail";
+        tail_bolt: "tail_bolt";
+        wings: "wings";
+        armor: "armor";
+        backpack: "backpack";
+        big_wheels: "big_wheels";
+    }>>>;
+}, z.core.$strict>;
+export type AppearanceInput = z.input<typeof appearanceSchema>;
+export type AppearanceDef = z.output<typeof appearanceSchema>;
+export type AppearancePart = (typeof APPEARANCE_PARTS)[number];

package/dist/api/appearance.js

@@ -0,0 +1,41 @@
+import { z } from "zod";
+/**
+ * APPEARANCE (asset library section). An appearance
+ * dresses a library model so one base makes many distinct originals: a
+ * body colour, an accent colour, a size, and up to four attachments from a
+ * fixed list. The model writes appearances; it never writes geometry. The
+ * same recipe draws the same character on every client.
+ *
+ * Not to be confused with game({ look }), the scene's render look.
+ * Kept in its own file so schema changes elsewhere rebase mechanically.
+ */
+/** Attachments an appearance can add. Each sits on an anchor the body plan has (head, face, back, tail, body, wheels). */
+export const APPEARANCE_PARTS = [
+    "horns",
+    "ears_long",
+    "ears_round",
+    "antenna",
+    "crown",
+    "hat_cap",
+    "hat_top",
+    "mustache",
+    "tail",
+    "tail_bolt",
+    "wings",
+    "armor",
+    "backpack",
+    "big_wheels",
+];
+const HEX = /^#[0-9a-fA-F]{6}$/;
+export const appearanceSchema = z
+    .object({
+    /** Main body colour, "#rrggbb". Shifts the model's palette toward it. */
+    tint: z.string().regex(HEX, 'colours are "#rrggbb", e.g. "#ffd23f"').optional(),
+    /** Colour of the attachments, "#rrggbb". Default: a darker tint. */
+    accent: z.string().regex(HEX, 'colours are "#rrggbb", e.g. "#3a2a1a"').optional(),
+    /** Size multiplier on the library model's height (0.4 to 3). Visual only; the prefab's radius is the hit size. */
+    scale: z.number().min(0.4, "scale is at least 0.4").max(3, "scale is at most 3").optional(),
+    /** Up to four attachments, e.g. ["ears_long", "tail_bolt"]. */
+    parts: z.array(z.enum(APPEARANCE_PARTS)).max(4, "an appearance carries at most 4 parts").default([]),
+})
+    .strict();

package/dist/api/cards.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Card battler declarations (game({ template: "cards" })). The template
+ * already runs the duel (heroes, mana, draws, a board of units, spells,
+ * guards, the turn timer), the gauntlet of duels with a draft between
+ * them, the server-side shuffle, hidden hands, the AI opponents and the
+ * referee. A game declares its table rules and its cards.
+ *
+ *   cardTable({ health: 20, duels: 4, starter: ["blot_imp", "blot_imp", ...], ai: [{ health: 14, smart: 0.3 }] });
+ *   card("ink_frog", { model: "style.lowpoly.frog", kind: "unit", cost: 2, attack: 2, health: 3 });
+ *   card("splash", { model: "style.lowpoly.crystal", kind: "spell", cost: 1, effect: { kind: "damage", amount: 2, target: "enemy" } });
+ */
+import { z } from "zod";
+import type { GameManifest } from "./registry.js";
+export declare const EFFECT_KINDS: readonly ["damage", "heal", "draw", "buff"];
+/**
+ * Who an effect hits. "enemy": the player picks an enemy unit or the enemy
+ * hero; "enemy_hero"; "all_enemies": every enemy unit; "own_hero";
+ * "own_unit": the player picks one of their units; "all_own": every unit
+ * they have. draw ignores the target.
+ */
+export declare const EFFECT_TARGETS: readonly ["enemy", "enemy_hero", "all_enemies", "own_hero", "own_unit", "all_own"];
+export declare const cardEffectSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        damage: "damage";
+        heal: "heal";
+        draw: "draw";
+        buff: "buff";
+    }>;
+    amount: z.ZodNumber;
+    target: z.ZodDefault<z.ZodEnum<{
+        enemy: "enemy";
+        enemy_hero: "enemy_hero";
+        all_enemies: "all_enemies";
+        own_hero: "own_hero";
+        own_unit: "own_unit";
+        all_own: "all_own";
+    }>>;
+}, z.core.$strict>;
+/**
+ * A card. A "unit" stands on the board with attack and health; `guard`
+ * units must be attacked first; `rush` units may attack the turn they are
+ * played. A unit's `effect` happens when it is played. A "spell" is only
+ * its effect. cost is mana (0 to 10).
+ */
+export declare const cardSchema: z.ZodObject<{
+    model: z.ZodString;
+    kind: z.ZodEnum<{
+        unit: "unit";
+        spell: "spell";
+    }>;
+    cost: z.ZodNumber;
+    attack: z.ZodDefault<z.ZodNumber>;
+    health: z.ZodDefault<z.ZodNumber>;
+    guard: z.ZodDefault<z.ZodBoolean>;
+    rush: z.ZodDefault<z.ZodBoolean>;
+    effect: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodEnum<{
+            damage: "damage";
+            heal: "heal";
+            draw: "draw";
+            buff: "buff";
+        }>;
+        amount: z.ZodNumber;
+        target: z.ZodDefault<z.ZodEnum<{
+            enemy: "enemy";
+            enemy_hero: "enemy_hero";
+            all_enemies: "all_enemies";
+            own_hero: "own_hero";
+            own_unit: "own_unit";
+            all_own: "all_own";
+        }>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const cardTableSchema: z.ZodObject<{
+    health: z.ZodDefault<z.ZodNumber>;
+    startHand: z.ZodDefault<z.ZodNumber>;
+    handMax: z.ZodDefault<z.ZodNumber>;
+    boardMax: z.ZodDefault<z.ZodNumber>;
+    manaMax: z.ZodDefault<z.ZodNumber>;
+    turnSeconds: z.ZodDefault<z.ZodNumber>;
+    draftSeconds: z.ZodDefault<z.ZodNumber>;
+    duels: z.ZodDefault<z.ZodNumber>;
+    starter: z.ZodArray<z.ZodString>;
+    pool: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    ai: z.ZodArray<z.ZodObject<{
+        health: z.ZodNumber;
+        smart: z.ZodNumber;
+    }, z.core.$strict>>;
+    turnCap: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>;
+export type CardInput = z.input<typeof cardSchema>;
+export type CardDef = z.output<typeof cardSchema>;
+export type CardTableInput = z.input<typeof cardTableSchema>;
+export type CardTableDef = z.output<typeof cardTableSchema>;
+/** The table: hero health, hand and board sizes, the gauntlet, the starter deck and the AI tiers (one per game). */
+export declare function cardTable(def: CardTableInput): CardTableDef;
+/** A card (at most 40). */
+export declare function card(id: string, def: CardInput): CardDef;
+/** Store upgrade stats a card battler reads: hero health, unit attack, starting mana, starting hand. */
+export declare const CARD_STATS: readonly ["maxHealth", "might", "haste", "amount"];
+/** The card battler content of a manifest, cross-checked (one line per issue). */
+export declare function cardsContent(m: GameManifest): {
+    table: CardTableDef;
+    cards: [string, CardDef][];
+};