@jgengine/core 0.1.0

package/dist/runtime/hostPersistence.js

@@ -0,0 +1,117 @@
+import { isSaveEnabled, parseSaveAutoMs, saveScopeIncludesChunks, saveScopeIncludesPlayer, } from "./save.js";
+import { createEmptyPlayerRow, splitProfilePlayer } from "./snapshot.js";
+export const LEADERBOARD_PENDING_KEY = "leaderboardPending";
+function isLeaderboardIncrement(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const candidate = value;
+    return (typeof candidate.userId === "string" &&
+        typeof candidate.stat === "string" &&
+        (candidate.scope === "global" || candidate.scope === "server" || candidate.scope === "profile") &&
+        typeof candidate.by === "number" &&
+        (candidate.serverId === undefined || typeof candidate.serverId === "string"));
+}
+export function drainPendingLeaderboardIncrements(session) {
+    const raw = session[LEADERBOARD_PENDING_KEY];
+    if (!Array.isArray(raw) || raw.length === 0) {
+        return { increments: [], session };
+    }
+    const rest = { ...session };
+    delete rest[LEADERBOARD_PENDING_KEY];
+    return { increments: raw.filter(isLeaderboardIncrement), session: rest };
+}
+export const FEED_RING_LIMIT = 20;
+export function trimFeedEntries(entries, limit = FEED_RING_LIMIT) {
+    if (entries.length <= limit)
+        return entries;
+    return entries.slice(entries.length - limit);
+}
+export function shouldAutoSave(save, dirtyAt, lastSavedAt, now) {
+    if (!isSaveEnabled(save))
+        return false;
+    if (dirtyAt === undefined)
+        return false;
+    const intervalMs = parseSaveAutoMs(save.auto);
+    const anchor = lastSavedAt ?? 0;
+    return now - anchor >= intervalMs;
+}
+export function toServerListing(record) {
+    return {
+        serverId: record.serverId,
+        status: record.status,
+        memberCount: record.memberUserIds.length,
+        slotsPerServer: record.slotsPerServer,
+        mode: record.mode,
+        updatedAt: record.updatedAt,
+    };
+}
+export function buildHydratePlayers(server, profiles) {
+    const players = {};
+    for (const userId of server.memberUserIds) {
+        const profile = profiles[userId] ?? null;
+        const sessionPlayer = server.sessionPlayers[userId];
+        if (profile) {
+            players[userId] = {
+                ...profile.playerState,
+                ...(sessionPlayer?.session ? { session: sessionPlayer.session } : {}),
+            };
+        }
+        else if (sessionPlayer) {
+            players[userId] = sessionPlayer;
+        }
+        else {
+            players[userId] = createEmptyPlayerRow(userId);
+        }
+    }
+    return players;
+}
+export function planServerPersist(server, snapshot, save, now) {
+    const drained = drainPendingLeaderboardIncrements(snapshot.server.session);
+    const serverState = drained.increments.length > 0 ? { ...snapshot.server, session: drained.session } : snapshot.server;
+    const leaderboard = drained.increments.map((entry) => entry.scope === "server" && entry.serverId === undefined
+        ? { ...entry, serverId: server.serverId }
+        : entry);
+    const sessionPlayers = {};
+    const profiles = [];
+    for (const userId of Object.keys(snapshot.players)) {
+        const player = snapshot.players[userId];
+        if (!player)
+            continue;
+        const { persistent, session } = splitProfilePlayer(player);
+        sessionPlayers[userId] = { ...persistent, session };
+        if (isSaveEnabled(save) &&
+            saveScopeIncludesPlayer(save.scope) &&
+            snapshot.dirty.players.includes(userId)) {
+            profiles.push({
+                userId,
+                gameId: server.gameId,
+                playerState: persistent,
+                revision: snapshot.revision,
+                updatedAt: now,
+            });
+        }
+    }
+    const chunks = [];
+    if (isSaveEnabled(save) && saveScopeIncludesChunks(save.scope)) {
+        for (const chunkKey of snapshot.dirty.chunks) {
+            const chunk = snapshot.chunks[chunkKey];
+            if (!chunk)
+                continue;
+            chunks.push({ serverId: server.serverId, chunkKey, snapshot: chunk, updatedAt: now });
+        }
+    }
+    return {
+        server: {
+            ...server,
+            serverState,
+            sessionPlayers,
+            revision: snapshot.revision,
+            dirtyAt: snapshot.dirty.server || snapshot.dirty.players.length > 0 ? now : server.dirtyAt,
+            updatedAt: now,
+            lastSavedAt: now,
+        },
+        profiles,
+        chunks,
+        leaderboard,
+    };
+}

