@jgengine/core 0.1.0

package/dist/economy/currency.d.ts

@@ -0,0 +1,26 @@
+export interface CurrencyDefinition<TCurrencyId extends string = string> {
+    id: TCurrencyId;
+    name: string;
+    /** Prepended when formatting amounts (e.g. "$"). */
+    symbol?: string;
+    /** Appended when formatting amounts (e.g. "tokens"). */
+    unit?: string;
+}
+export type CurrencyOperation = "add" | "deduct";
+export type CurrencyAdjustment = {
+    success: true;
+    newBalance: number;
+    appliedDelta: number;
+} | {
+    success: false;
+    reason: string;
+};
+export declare function sanitizeCurrencyAmount(amount: number): number;
+export declare function formatCurrencyAmount(currency: CurrencyDefinition, amount: number): string;
+export declare function insufficientCurrencyReason(currency: CurrencyDefinition, needed: number, current: number): string;
+export declare function applyCurrencyOperation(currency: CurrencyDefinition, current: number, operation: CurrencyOperation, amount: number): CurrencyAdjustment;
+/** Deducts clamp to the available balance (a delta can never overdraw); adds apply in full. */
+export declare function resolveCurrencyDelta(current: number, delta: number): {
+    operation: CurrencyOperation;
+    amount: number;
+};

package/dist/economy/currency.js

@@ -0,0 +1,28 @@
+export function sanitizeCurrencyAmount(amount) {
+    return Math.max(0, Math.floor(amount));
+}
+export function formatCurrencyAmount(currency, amount) {
+    const prefix = currency.symbol ?? "";
+    const suffix = currency.unit ? ` ${currency.unit}` : "";
+    return `${prefix}${amount}${suffix}`;
+}
+export function insufficientCurrencyReason(currency, needed, current) {
+    return `Insufficient ${currency.id}: need ${formatCurrencyAmount(currency, needed)}, have ${formatCurrencyAmount(currency, current)}`;
+}
+export function applyCurrencyOperation(currency, current, operation, amount) {
+    const safeAmount = sanitizeCurrencyAmount(amount);
+    if (safeAmount === 0)
+        return { success: true, newBalance: current, appliedDelta: 0 };
+    if (operation === "deduct" && current < safeAmount) {
+        return { success: false, reason: insufficientCurrencyReason(currency, safeAmount, current) };
+    }
+    const appliedDelta = operation === "add" ? safeAmount : -safeAmount;
+    return { success: true, newBalance: current + appliedDelta, appliedDelta };
+}
+/** Deducts clamp to the available balance (a delta can never overdraw); adds apply in full. */
+export function resolveCurrencyDelta(current, delta) {
+    const safeDelta = Math.floor(delta);
+    if (safeDelta > 0)
+        return { operation: "add", amount: safeDelta };
+    return { operation: "deduct", amount: Math.min(Math.abs(safeDelta), current) };
+}

package/dist/economy/wallet.d.ts

@@ -0,0 +1,16 @@
+export interface WalletState {
+    balances: Readonly<Record<string, number>>;
+}
+export type ChargeResult = {
+    status: "ok";
+    state: WalletState;
+} | {
+    status: "rejected";
+    reason: "insufficient-funds";
+};
+export declare function createEmptyWallet(): WalletState;
+export declare function balance(state: WalletState, currency: string): number;
+export declare function grant(state: WalletState, currency: string, amount: number): WalletState;
+export declare function charge(state: WalletState, currency: string, amount: number): ChargeResult;
+export declare function canAfford(state: WalletState, costs: Readonly<Record<string, number>>): boolean;
+export declare function chargeAll(state: WalletState, costs: Readonly<Record<string, number>>): ChargeResult;

package/dist/economy/wallet.js

