@jgengine/core 0.5.0 → 0.7.0

package/dist/runtime/gameContext.js

@@ -1,14 +1,18 @@
-import { createDeathSystem, deathReasonFromEffect } from "../combat/death.js";
+import { createDeathSystem, deathReasonFromEffect, normalizeOnDeath } from "../combat/death.js";
 import { createEffectSystem, } from "../combat/effects.js";
 import { createProjectileSystem } from "../combat/projectiles.js";
+import { resolveHitReaction, } from "../combat/hitReaction.js";
+import { pointInTelegraph, } from "../combat/telegraph.js";
 import { createCommandRegistry, } from "../commands/commandRegistry.js";
 import { balance as walletBalance, canAfford as walletCanAfford, charge as walletCharge, chargeAll as walletChargeAll, createEmptyWallet, grant as walletGrant, } from "../economy/wallet.js";
+import { createCosmetics } from "../game/cosmetics.js";
 import { createGameEvents } from "../game/events.js";
 import { createGameFeed } from "../game/feed.js";
 import { createLeaderboard } from "../game/leaderboard.js";
 import { createLoadouts } from "../game/loadout.js";
 import { createLootRegistry, grantDrops } from "../game/lootTable.js";
 import { createQuestJournal } from "../game/quest.js";
+import { createWorldItemStore, resolveDeathDrops, DEFAULT_RARITY, WORLD_ITEM_ENTITY_NAME, } from "../game/worldItem.js";
 import { createSocial } from "../game/social.js";
 import { createTradeSystem } from "../game/trade.js";
 import { createUnlocks } from "../game/unlocks.js";
@@ -17,15 +21,20 @@ import { createItemUse, } from "../item/use.js";
 import { createWeaponStats } from "../item/weapon.js";
 import { createPoseState } from "../movement/poseState.js";
 import { createEntityStatsApi, seedStatValues, setStatValue, } from "../scene/entityStats.js";
+import { createForms } from "../scene/form.js";
 import { createObjectStore } from "../scene/objectStore.js";
+import { createRoster } from "../scene/roster.js";
+import { createPossession } from "../scene/possession.js";
 import { createSpatialApi } from "../scene/spatial.js";
 import { createTargeting } from "../scene/targeting.js";
 import { createStats } from "../stats/statModifiers.js";
 import { createChangeSignal, notifyAfter } from "../store/changeSignal.js";