package/dist/runtime/save.d.ts

@@ -0,0 +1,9 @@
+export type SaveScope = "player" | "chunks" | "player+chunks";
+export type SaveConfig = "none" | {
+    auto: string;
+    scope: SaveScope;
+};
+export declare function parseSaveAutoMs(auto: string): number;
+export declare function saveScopeIncludesPlayer(scope: SaveScope): boolean;
+export declare function saveScopeIncludesChunks(scope: SaveScope): boolean;
+export declare function isSaveEnabled(config: SaveConfig): config is Exclude<SaveConfig, "none">;

package/dist/runtime/save.js

@@ -0,0 +1,29 @@
+export function parseSaveAutoMs(auto) {
+    const match = /^(\d+(?:\.\d+)?)(ms|s|m|h)$/.exec(auto.trim());
+    if (!match) {
+        throw new Error(`Invalid save.auto interval: ${auto}`);
+    }
+    const amount = Number(match[1]);
+    const unit = match[2];
+    switch (unit) {
+        case "ms":
+            return amount;
+        case "s":
+            return amount * 1_000;
+        case "m":
+            return amount * 60_000;
+        case "h":
+            return amount * 3_600_000;
+        default:
+            throw new Error(`Invalid save.auto unit: ${unit}`);
+    }
+}
+export function saveScopeIncludesPlayer(scope) {
+    return scope === "player" || scope === "player+chunks";
+}
+export function saveScopeIncludesChunks(scope) {
+    return scope === "chunks" || scope === "player+chunks";
+}
+export function isSaveEnabled(config) {
+    return config !== "none";
+}

package/dist/runtime/snapshot.d.ts

@@ -0,0 +1,87 @@
+export declare const RUNTIME_SNAPSHOT_VERSION = 1;
+export type RuntimeEntityRow = {
+    instanceId: string;
+    catalogId: string;
+    position?: [number, number, number];
+    rotationY?: number;
+    parentSpace?: string;
+    group?: string;
+    stats?: Record<string, {
+        current: number;
+        max: number;
+        min?: number;
+    }>;
+    targetInstanceId?: string | null;
+    userId?: string;
+};
+export type RuntimeObjectRow = {
+    instanceId: string;
+    catalogId: string;
+    position: [number, number, number];
+    rotationY?: number;
+    parentSpace?: string;
+    flags?: Record<string, unknown>;
+};
+export type RuntimeInventorySlot = {
+    item: string;
+    count: number;
+    slot?: number;
+};
+export type RuntimePlayerRow = {
+    userId: string;
+    inventories: Record<string, RuntimeInventorySlot[]>;
+    economy: Record<string, number>;
+    unlocks: string[];
+    quests?: unknown;
+    social?: unknown;
+    leaderboard?: Record<string, number>;
+    session?: Record<string, unknown>;
+};
+export type RuntimeChunkRow = {
+    chunkKey: string;
+    objects: RuntimeObjectRow[];
+    entities: RuntimeEntityRow[];
+    flags?: Record<string, unknown>;
+};
+export type RuntimeServerRow = {
+    entities: RuntimeEntityRow[];
+    objects: RuntimeObjectRow[];
+    session: Record<string, unknown>;
+    feeds?: Record<string, unknown[]>;
+};
+export type RuntimeProfileRow = {
+    userId: string;
+    gameId: string;
+    player: RuntimePlayerRow;
+    updatedAt: number;
+};
+export type GameRuntimeSnapshot = {
+    version: number;
+    gameId: string;
+    serverId: string;
+    server: RuntimeServerRow;
+    players: Record<string, RuntimePlayerRow>;
+    chunks: Record<string, RuntimeChunkRow>;
+    revision: number;
+    dirty: {
+        server: boolean;
+        players: string[];
+        chunks: string[];
+    };
+};
+export declare function createEmptyServerRow(): RuntimeServerRow;
+export declare function createEmptyPlayerRow(userId: string): RuntimePlayerRow;
+export declare function createRuntimeSnapshot(args: {
+    gameId: string;
+    serverId: string;
+    server?: RuntimeServerRow;
+    players?: Record<string, RuntimePlayerRow>;
+    chunks?: Record<string, RuntimeChunkRow>;
+}): GameRuntimeSnapshot;
+export declare function markServerDirty(snapshot: GameRuntimeSnapshot): GameRuntimeSnapshot;
+export declare function markPlayerDirty(snapshot: GameRuntimeSnapshot, userId: string): GameRuntimeSnapshot;
+export declare function clearDirtyFlags(snapshot: GameRuntimeSnapshot): GameRuntimeSnapshot;
+export declare function splitProfilePlayer(player: RuntimePlayerRow): {
+    persistent: RuntimePlayerRow;
+    session: Record<string, unknown>;
+};

