@jgengine/core 0.10.0 → 0.11.0

package/skills/jgengine/capabilities.md

@@ -0,0 +1,29 @@
+<!-- GENERATED by scripts/gen-capability-index.ts — do not edit. Regenerate: bun run gen:capabilities -->
+
+# jgengine — capability index
+
+Reach for these before hand-rolling. Each row is *the thing you need* → *the primitive that already does it*.
+
+## define-game — single public game-authoring path — compose systems, world, and loop in one definition
+
+- `defineGame` (function) · `import { defineGame } from "@jgengine/core/authoring"`
+
+## headless-runner — play a real game loop with no renderer — tick, feed input, read the world snapshot
+
+- `HeadlessRunner` (interface) · `import { HeadlessRunner } from "@jgengine/core/runtime/headlessRunner"`
+
+## loot-table — validate a loot table definition for use with the registry
+
+- `lootTable` (function) · `import { lootTable } from "@jgengine/core/authoring"`
+
+## runtime-save — save/load the whole game world through a pluggable backend, autosave or save points
+
+- `createRuntimeSave` (function) · `import { createRuntimeSave } from "@jgengine/core/runtime/runtimeSave"`
+
+## scene-ownership — audit a whole ownership manifest for boundary violations
+
+- `auditManifest` (function) · `import { auditManifest } from "@jgengine/core/authoring"`
+- `classifyOwnership` (function) · `import { classifyOwnership } from "@jgengine/core/authoring"`
+- `collectOwnershipDiagnostics` (function) · `import { collectOwnershipDiagnostics } from "@jgengine/core/authoring"`
+- `isSceneOwnershipManifest` (function) · `import { isSceneOwnershipManifest } from "@jgengine/core/authoring"`
+- `ownershipKey` (function) · `import { ownershipKey } from "@jgengine/core/authoring"`

package/skills/jgengine/reference-cartridge.md

