@jgengine/core 0.6.0 → 0.8.0

package/dist/economy/techTree.js

@@ -0,0 +1,66 @@
+import { createUnlocks, grantUnlock, hasUnlock, unlockTree } from "../game/unlocks.js";
+export function techPrerequisitesMet(state, node) {
+    const requires = node.requires ?? [];
+    return requires.every((id) => hasUnlock(state, id));
+}
+export function missingPrerequisites(state, node) {
+    return (node.requires ?? []).filter((id) => !hasUnlock(state, id));
+}
+export function canUnlockTech(defs, state, id) {
+    const node = defs.find((n) => n.id === id);
+    if (node === undefined)
+        return { ok: false, reason: "unknown-node" };
+    if (hasUnlock(state, id))
+        return { ok: false, reason: "already-unlocked" };
+    const missing = missingPrerequisites(state, node);
+    if (missing.length > 0)
+        return { ok: false, reason: "missing-prerequisites", missing };
+    return { ok: true };
+}
+export function grantTech(state, node) {
+    let next = grantUnlock(state, node.id);
+    for (const extra of node.grants ?? [])
+        next = grantUnlock(next, extra);
+    return next;
+}
+export function availableTech(defs, state) {
+    return defs.filter((node) => !hasUnlock(state, node.id) && techPrerequisitesMet(state, node));
+}
+export function unlockedRecipes(defs, state) {
+    const recipes = [];
+    for (const node of defs) {
+        if (node.recipe !== undefined && hasUnlock(state, node.id))
+            recipes.push(node.recipe);
+    }
+    return recipes;
+}
+export function createTechTree(defs = []) {
+    const nodes = new Map();
+    for (const def of defs)
+        nodes.set(def.id, def);
+    const unlocks = createUnlocks(defs.map((d) => ({ id: d.id, category: d.category })));
+    function stateOf(userId) {
+        return unlocks.list(userId);
+    }
+    return {
+        has: (userId, id) => unlocks.has(userId, id),
+        canUnlock: (userId, id) => canUnlockTech(defs, stateOf(userId), id),
+        unlock(userId, id) {
+            const check = canUnlockTech(defs, stateOf(userId), id);
+            if (!check.ok)
+                return check;
+            const node = nodes.get(id);
+            unlocks.grant(userId, node.id);
+            for (const extra of node.grants ?? [])
+                unlocks.grant(userId, extra);
+            return { ok: true };
+        },
+        available: (userId) => availableTech(defs, stateOf(userId)),
+        recipes: (userId) => unlockedRecipes(defs, stateOf(userId)),
+        list: (userId) => unlocks.list(userId),
+        tree: (categoryId) => unlockTree(defs, categoryId),
+        node: (id) => nodes.get(id) ?? null,
+        snapshot: (userId) => unlocks.snapshot(userId),
+        hydrate: (userId, ids) => unlocks.hydrate(userId, ids),
+    };
+}

package/dist/game/chat.d.ts

