@jgengine/core 0.9.0 → 0.11.0

package/skills/jgengine-gameplay/capabilities.md

@@ -0,0 +1,378 @@
+<!-- GENERATED by scripts/gen-capability-index.ts — do not edit. Regenerate: bun run gen:capabilities -->
+
+# jgengine-gameplay — capability index
+
+Reach for these before hand-rolling. Each row is *the thing you need* → *the primitive that already does it*.
+
+## advance-ledger — settle due scheduled transactions through a policy pipeline
+
+- `advanceLedger` (function) · `import { advanceLedger } from "@jgengine/core/gameplay"`
+
+## best-record — persist personal-best times/scores with safe storage fallback
+
+- `createRecordBook` (function) · `import { createRecordBook } from "@jgengine/core/gameplay"`
+
+## build — a serializable directed/undirected pair key that resists delimiter collisions
+
+- `createPairKeyCodec` (function) · `import { createPairKeyCodec } from "@jgengine/core/gameplay"`
+
+## cancel-scheduled-rule — remove a scheduled rule and its cursor entirely
+
+- `cancelRule` (function) · `import { cancelRule } from "@jgengine/core/gameplay"`
+
+## cancel-work — remove a job and compute its refund from reservation and progress
+
+- `cancelJob` (function) · `import { cancelJob } from "@jgengine/core/gameplay"`
+
+## compose-game-loop — fold composable systems into the game loop without a manual tick fan-out
+
+- `composeGameLoop` (function) · `import { composeGameLoop } from "@jgengine/core/gameplay"`
+
+## consumables — use/consume items with cooldowns and effects
+
+- `createItemUse` (function) · `import { createItemUse } from "@jgengine/core/gameplay"`
+
+## cosmetics — equip cosmetic skins and customizations by slot
+
+- `createCosmetics` (function) · `import { createCosmetics } from "@jgengine/core/gameplay"`
+
+## decay-meter — survival meters that drain/refill over game time (hunger, water, oxygen, stamina)
+
+- `createDecayMeterSet` (function) · `import { createDecayMeterSet } from "@jgengine/core/gameplay"`
+- `decayMeterMoodles` (function) · `import { decayMeterMoodles } from "@jgengine/core/gameplay"`
+- `decayMeterSnapshot` (function) · `import { decayMeterSnapshot } from "@jgengine/core/gameplay"`
+- `decayMeterState` (function) · `import { decayMeterState } from "@jgengine/core/gameplay"`
+- `decayMeters` (function) · `import { decayMeters } from "@jgengine/core/gameplay"`
+- `initDecayMeters` (function) · `import { initDecayMeters } from "@jgengine/core/gameplay"`
+- `refillMeter` (function) · `import { refillMeter } from "@jgengine/core/gameplay"`
+
+## declarative-predicate — serializable data-driven conditions with no callbacks in saved content
+
+- `evaluatePredicate` (function) · `import { evaluatePredicate } from "@jgengine/core/gameplay"`
+- `readPath` (function) · `import { readPath } from "@jgengine/core/gameplay"`
+
+## define-game — single public game-authoring path — compose systems, world, and loop in one definition
+
+- `defineGame` (function) · `import { defineGame } from "@jgengine/core/gameplay"`
+
+## detect — fire-once threshold/milestone/tier crossings when a value moves
+
+- `crossThresholds` (function) · `import { crossThresholds } from "@jgengine/core/gameplay"`
+
+## dialogue-bridge — open/close the talkable→DialogueBox flow with no per-game store or command glue
+
+- `createGameDialogue` (function) · `import { createGameDialogue } from "@jgengine/core/gameplay"`
+
+## durability — track item wear, breakage, and repair
+
+- `applyWear` (function) · `import { applyWear } from "@jgengine/core/gameplay"`
+
+## enqueue-work — reserve inputs and add a timed job, honoring capacity and validation policy
+
+- `enqueue` (function) · `import { enqueue } from "@jgengine/core/gameplay"`
+
+## event-bus — typed publish/subscribe bus for gameplay events
+
+- `createGameEvents` (function) · `import { createGameEvents } from "@jgengine/core/gameplay"`
+
+## event-feed — a rolling feed of recent gameplay events for a HUD ticker or killfeed
+
+- `createGameFeed` (function) · `import { createGameFeed } from "@jgengine/core/gameplay"`
+
+## game-save — save/load game state with a pluggable backend, autosave, slots, and migration
+
+- `createSaveStore` (function) · `import { createSaveStore } from "@jgengine/core/gameplay"`
+
+## game-system — declare a composable capability with its own schedule and lifecycle
+
+- `SystemDefinition` (interface) · `import { SystemDefinition } from "@jgengine/core/gameplay"`
+
+## item-generation — compose constraints, weighted pools, transforms, and provenance into a deterministic generated item
+
+- `generate` (function) · `import { generate } from "@jgengine/core/gameplay"`
+
+## item-identity — resolve which match/set bonuses an item qualifies for
+
+- `activeSetBonuses` (function) · `import { activeSetBonuses } from "@jgengine/core/gameplay"`
+- `applySetBonuses` (function) · `import { applySetBonuses } from "@jgengine/core/gameplay"`
+- `candidateViolatesForbid` (function) · `import { candidateViolatesForbid } from "@jgengine/core/gameplay"`
+- `captureProvenance` (function) · `import { captureProvenance } from "@jgengine/core/gameplay"`
+- `countSetMembers` (function) · `import { countSetMembers } from "@jgengine/core/gameplay"`
+- `identityOf` (function) · `import { identityOf } from "@jgengine/core/gameplay"`
+- `isIdentityValid` (function) · `import { isIdentityValid } from "@jgengine/core/gameplay"`
+- `matchesQuery` (function) · `import { matchesQuery } from "@jgengine/core/gameplay"`
+- `validateIdentity` (function) · `import { validateIdentity } from "@jgengine/core/gameplay"`
+
+## item-instance-registry — a runtime store for procedurally generated item instances
+
+- `createItemInstanceRegistry` (function) · `import { createItemInstanceRegistry } from "@jgengine/core/gameplay"`
+- `proceduralLootEntry` (function) · `import { proceduralLootEntry } from "@jgengine/core/gameplay"`
+
+## item-use-composition — compose pluggable, ordered item use-behaviors from serializable references
+
+- `createUseBehaviorRegistry` (function) · `import { createUseBehaviorRegistry } from "@jgengine/core/gameplay"`
+
+## lap-splits — per-lap durations from a cumulative split book
+
+- `lapDurations` (function) · `import { lapDurations } from "@jgengine/core/gameplay"`
+- `parDelta` (function) · `import { parDelta } from "@jgengine/core/gameplay"`
+- `splitSegments` (function) · `import { splitSegments } from "@jgengine/core/gameplay"`
+
+## lap-timer — wall-clock current/last/best lap timing with splits
+
+- `createLapTimer` (function) · `import { createLapTimer } from "@jgengine/core/gameplay"`
+
+## leaderboard — ranked score tracking across global, server, and per-profile scopes
+
+- `createLeaderboard` (function) · `import { createLeaderboard } from "@jgengine/core/gameplay"`
+
+## lifecycle — declarative start/restart run flow — the engine owns the command glue and phase sync, the game supplies pure state transitions
+
+- `LifecycleConfig` (interface) · `import { LifecycleConfig } from "@jgengine/core/gameplay"`
+
+## limb-health — per-body-part/region health tracked separately
+
+- `createMultiRegionHealth` (function) · `import { createMultiRegionHealth } from "@jgengine/core/gameplay"`
+
+## listing-book — player-driven marketplace listings with a house cut, expiry sweep, and seller collection box
+
+- `createListingBook` (function) · `import { createListingBook } from "@jgengine/core/gameplay"`
+
+## loadouts — save and swap named equipment loadouts
+
+- `createLoadouts` (function) · `import { createLoadouts } from "@jgengine/core/gameplay"`
+
+## local-save — persist a game to on-device localStorage (offline)
+
+- `localSaveBackend` (function) · `import { localSaveBackend } from "@jgengine/core/gameplay"`
+
+## loot-filter — filter and highlight drops by rarity/name rules
+
+- `evaluateLootFilter` (function) · `import { evaluateLootFilter } from "@jgengine/core/gameplay"`
+
+## loot-pipeline — compose ordered loot pools with fallbacks, roll modifiers, and provenance
+
+- `createLootPipeline` (function) · `import { createLootPipeline } from "@jgengine/core/gameplay"`
+- `defineLootPipeline` (function) · `import { defineLootPipeline } from "@jgengine/core/gameplay"`
+
+## loot-table — register loot tables and roll weighted randomized drops
+
+- `createLootRegistry` (function) · `import { createLootRegistry } from "@jgengine/core/gameplay"`
+- `lootTable` (function) · `import { lootTable } from "@jgengine/core/gameplay"`
+
+## modular-item — attach parts into item mount slots to compute combined stats
+
+- `slotAccepts` (function) · `import { slotAccepts } from "@jgengine/core/gameplay"`
+
+## move — a keyed value toward a target by a bounded step
+
+- `towardValue` (function) · `import { towardValue } from "@jgengine/core/gameplay"`
+
+## name-generator — generate procedural names from templates and word banks
+
+- `createNameGenerator` (function) · `import { createNameGenerator } from "@jgengine/core/gameplay"`
+
+## notice-feed — serializable tone-tagged notice/event feed bounded by count and age (toasts, life events, killfeed)
+
+- `appendFeed` (function) · `import { appendFeed } from "@jgengine/core/gameplay"`
+- `pruneFeed` (function) · `import { pruneFeed } from "@jgengine/core/gameplay"`
+
+## objectives — check progress of a threshold objective against a live metric
+
+- `evaluateObjective` (function) · `import { evaluateObjective } from "@jgengine/core/gameplay"`
+
+## param-layers — register parameter layers by stable id and resolve serialized selections
+
+- `createLayerRegistry` (function) · `import { createLayerRegistry } from "@jgengine/core/gameplay"`
+- `diffParams` (function) · `import { diffParams } from "@jgengine/core/gameplay"`
+- `orderLayers` (function) · `import { orderLayers } from "@jgengine/core/gameplay"`
+- `resolveParams` (function) · `import { resolveParams } from "@jgengine/core/gameplay"`
+- `resolveSelection` (function) · `import { resolveSelection } from "@jgengine/core/gameplay"`
+- `validateLayers` (function) · `import { validateLayers } from "@jgengine/core/gameplay"`
+
+## pause-scheduled-rule — stop a scheduled rule from firing while retaining its cursor
+
+- `pauseRule` (function) · `import { pauseRule } from "@jgengine/core/gameplay"`
+
+## pause-work — pause a queued or active job in place, retaining its progress
+
+- `pauseJob` (function) · `import { pauseJob } from "@jgengine/core/gameplay"`
+
+## ping-wheel — contextual ping/marker communication between teammates
+
+- `createPingSystem` (function) · `import { createPingSystem } from "@jgengine/core/gameplay"`
+
+## policy-annotate — tag a scheduled transaction's provenance without changing its value
+
+- `annotate` (function) · `import { annotate } from "@jgengine/core/gameplay"`
+
+## policy-cap — cap a scheduled transaction amount by context
+
+- `capAmount` (function) · `import { capAmount } from "@jgengine/core/gameplay"`
+
+## policy-curve — scale a transaction by a curve over context
+
+- `curveScale` (function) · `import { curveScale } from "@jgengine/core/gameplay"`
+
+## policy-redirect — redirect a scheduled transaction's source or recipient
+
+- `redirect` (function) · `import { redirect } from "@jgengine/core/gameplay"`
+
+## policy-reject — reject scheduled transactions by predicate
+
+- `rejectWhen` (function) · `import { rejectWhen } from "@jgengine/core/gameplay"`
+
+## policy-tax — split off a fraction of a transaction as tax or transfer
+
+- `taxFraction` (function) · `import { taxFraction } from "@jgengine/core/gameplay"`
+
+## policy-threshold — scale a transaction by a context threshold band
+
+- `thresholdScale` (function) · `import { thresholdScale } from "@jgengine/core/gameplay"`
+
+## production-building — a factory building converting inputs to outputs over time
+
+- `createProductionState` (function) · `import { createProductionState } from "@jgengine/core/gameplay"`
+
+## quest-log — track accepted quests and their per-objective progress
+
+- `createQuestJournal` (function) · `import { createQuestJournal } from "@jgengine/core/gameplay"`
+
+## race-placements — look up one racer's place + win/lose within a finish order
+
+- `placementOf` (function) · `import { placementOf } from "@jgengine/core/gameplay"`
+- `racePlacements` (function) · `import { racePlacements } from "@jgengine/core/gameplay"`
+
+## race-session — pure idle→countdown→racing→finished clock every racer wraps around its state
+
+- `idleRaceSession` (function) · `import { idleRaceSession } from "@jgengine/core/gameplay"`
+
+## race-track — a checkpoint race with laps, standings, splits, and win conditions
+
+- `createRaceState` (function) · `import { createRaceState } from "@jgengine/core/gameplay"`
+
+## resolve — the current tier/band label for a keyed or scalar value
+
+- `tierAt` (function) · `import { tierAt } from "@jgengine/core/gameplay"`
+
+## resource-ledger — schedule recurring resource transactions with policy transforms
+
+- `createResourceLedger` (function) · `import { createResourceLedger } from "@jgengine/core/gameplay"`
+
+## resume-scheduled-rule — resume a paused scheduled rule, deferring missed cycles to its catch-up policy
+
+- `resumeRule` (function) · `import { resumeRule } from "@jgengine/core/gameplay"`
+
+## resume-work — resume a paused job back into the queue's slot competition
+
+- `resumeJob` (function) · `import { resumeJob } from "@jgengine/core/gameplay"`
+
+## retained-vfx — create/update/stop long-lived dynamic visual effects (beam, tether, zone, target line) by stable id
+
+- `createVfxInstanceStore` (function) · `import { createVfxInstanceStore } from "@jgengine/core/gameplay"`
+
+## rule-selection — register rules and bridge a selection to its contributed parameter layers
+
+- `createRuleRegistry` (function) · `import { createRuleRegistry } from "@jgengine/core/gameplay"`
+- `rerollRules` (function) · `import { rerollRules } from "@jgengine/core/gameplay"`
+- `selectRules` (function) · `import { selectRules } from "@jgengine/core/gameplay"`
+
+## run-modifiers — a roguelike run built from stacking drafted modifier picks
+
+- `createRunDraft` (function) · `import { createRunDraft } from "@jgengine/core/gameplay"`
+
+## set — a bounded keyed value in a caller-owned serializable record
+
+- `setValue` (function) · `import { setValue } from "@jgengine/core/gameplay"`
+
+## social-emotes — emotes and social interactions between nearby players
+
+- `createSocial` (function) · `import { createSocial } from "@jgengine/core/gameplay"`
+
+## spawn-points — register spawn locations and pick where entities respawn
+
+- `createSpawnPoints` (function) · `import { createSpawnPoints } from "@jgengine/core/gameplay"`
+
+## stat-graph — derive game-defined stats from named inputs with provenance and preview
+
+- `createStatGraph` (function) · `import { createStatGraph } from "@jgengine/core/gameplay"`
+
+## stat-graph-bridge — feed an existing StatModifierSet into a stat-graph source
+
+- `statModifierContributions` (function) · `import { statModifierContributions } from "@jgengine/core/gameplay"`
+
+## system-schedule — compile fixed/frame/interval system ticks into deterministic ordered stages
+
+- `compileSystemSchedule` (function) · `import { compileSystemSchedule } from "@jgengine/core/gameplay"`
+
+## tick-work — advance jobs over time, completing work and emitting typed lifecycle events
+
+- `tick` (function) · `import { tick } from "@jgengine/core/gameplay"`
+
+## toast-feed — queue of transient self-expiring on-screen messages (toasts, announcer, kill-feed)
+
+- `appendToast` (function) · `import { appendToast } from "@jgengine/core/gameplay"`
+- `createToastQueue` (function) · `import { createToastQueue } from "@jgengine/core/gameplay"`
+
+## touch-controls — default on-screen button silhouette for a touch action
+
+- `touchButtonShape` (function) · `import { touchButtonShape } from "@jgengine/core/gameplay"`
+
+## triggered-rules — event-conditioned effects with declarative predicates, lifetimes, and stacking
+
+- `createTriggeredRuleEngine` (function) · `import { createTriggeredRuleEngine } from "@jgengine/core/gameplay"`
+- `getRuleEffect` (function) · `import { getRuleEffect } from "@jgengine/core/gameplay"`
+- `listRuleEffects` (function) · `import { listRuleEffects } from "@jgengine/core/gameplay"`
+- `registerRuleEffect` (function) · `import { registerRuleEffect } from "@jgengine/core/gameplay"`
+
+## unit-training — compose a timed work queue that trains catalog units into spawn orders
+
+- `unitTrainingConfig` (function) · `import { unitTrainingConfig } from "@jgengine/core/gameplay"`
+
+## unlockables — gate content behind unlock conditions the player earns
+
+- `createUnlockCatalog` (function) · `import { createUnlockCatalog } from "@jgengine/core/gameplay"`
+
+## wallet — hold currency balances with charge and affordability checks
+
+- `createEmptyWallet` (function) · `import { createEmptyWallet } from "@jgengine/core/gameplay"`
+
+## weapon-stats — resolve per-weapon stat values for combat math
+
+- `createWeaponStats` (function) · `import { createWeaponStats } from "@jgengine/core/gameplay"`
+
+## weighted-pick — pick one item from a set with an injected random source
+
+- `pickUniform` (function) · `import { pickUniform } from "@jgengine/core/gameplay"`
+
+## work-active-jobs — list jobs currently progressing in a work queue
+
+- `activeJobs` (function) · `import { activeJobs } from "@jgengine/core/gameplay"`
+
+## work-job-by-id — look up a queued job by id
+
+- `jobById` (function) · `import { jobById } from "@jgengine/core/gameplay"`
+
+## work-job-progress — compute a job's fractional progress
+
+- `jobProgress` (function) · `import { jobProgress } from "@jgengine/core/gameplay"`
+
+## work-order-fifo — order queued jobs by enqueue sequence
+
+- `fifoOrdering` (function) · `import { fifoOrdering } from "@jgengine/core/gameplay"`
+
+## work-order-priority — order queued jobs by priority, then FIFO within equal priority
+
+- `priorityOrdering` (function) · `import { priorityOrdering } from "@jgengine/core/gameplay"`
+
+## work-queue — a serializable timed job queue with reservation, cancellation, completion, and output routing
+
+- `createWorkQueue` (function) · `import { createWorkQueue } from "@jgengine/core/gameplay"`
+
+## work-queue-size — count non-terminal jobs in a work queue
+
+- `queueSize` (function) · `import { queueSize } from "@jgengine/core/gameplay"`
+
+## work-queued-jobs — list jobs waiting for a slot, in selection order
+
+- `queuedJobs` (function) · `import { queuedJobs } from "@jgengine/core/gameplay"`

