@jgengine/core 0.7.0 → 0.9.0

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

@@ -0,0 +1,61 @@
+/**
+ * Voxel character controller (pure model).
+ *
+ * The base first-person controller in `movementModel.ts` assumes flat ground at
+ * y=0 — it integrates gravity into a `jumpOffset` and never asks the world how
+ * tall the ground is. That is fine for a plaza demo but wrong for any game where
+ * the player walks on placed blocks and digs down into the world: they float on
+ * an invisible floor, clip through walls, and can never descend.
+ *
+ * This module resolves the player as an axis-aligned box against a set of solid
+ * unit cells (a `SolidQuery`), so the same held-keys → intent pipeline drives a
+ * body that stands on blocks, falls into holes, is stopped by walls, and steps
+ * up single-block ledges. Keeping it renderer-free means the shell can drive it
+ * from live scene objects while the descent/landing/step-up behaviour stays unit
+ * testable without three.js.
+ *
+ * Cell convention matches the shell's object rendering and the voxel raycast:
+ * cell (x,y,z) is the solid box X∈[x-0.5,x+0.5], Y∈[y,y+1], Z∈[z-0.5,z+0.5]. A
+ * block at cell y therefore has its top face at world y+1, so a player standing
+ * on the surface layer (cell y=-1) rests with their feet at y=0.
+ */
+import { type MovementIntent, type MovementTuningOverrides } from "./movementModel.js";
+export type SolidQuery = (x: number, y: number, z: number) => boolean;
+/** Footprint + height of the player box, in world units. */
+export interface VoxelPlayerDims {
+    /** Half the box width on both horizontal axes. */
+    halfWidth: number;
+    /** Box height measured up from the feet. */
+    height: number;
+    /** Tallest ledge the player walks up without jumping. */
+    stepHeight: number;
+}
+export declare const DEFAULT_VOXEL_DIMS: VoxelPlayerDims;
+/** Mutable kinematic state carried between frames by the voxel controller. */
+export interface VoxelPlayerBody {
+    x: number;
+    y: number;
+    z: number;
+    velocityX: number;
+    velocityY: number;
+    velocityZ: number;
+    grounded: boolean;
+    jumpHeld: boolean;
+}
+export declare function createVoxelPlayerBody(x: number, y: number, z: number): VoxelPlayerBody;
+/** Samples the terrain floor height at a point; unset means flat ground plays no part in support. */
+export type GroundHeightQuery = (x: number, z: number) => number;
+/**
+ * Advance one frame of voxel-collided player kinematics. Mutates `body`
+ * (position, velocity, grounded) in place.
+ *
+ * `forwardX`/`forwardZ` are the camera heading projected onto the ground plane
+ * (need not be normalized). Pulling this out of the render loop is what lets us
+ * assert "dig the block underfoot and the player drops a level" in a unit test.
+ *
+ * `groundHeight`, when supplied, is an additional solid floor sampled at the
+ * body's (x, z): the player never sinks below it and standing on it counts as
+ * supported (resets jump state like landing on a solid cell). Where terrain and
+ * a solid cell's top disagree, the higher of the two wins.
+ */
+export declare function advanceVoxelPlayer(body: VoxelPlayerBody, intent: MovementIntent, forwardX: number, forwardZ: number, baseSpeed: number, rawDeltaSeconds: number, isSolid: SolidQuery, dims?: VoxelPlayerDims, tuning?: MovementTuningOverrides, groundHeight?: GroundHeightQuery): void;

package/dist/movement/voxelController.js

