@jgengine/core 0.10.0 → 0.12.0

package/dist/game/systemSchedule.js

@@ -0,0 +1,242 @@
+/** Default fixed-sim stage order — systems pick a stage; most need only this. */
+export const DEFAULT_FIXED_STAGES = [
+    "input",
+    "movement",
+    "combat",
+    "ai",
+    "activities",
+    "cleanup",
+];
+/**
+ * Default frame stage order. Gameplay stages mirror the fixed table so once-per-frame systems
+ * (`type: "frame"`) can pick `combat`/`ai`/… without falling into the unknown-stage bucket;
+ * presentation stages follow.
+ */
+export const DEFAULT_FRAME_STAGES = [
+    "input",
+    "movement",
+    "combat",
+    "ai",
+    "activities",
+    "cleanup",
+    "animation",
+    "camera",
+    "effects",
+];
+const DEFAULT_FIXED_RATE = 60;
+function asList(value) {
+    if (value === undefined)
+        return [];
+    return typeof value === "string" ? [value] : value;
+}
+function channelOf(tick) {
+    if (tick === undefined)
+        return "event";
+    return tick.type;
+}
+function stageOf(tick, channel) {
+    if (tick === undefined || tick.type === "manual")
+        return "";
+    if (tick.type === "fixed" || tick.type === "frame" || tick.type === "interval") {
+        return tick.stage ?? defaultStage(channel);
+    }
+    return "";
+}
+function defaultStage(channel) {
+    if (channel === "fixed")
+        return "combat";
+    if (channel === "frame")
+        return "effects";
+    if (channel === "interval")
+        return "activities";
+    return "";
+}
+function rateOf(tick, defaultFixedRate) {
+    if (tick?.type === "fixed")
+        return tick.rate ?? defaultFixedRate;
+    return undefined;
+}
+function everyOf(tick) {
+    if (tick?.type === "interval")
+        return tick.every;
+    return undefined;
+}
+function afterOf(tick) {
+    if (tick === undefined || tick.type === "manual")
+        return [];
+    if (tick.type === "fixed" || tick.type === "frame" || tick.type === "interval") {
+        return asList(tick.after);
+    }
+    return [];
+}
+function beforeOf(tick) {
+    if (tick === undefined || tick.type === "manual")
+        return [];
+    if (tick.type === "fixed" || tick.type === "frame" || tick.type === "interval") {
+        return asList(tick.before);
+    }
+    return [];
+}
+/**
+ * Topological sort with a stable tie-break on original declaration index, then id.
+ * Edges: `after: "x"` means this runs after x (x → this); `before: "y"` means this → y.
+ * @internal
+ */
+export function orderWithConstraints(ids, after, before, indexOf) {
+    const idSet = new Set(ids);
+    const preds = new Map();
+    const succs = new Map();
+    for (const id of ids) {
+        preds.set(id, new Set());
+        succs.set(id, new Set());
+    }
+    const addEdge = (from, to) => {
+        if (!idSet.has(from) || !idSet.has(to) || from === to)
+            return;
+        succs.get(from).add(to);
+        preds.get(to).add(from);
+    };
+    for (const id of ids) {
+        for (const a of after.get(id) ?? [])
+            addEdge(a, id);
+        for (const b of before.get(id) ?? [])
+            addEdge(id, b);
+    }
+    const ready = ids
+        .filter((id) => preds.get(id).size === 0)
+        .sort((a, b) => {
+        const ia = indexOf.get(a) ?? 0;
+        const ib = indexOf.get(b) ?? 0;
+        if (ia !== ib)
+            return ia - ib;
+        return a < b ? -1 : a > b ? 1 : 0;
+    });
+    const ordered = [];
+    while (ready.length > 0) {
+        const next = ready.shift();
+        ordered.push(next);
+        for (const succ of succs.get(next) ?? []) {
+            const set = preds.get(succ);
+            set.delete(next);
+            if (set.size === 0) {
+                ready.push(succ);
+                ready.sort((a, b) => {
+                    const ia = indexOf.get(a) ?? 0;
+                    const ib = indexOf.get(b) ?? 0;
+                    if (ia !== ib)
+                        return ia - ib;
+                    return a < b ? -1 : a > b ? 1 : 0;
+                });
+            }
+        }
+    }
+    if (ordered.length !== ids.length) {
+        const leftover = ids.filter((id) => !ordered.includes(id));
+        throw new Error(`system schedule: cyclic before/after constraints among: ${leftover.join(", ")}`);
+    }
+    return ordered;
+}
+function bucketByStage(items, stageOrder, indexOf) {
+    const stageIndex = new Map();
+    stageOrder.forEach((s, i) => stageIndex.set(s, i));
+    const unknownStages = new Set();
+    for (const item of items) {
+        if (item.stage !== "" && !stageIndex.has(item.stage))
+            unknownStages.add(item.stage);
+    }
+    const stages = [...stageOrder, ...[...unknownStages].sort()];
+    const buckets = [];
+    for (const stage of stages) {
+        const inStage = items.filter((s) => s.stage === stage);
+        if (inStage.length === 0)
+            continue;
+        const after = new Map();
+        const before = new Map();
+        for (const s of inStage) {
+            after.set(s.id, s.after);
+            before.set(s.id, s.before);
+        }
+        const order = orderWithConstraints(inStage.map((s) => s.id), after, before, indexOf);
+        buckets.push({ stage, systems: order });
+    }
+    return buckets;
+}
+/**
+ * Compile system definitions into a deterministic schedule.
+ * Validates unique ids, `dependsOn`, and before/after cycles.
+ *
+ * @capability system-schedule compile fixed/frame/interval system ticks into deterministic ordered stages
+ */
+export function compileSystemSchedule(systems, options) {
+    const fixedStages = options?.fixedStages ?? DEFAULT_FIXED_STAGES;
+    const frameStages = options?.frameStages ?? DEFAULT_FRAME_STAGES;
+    const defaultFixedRate = options?.defaultFixedRate ?? DEFAULT_FIXED_RATE;
+    const systemsById = new Map();
+    const indexOf = new Map();
+    systems.forEach((system, index) => {
+        if (systemsById.has(system.id)) {
+            throw new Error(`system schedule: duplicate system id "${system.id}"`);
+        }
+        systemsById.set(system.id, system);
+        indexOf.set(system.id, index);
+    });
+    for (const system of systems) {
+        for (const dep of system.dependsOn ?? []) {
+            if (!systemsById.has(dep)) {
+                throw new Error(`system schedule: "${system.id}" dependsOn unknown system "${dep}"`);
+            }
+        }
+    }
+    const scheduled = systems.map((system) => {
+        const channel = channelOf(system.tick);
+        return {
+            id: system.id,
+            channel,
+            stage: stageOf(system.tick, channel),
+            rate: rateOf(system.tick, defaultFixedRate),
+            every: everyOf(system.tick),
+            after: afterOf(system.tick),
+            before: beforeOf(system.tick),
+            dependsOn: system.dependsOn ?? [],
+        };
+    });
+    const fixedItems = scheduled.filter((s) => s.channel === "fixed");
+    const rates = [...new Set(fixedItems.map((s) => s.rate ?? defaultFixedRate))].sort((a, b) => b - a);
+    const fixed = rates.map((rate) => {
+        const group = fixedItems.filter((s) => (s.rate ?? defaultFixedRate) === rate);
+        const stages = bucketByStage(group, fixedStages, indexOf);
+        return {
+            rate,
+            stages,
+            order: stages.flatMap((b) => b.systems),
+        };
+    });
+    const frameItems = scheduled.filter((s) => s.channel === "frame");
+    const frame = bucketByStage(frameItems, frameStages, indexOf);
+    const frameOrder = frame.flatMap((b) => b.systems);
+    const intervals = scheduled.filter((s) => s.channel === "interval");
+    // Stable order for intervals: stage buckets then constraints across all interval systems
+    const intervalBuckets = bucketByStage(intervals, fixedStages, indexOf);
+    const intervalOrder = intervalBuckets.flatMap((b) => b.systems);
+    const intervalsOrdered = intervalOrder.map((id) => intervals.find((s) => s.id === id));
+    const manual = scheduled.filter((s) => s.channel === "manual").map((s) => s.id);
+    const eventOnly = scheduled
+        .filter((s) => s.channel === "event")
+        .map((s) => s.id);
+    const tickOrder = [
+        ...fixed.flatMap((g) => g.order),
+        ...frameOrder,
+        ...intervalOrder,
+    ];
+    return {
+        systemsById,
+        scheduled,
+        fixed,
+        frame,
+        frameOrder,
+        intervals: intervalsOrdered,
+        manual,
+        eventOnly,
+        tickOrder,
+    };
+}