package/skills/jgengine-gameplay/reference-systems.md

@@ -0,0 +1,60 @@
+# Composable systems (`defineSystem`)
+
+Single public authoring path: `defineGame({ systems, loop?, … })` from `@jgengine/shell/defineGame` (or core). Systems are meaningful capabilities — not micro-ticks.
+
+## API
+
+```ts
+import { defineSystem } from "@jgengine/core/game/defineSystem";
+import { compileSystemSchedule, DEFAULT_FIXED_STAGES, DEFAULT_FRAME_STAGES } from "@jgengine/core/game/systemSchedule";
+import { composeGameLoop, installSystems } from "@jgengine/core/game/systemRuntime";
+
+export const combat = defineSystem({
+  id: "combat",
+  feature: "quest", // optional — enables ctx.game.quest without features: { quest: true }
+  dependsOn: ["movement"], // optional — must also be in systems[]
+  tick: {
+    type: "fixed", // | "frame" | "interval" | "manual"
+    rate: 60,      // fixed only (Hz); default 60
+    every: 1,      // interval only (game-seconds)
+    stage: "combat",
+    after: "movement", // optional local order within the stage
+    before: "cleanup",
+  },
+  create(ctx) {},
+  start(ctx) {},
+  update(ctx, dt) {},
+  events: {
+    "entity.died"(ctx, event) {},
+  },
+  save: { key: "combat", snapshot: () => state, hydrate: (data) => { state = data; } },
+  replicate: (ctx) => ({ key: "combat-pub", snapshot: () => pub, hydrate: (d) => { pub = d; } }),
+  reset(ctx) {},
+  dispose(ctx) {},
+});
+```
+
+`defineGame` OR-merges `feature` flags, then `composeGameLoop(systems, loop)` so systems install on `onInit` and tick before residual `loop.onTick`. Classic games migrate by moving fan-out out of `onTick` into systems while keeping boot in `loop`.
+
+## Timing channels
+
+| `tick.type` | When it runs |
+|-------------|--------------|
+| `fixed` | Accumulator at `rate` Hz (default 60); multi-subscribe OK |
+| `frame` | Once per `onTick` with the frame's game `dt` |
+| `interval` | Every `every` game-seconds (own accumulator per system) |
+| `manual` | Installed only; call `systemsOf(ctx)?.runManual(ctx, id)` |
+| *(omit)* | Event-only — handlers in `events` |
+
+Multiple systems may share a channel. Order is stage tables + optional `before`/`after` — **never import order**. `compileSystemSchedule` validates unique ids, `dependsOn`, and cycles.
+
+Default stages: fixed `input → movement → combat → ai → activities → cleanup`; frame includes those plus `animation → camera → effects`.
+
+## Cartridge path
+
+Cartridge remains a convenience wrapper. Express the same shape as ordinary systems (`runFlow`, wave director, combat) under `defineGame({ systems })` when you outgrow the cartridge schema — one authoring model, no rewrite cliff.
+
+## Ownership
+
+- **Save / replicate** — system modules register via `ctx.game.registerSave` / `registerReplicate` at install.
+- **Reset / dispose** — `loop.onReset` / `loop.onDispose` (composed) run system hooks.

