@jgengine/core 0.6.0 → 0.8.0

package/dist/runtime/persistenceScope.js

@@ -0,0 +1,64 @@
+export function partitionScopes(state, schema) {
+    const runKeys = new Set(schema.run);
+    const meta = {};
+    const run = {};
+    for (const key of Object.keys(state)) {
+        if (runKeys.has(key))
+            run[key] = state[key];
+        else
+            meta[key] = state[key];
+    }
+    return { meta, run };
+}
+export function resetRun(scoped) {
+    return { meta: scoped.meta, run: {} };
+}
+export function mergeScopes(scoped) {
+    return { ...scoped.meta, ...scoped.run };
+}
+const RUN_FIELD_DEFAULTS = {
+    inventories: {},
+    economy: {},
+    unlocks: [],
+    quests: undefined,
+    social: undefined,
+    leaderboard: {},
+    session: {},
+};
+export function clearRunFields(player, runFields) {
+    const next = { ...player };
+    for (const field of runFields) {
+        if (field === "userId")
+            continue;
+        const key = field;
+        if (key in RUN_FIELD_DEFAULTS) {
+            const template = RUN_FIELD_DEFAULTS[key];
+            if (template === undefined)
+                delete next[field];
+            else
+                next[field] = Array.isArray(template) ? [...template] : { ...template };
+        }
+        else {
+            delete next[field];
+        }
+    }
+    return next;
+}
+export function applyRunReset(profile, runFields, now) {
+    return {
+        ...profile,
+        playerState: clearRunFields(profile.playerState, runFields),
+        revision: profile.revision + 1,
+        updatedAt: now,
+    };
+}
+export function planScenarioReset(reset) {
+    return {
+        gameId: reset.gameId,
+        serverId: reset.serverId ?? null,
+        wipeChunks: reset.wipeChunks ?? true,
+        wipeServerSession: reset.wipeServerSession ?? true,
+        resetPlayers: reset.resetPlayers === "run" ? "run" : "none",
+        runFields: reset.runFields ?? [],
+    };
+}

package/dist/runtime/transport.d.ts

@@ -1,3 +1,5 @@
+import type { ChatSync } from "../multiplayer/chatContract.js";
+import type { PlayerPose } from "../multiplayer/poseSyncGate.js";
 import type { PresenceTransport } from "../multiplayer/presenceContract.js";
 export type JoinServerResult = {
     serverId: string;
@@ -58,3 +60,33 @@ export type GameBackend<TPresenceRow = unknown, TPresenceLocation = unknown, TGa
     feeds?: GameRuntimeFeeds;
     presence?: PresenceTransport<TPresenceRow, TPresenceLocation, TGameId>;
 };
+export type PresencePoseRow = {
+    userId: string;
+    position: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    rotationY: number;
+    rotationPitch: number;
+    lastSeenAt: number;
+};
+export type PresenceSync = {
+    subscribe: (serverId: string, onChange: (rows: PresencePoseRow[]) => void) => FeedUnsubscribe;
+    syncPose: (serverId: string, pose: PlayerPose) => void;
+};
+export type LiveGameBackend<TPresenceRow = unknown, TPresenceLocation = unknown, TGameId extends string = string> = GameBackend<TPresenceRow, TPresenceLocation, TGameId> & {
+    presenceSync: PresenceSync;
+    pushFeedEntry: (args: {
+        serverId: string;
+        action: string;
+        entry: unknown;
+    }) => Promise<void>;
+    chatSyncFor?: (serverId: string) => ChatSync;
+};
+export type MultiplayerSession = {
+    gameId: string;
+    userId: string;
+    backend: LiveGameBackend;
+    feedActions: string[];
+};

package/dist/scene/autoTarget.d.ts