@@ -0,0 +1,49 @@
+export function createEmptyWallet() {
+    return { balances: {} };
+}
+function assertValidAmount(amount) {
+    if (!Number.isFinite(amount) || amount <= 0) {
+        throw new RangeError(`amount must be a positive finite number, got ${amount}`);
+    }
+}
+export function balance(state, currency) {
+    return state.balances[currency] ?? 0;
+}
+export function grant(state, currency, amount) {
+    assertValidAmount(amount);
+    return {
+        balances: {
+            ...state.balances,
+            [currency]: balance(state, currency) + amount,
+        },
+    };
+}
+export function charge(state, currency, amount) {
+    assertValidAmount(amount);
+    const current = balance(state, currency);
+    if (current < amount) {
+        return { status: "rejected", reason: "insufficient-funds" };
+    }
+    return {
+        status: "ok",
+        state: {
+            balances: {
+                ...state.balances,
+                [currency]: current - amount,
+            },
+        },
+    };
+}
+export function canAfford(state, costs) {
+    return Object.entries(costs).every(([currency, amount]) => balance(state, currency) >= amount);
+}
+export function chargeAll(state, costs) {
+    if (!canAfford(state, costs)) {
+        return { status: "rejected", reason: "insufficient-funds" };
+    }
+    const balances = { ...state.balances };
+    for (const [currency, amount] of Object.entries(costs)) {
+        balances[currency] = balance(state, currency) - amount;
+    }
+    return { status: "ok", state: { balances } };
+}

package/dist/game/defineGame.d.ts

@@ -0,0 +1,41 @@
+import type { ActionCodesMap } from "../input/actionBindings.js";
+import type { ItemTraits } from "../inventory/inventoryModel.js";
+import type { SaveConfig } from "../runtime/save.js";
+import type { AssetCatalog, ModelAssetRef } from "../scene/assetCatalog.js";
+import { type EntityStore } from "../scene/entityStore.js";
+import type { WorldFeature } from "../world/features.js";
+export interface PhysicsConfig {
+    gravity?: number;
+}
+export interface InventoryDeclaration {
+    slots: number;
+    hud?: string;
+    accepts?: string | readonly string[];
+    traits?: ItemTraits;
+    applyModifiers?: boolean;
+}
+export type GameServerConfig = "persistent" | {
+    mode: string;
+    [key: string]: unknown;
+};
+export interface GameLoop<TContext = unknown> {
+    onInit?(ctx: TContext): void;
+    onNewPlayer?(ctx: TContext): void;
+    onTick?(ctx: TContext, dt: number): void;
+}
+export interface GameDefinition<TAssetRef extends ModelAssetRef = ModelAssetRef, TMultiplayer = unknown> {
+    name: string;
+    assets: AssetCatalog<TAssetRef>;
+    multiplayer: TMultiplayer;
+    scene: EntityStore;
+    world?: WorldFeature;
+    physics?: PhysicsConfig;
+    inventories?: Record<string, InventoryDeclaration>;
+    input?: ActionCodesMap;
+    server?: GameServerConfig;
+    save?: SaveConfig;
+    ui?: unknown;
+    loop?: GameLoop<any>;
+}
+export type GameDefinitionConfig<TAssetRef extends ModelAssetRef = ModelAssetRef, TMultiplayer = unknown> = Omit<GameDefinition<TAssetRef, TMultiplayer>, "scene">;
+export declare function defineGame<TAssetRef extends ModelAssetRef, TMultiplayer>(config: GameDefinitionConfig<TAssetRef, TMultiplayer>): GameDefinition<TAssetRef, TMultiplayer>;

package/dist/game/defineGame.js

@@ -0,0 +1,7 @@
+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() };
+}

package/dist/game/events.d.ts