@@ -0,0 +1,229 @@
+/**
+ * Voxel character controller (pure model).
+ *
+ * The base first-person controller in `movementModel.ts` assumes flat ground at
+ * y=0 — it integrates gravity into a `jumpOffset` and never asks the world how
+ * tall the ground is. That is fine for a plaza demo but wrong for any game where
+ * the player walks on placed blocks and digs down into the world: they float on
+ * an invisible floor, clip through walls, and can never descend.
+ *
+ * This module resolves the player as an axis-aligned box against a set of solid
+ * unit cells (a `SolidQuery`), so the same held-keys → intent pipeline drives a
+ * body that stands on blocks, falls into holes, is stopped by walls, and steps
+ * up single-block ledges. Keeping it renderer-free means the shell can drive it
+ * from live scene objects while the descent/landing/step-up behaviour stays unit
+ * testable without three.js.
+ *
+ * Cell convention matches the shell's object rendering and the voxel raycast:
+ * cell (x,y,z) is the solid box X∈[x-0.5,x+0.5], Y∈[y,y+1], Z∈[z-0.5,z+0.5]. A
+ * block at cell y therefore has its top face at world y+1, so a player standing
+ * on the surface layer (cell y=-1) rests with their feet at y=0.
+ */
+import { MOVEMENT_TUNING } from "./movementModel.js";
+export const DEFAULT_VOXEL_DIMS = {
+    halfWidth: 0.3,
+    height: 1.8,
+    stepHeight: 0.6,
+};
+export function createVoxelPlayerBody(x, y, z) {
+    return { x, y, z, velocityX: 0, velocityY: 0, velocityZ: 0, grounded: true, jumpHeld: false };
+}
+const SUPPORT_EPSILON = 0.02;
+const PENETRATION_EPSILON = 1e-4;
+function cellX(worldX) {
+    return Math.floor(worldX + 0.5);
+}
+function cellZ(worldZ) {
+    return Math.floor(worldZ + 0.5);
+}
+/** True if the player box centred at (x, y, z) overlaps any solid cell. */
+function overlapsSolid(x, y, z, isSolid, dims) {
+    const minCellX = cellX(x - dims.halfWidth);
+    const maxCellX = cellX(x + dims.halfWidth);
+    const minCellZ = cellZ(z - dims.halfWidth);
+    const maxCellZ = cellZ(z + dims.halfWidth);
+    const minCellY = Math.floor(y + PENETRATION_EPSILON);
+    const maxCellY = Math.floor(y + dims.height - PENETRATION_EPSILON);
+    for (let cx = minCellX; cx <= maxCellX; cx += 1) {
+        for (let cz = minCellZ; cz <= maxCellZ; cz += 1) {
+            for (let cy = minCellY; cy <= maxCellY; cy += 1) {
+                if (isSolid(cx, cy, cz))
+                    return true;
+            }
+        }
+    }
+    return false;
+}
+/** True if a solid cell sits directly beneath the feet, or terrain supports them (i.e. the player is supported). */
+function hasSupport(x, z, y, isSolid, dims, groundHeight) {
+    const cy = Math.floor(y - SUPPORT_EPSILON);
+    const minCellX = cellX(x - dims.halfWidth);
+    const maxCellX = cellX(x + dims.halfWidth);
+    const minCellZ = cellZ(z - dims.halfWidth);
+    const maxCellZ = cellZ(z + dims.halfWidth);
+    for (let cx = minCellX; cx <= maxCellX; cx += 1) {
+        for (let cz = minCellZ; cz <= maxCellZ; cz += 1) {
+            if (isSolid(cx, cy, cz))
+                return true;
+        }
+    }
+    if (groundHeight !== undefined && y <= groundHeight(x, z) + SUPPORT_EPSILON)
+        return true;
+    return false;
+}
+/**
+ * Highest solid-cell top under the footprint at (x, z) within the vertical
+ * window [fromY, toY]. Returns null when nothing supports the feet there — used
+ * both to snap a fall onto a block and to raise a step-up.
+ */
+function supportTopWithin(x, z, fromY, toY, isSolid, dims) {
+    const minCellX = cellX(x - dims.halfWidth);
+    const maxCellX = cellX(x + dims.halfWidth);
+    const minCellZ = cellZ(z - dims.halfWidth);
+    const maxCellZ = cellZ(z + dims.halfWidth);
+    const lowCellY = Math.floor(fromY - PENETRATION_EPSILON);
+    const highCellY = Math.floor(toY - PENETRATION_EPSILON);
+    let best = null;
+    for (let cx = minCellX; cx <= maxCellX; cx += 1) {
+        for (let cz = minCellZ; cz <= maxCellZ; cz += 1) {
+            for (let cy = lowCellY; cy <= highCellY; cy += 1) {
+                if (!isSolid(cx, cy, cz))
+                    continue;
+                const top = cy + 1;
+                if (best === null || top > best)
+                    best = top;
+            }
+        }
+    }
+    return best;
+}
+function targetHorizontalVelocity(intent, forwardX, forwardZ, baseSpeed) {
+    if (!intent.moving)
+        return { x: 0, z: 0 };
+    let fx = forwardX;
+    let fz = forwardZ;
+    const lengthSq = fx * fx + fz * fz;
+    if (lengthSq < 1e-6) {
+        fx = 0;
+        fz = -1;
+    }
+    else {
+        const inv = 1 / Math.sqrt(lengthSq);
+        fx *= inv;
+        fz *= inv;
+    }
+    const rightX = -fz;
+    const rightZ = fx;
+    let vx = fx * intent.forward + rightX * intent.right;
+    let vz = fz * intent.forward + rightZ * intent.right;
+    const magSq = vx * vx + vz * vz;
+    if (magSq < 1e-6)
+        return { x: 0, z: 0 };
+    const speedMultiplier = intent.crouching
+        ? MOVEMENT_TUNING.crouchSpeedMultiplier
+        : intent.running
+            ? MOVEMENT_TUNING.runSpeedMultiplier
+            : 1;
+    const targetSpeed = baseSpeed * MOVEMENT_TUNING.walkSpeedMultiplier * speedMultiplier;
+    const scale = targetSpeed / Math.sqrt(magSq);
+    vx *= scale;
+    vz *= scale;
+    return { x: vx, z: vz };
+}
+/**
+ * Move the body along one horizontal axis, resolving collisions. Returns the
+ * component of the step that survived (0 when a wall stopped the move). When the
+ * move is blocked but the obstacle is a short ledge, the body steps up onto it.
+ */
+function moveAxis(body, axis, delta, isSolid, dims) {
+    if (delta === 0)
+        return 0;
+    const nextX = axis === "x" ? body.x + delta : body.x;
+    const nextZ = axis === "z" ? body.z + delta : body.z;
+    if (!overlapsSolid(nextX, body.y, nextZ, isSolid, dims)) {
+        body.x = nextX;
+        body.z = nextZ;
+        return delta;
+    }
+    if (body.grounded) {
+        const raised = supportTopWithin(nextX, nextZ, body.y, body.y + dims.stepHeight, isSolid, dims);
+        if (raised !== null &&
+            raised - body.y <= dims.stepHeight + PENETRATION_EPSILON &&
+            raised >= body.y &&
+            !overlapsSolid(nextX, raised, nextZ, isSolid, dims)) {
+            body.x = nextX;
+            body.z = nextZ;
+            body.y = raised;
+            return delta;
+        }
+    }
+    return 0;
+}
+/**
+ * Advance one frame of voxel-collided player kinematics. Mutates `body`
+ * (position, velocity, grounded) in place.
+ *
+ * `forwardX`/`forwardZ` are the camera heading projected onto the ground plane
+ * (need not be normalized). Pulling this out of the render loop is what lets us
+ * assert "dig the block underfoot and the player drops a level" in a unit test.
+ *
+ * `groundHeight`, when supplied, is an additional solid floor sampled at the
+ * body's (x, z): the player never sinks below it and standing on it counts as
+ * supported (resets jump state like landing on a solid cell). Where terrain and
+ * a solid cell's top disagree, the higher of the two wins.
+ */
+export function advanceVoxelPlayer(body, intent, forwardX, forwardZ, baseSpeed, rawDeltaSeconds, isSolid, dims = DEFAULT_VOXEL_DIMS, tuning, groundHeight) {
+    const dt = Math.min(rawDeltaSeconds, MOVEMENT_TUNING.maxFrameSeconds);
+    const gravityAcceleration = tuning?.gravityAcceleration ?? MOVEMENT_TUNING.gravityAcceleration;
+    const jumpVelocity = tuning?.jumpVelocity ?? MOVEMENT_TUNING.jumpVelocity;
+    const target = targetHorizontalVelocity(intent, forwardX, forwardZ, baseSpeed);
+    const acceleration = body.grounded
+        ? MOVEMENT_TUNING.groundAcceleration
+        : MOVEMENT_TUNING.airAcceleration;
+    const accelerationBlend = 1 - Math.exp(-acceleration * dt);
+    body.velocityX += (target.x - body.velocityX) * accelerationBlend;
+    body.velocityZ += (target.z - body.velocityZ) * accelerationBlend;
+    if (!intent.moving && body.grounded) {
+        const friction = Math.exp(-MOVEMENT_TUNING.groundFriction * dt);
+        body.velocityX *= friction;
+        body.velocityZ *= friction;
+    }
+    if (moveAxis(body, "x", body.velocityX * dt, isSolid, dims) === 0)
+        body.velocityX = 0;
+    if (moveAxis(body, "z", body.velocityZ * dt, isSolid, dims) === 0)
+        body.velocityZ = 0;
+    const supported = body.grounded && hasSupport(body.x, body.z, body.y, isSolid, dims, groundHeight);
+    body.grounded = supported;
+    const jumpPressed = intent.jumping;
+    if (jumpPressed && !body.jumpHeld && body.grounded && !intent.crouching) {
+        body.velocityY = jumpVelocity;
+        body.grounded = false;
+    }
+    body.jumpHeld = jumpPressed;
+    if (!body.grounded) {
+        body.velocityY -= gravityAcceleration * dt;
+        const nextY = body.y + body.velocityY * dt;
+        if (body.velocityY <= 0) {
+            const terrainFloor = groundHeight?.(body.x, body.z);
+            const solidBlocked = overlapsSolid(body.x, nextY, body.z, isSolid, dims);
+            const terrainBlocked = terrainFloor !== undefined && nextY <= terrainFloor;
+            if (solidBlocked || terrainBlocked) {
+                const solidTop = solidBlocked
+                    ? (supportTopWithin(body.x, body.z, nextY, body.y + dims.height, isSolid, dims) ?? Math.floor(body.y))
+                    : undefined;
+                body.y = Math.max(solidTop ?? -Infinity, terrainFloor ?? -Infinity);
+                body.velocityY = 0;
+                body.grounded = true;
+            }
+            else {
+                body.y = nextY;
+            }
+        }
+        else if (overlapsSolid(body.x, nextY, body.z, isSolid, dims)) {
+            body.velocityY = 0;
+        }
+        else {
+            body.y = nextY;
+        }
+    }
+}