@@ -0,0 +1,15 @@
+export type AutoTargetPolicy = "nearest" | "farthest" | "random" | "strongest" | "weakest" | "first" | "last";
+export interface AutoTargetDeps {
+    candidates: (fromId: string) => readonly string[];
+    distance: (fromId: string, toId: string) => number | null;
+    strength?: (toId: string) => number;
+    progress?: (toId: string) => number;
+    rng?: () => number;
+}
+export declare function selectAutoTarget(policy: AutoTargetPolicy, fromId: string, deps: AutoTargetDeps): string | null;
+export interface AutoTargeter {
+    policy(): AutoTargetPolicy;
+    setPolicy(policy: AutoTargetPolicy): void;
+    pick(fromId: string): string | null;
+}
+export declare function createAutoTargeter(policy: AutoTargetPolicy, deps: AutoTargetDeps): AutoTargeter;

package/dist/scene/autoTarget.js

@@ -0,0 +1,54 @@
+function metric(policy, fromId, toId, deps) {
+    switch (policy) {
+        case "nearest":
+        case "farthest":
+            return deps.distance(fromId, toId);
+        case "strongest":
+        case "weakest":
+            return deps.strength?.(toId) ?? 0;
+        case "first":
+        case "last":
+            return deps.progress?.(toId) ?? 0;
+        case "random":
+            return 0;
+    }
+}
+function prefersHigher(policy) {
+    return policy === "farthest" || policy === "strongest" || policy === "first";
+}
+export function selectAutoTarget(policy, fromId, deps) {
+    const candidates = deps.candidates(fromId).filter((id) => id !== fromId);
+    if (candidates.length === 0)
+        return null;
+    if (policy === "random") {
+        const rng = deps.rng ?? Math.random;
+        return candidates[Math.min(candidates.length - 1, Math.floor(rng() * candidates.length))];
+    }
+    const higher = prefersHigher(policy);
+    let best = null;
+    let bestScore = higher ? Number.NEGATIVE_INFINITY : Number.POSITIVE_INFINITY;
+    for (const id of candidates) {
+        const score = metric(policy, fromId, id, deps);
+        if (score === null)
+            continue;
+        if (best === null || (higher ? score > bestScore : score < bestScore)) {
+            best = id;
+            bestScore = score;
+        }
+    }
+    return best;
+}
+export function createAutoTargeter(policy, deps) {
+    let current = policy;
+    return {
+        policy() {
+            return current;
+        },
+        setPolicy(next) {
+            current = next;
+        },
+        pick(fromId) {
+            return selectAutoTarget(current, fromId, deps);
+        },
+    };
+}

package/dist/scene/behaviors.d.ts

@@ -1,8 +1,15 @@
 import { type ProximityPrompt } from "../interaction/proximityPrompt.js";
+import type { Waypoint } from "../nav/pathFollow.js";
 export interface WanderBehavior {
     kind: "wander";
     radius: number;
 }