package/dist/game/toasts.d.ts

@@ -0,0 +1,43 @@
+/** A transient HUD message that expires on its own — banner, pickup note, alert. */
+export interface Toast<T = string> {
+    /** Stable id for keying in a UI list. */
+    id: string;
+    /** Message payload (a string, or any structured content the HUD renders). */
+    body: T;
+    /** Wall-clock time (seconds) after which the toast should be dropped. */
+    expiresAt: number;
+}
+/**
+ * Append `toast`, keeping only the newest `cap` entries.
+ *
+ * @capability toast-feed queue of transient self-expiring on-screen messages (toasts, announcer, kill-feed)
+ */
+export declare function appendToast<T>(toasts: readonly Toast<T>[], toast: Toast<T>, cap: number): readonly Toast<T>[];
+/** Drop every toast whose `expiresAt` is at or before `now`. Returns the same array when nothing expired. */
+export declare function pruneToasts<T>(toasts: readonly Toast<T>[], now: number): readonly Toast<T>[];
+/** Stateful transient-toast list with a size cap and time-to-live eviction. */
+export interface ToastQueue<T = string> {
+    /** Raise a toast at `now` living `ttlSeconds` (falling back to the queue default); returns it. */
+    push(body: T, now: number, ttlSeconds?: number): Toast<T>;
+    /** Evict toasts that have expired as of `now`. */
+    prune(now: number): void;
+    /** Current live toasts, oldest first. */
+    list(): readonly Toast<T>[];
+    /** Remove all toasts. */
+    clear(): void;
+}
+/** Options for {@link createToastQueue}. */
+export interface ToastQueueOptions {
+    /** Maximum toasts retained; older ones fall off. Defaults to 4. */
+    cap?: number;
+    /** Default lifetime in seconds when `push` is not given one. Defaults to 3. */
+    ttlSeconds?: number;
+}
+/**
+ * A capped, self-expiring toast queue — the append-with-limit plus TTL-prune list every HUD hand-rolled
+ * on top of a plain array. Feed it game time: `push` raises a message, `prune(now)` drops expired ones,
+ * `list()` is what the HUD renders. Unlike the append-only event feed, toasts evict themselves.
+ *
+ * @capability toast-feed queue of transient self-expiring on-screen messages (toasts, announcer, kill-feed)
+ */
+export declare function createToastQueue<T = string>(options?: ToastQueueOptions): ToastQueue<T>;