@@ -0,0 +1,66 @@
+import type { GameEvents } from "./events.js";
+import type { EmotesDeps } from "./social.js";
+export type ChatChannelKind = "global" | "party" | "proximity";
+export interface ChatRateLimit {
+    count: number;
+    perMs: number;
+}
+export interface ChatChannelDef {
+    id: string;
+    kind: ChatChannelKind;
+    radius?: number;
+    historyLimit?: number;
+    rateLimit?: ChatRateLimit;
+}
+export interface ChatMessage {
+    id: string;
+    channelId: string;
+    fromUserId: string;
+    body: string;
+    at: number;
+}
+export type ChatRecipients = readonly string[] | "all";
+export type ChatSendResult = {
+    message: ChatMessage;
+    recipients: ChatRecipients;
+} | {
+    reason: string;
+};
+export interface ChatSnapshot {
+    messages: Record<string, ChatMessage[]>;
+    counter: number;
+}
+export interface Chat {
+    register(def: ChatChannelDef): void;
+    channels(): ChatChannelDef[];
+    send(fromUserId: string, channelId: string, body: string): ChatSendResult;
+    whisper(fromUserId: string, toUserId: string, body: string): ChatSendResult;
+    history(channelId: string, options?: {
+        limit?: number;
+        viewerUserId?: string;
+    }): ChatMessage[];
+    snapshot(): ChatSnapshot;
+    hydrate(data: ChatSnapshot): void;
+}
+export interface ChatDeps {
+    events: GameEvents;
+    now?: () => number;
+    party?: {
+        membersOf(userId: string): string[];
+    };
+    proximity?: EmotesDeps;
+    blockedBy?: (userId: string) => readonly string[];
+    maxBodyLength?: number;
+    defaultRateLimit?: ChatRateLimit;
+}
+export declare const DEFAULT_CHAT_RATE_LIMIT: ChatRateLimit;
+export declare const DEFAULT_CHAT_HISTORY_LIMIT = 100;
+export declare const DEFAULT_CHAT_BODY_LENGTH = 500;
+export declare const DEFAULT_PROXIMITY_CHAT_RADIUS = 20;
+export declare const WHISPER_CHANNEL_PREFIX = "whisper:";
+export declare function whisperChannelId(a: string, b: string): string;
+export interface ChatRateLimiter {
+    allow(key: string, atMs: number): boolean;
+}
+export declare function createChatRateLimiter(limit: ChatRateLimit): ChatRateLimiter;
+export declare function createChat(deps: ChatDeps): Chat;

package/dist/game/chat.js

