@jgengine/core 0.1.0

package/dist/movement/poseState.d.ts

@@ -0,0 +1,23 @@
+export type MovementPose = "standing" | "crouch" | "prone" | "running";
+export type AimMode = "hip" | "ads";
+export interface PoseHitbox {
+    height: number;
+    eyeHeight: number;
+    speedMultiplier: number;
+}
+export declare const POSE_HITBOX: Record<MovementPose, PoseHitbox>;
+export interface PoseAllowedStates {
+    poses?: readonly MovementPose[];
+    aim?: readonly AimMode[];
+}
+export interface PoseRejection {
+    reason: string;
+}
+export interface PoseState {
+    getPose(instanceId: string): MovementPose;
+    setPose(instanceId: string, pose: MovementPose): PoseRejection | null;
+    getAim(instanceId: string): AimMode;
+    setAim(instanceId: string, mode: AimMode): PoseRejection | null;
+    clear(instanceId: string): void;
+}
+export declare function createPoseState(resolveAllowed: (instanceId: string) => PoseAllowedStates | null | undefined): PoseState;

package/dist/movement/poseState.js

@@ -0,0 +1,61 @@
+import { MOVEMENT_TUNING } from "./movementModel.js";
+const STANDING_HEIGHT = 1.8;
+const CROUCH_HEIGHT = STANDING_HEIGHT * (MOVEMENT_TUNING.crouchEyeHeight / MOVEMENT_TUNING.standEyeHeight);
+export const POSE_HITBOX = {
+    standing: {
+        height: STANDING_HEIGHT,
+        eyeHeight: MOVEMENT_TUNING.standEyeHeight,
+        speedMultiplier: 1,
+    },
+    crouch: {
+        height: CROUCH_HEIGHT,
+        eyeHeight: MOVEMENT_TUNING.crouchEyeHeight,
+        speedMultiplier: MOVEMENT_TUNING.crouchSpeedMultiplier,
+    },
+    prone: {
+        height: CROUCH_HEIGHT * 0.5,
+        eyeHeight: MOVEMENT_TUNING.crouchEyeHeight * 0.4,
+        speedMultiplier: MOVEMENT_TUNING.crouchSpeedMultiplier * 0.5,
+    },
+    running: {
+        height: STANDING_HEIGHT,
+        eyeHeight: MOVEMENT_TUNING.standEyeHeight,
+        speedMultiplier: MOVEMENT_TUNING.runSpeedMultiplier,
+    },
+};
+export function createPoseState(resolveAllowed) {
+    const poses = new Map();
+    const aims = new Map();
+    function allowedPoses(instanceId) {
+        return resolveAllowed(instanceId)?.poses ?? ["standing"];
+    }
+    function allowedAims(instanceId) {
+        return resolveAllowed(instanceId)?.aim ?? ["hip"];
+    }
+    return {
+        getPose(instanceId) {
+            return poses.get(instanceId) ?? "standing";
+        },
+        setPose(instanceId, pose) {
+            if (!allowedPoses(instanceId).includes(pose)) {
+                return { reason: `Entity "${instanceId}" does not allow pose "${pose}".` };
+            }
+            poses.set(instanceId, pose);
+            return null;
+        },
+        getAim(instanceId) {
+            return aims.get(instanceId) ?? "hip";
+        },
+        setAim(instanceId, mode) {
+            if (!allowedAims(instanceId).includes(mode)) {
+                return { reason: `Entity "${instanceId}" does not allow aim mode "${mode}".` };
+            }
+            aims.set(instanceId, mode);
+            return null;
+        },
+        clear(instanceId) {
+            poses.delete(instanceId);
+            aims.delete(instanceId);
+        },
+    };
+}

package/dist/multiplayer/poseSyncGate.d.ts