package/dist/game/toasts.js

@@ -0,0 +1,44 @@
+/**
+ * Append `toast`, keeping only the newest `cap` entries.
+ *
+ * @capability toast-feed queue of transient self-expiring on-screen messages (toasts, announcer, kill-feed)
+ */
+export function appendToast(toasts, toast, cap) {
+    const next = [...toasts, toast];
+    return cap > 0 && next.length > cap ? next.slice(next.length - cap) : next;
+}
+/** Drop every toast whose `expiresAt` is at or before `now`. Returns the same array when nothing expired. */
+export function pruneToasts(toasts, now) {
+    const kept = toasts.filter((toast) => toast.expiresAt > now);
+    return kept.length === toasts.length ? toasts : kept;
+}
+/**
+ * A capped, self-expiring toast queue — the append-with-limit plus TTL-prune list every HUD hand-rolled
+ * on top of a plain array. Feed it game time: `push` raises a message, `prune(now)` drops expired ones,
+ * `list()` is what the HUD renders. Unlike the append-only event feed, toasts evict themselves.
+ *
+ * @capability toast-feed queue of transient self-expiring on-screen messages (toasts, announcer, kill-feed)
+ */
+export function createToastQueue(options = {}) {
+    const cap = options.cap ?? 4;
+    const defaultTtl = options.ttlSeconds ?? 3;
+    let toasts = [];
+    let counter = 0;
+    return {
+        push(body, now, ttlSeconds) {
+            const toast = { id: `toast-${counter}`, body, expiresAt: now + (ttlSeconds ?? defaultTtl) };
+            counter += 1;
+            toasts = appendToast(toasts, toast, cap);
+            return toast;
+        },
+        prune(now) {
+            toasts = pruneToasts(toasts, now);
+        },
+        list() {
+            return toasts;
+        },
+        clear() {
+            toasts = [];
+        },
+    };
+}