package/dist/runtime/snapshot.js

@@ -0,0 +1,75 @@
+export const RUNTIME_SNAPSHOT_VERSION = 1;
+export function createEmptyServerRow() {
+    return {
+        entities: [],
+        objects: [],
+        session: {},
+        feeds: {},
+    };
+}
+export function createEmptyPlayerRow(userId) {
+    return {
+        userId,
+        inventories: {},
+        economy: {},
+        unlocks: [],
+        session: {},
+    };
+}
+export function createRuntimeSnapshot(args) {
+    return {
+        version: RUNTIME_SNAPSHOT_VERSION,
+        gameId: args.gameId,
+        serverId: args.serverId,
+        server: args.server ?? createEmptyServerRow(),
+        players: args.players ?? {},
+        chunks: args.chunks ?? {},
+        revision: 0,
+        dirty: {
+            server: false,
+            players: [],
+            chunks: [],
+        },
+    };
+}
+export function markServerDirty(snapshot) {
+    return {
+        ...snapshot,
+        revision: snapshot.revision + 1,
+        dirty: { ...snapshot.dirty, server: true },
+    };
+}
+export function markPlayerDirty(snapshot, userId) {
+    if (snapshot.dirty.players.includes(userId)) {
+        return markServerDirty(snapshot);
+    }
+    return {
+        ...snapshot,
+        revision: snapshot.revision + 1,
+        dirty: {
+            ...snapshot.dirty,
+            server: true,
+            players: [...snapshot.dirty.players, userId],
+        },
+    };
+}
+export function clearDirtyFlags(snapshot) {
+    return {
+        ...snapshot,
+        dirty: {
+            server: false,
+            players: [],
+            chunks: [],
+        },
+    };
+}
+export function splitProfilePlayer(player) {
+    const { session = {}, ...persistentFields } = player;
+    return {
+        persistent: {
+            ...persistentFields,
+            session: {},
+        },
+        session,
+    };
+}

package/dist/runtime/transport.d.ts

@@ -0,0 +1,60 @@
+import type { PresenceTransport } from "../multiplayer/presenceContract.js";
+export type JoinServerResult = {
+    serverId: string;
+    isNew: boolean;
+};
+export type RunCommandArgs = {
+    serverId: string;
+    command: string;
+    input: unknown;
+};
+export type TransportRunCommandResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+export type GameRuntimeServerView = {
+    serverId: string;
+    gameId: string;
+    revision: number;
+    memberUserIds: string[];
+    serverState: unknown;
+    updatedAt: number;
+};
+export type GameRuntimePlayerView = {
+    userId: string;
+    gameId: string;
+    playerState: unknown;
+    updatedAt: number;
+};
+export type GameRuntimeFeedView = {
+    action: string;
+    entries: unknown[];
+};
+export type GameRuntimeTransport = {
+    joinServer: (args: {
+        gameId: string;
+        serverId?: string;
+    }) => Promise<JoinServerResult>;
+    leaveServer: (args: {
+        serverId: string;
+    }) => Promise<void>;
+    runCommand: (args: RunCommandArgs) => Promise<TransportRunCommandResult>;
+};
+export type FeedUnsubscribe = () => void;
+export type GameRuntimeFeeds = {
+    subscribeServer: (serverId: string, onChange: (view: GameRuntimeServerView | null) => void) => FeedUnsubscribe;
+    subscribePlayer: (args: {
+        serverId: string;
+    }, onChange: (view: GameRuntimePlayerView | null) => void) => FeedUnsubscribe;
+    subscribeFeed: (args: {
+        serverId: string;
+        action: string;
+    }, onChange: (view: GameRuntimeFeedView) => void) => FeedUnsubscribe;
+};
+export type GameBackend<TPresenceRow = unknown, TPresenceLocation = unknown, TGameId extends string = string> = {
+    transport: GameRuntimeTransport;
+    feeds?: GameRuntimeFeeds;
+    presence?: PresenceTransport<TPresenceRow, TPresenceLocation, TGameId>;
+};