package/dist/multiplayer/chatContract.d.ts

@@ -0,0 +1,42 @@
+import type { ChatMessage } from "../game/chat.js";
+export interface ChatSendArgs {
+    channelId: string;
+    body: string;
+}
+export interface ChatSendOutcome {
+    ok: boolean;
+    reason?: string;
+}
+export interface ChatActions {
+    sendMessage(args: ChatSendArgs): Promise<ChatSendOutcome>;
+}
+/**
+ * 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.
+ */
+export interface ChatTransport {
+    useMessages(channelId: string | "skip"): readonly ChatMessage[] | undefined;
+    useActions(): ChatActions;
+}
+/**
+ * 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/react's chatTransportFromSync
+ * lifts a ChatSync into a ChatTransport.
+ */
+export interface ChatSync {
+    subscribe(channelId: string, onChange: (messages: readonly ChatMessage[]) => void): () => void;
+    send(channelId: string, body: string): Promise<ChatSendOutcome>;
+}
+export declare function createLocalChatTransport(options?: {
+    userId?: string;
+    historyLimit?: number;
+    now?: () => number;
+}): {
+    transport: ChatTransport;
+    sync: ChatSync;
+    actions: ChatActions;
+};

package/dist/multiplayer/chatContract.js

@@ -0,0 +1,57 @@
+export function createLocalChatTransport(options) {
+    const userId = options?.userId ?? "local";
+    const historyLimit = options?.historyLimit ?? 100;
+    const now = options?.now ?? Date.now;
+    const messagesByChannel = new Map();
+    const listeners = new Map();
+    let counter = 0;
+    function snapshot(channelId) {
+        return (messagesByChannel.get(channelId) ?? []).slice();
+    }
+    const sync = {
+        subscribe(channelId, onChange) {
+            let set = listeners.get(channelId);
+            if (set === undefined) {
+                set = new Set();
+                listeners.set(channelId, set);
+            }
+            set.add(onChange);
+            onChange(snapshot(channelId));
+            return () => {
+                set.delete(onChange);
+                if (set.size === 0)
+                    listeners.delete(channelId);
+            };
+        },
+        send(channelId, body) {
+            const trimmed = body.trim();
+            if (trimmed.length === 0)
+                return Promise.resolve({ ok: false, reason: "empty message" });
+            counter += 1;
+            const message = {
+                id: `local_${counter}`,
+                channelId,
+                fromUserId: userId,
+                body: trimmed,
+                at: now(),
+            };
+            const ring = messagesByChannel.get(channelId) ?? [];
+            ring.push(message);
+            if (ring.length > historyLimit)
+                ring.splice(0, ring.length - historyLimit);
+            messagesByChannel.set(channelId, ring);
+            const current = snapshot(channelId);
+            for (const listener of listeners.get(channelId) ?? [])
+                listener(current);
+            return Promise.resolve({ ok: true });
+        },
+    };
+    const actions = {
+        sendMessage: (args) => sync.send(args.channelId, args.body),
+    };
+    const transport = {
+        useMessages: (channelId) => (channelId === "skip" ? undefined : snapshot(channelId)),
+        useActions: () => actions,
+    };
+    return { transport, sync, actions };
+}

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