@@ -0,0 +1,72 @@
+# jgengine-api — Cartridge
+
+Reference module for the [`jgengine`](./SKILL.md) skill. Load this when building a game as a **cartridge** — one declarative config instead of hand-wired loop/state/UI files. A cartridge game is ~75% smaller than the classic shape and nearly all of it is data; reach for `defineGame` + `defineSystem` ([reference-systems.md](./reference-systems.md)) when the simulation outgrows cartridge archetypes — same single authoring model, no rewrite cliff.
+
+## Why
+
+Across the classic games, 78–91% of each game's LOC was generic wiring restated per game: a run-state store with subscribe/notify, chase-and-contact enemy loops, auto-fire weapon routines, magnet pickups, draft plumbing, phase-gated HUD trees, and tests for all of it. The cartridge layer owns every one of those; the game ships only its **data** (catalogs, tuning, layout) and any genuinely bespoke rules through typed escape hatches.
+
+## Shape
+
+`game.config.ts` is the whole game — `cartridge({...})` from `@jgengine/shell/cartridge` compiles the config into a `PlayableGame` (validating it first — a bad reference throws at import with a list of problems). `loop.ts` and `world.ts` disappear; the spec carries the world feature and the loop is engine-owned. `main.tsx` is 5 lines via `mountGame` (`@/components/ui/mount`, registry). Sprites/SVG art stay in `src/game/assets.ts`; the game keeps one test file under `src/game/`.
+
+```ts
+import { cartridge, type CartridgeConfig } from "@jgengine/shell/cartridge";
+import { standardCartridgePanels } from "@/components/ui/cartridge-panels";
+
+export const config: CartridgeConfig = {
+  name, seed, panels: standardCartridgePanels, assets, entitySprites,
+  flow: { start: "gate", countdownSeconds: 3, restart: true },  // press-to-start → 3-2-1 → playing; "restart" command
+  player: { kind, health, walkSpeed },              // compiled into content + spawned per player
+  enemies: { id: { label, health, walkSpeed, xp, contact: { damage, intervalSeconds }, behavior: "chase" | "none" } },
+  combat: { contactRadius },
+  spawning: { director: SpawnDirectorConfig, placement: { kind: "ring", radius } },
+  weapons: { id: { kind: "projectile" | "orbit" | "pulse" | "custom", damage, cooldownMs, maxLevel, ... } },
+  progression: { xp: Curve, maxLevel, draft: { choices, upgrades } },
+  fields: { magnetRadius, damageMultiplier },       // named run-scalars upgrades mutate
+  xpGems: { collectRadius, pullSpeed, rarityThresholds, defaultRarity },
+  rules: { win: { kind: "survive", seconds }, lose: { kind: "playerDeath" } | { kind: "custom", check }, killLeaderboardStat },
+  world, physics, camera, worldItem, theme, hud, screens,   // screens: start/win/lose
+};
+export const game = cartridge(config);
+```
+
+The run is a phase machine every game gets for free: `start → countdown → playing → won | lost`. `flow.start: "gate"` renders `screens.start` (TitleScreen binding) until begin; `flow.countdownSeconds` renders the big-number countdown; `flow.restart: true` registers a `restart` command that resets the run in place, clears cartridge entities, and restores player stats — no hand-rolled session store, phase union, or reset function. `run.playingSeconds` is the run clock (drives the survive rule and the timer panel), so pauses and pre-game phases never skew timing.
+
+## Cartridge surface (`@jgengine/shell/cartridge/`)
+
+The survivor-shaped defaults (XP gems, contact-radius melee, orbit/pulse/projectile weapons) are a genre archetype, not a core primitive — the whole cartridge implementation lives in `@jgengine/shell` (opt-in, alongside its React binding), never in `@jgengine/core`. `core` only supplies the generic pieces it composes: `spawnDirector`, `abilityKit`, `leveling`/`progression`, `runDraft`, `autoTarget`. A puzzle or tactics game imports none of this.
+
+- `@jgengine/shell/cartridge/spec` — the `CartridgeSpec` types, `Leveled` values (`number | { base, perLevel, min?, max? } | { table }` resolved by `leveled(value, level)`), `WASD_KEYBINDS` (the default when `input` is omitted).
+- `@jgengine/shell/cartridge/runtime` — `createCartridge(spec)` → `{ content, loop, run(ctx), weaponKit(ctx), chooseUpgrade(ctx, offerId) }`. Owns the run store (outcome/kills/fields/weapon levels, subscribe/notify), spawn director advance + ring placement, chase + contact-damage enemies (terrain-grounded), the three weapon archetypes with auto-targeting, magnet xp-gem pickups feeding `leveling()`, pause-and-draft level-ups, kill → gem drop + leaderboard, and win/lose rules.
+- `@jgengine/shell/cartridge/validate` — `validateCartridge(spec)` → problem list: spawn waves must reference declared enemies, upgrades must reference declared weapons/fields, stacks can't exceed weapon `maxLevel`, tuning must be positive, rarity thresholds descending. The game's test asserts it returns `[]`.
+
+Weapon archetypes: `projectile` (auto-target nearest in `range`, travel-time bolt fx), `orbit` (leveled blade count/radius sweeping `hitRadius`), `pulse` (radial AoE with linear falloff and an expanding-ring fx). Upgrade effects: `weaponLevel` (+1 level per stack), `statBonus` (+max and +current on pick), `fieldAdd` / `fieldMultiply` (recomputed from stacks). Weapon damage is multiplied by the `damageMultiplier` field when declared.
+
+## Presentation (shell + registry)
+
+`hud.panels` is a schema — items `vital | xp | timer | score | abilityBar | component`, anchored via the movable HUD layout; `screens.win/lose` render the results/death screens; the upgrade-draft modal appears whenever a draft is pending. The shell renders the frame and injects concrete components through the `panels` seam — `standardCartridgePanels` (registry `cartridge-panels`) binds the jgengine UI kit; swap any binding for a custom component without touching the engine. Weapon fx render engine-side from the run store's bolt/pulse feeds (`fxColor`/`fxEmissive` per weapon). `theme` is the `--jg-*` CSS var block — hand-pick it or derive from a few seed colors with `deriveJgTheme` (registry `jg-theme`).
+
+## Escape hatches — bespoke logic without leaving the cartridge
+
+- `weapons.<id> = { kind: "custom", fire(ctx, run, args) }` — cooldown/level/damage handled for you; the fire shape is yours.
+- `spawning.placement = { kind: "custom", position(ctx, run) }`.
+- `rules.win = { kind: "custom", check(ctx, run) }`.
+- `progression.draft.upgrades[].effect = { kind: "custom", apply(ctx, run, stacks) }`.
+- `systems: [(ctx, run, dt) => ...]` — extra per-tick simulation after the built-ins, only while playing.
+- `hud` items `{ kind: "component", Component }` — arbitrary React panels alongside the schema ones.
+
+A game that is *mostly* bespoke simulation (custom physics, session machines) should keep `defineGame` and write its systems — the cartridge is for games whose shape the archetypes already cover.
+
+## Testing
+
+Cartridge behaviors are engine-tested once (`packages/shell/src/cartridge/runtime.test.ts`); the game test is one call plus any game-specific assertions:
+
+```ts
+import { bootCartridge, cartridgeSmokeTest, tickCartridge } from "@jgengine/shell/cartridge/testkit";
+cartridgeSmokeTest(config);   // validate + world summary + headless run/spawn/kill/gem smoke
+```
+
+`bootCartridge`/`tickCartridge` build a headless `GameContext` and drive the loop (auto-choosing drafts) for custom assertions — see `@jgengine/shell/cartridge/testkit`. The testkit imports `bun:test`; import it from test files only.
+
+Barrel surface tokens: createKeyValueStore createUnlocks durabilityFraction isComplete isOverdrawn memorySaveBackend partInSlot pruneToasts policyProjectsViewers projectByVisibleIds projectEntitiesForViewer projectPerUserForViewer visibleEntityIds applyDeltaToSnapshot applySurfaceDeltaToSnapshot boundaryNeighbors catenaryCurve distanceToPolygonEdge footprintObstacles hasValidAdjacency pointInPolygon polygonArea polygonBounds populateNavGridFromEnvironment readScatterPalette readScatterRules revertDeltaFromSnapshot revertSurfaceDeltaFromSnapshot slopeStepCost solveLock solveLockPath

