@jgengine/core 0.8.0 → 0.10.0

package/dist/movement/glideModel.js

@@ -0,0 +1,54 @@
+export function createGlideModel(config = {}) {
+    const gravity = (config.gravity ?? 20) * (config.gravityScale ?? 0.25);
+    const thrustAccel = config.thrustAccel ?? 10;
+    const forwardSpeed = config.forwardSpeed ?? 12;
+    const yawRate = config.yawRate ?? 1.6;
+    const climbAccel = config.climbAccel ?? 0;
+    const maxFallSpeed = config.maxFallSpeed ?? 8;
+    const baseControl = config.control ?? 1;
+    let x = 0;
+    let y = 0;
+    let z = 0;
+    let heading = 0;
+    let vx = 0;
+    let vy = 0;
+    let vz = 0;
+    function snapshot() {
+        return { position: [x, y, z], velocity: [vx, vy, vz], heading };
+    }
+    return {
+        launch(position, nextHeading, initialSpeed = forwardSpeed) {
+            x = position[0];
+            y = position[1];
+            z = position[2];
+            heading = nextHeading;
+            vx = Math.sin(heading) * initialSpeed;
+            vy = 0;
+            vz = Math.cos(heading) * initialSpeed;
+        },
+        pose: snapshot,
+        step(dt, input = {}, externalVelocity) {
+            if (dt <= 0)
+                return snapshot();
+            const control = Math.max(0, Math.min(1, input.control ?? baseControl));
+            heading += (input.yaw ?? 0) * yawRate * control * dt;
+            const fx = Math.sin(heading);
+            const fz = Math.cos(heading);
+            const along = vx * fx + vz * fz;
+            const cruise = (forwardSpeed - along) * Math.min(1, (thrustAccel / Math.max(1, forwardSpeed)) * dt);
+            vx += fx * cruise * control;
+            vz += fz * cruise * control;
+            vy -= gravity * dt;
+            const throttle = Math.max(0, Math.min(1, input.throttle ?? 0));
+            if (climbAccel > 0 && throttle > 0)
+                vy += climbAccel * throttle * control * dt;
+            if (vy < -maxFallSpeed)
+                vy = -maxFallSpeed;
+            const [ex, ey, ez] = externalVelocity ?? [0, 0, 0];
+            x += (vx + ex) * dt;
+            y += (vy + ey) * dt;
+            z += (vz + ez) * dt;
+            return snapshot();
+        },
+    };
+}

package/dist/movement/grappleSwing.d.ts

@@ -0,0 +1,34 @@
+export type SwingVec3 = readonly [number, number, number];
+export interface GrappleSwingConfig {
+    /** Rope shortens by this many units/s while `reeling`. Default `0` (fixed length). */
+    reelSpeed?: number;
+    minLength?: number;
+    /** Extra spring pull toward the anchor when the rope is taut (elastic feel); default `0` (hard constraint only). */
+    stiffness?: number;
+    /** Velocity damping per second while attached; default `0.1`. */
+    damping?: number;
+}
+export interface GrappleSwingState {
+    attached: boolean;
+    anchor: SwingVec3 | null;
+    ropeLength: number;
+}
+export interface GrappleSwingStep {
+    position: SwingVec3;
+    velocity: SwingVec3;
+}
+/**
+ * A rope-swing constraint for kinematic controllers (#282.5) — the walk-controller-compatible
+ * sibling of `physics/traversal`'s rigid-body `Grapple`. Fire at an anchor, feed each frame's
+ * integrated position/velocity through `step`, and commit what comes back (via `beforeCommit`
+ * or `setPose`): positions beyond the rope clamp to its sphere and velocity loses its outward
+ * radial component, which is exactly a pendulum swing.
+ */
+export interface GrappleSwing {
+    fire(anchor: SwingVec3, from: SwingVec3): void;
+    release(): void;
+    state(): GrappleSwingState;
+    /** Constrain one frame. `reeling` shortens the rope; returns the corrected position/velocity. */
+    step(position: SwingVec3, velocity: SwingVec3, dt: number, reeling?: boolean): GrappleSwingStep;
+}
+export declare function createGrappleSwing(config?: GrappleSwingConfig): GrappleSwing;

package/dist/movement/grappleSwing.js

