@jgengine/core 0.6.0 → 0.8.0

package/dist/time/simClock.js

@@ -7,9 +7,12 @@ export function createSimClock(options = {}) {
     const configuredSpeeds = config.speeds === undefined ? [1, 2, 3, 4] : config.speeds.filter((value) => value > 0);
     const speeds = configuredSpeeds.length > 0 ? configuredSpeeds : [1];
     const dayLength = config.dayLength !== undefined && config.dayLength > 0 ? config.dayLength : SECONDS_PER_GAME_DAY;
+    const daysPerYear = config.daysPerYear !== undefined && config.daysPerYear > 0 ? config.daysPerYear : 365;
+    const seasons = config.seasons;
     let now = config.start !== undefined && config.start > 0 ? config.start : 0;
     let paused = config.startPaused ?? false;
     let playSpeed = speeds[0];
+    let timescale = 1;
     let nextTimerId = 0;
     const timers = new Map();
     let displayMinute = minuteIndex(now, dayLength);
@@ -17,14 +20,26 @@ export function createSimClock(options = {}) {
         const day = Math.floor(now / dayLength);
         const dayFraction = (now - day * dayLength) / dayLength;
         const secondOfDay = dayFraction * 24 * 3600;
-        return {
+        const year = Math.floor(day / daysPerYear);
+        const dayOfYear = day - year * daysPerYear;
+        const yearFraction = (dayOfYear + dayFraction) / daysPerYear;
+        const result = {
             totalSeconds: now,
             day,
             hour: Math.floor(secondOfDay / 3600) % 24,
             minute: Math.floor(secondOfDay / 60) % 60,
             second: Math.floor(secondOfDay) % 60,
             dayFraction,
+            year,
+            dayOfYear,
+            yearFraction,
         };
+        if (seasons !== undefined && seasons.length > 0) {
+            const segmentLength = daysPerYear / seasons.length;
+            const index = Math.min(seasons.length - 1, Math.floor(dayOfYear / segmentLength));
+            result.season = seasons[index];
+        }
+        return result;
     }
     function fireDueTimers() {
         let fires = 0;
@@ -52,9 +67,9 @@ export function createSimClock(options = {}) {
         }
     }
     function advance(realDt) {
-        if (paused || realDt <= 0)
+        if (paused || realDt <= 0 || timescale === 0)
             return 0;
-        const gameDt = realDt * scale * playSpeed;
+        const gameDt = realDt * scale * playSpeed * timescale;
         now += gameDt;
         fireDueTimers();
         const minute = minuteIndex(now, dayLength);
@@ -91,6 +106,13 @@ export function createSimClock(options = {}) {
         const index = speeds.indexOf(playSpeed);
         setSpeed(speeds[(index + 1) % speeds.length]);
     }
+    function setTimescale(multiplier) {
+        const next = Number.isFinite(multiplier) && multiplier > 0 ? multiplier : 0;
+        if (next === timescale)
+            return;
+        timescale = next;
+        onChange();
+    }
     function register(due, interval, callback) {
         const id = nextTimerId;
         nextTimerId += 1;
@@ -108,6 +130,7 @@ export function createSimClock(options = {}) {
             paused,
             speed: paused ? 0 : playSpeed,
             playSpeed,
+            timescale,
             scale,
             speeds,
             calendar: calendar(),
@@ -119,6 +142,8 @@ export function createSimClock(options = {}) {
         toggle: () => (paused ? play() : pause()),
         setSpeed,
         cycleSpeed,
+        timescale: () => timescale,
+        setTimescale,
         after: (seconds, callback) => register(now + Math.max(0, seconds), null, callback),
         every: (seconds, callback) => {
             const interval = Math.max(Number.EPSILON, seconds);

package/dist/turn/commit.d.ts

@@ -0,0 +1,27 @@
+export type CommitMode = "immediate" | "simultaneous" | "rewind";
+export interface SubmittedAction<TAction> {
+    participant: string;
+    action: TAction;
+}
+export interface CommitOutcome<TAction> {
+    status: "committed" | "sealed" | "pending" | "rejected";
+    committed: SubmittedAction<TAction>[];
+    reason?: string;
+}
+export interface CommitControllerConfig {
+    mode: CommitMode;
+    participants?: readonly string[];
+}
+export interface CommitController<TAction> {
+    readonly mode: CommitMode;
+    submit(participant: string, action: TAction): CommitOutcome<TAction>;
+    expected(participants: readonly string[]): void;
+    hasSubmitted(participant: string): boolean;
+    allReady(): boolean;
+    pending(): SubmittedAction<TAction>[];
+    reveal(): SubmittedAction<TAction>[];
+    commit(): SubmittedAction<TAction>[];
+    rewind(): SubmittedAction<TAction>[];
+    clear(): void;
+}
+export declare function createCommitController<TAction>(config: CommitControllerConfig): CommitController<TAction>;

package/dist/turn/commit.js

@@ -0,0 +1,72 @@
+export function createCommitController(config) {
+    const mode = config.mode;
+    let expected = config.participants === undefined ? null : [...config.participants];
+    let sealed = new Map();
+    let revealed = false;
+    function orderedSubmissions() {
+        const source = expected ?? [...sealed.keys()];
+        const result = [];
+        for (const participant of source) {
+            if (sealed.has(participant))
+                result.push({ participant, action: sealed.get(participant) });
+        }
+        for (const [participant, action] of sealed) {
+            if (expected !== null && !expected.includes(participant))
+                result.push({ participant, action });
+        }
+        return result;
+    }
+    function allReady() {
+        if (expected === null)
+            return sealed.size > 0;
+        return expected.every((participant) => sealed.has(participant));
+    }
+    function clear() {
+        sealed = new Map();
+        revealed = false;
+    }
+    return {
+        mode,
+        submit(participant, action) {
+            if (mode === "immediate") {
+                return { status: "committed", committed: [{ participant, action }] };
+            }
+            if (sealed.has(participant) && !(mode === "rewind")) {
+                return { status: "rejected", committed: [], reason: "already-submitted" };
+            }
+            sealed.set(participant, action);
+            if (mode === "simultaneous") {
+                return { status: "sealed", committed: [] };
+            }
+            return { status: "pending", committed: [] };
+        },
+        expected(participants) {
+            expected = [...participants];
+        },
+        hasSubmitted: (participant) => sealed.has(participant),
+        allReady,
+        pending: () => orderedSubmissions(),
+        reveal() {
+            if (mode !== "simultaneous")
+                return orderedSubmissions();
+            if (!allReady())
+                return [];
+            revealed = true;
+            const out = orderedSubmissions();
+            return out;
+        },
+        commit() {
+            if (mode === "simultaneous" && !revealed && !allReady())
+                return [];
+            const out = orderedSubmissions();
+            clear();
+            return out;
+        },
+        rewind() {
+            const discarded = orderedSubmissions();
+            clear();
+            return discarded;
+        },
+        clear,
+    };
+}

package/dist/turn/intent.d.ts

@@ -0,0 +1,14 @@
+export interface DeclaredIntent<TKind extends string = string> {
+    kind: TKind;
+    magnitude?: number;
+    targetId?: string;
+    note?: string;
+}
+export interface IntentBoard<TKind extends string = string> {
+    declare(participantId: string, intent: DeclaredIntent<TKind>): void;
+    peek(participantId: string): DeclaredIntent<TKind> | null;
+    all(): readonly [string, DeclaredIntent<TKind>][];
+    consume(participantId: string): DeclaredIntent<TKind> | null;
+    clear(participantId?: string): void;
+}
+export declare function createIntentBoard<TKind extends string = string>(): IntentBoard<TKind>;

package/dist/turn/intent.js

@@ -0,0 +1,29 @@
+export function createIntentBoard() {
+    const intents = new Map();
+    return {
+        declare(participantId, intent) {
+            intents.set(participantId, { ...intent });
+        },
+        peek(participantId) {
+            const intent = intents.get(participantId);
+            return intent === undefined ? null : { ...intent };
+        },
+        all() {
+            return [...intents.entries()].map(([participantId, intent]) => [participantId, { ...intent }]);
+        },
+        consume(participantId) {
+            const intent = intents.get(participantId);
+            if (intent === undefined)
+                return null;
+            intents.delete(participantId);
+            return intent;
+        },
+        clear(participantId) {
+            if (participantId === undefined) {
+                intents.clear();
+                return;
+            }
+            intents.delete(participantId);
+        },
+    };
+}

package/dist/turn/turnLoop.d.ts

@@ -0,0 +1,60 @@
+import { type CommitController, type CommitMode } from "./commit.js";
+export type { CommitMode, CommitController } from "./commit.js";
+export interface PoolConfig {
+    id: string;
+    max: number;
+    start?: number;
+}
+export interface TurnLoopConfig {
+    order: readonly string[];
+    phases?: readonly string[];
+    pools?: readonly PoolConfig[];
+    commit?: {
+        mode: CommitMode;
+    };
+    onTurnStart?(participantId: string): void;
+    onTurnEnd?(participantId: string): void;
+}
+export interface PoolState {
+    id: string;
+    current: number;
+    max: number;
+}
+export interface TurnState {
+    round: number;
+    order: readonly string[];
+    activeIndex: number;
+    active: string | null;
+    phaseIndex: number;
+    phase: string | null;
+}
+export interface TurnLoopSnapshot {
+    round: number;
+    order: string[];
+    activeIndex: number;
+    phaseIndex: number;
+    pools: Record<string, Record<string, number>>;
+}
+export interface TurnLoop<TAction = unknown> {
+    readonly commit: CommitController<TAction>;
+    state(): TurnState;
+    order(): readonly string[];
+    active(): string | null;
+    phase(): string | null;
+    round(): number;
+    setOrder(order: readonly string[], keepActive?: boolean): TurnState;
+    addParticipant(id: string, atIndex?: number): TurnState;
+    removeParticipant(id: string): TurnState;
+    advancePhase(): TurnState;
+    advanceTurn(): TurnState;
+    advanceRound(): TurnState;
+    pools(participantId: string): PoolState[];
+    pool(participantId: string, poolId: string): PoolState | null;
+    canSpend(participantId: string, poolId: string, amount?: number): boolean;
+    spend(participantId: string, poolId: string, amount?: number): boolean;
+    gain(participantId: string, poolId: string, amount: number): boolean;
+    refill(participantId: string, poolId?: string): void;
+    capture(): TurnLoopSnapshot;
+    restore(snapshot: TurnLoopSnapshot): void;
+}
+export declare function createTurnLoop<TAction = unknown>(config: TurnLoopConfig): TurnLoop<TAction>;

package/dist/turn/turnLoop.js

@@ -0,0 +1,223 @@
+import { createCommitController } from "./commit.js";
+export function createTurnLoop(config) {
+    const poolConfigs = config.pools ?? [];
+    const phases = config.phases ?? [];
+    const commit = createCommitController({
+        mode: config.commit?.mode ?? "immediate",
+        participants: config.order,
+    });
+    let order = [...config.order];
+    let round = 1;
+    let activeIndex = order.length > 0 ? 0 : -1;
+    let phaseIndex = 0;
+    const pools = new Map();
+    function resetPools(participantId) {
+        const set = new Map();
+        for (const pc of poolConfigs) {
+            set.set(pc.id, { id: pc.id, current: pc.start ?? pc.max, max: pc.max });
+        }
+        pools.set(participantId, set);
+    }
+    function ensurePools(participantId) {
+        const existing = pools.get(participantId);
+        if (existing !== undefined)
+            return existing;
+        resetPools(participantId);
+        return pools.get(participantId);
+    }
+    for (const id of order)
+        resetPools(id);
+    if (activeIndex >= 0)
+        config.onTurnStart?.(order[activeIndex]);
+    function active() {
+        return activeIndex >= 0 && activeIndex < order.length ? order[activeIndex] : null;
+    }
+    function phase() {
+        return phases.length > 0 ? phases[phaseIndex] ?? null : null;
+    }
+    function state() {
+        return {
+            round,
+            order: [...order],
+            activeIndex,
+            active: active(),
+            phaseIndex: phases.length > 0 ? phaseIndex : 0,
+            phase: phase(),
+        };
+    }
+    function advanceTurn() {
+        if (order.length === 0) {
+            activeIndex = -1;
+            return state();
+        }
+        const previous = active();
+        phaseIndex = 0;
+        if (activeIndex < 0) {
+            activeIndex = 0;
+        }
+        else if (activeIndex >= order.length - 1) {
+            activeIndex = 0;
+            round += 1;
+        }
+        else {
+            activeIndex += 1;
+        }
+        if (previous !== null)
+            config.onTurnEnd?.(previous);
+        const current = active();
+        if (current !== null) {
+            resetPools(current);
+            config.onTurnStart?.(current);
+        }
+        return state();
+    }
+    function advancePhase() {
+        if (phases.length === 0)
+            return advanceTurn();
+        if (phaseIndex >= phases.length - 1)
+            return advanceTurn();
+        phaseIndex += 1;
+        return state();
+    }
+    function advanceRound() {
+        if (order.length === 0) {
+            round += 1;
+            return state();
+        }
+        round += 1;
+        activeIndex = 0;
+        phaseIndex = 0;
+        for (const id of order)
+            resetPools(id);
+        return state();
+    }
+    function setOrder(next, keepActive = false) {
+        const previousActive = active();
+        order = [...next];
+        for (const id of order)
+            if (!pools.has(id))
+                resetPools(id);
+        for (const id of [...pools.keys()])
+            if (!order.includes(id))
+                pools.delete(id);
+        if (order.length === 0) {
+            activeIndex = -1;
+        }
+        else if (keepActive && previousActive !== null && order.includes(previousActive)) {
+            activeIndex = order.indexOf(previousActive);
+        }
+        else {
+            activeIndex = Math.min(Math.max(activeIndex, 0), order.length - 1);
+        }
+        return state();
+    }
+    function addParticipant(id, atIndex) {
+        if (order.includes(id))
+            return state();
+        const index = atIndex === undefined ? order.length : Math.min(Math.max(atIndex, 0), order.length);
+        order.splice(index, 0, id);
+        resetPools(id);
+        if (activeIndex < 0)
+            activeIndex = 0;
+        else if (index <= activeIndex)
+            activeIndex += 1;
+        return state();
+    }
+    function removeParticipant(id) {
+        const index = order.indexOf(id);
+        if (index < 0)
+            return state();
+        order.splice(index, 1);
+        pools.delete(id);
+        if (order.length === 0) {
+            activeIndex = -1;
+        }
+        else if (index < activeIndex) {
+            activeIndex -= 1;
+        }
+        else if (activeIndex >= order.length) {
+            activeIndex = 0;
+        }
+        return state();
+    }
+    return {
+        commit,
+        state,
+        order: () => [...order],
+        active,
+        phase,
+        round: () => round,
+        setOrder,
+        addParticipant,
+        removeParticipant,
+        advancePhase,
+        advanceTurn,
+        advanceRound,
+        pools: (participantId) => [...ensurePools(participantId).values()].map((p) => ({ ...p })),
+        pool: (participantId, poolId) => {
+            const p = ensurePools(participantId).get(poolId);
+            return p === undefined ? null : { ...p };
+        },
+        canSpend: (participantId, poolId, amount = 1) => {
+            const p = ensurePools(participantId).get(poolId);
+            return p !== undefined && p.current >= amount;
+        },
+        spend: (participantId, poolId, amount = 1) => {
+            const p = ensurePools(participantId).get(poolId);
+            if (p === undefined || p.current < amount)
+                return false;
+            p.current -= amount;
+            return true;
+        },
+        gain: (participantId, poolId, amount) => {
+            const p = ensurePools(participantId).get(poolId);
+            if (p === undefined)
+                return false;
+            p.current = Math.min(p.max, p.current + amount);
+            return true;
+        },
+        refill: (participantId, poolId) => {
+            const set = ensurePools(participantId);
+            if (poolId === undefined) {
+                for (const p of set.values())
+                    p.current = p.max;
+                return;
+            }
+            const p = set.get(poolId);
+            if (p !== undefined)
+                p.current = p.max;
+        },
+        capture: () => {
+            const poolSnapshot = {};
+            for (const [participantId, set] of pools) {
+                const entry = {};
+                for (const [poolId, p] of set)
+                    entry[poolId] = p.current;
+                poolSnapshot[participantId] = entry;
+            }
+            return { round, order: [...order], activeIndex, phaseIndex, pools: poolSnapshot };
+        },
+        restore: (snapshot) => {
+            round = snapshot.round;
+            order = [...snapshot.order];
+            activeIndex = snapshot.activeIndex;
+            phaseIndex = snapshot.phaseIndex;
+            pools.clear();
+            for (const id of order)
+                resetPools(id);
+            for (const [participantId, entry] of Object.entries(snapshot.pools)) {
+                const set = pools.get(participantId) ?? new Map();
+                for (const [poolId, current] of Object.entries(entry)) {
+                    const existing = set.get(poolId);
+                    if (existing !== undefined)
+                        existing.current = current;
+                    else {
+                        const pc = poolConfigs.find((c) => c.id === poolId);
+                        set.set(poolId, { id: poolId, current, max: pc?.max ?? current });
+                    }
+                }
+                pools.set(participantId, set);
+            }
+        },
+    };
+}

package/dist/world/buildPermissions.d.ts

@@ -0,0 +1,47 @@
+export type BuildRole = "owner" | "editor" | "viewer";
+export interface PlotPermissionConfig {
+    plotId: string;
+    ownerId: string;
+    guildId?: string;
+    roles?: Readonly<Record<string, BuildRole>>;
+    guildRole?: BuildRole;
+}
+export interface PlotPermissionSnapshot {
+    plotId: string;
+    ownerId: string;
+    guildId?: string;
+    roles: Readonly<Record<string, BuildRole>>;
+    guildRole?: BuildRole;
+}
+export interface BuildActor {
+    userId: string;
+    guildId?: string;
+}
+export interface PlotPermissions {
+    roleOf(actor: BuildActor): BuildRole | null;
+    canEdit(actor: BuildActor): boolean;
+    canView(actor: BuildActor): boolean;
+    grant(userId: string, role: BuildRole): void;
+    revoke(userId: string): void;
+    setGuild(guildId: string | null, role?: BuildRole): void;
+    transferOwner(userId: string): void;
+    snapshot(): PlotPermissionSnapshot;
+}
+export declare function createPlotPermissions(config: PlotPermissionConfig): PlotPermissions;
+export type ContributionGoal = Readonly<Record<string, number>>;
+export interface ContributionResult {
+    accepted: number;
+    overflow: number;
+    complete: boolean;
+}
+export interface ContributionPool {
+    contribute(userId: string, resource: string, amount: number): ContributionResult;
+    totals(): Readonly<Record<string, number>>;
+    remaining(): Readonly<Record<string, number>>;
+    byContributor(userId: string): Readonly<Record<string, number>>;
+    progress(): number;
+    isComplete(): boolean;
+    snapshot(): Record<string, Record<string, number>>;
+    restore(snapshot: Record<string, Record<string, number>>): void;
+}
+export declare function createContributionPool(goal: ContributionGoal): ContributionPool;

package/dist/world/buildPermissions.js

@@ -0,0 +1,134 @@
+const ROLE_RANK = { viewer: 0, editor: 1, owner: 2 };
+export function createPlotPermissions(config) {
+    let ownerId = config.ownerId;
+    let guildId = config.guildId;
+    let guildRole = config.guildRole;
+    const roles = new Map(Object.entries(config.roles ?? {}));
+    function roleOf(actor) {
+        if (actor.userId === ownerId)
+            return "owner";
+        const explicit = roles.get(actor.userId);
+        if (explicit !== undefined)
+            return explicit;
+        if (guildId !== undefined &&
+            guildRole !== undefined &&
+            actor.guildId !== undefined &&
+            actor.guildId === guildId) {
+            return guildRole;
+        }
+        return null;
+    }
+    return {
+        roleOf,
+        canEdit(actor) {
+            const role = roleOf(actor);
+            return role !== null && ROLE_RANK[role] >= ROLE_RANK.editor;
+        },
+        canView(actor) {
+            return roleOf(actor) !== null;
+        },
+        grant(userId, role) {
+            if (userId === ownerId)
+                return;
+            roles.set(userId, role);
+        },
+        revoke(userId) {
+            roles.delete(userId);
+        },
+        setGuild(nextGuildId, role) {
+            guildId = nextGuildId ?? undefined;
+            guildRole = nextGuildId === null ? undefined : role ?? guildRole ?? "editor";
+        },
+        transferOwner(userId) {
+            roles.delete(userId);
+            ownerId = userId;
+        },
+        snapshot() {
+            return {
+                plotId: config.plotId,
+                ownerId,
+                ...(guildId === undefined ? {} : { guildId }),
+                roles: Object.fromEntries(roles),
+                ...(guildRole === undefined ? {} : { guildRole }),
+            };
+        },
+    };
+}
+export function createContributionPool(goal) {
+    const perResource = new Map();
+    function totalFor(resource) {
+        let sum = 0;
+        for (const amount of perResource.get(resource)?.values() ?? [])
+            sum += amount;
+        return sum;
+    }
+    function totals() {
+        const out = {};
+        for (const resource of Object.keys(goal))
+            out[resource] = totalFor(resource);
+        return out;
+    }
+    function isComplete() {
+        for (const resource of Object.keys(goal)) {
+            if (totalFor(resource) < goal[resource])
+                return false;
+        }
+        return true;
+    }
+    return {
+        contribute(userId, resource, amount) {
+            if (amount <= 0 || goal[resource] === undefined) {
+                return { accepted: 0, overflow: amount > 0 ? amount : 0, complete: isComplete() };
+            }
+            const need = Math.max(0, goal[resource] - totalFor(resource));
+            const accepted = Math.min(need, amount);
+            const overflow = amount - accepted;
+            if (accepted > 0) {
+                const contributors = perResource.get(resource) ?? new Map();
+                contributors.set(userId, (contributors.get(userId) ?? 0) + accepted);
+                perResource.set(resource, contributors);
+            }
+            return { accepted, overflow, complete: isComplete() };
+        },
+        totals,
+        remaining() {
+            const out = {};
+            for (const resource of Object.keys(goal))
+                out[resource] = Math.max(0, goal[resource] - totalFor(resource));
+            return out;
+        },
+        byContributor(userId) {
+            const out = {};
+            for (const [resource, contributors] of perResource) {
+                const amount = contributors.get(userId);
+                if (amount !== undefined)
+                    out[resource] = amount;
+            }
+            return out;
+        },
+        progress() {
+            const resources = Object.keys(goal);
+            if (resources.length === 0)
+                return 1;
+            let sum = 0;
+            for (const resource of resources) {
+                const target = goal[resource];
+                sum += target <= 0 ? 1 : Math.min(1, totalFor(resource) / target);
+            }
+            return sum / resources.length;
+        },
+        isComplete,
+        snapshot() {
+            const out = {};
+            for (const [resource, contributors] of perResource)
+                out[resource] = Object.fromEntries(contributors);
+            return out;
+        },
+        restore(snapshot) {
+            perResource.clear();
+            for (const [resource, contributors] of Object.entries(snapshot)) {
+                perResource.set(resource, new Map(Object.entries(contributors)));
+            }
+        },
+    };
+}