@@ -0,0 +1,87 @@
+export type DeathReason = {
+    kind: "player_kill";
+    killerUserId: string;
+    via?: {
+        item?: string;
+    };
+} | {
+    kind: "environment";
+    source: string;
+} | {
+    kind: "self";
+    source: string;
+};
+export interface EntityDiedEvent {
+    instanceId: string;
+    catalogId: string;
+    userId?: string;
+    displayName?: string;
+    reason: DeathReason;
+    position: [number, number, number];
+    serverId?: string;
+}
+export interface LootGrantedEvent {
+    userId: string;
+    drops: {
+        item?: string;
+        currency?: string;
+        count: number;
+    }[];
+    source?: string;
+}
+export interface InventoryAddedEvent {
+    userId: string;
+    item: string;
+    count: number;
+    source?: string;
+}
+export interface QuestAcceptedEvent {
+    userId: string;
+    questId: string;
+}
+export interface QuestUpdatedEvent {
+    userId: string;
+    questId: string;
+    objectiveId?: string;
+    progress?: number;
+}
+export interface QuestCompletedEvent {
+    userId: string;
+    questId: string;
+}
+export interface SocialFriendAddedEvent {
+    userId: string;
+    friendUserId: string;
+}
+export interface SocialPartyJoinedEvent {
+    userId: string;
+    partyId: string;
+}
+export interface SocialPartyLeftEvent {
+    userId: string;
+    partyId: string;
+}
+export interface StatLevelUpEvent {
+    userId: string;
+    stat: string;
+    level: number;
+}
+export interface GameEventMap {
+    "entity.died": EntityDiedEvent;
+    "loot.granted": LootGrantedEvent;
+    "inventory.added": InventoryAddedEvent;
+    "quest.accepted": QuestAcceptedEvent;
+    "quest.updated": QuestUpdatedEvent;
+    "quest.completed": QuestCompletedEvent;
+    "social.friend.added": SocialFriendAddedEvent;
+    "social.party.joined": SocialPartyJoinedEvent;
+    "social.party.left": SocialPartyLeftEvent;
+    "stat.levelUp": StatLevelUpEvent;
+}
+export type GameEventHandler<TPayload> = (payload: TPayload) => void;
+export interface GameEvents<TMap extends GameEventMap = GameEventMap> {
+    on<TName extends keyof TMap>(name: TName, handler: GameEventHandler<TMap[TName]>): () => void;
+    subscribe<TName extends keyof TMap>(name: TName, handler: GameEventHandler<TMap[TName]>): () => void;
+    emit<TName extends keyof TMap>(name: TName, payload: TMap[TName]): void;
+}
+export declare function createGameEvents<TMap extends GameEventMap = GameEventMap>(): GameEvents<TMap>;

package/dist/game/events.js

@@ -0,0 +1,24 @@
+export function createGameEvents() {
+    const listeners = new Map();
+    function on(name, handler) {
+        let set = listeners.get(name);
+        if (!set) {
+            set = new Set();
+            listeners.set(name, set);
+        }
+        const entry = handler;
+        set.add(entry);
+        return () => set.delete(entry);
+    }
+    return {
+        on,
+        subscribe: on,
+        emit(name, payload) {
+            const set = listeners.get(name);
+            if (!set)
+                return;
+            for (const handler of set)
+                handler(payload);
+        },
+    };
+}

package/dist/game/feed.d.ts

@@ -0,0 +1,19 @@
+import type { GameEventMap, GameEvents } from "./events.js";
+export interface FeedEntry<T = unknown> {
+    at: number;
+    data: T;
+}
+export interface GameFeedOptions {
+    limit?: number;
+}
+export interface GameFeed {
+    bind<TName extends keyof GameEventMap>(action: TName, events: GameEvents): () => void;
+    push(action: string, entry: unknown): void;
+    recent(action: string, options?: {
+        limit?: number;
+    }): FeedEntry[];
+    subscribe(action: string, listener: (entry: FeedEntry) => void): () => void;
+    snapshot(): Record<string, FeedEntry[]>;
+    hydrate(data: Record<string, FeedEntry[]>): void;
+}
+export declare function createGameFeed(options?: GameFeedOptions): GameFeed;

