@jgengine/core 0.9.0 → 0.10.0

package/dist/index.js

@@ -1,5 +1,12 @@
 export * from "./runtime/save.js";
 export * from "./runtime/snapshot.js";
+export * from "./runtime/worldSnapshot.js";
+export * from "./runtime/worldReplication.js";
+export * from "./game/connectedPlayers.js";
+export * from "./runtime/hostedGameRunner.js";
+export * from "./runtime/hostedWorldSession.js";
+export * from "./runtime/worldMirror.js";
+export * from "./runtime/worldChannel.js";
 export * from "./runtime/commandRunner.js";
 export * from "./runtime/gameRuntime.js";
 export * from "./runtime/adapter.js";

package/dist/input/actionBindings.d.ts

@@ -29,6 +29,7 @@ export type ActionCodes<TCode extends string = string> = readonly TCode[] | {
     toggle?: readonly TCode[];
     repeatMs?: number;
 };
+/** Maps each game action name to the input codes (hold/toggle keys, repeat rate) that trigger it. */
 export type ActionCodesMap<TAction extends string = string, TCode extends string = string> = Record<TAction, ActionCodes<TCode>>;
 export declare function actionRepeatMs(codes: ActionCodes | undefined): number | undefined;
 export interface ShouldDispatchActionInput {
@@ -53,6 +54,7 @@ export declare function isHotbarSlotAction(action: string): boolean;
  * yield null so the shell can handle them itself.
  */
 export declare function resolveActionCommand(action: string, has: (command: string) => boolean, reserved: ReadonlySet<string>): string | null;
+/** Short display label for a raw key/button code (e.g. `"KeyW"` → `"W"`). */
 export declare function bindingLabel(code: string): string;
 /** Short display label for an action's first bound code, or null when unbound. */
 export declare function actionLabel(map: ActionCodesMap, action: string): string | null;

package/dist/input/actionBindings.js

@@ -127,6 +127,7 @@ const CODE_LABELS = {
     ArrowLeft: "←",
     ArrowRight: "→",
 };
+/** Short display label for a raw key/button code (e.g. `"KeyW"` → `"W"`). */
 export function bindingLabel(code) {
     const direct = CODE_LABELS[code];
     if (direct !== undefined)

package/dist/input/axisInput.d.ts

@@ -63,4 +63,11 @@ export interface GenericAxisChannel<TAxes extends string> {
     reset(): void;
     readonly value: Record<TAxes, number>;
 }
+/**
+ * Instantaneous (unsmoothed) analog sample of an axis binding map — the per-frame target an
+ * `AxisChannel` ramps toward, exposed as a pure read for `ctx.input.axis` and headless sampling.
+ * Each axis is its binding's positive-minus-negative held state (or its pointer source while a pointer
+ * is active), clamped to the axis range; axes without a listed range default to bipolar `[-1, 1]`.
+ */
+export declare function sampleAxisBindings<TAxes extends string>(bindings: Record<TAxes, AxisBinding>, isDown: (code: string) => boolean, pointer?: PointerAxisState | null, ranges?: Partial<Record<TAxes, AxisRange>>): Record<TAxes, number>;
 export declare function createAxisChannel<TAxes extends string>(config: GenericAxisConfig<TAxes>): GenericAxisChannel<TAxes>;

package/dist/input/axisInput.js

@@ -75,6 +75,22 @@ export const DRIVE_AXIS_BINDINGS = {
     handbrake: { positive: ["Space"] },
 };
 const BIPOLAR_RANGE = { min: -1, max: 1 };
+/**
+ * Instantaneous (unsmoothed) analog sample of an axis binding map — the per-frame target an
+ * `AxisChannel` ramps toward, exposed as a pure read for `ctx.input.axis` and headless sampling.
+ * Each axis is its binding's positive-minus-negative held state (or its pointer source while a pointer
+ * is active), clamped to the axis range; axes without a listed range default to bipolar `[-1, 1]`.
+ */
+export function sampleAxisBindings(bindings, isDown, pointer, ranges) {
+    const out = {};
+    for (const axis of Object.keys(bindings)) {
+        const binding = bindings[axis];
+        const range = ranges?.[axis] ?? BIPOLAR_RANGE;
+        const fromPointer = binding.pointer === undefined ? null : pointerAxisValue(binding.pointer, pointer ?? null);
+        out[axis] = clampAxis(fromPointer ?? digitalTarget(binding, isDown), range);
+    }
+    return out;
+}
 export function createAxisChannel(config) {
     const axes = Object.keys(config.bindings);
     const smoothing = config.smoothing ?? 6;

package/dist/interaction/contextMenu.d.ts

@@ -7,6 +7,7 @@ export interface ContextVerb {
     /** Greyed-out and non-dispatchable when true (e.g. requirement unmet). */
     disabled?: boolean;
 }
+/** Builds a {@link ContextVerb} for a right-click menu entry. */
 export declare function contextVerb(label: string, command: string, args?: Record<string, unknown>): ContextVerb;
 export interface ContextMenu {
     kind: ContextTargetKind;

package/dist/interaction/contextMenu.js

@@ -1,3 +1,4 @@
+/** Builds a {@link ContextVerb} for a right-click menu entry. */
 export function contextVerb(label, command, args) {
     return args === undefined ? { label, command } : { label, command, args };
 }

package/dist/interaction/proximityPrompt.d.ts

@@ -5,6 +5,8 @@ export interface PromptPoint {
 export interface KeybindPromptDisplay {
     kind: "keybind";
     actionId: string;
+    /** What the interaction does, shown beside the key glyph (e.g. `"Open Chest"`, `"Talk"`); omit for key-only. */
+    label?: string;
 }
 export interface GaugePromptDisplay {
     kind: "gauge";
@@ -15,7 +17,7 @@ export interface LabelPromptDisplay {
     text: string;
 }
 export type ProximityPromptDisplay = KeybindPromptDisplay | GaugePromptDisplay | LabelPromptDisplay;
-export declare function keybind(actionId: string): KeybindPromptDisplay;
+export declare function keybind(actionId: string, label?: string): KeybindPromptDisplay;
 export declare function gauge(gaugeId: string): GaugePromptDisplay;
 export declare function label(text: string): LabelPromptDisplay;
 export interface PromptCommand {

package/dist/interaction/proximityPrompt.js

@@ -1,5 +1,5 @@
-export function keybind(actionId) {
-    return { kind: "keybind", actionId };
+export function keybind(actionId, label) {
+    return label === undefined ? { kind: "keybind", actionId } : { kind: "keybind", actionId, label };
 }
 export function gauge(gaugeId) {
     return { kind: "gauge", gaugeId };
@@ -39,7 +39,7 @@ export function promptDisplaysEqual(a, b) {
     if (a === b)
         return true;
     if (a.kind === "keybind")
-        return b.kind === "keybind" && a.actionId === b.actionId;
+        return b.kind === "keybind" && a.actionId === b.actionId && a.label === b.label;
     if (a.kind === "gauge")
         return b.kind === "gauge" && a.gaugeId === b.gaugeId;
     return b.kind === "label" && a.text === b.text;

package/dist/meta/changelog.d.ts

@@ -1,4 +1,4 @@
-export declare const VERSION = "0.9.0";
+export declare const VERSION = "0.10.0";
 export interface ChangelogEntry {
     migrate: readonly string[];
     added: readonly string[];

package/dist/meta/changelog.js

@@ -1,5 +1,26 @@
-export const VERSION = "0.9.0";
+export const VERSION = "0.10.0";
 export const CHANGELOG = {
+    "0.10.0": {
+        migrate: [
+            "Bump every @jgengine/* dependency to ^0.10.0 (the eight packages version in lockstep).",
+            "Nothing to change for existing games — the shared mobile-composition system (viewport allocation, region collision, --jg-* viewport vars) is wired automatically by the shell; HudPanels inside a HudCanvas register themselves. Legacy orientation: \"landscape\" | \"portrait\" keeps its advisory dismissible-hint behavior.",
+            "Opt a driving/landscape game into the strict gate: replace advisory orientation with the contract form orientation: { mobile: \"landscape-required\" } (rules: any · portrait/landscape advisory · portrait-required/landscape-required · unsupported). In portrait the engine shows a polished RotateDeviceScreen, suppresses input, freezes the sim, and unmounts the HUD/controls until the device is landscape.",
+            "Declare HUD intent where useful: HudPanel gains priority (critical/secondary/tertiary), mobileBehavior (hidden unmounts on phones, transient softens collision), allowOverlapWith, and collisionGroup — all optional; omitting them keeps prior behavior.",
+            "Mobile validation now also fails on overlap: bun run shoot <game> --device mobile|mobile-landscape|both exits non-zero on forbidden inter-element collisions, naming both regions.",
+        ],
+        added: [
+            "Shared mobile layout composition — @jgengine/core/ui/gameLayout (resolveLayoutMode, intersects, overlapArea, detectLayoutCollisions, computeGameplayRect, LayoutRegion, GameViewportLayout) and @jgengine/core/ui/orientation (resolveOrientationRequirement, orientationGateActive, MobileOrientationRule); @jgengine/react adds GameViewportProvider (mounted by the shell), hooks (useGameViewportLayout, useGameLayoutMode, useGameOrientation, useReservedControlZones, useLayoutCollisions, useRegisterLayoutRegion), and a headless RotateDeviceScreen. The provider tracks window.visualViewport, publishes --jg-viewport-*/--jg-visual-viewport-*/--jg-safe-* CSS vars, resolves the explicit layout mode, and detects forbidden region overlaps.",
+            "Mandatory orientation contract — PlayableGame.orientation accepts { mobile: <rule> }; landscape-required/portrait-required render an engine-owned rotate gate that blocks gameplay (input suppressed, simulation frozen, HUD/controls unmounted), self-correcting when the device is turned. Reduced-motion and safe-area respected; visualViewport-sized for mobile Safari/PWA.",
+            "Reserved touch-control zones — the touch dock registers its joystick / action-cluster / utility rectangles (runtime-measured) as control regions, so HUD placement and collision validation know exactly where controls sit.",
+            "HUD placement metadata — HudPanel gains priority, mobileBehavior, allowOverlapWith, collisionGroup, and registers as a collision-tracked layout region.",
+            "Mobile-landscape shoot device — bun run shoot --device mobile-landscape (844×390) plus collision-gate reads that fail mobile validation on forbidden overlaps.",
+            "Canyon Chase migrated as the reference landscape-required game — declares orientation: { mobile: \"landscape-required\" } and composes its HUD through coordinated HudPanel regions instead of independent fixed corners.",
+        ],
+        changed: [
+            "First-person projectile tracers now originate from the weapon muzzle instead of the camera/eye centerline; hit detection is unchanged (still crosshair-accurate), and non-viewmodel games and enemy tracers are unaffected.",
+        ],
+        removed: [],
+    },
     "0.9.0": {
         migrate: [
             "Bump every @jgengine/* dependency to ^0.9.0 (the eight packages version in lockstep).",

package/dist/movement/movementModel.d.ts

@@ -115,6 +115,10 @@ export interface CollisionObstacle {
  * objects — this also early-exits per obstacle on horizontal distance.
  */
 export declare function resolveObstacleStep(current: readonly [number, number, number], stepX: number, stepZ: number, obstacles: readonly CollisionObstacle[], playerRadius?: number): MovementFrameStep;
+/** Placed objects within `radius` (XZ) of `center`, as {@link CollisionObstacle}s to pre-filter for {@link resolveObstacleStep}. */
+export declare function nearbyObstacles(objects: readonly {
+    position: readonly [number, number, number];
+}[], center: readonly [number, number, number], radius?: number): CollisionObstacle[];
 /** Zeroes the off-axis component so travel is locked to a single world axis (`PlayerMovementConfig.mode: "axis"`). */
 export declare function constrainStepToAxis(stepX: number, stepZ: number, axis: "x" | "z"): MovementFrameStep;
 /**

package/dist/movement/movementModel.js

@@ -227,6 +227,19 @@ export function resolveObstacleStep(current, stepX, stepZ, obstacles, playerRadi
     }
     return { stepX: resultX, stepZ: resultZ };
 }
+const OBSTACLE_GATHER_RADIUS = 3;
+/** Placed objects within `radius` (XZ) of `center`, as {@link CollisionObstacle}s to pre-filter for {@link resolveObstacleStep}. */
+export function nearbyObstacles(objects, center, radius = OBSTACLE_GATHER_RADIUS) {
+    const radiusSq = radius * radius;
+    const result = [];
+    for (const object of objects) {
+        const dx = object.position[0] - center[0];
+        const dz = object.position[2] - center[2];
+        if (dx * dx + dz * dz <= radiusSq)
+            result.push({ position: object.position });
+    }
+    return result;
+}
 /** Zeroes the off-axis component so travel is locked to a single world axis (`PlayerMovementConfig.mode: "axis"`). */
 export function constrainStepToAxis(stepX, stepZ, axis) {
     return axis === "x" ? { stepX, stepZ: 0 } : { stepX: 0, stepZ };

package/dist/movement/playerMovement.d.ts

@@ -0,0 +1,41 @@
+import type { PhysicsConfig } from "../game/defineGame.js";
+import type { PlayerMovementConfig, VoxelCollisionConfig } from "../game/playableGame.js";
+import type { GameContext } from "../runtime/gameContext.js";
+import type { InputFrame } from "../runtime/inputSnapshot.js";
+import { type TerrainField } from "../world/terrain.js";
+import type { WorldFeature } from "../world/features.js";
+import { type MovementTuningOverrides } from "./movementModel.js";
+/** The resolved, per-world movement configuration {@link stepPlayerMovement} integrates against — the same inputs the shell FrameDriver used to read piecemeal, gathered into one struct so single-player and host movement run identical math. */
+export interface PlayerMovementTuning {
+    collision?: VoxelCollisionConfig;
+    movement?: PlayerMovementConfig;
+    physics?: MovementTuningOverrides;
+    ground: TerrainField;
+    hasTerrain: boolean;
+}
+/**
+ * Maps a game's declared `physics` onto the movement controllers' tuning. `PhysicsConfig.gravity` is a signed
+ * world acceleration (negative points down), but the controllers integrate `velocityY -= gravityAcceleration * dt`
+ * and expect a positive downward magnitude — so gravity is negated here to keep down-pointing gravity pulling down.
+ */
+export declare function resolvePhysicsTuning(physics: PhysicsConfig | undefined): MovementTuningOverrides | undefined;
+/** Gather a game's collision/movement/physics/world config into a {@link PlayerMovementTuning} — call once per world; both the shell and a host pass the result to {@link stepPlayerMovement}. */
+export declare function resolvePlayerMovementTuning(opts: {
+    collision?: VoxelCollisionConfig;
+    movement?: PlayerMovementConfig;
+    physics?: PhysicsConfig;
+    world?: WorldFeature;
+}): PlayerMovementTuning;
+/** One player's current heading (radians), integrated by {@link stepPlayerMovement} — the shell reads it back into its camera/aim yaw. */
+export declare function playerMovementHeading(ctx: GameContext, userId: string): number;
+/** Drop a player's retained movement state (heading + kinematic body) — call on leave so a rejoin starts fresh instead of resuming stale velocity. */
+export declare function forgetPlayerMovement(ctx: GameContext, userId: string): void;
+/**
+ * Integrate one player's movement for a tick from their held-input frame and commit the pose — the single
+ * genre-agnostic controller both the shell (its local player) and a host (each connected player in `onTick`) call,
+ * so single-player and server-authoritative movement are identical. Reads the player's controlled entity, terrain,
+ * scene solids, and pending motion impulses; writes the entity pose via `setPose`. Retains heading + kinematic body
+ * per `userId` on the `ctx`. Pass `heading` to override the internally-integrated yaw (the shell owns yaw for its
+ * camera); omit it and the controller turns from the frame's `turnLeft`/`turnRight` actions.
+ */
+export declare function stepPlayerMovement(ctx: GameContext, userId: string, input: InputFrame, dt: number, tuning: PlayerMovementTuning, heading?: number): void;

package/dist/movement/playerMovement.js

@@ -0,0 +1,181 @@
+import { applyHorizontalImpulses, applyMotionImpulses } from "../runtime/motionIntents.js";
+import { groundFieldFor, hasEnvironmentTerrain } from "../world/terrain.js";
+import { advancePlayerMotion, constrainStepToAxis, createEmptyMovementKeys, createPlayerMotionState, nearbyObstacles, resolveMovementIntent, resolveObstacleStep, snapPositionToGrid, } from "./movementModel.js";
+import { steerYaw } from "./steering.js";
+import { advanceVoxelPlayer, createVoxelPlayerBody, } from "./voxelController.js";
+const DEFAULT_TURN_SPEED = 2.4;
+const DEFAULT_WALK_SPEED = 2;
+/**
+ * Maps a game's declared `physics` onto the movement controllers' tuning. `PhysicsConfig.gravity` is a signed
+ * world acceleration (negative points down), but the controllers integrate `velocityY -= gravityAcceleration * dt`
+ * and expect a positive downward magnitude — so gravity is negated here to keep down-pointing gravity pulling down.
+ */
+export function resolvePhysicsTuning(physics) {
+    if (physics === undefined)
+        return undefined;
+    return {
+        get gravityAcceleration() {
+            return physics.gravity === undefined ? undefined : -physics.gravity;
+        },
+        get jumpVelocity() {
+            return physics.jumpVelocity;
+        },
+    };
+}
+/** Gather a game's collision/movement/physics/world config into a {@link PlayerMovementTuning} — call once per world; both the shell and a host pass the result to {@link stepPlayerMovement}. */
+export function resolvePlayerMovementTuning(opts) {
+    const physics = resolvePhysicsTuning(opts.physics);
+    return {
+        ...(opts.collision === undefined ? {} : { collision: opts.collision }),
+        ...(opts.movement === undefined ? {} : { movement: opts.movement }),
+        ...(physics === undefined ? {} : { physics }),
+        ground: groundFieldFor(opts.world),
+        hasTerrain: hasEnvironmentTerrain(opts.world),
+    };
+}
+const stores = new WeakMap();
+function storeFor(ctx) {
+    let store = stores.get(ctx);
+    if (store === undefined) {
+        store = { players: new Map(), solids: { count: -1, set: new Set() } };
+        stores.set(ctx, store);
+    }
+    return store;
+}
+function stateFor(store, userId) {
+    let state = store.players.get(userId);
+    if (state === undefined) {
+        state = { heading: 0, voxelBody: null, motion: null };
+        store.players.set(userId, state);
+    }
+    return state;
+}
+/** One player's current heading (radians), integrated by {@link stepPlayerMovement} — the shell reads it back into its camera/aim yaw. */
+export function playerMovementHeading(ctx, userId) {
+    return stores.get(ctx)?.players.get(userId)?.heading ?? 0;
+}
+/** Drop a player's retained movement state (heading + kinematic body) — call on leave so a rejoin starts fresh instead of resuming stale velocity. */
+export function forgetPlayerMovement(ctx, userId) {
+    stores.get(ctx)?.players.delete(userId);
+}
+/**
+ * Integrate one player's movement for a tick from their held-input frame and commit the pose — the single
+ * genre-agnostic controller both the shell (its local player) and a host (each connected player in `onTick`) call,
+ * so single-player and server-authoritative movement are identical. Reads the player's controlled entity, terrain,
+ * scene solids, and pending motion impulses; writes the entity pose via `setPose`. Retains heading + kinematic body
+ * per `userId` on the `ctx`. Pass `heading` to override the internally-integrated yaw (the shell owns yaw for its
+ * camera); omit it and the controller turns from the frame's `turnLeft`/`turnRight` actions.
+ */
+export function stepPlayerMovement(ctx, userId, input, dt, tuning, heading) {
+    const playerId = ctx.player.possession.active(userId);
+    const player = ctx.scene.entity.get(playerId);
+    if (player === null)
+        return;
+    const store = storeFor(ctx);
+    const state = stateFor(store, userId);
+    const held = new Set(input.held);
+    const isDown = (action) => held.has(action);
+    if (heading !== undefined) {
+        state.heading = heading;
+    }
+    else {
+        const turnInput = (isDown("turnRight") ? 1 : 0) - (isDown("turnLeft") ? 1 : 0);
+        if (turnInput !== 0)
+            state.heading = steerYaw(state.heading, turnInput, DEFAULT_TURN_SPEED, dt);
+    }
+    const forwardX = Math.sin(state.heading);
+    const forwardZ = Math.cos(state.heading);
+    const keys = createEmptyMovementKeys();
+    keys.w = isDown("moveForward");
+    keys.s = isDown("moveBack");
+    keys.a = isDown("moveLeft");
+    keys.d = isDown("moveRight");
+    keys.shift = isDown("sprint") && (tuning.movement?.canSprint?.(ctx) ?? true);
+    keys.space = isDown("jump");
+    const intent = resolveMovementIntent(keys, true);
+    const motionBatch = ctx.player.motionFor(userId).takePending();
+    const walkSpeed = player.movement?.walkSpeed ?? DEFAULT_WALK_SPEED;
+    if (tuning.collision?.voxel === true) {
+        let body = state.voxelBody;
+        if (body === null) {
+            body = createVoxelPlayerBody(player.position[0], player.position[1], player.position[2]);
+            state.voxelBody = body;
+        }
+        const objects = ctx.scene.object.list();
+        if (store.solids.count !== objects.length) {
+            store.solids.set = new Set(objects.map((o) => `${o.position[0]},${o.position[1]},${o.position[2]}`));
+            store.solids.count = objects.length;
+        }
+        const solids = store.solids.set;
+        const isSolid = (x, y, z) => solids.has(`${x},${y},${z}`);
+        const dims = {
+            halfWidth: tuning.collision.halfWidth ?? 0.3,
+            height: tuning.collision.height ?? 1.8,
+            stepHeight: tuning.collision.stepHeight ?? 0.6,
+        };
+        body.velocityY = applyMotionImpulses(body.velocityY, motionBatch);
+        [body.velocityX, body.velocityZ] = applyHorizontalImpulses(body.velocityX, body.velocityZ, motionBatch);
+        advanceVoxelPlayer(body, intent, forwardX, forwardZ, walkSpeed, dt, isSolid, dims, tuning.physics, tuning.hasTerrain ? (x, z) => tuning.ground.sampleHeight(x, z) : undefined);
+        if (motionBatch !== null && motionBatch.y !== null)
+            body.y = motionBatch.y;
+        ctx.scene.entity.setPose(playerId, {
+            position: [body.x, body.y, body.z],
+            rotationY: intent.moving ? Math.atan2(body.velocityX, body.velocityZ) : player.rotationY,
+            dt,
+        });
+        return;
+    }
+    let motion = state.motion;
+    if (motion === null) {
+        motion = createPlayerMotionState();
+        state.motion = motion;
+    }
+    motion.verticalVelocity = applyMotionImpulses(motion.verticalVelocity, motionBatch);
+    [motion.horizontalVelocityX, motion.horizontalVelocityZ] = applyHorizontalImpulses(motion.horizontalVelocityX, motion.horizontalVelocityZ, motionBatch);
+    const step = advancePlayerMotion(motion, intent, forwardX, forwardZ, walkSpeed, dt, tuning.physics);
+    let stepX = step.stepX;
+    let stepZ = step.stepZ;
+    if (tuning.movement?.mode === "axis") {
+        const constrained = constrainStepToAxis(stepX, stepZ, tuning.movement.axis ?? "x");
+        stepX = constrained.stepX;
+        stepZ = constrained.stepZ;
+    }
+    if (tuning.movement?.collideObjects === true) {
+        const obstacles = nearbyObstacles(ctx.scene.object.list(), player.position);
+        const resolved = resolveObstacleStep(player.position, stepX, stepZ, obstacles);
+        stepX = resolved.stepX;
+        stepZ = resolved.stepZ;
+    }
+    let nextX = player.position[0] + stepX;
+    let nextZ = player.position[2] + stepZ;
+    if (tuning.movement?.mode === "grid") {
+        const snapped = snapPositionToGrid(nextX, nextZ, tuning.movement.cellSize ?? 1);
+        nextX = snapped[0];
+        nextZ = snapped[1];
+    }
+    let nextY = tuning.ground.sampleHeight(nextX, nextZ) + motion.jumpOffset;
+    if (motionBatch !== null && motionBatch.y !== null) {
+        nextY = motionBatch.y;
+        motion.jumpOffset = motionBatch.y - tuning.ground.sampleHeight(nextX, nextZ);
+    }
+    if (tuning.movement?.beforeCommit !== undefined) {
+        const frame = {
+            entityId: playerId,
+            current: player.position,
+            next: [nextX, nextY, nextZ],
+            dt,
+            ctx,
+        };
+        const replacement = tuning.movement.beforeCommit(frame);
+        if (replacement !== undefined) {
+            nextX = replacement[0];
+            nextY = replacement[1];
+            nextZ = replacement[2];
+        }
+    }
+    ctx.scene.entity.setPose(playerId, {
+        position: [nextX, nextY, nextZ],
+        rotationY: intent.moving ? Math.atan2(motion.horizontalVelocityX, motion.horizontalVelocityZ) : player.rotationY,
+        dt,
+    });
+}

package/dist/random/rng.d.ts

@@ -1,2 +1,4 @@
+/** Deterministic pseudo-random generator seeded from a string or number — same seed, same sequence. */
 export declare function seededRng(seed: string | number): () => number;
+/** Derives independent, deterministic {@link seededRng} streams from one base seed, keyed by stream name. */
 export declare function seededStreams(seed: string | number): (stream: string) => () => number;

package/dist/random/rng.js

@@ -7,6 +7,7 @@ function hashSeed(seed) {
     }
     return h >>> 0;
 }
+/** Deterministic pseudo-random generator seeded from a string or number — same seed, same sequence. */
 export function seededRng(seed) {
     let a = hashSeed(seed) >>> 0;
     return () => {
@@ -17,6 +18,7 @@ export function seededRng(seed) {
         return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
     };
 }
+/** Derives independent, deterministic {@link seededRng} streams from one base seed, keyed by stream name. */
 export function seededStreams(seed) {
     const base = typeof seed === "number" ? seed.toString() : seed;
     return (stream) => seededRng(`${base}:${stream}`);

package/dist/render/postProcessing.d.ts

@@ -0,0 +1,56 @@
+/** Renderer tone-mapping curve applied by the post chain's output stage. */
+export type ToneMappingMode = "aces" | "agx" | "reinhard" | "cineon" | "linear" | "none";
+/** UnrealBloom stage — soft HDR glow around bright pixels (sun, glints, emissive). */
+export interface BloomConfig {
+    /** Glow intensity. Default 0.32. */
+    strength?: number;
+    /** Glow spread radius, 0..1. Default 0.55. */
+    radius?: number;
+    /** Luminance above which a pixel blooms, 0..1. Default 0.85. */
+    threshold?: number;
+}
+/** Ground-truth ambient occlusion stage — darkens contact creases and cavities for depth. */
+export interface AoConfig {
+    /** Sample radius in world units. Default 1.8. */
+    radius?: number;
+    /** Occlusion strength multiplier. Default 2.4. */
+    intensity?: number;
+    /** Distance over which occlusion fades out, world units. Default 3.6. */
+    distanceFalloff?: number;
+    /** Blend the AO onto the beauty at this fraction, 0..1. Default 1. */
+    blend?: number;
+}
+/** Final colour-grade stage: lift/gain/gamma, saturation, vignette, film grain — applied in display space after tone mapping. */
+export interface GradeConfig {
+    /** Additive shadow tint (RGB, ~0..0.1). Default cool [0.012, 0.010, 0.018]. */
+    lift?: readonly [number, number, number];
+    /** Multiplicative highlight tint (RGB, ~1). Default warm [1.05, 1.02, 0.98]. */
+    gain?: readonly [number, number, number];
+    /** Output gamma. Default 0.96. */
+    gamma?: number;
+    /** Saturation multiplier around luma. Default 1.12. */
+    saturation?: number;
+    /** Vignette darkening strength at the corners, 0..1. Default 0.2. */
+    vignette?: number;
+    /** Animated film-grain amplitude. Default 0.012. */
+    grain?: number;
+}
+/**
+ * Declarative post-processing chain (RenderPass → AO → Bloom → tone-map output →
+ * Grade). Present on a game means the shell mounts an `EffectComposer` and owns
+ * the render; absent means the renderer draws directly (unchanged). Each stage is
+ * a config object, `false` to skip, or omitted for its default. Pure data — no
+ * three.js types leak into core.
+ */
+export interface PostProcessingConfig {
+    /** Master switch; a config object with `enabled: false` mounts nothing. Default true. */
+    enabled?: boolean;
+    /** Tone-mapping curve the output stage applies. Default "aces". */
+    toneMapping?: ToneMappingMode;
+    /** Exposure multiplier applied before tone mapping. Default 1. */
+    exposure?: number;
+    bloom?: BloomConfig | false;
+    /** Ambient occlusion. Heavier than the other stages — omit or `false` on low-end targets. Default off (omitted). */
+    ao?: AoConfig | false;
+    grade?: GradeConfig | false;
+}

package/dist/render/postProcessing.js

@@ -0,0 +1 @@
+export {};

package/dist/runtime/adapter.d.ts

@@ -1,52 +1,71 @@
 export type MultiplayerTopology = "shared" | "lobbies" | "private";
+/**
+ * Where the world simulation is authoritative. `"client"` (default) keeps the historical model — each client runs
+ * its own `onTick` and syncs only presence/feeds/chat. `"server"` opts into host-authoritative replication: the
+ * host runs the loop, and the shell mirrors the server's world into the local `ctx` instead of simulating locally.
+ */
+export type MultiplayerAuthority = "server" | "client";
 export type MultiplayerAdapterConfig = {
     kind: "convex";
     topology?: MultiplayerTopology;
+    authority?: MultiplayerAuthority;
 } | {
     kind: "ws";
     topology?: MultiplayerTopology;
     url?: string;
+    authority?: MultiplayerAuthority;
 } | {
     kind: "socketio";
     topology?: MultiplayerTopology;
     url?: string;
+    authority?: MultiplayerAuthority;
 } | {
     kind: "p2p";
     topology?: MultiplayerTopology;
     room?: string;
+    authority?: MultiplayerAuthority;
 } | {
     kind: "lan";
     topology?: MultiplayerTopology;
     port?: number;
     path?: string;
+    authority?: MultiplayerAuthority;
 } | {
     kind: "offline";
 };
 export declare function convex(config?: {
     topology?: MultiplayerTopology;
+    authority?: MultiplayerAuthority;
 }): MultiplayerAdapterConfig;
 export declare function ws(config?: {
     topology?: MultiplayerTopology;
     url?: string;
+    authority?: MultiplayerAuthority;
 }): MultiplayerAdapterConfig;
 export declare function fly(config: {
     app: string;
     topology?: MultiplayerTopology;
     path?: string;
+    authority?: MultiplayerAuthority;
 }): MultiplayerAdapterConfig;
 export declare function socketIo(config?: {
     topology?: MultiplayerTopology;
     url?: string;
+    authority?: MultiplayerAuthority;
 }): MultiplayerAdapterConfig;
 export declare function p2p(config?: {
     topology?: MultiplayerTopology;
     room?: string;
+    authority?: MultiplayerAuthority;
 }): MultiplayerAdapterConfig;
 export declare function lan(config?: {
     topology?: MultiplayerTopology;
     port?: number;
     path?: string;
+    authority?: MultiplayerAuthority;
 }): MultiplayerAdapterConfig;
+/** True when the adapter opts into host-authoritative world replication (`authority: "server"`). */
+export declare function isServerAuthoritative(multiplayer: unknown): boolean;
 export declare function offline(): MultiplayerAdapterConfig;
 export declare function adapterOf(multiplayer: unknown): MultiplayerAdapterConfig | null;
 export declare function multiplayerAdapterKind(multiplayer: unknown): string | null;

package/dist/runtime/adapter.js

@@ -1,24 +1,30 @@
 export function convex(config) {
-    return { kind: "convex", topology: config?.topology ?? "shared" };
+    return { kind: "convex", topology: config?.topology ?? "shared", authority: config?.authority };
 }
 export function ws(config) {
-    return { kind: "ws", topology: config?.topology ?? "shared", url: config?.url };
+    return { kind: "ws", topology: config?.topology ?? "shared", url: config?.url, authority: config?.authority };
 }
 export function fly(config) {
     return {
         kind: "ws",
         topology: config.topology ?? "shared",
         url: `wss://${config.app}.fly.dev${config.path ?? "/ws"}`,
+        authority: config.authority,
     };
 }
 export function socketIo(config) {
-    return { kind: "socketio", topology: config?.topology ?? "shared", url: config?.url };
+    return { kind: "socketio", topology: config?.topology ?? "shared", url: config?.url, authority: config?.authority };
 }
 export function p2p(config) {
-    return { kind: "p2p", topology: config?.topology ?? "private", room: config?.room };
+    return { kind: "p2p", topology: config?.topology ?? "private", room: config?.room, authority: config?.authority };
 }
 export function lan(config) {
-    return { kind: "lan", topology: config?.topology ?? "shared", port: config?.port, path: config?.path };
+    return { kind: "lan", topology: config?.topology ?? "shared", port: config?.port, path: config?.path, authority: config?.authority };
+}
+/** True when the adapter opts into host-authoritative world replication (`authority: "server"`). */
+export function isServerAuthoritative(multiplayer) {
+    const adapter = adapterOf(multiplayer);
+    return adapter !== null && "authority" in adapter && adapter.authority === "server";
 }
 export function offline() {
     return { kind: "offline" };