@@ -0,0 +1,18 @@
+export interface PlayerPose {
+    x: number;
+    y: number;
+    z: number;
+    rotationY: number;
+    rotationPitch: number;
+}
+export interface PoseSyncTuning {
+    minIntervalMs: number;
+    heartbeatMs: number;
+    positionEpsilon: number;
+    verticalEpsilon: number;
+    rotationEpsilon: number;
+}
+export interface PoseSyncGate {
+    evaluate(pose: PlayerPose, nowMs: number): boolean;
+}
+export declare function createPoseSyncGate(tuning: PoseSyncTuning): PoseSyncGate;

package/dist/multiplayer/poseSyncGate.js

@@ -0,0 +1,30 @@
+function poseChanged(a, b, tuning) {
+    return (Math.abs(a.x - b.x) > tuning.positionEpsilon
+        || Math.abs(a.y - b.y) > tuning.verticalEpsilon
+        || Math.abs(a.z - b.z) > tuning.positionEpsilon
+        || Math.abs(a.rotationY - b.rotationY) > tuning.rotationEpsilon
+        || Math.abs(a.rotationPitch - b.rotationPitch) > tuning.rotationEpsilon);
+}
+export function createPoseSyncGate(tuning) {
+    let lastSentPose = null;
+    let lastSentAt = 0;
+    return {
+        evaluate(pose, nowMs) {
+            if (lastSentPose === null) {
+                lastSentPose = pose;
+                lastSentAt = nowMs;
+                return true;
+            }
+            const changed = poseChanged(lastSentPose, pose, tuning);
+            const intervalElapsed = nowMs - lastSentAt >= tuning.minIntervalMs;
+            const heartbeatDue = nowMs - lastSentAt >= tuning.heartbeatMs;
+            if (!changed && !heartbeatDue)
+                return false;
+            if (!intervalElapsed && !heartbeatDue)
+                return false;
+            lastSentPose = pose;
+            lastSentAt = nowMs;
+            return true;
+        },
+    };
+}

package/dist/multiplayer/presenceContract.d.ts

@@ -0,0 +1,60 @@
+export interface PresencePosition {
+    x: number;
+    y: number;
+    z: number;
+}
+export interface PresencePose {
+    position: {
+        x: number;
+        y?: number;
+        z: number;
+    };
+    rotationY?: number;
+    rotationPitch?: number;
+    externalId?: string;
+}
+export interface PresenceSession<TGameId extends string = string> {
+    homeGameId: TGameId;
+    externalId: string;
+}
+export interface EnsurePresenceArgs<TGameId extends string = string> {
+    gameId: TGameId;
+    externalId: string;
+}
+export interface EnsurePresenceResult {
+    presenceId: string;
+    position: PresencePosition;
+    rotationY: number;
+}
+export interface LeavePresenceArgs<TGameId extends string = string> {
+    gameId: TGameId;
+    externalId: string;
+}
+export interface PresenceFeeds<TRow, TLocation> {
+    myPresenceLocation: TLocation | null | undefined;
+    onlinePresences: readonly TRow[] | undefined;
+    dormantPresences: readonly TRow[] | undefined;
+}
+export interface PresenceActions<TGameId extends string = string> {
+    ensurePresence(args: EnsurePresenceArgs<TGameId>): Promise<EnsurePresenceResult | null>;
+    leavePresence(args: LeavePresenceArgs<TGameId>): Promise<{
+        left: boolean;
+    }>;
+    syncPose(pose: PresencePose): void;
+}
+/**
+ * Backend seam for multiplayer presence. Feeds are reactive data and change
+ * identity whenever any player's pose updates; actions MUST be identity-stable
+ * for the lifetime of a mounted session so join/leave lifecycle effects can
+ * depend on them without re-running per pose tick. The use* members are called
+ * as React hooks by consumers, so a mounted transport must never change
+ * identity — remount the subtree to switch backends.
+ */
+export interface PresenceTransport<TRow, TLocation, TGameId extends string = string> {
+    useFeeds(session: PresenceSession<TGameId> | "skip"): PresenceFeeds<TRow, TLocation>;
+    useActions(): PresenceActions<TGameId>;
+}
+export declare function createLocalPresenceTransport<TRow, TLocation, TGameId extends string = string>(): {
+    transport: PresenceTransport<TRow, TLocation, TGameId>;
+    actions: PresenceActions<TGameId>;
+};