package/skills/jgengine-combat/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: jgengine-combat
+description: Compose targeting, stats, damage, effects, abilities, and rewards.
+---
+
+# JGengine combat
+
+## Ownership
+
+This skill owns combat resolution: target policy, combat stats, teams/factions as combat inputs, effects, damage/healing, projectiles, abilities, cooldowns, death/downed state, encounters, and reward/loot resolution. Movement and perception live in `jgengine-world`; inventory/economy state lives in `jgengine-gameplay`.
+
+Search [capabilities.md](capabilities.md), then use [api.md](api.md) for signatures and [reference.md](reference.md) for complete pipelines.
+
+## Canonical pipeline
+
+1. Acquire eligible candidates from a bounded spatial source.
+2. Select a target through caller-owned policy and deterministic tie-breaking.
+3. Validate costs, cooldowns, range, visibility, and authority.
+4. Resolve typed effects through ordered, inspectable stages.
+5. Apply damage/healing/status transitions and emit provenance-rich events.
+6. Resolve death/downed and rewards separately from the hit itself.
+
+Compose stages through registration/policy seams; adding a damage type, effect, target policy, or reward strategy must not add a central engine branch.
+
+## Traps
+
+- Stats are named caller data; the engine does not privilege genre attributes.
+- Visual projectiles/VFX do not own authoritative hit resolution.
+- Random rolls accept injected RNG and stable seeds.
+- Interceptors record why values changed; hidden callbacks make outcomes unauditable.
+- Reward generation and allocation are different operations, especially in multiplayer.
+- Compose multiple loot pools with `createLootPipeline` (ordered stages, gates, fallbacks, roll modifiers, per-drop provenance) over `lootTable`; keep genre concepts (world/dedicated/boss/luck/pity) in game-space stages and modifiers, never in core.
+- UI bars, reticles, and feedback route to `jgengine-ui`.
+