package/dist/runtime/transport.js

@@ -0,0 +1 @@
+export {};

package/dist/scene/assetCatalog.d.ts

@@ -0,0 +1,10 @@
+export interface ModelAssetRef {
+    url: string;
+}
+export interface AssetCatalog<TMeta extends ModelAssetRef = ModelAssetRef> {
+    register(id: string, asset: TMeta): void;
+    resolve(id: string): TMeta | null;
+    has(id: string): boolean;
+    ids(): readonly string[];
+}
+export declare function createAssetCatalog<TMeta extends ModelAssetRef = ModelAssetRef>(): AssetCatalog<TMeta>;

package/dist/scene/assetCatalog.js

@@ -0,0 +1,17 @@
+export function createAssetCatalog() {
+    const assets = new Map();
+    return {
+        register(id, asset) {
+            assets.set(id, asset);
+        },
+        resolve(id) {
+            return assets.get(id) ?? null;
+        },
+        has(id) {
+            return assets.has(id);
+        },
+        ids() {
+            return Array.from(assets.keys());
+        },
+    };
+}

package/dist/scene/assetPreload.d.ts

@@ -0,0 +1,7 @@
+export type SceneAssetFetcher = (url: string) => void;
+export declare function createSceneAssetPreloader(fetcher: SceneAssetFetcher): {
+    preloadUrl(url: string): void;
+    preloadUrls(urls: readonly string[]): void;
+    hasPreloaded(url: string): boolean;
+    reset(): void;
+};

package/dist/scene/assetPreload.js

@@ -0,0 +1,22 @@
+export function createSceneAssetPreloader(fetcher) {
+    const preloadedUrls = new Set();
+    return {
+        preloadUrl(url) {
+            if (preloadedUrls.has(url))
+                return;
+            preloadedUrls.add(url);
+            fetcher(url);
+        },
+        preloadUrls(urls) {
+            for (const url of urls) {
+                this.preloadUrl(url);
+            }
+        },
+        hasPreloaded(url) {
+            return preloadedUrls.has(url);
+        },
+        reset() {
+            preloadedUrls.clear();
+        },
+    };
+}

package/dist/scene/behaviors.d.ts

@@ -0,0 +1,19 @@
+import { type ProximityPrompt } from "../interaction/proximityPrompt.js";
+export interface WanderBehavior {
+    kind: "wander";
+    radius: number;
+}
+export interface PromptableBehavior {
+    kind: "promptable";
+    prompt: ProximityPrompt;
+}
+export interface PlayerBehavior {
+    kind: "player";
+}
+export type BehaviorDescriptor = WanderBehavior | PromptableBehavior | PlayerBehavior;
+export declare function wander({ radius }: {
+    radius: number;
+}): WanderBehavior;
+export declare function promptable(prompt: ProximityPrompt): PromptableBehavior;
+export declare function talkable(dialogueId: string): PromptableBehavior;
+export declare function player(): PlayerBehavior;

package/dist/scene/behaviors.js

@@ -0,0 +1,18 @@
+import { command, keybind, proximityPrompt, } from "../interaction/proximityPrompt.js";
+export function wander({ radius }) {
+    return { kind: "wander", radius };
+}
+export function promptable(prompt) {
+    return { kind: "promptable", prompt };
+}
+const TALK_RADIUS = 2;
+export function talkable(dialogueId) {
+    return promptable(proximityPrompt({
+        radius: TALK_RADIUS,
+        display: keybind("interact"),
+        invoke: command("dialogue.open", { id: dialogueId }),
+    }));
+}
+export function player() {
+    return { kind: "player" };
+}

package/dist/scene/entityStats.d.ts

@@ -0,0 +1,38 @@
+export interface PoolStat {
+    current: number;
+    max: number;
+    min: number;
+}
+export interface PoolStatPatch {
+    current?: number;
+    max?: number;
+    min?: number;
+}
+export type PoolStatMap = Record<string, PoolStat>;
+export type PoolStatCatalog = Record<string, {
+    max: number;
+    min?: number;
+    current?: number;
+}>;
+export type PoolDeltaResult = {
+    status: "ok";
+    map: PoolStatMap;
+    stat: PoolStat;
+    hitMin: boolean;
+    hitMax: boolean;
+} | {
+    status: "rejected";
+    reason: string;
+};
+export declare function getPoolStat(map: PoolStatMap, statId: string): PoolStat | null;
+export declare function setPoolStat(map: PoolStatMap, statId: string, patch: PoolStatPatch): PoolStatMap;
+export declare function applyPoolDelta(map: PoolStatMap, statId: string, amount: number): PoolDeltaResult;
+export declare function seedPoolStats(catalogStats: PoolStatCatalog): PoolStatMap;
+export interface EntityStatsApi {
+    get(instanceId: string, statId: string): PoolStat | null;
+    set(instanceId: string, statId: string, patch: PoolStatPatch): boolean;
+    delta(instanceId: string, statId: string, amount: number): null | {
+        reason: string;
+    };
+}
+export declare function createEntityStatsApi(resolve: (instanceId: string) => PoolStatMap | undefined): EntityStatsApi;