@@ -0,0 +1,56 @@
+export function createGrappleSwing(config = {}) {
+    const reelSpeed = config.reelSpeed ?? 0;
+    const minLength = config.minLength ?? 1;
+    const stiffness = config.stiffness ?? 0;
+    const damping = config.damping ?? 0.1;
+    let anchor = null;
+    let ropeLength = 0;
+    return {
+        fire(nextAnchor, from) {
+            anchor = nextAnchor;
+            ropeLength = Math.max(minLength, Math.hypot(from[0] - nextAnchor[0], from[1] - nextAnchor[1], from[2] - nextAnchor[2]));
+        },
+        release() {
+            anchor = null;
+        },
+        state: () => ({ attached: anchor !== null, anchor, ropeLength }),
+        step(position, velocity, dt, reeling = false) {
+            if (anchor === null || dt <= 0)
+                return { position, velocity };
+            if (reeling && reelSpeed > 0)
+                ropeLength = Math.max(minLength, ropeLength - reelSpeed * dt);
+            let px = position[0];
+            let py = position[1];
+            let pz = position[2];
+            let vx = velocity[0];
+            let vy = velocity[1];
+            let vz = velocity[2];
+            const dx = px - anchor[0];
+            const dy = py - anchor[1];
+            const dz = pz - anchor[2];
+            const distance = Math.hypot(dx, dy, dz);
+            if (distance > ropeLength && distance > 1e-9) {
+                const nx = dx / distance;
+                const ny = dy / distance;
+                const nz = dz / distance;
+                px = anchor[0] + nx * ropeLength;
+                py = anchor[1] + ny * ropeLength;
+                pz = anchor[2] + nz * ropeLength;
+                const radial = vx * nx + vy * ny + vz * nz;
+                if (radial > 0) {
+                    vx -= nx * radial;
+                    vy -= ny * radial;
+                    vz -= nz * radial;
+                }
+                if (stiffness > 0) {
+                    const pull = (distance - ropeLength) * stiffness * dt;
+                    vx -= nx * pull;
+                    vy -= ny * pull;
+                    vz -= nz * pull;
+                }
+            }
+            const damp = Math.max(0, 1 - damping * dt);
+            return { position: [px, py, pz], velocity: [vx * damp, vy * damp, vz * damp] };
+        },
+    };
+}

package/dist/movement/leaderTrail.d.ts

@@ -0,0 +1,29 @@
+export type TrailPoint = readonly [number, number, number];
+export interface LeaderTrailConfig {
+    /** Arc-length gap between consecutive followers. */
+    spacing: number;
+    /** Followers the trail must be able to serve; history is capped to cover them. Default `16`. */
+    maxFollowers?: number;
+    /** Minimum leader movement before a new trail sample is recorded; default `spacing / 8`. */
+    sampleDistance?: number;
+}
+export interface TrailPose {
+    position: TrailPoint;
+    /** Yaw (radians) of the trail direction at this point, matching engine `rotationY`. */
+    heading: number;
+}
+/**
+ * A live breadcrumb trail recorded from a moving leader, with followers placed by arc-length
+ * behind the head — conga lines, convoys, duckling chains, snake bodies. Call `record` with the
+ * leader's position every tick; read `followerAt(i)` for the pose `spacing * (i + 1)` behind.
+ */
+export interface LeaderTrail {
+    record(position: TrailPoint): void;
+    /** Pose for follower `index` (0 = closest behind the leader); `null` until enough trail exists. */
+    followerAt(index: number): TrailPose | null;
+    /** Recorded arc length available behind the leader. */
+    length(): number;
+    /** Drop all history (teleport, respawn) and optionally restart from a position. */
+    reset(position?: TrailPoint): void;
+}
+export declare function createLeaderTrail(config: LeaderTrailConfig): LeaderTrail;

package/dist/movement/leaderTrail.js