package/dist/multiplayer/presenceContract.js

@@ -0,0 +1,19 @@
+export function createLocalPresenceTransport() {
+    const feeds = {
+        myPresenceLocation: null,
+        onlinePresences: [],
+        dormantPresences: [],
+    };
+    const actions = {
+        ensurePresence: async () => null,
+        leavePresence: async () => ({ left: true }),
+        syncPose: () => undefined,
+    };
+    return {
+        transport: {
+            useFeeds: () => feeds,
+            useActions: () => actions,
+        },
+        actions,
+    };
+}

package/dist/multiplayer/presenceModel.d.ts

@@ -0,0 +1,60 @@
+export interface PresencePoseState {
+    position: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    rotationY: number;
+    rotationPitch?: number;
+    lastSeenAtMs?: number;
+}
+export interface IncomingPose {
+    position: {
+        x: number;
+        z: number;
+        y?: number;
+    };
+    rotationY?: number;
+    rotationPitch?: number;
+}
+export interface PoseSyncRules {
+    /** Speed cap (units/sec) for client-authoritative movement. */
+    maxSpeed: number;
+    /** Vertical offset clamp (e.g. peak jump height). */
+    maxVerticalOffset: number;
+    /** Elapsed-time clamp so stale or bursty clients cannot teleport. */
+    minElapsedSec: number;
+    maxElapsedSec: number;
+    /** Unchanged poses refresh the keep-alive stamp at most this often. */
+    keepAliveRefreshMs: number;
+}
+export interface PoseSyncDecision {
+    position: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    rotationY: number;
+    rotationPitch: number;
+    /** True when the pose differs and a pose write is needed. */
+    changed: boolean;
+    /** True when only the keep-alive stamp should be written. */
+    refreshKeepAlive: boolean;
+}
+export declare function decidePoseSync(current: PresencePoseState, incoming: IncomingPose, rules: PoseSyncRules, nowMs: number): PoseSyncDecision;
+export declare function shouldRefreshKeepAlive(lastSeenAtMs: number | undefined, nowMs: number, rules: Pick<PoseSyncRules, "keepAliveRefreshMs">): boolean;
+export declare function shouldPersistWorldSnapshot(lastSavedAtMs: number | undefined, nowMs: number, intervalMs: number): boolean;
+export interface ActivePresenceResolution<T> {
+    active: T | null;
+    /** Other unrevoked rows for the same actor — a session may only have one. */
+    extras: T[];
+}
+export declare function resolveActivePresence<T extends {
+    revokedAt?: number;
+    lastSeenAt?: number;
+}>(rows: readonly T[]): ActivePresenceResolution<T>;
+export declare function isPresenceExpired(lastSeenAtMs: number, nowMs: number, idleCutoffMs: number): boolean;
+/** Most-recently-seen row across an actor's rows, to reuse instead of inserting a new one. */
+export declare function pickReusablePresence<T extends {
+    lastSeenAt?: number;
+}>(rows: readonly T[]): T | undefined;

package/dist/multiplayer/presenceModel.js

