@jgengine/core 0.7.0 → 0.8.0

package/dist/runtime/hostPersistence.d.ts

@@ -62,6 +62,26 @@ export declare function drainPendingLeaderboardIncrements(session: Record<string
     increments: LeaderboardIncrement[];
     session: Record<string, unknown>;
 };
+export declare const LEADERBOARD_TOP_LIMIT = 100;
+export type LeaderboardRow = {
+    gameId: string;
+    stat: string;
+    scope: LeaderboardScope;
+    serverId?: string;
+    userId: string;
+    value: number;
+    updatedAt: number;
+};
+export declare function leaderboardRowKey(row: Omit<LeaderboardRow, "value" | "updatedAt">): string;
+export declare function applyLeaderboardRows(rows: Map<string, LeaderboardRow>, gameId: string, entries: LeaderboardIncrement[], now: number): void;
+export declare function topLeaderboardRows(rows: Iterable<LeaderboardRow>, args: {
+    gameId: string;
+    stat: string;
+    scope: LeaderboardScope;
+    serverId?: string;
+    limit?: number;
+}): LeaderboardEntry[];
+export declare function profileLeaderboardStats(rows: Iterable<LeaderboardRow>, gameId: string, userId: string): Record<string, number>;
 export declare const FEED_RING_LIMIT = 20;
 export declare function trimFeedEntries<T>(entries: T[], limit?: number): T[];
 export declare function shouldAutoSave(save: SaveConfig, dirtyAt: number | undefined, lastSavedAt: number | undefined, now: number): boolean;
@@ -78,6 +98,7 @@ export type ServerListing = {
     updatedAt: number;
 };
 export declare function toServerListing(record: GameServerRecord): ServerListing;