@@ -0,0 +1,67 @@
+export function createLeaderTrail(config) {
+    if (!(config.spacing > 0))
+        throw new Error(`leader trail spacing must be positive, got ${config.spacing}`);
+    const spacing = config.spacing;
+    const maxFollowers = Math.max(1, config.maxFollowers ?? 16);
+    const sampleDistance = config.sampleDistance ?? spacing / 8;
+    const capacity = spacing * (maxFollowers + 1);
+    let points = [];
+    let lengths = [];
+    let total = 0;
+    function trim() {
+        while (total > capacity && lengths.length > 0) {
+            const tailSegment = lengths[0];
+            if (total - tailSegment < capacity)
+                break;
+            lengths.shift();
+            points.shift();
+            total -= tailSegment;
+        }
+    }
+    return {
+        record(position) {
+            const head = points[points.length - 1];
+            if (head === undefined) {
+                points.push(position);
+                return;
+            }
+            const step = Math.hypot(position[0] - head[0], position[1] - head[1], position[2] - head[2]);
+            if (step < sampleDistance)
+                return;
+            points.push(position);
+            lengths.push(step);
+            total += step;
+            trim();
+        },
+        followerAt(index) {
+            const behind = spacing * (index + 1);
+            if (behind > total)
+                return null;
+            let remaining = behind;
+            for (let i = lengths.length - 1; i >= 0; i -= 1) {
+                const segment = lengths[i];
+                const to = points[i + 1];
+                const from = points[i];
+                if (remaining <= segment) {
+                    const fraction = segment <= 1e-9 ? 0 : remaining / segment;
+                    return {
+                        position: [
+                            to[0] + (from[0] - to[0]) * fraction,
+                            to[1] + (from[1] - to[1]) * fraction,
+                            to[2] + (from[2] - to[2]) * fraction,
+                        ],
+                        heading: Math.atan2(to[0] - from[0], to[2] - from[2]),
+                    };
+                }
+                remaining -= segment;
+            }
+            return null;
+        },
+        length: () => total,
+        reset(position) {
+            points = position === undefined ? [] : [position];
+            lengths = [];
+            total = 0;
+        },
+    };
+}

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/movement/steering.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Yaw-frame steering math. The engine's heading convention is
+ * `forward = (sin yaw, cos yaw)` on the XZ plane with +Y up, which makes a
+ * positive yaw increment rotate counterclockwise seen from above — a turn to
+ * the entity's LEFT on screen. Every hand-written `heading += steer * rate * dt`
+ * therefore turns the wrong way; integrate steering through `steerYaw` instead.
+ */
+export type YawVectorXZ = readonly [number, number];
+/** XZ forward direction of a yaw (`rotationY`): `(sin yaw, cos yaw)`. */
+export declare function yawForward(yaw: number): YawVectorXZ;
+/** XZ screen-right of a yaw — `forward × up` with up = +Y: `(-cos yaw, sin yaw)`. */
+export declare function yawRight(yaw: number): YawVectorXZ;
+/**
+ * Integrate one steering step. `steerRight` is the signed steer input
+ * (+1 = turn right, matching `DRIVE_AXIS_BINDINGS`' KeyD/ArrowRight),
+ * `turnRatePerSecond` is radians per second at full lock. Steering right
+ * decreases yaw in the engine frame; this helper owns that sign so game
+ * code never re-derives it.
+ */
+export declare function steerYaw(yaw: number, steerRight: number, turnRatePerSecond: number, dt: number): number;
+/**
+ * Signed steer-right input that closes on `desiredYaw` when integrated
+ * through `steerYaw` — the seek half every AI driver and homing script
+ * needs. Magnitude is the wrapped radian error in (−π, π]; scale and clamp
+ * it into [-1, 1] at the call site.
+ */
+export declare function steerToward(yaw: number, desiredYaw: number): number;

package/dist/movement/steering.js

@@ -0,0 +1,40 @@
+/**
+ * Yaw-frame steering math. The engine's heading convention is
+ * `forward = (sin yaw, cos yaw)` on the XZ plane with +Y up, which makes a
+ * positive yaw increment rotate counterclockwise seen from above — a turn to
+ * the entity's LEFT on screen. Every hand-written `heading += steer * rate * dt`
+ * therefore turns the wrong way; integrate steering through `steerYaw` instead.
+ */
+/** XZ forward direction of a yaw (`rotationY`): `(sin yaw, cos yaw)`. */
+export function yawForward(yaw) {
+    return [Math.sin(yaw), Math.cos(yaw)];
+}
+/** XZ screen-right of a yaw — `forward × up` with up = +Y: `(-cos yaw, sin yaw)`. */
+export function yawRight(yaw) {
+    return [-Math.cos(yaw), Math.sin(yaw)];
+}
+/**
+ * Integrate one steering step. `steerRight` is the signed steer input
+ * (+1 = turn right, matching `DRIVE_AXIS_BINDINGS`' KeyD/ArrowRight),
+ * `turnRatePerSecond` is radians per second at full lock. Steering right
+ * decreases yaw in the engine frame; this helper owns that sign so game
+ * code never re-derives it.
+ */
+export function steerYaw(yaw, steerRight, turnRatePerSecond, dt) {
+    return yaw - steerRight * turnRatePerSecond * dt;
+}
+/**
+ * Signed steer-right input that closes on `desiredYaw` when integrated
+ * through `steerYaw` — the seek half every AI driver and homing script
+ * needs. Magnitude is the wrapped radian error in (−π, π]; scale and clamp
+ * it into [-1, 1] at the call site.
+ */
+export function steerToward(yaw, desiredYaw) {
+    let delta = (desiredYaw - yaw) % TWO_PI;
+    if (delta > Math.PI)
+        delta -= TWO_PI;
+    if (delta <= -Math.PI)
+        delta += TWO_PI;
+    return -delta;
+}
+const TWO_PI = Math.PI * 2;

package/dist/multiplayer/feedWriteGate.d.ts

@@ -0,0 +1,10 @@
+export type FeedWriteGate = {
+    allowedActions: readonly string[];
+};
+export declare function createFeedWriteGate(allowedActions?: readonly string[]): FeedWriteGate;
+export declare function validateFeedWrite(gate: FeedWriteGate | undefined, action: string): {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};