@@ -0,0 +1,165 @@
+export const DEFAULT_CHAT_RATE_LIMIT = { count: 10, perMs: 10_000 };
+export const DEFAULT_CHAT_HISTORY_LIMIT = 100;
+export const DEFAULT_CHAT_BODY_LENGTH = 500;
+export const DEFAULT_PROXIMITY_CHAT_RADIUS = 20;
+export const WHISPER_CHANNEL_PREFIX = "whisper:";
+export function whisperChannelId(a, b) {
+    const [first, second] = a < b ? [a, b] : [b, a];
+    return `${WHISPER_CHANNEL_PREFIX}${first}:${second}`;
+}
+export function createChatRateLimiter(limit) {
+    const windows = new Map();
+    return {
+        allow(key, atMs) {
+            const cutoff = atMs - limit.perMs;
+            const stamps = (windows.get(key) ?? []).filter((stamp) => stamp > cutoff);
+            if (stamps.length >= limit.count) {
+                windows.set(key, stamps);
+                return false;
+            }
+            stamps.push(atMs);
+            windows.set(key, stamps);
+            return true;
+        },
+    };
+}
+const BUILTIN_CHANNELS = [
+    { id: "global", kind: "global" },
+    { id: "party", kind: "party" },
+    { id: "proximity", kind: "proximity", radius: DEFAULT_PROXIMITY_CHAT_RADIUS },
+];
+export function createChat(deps) {
+    const now = deps.now ?? Date.now;
+    const events = deps.events;
+    const maxBodyLength = deps.maxBodyLength ?? DEFAULT_CHAT_BODY_LENGTH;
+    const defaultRateLimit = deps.defaultRateLimit ?? DEFAULT_CHAT_RATE_LIMIT;
+    const blockedBy = deps.blockedBy ?? (() => []);
+    const channelDefs = new Map();
+    for (const def of BUILTIN_CHANNELS)
+        channelDefs.set(def.id, { ...def });
+    const messagesByChannel = new Map();
+    const limiters = new Map();
+    let counter = 0;
+    function limiterFor(channelId, rateLimit) {
+        let limiter = limiters.get(channelId);
+        if (limiter === undefined) {
+            limiter = createChatRateLimiter(rateLimit);
+            limiters.set(channelId, limiter);
+        }
+        return limiter;
+    }
+    function hasBlocked(userId, targetUserId) {
+        return blockedBy(userId).includes(targetUserId);
+    }
+    function resolveRecipients(fromUserId, channelId, def) {
+        if (channelId.startsWith(WHISPER_CHANNEL_PREFIX)) {
+            const pair = channelId.slice(WHISPER_CHANNEL_PREFIX.length).split(":");
+            const toUserId = pair.find((userId) => userId !== fromUserId);
+            if (pair.length !== 2 || toUserId === undefined || !pair.includes(fromUserId)) {
+                return { reason: "not a participant of this whisper" };
+            }
+            if (hasBlocked(toUserId, fromUserId) || hasBlocked(fromUserId, toUserId)) {
+                return { reason: "blocked" };
+            }
+            return { recipients: [toUserId] };
+        }
+        if (def === null)
+            return { reason: `unknown channel "${channelId}"` };
+        if (def.kind === "global")
+            return { recipients: "all" };
+        if (def.kind === "party") {
+            const members = deps.party?.membersOf(fromUserId) ?? [];
+            if (!members.includes(fromUserId))
+                return { reason: "not in a party" };
+            return {
+                recipients: members.filter((userId) => userId !== fromUserId && !hasBlocked(userId, fromUserId)),
+            };
+        }
+        const proximity = deps.proximity;
+        if (proximity === undefined)
+            return { reason: "proximity chat not configured" };
+        const origin = proximity.entities.get(fromUserId);
+        if (origin === null)
+            return { reason: `entity "${fromUserId}" is not spawned` };
+        const nearby = proximity.spatial.inRadius(origin.position, def.radius ?? DEFAULT_PROXIMITY_CHAT_RADIUS, (id) => id !== fromUserId && proximity.entities.get(id)?.role === "player");
+        return { recipients: nearby.filter((userId) => !hasBlocked(userId, fromUserId)) };
+    }
+    function append(channelId, message, historyLimit) {
+        const ring = messagesByChannel.get(channelId) ?? [];
+        ring.push(message);
+        if (ring.length > historyLimit)
+            ring.splice(0, ring.length - historyLimit);
+        messagesByChannel.set(channelId, ring);
+    }
+    function sendResolved(fromUserId, channelId, body, def) {
+        const trimmed = body.trim();
+        if (trimmed.length === 0)
+            return { reason: "empty message" };
+        if (trimmed.length > maxBodyLength)
+            return { reason: "message too long" };
+        const resolved = resolveRecipients(fromUserId, channelId, def);
+        if ("reason" in resolved)
+            return resolved;
+        const at = now();
+        const rateLimit = def?.rateLimit ?? defaultRateLimit;
+        if (!limiterFor(channelId, rateLimit).allow(`${fromUserId}|${channelId}`, at)) {
+            return { reason: "rate limited" };
+        }
+        counter += 1;
+        const message = {
+            id: `msg_${counter}`,
+            channelId,
+            fromUserId,
+            body: trimmed,
+            at,
+        };
+        append(channelId, message, def?.historyLimit ?? DEFAULT_CHAT_HISTORY_LIMIT);
+        const event = { ...message };
+        if (resolved.recipients !== "all")
+            event.recipients = resolved.recipients;
+        events.emit("chat.message", event);
+        return { message, recipients: resolved.recipients };
+    }
+    return {
+        register(def) {
+            channelDefs.set(def.id, { ...def });
+            limiters.delete(def.id);
+        },
+        channels() {
+            return Array.from(channelDefs.values(), (def) => ({ ...def }));
+        },
+        send(fromUserId, channelId, body) {
+            const def = channelDefs.get(channelId) ?? null;
+            return sendResolved(fromUserId, channelId, body, def);
+        },
+        whisper(fromUserId, toUserId, body) {
+            if (fromUserId === toUserId)
+                return { reason: "cannot whisper yourself" };
+            const channelId = whisperChannelId(fromUserId, toUserId);
+            return sendResolved(fromUserId, channelId, body, channelDefs.get(channelId) ?? null);
+        },
+        history(channelId, options) {
+            const ring = messagesByChannel.get(channelId) ?? [];
+            const viewerUserId = options?.viewerUserId;
+            const visible = viewerUserId === undefined
+                ? ring
+                : ring.filter((message) => !hasBlocked(viewerUserId, message.fromUserId));
+            const limit = options?.limit;
+            return limit === undefined ? visible.slice() : visible.slice(-limit);
+        },
+        snapshot() {
+            const messages = {};
+            for (const [channelId, ring] of messagesByChannel) {
+                messages[channelId] = ring.map((message) => ({ ...message }));
+            }
+            return { messages, counter };
+        },
+        hydrate(data) {
+            messagesByChannel.clear();
+            for (const [channelId, ring] of Object.entries(data.messages)) {
+                messagesByChannel.set(channelId, ring.map((message) => ({ ...message })));
+            }
+            counter = data.counter;
+        },
+    };
+}

