@jgengine/core 0.10.0 → 0.12.0

package/skills/jgengine-gameplay/capabilities.md

@@ -0,0 +1,454 @@
+<!-- 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"`
+
+## auction-book — timed bid auctions with escrowed bids, buyout, anti-snipe close extension, and collection-box settlement
+
+- `createAuctionBook` (function) · `import { createAuctionBook } 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"`
+
+## carry-encumbrance — carried mass vs capacity into movement penalty tiers and a speed multiplier
+
+- `resolveEncumbrance` (function) · `import { resolveEncumbrance } from "@jgengine/core/inventory/encumbrance"`
+
+## carry-load — sum carried mass from item stacks via an injected mass resolver
+
+- `totalLoad` (function) · `import { totalLoad } from "@jgengine/core/inventory/encumbrance"`
+
+## 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"`
+
+## creature-breeding — deterministic stat inheritance, mutation, and lineage genetics for taming games
+
+- `breedOffspring` (function) · `import { breedOffspring } from "@jgengine/core/game/breeding"`
+
+## 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-system — composable game behavior — pure data + hooks the engine schedules; pass via `defineGame({ systems })`
+
+- `defineSystem` (function) · `import { defineSystem } 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"`
+
+## encumbrance-move-curve — progressive move-speed multiplier from a carry-load fraction
+
+- `encumbranceMoveMultiplier` (function) · `import { encumbranceMoveMultiplier } from "@jgengine/core/inventory/encumbrance"`
+
+## 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"`
+
+## imprint-bonus — apply imprint stat and handler bonuses at an imprint fraction
+
+- `applyImprintBonus` (function) · `import { applyImprintBonus } from "@jgengine/core/game/breeding"`
+
+## imprint-increment — per-care-request imprint gain across a maturation schedule
+
+- `imprintIncrementPerRequest` (function) · `import { imprintIncrementPerRequest } from "@jgengine/core/game/breeding"`
+
+## incubation-tick — advance egg incubation health inside/outside its temperature range
+
+- `tickIncubation` (function) · `import { tickIncubation } from "@jgengine/core/game/breeding"`
+
+## incubation-viability — test whether an egg incubation still has health to hatch
+
+- `incubationViable` (function) · `import { incubationViable } from "@jgengine/core/game/breeding"`
+
+## 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"`
+
+## leveling-track — grant XP, resolve level-ups against a curve, and write level+xp stats back through a stat adapter
+
+- `leveling` (function) · `import { leveling } 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"`
+
+## maturation-stage — resolve the baby/juvenile/adolescent/adult stage from elapsed maturation
+
+- `maturationStage` (function) · `import { maturationStage } from "@jgengine/core/game/breeding"`
+
+## 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"`
+
+## price-history — rolling per-item sale records aggregated into market price stats
+
+- `createPriceHistory` (function) · `import { createPriceHistory } from "@jgengine/core/gameplay"`
+
+## production-building — a factory building converting inputs to outputs over time
+
+- `createProductionState` (function) · `import { createProductionState } from "@jgengine/core/gameplay"`
+
+## progression-curve — evaluate a level/rank curve (const, linear, power, geometric, steps, piecewise) at a point
+
+- `evalCurve` (function) · `import { evalCurve } 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"`
+
+## seeded-random — injected deterministic randomness for game logic — never `Math.random` in a simulation
+
+- `seededRng` (function) · `import { seededRng } 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"`
+
+## tribe-group — shared-ownership group (tribe/guild/clan) with ranked permissions, group vs personal assets, alliances, and a bounded event log
+
+- `createTribe` (function) · `import { createTribe } from "@jgengine/core/game/tribe"`
+
+## tribe-registry — registry of tribes with mutual alliances and cross-tribe relation lookup
+
+- `createTribeRegistry` (function) · `import { createTribeRegistry } from "@jgengine/core/game/tribe"`
+
+## 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"`
+
+## typed-keyed-store — a cast-free typed handle onto a per-owner keyed family of reactive game-store slots, replayable and host-authoritative
+
+- `defineKeyedStore` (function) · `import { defineKeyedStore } from "@jgengine/core/store/defineKeyedStore"`
+
+## typed-store — a cast-free typed handle onto one reactive game-store slot, replayable and host-authoritative
+
+- `defineStore` (function) · `import { defineStore } from "@jgengine/core/store/defineStore"`
+
+## unit-training — compose a timed work queue that trains catalog units into spawn orders
+
+- `unitTrainingConfig` (function) · `import { unitTrainingConfig } from "@jgengine/core/gameplay"`
+
+## unlock-points — spendable point pool earned per level and spent to unlock nodes, with refund and respec
+
+- `createUnlockPoints` (function) · `import { createUnlockPoints } from "@jgengine/core/economy/unlockPoints"`
+
+## 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,56 @@
+# Composable systems (`defineSystem`)
+
+Single public authoring path: `defineGame({ systems, loop?, … })` from `@jgengine/shell/defineGame`. 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`.
+
+## 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,51 @@
+---
+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.
+
+For a *connected* walkthrough that wires several primitives into a running loop, read the goal-oriented recipes under [recipes/](recipes/) — organized by composition seam (what connects to what), never by genre. Start there before reading a game's source to learn how pieces fit; a hybrid game is just a different composition of the same primitives.
+
+- [recipes/commanding-entities.md](recipes/commanding-entities.md) — select → order → tick → resolve: direct command over a group of entities (the command loop behind squad control, base-defense, herding, autobattle, or a mutating game's real-time phase).
+
+## Canonical workflows
+
+### Declare the place
+
+A world is the place you play in: substrate + laws, via `world()` from `@jgengine/core/world/place` — `{ id, ground: { mode: flat|round|voxel|board, size, surface?, generator? }, physics? }`. Thin is complete: flat with `Infinity` axes for 3D, `board` for 2D, or omit `world` for pure UI/rules games. Never put seed, sky, or vegetation in a world definition — seeds derive from world id + save/run (`seedForPlace`); sky look and foliage scatter are editor-authored scene content, with the engine default sky when the document has none. `ground.surface` carries matter/feel laws (metal vs slime vs felt) that the same rule systems read — swap the surface, not the rules. See [reference.md](reference.md) for the full shape; `environment()` is the legacy consumption path for editor/preset-written scene data, never the starter.
+
+### 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.
+
+### Fallback-seam diagnostics
+
+Render seams fall back to placeholders when content is unauthored: default green ground (no environment), primitive capsule/box actors (no `entityModels`/`objectModels` mapping), stylized proxy foliage (no scatter `resolveItem`). These placeholders are sometimes intended, so runtime never changes — but a dev-only, opt-in probe (`@jgengine/core/devtools/fallbackSeams`) tells "unauthored/misconfigured" apart from "intended". The shell arms it via `armFallbackSeams(devtoolsEnabled)`; each seam reports at its choice site (`reportFallbackSeam`), and counts surface through the devtools `fallbacks` probe. Disarmed (production) it is a pure, allocation-free no-op.
+
+## Traps
+
+- Do not put seed, sky presets, or vegetation/scatter fields in a world definition — `world()` rejects them; dressing belongs to the editor's scene document.
+- 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.
+