@netforge/engine 0.0.0-stage → 0.1.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,148 @@
-# 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 client side of the Net Forge game engine.
+
+Two entry points, on purpose:
+
+| Import | Who uses it | What it holds |
+|---|---|---|
+| `@netforge/engine` | generated game code (the model) | `game`, `prefab`, `system`, `earn`, `store`, `engine.test.run`: declarative, Zod-validated, no DOM, no renderer, no netcode |
+| `@netforge/engine/runtime` | templates, the Net Forge shell, the demo | three.js renderer (WebGPU, WebGL2 fallback), `InstancedCrowd`, `CameraRig`, `InputController` (keyboard/mouse, nipplejs touch), `AssetLoader` (glTF + meshopt + KTX2), `ArenaClient`, `SystemScheduler`, `collectManifest` |
+
+A game module never reaches the renderer, netcode or physics.
+Bad declarations throw `GameDefinitionError` with one actionable line per
+issue, e.g. `model: reference assets by library id (e.g. "style.lowpoly.bat"), never by URL or path`.
+
+## Status (Template 1)
+
+- Declarations, validation, manifest cross-checks and the tick-based
+  `SystemScheduler`, plus `weapon()`, `upgrade()`, pickup prefabs, bosses,
+  and systems' `alive()`, `on(event)`, `respawnDead()`, `end(outcome)`.
+- `@netforge/engine/game` runs a declared game on engine-sim:
+  `compileGame` (manifest to sim content), `GameRunner` (systems on a run
+  clock, game events, run phases), `EarnTracker`, the engine-sim
+  `SimAdapter` (`engineSimAdapter`, wire schema `engineSchema`) and a
+  playtest bot. `engine.test.run` plays the declared game when there is one
+  (kills, waves, levels, earn by rule, softlock, ms/tick).
+- `@netforge/engine/net` is the client half of the netcode (the server
+  half runs in the hosted Net Forge room server): prediction and reconciliation, interpolation, delta
+  snapshots with per-kind fields, input packets, client clock adjustment
+  for one-input-per-tick sims, the wire protocol and the Colyseus room client.
+- `AssetLoader` is built but no template uses it yet (Template 1 art is
+  procedural, see packages/template-survivor/client/library.ts).
+
+## Status (Template 2, the arena shooter)
+
+- `game({ template: "arena", arena, round, players: { loadout, bots,
+  respawn, drop } })`, weapon kinds `blaster` (with `spread`) and `beam`,
+  and `emit(event, players?)` for crediting chosen players.
+- `compileGame` builds the yard (floor, pillars, spawns) and the arena
+  rules; it refuses survivor weapons in an arena and arena weapons in a
+  survivor game, with a line the model can act on.
+- `GameRunner` adds the round clock and frag limit (a round is a run),
+  `opponent.killed` / `player.died` / `round.top` / `round.finished`
+  events, kills and deaths per player, a kill feed in `RunInfo`, and seat
+  bots (`players.bots`) that fill empty seats while a human is present and
+  never earn. Killing a bot scores and shows in the feed but pays no earn
+  rule, and `round.top` pays only when another person was in the round
+  (both arrive as unpaid events, and so does anything a system emits while
+  handling one). Bots play through `arenaBotInput` (game/arena-bot.ts), a pure
+  function of the present, so a room's run replays exactly.
+- `engineSimAdapter` gives arena games the lag-compensation hooks the room
+  server's core already calls (`hitscans`, `hitboxes`, `applyHit`), runs
+  the client without authority, and grants store upgrades by name.
+- `engine.test.run` plays arena games with the bots and reports kills,
+  deaths, rounds, `topScore` and `scorers`.
+- The registry seals a game once its manifest is collected, so one process
+  (the room server) can load several game modules in turn.
+
+## Board genres (`@netforge/engine/rules`)
+
+Tower defense, idle, card battler and monster collector do not run on
+engine-sim's action world. Each is a deterministic rules module (integer
+state, a seeded PRNG word, no clocks) behind the same `SimAdapter` seam,
+so the room server, the netcode, the referee, run verification, the store,
+the stake and losable gear are the ones every template uses.
+
+- `RulesGenre<S>` (rules/kit.ts): `create`, `join`, `act` (a player's
+  validated action), `step` (one tick), `outcome`, `view(state, player)`
+  (what that player may see: hidden hands stay hidden), `entities` (moving
+  things, interpolated on the client) and the genre's own bot.
+- `rulesAdapter(genre, manifest)`: earn rules per player per run
+  (`EarnTracker`), seat bots that never earn, unpaid events, the late-start rule
+  (world progress never pays a run that started after the world began),
+  store upgrades and gear as recorded room commands capped at maxLevel,
+  cosmetics, the end screen and `run.reset`. Each player's avatar (a cursor,
+  a builder, a walking hero) is predicted from its own input.
+- `SimAdapter.infoFor(world, player)`: run state sent to one player only
+  (the room sends it when it changed, every `infoEveryTicks`).
+- Declarations: each genre adds its own typed functions to this package's
+  root (tower defense: `towerBoard`, `tower`, `waves`), validated by its own
+  Zod schemas and stored with `declareContent`. `engine.test.run` plays a
+  board genre through `playRules` and reports its own checks under
+  `rules.checks`.
+
+## Game feel kit (`runtime/feel`)
+
+One-line components every template uses. `FeelKit` wraps them:
+`hit`, `kill`, `hurt`, `levelUp`, `land`, `dash` and `footstep`, with the
+presets `subtle`, `default` and `heavy`. The parts work alone too:
+
+- `Trauma`: seeded-noise trauma shake.
+- `FeelClock`: hit-stop and slow motion with a smooth catch-up; the netcode never pauses.
+- `HitFlash` and `KnockbackOffsets`: flash and spring squash per entity id.
+- `Spring` and `Spring3`.
+- `DamageNumbers`: pooled, and merges rapid hits on one id.
+- `Tweens` and `Ease`, with `pop`, `shakeEl` and `countUp` for UI.
+- `FeelAudio`: procedural cues with throttles, voice limits, pan and distance falloff; `addBuffer` takes CC0 samples later. `Footsteps` alongside it.
+- `Rumble`: Gamepad dual-rumble, with a `navigator.vibrate` fallback.
+
+`CameraRig` adds `addTrauma`, `punch` (an FOV kick), a smoothed and
+clamped lead and a dead zone. Its old `shake(amplitude, seconds)` still
+works.
+
+## Render pipeline (`runtime/render`)
+
+`createRenderStack(handle, scene, camera, { preset, quality, bloom, outline })`
+returns the whole pipeline. Call `stack.frame(dt, focus)` in place of
+`renderer.render(scene, camera)`. It includes:
+
+- `LightingRig`: hemisphere light plus a sun whose shadow follows the focus, texel-snapped.
+- `PostFX`: bloom, colour grade, vignette and hurt pulse, tone mapping applied once, FXAA, and an optional depth outline.
+- `Atmosphere`: fog and a sky gradient.
+- `QualityManager`: tiers and dynamic resolution.
+- `GpuParticles`: one draw, with motion on the GPU.
+- `GroundDecals` and `GroundRings`.
+
+It runs on WebGPU and on WebGL2. Animated characters:
+
+- `AnimatedCrowd`: procedural vertex animation for instanced crowds.
+- `VatCrowd` and `bakeVertexAnimation`: vertex-animation textures for skinned crowds.
+- `AnimatedCharacter`: glTF skinned meshes on an `AnimationMixer` with locomotion blending.
+- `buildSegmentRig`: a procedural rig for tests and demos.
+
+The demo shows all of it with `?fx=1` (`&outline=1`, `&crowd=vat`,
+`&preset=dusk`, `&quality=low`).
+
+Game code declares the look and feel it wants: `game({ look })`,
+`prefab({ feel })` and `weapon({ feel })`, validated by `lookSchema` and
+`feelSchema`. See `llms.txt`.
+
+## Demo
+
+```sh
+pnpm --filter @netforge/engine-sim build
+pnpm --filter @netforge/engine demo          # http://localhost:5310
+# ?enemies=2000  ?webgl=1 (force the WebGL2 backend)  ?autopilot=1 (scripted input)
+```
+
+Measure in headless Chrome (raw CDP, no puppeteer dependency):
+
+```sh
+pnpm --filter @netforge/engine demo:build
+pnpm --filter @netforge/engine exec vite preview --config demo/vite.config.ts --port 5311
+CHROME_BIN=/path/to/chrome node packages/engine/scripts/measure-demo.mjs "http://localhost:5311/?autopilot=1" 20 --enable-unsafe-webgpu --use-angle=metal
+```
+
+The script always launches with `--use-mock-keychain --password-store=basic`
+and a throwaway profile, so it never prompts for the macOS keychain.

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][];
+};