package/dist/game/cosmetics.d.ts

@@ -0,0 +1,25 @@
+export interface CosmeticLoadoutDef {
+    slots: Record<string, string>;
+}
+export interface CosmeticsChangedEvent {
+    userId: string;
+    slots: Record<string, string>;
+}
+export interface CosmeticsEvents {
+    emit(name: "cosmetics.changed", payload: CosmeticsChangedEvent): void;
+}
+export interface CosmeticsDeps {
+    events?: CosmeticsEvents;
+}
+export interface Cosmetics {
+    register(defs: Record<string, CosmeticLoadoutDef>): void;
+    has(loadoutId: string): boolean;
+    apply(userId: string, loadoutId: string): {
+        reason: string;
+    } | null;
+    equip(userId: string, slot: string, cosmeticId: string | null): void;
+    get(userId: string): Readonly<Record<string, string>>;
+    snapshot(userId: string): Record<string, string>;
+    hydrate(userId: string, state: Record<string, string>): void;
+}
+export declare function createCosmetics(deps?: CosmeticsDeps): Cosmetics;

package/dist/game/cosmetics.js

@@ -0,0 +1,51 @@
+const EMPTY_SLOTS = Object.freeze({});
+export function createCosmetics(deps = {}) {
+    const definitions = new Map();
+    const equipped = new Map();
+    function slotsOf(userId) {
+        let slots = equipped.get(userId);
+        if (slots === undefined) {
+            slots = {};
+            equipped.set(userId, slots);
+        }
+        return slots;
+    }
+    function notify(userId) {
+        deps.events?.emit("cosmetics.changed", { userId, slots: { ...slotsOf(userId) } });
+    }
+    return {
+        register(defs) {
+            for (const [loadoutId, def] of Object.entries(defs))
+                definitions.set(loadoutId, def);
+        },
+        has(loadoutId) {
+            return definitions.has(loadoutId);
+        },
+        apply(userId, loadoutId) {
+            const def = definitions.get(loadoutId);
+            if (def === undefined)
+                return { reason: `unknown cosmetic loadout "${loadoutId}"` };
+            const slots = slotsOf(userId);
+            Object.assign(slots, def.slots);
+            notify(userId);
+            return null;
+        },
+        equip(userId, slot, cosmeticId) {
+            const slots = slotsOf(userId);
+            if (cosmeticId === null)
+                delete slots[slot];
+            else
+                slots[slot] = cosmeticId;
+            notify(userId);
+        },
+        get(userId) {
+            return equipped.get(userId) ?? EMPTY_SLOTS;
+        },
+        snapshot(userId) {
+            return { ...slotsOf(userId) };
+        },
+        hydrate(userId, state) {
+            equipped.set(userId, { ...state });
+        },
+    };
+}

package/dist/game/defineGame.d.ts

@@ -1,12 +1,15 @@
 import type { ActionCodesMap } from "../input/actionBindings.js";
