@jgengine/core 0.6.0 → 0.7.0

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/turnLoop.d.ts

@@ -0,0 +1,58 @@
+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;
+    };
+}
+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,216 @@
+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);
+    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();
+        }
+        phaseIndex = 0;
+        if (activeIndex < 0) {
+            activeIndex = 0;
+        }
+        else if (activeIndex >= order.length - 1) {
+            activeIndex = 0;
+            round += 1;
+        }
+        else {
+            activeIndex += 1;
+        }
+        const current = active();
+        if (current !== null)
+            resetPools(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)));
+            }
+        },
+    };
+}

package/dist/world/carve.d.ts

@@ -0,0 +1,105 @@
+import { type TerrainField } from "./terrain.js";
+import type { WorldBounds } from "./features.js";
+export declare const EMPTY_VOXEL = 0;
+export interface VoxelMaterial {
+    /** Cell value stored in the grid; 0 is reserved for empty. */
+    id: number;
+    name: string;
+    /** A carve tool's strength must reach this to remove the material — hard rock resists a weak drill. Default 0 (anything digs it). */
+    strength: number;
+    /** Debris/harvest hint carried through to game code; the engine only tallies removed cells by id. */
+    drop?: string;
+}
+export type VoxelMaterialTable = Readonly<Record<number, VoxelMaterial>>;
+export interface VoxelVolumeConfig {
+    /** Grid resolution in cells: [nx, ny, nz]. */
+    dims: readonly [number, number, number];
+    /** World position of the min corner of cell [0,0,0]. Default [0,0,0]. */
+    origin?: readonly [number, number, number];
+    /** World-space edge length of one cubic cell. Default 1. */
+    scale?: number;
+    /** Material id every cell starts as. Default 1 (a solid volume waiting to be dug). */
+    fill?: number;
+    /** Strength lookup by material id; carve honours it against a tool strength. */
+    materials?: VoxelMaterialTable;
+}
+export interface CarveOp {
+    /** Sphere centre in world coordinates. */
+    center: readonly [number, number, number];
+    /** Sphere radius in world units. */
+    radius: number;
+    /** Only cells whose material `strength` is ≤ this are removed. Default Infinity (dig anything). */
+    toolStrength?: number;
+}
+export interface DepositOp {
+    center: readonly [number, number, number];
+    radius: number;
+    /** Material id to fill empty cells with (Engineer platform / Astroneer terrain add). */
+    material: number;
+}
+/**
+ * A runtime-editable dense voxel grid — the carve/deposit op behind destructible dig worlds (Deep
+ * Rock Galactic tunnels, Astroneer terrain). Cells hold a material id (0 = empty); `carve` clears a
+ * sphere of solid cells that a tool is strong enough to break and returns how many it removed (feed
+ * that to a loot roll), `deposit` fills a sphere with a material. World↔cell mapping is `origin`+`scale`.
+ */
+export declare class VoxelVolume {
+    readonly nx: number;
+    readonly ny: number;
+    readonly nz: number;
+    readonly scale: number;
+    readonly origin: readonly [number, number, number];
+    private readonly cells;
+    private readonly materials;
+    private solidCount;
+    constructor(config: VoxelVolumeConfig);
+    get solid(): number;
+    private index;
+    inBounds(ix: number, iy: number, iz: number): boolean;
+    get(ix: number, iy: number, iz: number): number;
+    set(ix: number, iy: number, iz: number, material: number): void;
+    worldToCell(x: number, y: number, z: number): readonly [number, number, number];
+    solidAtWorld(x: number, y: number, z: number): boolean;
+    private strengthOf;
+    private forEachCellInSphere;
+    /** Clear every solid cell in the sphere the tool can break; returns the number removed. */
+    carve(op: CarveOp): number;
+    /** Fill every empty cell in the sphere with `material`; returns the number filled. */
+    deposit(op: DepositOp): number;
+}
+export interface CraterOp {
+    /** Crater centre (x, z in world units). */
+    x: number;
+    z: number;
+    radius: number;
+    /** How deep the bowl cuts at its centre. */
+    depth: number;
+}
+export interface MoundOp {
+    x: number;
+    z: number;
+    radius: number;
+    /** How high the mound rises at its centre. */
+    height: number;
+}
+/**
+ * A `TerrainField` you can write craters and mounds into at runtime — the height-field side of
+ * destructible terrain (Helldivers 2 explosion craters, engineer-deposited berms). Wraps a base field
+ * and layers smooth radial deformations on top, so `sampleHeight` (and therefore ground-snap,
+ * collision, and the shell's terrain mesh) all read the deformed surface. `carve` digs a bowl,
+ * `deposit` raises a mound.
+ */
+export declare class CarvableField implements TerrainField {
+    readonly bounds?: WorldBounds;
+    readonly waterLevel?: number;
+    readonly sampleNormal: TerrainField["sampleNormal"];
+    private readonly base;
+    private readonly edits;
+    constructor(base: TerrainField);
+    get editCount(): number;
+    sampleHeight(x: number, z: number): number;
+    carve(op: CraterOp): void;
+    deposit(op: MoundOp): void;
+    clear(): void;
+}
+export declare function carvableTerrain(base: TerrainField): CarvableField;