@jgengine/core 0.11.0 → 0.13.0

package/dist/game/defineGame.d.ts

@@ -13,7 +13,7 @@ import { type EntityStore } from "../scene/entityStore.js";
 import type { StoreHandle } from "../store/defineStore.js";
 import type { TimeConfig } from "../time/simClock.js";
 import type { WorldFeature } from "../world/features.js";
-/** Tunes offline whole-world save (`defineGame({ persist })`). Defaults: continuous `autosave` to `localStorage`, one slot, no version. */
+/** Tunes offline whole-world save (`defineGameDefinition({ persist })`). Offline games already autosave to `localStorage` by default — pass this only to tune it (or `persist: false` to opt out). Defaults: continuous `autosave` to `localStorage`, one slot, no version. */
 export interface PersistConfig {
     /** `"autosave"` (default) writes on a debounce after any change; `"manual"` writes only on `ctx.game.save.checkpoint()` (save points / quest triggers). */
     mode?: RuntimeSaveMode;
@@ -140,7 +140,7 @@ export interface LifecycleConfig<TState = unknown> {
         restart?: string;
     };
 }
-/** Fully-resolved game description produced by {@link defineGame} — assets, scene, and opted-in subsystems. */
+/** Fully-resolved game description produced by {@link defineGameDefinition} — assets, scene, and opted-in subsystems. */
 export interface GameDefinition<TAssetRef extends ModelAssetRef = ModelAssetRef, TMultiplayer = unknown> {
     name: string;
     assets: AssetCatalog<TAssetRef>;
@@ -156,7 +156,13 @@ export interface GameDefinition<TAssetRef extends ModelAssetRef = ModelAssetRef,
      * Classic `loop` hooks still run for incremental migration (systems tick first, then `loop.onTick`).
      */
     systems?: readonly SystemDefinition[];
+    /**
+     * The place this game happens in — preferred shape is `world()` from `@jgengine/core/world/place`
+     * (ground + per-place laws; dressing lives in the editor's scene document). Omit entirely for
+     * pure UI/rules games that are not a spatial place.
+     */
     world?: WorldFeature;
+    /** Game-level default physics laws; a place world's own `physics` resolves over this. */
     physics?: PhysicsConfig;
     /** Simulation clock: real→game time scale, selectable speeds, calendar. Exposed as `ctx.time`; the shell feeds its scaled dt to `loop.onTick`. */
     time?: TimeConfig;
@@ -165,8 +171,9 @@ export interface GameDefinition<TAssetRef extends ModelAssetRef = ModelAssetRef,
     inventories?: Record<string, InventoryDeclaration>;
     input?: ActionCodesMap;
     server?: GameServerConfig;
+    /** Hosted per-player save policy, read only by an authoritative multiplayer host. Solo games leave this unset (nothing persists by default) and use `persist` when they want a save at all. */
     save?: SaveConfig;
-    /** Offline/single-player whole-world save. `true` autosaves the entire game to `localStorage`; a config object tunes the mode/cadence/target. Binds `ctx.game.save` — the game drives save points and restore. Ignored for multiplayer worlds (the host persists). */
+    /** The one save knob for solo games: offline whole-world save. **On by default** — an offline game autosaves the entire world to `localStorage` and binds `ctx.game.save` with no config at all; the game only drives save points and restore (`ctx.game.save.load()` at boot). Pass `false` to opt out entirely, or a config object to tune the mode/cadence/target (`storage: "memory"` for in-session-only). Ignored for multiplayer worlds (the host persists via `save`). */
     persist?: boolean | PersistConfig;
     ui?: unknown;
     loop?: GameLoop<GameContext>;
@@ -180,14 +187,14 @@ export interface GameDefinition<TAssetRef extends ModelAssetRef = ModelAssetRef,
      */
     replication?: ReplicationPolicy;
 }