@@ -0,0 +1,51 @@
+export function decidePoseSync(current, incoming, rules, nowMs) {
+    const elapsedSec = Math.max(rules.minElapsedSec, Math.min(rules.maxElapsedSec, (nowMs - (current.lastSeenAtMs ?? nowMs)) / 1000));
+    const maxDist = rules.maxSpeed * elapsedSec;
+    const maxDistSq = maxDist * maxDist;
+    let targetX = incoming.position.x;
+    let targetZ = incoming.position.z;
+    const dx = targetX - current.position.x;
+    const dz = targetZ - current.position.z;
+    const magSq = dx * dx + dz * dz;
+    if (magSq > maxDistSq) {
+        const scale = Math.sqrt(maxDistSq / magSq);
+        targetX = current.position.x + dx * scale;
+        targetZ = current.position.z + dz * scale;
+    }
+    const nextY = incoming.position.y === undefined
+        ? current.position.y
+        : Math.max(0, Math.min(rules.maxVerticalOffset, incoming.position.y));
+    const nextRotationY = incoming.rotationY ?? current.rotationY;
+    const nextRotationPitch = incoming.rotationPitch ?? current.rotationPitch ?? 0;
+    const moved = targetX !== current.position.x || targetZ !== current.position.z;
+    const jumped = nextY !== current.position.y;
+    const rotated = nextRotationY !== current.rotationY || nextRotationPitch !== (current.rotationPitch ?? 0);
+    const changed = moved || jumped || rotated;
+    return {
+        position: { x: targetX, y: nextY, z: targetZ },
+        rotationY: nextRotationY,
+        rotationPitch: nextRotationPitch,
+        changed,
+        refreshKeepAlive: !changed && shouldRefreshKeepAlive(current.lastSeenAtMs, nowMs, rules),
+    };
+}
+export function shouldRefreshKeepAlive(lastSeenAtMs, nowMs, rules) {
+    return nowMs - (lastSeenAtMs ?? 0) >= rules.keepAliveRefreshMs;
+}
+export function shouldPersistWorldSnapshot(lastSavedAtMs, nowMs, intervalMs) {
+    return lastSavedAtMs === undefined || nowMs - lastSavedAtMs >= intervalMs;
+}
+export function resolveActivePresence(rows) {
+    const actives = rows.filter((row) => row.revokedAt === undefined);
+    if (actives.length === 0)
+        return { active: null, extras: [] };
+    const sorted = [...actives].sort((a, b) => (b.lastSeenAt ?? 0) - (a.lastSeenAt ?? 0));
+    return { active: sorted[0] ?? null, extras: sorted.slice(1) };
+}
+export function isPresenceExpired(lastSeenAtMs, nowMs, idleCutoffMs) {
+    return nowMs - lastSeenAtMs >= idleCutoffMs;
+}
+/** Most-recently-seen row across an actor's rows, to reuse instead of inserting a new one. */
+export function pickReusablePresence(rows) {
+    return [...rows].sort((a, b) => (b.lastSeenAt ?? 0) - (a.lastSeenAt ?? 0))[0];
+}

package/dist/runtime/adapter.d.ts

@@ -0,0 +1,24 @@
+export type MultiplayerTopology = "shared" | "lobbies" | "private";
+export type MultiplayerAdapterConfig = {
+    kind: "convex";
+    topology?: MultiplayerTopology;
+} | {
+    kind: "ws";
+    topology?: MultiplayerTopology;
+} | {
+    kind: "offline";
+};
+export declare function convex(config?: {
+    topology?: MultiplayerTopology;
+}): MultiplayerAdapterConfig;
+export declare function ws(config?: {
+    topology?: MultiplayerTopology;
+}): MultiplayerAdapterConfig;
+export declare function offline(): MultiplayerAdapterConfig;
+export type ServersPoolConfig = {
+    maxServers: number;
+    slotsPerServer: number;
+    minPlayersToStart?: number;
+    adapter: MultiplayerAdapterConfig;
+};
+export declare function servers(config: ServersPoolConfig): ServersPoolConfig;

package/dist/runtime/adapter.js

@@ -0,0 +1,12 @@
+export function convex(config) {
+    return { kind: "convex", topology: config?.topology ?? "shared" };
+}
+export function ws(config) {
+    return { kind: "ws", topology: config?.topology ?? "shared" };
+}
+export function offline() {
+    return { kind: "offline" };
+}
+export function servers(config) {
+    return config;
+}

package/dist/runtime/commandRunner.d.ts

