@jgengine/core 0.7.0 → 0.8.0

package/llms.txt

@@ -0,0 +1,4102 @@
+# @jgengine/core
+> Genre-agnostic TypeScript game engine SDK: game runtime, state store, entity scene, combat, movement, inventory, economy, quests, multiplayer primitives.
+
+Version: 0.8.0
+License: AGPL-3.0-only
+Repository: https://github.com/Noisemaker111/jgengine
+Docs: https://jgengine.com
+Imports use deep paths: `@jgengine/core/<path>`.
+
+## Exported surface
+
+### @jgengine/core/ai/crowd
+
+- computeFlowField (function): function computeFlowField(grid: NavGrid, goals: readonly NavPoint[], options: FlowFieldOptions = {}): FlowField
+- createCrowdField (function): function createCrowdField(grid: NavGrid): CrowdField
+- selectPoi (function): function selectPoi(pois: readonly Poi[], from: NavPoint, options: SelectPoiOptions): Poi | null
+- FlowFieldOptions (interface): interface FlowFieldOptions
+- FlowField (interface): interface FlowField
+- CrowdField (interface): interface CrowdField
+- Poi (interface): interface Poi
+- SelectPoiOptions (interface): interface SelectPoiOptions
+
+### @jgengine/core/ai/jobBoard
+
+- createJobBoard (function): function createJobBoard(): JobBoard
+- JobPhase (type): type JobPhase = "idle" | "travelling" | "working" | "done"
+- JobDef (interface): interface JobDef
+- Job (interface): interface Job
+- JobTickContext (interface): interface JobTickContext
+- JobReport (interface): interface JobReport
+- WorkerState (interface): interface WorkerState
+- JobBoard (interface): interface JobBoard
+
+### @jgengine/core/ai/spawnDirector
+
+- createSpawnDirectorState (function): function createSpawnDirectorState(config: SpawnDirectorConfig): SpawnDirectorState
+- raiseAlert (function): function raiseAlert(state: SpawnDirectorState, amount: number): SpawnDirectorState
+- advanceWave (function): function advanceWave(config: SpawnDirectorConfig, state: SpawnDirectorState): SpawnDirectorState
+- advanceSpawnDirector (function): function advanceSpawnDirector(config: SpawnDirectorConfig, state: SpawnDirectorState, dt: number, ctx: DirectorContext): DirectorStep
+- pickSpawnPoint (function): function pickSpawnPoint(points: readonly NavPoint[], players: readonly NavPoint[], options: { roll: number; bias?: number }): NavPoint | null
+- SpawnEntry (interface): interface SpawnEntry
+- WaveManifest (interface): interface WaveManifest
+- SpawnDirectorConfig (interface): interface SpawnDirectorConfig
+- SpawnDirectorState (interface): interface SpawnDirectorState
+- DirectorContext (interface): interface DirectorContext
+- SpawnRequest (interface): interface SpawnRequest
+- DirectorStep (interface): interface DirectorStep
+
+### @jgengine/core/ai/threat
+
+- createThreatTable (function): function createThreatTable(config: ThreatTableConfig = {}): ThreatTable
+- ThreatTableConfig (interface): interface ThreatTableConfig
+- ThreatEntry (interface): interface ThreatEntry
+- HighestThreatOptions (interface): interface HighestThreatOptions
+- ThreatTable (interface): interface ThreatTable
+
+### @jgengine/core/anim/easing
+
+- lerp (function): function lerp(from: number, to: number, t: number): number
+- clamp01 (function): function clamp01(t: number): number
+- smoothstep (function): function smoothstep(t: number): number
+- easeInQuad (function): function easeInQuad(t: number): number
+- easeOutQuad (function): function easeOutQuad(t: number): number
+- easeInOutQuad (function): function easeInOutQuad(t: number): number
+- easeInCubic (function): function easeInCubic(t: number): number
+- easeOutCubic (function): function easeOutCubic(t: number): number
+- easeInOutCubic (function): function easeInOutCubic(t: number): number
+- easeOutBack (function): function easeOutBack(t: number): number
+- easeOutElastic (function): function easeOutElastic(t: number): number
+- tween (function): function tween(from: number, to: number, t: number, easing: Easing = smoothstep): number
+- timedProgress (function): function timedProgress(startedAt: number, now: number, durationMs: number): number
+- Easing (type): type Easing = (t: number) => number
+
+### @jgengine/core/assets/spriteSheet
+
+- sanitizeAssetName (function): function sanitizeAssetName(value: string): string
+- normalizeSpriteSheetGridConfig (function): function normalizeSpriteSheetGridConfig(imageWidth: number, imageHeight: number, config: SpriteSheetGridConfig): Required<SpriteSheetGridConfig>
+- buildSpriteSheetGridBoxes (function): function buildSpriteSheetGridBoxes({ imageWidth, imageHeight, config, namePrefix, names, }: { imageWidth: number; imageHeight: number; config: SpriteSheetGridConfig; namePrefix: string; names?: readonly string[]; }): SpriteSheetSliceBox[]
+- buildSpriteSheetManifest (function): function buildSpriteSheetManifest({ sourceName, imageWidth, imageHeight, config, slices, }: { sourceName: string; imageWidth: number; imageHeight: number; config: SpriteSheetGridConfig; slices: SpriteSheetSliceBox[]; }): SpriteSheetManifest
+- SpriteSheetGridConfig (interface): interface SpriteSheetGridConfig
+- SpriteSheetSliceBox (interface): interface SpriteSheetSliceBox
+- SpriteSheetManifest (interface): interface SpriteSheetManifest
+
+### @jgengine/core/audio/audioFalloff
+
+- computeFalloffGain (function): function computeFalloffGain(distance: number, config: AudioFalloffConfig = {}): number
+- resolveEmitterGain (function): function resolveEmitterGain(distance: number, sound: Pick<SoundDef, "gain" | "positional" | "falloff">, busGain: number): number
+- distance3 (function): function distance3(a: { x: number; y: number; z: number }, b: { x: number; y: number; z: number }): number
+- AudioBusId (type): type AudioBusId = string
+- FalloffCurve (type): type FalloffCurve = "linear" | "inverse" | "none"
+- AudioFalloffConfig (interface): interface AudioFalloffConfig
+- AudioBusDef (interface): interface AudioBusDef
+- SoundDef (interface): interface SoundDef
+
+### @jgengine/core/behaviour/behaviour
+
+- createBehaviourWorld (function): function createBehaviourWorld(): BehaviourWorld
+- JGEngineRegister (interface): interface JGEngineRegister — Unity-style behaviour lifecycle over a headless id-keyed node tree, ported from vladkrutenyuk/three-start (MIT) and adapted to run without three.js: nodes are plain string ids (use entity instance ids to pair with `entityStore`), and the shell binds render-side hooks separately.
+- RegisterField (type): type RegisterField<TKey extends string, TFallback = unknown> = TKey extends keyof JGEngineRegister ? JGEngineRegister[TKey] : TFallback
+- BehaviourModules (type): type BehaviourModules = RegisterField<"modules", Record<string, BehaviourModule>> — Resolves to the augmented module map when `JGEngineRegister` declares one.
+- Behaviour (class): class Behaviour — Subclass and override the lifecycle hooks. A behaviour only joins the per-frame update dispatch if it actually overrides `onUpdate` (prototype-identity check at each activation), so hook-only behaviours cost nothing per frame.
+- BehaviourModule (class): class BehaviourModule — A world-lifetime service with typed sibling access via `this.modules`. Modules awake and start before any behaviour during `world.start()`, subscribe to update dispatch first (their `onUpdate` fires before every behaviour's), and have no disable/destroy — they live as long as the world.
+- BehaviourWorld (interface): interface BehaviourWorld
+
+### @jgengine/core/board/laneBoard
+
+- createLaneBoardState (function): function createLaneBoardState<C>(config: LaneBoardConfig<C>): LaneBoardState<C>
+- placeCard (function): function placeCard<C>(state: LaneBoardState<C>, config: LaneBoardConfig<C>, lane: number, side: Side, card: C): LaneResult<C>
+- removeCard (function): function removeCard<C>(state: LaneBoardState<C>, lane: number, side: Side, predicate: (card: C, index: number) => boolean): LaneResult<C>
+- laneAggregate (function): function laneAggregate<C>(state: LaneBoardState<C>, config: LaneBoardConfig<C>, lane: number, side: Side): LaneAggregate
+- laneOutcome (function): function laneOutcome<C>(state: LaneBoardState<C>, config: LaneBoardConfig<C>, lane: number): LaneOutcome
+- boardTotals (function): function boardTotals<C>(state: LaneBoardState<C>, config: LaneBoardConfig<C>): Readonly<Record<Side, number>>
+- lanesWon (function): function lanesWon<C>(state: LaneBoardState<C>, config: LaneBoardConfig<C>): Readonly<Record<Side, number>>
+- createLaneBoard (function): function createLaneBoard<C>(config: LaneBoardConfig<C>): LaneBoard<C>
+- Side (type): type Side = string
+- LaneRuleInput (interface): interface LaneRuleInput<C>
+- LaneRule (interface): interface LaneRule<C>
+- LaneBoardConfig (interface): interface LaneBoardConfig<C>
+- LaneCells (interface): interface LaneCells<C>
+- LaneBoardState (interface): interface LaneBoardState<C>
+- LaneAggregate (interface): interface LaneAggregate
+- LaneOutcome (interface): interface LaneOutcome
+- LaneRejection (type): type LaneRejection = "invalid-lane" | "invalid-side"
+- LanePlaceResult (interface): interface LanePlaceResult<C>
+- LanePlaceRejected (interface): interface LanePlaceRejected
+- LaneResult (type): type LaneResult<C> = LanePlaceResult<C> | LanePlaceRejected
+- LaneBoard (interface): interface LaneBoard<C>
+
+### @jgengine/core/board/timelineBoard
+
+- createTimelineBoardState (function): function createTimelineBoardState(slots: readonly TimelineSlotConfig[]): TimelineBoardState
+- tickTimeline (function): function tickTimeline(state: TimelineBoardState, dtMs: number): TimelineTickResult
+- setSlotEnabled (function): function setSlotEnabled(state: TimelineBoardState, slotId: string, enabled: boolean): TimelineBoardState
+- resetSlot (function): function resetSlot(state: TimelineBoardState, slotId: string, remainingMs?: number): TimelineBoardState
+- createTimelineBoard (function): function createTimelineBoard(slots: readonly TimelineSlotConfig[]): TimelineBoard
+- TimelineSlotConfig (interface): interface TimelineSlotConfig
+- TimelineSlot (interface): interface TimelineSlot
+- TimelineBoardState (interface): interface TimelineBoardState
+- TimelineFire (interface): interface TimelineFire
+- TimelineTickResult (interface): interface TimelineTickResult
+- TimelineBoard (interface): interface TimelineBoard
+
+### @jgengine/core/cards/cardPile
+
+- pileRng (function): function pileRng(seed: string | number): () => number
+- shuffleWithRng (function): function shuffleWithRng<T>(values: readonly T[], rng: () => number): T[]
+- createCardPileState (function): function createCardPileState(config: CardPileConfig, initial?: Partial<Record<ZoneName, readonly string[]>>): CardPileState
+- zoneOf (function): function zoneOf(state: CardPileState, cardId: string): ZoneName | null
+- countIn (function): function countIn(state: CardPileState, zone: ZoneName): number
+- peek (function): function peek(state: CardPileState, zone: ZoneName, n = 1): readonly string[]
+- shuffleZone (function): function shuffleZone(state: CardPileState, zone: ZoneName, seed: string | number): CardPileState
+- moveCards (function): function moveCards(state: CardPileState, ids: readonly string[], from: ZoneName, to: ZoneName, position: "top" | "bottom" = "top"): PileResult
+- draw (function): function draw(state: CardPileState, n: number, options: { from: ZoneName; to: ZoneName; handLimit?: number; reshuffleFrom?: ZoneName; seed?: string | number; }): DrawResult
+- createCardPile (function): function createCardPile(config: CardPileConfig, initial?: Partial<Record<ZoneName, readonly string[]>>): CardPile
+- ZoneName (type): type ZoneName = string
+- CardPileConfig (interface): interface CardPileConfig
+- CardPileState (interface): interface CardPileState
+- DrawResult (interface): interface DrawResult
+- PileRejection (type): type PileRejection = | "unknown-zone" | "card-not-in-zone" | "hand-limit" | "empty-source"
+- PileMoveResult (interface): interface PileMoveResult
+- PileMoveRejected (interface): interface PileMoveRejected
+- PileResult (type): type PileResult = PileMoveResult | PileMoveRejected
+- CardPile (interface): interface CardPile
+
+### @jgengine/core/cards/modifierPipeline
+
+- runPipeline (function): function runPipeline<V>(base: V, modifiers: readonly Modifier<V>[], equals: (a: V, b: V) => boolean = Object.is): PipelineResult<V>
+- createModifierPipeline (function): function createModifierPipeline<V>(initial: readonly Modifier<V>[] = [], equals: (a: V, b: V) => boolean = Object.is): ModifierPipeline<V>
+- Modifier (interface): interface Modifier<V>
+- PipelineContext (interface): interface PipelineContext<V>
+- TraceStep (interface): interface TraceStep<V>
+- PipelineResult (interface): interface PipelineResult<V>
+- ModifierPipeline (interface): interface ModifierPipeline<V>
+
+### @jgengine/core/combat/abilityKit
+
+- createAbilityKit (function): function createAbilityKit(configs: readonly AbilitySlotConfig[]): AbilityKit
+- AbilityCastType (type): type AbilityCastType = "instant" | "projectile" | "channel" | "targeted"
+- AbilitySlotState (type): type AbilitySlotState = "ready" | "cooldown" | "no-resource" | "just-cast"
+- AbilitySlotConfig (interface): interface AbilitySlotConfig
+- AbilitySlotSnapshot (interface): interface AbilitySlotSnapshot
+- AbilityCastReason (type): type AbilityCastReason = "unknown-slot" | "cooldown" | "no-resource"
+- AbilitySlotRetune (interface): interface AbilitySlotRetune
+- AbilityCastResult (type): type AbilityCastResult = | { ok: true; slot: AbilitySlotSnapshot } | { ok: false; reason: AbilityCastReason; slot: AbilitySlotSnapshot | null }
+- AbilityKit (interface): interface AbilityKit
+
+### @jgengine/core/combat/animationState
+
+- clipDurationMs (function): function clipDurationMs(clip: AnimationClip): number
+- frameAtMs (function): function frameAtMs(clip: AnimationClip, elapsedMs: number): number
+- phasesAtFrame (function): function phasesAtFrame(clip: AnimationClip, frame: number): FramePhase[]
+- activeRangeAtFrame (function): function activeRangeAtFrame(clip: AnimationClip, frame: number): FrameRange | null
+- createAnimationState (function): function createAnimationState(config: AnimationStateConfig): AnimationState
+- FramePhase (type): type FramePhase = "windup" | "active" | "recovery" | "cancel"
+- FrameRange (interface): interface FrameRange
+- AnimationClip (interface): interface AnimationClip
+- AnimationSnapshot (interface): interface AnimationSnapshot
+- AnimationTickResult (interface): interface AnimationTickResult
+- AnimationState (interface): interface AnimationState
+- AnimationStateConfig (interface): interface AnimationStateConfig
+
+### @jgengine/core/combat/attackTags
+
+- attackMeta (function): function attackMeta(tags: readonly AttackTag[], extra?: Omit<AttackMeta, "tags">): AttackMeta
+- hasTag (function): function hasTag(meta: AttackMeta, tag: AttackTag): boolean
+- hasAnyTag (function): function hasAnyTag(meta: AttackMeta, tags: readonly AttackTag[]): boolean
+- isBlockable (function): function isBlockable(meta: AttackMeta): boolean
+- isParryable (function): function isParryable(meta: AttackMeta): boolean
+- isDodgeable (function): function isDodgeable(meta: AttackMeta): boolean
+- counters (function): function counters(meta: AttackMeta, move: CounterMove): boolean
+- AttackTag (type): type AttackTag = | "unblockable" | "thrust" | "sweep" | "grab" | "overhead" | "ranged" | "aerial"
+- AttackMeta (interface): interface AttackMeta
+- CounterMove (type): type CounterMove = "mikiri" | "deflect" | "sidestep"
+
+### @jgengine/core/combat/breakMeters
+
+- createStaggerMeter (function): function createStaggerMeter(config: StaggerMeterConfig): StaggerMeter
+- createBuildupMeter (function): function createBuildupMeter(config: BuildupMeterConfig): BuildupMeter
+- StaggerMeterConfig (interface): interface StaggerMeterConfig
+- StaggerMeter (interface): interface StaggerMeter
+- BuildupMeterConfig (interface): interface BuildupMeterConfig
+- BuildupProc (interface): interface BuildupProc
+- BuildupMeter (interface): interface BuildupMeter
+
+### @jgengine/core/combat/comboString
+
+- stepById (function): function stepById(combo: ComboString, stepId: string): ComboStep | null
+- advanceCombo (function): function advanceCombo(input: AdvanceComboInput): AdvanceComboResult
+- createComboRunner (function): function createComboRunner(combo: ComboString, anim: AnimationState): ComboRunner
+- ComboStep (interface): interface ComboStep
+- ComboString (interface): interface ComboString
+- AdvanceComboInput (interface): interface AdvanceComboInput
+- AdvanceComboResult (type): type AdvanceComboResult = | { accepted: true; step: ComboStep } | { accepted: false; reason: "unknown-step" | "not-chainable" | "wrong-stance" | "window-closed" }
+- ComboRunner (interface): interface ComboRunner
+
+### @jgengine/core/combat/death
+
+- normalizeOnDeath (function): function normalizeOnDeath(spec: OnDeathSpec | null | undefined): NormalizedOnDeath
+- createDeathSystem (function): function createDeathSystem(deps: DeathSystemDeps): DeathSystem
+- deathReasonFromEffect (function): function deathReasonFromEffect(ctx: EffectDeathContext): DeathReason
+- DeathReasonKind (type): type DeathReasonKind = DeathReason["kind"]
+- OnDeathDropRule (interface): interface OnDeathDropRule
+- OnDeathCommandRule (interface): interface OnDeathCommandRule
+- DropMode (type): type DropMode = "grant" | "world"
+- OnDeathSpec (interface): interface OnDeathSpec
+- NormalizedOnDeath (interface): interface NormalizedOnDeath
+- DeathIdentity (interface): interface DeathIdentity
+- DeathSystemDeps (interface): interface DeathSystemDeps
+- DeathResolution (type): type DeathResolution = | { status: "resolved"; drops: Drop[]; ranCommand: string | null } | { status: "rejected"; reason: string }
+- DeathSystem (interface): interface DeathSystem
+- EffectDeathContext (interface): interface EffectDeathContext
+
+### @jgengine/core/combat/defensiveWindow
+
+- windowActiveAt (function): function windowActiveAt(config: DefensiveWindowConfig, elapsedMs: number): boolean
+- iframeActiveAt (function): function iframeActiveAt(config: DefensiveWindowConfig, elapsedMs: number): boolean
+- totalWindowMs (function): function totalWindowMs(config: DefensiveWindowConfig): number
+- resolveDefense (function): function resolveDefense(input: ResolveDefenseInput): DefenseResolution
+- createDefensiveWindow (function): function createDefensiveWindow(config: DefensiveWindowConfig): DefensiveWindow
+- DefenseKind (type): type DefenseKind = "parry" | "block" | "dodge"
+- DefensiveWindowConfig (interface): interface DefensiveWindowConfig
+- DefenseOutcome (type): type DefenseOutcome = "parry" | "block" | "iframe" | "hit"
+- DefenseResolution (interface): interface DefenseResolution
+- ResolveDefenseInput (interface): interface ResolveDefenseInput
+- DefensiveWindow (interface): interface DefensiveWindow
+
+### @jgengine/core/combat/downed
+
+- createDownedState (function): function createDownedState(config: DownedConfig): DownedState
+- DownedPhase (type): type DownedPhase = "alive" | "downed" | "dead"
+- DownedConfig (interface): interface DownedConfig
+- DownedEntry (interface): interface DownedEntry
+- DownedEventKind (type): type DownedEventKind = | "downed" | "revived" | "reviving" | "died" | "banner.created" | "banner.expired" | "respawned"
+- DownedEvent (interface): interface DownedEvent
+- DownedState (interface): interface DownedState
+
+### @jgengine/core/combat/effects
+
+- resolveAreaTargets (function): function resolveAreaTargets(spatial: CombatSpatialDeps, input: AreaTargetInput, accept?: (instanceId: string) => boolean): AreaTarget[]
+- createEffectSystem (function): function createEffectSystem(deps: EffectSystemDeps): EffectSystem
+- ReceiveRule (interface): interface ReceiveRule
+- ReceiveMap (type): type ReceiveMap = Record<string, ReceiveRule>
+- EffectVia (interface): interface EffectVia
+- SingleTargetEffectInput (interface): interface SingleTargetEffectInput
+- AreaEffectInput (interface): interface AreaEffectInput
+- EffectInput (type): type EffectInput = SingleTargetEffectInput | AreaEffectInput
+- AppliedPoolDelta (interface): interface AppliedPoolDelta
+- EffectResult (interface): interface EffectResult
+- LethalContext (interface): interface LethalContext
+- CombatSpatialDeps (interface): interface CombatSpatialDeps
+- AreaTargetInput (interface): interface AreaTargetInput
+- AreaTarget (interface): interface AreaTarget
+- EffectSystemDeps (interface): interface EffectSystemDeps
+- EffectSystem (interface): interface EffectSystem
+
+### @jgengine/core/combat/hitReaction
+
+- resolveHitReaction (function): function resolveHitReaction(config: HitReactionConfig, input: HitReactionInput): HitReaction
+- applyImpulse (function): function applyImpulse(position: EntityPosition, impulse: [number, number, number]): EntityPosition
+- CameraShake (interface): interface CameraShake
+- HitReactionConfig (interface): interface HitReactionConfig
+- HitReactionInput (interface): interface HitReactionInput
+- HitReaction (interface): interface HitReaction
+
+### @jgengine/core/combat/projectiles
+
+- createProjectileSystem (function): function createProjectileSystem(deps: ProjectileSystemDeps): ProjectileSystem
+- ProjectileShotInput (interface): interface ProjectileShotInput
+- EntityRaycastHit (interface): interface EntityRaycastHit — A raycast hit against a scene entity — the ray reached `instanceId` at `distance` along its length.
+- ObjectRaycastHit (interface): interface ObjectRaycastHit — A raycast hit against a placed scene object's bounding box — see `ProjectileObjectsDeps.halfExtents`.
+- RaycastHit (type): type RaycastHit = EntityRaycastHit | ObjectRaycastHit
+- Raycast (type): type Raycast = (from: string, aim: Aim, range: number) => RaycastHit[]
+- ProjectileSettleReport (interface): interface ProjectileSettleReport
+- ProjectileObjectsDeps (interface): interface ProjectileObjectsDeps — Read-only scene object access for the default `raycast`; matches `ObjectStore.list()`/a catalog lookup structurally.
+- ProjectileSystemDeps (interface): interface ProjectileSystemDeps
+- ProjectileHit (type): type ProjectileHit = | { kind: "entity"; instanceId: string; distance: number } | { kind: "object"; instanceId: string; catalogId: string; distance: number }
+- ProjectilePrediction (interface): interface ProjectilePrediction
+- SettleResult (type): type SettleResult = | { status: "settled"; shotId: string; at: [number, number, number]; hits: EffectResult[] } | { status: "rejected"; shotId: string; reason: string }
+- ProjectileSystem (interface): interface ProjectileSystem
+
+### @jgengine/core/combat/resistance
+
+- resolveResistance (function): function resolveResistance(matrix: ResistanceMatrix, category: string, targetProperties: readonly string[]): ResistanceResult
+- resistanceScale (function): function resistanceScale(matrix: ResistanceMatrix, category: string, targetProperties: readonly string[]): number
+- ResistVerdict (type): type ResistVerdict = "immune" | "resist" | "normal" | "vulnerable"
+- ResistanceMatrix (interface): interface ResistanceMatrix
+- ResistanceResult (interface): interface ResistanceResult
+
+### @jgengine/core/combat/telegraph
+
+- telegraphProgress (function): function telegraphProgress(windupMs: number, startedAtMs: number, nowMs: number): number
+- telegraphFired (function): function telegraphFired(windupMs: number, startedAtMs: number, nowMs: number): boolean
+- telegraphTurnProgress (function): function telegraphTurnProgress(config: TelegraphConfig, startedTurn: number, currentTurn: number): number
+- telegraphFiredAtTurn (function): function telegraphFiredAtTurn(config: TelegraphConfig, startedTurn: number, currentTurn: number): boolean
+- telegraphTurnsRemaining (function): function telegraphTurnsRemaining(config: TelegraphConfig, startedTurn: number, currentTurn: number): number
+- pointInTelegraph (function): function pointInTelegraph(config: TelegraphConfig, point: EntityPosition): boolean
+- TelegraphShape (type): type TelegraphShape = | { kind: "circle"; radius: number } | { kind: "ring"; radius: number; innerRadius: number } | { kind: "cone"; radius: number; angle: number } | { kind: "line"; length: number; width: number }
+- TelegraphConfig (interface): interface TelegraphConfig
+
+### @jgengine/core/commands/commandRegistry
+
+- createCommandRegistry (function): function createCommandRegistry<TState>(): CommandRegistry<TState>
+- CommandRejection (interface): interface CommandRejection
+- CommandDefinition (interface): interface CommandDefinition<TState, TInput>
+- CommandResult (type): type CommandResult<TState> = | { status: "applied"; state: TState } | { status: "rejected"; reason: string } | { status: "unknown-command" }
+- CommandRegistry (interface): interface CommandRegistry<TState>
+
+### @jgengine/core/crafting/crop
+
+- emptyTile (function): function emptyTile(): CropTileState
+- canTill (function): function canTill(state: CropTileState): boolean
+- tillTile (function): function tillTile(state: CropTileState): CropTileState
+- canPlant (function): function canPlant(state: CropTileState): boolean
+- plantCrop (function): function plantCrop(state: CropTileState, cropId: string): CropTileState
+- waterTile (function): function waterTile(state: CropTileState): CropTileState
+- maturityDays (function): function maturityDays(def: CropDef): number
+- advanceCropDay (function): function advanceCropDay(def: CropDef, state: CropTileState): CropTileState
+- harvestCrop (function): function harvestCrop(def: CropDef, state: CropTileState): HarvestResult
+- tileKey (function): function tileKey(coord: TileCoord): string
+- singleTile (function): function singleTile(): TilePattern
+- squarePattern (function): function squarePattern(radius: number): TilePattern
+- diamondPattern (function): function diamondPattern(radius: number): TilePattern
+- rectPattern (function): function rectPattern(width: number, depth: number): TilePattern
+- patternAt (function): function patternAt(center: TileCoord, pattern: TilePattern): TileCoord[]
+- applyToolToTiles (function): function applyToolToTiles(tiles: ReadonlyMap<string, CropTileState>, center: TileCoord, pattern: TilePattern, apply: (state: CropTileState, coord: TileCoord) => CropTileState, fill: () => CropTileState = emptyTile): ApplyToolResult
+- createDayTicker (function): function createDayTicker(startDay = 0): DayTicker
+- createCropField (function): function createCropField(catalog: CropCatalog = () => null): CropField
+- SoilState (type): type SoilState = "untilled" | "tilled"
+- CropDef (interface): interface CropDef
+- CropTileState (interface): interface CropTileState
+- CropCatalog (type): type CropCatalog = (cropId: string) => CropDef | null
+- HarvestResult (interface): interface HarvestResult
+- TileCoord (type): type TileCoord = readonly [number, number]
+- TilePattern (type): type TilePattern = readonly TileCoord[]
+- ApplyToolResult (interface): interface ApplyToolResult
+- DayTicker (interface): interface DayTicker
+- CropField (interface): interface CropField
+
+### @jgengine/core/crafting/production
+
+- productionBuilding (function): function productionBuilding(config: ProductionBuildingConfig): ProductionBuildingDef
+- createProductionState (function): function createProductionState(): ProductionState
+- acceptsInput (function): function acceptsInput(def: ProductionBuildingDef, state: ProductionState, itemId: string): boolean
+- feedProduction (function): function feedProduction(def: ProductionBuildingDef, state: ProductionState, itemId: string, count: number): { state: ProductionState; accepted: number }
+- drainOutput (function): function drainOutput(state: ProductionState, itemId: string, count?: number): { state: ProductionState; taken: number }
+- tickProduction (function): function tickProduction(def: ProductionBuildingDef, state: ProductionState, input: ProductionTickInput): ProductionState
+- advanceTransport (function): function advanceTransport(path: TransportPath, items: readonly TransportItem[], dt: number): { items: TransportItem[]; delivered: TransportItem[] }
+- resolvePowerGrid (function): function resolvePowerGrid(supply: number, consumers: readonly PowerConsumer[]): PowerGridResult
+- ProductionBuildingDef (interface): interface ProductionBuildingDef
+- ProductionBuildingConfig (interface): interface ProductionBuildingConfig
+- ItemCounts (type): type ItemCounts = Readonly<Record<string, number>>
+- ProductionState (interface): interface ProductionState
+- ProductionTickInput (interface): interface ProductionTickInput
+- TransportItem (interface): interface TransportItem
+- TransportPath (interface): interface TransportPath
+- PowerConsumer (interface): interface PowerConsumer
+- PowerGridResult (interface): interface PowerGridResult
+
+### @jgengine/core/crafting/recipe
+
+- craftSeconds (function): function craftSeconds(recipe: RecipeDef): number
+- missingInputs (function): function missingInputs(state: InventoryState, recipe: RecipeDef): RecipeItem[]
+- hasRecipeInputs (function): function hasRecipeInputs(state: InventoryState, recipe: RecipeDef): boolean
+- stationSatisfied (function): function stationSatisfied(recipe: RecipeDef, context: CraftContext): boolean
+- canCraft (function): function canCraft(state: InventoryState, layout: InventoryLayout, traits: ItemTraits, recipe: RecipeDef, context: CraftContext = {}): CraftCheck
+- craft (function): function craft(state: InventoryState, layout: InventoryLayout, traits: ItemTraits, recipe: RecipeDef, context: CraftContext = {}): CraftResult
+- createRecipeGraph (function): function createRecipeGraph(defs: readonly RecipeDef[] = []): RecipeGraph
+- RecipeItem (interface): interface RecipeItem
+- RecipeDef (interface): interface RecipeDef
+- StationInstance (interface): interface StationInstance
+- CraftContext (interface): interface CraftContext
+- CraftRejection (type): type CraftRejection = | { reason: "missing-inputs"; missing: readonly RecipeItem[] } | { reason: "no-station"; station: string } | { reason: "locked"; requires: readonly string[] } | { reason: "no-output-space" }
+- CraftCheck (type): type CraftCheck = { ok: true } | ({ ok: false } & CraftRejection)
+- CraftResult (type): type CraftResult = { status: "ok"; state: InventoryState } | ({ status: "rejected" } & CraftRejection)
+- RecipeGraph (interface): interface RecipeGraph
+
+### @jgengine/core/data/dataSource
+
+- createDataSource (function): function createDataSource<T>(load: (signal: AbortSignal) => Promise<T>, options: DataSourceOptions = {}): DataSource<T>
+- DataSourceStatus (type): type DataSourceStatus = "idle" | "loading" | "ready" | "error"
+- DataSourceState (interface): interface DataSourceState<T>
+- DataSourceClock (interface): interface DataSourceClock
+- DataSourceOptions (interface): interface DataSourceOptions
+- RefreshOptions (interface): interface RefreshOptions
+- DataSource (interface): interface DataSource<T>
+
+### @jgengine/core/data/devProxy
+
+- parseDevProxyTable (function): function parseDevProxyTable(raw: string | undefined): DevProxyTable
+- proxiedUrl (function): function proxiedUrl(target: string, options: ProxiedUrlOptions = {}): string
+- DevProxyTable (interface): interface DevProxyTable
+- ProxiedUrlOptions (interface): interface ProxiedUrlOptions
+- DEFAULT_DEV_PROXY_PREFIX (const): const DEFAULT_DEV_PROXY_PREFIX: "/proxy"
+
+### @jgengine/core/data/fetchJson
+
+- fetchJson (function): function fetchJson<T>(url: string, options: FetchJsonOptions = {}): Promise<T>
+- FetchImpl (type): type FetchImpl = typeof fetch
+- FetchJsonOptions (interface): interface FetchJsonOptions
+- HttpStatusError (class): class HttpStatusError extends Error
+- JsonParseError (class): class JsonParseError extends Error
+
+### @jgengine/core/data/jsonDataSource
+
+- createJsonDataSource (function): function createJsonDataSource<T>(url: string, options: JsonDataSourceOptions = {}): DataSource<T>
+- JsonDataSourceOptions (type): type JsonDataSourceOptions = DataSourceOptions & Omit<FetchJsonOptions, "signal">
+
+### @jgengine/core/devtools/devtools
+
+- formatLogMessage (function): function formatLogMessage(args: readonly unknown[]): string
+- createDevtools (function): function createDevtools(): Devtools
+- tunable (function): function tunable<T>(name: string, initial: T, options?: TunableOptions<T>): Tunable<T>
+- snapshotDevtools (function): function snapshotDevtools(): DevtoolsSnapshot
+- instrumentLatency (function): function instrumentLatency<T extends object>(target: T, methods: readonly (keyof T)[], record: (ms: number) => void = devtools.latency.record): T
+- DevtoolsControlKind (type): type DevtoolsControlKind = "slider" | "toggle" | "color" | "select" | "text"
+- TunableOptions (interface): interface TunableOptions<T>
+- DevtoolsControl (interface): interface DevtoolsControl
+- Tunable (interface): interface Tunable<T>
+- FrameStats (interface): interface FrameStats
+- RenderSample (interface): interface RenderSample
+- LatencyStats (interface): interface LatencyStats
+- DevtoolsLogLevel (type): type DevtoolsLogLevel = "log" | "info" | "warn" | "error"
+- DevtoolsLogEntry (interface): interface DevtoolsLogEntry
+- DiscoveredEntry (interface): interface DiscoveredEntry
+- TunableAccessor (interface): interface TunableAccessor
+- DevtoolsOverrides (interface): interface DevtoolsOverrides
+- DevtoolsSnapshot (interface): interface DevtoolsSnapshot
+- Devtools (interface): interface Devtools
+- devtools (const): const devtools: Devtools
+
+### @jgengine/core/devtools/transformTunables
+
+- transformTunableExports (function): function transformTunableExports(code: string, table: string): TunableTransformResult
+- tunableModuleTable (function): function tunableModuleTable(id: string): string | null
+- tunableDiscoveryPlugin (function): function tunableDiscoveryPlugin(): { name: string; enforce: "pre"; transform(code: string, id: string): { code: string; map: null } | null; }
+- TunableTransformResult (interface): interface TunableTransformResult
+
+### @jgengine/core/economy/currency
+
+- sanitizeCurrencyAmount (function): function sanitizeCurrencyAmount(amount: number): number
+- formatCurrencyAmount (function): function formatCurrencyAmount(currency: CurrencyDefinition, amount: number): string
+- insufficientCurrencyReason (function): function insufficientCurrencyReason(currency: CurrencyDefinition, needed: number, current: number): string
+- applyCurrencyOperation (function): function applyCurrencyOperation(currency: CurrencyDefinition, current: number, operation: CurrencyOperation, amount: number): CurrencyAdjustment
+- resolveCurrencyDelta (function): function resolveCurrencyDelta(current: number, delta: number): { operation: CurrencyOperation; amount: number } — Deducts clamp to the available balance (a delta can never overdraw); adds apply in full.
+- CurrencyDefinition (interface): interface CurrencyDefinition<TCurrencyId extends string = string>
+- CurrencyOperation (type): type CurrencyOperation = "add" | "deduct"
+- CurrencyAdjustment (type): type CurrencyAdjustment = | { success: true; newBalance: number; appliedDelta: number } | { success: false; reason: string }
+
+### @jgengine/core/economy/sharedWallet
+
+- scopeKey (function): function scopeKey(scope: WalletScope): string
+- userScope (function): function userScope(userId: string): WalletScope
+- groupScope (function): function groupScope(groupId: string): WalletScope
+- createWalletBook (function): function createWalletBook(): WalletBook
+- balanceIn (function): function balanceIn(book: WalletBook, scope: WalletScope, currency: string): number
+- grantTo (function): function grantTo(book: WalletBook, scope: WalletScope, currency: string, amount: number, by?: string): WalletBook
+- chargeFrom (function): function chargeFrom(book: WalletBook, scope: WalletScope, currency: string, amount: number, by?: string): BookChargeResult
+- contributionOf (function): function contributionOf(book: WalletBook, groupId: string, userId: string): Readonly<Record<string, number>>
+- contributorsOf (function): function contributorsOf(book: WalletBook, groupId: string): string[]
+- WalletScope (type): type WalletScope = | { kind: "user"; userId: string } | { kind: "group"; groupId: string }
+- WalletBook (interface): interface WalletBook
+- BookChargeResult (type): type BookChargeResult = | { status: "ok"; book: WalletBook } | { status: "rejected"; reason: "insufficient-funds" }
+
+### @jgengine/core/economy/techTree
+
+- techPrerequisitesMet (function): function techPrerequisitesMet(state: TechState, node: TechNodeDef): boolean
+- missingPrerequisites (function): function missingPrerequisites(state: TechState, node: TechNodeDef): string[]
+- canUnlockTech (function): function canUnlockTech(defs: readonly TechNodeDef[], state: TechState, id: string): TechCheck
+- grantTech (function): function grantTech(state: TechState, node: TechNodeDef): string[]
+- availableTech (function): function availableTech(defs: readonly TechNodeDef[], state: TechState): TechNodeDef[]
+- unlockedRecipes (function): function unlockedRecipes(defs: readonly TechNodeDef[], state: TechState): string[]
+- createTechTree (function): function createTechTree(defs: readonly TechNodeDef[] = []): TechTree
+- TechNodeDef (interface): interface TechNodeDef extends UnlockDef
+- TechState (type): type TechState = UnlockState
+- TechRejection (type): type TechRejection = | { reason: "unknown-node" } | { reason: "already-unlocked" } | { reason: "missing-prerequisites"; missing: readonly string[] }
+- TechCheck (type): type TechCheck = { ok: true } | ({ ok: false } & TechRejection)
+- TechTree (interface): interface TechTree
+
+### @jgengine/core/economy/wallet
+
+- createEmptyWallet (function): function createEmptyWallet(): WalletState
+- balance (function): function balance(state: WalletState, currency: string): number
+- grant (function): function grant(state: WalletState, currency: string, amount: number): WalletState
+- charge (function): function charge(state: WalletState, currency: string, amount: number): ChargeResult
+- canAfford (function): function canAfford(state: WalletState, costs: Readonly<Record<string, number>>): boolean
+- chargeAll (function): function chargeAll(state: WalletState, costs: Readonly<Record<string, number>>): ChargeResult
+- WalletState (interface): interface WalletState
+- ChargeResult (type): type ChargeResult = { status: "ok"; state: WalletState } | { status: "rejected"; reason: "insufficient-funds" }
+
+### @jgengine/core/game/chat
+
+- whisperChannelId (function): function whisperChannelId(a: string, b: string): string
+- createChatRateLimiter (function): function createChatRateLimiter(limit: ChatRateLimit): ChatRateLimiter
+- createChat (function): function createChat(deps: ChatDeps): Chat
+- ChatChannelKind (type): type ChatChannelKind = "global" | "party" | "proximity"
+- ChatRateLimit (interface): interface ChatRateLimit
+- ChatChannelDef (interface): interface ChatChannelDef
+- ChatMessage (interface): interface ChatMessage
+- ChatRecipients (type): type ChatRecipients = readonly string[] | "all"
+- ChatSendResult (type): type ChatSendResult = | { message: ChatMessage; recipients: ChatRecipients } | { reason: string }
+- ChatSnapshot (interface): interface ChatSnapshot
+- Chat (interface): interface Chat
+- ChatDeps (interface): interface ChatDeps
+- DEFAULT_CHAT_RATE_LIMIT (const): const DEFAULT_CHAT_RATE_LIMIT: ChatRateLimit
+- DEFAULT_CHAT_HISTORY_LIMIT (const): const DEFAULT_CHAT_HISTORY_LIMIT: 100
+- DEFAULT_CHAT_BODY_LENGTH (const): const DEFAULT_CHAT_BODY_LENGTH: 500
+- DEFAULT_PROXIMITY_CHAT_RADIUS (const): const DEFAULT_PROXIMITY_CHAT_RADIUS: 20
+- WHISPER_CHANNEL_PREFIX (const): const WHISPER_CHANNEL_PREFIX: "whisper:"
+- ChatRateLimiter (interface): interface ChatRateLimiter
+
+### @jgengine/core/game/cosmetics
+
+- createCosmetics (function): function createCosmetics(deps: CosmeticsDeps = {}): Cosmetics
+- CosmeticLoadoutDef (interface): interface CosmeticLoadoutDef
+- CosmeticsChangedEvent (interface): interface CosmeticsChangedEvent
+- CosmeticsEvents (interface): interface CosmeticsEvents
+- CosmeticsDeps (interface): interface CosmeticsDeps
+- Cosmetics (interface): interface Cosmetics
+
+### @jgengine/core/game/defineGame
+
+- defineGame (function): function defineGame<TAssetRef extends ModelAssetRef, TMultiplayer>(config: GameDefinitionConfig<TAssetRef, TMultiplayer>): GameDefinition<TAssetRef, TMultiplayer>
+- PhysicsConfig (interface): interface PhysicsConfig
+- InventoryDeclaration (interface): interface InventoryDeclaration
+- GameServerConfig (type): type GameServerConfig = "persistent" | { mode: string; [key: string]: unknown }
+- GameLoop (interface): interface GameLoop<TContext = unknown>
+- GameDefinition (interface): interface GameDefinition<TAssetRef extends ModelAssetRef = ModelAssetRef, TMultiplayer = unknown>
+- GameDefinitionConfig (type): type GameDefinitionConfig<TAssetRef extends ModelAssetRef = ModelAssetRef, TMultiplayer = unknown> = Omit<GameDefinition<TAssetRef, TMultiplayer>, "scene" | "assets"> & { assets?: AssetCatalog<TAssetRef>; }
+
+### @jgengine/core/game/events
+
+- createGameEvents (function): function createGameEvents<TMap extends GameEventMap = GameEventMap>(): GameEvents<TMap>
+- DeathReason (type): type DeathReason = | { kind: "player_kill"; killerUserId: string; via?: { item?: string } } | { kind: "environment"; source: string } | { kind: "self"; source: string }
+- EntityDiedEvent (interface): interface EntityDiedEvent
+- LootGrantedEvent (interface): interface LootGrantedEvent
+- InventoryAddedEvent (interface): interface InventoryAddedEvent
+- QuestAcceptedEvent (interface): interface QuestAcceptedEvent
+- QuestUpdatedEvent (interface): interface QuestUpdatedEvent
+- QuestCompletedEvent (interface): interface QuestCompletedEvent
+- SocialFriendAddedEvent (interface): interface SocialFriendAddedEvent
+- SocialPartyJoinedEvent (interface): interface SocialPartyJoinedEvent
+- SocialPartyLeftEvent (interface): interface SocialPartyLeftEvent
+- SocialWorldInvitedEvent (interface): interface SocialWorldInvitedEvent
+- SocialWorldAcceptedEvent (interface): interface SocialWorldAcceptedEvent
+- ChatMessageEvent (interface): interface ChatMessageEvent
+- StatLevelUpEvent (interface): interface StatLevelUpEvent
+- EntityFloatTextEvent (interface): interface EntityFloatTextEvent
+- CombatTelegraphEvent (interface): interface CombatTelegraphEvent
+- CombatHitReactionEvent (interface): interface CombatHitReactionEvent
+- ProjectileSettledEvent (interface): interface ProjectileSettledEvent
+- WorldItemDroppedEvent (interface): interface WorldItemDroppedEvent
+- WorldItemPickedUpEvent (interface): interface WorldItemPickedUpEvent
+- CosmeticsChangedEvent (interface): interface CosmeticsChangedEvent
+- EmotePlayedEvent (interface): interface EmotePlayedEvent
+- PossessionSwappedEvent (interface): interface PossessionSwappedEvent
+- FormChangedEvent (interface): interface FormChangedEvent
+- GameEventMap (interface): interface GameEventMap
+- GameEventHandler (type): type GameEventHandler<TPayload> = (payload: TPayload) => void
+- GameEvents (interface): interface GameEvents<TMap extends GameEventMap = GameEventMap>
+
+### @jgengine/core/game/feed
+
+- appendFeedEntry (function): function appendFeedEntry<T>(buffer: readonly FeedEntry<T>[], entry: FeedEntry<T>, limit: number): FeedEntry<T>[]
+- recentFeedEntries (function): function recentFeedEntries<T>(buffer: readonly FeedEntry<T>[], limit?: number): FeedEntry<T>[]
+- createGameFeed (function): function createGameFeed(options?: GameFeedOptions): GameFeed
+- FeedEntry (interface): interface FeedEntry<T = unknown>
+- GameFeedOptions (interface): interface GameFeedOptions
+- GameFeed (interface): interface GameFeed
+
+### @jgengine/core/game/leaderboard
+
+- createLeaderboard (function): function createLeaderboard(sink?: { onIncrement?(row: LeaderboardRow): void }): Leaderboard
+- LeaderboardScope (type): type LeaderboardScope = "global" | "server" | "profile"
+- LeaderboardTrackDef (interface): interface LeaderboardTrackDef
+- LeaderboardRow (interface): interface LeaderboardRow
+- IncrementResult (type): type IncrementResult = { status: "ok"; value: number } | { status: "rejected"; reason: "not-tracked" }
+- Leaderboard (interface): interface Leaderboard
+
+### @jgengine/core/game/levelSequence
+
+- createLevelSequence (function): function createLevelSequence<TLevelConfig>(config: LevelSequenceConfig<TLevelConfig>): LevelSequence<TLevelConfig> — A pure, deterministic level campaign: an ordered list of levels, each with its own opaque config, played through a `start` → (`clear` → `advance`)* → `complete` happy path, with `fail`/`retry` handling per-level attempts. Mirrors the reducer style of `game/race.ts` and `ai/spawnDirector.ts` — no I/O, no timers, just state transitions driven by the caller.
+- LevelDescriptor (interface): interface LevelDescriptor<TLevelConfig>
+- LevelSequenceConfig (interface): interface LevelSequenceConfig<TLevelConfig>
+- LevelSequenceStatus (type): type LevelSequenceStatus = "idle" | "playing" | "cleared" | "failed" | "complete"
+- CurrentLevel (interface): interface CurrentLevel<TLevelConfig>
+- LevelSequenceProgress (interface): interface LevelSequenceProgress
+- LevelSequence (interface): interface LevelSequence<TLevelConfig>
+
+### @jgengine/core/game/loadout
+
+- createLoadouts (function): function createLoadouts(deps: LoadoutDeps): Loadouts
+- LoadoutItemEntry (interface): interface LoadoutItemEntry
+- LoadoutDef (interface): interface LoadoutDef
+- LoadoutInventoryTransaction (interface): interface LoadoutInventoryTransaction
+- LoadoutDeps (interface): interface LoadoutDeps
+- Loadouts (interface): interface Loadouts
+
+### @jgengine/core/game/lootFilter
+
+- evaluateLootFilter (function): function evaluateLootFilter(rules: readonly LootFilterRule[], item: LootFilterItem): LootFilterOverride — First matching rule wins (PoE/Last Epoch block semantics) — later rules never override an earlier match. Returns overrides only; fields the rule doesn't set are left for the caller's baseline (rarity style) to fill in.
+- lootFilter (function): function lootFilter(rules: readonly LootFilterRule[]): readonly LootFilterRule[] — Validating factory — rule ids must be unique so authoring mistakes fail loudly.
+- LootFilterItem (interface): interface LootFilterItem
+- LootFilterCondition (interface): interface LootFilterCondition
+- LootFilterRule (interface): interface LootFilterRule
+- LootFilterOverride (interface): interface LootFilterOverride
+
+### @jgengine/core/game/lootTable
+
+- createLootRegistry (function): function createLootRegistry(): LootRegistry
+- lootTable (function): function lootTable(def: LootTableDef): LootTableDef
+- grantDrops (function): function grantDrops(drops: Drop[], appliers: { putItem: (itemId: string, count: number) => unknown; grantCurrency: (currencyId: string, amount: number) => unknown; }): void
+- LootEntry (interface): interface LootEntry
+- LootTableDef (interface): interface LootTableDef
+- Drop (interface): interface Drop
+- LootRegistry (interface): interface LootRegistry
+
+### @jgengine/core/game/ping
+
+- classifyPing (function): function classifyPing(hit: PointerHit, deps: PingClassifyDeps = {}, options: PingClassifyOptions = {}): PingCategory — Classify what a pointer/aim ray hit into a ping category. Entity hits resolve by catalog role (hostile → enemy, else location); object hits by an optional catalog category tag; open ground is a location ping.
+- createPingSystem (function): function createPingSystem(deps: PingSystemDeps): PingSystem
+- PingCategory (type): type PingCategory = string
+- PingCategoryDef (interface): interface PingCategoryDef
+- DEFAULT_PING_CATEGORIES (const): const DEFAULT_PING_CATEGORIES: Record<PingCategory, PingCategoryDef> — Content-agnostic default ping wheel: enemy / loot / location / danger.
+- PING_FEED_ACTION (const): const PING_FEED_ACTION: "party.ping"
+- PingClassifyDeps (interface): interface PingClassifyDeps
+- PingClassifyOptions (interface): interface PingClassifyOptions
+- PingPayload (interface): interface PingPayload
+- PingFeedSink (interface): interface PingFeedSink
+- PingParty (interface): interface PingParty
+- PingSystemDeps (interface): interface PingSystemDeps
+- PingSystem (interface): interface PingSystem
+
+### @jgengine/core/game/playableGame
+
+- worldHealthBarAllowsRole (function): function worldHealthBarAllowsRole(roles: readonly CatalogEntityRole[] | undefined, role: CatalogEntityRole | undefined): boolean
+- PointerConfig (interface): interface PointerConfig
+- CameraFollowState (interface): interface CameraFollowState
+- FirstPersonCameraConfig (interface): interface FirstPersonCameraConfig
+- CameraRigKind (type): type CameraRigKind = | "orbit" | "first" | "topDown" | "rts" | "shoulder" | "lockOn" | "chase" | "observer" | "turntable" | "sideScroll" | "inspection" | "none" — Which camera rig the shell mounts. Every rig accepts `followEntityId: null` (avatar-less games — city-builders, card games, auto-battlers — still get a camera). Rigs are tuned through their config block below, never by writing camera positions from `onTick`. - `orbit` — third-person chase (the historical default; `perspective: "third"`). - `first` — pointer-lock mouse-look (`perspective: "first"`). - `topDown` — fixed height/pitch/yaw with decoupled follow (ARPG iso, top-down). - `rts` — free-pan / edge-scroll / rotate / zoom, optional follow. - `shoulder` — over-the-shoulder with ADS transition + shoulder swap. - `lockOn` — yaw bound to the player→target vector; move axis becomes strafe. - `chase` — speed-reactive vehicle chase (speed→FOV, spring arm, shake) + cockpit/hood/rear views. - `observer` — detached spectator/photo cam bound to any entity or fixed point; never reads player input. - `turntable` — slow auto-orbit of a fixed point: a rotating display stand for a scene. The friendly, flat spelling of `observer`'s point-orbit mode; providing `camera.turntable` selects it without an explicit `rig`. - `sideScroll` — fixed lateral follow (2.5D platformer/beat-'em-up side view); reads no player input. - `inspection` — model-viewer rig (#207.7): left-drag orbit, middle/right-drag pan, scroll zoom toward a configurable anchor; orbits a fixed point, reads no player/entity input. - `none` — no camera rig is mounted; use for HUD-only presentations or a game that manages its own camera.
+- SideScrollCameraConfig (interface): interface SideScrollCameraConfig — Fixed lateral 2.5D follow (side-on platformer cam): the camera sits perpendicular to the travel axis, tracks the followed entity, and never reads player look input.
+- TopDownCameraConfig (interface): interface TopDownCameraConfig — Fixed top-down / isometric rig (#23) — height/pitch/yaw + decoupled follow.
+- RtsCameraConfig (interface): interface RtsCameraConfig extends TopDownCameraConfig — Free-pan / edge-scroll RTS rig (#24) — pan/rotate/zoom independent of any avatar.
+- ShoulderCameraConfig (interface): interface ShoulderCameraConfig — Over-the-shoulder combat rig (#25) — offset, ADS, shoulder swap, decoupled reticle.
+- LockOnCameraConfig (interface): interface LockOnCameraConfig — Lock-on / strafe rig (#26) — yaw bound to player→target, move axis becomes strafe.
+- ChaseView (type): type ChaseView = "chase" | "cockpit" | "hood" | "rear" — Fixed interior view for the chase rig (#27).
+- ChaseCameraConfig (interface): interface ChaseCameraConfig — Speed-reactive vehicle chase rig (#27) — speed→FOV, spring arm, procedural shake, interior views.
+- ObserverCameraConfig (interface): interface ObserverCameraConfig — Detached spectator/photo cam (#120) — binds to any entity or fixed point, never reads player input.
+- TurntableCameraConfig (interface): interface TurntableCameraConfig — Turntable / showcase rig — slowly auto-orbits a fixed world point (no player input), the way a museum turntable rotates an object on display. A flat, self-describing spelling of `observer`'s point-orbit mode: `target` names the point directly instead of `bind: { kind: "point", position }`. Set `camera.turntable` and the rig is inferred — you don't also write `rig`.
+- InspectionZoomAnchor (type): type InspectionZoomAnchor = "target" | "cursor" | "center" — How scroll-zoom re-anchors the view for the inspection rig (#207.7): - `target` — dolly toward the orbit target (classic OrbitControls behavior). - `cursor` — dolly toward the point under the pointer. - `center` — dolly toward the viewport center; equivalent to `target` for an OrbitControls-driven rig, since the camera always faces `target` and that point already projects to the exact center of the viewport.
+- InspectionCameraConfig (interface): interface InspectionCameraConfig — Model-viewer / inspection rig (#207.7) — orbit + pan + anchored zoom around a fixed point, never reads player input.
+- CameraKeyframe (interface): interface CameraKeyframe — One stop on a scripted camera path (#29).
+- CinematicCameraConfig (interface): interface CinematicCameraConfig — Scripted keyframe / path player (#29). When set it overrides the active rig.
+- CameraShakeConfig (interface): interface CameraShakeConfig — Camera-shake / trauma defaults (#28). Any rig reads the trauma channel; game systems feed it via `cameraShake()`.
+- CAMERA_FRUSTUM_DEFAULTS (const): const CAMERA_FRUSTUM_DEFAULTS: { readonly fov: 55; readonly near: 0.1; readonly far: 300; }
+- GameCameraConfig (interface): interface GameCameraConfig
+- EntitySpriteConfig (interface): interface EntitySpriteConfig
+- WorldItemRenderConfig (interface): interface WorldItemRenderConfig
+- VoxelCollisionConfig (interface): interface VoxelCollisionConfig — Player-vs-world collision for the first-person controller. Without this the shell keeps the player on flat ground at y=0. With `voxel: true` the shell resolves the player as a box against placed scene objects (each treated as a solid unit cell), so they stand on blocks, fall into holes, and are stopped by walls — the controller a block-building/mining game needs.
+- ModelAnimationConfig (interface): interface ModelAnimationConfig — Rig playback for a `ModelConfig`'s GLTF animation clips — looping idles, one-shots, and held poses.
+- ModelMaterialOverride (interface): interface ModelMaterialOverride — Per-entity PBR material override (#151.3) applied to every `MeshStandardMaterial` in the model's cloned scene graph.
+- ModelConfig (interface): interface ModelConfig
+- ObjectStyle (interface): interface ObjectStyle
+- AmbientLightingConfig (interface): interface AmbientLightingConfig
+- DirectionalLightingConfig (interface): interface DirectionalLightingConfig
+- HemisphereLightingConfig (interface): interface HemisphereLightingConfig
+- LightingConfig (interface): interface LightingConfig — Declarative lighting replacing the shell's hardcoded ambient/directional default (#207.5); mounts regardless of world kind, only when supplied.
+- BackdropFogConfig (interface): interface BackdropFogConfig
+- BackdropConfig (interface): interface BackdropConfig — Generic sky/background/fog for ANY world kind, including a custom `environment` component (#207.6).
+- PlayerMovementConfig (interface): interface PlayerMovementConfig — Movement-control levers for the shell-driven local player walk controller.
+- MovementCommitFrame (interface): interface MovementCommitFrame — One frame's movement resolution handed to `PlayerMovementConfig.beforeCommit`.
+- PlayableGame (interface): interface PlayableGame<TUi = unknown, TWorldOverlay = unknown, TRenderEntity = never, TRenderObject = never>
+
+### @jgengine/core/game/progression
+
+- evalCurve (function): function evalCurve(spec: Curve, x: number): number
+- curve (function): function curve(spec: Curve): (x: number) => number
+- leveling (function): function leveling(config: LevelingConfig): LevelingTrack
+- CurveDef (type): type CurveDef = | { kind: "const"; value: number } | { kind: "linear"; base: number; per: number } | { kind: "power"; base: number; exponent: number } | { kind: "geometric"; base: number; ratio: number } | { kind: "steps"; values: number[] } | { kind: "piecewise"; points: [number, number][] }
+- CurveShape (interface): interface CurveShape
+- Curve (type): type Curve = CurveDef & CurveShape
+- LevelProgress (interface): interface LevelProgress
+- LevelingConfig (interface): interface LevelingConfig
+- LevelingStatAccess (interface): interface LevelingStatAccess
+- LevelingTrack (interface): interface LevelingTrack
+
+### @jgengine/core/game/quest
+
+- createQuestJournal (function): function createQuestJournal(deps: QuestJournalDeps): QuestJournal
+- applyQuestRewards (function): function applyQuestRewards(rewards: QuestRewards, appliers: { grantXp?(amount: number): void; grantEconomy?(currencyId: string, amount: number): void; grantItem?(inventoryId: string, itemId: string, count: number): void; grantUnlock?(unlockId: string): void; }): void
+- createQuestEvaluator (function): function createQuestEvaluator(defs: QuestDef[] | Record<string, QuestDef>): QuestEvaluator
+- QuestObjective (interface): interface QuestObjective
+- QuestRewards (interface): interface QuestRewards
+- QuestDef (interface): interface QuestDef
+- QuestStatus (type): type QuestStatus = "active" | "completed"
+- QuestObjectiveProgress (interface): interface QuestObjectiveProgress
+- QuestInstance (interface): interface QuestInstance
+- QuestSnapshotEntry (type): type QuestSnapshotEntry = { questId: string; status: QuestStatus; progress: Record<string, number>; }
+- QuestJournalDeps (interface): interface QuestJournalDeps
+- QuestJournal (interface): interface QuestJournal
+- QuestAcceptOptions (interface): interface QuestAcceptOptions
+- QuestTurnIn (interface): interface QuestTurnIn
+- QuestEvaluator (interface): interface QuestEvaluator
+
+### @jgengine/core/game/race
+
+- raceTrack (function): function raceTrack(config: RaceTrackConfig): RaceTrack — A race track is an ordered ring of checkpoint trigger volumes plus a lap count. The final checkpoint is the lap/finish line: a racer completes a lap by passing all checkpoints in order and hitting the last one.
+- firstPastPost (function): function firstPastPost(count = 1): RaceWinCondition — Race ends when `count` racers have crossed the finish; ranking is the current standings order.
+- topK (function): function topK(k: number): RaceWinCondition — Round-cut (Fall Guys): the first `k` finishers qualify; race resolves the moment `k` cross.
+- everyoneFinishes (function): function everyoneFinishes(): RaceWinCondition — Every non-eliminated racer must finish.
+- lastStanding (function): function lastStanding(): RaceWinCondition — Destruction-derby last-man-standing: ends when at most one racer is left un-eliminated.
+- createRaceState (function): function createRaceState(config: RaceStateConfig): RaceState
+- Checkpoint (interface): interface Checkpoint
+- RaceTrackConfig (interface): interface RaceTrackConfig
+- RaceTrack (interface): interface RaceTrack
+- RacerProgress (interface): interface RacerProgress
+- RaceEvent (type): type RaceEvent = | { type: "checkpoint.hit"; racerId: string; checkpoint: number; lap: number; time: number } | { type: "lap.completed"; racerId: string; lap: number; time: number } | { type: "position.changed"; racerId: string; position: number; previous: number } | { type: "race.finished"; ranking…
+- RaceWinCondition (type): type RaceWinCondition = (standings: readonly RacerProgress[], track: RaceTrack) => readonly string[] | null
+- RaceStateConfig (interface): interface RaceStateConfig
+- RaceState (class): class RaceState — Race state machine (issue #87). Drive it each tick with `update(now, positions)` — `now` is game time (`ctx.time`), `positions` maps each racer to a world point tested against the ordered checkpoint volumes. It emits `checkpoint.hit` / `lap.completed` / `position.changed` / `race.finished`, keeps cumulative split times for PB deltas, resolves a pluggable win condition (first-past-post, round-cut, derby last-standing), and `resetToCheckpoint` hands back a respawn pose at the racer's last checkpoint. `removeRacer` drops a racer mid-race and `reset` returns the whole instance to its pre-race state for reuse.
+
+### @jgengine/core/game/runDraft
+
+- createRunModifierStack (function): function createRunModifierStack<TStat extends string = string, TData = unknown>(offers: readonly RunModifierOffer<TStat, TData>[]): RunModifierStack<TStat, TData>
+- createRunDraft (function): function createRunDraft<TStat extends string = string, TData = unknown>(config: RunDraftConfig<TStat, TData>): RunDraft<TStat, TData>
+- RunModifierOffer (interface): interface RunModifierOffer<TStat extends string = string, TData = unknown>
+- RunModifierPick (interface): interface RunModifierPick
+- RunModifierStack (interface): interface RunModifierStack<TStat extends string = string, TData = unknown>
+- RunDraftConfig (interface): interface RunDraftConfig<TStat extends string = string, TData = unknown>
+- RunDraft (interface): interface RunDraft<TStat extends string = string, TData = unknown>
+
+### @jgengine/core/game/social
+
+- createSocial (function): function createSocial(deps: SocialDeps): Social
+- PresenceInfo (interface): interface PresenceInfo
+- EmoteEntityLookup (interface): interface EmoteEntityLookup
+- EmoteSpatialLookup (interface): interface EmoteSpatialLookup
+- EmotesDeps (interface): interface EmotesDeps
+- SocialDeps (interface): interface SocialDeps
+- FriendEntry (interface): interface FriendEntry
+- FriendsSnapshot (interface): interface FriendsSnapshot
+- FriendRequestEntry (interface): interface FriendRequestEntry
+- Friends (interface): interface Friends
+- PartyRole (type): type PartyRole = "leader" | "member"
+- PartyMemberEntry (interface): interface PartyMemberEntry
+- PartyConfig (interface): interface PartyConfig
+- PartyInviteEntry (interface): interface PartyInviteEntry
+- Party (interface): interface Party
+- DEFAULT_EMOTE_RADIUS (const): const DEFAULT_EMOTE_RADIUS: 20
+- EmoteBroadcastResult (interface): interface EmoteBroadcastResult
+- Emotes (interface): interface Emotes
+- WorldInviteTarget (interface): interface WorldInviteTarget
+- WorldInvite (interface): interface WorldInvite extends WorldInviteTarget
+- WorldInvites (interface): interface WorldInvites
+- Social (interface): interface Social
+
+### @jgengine/core/game/spawnPoints
+
+- createSpawnPoints (function): function createSpawnPoints(): SpawnPoints
+- SpawnPointPose (interface): interface SpawnPointPose
+- RespawnTarget (interface): interface RespawnTarget
+- SpawnPoints (interface): interface SpawnPoints
+
+### @jgengine/core/game/trade
+
+- canAffordCosts (function): function canAffordCosts(balances: Record<string, number>, costs: Record<string, number>): string | null
+- resolveBuy (function): function resolveBuy(itemId: string, trade: TradeField | null | undefined, shopId: string, count: number, balances: Record<string, number>): TradeResolution
+- resolveSell (function): function resolveSell(itemId: string, trade: TradeField | null | undefined, count: number): TradeResolution
+- applyTradeOutcome (function): function applyTradeOutcome(outcome: TradeOutcome, appliers: { adjustItem(itemId: string, count: number): { reason: string } | null; adjustCurrency(delta: Record<string, number>): void; }): { reason: string } | null
+- createTradeSystem (function): function createTradeSystem(deps: TradeSystemDeps): TradeSystem
+- TradeField (interface): interface TradeField
+- TradeRejection (interface): interface TradeRejection
+- TradeWallet (interface): interface TradeWallet
+- TradeInventory (interface): interface TradeInventory
+- TradeSystemDeps (interface): interface TradeSystemDeps
+- TradeParty (interface): interface TradeParty
+- TradeSystem (interface): interface TradeSystem
+- TradeOutcome (interface): interface TradeOutcome
+- TradeResolution (type): type TradeResolution = | { status: "ok"; outcome: TradeOutcome } | { status: "rejected"; reason: string }
+
+### @jgengine/core/game/unlocks
+
+- hasUnlock (function): function hasUnlock(granted: UnlockState, unlockId: string): boolean
+- grantUnlock (function): function grantUnlock(granted: UnlockState, unlockId: string): string[]
+- unlockTree (function): function unlockTree(defs: readonly UnlockDef[], categoryId: string): UnlockDef[]
+- createUnlockCatalog (function): function createUnlockCatalog(defs: readonly UnlockDef[] = []): UnlockCatalog
+- createUnlocks (function): function createUnlocks(defs: UnlockDef[] = []): Unlocks
+- UnlockDef (interface): interface UnlockDef
+- UnlockState (type): type UnlockState = readonly string[]
+- UnlockCatalog (interface): interface UnlockCatalog
+- Unlocks (interface): interface Unlocks
+
+### @jgengine/core/game/worldItem
+
+- scatterOffset (function): function scatterOffset(rng: () => number, options: ScatterOptions = DEFAULT_SCATTER): EntityPosition — Random offset within an annulus `[minRadius, radius]` around the origin — the on-death scatter impulse.
+- scatterPosition (function): function scatterPosition(origin: EntityPosition, rng: () => number, options: ScatterOptions = DEFAULT_SCATTER): EntityPosition
+- selectNearestWorldItem (function): function selectNearestWorldItem(candidates: readonly { instanceId: string; position: EntityPosition }[], from: EntityPosition, radius: number): string | null — Pure pickup-radius + nearest-item selection, usable without a live store (click-to-grab, proximity prompts).
+- createWorldItemStore (function): function createWorldItemStore(deps: WorldItemStoreDeps): WorldItemStore
+- resolveDeathDrops (function): function resolveDeathDrops(drops: readonly Drop[], options: ResolveDeathDropsOptions): ResolvedDeathDrops — Splits rolled death drops between direct grants and scattered ground items. `mode: "grant"` is the legacy behavior (loot straight to inventory); `mode: "world"` routes item drops through a scatter impulse and leaves currency drops granting directly (coins fly to the killer, gear hits the ground).
+- resolveWorldItemPresentation (function): function resolveWorldItemPresentation(item: LootFilterItem, rarityStyle: Record<string, RarityStyle> | undefined, rules: readonly LootFilterRule[] | undefined): WorldItemPresentation — Composes the baseline rarity→beam/color/label render binding (#32, catalog data the game supplies) with the loot-filter rule overrides (#33). A matching rule wins field-by-field; unmatched fields fall back to the rarity's baseline style.
+- WORLD_ITEM_ENTITY_NAME (const): const WORLD_ITEM_ENTITY_NAME: "world_item" — Scene-entity catalog name every dropped-item instance spawns under (see the three buckets: worldItem is an entity, never an inventory item or object).
+- DEFAULT_RARITY (const): const DEFAULT_RARITY: "common"
+- DEFAULT_PICKUP_RADIUS (const): const DEFAULT_PICKUP_RADIUS: 2
+- ScatterOptions (interface): interface ScatterOptions
+- DEFAULT_SCATTER (const): const DEFAULT_SCATTER: ScatterOptions
+- WorldItemRecord (interface): interface WorldItemRecord
+- WorldItemSpawnInput (interface): interface WorldItemSpawnInput
+- WorldItemStoreDeps (interface): interface WorldItemStoreDeps
+- WorldItemStore (interface): interface WorldItemStore
+- ResolveDeathDropsOptions (interface): interface ResolveDeathDropsOptions
+- ResolvedDeathDrops (interface): interface ResolvedDeathDrops
+- RarityStyle (interface): interface RarityStyle
+- WorldItemPresentation (interface): interface WorldItemPresentation
+
+### @jgengine/core/index
+
+- parseSaveAutoMs (function): function parseSaveAutoMs(auto: string): number
+- saveScopeIncludesPlayer (function): function saveScopeIncludesPlayer(scope: SaveScope): boolean
+- saveScopeIncludesChunks (function): function saveScopeIncludesChunks(scope: SaveScope): boolean
+- isSaveEnabled (function): function isSaveEnabled(config: SaveConfig): config is Exclude<SaveConfig, "none">
+- SaveScope (type): type SaveScope = "player" | "chunks" | "player+chunks"
+- SaveConfig (type): type SaveConfig = | "none" | { auto: string; scope: SaveScope; }
+- createEmptyServerRow (function): function createEmptyServerRow(): RuntimeServerRow
+- createEmptyPlayerRow (function): function createEmptyPlayerRow(userId: string): RuntimePlayerRow
+- createRuntimeSnapshot (function): function createRuntimeSnapshot(args: { gameId: string; serverId: string; server?: RuntimeServerRow; players?: Record<string, RuntimePlayerRow>; chunks?: Record<string, RuntimeChunkRow>; }): GameRuntimeSnapshot
+- markServerDirty (function): function markServerDirty(snapshot: GameRuntimeSnapshot): GameRuntimeSnapshot
+- markPlayerDirty (function): function markPlayerDirty(snapshot: GameRuntimeSnapshot, userId: string): GameRuntimeSnapshot
+- clearDirtyFlags (function): function clearDirtyFlags(snapshot: GameRuntimeSnapshot): GameRuntimeSnapshot
+- splitProfilePlayer (function): function splitProfilePlayer(player: RuntimePlayerRow): { persistent: RuntimePlayerRow; session: Record<string, unknown>; }
+- RUNTIME_SNAPSHOT_VERSION (const): const RUNTIME_SNAPSHOT_VERSION: 1
+- RuntimeEntityRow (type): type RuntimeEntityRow = { instanceId: string; catalogId: string; position?: [number, number, number]; rotationY?: number; parentSpace?: string; group?: string; stats?: Record<string, { current: number; max: number; min?: number }>; targetInstanceId?: string | null; userId?: string; }
+- RuntimeObjectRow (type): type RuntimeObjectRow = { instanceId: string; catalogId: string; position: [number, number, number]; rotationY?: number; parentSpace?: string; flags?: Record<string, unknown>; }
+- RuntimeInventorySlot (type): type RuntimeInventorySlot = { item: string; count: number; slot?: number; }
+- RuntimePlayerRow (type): type RuntimePlayerRow = { userId: string; inventories: Record<string, RuntimeInventorySlot[]>; economy: Record<string, number>; unlocks: string[]; quests?: unknown; social?: unknown; leaderboard?: Record<string, number>; session?: Record<string, unknown>; }
+- RuntimeChunkRow (type): type RuntimeChunkRow = { chunkKey: string; objects: RuntimeObjectRow[]; entities: RuntimeEntityRow[]; flags?: Record<string, unknown>; }
+- RuntimeServerRow (type): type RuntimeServerRow = { entities: RuntimeEntityRow[]; objects: RuntimeObjectRow[]; session: Record<string, unknown>; feeds?: Record<string, unknown[]>; }
+- RuntimeProfileRow (type): type RuntimeProfileRow = { userId: string; gameId: string; player: RuntimePlayerRow; updatedAt: number; }
+- GameRuntimeSnapshot (type): type GameRuntimeSnapshot = { version: number; gameId: string; serverId: string; server: RuntimeServerRow; players: Record<string, RuntimePlayerRow>; chunks: Record<string, RuntimeChunkRow>; revision: number; dirty: { server: boolean; players: string[]; chunks: string[]; }; }
+- runCommand (function): function runCommand<TInput>(snapshot: import("./snapshot").GameRuntimeSnapshot, commands: Record<string, CommandDef<TInput>>, commandName: string, input: TInput, actorUserId: string): RunCommandResult
+- CommandValidationError (type): type CommandValidationError = { reason: string }
+- CommandDef (type): type CommandDef<TInput = unknown> = { validate: (snapshot: import("./snapshot").GameRuntimeSnapshot, input: TInput) => CommandValidationError | null; apply: ( snapshot: import("./snapshot").GameRuntimeSnapshot, input: TInput, ) => import("./snapshot").GameRuntimeSnapshot; }
+- RunCommandResult (type): type RunCommandResult = | { ok: true; snapshot: import("./snapshot").GameRuntimeSnapshot } | { ok: false; reason: string }
+- createGameRuntime (function): function createGameRuntime(definition: GameRuntimeDefinition): GameRuntime
+- ServerLoopHooks (type): type ServerLoopHooks = { onInit?: (ctx: RuntimeInitContext) => void; onNewPlayer?: (ctx: RuntimeLoopContext) => void; onTick?: (ctx: RuntimeLoopContext, dtSeconds: number) => void; }
+- RuntimeInitContext (type): type RuntimeInitContext = { snapshot: GameRuntimeSnapshot; setSnapshot: (snapshot: GameRuntimeSnapshot) => void; }
+- RuntimeLoopContext (type): type RuntimeLoopContext = RuntimeInitContext & { player: { userId: string; isNew: boolean; }; }
+- GameRuntimeDefinition (type): type GameRuntimeDefinition = { gameId: string; save: SaveConfig; commands: Record<string, CommandDef>; loop?: ServerLoopHooks; }
+- HydrateInput (type): type HydrateInput = { gameId: string; serverId: string; serverRow: RuntimeServerRow; playersByUserId: Record<string, RuntimePlayerRow>; chunksByKey: Record<string, RuntimeChunkRow>; }
+- GameRuntime (type): type GameRuntime = { gameId: string; save: SaveConfig; hydrate: (input: HydrateInput) => GameRuntimeSnapshot; runCommand: ( snapshot: GameRuntimeSnapshot, actorUserId: string, commandName: string, input: unknown, ) => ReturnType<typeof runCommand>; tick: (snapshot: GameRuntimeSnapshot, dtSeconds: nu…
+- convex (function): function convex(config?: { topology?: MultiplayerTopology }): MultiplayerAdapterConfig
+- ws (function): function ws(config?: { topology?: MultiplayerTopology; url?: string }): MultiplayerAdapterConfig
+- fly (function): function fly(config: { app: string; topology?: MultiplayerTopology; path?: string }): MultiplayerAdapterConfig
+- socketIo (function): function socketIo(config?: { topology?: MultiplayerTopology; url?: string }): MultiplayerAdapterConfig
+- p2p (function): function p2p(config?: { topology?: MultiplayerTopology; room?: string }): MultiplayerAdapterConfig
+- lan (function): function lan(config?: { topology?: MultiplayerTopology; port?: number; path?: string; }): MultiplayerAdapterConfig
+- offline (function): function offline(): MultiplayerAdapterConfig
+- adapterOf (function): function adapterOf(multiplayer: unknown): MultiplayerAdapterConfig | null
+- multiplayerAdapterKind (function): function multiplayerAdapterKind(multiplayer: unknown): string | null
+- servers (function): function servers(config: ServersPoolConfig): import("/home/runner/work/jgengine/jgengine/packages/core/src/runtime/adapter").ServersPoolConfig
+- MultiplayerTopology (type): type MultiplayerTopology = "shared" | "lobbies" | "private"
+- MultiplayerAdapterConfig (type): type MultiplayerAdapterConfig = | { kind: "convex"; topology?: MultiplayerTopology } | { kind: "ws"; topology?: MultiplayerTopology; url?: string } | { kind: "socketio"; topology?: MultiplayerTopology; url?: string } | { kind: "p2p"; topology?: MultiplayerTopology; room?: string } | { kind: "lan"; t…
+- ServersPoolConfig (type): type ServersPoolConfig = { maxServers: number; slotsPerServer: number; minPlayersToStart?: number; adapter: MultiplayerAdapterConfig; }
+- JoinServerResult (type): type JoinServerResult = { serverId: string; isNew: boolean; }
+- RunCommandArgs (type): type RunCommandArgs = { serverId: string; command: string; input: unknown; }
+- TransportRunCommandResult (type): type TransportRunCommandResult = | { ok: true } | { ok: false; reason: string }
+- GameRuntimeServerView (type): type GameRuntimeServerView = { serverId: string; gameId: string; revision: number; memberUserIds: string[]; serverState: unknown; updatedAt: number; }
+- GameRuntimePlayerView (type): type GameRuntimePlayerView = { userId: string; gameId: string; playerState: unknown; updatedAt: number; }
+- GameRuntimeFeedView (type): type GameRuntimeFeedView = { action: string; entries: unknown[]; }
+- GameRuntimeTransport (type): type GameRuntimeTransport = { joinServer: (args: { gameId: string; serverId?: string }) => Promise<JoinServerResult>; leaveServer: (args: { serverId: string }) => Promise<void>; runCommand: (args: RunCommandArgs) => Promise<TransportRunCommandResult>; }
+- FeedUnsubscribe (type): type FeedUnsubscribe = () => void
+- GameRuntimeFeeds (type): type GameRuntimeFeeds = { subscribeServer: ( serverId: string, onChange: (view: GameRuntimeServerView | null) => void, ) => FeedUnsubscribe; subscribePlayer: ( args: { serverId: string }, onChange: (view: GameRuntimePlayerView | null) => void, ) => FeedUnsubscribe; subscribeFeed: ( args: { serverId:…
+- GameBackend (type): type GameBackend<TPresenceRow = unknown, TPresenceLocation = unknown, TGameId extends string = string> = { transport: GameRuntimeTransport; feeds?: GameRuntimeFeeds; presence?: PresenceTransport<TPresenceRow, TPresenceLocation, TGameId>; }
+- PresencePoseRow (type): type PresencePoseRow = { userId: string; position: { x: number; y: number; z: number }; rotationY: number; rotationPitch: number; lastSeenAt: number; }
+- PresenceSync (type): type PresenceSync = { subscribe: (serverId: string, onChange: (rows: PresencePoseRow[]) => void) => FeedUnsubscribe; syncPose: (serverId: string, pose: PlayerPose) => void; }
+- LiveGameBackend (type): type LiveGameBackend<TPresenceRow = unknown, TPresenceLocation = unknown, TGameId extends string = string> = GameBackend<TPresenceRow, TPresenceLocation, TGameId> & { presenceSync: PresenceSync; pushFeedEntry: (args: { serverId: string; action: string; entry: unknown }) => Promise<void>; chatSyncFor…
+- MultiplayerSession (type): type MultiplayerSession = { gameId: string; userId: string; backend: LiveGameBackend; feedActions: string[]; }
+
+### @jgengine/core/input/actionBindings
+
+- bindingMatches (function): function bindingMatches<TCode extends string>(code: TCode, binding: ActionBinding<TCode>): boolean
+- resolveBoundAction (function): function resolveBoundAction<TAction extends string, TCode extends string>(code: TCode, bindings: ActionBindingMap<TAction, TCode>): TAction | null — First action (in the map's key order) bound to the given control code, or null.
+- normalizeKeyCode (function): function normalizeKeyCode(code: string): string — Collapse left/right modifier variants of a KeyboardEvent.code so bindings store one logical key.
+- actionRepeatMs (function): function actionRepeatMs(codes: ActionCodes | undefined): number | undefined
+- shouldDispatchAction (function): function shouldDispatchAction({ pressed, down, repeatMs, lastFiredAt, now }: ShouldDispatchActionInput): boolean
+- toActionStateBindingMap (function): function toActionStateBindingMap<TAction extends string, TCode extends string>(map: ActionCodesMap<TAction, TCode>): ActionStateBindingMap<TAction, TCode>
+- hotbarSlotBindings (function): function hotbarSlotBindings(count: number, options?: { action?: (slot: number) => string }): ActionCodesMap
+- hotbarSlotActionIndex (function): function hotbarSlotActionIndex(action: string): number | null — 0-based slot index for a hotbar-slot action name (`slot1`, `hotbarSlot1`), or null.
+- isHotbarSlotAction (function): function isHotbarSlotAction(action: string): boolean
+- resolveActionCommand (function): function resolveActionCommand(action: string, has: (command: string) => boolean, reserved: ReadonlySet<string>): string | null — Convention mapping a bound input action to the command it fires: the action's own name when a command by that name exists, otherwise a `ui.<action>` fallback. Reserved actions (consumed natively by the shell) and hotbar slots yield null so the shell can handle them itself.
+- bindingLabel (function): function bindingLabel(code: string): string
+- actionLabel (function): function actionLabel(map: ActionCodesMap, action: string): string | null — Short display label for an action's first bound code, or null when unbound.
+- createActionStateTracker (function): function createActionStateTracker<TAction extends string, TCode extends string = string>(map: ActionStateBindingMap<TAction, TCode>): ActionStateTracker<TAction>
+- ActionBinding (interface): interface ActionBinding<TCode extends string = string> — Action-binding model: games bind semantic actions ("jump", "interact") to physical control codes; capture layers resolve raw events through this map so gameplay code never sees keycodes. Control codes are plain strings, so the same model serves keyboard codes, mouse buttons, touch controls, or gamepad inputs.
+- ActionBindingMap (type): type ActionBindingMap<TAction extends string, TCode extends string = string> = Record< TAction, ActionBinding<TCode> >
+- ActionBindingModes (interface): interface ActionBindingModes<TCode extends string = string>
+- ActionBindingConfig (type): type ActionBindingConfig<TCode extends string = string> = ActionBinding<TCode>[] | ActionBindingModes<TCode>
+- ActionStateBindingMap (type): type ActionStateBindingMap<TAction extends string, TCode extends string = string> = Record< TAction, ActionBindingConfig<TCode> >
+- ActionCodes (type): type ActionCodes<TCode extends string = string> = | readonly TCode[] | { hold?: readonly TCode[]; toggle?: readonly TCode[]; repeatMs?: number }
+- ActionCodesMap (type): type ActionCodesMap<TAction extends string = string, TCode extends string = string> = Record< TAction, ActionCodes<TCode> >
+- ShouldDispatchActionInput (interface): interface ShouldDispatchActionInput
+- ActionStateTracker (interface): interface ActionStateTracker<TAction extends string>
+
+### @jgengine/core/input/axisInput
+
+- clampAxis (function): function clampAxis(value: number, range: AxisRange): number
+- rampToward (function): function rampToward(current: number, target: number, rate: number, dt: number): number
+- AxisInput (interface): interface AxisInput
+- NEUTRAL_AXIS (const): const NEUTRAL_AXIS: AxisInput
+- AxisName (type): type AxisName = keyof AxisInput
+- AxisBinding (interface): interface AxisBinding
+- AxisBindingMap (type): type AxisBindingMap = Record<AxisName, AxisBinding>
+- AxisChannelConfig (interface): interface AxisChannelConfig
+- AxisRange (interface): interface AxisRange
+- AXIS_RANGE (const): const AXIS_RANGE: Record<AxisName, AxisRange>
+- AxisChannel (class): class AxisChannel — Analog control channel — distinct from the digital action bindings. Throttle/brake/steer/handbrake are continuous values ramped from held keys (a keyboard feels like a pedal) or driven directly from a gamepad axis via `setAnalog`. `sample(dt, isDown)` folds the current held-key state into the smoothed value; a `setAnalog` override replaces the digital target for that axis until cleared.
+- DRIVE_AXIS_BINDINGS (const): const DRIVE_AXIS_BINDINGS: AxisBindingMap
+
+### @jgengine/core/input/gestureSurface
+
+- createGestureSurfaceTracker (function): function createGestureSurfaceTracker(bindings: TouchGestureBindings, tuning: GestureSurfaceTuning = DEFAULT_GESTURE_TUNING): GestureSurfaceTracker
+- GestureSurfaceTuning (interface): interface GestureSurfaceTuning
+- DEFAULT_GESTURE_TUNING (const): const DEFAULT_GESTURE_TUNING: GestureSurfaceTuning
+- GestureSurfaceTracker (interface): interface GestureSurfaceTracker
+
+### @jgengine/core/input/lookChannel
+
+- createLookChannel (function): function createLookChannel({ sensitivity, maxVerticalOffset = Infinity }: LookChannelOptions): LookChannel
+- LookDeltas (interface): interface LookDeltas — Per-frame look channel shared between an event-driven capture layer (writer of raw pointer deltas) and a frame-driven controller (consumer), plus the latest committed pose for same-frame readers such as presence sync. Kept as plain mutable state on purpose: routing per-frame deltas through a reactive store would notify subscribers every frame for state no UI reads.
+- LookChannel (interface): interface LookChannel
+- LookChannelOptions (interface): interface LookChannelOptions
+
+### @jgengine/core/input/pointer
+
+- aimToPoint (function): function aimToPoint(origin: PointerVec3, point: PointerVec3): Aim — Build an `origin → point` aim for `item.use` / projectiles, firing toward the cursor.
+- moveTargetFromHit (function): function moveTargetFromHit(hit: PointerHit): PointerVec3 — The move-to target of a pointer hit — sugar over `hit.point`.
+- groundOf (function): function groundOf(hit: PointerHit): readonly [number, number] — Project a pointer hit onto the XZ plane for navmesh routing (`findPath` takes `[x, z]`).
+- createDragCapture (function): function createDragCapture(config: DragCaptureConfig = {}): DragCapture
+- PointerVec3 (type): type PointerVec3 = readonly [number, number, number]
+- PointerHit (interface): interface PointerHit — Renderer-free result of a screen→world raycast. The shell's pointer service produces this from the cursor; core-side gameplay (item.use aim, click-to-move, ground-target abilities, pings) consumes it without touching three.js.
+- PointerButton (type): type PointerButton = "primary" | "secondary" | "middle"
+- DragState (interface): interface DragState — Snapshot of an in-progress or just-released drag: origin/current cursor points plus the clamped pull vector.
+- DragResult (type): type DragResult = DragState
+- DragCaptureConfig (interface): interface DragCaptureConfig
+- DragCapture (interface): interface DragCapture — Renderer-agnostic drag-capture / pull-vector state machine for slingshot-style aiming, drawback abilities, and similar gestures.
+
+### @jgengine/core/input/touchGestures
+
+- createTouchGestureTracker (function): function createTouchGestureTracker(tuning: TouchGestureTuning): TouchGestureTracker
+- TouchGestureTuning (interface): interface TouchGestureTuning — Single-finger gesture disambiguation for touch look controls: one touch stream drives look-drag, tap, and long-press-hold without fighting. Movement past the tap threshold commits the gesture to "look" and cancels tap/hold; a still finger that lifts quickly is a tap; a still finger held past the long-press delay is a hold. Timestamps are injected so the state machine stays pure; the capture layer owns timers and touch identifiers.
+- TouchGestureEnd (type): type TouchGestureEnd = "tap" | "hold-end" | null
+- TouchGestureTracker (interface): interface TouchGestureTracker
+
+### @jgengine/core/input/touchScheme
+
+- touchCode (function): function touchCode(action: string): string
+- withTouchCodes (function): function withTouchCodes(map: ActionCodesMap | undefined): ActionCodesMap — Every action gains a synthetic touch code alongside its physical codes.
+- touchActionLabel (function): function touchActionLabel(action: string): string
+- deriveTouchScheme (function): function deriveTouchScheme(input: ActionCodesMap | undefined, { reserved, firstPerson, config }: DeriveTouchSchemeOptions): TouchScheme | null — Null means "render no touch controls" — either the game opted out or there is nothing to synthesize.
+- TOUCH_CODE_PREFIX (const): const TOUCH_CODE_PREFIX: "touch:"
+- TouchDragBinding (interface): interface TouchDragBinding
+- TouchGestureBindings (interface): interface TouchGestureBindings
+- TouchButtonSpec (interface): interface TouchButtonSpec
+- TouchControlsConfig (interface): interface TouchControlsConfig
+- TouchJoystick (interface): interface TouchJoystick
+- TouchButton (interface): interface TouchButton
+- TouchScheme (interface): interface TouchScheme
+- DeriveTouchSchemeOptions (interface): interface DeriveTouchSchemeOptions
+
+### @jgengine/core/interaction/contextMenu
+
+- contextVerb (function): function contextVerb(label: string, command: string, args?: Record<string, unknown>): ContextVerb
+- buildContextMenu (function): function buildContextMenu(input: BuildContextMenuInput): ContextMenu | null — Assemble a menu from a target's catalog verbs; null when the target lists none.
+- contextVerbInput (function): function contextVerbInput(menu: ContextMenu, verb: ContextVerb): Record<string, unknown> — Command input a chosen verb dispatches: the verb's own args, plus the target id and the world point, so a single handler can walk the actor to the target then perform it.
+- ContextTargetKind (type): type ContextTargetKind = "entity" | "object"
+- ContextVerb (interface): interface ContextVerb — One right-click verb: a label plus the command it dispatches (walk-then-act supported by args).
+- ContextMenu (interface): interface ContextMenu
+- BuildContextMenuInput (interface): interface BuildContextMenuInput
+
+### @jgengine/core/interaction/proximityPrompt
+
+- keybind (function): function keybind(actionId: string): KeybindPromptDisplay
+- gauge (function): function gauge(gaugeId: string): GaugePromptDisplay
+- label (function): function label(text: string): LabelPromptDisplay
+- command (function): function command(name: string, input?: unknown): PromptCommand
+- proximityPrompt (function): function proximityPrompt({ radius, display, invoke = null }: ProximityPromptConfig): ProximityPrompt
+- resolveActivePrompt (function): function resolveActivePrompt<T extends PositionedPrompt>(playerPosition: PromptPoint, prompts: readonly T[]): T | null — Nearest prompt strictly within its radius wins; a higher-priority prompt in range beats any lower-priority one regardless of distance; equal priority and distance keep the earliest prompt in the list.
+- promptDisplaysEqual (function): function promptDisplaysEqual(a: ProximityPromptDisplay, b: ProximityPromptDisplay): boolean
+- promptCommandsEqual (function): function promptCommandsEqual(a: PromptCommand | null, b: PromptCommand | null): boolean
+- positionedPromptsEqual (function): function positionedPromptsEqual(a: PositionedPrompt, b: PositionedPrompt): boolean
+- PromptPoint (interface): interface PromptPoint
+- KeybindPromptDisplay (interface): interface KeybindPromptDisplay
+- GaugePromptDisplay (interface): interface GaugePromptDisplay
+- LabelPromptDisplay (interface): interface LabelPromptDisplay
+- ProximityPromptDisplay (type): type ProximityPromptDisplay = KeybindPromptDisplay | GaugePromptDisplay | LabelPromptDisplay
+- PromptCommand (interface): interface PromptCommand
+- ProximityPrompt (interface): interface ProximityPrompt
+- ProximityPromptConfig (interface): interface ProximityPromptConfig
+- PositionedPrompt (interface): interface PositionedPrompt
+
+### @jgengine/core/interaction/qte
+
+- evaluateQteSequence (function): function evaluateQteSequence(steps: readonly QteStep[], inputs: readonly QteInputEvent[]): QteOutcome
+- pendingQteStep (function): function pendingQteStep(steps: readonly QteStep[], elapsedSeconds: number): QteStep | null
+- qteProgress (function): function qteProgress(steps: readonly QteStep[], elapsedSeconds: number): number
+- QteStep (interface): interface QteStep
+- QteInputEvent (interface): interface QteInputEvent
+- QteOutcome (type): type QteOutcome = | { status: "success" } | { status: "fail"; atStep: string; reason: "missed-window" | "wrong-action" | "too-early" }
+
+### @jgengine/core/interaction/skillCheck
+
+- skillCheckMarkerPosition (function): function skillCheckMarkerPosition(config: SkillCheckConfig, elapsedSeconds: number): number
+- skillCheckZoneAt (function): function skillCheckZoneAt(config: SkillCheckConfig, elapsedSeconds: number): SkillCheckZone
+- evaluateSkillCheck (function): function evaluateSkillCheck(config: SkillCheckConfig, elapsedSeconds: number): SkillCheckResult
+- SkillCheckZone (interface): interface SkillCheckZone
+- SkillCheckConfig (interface): interface SkillCheckConfig
+- SkillCheckResult (interface): interface SkillCheckResult
+
+### @jgengine/core/inventory/inventoryModel
+
+- createEmptyInventory (function): function createEmptyInventory(layout: InventoryLayout): InventoryState
+- putItem (function): function putItem(state: InventoryState, layout: InventoryLayout, traits: ItemTraits, itemId: string, count: number, options?: { slot?: number }): PutResult
+- takeItem (function): function takeItem(state: InventoryState, itemId: string, count: number): TakeResult
+- countItem (function): function countItem(state: InventoryState, itemId: string): number
+- hasItem (function): function hasItem(state: InventoryState, itemId: string, count: number): boolean
+- moveItem (function): function moveItem(from: InventoryState, fromSlot: number, to: InventoryState, toLayout: InventoryLayout, traits: ItemTraits, toSlot?: number): MoveResult
+- createInventorySet (function): function createInventorySet<TId extends string>(layouts: Record<TId, InventoryLayout>, traits: ItemTraits): InventorySet<TId>
+- ItemTraits (interface): interface ItemTraits
+- InventoryLayout (interface): interface InventoryLayout
+- InventorySlot (type): type InventorySlot = { itemId: string; count: number } | null
+- InventoryState (interface): interface InventoryState
+- PutResult (type): type PutResult = | { status: "ok"; state: InventoryState } | { status: "rejected"; reason: "no-space" | "wrong-kind" | "slot-occupied" | "invalid-slot" }
+- TakeResult (type): type TakeResult = { status: "ok"; state: InventoryState } | { status: "rejected"; reason: "insufficient" }
+- MoveResult (type): type MoveResult = | { status: "ok"; from: InventoryState; to: InventoryState } | { status: "rejected"; reason: "invalid-slot" | "empty-slot" | "wrong-kind" | "no-space" }
+- InventorySet (interface): interface InventorySet<TId extends string>
+
+### @jgengine/core/inventory/shapedGrid
+
+- normalizeFootprint (function): function normalizeFootprint(footprint: Footprint): Footprint
+- rotateFootprint (function): function rotateFootprint(footprint: Footprint, rotation: Rotation): Footprint
+- occupiedCells (function): function occupiedCells(footprint: Footprint, origin: Cell, rotation: Rotation): Cell[]
+- createShapedGrid (function): function createShapedGrid<T>(width: number, height: number): ShapedGrid<T>
+- canPlace (function): function canPlace<T>(grid: ShapedGrid<T>, footprint: Footprint, origin: Cell, rotation: Rotation, ignoreId?: string): ShapedRejection | null
+- placeShaped (function): function placeShaped<T>(grid: ShapedGrid<T>, item: ShapedItem<T>, origin: Cell, rotation: Rotation = 0): ShapedResult<T>
+- removeShaped (function): function removeShaped<T>(grid: ShapedGrid<T>, id: string): ShapedResult<T>
+- moveShaped (function): function moveShaped<T>(grid: ShapedGrid<T>, id: string, origin: Cell, rotation?: Rotation): ShapedResult<T>
+- cellOccupant (function): function cellOccupant<T>(grid: ShapedGrid<T>, cell: Cell): string | null
+- gridAdjacencyQuery (function): function gridAdjacencyQuery<T>(grid: ShapedGrid<T>, options: { diagonal?: boolean } = {}): GridAdjacencyQuery
+- cellFromPoint (function): function cellFromPoint(point: { x: number; y: number }, cellSize: number, gridOrigin: { x: number; y: number } = { x: 0, y: 0 }): Cell
+- Cell (type): type Cell = readonly [number, number]
+- Footprint (type): type Footprint = readonly Cell[]
+- Rotation (type): type Rotation = 0 | 1 | 2 | 3
+- ShapedItem (interface): interface ShapedItem<T>
+- Placement (interface): interface Placement<T>
+- ShapedGrid (interface): interface ShapedGrid<T>
+- ShapedRejection (type): type ShapedRejection = "out-of-bounds" | "overlap" | "duplicate-id" | "unknown-id"
+- ShapedPlaceResult (interface): interface ShapedPlaceResult<T>
+- ShapedRejected (interface): interface ShapedRejected
+- ShapedResult (type): type ShapedResult<T> = ShapedPlaceResult<T> | ShapedRejected
+- GridAdjacencyQuery (interface): interface GridAdjacencyQuery
+
+### @jgengine/core/inventory/slotModel
+
+- createSlots (function): function createSlots<T>(size: number): Slot<T>[]
+- normalizeSlots (function): function normalizeSlots<T>(values: SlotGrid<T>, size: number): Slot<T>[]
+- placeAt (function): function placeAt<T>(grid: SlotGrid<T>, index: number, value: T): SlotResult<T>
+- removeAt (function): function removeAt<T>(grid: SlotGrid<T>, index: number): SlotResult<T>
+- moveSlot (function): function moveSlot<T>(grid: SlotGrid<T>, from: number, to: number): SlotResult<T>
+- firstEmpty (function): function firstEmpty<T>(grid: SlotGrid<T>): number | null
+- insertFirst (function): function insertFirst<T>(grid: SlotGrid<T>, value: T): SlotResult<T>
+- compactSlots (function): function compactSlots<T>(grid: SlotGrid<T>): Slot<T>[]
+- countFilled (function): function countFilled<T>(grid: SlotGrid<T>): number
+- indexOfSlot (function): function indexOfSlot<T>(grid: SlotGrid<T>, match: (value: T, index: number) => boolean): number | null
+- Slot (type): type Slot<T> = T | null
+- SlotGrid (type): type SlotGrid<T> = readonly Slot<T>[]
+- SlotResult (type): type SlotResult<T> = | { status: "ok"; grid: Slot<T>[] } | { status: "rejected"; reason: "invalid-slot" | "slot-occupied" | "empty-slot" }
+
+### @jgengine/core/inventory/storageTier
+
+- tierOf (function): function tierOf(tiers: Record<string, StorageTier>, inventoryId: string): StorageTier
+- partitionOnDeath (function): function partitionOnDeath(containers: readonly ContainerSnapshot[]): DeathPartition
+- createDeliveryQueue (function): function createDeliveryQueue(): DeliveryQueue
+- insureLost (function): function insureLost(lost: readonly ItemStack[], policy: InsurancePolicy, userId: string, now: number, rng: () => number = Math.random): ScheduledDelivery | null
+- resolveConsolation (function): function resolveConsolation(policy: ConsolationPolicy, partition: DeathPartition): { loadoutId: string } | null
+- StorageTier (type): type StorageTier = "carried" | "banked"
+- ItemStack (interface): interface ItemStack
+- ContainerSnapshot (interface): interface ContainerSnapshot
+- DeathPartition (interface): interface DeathPartition
+- DeliveryEntry (interface): interface DeliveryEntry
+- ScheduledDelivery (interface): interface ScheduledDelivery
+- DeliveryQueue (interface): interface DeliveryQueue
+- InsurancePolicy (interface): interface InsurancePolicy
+- ConsolationPolicy (interface): interface ConsolationPolicy
+
+### @jgengine/core/item/affix
+
+- createAffixRoller (function): function createAffixRoller(config: RollerConfig): AffixRoller
+- AffixOp (type): type AffixOp = "add" | "mul"
+- AffixDef (interface): interface AffixDef
+- AffixPool (interface): interface AffixPool
+- RarityTier (interface): interface RarityTier
+- ItemBaseDef (interface): interface ItemBaseDef
+- RollerConfig (interface): interface RollerConfig
+- RolledAffix (interface): interface RolledAffix
+- RolledItem (interface): interface RolledItem
+- seededRng (function): function seededRng(seed: string | number): () => number
+- AffixRoller (interface): interface AffixRoller
+
+### @jgengine/core/item/durability
+
+- createDurability (function): function createDurability(spec: DurabilitySpec): DurabilityState
+- durabilityFraction (function): function durabilityFraction(state: DurabilityState): number
+- isBroken (function): function isBroken(state: DurabilityState): boolean
+- isDisabled (function): function isDisabled(spec: DurabilitySpec, state: DurabilityState): boolean
+- wearAmount (function): function wearAmount(spec: DurabilitySpec, kind: WearKind): number
+- applyWear (function): function applyWear(state: DurabilityState, amount: number): DurabilityState
+- wear (function): function wear(spec: DurabilitySpec, state: DurabilityState, kind: WearKind, times = 1): DurabilityState
+- canRepairAt (function): function canRepairAt(spec: DurabilitySpec, stationId?: string): boolean
+- repairQuote (function): function repairQuote(spec: DurabilitySpec, state: DurabilityState, options?: { to?: number; station?: string }): RepairQuote | null
+- createDurabilityTracker (function): function createDurabilityTracker(): DurabilityTracker
+- RepairMaterial (interface): interface RepairMaterial
+- RepairSpec (interface): interface RepairSpec
+- DurabilitySpec (interface): interface DurabilitySpec
+- DurabilityState (interface): interface DurabilityState
+- WearKind (type): type WearKind = "use" | "hit"
+- RepairCost (interface): interface RepairCost
+- RepairQuote (interface): interface RepairQuote
+- DurabilityTracker (interface): interface DurabilityTracker
+
+### @jgengine/core/item/modularItem
+
+- slotById (function): function slotById(def: ModularItemDef, slotId: string): MountSlotDef | null
+- slotAccepts (function): function slotAccepts(slot: MountSlotDef, category: string): boolean
+- install (function): function install(def: ModularItemDef, installed: readonly InstalledPart[], slotId: string, part: PartDef): InstallResult
+- uninstall (function): function uninstall(installed: readonly InstalledPart[], slotId: string): readonly InstalledPart[]
+- partInSlot (function): function partInSlot(installed: readonly InstalledPart[], slotId: string): PartDef | null
+- computeEffectiveStats (function): function computeEffectiveStats(def: ModularItemDef, installed: readonly InstalledPart[]): Record<string, number>
+- missingRequiredSlots (function): function missingRequiredSlots(def: ModularItemDef, installed: readonly InstalledPart[]): string[]
+- isComplete (function): function isComplete(def: ModularItemDef, installed: readonly InstalledPart[]): boolean
+- createModularItem (function): function createModularItem(def: ModularItemDef, initial: readonly InstalledPart[] = []): ModularItem
+- MountSlotDef (interface): interface MountSlotDef
+- ModularItemDef (interface): interface ModularItemDef
+- PartDef (interface): interface PartDef
+- InstalledPart (interface): interface InstalledPart
+- InstallResult (type): type InstallResult = | { status: "ok"; installed: readonly InstalledPart[] } | { status: "rejected"; reason: "unknown-slot" | "wrong-category" | "slot-occupied" }
+- ModularItem (interface): interface ModularItem
+
+### @jgengine/core/item/use
+
+- createItemUse (function): function createItemUse<TState>(resolveUse: (itemId: string) => string | null | undefined): ItemUse<TState>
+- ItemUseInput (interface): interface ItemUseInput
+- ItemUseRejection (interface): interface ItemUseRejection
+- ItemUseResult (interface): interface ItemUseResult<TState>
+- ItemUseHandler (interface): interface ItemUseHandler<TState>
+- ItemUse (interface): interface ItemUse<TState>
+
+### @jgengine/core/item/weapon
+
+- getWeaponStat (function): function getWeaponStat(entry: WeaponEntry | null | undefined, stat: string): number | null
+- createWeaponStats (function): function createWeaponStats(resolveEntry: (itemId: string) => WeaponEntry | null | undefined): WeaponStats
+- WeaponEntry (interface): interface WeaponEntry
+- WeaponStats (interface): interface WeaponStats
+
+### @jgengine/core/meta/changelog
+
+- VERSION (const): const VERSION: "0.8.0"
+- ChangelogEntry (interface): interface ChangelogEntry
+- CHANGELOG (const): const CHANGELOG: Record<string, ChangelogEntry>
+
+### @jgengine/core/movement/avatarGait
+
+- advanceGaitPhase (function): function advanceGaitPhase(phase: number, speedUnitsPerSec: number, dtSec: number, tuning: GaitTuning = DEFAULT_GAIT_TUNING): number
+- gaitBobOffset (function): function gaitBobOffset(phase: number, speedUnitsPerSec: number, tuning: GaitTuning = DEFAULT_GAIT_TUNING): number — Vertical hop per footfall — two peaks per stride cycle.
+- gaitSwayAngle (function): function gaitSwayAngle(phase: number, speedUnitsPerSec: number, tuning: GaitTuning = DEFAULT_GAIT_TUNING): number — Signed side-to-side lean alternating with each footfall.
+- GaitTuning (interface): interface GaitTuning
+- DEFAULT_GAIT_TUNING (const): const DEFAULT_GAIT_TUNING: GaitTuning
+
+### @jgengine/core/movement/cameraRig
+
+- clampCameraPitch (function): function clampCameraPitch(pitch: number): number
+- resolveTargetEyeHeight (function): function resolveTargetEyeHeight(crouching: boolean, grounded: boolean): number
+- advanceEyeHeight (function): function advanceEyeHeight(currentEyeHeight: number, targetEyeHeight: number, deltaSeconds: number): number
+- resolveHeadBobRate (function): function resolveHeadBobRate(crouching: boolean, running: boolean): number
+- resolveHeadBobAmplitude (function): function resolveHeadBobAmplitude(crouching: boolean, running: boolean, grounded: boolean): number
+- advanceHeadBobTime (function): function advanceHeadBobTime(currentHeadBobTime: number, moving: boolean, grounded: boolean, bobRate: number, deltaSeconds: number): number
+- resolveHeadBobOffset (function): function resolveHeadBobOffset(headBobTime: number, bobAmplitude: number): number
+- resolveCameraTrackingBlend (function): function resolveCameraTrackingBlend(deltaSeconds: number): number
+- CAMERA_PITCH_LIMIT (const): const CAMERA_PITCH_LIMIT: 1.45
+
+### @jgengine/core/movement/dash
+
+- iframeActive (function): function iframeActive(config: DashConfig, elapsedMs: number): boolean
+- dashEase (function): function dashEase(t: number): number
+- dashOffset (function): function dashOffset(config: DashConfig, dir: DashDirection, elapsedMs: number): [number, number, number]
+- createDashState (function): function createDashState(config: DashConfig): DashState
+- DashConfig (interface): interface DashConfig
+- DashDirection (interface): interface DashDirection
+- DashRejection (type): type DashRejection = { reason: "no-stamina" | "cooldown" | "dashing" }
+- DashBurst (interface): interface DashBurst
+- DashState (interface): interface DashState
+
+### @jgengine/core/movement/movementModel
+
+- createEmptyMovementKeys (function): function createEmptyMovementKeys(): MovementKeysState
+- resolveMovementIntent (function): function resolveMovementIntent(keys: MovementKeysState, canMove: boolean): MovementIntent — Translate the set of held keys into an intent. When `canMove` is false (a menu is open, the world is paused) the avatar is fully idle so it never drifts behind an overlay.
+- createPlayerMotionState (function): function createPlayerMotionState(): PlayerMotionState
+- advancePlayerMotion (function): function advancePlayerMotion(motion: PlayerMotionState, intent: MovementIntent, forwardX: number, forwardZ: number, baseSpeed: number, rawDeltaSeconds: number, tuning?: MovementTuningOverrides): MovementFrameStep — Advance one frame of avatar kinematics. Mutates `motion` (velocity, jump, gravity, grounded) and returns the horizontal step to commit through the collision-resolving stepper.
+- resolveObstacleStep (function): function resolveObstacleStep(current: readonly [number, number, number], stepX: number, stepZ: number, obstacles: readonly CollisionObstacle[], playerRadius: number = DEFAULT_OBSTACLE_PLAYER_RADIUS): MovementFrameStep — Resolve a horizontal step against nearby placed objects with classic axis-separated sliding (try X, then Z against the post-X position) so walking into a wall stops the blocked axis but keeps sliding along the other. Obstacles are treated as circle-vs-AABB in the X/Z plane, inflated by `playerRadius`; an obstacle whose vertical span misses the player's feet-to-head span is skipped entirely. Callers should pre-filter to nearby objects — this also early-exits per obstacle on horizontal distance.
+- constrainStepToAxis (function): function constrainStepToAxis(stepX: number, stepZ: number, axis: "x" | "z"): MovementFrameStep — Zeroes the off-axis component so travel is locked to a single world axis (`PlayerMovementConfig.mode: "axis"`).
+- snapPositionToGrid (function): function snapPositionToGrid(x: number, z: number, cellSize: number): [number, number] — Snap a world position to its containing cell's center, matching the bounds-free form of `navGrid`'s and `tacticalGrid`'s `floor` + half-cell convention (`PlayerMovementConfig.mode: "grid"`).
+- cameraYawToAvatarBodyYaw (function): function cameraYawToAvatarBodyYaw(cameraYaw: number): number — Camera yaw looks along -Z; character mesh faces +Z at body rotation.y = 0.
+- MovementKey (type): type MovementKey = "w" | "a" | "s" | "d" | "shift" | "control" | "c" | "space" — Movement core (pure model).
+- MovementKeysState (type): type MovementKeysState = Record<MovementKey, boolean>
+- MovementIntent (interface): interface MovementIntent — Frame-independent description of what the player is asking the avatar to do. `forward`/`right` are in the range -1..1 in the avatar's local frame; the controller rotates them into world space against the camera each frame.
+- MOVEMENT_TUNING (const): const MOVEMENT_TUNING: { readonly standEyeHeight: 1.7; readonly crouchEyeHeight: 1.15; readonly walkSpeedMultiplier: 1.75; readonly runSpeedMultiplier: 2.25; readonly crouchSpeedMultiplier: 0.45; readonly groundAcceleration: 26; readonly airAcceleration: 12; readonly groundFriction: 18; readonly jum… — Kinematics + feel tuning for the first-person controller. Centralised here so movement feel lives in one place rather than scattered through the renderer.
+- PlayerMotionState (interface): interface PlayerMotionState — Mutable kinematic state carried between frames by the controller. Kept here so the velocity / jump / gravity integration is a pure function testable without a renderer — the controller just owns the ref.
+- MovementFrameStep (interface): interface MovementFrameStep — Horizontal step (world units) the avatar should commit this frame.
+- MovementTuningOverrides (interface): interface MovementTuningOverrides — Per-game overrides for the gravity/jump feel, sourced from `GameDefinition.physics`. Omitted fields fall back to {@link MOVEMENT_TUNING}.
+- CollisionObstacle (interface): interface CollisionObstacle — A placed scene object the walking player collides against as a circle-vs-AABB obstacle.
+- MAX_JUMP_OFFSET (const): const MAX_JUMP_OFFSET: 1.15 — Peak jump height from MOVEMENT_TUNING.jumpVelocity + gravity, with small buffer.
+
+### @jgengine/core/movement/poseState
+
+- createPoseState (function): function createPoseState(resolveAllowed: (instanceId: string) => PoseAllowedStates | null | undefined): PoseState
+- MovementPose (type): type MovementPose = "standing" | "crouch" | "prone" | "running"
+- AimMode (type): type AimMode = "hip" | "ads"
+- PoseHitbox (interface): interface PoseHitbox
+- POSE_HITBOX (const): const POSE_HITBOX: Record<MovementPose, PoseHitbox>
+- PoseAllowedStates (interface): interface PoseAllowedStates
+- PoseRejection (interface): interface PoseRejection
+- PoseState (interface): interface PoseState
+
+### @jgengine/core/movement/voxelController
+
+- createVoxelPlayerBody (function): function createVoxelPlayerBody(x: number, y: number, z: number): VoxelPlayerBody
+- advanceVoxelPlayer (function): function advanceVoxelPlayer(body: VoxelPlayerBody, intent: MovementIntent, forwardX: number, forwardZ: number, baseSpeed: number, rawDeltaSeconds: number, isSolid: SolidQuery, dims: VoxelPlayerDims = DEFAULT_VOXEL_DIMS, tuning?: MovementTuningOverrides, groundHeight?: GroundHeightQuery): void — Advance one frame of voxel-collided player kinematics. Mutates `body` (position, velocity, grounded) in place.
+- SolidQuery (type): type SolidQuery = (x: number, y: number, z: number) => boolean
+- VoxelPlayerDims (interface): interface VoxelPlayerDims — Footprint + height of the player box, in world units.
+- DEFAULT_VOXEL_DIMS (const): const DEFAULT_VOXEL_DIMS: VoxelPlayerDims
+- VoxelPlayerBody (interface): interface VoxelPlayerBody — Mutable kinematic state carried between frames by the voxel controller.
+- GroundHeightQuery (type): type GroundHeightQuery = (x: number, z: number) => number — Samples the terrain floor height at a point; unset means flat ground plays no part in support.
+
+### @jgengine/core/multiplayer/chatContract
+
+- createLocalChatTransport (function): function createLocalChatTransport(options?: { userId?: string; historyLimit?: number; now?: () => number; }): { transport: ChatTransport; sync: ChatSync; actions: ChatActions; }
+- ChatSendArgs (interface): interface ChatSendArgs
+- ChatSendOutcome (interface): interface ChatSendOutcome
+- ChatActions (interface): interface ChatActions
+- ChatTransport (interface): interface ChatTransport — Backend seam for remote text chat, mirroring PresenceTransport: the use* members are called as React hooks by consumers, so a mounted transport must never change identity — remount the subtree to switch backends. useMessages returns undefined while the subscription is loading and the channel's recent history once live.
+- ChatSync (interface): interface ChatSync — Callback seam for backends that cannot host React hooks (e.g. the ws client): subscribe delivers the channel's recent history on every change; send resolves with the host's verdict.
+
+### @jgengine/core/multiplayer/combatSnapshot
+
+- serializeBoard (function): function serializeBoard(args: SerializeBoardArgs): BoardSnapshot
+- cloneSnapshot (function): function cloneSnapshot(snapshot: BoardSnapshot): BoardSnapshot
+- replayCombat (function): function replayCombat(a: BoardSnapshot, b: BoardSnapshot, rules: CombatRules): ReplayResult
+- SnapshotUnit (interface): interface SnapshotUnit
+- BoardSnapshot (interface): interface BoardSnapshot
+- SerializeBoardArgs (interface): interface SerializeBoardArgs
+- CombatRules (interface): interface CombatRules
+- CombatSide (type): type CombatSide = "a" | "b" | "draw"
+- ReplayBlow (interface): interface ReplayBlow
+- ReplayResult (interface): interface ReplayResult
+
+### @jgengine/core/multiplayer/identity
+
+- sessionPlayer (function): function sessionPlayer(session: AuthSession): PlayerIdentity
+- resolveGuestSession (function): function resolveGuestSession(seed?: string): AuthSession
+- AuthSession (interface): interface AuthSession
+- PlayerIdentity (interface): interface PlayerIdentity
+
+### @jgengine/core/multiplayer/lagCompensation
+
+- createPositionHistory (function): function createPositionHistory(config: PositionHistoryConfig): PositionHistory
+- rewindTimestamp (function): function rewindTimestamp(nowMs: number, rttMs: number, interpDelayMs: number): number
+- raySphereDistance (function): function raySphereDistance(ray: HitscanRay, center: Vec3, radius: number): number | null
+- resolveHitscan (function): function resolveHitscan(history: PositionHistory, targets: readonly HitscanTarget[], ray: HitscanRay, atMs: number): HitscanHit | null
+- Vec3 (interface): interface Vec3
+- PositionSample (interface): interface PositionSample extends Vec3
+- PositionHistoryConfig (interface): interface PositionHistoryConfig
+- PositionHistory (class): class PositionHistory
+- HitscanRay (interface): interface HitscanRay
+- HitscanTarget (interface): interface HitscanTarget
+- HitscanHit (interface): interface HitscanHit
+
+### @jgengine/core/multiplayer/matchmaking
+
+- normalizeJoinCode (function): function normalizeJoinCode(code: string): string
+- generateJoinCode (function): function generateJoinCode(random: () => number, length = 6): string
+- hasSpace (function): function hasSpace(listing: SessionListing): boolean
+- matchesFilter (function): function matchesFilter(listing: SessionListing, filter: MatchFilter): boolean
+- browseSessions (function): function browseSessions(listings: readonly SessionListing[], filter: MatchFilter = {}, options: BrowseOptions = {}): SessionListing[]
+- findByJoinCode (function): function findByJoinCode(listings: readonly SessionListing[], code: string): SessionListing | null
+- quickMatch (function): function quickMatch(listings: readonly SessionListing[], filter: MatchFilter = {}): SessionListing | null
+- SessionVisibility (type): type SessionVisibility = "public" | "private"
+- SessionStatus (type): type SessionStatus = "open" | "running" | "closed"
+- SessionListing (interface): interface SessionListing
+- MatchFilter (interface): interface MatchFilter
+- BrowseOptions (interface): interface BrowseOptions
+
+### @jgengine/core/multiplayer/poseSyncGate
+
+- createPoseSyncGate (function): function createPoseSyncGate(tuning: PoseSyncTuning): PoseSyncGate
+- PlayerPose (interface): interface PlayerPose
+- PoseSyncTuning (interface): interface PoseSyncTuning
+- PoseSyncGate (interface): interface PoseSyncGate
+
+### @jgengine/core/multiplayer/presenceContract
+
+- createLocalPresenceTransport (function): function createLocalPresenceTransport<TRow, TLocation, TGameId extends string = string>(): { transport: PresenceTransport<TRow, TLocation, TGameId>; actions: PresenceActions<TGameId>; }
+- PresencePosition (interface): interface PresencePosition
+- PresencePose (interface): interface PresencePose
+- PresenceSession (interface): interface PresenceSession<TGameId extends string = string>
+- EnsurePresenceArgs (interface): interface EnsurePresenceArgs<TGameId extends string = string>
+- EnsurePresenceResult (interface): interface EnsurePresenceResult
+- LeavePresenceArgs (interface): interface LeavePresenceArgs<TGameId extends string = string>
+- PresenceFeeds (interface): interface PresenceFeeds<TRow, TLocation>
+- PresenceActions (interface): interface PresenceActions<TGameId extends string = string>
+- PresenceTransport (interface): interface PresenceTransport<TRow, TLocation, TGameId extends string = string> — Backend seam for multiplayer presence. Feeds are reactive data and change identity whenever any player's pose updates; actions MUST be identity-stable for the lifetime of a mounted session so join/leave lifecycle effects can depend on them without re-running per pose tick. The use* members are called as React hooks by consumers, so a mounted transport must never change identity — remount the subtree to switch backends.
+
+### @jgengine/core/multiplayer/presenceModel
+
+- decidePoseSync (function): function decidePoseSync(current: PresencePoseState, incoming: IncomingPose, rules: PoseSyncRules, nowMs: number): PoseSyncDecision
+- shouldRefreshKeepAlive (function): function shouldRefreshKeepAlive(lastSeenAtMs: number | undefined, nowMs: number, rules: Pick<PoseSyncRules, "keepAliveRefreshMs">): boolean
+- shouldPersistWorldSnapshot (function): function shouldPersistWorldSnapshot(lastSavedAtMs: number | undefined, nowMs: number, intervalMs: number): boolean
+- resolveActivePresence (function): function resolveActivePresence<T extends { revokedAt?: number; lastSeenAt?: number }>(rows: readonly T[]): ActivePresenceResolution<T>
+- isPresenceExpired (function): function isPresenceExpired(lastSeenAtMs: number, nowMs: number, idleCutoffMs: number): boolean
+- pickReusablePresence (function): function pickReusablePresence<T extends { lastSeenAt?: number }>(rows: readonly T[]): T | undefined — Most-recently-seen row across an actor's rows, to reuse instead of inserting a new one.
+- PresencePoseState (interface): interface PresencePoseState
+- IncomingPose (interface): interface IncomingPose
+- PoseSyncRules (interface): interface PoseSyncRules
+- PoseSyncDecision (interface): interface PoseSyncDecision
+- ActivePresenceResolution (interface): interface ActivePresenceResolution<T>
+
+### @jgengine/core/multiplayer/simultaneousCommit
+
+- createCommitRound (function): function createCommitRound<TAction>(config: CommitRoundConfig): CommitRound<TAction>
+- resolveCommits (function): function resolveCommits<TAction, TResult>(reveals: readonly SealedCommit<TAction>[], resolver: (ordered: readonly SealedCommit<TAction>[]) => TResult): TResult
+- CommitPhase (type): type CommitPhase = "collecting" | "revealed"
+- SealedCommit (interface): interface SealedCommit<TAction>
+- CommitRoundConfig (interface): interface CommitRoundConfig
+- SealResult (type): type SealResult = | { ok: true; allSealed: boolean } | { ok: false; reason: "unknown_participant" | "already_sealed" | "already_revealed" }
+- CommitRound (class): class CommitRound<TAction>
+
+### @jgengine/core/multiplayer/voiceContract
+
+- createLocalVoiceTransport (function): function createLocalVoiceTransport(options?: { userId?: string }): { transport: VoiceTransport; participants(channelId: string): readonly VoiceParticipant[]; }
+- createPushToTalk (function): function createPushToTalk(config?: { mode?: PushToTalkMode; onChange?: (transmitting: boolean) => void; }): PushToTalk
+- VoiceParticipant (interface): interface VoiceParticipant
+- VoiceRoute (interface): interface VoiceRoute
+- VoiceTransport (interface): interface VoiceTransport — Signaling seam for voice: who is in a channel and which media stream descriptor they published. The media plane (WebRTC, SFU, or anything else that moves audio bytes) stays behind this seam, host-supplied — the engine never touches it. subscribers delivers the channel roster on every change, starting with the current roster.
+- PushToTalkMode (type): type PushToTalkMode = "hold" | "toggle" | "openMic"
+- PushToTalkStatus (type): type PushToTalkStatus = "idle" | "keyed" | "open"
+- PushToTalk (interface): interface PushToTalk
+
+### @jgengine/core/nav/navConstrain
+
+- constrainToNavGrid (function): function constrainToNavGrid(grid: NavGrid, options?: NavConstrainOptions): (proposed: NavConstrainProposed, entity: NavConstrainEntity) => NavConstrainProposed | null
+- NavConstrainProposed (interface): interface NavConstrainProposed
+- NavConstrainEntity (interface): interface NavConstrainEntity
+- NavConstrainOptions (interface): interface NavConstrainOptions
+
+### @jgengine/core/nav/navFromEnvironment
+
+- populateNavGridFromEnvironment (function): function populateNavGridFromEnvironment(grid: NavObstacleGrid, world: EnvironmentWorldFeature): number — Expands every structure descriptor on an environment world feature into its generated buildings and blocks their footprints on `grid`. Returns the number of buildings blocked.
+- NavObstacleGrid (interface): interface NavObstacleGrid
+
+### @jgengine/core/nav/navGrid
+
+- createNavGrid (function): function createNavGrid(config: NavGridConfig): NavGrid
+- findPath (function): function findPath(grid: NavGrid, from: NavPoint, to: NavPoint, options: FindPathOptions = {}): NavPoint[] | null — A* over the walkable grid. Returns a polyline of world-space `[x, z]` waypoints from `from` to `to`, or `null` when no route exists. Blocked start/goal snap to the nearest walkable cell so a click on an obstacle still routes to its edge.
+- slopeStepCost (function): function slopeStepCost(field: { sampleHeight(x: number, z: number): number }, weight = DEFAULT_SLOPE_STEP_WEIGHT): (from: NavPoint, to: NavPoint) => number — `FindPathOptions.stepCost` factory that penalizes steep terrain: cost is `1 + weight * |Δheight| / horizontalDistance`, so with the default weight a 45° slope roughly doubles the step cost.
+- smoothPath (function): function smoothPath(grid: NavGrid, points: readonly NavPoint[]): NavPoint[] — Remove waypoints the mover can skip because it has clear line-of-sight past them.
+- NavPoint (type): type NavPoint = readonly [number, number]
+- NavGridConfig (interface): interface NavGridConfig
+- NavCell (interface): interface NavCell
+- FindPathOptions (interface): interface FindPathOptions
+- NavGrid (interface): interface NavGrid
+
+### @jgengine/core/nav/pathFollow
+
+- pathFromNav (function): function pathFromNav(points: readonly NavPoint[], elevation: number | HeightSampler = 0, offset = 0): Waypoint[]
+- createPathFollow (function): function createPathFollow(config: PathFollowConfig): PathFollowState
+- advancePathFollow (function): function advancePathFollow(config: PathFollowConfig, state: PathFollowState, dt: number): PathFollowState — Advance a path-follower by `speed * dt` along its authored polyline. Pure — returns the next state. Crosses multiple waypoints in one step, loops when configured, and reports `done` at the end of a non-looping path. No navmesh required (#52); feed it a navmesh route via `pathFromNav` for click-to-move (#51).
+- Waypoint (type): type Waypoint = readonly [number, number, number]
+- PathFollowConfig (interface): interface PathFollowConfig
+- PathFollowState (interface): interface PathFollowState
+- HeightSampler (interface): interface HeightSampler
+
+### @jgengine/core/physics/ballisticSweep
+
+- createBallisticSweep (function): function createBallisticSweep(world: PhysicsWorld, options: BallisticSweepOptions = {}): BallisticSweep — Marches the closed-form arc (constant gravity, straight lateral) through `world` and reports the first sample inside any live body's AABB — sleeping bodies included — refined by one bisection between the last clear sample and the hit sample. Returns `null` when the whole arc is clear.
+- BallisticSweepHit (interface): interface BallisticSweepHit
+- BallisticSweep (type): type BallisticSweep = ( origin: readonly [number, number, number], velocity: readonly [number, number, number], gravity: number, maxTime: number, ) => BallisticSweepHit | null
+- BallisticSweepOptions (interface): interface BallisticSweepOptions
+
+### @jgengine/core/physics/buoyancy
+
+- createBuoyantBody (function): function createBuoyantBody(world: PhysicsWorld, config: BuoyantBodyConfig): BuoyantBody
+- BuoyantBodyConfig (interface): interface BuoyantBodyConfig
+- BuoyantBody (class): class BuoyantBody — Floats a {@link PhysicsWorld} body on a CPU {@link WaterSurface}: each hull sample point pushes the body up by its submerged depth (Archimedes, coarse), with vertical and horizontal water drag so the hull settles at the waterline and rides the Gerstner waves. Passing an {@link AxisInput} drives it as a boat — throttle thrusts along the heading, steer yaws, a keel bleeds sideways slip. Call `update(dt, time, input?)` before the shared `world.step(dt)`.
+
+### @jgengine/core/physics/carryable
+
+- carrySpeedMultiplier (function): function carrySpeedMultiplier(mass: number, carryCapacity: number, owners: number): number — Movement multiplier (1 = unhindered, →0 = crushed) for a body of `mass` carried by `owners`. Pure — the HUD/movement kit reads it to slow a laden hauler (Lethal Company) and to gate items that need 2+ people (R.E.P.O.).
+- CarryableConfig (interface): interface CarryableConfig
+- Carryable (class): class Carryable — A grabbed physics object following a moving hold point through a spring constraint (the pick — a raycast — is the caller's/shell's job; core owns the constraint). Supports shared multi-owner carry (the follow point is the average of owners' hold points), an encumbrance read, and drop/throw. Reuses `PhysicsWorld.springJoint` to a world anchor moved each frame.
+
+### @jgengine/core/physics/damageZones
+
+- createDamageModel (function): function createDamageModel(config: DamageModelConfig): DamageModel
+- DamageZoneDef (interface): interface DamageZoneDef
+- DamageZoneState (interface): interface DamageZoneState
+- DamageTransition (interface): interface DamageTransition
+- DamageModelConfig (interface): interface DamageModelConfig
+- DamageModel (class): class DamageModel — Coarse crash-damage model (issue #86 — stages, not soft-body). Each zone accumulates contact impulse fed from G3's `onCollision` `CollisionEvent`; crossing a threshold bumps the zone to the next discrete stage (the caller swaps the visual/collider), an optional `detachStage` ejects a part as debris once, and a total-impulse `disableAt` flips the whole body to a disabled state. `absorb` returns a transition only when something actually changed, so it doubles as the event source for HUD/feed.
+
+### @jgengine/core/physics/forceVolume
+
+- ForceMode (type): type ForceMode = "impulse" | "velocity" | "accelerate"
+- ForceVolumeConfig (interface): interface ForceVolumeConfig
+- ForceVolume (class): class ForceVolume — A trigger region that pushes bodies passing through it — boost pads (`impulse` + `once`), conveyors (`velocity`), fans/wind (`accelerate`). Call `apply` each tick; `once` mode fires only on entry by tracking membership between ticks.
+- PlatformCarryConfig (interface): interface PlatformCarryConfig
+- PlatformCarry (class): class PlatformCarry — Carries bodies standing on a moving platform by composing their transform with the platform's per-`step` delta — moving/rotating lifts and conveyor floors (Fall Guys, Gang Beasts). The platform is a body the game repositions each frame; riders are detected by overlap on its top face.
+
+### @jgengine/core/physics/physicsWorld
+
+- cellCoord (function): function cellCoord(value: number, min: number, cellSize: number, cells: number): number — Grid cell containing a point, clamped into the grid. Pure — exported for tests.
+- cellIndex (function): function cellIndex(cx: number, cy: number, cz: number, nx: number, ny: number): number — Linear cell index from clamped 3D coords. Pure — exported for tests.
+- PhysicsBounds (interface): interface PhysicsBounds
+- PhysicsWorldConfig (interface): interface PhysicsWorldConfig
+- PhysicsStats (interface): interface PhysicsStats
+- BodyCommonOptions (interface): interface BodyCommonOptions
+- BoxBodyOptions (interface): interface BoxBodyOptions extends BodyCommonOptions
+- SphereBodyOptions (interface): interface SphereBodyOptions extends BodyCommonOptions — The radius fills all three half-extent columns, so broadphase and bounds see the sphere's enclosing AABB.
+- AddBodyOptions (type): type AddBodyOptions = BoxBodyOptions | SphereBodyOptions
+- SHAPE_BOX (const): const SHAPE_BOX: 0
+- SHAPE_SPHERE (const): const SHAPE_SPHERE: 1
+- JointKind (type): type JointKind = "hinge" | "distance" | "spring" | "fixed" — `hinge`/`fixed`/`distance` are hard bilateral constraints; `spring` is a soft PD constraint. No angular state → `hinge`/`fixed` both pin the shared anchor (`axis` is metadata), `distance` holds a fixed separation, `spring` drives toward `restLength` (suspension, follow-point carry).
+- JointOptions (interface): interface JointOptions
+- CollisionEvent (interface): interface CollisionEvent — A contact reported to `onCollision`. The object is reused each call — read/copy, never retain.
+- MAX_BROADPHASE_CELLS (const): const MAX_BROADPHASE_CELLS: 1000000 — Cap on `nx*ny*nz` broadphase cells — guards a huge-bounds/tiny-cellSize config from hanging `step()`.
+- PhysicsWorld (class): class PhysicsWorld
+
+### @jgengine/core/physics/ragdoll
+
+- createRagdoll (function): function createRagdoll(world: PhysicsWorld, config: RagdollConfig): Ragdoll
+- RagdollBoneSpec (interface): interface RagdollBoneSpec
+- RagdollLinkSpec (interface): interface RagdollLinkSpec
+- RagdollBalanceConfig (interface): interface RagdollBalanceConfig
+- RagdollConfig (interface): interface RagdollConfig
+- Ragdoll (class): class Ragdoll — A jointed multi-body character — floppy by default, or active-ragdoll when a balance motor is configured. Bones are `PhysicsWorld` bodies; links are joints on the joint API. `balance(dt, mx, mz)` drives the root toward its target height (staying upright) and pushes it by the move vector.
+
+### @jgengine/core/physics/spatialGrid
+
+- SpatialGridConfig (interface): interface SpatialGridConfig
+- SpatialGrid (class): class SpatialGrid — A uniform-grid broad-phase over the x/z plane, separate from the rigid-body sim, for cheap same-tick proximity across hundreds–thousands of simple movers (swarm enemies). Rebuild each tick from the caller's own position arrays, then `queryCircle` (enemies hitting the player / an AoE) or `forEachPair` (mutual separation). Both are precise: no false negatives, no false positives beyond the exact distance test.
+
+### @jgengine/core/physics/structure
+
+- StructureMaterial (interface): interface StructureMaterial
+- StructureMaterialTable (type): type StructureMaterialTable = Readonly<Record<string, StructureMaterial>>
+- StructureNodeSpec (interface): interface StructureNodeSpec
+- StructureEdgeSpec (interface): interface StructureEdgeSpec
+- CollapseEvent (interface): interface CollapseEvent
+- DebrisConfig (interface): interface DebrisConfig
+- StructureGraph (class): class StructureGraph — A structural-integrity graph over a building — nodes are pieces (walls, beams, floors), edges are load-bearing connections, some nodes are anchored foundations. `damage`/`damageEdge` wear pieces and connections down; when a piece shatters or an edge severs, the graph recomputes which pieces still reach an anchor and hands back every newly-disconnected piece as one `CollapseEvent`. Feed that to `toDebris` to sink the fallen pieces into a `PhysicsWorld` as rigid bodies ("The Finals" smooth destruction, Rainbow Six walls). Coarse by design: it replicates the collapse event, not per fragment.
+
+### @jgengine/core/physics/traversal
+
+- GrappleConfig (interface): interface GrappleConfig
+- Grapple (class): class Grapple — A fired-anchor rope on the joint API — grapple (reel toward a hit point), zipline (rigid cable to a far anchor you then slide/reel along), swing (rigid rope + gravity = a pendulum). `fire` attaches a `distance`/`spring` joint from the traveller body to a fixed world point; `reel` shrinks its rest length so the constraint drags the body in; `moveAnchor` re-points it (zipline glide, grapple-to- moving-target). The pick — a raycast to find the anchor — is the caller's; core owns the constraint.
+- GlideConfig (interface): interface GlideConfig
+- Glide (class): class Glide — A reduced-gravity, forward-thrust glide over a physics body — wingsuit / glider / paraglider (Enshrouded, Grounded). Call `apply(dt, steerX, steerZ)` each frame *before* `world.step`: it feeds back most of the gravity the sim is about to apply (leaving `gravityScale` of it), pushes the body along the steer vector by `thrust`, and clamps descent to `maxFallSpeed`. Stop calling it to fall normally again — no attach/detach state to leak.
+
+### @jgengine/core/physics/vehicleBody
+
+- sampleGripCurve (function): function sampleGripCurve(curve: GripCurve, slip: number): number — Piecewise-linear tire-grip curve: normalized lateral slip → available grip (0..1). Grip peaks near the breakaway slip then falls off as the tire slides — the shape that separates a planted corner from a drift. Points are read in ascending slip order; ends clamp.
+- createVehicleBody (function): function createVehicleBody(world: PhysicsWorld, config: VehicleBodyConfig): VehicleBody
+- GripCurve (interface): interface GripCurve
+- DEFAULT_GRIP_CURVE (const): const DEFAULT_GRIP_CURVE: GripCurve
+- WheelSpec (interface): interface WheelSpec
+- WheelState (interface): interface WheelState
+- VehicleBodyConfig (interface): interface VehicleBodyConfig
+- VehicleBody (class): class VehicleBody — Arcade vehicle over the {@link PhysicsWorld} rigid-body sim. The chassis is a single box body driven by an {@link AxisInput}: per-wheel suspension is a spring-damper held with G3's `springJoint` against the sampled ground, drive/brake push along the heading, and a tire-grip curve bleeds lateral velocity (cornering, and drift under handbrake). Because the chassis is a physics body it still collides — that contact feeds crash damage. Call `update(dt, input)` before the shared `world.step(dt)`.
+
+### @jgengine/core/puzzle/cellGrid
+
+- createCellGrid (function): function createCellGrid<T>(width: number, height: number): CellGrid<T>
+- inGridBounds (function): function inGridBounds<T>(grid: CellGrid<T>, x: number, y: number): boolean
+- cellAt (function): function cellAt<T>(grid: CellGrid<T>, x: number, y: number): T | null
+- withCell (function): function withCell<T>(grid: CellGrid<T>, x: number, y: number, value: T | null): CellGrid<T>
+- withCells (function): function withCells<T>(grid: CellGrid<T>, entries: readonly { readonly x: number; readonly y: number; readonly value: T | null }[]): CellGrid<T>
+- fullRows (function): function fullRows<T>(grid: CellGrid<T>): number[]
+- clearRows (function): function clearRows<T>(grid: CellGrid<T>, rows: readonly number[]): CellGrid<T>
+- collapseColumns (function): function collapseColumns<T>(grid: CellGrid<T>): CellGrid<T>
+- findRuns (function): function findRuns<T>(grid: CellGrid<T>, minLength: number, matches: (a: T, b: T) => boolean = (a, b) => a === b): CellRun<T>[]
+- CellGrid (interface): interface CellGrid<T>
+- CellRun (interface): interface CellRun<T>
+
+### @jgengine/core/puzzle/fallingPiece
+
+- pieceCells (function): function pieceCells<TShape extends string>(table: ShapeTable<TShape>, piece: FallingPiece<TShape>): readonly (readonly [number, number])[]
+- pieceCollides (function): function pieceCollides<T, TShape extends string>(grid: CellGrid<T>, table: ShapeTable<TShape>, piece: FallingPiece<TShape>): boolean
+- mergePiece (function): function mergePiece<T, TShape extends string>(grid: CellGrid<T>, table: ShapeTable<TShape>, piece: FallingPiece<TShape>, value: T): CellGrid<T>
+- dropDistance (function): function dropDistance<T, TShape extends string>(grid: CellGrid<T>, table: ShapeTable<TShape>, piece: FallingPiece<TShape>): number
+- gravityInterval (function): function gravityInterval(level: number, base = 0.8, perLevel = 0.07, min = 0.05): number
+- levelForLines (function): function levelForLines(lines: number, linesPerLevel = 10): number
+- lineScore (function): function lineScore(cleared: number, level: number, table: readonly number[] = CLASSIC_LINE_SCORE): number
+- createLockDelay (function): function createLockDelay(delaySeconds: number): LockDelayState
+- stepLockDelay (function): function stepLockDelay(state: LockDelayState, grounded: boolean, dt: number): { state: LockDelayState; locked: boolean }
+- FallingPiece (interface): interface FallingPiece<TShape extends string = string>
+- ShapeTable (type): type ShapeTable<TShape extends string = string> = Record< TShape, readonly (readonly (readonly [number, number])[])[] >
+- LockDelayState (interface): interface LockDelayState
+
+### @jgengine/core/random/nameGen
+
+- pickFrom (function): function pickFrom(rng: () => number, bank: readonly string[]): string
+- createNameGenerator (function): function createNameGenerator(options: NameGeneratorOptions): NameGenerator
+- fillTemplate (function): function fillTemplate(template: string, vars: Record<string, () => string> | Record<string, string>): string
+- SyllableBank (interface): interface SyllableBank
+- NameGeneratorOptions (interface): interface NameGeneratorOptions
+- NameGenerator (interface): interface NameGenerator
+
+### @jgengine/core/random/rng
+
+- seededRng (function): function seededRng(seed: string | number): () => number
+- seededStreams (function): function seededStreams(seed: string | number): (stream: string) => () => number
+
+### @jgengine/core/runtime/adapter
+
+- convex (function): function convex(config?: { topology?: MultiplayerTopology }): MultiplayerAdapterConfig
+- ws (function): function ws(config?: { topology?: MultiplayerTopology; url?: string }): MultiplayerAdapterConfig
+- fly (function): function fly(config: { app: string; topology?: MultiplayerTopology; path?: string }): MultiplayerAdapterConfig
+- socketIo (function): function socketIo(config?: { topology?: MultiplayerTopology; url?: string }): MultiplayerAdapterConfig
+- p2p (function): function p2p(config?: { topology?: MultiplayerTopology; room?: string }): MultiplayerAdapterConfig
+- lan (function): function lan(config?: { topology?: MultiplayerTopology; port?: number; path?: string; }): MultiplayerAdapterConfig
+- offline (function): function offline(): MultiplayerAdapterConfig
+- adapterOf (function): function adapterOf(multiplayer: unknown): MultiplayerAdapterConfig | null
+- multiplayerAdapterKind (function): function multiplayerAdapterKind(multiplayer: unknown): string | null
+- servers (function): function servers(config: ServersPoolConfig): import("/home/runner/work/jgengine/jgengine/packages/core/src/runtime/adapter").ServersPoolConfig
+- MultiplayerTopology (type): type MultiplayerTopology = "shared" | "lobbies" | "private"
+- MultiplayerAdapterConfig (type): type MultiplayerAdapterConfig = | { kind: "convex"; topology?: MultiplayerTopology } | { kind: "ws"; topology?: MultiplayerTopology; url?: string } | { kind: "socketio"; topology?: MultiplayerTopology; url?: string } | { kind: "p2p"; topology?: MultiplayerTopology; room?: string } | { kind: "lan"; t…
+- ServersPoolConfig (type): type ServersPoolConfig = { maxServers: number; slotsPerServer: number; minPlayersToStart?: number; adapter: MultiplayerAdapterConfig; }
+
+### @jgengine/core/runtime/cameraDirector
+
+- createCameraDirector (function): function createCameraDirector(): CameraDirector
+- CameraDirector (interface): interface CameraDirector
+
+### @jgengine/core/runtime/commandRunner
+
+- runCommand (function): function runCommand<TInput>(snapshot: import("./snapshot").GameRuntimeSnapshot, commands: Record<string, CommandDef<TInput>>, commandName: string, input: TInput, actorUserId: string): RunCommandResult
+- CommandValidationError (type): type CommandValidationError = { reason: string }
+- CommandDef (type): type CommandDef<TInput = unknown> = { validate: (snapshot: import("./snapshot").GameRuntimeSnapshot, input: TInput) => CommandValidationError | null; apply: ( snapshot: import("./snapshot").GameRuntimeSnapshot, input: TInput, ) => import("./snapshot").GameRuntimeSnapshot; }
+- RunCommandResult (type): type RunCommandResult = | { ok: true; snapshot: import("./snapshot").GameRuntimeSnapshot } | { ok: false; reason: string }
+
+### @jgengine/core/runtime/gameContext
+
+- createGameContext (function): function createGameContext<TAssetRef extends ModelAssetRef, TMultiplayer>(options: GameContextOptions<TAssetRef, TMultiplayer>): GameContext
+- GameContextItemEntry (interface): interface GameContextItemEntry
+- CatalogEntityRole (type): type CatalogEntityRole = "player" | "enemy" | "hostile" | "npc" | "vehicle"
+- GameContextEntityEntry (interface): interface GameContextEntityEntry
+- GameContextObjectEntry (interface): interface GameContextObjectEntry
+- GameContextContent (interface): interface GameContextContent
+- GameContextOptions (interface): interface GameContextOptions<TAssetRef extends ModelAssetRef = ModelAssetRef, TMultiplayer = unknown>
+- SceneObjectContext (interface): interface SceneObjectContext extends ObjectStore
+- FloatTextInput (interface): interface FloatTextInput
+- TelegraphInput (interface): interface TelegraphInput
+- HitReactionInput (interface): interface HitReactionInput
+- SceneEntityContext (interface): interface SceneEntityContext
+- WorldItemPickupResult (type): type WorldItemPickupResult = | { status: "ok"; record: WorldItemRecord } | { status: "rejected"; reason: string }
+- SceneWorldItemContext (interface): interface SceneWorldItemContext
+- GameContextCommands (interface): interface GameContextCommands
+- GameContextFeed (interface): interface GameContextFeed extends Omit<GameFeed, "bind">
+- GameContextLoot (interface): interface GameContextLoot
+- GameContextEconomy (interface): interface GameContextEconomy
+- GameContextItemUse (interface): interface GameContextItemUse
+- GameContextWorld (interface): interface GameContextWorld
+- GameContextCards (interface): interface GameContextCards
+- GameContextTurn (interface): interface GameContextTurn
+- GameContext (interface): interface GameContext
+
+### @jgengine/core/runtime/gameRuntime
+
+- createGameRuntime (function): function createGameRuntime(definition: GameRuntimeDefinition): GameRuntime
+- ServerLoopHooks (type): type ServerLoopHooks = { onInit?: (ctx: RuntimeInitContext) => void; onNewPlayer?: (ctx: RuntimeLoopContext) => void; onTick?: (ctx: RuntimeLoopContext, dtSeconds: number) => void; }
+- RuntimeInitContext (type): type RuntimeInitContext = { snapshot: GameRuntimeSnapshot; setSnapshot: (snapshot: GameRuntimeSnapshot) => void; }
+- RuntimeLoopContext (type): type RuntimeLoopContext = RuntimeInitContext & { player: { userId: string; isNew: boolean; }; }
+- GameRuntimeDefinition (type): type GameRuntimeDefinition = { gameId: string; save: SaveConfig; commands: Record<string, CommandDef>; loop?: ServerLoopHooks; }
+- HydrateInput (type): type HydrateInput = { gameId: string; serverId: string; serverRow: RuntimeServerRow; playersByUserId: Record<string, RuntimePlayerRow>; chunksByKey: Record<string, RuntimeChunkRow>; }
+- GameRuntime (type): type GameRuntime = { gameId: string; save: SaveConfig; hydrate: (input: HydrateInput) => GameRuntimeSnapshot; runCommand: ( snapshot: GameRuntimeSnapshot, actorUserId: string, commandName: string, input: unknown, ) => ReturnType<typeof runCommand>; tick: (snapshot: GameRuntimeSnapshot, dtSeconds: nu…
+
+### @jgengine/core/runtime/hostPersistence
+
+- drainPendingLeaderboardIncrements (function): function drainPendingLeaderboardIncrements(session: Record<string, unknown>): { increments: LeaderboardIncrement[]; session: Record<string, unknown>; }
+- leaderboardRowKey (function): function leaderboardRowKey(row: Omit<LeaderboardRow, "value" | "updatedAt">): string
+- applyLeaderboardRows (function): function applyLeaderboardRows(rows: Map<string, LeaderboardRow>, gameId: string, entries: LeaderboardIncrement[], now: number): void
+- topLeaderboardRows (function): function topLeaderboardRows(rows: Iterable<LeaderboardRow>, args: { gameId: string; stat: string; scope: LeaderboardScope; serverId?: string; limit?: number; }): LeaderboardEntry[]
+- profileLeaderboardStats (function): function profileLeaderboardStats(rows: Iterable<LeaderboardRow>, gameId: string, userId: string): Record<string, number>
+- trimFeedEntries (function): function trimFeedEntries<T>(entries: T[], limit = FEED_RING_LIMIT): T[]
+- shouldAutoSave (function): function shouldAutoSave(save: SaveConfig, dirtyAt: number | undefined, lastSavedAt: number | undefined, now: number): boolean
+- toServerListing (function): function toServerListing(record: GameServerRecord): ServerListing
+- toOpenServerListings (function): function toOpenServerListings(listings: Iterable<ServerListing>, limit = 20): ServerListing[]
+- buildHydratePlayers (function): function buildHydratePlayers(server: GameServerRecord, profiles: Record<string, PlayerProfileRecord | null>): Record<string, RuntimePlayerRow>
+- planServerPersist (function): function planServerPersist(server: GameServerRecord, snapshot: GameRuntimeSnapshot, save: SaveConfig, now: number): ServerPersistPlan
+- GameServerStatus (type): type GameServerStatus = "open" | "running" | "closed"
+- SessionVisibility (type): type SessionVisibility = "public" | "private"
+- SessionAttributes (type): type SessionAttributes = { label?: string; mode?: string; visibility?: SessionVisibility; joinCode?: string; tags?: string[]; }
+- GameServerRecord (type): type GameServerRecord = { serverId: string; gameId: string; status: GameServerStatus; mode?: string; modeConfig?: unknown; label?: string; visibility?: SessionVisibility; joinCode?: string; tags?: string[]; memberUserIds: string[]; slotsPerServer: number; save: SaveConfig; serverState: RuntimeServer…
+- PlayerProfileRecord (type): type PlayerProfileRecord = { userId: string; gameId: string; playerState: RuntimePlayerRow; revision: number; updatedAt: number; }
+- WorldChunkRecord (type): type WorldChunkRecord = { serverId: string; chunkKey: string; snapshot: RuntimeChunkRow; updatedAt: number; }
+- LeaderboardIncrement (type): type LeaderboardIncrement = { userId: string; stat: string; scope: LeaderboardScope; serverId?: string; by: number; }
+- LeaderboardEntry (type): type LeaderboardEntry = { userId: string; value: number; }
+- LEADERBOARD_PENDING_KEY (const): const LEADERBOARD_PENDING_KEY: "leaderboardPending"
+- LEADERBOARD_TOP_LIMIT (const): const LEADERBOARD_TOP_LIMIT: 100
+- LeaderboardRow (type): type LeaderboardRow = { gameId: string; stat: string; scope: LeaderboardScope; serverId?: string; userId: string; value: number; updatedAt: number; }
+- FEED_RING_LIMIT (const): const FEED_RING_LIMIT: 20
+- ServerListing (type): type ServerListing = { serverId: string; status: GameServerStatus; memberCount: number; slotsPerServer: number; mode?: string; label?: string; visibility?: SessionVisibility; joinCode?: string; tags?: string[]; updatedAt: number; }
+- HostPersistence (type): type HostPersistence = { savePlan?: (plan: ServerPersistPlan) => Promise<void>; resetScenario?: (reset: NormalizedScenarioReset) => Promise<void>; loadServer: (serverId: string) => Promise<GameServerRecord | null>; saveServer: (record: GameServerRecord) => Promise<void>; listServers: (gameId: string…
+- ServerPersistPlan (type): type ServerPersistPlan = { server: GameServerRecord; profiles: PlayerProfileRecord[]; chunks: WorldChunkRecord[]; leaderboard: LeaderboardIncrement[]; }
+
+### @jgengine/core/runtime/inputSnapshot
+
+- createInputSnapshot (function): function createInputSnapshot(): InputSnapshot
+- InputSnapshot (interface): interface InputSnapshot
+
+### @jgengine/core/runtime/motionIntents
+
+- createMotionIntents (function): function createMotionIntents(): MotionIntents
+- MotionIntents (interface): interface MotionIntents — Seam for game code to reach the vertical motion the shell's FrameDriver otherwise owns privately (#162.4). Game code calls `impulse`, `setVerticalVelocity`, and/or `setY` from `onTick` or commands; the shell calls `takePending()` once per frame, before integrating gravity, to drain what accumulated. `setY` wins over physics for that frame; impulses add to the vertical velocity the driver is about to integrate; a later `setVerticalVelocity` replaces that velocity outright.
+- MotionIntentBatch (interface): interface MotionIntentBatch
+
+### @jgengine/core/runtime/persistenceScope
+
+- partitionScopes (function): function partitionScopes<T extends Record<string, unknown>>(state: T, schema: ScopeSchema): ScopedState<T>
+- resetRun (function): function resetRun<T extends Record<string, unknown>>(scoped: ScopedState<T>): ScopedState<T>
+- mergeScopes (function): function mergeScopes<T extends Record<string, unknown>>(scoped: ScopedState<T>): Partial<T>
+- clearRunFields (function): function clearRunFields(player: RuntimePlayerRow, runFields: readonly string[]): RuntimePlayerRow
+- applyRunReset (function): function applyRunReset(profile: PlayerProfileRecord, runFields: readonly string[], now: number): PlayerProfileRecord
+- planScenarioReset (function): function planScenarioReset(reset: ScenarioReset): NormalizedScenarioReset
+- PersistenceScope (type): type PersistenceScope = "run" | "meta"
+- ScopeSchema (interface): interface ScopeSchema
+- ScopedState (interface): interface ScopedState<T = Record<string, unknown>>
+- ScenarioReset (interface): interface ScenarioReset
+- NormalizedScenarioReset (interface): interface NormalizedScenarioReset
+
+### @jgengine/core/runtime/save
+
+- parseSaveAutoMs (function): function parseSaveAutoMs(auto: string): number
+- saveScopeIncludesPlayer (function): function saveScopeIncludesPlayer(scope: SaveScope): boolean
+- saveScopeIncludesChunks (function): function saveScopeIncludesChunks(scope: SaveScope): boolean
+- isSaveEnabled (function): function isSaveEnabled(config: SaveConfig): config is Exclude<SaveConfig, "none">
+- SaveScope (type): type SaveScope = "player" | "chunks" | "player+chunks"
+- SaveConfig (type): type SaveConfig = | "none" | { auto: string; scope: SaveScope; }
+
+### @jgengine/core/runtime/snapshot
+
+- createEmptyServerRow (function): function createEmptyServerRow(): RuntimeServerRow
+- createEmptyPlayerRow (function): function createEmptyPlayerRow(userId: string): RuntimePlayerRow
+- createRuntimeSnapshot (function): function createRuntimeSnapshot(args: { gameId: string; serverId: string; server?: RuntimeServerRow; players?: Record<string, RuntimePlayerRow>; chunks?: Record<string, RuntimeChunkRow>; }): GameRuntimeSnapshot
+- markServerDirty (function): function markServerDirty(snapshot: GameRuntimeSnapshot): GameRuntimeSnapshot
+- markPlayerDirty (function): function markPlayerDirty(snapshot: GameRuntimeSnapshot, userId: string): GameRuntimeSnapshot
+- clearDirtyFlags (function): function clearDirtyFlags(snapshot: GameRuntimeSnapshot): GameRuntimeSnapshot
+- splitProfilePlayer (function): function splitProfilePlayer(player: RuntimePlayerRow): { persistent: RuntimePlayerRow; session: Record<string, unknown>; }
+- RUNTIME_SNAPSHOT_VERSION (const): const RUNTIME_SNAPSHOT_VERSION: 1
+- RuntimeEntityRow (type): type RuntimeEntityRow = { instanceId: string; catalogId: string; position?: [number, number, number]; rotationY?: number; parentSpace?: string; group?: string; stats?: Record<string, { current: number; max: number; min?: number }>; targetInstanceId?: string | null; userId?: string; }
+- RuntimeObjectRow (type): type RuntimeObjectRow = { instanceId: string; catalogId: string; position: [number, number, number]; rotationY?: number; parentSpace?: string; flags?: Record<string, unknown>; }
+- RuntimeInventorySlot (type): type RuntimeInventorySlot = { item: string; count: number; slot?: number; }
+- RuntimePlayerRow (type): type RuntimePlayerRow = { userId: string; inventories: Record<string, RuntimeInventorySlot[]>; economy: Record<string, number>; unlocks: string[]; quests?: unknown; social?: unknown; leaderboard?: Record<string, number>; session?: Record<string, unknown>; }
+- RuntimeChunkRow (type): type RuntimeChunkRow = { chunkKey: string; objects: RuntimeObjectRow[]; entities: RuntimeEntityRow[]; flags?: Record<string, unknown>; }
+- RuntimeServerRow (type): type RuntimeServerRow = { entities: RuntimeEntityRow[]; objects: RuntimeObjectRow[]; session: Record<string, unknown>; feeds?: Record<string, unknown[]>; }
+- RuntimeProfileRow (type): type RuntimeProfileRow = { userId: string; gameId: string; player: RuntimePlayerRow; updatedAt: number; }
+- GameRuntimeSnapshot (type): type GameRuntimeSnapshot = { version: number; gameId: string; serverId: string; server: RuntimeServerRow; players: Record<string, RuntimePlayerRow>; chunks: Record<string, RuntimeChunkRow>; revision: number; dirty: { server: boolean; players: string[]; chunks: string[]; }; }
+
+### @jgengine/core/runtime/transport
+
+- JoinServerResult (type): type JoinServerResult = { serverId: string; isNew: boolean; }
+- RunCommandArgs (type): type RunCommandArgs = { serverId: string; command: string; input: unknown; }
+- TransportRunCommandResult (type): type TransportRunCommandResult = | { ok: true } | { ok: false; reason: string }
+- GameRuntimeServerView (type): type GameRuntimeServerView = { serverId: string; gameId: string; revision: number; memberUserIds: string[]; serverState: unknown; updatedAt: number; }
+- GameRuntimePlayerView (type): type GameRuntimePlayerView = { userId: string; gameId: string; playerState: unknown; updatedAt: number; }
+- GameRuntimeFeedView (type): type GameRuntimeFeedView = { action: string; entries: unknown[]; }
+- GameRuntimeTransport (type): type GameRuntimeTransport = { joinServer: (args: { gameId: string; serverId?: string }) => Promise<JoinServerResult>; leaveServer: (args: { serverId: string }) => Promise<void>; runCommand: (args: RunCommandArgs) => Promise<TransportRunCommandResult>; }
+- FeedUnsubscribe (type): type FeedUnsubscribe = () => void
+- GameRuntimeFeeds (type): type GameRuntimeFeeds = { subscribeServer: ( serverId: string, onChange: (view: GameRuntimeServerView | null) => void, ) => FeedUnsubscribe; subscribePlayer: ( args: { serverId: string }, onChange: (view: GameRuntimePlayerView | null) => void, ) => FeedUnsubscribe; subscribeFeed: ( args: { serverId:…
+- GameBackend (type): type GameBackend<TPresenceRow = unknown, TPresenceLocation = unknown, TGameId extends string = string> = { transport: GameRuntimeTransport; feeds?: GameRuntimeFeeds; presence?: PresenceTransport<TPresenceRow, TPresenceLocation, TGameId>; }
+- PresencePoseRow (type): type PresencePoseRow = { userId: string; position: { x: number; y: number; z: number }; rotationY: number; rotationPitch: number; lastSeenAt: number; }
+- PresenceSync (type): type PresenceSync = { subscribe: (serverId: string, onChange: (rows: PresencePoseRow[]) => void) => FeedUnsubscribe; syncPose: (serverId: string, pose: PlayerPose) => void; }
+- LiveGameBackend (type): type LiveGameBackend<TPresenceRow = unknown, TPresenceLocation = unknown, TGameId extends string = string> = GameBackend<TPresenceRow, TPresenceLocation, TGameId> & { presenceSync: PresenceSync; pushFeedEntry: (args: { serverId: string; action: string; entry: unknown }) => Promise<void>; chatSyncFor…
+- MultiplayerSession (type): type MultiplayerSession = { gameId: string; userId: string; backend: LiveGameBackend; feedActions: string[]; }
+
+### @jgengine/core/scene/assetCatalog
+
+- createAssetCatalog (function): function createAssetCatalog<TMeta extends ModelAssetRef = ModelAssetRef>(): AssetCatalog<TMeta>
+- ModelDims (interface): interface ModelDims
+- ModelAssetRef (interface): interface ModelAssetRef
+- AssetCatalog (interface): interface AssetCatalog<TMeta extends ModelAssetRef = ModelAssetRef>
+
+### @jgengine/core/scene/assetPreload
+
+- createSceneAssetPreloader (function): function createSceneAssetPreloader(fetcher: SceneAssetFetcher): { preloadUrl(url: string): void; preloadUrls(urls: readonly string[]): void; hasPreloaded(url: string): boolean; reset(): void; }
+- SceneAssetFetcher (type): type SceneAssetFetcher = (url: string) => void
+
+### @jgengine/core/scene/autoTarget
+
+- selectAutoTarget (function): function selectAutoTarget(policy: AutoTargetPolicy, fromId: string, deps: AutoTargetDeps): string | null
+- createAutoTargeter (function): function createAutoTargeter(policy: AutoTargetPolicy, deps: AutoTargetDeps): AutoTargeter
+- AutoTargetPolicy (type): type AutoTargetPolicy = | "nearest" | "farthest" | "random" | "strongest" | "weakest" | "first" | "last"
+- AutoTargetDeps (interface): interface AutoTargetDeps
+- AutoTargeter (interface): interface AutoTargeter
+
+### @jgengine/core/scene/behaviors
+
+- wander (function): function wander({ radius }: { radius: number }): WanderBehavior
+- patrol (function): function patrol({ waypoints, speed, loop = true, }: { waypoints: readonly Waypoint[]; speed: number; loop?: boolean; }): PatrolBehavior
+- promptable (function): function promptable(prompt: ProximityPrompt): PromptableBehavior
+- talkable (function): function talkable(dialogueId: string): PromptableBehavior
+- player (function): function player(): PlayerBehavior
+- WanderBehavior (interface): interface WanderBehavior
+- PatrolBehavior (interface): interface PatrolBehavior
+- PromptableBehavior (interface): interface PromptableBehavior
+- PlayerBehavior (interface): interface PlayerBehavior
+- BehaviorDescriptor (type): type BehaviorDescriptor = | WanderBehavior | PatrolBehavior | PromptableBehavior | PlayerBehavior
+
+### @jgengine/core/scene/captureCheck
+
+- captureChance (function): function captureChance(input: CaptureCheckInput): number
+- rollCapture (function): function rollCapture(input: CaptureCheckInput, rng: () => number = Math.random): boolean
+- CaptureCheckInput (interface): interface CaptureCheckInput
+
+### @jgengine/core/scene/entityStats
+
+- getStatValue (function): function getStatValue(map: StatValueMap, statId: string): StatValue | null
+- setStatValue (function): function setStatValue(map: StatValueMap, statId: string, patch: StatValuePatch): StatValueMap
+- applyPoolDelta (function): function applyPoolDelta(map: StatValueMap, statId: string, amount: number): PoolDeltaResult
+- seedStatValues (function): function seedStatValues(catalogStats: StatCatalog): StatValueMap
+- createEntityStatsApi (function): function createEntityStatsApi(resolve: (instanceId: string) => StatValueMap | undefined): EntityStatsApi
+- StatValue (interface): interface StatValue
+- StatValuePatch (interface): interface StatValuePatch
+- StatValueMap (type): type StatValueMap = Record<string, StatValue>
+- StatCatalog (type): type StatCatalog = Record<string, { max: number; min?: number; current?: number }>
+- PoolDeltaResult (type): type PoolDeltaResult = | { status: "ok"; map: StatValueMap; stat: StatValue; hitMin: boolean; hitMax: boolean } | { status: "rejected"; reason: string }
+- EntityStatsApi (interface): interface EntityStatsApi
+
+### @jgengine/core/scene/entityStore
+
+- groundSpeed (function): function groundSpeed(entity: SceneEntity<unknown>): number — Ground speed (horizontal magnitude of velocity) in world units per second. Scale to km/h or mph in game code.
+- movedWhileFrozen (function): function movedWhileFrozen(entity: SceneEntity<unknown>, threshold = DEFAULT_FROZEN_MOVE_THRESHOLD): boolean
+- createEntityStore (function): function createEntityStore<TMeta = undefined>(): EntityStore<TMeta>
+- EntityRole (type): type EntityRole = "player" | "npc" | "prop"
+- EntityMovement (interface): interface EntityMovement
+- EntityPosition (type): type EntityPosition = readonly [number, number, number]
+- SpawnPositionInput (type): type SpawnPositionInput = EntityPosition | { x: number; y: number; z: number }
+- SceneEntity (interface): interface SceneEntity<TMeta = undefined>
+- SpawnOptions (interface): interface SpawnOptions<TMeta = undefined>
+- EntityPose (interface): interface EntityPose
+- SpawnPose (interface): interface SpawnPose
+- EntityStore (interface): interface EntityStore<TMeta = undefined>
+
+### @jgengine/core/scene/form
+
+- createForms (function): function createForms(deps: FormsDeps): Forms
+- FormDef (interface): interface FormDef
+- FormChangedEvent (interface): interface FormChangedEvent
+- FormEntities (interface): interface FormEntities
+- FormTime (interface): interface FormTime
+- FormEvents (interface): interface FormEvents
+- FormsDeps (interface): interface FormsDeps
+- Forms (interface): interface Forms
+
+### @jgengine/core/scene/mount
+
+- createMountController (function): function createMountController(): MountController
+- MountKind (type): type MountKind = "ground" | "boat" | "flying" | "swimming"
+- MountKit (interface): interface MountKit
+- MountSeat (interface): interface MountSeat
+- RideableConfig (interface): interface RideableConfig
+- SeatRef (interface): interface SeatRef
+- Occupant (interface): interface Occupant
+- MountResult (type): type MountResult = { ok: true; seat: MountSeat } | { ok: false; reason: string }
+- MountController (class): class MountController — Mount / rideable control-transfer (issue #83). Registers rideables (each with one or more seats — a control seat drives, the rest ride) and tracks who is on what. It owns no camera or physics: game code reads `cameraTarget(riderId)` to point the follow camera at the mount, and `driveTarget(riderId)` to route that rider's {@link import("../physics/vehicleBody").AxisInput}-driven input at the mount's movement kit — the same seam a horse, a truck, or a shared multi-seat ship all plug into.
+
+### @jgengine/core/scene/movementSpeed
+
+- deriveWalkSpeed (function): function deriveWalkSpeed(base: number, modifiers: MovementSpeedModifiers): number — `base * (multiplier ?? 1) + (flatBonus ?? 0)`, clamped to never go negative.
+- applyStatDrivenSpeed (function): function applyStatDrivenSpeed(deps: MovementSpeedDeps, instanceId: string, config: MovementSpeedConfig): boolean — Recomputes `movement.walkSpeed` for an entity from its stats and writes it back via `deps.entities.update`. Either stat id is optional; an omitted or unresolved stat contributes its neutral value (multiplier 1, flat bonus 0) rather than failing. Returns false only when the entity itself doesn't exist.
+- MovementSpeedModifiers (interface): interface MovementSpeedModifiers
+- MovementSpeedDeps (interface): interface MovementSpeedDeps
+- MovementSpeedConfig (interface): interface MovementSpeedConfig
+
+### @jgengine/core/scene/objectQuery
+
+- raycastObjects (function): function raycastObjects(objects: readonly SceneObject[], input: ObjectRaycastInput): ObjectRaycastHit | null
+- raycastObjectsAll (function): function raycastObjectsAll(objects: readonly SceneObject[], input: ObjectRaycastInput): ObjectRaycastHit[]
+- ObjectRaycastInput (interface): interface ObjectRaycastInput
+- ObjectRaycastHit (interface): interface ObjectRaycastHit
+
+### @jgengine/core/scene/objectStore
+
+- createObjectStore (function): function createObjectStore(): ObjectStore
+- objectVisualScale (function): function objectVisualScale(visual: ObjectVisual | undefined): readonly [number, number, number]
+- ObjectVisual (interface): interface ObjectVisual
+- SceneObject (interface): interface SceneObject
+- PlaceOptions (interface): interface PlaceOptions
+- ObjectListFilter (interface): interface ObjectListFilter
+- ObjectStore (interface): interface ObjectStore
+
+### @jgengine/core/scene/paintLayer
+
+- createPaintLayer (function): function createPaintLayer(): PaintLayer
+- PaintStroke (interface): interface PaintStroke
+- PaintLayer (interface): interface PaintLayer
+
+### @jgengine/core/scene/possession
+
+- createPossession (function): function createPossession(deps: PossessionDeps): Possession
+- PossessionSwappedEvent (interface): interface PossessionSwappedEvent
+- PossessionEntities (interface): interface PossessionEntities
+- PossessionEvents (interface): interface PossessionEvents
+- PossessionDeps (interface): interface PossessionDeps
+- Possession (interface): interface Possession
+
+### @jgengine/core/scene/roster
+
+- createRoster (function): function createRoster(deps: RosterDeps = {}): Roster
+- RosterEntry (interface): interface RosterEntry
+- RosterCaptureOptions (interface): interface RosterCaptureOptions
+- Roster (interface): interface Roster
+- RosterDeps (interface): interface RosterDeps
+
+### @jgengine/core/scene/selection
+
+- screenRect (function): function screenRect(ax: number, ay: number, bx: number, by: number): ScreenRect — Normalize two drag corners (in any order) into a rectangle.
+- rectContainsPoint (function): function rectContainsPoint(rect: ScreenRect, x: number, y: number): boolean
+- selectWithinRect (function): function selectWithinRect(candidates: readonly ScreenPoint[], rect: ScreenRect): string[] — Ids of the projected candidates whose screen point falls inside the marquee.
+- isMarquee (function): function isMarquee(rect: ScreenRect, thresholdPx = 4): boolean — True when the drag is large enough to be a marquee rather than a click.
+- createSelectionSet (function): function createSelectionSet(initial?: Iterable<string>): SelectionSet — An ordered, deduplicated set of selected instance ids for RTS unit-command routing.
+- ScreenRect (interface): interface ScreenRect
+- ScreenPoint (interface): interface ScreenPoint
+- SelectionSet (interface): interface SelectionSet
+
+### @jgengine/core/scene/spatial
+
+- distanceBetween (function): function distanceBetween(a: EntityPosition, b: EntityPosition): number
+- createSpatialApi (function): function createSpatialApi(options: SpatialApiOptions): SpatialApi
+- Aim (type): type Aim = | { origin: EntityPosition; direction: EntityPosition } | { yaw: number; pitch: number; spread?: number }
+- QueryArcOptions (interface): interface QueryArcOptions
+- MoveTowardOptions (interface): interface MoveTowardOptions
+- SpatialGridOptions (interface): interface SpatialGridOptions
+- SpatialApiOptions (interface): interface SpatialApiOptions
+- SpatialApi (interface): interface SpatialApi
+
+### @jgengine/core/scene/stationClaim
+
+- createStationClaim (function): function createStationClaim(controller?: MountController): StationClaim
+- Station (interface): interface Station
+- SharedVehicleConfig (interface): interface SharedVehicleConfig
+- ClaimResult (type): type ClaimResult = | { ok: true; station: Station } | { ok: false; reason: "unknown_vehicle" | "unknown_facet" | "station_taken" | "vehicle_full" }
+- StationClaim (class): class StationClaim
+
+### @jgengine/core/scene/targeting
+
+- createTargeting (function): function createTargeting(options: TargetingOptions): Targeting
+- TargetRelation (type): type TargetRelation = "hostile" | "friendly"
+- TargetFilter (type): type TargetFilter = TargetRelation | "any"
+- TargetingOptions (interface): interface TargetingOptions
+- CycleTargetOptions (interface): interface CycleTargetOptions
+- Targeting (interface): interface Targeting
+
+### @jgengine/core/sensor/concealment
+
+- colorDistance (function): function colorDistance(a: ColorHex, b: ColorHex): number
+- concealmentScore (function): function concealmentScore(entityColors: readonly ColorHex[], backgroundColors: readonly ColorHex[]): number
+- createConcealmentSensor (function): function createConcealmentSensor(config?: { threshold?: number }): ConcealmentSensor
+- ColorHex (type): type ColorHex = string
+- ConcealmentTarget (interface): interface ConcealmentTarget
+- ConcealmentSample (interface): interface ConcealmentSample
+- ConcealmentSensor (interface): interface ConcealmentSensor
+
+### @jgengine/core/sensor/freezeMonitor
+
+- createFreezeMonitor (function): function createFreezeMonitor(config?: { toleranceSpeed?: number; graceSeconds?: number }): FreezeMonitor
+- FreezeSubject (interface): interface FreezeSubject
+- FreezeViolation (interface): interface FreezeViolation
+- FreezeMonitor (interface): interface FreezeMonitor
+
+### @jgengine/core/sensor/frustumSensor
+
+- projectToView (function): function projectToView(camera: FrustumCamera, point: EntityPosition): FrustumProjection — Project a world point into the camera's view. Pure geometry — no three.js — so a game can run "is this framed?" checks headlessly (photo-mode scoring, server-side kill-cam validation) as well as from the live render camera.
+- framingScore (function): function framingScore(projection: FrustumProjection, config?: FramingConfig): number — 0 (not framed) .. 1 (dead-center, ideal distance) framing quality for an in-view projection.
+- createFrustumSensor (function): function createFrustumSensor(config?: FramingConfig): FrustumSensor — A view-frustum sensor on a held camera object: which entities are in frame, how well framed they are, and how long they've stayed on-screen (photo-mode "is this subject framed", Content Warning-style monster-filming scoring).
+- FrustumCamera (interface): interface FrustumCamera
+- FrustumTarget (interface): interface FrustumTarget
+- FrustumProjection (interface): interface FrustumProjection
+- FramingConfig (interface): interface FramingConfig
+- FrustumSample (interface): interface FrustumSample
+- FrustumSensor (interface): interface FrustumSensor
+
+### @jgengine/core/sensor/hiddenStateProbe
+
+- probeHiddenState (function): function probeHiddenState(origin: EntityPosition, sources: readonly HiddenStateSource[], options: SensorProbeOptions): SensorReading | null — A sensor verb: probe a hidden zone/entity state variable in range and surface a reading (EMF reader, spirit box, thermometer, geiger counter). Unlike `proximityPrompt` (a UI affordance), this reads world state the player has no other way to see — the strongest in-range reading wins, mirroring how a real handheld sensor needle settles on the loudest nearby source.
+- probeHiddenStateAll (function): function probeHiddenStateAll(origin: EntityPosition, sources: readonly HiddenStateSource[], options: SensorProbeOptions): SensorReading[] — All in-range readings for `variableId`, strongest first.
+- HiddenStateValue (type): type HiddenStateValue = number | string | boolean
+- HiddenStateSource (interface): interface HiddenStateSource
+- SensorProbeOptions (interface): interface SensorProbeOptions
+- SensorReading (interface): interface SensorReading
+
+### @jgengine/core/sensor/recordingBuffer
+
+- createRecordingBuffer (function): function createRecordingBuffer<T>(options: RecordingBufferOptions = {}): RecordingBuffer<T> — A session-recording buffer for replay / photo mode / kill-cam: append timestamped snapshots (poses, camera state, whatever `T` is) on game-time, then seek/scrub the recording independent of the live sim. Frames are expected in non-decreasing `t` order (one push per tick); `seek`/`range` binary-search on that assumption.
+- RecordingFrame (interface): interface RecordingFrame<T>
+- RecordingBufferOptions (interface): interface RecordingBufferOptions
+- RecordingBuffer (interface): interface RecordingBuffer<T>
+
+### @jgengine/core/sensor/revealQuery
+
+- createRevealQuery (function): function createRevealQuery(options: RevealQueryOptions): RevealQuery — `inRadius` already ignores occlusion; combat's AoE resolution is what layers a line-of-sight filter on top of it (see `effect({ at, radius, los })`). This is the same unfiltered radius query, scoped to catalog-declared tags and shaped for a vision readout (Dark Sight / detective-vision reveal) instead of damage resolution — it never consults an occluder, by design.
+- RevealHit (interface): interface RevealHit
+- RevealQueryOptions (interface): interface RevealQueryOptions
+- RevealQuery (interface): interface RevealQuery
+
+### @jgengine/core/session/contestedChannel
+
+- createContestedChannel (function): function createContestedChannel(config: ContestedChannelConfig): ContestedChannel
+- ContestedPhase (type): type ContestedPhase = "idle" | "active" | "paused" | "contested" | "complete" | "interrupted"
+- ContestReaction (type): type ContestReaction = "pause" | "decay"
+- ContestedChannelConfig (interface): interface ContestedChannelConfig
+- ContestedEventKind (type): type ContestedEventKind = "start" | "tick" | "contested" | "paused" | "complete" | "interrupted"
+- ContestedEvent (interface): interface ContestedEvent
+- ContestedSnapshot (interface): interface ContestedSnapshot
+- ContestedChannel (interface): interface ContestedChannel
+
+### @jgengine/core/session/extraction
+
+- createRaidSession (function): function createRaidSession(config: RaidSessionConfig): RaidSession
+- ExtractPoint (interface): interface ExtractPoint
+- RaidSessionConfig (interface): interface RaidSessionConfig
+- RaidStatus (type): type RaidStatus = "in-raid" | "extracting" | "extracted" | "dead"
+- ExtractionAttempt (interface): interface ExtractionAttempt
+- ExtractionResult (interface): interface ExtractionResult
+- DeathResult (interface): interface DeathResult
+- RaidPlayerSnapshot (interface): interface RaidPlayerSnapshot
+- RaidSession (interface): interface RaidSession
+
+### @jgengine/core/session/ring
+
+- ringSampleAt (function): function ringSampleAt(config: RingConfig, time: number): RingSample
+- createRing (function): function createRing(config: RingConfig): Ring
+- RingPoint (type): type RingPoint = [number, number]
+- RingPhase (interface): interface RingPhase
+- RingConfig (interface): interface RingConfig
+- RingSample (interface): interface RingSample
+- RingHit (interface): interface RingHit
+- Ring (interface): interface Ring
+
+### @jgengine/core/session/roles
+
+- assignRoles (function): function assignRoles(userIds: readonly string[], roles: readonly RoleSpec[], rng: () => number = Math.random): Record<string, string>
+- RoleSpec (interface): interface RoleSpec
+
+### @jgengine/core/session/roundState
+
+- lossBonusFor (function): function lossBonusFor(rule: LossBonusRule | undefined, streak: number): number
+- createRoundState (function): function createRoundState(config: RoundConfig<RoundPhase>): RoundState<RoundPhase>
+- RoundPhase (type): type RoundPhase = string
+- RoundPhaseDurations (interface): interface RoundPhaseDurations — Default phase-duration shape for the built-in buy/live/end cycle; pass a wider `Record<string, number>` when using a custom `phaseOrder`.
+- LossBonusRule (interface): interface LossBonusRule
+- RoundTeam (interface): interface RoundTeam — A team entry with an optional role tag (e.g. "attacker", "defender") retrievable via `RoundState.roleOf`.
+- RoundConfig (interface): interface RoundConfig<TPhase extends string = RoundPhase>
+- RoundEventKind (type): type RoundEventKind = | "phase.start" | "phase.end" | "round.win" | "round.economy" | "match.end"
+- RoundEconomy (interface): interface RoundEconomy
+- RoundEvent (interface): interface RoundEvent<TPhase extends string = RoundPhase>
+- PhaseEndHook (type): type PhaseEndHook<TPhase extends string = RoundPhase> = ( endingPhase: TPhase, nextPhase: TPhase, round: number, ) => void
+- RoundSnapshot (interface): interface RoundSnapshot<TPhase extends string = RoundPhase>
+- RoundState (interface): interface RoundState<TPhase extends string = RoundPhase>
+
+### @jgengine/core/stats/accumulatorMeter
+
+- tierAt (function): function tierAt(value: number, tiers: readonly MeterTier[]): string | null
+- createAccumulatorMeter (function): function createAccumulatorMeter(config: AccumulatorMeterConfig): AccumulatorMeter
+- MeterTier (interface): interface MeterTier
+- MeterMode (type): type MeterMode = "hold" | "reset"
+- AccumulatorMeterConfig (interface): interface AccumulatorMeterConfig
+- MeterAddResult (interface): interface MeterAddResult
+- AccumulatorMeter (interface): interface AccumulatorMeter
+
+### @jgengine/core/stats/eventMeter
+
+- createEventMeter (function): function createEventMeter(config: EventMeterConfig): EventMeter
+- EventMeterConfig (interface): interface EventMeterConfig
+- EventMeterFeedResult (interface): interface EventMeterFeedResult
+- EventMeter (interface): interface EventMeter
+
+### @jgengine/core/stats/rollCheck
+
+- rollCheck (function): function rollCheck(input: CheckInput, rng: () => number = Math.random): CheckResult
+- CheckAdvantage (type): type CheckAdvantage = "advantage" | "disadvantage" | "normal"
+- CheckInput (interface): interface CheckInput
+- CheckResult (interface): interface CheckResult
+
+### @jgengine/core/stats/statModifiers
+
+- createStats (function): function createStats<TStat extends string>(base: Record<TStat, number>): Stats<TStat>
+- StatModifier (interface): interface StatModifier
+- StatModifierSet (type): type StatModifierSet<TStat extends string> = Partial<Record<TStat, StatModifier>>
+- Stats (interface): interface Stats<TStat extends string>
+
+### @jgengine/core/store/changeSignal
+
+- createChangeSignal (function): function createChangeSignal(): ChangeSignal
+- notifyAfter (function): function notifyAfter<T extends object, K extends keyof T>(target: T, methods: readonly K[], notify: () => void): T
+- ChangeSignal (interface): interface ChangeSignal
+
+### @jgengine/core/store/engineStore
+
+- EngineStoreConfig (interface): interface EngineStoreConfig<TState, TAction, TEventMap extends object>
+- EngineStore (class): class EngineStore<TState, TAction, TEventMap extends object>
+
+### @jgengine/core/store/features
+
+- composeStateFeatures (function): function composeStateFeatures<TState, TAction, TEventMap extends object>(features: readonly StateFeature<TState, TAction, TEventMap>[]): { reduce(state: TState, action: TAction): TState; derive(state: TState): TState; onTransition(previous: TState, next: TState, emit: <K extends keyof TEventMap>(eve…
+- StateFeature (interface): interface StateFeature<TState, TAction, TEventMap extends object>
+
+### @jgengine/core/store/observableKeyedStore
+
+- createObservableKeyedStore (function): function createObservableKeyedStore<T>(areEqual?: (previous: T, next: T) => boolean): ObservableKeyedStore<T>
+- ObservableKeyedStore (interface): interface ObservableKeyedStore<T>
+
+### @jgengine/core/survival/decayMeter
+
+- createDecayMeterSet (function): function createDecayMeterSet(configs: readonly DecayMeterConfig[]): DecayMeterSet — Named decay meters — hunger, thirst, oxygen, sanity, warmth, stamina. Each drains (or recovers) on game-time `dt` at a configurable rate, refills from consumables or actions, and raises moodle statuses at thresholds. Rate modifiers let the environment drive them (colder → faster warmth loss; toxic biome → oxygen drops), so a game reads an environment field then calls `setRateModifier`.
+- MeterThreshold (interface): interface MeterThreshold
+- DecayMeterConfig (interface): interface DecayMeterConfig
+- DecayMeterState (interface): interface DecayMeterState
+- DecayMeterSet (interface): interface DecayMeterSet
+
+### @jgengine/core/survival/moodle
+
+- stackMoodles (function): function stackMoodles(...groups: readonly (readonly Moodle[])[]): Moodle[] — Merge any number of moodle groups into one stack — meters, ailments, and buffs share this display. Same-id moodles fold together (stacks add, worst severity wins); the result is ordered worst-first so the HUD reads critical statuses at a glance.
+- createMoodleStack (function): function createMoodleStack(): MoodleStack — A stateful holder for timed status moodles (food buffs, temporary shelter, warmth). Meters and multi-region health derive their own moodles on read; combine all three through `stackMoodles(stack.list(), meterMoodles, ailmentMoodles)` for one display.
+- MoodleSeverity (type): type MoodleSeverity = "good" | "neutral" | "warning" | "critical"
+- MoodleSource (type): type MoodleSource = "meter" | "ailment" | "buff"
+- Moodle (interface): interface Moodle
+- MOODLE_SEVERITY_ORDER (const): const MOODLE_SEVERITY_ORDER: Record<MoodleSeverity, number>
+- TimedMoodleInput (interface): interface TimedMoodleInput
+- MoodleStack (interface): interface MoodleStack
+
+### @jgengine/core/survival/regionHealth
+
+- createMultiRegionHealth (function): function createMultiRegionHealth(config: MultiRegionHealthConfig): MultiRegionHealth
+- HealthRegionConfig (interface): interface HealthRegionConfig
+- AilmentConfig (interface): interface AilmentConfig
+- MultiRegionHealthConfig (interface): interface MultiRegionHealthConfig
+- RegionHealthState (interface): interface RegionHealthState
+- AilmentInstance (interface): interface AilmentInstance
+- DamageResult (interface): interface DamageResult
+- TreatResult (interface): interface TreatResult
+- MultiRegionHealth (interface): interface MultiRegionHealth
+
+### @jgengine/core/tactics/fallingGrid
+
+- gravityIntervalMs (function): function gravityIntervalMs(level: number, config: GravityIntervalConfig = {}): number — Gravity tick interval for a given level: linear speed-up with a floor, generalizing `Games/block-stacker`'s `gravityInterval` (`max(0.05, 0.8 - level * 0.07)` seconds) to milliseconds with configurable base/step/floor.
+- createFallingGrid (function): function createFallingGrid<TCell>(config: FallingGridConfig): FallingGrid<TCell> — A game-agnostic cell grid for gravity-driven falling-block mechanics: bounded occupancy, footprint placement/collision, line-clear collapse, column-gravity settle (for match-3/sand style cascades), and a pure lock-delay helper. Extracted from `Games/block-stacker`'s tetris logic so any falling-block game can adopt it instead of reimplementing the grid.
+- FallingGridCell (type): type FallingGridCell = readonly [number, number]
+- FallingGridConfig (interface): interface FallingGridConfig
+- LockState (interface): interface LockState — Elapsed grounded time for the lock-delay state machine. `null` means airborne / not timing.
+- FallingGridSnapshot (interface): interface FallingGridSnapshot<TCell>
+- FallingGrid (interface): interface FallingGrid<TCell>
+- GravityIntervalConfig (interface): interface GravityIntervalConfig
+
+### @jgengine/core/tactics/predictiveQuery
+
+- predictAreaEffect (function): function predictAreaEffect(deps: PredictiveDeps, input: AreaPredictInput): PredictedTarget[]
+- predictArcEffect (function): function predictArcEffect(deps: PredictiveDeps, input: ArcPredictInput): PredictedTarget[]
+- predictTiles (function): function predictTiles(input: TilePredictInput): Tile[]
+- PredictiveDeps (interface): interface PredictiveDeps
+- PredictedTarget (interface): interface PredictedTarget
+- AreaPredictInput (interface): interface AreaPredictInput extends AreaTargetInput
+- ArcPredictInput (interface): interface ArcPredictInput
+- TilePredictInput (interface): interface TilePredictInput
+
+### @jgengine/core/tactics/snapshot
+
+- deepClone (function): function deepClone<T>(value: T): T
+- createSnapshotStore (function): function createSnapshotStore(): SnapshotStore
+- SnapshotSlice (interface): interface SnapshotSlice<T = unknown>
+- Snapshot (type): type Snapshot = Record<string, unknown>
+- SnapshotStore (interface): interface SnapshotStore
+
+### @jgengine/core/tactics/surface
+
+- createSurfaceLayer (function): function createSurfaceLayer(config: SurfaceLayerConfig): SurfaceLayer
+- SurfaceKindDef (interface): interface SurfaceKindDef
+- SurfaceReaction (interface): interface SurfaceReaction
+- SurfaceLayerConfig (interface): interface SurfaceLayerConfig
+- SurfacePatch (interface): interface SurfacePatch
+- SurfaceEvent (type): type SurfaceEvent = | { kind: "apply"; tile: Tile; surface: string } | { kind: "react"; tile: Tile; consumed: readonly [string, string]; produced: string | null } | { kind: "expire"; tile: Tile; surface: string }
+- SurfaceCellKind (interface): interface SurfaceCellKind
+- SurfaceCell (interface): interface SurfaceCell
+- SurfaceLayerSnapshot (type): type SurfaceLayerSnapshot = Record<string, Record<string, number | null>>
+- SurfaceLayer (interface): interface SurfaceLayer
+
+### @jgengine/core/tactics/tacticalGrid
+
+- createTacticalGrid (function): function createTacticalGrid(config: TacticalGridConfig): TacticalGrid
+- Tile (type): type Tile = readonly [number, number]
+- TacticalGridWorldConfig (interface): interface TacticalGridWorldConfig — Maps abstract `[col, row]` tiles onto world-space `[x, z]`, mirroring `navGrid`'s bounds+cellSize convention.
+- TacticalGridConfig (interface): interface TacticalGridConfig
+- ReachableOptions (interface): interface ReachableOptions
+- ReachableTile (interface): interface ReachableTile
+- PushObstacle (type): type PushObstacle = "wall" | "edge"
+- PushCollision (interface): interface PushCollision
+- PushMove (interface): interface PushMove
+- PushResult (interface): interface PushResult
+- PushOptions (interface): interface PushOptions
+- TacticalGridSnapshot (interface): interface TacticalGridSnapshot
+- TacticalGrid (interface): interface TacticalGrid
+
+### @jgengine/core/time/beatClock
+
+- createBeatClock (function): function createBeatClock(config: BeatClockConfig, onBeat?: (beatIndex: number) => void): BeatClock
+- nextBeatTime (function): function nextBeatTime(nowSec: number, beatDurationSec: number, epsilon = QUANTIZE_EPSILON): number — The absolute beat-time (game-seconds) that a press at `nowSec` quantizes to: the same instant if it lands on a beat boundary, else the next one.
+- createBeatInputBuffer (function): function createBeatInputBuffer<T>(beatDurationSec: number): BeatInputBuffer<T>
+- BeatClockConfig (interface): interface BeatClockConfig
+- BeatSnapshot (interface): interface BeatSnapshot
+- BeatClock (interface): interface BeatClock
+- BufferedAction (interface): interface BufferedAction<T>
+- BeatInputBuffer (interface): interface BeatInputBuffer<T>
+
+### @jgengine/core/time/calendarClock
+
+- computeGameTime (function): function computeGameTime(gameTimestamp: number): GameTime
+- computeClientServerOffset (function): function computeClientServerOffset(serverNow: number, clientNow: number): number
+- getGameClockTimestamp (function): function getGameClockTimestamp(createdAt: number, serverNow: number, clientNow: number, gameTimeScale?: number): number
+- GameTime (interface): interface GameTime
+
+### @jgengine/core/time/gameClock
+
+- sanitizeGameTimeScale (function): function sanitizeGameTimeScale(timeScale?: number | null): number
+- getScaledElapsedMs (function): function getScaledElapsedMs(createdAt: number, now: number, timeScale?: number | null): number
+- getCurrentGameTimestamp (function): function getCurrentGameTimestamp(createdAt: number, now: number, timeScale?: number | null): number
+- computeGameDay (function): function computeGameDay(createdAt: number, now: number = Date.now(), timeScale?: number | null): number
+- DEFAULT_TIME_SCALE (const): const DEFAULT_TIME_SCALE: 24 — Simulation clock: real time scaled into game time, plus the derived game-day counter.
+- SECONDS_PER_GAME_DAY (const): const SECONDS_PER_GAME_DAY: number
+
+### @jgengine/core/time/serverTick
+
+- planServerTick (function): function planServerTick<TSystemId extends string>(systems: readonly TickSystemDefinition<TSystemId>[], anchors: TickAnchors, now: number): ServerTickPlan<TSystemId> — Decides which systems a heartbeat should run. A system with no anchor runs immediately. Returned anchors carry only systems present in the pipeline, so removed systems clean up.
+- TickSystemDefinition (interface): interface TickSystemDefinition<TSystemId extends string = string>
+- TickAnchors (type): type TickAnchors = Record<string, number> — Last-run timestamp per system id.
+- ServerTickPlan (interface): interface ServerTickPlan<TSystemId extends string = string>
+
+### @jgengine/core/time/simClock
+
+- createSimClock (function): function createSimClock(options: SimClockOptions = {}): SimClock
+- TimeConfig (interface): interface TimeConfig
+- CalendarTime (interface): interface CalendarTime
+- ClockSnapshot (interface): interface ClockSnapshot
+- SimClock (interface): interface SimClock
+- SimClockOptions (interface): interface SimClockOptions
+
+### @jgengine/core/turn/commit
+
+- createCommitController (function): function createCommitController<TAction>(config: CommitControllerConfig): CommitController<TAction>
+- CommitMode (type): type CommitMode = "immediate" | "simultaneous" | "rewind"
+- SubmittedAction (interface): interface SubmittedAction<TAction>
+- CommitOutcome (interface): interface CommitOutcome<TAction>
+- CommitControllerConfig (interface): interface CommitControllerConfig
+- CommitController (interface): interface CommitController<TAction>
+
+### @jgengine/core/turn/intent
+
+- createIntentBoard (function): function createIntentBoard<TKind extends string = string>(): IntentBoard<TKind>
+- DeclaredIntent (interface): interface DeclaredIntent<TKind extends string = string>
+- IntentBoard (interface): interface IntentBoard<TKind extends string = string>
+
+### @jgengine/core/turn/turnLoop
+
+- createTurnLoop (function): function createTurnLoop<TAction = unknown>(config: TurnLoopConfig): TurnLoop<TAction>
+- CommitMode (type): type CommitMode = "immediate" | "simultaneous" | "rewind"
+- CommitController (interface): interface CommitController<TAction>
+- PoolConfig (interface): interface PoolConfig
+- TurnLoopConfig (interface): interface TurnLoopConfig
+- PoolState (interface): interface PoolState
+- TurnState (interface): interface TurnState
+- TurnLoopSnapshot (interface): interface TurnLoopSnapshot
+- TurnLoop (interface): interface TurnLoop<TAction = unknown>
+
+### @jgengine/core/world/buildingIndex
+
+- buildingIndex (function): function buildingIndex(buildings: readonly GeneratedBuilding[]): BuildingIndex
+- BuildingHit (interface): interface BuildingHit
+- BuildingIndex (interface): interface BuildingIndex
+
+### @jgengine/core/world/buildings
+
+- createBuildingConfig (function): function createBuildingConfig(input: BuildingConfigInput = {}): BuildingConfig
+- generateBuilding (function): function generateBuilding(input: BuildingConfigInput = {}): GeneratedBuilding
+- createBuildingGrid (function): function createBuildingGrid(config: BuildingGridConfig): BuildingLot[]
+- generateBuildingDistrict (function): function generateBuildingDistrict(config: BuildingGridConfig): GeneratedBuilding[]
+- BuildingSeed (type): type BuildingSeed = number | string
+- Vec3 (type): type Vec3 = readonly [number, number, number]
+- BuildingFacade (type): type BuildingFacade = "front" | "back" | "left" | "right" | "roof"
+- BuildingPartKind (type): type BuildingPartKind = | "wall" | "window" | "awning" | "airConditioner" | "clothesline" | "storefront" | "shutter" | "storeSign" | "roof" | "roofProp" | "guardrail" | "corner"
+- BuildingPartTag (type): type BuildingPartTag = "ground" | "upper" | "open" | "closed" | "decor" | "structure"
+- BuildingProbabilities (interface): interface BuildingProbabilities
+- BuildingVariantCounts (interface): interface BuildingVariantCounts
+- BuildingConfig (interface): interface BuildingConfig
+- BuildingConfigInput (type): type BuildingConfigInput = Partial< Omit<BuildingConfig, "probabilities" | "variants"> > & { probabilities?: Partial<BuildingProbabilities>; variants?: Partial<BuildingVariantCounts>; }
+- BuildingKitSlot (interface): interface BuildingKitSlot
+- BuildingCellRef (interface): interface BuildingCellRef
+- BuildingPartPlacement (interface): interface BuildingPartPlacement
+- GeneratedBuilding (interface): interface GeneratedBuilding
+- BuildingLot (interface): interface BuildingLot
+- BuildingGridConfig (interface): interface BuildingGridConfig
+- DEFAULT_BUILDING_CONFIG (const): const DEFAULT_BUILDING_CONFIG: BuildingConfig
+
+### @jgengine/core/world/buildPermissions
+
+- createPlotPermissions (function): function createPlotPermissions(config: PlotPermissionConfig): PlotPermissions
+- createContributionPool (function): function createContributionPool(goal: ContributionGoal): ContributionPool
+- BuildRole (type): type BuildRole = "owner" | "editor" | "viewer"
+- PlotPermissionConfig (interface): interface PlotPermissionConfig
+- PlotPermissionSnapshot (interface): interface PlotPermissionSnapshot
+- BuildActor (interface): interface BuildActor
+- PlotPermissions (interface): interface PlotPermissions
+- ContributionGoal (type): type ContributionGoal = Readonly<Record<string, number>>
+- ContributionResult (interface): interface ContributionResult
+- ContributionPool (interface): interface ContributionPool
+
+### @jgengine/core/world/carve
+
+- carvableTerrain (function): function carvableTerrain(base: TerrainField): CarvableField
+- EMPTY_VOXEL (const): const EMPTY_VOXEL: 0
+- VoxelMaterial (interface): interface VoxelMaterial
+- VoxelMaterialTable (type): type VoxelMaterialTable = Readonly<Record<number, VoxelMaterial>>
+- VoxelVolumeConfig (interface): interface VoxelVolumeConfig
+- CarveOp (interface): interface CarveOp
+- DepositOp (interface): interface DepositOp
+- VoxelVolume (class): class VoxelVolume — A runtime-editable dense voxel grid — the carve/deposit op behind destructible dig worlds (Deep Rock Galactic tunnels, Astroneer terrain). Cells hold a material id (0 = empty); `carve` clears a sphere of solid cells that a tool is strong enough to break and returns how many it removed (feed that to a loot roll), `deposit` fills a sphere with a material. World↔cell mapping is `origin`+`scale`.
+- CraterOp (interface): interface CraterOp
+- MoundOp (interface): interface MoundOp
+- CarvableField (class): class CarvableField implements TerrainField — A `TerrainField` you can write craters and mounds into at runtime — the height-field side of destructible terrain (Helldivers 2 explosion craters, engineer-deposited berms). Wraps a base field and layers smooth radial deformations on top, so `sampleHeight` (and therefore ground-snap, collision, and the shell's terrain mesh) all read the deformed surface. `carve` digs a bowl, `deposit` raises a mound.
+
+### @jgengine/core/world/connectors
+
+- socketsCompatible (function): function socketsCompatible(a: ConnectorSocket, b: ConnectorSocket): boolean
+- socketWorldPosition (function): function socketWorldPosition(socket: ConnectorSocket, origin: ConnectorVec3, rotationY: number): ConnectorVec3
+- worldSockets (function): function worldSockets(def: ConnectorPieceDef, piece: PlacedPiece): WorldSocket[]
+- collectWorldSockets (function): function collectWorldSockets(registry: ConnectorRegistry, pieces: readonly PlacedPiece[]): WorldSocket[]
+- snapToNearest (function): function snapToNearest(registry: ConnectorRegistry, placed: readonly PlacedPiece[], movingDef: ConnectorPieceDef, cursor: ConnectorVec3, options: SnapOptions = {}): SnapResult | null
+- ConnectorVec3 (type): type ConnectorVec3 = readonly [number, number, number]
+- ConnectorSocket (interface): interface ConnectorSocket
+- ConnectorPieceDef (interface): interface ConnectorPieceDef
+- PlacedPiece (interface): interface PlacedPiece
+- WorldSocket (interface): interface WorldSocket
+- SnapResult (interface): interface SnapResult
+- SnapOptions (interface): interface SnapOptions
+- ConnectorRegistry (type): type ConnectorRegistry = (kind: string) => ConnectorPieceDef | null
+
+### @jgengine/core/world/envField
+
+- createEnvironmentField (function): function createEnvironmentField(config: EnvironmentFieldConfig = {}): EnvironmentField — A sampleable environment field: read temperature, wetness, sun/sky exposure, and ambient light at any world position and time. Built on the same renderer-free footing as terrain/wind/water so meters, spawn gating, and damage-in-sunlight read the world the shell renders — no three.js. Instantaneous and pure (no accumulation); stateful build-up belongs to a decay meter reading this field.
+- OccluderRect (interface): interface OccluderRect — A sky-occluding footprint — a roof, dense canopy, a cave mouth. `shade` 0..1 = fraction of sky blocked.
+- HeatSource (interface): interface HeatSource — A localized warmth source — campfire, forge, geothermal vent.
+- ShadeProvider (type): type ShadeProvider = readonly OccluderRect[] | ((x: number, z: number) => number)
+- ScalarField (type): type ScalarField = number | ((x: number, z: number, time: number) => number)
+- EnvironmentFieldConfig (interface): interface EnvironmentFieldConfig
+- EnvironmentSample (interface): interface EnvironmentSample
+- EnvironmentField (interface): interface EnvironmentField
+
+### @jgengine/core/world/environmentSummary
+
+- resolveStructureBuildings (function): function resolveStructureBuildings(descriptor: BuildingEnvironmentDescriptor): GeneratedBuilding[]
+- summarizeEnvironment (function): function summarizeEnvironment(feature: EnvironmentWorldFeature): EnvironmentSummary
+- TerrainHeightStats (interface): interface TerrainHeightStats
+- TerrainSummary (interface): interface TerrainSummary
+- StructureSummary (interface): interface StructureSummary
+- VegetationSummary (interface): interface VegetationSummary
+- WaterSummary (interface): interface WaterSummary
+- WeatherSummary (interface): interface WeatherSummary
+- EnvironmentCounts (interface): interface EnvironmentCounts
+- EnvironmentSummary (interface): interface EnvironmentSummary
+
+### @jgengine/core/world/features
+
+- padFlattenMasks (function): function padFlattenMasks(pads: readonly PadEnvironmentDescriptor[]): readonly TerrainFlattenMask[] — Derives implicit `TerrainFlattenMask`s carving each pad's footprint into the terrain beneath it.
+- environment (function): function environment(config: EnvironmentWorldConfig = {}): EnvironmentWorldFeature
+- terrain (function): function terrain(config: TerrainEnvironmentConfig = {}): TerrainEnvironmentDescriptor
+- sky (function): function sky(config: SkyEnvironmentConfig = {}): SkyEnvironmentDescriptor
+- rain (function): function rain(config: RainEnvironmentConfig = {}): RainEnvironmentDescriptor
+- snow (function): function snow(config: SnowEnvironmentConfig = {}): SnowEnvironmentDescriptor
+- grass (function): function grass(config: GrassEnvironmentConfig = {}): GrassEnvironmentDescriptor
+- ocean (function): function ocean(config: OceanEnvironmentConfig = {}): OceanEnvironmentDescriptor
+- building (function): function building(config: BuildingEnvironmentConfig = {}): BuildingEnvironmentDescriptor
+- pad (function): function pad(config: PadEnvironmentConfig): PadEnvironmentDescriptor
+- biomes (function): function biomes(config: BiomesWorldConfig): WorldFeature
+- voxel (function): function voxel(config: VoxelWorldConfig): WorldFeature
+- plots (function): function plots(config: PlotsWorldConfig = {}): WorldFeature
+- tilemap (function): function tilemap(config: TilemapWorldConfig): WorldFeature
+- flat (function): function flat(): WorldFeature
+- WorldBounds (interface): interface WorldBounds
+- EnvironmentVec2 (type): type EnvironmentVec2 = readonly [number, number]
+- EnvironmentArea (interface): interface EnvironmentArea extends WorldBounds
+- TerrainColors (interface): interface TerrainColors
+- TerrainFlattenMask (interface): interface TerrainFlattenMask
+- TerrainEnvironmentConfig (interface): interface TerrainEnvironmentConfig
+- RainEnvironmentConfig (interface): interface RainEnvironmentConfig
+- SnowEnvironmentConfig (interface): interface SnowEnvironmentConfig
+- GrassEnvironmentConfig (interface): interface GrassEnvironmentConfig
+- OceanEnvironmentConfig (interface): interface OceanEnvironmentConfig
+- SkyEnvironmentConfig (interface): interface SkyEnvironmentConfig
+- BuildingEnvironmentConfig (interface): interface BuildingEnvironmentConfig
+- PadSize (type): type PadSize = readonly [number, number] | { radius: number }
+- PadEnvironmentConfig (interface): interface PadEnvironmentConfig
+- TerrainEnvironmentDescriptor (type): type TerrainEnvironmentDescriptor = { kind: "terrain" } & Required< Pick<TerrainEnvironmentConfig, "bounds" | "height"> > & Omit<TerrainEnvironmentConfig, "bounds" | "height">
+- RainEnvironmentDescriptor (type): type RainEnvironmentDescriptor = { kind: "rain" } & Required< Pick<RainEnvironmentConfig, "area" | "density" | "speed" | "dropLength" | "wind" | "color"> >
+- SnowEnvironmentDescriptor (type): type SnowEnvironmentDescriptor = { kind: "snow" } & Required< Pick<SnowEnvironmentConfig, "area" | "density" | "speed" | "flakeSize" | "drift" | "wind" | "color"> >
+- GrassEnvironmentDescriptor (type): type GrassEnvironmentDescriptor = { kind: "grass" } & Required< Pick<GrassEnvironmentConfig, "area" | "density" | "bladeHeight" | "bladeWidth" | "windStrength" | "colors"> > & Pick<GrassEnvironmentConfig, "seed">
+- OceanEnvironmentDescriptor (type): type OceanEnvironmentDescriptor = { kind: "ocean" } & Required< Pick<OceanEnvironmentConfig, "bounds" | "level" | "waveHeight" | "waveScale" | "waveSpeed" | "color"> > & Pick<OceanEnvironmentConfig, "position">
+- BuildingEnvironmentDescriptor (type): type BuildingEnvironmentDescriptor = { kind: "building" } & Required< Pick<BuildingEnvironmentConfig, "count" | "footprint" | "stories" | "storyHeight" | "spacing" | "style"> > & Pick<BuildingEnvironmentConfig, "seed" | "position">
+- PadEnvironmentDescriptor (type): type PadEnvironmentDescriptor = { kind: "pad" } & Required< Pick<PadEnvironmentConfig, "center" | "size" | "height" | "color"> > & Pick<PadEnvironmentConfig, "rotationY">
+- SkyEnvironmentDescriptor (type): type SkyEnvironmentDescriptor = { kind: "sky" } & Required< Pick<SkyEnvironmentConfig, "preset" | "timeOfDay"> > & Omit<SkyEnvironmentConfig, "preset" | "timeOfDay">
+- WeatherEnvironmentDescriptor (type): type WeatherEnvironmentDescriptor = RainEnvironmentDescriptor | SnowEnvironmentDescriptor
+- VegetationEnvironmentDescriptor (type): type VegetationEnvironmentDescriptor = GrassEnvironmentDescriptor
+- WaterEnvironmentDescriptor (type): type WaterEnvironmentDescriptor = OceanEnvironmentDescriptor
+- StructureEnvironmentDescriptor (type): type StructureEnvironmentDescriptor = BuildingEnvironmentDescriptor
+- EnvironmentDescriptorList (type): type EnvironmentDescriptorList<T> = T | readonly T[]
+- EnvironmentWorldConfig (interface): interface EnvironmentWorldConfig
+- EnvironmentWorldFeature (interface): interface EnvironmentWorldFeature
+- WorldGridCell (interface): interface WorldGridCell
+- WorldGridConfig (interface): interface WorldGridConfig — Shared by `biomes()`/`voxel()`/`plots()`/`tilemap()` so the shell can render their declared content as instanced boxes without a hand-written renderer.
+- BiomesWorldConfig (interface): interface BiomesWorldConfig extends WorldGridConfig
+- VoxelWorldConfig (interface): interface VoxelWorldConfig extends WorldGridConfig
+- PlotsWorldConfig (interface): interface PlotsWorldConfig extends WorldGridConfig
+- TilemapWorldConfig (interface): interface TilemapWorldConfig extends WorldGridConfig
+- WorldFeature (type): type WorldFeature = | ({ kind: "biomes" } & BiomesWorldConfig) | ({ kind: "voxel" } & VoxelWorldConfig) | ({ kind: "plots" } & PlotsWorldConfig) | ({ kind: "tilemap" } & TilemapWorldConfig) | EnvironmentWorldFeature | { kind: "flat" }
+
+### @jgengine/core/world/fog
+
+- createFogField (function): function createFogField(config: FogConfig): FogField
+- FogBounds (interface): interface FogBounds
+- FogConfig (interface): interface FogConfig
+- FogCells (interface): interface FogCells
+- FogField (interface): interface FogField — Reveal-on-event fog of war over a fixed grid. Walking (`revealAlong`) and digging/acting (`reveal`) clear cells; once revealed a cell stays revealed. Pure and renderer-free — the shell/react map draws `cells()`.
+
+### @jgengine/core/world/geometry
+
+- snapToGrid (function): function snapToGrid(point: Vec2, size: number): Vec2
+- footprintAabb (function): function footprintAabb(center: Vec2, footprint: Footprint, quarterTurns = 0): Aabb
+- expandAabb (function): function expandAabb(aabb: Aabb, margin: number): Aabb
+- aabbOverlap (function): function aabbOverlap(a: Aabb, b: Aabb): boolean
+- aabbContains (function): function aabbContains(outer: Aabb, inner: Aabb): boolean
+- pointInAabb (function): function pointInAabb(point: Vec2, aabb: Aabb): boolean
+- clampToAabb (function): function clampToAabb(point: Vec2, aabb: Aabb): Vec2
+- resolveMove (function): function resolveMove(from: Vec2, delta: Vec2, blockers: readonly Aabb[], options: MoveOptions = {}): Vec2
+- Vec2 (type): type Vec2 = readonly [number, number]
+- Footprint (interface): interface Footprint
+- Aabb (interface): interface Aabb
+- MoveOptions (interface): interface MoveOptions
+
+### @jgengine/core/world/gridInstances
+
+- resolveGridInstances (function): function resolveGridInstances(config: WorldGridConfig): readonly GridInstanceTransform[] — Pure cell→instance math for `biomes()`/`voxel()`/`plots()`/`tilemap()` world features: one extruded box per declared cell, grounded at y=0 and centered on its cell in x/z. Consumed by the shell's grid-world renderer so it can drive a single `THREE.InstancedMesh` without duplicating this math per game.
+- GridInstanceTransform (interface): interface GridInstanceTransform
+
+### @jgengine/core/world/interiors
+
+- createInteriors (function): function createInteriors(config: InteriorsConfig = {}): Interiors
+- SpaceRef (type): type SpaceRef = { kind: "exterior" } | { kind: "interior"; id: string }
+- EntityLocation (interface): interface EntityLocation
+- Interior (interface): interface Interior
+- Exterior (interface): interface Exterior
+- InteriorsConfig (interface): interface InteriorsConfig
+- Interiors (interface): interface Interiors
+
+### @jgengine/core/world/markers
+
+- markerKindStyle (function): function markerKindStyle(kind: string, styles: Record<string, MarkerKindStyle> = DEFAULT_MARKER_KINDS): MarkerKindStyle
+- createMarkerSet (function): function createMarkerSet<TMeta = unknown>(now: () => number = Date.now): MarkerSet<TMeta>
+- MarkerPosition (type): type MarkerPosition = readonly [number, number, number]
+- MapMarker (interface): interface MapMarker<TMeta = unknown>
+- MarkerInput (interface): interface MarkerInput<TMeta = unknown>
+- MarkerQuery (interface): interface MarkerQuery
+- MarkerKindStyle (interface): interface MarkerKindStyle — Visual descriptor for a marker kind. Games supply their own palette; the engine ships `DEFAULT_MARKER_KINDS` as a content-agnostic starting set that the react minimap/compass read for colors and glyphs.
+- DEFAULT_MARKER_KINDS (const): const DEFAULT_MARKER_KINDS: Record<string, MarkerKindStyle>
+- MarkerSet (interface): interface MarkerSet<TMeta = unknown>
+
+### @jgengine/core/world/minimap
+
+- compassBearing (function): function compassBearing(from: WorldXZ, to: WorldXZ): number — Compass bearing (radians, 0 = map north = −Z, increasing clockwise toward +X = east) from one world XZ point to another. Feeds both the minimap direction and the compass strip.
+- headingToBearing (function): function headingToBearing(yaw: number): number — Bearing of an entity facing direction given its `rotationY` (yaw) in radians.
+- bearingToCardinal (function): function bearingToCardinal(bearing: number): Cardinal
+- relativeBearing (function): function relativeBearing(bearing: number, reference: number): number — Signed offset of `bearing` from `reference`, wrapped into (−π, π].
+- projectToMinimap (function): function projectToMinimap(world: WorldXZ | readonly [number, number, number], view: MinimapView): MinimapPoint — Project a world XZ (or XYZ) point into minimap pixel space. Origin is the top-left of the `size×size` box; north (−Z) maps to −Y (up). Pass `view.rotate` to spin the map under a fixed north-up player arrow.
+- clampToMinimapEdge (function): function clampToMinimapEdge(point: MinimapPoint, size: number): { x: number; y: number } — Clamp a projected point to the minimap edge, preserving direction (edge markers).
+- WorldXZ (type): type WorldXZ = readonly [number, number]
+- Cardinal (type): type Cardinal = "N" | "NE" | "E" | "SE" | "S" | "SW" | "W" | "NW"
+- MinimapView (interface): interface MinimapView
+- MinimapPoint (interface): interface MinimapPoint
+
+### @jgengine/core/world/placedStructureStore
+
+- createPlacedStructureStore (function): function createPlacedStructureStore(): PlacedStructureStore
+- StructureVec3 (type): type StructureVec3 = readonly [number, number, number]
+- PlacedStructure (interface): interface PlacedStructure
+- AddStructureInput (interface): interface AddStructureInput
+- StructureFilter (interface): interface StructureFilter
+- PlacedStructureSnapshot (interface): interface PlacedStructureSnapshot
+- PlacedStructureStore (interface): interface PlacedStructureStore
+
+### @jgengine/core/world/placement
+
+- validatePlacement (function): function validatePlacement(request: PlacementRequest, rules: PlacementRules = {}): PlacementResult
+- footprintObstacle (function): function footprintObstacle(request: PlacementRequest, id?: string): PlacementObstacle
+- PlacementObstacle (interface): interface PlacementObstacle
+- PlacementRequest (interface): interface PlacementRequest
+- PlacementRules (interface): interface PlacementRules
+- PlacementResult (type): type PlacementResult = | { status: "ok"; center: Vec2; aabb: Aabb } | { status: "rejected"; reason: "out-of-bounds" } | { status: "rejected"; reason: "overlap"; obstacle: PlacementObstacle; index: number }
+
+### @jgengine/core/world/placementController
+
+- quarterTurnsToRotationY (function): function quarterTurnsToRotationY(quarterTurns: number): number
+- createPlacementController (function): function createPlacementController(config: PlacementControllerConfig): PlacementController
+- SnapMode (type): type SnapMode = "grid" | "free" | "surface"
+- PlacementVec3 (type): type PlacementVec3 = readonly [number, number, number]
+- PlacementHit (interface): interface PlacementHit
+- PlacementSlot (interface): interface PlacementSlot — A fixed buildable slot the placement controller snaps to instead of grid/free positioning.
+- PlacementControllerConfig (interface): interface PlacementControllerConfig
+- PlacementPreview (interface): interface PlacementPreview
+- PlacementCommit (interface): interface PlacementCommit
+- PlacementController (interface): interface PlacementController
+
+### @jgengine/core/world/realm
+
+- composeRealm (function): function composeRealm(base: RealmBase, cards: readonly RealmCard[]): ComposedRealm — Assemble a played realm instance at runtime from a deck of modifier cards — the Nightingale "realm card" model. A major card is the biome base; minor cards layer weather, day length, and spawn edits. The result recomposes both the environment (into a sampleable field via `environmentField()`) and the spawn table, and it depends on the weather hooks in this group (#92) to turn its `weather` into gameplay modifiers. Cards apply in array order; sort your deck (majors first) before composing.
+- RealmEnvironmentParams (interface): interface RealmEnvironmentParams — The recomposable environment parameters a realm card can override.
+- DEFAULT_REALM_ENVIRONMENT (const): const DEFAULT_REALM_ENVIRONMENT: RealmEnvironmentParams
+- SpawnTableOverride (interface): interface SpawnTableOverride — Spawn-table edits a card layers on: replace weights, add/scale, or remove ids.
+- RealmCard (interface): interface RealmCard
+- RealmBase (interface): interface RealmBase
+- ComposedRealm (interface): interface ComposedRealm
+
+### @jgengine/core/world/regions
+
+- createRegionField (function): function createRegionField<T = unknown>(config: RegionFieldConfig<T>): RegionField<T>
+- isRegionField (function): function isRegionField(field: TerrainField): field is RegionField
+- Rgb (type): type Rgb = readonly [number, number, number]
+- ColorInput (type): type ColorInput = string | Rgb
+- RegionHeight (interface): interface RegionHeight
+- RegionDef (interface): interface RegionDef<T = unknown> — A content-agnostic region. The engine blends `height` and the visual/physical knobs (`tint`, `water`, `fog`, `speedMultiplier`, …) across region borders and selects the dominant region by nearest center in `selector` space. `data` is an opaque payload the engine never inspects — games hang their own content off it (spawn tables, prop palettes, structure ids, names, …).
+- RegionSample (interface): interface RegionSample<T = unknown>
+- RegionField (interface): interface RegionField<T = unknown> extends TerrainField
+- RegionFieldConfig (interface): interface RegionFieldConfig<T = unknown>
+
+### @jgengine/core/world/scatter
+
+- scatterAabb (function): function scatterAabb(area: ScatterArea | Aabb): Aabb
+- scatter (function): function scatter(config: ScatterConfig): ScatterPoint[]
+- ScatterArea (interface): interface ScatterArea
+- ScatterConfig (interface): interface ScatterConfig
+- ScatterPoint (interface): interface ScatterPoint
+
+### @jgengine/core/world/scatterItems
+
+- scatterItems (function): function scatterItems<T>(field: RegionField<T>, area: Aabb, layersFor: (sample: RegionSample<T>) => readonly ScatterLayer[], options: { cell?: number; max?: number; saltKey?: number } = {}): ScatterInstance[] — Deterministically place opaque items across `area`, grounded on a region field. For each grid cell it asks `layersFor` which items may appear in that region and rolls one against their densities. The engine never interprets `item` — a game maps it to a mesh or entity. Content scatter (region-driven density) as opposed to `scatter` in `./scatter`, which is renderer-free geometric point distribution.
+- pickWeighted (function): function pickWeighted<T>(entries: readonly { value: T; weight: number }[], roll: number): T | null — Weighted pick from opaque entries; `roll` in [0, 1). Returns null when empty.
+- ScatterLayer (interface): interface ScatterLayer — One placeable class. `item` is an opaque id the caller maps to a mesh/entity.
+- ScatterInstance (interface): interface ScatterInstance
+
+### @jgengine/core/world/support
+
+- solveSupport (function): function solveSupport(pieces: readonly SupportPiece[], links: readonly SupportLink[], config: SupportConfig = {}): SupportResult
+- toDebrisBodies (function): function toDebrisBodies(pieces: readonly SupportPiece[], collapsedIds: readonly string[], options: DebrisOptions = {}): AddBodyOptions[]
+- SupportPiece (interface): interface SupportPiece
+- SupportLink (interface): interface SupportLink
+- SupportConfig (interface): interface SupportConfig
+- SupportResult (interface): interface SupportResult
+- DebrisOptions (interface): interface DebrisOptions
+
+### @jgengine/core/world/terraform
+
+- brushWeight (function): function brushWeight(distance: number, radius: number, falloff: TerraformFalloff): number
+- createEditableTerrain (function): function createEditableTerrain(config: EditableTerrainConfig): EditableTerrain
+- createTerraformBrush (function): function createTerraformBrush(terrain: Pick<EditableTerrain, "apply">, config: TerraformBrushConfig = {}): TerraformBrush
+- TerraformMode (type): type TerraformMode = "raise" | "lower" | "flatten" | "paint"
+- TerraformFalloff (type): type TerraformFalloff = "smooth" | "linear" | "none"
+- TerraformEdit (interface): interface TerraformEdit
+- EditableTerrainConfig (interface): interface EditableTerrainConfig
+- TerraformSnapshot (interface): interface TerraformSnapshot
+- EditableTerrain (interface): interface EditableTerrain extends TerrainField
+- TerraformBrushConfig (interface): interface TerraformBrushConfig
+- TerraformBrush (interface): interface TerraformBrush
+
+### @jgengine/core/world/terrain
+
+- valueNoise (function): function valueNoise(x: number, z: number, seed: number): number
+- fractalNoise (function): function fractalNoise(x: number, z: number, config: FractalNoiseConfig): number
+- seedFrom (function): function seedFrom(value: string | number | undefined, fallback: number): number
+- withNormal (function): function withNormal(sampleHeight: (x: number, z: number) => number): TerrainField["sampleNormal"]
+- flatField (function): function flatField(): TerrainField
+- noiseField (function): function noiseField(config: NoiseFieldConfig = {}): TerrainField
+- rollingField (function): function rollingField(config: RollingFieldConfig = {}): TerrainField
+- arenaField (function): function arenaField(config: ArenaFieldConfig = {}): TerrainField
+- groundFieldFor (function): function groundFieldFor(world?: WorldFeature): TerrainField
+- resolveTerrainPalette (function): function resolveTerrainPalette(descriptor: Pick<TerrainEnvironmentConfig, "material" | "colors"> = {}): TerrainPalette
+- resolveTerrainField (function): function resolveTerrainField(descriptor?: TerrainEnvironmentDescriptor): TerrainField
+- snapToGround (function): function snapToGround(field: TerrainField, position: readonly [number, number, number], offset = 0): [number, number, number] — Returns `position` with `y` replaced by the field's ground height (plus `offset`) at its `x`/`z`.
+- snapEntityToGround (function): function snapEntityToGround(entities: GroundSnapEntityStore, id: string, field: TerrainField, offset = 0): boolean — Ground-snaps an already-spawned entity in place; returns false when `id` is unknown.
+- resolveGroundStep (function): function resolveGroundStep(field: TerrainField, x: number, z: number, stepX: number, stepZ: number, maxSlope = DEFAULT_MAX_WALK_SLOPE): { stepX: number; stepZ: number }
+- TerrainNormal (type): type TerrainNormal = readonly [number, number, number]
+- TerrainField (interface): interface TerrainField
+- FractalNoiseConfig (interface): interface FractalNoiseConfig
+- FLAT_FIELD (const): const FLAT_FIELD: TerrainField
+- NoiseFieldConfig (interface): interface NoiseFieldConfig
+- RollingFieldConfig (interface): interface RollingFieldConfig
+- ArenaFieldConfig (interface): interface ArenaFieldConfig
+- ARENA_WATER_LEVEL (const): const ARENA_WATER_LEVEL: -0.9
+- TerrainPalette (interface): interface TerrainPalette
+- DEFAULT_TERRAIN_MATERIAL (const): const DEFAULT_TERRAIN_MATERIAL: "grass"
+- TERRAIN_MATERIAL_PALETTES (const): const TERRAIN_MATERIAL_PALETTES: Record<string, TerrainPalette>
+- GroundSnapTarget (interface): interface GroundSnapTarget
+- GroundSnapEntityStore (interface): interface GroundSnapEntityStore
+- DEFAULT_MAX_WALK_SLOPE (const): const DEFAULT_MAX_WALK_SLOPE: 0.6
+
+### @jgengine/core/world/voxelField
+
+- createVoxelField (function): function createVoxelField<T extends string = string>(config?: VoxelFieldConfig): VoxelField<T>
+- VoxelCoord (type): type VoxelCoord = readonly [number, number, number]
+- VoxelFace (type): type VoxelFace = "px" | "nx" | "py" | "ny" | "pz" | "nz"
+- VoxelFieldConfig (interface): interface VoxelFieldConfig
+- VoxelCell (interface): interface VoxelCell<T extends string = string>
+- VoxelHit (interface): interface VoxelHit<T extends string = string>
+- VoxelBounds (interface): interface VoxelBounds
+- VoxelFieldSummary (interface): interface VoxelFieldSummary<T extends string = string>
+- VoxelField (interface): interface VoxelField<T extends string = string>
+- VOXEL_FACES (const): const VOXEL_FACES: readonly VoxelFace[]
+- VOXEL_FACE_NORMALS (const): const VOXEL_FACE_NORMALS: Record<VoxelFace, VoxelCoord>
+
+### @jgengine/core/world/walls
+
+- wallSegments (function): function wallSegments(points: readonly Vec2[], closed: boolean): WallSegment[]
+- isEnclosed (function): function isEnclosed(points: readonly Vec2[], tolerance = 0.5): boolean
+- enclosePath (function): function enclosePath(points: readonly Vec2[], tolerance = 0.5): readonly Vec2[]
+- polygonArea (function): function polygonArea(polygon: readonly Vec2[]): number
+- footprintFromWalls (function): function footprintFromWalls(points: readonly Vec2[], tolerance = 0.5): EnclosedFootprint | null
+- autoRoof (function): function autoRoof(footprint: EnclosedFootprint, config: RoofConfig = {}): RoofPlan
+- createSurfacePaint (function): function createSurfacePaint(): SurfacePaintStore
+- createWallDrawTool (function): function createWallDrawTool(config: { snap?: number; closeTolerance?: number } = {}): WallDrawTool
+- wallSegmentBounds (function): function wallSegmentBounds(segment: WallSegment, thickness: number): Aabb
+- WallVec3 (type): type WallVec3 = readonly [number, number, number]
+- WallSegment (interface): interface WallSegment
+- EnclosedFootprint (interface): interface EnclosedFootprint
+- RoofStyle (type): type RoofStyle = "hip" | "gable" | "flat"
+- RoofPlan (interface): interface RoofPlan
+- RoofConfig (interface): interface RoofConfig
+- PaintTarget (type): type PaintTarget = "floor" | "wall"
+- SurfacePaintStore (interface): interface SurfacePaintStore
+- WallDrawTool (interface): interface WallDrawTool
+
+### @jgengine/core/world/water
+
+- synthesizeWaves (function): function synthesizeWaves(config: WaterSurfaceConfig = {}): GerstnerWave[]
+- waterSurface (function): function waterSurface(config: WaterSurfaceConfig = {}): WaterSurface
+- waterSurfaceFromDescriptor (function): function waterSurfaceFromDescriptor(descriptor: OceanEnvironmentDescriptor, waves?: number): WaterSurface
+- WaterNormal (type): type WaterNormal = readonly [number, number, number]
+- GerstnerWave (interface): interface GerstnerWave
+- WaterSurfaceConfig (interface): interface WaterSurfaceConfig
+- WaterSurface (interface): interface WaterSurface
+
+### @jgengine/core/world/weather
+
+- resolveWeather (function): function resolveWeather(state: WeatherState, table: WeatherModifierTable): ResolvedWeather — Resolve a weather state against a game-owned modifier table into concrete gameplay numbers. Multiplier-style effects (grip, visibility, spread) interpolate from the neutral 1 by intensity; rate-style effects (structureDamage, ignition, chill) scale linearly. Games read `grip`/`visibility` in movement and AI, `structureDamage` on a building tick, and `spread`/`ignition` feed the fire grid.
+- createFireGrid (function): function createFireGrid(config: FireGridConfig): FireGrid
+- WeatherKind (type): type WeatherKind = string
+- WeatherState (interface): interface WeatherState
+- WeatherModifier (interface): interface WeatherModifier — Per-kind gameplay effect values at full intensity. Intensity interpolates from neutral.
+- WeatherModifierTable (type): type WeatherModifierTable = Record<WeatherKind, WeatherModifier>
+- ResolvedWeather (interface): interface ResolvedWeather
+- FireCellState (type): type FireCellState = "unburnt" | "burning" | "burnt"
+- FireCell (interface): interface FireCell
+- FireGridConfig (interface): interface FireGridConfig
+- FireStepOptions (interface): interface FireStepOptions
+- FireGrid (interface): interface FireGrid
+
+### @jgengine/core/world/wind
+
+- windField (function): function windField(config: WindFieldConfig = {}): WindField
+- WindVector (type): type WindVector = readonly [number, number]
+- WindFieldConfig (interface): interface WindFieldConfig
+- WindField (interface): interface WindField
+
+## Guides
+
+# JGengine — API Reference
+
+The engine ships **verbs and primitives**; your game ships **nouns** (catalogs) and thin handlers. Read this before writing `game.config.ts` or any game content. Companion skills: **`jgengine-newgame`** (master blueprint + phased build to completion) and **`jgengine-verify`** (browserless scene gate) — read them before building. The UI quality bar lives in [`reference/ui-react.md`](reference/ui-react.md); asset sourcing lives in the **Assets** section below.
+
+The heaviest domains live in on-demand reference modules under [`reference/`](reference/) — load one only when you're building in that domain: [`reference/combat.md`](reference/combat.md) (effects, projectiles, death, feel, abilities), [`reference/world.md`](reference/world.md) (terrain, environment, physics, vehicles, spawn), [`reference/multiplayer.md`](reference/multiplayer.md) (transport, host, persistence, presence), [`reference/ui-react.md`](reference/ui-react.md) (`@jgengine/react` hooks, headless + styled UI kits, the registry install path, and the UI quality bar). Each domain's section below is a one-line pointer to its module.
+
+## Packages
+
+All published on npm, source at [github.com/Noisemaker111/jgengine](https://github.com/Noisemaker111/jgengine) (AGPL-3.0):
+
+| Package | Role | May import |
+|---------|------|------------|
+| `@jgengine/core` | Everything below: defineGame, GameContext, scene, combat, game systems, movement, input, world features, runtime/transport contracts | nothing platform-specific — no React, Convex, three.js, browser |
+| `@jgengine/react` | `GameProvider`, hooks, headless UI primitives | react + core |
+| `@jgengine/shell` | `GamePlayerShell` — R3F canvas, camera rig library (orbit, first-person, top-down/iso, RTS, over-the-shoulder, lock-on, chase, cinematic + shake channel), input tracking, HUD mounting, `GameUiPreview`, demo game; you supply a `GameRegistry` | react + three + core |
+| `@jgengine/ws` | Browser-safe `GameBackend` over a pluggable string-pipe transport (WebSocket/socket.io/WebRTC/loopback), protocol codec, HTTP reads, browser-safe authoritative host + router (`host`/`hostRouter`), and P2P (`peer`) | core |
+| `@jgengine/node` | Node process bindings over `@jgengine/ws`'s host/router: `ws`-package server, socket.io server attach, file persistence (re-exports `createGameHost`/`memoryPersistence` unchanged) | node + ws + core |
+| `@jgengine/sql` | `HostPersistence` on Postgres (structural pool, no hard `pg` dep) | core |
+| `@jgengine/convex` | The Convex **adapter** behind the `GameBackend` seam | react + convex + core |
+
+Import by deep path: `@jgengine/core/<domain>/<file>` (e.g. `@jgengine/core/runtime/gameContext`).
+
+## Hit a snag? File an issue
+
+Any hiccup with JGengine — a doc that's wrong, a missing primitive, a rough edge, or a feature/improvement idea — file it fast at [github.com/Noisemaker111/jgengine/issues](https://github.com/Noisemaker111/jgengine/issues). A 30-second issue (what you were building, the glue it forced, the API you wanted) is worth more than a silent workaround — that's the fastest way gaps and doc errors get closed. Don't reverse-engineer around a broken doc in silence; report it.
+
+## Upgrading? Read the changelog
+
+All eight packages version in lockstep. When you bump (e.g. `0.6` → `0.7`) to pick up new capabilities, read [`CHANGELOG.md`](https://github.com/Noisemaker111/jgengine/blob/main/CHANGELOG.md) — each release leads with a **Migrate** block listing the concrete steps to move a game onto the new APIs. It ships inside every package too (`node_modules/@jgengine/core/CHANGELOG.md`), and as typed values: `import { VERSION, CHANGELOG } from "@jgengine/core/meta/changelog"` to diff your installed version against the latest programmatically.
+
+## Concept → Type Reference
+
+Exact import paths and export names — **do not invent paths**; every row below resolves to a real file under `packages/core/src`. Import the deep path form `@jgengine/core/<path>`.
+
+| Concept | Import path (`@jgengine/core/…`) | Export(s) |
+|---------|----------------------------------|-----------|
+| Game boot | `game/defineGame` | `defineGame`, `GameDefinition`, `GameLoop`, `InventoryDeclaration`, `PhysicsConfig`, `GameServerConfig`, `TimeConfig` |
+| Simulation clock | `time/simClock` | `createSimClock`, `SimClock`, `TimeConfig`, `ClockSnapshot`, `CalendarTime` |
+| Runner contract | `game/playableGame` | `PlayableGame`, `GameCameraConfig`, `CameraRigKind`, `TopDownCameraConfig`, `RtsCameraConfig`, `ShoulderCameraConfig`, `LockOnCameraConfig`, `ChaseCameraConfig`, `ObserverCameraConfig`, `CameraShakeConfig`, `CinematicCameraConfig`, `CameraKeyframe`, `EntitySpriteConfig` |
+| Runtime ctx | `runtime/gameContext` | `createGameContext`, `GameContext`, `GameContextContent`, `GameContextItemEntry`, `GameContextEntityEntry`, `GameContextObjectEntry`, `CatalogEntityRole` |
+| Behaviour lifecycle | `behaviour/behaviour` | `Behaviour` (`onAwake`→`onEnable`→`onStart`→`onUpdate(dt)`→`onDisable`→`onDestroy`), `BehaviourModule`, `createBehaviourWorld`, `BehaviourWorld`, `JGEngineRegister`, `RegisterField`, `BehaviourModules` — Unity-style lifecycle over an id-keyed node tree (`setActive` cascade, lazy update dispatch); key nodes by entity instance ids. Games augment `JGEngineRegister` via `declare module "@jgengine/core/behaviour/behaviour"` for typed `world.modules`. Three.js binding: `Object3DBehaviour`, `attachObject3D`, `useBehaviourWorld` from `@jgengine/shell/behaviour` |
+| Reactive keyed store | `store/observableKeyedStore` | `createObservableKeyedStore`, `ObservableKeyedStore` — backs `ctx.game.store` |
+| Scene instance role | `scene/entityStore` | `EntityRole`, `SceneEntity`, `SpawnOptions`, `EntityPose` |
+| Object spatial queries | `scene/objectQuery` | `raycastObjects`, `raycastObjectsAll`, `ObjectRaycastInput`, `ObjectRaycastHit` — backs `ctx.scene.object.raycast`/`raycastAll` |
+| Runtime paint layer | `scene/paintLayer` | `createPaintLayer`, `PaintLayer`, `PaintStroke` — backs `ctx.scene.entity.paint` |
+| Possession | `scene/possession` | `createPossession`, `Possession`, `PossessionDeps`, `PossessionSwappedEvent` |
+| Form / shapeshift | `scene/form` | `createForms`, `Forms`, `FormDef`, `FormsDeps`, `FormChangedEvent` |
+| Multiplayer adapters | `runtime/adapter` | `offline`, `ws`, `convex`, `socketIo`, `p2p`, `lan`, `fly`, `servers`, `MultiplayerTopology`, `ServersPoolConfig` |
+| Loot | `game/lootTable` | `lootTable`, `LootTableDef`, `LootEntry`, `Drop` |
+| Dropped-item entity | `game/worldItem` | `WORLD_ITEM_ENTITY_NAME`, `WorldItemRecord`, `WorldItemSpawnInput`, `createWorldItemStore`, `resolveDeathDrops`, `scatterOffset`, `scatterPosition`, `selectNearestWorldItem`, `resolveWorldItemPresentation`, `RarityStyle`, `WorldItemPresentation`, `DEFAULT_RARITY`, `DEFAULT_PICKUP_RADIUS`, `DEFAULT_SCATTER` |
+| Loot filter | `game/lootFilter` | `lootFilter`, `evaluateLootFilter`, `LootFilterRule`, `LootFilterCondition`, `LootFilterItem`, `LootFilterOverride` |
+| Loadout | `game/loadout` | `LoadoutDef`, `LoadoutItemEntry`, `Loadouts` |
+| Cosmetic loadout | `game/cosmetics` | `createCosmetics`, `Cosmetics`, `CosmeticLoadoutDef` |
+| Quest | `game/quest` | `QuestDef`, `QuestRewards`, `QuestObjective`, `QuestJournal` |
+| World features | `world/features` | `WorldFeature`, `biomes`, `voxel`, `plots`, `tilemap`, `flat`, `environment`, `terrain`, `rain`, `snow`, `grass`, `ocean`, `building` |
+| Voxel field | `world/voxelField` | `createVoxelField`, `VoxelField`, `VoxelCell`, `VoxelHit`, `VoxelBounds`, `VoxelFieldSummary`, `VoxelFace`, `VOXEL_FACES`, `VOXEL_FACE_NORMALS` — a chunked block lattice, distinct from the `voxel()` `WorldFeature` descriptor |
+| Terrain field | `world/terrain` | `TerrainField`, `noiseField`, `resolveTerrainField`, `rollingField`, `fractalNoise`, `valueNoise`, `withNormal`, `arenaField`, `flatField`, `resolveGroundStep`, `snapToGround`, `snapEntityToGround`, `resolveTerrainPalette`, `TERRAIN_MATERIAL_PALETTES` |
+| Seeded RNG | `random/rng` | `seededRng`, `seededStreams` |
+| Name generator | `random/nameGen` | `createNameGenerator`, `pickFrom`, `fillTemplate`, `NameGenerator`, `NameGeneratorOptions`, `SyllableBank` |
+| Regions | `world/regions` | `createRegionField`, `isRegionField`, `RegionDef`, `RegionField`, `RegionSample` |
+| Wind field | `world/wind` | `windField`, `WindField`, `WindFieldConfig`, `WindVector` |
+| Water surface | `world/water` | `waterSurface`, `waterSurfaceFromDescriptor`, `synthesizeWaves`, `WaterSurface`, `GerstnerWave` |
+| Scatter | `world/scatter` | `scatter`, `scatterAabb`, `ScatterConfig`, `ScatterPoint` |
+| Content scatter | `world/scatterItems` | `scatterItems`, `pickWeighted`, `ScatterLayer`, `ScatterInstance` |
+| Building generator | `world/buildings` | `generateBuilding`, `generateBuildingDistrict`, `createBuildingGrid`, `GeneratedBuilding` |
+| Building index | `world/buildingIndex` | `buildingIndex`, `BuildingIndex`, `BuildingHit` |
+| Scene summary | `world/environmentSummary` | `summarizeEnvironment`, `resolveStructureBuildings`, `EnvironmentSummary` |
+| Map markers | `world/markers` | `createMarkerSet`, `MarkerSet`, `MapMarker`, `MarkerInput`, `MarkerKindStyle`, `DEFAULT_MARKER_KINDS`, `markerKindStyle` |
+| Fog of war | `world/fog` | `createFogField`, `FogField`, `FogConfig`, `FogBounds`, `FogCells` |
+| Minimap math | `world/minimap` | `projectToMinimap`, `clampToMinimapEdge`, `compassBearing`, `headingToBearing`, `bearingToCardinal`, `relativeBearing`, `MinimapView` |
+| Ping | `game/ping` | `createPingSystem`, `classifyPing`, `PingSystem`, `PingPayload`, `PingCategory`, `PingCategoryDef`, `DEFAULT_PING_CATEGORIES`, `PING_FEED_ACTION` |
+| Proximity prompt | `interaction/proximityPrompt` | `proximityPrompt`, `ProximityPrompt`, `ProximityPromptDisplay`, `keybind`, `gauge`, `label`, `command` |
+| Skill-check minigame | `interaction/skillCheck` | `evaluateSkillCheck`, `skillCheckMarkerPosition`, `skillCheckZoneAt`, `SkillCheckConfig`, `SkillCheckZone`, `SkillCheckResult` |
+| QTE sequencer | `interaction/qte` | `evaluateQteSequence`, `pendingQteStep`, `qteProgress`, `QteStep`, `QteInputEvent`, `QteOutcome` |
+| Item use | `item/use` | `createItemUse`, `ItemUseHandler`, `ItemUseInput`, `ItemUseResult`, `ItemUseRejection` |
+| Durability | `item/durability` | `createDurability`, `wear`, `repairQuote`, `isDisabled`, `createDurabilityTracker`, `DurabilitySpec`, `DurabilityState`, `RepairSpec`, `RepairQuote` |
+| Affix roller | `item/affix` | `createAffixRoller`, `seededRng`, `AffixRoller`, `RollerConfig`, `AffixPool`, `AffixDef`, `RarityTier`, `ItemBaseDef`, `RolledItem`, `RolledAffix` |
+| Modular item | `item/modularItem` | `createModularItem`, `install`, `computeEffectiveStats`, `missingRequiredSlots`, `ModularItemDef`, `MountSlotDef`, `PartDef`, `InstalledPart` |
+| Storage tier | `inventory/storageTier` | `partitionOnDeath`, `createDeliveryQueue`, `insureLost`, `resolveConsolation`, `tierOf`, `StorageTier`, `ContainerSnapshot`, `DeathPartition`, `DeliveryQueue`, `InsurancePolicy`, `ConsolationPolicy` |
+| Contested channel | `session/contestedChannel` | `createContestedChannel`, `ContestedChannel`, `ContestedChannelConfig`, `ContestedEvent`, `ContestedPhase`, `ContestedSnapshot` |
+| Round state | `session/roundState` | `createRoundState`, `lossBonusFor`, `RoundState`, `RoundConfig`, `RoundPhase`, `RoundTeam`, `RoundEvent`, `RoundEconomy`, `RoundSnapshot`, `LossBonusRule` |
+| Shrinking ring | `session/ring` | `createRing`, `ringSampleAt`, `Ring`, `RingConfig`, `RingPhase`, `RingSample`, `RingHit`, `RingPoint` |
+| Extraction session | `session/extraction` | `createRaidSession`, `RaidSession`, `RaidSessionConfig`, `ExtractPoint`, `ExtractionResult`, `DeathResult`, `RaidStatus` |
+| Role assignment | `session/roles` | `assignRoles`, `RoleSpec` |
+| Downed / revive | `combat/downed` | `createDownedState`, `DownedState`, `DownedConfig`, `DownedPhase`, `DownedEntry`, `DownedEvent` |
+| Persistence scopes | `runtime/persistenceScope` | `partitionScopes`, `resetRun`, `mergeScopes`, `clearRunFields`, `applyRunReset`, `planScenarioReset`, `ScopeSchema`, `ScenarioReset`, `PersistenceScope` |
+| Inventory | `inventory/inventoryModel` | `InventoryLayout`, `InventorySet`, `ItemTraits` |
+| Progression | `game/progression` | `curve`, `evalCurve`, `leveling`, `Curve`, `LevelingTrack`, `LevelProgress` |
+| Inventory slots | `inventory/slotModel` | `createSlots`, `placeAt`, `removeAt`, `moveSlot`, `firstEmpty`, `compactSlots`, `Slot`, `SlotGrid` |
+| Shaped inventory | `inventory/shapedGrid` | `createShapedGrid`, `placeShaped`, `moveShaped`, `removeShaped`, `canPlace`, `rotateFootprint`, `occupiedCells`, `gridAdjacencyQuery`, `cellFromPoint`, `ShapedGrid`, `Footprint`, `Placement`, `Rotation` |
+| Card piles | `cards/cardPile` | `createCardPile`, `createCardPileState`, `draw`, `moveCards`, `shuffleZone`, `pileRng`, `CardPile`, `CardPileState`, `CardPileConfig` |
+| Modifier pipeline | `cards/modifierPipeline` | `createModifierPipeline`, `runPipeline`, `Modifier`, `TraceStep`, `PipelineResult` |
+| Lane board | `board/laneBoard` | `createLaneBoard`, `laneAggregate`, `laneOutcome`, `boardTotals`, `lanesWon`, `LaneBoard`, `LaneRule`, `LaneBoardConfig` |
+| Timeline board | `board/timelineBoard` | `createTimelineBoard`, `tickTimeline`, `TimelineBoard`, `TimelineSlot`, `TimelineFire` |
+| World geometry | `world/geometry` | `footprintAabb`, `aabbOverlap`, `snapToGrid`, `resolveMove`, `Aabb`, `Footprint` |
+| Placement | `world/placement` | `validatePlacement`, `footprintObstacle`, `PlacementRules`, `PlacementResult` |
+| Placement ghost | `world/placementController` | `createPlacementController`, `PlacementController`, `PlacementPreview`, `PlacementCommit`, `SnapMode`, `quarterTurnsToRotationY` |
+| Connector sockets | `world/connectors` | `snapToNearest`, `socketsCompatible`, `worldSockets`, `socketWorldPosition`, `ConnectorSocket`, `ConnectorPieceDef`, `PlacedPiece`, `SnapResult` |
+| Structural support | `world/support` | `solveSupport`, `toDebrisBodies`, `SupportPiece`, `SupportLink`, `SupportResult` |
+| Wall/roof authoring | `world/walls` | `createWallDrawTool`, `footprintFromWalls`, `autoRoof`, `wallSegments`, `createSurfacePaint`, `WallDrawTool`, `RoofPlan`, `EnclosedFootprint` |
+| Placed structures | `world/placedStructureStore` | `createPlacedStructureStore`, `PlacedStructure`, `PlacedStructureStore`, `PlacedStructureSnapshot` |
+| Terraform | `world/terraform` | `createEditableTerrain`, `createTerraformBrush`, `brushWeight`, `EditableTerrain`, `TerraformBrush`, `TerraformEdit`, `TerraformMode` |
+| Build permissions | `world/buildPermissions` | `createPlotPermissions`, `createContributionPool`, `PlotPermissions`, `ContributionPool`, `BuildRole`, `ContributionGoal` |
+| Interiors | `world/interiors` | `createInteriors`, `Interior`, `Exterior`, `SpaceRef` |
+| Game clock | `time/gameClock` | `getScaledElapsedMs`, `computeGameDay`, `SECONDS_PER_GAME_DAY` |
+| Scene behaviors | `scene/behaviors` | `wander`, `patrol`, `promptable`, `talkable`, `player` |
+| Capture check | `scene/captureCheck` | `captureChance`, `rollCapture`, `CaptureCheckInput` |
+| Owned roster | `scene/roster` | `createRoster`, `Roster`, `RosterEntry`, `RosterCaptureOptions` |
+| Economy wallet | `economy/wallet` | `createEmptyWallet`, `balance`, `grant`, `charge`, `canAfford`, `chargeAll` |
+| Tech tree | `economy/techTree` | `createTechTree`, `TechTree`, `TechNodeDef`, `canUnlockTech`, `availableTech`, `unlockedRecipes`, `grantTech`, `techPrerequisitesMet` |
+| Recipe graph | `crafting/recipe` | `createRecipeGraph`, `RecipeGraph`, `RecipeDef`, `RecipeItem`, `canCraft`, `craft`, `missingInputs`, `stationSatisfied`, `craftSeconds` |
+| Production building | `crafting/production` | `productionBuilding`, `ProductionBuildingDef`, `createProductionState`, `tickProduction`, `feedProduction`, `drainOutput`, `advanceTransport`, `resolvePowerGrid` |
+| Crop tile / farming | `crafting/crop` | `createCropField`, `CropField`, `CropDef`, `CropTileState`, `tillTile`, `plantCrop`, `waterTile`, `advanceCropDay`, `harvestCrop`, `applyToolToTiles`, `squarePattern`, `diamondPattern`, `createDayTicker` |
+| Skill-check roll | `stats/rollCheck` | `rollCheck`, `CheckInput`, `CheckResult`, `CheckAdvantage` |
+| Input bindings (full) | `input/actionBindings` | `hotbarSlotBindings`, `actionLabel`, `bindingLabel`, `resolveActionCommand`, `bindingMatches`, `createActionStateTracker` |
+| Touch controls | `input/touchScheme` | `deriveTouchScheme`, `touchCode`, `touchActionLabel`, `withTouchCodes`, `TouchControlsConfig`, `TouchGestureBindings`, `TouchDragBinding`, `TouchButtonSpec`, `TouchScheme`, `TouchJoystick`, `TouchButton` |
+| Pointer hit | `input/pointer` | `PointerHit`, `PointerButton`, `aimToPoint`, `moveTargetFromHit`, `groundOf`, `PointerVec3` |
+| Navmesh + A* | `nav/navGrid` | `createNavGrid`, `findPath`, `smoothPath`, `NavGrid`, `NavGridConfig`, `NavPoint`, `FindPathOptions` |
+| Path follow | `nav/pathFollow` | `createPathFollow`, `advancePathFollow`, `pathFromNav`, `PathFollowConfig`, `PathFollowState`, `Waypoint` |
+| Nav-grid movement constraint | `nav/navConstrain` | `constrainToNavGrid`, `NavConstrainProposed`, `NavConstrainEntity`, `NavConstrainOptions` — a standalone walkable-pass-through + wall-slide helper; adapt its `(proposed, entity)` shape to `PlayerMovementConfig.beforeCommit`'s `(frame) => [x,y,z]` with a small closure |
+| Selection set | `scene/selection` | `createSelectionSet`, `SelectionSet`, `screenRect`, `selectWithinRect`, `rectContainsPoint`, `isMarquee`, `ScreenRect` |
+| Context menu | `interaction/contextMenu` | `contextVerb`, `buildContextMenu`, `contextVerbInput`, `ContextVerb`, `ContextMenu` |
+| Shared / group wallet | `economy/sharedWallet` | `createWalletBook`, `WalletBook`, `WalletScope`, `userScope`, `groupScope`, `balanceIn`, `grantTo`, `chargeFrom`, `contributionOf`, `contributorsOf` |
+| Analog axis input | `input/axisInput` | `AxisInput`, `AxisChannel`, `AxisBindingMap`, `DRIVE_AXIS_BINDINGS`, `clampAxis`, `rampToward`, `NEUTRAL_AXIS` |
+| Raw control polling | `runtime/inputSnapshot` | `createInputSnapshot`, `InputSnapshot` — backs `ctx.input` |
+| Physics world | `physics/physicsWorld` | `PhysicsWorld`, `PhysicsWorldConfig`, `PhysicsBounds`, `PhysicsStats`, `AddBodyOptions` (`{ shape: "box", halfExtents }` \| `{ shape: "sphere", radius }`), `JointOptions`, `JointKind`, `CollisionEvent` |
+| Ballistic collision sweep | `physics/ballisticSweep` | `createBallisticSweep`, `BallisticSweep`, `BallisticSweepHit`, `BallisticSweepOptions` |
+| Tweening / easing | `anim/easing` | `Easing`, `lerp`, `clamp01`, `smoothstep`, `easeInQuad`, `easeOutQuad`, `easeInOutQuad`, `easeInCubic`, `easeOutCubic`, `easeInOutCubic`, `easeOutBack`, `easeOutElastic`, `tween`, `timedProgress` |
+| Async data source | `data/dataSource` | `createDataSource`, `DataSource`, `DataSourceState`, `DataSourceStatus`, `DataSourceOptions`, `DataSourceClock`, `RefreshOptions` |
+| JSON fetch | `data/fetchJson` | `fetchJson`, `FetchJsonOptions`, `FetchImpl`, `HttpStatusError`, `JsonParseError` |
+| JSON data source | `data/jsonDataSource` | `createJsonDataSource`, `JsonDataSourceOptions` |
+| Dev proxy routing | `data/devProxy` | `proxiedUrl`, `parseDevProxyTable`, `DevProxyTable`, `ProxiedUrlOptions`, `DEFAULT_DEV_PROXY_PREFIX` |
+| Grid-cell world rendering | `world/gridInstances` | `resolveGridInstances`, `GridInstanceTransform` |
+| Turn loop | `turn/turnLoop` | `createTurnLoop`, `TurnLoop`, `TurnLoopConfig`, `TurnState`, `PoolConfig`, `PoolState`, `TurnLoopSnapshot` |
+| Declared-action intent board | `turn/intent` | `createIntentBoard`, `IntentBoard`, `DeclaredIntent` — `declare(participantId, intent)`, `peek`, `all`, `consume`, `clear` |
+| Commit modes | `turn/commit` | `createCommitController`, `CommitController`, `CommitMode`, `CommitOutcome`, `SubmittedAction` |
+| Intent board | `turn/intent` | `createIntentBoard`, `IntentBoard`, `DeclaredIntent` |
+| Tactical grid | `tactics/tacticalGrid` | `createTacticalGrid`, `TacticalGrid`, `TacticalGridConfig`, `Tile`, `ReachableTile`, `PushResult`, `PushCollision` |
+| Predictive query | `tactics/predictiveQuery` | `predictAreaEffect`, `predictArcEffect`, `predictTiles`, `PredictiveDeps`, `PredictedTarget` |
+| Sim snapshot | `tactics/snapshot` | `createSnapshotStore`, `SnapshotStore`, `SnapshotSlice`, `Snapshot`, `deepClone` |
+| Surfaces | `tactics/surface` | `createSurfaceLayer`, `SurfaceLayer`, `SurfaceLayerConfig`, `SurfaceKindDef`, `SurfaceReaction`, `SurfaceEvent` |
+| Area targeting | `combat/effects` | `resolveAreaTargets`, `AreaTarget`, `AreaTargetInput` (shared AoE targeting behind `effect` + the predictive query) |
+| Environment field | `world/envField` | `createEnvironmentField`, `EnvironmentField`, `EnvironmentSample`, `EnvironmentFieldConfig`, `OccluderRect`, `HeatSource` |
+| Weather + fire | `world/weather` | `resolveWeather`, `WeatherState`, `WeatherModifier`, `WeatherModifierTable`, `ResolvedWeather`, `createFireGrid`, `FireGrid`, `FireCell`, `FireGridConfig` |
+| Realm composition | `world/realm` | `composeRealm`, `RealmCard`, `RealmBase`, `ComposedRealm`, `RealmEnvironmentParams`, `SpawnTableOverride` |
+| Decay meters | `survival/decayMeter` | `createDecayMeterSet`, `DecayMeterSet`, `DecayMeterConfig`, `MeterThreshold`, `DecayMeterState` |
+| Status moodles | `survival/moodle` | `createMoodleStack`, `stackMoodles`, `MoodleStack`, `Moodle`, `MoodleSeverity`, `TimedMoodleInput` |
+| Multi-region health | `survival/regionHealth` | `createMultiRegionHealth`, `MultiRegionHealth`, `HealthRegionConfig`, `AilmentConfig`, `RegionHealthState`, `AilmentInstance` |
+| Audio contract | `audio/audioFalloff` | `computeFalloffGain`, `resolveEmitterGain`, `distance3`, `AudioFalloffConfig`, `FalloffCurve`, `SoundDef`, `AudioBusDef`, `AudioBusId` |
+| Beat clock | `time/beatClock` | `createBeatClock`, `createBeatInputBuffer`, `nextBeatTime`, `BeatClock`, `BeatClockConfig`, `BeatSnapshot`, `BeatInputBuffer`, `BufferedAction` |
+| Spawn director | `ai/spawnDirector` | `createSpawnDirectorState`, `advanceSpawnDirector`, `advanceWave`, `raiseAlert`, `pickSpawnPoint`, `SpawnDirectorConfig`, `WaveManifest`, `SpawnEntry`, `SpawnRequest`, `DirectorContext` |
+| Threat table | `ai/threat` | `createThreatTable`, `ThreatTable`, `ThreatTableConfig`, `ThreatEntry`, `HighestThreatOptions` |
+| Job board | `ai/jobBoard` | `createJobBoard`, `JobBoard`, `JobDef`, `Job`, `JobPhase`, `WorkerState`, `JobReport`, `JobTickContext` |
+| Crowd flow | `ai/crowd` | `computeFlowField`, `createCrowdField`, `selectPoi`, `FlowField`, `FlowFieldOptions`, `CrowdField`, `Poi`, `SelectPoiOptions` |
+| Physics actors | `physics/ragdoll`, `physics/carryable`, `physics/forceVolume`, `physics/spatialGrid` | `createRagdoll`, `Ragdoll`, `Carryable`, `carrySpeedMultiplier`, `ForceVolume`, `PlatformCarry`, `SpatialGrid` |
+| Traversal (grapple/glide) | `physics/traversal` | `Grapple`, `GrappleConfig`, `Glide`, `GlideConfig` |
+| Structural destruction | `physics/structure` | `StructureGraph`, `StructureNodeSpec`, `StructureEdgeSpec`, `StructureMaterial`, `StructureMaterialTable`, `CollapseEvent`, `DebrisConfig` |
+| Destructible terrain | `world/carve` | `VoxelVolume`, `VoxelMaterial`, `VoxelMaterialTable`, `CarvableField`, `carvableTerrain`, `CarveOp`, `DepositOp`, `CraterOp`, `MoundOp`, `EMPTY_VOXEL` |
+| Vehicle body | `physics/vehicleBody` | `createVehicleBody`, `VehicleBody`, `VehicleBodyConfig`, `WheelSpec`, `GripCurve`, `sampleGripCurve`, `DEFAULT_GRIP_CURVE` |
+| Buoyant boat | `physics/buoyancy` | `createBuoyantBody`, `BuoyantBody`, `BuoyantBodyConfig` |
+| Crash damage | `physics/damageZones` | `createDamageModel`, `DamageModel`, `DamageZoneDef`, `DamageTransition` |
+| Mounts / rideables | `scene/mount` | `createMountController`, `MountController`, `MountKit`, `MountSeat`, `RideableConfig` |
+| Shared-vehicle stations | `scene/stationClaim` | `createStationClaim`, `StationClaim`, `Station`, `SharedVehicleConfig`, `ClaimResult` |
+| Lag compensation | `multiplayer/lagCompensation` | `createPositionHistory`, `PositionHistory`, `rewindTimestamp`, `resolveHitscan`, `raySphereDistance`, `HitscanRay`, `HitscanTarget` |
+| Simultaneous commit | `multiplayer/simultaneousCommit` | `createCommitRound`, `CommitRound`, `SealedCommit`, `resolveCommits` |
+| Combat-snapshot replay | `multiplayer/combatSnapshot` | `serializeBoard`, `cloneSnapshot`, `replayCombat`, `BoardSnapshot`, `SnapshotUnit`, `CombatRules`, `ReplayResult` |
+| Session matchmaking | `multiplayer/matchmaking` | `browseSessions`, `findByJoinCode`, `quickMatch`, `matchesFilter`, `normalizeJoinCode`, `generateJoinCode`, `SessionListing`, `MatchFilter` |
+| Auth identity | `multiplayer/identity` | `AuthSession`, `PlayerIdentity`, `sessionPlayer`, `resolveGuestSession` |
+| Text chat | `game/chat`, `multiplayer/chatContract` | `createChat`, `Chat`, `ChatMessage`, `ChatChannelDef`, `whisperChannelId`, `createChatRateLimiter`, `ChatTransport`, `ChatSync`, `createLocalChatTransport` |
+| Voice seam | `multiplayer/voiceContract` | `VoiceTransport`, `VoiceParticipant`, `VoiceRoute`, `createLocalVoiceTransport`, `createPushToTalk`, `PushToTalkMode` |
+| Race state | `game/race` | `raceTrack`, `RaceTrack`, `createRaceState`, `RaceState`, `RaceEvent`, `RaceWinCondition`, `firstPastPost`, `topK`, `lastStanding`, `everyoneFinishes` |
+| Reveal query | `sensor/revealQuery` | `createRevealQuery`, `RevealQuery`, `RevealQueryOptions`, `RevealHit` |
+| Hidden-state probe | `sensor/hiddenStateProbe` | `probeHiddenState`, `probeHiddenStateAll`, `HiddenStateSource`, `HiddenStateValue`, `SensorProbeOptions`, `SensorReading` |
+| View-frustum sensor | `sensor/frustumSensor` | `createFrustumSensor`, `projectToView`, `framingScore`, `FrustumCamera`, `FrustumTarget`, `FrustumProjection`, `FrustumSample`, `FrustumSensor`, `FramingConfig` |
+| Recording buffer | `sensor/recordingBuffer` | `createRecordingBuffer`, `RecordingBuffer`, `RecordingFrame`, `RecordingBufferOptions` |
+| Concealment scoring | `sensor/concealment` | `colorDistance`, `concealmentScore`, `createConcealmentSensor`, `ColorHex`, `ConcealmentTarget`, `ConcealmentSample`, `ConcealmentSensor` |
+| Freeze violation monitor | `sensor/freezeMonitor` | `createFreezeMonitor`, `FreezeMonitor`, `FreezeSubject`, `FreezeViolation` |
+| Animation SM | `combat/animationState` | `createAnimationState`, `AnimationState`, `AnimationClip`, `FramePhase`, `FrameRange`, `phasesAtFrame`, `activeRangeAtFrame`, `frameAtMs` |
+| Accumulator meter | `stats/accumulatorMeter` | `createAccumulatorMeter`, `AccumulatorMeter`, `AccumulatorMeterConfig`, `MeterTier`, `MeterAddResult`, `tierAt` |
+| Stagger / buildup | `combat/breakMeters` | `createStaggerMeter`, `createBuildupMeter`, `StaggerMeter`, `BuildupMeter`, `BuildupProc` |
+| Attack tags | `combat/attackTags` | `attackMeta`, `AttackTag`, `AttackMeta`, `hasTag`, `isBlockable`, `isParryable`, `isDodgeable`, `counters` |
+| Defensive window | `combat/defensiveWindow` | `createDefensiveWindow`, `resolveDefense`, `DefensiveWindowConfig`, `DefenseKind`, `DefenseOutcome`, `windowActiveAt`, `iframeActiveAt` |
+| Combo string | `combat/comboString` | `createComboRunner`, `advanceCombo`, `ComboString`, `ComboStep`, `AdvanceComboResult` |
+| Hit reaction | `combat/hitReaction` | `resolveHitReaction`, `HitReaction`, `HitReactionConfig`, `CameraShake`, `applyImpulse` |
+| Telegraph | `combat/telegraph` | `pointInTelegraph`, `telegraphProgress`, `telegraphFired`, `telegraphTurnProgress`, `telegraphFiredAtTurn`, `telegraphTurnsRemaining`, `TelegraphShape`, `TelegraphConfig` |
+| Dash / dodge | `movement/dash` | `createDashState`, `DashState`, `DashConfig`, `DashBurst`, `iframeActive`, `dashOffset` |
+| Ability kit | `combat/abilityKit` | `createAbilityKit`, `AbilityKit`, `AbilitySlotConfig`, `AbilitySlotSnapshot`, `AbilitySlotState`, `AbilityCastType`, `AbilityCastResult`, `AbilitySlotRetune` |
+| Event meter | `stats/eventMeter` | `createEventMeter`, `EventMeter`, `EventMeterConfig`, `EventMeterFeedResult` |
+| Auto-target policy | `scene/autoTarget` | `selectAutoTarget`, `createAutoTargeter`, `AutoTargetPolicy`, `AutoTargeter`, `AutoTargetDeps` |
+| Resistance matrix | `combat/resistance` | `resolveResistance`, `resistanceScale`, `ResistanceMatrix`, `ResistVerdict`, `ResistanceResult` |
+| Run draft | `game/runDraft` | `createRunDraft`, `createRunModifierStack`, `RunDraft`, `RunModifierStack`, `RunModifierOffer` |
+| Uniform-cell grid | `puzzle/cellGrid` | `CellGrid`, `CellRun`, `createCellGrid`, `cellAt`, `inGridBounds`, `withCell`, `withCells`, `fullRows`, `clearRows`, `collapseColumns`, `findRuns` |
+| Falling piece | `puzzle/fallingPiece` | `FallingPiece`, `ShapeTable`, `LockDelayState`, `pieceCells`, `pieceCollides`, `mergePiece`, `dropDistance`, `gravityInterval`, `levelForLines`, `lineScore`, `createLockDelay`, `stepLockDelay` |
+| Falling tile grid | `tactics/fallingGrid` | `createFallingGrid`, `FallingGrid`, `FallingGridConfig`, `FallingGridCell`, `FallingGridSnapshot`, `LockState`, `gravityIntervalMs`, `GravityIntervalConfig` — a generic tile-drop grid (any `TCell` payload), distinct from `puzzle/cellGrid`+`puzzle/fallingPiece`'s row-clear/shape-table pair |
+| Spawn/respawn points | `game/spawnPoints` | `createSpawnPoints`, `SpawnPoints`, `SpawnPointPose`, `RespawnTarget` |
+| Level sequence | `game/levelSequence` | `createLevelSequence`, `LevelSequence`, `LevelSequenceConfig`, `LevelDescriptor`, `CurrentLevel`, `LevelSequenceStatus`, `LevelSequenceProgress` |
+| Devtools overlay + tunables | `devtools/devtools` | `devtools`, `createDevtools`, `tunable`, `snapshotDevtools`, `instrumentLatency`, `Tunable`, `TunableOptions`, `TunableAccessor`, `DevtoolsControl`, `DiscoveredEntry`, `DevtoolsOverrides`, `DevtoolsSnapshot` |
+| Tunable auto-discovery | `devtools/transformTunables` | `transformTunableExports`, `tunableModuleTable`, `tunableDiscoveryPlugin`, `TunableTransformResult` |
+
+## Getting started (new project)
+
+```sh
+bun add @jgengine/core @jgengine/react @jgengine/shell react react-dom three three-stdlib @react-three/fiber @react-three/drei
+bun add -d @tailwindcss/vite tailwindcss   # HUD styling (Vite + Tailwind v4)
+```
+
+A single game's standalone entry mounts `GameHost` (`@jgengine/shell/GameHost`) over the `game` your `game.config.ts` exports. The full standalone harness is four small files plus a script — this is exactly the shape every `Games/*` game ships, so `bun dev` plays it on its own with no host app:
+
+```html
+<!-- index.html -->
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>My Game</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>
+```
+
+```ts
+// vite.config.ts — monorepo-aware: the alias branch only fires when this folder
+// sits inside the engine repo checkout; copied anywhere else, @jgengine/* resolves
+// from npm dist and the alias list is empty
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import tailwindcss from "@tailwindcss/vite";
+import react from "@vitejs/plugin-react";
+import { defineConfig } from "vite";
+
+const engineSrc = (pkg: string) => fileURLToPath(new URL(`../../packages/${pkg}/src`, import.meta.url));
+
+export default defineConfig({
+  plugins: [react(), tailwindcss()],
+  resolve: {
+    alias: existsSync(engineSrc("core"))
+      ? [
+          { find: /^@jgengine\/core\/(.*)$/, replacement: `${engineSrc("core")}/$1` },
+          { find: /^@jgengine\/react\/(.*)$/, replacement: `${engineSrc("react")}/$1` },
+          { find: /^@jgengine\/ws\/(.*)$/, replacement: `${engineSrc("ws")}/$1` },
+          { find: /^@jgengine\/shell\/(.*)$/, replacement: `${engineSrc("shell")}/$1` },
+          { find: /^@jgengine\/assets$/, replacement: `${engineSrc("assets")}/index.ts` },
+          { find: /^@jgengine\/assets\/(.*)$/, replacement: `${engineSrc("assets")}/$1` },
+        ]
+      : [],
+  },
+});
+```
+
+```css
+/* src/index.css */
+@import "tailwindcss";
+@source "../node_modules/@jgengine/react/dist";
+@source "../node_modules/@jgengine/shell/dist";
+```
+
+Inside the engine repo the two `@source` lines point at `../../../packages/react/src` and `../../../packages/shell/src` instead (see any `Games/*/src/index.css`) — same file, different `@source` targets depending on where dist lives.
+
+```tsx
+// main.tsx
+import "./index.css";
+
+import { createRoot } from "react-dom/client";
+import { GameHost } from "@jgengine/shell/GameHost";
+import { game } from "./game.config";
+
+const root = document.getElementById("root");
+if (root === null) throw new Error("main: missing #root mount element");
+createRoot(root).render(<GameHost playable={game} />);
+```
+
+Add `"dev": "vite"` to `package.json`'s `scripts` — `bun dev` then launches the game standalone.
+
+`GameHost` resolves multiplayer itself from `game.multiplayer` (falling back to offline when the adapter can't resolve, with a console warning) — pass `multiplayer` (a prebuilt `ShellMultiplayer | null`, used as-is with no resolution attempted) or `resolveMultiplayer` (`(args) => ShellMultiplayer | null`, tried before the built-in resolver, falling back to it on `null`) only when the host app needs to supply its own session, e.g. trying several transports in sequence.
+
+A multi-game host (a launcher, a dev registry) wires `GamePlayer` over a `GameRegistry`:
+
+```tsx
+import { GamePlayer } from "@jgengine/shell/GamePlayer";
+import type { GameRegistry } from "@jgengine/shell/registry";
+
+const games: GameRegistry = {
+  "my-game": () => import("./my-game").then((m) => m.game),
+};
+
+function App() {
+  return <GamePlayer gameId="my-game" registry={games} loading={<p>Loading…</p>} />;
+}
+```
+
+`GamePlayer({ gameId, registry, fallbackGameId?, loading?, multiplayer? })` (`@jgengine/shell/GamePlayer`) is `GamePlayerShell` plus the lazy-load glue: it looks up `gameId` in `registry`, awaits the loader, renders `loading` (default `null`) until it resolves, then mounts `GamePlayerShell playable={...} multiplayer={...}`; switching `gameId` re-triggers the load, and an in-flight load is discarded if the id changes again first. `resolveGameLoader(registry, gameId, fallbackGameId?)` (`@jgengine/shell/registry`) is the underlying lookup — `registry[gameId] ?? registry[fallbackGameId]` — for hosts that want the fallback behavior without the component.
+
+HUD styling is Tailwind v4 via the `index.css` above — without its `@source` lines the HUD renders unstyled. Then build the game itself under `src/` per the layout below — `src/game.config.ts` is the single entry, defined with `defineGame` from `@jgengine/shell/defineGame`.
+
+## Scope
+
+This file documents engine primitives and conventions only — never game domain. Example ids (`iron_block`, `mob_grunt`, `shop_town`) are placeholders, not content to copy.
+
+| Engine owns | Your game owns |
+|-------------|----------------|
+| Weighted loot RNG, trade validation, loadout application, quest journal state, social graph, stat clamp math, effect absorption, projectile geometry, death resolution, event bus, feeds, leaderboards, input capture, pose hitboxes | Catalog entries and ids, effect id names, XP curves, shop/item/quest/loadout definitions, use-handlers, AI logic, UI content |
+
+**Rules:**
+
+1. **Catalog-first** — shape and behavior of every id lives in game-owned catalog files. Runtime calls pass ids, positions, instance keys.
+2. **Three buckets** — inventory items, scene objects, scene entities. Never merge them.
+3. **Dumb place/spawn** — no behaviors on `place()`/`spawn()`; the catalog owns them.
+4. **Commands for verbs** — input maps to actions, actions to commands/handlers; no raw keys in game logic.
+5. **Primitives over glue** — a loop several games need (loot roll, shop buy, kit seeding) belongs in the engine, not copy-pasted per game.
+6. **No speculative config** — `defineGame` fields exist only with a live engine consumer.
+7. **This file stays domain-free.**
+
+## The three buckets
+
+| Bucket | What | API |
+|--------|------|-----|
+| **Inventory** | Stackable ids in containers | `ctx.player.inventory.put / take / move / has / count` |
+| **Scene object** | Static world content | `ctx.scene.object.place / remove / move / rotate / list` |
+| **Scene entity** | Movers driven per tick | `ctx.scene.entity.spawn / despawn / setPose / effect / …` |
+
+A voxel block is an object. A rack is an object with a slot inventory. A GPU is an inventory item inside it. A player, mob, or car is an entity. A dropped-item lying on the ground is also an entity — `ctx.scene.worldItem` (position + item ref + rarity, spawned under `game/worldItem`'s `WORLD_ITEM_ENTITY_NAME`) — never a fourth bucket and never merged into inventory or object.
+
+## Game repo layout
+
+Every game is one shape, enforced by `check-game-shape` (part of `check-types`): the top of `src/` holds only the skeleton, and every game-specific module, UI component, and test lives under `src/game/`. Dense files — one `catalog.ts` per domain, never one file per entry.
+
+```
+src/
+  game.config.ts       single entry — export const game = defineGame({...}) from "@jgengine/shell/defineGame"
+  index.tsx            barrel — export { game } from "./game.config" (+ any UI-preview scenario re-export)
+  main.tsx             standalone host — mounts <GameHost playable={game}/> from "@jgengine/shell/GameHost"
+  loop.ts              onInit, onNewPlayer, onTick
+  world.ts             WorldFeature + PhysicsConfig (only for games that have one)
+  game/
+    keybinds.ts          ActionCodesMap — named actions + hotbarSlotBindings(n)
+    inventories.ts       inventory declarations
+    assets.ts             Render catalog
+    content.ts             itemById / entityById lookups over all catalogs
+    loadouts.ts             Loadout ids → items/economy/unlocks per inventory
+    world/                zones.ts, setup.ts (place/spawn from onInit)
+    items/                <domain>/catalog.ts + use-handlers.ts
+    objects/              catalog.ts (+ loot tables beside their domain)
+    entities/             players/ enemies/ npcs/ — catalog.ts per role (never actors/)
+    quests/catalog.ts     when using game.quest
+    progression/          curves.ts — game-owned XP curve numbers fed to game/progression
+    ui/GameUI.tsx         ALL layout/positioning
+    ui/components/        content-only pieces GameUI places
+```
+
+## `defineGame` — the single authoring entry
+
+`@jgengine/shell/defineGame` is the game-authoring entry: one call in `game.config.ts` takes both engine fields (`name`, `assets`, `world`, `physics`, `inventories`, `input`, `server`, `save`, `time`, `feed`, `multiplayer`) and presentation fields (`content`, `loop`, `GameUI`, `camera`, `environment`, `WorldOverlay`, `renderEntity`, `renderObject`, `entitySprites`, `entityModels`, `objectModels`, `hotbarSelection`, `prompts`, `pointer`, `touch`, `worldHealthBars`, `audio`, `entitySounds`, `objectSounds`, `worldItem`, `shadows`, `collision`, `movement`, `devtools`) and returns a ready `PlayableGame` — no separate object to assemble. It is a thin wrapper over the core `defineGame` primitive (below) plus the `PlayableGame` runner assembly; see `packages/shell/src/defineGame.tsx` for the exact accepted fields. Never game tuning (walk speeds, damage, prompts — those live in catalogs).
+
+**Smart defaults** — omit any of these and the call still resolves: `multiplayer` → `offline()`; `assets` → an empty asset catalog; `loop` hooks (`onInit`/`onNewPlayer`/`onTick`) → no-ops; `content` → `{}`; `GameUI` → an empty component; `camera` → third-person orbit; `feed` → 20-entry ring buffers per action; a `world` of kind `environment()` auto-renders as the backdrop with no `environment` component supplied — a non-`environment()` world (`flat()`, `voxel()`, …) still needs the game to hand it one.
+
+```ts
+// game.config.ts — imports only, nothing inline
+import { defineGame } from "@jgengine/shell/defineGame";
+import { assets } from "./game/assets";
+import { content } from "./game/content";
+import { GameUI } from "./game/ui/GameUI";
+import { inventories } from "./game/inventories";
+import { keybinds } from "./game/keybinds";
+import { loop } from "./loop";
+import { physics, world } from "./world";
+
+export const game = defineGame({
+  name: "My Game",
+  assets,
+  world,
+  physics,
+  inventories,
+  input: keybinds,
+  server: "persistent",            // or { mode: "ffa", scoreLimit: 30 } — rules live in game code
+  save: { auto: "5m", scope: "player+chunks" },   // or "none"
+  multiplayer: offline(),          // or ws({ topology, url? }) / fly({ app }) / convex({ topology }) / socketIo({ topology, url? }) / p2p({ room? }) / lan({ port?, path? }) / servers({ …, adapter }) — defaults to offline()
+  content,
+  loop,                            // Partial<GameLoop<GameContext>> — missing hooks default to no-ops
+  GameUI,
+  camera: { perspective: "third" },  // optional — this is the default
+});
+```
+
+```ts
+// game/keybinds.ts — named actions + generated hotbar slots; one key, one action
+import { hotbarSlotBindings, type ActionCodesMap } from "@jgengine/core/input/actionBindings";
+
+export const keybinds: ActionCodesMap = {
+  moveForward: ["KeyW"], moveBack: ["KeyS"], moveLeft: ["KeyA"], moveRight: ["KeyD"],
+  jump: ["Space"], sprint: ["ShiftLeft"],
+  interact: ["KeyE"],
+  crouch: { hold: ["KeyC"], toggle: ["KeyZ"] },
+  aim: { hold: ["mouse2"], toggle: ["KeyV"] },
+  tabTarget: ["Tab"], clearTarget: ["Escape"],
+  ...hotbarSlotBindings(9),        // hotbarSlot1..9 → Digit1..9 (a 10th slot gets Digit0)
+};
+```
+
+```ts
+// game/inventories.ts
+import type { InventoryDeclaration } from "@jgengine/core/game/defineGame";
+export const inventories: Record<string, InventoryDeclaration> = {
+  hotbar: { slots: 9, hud: "hotbar" },
+  backpack: { slots: 28, traits: itemTraits },
+  equipment: { slots: 4, accepts: ["weapon", "armor"], applyModifiers: true },
+};
+
+// world.ts — top of src/, not under game/
+import type { PhysicsConfig } from "@jgengine/core/game/defineGame";
+import { biomes, type WorldFeature } from "@jgengine/core/world/features";
+export const world: WorldFeature = biomes({ map: "world/biomes", zones: "world/zones" });
+export const physics: PhysicsConfig = { gravity: -32 };
+```
+
+- `PhysicsConfig.gravity`/`jumpVelocity` tune the shell's built-in walk controller's fall/jump feel (defaults ~`-24`/`7.1`) — the only two levers on gravity and jump height; everything else about movement (speed, poses) stays catalog `movement` fields.
+- Input bindings are string arrays (hold semantics) or `{ hold, toggle, repeatMs? }` for the same verb. `repeatMs` turns a held action into an auto-repeat fire (build-mode place-on-drag, rapid-fire without a separate `wasPressed`/interval combo in game code) — the shell refires the command every `repeatMs` while the binding stays down, on top of its normal press-edge fire.
+- **Keybind → command convention.** The shell fires a command for any bound action that isn't reserved: pressing an action runs a command of the **same name** if one is defined, else a `ui.<action>` fallback (so `openBackpack` → `ui.openBackpack`). Just declare the binding and a matching command — no per-game `keydown` listener. Reserved actions the shell consumes natively and never routes to a command: `moveForward/moveBack/moveLeft/moveRight`, `turnLeft/turnRight`, `sprint`, `jump`, `tabTarget`, `clearTarget`, `useAbility`, `interact`, and any `hotbarSlotN`/`slotN`. `tabTarget`/`clearTarget` run `target.cycle`/`target.clear` (native `cycleTarget`/`setTarget` fallback).
+- **`interact`** is special: pressing it resolves the active proximity prompt from the `prompts` field of `defineGame({...})` and runs that prompt's `invoke` command. A prompt with `invoke: null` is display-only and does nothing on the key.
+- UI keybind badges derive from `keybinds` via `actionLabel(keybinds, "openBackpack")` — `bindingLabel` maps codes to short labels (`Digit1`→`1`, `KeyB`→`B`, `mouse0`→`LMB`, `Escape`→`Esc`). Never hardcode label strings; they drift the moment a binding changes.
+- `server.mode` is a string your loop/commands interpret — the engine ships no gamemode presets.
+- Never in defineGame: player tuning, catalog helpers (`defineItems` etc.), game nouns, behaviors, prompts, or inline binding/inventory/world blobs. The one exception is `physics.gravity`/`physics.jumpVelocity` — global controller tuning, not a catalog value (see "Controller kinematics" below).
+- `assets` may be omitted for a game with no models (a HUD-only card/board game, say) — `defineGame` injects an empty catalog, so `GameDefinition.assets` is always present downstream with no per-caller `?.` checks.
+- `devtools` defaults to `true` — every game gets the F2-toggled debug overlay (Perf/Tune/Logs/Net/Keys) for free, and every top-level `export const` number/boolean/color and every exported flat table of them under `src/` is auto-discovered into the Tune tab with zero game code; set `false` to disable the toggle entirely. See "Devtools — F2 overlay and tunables" below.
+
+### `@jgengine/core/game/defineGame` — the underlying primitive
+
+The low-level engine boot call the shell `defineGame` composes internally: engine fields only (`name`, `assets`, `world`, `physics`, `inventories`, `input`, `server`, `save`, `time`, `feed`, `multiplayer`, `loop`) — no `content`/`GameUI`/`camera`/render fields, those are the shell layer's job.
+
+```ts
+import { defineGame as defineEngineGame } from "@jgengine/core/game/defineGame";
+import { offline } from "@jgengine/core/runtime/adapter";
+
+const game = defineEngineGame({
+  name: "My Game",
+  assets, world, physics, inventories,
+  input: keybinds,
+  server: "persistent",
+  save: { auto: "5m", scope: "player+chunks" },
+  multiplayer: offline(),
+  loop,                            // GameLoop<GameContext>
+});
+```
+
+Reach for this directly only outside a React host — a headless server, a non-shell runner; a browser game authors through `@jgengine/shell/defineGame` above, which calls this and returns the `PlayableGame` a runner needs.
+
+## `PlayableGame` — how a game plugs into a runner
+
+The type `@jgengine/shell/defineGame` returns and every runner (`GameHost`, `GamePlayerShell`) consumes. A game never builds this object by hand — `defineGame({...})` assembles it from the merged config. Source type at `@jgengine/core/game/playableGame`:
+
+```ts
+export type PlayableGame<TUi = unknown> = {
+  game: GameDefinition;
+  content: GameContextContent;                 // { itemById?, entityById?, objectById? }
+  loop: Required<GameLoop<GameContext>>;       // onInit, onNewPlayer, onTick
+  GameUI: TUi;                                 // React component in web runners
+  prompts?: (ctx: GameContext) => readonly PositionedPrompt[]; // interact-key + HUD source
+};
+```
+
+`prompts` is the **single source** of positioned proximity prompts: the shell reads it to fire the `interact` key, and the HUD should read the same list through `useActivePrompt(playable.prompts?.(ctx))` rather than building its own — one list, no drift. A prompt is only actionable if its `invoke` is non-null.
+
+Optional render/world fields the shell also reads: `entitySprites` / `entityModels` (billboards / GLBs keyed by entity kind), `objectModels` (GLBs keyed by object catalog id), `renderObject` (per-object visual override — return your own mesh for a placed object and the shell still positions it; falls back to `objectModels` → colored box), `WorldOverlay` (canvas-layer VFX), `environment` (canvas-layer scenery — ground/sky/structures; when set, replaces the default ground plane + debug grid + rock field), `camera`, `shadows` (cast/receive shadows across the R3F canvas; default true), and `worldHealthBars` (`boolean | { statId?, roles? }` — `roles` restricts bars to entities whose catalog `role` is in the given `CatalogEntityRole` list, e.g. skip friendly NPCs). A model value is a catalog id (`string`, resolved via `game.assets`) or an inline `ModelConfig { url, scale?, y?, anchor?, dims?, material?, animation? }` (`material` overrides color/metalness/roughness/emissive/emissiveIntensity on the cloned mesh, leaving shared GLTF caches untouched; `animation?: { clip?, loop?, timeScale?, paused?, time? }` plays a GLTF clip — `clip` defaults to the first clip, `loop` defaults true — and `paused: true` + `time: <seconds>` holds the rig on one fixed frame, a pose library for inventory previews or held cutscene poses). Catalog-resolved models carry measured `dims` (`catalog.resolve(id).dims = { footprint:{w,d}, center:{x,z}, minY }`); with the default `anchor: "center"` the shell centers the footprint on the placement point and ground-snaps `minY` to it, so corner-pivot kit models place correctly with no per-game pivot math. Applies through both `entityModels` and `objectModels`.
+
+`renderEntity?: (entity: SceneEntity) => ReactNode` and `renderObject?: (object: SceneObject) => ReactNode` hand you the mesh for one entity/object while the shell still positions it and keeps it tagged for picking/selection; return null/undefined to fall through to model → sprite/box. `objectStyles?: Record<catalogId, { color?, opacity?, hidden? }>` styles the default colored-box object render — `color` overrides the hash color, `opacity < 1` sets transparent, `hidden` skips the mesh but keeps the picking tag.
+
+**Presentation mode.** `PlayableGame.presentation`: `"3d"` (default) mounts the canvas, camera rig, and pointer; `"hud"` mounts none of that — the game is `GameUI` plus the command/input loop, for board/card/menu games that need no 3D camera at all.
+
+**Auto environment.** When `world` is an `environment()` descriptor and `PlayableGame.environment` is unset, the shell renders that descriptor as the backdrop automatically — no manual `environment` wiring needed for the common case. Set `environment` explicitly only to override that default (a custom canvas component always wins). The same auto-render convention covers grid-cell worlds (`biomes`/`voxel`/`plots`/`tilemap`) — see "World features" below.
+
+**Lighting and backdrop.** `PlayableGame.lighting` (`LightingConfig`, `@jgengine/core/game/playableGame`) replaces the shell's hardcoded ambient/directional default when present, regardless of world kind: `ambient?: { color?, intensity? }`, `directional?: { color?, intensity?, position, castShadow? }[]`, `hemisphere?: { skyColor?, groundColor?, intensity? }`. `PlayableGame.backdrop` (`BackdropConfig`) is a generic background/sky/fog for **any** world kind, including a custom `environment` component: `background?: string` (CSS color), `sky?: SkyEnvironmentConfig` (same descriptor `environment()`'s `sky` field takes), `fog?: { color?, near?, far?, density? }` (`density` set switches to exponential `FogExp2` and `near`/`far` are ignored). Both are optional and additive to whatever the world/`environment` renderer already draws.
+
+**Player movement tuning** — the `movement` field (`PlayerMovementConfig`) tunes the shell's local-player walk controller beyond `physics.gravity`/`jumpVelocity`: `mode` (`"free"` camera-relative default, `"axis"` locks travel to one world `axis`, `"grid"` snaps each committed step to `cellSize` centers), `collideObjects` (collide against placed scene objects as unit-box AABBs even without `collision.voxel`), and `beforeCommit(frame)` — an escape hatch called each frame with `{ entityId, current, next, dt }` that can return a replacement `[x, y, z]` to constrain or redirect the step (rails, bounds, custom collision) before it commits and before `onTick` runs.
+
+The runner boots `createGameContext({ definition, content, player: { userId, isNew } })`, calls `loop.onInit(ctx)` then `loop.onNewPlayer(ctx)`, and drives `loop.onTick(ctx, dt)` per frame. **Convention: `onNewPlayer` spawns the player entity with `id === ctx.player.userId`** — bounded stats, targeting, and kill attribution key off that.
+
+### Object spatial queries, entity patching, and surface sampling
+
+```ts
+ctx.scene.object.at(x, y, z)                                   // cell lookup, cell size 1, most-recent wins
+ctx.scene.object.inBox(min, max)                                // inclusive AABB query
+ctx.scene.object.raycast({ origin, direction, maxDistance, halfExtents?, filter? })   // → nearest hit or null
+ctx.scene.object.raycastAll({ origin, direction, maxDistance, halfExtents?, filter? }) // → hits, nearest-first
+ctx.scene.entity.update(id, patch)   // name/position/rotations/role/movement/behaviors/meta; false for unknown id
+```
+
+Placed objects are unit boxes (half-extents `[0.5, 0.5, 0.5]`) centered on position, matching the shell's default render, so `raycast`/`raycastAll` (`scene/objectQuery`) match what a player sees. `entity.update` notifies subscribers and bumps `ctx.version()` the same as `spawn`/`despawn`/`setPose` — it's the general-purpose patch the more specific methods (`setPose`, `form.shapeshift`, `possession.possess`) build on.
+
+`ctx.scene.object.place(catalogId, x, y, z, { instanceId?, parentSpace?, rotation?, visual? })` takes an optional `visual: ObjectVisual` (`@jgengine/core/scene/objectStore`) — `{ scale?: number | [x,y,z], color?, opacity? }` — a per-instance render override independent of the catalog entry; `ctx.scene.object.setVisual(instanceId, visual | undefined)` changes it after placement (`undefined` clears back to the catalog default). Distinct from `objectStyles` on `PlayableGame` (styles a catalog id for every instance); `visual`/`setVisual` targets one placed instance (a damaged crate, a dyed banner, a resized prop).
+
+`pointerService.worldHitCenter()` (shell) casts from the viewport center regardless of cursor presence (pointer-lock aim) — combine with `pointer.worldHit()` (cursor-driven) to support both mouse-look and free-cursor games from the same probe. `PointerHit` also carries an optional `uv?: { u, v }` on UV-mapped mesh hits (absent for the ground fallback), `material?: { color, metalness?, roughness? } | null` sampled off the hit mesh's `MeshStandardMaterial` (`null`/unset for non-standard materials, e.g. the ground plane) — combine `uv` + `material` for paint tools, decals, and material-aware interaction — and `instanceId?: number`, the hit index when the intersected mesh is a `THREE.InstancedMesh` (grid-world cells, `InstancedBodies` debris, any instanced render), absent otherwise.
+
+**Runtime paint layer** (`ctx.scene.entity.paint`, backed by `scene/paintLayer`) — a `PaintLayer` keyed by instance id (entity or object): `paint(instanceId, { u, v, radius, color })`, `strokes(instanceId)`, `clear(instanceId?)`, `version(instanceId)` (bumps per paint/clear), `subscribe(listener)`. The shell auto-renders painted instances through a lazily-created 512×512 canvas texture kept in sync — no per-game render wiring. Clearing refills with the material's base color; the original texture pixels are not restored.
+
+### Audio — positional emitters, listener falloff, buses
+Catalog-first, no per-game audio glue. The `audio` field of `defineGame({...})` — `{ sounds: Record<string, SoundDef>, buses?: Record<string, AudioBusDef> }` — declares the sound catalog (`SoundDef = { id, url, bus, gain?, loop?, positional?, falloff? }`) and mix buses (`music`/`sfx`/`ambient`/…, `AudioBusDef = { id, gain? }`) — both types from `@jgengine/core/audio/audioFalloff`. `entitySounds?: Record<string, string>` maps an entity **kind name** (same convention as `entitySprites`/`entityModels`) to a sound id: while a matching entity exists, the shell keeps a looping positional emitter on it, repositioned every frame. `objectSounds?: Record<string, string>` does the same keyed by placed-object catalog id. The pure distance→gain math (`computeFalloffGain(distance, config)`, curves `"linear" | "inverse" | "none"`) lives in core so it is unit-tested without a browser; `@jgengine/shell` (`shell/audio/audioEngine`, `shell/audio/AudioComponents`) is the only package that touches Web Audio — it owns an `AudioContext`, mounts `AudioListener` on the camera every frame, and `EntityAudioEmitters`/`ObjectAudioEmitters` drive per-instance emitter gain from the core falloff function. `GamePlayerShell` wires all of this automatically from `playable.audio`/`entitySounds`/`objectSounds` — a game never touches `AudioContext` directly.
+### Camera rigs (`camera` field of `defineGame({...})`)
+The shell ships a **rig library**; a game picks and tunes one through `camera` config, never by writing camera positions from `onTick`. Select with `camera.rig` (or the `perspective: "third" | "first"` shorthand) — or by config block alone (#207.8): supplying `camera.<rig>` selects that rig with no redundant `rig` field, checked in the table's order; an explicit `rig` wins when several blocks are present:
+| `rig` | For | Key config (`camera.<rig>`) |
+|-------|-----|------------------------------|
+| `orbit` (default) | Third-person chase | `initialDistance`, `targetHeight`, `min/maxPolarAngle`, drag/zoom |
+| `first` | FPS mouse-look | `firstPerson: { eyeHeight, sensitivity, maxPitch, reticle, viewmodel }` |
+| `topDown` | ARPG iso / top-down (Diablo IV, Hades II) | `topDown: { height, pitch, yaw, followSmoothing, zoom }` — decoupled follow; `pitch` is camera elevation (PI/2 = straight down, near 0 = grazing and boom-distance blows up past `frustum.far`) |
+| `rts` | Free-pan / edge-scroll (The Sims, Manor Lords) | `rts: { panSpeed, edgeScroll, rotateSpeed, bounds, start, pan }` — `pan: false` turns it into a static backdrop camera: no WASD/arrow pan, no edge-scroll, no Q/E rotate, no wheel zoom, still re-centers on `followEntityId` if one resolves |
+| `shoulder` | Over-the-shoulder (Helldivers 2, Remnant II) | `shoulder: { shoulderOffset, distance, ads, side }` — ADS + shoulder-swap (V) |
+| `lockOn` | Souls-like strafe (Elden Ring) | `lockOn: { targetEntityId?, distance, framingBias, yawSmoothing }` — yaw binds to player→target; WASD becomes strafe |
+| `chase` | Vehicle chase (Forza, Rocket League) | `chase: { distance, springDamping, fov: { base, max, speedForMax }, shakePerSpeed, view: "chase"|"cockpit"|"hood"|"rear" }` |
+| `sideScroll` | Fixed lateral follow — 2.5D platformer/beat-'em-up | `sideScroll: { distance, height, lookHeight, axis: "x"\|"z", followSmoothing, fov }` — reads no player input, follows like the other follow rigs (defaults to the local player) |
+| `observer` | Detached spectator/photo/kill-cam (#120) | `observer: { bind: { kind: "entity", entityId } \| { kind: "point", position }, distance, height, orbitSpeed }` — reads no player input, auto-orbits the bound subject |
+| `inspection` | Model-viewer / data-viz orbit (#207.7) | `inspection: { anchor: "target"\|"cursor"\|"center", target, initialDistance, initialPosition, min/maxDistance, min/maxPolarAngle, pan, rotateSpeed, zoomSpeed, dampingFactor }` — left-drag orbit, middle/right-drag pan (pan defaults on for this rig only), scroll zoom toward the anchor (`cursor` = zoom-to-cursor); orbits a fixed `target`, never reads player/entity state |
+| `none` | No camera rig mounted | HUD-only presentations or a game that manages its own camera; see `presentation: "hud"` below |
+**Frustum:** `camera.frustum: { fov?, near?, far? }` overrides the canvas camera; `far` defaults to 300, so any world whose content spans more than a few hundred units must raise it or distant settlements/terrain silently clip out of view. **Every rig accepts `followEntityId: null`** so avatar-less games (city-builders, card games, auto-battlers) still mount a camera. Leave `followEntityId` unset and the shell defaults it to `ctx.player.possession.active(userId)` every frame, so a possession swap (party control-swap, BG3-style) or a form's mesh/camera-relevant change re-targets the camera automatically — set it explicitly only to override that default. **Shake / trauma (#28):** every rig reads a shake channel; feed it from anywhere with `import { cameraShake } from "@jgengine/shell/camera"` — `cameraShake(amplitude, decayPerSecond?)` (amplitude 0..1) — or from React via `useCameraShake()`. Tune with `camera.shake: { maxOffset, maxRoll, decayPerSecond, exponent, frequency }`. **Cinematic (#29):** set `camera.cinematic: { keyframes: [{ position, lookAt, fov?, duration?, ease? }], loop? }` to play a scripted path over the active rig, and `camera.transitionSeconds` cross-fades the camera when the rig changes so mode swaps don't hard-cut. The pure rig math (shake decay, spring-arm, speed→FOV, offset/strafe, keyframe lerp) is exported from `@jgengine/shell/camera` for testing.
+
+## `GameContext` — the ctx surface
+
+`createGameContext` (in `@jgengine/core/runtime/gameContext`) wires every system:
+
+```
+ctx.scene.object    place, remove, move, rotate, get, list, subscribe,
+                    at, inBox, raycast, raycastAll, catalog
+ctx.scene.entity    spawn, despawn, setPose, update, get, list,
+                    stats.{get,set,delta}, setTarget, getTarget, cycleTarget,
+                    canReceive, preview, effect, paint,
+                    willHitProjectile, fireProjectile, settleProjectile,
+                    distance, inRadius, hasLineOfSight, queryArc, moveToward,
+                    spawnPoseOf, resetToSpawn, resetAllToSpawn,
+                    form.{register,get,active,abilities,shapeshift,revert}
+ctx.game            commands, events, feed, loot, trade, quest, social, chat,
+                    unlocks, economy, leaderboard, roster, store, cards, turn
+ctx.game.social     friends, party, presence, emotes.play, worldInvites
+ctx.game.store      set, delete, get, has, subscribe, mapSnapshot, arraySnapshot — game-defined
+                    keyed reactive store slot (any value type); mutations bump ctx.version()
+ctx.game.cards      pile(id, config?) — lazily creates (config required on first call) or returns
+                    the existing notify-wrapped CardPile for id
+ctx.game.turn       loop(id, config?) — lazily creates (config required on first call) or returns
+                    the existing notify-wrapped TurnLoop for id
+ctx.player          userId, isNew, inventory, stats (modifiers), loadout,
+                    applyLoadout, movement (pose/aim), motion (impulse/setVerticalVelocity/setY/takePending),
+                    possession, cosmetics
+ctx.player.motion   impulse(vy), setVerticalVelocity(vy), setY(y), takePending() — game-code
+                    seam into the shell's vertical-motion integrator; drained once per frame
+                    before gravity, so a jump pad or grapple release calls this from
+                    onTick/commands instead of touching y directly
+ctx.item            use, weapon
+ctx.input           publish(held), isDown(action), held() — per-frame held-action snapshot, polled from onTick
+ctx.world           ground (TerrainField), groundHeightAt(x, z) — the canonical
+                    sampler for the game's declared world; environment worlds
+                    resolve their terrain field, every other world kind is 0.
+                    Use it for every spawn/placement/waypoint y — never
+                    hand-roll a noise sampler or hardcode y = 0 on relief
+ctx.camera          follow(entityId | null), followedEntityId(), setCinematic(config), cinematic(),
+                    subscribe — runtime camera-follow/cinematic override; the shell reads
+                    followedEntityId() each frame, falling back to the static
+                    playable.camera.followEntityId when it returns undefined
+ctx.time            advance, now, calendar, snapshot; pause, play, toggle,
+                    setSpeed, cycleSpeed; after, every, at (game-time timers)
+ctx.subscribe / ctx.version    change signal — UI layers bind via useSyncExternalStore
+```
+
+`content.itemById(id)` supplies `{ use?, weapon?, trade? }`; `content.entityById(id)` supplies `{ stats?, receive?, onDeath?, movement?, role? }`; `content.objectById(id)` supplies `GameContextObjectEntry` `{ proximityPrompt?, breakable?, slotInventory? }`. Build all three from your catalogs in `content.ts`. A placed object resolves its catalog entry via `ctx.scene.object.catalog(instanceId)`; `ctx.scene.object.at(x, y, z, tolerance?)` finds placed objects near a point (grid interaction, click resolution beyond the pointer service). `ctx.scene.entity.update(id, patch)` writes a shallow patch onto a spawned entity's mutable fields (e.g. `movement.walkSpeed`) without a full respawn — `scene/movementSpeed`'s `applyStatDrivenSpeed(deps, id, { baseSpeed, multiplierStat?, flatBonusStat? })` is the catalog-driven helper that recomputes and writes `movement.walkSpeed` from a stat-modifier pair each time a buff changes.
+
+### Two tiers: `ctx` runtime vs pure factories
+
+The `ctx` surface above is the **stateful runtime** — it's what game code uses. Every subsystem it wires is *also* exported as a **pure factory** that `createGameContext` composes internally: `createTradeSystem`, `createDeathSystem`, `createEffectSystem`, `createProjectileSystem`, `createSpatialApi`, `createEntityStatsApi`, `createEntityStore`, `createObjectStore`, `createStats`, `createLoadouts`, `createLootRegistry`, `createQuestJournal`, `createSocial`, `createSlots`, `createInteriors` (plus stateless helpers beside each — `canAffordCosts`/`resolveBuy` in `game/trade`, `getStatValue`/`applyPoolDelta` in `scene/entityStats`, and so on). **Build a game through `ctx`, not these** — reach for the factories only for unit tests of pure game math, headless servers, or a custom runtime. Import the domain deep path (`@jgengine/core/combat/death`, `@jgengine/core/game/trade`, `@jgengine/core/stats/statModifiers`, …) and read the `.d.ts`; each is a real export in the published package.
+
+`createSpatialApi`'s optional `grid: { cellSize }` opts `inRadius`/`queryArc` into a lazily-built x/z broadphase index over `candidates()` instead of a linear scan — worth it once candidate counts run into the hundreds+. The index is reused across calls until `invalidate()` is called, so call it after any position change (move, spawn, despawn); a candidate outside the index at query time still resolves exactly (never silently skipped), only a *moved* one can be missed until invalidated.
+
+## `loop` — lifecycle
+
+```ts
+export function onInit(ctx: GameContext) {
+  ctx.item.use.register(itemUseHandlers);
+  ctx.player.loadout.register(loadouts);
+  for (const table of lootTables) ctx.game.loot.register(table);
+  ctx.game.quest.register(quests);
+  ctx.game.quest.bind("entity.died");
+  ctx.game.feed.bind("entity.died");
+  ctx.game.events.on("entity.died", (evt) => onEntityDied(ctx, evt));
+  setupWorld(ctx);
+}
+
+export function onNewPlayer(ctx: GameContext) {
+  ctx.scene.entity.spawn("player_default", { id: ctx.player.userId, position: spawnPoint });
+  if (ctx.player.isNew) ctx.player.applyLoadout(ctx.player.userId, "starterKit");
+}
+
+export function onTick(ctx: GameContext, dt: number) {
+  // AI, regen, respawn timers — dt is GAME time (see ctx.time). Never death detection (see entity.died)
+}
+```
+
+`onInit` runs once per boot; register everything there. Loot tables register through `ctx.game.loot.register` — `lootTable()` is a pure validating factory, there is no global side-effect registry.
+
+## `ctx.time` — the simulation clock
+
+`onTick`'s `dt` is **game time, not real time**: the shell scales each frame's real delta by `definition.time.scale` (real→game seconds at 1×) and the live speed multiplier, so writing decay/regen/AI as `rate * dt` makes it obey pause and fast-forward for free — never read wall-clock in a tick. Configure via `defineGame({ time: { scale?, speeds?, dayLength?, start?, startPaused?, daysPerYear?, seasons? } })` (all optional; default is real-time 1:1 with speeds `[1,2,3,4]`, 365-day years).
+
+- **Continuous** work scales through `dt`. **Scheduled** work uses game-time timers: `ctx.time.after(sec, cb)`, `ctx.time.every(sec, cb)`, `ctx.time.at(gameSec, cb)` — measured in game-seconds, so 4× fires them 4× sooner and pause freezes them. Each returns a cancel handle.
+- **Controls** (drive from a HUD or a command): `pause()`, `play()`, `toggle()`, `setSpeed(mult)` (0 pauses), `cycleSpeed()`. Read state with `ctx.time.snapshot()` / `ctx.time.calendar()` (`{ day, hour, minute, second, dayFraction, year, dayOfYear, yearFraction, season? }`), or in React with `useGameClock()` → snapshot + `controls`. Speeding to 4× or pausing affects **everything** on the tick — no per-system wiring.
+- **Calendar year/season** rides the same day counter, no separate clock: `year`/`dayOfYear` fall out of `day` divided by `TimeConfig.daysPerYear` (default 365), `yearFraction` is progress through the current year (0..1). Setting `TimeConfig.seasons: string[]` (e.g. `["spring","summer","fall","winter"]`) slices the year into equal named segments and populates `calendar().season`; omit `seasons` and the field is absent — a living-world sim names its own season boundaries this way instead of a hand-rolled `dayOfYear % ...` module.
+
+### Beat clock — BPM signal + input quantization
+
+`@jgengine/core/time/beatClock` is a separate, purpose-built signal from `simClock` — a BPM tick generator for rhythm games (Hi-Fi Rush–style quantized combat), not a day/pause clock. `createBeatClock({ bpm, beatsPerBar? }, onBeat?)` returns a `BeatClock`: call `advance(gameDt)` from `onTick` with the same **game-time** `dt` (never wall-clock) — it fires `onBeat(beatIndex)` once per newly crossed integer beat and returns a `BeatSnapshot` (`beat`, `beatIndex`, `bar`, `beatInBar`, `phase`). `createBeatInputBuffer<T>(beatDurationSec)` is the auto-correct input buffer: `buffer(action, nowSec)` quantizes an off-beat press to fire on the next beat tick (or immediately if pressed exactly on one); `advance(nowSec)` drains and returns every action whose beat has arrived. `nextBeatTime(nowSec, beatDurationSec)` is the underlying pure quantization function. Feed a music track's actual BPM in; the buffer is what makes an early/late input still land on-beat.
+
+## Content catalogs
+
+### Object catalog fields
+
+| Field | Purpose |
+|-------|---------|
+| `id`, `model` | Canonical id, asset key |
+| `footprint` | `{ w, h, d }` placement bounds |
+| `snap` | `"grid"` \| `"free"` \| `"wall"` |
+| `solid` | Blocks movement |
+| `breakable` | `false` or `{ baseBreakTime, harvest, drops, dropsWhenUnmet }` |
+| `proximityPrompt` | Float UI + optional command invoke |
+| `slotInventory` | Attached container `{ slots, accepts }` created at place time (`object:<instanceId>`) |
+
+Break resolution: `duration = baseBreakTime / (tool?.breakSpeed ?? 1)`; drops per `when` (`always` / `harvestMet` / `silkTouch` / `playerKill`); then `inventory.put` + `object.remove`.
+
+### Item catalog fields
+
+| Field | Purpose |
+|-------|---------|
+| `id`, `kind`, `stack`, `model` | Basics; `stack` feeds `itemTraits.stackLimit` |
+| `use` | Game handler name dispatched by `item.use` (`"fireGun"`, `"castBolt"`, `"drinkPotion"`) |
+| `weapon` | Stats the handler reads via `item.weapon.getStat` — `damage`, `heal`, `reach`, `manaCost`, `projectile.{mass,gravity,fuseTime,settleOn}`, `explosion.{radius}` … |
+| `trade` | `{ buy?: {coins: 80}, sell?, shops?: ["shop_town"] }` |
+| `requires` | Unlock ids gating purchase/use |
+| `placesObject` | Object id placed from hotbar |
+| `rarity`, `baseType` | Read by the `worldItem` rarity render binding + loot filter when this item drops to the ground (#32/#33); `baseType` defaults to the item id when absent |
+
+### Entity catalog fields
+
+| Field | Purpose |
+|-------|---------|
+| `movement` | `walkSpeed` (reaches spawn automatically), `poses?: ["standing","crouch","prone","running"]`, `aim?: ["hip","ads"]`, `frozen?: boolean` — a scene-instance-level movement lock (cutscenes, stuns, mount transitions); `movedWhileFrozen(entity)` (`scene/entityStore`) flags an entity whose velocity moved anyway despite `frozen: true`, catching a system that bypassed the lock |
+| `role` | `CatalogEntityRole` = `"player"` \| `"enemy"` \| `"hostile"` \| `"npc"` \| `"vehicle"` — catalog hostility class for targeting (`"enemy"`/`"hostile"` classify hostile in `cycleTarget`). Distinct from the scene *instance* `EntityRole` (`"player"` \| `"npc"` \| `"prop"`, in `scene/entityStore`) which drives input/camera binding — **possession** (`ctx.player.possession`) flips this instance role between `"player"`/`"npc"` on every control swap, so exactly one owned entity is ever the input/camera target |
+| `stats` | Stat declarations — bounded values: `{ health: { max: 120, min: 0 }, level: { max: 60, min: 1, current: 1 }, … }` — `current` optional, defaults to `max` |
+| `receive` | Per-effect absorption: `{ damage: { order: ["shield","health"], modifiers? }, heal: { order: ["health"] } }` — keyed by **game-defined effect ids**; presence = can receive |
+| `onDeath` | `{ drops: "table_id" }` or reason-aware `{ drops: [{ table, when: { reason: "player_kill" } }], command?: { name, when? } }` |
+| `wander`, `talkable` | AI descriptor; dialogue id sugar for a talk prompt |
+
+### Dialogue catalog
+
+`entities/npcs/dialogues.ts` — `{ id, lines: [{ speaker, text } | { choices: [{ label, invoke: { command, args } | null }] }] }`. Choices invoke `quest.accept`, `trade.open`, etc. Types ship from `@jgengine/react/components` (`DialogueDef`, `DialogueChoice`, `DialogueLine`) so a game imports them rather than redeclaring — the `DialogueBox` component renders the same shape it types.
+
+A choice may gate its branch behind a roll: `{ check: { modifier, dc, advantage? }, onSuccess?, onFailure? }` (`onSuccess`/`onFailure` default to `invoke` when omitted). `DialogueBox` rolls via `@jgengine/core/stats/rollCheck`'s `rollCheck({ modifier, dc, advantage }, rng?)` (d20 by default; `advantage`/`disadvantage` roll twice and take the high/low; a natural 1 or max-die result reports `critical`) when the player clicks a checked choice, then calls `onChoice(choice, result)`; game code resolves which command to run with `resolveDialogueInvoke(choice, result)` (also exported from `@jgengine/react/components`).
+
+## `scene.entity.stats` — bounded stats
+
+```ts
+stats.get(instanceId, statId)        // → { current, max, min } | null
+stats.set(instanceId, statId, { current?, max?, min? })
+stats.delta(instanceId, statId, n)   // → null | { reason } — clamps into [min, max]
+```
+
+Health, mana, xp, level, energy — any stat id declared on the catalog. Spawn seeds from the catalog (`current ?? max`). Combat writes through effects; non-combat (regen ticks, XP grants) calls `delta` directly.
+
+**XP/level use the engine progression primitive.** `@jgengine/core/game/progression` ships `curve()`/`evalCurve()` (evaluate a game-owned XP-per-level curve *definition*) and `leveling()` (a level track over the bounded `xp`/`level` stats that reports overflow). You own the curve *numbers* in a catalog; the engine owns the overflow math — on level-up bump `level.current`, reset `xp.max` from the curve, push a `stat.levelUp` feed entry. Hand-rolling `xpForLevel`/`levelFromXp`/`xpToNextLevel` is the anti-pattern — those already exist. `LevelingConfig.thresholdMode` picks how the curve is read: `"perLevel"` (default) treats `xpForLevel(N)` as the incremental N-1→N cost, summed internally; `"cumulative"` treats `xpForLevel(N)` as the total lifetime XP to reach level N (0 at/below `startLevel`) and compares `xp.current` straight against those totals — pick this for a design that quotes "total XP to level N" tables.
+
+`leveling({ …, thresholdMode: "cumulative" })` switches to lifetime-total semantics: `xp` is a running total instead of a per-level bank, and `resolve(level, xp)` walks upward from `level` to the highest level whose cumulative threshold `xp` clears — it never demotes, and clamps the returned `xp` to the max-level threshold once capped. Default is `"perLevel"` (unchanged, fully back-compat) — pick `"cumulative"` for a total-XP display (MMO-style "12,450 XP") instead of a resettable per-level bank.
+
+`ctx.player.stats` is a different thing: **modifiers** (buffs, ADS zoom, walk-speed bonuses) via `base/add/remove/get` with expiries — never bounded current/max values.
+
+## Targeting (MMO tab-target)
+
+Persistent per-entity session state — never a per-use input field.
+
+```ts
+ctx.scene.entity.setTarget(fromId, toId | null)
+ctx.scene.entity.getTarget(fromId)                    // → instanceId | null
+ctx.scene.entity.cycleTarget(fromId, { filter: "hostile" | "friendly" | "any", direction? })
+```
+
+Hostility comes from catalog `role` (`"enemy"`/`"hostile"` classify hostile). Input `tabTarget`/`clearTarget` actions route here. Handlers always read `getTarget(input.from)` — `ItemUseInput` deliberately has **no `to` field** (single source of truth, no client-supplied target to validate, three targeting models stay clean: aim for shooters, `queryArc` for melee, `getTarget` for MMO).
+
+## `item.use` — one verb for all usable items
+
+```ts
+ctx.item.use.register(handlers)      // once in onInit; duplicate names throw
+ctx.item.use.can(ctx, input)         // → { reason } | null
+ctx.item.use.use(ctx, input)         // dispatches catalog `use` → your handler
+
+type ItemUseInput = { from: string; itemId: string; inventoryId?: string; aim?: Aim };
+type ItemUseHandler<GameContext> = {
+  can?(ctx, input): { reason: string } | null;
+  apply(ctx, input): { state: GameContext; error?: string };
+};
+```
+
+**Handlers receive the full `GameContext` as state** and mutate through it. Handlers own ammo, cooldowns, range checks, and effect ids; the engine owns projectile geometry, stat clamp math, and `canReceive`.
+
+| Handler | Engine calls |
+|---------|--------------|
+| gun | spend ammo → `fireProjectile` → `settleProjectile` |
+| grenade | `fireProjectile` (ballistic) → settle → `effect({ at, radius })` |
+| melee | `queryArc` + reach from `getStat` → `effect` per hit |
+| MMO cast | `getTarget(from)` → `stats.delta(mana)` → `effect({ to })` |
+| consumable | `effect({ to: from, effect: "heal", via: { amount: -n } })` |
+
+Banned in the engine: `weapon.fire`, `consumable.use`, `game.combat.*`, per-weapon commands.
+
+### Skill-checks and QTE (timed/rolled minigames)
+
+`@jgengine/core/interaction/skillCheck` models a moving-target-zone minigame (casting/reeling, active-reload): `evaluateSkillCheck({ trackWidth, zone, markerPeriod, window, zoneDriftPerSecond? }, elapsedSeconds)` bounces a marker back and forth over `markerPeriod` seconds and returns `{ success, timedOut, markerPosition, zone }` — `zone` itself can drift when `zoneDriftPerSecond` is set. It is pure: an `item.use` handler starts a session by recording `ctx.time.now()` (game-time, so pause/fast-forward apply for free) the first time it's pressed, and evaluates `evaluateSkillCheck` against the elapsed time on the next press to lock in success/fail — the session bookkeeping (a `Map<instanceId, startedAt>`) is game-owned, same pattern as an ability-cooldown map.
+
+`@jgengine/core/interaction/qte` sequences discrete timed prompts: `evaluateQteSequence(steps: QteStep[], inputs: QteInputEvent[])` walks `{ id, action, windowStart, windowEnd }` steps against `{ action, at }` presses and returns `{ status: "success" }` or `{ status: "fail", atStep, reason }`; `pendingQteStep`/`qteProgress` read the currently-active step and fraction complete for UI.
+
+`@jgengine/react` ships matching headless UI: `SkillCheckBar({ config, startedAt })` and `QteTrack({ steps, startedAt })` self-tick via `requestAnimationFrame` and read `ctx.time.now()` each frame — pass `className`/`trackClassName`/`zoneClassName`/`markerClassName` (or `stepClassName`/`activeClassName`/`doneClassName` for `QteTrack`) for the moving-zone/timing visuals the UI quality bar requires.
+
+### Capture and owned roster
+
+`@jgengine/core/scene/captureCheck` — `captureChance({ hpFraction, catchPower, difficulty? })` returns a 0..1 probability (lower `hpFraction` and higher `catchPower` raise it, higher `difficulty` lowers it); `rollCapture(input, rng?)` rolls it. `@jgengine/core/scene/roster` — `createRoster()` is a persisted, per-owner store (`capture`, `release`, `list`, `get`, `setEquipped`, `equippedList`, `snapshot`/`hydrate`) wired onto the runtime as `ctx.game.roster`, distinct from `game.social.party` (session-ephemeral) — roster entries persist and are optionally equipped (deployed) independent of party membership.
+
+A capture item's `item.use` handler composes the primitives instead of forking them: read the wild target's hp via `ctx.scene.entity.stats.get(target, "health")`, roll `rollCapture({ hpFraction, catchPower })`, and on success call `ctx.scene.entity.despawn(target)` + `ctx.game.roster.capture(ownerId, catalogId)` — the wild scene entity is removed and re-parented into the owner's persisted roster; the react `CaptureOdds({ chance })` component shows the live odds meter the UI quality bar requires.
+
+## Combat — effects, projectiles, death, feel, abilities
+
+Combat primitives — effects & projectiles, death handling, melee/defense/telegraph feel, and abilities/resources/auto-target/resistance/run drafts. Full surface: **[reference/combat.md](reference/combat.md)**.
+
+## Loot
+
+```ts
+lootTable({ id, rolls?, entries: [{ item? | currency?, count: n | [min,max], weight }] })
+ctx.game.loot.register(table)        // in onInit
+ctx.game.loot.has(id) / roll(id, rng?) / grantToPlayer(userId, drops, source?)
+```
+
+Tables colocate with their domain (`entities/enemies/loot-tables.ts`, `objects/loot-tables.ts`). Entities reference them via `onDeath.drops`; chests via a `loot.open` command arg. `grantToPlayer` fills declared inventories, grants currencies, and emits `loot.granted`.
+
+## Card, board & shaped-inventory primitives
+Pure, renderer-free structures for card, board, and deckbuilder games — they sit **beside** the slot inventory, not in place of it. All are immutable-reducer + thin-controller pairs, mirroring the two-tier ctx/factory model: use the `create*` controller in game code, reach for the exported pure functions (`draw`, `moveCards`, `tickTimeline`, `laneAggregate`, `runPipeline`, `placeShaped`) for unit tests and headless servers.
+```ts
+// cards/cardPile — named ordered zones (deck/hand/discard/exhaust); seeded shuffle, hand limit, reshuffle-on-empty
+const pile = ctx.game.cards.pile("deck", { zones: ["deck","hand","discard","exhaust"], drawFrom:"deck", handZone:"hand", discardTo:"discard", handLimit:7, reshuffleFrom:"discard" });
+pile.reset(createCardPileState(pileConfig, { deck: ids }));   // seed zone contents once, from onInit
+pile.shuffle("deck", seed);            // seeded Fisher–Yates via pileRng — deterministic under the same seed
+pile.draw(5);                          // deck → hand, clamped to handLimit, reshuffles discard when deck runs dry
+pile.discard(ids); pile.exhaust(ids, "exhaust");   // Slay the Spire / Balatro lifecycle
+// cards/modifierPipeline — ordered { source, apply(value) → value } with an inspectable per-step trace
+const score = runPipeline({ chips: 10, mult: 1 }, jokers);   // score.value + score.trace[i].{before,after,changed} for Balatro-style scoring readouts
+// board/laneBoard — N lanes, per-side power aggregate + optional per-lane LaneRule modifier (Marvel Snap / Inscryption)
+board.aggregate(lane, "player").total; board.outcome(lane).winner; board.lanesWon();
+// board/timelineBoard — N slots each on an independent cooldown, resolving in expiry order (The Bazaar auto-battlers)
+board.tick(dtMs);   // → fires[] sorted by expiry time then slot index; multiple fires per slot per tick
+// inventory/shapedGrid — polyomino footprints, rotate, overlap-check, adjacency (Backpack Hero / Tetris inventory)
+placeShaped(grid, { id, value, footprint }, [col,row], rotation);   // rotateFootprint / canPlace guard overlap + bounds
+gridAdjacencyQuery(grid).neighborsOf(id);   // feeds synergy effects
+```
+Reuse the engine's seeded RNG (`pileRng`) for anything random — never `Math.random()` in game logic. The React drag/rotate/drop/snap gesture layer over these lives in `@jgengine/react` (see UI section).
+
+`ctx.game.cards.pile(id, config?)` is the runtime-wired accessor for `createCardPile`: lazily creates the pile on first call (`config` required then) or returns the existing one for `id` on every later call, and every mutation notifies `ctx.subscribe`/bumps `ctx.version()` — so a `useEngineState`-bound hand/discard view re-renders without a game-owned store. Reach for `createCardPile` directly only for a headless test or server; game code goes through `ctx.game.cards.pile`.
+
+## Puzzle primitives — cell grids and falling pieces
+
+Two pure, renderer-free `@jgengine/core` primitives for cell-based puzzle games (Tetris wells, match-3 boards); tile art and the drop-cadence loop are the shell's/game's job.
+
+- **`puzzle/cellGrid`** — a generic immutable `CellGrid<T>` for uniform typed-cell boards. Row 0 is the top; `y` grows downward. `createCellGrid`, `cellAt`, `withCell`/`withCells` (immutable single/batch writes), `fullRows`/`clearRows` (line-clear + compaction), `collapseColumns` (match-3 cascade gravity), `findRuns` (run detection with an optional custom matcher).
+- **`puzzle/fallingPiece`** — the falling-piece layer over a `CellGrid`: `ShapeTable<TShape>` maps rotation states to cell offsets; `pieceCells`/`pieceCollides`/`mergePiece` place, test, and commit a piece; `dropDistance` computes the ghost-piece landing row; `gravityInterval`/`levelForLines`/`lineScore` are the classic Tetris drop-speed/level/score curves (overridable); `createLockDelay`/`stepLockDelay` is the grounded→countdown→lock stepper (`delaySeconds: 0` locks instantly on touchdown).
+- **`tactics/fallingGrid`** — a generic tile-drop grid over any `TCell` payload (distinct from the `cellGrid`/`fallingPiece` row-clear pair): `createFallingGrid(config)`, `gravityIntervalMs(level, config?)` for the drop-speed curve, and a `FallingGridSnapshot`/`LockState` shape for the grounded→lock stepper.
+
+## Dropped items — `worldItem` and the loot filter
+A `worldItem` is a scene **entity** (position + item ref + rarity), never an inventory item or object — see the three buckets. `onDeath.dropMode: "world"` (above) is the usual producer; games can also hand-place ground loot (chests, quest drops).
+ctx.scene.worldItem.spawn({ itemId, position, rarity?, baseType?, count?, affixTier?, source? })
+ctx.scene.worldItem.get(instanceId) / list() / nearestInRadius(from, radius, filter?)
+ctx.scene.worldItem.pickup(instanceId, userId)   // grants to inventory + despawns, emits worldItem.picked_up
+Click-to-grab is engine-owned: setting `pointer.grabWorldItems: true` in `defineGame({...})` makes `@jgengine/shell`'s `GamePlayerShell` resolve `pointer.worldHit()` on primary click, and — when the hit entity is a `worldItem` within the `worldItem.pickupRadius` (default `DEFAULT_PICKUP_RADIUS`) configured on `defineGame({...})` of the local player — calls `pickup` directly, no game command needed. `@jgengine/react`'s `useWorldItems()` / `useNearestWorldItem(radius)` drive a HUD pickup prompt off the same store.
+Presentation is a two-layer render binding, both engine-owned (rendered by `@jgengine/shell`'s `WorldItems`) over **game-supplied data**:
+1. **Rarity baseline** — the `worldItem.rarityStyle: Record<rarity, { color?, beam?, label? }>` field of `defineGame({...})`, the game's rarity palette (Borderlands/Diablo-style beam + color coding).
+2. **Loot filter overlay** (#33) — the `worldItem.filter: LootFilterRule[]` field of `defineGame({...})`, built with `lootFilter([{ id, when: { rarity?, baseType?, minAffixTier?, maxAffixTier? }, hide?, color?, beam?, label? }])` from `game/lootFilter`. **First matching rule wins** (PoE/Last Epoch block semantics); a rule only overrides the fields it sets, everything else falls back to the rarity baseline. `resolveWorldItemPresentation(item, rarityStyle, rules)` composes both layers and is what the shell calls per item.
+## Gear systems — durability, affixes, modular items, storage tiers
+Four pure primitives that hang off item **instances** (not the stackable catalog id) — all catalog-first (specs are game-supplied config) and renderer-free. Item instances that carry durability/affix/modular state key off a game-assigned instance id, the same way targeting keys off entity instance ids.
+**Durability** (`item/durability`) — per-instance wear + repair. `DurabilitySpec` (`{ max, wearPerUse?, wearPerHit?, disableAtZero?, repair? }`) is catalog data; `createDurability(spec)` seeds a `DurabilityState`, `wear(spec, state, "use" | "hit", times?)` decrements (floors at 0), `isDisabled(spec, state)` gates use at zero, `durabilityFraction` feeds a HUD bar. Repair is quote-then-apply: `repairQuote(spec, state, { station?, to? })` returns the `{ item, count }[]` material cost (scaled by points restored) + the post-repair state (optional `qualityLossPerRepair` shrinks `max` each repair, Tarkov-style) — the game charges the materials through inventory, then commits the quote's `state`. `createDurabilityTracker()` keeps `DurabilityState` per instance id for the runtime.
+**Affix roller** (`item/affix`) — procgen `base × rarity → { rolled affixes, computed stats, name }`. `createAffixRoller({ pools, rarities })` over rarity-weighted `AffixPool`s. `roll(base, rarityId, rng)` draws `affixCount` distinct affixes without replacement (weighted, via the engine's `pickWeighted`), computes stats (base × `rarity.statScale`, then `op: "add"` affixes, then `op: "mul"`), and composes a name from `rarity.namePart` + prefix/suffix parts. `rollRarity(rng)` picks a weighted tier; `rollRandom(base, rng)` chains both. Pass `seededRng(seed)` for deterministic drops; any `() => number` rng works (same contract as `loot.roll`). `seededRng` lives in `random/rng` (re-exported here) alongside `seededStreams(seed)`, which derives independent named streams from one seed — `streams("worldgen")` vs `streams("history")` — so simulation draws never perturb generation (intervening in a run cannot change the map).
+**Modular item** (`item/modularItem`) — a whole assembled from parts in typed mount slots (guns, mechs). `ModularItemDef` has `slots: MountSlotDef[]` (`{ id, accepts, required? }`); `install(def, installed, slotId, part)` validates the slot exists, accepts the part's `category`, and is empty; `computeEffectiveStats(def, installed)` rolls part `stats` (additive) then `multipliers` over `baseStats`; `missingRequiredSlots`/`isComplete` gate a buildable whole. `createModularItem(def)` is the stateful wrapper (`install`/`uninstall`/`effectiveStats`/`partInSlot`).
+**Storage tiers + insurance** (`inventory/storageTier`) — the extraction-economy inventory half. Inventory containers carry a `tier: "carried" | "banked"` (`InventoryDeclaration.tier`; a Tarkov secure container is just a `banked` container on the body). `partitionOnDeath(containers)` splits a death snapshot into `{ kept, lost }` (banked survives, carried is dropped, stacks merged). `createDeliveryQueue()` is the delayed-delivery (insurance) hook: `schedule` a `ScheduledDelivery` with a game-time `deliverAt`, then `due(now)` / `claimDue(now)` drain it on the tick clock. `insureLost(lost, policy, userId, now, rng?)` filters the lost set to insured items and stamps a delayed `deliverAt` → feed straight into the queue. `resolveConsolation(policy, partition)` returns a baseline loadout id (apply via `applyLoadout`) — the death consolation grant, optionally gated on `if-carried-empty`. *(Session/round machines — extraction hold-to-leave, raid banking — consume this tier; see the objective-machine group.)*
+## Objective, round & session machines
+Content-agnostic state machines for competitive/session shapes — plant/defuse, buy/live/end rounds, downed/revive, the battle-royale ring, extraction raids, run-vs-meta persistence. All pure `core`; every timer takes a **game-time** `dt`/`now` (`ctx.time`), so pause and fast-forward apply for free. Drive them from `loop.onTick` and pipe their events into `ctx.game.feed`/`events`; render their snapshots as HUD (per the UI quality bar in [`reference/ui-react.md`](reference/ui-react.md) — the downed banner, ring warning, and extraction timer are required HUD).
+**Contested channel** (`session/contestedChannel`) — the interrupt-on-damage progress objective behind plant/defuse, cash-out, urn deposit, banishing, and hold-to-extract. `createContestedChannel({ duration, interruptOnDamage?, resetOnInterrupt?, favorability?, ratePerOccupant?, contested?, decayRate? })`: `start(team)` begins the channel, `tick(dt, occupants)` advances it against per-team occupancy (`Record<teamId, count>`) and emits `start`/`tick`/`contested`/`paused`/`complete` events, `damage(reason?)` interrupts (keeps or zeroes progress per `resetOnInterrupt`). `favorability[team]` scales fill rate (Deadlock deposit); `ratePerOccupant` fills faster with more owners present; `contested: "pause" | "decay"` chooses whether an opposing occupant freezes or reverses progress (The Finals contest). The owner leaving pauses it. Extraction hold-to-leave reuses this primitive verbatim.
+**Round state** (`session/roundState`) — the buy→live→end match machine (Valorant/CS). `createRoundState({ phases, teams, phaseOrder?, winCondition?, maxRounds?, winReward?, lossBonus? })`: `tick(dt)` runs the phase timer and auto-advances (emitting `phase.start`/`phase.end`, rolling the last phase back into the next round's first), `concludeRound(winner)` records the win on any "conclude-eligible" phase (any phase but the first/last in the cycle), settles `round.economy` (winner gets `winReward`, losers get an escalating `lossBonus` via `lossBonusFor(rule, streak)` clamped to `max`), and moves to the next phase. `onPhaseEnd(hook)` fires commerce/spawn gates on each transition; `match.end` fires at `maxRounds`. `server.mode` stays a game string — this is the timer/economy engine under it.
+
+Two extras beyond the default buy/live/end cycle: `phaseOrder?: string[]` overrides the phase names/cycle entirely (a wider `Record<string, number>` `phases` shape to match) — a draft→ban→play→score cycle is the same machine with different phase names. `teams: (string | { id, role? })[]` accepts a plain id or a `{ id, role }` pair; `roleOf(team)` reads the tag back (`"attacker"`/`"defender"`, Valorant side assignment) without a parallel lookup table. `winCondition?: (snapshot: RoundSnapshot) => string | null` lets `evaluate()` (call it from `onTick` alongside `tick(dt)`) auto-conclude the round the instant a score/objective condition is met, instead of the game hand-calling `concludeRound` — return a team id to end it, `null` to keep playing; `RoundSnapshot` is `{ round, phase, timeLeft, scores, lossStreaks, roles, matchOver }`.
+**Role assignment** (`session/roles`) — `assignRoles(players, specs: RoleSpec[])` distributes fixed-count or proportional roles (hider/seeker, spy/operative, prop/hunter) across a player list — the allocation half of an asymmetric session mode; `RoundConfig.teams`' per-team `role` is the lighter-weight alternative when a round machine already tracks the roster.
+**Downed / revive** (`combat/downed`) — the 3-state alive→downed→dead chain (Apex/Helldivers). `createDownedState({ bleedoutSeconds, reviveSeconds?, reviveHealthFraction?, banner? })`: `down(id)` starts the bleedout, `tick(dt)` counts it down (→ `died`, optionally spawning a `banner`), `revive(id, dt)` accumulates an ally's hold time (→ `revived` with the health fraction the game restores), `finish(id)` executes a downed enemy, and `respawnFromBanner(id)` brings a banner-holder back at a beacon. It sits **in front of** the engine death resolution: on lethal damage call `down` instead of dying; on `died`/`bleedout` run the real `resolveDeath`. No banner ⇒ death is terminal.
+**Shrinking ring** (`session/ring`) — the battle-royale safe zone with out-of-bounds DoT. A catalog `RingConfig` is `{ center, phases: RingPhase[] }` where each phase is `{ startTime, shrinkDuration, fromRadius, toRadius, damagePerSecond, center? }` on the game clock. `ringSampleAt(config, t)` / `createRing(config).at(t)` returns the live `{ center, radius, damagePerSecond, shrinking }` (radius/center interpolate during each shrink window, hold between phases); `isOutside(t, pos)` / `distanceOutside(t, pos)` test a point, and `damageOutside(t, dt, positions)` returns per-entity `{ id, damage }` for everyone beyond the wall — feed those into `scene.entity.stats.delta`/`effect` each tick.
+**Extraction session** (`session/extraction`) — the raid-scoped "reach an extract and leave to bank what you carried" wrapper (Tarkov/DMZ/Helldivers), composed from the contested channel + `inventory/storageTier`. `createRaidSession({ extracts, insurance?, consolation? })`: `beginExtract(userId, extractId, team?)` opens a hold-to-leave channel, `tickExtract`/`damage` drive it, and on completion `resolveExtraction(userId, containers)` banks everything carried. `resolveDeath(userId, containers, now, rng?)` runs `partitionOnDeath` (banked kept, carried lost), schedules insured items through the built-in delivery queue (`claimDeliveries(now)` drains it on the clock), and yields the consolation loadout id. `playerSnapshot(userId)` feeds the extraction-timer HUD.
+**Persistence scopes** (`runtime/persistenceScope`) — the run-vs-meta split with explicit reset boundaries (Icarus mission wipe, Once Human season reset). `partitionScopes(state, { run })` splits a flat record into `{ meta, run }` by key; `resetRun` clears the run half while meta (talents/blueprints/account currency) survives; `clearRunFields(playerRow, runFields)` and `applyRunReset(profile, runFields, now)` do the same over `RuntimePlayerRow`/`PlayerProfileRecord`. `planScenarioReset({ gameId, serverId?, wipeChunks?, wipeServerSession?, resetPlayers?, runFields? })` normalizes a scenario/season reset that `HostPersistence.resetScenario?(reset)` applies — `@jgengine/sql` implements it (deletes the server's chunks + session, run-resets each profile in one transaction), keeping account meta intact.
+
+## Trade
+
+Catalog `trade` fields drive everything — no duplicate price lists.
+
+```ts
+ctx.game.trade.canBuy(itemId, shopId, count?)   // → reason | null
+ctx.game.trade.canSell(itemId, count?)
+ctx.game.trade.buy(itemId, count, { shop, inventoryId })   // charge → put, rolls back on failure
+ctx.game.trade.sell(itemId, count, { shop, inventoryId })
+ctx.game.trade.tradableAt(shopId, allItemIds)   // derive stock from catalogs
+```
+
+## Economy and unlocks
+
+```ts
+ctx.game.economy.balance(userId, currencyId) / grant(...) / charge(...)  // charge → { reason } | null
+ctx.game.unlocks.has(userId, id) / grant(userId, id) / list(userId) / tree(categoryId)
+```
+
+Catalog `requires: [unlockId]` gates validate at command time.
+
+## Crafting, tech tree & production
+
+Four **pure** primitives (no ctx, no renderer) for survival-crafting, tech-tree, factory, and farming games. All are catalog-first: recipes, tech nodes, production rates, and crop stages are game **data** you feed the primitive — the engine owns the graph math, the timers ride `ctx.time` (game-seconds), never wall-clock.
+
+**Recipe graph** — `@jgengine/core/crafting/recipe`. A `RecipeDef` is `{ id, inputs: RecipeItem[], outputs: RecipeItem[], seconds?, station?, stationRange?, requires? }` — inputs + optional required-workstation-in-range + time → outputs. `craft(state, layout, traits, recipe, context)` consumes inputs and produces outputs on an `InventoryState` **atomically** (rejects `missing-inputs` / `no-station` / `locked` / `no-output-space` without mutating on failure); `canCraft(...)` is the dry-run. `context = { origin?, stations?, unlocked? }`: `stationSatisfied` checks a matching placed workstation (`{ catalogId, position }`) within `stationRange` of `origin`, and `requires` gates on `unlocked(id)` (wire it to `ctx.game.unlocks.has` or the tech tree). `createRecipeGraph(defs)` indexes recipes by `producing(itemId)` / `using(itemId)` / `category`. Long crafts schedule completion with `ctx.time.after(craftSeconds(recipe), …)`.
+
+**Tech tree** — `@jgengine/core/economy/techTree`. **Generalizes flat `unlocks`, does not duplicate it**: a `TechNodeDef extends UnlockDef` adds `requires` (prerequisite node/unlock ids), an optional `recipe` payload, and `grants` (extra flat unlock ids). A node id **is** an unlock id, so flat unlocks are just tech nodes with no `requires`. `createTechTree(defs)` wraps `createUnlocks` internally and gates grants on prerequisites: `unlock(userId, id)` refuses until every `requires` is met, `available(userId)` is the reachable frontier, `recipes(userId)` lists the recipe payloads a player has unlocked (feed them to the recipe graph). `tree(categoryId)` and per-user `has`/`list`/`snapshot`/`hydrate` mirror `unlocks`.
+
+**Production building** — `@jgengine/core/crafting/production`. `productionBuilding({ id, inputs, outputs, rate, power?, bufferMultiplier? })` — a placed building that consumes buffered inputs and emits outputs on a timer. `rate` is production **cycles per game-second**; `tickProduction(def, state, { dt, powered? })` advances continuously through `dt` (so pause/fast-forward apply for free) and completes as many cycles as the buffer allows. `feedProduction` / `drainOutput` move items in and out of the internal buffers (a puller/conveyor). `advanceTransport(path, items, dt)` slides items along a belt and splits off `delivered`. `resolvePowerGrid(supply, consumers)` powers demands greedily until supply is exhausted — gate a building's tick on `powered`.
+
+**Farming** — `@jgengine/core/crafting/crop`. `CropTileState` is a soil state machine (`untilled` → `tilled` → planted); `tillTile` / `plantCrop` / `waterTile` are pure tile transitions and `advanceCropDay(def, tile)` runs the **day tick** — a `CropDef { stages, regrowDays?, needsDailyWater?, harvest? }` advances a growth stage per watered day and sets `harvestable`; `harvestCrop` yields and either clears the tile or resets a regrow crop. `applyToolToTiles(tiles, center, pattern, apply)` applies a tool across a tile pattern under the cursor — `singleTile()`, `squarePattern(r)`, `diamondPattern(r)`, `rectPattern(w,d)` (watering-can / hoe AoE). `createCropField(catalog)` is the stateful wrapper over a tile grid (`till`/`plant`/`water`/`harvest`/`advanceDay`); drive `advanceDay()` off the calendar day rolling over — `createDayTicker(startDay)` reports how many days `ctx.time.calendar().day` has crossed.
+
+## `applyLoadout`
+
+```ts
+ctx.player.loadout.register(loadouts)                    // onInit
+ctx.player.applyLoadout(userId, loadoutId)               // → null | { reason }
+```
+
+`LoadoutDef = { inventories?: { hotbar: [{ item, count, slot? }], … }, stats?, economy?, unlocks? }`. Application is **all-or-nothing**: every inventory put dry-runs first; any rejection applies nothing. Starter kits gate on `ctx.player.isNew`; class/respawn kits run from commands. Never scatter raw `put`/`grant` calls for a kit.
+
+## Quests
+
+```ts
+ctx.game.quest.register(catalog)                          // onInit
+canAccept / accept / abandon / canTurnIn / turnIn / grant / revoke
+progress(userId, questId, objectiveId, delta)
+list(userId)  /  has(questId)
+bind("entity.died")        // kill objectives match objective.target === catalogId
+bind("inventory.added")    // collect objectives match objective.item
+```
+
+Catalog: `{ id, title, giver?, turnIn?, requires?, objectives: [{ id, kind, target?/item?, count, partyShare? }], rewards? }`. `requires` is satisfied by a completed quest of that id or an unlock. `turnIn` applies declarative `QuestRewards` — `{ xp?: { amount }, economy?: Record<string, number>, items?: { item, count, inventory }[], unlocks?: string[], quests?: string[] }` — note `xp` takes an `{ amount }` wrapper (applied via `stats.delta` + your level-up loop) and each reward `item` names the `inventory` it fills; chained `quests` are auto-offered if acceptable. Events: `quest.accepted` / `quest.updated` / `quest.completed`. `partyShare: { radius, credit: "all" | "tagger" }` extends kill credit to nearby party members.
+
+## Social
+
+```ts
+ctx.game.social.friends.canRequest / request / accept / decline / remove / block / list / requestsFor   // persisted
+ctx.game.social.party.register({ maxMembers })   // then canInvite / invite / accept / decline / kick / leave / promote / list / membersOf / invitesFor
+ctx.game.social.presence.get(userId)             // { online, serverId?, zoneId?, instanceId? }
+ctx.game.social.emotes.play(fromUserId, emoteId, radius?)   // → { from, emoteId, at, recipients } | { reason }
+ctx.game.social.worldInvites.invite(fromUserId, toUserId, { serverId, joinCode? })   // then canInvite / accept / decline / listFor
+```
+
+Party is ephemeral session state (invites expire; leader leaving promotes the next member). Events: `social.friend.added`, `social.party.joined`, `social.party.left`.
+
+**World invites** bridge friends and `multiplayer/matchmaking`: an invite carries the `{ serverId, joinCode? }` of the session you're in (the same fields as a `SessionListing`); `accept(userId, inviteId)` → `{ target }` is the join target you hand to your backend's `joinServer`/`joinByCode` — the invite never joins anything itself. Invites are ephemeral like party invites (TTL via `SocialDeps.worldInviteTtlMs`, default 60s; blocked users can't invite either direction). Events: `social.world.invited`, `social.world.accepted`. React: `useWorldInvites()` lists pending invites for the local player.
+
+`emotes.play` reuses `scene.entity.inRadius` to find nearby **player**-role entities (default radius 20) and emits `emote.played` — never build a parallel proximity broadcast. Emote ids are game-defined strings (no registration, same convention as effect ids). Bind it into the existing feed primitive for a HUD feed: `ctx.game.feed.bind("emote.played")` + `useFeed({ action: "emote.played" })` — no dedicated emote hook exists or is needed.
+
+## Chat
+
+```ts
+ctx.game.chat.send(fromUserId, channelId, body)      // → { message, recipients } | { reason }
+ctx.game.chat.whisper(fromUserId, toUserId, body)    // stable per-pair channel "whisper:<a>:<b>"
+ctx.game.chat.history(channelId, { limit?, viewerUserId? })   // viewer filter drops blocked senders
+ctx.game.chat.register({ id, kind, radius?, historyLimit?, rateLimit? })   // custom channels
+ctx.game.chat.channels() / snapshot() / hydrate(data)
+```
+
+Built-in channels: `global` (everyone), `party` (reuses `social.party.membersOf`; rejects "not in a party"), `proximity` (reuses the same spatial/entity seam as emotes, default radius 20, **player**-role entities only). `kind` picks the recipient resolution; custom channels pick one of the three kinds. Sends are trimmed, capped (500 chars), and rate-limited per user per channel (default 10/10s, sliding window — `createChatRateLimiter` is the reusable pure primitive). Mute rides social's blocked set: blocked pairs can't whisper, and blocked senders are dropped from party/proximity recipients and from `history` when `viewerUserId` is passed. Every send emits `chat.message` (recipients omitted = broadcast). History is a bounded ring per channel (default 100) with `snapshot`/`hydrate` like `Friends`.
+
+**Remote chat seam** (`multiplayer/chatContract`): `ChatTransport` is the hook-shaped contract (`useMessages(channelId | "skip")` / `useActions()`, identity-stable like `PresenceTransport`); `ChatSync` is the callback shape for backends that can't host React hooks. Bindings: ws — `createWsBackend(...).chatSync` / `.chatSyncFor(serverId)` over `chatSend` frames + a `chat` update channel (host relays per-channel rings, validates length + rate limit); Convex — `@jgengine/convex/convexChatTransport` `createConvexChatTransport({ messages, sendMessage })` (one live query + one mutation); local/dev — `createLocalChatTransport()`. React lifts a `ChatSync` via `chatTransportFromSync`.
+
+## Cosmetic loadout
+
+```ts
+ctx.player.cosmetics.register(defs)                       // onInit — Record<loadoutId, { slots: Record<slot, cosmeticId> }>
+ctx.player.cosmetics.apply(userId, loadoutId)              // merges the preset's slots
+ctx.player.cosmetics.equip(userId, slot, cosmeticId | null)  // set/clear one slot directly
+ctx.player.cosmetics.get(userId)                          // Record<slot, cosmeticId>
+```
+
+A per-player appearance layer distinct from `applyLoadout` (which grants inventory/stats/economy/unlocks) — cosmetics never touch gameplay state, only equipped slot ids for your renderer to read. Emits `cosmetics.changed`.
+
+## Possession
+
+```ts
+ctx.player.possession.own(userId, entityId) / disown / owns / listOwned(userId)
+ctx.player.possession.active(userId)                      // → entityId, defaults to userId itself
+ctx.player.possession.possess(userId, entityId)            // → null | { reason } — must be owned + spawned
+```
+
+A player can own N scene entities (party members, vehicles, a possessed creature) and control exactly one at a time — distinct from `game.social.party`, which is a social grouping, not a control model. `possess` flips the previous/next entity's scene `EntityRole` between `"player"`/`"npc"` and emits `possession.swapped`; `@jgengine/shell`'s `GamePlayerShell` reads `active(userId)` every frame to rebind WASD movement, tab-targeting, hotbar `from`, and the camera rig's `followEntityId` to whichever entity is currently controlled — a game never wires this rebind itself.
+
+## Form / shapeshift
+
+```ts
+ctx.scene.entity.form.register(defs)                              // onInit — FormDef[] = { id, movement?, abilities?, model? }
+ctx.scene.entity.form.shapeshift(instanceId, formId, durationSeconds?)   // → null | { reason }
+ctx.scene.entity.form.active(instanceId)                          // → formId | null
+ctx.scene.entity.form.abilities(instanceId)                       // → readonly string[] | null
+ctx.scene.entity.form.revert(instanceId)                          // early revert
+```
+
+A `form` bundles movement params + an ability-id list + a mesh into one swappable unit (shapeshift/transformation — V Rising bear/wolf/bat, Wukong's boss transformation). `model` reuses the entity's catalog `name` (the same key `entityModels`/`entitySprites` resolve against), so the mesh swap rides the existing render lookup — no parallel mesh field. `durationSeconds` is **game time**: it schedules the automatic revert through `ctx.time.after`, so it obeys pause and fast-forward like everything else on the clock. Emits `form.changed`.
+
+## Events, feed, leaderboard
+
+```ts
+ctx.game.events.on(name, handler)      // register in onInit; typed GameEventMap
+ctx.game.feed.bind(action)             // pipe an engine event into a ring buffer (default 20)
+ctx.game.feed.push(action, entry)      // manual channels (chat, crafting)
+ctx.game.feed.recent(action, { limit? })
+ctx.game.leaderboard.track({ stat, scope: "global" | "server" | "profile" })   // onInit
+ctx.game.leaderboard.increment(userId, stat, { scope, by? }) / getTop / getProfile
+```
+
+`ctx.game.commands.define(name, { validate?(ctx, input), apply(ctx, input) })` registers a verb (`has`/`names`/`run` round it out); `run(name, input)` returns `{ status: "applied", state } | { status: "rejected", reason } | { status: "unknown-command" }`. `apply` may either **return** the next state (the classic reducer shape) or mutate `ctx` in place and return **nothing** — `run` keeps the current `ctx` as `state` when `apply` returns `void`, so a handler that only calls other `ctx` methods (spawn, effect, loot.grantToPlayer, …) doesn't need a pointless `return ctx`. **Event handlers use `ctx` directly** the same way (side effects: leaderboard, economy, scheduling) and never reassign state. One feed primitive for kill feeds, loot logs, quest updates — no per-domain feed hooks.
+
+## `ctx.game.store` — reactive game state
+
+```ts
+ctx.game.store.set("health", 100)      // any key, any value type
+ctx.game.store.get("health")           // T | undefined
+ctx.game.store.has("health")
+ctx.game.store.delete("health")
+ctx.game.store.subscribe(listener)     // change-signal fires on set/delete
+ctx.game.store.mapSnapshot() / arraySnapshot()
+```
+
+A reactive per-game keyed store (`ObservableKeyedStore<unknown>`) attached to `GameContext` — reach for it instead of a module-level singleton store for ad-hoc reactive game state (turn trackers, deck UIs, anything that doesn't already have a `ctx` surface). `set`/`delete` bump `ctx.version()` and notify `ctx.subscribe` listeners; `get`/`has` are plain reads. Unlike a per-slot handle, there is no `define`/seed step — a key simply doesn't exist until the first `set`.
+
+## `ctx.game.cards` / `ctx.game.turn` — lazily-created piles and turn loops
+
+`ctx.game.cards.pile(id, config?)` and `ctx.game.turn.loop(id, config?)` lazily create (config required on first call) or return the existing notify-wrapped `CardPile`/`TurnLoop` for `id` — call with just the id after the first `onInit` seed to fetch the same instance; every mutating method is wrapped so it bumps `ctx.version()`/notifies `ctx.subscribe` automatically, same as every other `ctx` surface. This replaces manually constructing `createCardPile`/`createTurnLoop` and wiring notification yourself.
+
+## Movement, pose, input
+
+```ts
+ctx.player.movement.getPose(id) / setPose(id, "crouch")   // validates catalog movement.poses
+ctx.player.movement.getAim(id) / setAim(id, "ads")        // ADS = aim state + zoom modifier, not a pose
+```
+
+Poses (`standing/crouch/prone/running`) change the collision capsule (`POSE_HITBOX`); aim pairs with a `player.stats` zoom modifier on `"reticle"`. Game code reads action names only (`isDown("aim")`, `wasPressed("interact")`) — hold vs toggle is resolved by the binding config, never by raw key branches.
+
+### `ctx.input` — polling the raw controls
+
+`ctx.input` (`@jgengine/core/runtime/inputSnapshot`) is a per-frame held-action snapshot for `onTick` to poll, distinct from the command-dispatch path (bound actions still run commands the normal way): `publish(held: readonly string[])` (the shell calls this once per frame before `onTick`), `isDown(action)`, `held()` for the full list. Publishing never bumps `ctx.version()` — it's a poll surface, not reactive state.
+
+**`repeatMs`** — bind an action as `{ hold: [...], repeatMs: 150 }` (`input/actionBindings`) and the shell fires its command on the down edge, then again every `repeatMs` while held, resetting on release (hotbar-style repeat-fire without a per-game timer).
+
+**Aim on generic commands** — every command resolved from a bound action now runs with `{ yaw, pitch, aim: { yaw, pitch } }` in its payload, so a handler can read the camera-relative aim without going through `pointer.worldHit()`.
+
+### Controller kinematics — movement config, physics tuning, respawn
+
+`PlayableGame.movement` (`PlayerMovementConfig`) tunes the shell's built-in walk controller (never touch `PhysicsWorld` for ordinary player movement):
+
+```ts
+movement: {
+  mode?: "free" | "axis" | "grid";           // "free" (default) camera-relative; "axis" locks travel to one world axis; "grid" snaps each committed position to cell centers
+  axis?: "x" | "z";                          // world axis for mode "axis". Default "x"
+  cellSize?: number;                         // cell size for mode "grid". Default 1
+  collideObjects?: boolean;                  // collide the walking player against placed scene objects (unit-box AABBs) even without collision.voxel
+  beforeCommit?: (frame: MovementCommitFrame) => readonly [number, number, number] | undefined | void;   // intercepts each frame's resolved position before the pose commits; return a replacement to constrain/redirect the step
+}
+```
+
+`nav/navConstrain`'s `constrainToNavGrid(grid, { y? })` is a standalone walkable-pass-through + wall-sliding helper over a `nav/navGrid`; its `(proposed, entity)` shape doesn't match `beforeCommit`'s `(frame) => [x,y,z]` signature directly, so wire it in with a small adapter closure rather than passing it straight through.
+
+`defineGame({ physics: { gravity, jumpVelocity } })` drives the kinematics controller directly: `gravity` (signed, e.g. `-24`) and `jumpVelocity` override the built-in tuning; omit either to keep the defaults. This is the one global exception to "never player tuning in `defineGame`" — it configures the shared controller, not a catalog entry. It is still **distinct** from `physics/physicsWorld`'s standalone rigid-body sim (see below) — `defineGame.physics` never touches that sim.
+
+**Vertical motion intents** — `ctx.player.motion` (`@jgengine/core/runtime/motionIntents`): `impulse(vy)` adds to the vertical velocity the shell's controller is about to integrate, `setVerticalVelocity(vy)` replaces it outright, `setY(y)` wins over physics for that frame. The shell calls `takePending()` once per frame, before integrating gravity, to drain what accumulated; this is not reactive state (jump pads, launch abilities, bounce pads).
+
+**`collision: { voxel: true }` — object lattice as solids.** When set, the shell's local player uses a voxel body whose `isSolid(x,y,z)` is rebuilt from `ctx.scene.object.list()` as exact `` `${x},${y},${z}` `` keys (integer cell queries). Integer-placed objects are walkable/blocking; fractional-coord objects decorate without colliding. Removing an object opens a real trapdoor under gravity — do not fake the fall with `setPose`. `visual.scale` does not shrink the collider (always a unit cell). The voxel body is created once; prefer `motion.setY` / `impulse` for vertical relocation — full XY teleport of the local voxel body is not supported. Solid cache rebuilds when object **count** changes. Recipe: `jgengine-newgame` → voxel trapdoor board.
+
+**Respawn** — `ctx.scene.entity.spawnPoseOf(id)` reads the spawn pose, `resetToSpawn(id)` teleports back to it with zero velocity, `resetAllToSpawn(filter?)` does it for every entity matching an optional filter and returns the count (round resets, out-of-bounds recovery).
+
+## Touch & mobile
+
+Every game is touch-playable with zero per-game input code. On a coarse-pointer device the shell derives a `TouchScheme` from the game's `input` bindings (`deriveTouchScheme`, `@jgengine/core/input/touchScheme`): a virtual joystick binds whichever of `moveForward`/`moveBack`/`moveLeft`/`moveRight` (or `turnLeft`/`turnRight`) are bound, on-screen buttons cover the remaining actions, and drag-to-look mounts automatically for `first`-person camera rigs. Touch controls feed synthetic `touch:<action>` codes into the same `ActionStateTracker` the keyboard uses — game code reads `isDown`/`wasPressed` and never branches on input source.
+
+Refine the derived scheme with the `touch` field of `defineGame({...})` (`TouchControlsConfig`, all optional):
+
+```ts
+touch: {
+  gestures: {
+    tap: "rotateCw",
+    swipeUp: "hold",
+    swipeDown: "hardDrop",
+    drag: { left: "shiftLeft", right: "shiftRight" },
+  },
+  buttons: [
+    { action: "rotateCcw", label: "CCW" },
+    { action: "softDrop", label: "Soft" },
+  ],
+},
+```
+
+- **`gestures`** — bind `tap` / `swipeUp` / `swipeDown` / `swipeLeft` / `swipeRight` / `drag` (`{ left?, right?, up?, down?, stepPx? }`, repeats its action every `stepPx` of travel) on the play surface. An action consumed by a gesture is removed from the derived button set.
+- **`buttons`** — curate the on-screen cluster (order preserved; bare string or `{ action, label?, icon? }`); omit to auto-derive one button per remaining bound action. Buttons render a glyph, not text: `iconForAction` (`@jgengine/react/gameIcons`) resolves the action name to a `GameIconName` (`jump`, `sprint`, `rotateCw`, `hardDrop`, `swap`, `hand`, `restart`, arrows, …), the `label` becomes the `aria-label`; set `icon: "<GameIconName>"` to pick one explicitly or `icon: false` to force the text label.
+- **`hidden`** — actions to drop from the derived buttons without gesture-binding them.
+- **`movement: false`** — suppress the virtual joystick even when movement actions are bound.
+- **`look` / `lookSensitivity`** — drag-to-look on the play surface; defaults to `true` for `first`-person camera rigs, `0.005` radians/px.
+- **`touch: false`** — opt out entirely when the game's own DOM UI is already touch-native.
+
+`useDisplayProfile()` (`@jgengine/react/display`) reports `{ coarsePointer, compact, portrait }` — live media-query state, SSR-safe — for adaptive HUD layout; see the mobile/touch rules in [`reference/ui-react.md`](reference/ui-react.md).
+
+## Interaction — `proximityPrompt`
+
+One primitive for all float UI: `{ radius, display, invoke }` where `display` is `{ kind: "keybind", actionId }` | `{ kind: "gauge", gaugeId }` | `{ kind: "label", text }` and `invoke` is `{ command, args? }` or null (display-only). `talkable: "dialogue_id"` on an entity expands to a talk prompt. Engine picks the nearest prompt in radius (priority tie-break). Never build per-game hint resolver chains.
+
+## Pointer-driven input and navigation
+The **pointer is a service, not per-game glue**. Opt in with `camera` plus a `pointer` config in `defineGame({...})`; the shell casts the cursor into the world and dispatches commands you define — verbs stay commands, catalogs stay data.
+- **`pointer.worldHit()` (shell service).** The shell raycasts the cursor to `{ point, normal, entity, object }` (a renderer-free `PointerHit` from `@jgengine/core/input/pointer`) — entity/object are the topmost instance ids under the cursor, else `null`, with a ground-plane fallback for open terrain. Consume it renderer-free: `aimToPoint(origin, point)` builds an `Aim` for `item.use`/projectiles (ground-target skillshots, twin-stick), `groundOf(hit)` drops to `[x, z]` for routing. `pointer.worldHitCenter()` is the same raycast pinned to the viewport center instead of the live cursor — the reticle-aim query a locked/hidden-cursor rig (first-person, gamepad) needs when there is no cursor position to read.
+- **The `pointer` field of `defineGame({...})`** (all optional): `moveCommand` (left-click ground → `run(cmd, { point, entity, object })`, click-to-move), `select` (left-drag marquee + single-click box-select of entities), `orderCommand` (right-click ground → `run(cmd, { selection, point })`, issue a command to the selection), `contextMenu` (right-click an entity/object → its catalog `verbs` menu), `secondaryCommand` (right-click ground/entity/object → `run(cmd, { point, entity, object, aim })` when neither `orderCommand` nor `contextMenu` claims the click — a generic right-click verb for games with no selection/RTS model), `aim` (route the primary ability's aim to the cursor), `grabWorldItems` (left-click a `worldItem` within pickup radius → engine-owned `ctx.scene.worldItem.pickup`, no game command). Enabling `select`/`moveCommand` frees the left button for verbs; orbit moves to middle-drag.
+- **`createDragCapture({ maxPull?, grabRadius? })`** (`@jgengine/core/input/pointer`) — a renderer-agnostic slingshot/drawback state machine: `begin(origin, at)` starts a pull (rejected outside `grabRadius`), `update(at)` tracks the cursor, `release()` returns the final `DragState { origin, current, pull, magnitude, fraction }` (pull clamped to `maxPull`), `cancel()` aborts. Angry Birds-style slingshots, bow drawback, throwable wind-up — pair with `aimToPoint` to fire.
+- **Selection math** (`scene/selection`) is pure and testable: `createSelectionSet()`, `screenRect`/`selectWithinRect`/`isMarquee` over projected screen points.
+- **Context menu** (`interaction/contextMenu`): a catalog entity/object carries `verbs: contextVerb(label, command, args?)[]`; the shell builds the menu with `buildContextMenu` and dispatches the chosen command via `contextVerbInput` (verb args + `target`/`point`, so one handler can walk-then-act).
+- **Navmesh + A\*** (`nav/navGrid`): `createNavGrid({ bounds, cellSize, diagonal? })` → mark obstacles with `blockAabb`/`setWalkable`, or `populateNavGridFromEnvironment(grid, world)` to block every generated building's footprint on an `environment()` world's `structures` in one call (returns the count blocked) instead of hand-walking the district. `findPath(grid, from, to, { clearance?, smooth?, stepCost? })` returns a string-pulled `[x, z]` polyline (blocked start/goal snap to the nearest walkable cell) feeding **both click-to-move and AI routing**; `stepCost?(from, to)` multiplies the base cost of a grid step — `slopeStepCost(terrainField, weight?)` is the ready-made factory that penalizes steep terrain (routes around cliffs instead of over them). Renderer-free — AI and gameplay consume it without the shell.
+- **`pathFollow`** (`nav/pathFollow`): the lighter authored-polyline mover for tower-defense creeps that needs no navmesh — `createPathFollow({ waypoints, speed, loop? })` + pure `advancePathFollow(config, state, dt)` (crosses multiple waypoints per tick, reports `done`/`heading`/`distanceTravelled`). Feed it a navmesh route with `pathFromNav(route, elevation, offset?)` and the same follower drives click-to-move — `elevation` is either a fixed `y` or a `{ sampleHeight(x, z) }` field (any `TerrainField` qualifies), so a route across relief rides the ground instead of a flat plane.
+- **`constrainToNavGrid(grid, { y? })`** (`nav/navConstrain`) is a standalone walkable-pass-through + wall-slide helper: it passes through walkable moves, slides along walls at the navmesh boundary instead of stopping dead, and optionally remaps `y` to the grid. Its `(proposed, entity)` shape doesn't match `PlayerMovementConfig.beforeCommit`'s `(frame) => [x,y,z]` signature, so wire it in with a small adapter closure (see "Controller kinematics" above) to wall a player/AI to the same navmesh `findPath` already routes against.
+## AI — director, threat, jobs, crowds (`ai/*`)
+Renderer-free AI over the same navmesh (`findPath`/`pathFollow`) gameplay already uses. Everything ticks on **game-time `dt`** (the `ctx.time` simClock delta), so it obeys pause and fast-forward for free. Manifests, patrol routes, job definitions, threat weights, and POIs are **game data** — the primitives own the loop, the catalog owns the content.
+- **Spawn director** (`ai/spawnDirector`) — budgets and escalates spawns for wave shooters and difficulty directors (Brotato, Bloons TD 6, Risk of Rain 2, Helldivers 2, Deep Rock Galactic). `createSpawnDirectorState(config)` then pure `advanceSpawnDirector(config, state, dt, { alive, players? })` → `{ state, spawns: SpawnRequest[] }`. Each `WaveManifest` grants a `budget` spent on affordable weighted `SpawnEntry`s (`cost`/`weight`/`minWave`), capped by `maxAlive`; `duration` auto-advances waves (or call `advanceWave` on "wave cleared"). Budget also trickles via `budgetPerSecond`, ramps a difficulty curve with `escalationPerSecond` (grows with sim-time), scales with `playerBudgetPerSecond`, and surges on `raiseAlert(state, amount)` decaying over time (bug-breach/dropship escalation). Seeded (`seed`) so ticks are deterministic. `pickSpawnPoint(points, players, { roll, bias })` biases placement toward (or away from) players. `config.spawnPoints?: NavPoint[]` lets the director pick a point itself: each `SpawnRequest` then also carries `point` (the chosen `[x, z]`, biased by `config.spawnPointBias`) and `laneId` (the point's index into `spawnPoints`) — feed multiple named lanes/portals and read `laneId` back to route the spawned entity down its lane instead of correlating positions by hand.
+- **Threat table** (`ai/threat`) — MMO/extraction aggro (Escape from Tarkov, WoW-style tanking). `createThreatTable({ decayPerSecond?, max?, forgetBelow? })`: `add(source, amount)` accumulates, `decay(dt)` bleeds off per game-second and forgets emptied sources, `highest({ current?, stickiness? })` returns the top-threat source to feed `scene/targeting` — `stickiness` (e.g. 1.1) keeps the current target until another exceeds it by that factor, so aggro doesn't jitter. `ranked()` for a threat meter.
+- **Patrol** (`scene/behaviors`) — `patrol({ waypoints, speed, loop? })` is a `BehaviorDescriptor` (a route is data) that layers a fixed beat on top of `wander`; drive it with `createPathFollow`/`advancePathFollow` (lane creeps, scav patrols in Deadlock/Tarkov). Route waypoints between guard posts with `findPath`.
+- **Job board** (`ai/jobBoard`) — colony/companion task assignment (Palworld stations, Schedule I employees, Sons of the Forest directives). `createJobBoard()`: `post(job)` a `JobDef` (`station`, `work` seconds, `priority`, `arriveRadius`, `repeat`), `claim(worker)` auto-pulls the highest-priority queued job or `assign(worker, jobId)` for a player order (steals it from its holder), `release` requeues. Per tick `advance(worker, dt, { distanceToStation })` runs the state machine `travelling → working → done` (path to `station(worker)` via `findPath`, occupy, run the loop), returning a `JobReport` on completion; `repeat` jobs re-run as a production loop and report each cycle.
+- **Crowd flow** (`ai/crowd`) — many agents routing to their own points of interest with congestion (Two Point Museum corridors, Dave the Diver seating). `computeFlowField(grid, goals, { clearance?, congestion? })` runs Dijkstra from the goals over the walkable grid → `direction(point)`/`next(point)` steer any agent toward the nearest goal (no per-agent A*). `createCrowdField(grid)` tracks per-cell occupancy (`enter`/`leave`/`count`); pass `crowd.penalty(weight)` as the field's `congestion` to reroute flow around crowded cells each tick. `selectPoi(pois, from, { roll, occupancy?, distanceBias?, distance? })` weights a POI by appeal and proximity, skips ones at `capacity`, and accepts a `distance` override (e.g. `findPath` length) to choose over the navmesh, not line-of-sight.
+## Map, fog of war & ping
+Minimap/world-map/fog/compass state is renderer-free core (`world/*`), the top-down terrain image bakes in the shell, and the minimap/compass/world-map are react components. Ping rides the existing party + feed — it is not a new channel.
+- **Markers** (`world/markers`): `createMarkerSet()` is a reactive keyed set of `MapMarker { id, kind, position, label?, owner?, expiresAt?, meta? }` — `add`/`remove`/`get`/`list`/`query({ kind, owner, near, radius })`/`prune(now)`/`subscribe`. `kind` is a game-owned catalog string; `DEFAULT_MARKER_KINDS` (objective/enemy/loot/location/danger/ping/player/ally) supplies colors + glyphs the react map reads (override with your own `MarkerKindStyle` palette). Objective/entity/loot markers all live here.
+- **Fog of war** (`world/fog`): `createFogField({ bounds, cellSize })` is reveal-on-event — `reveal(x, z, radius?)` (a dig/act), `revealAlong(from, to, radius?)` (a walked trail); once a cell is revealed it stays revealed. `isRevealed`/`fraction`/`cells()` (stable snapshot for rendering)/`reset`/`subscribe`.
+- **Minimap math** (`world/minimap`): pure projection + bearings — `projectToMinimap(worldPoint, { center, worldRadius, size, rotate? })` → pixel `{ x, y, inside, distance }` (north = −Z maps up), `clampToMinimapEdge` for off-map markers, `compassBearing(from, to)`/`headingToBearing(yaw)`/`bearingToCardinal`/`relativeBearing` for the compass strip.
+- **Ping** (`game/ping`): `classifyPing(hit, { roleOf, categoryOf }, options?)` turns a G1 `pointer.worldHit()` `PointerHit` into a category (hostile entity → `enemy`, tagged object → its catalog category, open ground/ally → `location`). `createPingSystem({ markers, feed, party?, ttlMs?, classify, classifyOptions? })` composes classify + broadcast: `ping(from, hit, category?)` classifies, drops a categorized marker, and pushes the `PingPayload` to the party feed under `PING_FEED_ACTION` (`"party.ping"`) — the shell's feed bridge fans it to the squad. `DEFAULT_PING_CATEGORIES` is the enemy/loot/location/danger wheel. Enable the verb with the `pointer.pingCommand` field of `defineGame({...})`: the shell binds the `ping` input action → `worldHit()` → runs your command with `{ point, entity, object, normal }`.
+- **Shell render** (`@jgengine/shell/map`): `bakeTerrainMap(field, bounds, { resolution? })` renders a `TerrainField`/`RegionField` to a top-down PNG data-URL for the map background; `MapMarkerBeacons({ markers })` renders world-space beacons (the visible side of a ping) — wire via the `WorldOverlay` field of `defineGame({...})`. See the `extraction-map` demo game.
+## Sensors, vision & observer tools (`sensor/`)
+Pure `@jgengine/core/sensor/*` primitives for querying and surfacing world state the player can't normally see or reach through the standard occlusion/proximity rules — reveal vision, hidden-state sensors, photo-mode framing, and session replay. Shell renderers/HUD pieces live in `@jgengine/shell/vision` and `@jgengine/shell/replay`.
+| Primitive | Answers |
+|-----------|---------|
+| `createRevealQuery({ resolvePosition, resolveTags, candidates })` → `RevealQuery` | `inRadius(center, radius, tags)` — occlusion-ignoring tagged-entity radius query (Dark Sight / detective-vision reveal, #115). `inRadius` already never checks occlusion (only combat's AoE `effect()` layers a LoS filter on top of it) — this is that same query shaped for a vision readout: scoped to catalog-declared tags, sorted nearest-first |
+| `probeHiddenState(origin, sources, { range, variableId, falloff? })` / `probeHiddenStateAll(...)` → `SensorReading \| null` | A sensor verb: reads a hidden zone/entity state variable (EMF/thermometer/geiger, #116) in range, strongest reading first; `strength` falls off linearly with distance by default |
+| `projectToView(camera, point)` → `FrustumProjection` | Pure camera-frustum projection (no three.js) — `inView`, `screenX/screenY` (-1..1), `distance` |
+| `framingScore(projection, config?)` → `number` | 0..1 framing quality from screen-center placement + distance-to-ideal (photo-mode "is this subject framed", #117) |
+| `createFrustumSensor(config?)` → `FrustumSensor` | `tick(camera, targets, dt)` — per-target in-view + framing + `dwellSeconds` (resets the instant a target leaves frame); a view-frustum sensor on a held camera object (Content Warning-style monster-filming scoring) |
+| `createRecordingBuffer(options?)` → `RecordingBuffer<T>` | `append(t, data)` / `seek(t)` / `range(fromT, toT)` — a session-recording buffer for replay/photo mode/kill-cam (#120), keyed on game-time so pause/fast-forward scrub consistently |
+| `colorDistance(a, b)` / `concealmentScore(entityColors, backgroundColors)` / `createConcealmentSensor(config?)` → `ConcealmentSensor` | Camouflage/blend-in scoring — how well an entity's palette matches its surroundings (hide-and-seek, stealth camo checks) against a `threshold` |
+| `createFreezeMonitor(config?)` → `FreezeMonitor` | Detects a tracked subject moving past a tolerance speed during a "freeze" window (red-light-green-light, statue games) and reports `FreezeViolation`s |
+Shell wiring: `@jgengine/shell/vision/RevealVision` (`RevealHighlights` — depth-test-disabled 3D highlight meshes for tagged entities in radius, meant for `WorldOverlay`; `RevealScreenTint` — full-screen CSS tint for "vision mode is on", meant for `GameUI`), `@jgengine/shell/vision/HiddenStateProbeHud` (`SensorReadoutMeter` — needle-strength HUD readout), `@jgengine/shell/vision/FrustumSensorHud` (`FrustumSensorReadout` — drives the sensor off the live render camera via `useThree`/`useFrame`, portals its HUD through drei's `Html fullscreen`), `@jgengine/shell/replay/useSessionRecorder` (records an entity's pose into a `RecordingBuffer` every frame; drive an observer-cam ghost, scrubber, or kill-cam export from it). The detached spectator/photo cam itself is the `observer` camera rig (see Camera rigs above) — bind it to any entity or fixed point.
+
+## World features
+
+Renderer-free world surface — query primitives, environment fields + weather + realm composition, survival meters/moodles, interactive building & terraform, the optional headless physics world, vehicles/mounts/racing, and spawn placement. Full surface: **[reference/world.md](reference/world.md)**.
+
+## Turn-based & tactics (renderer-free)
+
+Pure-`core` primitives for turn-based, grid-tactics, and card games — every one is a stateful factory with matching pure math, and every stateful piece exposes `capture()`/`restore()` so it plugs straight into the snapshot store. Overlays and tile art are the shell's/game's job; these ship the logic.
+
+- **`turn/turnLoop` — `createTurnLoop(config)`.** An initiative machine over an ordered participant list with optional `phases` and per-turn action-economy `pools`. `advanceTurn()` walks the order (round++ on wrap) and **resets the entering participant's pools**; `advancePhase()` steps phases then rolls into the next turn. Pools are catalog data (`{ id, max, start? }`) — a single Slay-the-Spire energy pool or BG3's Action/Bonus/Movement/Reaction set, spent independently via `spend/canSpend/gain/refill`. `setOrder`/`addParticipant`/`removeParticipant` re-roll initiative without losing the active pointer. `config.onTurnStart?(participantId)`/`onTurnEnd?(participantId)` fire on every `advanceTurn()` transition (start also fires once for the initial participant at construction) — hang status-effect ticks, "your turn" banners, or AI-turn kickoff here instead of diffing `state()` between ticks yourself. `ctx.game.turn.loop(id, config?)` is the runtime-wired accessor: lazily creates (config required the first call) or returns the existing notify-wrapped loop for `id`, so a HUD bound to `ctx.subscribe` re-renders on every turn/phase/pool change with no separate store to wire.
+- **`turn/commit` — `createCommitController({ mode })`**, also hosted at `turnLoop.commit`. Three commit modes: `immediate` (submit resolves now), `simultaneous` (sealed hidden submissions → `reveal()` once `allReady()`, deterministic order — Marvel Snap), and `rewind` (visible `pending()` → `rewind()` to discard or `commit()` to finalize).
+- **`turn/intent` — `createIntentBoard()`.** A minimal per-participant "what will you do" board, lighter than a full commit round: `declare(participantId, { kind, magnitude?, targetId?, note? })` records one intent per participant (overwriting any prior undeclared one), `peek(participantId)` reads without clearing, `all()` lists every declared `[participantId, intent]` pair (for an enemy-intent HUD row, Slay-the-Spire style), `consume(participantId)` reads and clears in one call, `clear(participantId?)` clears one or everyone. Reach for this when you need visible declared-but-not-yet-resolved intents (telegraphed enemy actions) without the full simultaneous-reveal machinery of `turn/commit`.
+- **`tactics/tacticalGrid` — `createTacticalGrid({ width, height, blocked?, diagonal?, world? })`.** Tile occupancy (one unit per tile), `reachable(from, budget)` flood-fill (respects walls + occupants), `path(from, to)` shortest route, and `push(id, dir, { distance, chain })` discrete knockback-to-tile — chained collisions transfer momentum through struck units (Into the Breach), or stop with a recorded `PushCollision` against `wall`/`edge`/another unit. `world: { origin: [x, z], tileSize }` (mirroring `navGrid`'s bounds+cellSize convention) turns on `worldToTile(x, z)` (world point → `Tile | null`, null outside the grid) and `tileToWorld(tile)` (a tile's world-space center) — the render/pointer-hit round trip between the tactics grid and the 3D scene; omit `world` for a grid used purely as abstract logic (both throw if called without it).
+- **`tactics/predictiveQuery` — `predictAreaEffect`/`predictArcEffect`/`predictTiles`.** A "would-this-effect-hit" query for pre-commit overlays and enemy-intent telegraphs. It reuses the **exact** AoE/LoS targeting behind `ctx.scene.entity.effect` (`combat/effects` `resolveAreaTargets`) so the predicted target set matches what the effect would actually drain — without committing any state change.
+- **`tactics/snapshot` — `createSnapshotStore()`.** Cheap, repeatable turn-undo: `register(id, slice)` any `capture()/restore()` slice (the grid, surfaces, and turn loop all qualify), then `capture()/restore()` a deep-cloned snapshot or use the `push()/pop()` undo stack. `deepClone` handles objects/arrays/Map/Set so a held snapshot is immune to later mutation.
+- **`tactics/surface` — `createSurfaceLayer({ kinds, reactions })`.** A stateful tile surface layer with its own `tick(dt)` (timed surfaces decay + expire) and a **combination matrix** — `reactions` is data (`{ when: [a, b], result }`), so grease+fire→fire and water+lightning→electrified are catalog entries, not hard-coded. Distinct from terrain/water; drive its tick from `onTick`'s game-time `dt`.
+
+## External data — `data/dataSource` and the dev proxy
+
+Renderer-free async-state primitives (`@jgengine/core/data`) for a game that reads a live external source (a leaderboard API, a session browser, remote config) — distinct from `ctx.game.store`/multiplayer, which are for the game's own authoritative state.
+
+- **`createDataSource(load, options?)`** (`data/dataSource`) → `DataSource<T>` wraps one `load(signal)` async call as `{ status: "idle"|"loading"|"ready"|"error", data, error }`. `getState()` reads the current snapshot, `subscribe(listener)` fires on every change, `refresh({ force? })` re-runs `load` (de-duplicates a call already in flight unless `force`; aborts the prior call first when forced), `startPolling(intervalMs?)`/`stopPolling()` run `refresh` on an interval (`intervalMs` falls back to the one passed at construction; throws if neither is given), `dispose()` tears down polling and in-flight requests for good. Pass `options.clock` (`{ setInterval, clearInterval }`) to swap the timer source in tests.
+- **`fetchJson<T>(url, options?)`** (`data/fetchJson`) — `fetch` + JSON-parse in one call; throws `HttpStatusError` (`status`, `statusText`, `url`) on a non-OK response and `JsonParseError` (`url`, `cause`) on unparsable JSON, so a `DataSource`'s `error` is always one of these two typed shapes, never a bare `Error`. `options.fetchImpl` swaps the fetch implementation for tests/SSR.
+- **`createJsonDataSource<T>(url, options?)`** (`data/jsonDataSource`) — sugar combining the two above: a `DataSource<T>` whose `load` calls `fetchJson(url, options)`.
+- **Dev proxy (`data/devProxy`)** — same-origin routing for external APIs during `bun dev` so browser CORS never blocks a game's `fetchJson` call against a third-party host. `parseDevProxyTable(raw)` parses a `VITE_JGENGINE_DEV_PROXY` env value (a JSON object of `{ routeName: "https://api.example.com" }`) into a `DevProxyTable`; `proxiedUrl(target, { dev?, table?, prefix? })` rewrites a `target` URL whose prefix matches a table entry into `/proxy/<routeName>/<rest>` (default prefix `/proxy`) when `dev` is true (defaults to `import.meta.env.DEV`) — else returns `target` unchanged, so the same call hits the real host in production. `apps/dev`'s `vite.config.ts` reads the same env var and wires a matching Vite server `proxy` entry per route (`changeOrigin: true`, strips the `/proxy/<routeName>` prefix) — set `VITE_JGENGINE_DEV_PROXY` once and both sides (the URL rewrite and the actual proxy route) agree.
+
+## Multiplayer and the backend seam
+
+The transport/host/persistence seam — `createWsBackend`, protocol codec, browser-safe authoritative host + router, WebRTC P2P, the Node/Convex/SQL adapters, presence, and save cadence. Full surface: **[reference/multiplayer.md](reference/multiplayer.md)**.
+
+## UI — `@jgengine/react`
+
+The React layer — `GameProvider`, the hooks table, headless className-passthrough primitives (incl. map components), the identity/chat/voice/social/drag-layer kits, the shadcn registry install path for visual HUD components (`npx shadcn@latest add https://jgengine.com/r/<name>.json`), the screen-layout rule, and the **UI quality bar** (required, not optional polish). Full surface: **[reference/ui-react.md](reference/ui-react.md)**.
+
+## Devtools — F2 overlay and tunables
+
+`@jgengine/shell`'s `GamePlayerShell` mounts an F2-toggled debug overlay (`shell/src/devtools/DevtoolsOverlay.tsx`) over every game automatically — `defineGame({ devtools: false })` is the only way to turn the toggle off (default `true`). Five tabs:
+
+| Tab | Shows |
+|-----|-------|
+| Perf | fps, frame/sim ms, draw calls, triangles, entity/object counts, state notifies/s, registered probes |
+| Tune | every discovered tunable — checklist grouped by source file or table export name; check one to control it live |
+| Logs | captured `console.log`/`info`/`warn`/`error` |
+| Net | observed backend round-trip latency (fed by `instrumentLatency`) |
+| Keys | the game's `ActionCodesMap` bindings |
+
+**Tunables are zero-annotation.** Write plain code under `Games/<id>/src/**` — no import, no wrapper — and it's discoverable:
+
+```ts
+// loop.ts — top-level export const, nothing else
+export const GRAVITY = -22;
+export const SKY_COLOR = "#87ceeb";
+export const GOD_MODE = false;
+
+// game/content.ts — an exported flat table of numbers/booleans/colors
+export const TUNING = { reach: 6, spawnRate: 0.4, fogColor: "#334455" };
+```
+
+The dev runner's Vite plugin, `tunableDiscoveryPlugin` (`@jgengine/core/devtools/transformTunables`, wired in `apps/dev/vite.config.ts`), rewrites each top-level `export const <number|boolean|"#hex">` literal to `export let` and binds it into the devtools registry as the module loads (`transformTunableExports` is the pure string transform underneath; `tunableModuleTable(id)` derives the table id from the file path, skipping `main.tsx` and `*.test.*`). Table exports need no transform at all — after each game module loads, the dev app calls `devtools.discover.scanModule(moduleExports)`, which walks every export's own properties for a flat plain-object table of numbers/booleans/`"#rrggbb"` strings.
+
+F2 → Tune tab lists every discovered entry as a checklist, grouped by source file (top-level constants) or by table export name (object tables). Checking an entry hands it a live slider/toggle/color picker; unchecking resets it to its initial value. Kind is inferred from the value: `number` → slider, `boolean` → toggle, a `"#rgb"`/`"#rrggbb"`/`"#rrggbbaa"` string → color.
+
+**Liveness.** An edit applies live wherever the code reads the constant/table entry at use time. A value captured once at init — passed into a function call, baked into worldgen — only picks up the new value on reload. Overrides persist in `localStorage` per game (key `jg-devtools:<game name>`) and are re-applied *before* `loop.onInit` runs, so even an init-baked constant respects its override after a refresh — *if* the read happens at or after `onInit`. A read that happens earlier than that (see below) never sees the override, reload or not.
+
+**Default assumption: almost every gameplay number, boolean, and color is a tunable, not a hardcoded fact.** Walk speed, jump height, gravity, damage, cooldowns, spawn rates, drop chances, radii, durations, thresholds, multipliers, colors — if it's a scalar a designer would plausibly want to nudge while playing, it belongs in a place discovery can see (a top-level `export const`, or a direct scalar field on a catalog def object like `PlayerDef`/`EnemyDef`) — never buried as a bare literal inside a deeper nested object with no named export, and never computed once and thrown away. Treat "should this be tunable" as opt-out, not opt-in.
+
+**Catalog-derived content must read fields live, not bake them at import time.** A common trap: a `content.ts` (or any module implementing `GameContextContent`) that loops over a catalog array *once at module scope* and copies scalar fields into a separately cached `Map`:
+
+```ts
+// WRONG — copies walkSpeed by value at import time, before devtools can even scan exports
+const entityEntries = new Map<string, GameContextEntityEntry>();
+for (const p of players) {
+  entityEntries.set(p.id, { stats: p.stats, movement: { poses: p.poses, walkSpeed: p.walkSpeed } });
+}
+export const content: GameContextContent = {
+  entityById: (id) => entityEntries.get(id) ?? null,
+};
+```
+
+This runs during module import — earlier than `discoverGameTunables`/override-application in `apps/dev/src/main.tsx`, and earlier than any `loop.onInit`. The catalog object (`p`) still gets live-mutated by devtools, but nothing ever re-reads it, so the baked `walkSpeed` is permanently stale: no F2 edit and no persisted override ever reaches gameplay, reload or not.
+
+```ts
+// RIGHT — map ids to the catalog def itself; build the entry fresh on every lookup
+const playersById = new Map(players.map((p) => [p.id, p]));
+function entityById(id: string): GameContextEntityEntry | null {
+  const p = playersById.get(id);
+  return p === undefined ? null : { stats: p.stats, movement: { poses: p.poses, walkSpeed: p.walkSpeed } };
+}
+export const content: GameContextContent = { entityById };
+```
+
+Same shape, same call site — the only change is *when* `p.walkSpeed` is read: at lookup time (each spawn) instead of once at import. Objects (`stats`, `receive`) are already reference-safe to pass through either way; this only matters for scalars (numbers/booleans/strings) copied out of a catalog def.
+
+**`tunable()` still exists — an optional low-level primitive, not the recommended path.** Reach for it only when you need explicit bounds, an `options` select, or a change subscription that discovery can't infer:
+
+```ts
+import { tunable } from "@jgengine/core/devtools/devtools";
+
+const gravity = tunable("physics/gravity", -22, { min: -60, max: 0 });
+```
+
+Read `gravity.value` at use time (or `gravity.subscribe(listener)`) — never destructure once at module load. A `"group/label"` name (e.g. `"physics/gravity"`) groups the control under `group` in the Tune tab; `devtools.controls.register` is the same call underneath. Real example: `Games/voxel-mine/src/loop.ts` — `tunable("mining/reach", REACH, { min: 2, max: 16, step: 1 })`, read via a getter passed to `createEditorHandlers`.
+
+**Agent loop.** The overlay's "Copy report" button copies a JSON `DevtoolsSnapshot`; from a browser session an agent can instead call `window.__JG_DEVTOOLS.snapshot()` directly (or `snapshotDevtools()` from game code) for the same shape — frame stats, render sample, latency stats, captured logs, probe values, every registered control's current + initial value, and a `discovered` array (`id`, `kind`, `value`, `enabled`) covering every auto-discovered tunable whether or not it's enabled — a single call to check "is this actually working" without a screenshot. `window.__JG_DEVTOOLS.discover` is exposed directly too (`list`/`enable`/`disable`/`bind`/`scanTable`/`scanModule`/`clear`) so an agent can flip a discovered tunable on and read/write it from the console without touching the UI.
+
+`devtools.probes.register("name", () => value)` (`@jgengine/core/devtools/devtools`) surfaces a game-specific gauge (entity count, queue depth, whatever) in both the Perf tab and the snapshot; call the returned unregister function to remove it.
+
+## Assets — real art from day one
+
+Squares as enemies, colored boxes as buildings, and a flat grid floor read as *broken*, not unfinished. The blueprint's **Asset plan** names the packs before the first edit; a pass does not end while any default-material primitive, unstyled ground plane, or debug grid is visible in the staged screenshot — and that includes 2D HUD art: a first-letter tile, emoji, or one generic shape reused per slot is a placeholder exactly like a graybox enemy. Primitive stand-ins are allowed only *mid-pass* as scaffolding.
+
+**Sources** (CC0 — public domain, commercial use, no attribution — unless noted):
+
+| Source | What you get |
+|--------|--------------|
+| [Kenney.nl](https://kenney.nl) | 40,000+ CC0 assets: characters, buildings, nature, vehicles, weapons, UI, audio — the broadest single library |
+| [Quaternius](https://quaternius.com) / [KayKit](https://kaylousberg.itch.io) | CC0 low-poly packs incl. **rigged + animated characters**: medieval, sci-fi, dungeons, animals, adventurers |
+| [Poly Haven](https://polyhaven.com) / [ambientCG](https://ambientcg.com) | CC0 PBR textures, HDRIs, materials — the floor comes from here, never a flat color |
+| [Poly Pizza](https://poly.pizza) | Search engine over thousands of CC0 low-poly models for one specific thing |
+| [Game-Icons.net](https://game-icons.net) (CC BY 3.0 — credit it) / Kenney UI packs (CC0) | 4,000+ item/ability **icon silhouettes** — the registry `game-icon` item covers common HUD glyphs first |
+| [itch.io CC0 3D tag](https://itch.io/game-assets/assets-cc0/tag-3d) / [OpenGameArt](https://opengameart.org) | Long tail — **check the license per asset**, CC0 filter first |
+| [Mixamo](https://www.mixamo.com) | Free humanoid animations (Adobe license — fine for shipped games, not CC0) |
+| Kenney audio / [freesound CC0 filter](https://freesound.org) | Hit sounds, UI clicks, ambience |
+
+**Rules:**
+
+1. **One style family per game.** Kenney + Quaternius + KayKit low-poly mix fine; low-poly models on photoreal PBR ground reads broken. Name the family in the blueprint.
+2. **License discipline.** CC0 needs nothing; anything else gets a line in `src/game/assets-credits.md` (source, author, license). Never ship an asset you can't name the license of.
+3. **Wire through the engine seams.** GLB models live in the game's `src/game/assets.ts` render catalog keyed by catalog id; billboards via `entitySprites`, real meshes via `entityModels`/`objectModels` in `defineGame({...})`; ground/skies belong to the world layer. Catalog `model` fields reference asset keys — never file paths in game logic. Source models through **`@jgengine/assets`** (`buildCatalog({ basePath })` → resolve ids/aliases → urls); `pull` packs into your app's `public/models/` (extracts Kenney's shared `Textures/` alongside the GLBs so models render textured). Network-restricted: `pull` falls back through `--mirror <baseUrl>` / `JGENGINE_ASSETS_MIRROR`, and `--offline` fails fast — see the package README for the fallback order and add/import flow.
+4. **Coverage follows the content budget.** Every entity family, placed object, and held item maps to a real asset *before* the catalog entry ships. If the pack lacks a model, restyle the noun to one it has — rename the fantasy, don't ship a cube.
+5. **Scale/pivot sanity.** `@jgengine/assets` measures each model's footprint/center/`minY` at reindex and ships them on the catalog entry (`catalog.resolve(id).dims`); with `objectModels` anchor `"center"` (the default) the shell centers the footprint on the placement point and ground-snaps the lowest vertex — so `object.place(id, cellX, y, cellZ, { rotation })` renders centered + grounded with no pivot math and no `dimensions.ts`. Anchor `"origin"` opts back into the raw GLB origin. Check the first placement of each model against its catalog `footprint`; one wrong pivot repeated 100 times is a rebuild.
+6. **Item and ability icons are assets too.** Every hotbar/inventory/ability slot renders a real, distinct icon — the registry `game-icon` catalog (`iconForItemId`/`iconForAction`) or a Game-Icons/Kenney silhouette — per the UI quality bar's real-icons rule.
+
+## Genre cheat sheet
+
+- **Voxel/crafting**: objects for blocks/machines, `voxel()`, `object.break`/`object.placeFromInventory`.
+- **Tycoon/lab**: objects + `slotInventory`, `plots()`, configure via prompt → command.
+- **Shooter**: `fireProjectile`/`settleProjectile`; grenades settle → `effect({ at, radius })`; `movement.poses`/`aim` + zoom modifier; `servers({ … })` + game-owned `server.mode`; loadout classes from commands.
+- **MMO/RPG**: bounded stats + `leveling()` over a game XP curve; `tabTarget` → `cycleTarget`; handlers read `getTarget`; quests bound to `entity.died`/`inventory.added`; social party + `partyShare`; `server: "persistent"`.
+- **All combat games**: react to `entity.died` (feed/leaderboard/score) — never poll HP.
+
+## Anti-patterns
+
+| Wrong | Right |
+|-------|-------|
+| Player tuning in `defineGame` | Entity catalog `movement` + stats |
+| `behaviors: […]` on place/spawn | Catalog entry |
+| Engine `weapon.fire` / `consumable.use` / `combat.*` | `item.use` + catalog `use` → game handler |
+| `ItemUseInput.to` for targets | `getTarget(from)` in handlers |
+| `effect({ to })` for gunshots | `fireProjectile` + `settleProjectile` |
+| Polling HP in `onTick` for kills | `entity.died` event |
+| `combat.lootTable` / `loot.enemy` | `onDeath` on the entity that died |
+| Hand-rolled `Math.random()` loot in commands | `lootTable()` + `ctx.game.loot.roll` |
+| Hand-rolled `xpForLevel`/`levelFromXp` | `game/progression` `curve()` + `leveling()` |
+| Hardcoded shop arrays | `item.trade.shops` + `tradableAt` |
+| Kit seeding via scattered `put`/`grant` | `applyLoadout` |
+| Per-user quest state hand-rolled | `game.quest.register` + binds |
+| `useKillFeed` / per-domain feed hooks | `useFeed({ action })` |
+| Raw keys in game logic | `defineGame` input actions |
+| Positioning inside `ui/components/` or on primitives (`CurrencyPill className="absolute …"`) | Screen wrappers in `GameUI.tsx` only |
+| Game UI classes without `@source` in host CSS | `@source` entries for your game dirs + `node_modules/@jgengine/{shell,react}` |
+| One file per catalog entry / per brand | Dense `<domain>/catalog.ts` |
+| Convex mutations called from game code | `commands.run` through the `GameBackend` transport |
+| Half a system: quest without tracker, cooldown without sweep, keybind never shown, stub "coming soon" modal | Finish the system end to end — or cut it whole (see `jgengine-newgame`) |
+| Game-side workaround for a missing engine primitive | File the gap at github.com/Noisemaker111/jgengine/issues (or PR the primitive) and cut or scope the dependent system honestly |
+| Game nouns in this skill | Engine primitives + placeholder ids only |
+
+## New-game definition of done
+
+This is a gate, not a suggestion — every box, in one pass (workflow: **`jgengine-newgame`** skill). "Compiles and the hooks are wired" is not done; a declared system with no UI, no feedback, or no way to exercise it is not done — finish the system or cut it whole.
+
+- [ ] `game.config.ts` (`defineGame` from `@jgengine/shell/defineGame`) + `index.tsx` (barrel) + `main.tsx` (standalone host) + `loop.ts` + `game/content.ts`
+- [ ] Catalogs: `game/entities/<role>/catalog.ts`, `game/items/<domain>/catalog.ts`, `game/objects/catalog.ts`; loot tables beside their domain
+- [ ] Entity `stats` + `receive` orders aligned on the same stat ids; `role` set (drives targeting + camera)
+- [ ] `game/items/use-handlers.ts` registered in `onInit`; handlers read `getTarget`/`aim`, never a target input
+- [ ] `game/loadouts.ts` + `applyLoadout` in `onNewPlayer` (gated on `isNew`)
+- [ ] `game/quests/catalog.ts` + binds; if using xp/level, a game-owned curve fed to `game/progression` (`curve`/`leveling`) — **with their HUD/tracker, or cut**
+- [ ] `onInit`: register handlers/loadouts/loot/quests, event listeners, feed binds, leaderboard tracks; `setupWorld`
+- [ ] Player spawns with `id === ctx.player.userId`
+- [ ] `game/ui/GameUI.tsx` owns layout; components use `@jgengine/react` hooks
+- [ ] UI passes the **quality bar** above (contrast, scale, framing, genre fit) — not just hook wiring
+- [ ] Camera tuned via `camera` in `defineGame({...})` — defaults untouched means the feel was never checked
+- [ ] For an `environment()` world: a `<game>.world.test.ts` asserts `summarizeEnvironment(world)` (`@jgengine/core/world/environmentSummary`) is non-empty with the expected counts — the browserless scene-correctness gate
+- [ ] HUD screenshotted over a staged `GameUiPreview` scenario and **judged by looking at the image** against the UI quality bar in [`reference/ui-react.md`](reference/ui-react.md) — the final human glance, not the verification loop
+- [ ] Co-located bun tests for pure game math (curves, cooldowns, spawn logic)
+- [ ] Multiplayer via adapter config only; no direct backend calls
+
+## Quick reference
+
+```
+defineGame (shell) engine fields (assets, world, physics, inventories, input, server, save, time, feed, multiplayer)
+                   + presentation fields (content, loop, GameUI, camera, environment, shadows, movement, devtools, …) in one call — smart defaults fill the rest
+defineGame (core)  the underlying engine-only primitive: assets, world, physics, inventories, input, server, save, time, feed, multiplayer, loop
+PlayableGame       { game, content, loop, GameUI, camera, … } — the runner contract `defineGame` (shell) returns
+GameContext        ctx.scene / ctx.game / ctx.player / ctx.item / ctx.camera / ctx.input + subscribe/version
+scene.object       place, remove, move, rotate, at, setVisual (per-instance ObjectVisual: scale/color/opacity override)
+scene.entity       spawn (anchor/offset), despawn, setPose, update; stats; targeting; effects;
+                   projectiles (object-aware raycasts); spatial queries (opt-in grid broadphase)
+entity.stats       get / set / delta — bounded stats (health, mana, xp, level) on instances
+progression        game/progression — curve() / leveling() over bounded xp/level stats
+item.use           catalog `use` → GameContext handler; no input.to
+effects            drain-signed magnitudes; receive.<effect>.order; AoE = effect + at/radius/los
+projectiles        willHit → fire → settle; ballistic via weapon.projectile
+death              onDeath (reason-aware drops/command), entity.died, auto kill attribution + drop grant
+game.loot          register / has / roll / grantToPlayer   (lootTable() = pure factory)
+game.trade         canBuy / canSell / buy / sell / tradableAt
+game.quest         register, accept…turnIn, bind(entity.died | inventory.added), declarative rewards
+game.social        friends (persisted, requests listable), party (ephemeral, invites listable), presence, emotes (nearby broadcast), worldInvites (accept → join target)
+game.chat          send / whisper / history / register — global/party/proximity channels, rate-limited, mute via blocked set
+game.roster        capture / release / list / setEquipped — persisted owned-creature roster
+game.store/cards/turn   store: keyed reactive slot; cards.pile(id): lazy CardPile; turn.loop(id): lazy TurnLoop
+game.events/feed/leaderboard   on / bind+push+recent / track+increment+getTop
+devtools           F2 overlay (Perf/Tune/Logs/Net/Keys); zero-annotation — top-level export const number/boolean/color + exported flat tables auto-discover into Tune; tunable() is the optional low-level escape hatch; snapshotDevtools()/window.__JG_DEVTOOLS.snapshot() → DevtoolsSnapshot (+ discovered[]); probes.register(name, read) adds a Perf gauge
+applyLoadout       all-or-nothing kit seeding per userId
+player.movement    pose (hitboxes) + aim (zoom modifier)
+player.motion      impulse / setVerticalVelocity / setY — vertical-motion seam into the shell's frame driver
+player.possession  own/disown/owns/listOwned + active + possess — control-swap, rebinds shell camera
+player.cosmetics   register + apply/equip + get — per-player appearance slots, no gameplay effect
+scene.entity.form  register + shapeshift/revert + active/abilities — movement+ability+mesh bundle, game-time duration
+proximityPrompt    { radius, display: {kind}, invoke } — one float-UI primitive
+skillCheck/qte     evaluateSkillCheck (moving zone + window) / evaluateQteSequence (timed steps)
+captureCheck       captureChance / rollCapture — hp% + catchPower → probability
+dialogue check     DialogueChoice.check (roll vs DC + advantage/disadvantage) → onSuccess/onFailure
+world features     biomes / voxel / plots / tilemap / flat descriptors
+physics/physicsWorld  optional headless rigid-body sim (PhysicsWorld) — not the defineGame physics field (gravity/jumpVelocity, honored by the kinematics controller); bodies are box (halfExtents) or sphere (radius)
+physics/ballisticSweep  createBallisticSweep(world) → arc-vs-body hit test; wire into ProjectileSystemDeps.sweepBallistic
+anim/easing        lerp/clamp01/smoothstep/tween/timedProgress + easeIn/Out/InOut Quad/Cubic + easeOutBack/Elastic — pure 0..1 tweening math
+data/dataSource    createDataSource/createJsonDataSource — idle/loading/ready/error async state + polling; data/fetchJson + data/devProxy for CORS-safe dev fetches
+audio/audioFalloff computeFalloffGain / resolveEmitterGain — pure distance→gain curve; shell plays it
+time/beatClock     createBeatClock (BPM ticks) + createBeatInputBuffer (buffered action → next beat)
+ws/voiceChannel    createVoiceChannelRouter — positional falloff + simultaneous non-positional channels
+multiplayer/identity   AuthSession + sessionPlayer + resolveGuestSession — Clerk/better-auth via react structural adapters
+multiplayer/chatContract  ChatTransport (hooks) / ChatSync (callbacks) — ws + convex bindings, local for dev
+multiplayer/voiceContract VoiceTransport (join/leave/publish/subscribers) + createPushToTalk — media plane host-supplied
+GameBackend        { transport, feeds?, presence? } — Convex is one adapter (createConvexBackend)
+adapter kinds      offline / ws / convex / socketIo / p2p / lan (+ fly({app}) ws sugar) — runtime/adapter
+ws/pipe            TransportPipe/TransportPipeFactory — any bidirectional string channel (webSocketPipe default)
+ws/host, ws/hostRouter  browser-safe createGameHost + createHostRouter/loopbackPipe (node re-exports both)
+ws/peer            createPeerHost/createPeerGuest — WebRTC P2P, host tab authoritative, copy-paste signal codes
+ws/socketIoPipe, node/socketIoServer  socketIoPipe/createSocketIoBackend + attachGameSocketIoServer
+@jgengine/react    GameProvider + hooks + headless primitives (incl. identity/chat/voice/social kits); layout only in GameUI.tsx
+```
+
+Engine ships verbs and primitives. Your game ships nouns.
+
+# jgengine-api — Combat
+
+Reference module for the [`jgengine-api`](../SKILL.md) skill. Load this when you need the combat surface — effects, projectiles, death, feel, and abilities.
+
+## Effects and projectiles
+
+Effect ids are **game-defined strings**. Magnitudes **drain** stats: positive subtracts down `receive.<effect>.order` (spilling to the next stat in the order), negative restores. Heals pass a negative amount (`via: { amount: -flashHeal }`, typically read from a `weapon.heal` stat).
+
+```ts
+ctx.scene.entity.canReceive(instanceId, effect, magnitude?)  // null | reason — reads catalog receive
+ctx.scene.entity.preview({ from, to, effect, via })      // magnitude, no state change
+ctx.scene.entity.effect({ from, to, effect, via })                          // single target
+ctx.scene.entity.effect({ from, effect, via, at, radius, falloff?, los? })  // AoE at a point
+```
+
+AoE: `inRadius(at, radius)` → LoS filter (default on) → `canReceive` per target → absorption; `falloff: "linear" | "none"`. `via` = `{ item }` (magnitude from weapon stats) or `{ amount }`. `canReceive`'s `pools-depleted` reason checks headroom in the effect's direction: a positive (draining) magnitude needs a stat above its min, a negative (restorative) magnitude needs a stat below its max — so a heal can still raise a stat sitting at its minimum. Omitting `magnitude` assumes the draining direction.
+
+`canReceive`'s optional signed `magnitude` makes the check direction-aware: positive (or omitted) keeps the standard `"pools-depleted"` check; negative checks the opposite direction and returns `"pools-full"` only when every stat in the receive order is already at max — so a heal (`via: { amount: -n }`) correctly reaches a fully-depleted target and is rejected only when there's nothing left to restore.
+
+**Projectiles** (aim-based — no target ids):
+
+```ts
+willHitProjectile({ from, via, aim, effect })   // prediction only, for crosshair UI
+fireProjectile({ from, via, aim, effect })      // → shotId (pending)
+settleProjectile(shotId)                        // authoritative → { at, hits } | rejection
+```
+
+`Aim = { origin, direction } | { yaw, pitch, spread? }`. Hitscan settles into per-hit effects; ballistic shots (`weapon.projectile` with `fuseTime`/`settleOn`) settle to a landing point — the handler then calls `effect({ at: settle.at, radius })`. Settling twice rejects. Prediction is never authority.
+
+Raycasts are **object-aware**: the default raycast checks placed scene objects as well as entities, discriminated by `RaycastHit.kind` (`"entity" | "object"` — an `ObjectRaycastHit` also carries `catalogId`). A crate or wall between shooter and target blocks or absorbs the shot instead of every projectile passing through scenery; supply `ProjectileSystemDeps.objects` (`{ list(), halfExtents?(catalogId) }`, matching `ObjectStore.list()` structurally) to opt in, with a `[0.5, 0.5, 0.5]` half-extent default per object.
+
+## Death
+
+Resolved **once** by the engine when the last stat in the receive order hits min. No HP polling in `onTick`, ever.
+
+- `entity.died` is emitted (before despawn — handlers can still read the victim's stats), then reason-matching `onDeath` entries run.
+- `DeathReason = { kind: "player_kill", killerUserId, via? } | { kind: "environment", source } | { kind: "self", source }`. Kills by the local player attribute automatically.
+- `onDeath.drops` tables are rolled and **granted to the killer** on player kills (emits `loot.granted`) when `onDeath.dropMode` is `"grant"` (default); `onDeath.command` runs through `ctx.game.commands`.
+- `onDeath.dropMode: "world"` routes item drops through a scatter impulse into ground `worldItem`s instead of straight to inventory (currency drops still grant directly) — tune the impulse with `onDeath.scatter: { radius, minRadius?, height? }` (defaults from `game/worldItem`'s `DEFAULT_SCATTER`).
+- Respawning under the same instance id revives it (it can die again). Same-id respawn must not happen synchronously inside the `entity.died` handler — defer a tick.
+- `quest.bind("entity.died")` credits kill objectives from the same event; leaderboards and kill feeds hang off it too.
+
+## Combat feel (melee, defense, telegraphs)
+
+Layered on top of effects/projectiles/death — none of it replaces them, it adds **feel**. All models are renderer-free pure `@jgengine/core` factories a game composes per entity (like the `ctx`-vs-factory split above); the shell renders the telegraphs, styled damage numbers, hitstop shake.
+
+- **Animation state machine** (`combat/animationState`) is the root the rest hangs on. A `AnimationClip` is catalog data — `{ frames, fps, ranges }` where each `FrameRange` tags a window `windup | active | recovery | cancel` (cancel may overlap recovery). `createAnimationState({ clips })` gives a per-entity SM: `play(clipId)`, `tick(dt)` → `{ entered, exited, completed }`, and queries combat/defense subscribe to — `inPhase("active")`, `isActive()`, `canCancel()`, `activeWindowMs()`. Frame ranges are the "commit frame" contract for delayed/feinted attacks.
+- **Attack tags** (`combat/attackTags`) — `attackMeta(["unblockable" | "thrust" | "sweep" | "grab" | …], { effect, power })`. Defense logic reads them: `isBlockable`, `isParryable`, `isDodgeable`, `counters(meta, "mikiri")`. A grab beats all defenses; an unblockable is parry/dodge-only.
+- **Defensive window** (`combat/defensiveWindow`) — a parry/block/dodge with `{ startupMs, activeMs, recoveryMs, iframes }`. `resolveDefense({ config, elapsedMs, attack })` is the pure overlap of the defender's window against the moment the attacker's `active` frames land → `parry | block | iframe | hit`. `createDefensiveWindow(config)` tracks the open time (`open(now)` / `evaluate(now, attack)` / `isInvulnerable(now)`).
+- **Combo strings** (`combat/comboString`) — `ComboStep`s with `cancelInto` + `cancelPhases` + optional `stance`, over the anim SM. `advanceCombo(...)` (pure) accepts the next attack only inside the current step's cancel window and matching stance; `createComboRunner(combo, anim)` drives the SM.
+- **Meters share one accumulator** (`stats/accumulatorMeter`) — `createAccumulatorMeter({ max, mode: "hold" | "reset", decayPerSecond, decayDelayMs, tiers })`: fill via `add(n)` → `MeterAddResult { fired, overflow, tier, tierChanged }`, `tick(dt)` decays after an idle grace. `combat/breakMeters` builds two on it: `createStaggerMeter` (mode `hold` — fills from hits, `broke()` stays true until `recover()` after a riposte/deathblow) and `createBuildupMeter` (mode `reset` — `add(n)` returns a `BuildupProc { status, durationMs }` at threshold for bleed/frost/rot, then decays). The same base backs G6's ult/streak meters.
+- **Dash / dodge** (`movement/dash`) — `createDashState({ distance, durationMs, iframes, staminaCost, staminaMax, staminaRegenPerSecond, cooldownMs })`: `tryDash(dir, now)` → burst or `{ reason: "no-stamina" | "cooldown" | "dashing" }`, `isInvulnerable(now)` for the i-frame window, `offset(now)` for the burst displacement, `tick(dt, now)` regens stamina.
+- **Hit reaction** (`combat/hitReaction`) — `resolveHitReaction(config, { attackerPos, targetPos, power })` (pure) → `{ hitstopMs, impulse, shake }`. Wired on `ctx`: `ctx.scene.entity.hitReaction({ from, to, config, power? })` knocks the target back and emits `combat.hitReaction` (the shell reads `shake` for a trauma channel — feeds a G2 camera-shake rig when present, else the shell's own kick).
+- **Telegraph** (`combat/telegraph`) — a `TelegraphShape` (`circle | ring | cone | line`) + `windupMs`. `ctx.scene.entity.telegraph({ from, shape, at, dir?, windupMs, kind?, effect? })` emits `combat.telegraph` for the shell to draw a ground decal that fills over the windup, and — if `effect` is bound — applies that effect to everyone inside the shape (`pointInTelegraph`) at activation. Returns a cancel handle. **Turn-scoped variant**, for tactics/turn-based enemy intents instead of a real-time windup: set `TelegraphConfig.turns` (a count of turns instead of `windupMs`), then read `telegraphTurnProgress(config, startedTurn, currentTurn)` (0..1 fill fraction), `telegraphFiredAtTurn(config, startedTurn, currentTurn)` (has it resolved), and `telegraphTurnsRemaining(config, startedTurn, currentTurn)` — the same "enemy will hit this tile" decal, advanced by `turnLoop.round()`/`active()` instead of a clock.
+- **Damage-number typing** — `ctx.scene.entity.floatText({ …, crit?, element?, hitType?, scale? })` (and the `entity.floatText` event) carry hit metadata; the shell's `resolveFloatTextStyle` (`@jgengine/shell/world/floatTextStyle`) maps crit/element to color + scale + glow.
+
+## Abilities, resources, auto-target, resistance, run drafts
+
+Genre systems layered over the same effects/projectiles/targeting/loot primitives — all renderer-free pure `@jgengine/core` factories a game holds per player and ticks on **game-time** `dt` (so pause/fast-forward carry through). The ability kit is deliberately **separate from inventory items**: an item is a stackable id, an ability slot is cooldown/charge/resource state the HUD's four slot-states bind to.
+
+- **Ability kit** (`combat/abilityKit`) — `createAbilityKit([{ id, cooldownMs, chargesMax?, resourceCost?, castType?, flashMs? }])`. `state(id, resourceAvailable?)` → `AbilitySlotSnapshot { state: "ready" | "cooldown" | "no-resource" | "just-cast", charges, chargesMax, cooldownRemainingMs, cooldownFraction, justCast, ready }`; `cast(id, resourceAvailable?)` consumes a charge, starts the recharge, and flashes just-cast; `canCast` / `tick(dt)` / `reset` / `retuneSlot(id, { cooldownMs?, resourceCost? })` (rebalance a slot at runtime — patches the config in place without touching charges or an in-flight cooldown timer, returns `false` for an unknown slot). The kit is resource-**agnostic** — it reports `no-resource` by comparing `resourceCost` to a supplied `resourceAvailable` (a mana stat, or an ult meter), and never spends the resource itself; the game's handler spends it and calls `cast`. Charges recharge one at a time; the four states drive the hotbar slot art. Cooldowns tick on `dt`, so hang `kit.tick(dt)` in `onTick`.
+- **Event-fed meters** (`stats/eventMeter`, built on `stats/accumulatorMeter`) — `createEventMeter({ max, mode, gains, resets?, tiers?, decayPerSecond? })`. `feed(tag, scale?)` maps a tagged combat event to a gain (or a reset when `tag ∈ resets`) → `EventMeterFeedResult { fired, ready, tier, tierChanged, reset }`. Mode `"hold"` is the **ult/adrenaline** economy — charges off `{ damageDealt, damageTaken, kill }` events, `ready()` at full, `consume()` spends it (Overwatch/Marvel Rivals). Mode `"reset"` is the **streak/combo** meter — builds on `kill`, resets on a break tag like `damageTaken`, climbs ascending `tiers` (Returnal adrenaline, DMC style rank). One primitive, two catalog configs.
+- **Auto-target policy** (`scene/autoTarget`) — `selectAutoTarget(policy, fromId, deps)` / `createAutoTargeter(policy, deps)` evaluated each tick with zero input: `"nearest" | "farthest" | "random" | "strongest" | "weakest" | "first" | "last"`. `deps` supplies `candidates`/`distance` and optional `strength` (health/threat) + `progress` (path progress for first/last-on-path). Bullet-heaven auto-fire (Vampire Survivors nearest), Bloons tower priority (first/last on path). Feed the picked id to `abilityKit.cast` + `effect`.
+- **Resistance matrix** (`combat/resistance`) — a damage-category × target-property table distinct from `combat/attackTags` (those are defense tags). `resolveResistance(matrix, category, targetProperties)` → `{ verdict: "immune" | "resist" | "normal" | "vulnerable", multiplier, immune }`; `resistanceScale` returns just the multiplier (default `immune:0, resist:0.5, normal:1, vulnerable:2`, overridable). Immune on any property wins; resists stack multiplicatively. Sits over the `receive` gate — the handler multiplies its effect `amount` by the scale (Bloons lead/camo immunities, elemental RPG weaknesses).
+- **Run draft** (`game/runDraft`, built on `world/scatterItems` `pickWeighted` + `stats/statModifiers`) — `createRunModifierStack(offers)` accumulates stacking picks (`add`, `count`, `atMax`, `total(stat)` aggregating adds × exponentiated multiplies, `apply(stats)` onto a `createStats` source). `createRunDraft({ offers, rng? })` adds the pause-flow: `present(n)` draws N distinct weighted offers (excluding maxed-out ones), `choose(id)` applies to the stack. Pause/resume is game-side (`ctx.time.pause()` before `present`, `play()` after `choose`). Vampire Survivors level-up picks, Hades boons, Risk of Rain stacking items.
+
+# jgengine-api — World features
+
+Reference module for the [`jgengine-api`](../SKILL.md) skill. Load this when you need the renderer-free world surface.
+
+## World features
+
+Descriptors from `@jgengine/core/world/features` — config data the runner/world layer interprets:
+
+| Feature | Use |
+|---------|-----|
+| `biomes({ map, zones, bounds? })` | Region atmosphere/rules layering; zones reference biome ids |
+| `voxel({ seed, generate?, streaming? })` | Block worlds |
+| `plots(config)` | Shared city + instanced interiors |
+| `tilemap({ map })` | 2D/2.5D levels |
+| `flat()` | Plain arena |
+| `environment({ terrain, sky, weather, vegetation, water, structures, pads })` | Composable outdoor scene — terrain + sky/time-of-day + rain/snow + grass + ocean + buildings + ground pads. Each field takes the matching descriptor: `terrain()`, `sky()`, `rain()`/`snow()`, `grass()`, `ocean()`, `building()`, `pad()`. `building()` and `ocean()` take `position: [x, z]` to site a cluster/water body away from the origin (several settlements, an offset lake); building clusters ground-snap to the terrain field per building; each `pad()` (a flat platform/paved patch — `{ center, size: [w,d] | { radius }, height?, color?, rotationY? }`) implicitly flattens the terrain beneath it via a `TerrainFlattenMask`, so a building pad or spawn circle never fights the noise field underneath |
+
+`biomes`/`voxel`/`plots`/`tilemap` share a `WorldGridConfig` (`cells?: WorldGridCell[]`, `cellSize?`, `baseHeight?`, `defaultColor?`) — a `WorldGridCell` is `{ x, z, height?, color? }`, one extruded box per cell. `resolveGridInstances(config)` (`@jgengine/core/world/gridInstances`) is the pure cell→instance math (position, scale, color per cell); the shell renders the result as a single `THREE.InstancedMesh` **automatically whenever `PlayableGame.environment` is unset and `game.world` is one of these four grid kinds** — no manual render wiring for a cell-based world, same auto-render convention as `environment()` worlds.
+
+`terrain()`'s `material` (a named palette — `"grass" | "sand" | "snow" | "rock" | "ash"`, resolved via `resolveTerrainPalette`/`TERRAIN_MATERIAL_PALETTES` in `world/terrain`) sets the default low/high/waterline colors; `colors: { low?, high?, waterline? }` overrides any of them field-by-field, and `segments` tunes the render mesh's subdivision. `flatten: TerrainFlattenMask[]` (`{ center, radius, height?, falloff? }`) carves explicit flat circles into the noise field independent of pads — building foundations, spawn circles, roads — blending back to the noise height over `falloff` (default `radius * 0.5`). `sky({ preset?, timeOfDay?, horizonColor?, zenithColor?, sunIntensity?, ambientIntensity?, fog? })` — `preset: "day" | "dusk" | "night"` (default `"day"`) is the static look; `timeOfDay: true` instead drives sun position, sky colors, and fog from the world clock's `calendar().dayFraction` every frame (`@jgengine/shell`'s `TimeOfDayDaylight` mounts this automatically for an `environment()` world with `sky` set — no per-game render wiring). **Gotcha:** `sunIntensity` / `ambientIntensity` are honored only on the **day** keyframe (`daylightCycle` builds dusk/night/dawn from fixed constants). Raising intensities under `preset: "dusk"` or `"night"` does nothing — use `preset: "day"` plus warm `horizonColor`/`zenithColor` when the first screenshot must be bright and readable (see `jgengine-newgame`'s first-shot art recipe).
+
+`parentSpace` positions are local to that space — convert at seams only.
+
+### Query primitives (renderer-free, for gameplay)
+
+Pure `@jgengine/core` functions so gameplay reads the same world the shell renders — no three.js needed:
+
+| Primitive | Answers |
+|-----------|---------|
+| `resolveTerrainField(terrain(...))` / `noiseField(cfg)` → `TerrainField` | `sampleHeight(x,z)`, `sampleNormal(x,z)`, `waterLevel` — ground-snap, collision, camera. `resolveGroundStep` slope-limits movement |
+| `snapToGround(field, position, offset?)` → `[x,y,z]` | Replaces a position's `y` with the field's sampled ground height (+ `offset`) at its `x`/`z` — the pure version of a spawn/placement ground-snap |
+| `snapEntityToGround(entities, id, field, offset?)` → `boolean` | Ground-snaps an already-spawned entity in place via `entities.setPose` — false when `id` is unknown; the imperative sibling of `snapToGround` for "drop this entity onto the terrain right now" (mount dismount, teleport, respawn) |
+| `windField(cfg)` → `WindField` | `at(t)`, `atPoint(x,z,t)`, `strengthAt` — one wind source for weather sway, grass, sailing, fire spread |
+| `waterSurface(cfg)` / `waterSurfaceFromDescriptor(ocean(...))` → `WaterSurface` | `height(x,z,t)`, `normal`, `displace` — buoyancy, floating, shoreline (CPU Gerstner matching the ocean shader) |
+| `scatter(cfg)` → `ScatterPoint[]` | Seeded, overlap-aware point distribution — vegetation, props, lots, spawn points (`minDistance`, `avoid` rects) |
+| `createRegionField({ regions })` → `RegionField` | `sampleRegion(x,z)` blends content-agnostic biomes by nearest selector — height + `tint`/`water`/`fog`/`speedMultiplier` + opaque `data`. Extends `TerrainField`, so it ground-snaps too |
+| `scatterItems(field, area, layersFor)` → `ScatterInstance[]` | Region-driven content scatter — density per region, grounded, above-water/slope-aware. `pickWeighted` for weighted rolls. (vs `scatter`'s pure geometric points) |
+| `buildingIndex(district)` → `BuildingIndex` | `at`/`within`/`nearest`/`isInside`/`blockers` over a generated district — placement avoidance, pathfinding |
+
+**Voxel field (`world/voxelField`).** `createVoxelField<T extends string>({ chunkSize? })` (default 16) is a logical block lattice for voxel games and instanced renderers — distinct from the `voxel()` `WorldFeature` descriptor above (that's the runner-level world kind; this is the block data structure a voxel game's gameplay reads and writes). `set`/`remove`/`get`/`has`/`fill`/`clear`/`count`/`cells`/`bounds` are the block CRUD (`set` returns `false` only when the identical type is already there — a no-op write). `neighbors(x, y, z)` returns the 6-adjacent occupied cells; `exposedFaces(x, y, z)` returns the `VoxelFace`s (`"px"|"nx"|"py"|"ny"|"pz"|"nz"`) not touching another voxel — feed that straight into greedy-meshing/face-culling. `raycast(origin, direction, maxDistance)` runs a 3D DDA and returns `{ x, y, z, type, face, adjacent, distance }`, where `adjacent` is the empty cell just in front of the hit — the placement target for block-place tools. Renderers dirty-track via `chunkOf(x, y, z)` + `chunkVersion(chunk)` and `subscribe(listener)`, so an instanced mesh only rebuilds the chunks that changed. For a non-`environment()` voxel world, assert on `field.summary()` (`{ blocks, types, bounds }`) the same way an `environment()` world asserts on `summarizeEnvironment` (see `jgengine-verify`).
+
+**Destructible terrain (`world/carve`).** Two runtime-editable primitives for dig/carve worlds. `VoxelVolume` is a dense grid of material ids (0 = empty) — `carve({ center, radius, toolStrength })` clears a sphere of solid cells the tool is strong enough to break and returns the count removed (feed a loot roll), `deposit({ center, radius, material })` fills one (Deep Rock tunnels, Astroneer terrain add); `solidAtWorld` reads it back for collision. `CarvableField` (via `carvableTerrain(base)`) wraps any `TerrainField` and writes craters/mounds into its height — `carve({ x, z, radius, depth })`/`deposit({ x, z, radius, height })` — so ground-snap, collision, and the shell mesh all read the deformed surface (Helldivers 2 explosion craters). Cell strengths come from a `VoxelMaterial` table (DATA). Renders through `@jgengine/shell/terrain/CarvedTerrain`.
+
+Renderers for these descriptors live in `@jgengine/shell` (`shell/terrain`, `shell/water`, `shell/weather`, `shell/structures`).
+
+### Environment fields, weather hooks & realm composition
+Renderer-free survival/environment primitives that extend the world query layer — meters, spawn gating, and damage-in-sunlight read the same world the shell renders, all ticking on game-time `dt`.
+- **Environment field** (`world/envField`): `createEnvironmentField({ dayLength, baseTemperature, nightDrop, altitudeLapse, terrain, rain, occluders, heatSources, ambientFloor, temperatureAt })` → `EnvironmentField`. Sample **temperature**, **wetness**, **lightExposure** (direct sun/sky), and **ambientLight** (spawn gating) at any `(x, z, time)` — `sample(x, z, time, y?)` returns all four plus `sheltered`. Occluders (roofs/canopy) shade sun and shelter from rain; heat sources (campfires) warm nearby positions; `sunElevation(time)` drives the day cycle. Sun damages a vampire, cold forces campfires, low ambient light spawns mobs — the field answers "am I in sun vs. shade / cold vs. warm / dark vs. lit". Pure and instantaneous; stateful build-up belongs to a decay meter reading the field.
+- **Weather → gameplay** (`world/weather`): `resolveWeather(state, table)` turns a `WeatherState { kind, intensity }` into concrete `ResolvedWeather` (`grip`, `visibility`, `structureDamage`, `chill`, `ignition`, `spread`) via a game-owned `WeatherModifierTable` — multipliers interpolate from neutral by intensity, rate effects scale linearly. Read `grip`/`visibility` in movement and AI, `structureDamage` on a building tick.
+- **Fire spread** (`world/weather`): `createFireGrid({ cols, rows, cellSize, origin, fuelAt, spreadRate, burnRate, wind, windBias })` → `FireGrid` is a **coarse cellular** propagation (not a fluid solver): `ignite(x, z)` / `igniteCell(col, row)`, then `step(dt, { spread, wetnessAt })` transfers heat to neighbours biased by wind, consumes fuel (`unburnt → burning → burnt`), and honours firebreaks (zero-fuel cells) and rain/wetness suppression. `resolveWeather(...).spread` feeds the step; `@jgengine/shell/weather` `FireSpreadLayer` renders the burning/scorched cells.
+- **Realm composition** (`world/realm`): `composeRealm(base, cards)` assembles a played instance at runtime from a deck of modifier **cards** (Nightingale realm cards) — a `major` card is the biome base, `minor` cards layer environment param overrides, a `WeatherState`, and spawn-table edits (`set`/`add`/`scale`/`remove`). The result recomposes both the environment (into a sampleable field via `composed.environmentField(extra?)`) and the `spawnTable`, and depends on the weather hooks above to turn its `weather` into gameplay modifiers.
+### Survival meters, moodles & multi-region health
+The `survival/` domain — decay-over-time meters and per-part health, both feeding one stacking **moodle** status display distinct from numeric bars.
+- **Decay meters** (`survival/decayMeter`): `createDecayMeterSet([{ id, max, min?, start?, rate, thresholds }])` → `DecayMeterSet`. Each named meter (hunger, thirst, oxygen, sanity, warmth, stamina) drains/recovers on `tick(dt)` at `rate`, refills from consumables/actions via `refill(id, amount)`, and raises threshold moodles (`below`/`above`). `setRateModifier(id, mult)` lets the environment drive them — read an env field, then speed warmth loss when cold or oxygen loss in a toxic biome.
+- **Moodles** (`survival/moodle`): the shared status stack, distinct from raw bars. `stackMoodles(...groups)` folds meter, ailment, and buff `Moodle[]` into one worst-first display (same-id stacks add, worst severity wins). `createMoodleStack()` holds timed buffs (`add({ id, label, duration })` — Valheim's concurrent food buffs) and expires them on `tick(dt)`.
+- **Multi-region health** (`survival/regionHealth`): `createMultiRegionHealth({ regions, ailments })` → `MultiRegionHealth` gives per-part pools (head/thorax/arms/legs, Tarkov/DayZ style) — `damage(regionId, amount)` scales by `vulnerability` and kills when a `vital` part empties; a stacking **ailment queue** (`applyAilment`, `tick(dt)` drains like bleed) carries per-injury treatment (`treat(itemId)` clears wounds via bandage/tourniquet/splint). `ailmentMoodles()` shares the moodle display with the meters (#78 + #90).
+### Interactive building & terraform (renderer-free tools)
+Turn data-only placement into the build tooling of Valheim/Enshrouded/The Sims/Fortnite/Dinkum. All pure `@jgengine/core/world`; the shell renders the ghost/tint/brush (`shell/structures/PlacementGhost`, `shell/terrain/EditableGround`, `shell/terrain/TerraformBrushCursor`) driven by `pointer.worldHit()`.
+| Primitive | Answers |
+|-----------|---------|
+| `createPlacementController({ footprint, rules, snapMode, grid })` | Owns the ghost: `hover(hit)` → `PlacementPreview` (`valid` tint wraps `validatePlacement`), `rotate()`, `setSnapMode`/`cycleSnapMode` (`"grid"`/`"free"`/`"surface"`), `commit()` → `PlacementCommit` (`rotationY` via `quarterTurnsToRotationY`). Feed it `pointer.worldHit()`. |
+| `snapToNearest(registry, placed, movingDef, cursor, { snapDistance })` | Typed connector sockets — snaps a piece's socket onto the nearest **compatible** placed socket (`socketsCompatible` = both sides `accept` the other type). `worldSockets`/`socketWorldPosition` expand a piece's sockets to world space. |
+| `solveSupport(pieces, links, { maxDistance })` → `SupportResult` | Walks the connector graph to any `grounded` piece: `supported` stays, `unsupported` collapses, `distance` (hops-to-ground) drives the white→red decay tint. `toDebrisBodies(pieces, unsupported)` → `AddBodyOptions[]` for the `PhysicsWorld` debris sink. |
+| `createWallDrawTool({ snap, closeTolerance })` | Drag wall points → auto-encloses when the path returns to the start (`isEnclosed`), `footprint()` derives the room `EnclosedFootprint`, `roof()` auto-fits a hip/gable/flat `RoofPlan`. `createSurfacePaint()` stores per-tile floor/wall surfaces. |
+| `createPlacedStructureStore()` | Save/load a built layout: `add`/`move`/`rotate`/`remove`/`select`, `snapshot()`↔`load()` round-trip (survives reload), `subscribe` for the renderer. |
+| `createEditableTerrain({ bounds, base, cellSize })` → `EditableTerrain` | A `TerrainField` you can **write back to**: `apply(edit: TerraformEdit)` raises/lowers/flattens/paints under a cursor and re-samples `sampleHeight`; `surfaceAt`, `snapshot`/`restore`, `reset`. `createTerraformBrush(field)` is the cursor tool (`raise`/`lower`/`flatten`/`paint`, radius/strength). This write-back grid is the shared terrain-edit pattern. |
+| `createPlotPermissions({ plotId, ownerId, guildId? })` + `createContributionPool(goal)` | Per-plot/guild edit authority (`canEdit`/`canView`, `grant`/`revoke` `BuildRole`, guild inheritance) for co-op building, plus a pooled-resource contribution model (`contribute` caps at the goal, reports overflow, `isComplete`, per-contributor totals). |
+
+### Physics world (optional, headless)
+
+`physics/physicsWorld` `PhysicsWorld` is a standalone fixed-capacity rigid-body sim (SoA buffers, spatial-hash broadphase, sleeping) — **not** the `defineGame` `physics: { gravity, jumpVelocity }` field, which the built-in walk controller reads directly every frame (see "Controller kinematics" above; both values are real and honored, not dead config). Reach for `PhysicsWorld` when a game needs many colliding dynamic bodies (piles, debris, stress scenes): `new PhysicsWorld({ capacity, bounds, … })`, `addBody({ position, mass?, ...shape })`, then `step(dt)` per tick → `PhysicsStats`. Core owns the sim; `@jgengine/shell/world/InstancedBodies` renders its bodies. Most games never need it — the character controller covers ordinary movement. The broadphase grid (`nx*ny*nz` cells from `bounds`/`cellSize`) throws at construction if it would exceed a sane cell cap — shrink `bounds` or raise `cellSize` (same guard on `physics/spatialGrid`'s `SpatialGrid`).
+
+**Body shape: box or sphere.** `AddBodyOptions` is a discriminated union — `{ shape?: "box", halfExtents }` (box is the default, `shape` omittable) or `{ shape: "sphere", radius }` (the radius fills all three half-extent columns, so broadphase/bounds see the sphere's enclosing AABB). `world.shape[i]` (`SHAPE_BOX` / `SHAPE_SPHERE`) reports a live body's shape for a consumer walking the raw SoA arrays. Sphere-sphere and sphere-box pairs resolve with a proper radial normal (not the axis-aligned box/box path) — balls, projectile bodies, and rolling debris collide correctly against both boxes and each other.
+
+**Collision shapes are box/sphere/voxel only.** Every collider in the engine — `PhysicsWorld` bodies (box `halfExtents` or sphere `radius`), object/entity picking (`scene/objectQuery` raycasts against unit boxes), and `world/voxelField`/`world/carve` blocks — is an axis-aligned box, a sphere, or a voxel cell. Arbitrary authored level-mesh collision (a sculpted GLB as a collider) is not supported. The seams for custom collision are `movement.beforeCommit` (steer or replace the walk controller's resolved step) and object raycasts (query the scene yourself and react) — not a mesh collider.
+
+**Ballistic collision sweep (`physics/ballisticSweep`).** `createBallisticSweep(world, { step?, radius? })` → `BallisticSweep`, a `(origin, velocity, gravity, maxTime) => BallisticSweepHit | null` function that marches the closed-form arc (constant gravity, straight lateral) through a `PhysicsWorld` and reports the first sample inside any live body's AABB (sleeping bodies included), refined by one bisection step; `null` means the whole arc is clear. `step` (default 1/60) is the march interval in seconds, `radius` (default 0) inflates every body's AABB before the point test — pass the projectile's own radius. Wire it into `combat/projectiles` via `ProjectileSystemDeps.sweepBallistic`: when set, a ballistic shot settles at the swept impact point instead of the closed-form landing; omitted or `null` falls back to that closed-form arc.
+
+**Removing and moving bodies.** `removeBody(id)` tombstones a body — it drops out of integration/broadphase and its slot is queued for the next `addBody` — without moving or invalidating any other body's `id` (ids are raw SoA slots, stored as-is in joints and game state, so nothing ever gets swapped). It conservatively wakes any sleeping body whose AABB touched the removed one's (no persistent contact set to consult, so this errs toward waking too much, never too little). `setVelocity(id, x, y, z)` and `setPosition(id, x, y, z)` write a body's velocity/position directly (instead of poking the public `velX`/`posX` SoA arrays) and wake it if asleep; `teleport(id, x, y, z)` is `setPosition` plus a hard velocity reset (respawn/teleporter, vs. sliding). `isAlive(id)`/`highWater` (one past the highest slot ever handed out) let a consumer that iterates the raw SoA arrays skip tombstoned holes correctly instead of assuming `count` is a dense `0..count` range.
+
+**Joints & constraints.** `hingeJoint`/`fixedJoint`/`distanceJoint`/`springJoint(opts)` connect two bodies, or a body to a fixed world point (omit `bodyB`). The sim is translational (no angular DOF), so `hinge`/`fixed` pin the shared anchor (the `axis` is retained metadata), `distance` holds a fixed separation, and `spring` drives toward `restLength` with `stiffness`/`damping` (suspension, follow-point carry). `removeJoint(id)`, `setJointAnchor(id, x, y, z)` (move anchor B — a world anchor's follow point, or body B's local offset), `setJointAnchorA(id, x, y, z)` (move anchor A's local offset — e.g. re-rotating a suspension mount each frame as the chassis turns), `setJointRest`, and `readJointSegments(out)` for `@jgengine/shell/world/InstancedJoints` (debug line render). This is the foundation under vehicles, ragdolls, grapples, and carry.
+
+**Collision → gameplay events.** `world.onCollision(listener, minApproachSpeed?)` delivers every impacting contact — `CollisionEvent { a, b, nx, ny, nz, approachSpeed, impulse }` — to game code during `step` (the object is reused; read/copy it, never retain). This is the seam crash-damage and destruction read; pass `null` to detach.
+
+**Actors on top of the sim:** `physics/ragdoll` (`createRagdoll(world, { bones, links, balance? })` — jointed bones, floppy or active-ragdoll via a balance motor), `physics/carryable` (`Carryable` — grab a body to a follow point, shared multi-owner carry, `carrySpeedMultiplier` encumbrance, drop/throw; the raycast pick is the caller's job, core owns the constraint), `physics/forceVolume` (`ForceVolume` — impulse/velocity/accelerate trigger region, `once` for boost pads; `PlatformCarry` — carry bodies standing on a moving platform by its per-`step` delta). Separately, `physics/spatialGrid` `SpatialGrid` is a broad-phase grid over the x/z plane, **distinct** from the rigid-body sim, for cheap same-tick proximity across hundreds–thousands of simple movers — `rebuild(count, xs, zs)` then `queryCircle` (swarm enemies hitting a player/AoE) or `forEachPair` (mutual separation).
+
+**Traversal (`physics/traversal`).** `Grapple` fires a rope from a body to a fixed world point on the joint API — `fire(x,y,z)` attaches a `distance` (rigid) or `elastic` (spring) joint, `reel(dt)`/`payOut(dt)` shorten/lengthen the rope to pull the traveller in, `moveAnchor` re-points it (ziplines, grapple-to-moving-target). Grapple/zipline/swing (Sekiro, Deep Rock, Just Cause) are all the same primitive; the raycast that finds the anchor is the caller's. `Glide` is a reduced-gravity, forward-thrust wingsuit/glider over a body — call `apply(dt, steerX, steerZ)` each frame before `step` to feed back most of gravity (`gravityScale`), thrust along the steer vector, and clamp descent; stop calling it to fall normally, no attach/detach state.
+**Structural destruction (`physics/structure`).** `StructureGraph` models a building as nodes (pieces) + load-bearing edges with some nodes `anchor`ed (foundations). `damage(id, n)`/`damageEdge(a,b,n)`/`severEdge(a,b)` wear pieces and connections; when one breaks, the graph recomputes reachability to an anchor and returns a single `CollapseEvent { fell }` — every piece the loss disconnected. `toDebris(world, event)` sinks the fallen pieces into a `PhysicsWorld` as rigid bodies (The Finals, Rainbow Six). It is coarse by design: **replicate the collapse event (the `fell` id list), not each fragment's physics** — game clients re-derive the debris locally. Piece integrity and edge strength default from a `StructureMaterial` table (DATA).
+### Vehicles, mounts, crash damage & racing
+Five primitives layer a driving/racing game over the physics sim and `world/water`. All are **data-first** (spec the chassis/wheels/grip curve, damage thresholds, and checkpoint layout as catalog data) and pure `@jgengine/core`; renderers live in the game/shell. Each `update(dt, …)` runs **before** the shared `world.step(dt)`.
+- **Analog input — `input/axisInput`.** `AxisInput { throttle, brake, steer, handbrake }` is a continuous channel, **distinct from the digital action bindings**. `new AxisChannel({ bindings, smoothing })` ramps held keys into pedal-like analog values (`sample(dt, isDown)`), or `setAnalog(axis, value)` drives it straight from a gamepad axis. `DRIVE_AXIS_BINDINGS` is a ready WASD/arrow map.
+- **`physics/vehicleBody`.** `createVehicleBody(world, config)` is an arcade car: a chassis box body with per-wheel suspension held by G3's `springJoint` against the sampled `groundHeight`, drive/brake along the heading, and a `GripCurve` (`sampleGripCurve`) that bleeds lateral velocity for cornering — and, under `handbrake`, drift. `update(dt, axisInput)` then `world.step`. Because the chassis is a real body it still collides, which feeds crash damage. Rocket League, Trackmania, Wreckfest.
+- **`physics/buoyancy`.** `createBuoyantBody(world, { body, water, … })` floats a body on a CPU `WaterSurface` (Archimedes per hull point + water drag) so it settles at the waterline and rides the Gerstner waves; pass an `AxisInput` to `update(dt, time, input?)` and it drives as a boat (thrust + yaw + keel). Sea of Thieves, BOTW rafts.
+- **`scene/mount`.** `createMountController()` transfers control to a driven entity: `register({ id, kit, seats })`, `mount(riderId, mountId, seatId?)`, `dismount`. Read `cameraTarget(riderId)` to point the follow camera and `driveTarget(riderId)` to route that rider's `AxisInput` at the mount — the control seat drives, passenger seats ride (multi-seat shared vehicles), and an un-mounted rider drives themselves. `driver(mountId)`/`occupants(mountId)`/`kitOf`. Palworld mounts, V Rising horse, a crewed ship.
+- **`scene/stationClaim`.** `createStationClaim(controller?)` layers **facet stations** on `scene/mount` for a vehicle several players crew at once: `register({ id, kit, stations })` where each `Station` tags a seat with a `facet` (`"steer"`/`"sails"`/`"cannon"`). `claim(playerId, vehicleId, facetOrStationId)`, `release`, `controllerOf(vehicleId, facet)` (who mans it), `facetOf(playerId)`, `openFacets`, `crew`. Only a `control` station operates the hull (`driver`/`driveTarget`); the rest ride but command their own facet. Sea of Thieves helm + sails + cannons.
+- **`physics/damageZones`.** `createDamageModel({ zones, disableAt })` maps accumulated contact impulse (from `onCollision`) to **coarse discrete stages** (not soft-body): `absorb(zoneId, impulse)` / `routeCollision(event, resolveZone)` bump a zone's stage (caller swaps the visual/collider), an optional `detachStage` ejects a part as debris once, and crossing `disableAt` flips a whole-vehicle `disabled` state. Wreckfest crumple/derby.
+- **`game/race`.** `raceTrack({ checkpoints, laps })` is an ordered ring of AABB checkpoint volumes (the final one is the finish line); `createRaceState({ track, win })` — driven each tick by `update(now, positions)` on game time — emits `checkpoint.hit` / `lap.completed` / `position.changed` / `race.finished`, keeps split times, resolves a pluggable `RaceWinCondition` (`firstPastPost`, `topK` round-cut, `everyoneFinishes`, `lastStanding` derby), and `resetToCheckpoint(id)` hands back a respawn pose. `removeRacer(id)` drops a racer mid-race and renumbers the remaining standings; `reset()` clears all racer progress/finish state back to construction time so the same instance replays without rebuilding it. Trackmania, Mario Kart, Fall Guys.
+
+### Spawn placement
+
+`spawn(catalogId, { id?, position | anchor, offset?, parentSpace?, group? })` — anchor `{ kind: "entity" | "zone", id }` with offset `{ radius, pattern }` or `{ xyz }`. Catalog supplies movement/model; no behaviors on spawn.
+
+**Named spawn/respawn points** (`game/spawnPoints`) — `createSpawnPoints()`: `record(id, { x, y, z, rotationY? })` names a point (level bounds, team spawns, checkpoints), `get(id)`/`list()` read them back, `respawn(entities, entityId, spawnId)` teleports an existing entity to a recorded point via `setPose` in one call — the id-keyed alternative to threading raw coordinates through respawn logic by hand.
+
+**Level sequence** (`game/levelSequence`) — `createLevelSequence({ levels: [{ id, config }], retriesPerLevel? })` is a pure, deterministic campaign machine: `start()` enters level 0, `clear()` marks the current level cleared, `advance()` moves to the next (or `"complete"` after the last), `fail()` consumes an attempt and returns `"retry"` while `retriesPerLevel` remain else `"failed"`, `retry()` restarts after a retry-eligible failure. `current()` → `{ id, index, config, attempt } | null`; `progress()` → `{ index, total, cleared }`; `reset()` rewinds to idle. Mirrors the reducer style of `game/race` and `ai/spawnDirector` — a level-select/roguelike-run campaign shell without hand-rolling the state machine per game.