@jgengine/core 0.6.0 → 0.8.0

package/dist/runtime/gameContext.js

@@ -1,14 +1,21 @@
-import { createDeathSystem, deathReasonFromEffect } from "../combat/death.js";
+import { createCardPile } from "../cards/cardPile.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 { groundFieldFor } from "../world/terrain.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 { createChat } from "../game/chat.js";
 import { createSocial } from "../game/social.js";
 import { createTradeSystem } from "../game/trade.js";
 import { createUnlocks } from "../game/unlocks.js";
@@ -16,18 +23,29 @@ import { createInventorySet, putItem, } from "../inventory/inventoryModel.js";
 import { createItemUse, } from "../item/use.js";
 import { createWeaponStats } from "../item/weapon.js";
 import { createPoseState } from "../movement/poseState.js";
+import { createPaintLayer } from "../scene/paintLayer.js";
 import { createEntityStatsApi, seedStatValues, setStatValue, } from "../scene/entityStats.js";
+import { createForms } from "../scene/form.js";
+import { raycastObjects, raycastObjectsAll } from "../scene/objectQuery.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 { createObservableKeyedStore } from "../store/observableKeyedStore.js";
 import { createSimClock } from "../time/simClock.js";
+import { createTurnLoop } from "../turn/turnLoop.js";
+import { createCameraDirector } from "./cameraDirector.js";
+import { createInputSnapshot } from "./inputSnapshot.js";
+import { createMotionIntents } from "./motionIntents.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 ground = groundFieldFor(definition.world);
     const entities = definition.scene;
     const objects = createObjectStore();
     entities.subscribe(signal.notify);
@@ -77,20 +95,44 @@ export function createGameContext(options) {
             signal.notify();
         },
     };
-    const feed = createGameFeed();
+    const feed = createGameFeed(definition.feed);
     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),
+        friends: notifyAfter(rawSocial.friends, ["request", "accept", "decline", "remove", "block", "hydrate"], signal.notify),
+        party: notifyAfter(rawSocial.party, ["invite", "accept", "decline", "kick", "leave", "promote"], signal.notify),
         presence: rawSocial.presence,
+        emotes: rawSocial.emotes,
+        worldInvites: notifyAfter(rawSocial.worldInvites, ["invite", "accept", "decline"], signal.notify),
     };
+    const chat = notifyAfter(createChat({
+        events,
+        now,
+        party: rawSocial.party,
+        proximity: {
+            entities: { get: (id) => entities.get(id) },
+            spatial: { inRadius: (center, radius, filter) => spatial.inRadius(center, radius, filter) },
+        },
+        blockedBy: (userId) => rawSocial.friends.snapshot(userId).blocked,
+    }), ["register", "send", "whisper", "hydrate"], signal.notify);
     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 paintLayer = notifyAfter(createPaintLayer(), ["paint", "clear"], signal.notify);
     const inventoryDeclarations = definition.inventories ?? {};
     const inventoryIds = Object.keys(inventoryDeclarations);
     const layouts = {};
@@ -242,6 +284,47 @@ export function createGameContext(options) {
         pose.clear(instanceId);
         return existed;
     }