+export interface PatrolBehavior {
+    kind: "patrol";
+    waypoints: readonly Waypoint[];
+    speed: number;
+    loop: boolean;
+}
 export interface PromptableBehavior {
     kind: "promptable";
     prompt: ProximityPrompt;
@@ -10,10 +17,15 @@ export interface PromptableBehavior {
 export interface PlayerBehavior {
     kind: "player";
 }
-export type BehaviorDescriptor = WanderBehavior | PromptableBehavior | PlayerBehavior;
+export type BehaviorDescriptor = WanderBehavior | PatrolBehavior | PromptableBehavior | PlayerBehavior;
 export declare function wander({ radius }: {
     radius: number;
 }): WanderBehavior;
+export declare function patrol({ waypoints, speed, loop, }: {
+    waypoints: readonly Waypoint[];
+    speed: number;
+    loop?: boolean;
+}): PatrolBehavior;
 export declare function promptable(prompt: ProximityPrompt): PromptableBehavior;
 export declare function talkable(dialogueId: string): PromptableBehavior;
 export declare function player(): PlayerBehavior;

package/dist/scene/behaviors.js

@@ -2,6 +2,9 @@ import { command, keybind, proximityPrompt, } from "../interaction/proximityProm
 export function wander({ radius }) {
     return { kind: "wander", radius };
 }
+export function patrol({ waypoints, speed, loop = true, }) {
+    return { kind: "patrol", waypoints, speed, loop };
+}
 export function promptable(prompt) {
     return { kind: "promptable", prompt };
 }

package/dist/scene/captureCheck.d.ts

@@ -0,0 +1,7 @@
+export interface CaptureCheckInput {
+    hpFraction: number;
+    catchPower: number;
+    difficulty?: number;
+}
+export declare function captureChance(input: CaptureCheckInput): number;
+export declare function rollCapture(input: CaptureCheckInput, rng?: () => number): boolean;

package/dist/scene/captureCheck.js

@@ -0,0 +1,11 @@
+function clamp01(value) {
+    return Math.min(1, Math.max(0, value));
+}
+export function captureChance(input) {
+    const difficulty = input.difficulty ?? 1;
+    const hpFactor = 1 - clamp01(input.hpFraction) * 0.6;
+    return clamp01((input.catchPower * hpFactor) / Math.max(difficulty, 0.0001));
+}
+export function rollCapture(input, rng = Math.random) {
+    return rng() < captureChance(input);
+}

package/dist/scene/entityStore.d.ts

@@ -2,6 +2,7 @@ import type { BehaviorDescriptor } from "./behaviors.js";
 export type EntityRole = "player" | "npc" | "prop";
 export interface EntityMovement {
     walkSpeed?: number;
+    frozen?: boolean;
 }
 export type EntityPosition = readonly [number, number, number];
 export type SpawnPositionInput = EntityPosition | {
@@ -25,6 +26,7 @@ export interface SceneEntity<TMeta = undefined> {
 }
 /** Ground speed (horizontal magnitude of velocity) in world units per second. Scale to km/h or mph in game code. */
 export declare function groundSpeed(entity: SceneEntity<unknown>): number;
+export declare function movedWhileFrozen(entity: SceneEntity<unknown>, threshold?: number): boolean;
 export interface SpawnOptions<TMeta = undefined> {
     id?: string;
     position?: SpawnPositionInput;
@@ -44,15 +46,21 @@ export interface EntityPose {
     /** Seconds since the previous pose; when > 0 the store derives `velocity` from the position delta. Omit for teleports (velocity unchanged). */
     dt?: number;
 }
+export interface SpawnPose {
+    position: EntityPosition;
+    rotationY: number;
+}
 export interface EntityStore<TMeta = undefined> {
     spawn(name: string, options?: SpawnOptions<TMeta>): string;
     despawn(id: string): boolean;
-    update(id: string, patch: Partial<Pick<SceneEntity<TMeta>, "position" | "rotationY" | "rotationX" | "rotationZ" | "role" | "movement" | "behaviors" | "meta">>): boolean;
+    update(id: string, patch: Partial<Pick<SceneEntity<TMeta>, "name" | "position" | "rotationY" | "rotationX" | "rotationZ" | "role" | "movement" | "behaviors" | "meta">>): boolean;
     setPose(id: string, pose: EntityPose): boolean;
     get(id: string): SceneEntity<TMeta> | null;
     list(): readonly SceneEntity<TMeta>[];
     clear(): void;
     subscribe(listener: () => void): () => void;
     snapshot(): readonly SceneEntity<TMeta>[];
+    spawnPoseOf(id: string): SpawnPose | null;
+    resetToSpawn(id: string): boolean;
 }
 export declare function createEntityStore<TMeta = undefined>(): EntityStore<TMeta>;

package/dist/scene/entityStore.js

@@ -3,6 +3,13 @@ import { createObservableKeyedStore } from "../store/observableKeyedStore.js";
 export function groundSpeed(entity) {
     return Math.hypot(entity.velocity[0], entity.velocity[2]);
 }
+const DEFAULT_FROZEN_MOVE_THRESHOLD = 1e-6;
+export function movedWhileFrozen(entity, threshold = DEFAULT_FROZEN_MOVE_THRESHOLD) {
+    if (entity.movement.frozen !== true)
+        return false;
+    const speed = Math.hypot(entity.velocity[0], entity.velocity[1], entity.velocity[2]);
+    return speed > threshold;
+}
 function toEntityPosition(position) {
     if (position === undefined)
         return [0, 0, 0];
@@ -12,6 +19,7 @@ function toEntityPosition(position) {
 }
 export function createEntityStore() {
     const store = createObservableKeyedStore();
+    const spawnPoses = new Map();
     let nextCounter = 1;
     function generateId() {
         let id = `entity-${nextCounter}`;
@@ -28,11 +36,13 @@ export function createEntityStore() {
                 throw new Error(`Scene entity id "${options.id}" is already spawned.`);
             }
             const id = options.id ?? generateId();
+            const position = toEntityPosition(options.position);
+            const rotationY = options.rotationY ?? 0;
             store.set(id, {
                 id,
                 name,
-                position: toEntityPosition(options.position),
-                rotationY: options.rotationY ?? 0,
+                position,
+                rotationY,
                 rotationX: options.rotationX ?? 0,
                 rotationZ: options.rotationZ ?? 0,
                 velocity: [0, 0, 0],
@@ -41,11 +51,13 @@ export function createEntityStore() {
                 behaviors: options.behaviors ?? [],
                 meta: options.meta,
             });
+            spawnPoses.set(id, { position, rotationY });
             return id;
         },
         despawn(id) {
             const existed = store.has(id);
             store.delete(id);
+            spawnPoses.delete(id);
             return existed;
         },
         update(id, patch) {
@@ -94,5 +106,16 @@ export function createEntityStore() {
         snapshot() {
             return store.arraySnapshot();
         },
+        spawnPoseOf(id) {
+            return spawnPoses.get(id) ?? null;
+        },
+        resetToSpawn(id) {
+            const pose = spawnPoses.get(id);
+            const current = store.get(id);
+            if (pose === undefined || current === undefined)
+                return false;
+            store.set(id, { ...current, position: pose.position, rotationY: pose.rotationY, velocity: [0, 0, 0] });
+            return true;
+        },
     };
 }

package/dist/scene/form.d.ts

@@ -0,0 +1,40 @@
+import type { EntityMovement, SceneEntity } from "./entityStore.js";
+export interface FormDef {
+    id: string;
+    movement?: EntityMovement;
+    abilities?: readonly string[];
+    model?: string;
+}
+export interface FormChangedEvent {
+    instanceId: string;
+    formId: string | null;
+}
+export interface FormEntities {
+    get(id: string): SceneEntity | null;
+    update(id: string, patch: {
+        movement?: EntityMovement;
+        name?: string;
+    }): boolean;
+}
+export interface FormTime {
+    after(seconds: number, callback: () => void): () => void;
+}
+export interface FormEvents {
+    emit(name: "form.changed", payload: FormChangedEvent): void;
+}
+export interface FormsDeps {
+    entities: FormEntities;
+    time: FormTime;
+    events?: FormEvents;
+}
+export interface Forms {
+    register(defs: readonly FormDef[]): void;
+    get(formId: string): FormDef | null;
+    abilities(instanceId: string): readonly string[] | null;
+    active(instanceId: string): string | null;
+    shapeshift(instanceId: string, formId: string, durationSeconds?: number): {
+        reason: string;
+    } | null;
+    revert(instanceId: string): void;
+}
+export declare function createForms(deps: FormsDeps): Forms;

package/dist/scene/form.js

@@ -0,0 +1,56 @@
+export function createForms(deps) {
+    const defs = new Map();
+    const runtime = new Map();
+    function emitChange(instanceId, formId) {
+        deps.events?.emit("form.changed", { instanceId, formId });
+    }
+    function revertInternal(instanceId) {
+        const state = runtime.get(instanceId);
+        if (state === undefined)
+            return;
+        state.cancelTimer?.();
+        runtime.delete(instanceId);
+        deps.entities.update(instanceId, { movement: state.baseline.movement, name: state.baseline.name });
+        emitChange(instanceId, null);
+    }
+    return {
+        register(list) {
+            for (const def of list)
+                defs.set(def.id, def);
+        },
+        get(formId) {
+            return defs.get(formId) ?? null;
+        },
+        abilities(instanceId) {
+            const state = runtime.get(instanceId);
+            if (state === undefined)
+                return null;
+            return defs.get(state.formId)?.abilities ?? null;
+        },
+        active(instanceId) {
+            return runtime.get(instanceId)?.formId ?? null;
+        },
+        shapeshift(instanceId, formId, durationSeconds) {
+            const def = defs.get(formId);
+            if (def === undefined)
+                return { reason: `unknown form "${formId}"` };
+            const entity = deps.entities.get(instanceId);
+            if (entity === null)
+                return { reason: `entity "${instanceId}" is not spawned` };
+            const existing = runtime.get(instanceId);
+            existing?.cancelTimer?.();
+            const baseline = existing?.baseline ?? { movement: entity.movement, name: entity.name };
+            deps.entities.update(instanceId, {
+                movement: def.movement ?? baseline.movement,
+                name: def.model ?? baseline.name,
+            });
+            const cancelTimer = durationSeconds === undefined ? null : deps.time.after(durationSeconds, () => revertInternal(instanceId));
+            runtime.set(instanceId, { baseline, formId, cancelTimer });
+            emitChange(instanceId, formId);
+            return null;
+        },
+        revert(instanceId) {
+            revertInternal(instanceId);
+        },
+    };
+}

package/dist/scene/mount.d.ts

@@ -0,0 +1,62 @@
+export type MountKind = "ground" | "boat" | "flying" | "swimming";
+export interface MountKit {
+    kind: MountKind;
+    moveSpeed?: number;
+    turnSpeed?: number;
+}
+export interface MountSeat {
+    id: string;
+    offset: readonly [number, number, number];
+    control?: boolean;
+}
+export interface RideableConfig {
+    id: string;
+    kit: MountKit;
+    seats?: readonly MountSeat[];
+}
+export interface SeatRef {
+    mountId: string;
+    seatId: string;
+}
+export interface Occupant {
+    riderId: string;
+    seatId: string;
+}
+export type MountResult = {
+    ok: true;
+    seat: MountSeat;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Mount / rideable control-transfer (issue #83). Registers rideables (each with one or more seats — a
+ * control seat drives, the rest ride) and tracks who is on what. It owns no camera or physics: game code
+ * reads `cameraTarget(riderId)` to point the follow camera at the mount, and `driveTarget(riderId)` to
+ * route that rider's {@link import("../physics/vehicleBody.js").AxisInput}-driven input at the mount's
+ * movement kit — the same seam a horse, a truck, or a shared multi-seat ship all plug into.
+ */
+export declare class MountController {
+    private readonly mounts;
+    private readonly seatOfRider;
+    register(config: RideableConfig): void;
+    isRegistered(mountId: string): boolean;
+    kitOf(mountId: string): MountKit | null;
+    seatsOf(mountId: string): readonly MountSeat[];
+    private firstFreeSeat;
+    mount(riderId: string, mountId: string, seatId?: string): MountResult;
+    dismount(riderId: string): string | null;
+    seatOf(riderId: string): SeatRef | null;
+    isSeated(riderId: string): boolean;
+    seatOffset(riderId: string): readonly [number, number, number] | null;
+    occupants(mountId: string): readonly Occupant[];
+    driver(mountId: string): string | null;
+    /** Entity the follow camera should track for this rider: the mount when seated, else the rider. */
+    cameraTarget(riderId: string): string;
+    /**
+     * Entity this rider's input drives: the mount when in a control seat, `null` for a passenger seat
+     * (they ride but do not steer), and the rider themselves when not mounted at all.
+     */
+    driveTarget(riderId: string): string | null;
+}
+export declare function createMountController(): MountController;

package/dist/scene/mount.js

@@ -0,0 +1,107 @@
+const DEFAULT_SEAT = { id: "driver", offset: [0, 0, 0], control: true };
+/**
+ * Mount / rideable control-transfer (issue #83). Registers rideables (each with one or more seats — a
+ * control seat drives, the rest ride) and tracks who is on what. It owns no camera or physics: game code
+ * reads `cameraTarget(riderId)` to point the follow camera at the mount, and `driveTarget(riderId)` to
+ * route that rider's {@link import("../physics/vehicleBody.js").AxisInput}-driven input at the mount's
+ * movement kit — the same seam a horse, a truck, or a shared multi-seat ship all plug into.
+ */
+export class MountController {
+    mounts = new Map();
+    seatOfRider = new Map();
+    register(config) {
+        const seats = config.seats !== undefined && config.seats.length > 0 ? config.seats : [DEFAULT_SEAT];
+        this.mounts.set(config.id, { config, seats, bySeat: new Map() });
+    }
+    isRegistered(mountId) {
+        return this.mounts.has(mountId);
+    }
+    kitOf(mountId) {
+        return this.mounts.get(mountId)?.config.kit ?? null;
+    }
+    seatsOf(mountId) {
+        return this.mounts.get(mountId)?.seats ?? [];
+    }
+    firstFreeSeat(reg) {
+        const control = reg.seats.find((s) => s.control === true && !reg.bySeat.has(s.id));
+        if (control !== undefined)
+            return control;
+        return reg.seats.find((s) => !reg.bySeat.has(s.id)) ?? null;
+    }
+    mount(riderId, mountId, seatId) {
+        const reg = this.mounts.get(mountId);
+        if (reg === undefined)
+            return { ok: false, reason: "unknown_mount" };
+        const seat = seatId !== undefined ? reg.seats.find((s) => s.id === seatId) : this.firstFreeSeat(reg);
+        if (seat === undefined)
+            return { ok: false, reason: "unknown_seat" };
+        if (seat === null)
+            return { ok: false, reason: "mount_full" };
+        if (reg.bySeat.has(seat.id))
+            return { ok: false, reason: "seat_taken" };
+        this.dismount(riderId);
+        reg.bySeat.set(seat.id, riderId);
+        this.seatOfRider.set(riderId, { mountId, seatId: seat.id });
+        return { ok: true, seat };
+    }
+    dismount(riderId) {
+        const ref = this.seatOfRider.get(riderId);
+        if (ref === undefined)
+            return null;
+        this.mounts.get(ref.mountId)?.bySeat.delete(ref.seatId);
+        this.seatOfRider.delete(riderId);
+        return ref.mountId;
+    }
+    seatOf(riderId) {
+        return this.seatOfRider.get(riderId) ?? null;
+    }
+    isSeated(riderId) {
+        return this.seatOfRider.has(riderId);
+    }
+    seatOffset(riderId) {
+        const ref = this.seatOfRider.get(riderId);
+        if (ref === undefined)
+            return null;
+        return this.mounts.get(ref.mountId)?.seats.find((s) => s.id === ref.seatId)?.offset ?? null;
+    }
+    occupants(mountId) {
+        const reg = this.mounts.get(mountId);
+        if (reg === undefined)
+            return [];
+        return reg.seats
+            .filter((s) => reg.bySeat.has(s.id))
+            .map((s) => ({ riderId: reg.bySeat.get(s.id), seatId: s.id }));
+    }
+    driver(mountId) {
+        const reg = this.mounts.get(mountId);
+        if (reg === undefined)
+            return null;
+        for (const seat of reg.seats) {
+            if (seat.control === true) {
+                const rider = reg.bySeat.get(seat.id);
+                if (rider !== undefined)
+                    return rider;
+            }
+        }
+        return null;
+    }
+    /** Entity the follow camera should track for this rider: the mount when seated, else the rider. */
+    cameraTarget(riderId) {
+        const ref = this.seatOfRider.get(riderId);
+        return ref === undefined ? riderId : ref.mountId;
+    }
+    /**
+     * Entity this rider's input drives: the mount when in a control seat, `null` for a passenger seat
+     * (they ride but do not steer), and the rider themselves when not mounted at all.
+     */
+    driveTarget(riderId) {
+        const ref = this.seatOfRider.get(riderId);
+        if (ref === undefined)
+            return riderId;
+        const seat = this.mounts.get(ref.mountId)?.seats.find((s) => s.id === ref.seatId);
+        return seat?.control === true ? ref.mountId : null;
+    }
+}
+export function createMountController() {
+    return new MountController();
+}

package/dist/scene/movementSpeed.d.ts

@@ -0,0 +1,35 @@
+import type { StatValue } from "./entityStats.js";
+export interface MovementSpeedModifiers {
+    multiplier?: number;
+    flatBonus?: number;
+}
+/** `base * (multiplier ?? 1) + (flatBonus ?? 0)`, clamped to never go negative. */
+export declare function deriveWalkSpeed(base: number, modifiers: MovementSpeedModifiers): number;
+export interface MovementSpeedDeps {
+    stats: {
+        get(instanceId: string, statId: string): StatValue | null;
+    };
+    entities: {
+        get(id: string): {
+            movement?: {
+                walkSpeed?: number;
+            };
+        } | null;
+        update(id: string, patch: {
+            movement: {
+                walkSpeed: number;
+            };
+        }): boolean;
+    };
+}
+export interface MovementSpeedConfig {
+    baseSpeed: number;
+    multiplierStat?: string;
+    flatBonusStat?: string;
+}
+/**
+ * Recomputes `movement.walkSpeed` for an entity from its stats and writes it back via `deps.entities.update`.
+ * Either stat id is optional; an omitted or unresolved stat contributes its neutral value (multiplier 1,
+ * flat bonus 0) rather than failing. Returns false only when the entity itself doesn't exist.
+ */
+export declare function applyStatDrivenSpeed(deps: MovementSpeedDeps, instanceId: string, config: MovementSpeedConfig): boolean;

package/dist/scene/movementSpeed.js

@@ -0,0 +1,20 @@
+/** `base * (multiplier ?? 1) + (flatBonus ?? 0)`, clamped to never go negative. */
+export function deriveWalkSpeed(base, modifiers) {
+    const multiplier = modifiers.multiplier ?? 1;
+    const flatBonus = modifiers.flatBonus ?? 0;
+    return Math.max(0, base * multiplier + flatBonus);
+}
+/**
+ * Recomputes `movement.walkSpeed` for an entity from its stats and writes it back via `deps.entities.update`.
+ * Either stat id is optional; an omitted or unresolved stat contributes its neutral value (multiplier 1,
+ * flat bonus 0) rather than failing. Returns false only when the entity itself doesn't exist.
+ */
+export function applyStatDrivenSpeed(deps, instanceId, config) {
+    const entity = deps.entities.get(instanceId);
+    if (entity === null)
+        return false;
+    const multiplier = config.multiplierStat !== undefined ? deps.stats.get(instanceId, config.multiplierStat)?.current : undefined;
+    const flatBonus = config.flatBonusStat !== undefined ? deps.stats.get(instanceId, config.flatBonusStat)?.current : undefined;
+    const walkSpeed = deriveWalkSpeed(config.baseSpeed, { multiplier, flatBonus });
+    return deps.entities.update(instanceId, { movement: { ...entity.movement, walkSpeed } });
+}