+import { createSimClock } from "../time/simClock.js";
 export function createGameContext(options) {
     const { definition, content, player } = options;
     const now = options.now ?? Date.now;
     const signal = createChangeSignal();
+    const time = createSimClock({ config: definition.time, onChange: signal.notify });
     const entities = definition.scene;
     const objects = createObjectStore();
     entities.subscribe(signal.notify);
@@ -78,17 +87,29 @@ export function createGameContext(options) {
     const feed = createGameFeed();
     const lootRegistry = createLootRegistry();
     const unlocks = notifyAfter(createUnlocks(), ["grant", "hydrate"], signal.notify);
-    const rawSocial = createSocial({ events, now });
+    const rawSocial = createSocial({
+        events,
+        now,
+        emotes: {
+            entities: { get: (id) => entities.get(id) },
+            spatial: { inRadius: (center, radius, filter) => spatial.inRadius(center, radius, filter) },
+        },
+    });
     const social = {
         friends: notifyAfter(rawSocial.friends, ["request", "accept", "remove", "block", "hydrate"], signal.notify),
         party: notifyAfter(rawSocial.party, ["invite", "accept", "kick", "leave", "promote"], signal.notify),
         presence: rawSocial.presence,
+        emotes: rawSocial.emotes,
     };
     const leaderboard = notifyAfter(createLeaderboard(), ["increment", "hydrate"], signal.notify);
+    const roster = notifyAfter(createRoster({ now }), ["capture", "release", "setEquipped", "hydrate"], signal.notify);
     const playerStats = createStats({});
     const pose = createPoseState((instanceId) => catalogEntry(instanceId)?.movement);
     const commandRegistry = createCommandRegistry();
     const itemUse = createItemUse((itemId) => content.itemById?.(itemId)?.use);
+    const possession = notifyAfter(createPossession({ entities, events }), ["possess", "own", "disown"], signal.notify);
+    const forms = notifyAfter(createForms({ entities, time, events }), ["shapeshift", "revert"], signal.notify);
+    const cosmetics = notifyAfter(createCosmetics({ events }), ["apply", "equip", "hydrate"], signal.notify);
     const inventoryDeclarations = definition.inventories ?? {};
     const inventoryIds = Object.keys(inventoryDeclarations);
     const layouts = {};
@@ -240,6 +261,37 @@ export function createGameContext(options) {
         pose.clear(instanceId);
         return existed;
     }
+    const worldItems = notifyAfter(createWorldItemStore({
+        spawnEntity: (position) => entities.spawn(WORLD_ITEM_ENTITY_NAME, { position, role: "prop" }),
+        despawnEntity,
+        resolvePosition: (instanceId) => entities.get(instanceId)?.position,
+    }), ["spawn", "take"], signal.notify);
+    function spawnWorldItem(input) {
+        const record = worldItems.spawn(input);
+        events.emit("worldItem.dropped", {
+            instanceId: record.instanceId,
+            itemId: record.itemId,
+            rarity: record.rarity,
+            count: record.count,
+            position: [input.position[0], input.position[1], input.position[2]],
+            ...(record.source !== undefined ? { source: record.source } : {}),
+        });
+        return record;
+    }
+    function pickupWorldItem(instanceId, userId) {
+        const record = worldItems.take(instanceId);
+        if (record === null)
+            return { status: "rejected", reason: "not-found" };
+        loot.grantToPlayer(userId, [{ item: record.itemId, count: record.count }], "worldItem.pickup");
+        events.emit("worldItem.picked_up", {
+            instanceId,
+            userId,
+            itemId: record.itemId,
+            rarity: record.rarity,
+            count: record.count,
+        });
+        return { status: "ok", record };
+    }
     const death = createDeathSystem({
         resolveOnDeath: (instanceId) => catalogEntry(instanceId)?.onDeath,
         resolveIdentity(instanceId) {
@@ -266,7 +318,10 @@ export function createGameContext(options) {
         getStat: weapon.getStat,
         spatial: combatSpatial,
         onLethal(instanceId, lethalCtx) {
-            const catalogId = entities.get(instanceId)?.name;
+            const dyingEntity = entities.get(instanceId);
+            const catalogId = dyingEntity?.name;
+            const position = dyingEntity?.position;
+            const normalizedOnDeath = normalizeOnDeath(catalogEntry(instanceId)?.onDeath);
             const reason = deathReasonFromEffect({
                 ...lethalCtx,
                 userIdOf: (id) => (id === player.userId ? player.userId : undefined),
@@ -276,7 +331,23 @@ export function createGameContext(options) {
                 resolution.drops.length > 0 &&
                 reason.kind === "player_kill" &&
                 reason.killerUserId === player.userId) {
-                loot.grantToPlayer(player.userId, resolution.drops, catalogId);
+                if (normalizedOnDeath.dropMode === "world" && position !== undefined) {
+                    const resolved = resolveDeathDrops(resolution.drops, {
+                        mode: "world",
+                        origin: position,
+                        resolveRarity: (itemId) => content.itemById?.(itemId)?.rarity ?? DEFAULT_RARITY,
+                        resolveBaseType: (itemId) => content.itemById?.(itemId)?.baseType ?? itemId,
+                        scatter: normalizedOnDeath.scatter,
+                        ...(catalogId !== undefined ? { source: catalogId } : {}),
+                    });
+                    for (const spawn of resolved.worldSpawns)
+                        spawnWorldItem(spawn);
+                    if (resolved.grants.length > 0)
+                        loot.grantToPlayer(player.userId, resolved.grants, catalogId);
+                }
+                else {
+                    loot.grantToPlayer(player.userId, resolution.drops, catalogId);
+                }
             }
         },
     }), ["applyEffect"], signal.notify);
@@ -295,8 +366,76 @@ export function createGameContext(options) {
             event.instanceId = input.instanceId;
         if (input.amount !== undefined)
             event.amount = input.amount;
+        if (input.hitType !== undefined)
+            event.hitType = input.hitType;
+        if (input.element !== undefined)
+            event.element = input.element;
+        if (input.crit !== undefined)
+            event.crit = input.crit;
+        if (input.scale !== undefined)
+            event.scale = input.scale;
         events.emit("entity.floatText", event);
     }
+    let telegraphSeq = 0;
+    function fireTelegraph(input) {
+        const id = telegraphSeq++;
+        const telegraphEvent = {
+            id,
+            shape: input.shape,
+            position: [input.at[0], input.at[1], input.at[2]],
+            windupMs: input.windupMs,
+            kind: input.kind ?? "danger",
+        };
+        if (input.dir !== undefined)
+            telegraphEvent.dir = input.dir;
+        events.emit("combat.telegraph", telegraphEvent);
+        const bound = input.effect;
+        if (bound === undefined)
+            return () => { };
+        const config = { shape: input.shape, at: input.at, windupMs: input.windupMs };
+        if (input.dir !== undefined)
+            config.dir = input.dir;
+        return time.after(input.windupMs / 1000, () => {
+            const targets = entities.list().filter((entity) => pointInTelegraph(config, entity.position));
+            for (const target of targets) {
+                applyEffectAndFloat({
+                    from: input.from,
+                    to: target.id,
+                    effect: bound.effect,
+                    ...(bound.via === undefined ? {} : { via: bound.via }),
+                });
+            }
+        });
+    }
+    function applyHitReaction(input) {
+        const attacker = entities.get(input.from);
+        const target = entities.get(input.to);
+        if (target === null)
+            return null;
+        const attackerPos = attacker?.position ?? target.position;
+        const reaction = resolveHitReaction(input.config, {
+            attackerPos,
+            targetPos: target.position,
+            ...(input.power === undefined ? {} : { power: input.power }),
+        });
+        entities.setPose(input.to, {
+            position: [
+                target.position[0] + reaction.impulse[0],
+                target.position[1] + reaction.impulse[1],
+                target.position[2] + reaction.impulse[2],
+            ],
+            rotationY: target.rotationY,
+        });
+        const reactionEvent = {
+            instanceId: input.to,
+            position: [target.position[0], target.position[1], target.position[2]],
+            hitstopMs: reaction.hitstopMs,
+        };
+        if (reaction.shake !== null)
+            reactionEvent.shake = reaction.shake;
+        events.emit("combat.hitReaction", reactionEvent);
+        return reaction;
+    }
     function applyEffectAndFloat(input) {
         const positionsBefore = new Map();
         for (const entity of entities.list())
@@ -357,6 +496,8 @@ export function createGameContext(options) {
                 list: entities.list,
                 stats: entityStats,
                 floatText: emitFloatText,
+                telegraph: fireTelegraph,
+                hitReaction: applyHitReaction,
                 setTarget: targeting.setTarget,
                 getTarget: targeting.getTarget,
                 cycleTarget: targeting.cycleTarget,
@@ -371,6 +512,14 @@ export function createGameContext(options) {
                 hasLineOfSight: spatial.hasLineOfSight,
                 queryArc: spatial.queryArc,
                 moveToward: spatial.moveToward,
+                form: forms,
+            },
+            worldItem: {
+                spawn: spawnWorldItem,
+                get: worldItems.get,
+                list: worldItems.list,
+                nearestInRadius: worldItems.nearestInRadius,
+                pickup: pickupWorldItem,
             },
         },
         game: {
@@ -406,6 +555,7 @@ export function createGameContext(options) {
             unlocks,
             economy,
             leaderboard,
+            roster,
         },
         player: {
             userId: player.userId,
@@ -415,6 +565,8 @@ export function createGameContext(options) {
             loadout: loadouts,
             applyLoadout: loadouts.applyLoadout,
             movement: pose,
+            possession,
+            cosmetics,
         },
         item: {
             use: {
@@ -429,6 +581,7 @@ export function createGameContext(options) {
             },
             weapon,
         },
+        time,
         subscribe: signal.subscribe,
         version: signal.version,
     };

package/dist/runtime/hostPersistence.d.ts

@@ -1,13 +1,26 @@
 import type { LeaderboardScope } from "../game/leaderboard.js";
+import type { NormalizedScenarioReset } from "./persistenceScope.js";
 import type { SaveConfig } from "./save.js";
 import type { GameRuntimeSnapshot, RuntimeChunkRow, RuntimePlayerRow, RuntimeServerRow } from "./snapshot.js";
 export type GameServerStatus = "open" | "running" | "closed";
+export type SessionVisibility = "public" | "private";
+export type SessionAttributes = {
+    label?: string;
+    mode?: string;
+    visibility?: SessionVisibility;
+    joinCode?: string;
+    tags?: string[];
+};
 export type GameServerRecord = {
     serverId: string;
     gameId: string;
     status: GameServerStatus;
     mode?: string;
     modeConfig?: unknown;
+    label?: string;
+    visibility?: SessionVisibility;
+    joinCode?: string;
+    tags?: string[];
     memberUserIds: string[];
     slotsPerServer: number;
     save: SaveConfig;
@@ -58,11 +71,16 @@ export type ServerListing = {
     memberCount: number;
     slotsPerServer: number;
     mode?: string;
+    label?: string;
+    visibility?: SessionVisibility;
+    joinCode?: string;
+    tags?: string[];
     updatedAt: number;
 };
 export declare function toServerListing(record: GameServerRecord): ServerListing;
 export type HostPersistence = {
     savePlan?: (plan: ServerPersistPlan) => Promise<void>;
+    resetScenario?: (reset: NormalizedScenarioReset) => Promise<void>;
     loadServer: (serverId: string) => Promise<GameServerRecord | null>;
     saveServer: (record: GameServerRecord) => Promise<void>;
     listServers: (gameId: string) => Promise<GameServerRecord[]>;

package/dist/runtime/hostPersistence.js

@@ -42,6 +42,10 @@ export function toServerListing(record) {
         memberCount: record.memberUserIds.length,
         slotsPerServer: record.slotsPerServer,
         mode: record.mode,
+        label: record.label,
+        visibility: record.visibility,
+        joinCode: record.joinCode,
+        tags: record.tags,
         updatedAt: record.updatedAt,
     };
 }

package/dist/runtime/persistenceScope.d.ts

@@ -0,0 +1,32 @@
+import type { PlayerProfileRecord } from "./hostPersistence.js";
+import type { RuntimePlayerRow } from "./snapshot.js";
+export type PersistenceScope = "run" | "meta";
+export interface ScopeSchema {
+    run: readonly string[];
+}
+export interface ScopedState<T = Record<string, unknown>> {
+    meta: Partial<T>;
+    run: Partial<T>;
+}
+export declare function partitionScopes<T extends Record<string, unknown>>(state: T, schema: ScopeSchema): ScopedState<T>;
+export declare function resetRun<T extends Record<string, unknown>>(scoped: ScopedState<T>): ScopedState<T>;
+export declare function mergeScopes<T extends Record<string, unknown>>(scoped: ScopedState<T>): Partial<T>;
+export declare function clearRunFields(player: RuntimePlayerRow, runFields: readonly string[]): RuntimePlayerRow;
+export declare function applyRunReset(profile: PlayerProfileRecord, runFields: readonly string[], now: number): PlayerProfileRecord;
+export interface ScenarioReset {
+    gameId: string;
+    serverId?: string;
+    wipeChunks?: boolean;
+    wipeServerSession?: boolean;
+    resetPlayers?: PersistenceScope | "none";
+    runFields?: readonly string[];
+}
+export interface NormalizedScenarioReset {
+    gameId: string;
+    serverId: string | null;
+    wipeChunks: boolean;
+    wipeServerSession: boolean;
+    resetPlayers: "run" | "none";
+    runFields: readonly string[];
+}
+export declare function planScenarioReset(reset: ScenarioReset): NormalizedScenarioReset;

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

@@ -1,5 +1,18 @@
+export interface ModelDims {
+    footprint: {
+        w: number;
+        d: number;
+    };
+    center: {
+        x: number;
+        z: number;
+    };
+    minY: number;
+}
 export interface ModelAssetRef {
     url: string;
+    /** Measured at asset reindex: horizontal footprint, footprint center, and lowest Y in model space (pre-scale). Lets the shell auto-center and ground-snap corner-pivot kit models. */
+    dims?: ModelDims;
 }
 export interface AssetCatalog<TMeta extends ModelAssetRef = ModelAssetRef> {
     register(id: string, asset: TMeta): void;

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

@@ -16,11 +16,15 @@ export interface SceneEntity<TMeta = undefined> {
     rotationY: number;
     rotationX: number;
     rotationZ: number;
+    /** World units per second, derived from consecutive setPose calls that carry `dt`. Zero until the entity moves under a dt. */
+    velocity: EntityPosition;
     role: EntityRole;
     movement: EntityMovement;
     behaviors: readonly BehaviorDescriptor[];
     meta: TMeta;
 }
+/** 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 interface SpawnOptions<TMeta = undefined> {
     id?: string;
     position?: SpawnPositionInput;
@@ -37,11 +41,13 @@ export interface EntityPose {
     rotationY?: number;
     rotationX?: number;
     rotationZ?: number;
+    /** Seconds since the previous pose; when > 0 the store derives `velocity` from the position delta. Omit for teleports (velocity unchanged). */
+    dt?: 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>[];

package/dist/scene/entityStore.js

@@ -1,4 +1,8 @@
 import { createObservableKeyedStore } from "../store/observableKeyedStore.js";
+/** Ground speed (horizontal magnitude of velocity) in world units per second. Scale to km/h or mph in game code. */
+export function groundSpeed(entity) {
+    return Math.hypot(entity.velocity[0], entity.velocity[2]);
+}
 function toEntityPosition(position) {
     if (position === undefined)
         return [0, 0, 0];
@@ -31,6 +35,7 @@ export function createEntityStore() {
                 rotationY: options.rotationY ?? 0,
                 rotationX: options.rotationX ?? 0,
                 rotationZ: options.rotationZ ?? 0,
+                velocity: [0, 0, 0],
                 role: options.role ?? "prop",
                 movement: options.movement ?? {},
                 behaviors: options.behaviors ?? [],
@@ -54,9 +59,18 @@ export function createEntityStore() {
             const current = store.get(id);
             if (!current)
                 return false;
+            const position = toEntityPosition(pose.position);
+            const velocity = pose.dt !== undefined && pose.dt > 0
+                ? [
+                    (position[0] - current.position[0]) / pose.dt,
+                    (position[1] - current.position[1]) / pose.dt,
+                    (position[2] - current.position[2]) / pose.dt,
+                ]
+                : current.velocity;
             store.set(id, {
                 ...current,
-                position: toEntityPosition(pose.position),
+                position,
+                velocity,
                 rotationY: pose.rotationY ?? current.rotationY,
                 rotationX: pose.rotationX ?? current.rotationX,
                 rotationZ: pose.rotationZ ?? current.rotationZ,