+    function resetAllToSpawn(filter) {
+        let count = 0;
+        for (const entity of entities.list()) {
+            if (filter !== undefined && !filter(entity))
+                continue;
+            if (entities.resetToSpawn(entity.id))
+                count += 1;
+        }
+        return count;
+    }
+    const worldItems = notifyAfter(createWorldItemStore({
+        spawnEntity: (position) => entities.spawn(WORLD_ITEM_ENTITY_NAME, { position, role: "prop" }),
+        despawnEntity,
+        resolvePosition: (instanceId) => entities.get(instanceId)?.position,
+    }), ["spawn", "take", "remove"], 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) {
@@ -268,7 +351,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),
@@ -278,7 +364,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);
@@ -297,8 +399,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())
@@ -347,18 +517,70 @@ export function createGameContext(options) {
     const sceneObjects = {
         ...objects,
         catalog: (instanceId) => catalogObject(instanceId) ?? null,
+        raycast: (input) => raycastObjects(objects.list(), input),
+        raycastAll: (input) => raycastObjectsAll(objects.list(), input),
     };
+    const store = notifyAfter(createObservableKeyedStore(), ["set", "delete"], signal.notify);
+    const cardPiles = new Map();
+    function pile(id, config) {
+        const existing = cardPiles.get(id);
+        if (existing !== undefined)
+            return existing;
+        if (config === undefined) {
+            throw new Error(`cardPile "${id}" has not been created yet; pass a config on first access`);
+        }
+        const created = notifyAfter(createCardPile(config), ["shuffle", "draw", "discard", "exhaust", "move", "reset"], signal.notify);
+        cardPiles.set(id, created);
+        return created;
+    }
+    const turnLoops = new Map();
+    function loop(id, config) {
+        const existing = turnLoops.get(id);
+        if (existing !== undefined)
+            return existing;
+        if (config === undefined) {
+            throw new Error(`turn loop "${id}" has not been created yet; pass a config on first access`);
+        }
+        const raw = createTurnLoop(config);
+        const wrappedCommit = notifyAfter(raw.commit, ["submit", "expected", "commit", "rewind", "clear"], signal.notify);
+        const wrapped = {
+            ...notifyAfter(raw, [
+                "setOrder",
+                "addParticipant",
+                "removeParticipant",
+                "advancePhase",
+                "advanceTurn",
+                "advanceRound",
+                "spend",
+                "gain",
+                "refill",
+                "restore",
+            ], signal.notify),
+            commit: wrappedCommit,
+        };
+        turnLoops.set(id, wrapped);
+        return wrapped;
+    }
+    const camera = notifyAfter(createCameraDirector(), ["follow", "setCinematic"], signal.notify);
+    const input = createInputSnapshot();
+    const motion = createMotionIntents();
     const ctx = {
         scene: {
             object: sceneObjects,
             entity: {
                 spawn: spawnEntity,
                 despawn: despawnEntity,
+                update: entities.update,
                 setPose: entities.setPose,
                 get: entities.get,
                 list: entities.list,
+                spawnPoseOf: entities.spawnPoseOf,
+                resetToSpawn: entities.resetToSpawn,
+                resetAllToSpawn,
                 stats: entityStats,
                 floatText: emitFloatText,
+                telegraph: fireTelegraph,
+                hitReaction: applyHitReaction,
                 setTarget: targeting.setTarget,
                 getTarget: targeting.getTarget,
                 cycleTarget: targeting.cycleTarget,
@@ -373,8 +595,22 @@ export function createGameContext(options) {
                 hasLineOfSight: spatial.hasLineOfSight,
                 queryArc: spatial.queryArc,
                 moveToward: spatial.moveToward,
+                form: forms,
+                paint: paintLayer,
+            },
+            worldItem: {
+                spawn: spawnWorldItem,
+                get: worldItems.get,
+                list: worldItems.list,
+                nearestInRadius: worldItems.nearestInRadius,
+                pickup: pickupWorldItem,
+                consume: worldItems.remove,
             },
         },
+        world: {
+            ground,
+            groundHeightAt: ground.sampleHeight,
+        },
         game: {
             commands: {
                 define: commandRegistry.define,
@@ -405,9 +641,14 @@ export function createGameContext(options) {
             trade,
             quest,
             social,
+            chat,
             unlocks,
             economy,
             leaderboard,
+            roster,
+            store,
+            cards: { pile },
+            turn: { loop },
         },
         player: {
             userId: player.userId,
@@ -417,6 +658,9 @@ export function createGameContext(options) {
             loadout: loadouts,
             applyLoadout: loadouts.applyLoadout,
             movement: pose,
+            possession,
+            cosmetics,
+            motion,
         },
         item: {
             use: {
@@ -432,6 +676,8 @@ export function createGameContext(options) {
             weapon,
         },
         time,
+        camera,
+        input,
         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;
@@ -49,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;
@@ -58,11 +91,17 @@ 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 declare function toOpenServerListings(listings: Iterable<ServerListing>, limit?: number): 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

@@ -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)
@@ -42,9 +86,19 @@ 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,
     };
 }
+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/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;