package/dist/scene/entityStats.js

@@ -0,0 +1,65 @@
+function clamp(value, min, max) {
+    return Math.min(max, Math.max(min, value));
+}
+export function getPoolStat(map, statId) {
+    return map[statId] ?? null;
+}
+export function setPoolStat(map, statId, patch) {
+    const existing = map[statId];
+    const max = patch.max ?? existing?.max ?? 0;
+    const min = patch.min ?? existing?.min ?? 0;
+    const current = clamp(patch.current ?? existing?.current ?? max, min, max);
+    return { ...map, [statId]: { current, max, min } };
+}
+export function applyPoolDelta(map, statId, amount) {
+    const existing = map[statId];
+    if (existing === undefined) {
+        return { status: "rejected", reason: `unknown stat "${statId}"` };
+    }
+    const current = clamp(existing.current + amount, existing.min, existing.max);
+    const stat = { ...existing, current };
+    return {
+        status: "ok",
+        map: { ...map, [statId]: stat },
+        stat,
+        hitMin: current === existing.min,
+        hitMax: current === existing.max,
+    };
+}
+export function seedPoolStats(catalogStats) {
+    const map = {};
+    for (const [statId, declaration] of Object.entries(catalogStats)) {
+        const min = declaration.min ?? 0;
+        const current = clamp(declaration.current ?? declaration.max, min, declaration.max);
+        map[statId] = { current, max: declaration.max, min };
+    }
+    return map;
+}
+export function createEntityStatsApi(resolve) {
+    return {
+        get(instanceId, statId) {
+            const map = resolve(instanceId);
+            if (map === undefined)
+                return null;
+            return getPoolStat(map, statId);
+        },
+        set(instanceId, statId, patch) {
+            const map = resolve(instanceId);
+            if (map === undefined)
+                return false;
+            const next = setPoolStat(map, statId, patch);
+            map[statId] = next[statId];
+            return true;
+        },
+        delta(instanceId, statId, amount) {
+            const map = resolve(instanceId);
+            if (map === undefined)
+                return { reason: `unknown instance "${instanceId}"` };
+            const result = applyPoolDelta(map, statId, amount);
+            if (result.status === "rejected")
+                return { reason: result.reason };
+            map[statId] = result.stat;
+            return null;
+        },
+    };
+}

package/dist/scene/entityStore.d.ts

@@ -0,0 +1,52 @@
+import type { BehaviorDescriptor } from "./behaviors.js";
+export type EntityRole = "player" | "npc" | "prop";
+export interface EntityMovement {
+    walkSpeed?: number;
+}
+export type EntityPosition = readonly [number, number, number];
+export type SpawnPositionInput = EntityPosition | {
+    x: number;
+    y: number;
+    z: number;
+};
+export interface SceneEntity<TMeta = undefined> {
+    id: string;
+    name: string;
+    position: EntityPosition;
+    rotationY: number;
+    rotationX: number;
+    rotationZ: number;
+    role: EntityRole;
+    movement: EntityMovement;
+    behaviors: readonly BehaviorDescriptor[];
+    meta: TMeta;
+}
+export interface SpawnOptions<TMeta = undefined> {
+    id?: string;
+    position?: SpawnPositionInput;
+    rotationY?: number;
+    rotationX?: number;
+    rotationZ?: number;
+    role?: EntityRole;
+    movement?: EntityMovement;
+    behaviors?: readonly BehaviorDescriptor[];
+    meta?: TMeta;
+}
+export interface EntityPose {
+    position: SpawnPositionInput;
+    rotationY?: number;
+    rotationX?: number;
+    rotationZ?: 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;
+    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>[];
+}
+export declare function createEntityStore<TMeta = undefined>(): EntityStore<TMeta>;