-/** Input to {@link defineGame} — a `GameDefinition` with `scene` derived and `assets` optional. */
+/** Input to {@link defineGameDefinition} — a `GameDefinition` with `scene` derived and `assets` optional. */
 export type GameDefinitionConfig<TAssetRef extends ModelAssetRef = ModelAssetRef, TMultiplayer = unknown> = Omit<GameDefinition<TAssetRef, TMultiplayer>, "scene" | "assets"> & {
     assets?: AssetCatalog<TAssetRef>;
 };
 /**
- * Task-first entry point for authoring a game: fills in `scene` and default `assets`, validates `name`,
- * OR-merges `features` from installed systems, and composes `loop` from `systems` + any classic hooks.
- *
- * @capability define-game single public game-authoring path — compose systems, world, and loop in one definition
+ * Host-level constructor for a bare `GameDefinition`: fills in `scene` and default `assets`, validates
+ * `name`, OR-merges `features` from installed systems, and composes `loop` from `systems` + any classic
+ * hooks. Games author through `defineGame` from `@jgengine/shell/defineGame`, which calls this and adds
+ * the presentation layer; call this directly only from headless hosts that mount no shell.
  */
-export declare function defineGame<TAssetRef extends ModelAssetRef, TMultiplayer>(config: GameDefinitionConfig<TAssetRef, TMultiplayer>): GameDefinition<TAssetRef, TMultiplayer>;
+export declare function defineGameDefinition<TAssetRef extends ModelAssetRef, TMultiplayer>(config: GameDefinitionConfig<TAssetRef, TMultiplayer>): GameDefinition<TAssetRef, TMultiplayer>;

package/dist/game/defineGame.js

@@ -2,6 +2,7 @@ import { mergeSystemFeatures } from "./defineSystem.js";
 import { composeGameLoop } from "./systemRuntime.js";
 import { createAssetCatalog } from "../scene/assetCatalog.js";
 import { createEntityStore } from "../scene/entityStore.js";
+import { resolveWorldPhysics } from "../world/place.js";
 /** @internal */
 export function createDisposer() {
     const cleanups = [];
@@ -25,19 +26,26 @@ export function createDisposer() {
     };
 }
 /**
- * Task-first entry point for authoring a game: fills in `scene` and default `assets`, validates `name`,
- * OR-merges `features` from installed systems, and composes `loop` from `systems` + any classic hooks.
- *
- * @capability define-game single public game-authoring path — compose systems, world, and loop in one definition
+ * Host-level constructor for a bare `GameDefinition`: fills in `scene` and default `assets`, validates
+ * `name`, OR-merges `features` from installed systems, and composes `loop` from `systems` + any classic
+ * hooks. Games author through `defineGame` from `@jgengine/shell/defineGame`, which calls this and adds
+ * the presentation layer; call this directly only from headless hosts that mount no shell.
  */