+export declare function toOpenServerListings(listings: Iterable<ServerListing>, limit?: number): ServerListing[];
 export type HostPersistence = {
     savePlan?: (plan: ServerPersistPlan) => Promise<void>;
     resetScenario?: (reset: NormalizedScenarioReset) => Promise<void>;

package/dist/runtime/hostPersistence.js

@@ -20,6 +20,50 @@ export function drainPendingLeaderboardIncrements(session) {
     delete rest[LEADERBOARD_PENDING_KEY];
     return { increments: raw.filter(isLeaderboardIncrement), session: rest };
 }
+export const LEADERBOARD_TOP_LIMIT = 100;
+export function leaderboardRowKey(row) {
+    return [row.gameId, row.scope, row.stat, row.serverId ?? "", row.userId].join("|");
+}
+export function applyLeaderboardRows(rows, gameId, entries, now) {
+    for (const entry of entries) {
+        const key = leaderboardRowKey({ ...entry, gameId });
+        const existing = rows.get(key);
+        if (existing) {
+            rows.set(key, { ...existing, value: existing.value + entry.by, updatedAt: now });
+        }
+        else {
+            rows.set(key, {
+                gameId,
+                stat: entry.stat,
+                scope: entry.scope,
+                serverId: entry.serverId,
+                userId: entry.userId,
+                value: entry.by,
+                updatedAt: now,
+            });
+        }
+    }
+}
+export function topLeaderboardRows(rows, args) {
+    const limit = Math.min(Math.max(args.limit ?? LEADERBOARD_TOP_LIMIT, 1), LEADERBOARD_TOP_LIMIT);
+    return [...rows]
+        .filter((row) => row.gameId === args.gameId &&
+        row.stat === args.stat &&
+        row.scope === args.scope &&
+        (args.serverId === undefined || row.serverId === args.serverId))
+        .sort((a, b) => b.value - a.value)
+        .slice(0, limit)
+        .map((row) => ({ userId: row.userId, value: row.value }));
+}
+export function profileLeaderboardStats(rows, gameId, userId) {
+    const profile = {};
+    for (const row of rows) {
+        if (row.gameId === gameId && row.userId === userId && row.scope === "profile") {
+            profile[row.stat] = row.value;
+        }
+    }
+    return profile;
+}
 export const FEED_RING_LIMIT = 20;
 export function trimFeedEntries(entries, limit = FEED_RING_LIMIT) {
     if (entries.length <= limit)
@@ -49,6 +93,12 @@ export function toServerListing(record) {
         updatedAt: record.updatedAt,
     };
 }
+export function toOpenServerListings(listings, limit = 20) {
+    return [...listings]
+        .filter((listing) => listing.status === "running")
+        .sort((a, b) => b.updatedAt - a.updatedAt)
+        .slice(0, limit);
+}
 export function buildHydratePlayers(server, profiles) {
     const players = {};
     for (const userId of server.memberUserIds) {

package/dist/runtime/inputSnapshot.d.ts

@@ -0,0 +1,7 @@
+export interface InputSnapshot {
+    /** Replaces the held-action set for this frame. Called by the shell before `onTick` each frame; does not bump `ctx.version()` or notify `ctx.subscribe` listeners — per-frame publishes would storm subscribers. */
+    publish(held: readonly string[]): void;
+    isDown(action: string): boolean;
+    held(): readonly string[];
+}
+export declare function createInputSnapshot(): InputSnapshot;

package/dist/runtime/inputSnapshot.js

@@ -0,0 +1,12 @@
+export function createInputSnapshot() {
+    let heldSet = new Set();
+    let heldList = [];
+    return {
+        publish(held) {
+            heldList = held;
+            heldSet = new Set(held);
+        },
+        isDown: (action) => heldSet.has(action),
+        held: () => heldList,
+    };
+}

package/dist/runtime/motionIntents.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Seam for game code to reach the vertical motion the shell's FrameDriver
+ * otherwise owns privately (#162.4). Game code calls `impulse`,
+ * `setVerticalVelocity`, and/or `setY` from `onTick` or commands; the shell
+ * calls `takePending()` once per frame, before integrating gravity, to drain
+ * what accumulated. `setY` wins over physics for that frame; impulses add to
+ * the vertical velocity the driver is about to integrate; a later
+ * `setVerticalVelocity` replaces that velocity outright.
+ *
+ * Intentionally not `ctx.version()`/`ctx.subscribe` wired: these fire at
+ * most once per frame and would otherwise storm subscribers with per-frame
+ * churn (same rationale as `InputSnapshot.publish`).
+ */
+export interface MotionIntents {
+    impulse(velocityY: number): void;
+    setVerticalVelocity(velocityY: number): void;
+    setY(y: number): void;
+    takePending(): MotionIntentBatch | null;
+}
+export interface MotionIntentBatch {
+    impulses: readonly number[];
+    verticalVelocity: number | null;
+    y: number | null;
+}
+export declare function createMotionIntents(): MotionIntents;

package/dist/runtime/motionIntents.js

@@ -0,0 +1,25 @@
+export function createMotionIntents() {
+    let impulses = [];
+    let verticalVelocity = null;
+    let y = null;
+    return {
+        impulse(velocityY) {
+            impulses.push(velocityY);
+        },
+        setVerticalVelocity(velocityY) {
+            verticalVelocity = velocityY;
+        },
+        setY(nextY) {
+            y = nextY;
+        },
+        takePending() {
+            if (impulses.length === 0 && verticalVelocity === null && y === null)
+                return null;
+            const batch = { impulses, verticalVelocity, y };
+            impulses = [];
+            verticalVelocity = null;
+            y = null;
+            return batch;
+        },
+    };
+}

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/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,6 +46,10 @@ 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;
@@ -54,5 +60,7 @@ export interface EntityStore<TMeta = undefined> {
     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/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 } });
+}

package/dist/scene/objectQuery.d.ts

@@ -0,0 +1,18 @@
+import type { EntityPosition } from "./entityStore.js";
+import type { SceneObject } from "./objectStore.js";
+export interface ObjectRaycastInput {
+    origin: EntityPosition;
+    direction: EntityPosition;
+    maxDistance: number;
+    halfExtents?: EntityPosition;
+    filter?: (object: SceneObject) => boolean;
+}
+export interface ObjectRaycastHit {
+    instanceId: string;
+    catalogId: string;
+    distance: number;
+    point: EntityPosition;
+    normal: EntityPosition;
+}
+export declare function raycastObjects(objects: readonly SceneObject[], input: ObjectRaycastInput): ObjectRaycastHit | null;
+export declare function raycastObjectsAll(objects: readonly SceneObject[], input: ObjectRaycastInput): ObjectRaycastHit[];

package/dist/scene/objectQuery.js

@@ -0,0 +1,108 @@
+const DEFAULT_HALF_EXTENTS = [0.5, 0.5, 0.5];
+function normalize(direction) {
+    const length = Math.hypot(direction[0], direction[1], direction[2]);
+    if (length === 0)
+        return [0, 0, 0];
+    return [direction[0] / length, direction[1] / length, direction[2] / length];
+}
+function intersectAabb(origin, direction, min, max, maxDistance) {
+    let tMin = 0;
+    let tMax = maxDistance;
+    let normalAxis = -1;
+    let normalSign = 0;
+    for (let axis = 0; axis < 3; axis += 1) {
+        const originAxis = origin[axis];
+        const dirAxis = direction[axis];
+        const minAxis = min[axis];
+        const maxAxis = max[axis];
+        if (Math.abs(dirAxis) < 1e-12) {
+            if (originAxis < minAxis || originAxis > maxAxis)
+                return null;
+            continue;
+        }
+        const invD = 1 / dirAxis;
+        const t1 = (minAxis - originAxis) * invD;
+        const t2 = (maxAxis - originAxis) * invD;
+        const minIsNear = t1 <= t2;
+        const tNearAxis = minIsNear ? t1 : t2;
+        const tFarAxis = minIsNear ? t2 : t1;
+        const nearFaceSign = minIsNear ? -1 : 1;
+        if (tNearAxis > tMin) {
+            tMin = tNearAxis;
+            normalAxis = axis;
+            normalSign = nearFaceSign;
+        }
+        tMax = Math.min(tMax, tFarAxis);
+        if (tMin > tMax)
+            return null;
+    }
+    if (tMin > maxDistance || tMin < 0)
+        return null;
+    const normal = normalAxis === 0
+        ? [normalSign, 0, 0]
+        : normalAxis === 1
+            ? [0, normalSign, 0]
+            : normalAxis === 2
+                ? [0, 0, normalSign]
+                : [0, 1, 0];
+    return { distance: tMin, normal };
+}
+function hitFor(object, origin, direction, halfExtents, maxDistance) {
+    const min = [
+        object.position[0] - halfExtents[0],
+        object.position[1] - halfExtents[1],
+        object.position[2] - halfExtents[2],
+    ];
+    const max = [
+        object.position[0] + halfExtents[0],
+        object.position[1] + halfExtents[1],
+        object.position[2] + halfExtents[2],
+    ];
+    const hit = intersectAabb(origin, direction, min, max, maxDistance);
+    if (hit === null)
+        return null;
+    return {
+        instanceId: object.instanceId,
+        catalogId: object.catalogId,
+        distance: hit.distance,
+        point: [
+            origin[0] + direction[0] * hit.distance,
+            origin[1] + direction[1] * hit.distance,
+            origin[2] + direction[2] * hit.distance,
+        ],
+        normal: hit.normal,
+    };
+}
+export function raycastObjects(objects, input) {
+    const direction = normalize(input.direction);
+    if (direction[0] === 0 && direction[1] === 0 && direction[2] === 0)
+        return null;
+    const halfExtents = input.halfExtents ?? DEFAULT_HALF_EXTENTS;
+    let nearest = null;
+    for (const object of objects) {
+        if (input.filter !== undefined && !input.filter(object))
+            continue;
+        const hit = hitFor(object, input.origin, direction, halfExtents, input.maxDistance);
+        if (hit === null)
+            continue;
+        if (nearest === null || hit.distance < nearest.distance)
+            nearest = hit;
+    }
+    return nearest;
+}
+export function raycastObjectsAll(objects, input) {
+    const direction = normalize(input.direction);
+    if (direction[0] === 0 && direction[1] === 0 && direction[2] === 0)
+        return [];
+    const halfExtents = input.halfExtents ?? DEFAULT_HALF_EXTENTS;
+    const hits = [];
+    for (const object of objects) {
+        if (input.filter !== undefined && !input.filter(object))
+            continue;
+        const hit = hitFor(object, input.origin, direction, halfExtents, input.maxDistance);
+        if (hit !== null)
+            hits.push(hit);
+    }
+    hits.sort((a, b) => a.distance - b.distance);
+    return hits;
+}

package/dist/scene/objectStore.d.ts

@@ -1,15 +1,22 @@
 import type { EntityPosition } from "./entityStore.js";
+export interface ObjectVisual {
+    scale?: number | readonly [number, number, number];
+    color?: string;
+    opacity?: number;
+}
 export interface SceneObject {
     instanceId: string;
     catalogId: string;
     position: EntityPosition;
     rotationY: number;
     parentSpace?: string;
+    visual?: ObjectVisual;
 }
 export interface PlaceOptions {
     instanceId?: string;
     parentSpace?: string;
     rotation?: number;
+    visual?: ObjectVisual;
 }
 export interface ObjectListFilter {
     parentSpace?: string;
@@ -19,10 +26,14 @@ export interface ObjectStore {
     remove(instanceId: string): boolean;
     move(instanceId: string, x: number, y: number, z: number): boolean;
     rotate(instanceId: string, rotationY: number): boolean;
+    setVisual(instanceId: string, visual: ObjectVisual | undefined): boolean;
     get(instanceId: string): SceneObject | null;
     list(filter?: ObjectListFilter): readonly SceneObject[];
+    at(x: number, y: number, z: number, tolerance?: number): SceneObject[];
+    inBox(min: EntityPosition, max: EntityPosition): readonly SceneObject[];
     clear(): void;
     subscribe(listener: () => void): () => void;
     snapshot(): readonly SceneObject[];
 }
 export declare function createObjectStore(): ObjectStore;
+export declare function objectVisualScale(visual: ObjectVisual | undefined): readonly [number, number, number];