package/skills/jgengine-world/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: jgengine-world
+description: Build spatial runtime, movement, interaction, AI, and environments.
+---
+
+# JGengine world runtime
+
+## Ownership
+
+This skill owns runtime spatial behavior: authored-scene consumption, environments, movement, input mapping, interaction, AI, navigation, physics, visibility, time, and spatial audio. Scene creation and placement stay in `jgengine-editor`; presentation stays in `jgengine-ui`.
+
+Search [capabilities.md](capabilities.md) by intent before designing a primitive. Use [api.md](api.md) for exact exports and [reference.md](reference.md) for environment, camera, navigation, physics, audio, and authored-scene recipes.
+
+## Canonical workflows
+
+### Authored world
+
+1. Load the scene document through the shared authored-scene feature.
+2. Render objects, paths, terrain, foliage, and markers generically.
+3. Query the same ids/layers for spawns, routes, plots, and interaction.
+4. Keep derived caches rebuildable; the document remains authoritative.
+
+### Movement and interaction
+
+Choose input intent, controller/motor, collision/navigation, and camera as separate seams. Commands express game intent; world systems resolve motion. Interaction targets come from bounded spatial/sensor queries, not full-world scans.
+
+### AI and navigation
+
+Compose perception, selection, planning/behavior, movement, and lifecycle independently. Inject randomness and scheduling. Use spatial indexes, interest tiers, or bounded candidate sets for scale.
+
+## Traps
+
+- Do not put UI layout, touch chrome, combat resolution, or asset acquisition here.
+- Do not duplicate editor coordinates in runtime state.
+- Public APIs accept semantic policies and caller data, not renderer mechanics or internal tuning rolls.
+- Generated environments still need deterministic data assertions; authored environments need scene-document assertions.
+- Audio files and licensing belong to `jgengine-assets`; spatial playback policy belongs here.
+