-export function defineGame(config) {
+export function defineGameDefinition(config) {
     if (config.name.trim().length === 0) {
-        throw new Error("defineGame: name must be non-empty");
+        throw new Error("defineGameDefinition: name must be non-empty");
     }
+    // Boolean `features: { quest: true }` is sugar for the same activation map systems produce via
+    // `feature: "quest"`. Both OR-merge here; `createGameContext` only reads this final map through
+    // featureDescriptors.enabled — one enable path, no dual checks at install time.
     const features = mergeSystemFeatures(config.features, config.systems);
     const loop = composeGameLoop(config.systems, config.loop);
+    // A place world carries the laws of that place: its physics resolves over the game-level default,
+    // so every consumer of definition.physics (movement, combat, shell) sees the active world's laws.
+    const physics = resolveWorldPhysics(config.world, config.physics);
     return {
         ...config,
+        ...(physics === undefined ? {} : { physics }),
         features,
         loop,
         scene: createEntityStore(),

package/dist/game/defineSystem.d.ts

@@ -78,6 +78,8 @@ export interface SystemDefinition {
 /**
  * Declare a composable game system. Pure data + hooks — the engine compiles the schedule and
  * installs lifecycle when the game boots.
+  *
+ * @capability define-system composable game behavior — pure data + hooks the engine schedules; pass via `defineGame({ systems })`
  */
 export declare function defineSystem(definition: SystemDefinition): SystemDefinition;
 /** Collect feature flags implied by a system list (OR-merge; installing a system activates its capability).

package/dist/game/defineSystem.js

@@ -1,6 +1,8 @@
 /**
  * Declare a composable game system. Pure data + hooks — the engine compiles the schedule and
  * installs lifecycle when the game boots.
+  *
+ * @capability define-system composable game behavior — pure data + hooks the engine schedules; pass via `defineGame({ systems })`
  */
 export function defineSystem(definition) {
     if (definition.id.trim().length === 0) {

package/dist/game/events.d.ts

@@ -191,6 +191,31 @@ export interface AudioMusicEvent {
     theme: string | null;
     transpose?: number;
 }
+/**
+ * Start (or idempotently keep) the retained, id-keyed audio loop `id` from catalog `sound`, optionally
+ * anchored at world `at`. Restarting with the same `sound` does not restart the source (no click); a
+ * different `sound` replaces it. Drives RPM-pitched engine loops and slip-scaled tire squeal (#1051).
+ */
+export interface AudioLoopStartEvent {
+    id: string;
+    sound: string;
+    at?: readonly [number, number, number];
+}
+/**
+ * Live-update the retained loop `id`: `rate` re-pitches it (1 = authored, the shell clamps to 0.25–4),
+ * `gain` rescales its volume (0–1), and `at` repositions its emitter. Emitted every tick to track a
+ * live signal (RPM, tire slip); the shell smooths rate/gain and ignores an unknown `id` (#1051).
+ */
+export interface AudioLoopSetEvent {
+    id: string;
+    rate?: number;
+    gain?: number;
+    at?: readonly [number, number, number];
+}
+/** Stop and dispose the retained loop `id`; an unknown `id` is ignored (#1051). */
+export interface AudioLoopStopEvent {
+    id: string;
+}
 export interface GameEventMap {
     "entity.died": EntityDiedEvent;
     "entity.floatText": EntityFloatTextEvent;
@@ -221,6 +246,9 @@ export interface GameEventMap {
     "audio.play": AudioPlayEvent;
     "audio.music": AudioMusicEvent;
     "audio.resume": AudioResumeEvent;
+    "audio.loopStart": AudioLoopStartEvent;
+    "audio.loopSet": AudioLoopSetEvent;
+    "audio.loopStop": AudioLoopStopEvent;
     "entity.animation": EntityAnimationEvent;
 }
 export type GameEventHandler<TPayload> = (payload: TPayload) => void;

package/dist/game/partAnimation.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Procedural animation for part-composed (rig-less) models — characters kit-bashed from
+ * primitives/`ModelPart`s with no skeleton or clips. Pure, deterministic curve sampling:
+ * the same (time, speed, phase, flinch, death) input always yields the same pose, so
+ * replays and multi-client renders stay in lockstep and the hot path allocates nothing
+ * when an `out` pose is reused.
+ */
+/** Semantic motion role of one `ModelPart` in a part-composed character. */
+export type PartRole = "head" | "arm.l" | "arm.r" | "leg.l" | "leg.r" | "tail" | "wing.l" | "wing.r";
+/** Tuning for {@link samplePartPose}/{@link sampleBodyPose}; every field has a sensible default. */
+export interface PartMotionParams {
+    /** Full stride cycles per second at walking speed. Default 1.6. */
+    strideHz?: number;
+    /** Limb swing amplitude in radians at full walk. Default 0.7. */
+    swingRad?: number;
+    /** Body bob height in model units at full walk. Default 0.04. */
+    bobAmp?: number;
+    /** Idle sway/breathe amplitude in radians. Default 0.05. */
+    swayRad?: number;
+    /** Speed (world units/sec) treated as a full walk; swing/bob scale linearly below it. Default 2. */
+    walkSpeed?: number;
+    /** Backward flinch pitch in radians at flinch = 1. Default 0.35. */
+    flinchRad?: number;
+    /** Sideways topple roll in radians at death = 1. Default PI / 2. */
+    toppleRad?: number;
+    /**
+     * Squash-and-stretch amplitude for soft characters (blobs, slimes): footfall squash while
+     * walking, jelly breathe while idle, a squash pulse on flinch. Volume-conserving — the body
+     * bulges horizontally as it compresses. Default 0 (rigid; scale stays exactly 1).
+     */
+    squashAmp?: number;
+    /** How death reads: `"topple"` rolls sideways (default, hard characters); `"splat"` flattens the body out — right for blobs. */
+    deathStyle?: "topple" | "splat";
+}
+/** Sampled offsets to add onto a part's authored transform (or the character root). `scale` is multiplicative (1 = unchanged). */
+export interface PartPose {
+    position: [number, number, number];
+    rotation: [number, number, number];
+    scale: [number, number, number];
+}
+/** Live signals a driver feeds the samplers each frame. All values are render-side only. */
+export interface PartMotionInput {
+    /** Seconds since the driver started (any monotonic clock). */
+    timeSec: number;
+    /** Horizontal speed in world units/sec (smoothed by the driver). */
+    speed: number;
+    /** Per-character phase offset in [0, 1) so crowds don't stride in sync — see {@link partMotionPhase}. */
+    phase: number;
+    /** Hit-flinch envelope in [0, 1]; the driver sets 1 on a hit and decays it. */
+    flinch: number;
+    /** Death ramp in [0, 1]; the driver eases it to 1 after the entity dies. */
+    death: number;
+}
+/** A reusable identity pose (zero offsets, unit scale). */
+export declare function createPartPose(): PartPose;
+/**
+ * Deterministic per-character stride phase in [0, 1) from an id (e.g. the entity instance id),
+ * so a crowd of identical part-composed characters doesn't animate in lockstep.
+ */
+export declare function partMotionPhase(id: string): number;
+/**
+ * Sample the character-root pose: walk bob, idle breathe/sway, backward hit flinch, and death —
+ * a sideways topple by default, or a flatten-out splat with `deathStyle: "splat"`. With
+ * `squashAmp > 0` the body also squashes and stretches (footfall squash, jelly idle breathe,
+ * flinch squash pulse), volume-conserving. A driver applies this to the group wrapping the
+ * whole composition (base model plus parts) — limbs ride along, as they would on a real torso.
+ *
+ * @capability part-motion sample the root bob/sway/squash/flinch/death pose for a rig-less part-composed character
+ */
+export declare function sampleBodyPose(input: PartMotionInput, params?: PartMotionParams, out?: PartPose): PartPose;
+/**
+ * Sample one part's pose offset by role: counter-phase leg/arm swing driven by speed, a head
+ * counter-sway, tail wag, and wing flap. Offsets are added onto the part's authored
+ * position/rotation. Motion fades to zero as `death` ramps so the topple reads as one piece.
+ *
+ * @capability part-motion sample a limb/head/tail/wing pose offset for a role-tagged ModelPart
+ */
+export declare function samplePartPose(role: PartRole, input: PartMotionInput, params?: PartMotionParams, out?: PartPose): PartPose;

package/dist/game/partAnimation.js

@@ -0,0 +1,147 @@
+/**
+ * Procedural animation for part-composed (rig-less) models — characters kit-bashed from
+ * primitives/`ModelPart`s with no skeleton or clips. Pure, deterministic curve sampling:
+ * the same (time, speed, phase, flinch, death) input always yields the same pose, so
+ * replays and multi-client renders stay in lockstep and the hot path allocates nothing
+ * when an `out` pose is reused.
+ */
+const DEFAULT_STRIDE_HZ = 1.6;
+const DEFAULT_SWING_RAD = 0.7;
+const DEFAULT_BOB_AMP = 0.04;
+const DEFAULT_SWAY_RAD = 0.05;
+const DEFAULT_WALK_SPEED = 2;
+const DEFAULT_FLINCH_RAD = 0.35;
+const DEFAULT_TOPPLE_RAD = Math.PI / 2;
+const IDLE_BREATHE_HZ = 0.45;
+const TWO_PI = Math.PI * 2;
+function clamp01(value) {
+    return value < 0 ? 0 : value > 1 ? 1 : value;
+}
+function zeroPose(out) {
+    out.position[0] = 0;
+    out.position[1] = 0;
+    out.position[2] = 0;
+    out.rotation[0] = 0;
+    out.rotation[1] = 0;
+    out.rotation[2] = 0;
+    out.scale[0] = 1;
+    out.scale[1] = 1;
+    out.scale[2] = 1;
+    return out;
+}
+/** Volume-conserving vertical squash: compress y by `amount`, bulge x/z by half of it. */
+function applySquash(out, amount) {
+    out.scale[1] *= 1 - amount;
+    const bulge = 1 + amount * 0.5;
+    out.scale[0] *= bulge;
+    out.scale[2] *= bulge;
+}
+/** A reusable identity pose (zero offsets, unit scale). */
+export function createPartPose() {
+    return { position: [0, 0, 0], rotation: [0, 0, 0], scale: [1, 1, 1] };
+}
+/**
+ * Deterministic per-character stride phase in [0, 1) from an id (e.g. the entity instance id),
+ * so a crowd of identical part-composed characters doesn't animate in lockstep.
+ */
+export function partMotionPhase(id) {
+    let hash = 0;
+    for (let index = 0; index < id.length; index += 1)
+        hash = (hash * 31 + id.charCodeAt(index)) >>> 0;
+    return (hash % 1000) / 1000;
+}
+const SPLAT_FLATTEN = 0.7;
+/**
+ * Sample the character-root pose: walk bob, idle breathe/sway, backward hit flinch, and death —
+ * a sideways topple by default, or a flatten-out splat with `deathStyle: "splat"`. With
+ * `squashAmp > 0` the body also squashes and stretches (footfall squash, jelly idle breathe,
+ * flinch squash pulse), volume-conserving. A driver applies this to the group wrapping the
+ * whole composition (base model plus parts) — limbs ride along, as they would on a real torso.
+ *
+ * @capability part-motion sample the root bob/sway/squash/flinch/death pose for a rig-less part-composed character
+ */
+export function sampleBodyPose(input, params, out = createPartPose()) {
+    zeroPose(out);
+    const walkSpeed = params?.walkSpeed ?? DEFAULT_WALK_SPEED;
+    const strideHz = params?.strideHz ?? DEFAULT_STRIDE_HZ;
+    const bobAmp = params?.bobAmp ?? DEFAULT_BOB_AMP;
+    const swayRad = params?.swayRad ?? DEFAULT_SWAY_RAD;
+    const squashAmp = params?.squashAmp ?? 0;
+    const death = clamp01(input.death);
+    const alive = 1 - death;
+    const walk = clamp01(input.speed / walkSpeed) * alive;
+    const idle = (1 - walk) * alive;
+    const stride = TWO_PI * (input.timeSec * strideHz + input.phase);
+    const breathe = TWO_PI * (input.timeSec * IDLE_BREATHE_HZ + input.phase);
+    const step = Math.abs(Math.sin(stride));
+    // Double-bounce bob: the body rises on each step, twice per stride cycle.
+    out.position[1] = step * bobAmp * walk + Math.sin(breathe) * bobAmp * 0.5 * idle;
+    out.rotation[2] = Math.sin(breathe) * swayRad * idle;
+    out.rotation[0] = -clamp01(input.flinch) * (params?.flinchRad ?? DEFAULT_FLINCH_RAD) * alive;
+    if (squashAmp > 0) {
+        // Footfall squash: deepest where the bob is lowest (step ≈ 0), released at the top of the step.
+        applySquash(out, (1 - step) * squashAmp * walk);
+        // Jelly breathe: idle scale oscillation, gentler than a footfall.
+        applySquash(out, Math.sin(breathe) * squashAmp * 0.4 * idle);
+        // Flinch reads as a squash pulse on a soft body.
+        applySquash(out, clamp01(input.flinch) * squashAmp * alive);
+    }
+    if ((params?.deathStyle ?? "topple") === "splat") {
+        applySquash(out, death * SPLAT_FLATTEN);
+    }
+    else {
+        out.rotation[2] += death * (params?.toppleRad ?? DEFAULT_TOPPLE_RAD);
+    }
+    return out;
+}
+/**
+ * Sample one part's pose offset by role: counter-phase leg/arm swing driven by speed, a head
+ * counter-sway, tail wag, and wing flap. Offsets are added onto the part's authored
+ * position/rotation. Motion fades to zero as `death` ramps so the topple reads as one piece.
+ *
+ * @capability part-motion sample a limb/head/tail/wing pose offset for a role-tagged ModelPart
+ */
+export function samplePartPose(role, input, params, out = createPartPose()) {
+    zeroPose(out);
+    const walkSpeed = params?.walkSpeed ?? DEFAULT_WALK_SPEED;
+    const strideHz = params?.strideHz ?? DEFAULT_STRIDE_HZ;
+    const swingRad = params?.swingRad ?? DEFAULT_SWING_RAD;
+    const swayRad = params?.swayRad ?? DEFAULT_SWAY_RAD;
+    const alive = 1 - clamp01(input.death);
+    const walk = clamp01(input.speed / walkSpeed) * alive;
+    const idle = (1 - walk) * alive;
+    const stride = TWO_PI * (input.timeSec * strideHz + input.phase);
+    const breathe = TWO_PI * (input.timeSec * IDLE_BREATHE_HZ + input.phase);
+    switch (role) {
+        case "leg.l":
+            out.rotation[0] = Math.sin(stride) * swingRad * walk;
+            break;
+        case "leg.r":
+            out.rotation[0] = Math.sin(stride + Math.PI) * swingRad * walk;
+            break;
+        case "arm.l":
+            // Arms counter their same-side leg, at slightly lower amplitude.
+            out.rotation[0] = Math.sin(stride + Math.PI) * swingRad * 0.8 * walk;
+            out.rotation[2] = Math.sin(breathe) * swayRad * idle;
+            break;
+        case "arm.r":
+            out.rotation[0] = Math.sin(stride) * swingRad * 0.8 * walk;
+            out.rotation[2] = -Math.sin(breathe) * swayRad * idle;
+            break;
+        case "head":
+            out.rotation[2] = -Math.sin(breathe) * swayRad * idle;
+            out.rotation[1] = Math.sin(stride) * swayRad * 0.5 * walk;
+            out.rotation[0] = -clamp01(input.flinch) * 0.5 * (params?.flinchRad ?? DEFAULT_FLINCH_RAD) * alive;
+            break;
+        case "tail":
+            out.rotation[1] = Math.sin(stride) * swingRad * 0.5 * walk + Math.sin(breathe) * swayRad * 2 * idle;
+            break;
+        case "wing.l":
+            out.rotation[2] = Math.abs(Math.sin(stride)) * swingRad * walk + Math.sin(breathe) * swayRad * idle;
+            break;
+        case "wing.r":
+            out.rotation[2] = -Math.abs(Math.sin(stride)) * swingRad * walk - Math.sin(breathe) * swayRad * idle;
+            break;
+    }
+    return out;
+}