package/dist/game/trade.d.ts

@@ -32,6 +32,7 @@ export interface TradeSystem {
     sell(itemId: string, count: number | undefined, party: TradeParty): TradeRejection | null;
     tradableAt(shopId: string, allItemIds: string[]): string[];
 }
+/** @internal */
 export declare function canAffordCosts(balances: Record<string, number>, costs: Record<string, number>): string | null;
 export interface TradeOutcome {
     itemId: string;
@@ -45,8 +46,11 @@ export type TradeResolution = {
     status: "rejected";
     reason: string;
 };
+/** @internal */
 export declare function resolveBuy(itemId: string, trade: TradeField | null | undefined, shopId: string, count: number, balances: Record<string, number>): TradeResolution;
+/** @internal */
 export declare function resolveSell(itemId: string, trade: TradeField | null | undefined, count: number): TradeResolution;
+/** @internal */
 export declare function applyTradeOutcome(outcome: TradeOutcome, appliers: {
     adjustItem(itemId: string, count: number): {
         reason: string;
@@ -55,4 +59,10 @@ export declare function applyTradeOutcome(outcome: TradeOutcome, appliers: {
 }): {
     reason: string;
 } | null;
+/**
+ * Buy and sell goods against player currency balances, resolving affordability and price.
+ *
+ * @capability shop-trade buy and sell goods against player currency balances
+  * @internal
+  */
 export declare function createTradeSystem(deps: TradeSystemDeps): TradeSystem;

package/dist/game/trade.js

@@ -10,6 +10,7 @@ function negate(amounts) {
         out[currency] = -amount;
     return out;
 }
+/** @internal */
 export function canAffordCosts(balances, costs) {
     for (const [currency, amount] of Object.entries(costs)) {
         if ((balances[currency] ?? 0) < amount)
@@ -27,6 +28,7 @@ function buyEligibility(trade, shopId) {
 function sellEligibility(trade) {
     return trade?.sell ? null : "not-sellable";
 }
+/** @internal */
 export function resolveBuy(itemId, trade, shopId, count, balances) {
     const ineligible = buyEligibility(trade, shopId);
     if (ineligible)
@@ -37,12 +39,14 @@ export function resolveBuy(itemId, trade, shopId, count, balances) {
         return { status: "rejected", reason: unaffordable };
     return { status: "ok", outcome: { itemId, count, currency: negate(costs) } };
 }
+/** @internal */
 export function resolveSell(itemId, trade, count) {
     const ineligible = sellEligibility(trade);
     if (ineligible)
         return { status: "rejected", reason: ineligible };
     return { status: "ok", outcome: { itemId, count: -count, currency: scale(trade.sell, count) } };
 }
+/** @internal */
 export function applyTradeOutcome(outcome, appliers) {
     const itemResult = appliers.adjustItem(outcome.itemId, outcome.count);
     if (itemResult)
@@ -50,6 +54,12 @@ export function applyTradeOutcome(outcome, appliers) {
     appliers.adjustCurrency(outcome.currency);
     return null;
 }
+/**
+ * Buy and sell goods against player currency balances, resolving affordability and price.
+ *
+ * @capability shop-trade buy and sell goods against player currency balances
+  * @internal
+  */
 export function createTradeSystem(deps) {
     const { resolveTrade, wallet, inventory } = deps;
     function canBuy(itemId, shopId, count = 1) {

package/dist/game/tribe.d.ts

@@ -0,0 +1,184 @@
+import type { FactionRelation } from "../faction/factions.js";
+/**
+ * A rank within a group's hierarchy. Higher `level` means more authority: a member can only
+ * manage (kick, re-rank) members strictly below their own level, and cannot promote anyone to a
+ * level at or above their own. `permissions` are opaque, genre-agnostic capability slugs the game
+ * checks with {@link Tribe.can} (e.g. `"build"`, `"demolish"`, `"invite"`, `"kick"`, `"manage-ranks"`,
+ * plus the {@link AssetAction} slugs `"inventory"`, `"use"`, `"command"` for group-owned assets).
+ * A `bypass` rank (an admin) skips every permission check, exactly like the founder.
+ */
+export interface TribeRankDef {
+    id: string;
+    name: string;
+    /** Higher = more authority. Determines who can manage/promote whom. */
+    level: number;
+    /** Capability slugs this rank grants; checked by {@link Tribe.can} and {@link Tribe.canAccess}. */
+    permissions?: readonly string[];
+    /** Admin rank — bypasses all permission and hierarchy checks (like the founder). */
+    bypass?: boolean;
+}
+/** Per-asset action gated by rank on group-owned assets. */
+export type AssetAction = "inventory" | "use" | "command";
+/** Opaque reference to a shared thing (structure, creature, container) by kind + id. */
+export interface AssetRef {
+    kind: string;
+    id: string;
+}
+/** Who inside the group owns an asset: the group as a whole, or a specific member personally. */
+export type AssetOwnership = {
+    scope: "group";
+} | {
+    scope: "personal";
+    memberId: string;
+};
+/** The kind of change recorded in a tribe's event log (membership, ownership, or alliance). */
+export type TribeEventType = "member-added" | "member-removed" | "member-left" | "rank-changed" | "founder-transferred" | "asset-registered" | "asset-unregistered" | "alliance-formed" | "alliance-broken";
+/** One entry in a tribe's bounded event log. Optional fields present only when meaningful. */
+export interface TribeEvent {
+    seq: number;
+    type: TribeEventType;
+    at: number;
+    /** Member who performed the action, when applicable. */
+    actor?: string;
+    /** Member the action targets (added/removed/re-ranked). */
+    subject?: string;
+    /** Other tribe id, for alliance events. */
+    tribeId?: string;
+    rankId?: string;
+    assetKind?: string;
+    assetId?: string;
+}
+/** A member of a tribe and the rank id that governs their permissions. */
+export interface TribeMemberRecord {
+    id: string;
+    rankId: string;
+    joinedAt: number;
+}
+/** An asset (structure/creature) owned within a tribe — group-shared or held by one member. */
+export interface TribeAssetRecord {
+    kind: string;
+    id: string;
+    /** `null` marks a group-owned asset; otherwise the member who owns it personally. */
+    ownerId: string | null;
+}
+/** Full serializable state of one tribe — the save/replication baseline. */
+export interface TribeSnapshot {
+    id: string;
+    founderId: string;
+    ranks: TribeRankDef[];
+    defaultRankId: string;
+    founderRankId: string;
+    logCap: number;
+    members: TribeMemberRecord[];
+    assets: TribeAssetRecord[];
+    allies: string[];
+    events: TribeEvent[];
+    eventSeq: number;
+}
+/** Construction options for {@link createTribe}: id, founder, rank ladder, and log cap. */
+export interface TribeConfig {
+    id: string;
+    founderId: string;
+    /** At least one rank. */
+    ranks: readonly TribeRankDef[];
+    /** Rank new members receive; defaults to the lowest-level rank. */
+    defaultRankId?: string;
+    /** Rank the founder holds; defaults to the highest-level rank. */
+    founderRankId?: string;
+    /** Max events retained in the ring buffer (default 128). */
+    logCap?: number;
+    /** Injected clock for deterministic timestamps; defaults to `Date.now`. */
+    now?: () => number;
+}
+/** Standard `{ reason }`-on-failure / `null`-on-success result for authorized mutations. */
+export type TribeResult = {
+    reason: string;
+} | null;
+/**
+ * A shared-ownership group — a tribe, guild, clan, or company — as one first-class aggregate.
+ * Unifies ranked membership, group-vs-personal asset ownership, mutual alliances, and a bounded
+ * event log that otherwise have to be hand-assembled from parties, factions, build permissions,
+ * and per-owner rosters.
+ */
+export interface Tribe {
+    readonly id: string;
+    founderId(): string;
+    hasMember(memberId: string): boolean;
+    memberIds(): readonly string[];
+    rankOf(memberId: string): TribeRankDef | null;
+    /** True if the member's rank grants `permission`, or they are the founder / an admin rank. */
+    can(memberId: string, permission: string): boolean;
+    /** Founder or a `bypass` rank — skips every permission check. */
+    isAdmin(memberId: string): boolean;
+    addMember(actorId: string, memberId: string, rankId?: string): TribeResult;
+    removeMember(actorId: string, memberId: string): TribeResult;
+    leave(memberId: string): TribeResult;
+    setMemberRank(actorId: string, memberId: string, rankId: string): TribeResult;
+    transferFounder(actorId: string, memberId: string): TribeResult;
+    registerAsset(actorId: string, ref: AssetRef, ownership: AssetOwnership): TribeResult;
+    unregisterAsset(actorId: string, ref: AssetRef): TribeResult;
+    ownerOfAsset(ref: AssetRef): AssetOwnership | null;
+    /** Personal assets a member holds inside this group (they keep these on leaving). */
+    assetsOf(memberId: string): readonly AssetRef[];
+    /** Resolve access to an asset: rank permission for group assets, ownership for personal ones. */
+    canAccess(memberId: string, ref: AssetRef, action: AssetAction): boolean;
+    addAlly(tribeId: string): void;
+    removeAlly(tribeId: string): void;
+    isAllied(tribeId: string): boolean;
+    allyIds(): readonly string[];
+    /** `"friendly"` for self and allies, else `"neutral"` — never hostile by default. */
+    relationTo(tribeId: string): FactionRelation;
+    events(): readonly TribeEvent[];
+    snapshot(): TribeSnapshot;
+    hydrate(snapshot: TribeSnapshot): void;
+}
+/**
+ * Create a shared-ownership group aggregate (tribe / guild / clan / company). Members hold a
+ * {@link TribeRankDef rank} whose configurable permission slugs gate management actions and access
+ * to group-owned assets, while personally-owned assets stay with their member — and follow them out
+ * when they leave. Group↔group {@link Tribe.addAlly alliances} resolve allied tribes as friendly, and
+ * every membership / ownership / alliance change lands in a bounded ring-buffer {@link Tribe.events log}.
+ * All state is plain JSON via {@link Tribe.snapshot}/{@link Tribe.hydrate}; timestamps come from an
+ * injected clock for determinism. Compose many tribes with {@link createTribeRegistry} for mutual
+ * alliances and cross-member relation lookups.
+ *
+ * @capability tribe-group shared-ownership group (tribe/guild/clan) with ranked permissions, group vs personal assets, alliances, and a bounded event log
+ */
+export declare function createTribe(config: TribeConfig): Tribe;
+/** Injected dependencies for {@link createTribeRegistry} (e.g. a `now()` clock for event timestamps). */
+export interface TribeRegistryDeps {
+    now?: () => number;
+    defaultLogCap?: number;
+}
+/** Full serializable state of a tribe registry — every tribe's snapshot in one payload. */
+export interface TribeRegistrySnapshot {
+    tribes: TribeSnapshot[];
+}
+/**
+ * A collection of {@link Tribe tribes} with mutual alliance management and cross-member relation
+ * lookups. Alliances are kept symmetric here (both sides updated together), and member-to-member
+ * relations resolve through tribe membership + alliances, mirroring the `faction` graph vocabulary.
+ */
+export interface TribeRegistry {
+    create(config: TribeConfig): Tribe;
+    get(id: string): Tribe | null;
+    all(): readonly Tribe[];
+    remove(id: string): void;
+    /** Form a mutual alliance, updating and logging both tribes. */
+    formAlliance(tribeA: string, tribeB: string): TribeResult;
+    /** Break a mutual alliance on both sides. */
+    breakAlliance(tribeA: string, tribeB: string): void;
+    areAllied(tribeA: string, tribeB: string): boolean;
+    relationBetweenTribes(tribeA: string, tribeB: string): FactionRelation;
+    tribeOfMember(memberId: string): Tribe | null;
+    relationBetweenMembers(memberA: string, memberB: string): FactionRelation;
+    isFriendly(memberA: string, memberB: string): boolean;
+    snapshot(): TribeRegistrySnapshot;
+    hydrate(snapshot: TribeRegistrySnapshot): void;
+}
+/**
+ * Create a registry that owns many tribes, keeps alliances mutual, and resolves member relations.
+ *
+ * @capability tribe-registry registry of tribes with mutual alliances and cross-tribe relation lookup
+ */
+export declare function createTribeRegistry(deps?: TribeRegistryDeps): TribeRegistry;