@@ -0,0 +1,15 @@
+export type CommandValidationError = {
+    reason: string;
+};
+export type CommandDef<TInput = unknown> = {
+    validate: (snapshot: import("./snapshot.js").GameRuntimeSnapshot, input: TInput) => CommandValidationError | null;
+    apply: (snapshot: import("./snapshot.js").GameRuntimeSnapshot, input: TInput) => import("./snapshot.js").GameRuntimeSnapshot;
+};
+export type RunCommandResult = {
+    ok: true;
+    snapshot: import("./snapshot.js").GameRuntimeSnapshot;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function runCommand<TInput>(snapshot: import("./snapshot.js").GameRuntimeSnapshot, commands: Record<string, CommandDef<TInput>>, commandName: string, input: TInput, actorUserId: string): RunCommandResult;

package/dist/runtime/commandRunner.js

@@ -0,0 +1,25 @@
+export function runCommand(snapshot, commands, commandName, input, actorUserId) {
+    const command = commands[commandName];
+    if (!command) {
+        return { ok: false, reason: `Unknown command: ${commandName}` };
+    }
+    const validationError = command.validate(snapshot, input);
+    if (validationError) {
+        return { ok: false, reason: validationError.reason };
+    }
+    const next = command.apply(snapshot, input);
+    return {
+        ok: true,
+        snapshot: {
+            ...next,
+            revision: snapshot.revision + 1,
+            dirty: {
+                server: true,
+                players: next.dirty.players.includes(actorUserId)
+                    ? next.dirty.players
+                    : [...next.dirty.players, actorUserId],
+                chunks: next.dirty.chunks,
+            },
+        },
+    };
+}

package/dist/runtime/gameContext.d.ts

@@ -0,0 +1,138 @@
+import { type OnDeathSpec } from "../combat/death.js";
+import { type EffectInput, type EffectResult, type ReceiveMap, type SingleTargetEffectInput } from "../combat/effects.js";
+import { type ProjectileSystem } from "../combat/projectiles.js";
+import { type CommandDefinition, type CommandResult } from "../commands/commandRegistry.js";
+import type { GameDefinition } from "../game/defineGame.js";
+import { type GameEventMap, type GameEvents } from "../game/events.js";
+import { type GameFeed } from "../game/feed.js";
+import { type Leaderboard } from "../game/leaderboard.js";
+import { type Loadouts } from "../game/loadout.js";
+import { type Drop, type LootTableDef } from "../game/lootTable.js";
+import { type QuestJournal } from "../game/quest.js";
+import { type Social } from "../game/social.js";
+import { type TradeField, type TradeSystem } from "../game/trade.js";
+import { type Unlocks } from "../game/unlocks.js";
+import { type InventorySet } from "../inventory/inventoryModel.js";
+import { type ItemUseHandler, type ItemUseInput, type ItemUseRejection, type ItemUseResult } from "../item/use.js";
+import { type WeaponStats } from "../item/weapon.js";
+import { type PoseAllowedStates, type PoseState } from "../movement/poseState.js";
+import type { ModelAssetRef } from "../scene/assetCatalog.js";
+import { type EntityStatsApi, type PoolStatCatalog } from "../scene/entityStats.js";
+import type { EntityPose, SceneEntity, SpawnOptions } from "../scene/entityStore.js";
+import { type ObjectStore } from "../scene/objectStore.js";
+import { type SpatialApi } from "../scene/spatial.js";
+import { type CycleTargetOptions } from "../scene/targeting.js";
+import { type Stats } from "../stats/statModifiers.js";
+export interface GameContextItemEntry {
+    use?: string;
+    weapon?: Record<string, unknown>;
+    trade?: TradeField;
+}
+export interface GameContextEntityEntry {
+    stats?: PoolStatCatalog;
+    receive?: ReceiveMap;
+    onDeath?: OnDeathSpec;
+    movement?: PoseAllowedStates & {
+        walkSpeed?: number;
+    };
+    role?: string;
+}
+export interface GameContextContent {
+    itemById?(itemId: string): GameContextItemEntry | null | undefined;
+    entityById?(catalogId: string): GameContextEntityEntry | null | undefined;
+}
+export interface GameContextOptions<TAssetRef extends ModelAssetRef = ModelAssetRef, TMultiplayer = unknown> {
+    definition: GameDefinition<TAssetRef, TMultiplayer>;
+    content: GameContextContent;
+    player: {
+        userId: string;
+        isNew: boolean;
+    };
+    now?: () => number;
+}
+export interface SceneEntityContext {
+    spawn(name: string, options?: SpawnOptions): string;
+    despawn(instanceId: string): boolean;
+    setPose(instanceId: string, pose: EntityPose): boolean;
+    get(instanceId: string): SceneEntity | null;
+    list(): readonly SceneEntity[];
+    stats: EntityStatsApi;
+    setTarget(fromId: string, toId: string | null): void;
+    getTarget(fromId: string): string | null;
+    cycleTarget(fromId: string, options?: CycleTargetOptions): string | null;
+    canReceive(instanceId: string, effect: string): string | null;
+    preview(input: SingleTargetEffectInput): number;
+    effect(input: EffectInput): EffectResult[];
+    willHitProjectile: ProjectileSystem["willHitProjectile"];
+    fireProjectile: ProjectileSystem["fireProjectile"];
+    settleProjectile: ProjectileSystem["settleProjectile"];
+    distance: SpatialApi["distance"];
+    inRadius: SpatialApi["inRadius"];
+    hasLineOfSight: SpatialApi["hasLineOfSight"];
+    queryArc: SpatialApi["queryArc"];
+    moveToward: SpatialApi["moveToward"];
+}
+export interface GameContextCommands {
+    define<TInput>(name: string, definition: CommandDefinition<GameContext, TInput>): void;
+    has(name: string): boolean;
+    names(): string[];
+    run(name: string, input: unknown): CommandResult<GameContext>;
+}
+export interface GameContextFeed extends Omit<GameFeed, "bind"> {
+    bind(action: keyof GameEventMap): () => void;
+}
+export interface GameContextLoot {
+    register(def: LootTableDef): void;
+    has(id: string): boolean;
+    roll(id: string, rng?: () => number): Drop[];
+    grantToPlayer(userId: string, drops: Drop[], source?: string): void;
+}
+export interface GameContextEconomy {
+    balance(userId: string, currencyId: string): number;
+    grant(userId: string, currencyId: string, amount: number): void;
+    charge(userId: string, currencyId: string, amount: number): {
+        reason: string;
+    } | null;
+}
+export interface GameContextItemUse {
+    register(handlers: Record<string, ItemUseHandler<GameContext>>): void;
+    registered(): string[];
+    can(input: ItemUseInput): ItemUseRejection | null;
+    use(input: ItemUseInput): ItemUseResult<GameContext>;
+}
+export interface GameContext {
+    scene: {
+        object: ObjectStore;
+        entity: SceneEntityContext;
+    };
+    game: {
+        commands: GameContextCommands;
+        events: GameEvents;
+        feed: GameContextFeed;
+        loot: GameContextLoot;
+        trade: TradeSystem;
+        quest: QuestJournal;
+        social: Social;
+        unlocks: Unlocks;
+        economy: GameContextEconomy;
+        leaderboard: Leaderboard;
+    };
+    player: {
+        userId: string;
+        isNew: boolean;
+        inventory: InventorySet<string>;
+        stats: Stats<string>;
+        loadout: Loadouts;
+        applyLoadout(userId: string, loadoutId: string): {
+            reason: string;
+        } | null;
+        movement: PoseState;
+    };
+    item: {
+        use: GameContextItemUse;
+        weapon: WeaponStats;
+    };
+    subscribe(listener: () => void): () => void;
+    version(): number;
+}
+export declare function createGameContext<TAssetRef extends ModelAssetRef, TMultiplayer>(options: GameContextOptions<TAssetRef, TMultiplayer>): GameContext;