package/dist/game/feed.js

@@ -0,0 +1,47 @@
+export function createGameFeed(options) {
+    const limit = options?.limit ?? 20;
+    const buffers = new Map();
+    const listeners = new Map();
+    function append(action, entry) {
+        const buffer = buffers.get(action) ?? [];
+        buffer.push(entry);
+        if (buffer.length > limit)
+            buffer.splice(0, buffer.length - limit);
+        buffers.set(action, buffer);
+        for (const listener of listeners.get(action) ?? [])
+            listener(entry);
+    }
+    return {
+        bind(action, events) {
+            return events.on(action, (payload) => append(action, { at: Date.now(), data: payload }));
+        },
+        push(action, data) {
+            append(action, { at: Date.now(), data });
+        },
+        recent(action, opts) {
+            const buffer = buffers.get(action) ?? [];
+            const count = opts?.limit ?? buffer.length;
+            return buffer.slice(Math.max(0, buffer.length - count));
+        },
+        subscribe(action, listener) {
+            let set = listeners.get(action);
+            if (!set) {
+                set = new Set();
+                listeners.set(action, set);
+            }
+            set.add(listener);
+            return () => set.delete(listener);
+        },
+        snapshot() {
+            const out = {};
+            for (const [action, buffer] of buffers)
+                out[action] = buffer.slice();
+            return out;
+        },
+        hydrate(data) {
+            buffers.clear();
+            for (const [action, buffer] of Object.entries(data))
+                buffers.set(action, buffer.slice(-limit));
+        },
+    };
+}

package/dist/game/leaderboard.d.ts

@@ -0,0 +1,46 @@
+export type LeaderboardScope = "global" | "server" | "profile";
+export interface LeaderboardTrackDef {
+    stat?: string;
+    currency?: string;
+    scope: LeaderboardScope;
+}
+export interface LeaderboardRow {
+    stat: string;
+    scope: LeaderboardScope;
+    serverId?: string;
+    userId: string;
+    value: number;
+}
+export type IncrementResult = {
+    status: "ok";
+    value: number;
+} | {
+    status: "rejected";
+    reason: "not-tracked";
+};
+export interface Leaderboard {
+    track(def: LeaderboardTrackDef): void;
+    tracked(): {
+        stat: string;
+        scope: LeaderboardScope;
+    }[];
+    increment(userId: string, stat: string, options: {
+        scope: LeaderboardScope;
+        serverId?: string;
+        by?: number;
+    }): IncrementResult;
+    getTop(stat: string, options: {
+        scope: LeaderboardScope;
+        limit?: number;
+        serverId?: string;
+    }): {
+        userId: string;
+        value: number;
+    }[];
+    getProfile(userId: string): Record<string, number>;
+    snapshot(): LeaderboardRow[];
+    hydrate(rows: LeaderboardRow[]): void;
+}
+export declare function createLeaderboard(sink?: {
+    onIncrement?(row: LeaderboardRow): void;
+}): Leaderboard;

package/dist/game/leaderboard.js