package/dist/multiplayer/feedWriteGate.js

@@ -0,0 +1,12 @@
+export function createFeedWriteGate(allowedActions = []) {
+    return { allowedActions: [...allowedActions] };
+}
+export function validateFeedWrite(gate, action) {
+    if (gate === undefined || gate.allowedActions.length === 0) {
+        return { ok: false, reason: "client feed writes are disabled" };
+    }
+    if (!gate.allowedActions.includes(action)) {
+        return { ok: false, reason: `feed action not allowed: ${action}` };
+    }
+    return { ok: true };
+}

package/dist/multiplayer/presenceModel.d.ts

@@ -22,8 +22,10 @@ export interface IncomingPose {
 export interface PoseSyncRules {
     /** Speed cap (units/sec) for client-authoritative movement. */
     maxSpeed: number;
-    /** Vertical offset clamp (e.g. peak jump height). */
+    /** Vertical offset clamp above floorY (e.g. peak jump height). */
     maxVerticalOffset: number;
+    /** World-floor Y used as the base of the jump band. Defaults to 0. */
+    floorY?: number;
     /** Elapsed-time clamp so stale or bursty clients cannot teleport. */
     minElapsedSec: number;
     maxElapsedSec: number;
@@ -44,7 +46,17 @@ export interface PoseSyncDecision {
     /** True when only the keep-alive stamp should be written. */
     refreshKeepAlive: boolean;
 }
-export declare function decidePoseSync(current: PresencePoseState, incoming: IncomingPose, rules: PoseSyncRules, nowMs: number): PoseSyncDecision;
+export declare const DEFAULT_SPAWN_ORIGIN: {
+    readonly x: 0;
+    readonly y: 0;
+    readonly z: 0;
+};
+export declare function spawnPresenceState(origin: {
+    x: number;
+    y: number;
+    z: number;
+} | undefined, nowMs: number, rules: Pick<PoseSyncRules, "maxElapsedSec">): PresencePoseState;
+export declare function decidePoseSync(current: PresencePoseState, incoming: IncomingPose, rules: PoseSyncRules, nowMs: number, floorY?: number): PoseSyncDecision;
 export declare function shouldRefreshKeepAlive(lastSeenAtMs: number | undefined, nowMs: number, rules: Pick<PoseSyncRules, "keepAliveRefreshMs">): boolean;
 export declare function shouldPersistWorldSnapshot(lastSavedAtMs: number | undefined, nowMs: number, intervalMs: number): boolean;
 export interface ActivePresenceResolution<T> {

package/dist/multiplayer/presenceModel.js

@@ -9,8 +9,18 @@ function appearanceEqual(a, b) {
         return false;
     return aKeys.every((key) => a[key] === b[key]);
 }
-export function decidePoseSync(current, incoming, rules, nowMs) {
-    const elapsedSec = Math.max(rules.minElapsedSec, Math.min(rules.maxElapsedSec, (nowMs - (current.lastSeenAtMs ?? nowMs)) / 1000));
+export const DEFAULT_SPAWN_ORIGIN = { x: 0, y: 0, z: 0 };
+export function spawnPresenceState(origin = DEFAULT_SPAWN_ORIGIN, nowMs, rules) {
+    return {
+        position: { x: origin.x, y: origin.y, z: origin.z },
+        rotationY: 0,
+        rotationPitch: 0,
+        lastSeenAtMs: nowMs - rules.maxElapsedSec * 1000,
+    };
+}
+export function decidePoseSync(current, incoming, rules, nowMs, floorY) {
+    const rawElapsedSec = Math.max(0, (nowMs - (current.lastSeenAtMs ?? nowMs)) / 1000);
+    const elapsedSec = Math.min(rules.maxElapsedSec, rawElapsedSec);
     const maxDist = rules.maxSpeed * elapsedSec;
     const maxDistSq = maxDist * maxDist;
     let targetX = incoming.position.x;
@@ -23,9 +33,11 @@ export function decidePoseSync(current, incoming, rules, nowMs) {
         targetX = current.position.x + dx * scale;
         targetZ = current.position.z + dz * scale;
     }
+    const floor = floorY ?? rules.floorY ?? 0;
+    const ceiling = floor + rules.maxVerticalOffset;
     const nextY = incoming.position.y === undefined
         ? current.position.y
-        : Math.max(0, Math.min(rules.maxVerticalOffset, incoming.position.y));
+        : Math.max(floor, Math.min(ceiling, incoming.position.y));
     const nextRotationY = incoming.rotationY ?? current.rotationY;
     const nextRotationPitch = incoming.rotationPitch ?? current.rotationPitch ?? 0;
     const nextAppearance = incoming.appearance ?? current.appearance;