+import type { GameFeedOptions } from "./feed.js";
 import type { ItemTraits } from "../inventory/inventoryModel.js";
+import type { StorageTier } from "../inventory/storageTier.js";
 import type { SaveConfig } from "../runtime/save.js";
-import type { AssetCatalog, ModelAssetRef } from "../scene/assetCatalog.js";
+import { type AssetCatalog, type ModelAssetRef } from "../scene/assetCatalog.js";
 import { type EntityStore } from "../scene/entityStore.js";
 import type { TimeConfig } from "../time/simClock.js";
 import type { WorldFeature } from "../world/features.js";
 export interface PhysicsConfig {
     gravity?: number;
+    jumpVelocity?: number;
 }
 export interface InventoryDeclaration {
     slots: number;
@@ -14,6 +17,7 @@ export interface InventoryDeclaration {
     accepts?: string | readonly string[];
     traits?: ItemTraits;
     applyModifiers?: boolean;
+    tier?: StorageTier;
 }
 export type GameServerConfig = "persistent" | {
     mode: string;
@@ -33,6 +37,8 @@ export interface GameDefinition<TAssetRef extends ModelAssetRef = ModelAssetRef,
     physics?: PhysicsConfig;
     /** Simulation clock: real→game time scale, selectable speeds, calendar. Exposed as `ctx.time`; the shell feeds its scaled dt to `loop.onTick`. */
     time?: TimeConfig;
+    /** Per-action ring-buffer capacity for `ctx.game.feed`. Default 20. */
+    feed?: GameFeedOptions;
     inventories?: Record<string, InventoryDeclaration>;
     input?: ActionCodesMap;
     server?: GameServerConfig;
@@ -40,5 +46,7 @@ export interface GameDefinition<TAssetRef extends ModelAssetRef = ModelAssetRef,
     ui?: unknown;
     loop?: GameLoop<any>;
 }
-export type GameDefinitionConfig<TAssetRef extends ModelAssetRef = ModelAssetRef, TMultiplayer = unknown> = Omit<GameDefinition<TAssetRef, TMultiplayer>, "scene">;
+export type GameDefinitionConfig<TAssetRef extends ModelAssetRef = ModelAssetRef, TMultiplayer = unknown> = Omit<GameDefinition<TAssetRef, TMultiplayer>, "scene" | "assets"> & {
+    assets?: AssetCatalog<TAssetRef>;
+};
 export declare function defineGame<TAssetRef extends ModelAssetRef, TMultiplayer>(config: GameDefinitionConfig<TAssetRef, TMultiplayer>): GameDefinition<TAssetRef, TMultiplayer>;

package/dist/game/defineGame.js

@@ -1,7 +1,8 @@
+import { createAssetCatalog } from "../scene/assetCatalog.js";
 import { createEntityStore } from "../scene/entityStore.js";
 export function defineGame(config) {
     if (config.name.trim().length === 0) {
         throw new Error("defineGame: name must be non-empty");
     }
-    return { ...config, scene: createEntityStore() };
+    return { ...config, scene: createEntityStore(), assets: config.assets ?? createAssetCatalog() };
 }

package/dist/game/events.d.ts

@@ -1,3 +1,5 @@
+import type { TelegraphShape } from "../combat/telegraph.js";
+import type { CameraShake } from "../combat/hitReaction.js";
 export type DeathReason = {
     kind: "player_kill";
     killerUserId: string;
@@ -61,6 +63,28 @@ export interface SocialPartyLeftEvent {
     userId: string;
     partyId: string;
 }
+export interface SocialWorldInvitedEvent {
+    inviteId: string;
+    fromUserId: string;
+    toUserId: string;
+    serverId: string;
+    joinCode?: string;
+}
+export interface SocialWorldAcceptedEvent {
+    inviteId: string;
+    userId: string;
+    fromUserId: string;
+    serverId: string;
+    joinCode?: string;
+}
+export interface ChatMessageEvent {
+    id: string;
+    channelId: string;
+    fromUserId: string;
+    body: string;
+    at: number;
+    recipients?: readonly string[];
+}
 export interface StatLevelUpEvent {
     userId: string;
     stat: string;
@@ -72,6 +96,24 @@ export interface EntityFloatTextEvent {
     text: string;
     kind: string;
     amount?: number;
+    hitType?: string;
+    element?: string;
+    crit?: boolean;
+    scale?: number;
+}
+export interface CombatTelegraphEvent {
+    id: number;
+    shape: TelegraphShape;
+    position: [number, number, number];
+    dir?: number;
+    windupMs: number;
+    kind: string;
+}
+export interface CombatHitReactionEvent {
+    instanceId?: string;
+    position: [number, number, number];
+    hitstopMs: number;
+    shake?: CameraShake;
 }
 export interface ProjectileSettledEvent {
     from: string;
@@ -80,9 +122,45 @@ export interface ProjectileSettledEvent {
     effect: string;
     hit: boolean;
 }
+export interface WorldItemDroppedEvent {
+    instanceId: string;
+    itemId: string;
+    rarity: string;
+    count: number;
+    position: [number, number, number];
+    source?: string;
+}
+export interface WorldItemPickedUpEvent {
+    instanceId: string;
+    userId: string;
+    itemId: string;
+    rarity: string;
+    count: number;
+}
+export interface CosmeticsChangedEvent {
+    userId: string;
+    slots: Record<string, string>;
+}
+export interface EmotePlayedEvent {
+    from: string;
+    emoteId: string;
+    at: readonly [number, number, number];
+    recipients: readonly string[];
+}
+export interface PossessionSwappedEvent {
+    userId: string;
+    entityId: string;
+    previousEntityId: string;
+}
+export interface FormChangedEvent {
+    instanceId: string;
+    formId: string | null;
+}
 export interface GameEventMap {
     "entity.died": EntityDiedEvent;
     "entity.floatText": EntityFloatTextEvent;
+    "combat.telegraph": CombatTelegraphEvent;
+    "combat.hitReaction": CombatHitReactionEvent;
     "loot.granted": LootGrantedEvent;
     "inventory.added": InventoryAddedEvent;
     "quest.accepted": QuestAcceptedEvent;
@@ -91,8 +169,17 @@ export interface GameEventMap {
     "social.friend.added": SocialFriendAddedEvent;
     "social.party.joined": SocialPartyJoinedEvent;
     "social.party.left": SocialPartyLeftEvent;
+    "social.world.invited": SocialWorldInvitedEvent;
+    "social.world.accepted": SocialWorldAcceptedEvent;
+    "chat.message": ChatMessageEvent;
     "stat.levelUp": StatLevelUpEvent;
     "projectile.settled": ProjectileSettledEvent;
+    "worldItem.dropped": WorldItemDroppedEvent;
+    "worldItem.picked_up": WorldItemPickedUpEvent;
+    "cosmetics.changed": CosmeticsChangedEvent;
+    "emote.played": EmotePlayedEvent;
+    "possession.swapped": PossessionSwappedEvent;
+    "form.changed": FormChangedEvent;
 }
 export type GameEventHandler<TPayload> = (payload: TPayload) => void;
 export interface GameEvents<TMap extends GameEventMap = GameEventMap> {

package/dist/game/levelSequence.d.ts

@@ -0,0 +1,44 @@
+export interface LevelDescriptor<TLevelConfig> {
+    id: string;
+    config: TLevelConfig;
+}
+export interface LevelSequenceConfig<TLevelConfig> {
+    levels: readonly LevelDescriptor<TLevelConfig>[];
+    /** Extra attempts granted after the first per level. Defaults to 0 (a single attempt, no retries). */
+    retriesPerLevel?: number;
+}
+export type LevelSequenceStatus = "idle" | "playing" | "cleared" | "failed" | "complete";
+export interface CurrentLevel<TLevelConfig> {
+    id: string;
+    index: number;
+    config: TLevelConfig;
+    attempt: number;
+}
+export interface LevelSequenceProgress {
+    index: number;
+    total: number;
+    cleared: readonly string[];
+}
+export interface LevelSequence<TLevelConfig> {
+    current(): CurrentLevel<TLevelConfig> | null;
+    status(): LevelSequenceStatus;
+    /** Enters level 0. A no-op on an empty level list, which leaves `status()` at "idle" forever. */
+    start(): void;
+    /** Marks the current level cleared; call `advance()` to move to the next one. */
+    clear(): void;
+    /** Consumes an attempt on the current level. Returns "retry" while attempts remain, else "failed". */
+    fail(): "retry" | "failed";
+    /** Restarts the current level after a "retry"-eligible failure. Returns false if there was nothing to retry. */
+    retry(): boolean;
+    /** Moves past a cleared level, or to "complete" if it was the last one. Returns false unless status is "cleared". */
+    advance(): boolean;
+    reset(): void;
+    progress(): LevelSequenceProgress;
+}
+/**
+ * A pure, deterministic level campaign: an ordered list of levels, each with its own opaque config, played
+ * through a `start` → (`clear` → `advance`)* → `complete` happy path, with `fail`/`retry` handling per-level
+ * attempts. Mirrors the reducer style of `game/race.ts` and `ai/spawnDirector.ts` — no I/O, no timers, just
+ * state transitions driven by the caller.
+ */
+export declare function createLevelSequence<TLevelConfig>(config: LevelSequenceConfig<TLevelConfig>): LevelSequence<TLevelConfig>;

package/dist/game/levelSequence.js

@@ -0,0 +1,78 @@
+/**
+ * A pure, deterministic level campaign: an ordered list of levels, each with its own opaque config, played
+ * through a `start` → (`clear` → `advance`)* → `complete` happy path, with `fail`/`retry` handling per-level
+ * attempts. Mirrors the reducer style of `game/race.ts` and `ai/spawnDirector.ts` — no I/O, no timers, just
+ * state transitions driven by the caller.
+ */
+export function createLevelSequence(config) {
+    const levels = config.levels;
+    const maxAttempts = 1 + Math.max(0, Math.floor(config.retriesPerLevel ?? 0));
+    let index = 0;
+    let attempt = 1;
+    let status = "idle";
+    const clearedIds = [];
+    function current() {
+        if (status === "idle" || status === "complete")
+            return null;
+        const level = levels[index];
+        if (level === undefined)
+            return null;
+        return { id: level.id, index, config: level.config, attempt };
+    }
+    return {
+        current,
+        status: () => status,
+        start() {
+            if (levels.length === 0)
+                return;
+            index = 0;
+            attempt = 1;
+            clearedIds.length = 0;
+            status = "playing";
+        },
+        clear() {
+            if (status !== "playing" || current() === null)
+                return;
+            clearedIds.push(levels[index].id);
+            status = "cleared";
+        },
+        fail() {
+            if (status !== "playing" || current() === null)
+                return "failed";
+            status = "failed";
+            return attempt < maxAttempts ? "retry" : "failed";
+        },
+        retry() {
+            if (status !== "failed" || attempt >= maxAttempts)
+                return false;
+            attempt += 1;
+            status = "playing";
+            return true;
+        },
+        advance() {
+            if (status !== "cleared")
+                return false;
+            if (index >= levels.length - 1) {
+                status = "complete";
+                return true;
+            }
+            index += 1;
+            attempt = 1;
+            status = "playing";
+            return true;
+        },
+        reset() {
+            index = 0;
+            attempt = 1;
+            clearedIds.length = 0;
+            status = "idle";
+        },
+        progress() {
+            return {
+                index: status === "complete" ? levels.length : index,
+                total: levels.length,
+                cleared: [...clearedIds],
+            };
+        },
+    };
+}