@@ -0,0 +1,60 @@
+function resolveStatId(def) {
+    const stat = def.stat ?? def.currency;
+    if (stat === undefined) {
+        throw new Error("leaderboard track requires stat or currency");
+    }
+    return stat;
+}
+function trackKey(stat, scope) {
+    return `${scope}:${stat}`;
+}
+function rowKey(stat, scope, serverId, userId) {
+    return `${scope}:${stat}:${serverId ?? ""}:${userId}`;
+}
+export function createLeaderboard(sink) {
+    const trackedPairs = new Map();
+    const rows = new Map();
+    return {
+        track(def) {
+            const stat = resolveStatId(def);
+            trackedPairs.set(trackKey(stat, def.scope), { stat, scope: def.scope });
+        },
+        tracked() {
+            return Array.from(trackedPairs.values());
+        },
+        increment(userId, stat, options) {
+            if (!trackedPairs.has(trackKey(stat, options.scope))) {
+                return { status: "rejected", reason: "not-tracked" };
+            }
+            const key = rowKey(stat, options.scope, options.serverId, userId);
+            const value = (rows.get(key)?.value ?? 0) + (options.by ?? 1);
+            const row = { stat, scope: options.scope, serverId: options.serverId, userId, value };
+            rows.set(key, row);
+            sink?.onIncrement?.(row);
+            return { status: "ok", value };
+        },
+        getTop(stat, options) {
+            return Array.from(rows.values())
+                .filter((row) => row.stat === stat && row.scope === options.scope && row.serverId === options.serverId)
+                .sort((a, b) => b.value - a.value)
+                .slice(0, options.limit ?? 10)
+                .map((row) => ({ userId: row.userId, value: row.value }));
+        },
+        getProfile(userId) {
+            const profile = {};
+            for (const row of rows.values()) {
+                if (row.userId === userId && row.scope === "profile")
+                    profile[row.stat] = row.value;
+            }
+            return profile;
+        },
+        snapshot() {
+            return Array.from(rows.values());
+        },
+        hydrate(data) {
+            rows.clear();
+            for (const row of data)
+                rows.set(rowKey(row.stat, row.scope, row.serverId, row.userId), row);
+        },
+    };
+}

package/dist/game/loadout.d.ts

@@ -0,0 +1,47 @@
+export interface LoadoutItemEntry {
+    item: string;
+    count: number;
+    slot?: number;
+}
+export interface LoadoutDef {
+    inventories?: Record<string, LoadoutItemEntry[]>;
+    stats?: Record<string, {
+        current: number;
+        max?: number;
+        min?: number;
+    }>;
+    economy?: Record<string, number>;
+    unlocks?: string[];
+}
+export interface LoadoutInventoryTransaction {
+    put(inventoryId: string, itemId: string, count: number, slot?: number): {
+        reason: string;
+    } | null;
+    commit(): void;
+}
+export interface LoadoutDeps {
+    inventory: {
+        begin(userId: string): LoadoutInventoryTransaction;
+    };
+    stats: {
+        seed(userId: string, statId: string, pool: {
+            current: number;
+            max?: number;
+            min?: number;
+        }): void;
+    };
+    economy: {
+        grant(userId: string, currencyId: string, amount: number): void;
+    };
+    unlocks: {
+        grant(userId: string, unlockId: string): void;
+    };
+}
+export interface Loadouts {
+    register(defs: Record<string, LoadoutDef>): void;
+    has(loadoutId: string): boolean;
+    applyLoadout(userId: string, loadoutId: string): {
+        reason: string;
+    } | null;
+}
+export declare function createLoadouts(deps: LoadoutDeps): Loadouts;

package/dist/game/loadout.js

@@ -0,0 +1,36 @@
+export function createLoadouts(deps) {
+    const definitions = new Map();
+    return {
+        register(defs) {
+            for (const [loadoutId, def] of Object.entries(defs))
+                definitions.set(loadoutId, def);
+        },
+        has(loadoutId) {
+            return definitions.has(loadoutId);
+        },
+        applyLoadout(userId, loadoutId) {
+            const def = definitions.get(loadoutId);
+            if (def === undefined)
+                return { reason: `unknown loadout "${loadoutId}"` };
+            const transaction = deps.inventory.begin(userId);
+            for (const [inventoryId, entries] of Object.entries(def.inventories ?? {})) {
+                for (const entry of entries) {
+                    const rejection = transaction.put(inventoryId, entry.item, entry.count, entry.slot);
+                    if (rejection !== null)
+                        return { reason: `${inventoryId}: ${rejection.reason}` };
+                }
+            }
+            transaction.commit();
+            for (const [statId, pool] of Object.entries(def.stats ?? {})) {
+                deps.stats.seed(userId, statId, pool);
+            }
+            for (const [currencyId, amount] of Object.entries(def.economy ?? {})) {
+                deps.economy.grant(userId, currencyId, amount);
+            }
+            for (const unlockId of def.unlocks ?? []) {
+                deps.unlocks.grant(userId, unlockId);
+            }
+            return null;
+        },
+    };
+}