@@ -0,0 +1,13 @@
+export interface AuthSession {
+    userId: string;
+    displayName?: string;
+    avatarUrl?: string;
+    email?: string;
+    isNew?: boolean;
+}
+export interface PlayerIdentity {
+    userId: string;
+    isNew: boolean;
+}
+export declare function sessionPlayer(session: AuthSession): PlayerIdentity;
+export declare function resolveGuestSession(seed?: string): AuthSession;

package/dist/multiplayer/identity.js

@@ -0,0 +1,20 @@
+export function sessionPlayer(session) {
+    return { userId: session.userId, isNew: session.isNew ?? false };
+}
+const DEFAULT_GUEST_SEED = "local";
+export function resolveGuestSession(seed) {
+    const normalized = seed === undefined || seed.trim().length === 0 ? DEFAULT_GUEST_SEED : seed.trim();
+    const hash = fnv1a(normalized);
+    return {
+        userId: `guest_${hash}`,
+        displayName: `Guest ${hash.slice(0, 4).toUpperCase()}`,
+    };
+}
+function fnv1a(input) {
+    let hash = 0x811c9dc5;
+    for (let index = 0; index < input.length; index += 1) {
+        hash ^= input.charCodeAt(index);
+        hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    return hash.toString(36);
+}

package/dist/multiplayer/poseSyncGate.d.ts

@@ -4,6 +4,7 @@ export interface PlayerPose {
     z: number;
     rotationY: number;
     rotationPitch: number;
+    appearance?: Record<string, string>;
 }
 export interface PoseSyncTuning {
     minIntervalMs: number;

package/dist/multiplayer/poseSyncGate.js

@@ -1,9 +1,21 @@
+function appearanceChanged(a, b) {
+    if (a === b)
+        return false;
+    if (a === undefined || b === undefined)
+        return true;
+    const aKeys = Object.keys(a);
+    const bKeys = Object.keys(b);
+    if (aKeys.length !== bKeys.length)
+        return true;
+    return aKeys.some((key) => a[key] !== b[key]);
+}
 function poseChanged(a, b, tuning) {
     return (Math.abs(a.x - b.x) > tuning.positionEpsilon
         || Math.abs(a.y - b.y) > tuning.verticalEpsilon
         || Math.abs(a.z - b.z) > tuning.positionEpsilon
         || Math.abs(a.rotationY - b.rotationY) > tuning.rotationEpsilon
-        || Math.abs(a.rotationPitch - b.rotationPitch) > tuning.rotationEpsilon);
+        || Math.abs(a.rotationPitch - b.rotationPitch) > tuning.rotationEpsilon
+        || appearanceChanged(a.appearance, b.appearance));
 }
 export function createPoseSyncGate(tuning) {
     let lastSentPose = null;

package/dist/multiplayer/presenceModel.d.ts

@@ -7,6 +7,7 @@ export interface PresencePoseState {
     rotationY: number;
     rotationPitch?: number;
     lastSeenAtMs?: number;
+    appearance?: Record<string, string>;
 }
 export interface IncomingPose {
     position: {
@@ -16,12 +17,15 @@ export interface IncomingPose {
     };
     rotationY?: number;
     rotationPitch?: number;
+    appearance?: Record<string, string>;
 }
 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;
@@ -36,12 +40,23 @@ export interface PoseSyncDecision {
     };
     rotationY: number;
     rotationPitch: number;
+    appearance?: Record<string, string>;
     /** True when the pose differs and a pose write is needed. */
     changed: boolean;
     /** 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

@@ -1,5 +1,26 @@
-export function decidePoseSync(current, incoming, rules, nowMs) {
-    const elapsedSec = Math.max(rules.minElapsedSec, Math.min(rules.maxElapsedSec, (nowMs - (current.lastSeenAtMs ?? nowMs)) / 1000));
+function appearanceEqual(a, b) {
+    if (a === b)
+        return true;
+    if (a === undefined || b === undefined)
+        return false;
+    const aKeys = Object.keys(a);
+    const bKeys = Object.keys(b);
+    if (aKeys.length !== bKeys.length)
+        return false;
+    return aKeys.every((key) => a[key] === b[key]);
+}
+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;
@@ -12,19 +33,24 @@ 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;
+    const appearanceChanged = incoming.appearance !== undefined && !appearanceEqual(incoming.appearance, current.appearance);
     const moved = targetX !== current.position.x || targetZ !== current.position.z;
     const jumped = nextY !== current.position.y;
     const rotated = nextRotationY !== current.rotationY || nextRotationPitch !== (current.rotationPitch ?? 0);
-    const changed = moved || jumped || rotated;
+    const changed = moved || jumped || rotated || appearanceChanged;
     return {
         position: { x: targetX, y: nextY, z: targetZ },
         rotationY: nextRotationY,
         rotationPitch: nextRotationPitch,
+        appearance: nextAppearance,
         changed,
         refreshKeepAlive: !changed && shouldRefreshKeepAlive(current.lastSeenAtMs, nowMs, rules),
     };