package/dist/game/lootTable.d.ts

@@ -0,0 +1,27 @@
+export interface LootEntry {
+    item?: string;
+    currency?: string;
+    count: number | [number, number];
+    weight: number;
+}
+export interface LootTableDef {
+    id: string;
+    rolls?: number;
+    entries: LootEntry[];
+}
+export interface Drop {
+    item?: string;
+    currency?: string;
+    count: number;
+}
+export interface LootRegistry {
+    register(def: LootTableDef): void;
+    has(id: string): boolean;
+    roll(id: string, rng?: () => number): Drop[];
+}
+export declare function createLootRegistry(): LootRegistry;
+export declare function lootTable(def: LootTableDef): LootTableDef;
+export declare function grantDrops(drops: Drop[], appliers: {
+    putItem: (itemId: string, count: number) => unknown;
+    grantCurrency: (currencyId: string, amount: number) => unknown;
+}): void;

package/dist/game/lootTable.js

@@ -0,0 +1,78 @@
+function assertValidEntry(entry) {
+    const hasItem = entry.item !== undefined;
+    const hasCurrency = entry.currency !== undefined;
+    if (hasItem === hasCurrency) {
+        throw new Error("loot entry must have exactly one of item or currency");
+    }
+    if (!(entry.weight > 0)) {
+        throw new Error(`loot entry weight must be positive, got ${entry.weight}`);
+    }
+}
+function assertValidDef(def) {
+    if (def.entries.length === 0) {
+        throw new Error(`loot table "${def.id}" must have at least one entry`);
+    }
+    for (const entry of def.entries)
+        assertValidEntry(entry);
+}
+function resolveCount(count, rng) {
+    if (typeof count === "number")
+        return count;
+    const [min, max] = count;
+    return min + Math.floor(rng() * (max - min + 1));
+}
+function pickEntry(entries, rng) {
+    const total = entries.reduce((sum, entry) => sum + entry.weight, 0);
+    let roll = rng() * total;
+    for (const entry of entries) {
+        roll -= entry.weight;
+        if (roll < 0)
+            return entry;
+    }
+    return entries[entries.length - 1];
+}
+function rollEntry(entry, rng) {
+    const count = resolveCount(entry.count, rng);
+    return entry.item !== undefined ? { item: entry.item, count } : { currency: entry.currency, count };
+}
+export function createLootRegistry() {
+    const tables = new Map();
+    return {
+        register(def) {
+            assertValidDef(def);
+            if (tables.has(def.id)) {
+                throw new Error(`loot table "${def.id}" is already registered`);
+            }
+            tables.set(def.id, def);
+        },
+        has(id) {
+            return tables.has(id);
+        },
+        roll(id, rng = Math.random) {
+            const table = tables.get(id);
+            if (!table) {
+                throw new Error(`unknown loot table: ${id}`);
+            }
+            const rolls = table.rolls ?? 1;
+            const drops = [];
+            for (let i = 0; i < rolls; i++) {
+                drops.push(rollEntry(pickEntry(table.entries, rng), rng));
+            }
+            return drops;
+        },
+    };
+}
+export function lootTable(def) {
+    assertValidDef(def);
+    return def;
+}
+export function grantDrops(drops, appliers) {
+    for (const drop of drops) {
+        if (drop.item !== undefined) {
+            appliers.putItem(drop.item, drop.count);
+        }
+        else if (drop.currency !== undefined) {
+            appliers.grantCurrency(drop.currency, drop.count);
+        }
+    }
+}