@jgengine/core 0.1.0

package/dist/assets/spriteSheet.d.ts

@@ -0,0 +1,46 @@
+export interface SpriteSheetGridConfig {
+    columns: number;
+    rows: number;
+    marginX: number;
+    marginY: number;
+    gapX: number;
+    gapY: number;
+    cellWidth?: number;
+    cellHeight?: number;
+}
+export interface SpriteSheetSliceBox {
+    id: string;
+    name: string;
+    row: number;
+    column: number;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface SpriteSheetManifest {
+    version: 1;
+    source: {
+        name: string;
+        width: number;
+        height: number;
+    };
+    grid: SpriteSheetGridConfig;
+    slices: SpriteSheetSliceBox[];
+}
+export declare function sanitizeAssetName(value: string): string;
+export declare function normalizeSpriteSheetGridConfig(imageWidth: number, imageHeight: number, config: SpriteSheetGridConfig): Required<SpriteSheetGridConfig>;
+export declare function buildSpriteSheetGridBoxes({ imageWidth, imageHeight, config, namePrefix, names, }: {
+    imageWidth: number;
+    imageHeight: number;
+    config: SpriteSheetGridConfig;
+    namePrefix: string;
+    names?: readonly string[];
+}): SpriteSheetSliceBox[];
+export declare function buildSpriteSheetManifest({ sourceName, imageWidth, imageHeight, config, slices, }: {
+    sourceName: string;
+    imageWidth: number;
+    imageHeight: number;
+    config: SpriteSheetGridConfig;
+    slices: SpriteSheetSliceBox[];
+}): SpriteSheetManifest;

package/dist/assets/spriteSheet.js

@@ -0,0 +1,86 @@
+export function sanitizeAssetName(value) {
+    const normalized = value
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return normalized.length > 0 ? normalized : "asset";
+}
+function requirePositiveInteger(value, label) {
+    if (!Number.isInteger(value) || value <= 0) {
+        throw new Error(`${label} must be a positive integer.`);
+    }
+}
+function requireNonNegativeInteger(value, label) {
+    if (!Number.isInteger(value) || value < 0) {
+        throw new Error(`${label} must be a non-negative integer.`);
+    }
+}
+export function normalizeSpriteSheetGridConfig(imageWidth, imageHeight, config) {
+    requirePositiveInteger(imageWidth, "imageWidth");
+    requirePositiveInteger(imageHeight, "imageHeight");
+    requirePositiveInteger(config.columns, "columns");
+    requirePositiveInteger(config.rows, "rows");
+    requireNonNegativeInteger(config.marginX, "marginX");
+    requireNonNegativeInteger(config.marginY, "marginY");
+    requireNonNegativeInteger(config.gapX, "gapX");
+    requireNonNegativeInteger(config.gapY, "gapY");
+    const availableWidth = imageWidth - config.marginX * 2 - config.gapX * (config.columns - 1);
+    const availableHeight = imageHeight - config.marginY * 2 - config.gapY * (config.rows - 1);
+    const cellWidth = config.cellWidth ?? Math.floor(availableWidth / config.columns);
+    const cellHeight = config.cellHeight ?? Math.floor(availableHeight / config.rows);
+    requirePositiveInteger(cellWidth, "cellWidth");
+    requirePositiveInteger(cellHeight, "cellHeight");
+    const usedWidth = config.marginX * 2 + cellWidth * config.columns + config.gapX * (config.columns - 1);
+    const usedHeight = config.marginY * 2 + cellHeight * config.rows + config.gapY * (config.rows - 1);
+    if (usedWidth > imageWidth) {
+        throw new Error(`grid width ${usedWidth} exceeds image width ${imageWidth}.`);
+    }
+    if (usedHeight > imageHeight) {
+        throw new Error(`grid height ${usedHeight} exceeds image height ${imageHeight}.`);
+    }
+    return {
+        columns: config.columns,
+        rows: config.rows,
+        marginX: config.marginX,
+        marginY: config.marginY,
+        gapX: config.gapX,
+        gapY: config.gapY,
+        cellWidth,
+        cellHeight,
+    };
+}
+export function buildSpriteSheetGridBoxes({ imageWidth, imageHeight, config, namePrefix, names, }) {
+    const grid = normalizeSpriteSheetGridConfig(imageWidth, imageHeight, config);
+    const prefix = sanitizeAssetName(namePrefix);
+    const boxes = [];
+    for (let row = 0; row < grid.rows; row += 1) {
+        for (let column = 0; column < grid.columns; column += 1) {
+            const index = row * grid.columns + column;
+            const name = sanitizeAssetName(names?.[index] ?? `${prefix}-${String(index + 1).padStart(2, "0")}`);
+            boxes.push({
+                id: `${row}-${column}`,
+                name,
+                row,
+                column,
+                x: grid.marginX + column * (grid.cellWidth + grid.gapX),
+                y: grid.marginY + row * (grid.cellHeight + grid.gapY),
+                width: grid.cellWidth,
+                height: grid.cellHeight,
+            });
+        }
+    }
+    return boxes;
+}
+export function buildSpriteSheetManifest({ sourceName, imageWidth, imageHeight, config, slices, }) {
+    return {
+        version: 1,
+        source: {
+            name: sourceName,
+            width: imageWidth,
+            height: imageHeight,
+        },
+        grid: normalizeSpriteSheetGridConfig(imageWidth, imageHeight, config),
+        slices,
+    };
+}

package/dist/combat/death.d.ts

@@ -0,0 +1,61 @@
+import type { DeathReason, GameEvents } from "../game/events.js";
+import type { Drop } from "../game/lootTable.js";
+import type { EffectVia } from "./effects.js";
+export type DeathReasonKind = DeathReason["kind"];
+export interface OnDeathDropRule {
+    table: string;
+    when?: {
+        reason: DeathReasonKind;
+    };
+}
+export interface OnDeathCommandRule {
+    name: string;
+    args?: unknown;
+    when?: {
+        reason: DeathReasonKind;
+    };
+}
+export interface OnDeathSpec {
+    drops?: string | OnDeathDropRule[];
+    command?: string | OnDeathCommandRule;
+}
+export interface NormalizedOnDeath {
+    drops: OnDeathDropRule[];
+    command: OnDeathCommandRule | null;
+}
+export declare function normalizeOnDeath(spec: OnDeathSpec | null | undefined): NormalizedOnDeath;
+export interface DeathIdentity {
+    catalogId: string;
+    userId?: string;
+    displayName?: string;
+    position: [number, number, number];
+}
+export interface DeathSystemDeps {
+    resolveOnDeath(instanceId: string): OnDeathSpec | null | undefined;
+    resolveIdentity(instanceId: string): DeathIdentity | null;
+    loot: {
+        roll(tableId: string): Drop[];
+    };
+    events: GameEvents;
+    runCommand?(name: string, args: unknown): void;
+    despawn(instanceId: string): void;
+}
+export type DeathResolution = {
+    status: "resolved";
+    drops: Drop[];
+    ranCommand: string | null;
+} | {
+    status: "rejected";
+    reason: string;
+};
+export interface DeathSystem {
+    resolveDeath(instanceId: string, reason: DeathReason): DeathResolution;
+    revive(instanceId: string): boolean;
+}
+export declare function createDeathSystem(deps: DeathSystemDeps): DeathSystem;
+export interface EffectDeathContext {
+    from: string;
+    via?: EffectVia;
+    userIdOf?(instanceId: string): string | undefined;
+}
+export declare function deathReasonFromEffect(ctx: EffectDeathContext): DeathReason;

package/dist/combat/death.js

@@ -0,0 +1,61 @@
+export function normalizeOnDeath(spec) {
+    if (!spec)
+        return { drops: [], command: null };
+    const drops = spec.drops === undefined ? [] : typeof spec.drops === "string" ? [{ table: spec.drops }] : spec.drops;
+    const command = spec.command === undefined ? null : typeof spec.command === "string" ? { name: spec.command } : spec.command;
+    return { drops, command };
+}
+function matchesReason(when, reason) {
+    return when === undefined || when.reason === reason.kind;
+}
+export function createDeathSystem(deps) {
+    const dead = new Set();
+    return {
+        resolveDeath(instanceId, reason) {
+            if (dead.has(instanceId))
+                return { status: "rejected", reason: "already-dead" };
+            const identity = deps.resolveIdentity(instanceId);
+            if (identity === null)
+                return { status: "rejected", reason: "unknown-instance" };
+            dead.add(instanceId);
+            const event = {
+                instanceId,
+                catalogId: identity.catalogId,
+                reason,
+                position: identity.position,
+            };
+            if (identity.userId !== undefined)
+                event.userId = identity.userId;
+            if (identity.displayName !== undefined)
+                event.displayName = identity.displayName;
+            deps.events.emit("entity.died", event);
+            const onDeath = normalizeOnDeath(deps.resolveOnDeath(instanceId));
+            const drops = [];
+            for (const rule of onDeath.drops) {
+                if (matchesReason(rule.when, reason))
+                    drops.push(...deps.loot.roll(rule.table));
+            }
+            let ranCommand = null;
+            if (onDeath.command !== null &&
+                matchesReason(onDeath.command.when, reason) &&
+                deps.runCommand !== undefined) {
+                deps.runCommand(onDeath.command.name, onDeath.command.args);
+                ranCommand = onDeath.command.name;
+            }
+            deps.despawn(instanceId);
+            return { status: "resolved", drops, ranCommand };
+        },
+        revive(instanceId) {
+            return dead.delete(instanceId);
+        },
+    };
+}
+export function deathReasonFromEffect(ctx) {
+    const killerUserId = ctx.userIdOf?.(ctx.from);
+    if (killerUserId !== undefined) {
+        return ctx.via?.item !== undefined
+            ? { kind: "player_kill", killerUserId, via: { item: ctx.via.item } }
+            : { kind: "player_kill", killerUserId };
+    }
+    return { kind: "environment", source: ctx.via?.item ?? "effect" };
+}

package/dist/combat/effects.d.ts

@@ -0,0 +1,61 @@
+import type { EntityPosition } from "../scene/entityStore.js";
+import { type PoolStatMap } from "../scene/entityStats.js";
+export interface ReceiveRule {
+    order: string[];
+    modifiers?: Record<string, number>;
+}
+export type ReceiveMap = Record<string, ReceiveRule>;
+export interface EffectVia {
+    item?: string;
+    amount?: number;
+}
+export interface SingleTargetEffectInput {
+    from: string;
+    to: string;
+    effect: string;
+    via?: EffectVia;
+}
+export interface AreaEffectInput {
+    from: string;
+    effect: string;
+    via?: EffectVia;
+    at: EntityPosition;
+    radius: number;
+    falloff?: "linear" | "none";
+    los?: boolean;
+}
+export type EffectInput = SingleTargetEffectInput | AreaEffectInput;
+export interface AppliedPoolDelta {
+    statId: string;
+    delta: number;
+}
+export interface EffectResult {
+    instanceId: string;
+    effect: string;
+    applied: AppliedPoolDelta[];
+    lethal: boolean;
+}
+export interface LethalContext {
+    from: string;
+    via?: EffectVia;
+    effect: string;
+}
+export interface CombatSpatialDeps {
+    inRadius(center: EntityPosition, radius: number): string[];
+    hasLineOfSight(from: EntityPosition | string, to: string): boolean;
+    positionOf(instanceId: string): EntityPosition | undefined;
+}
+export interface EffectSystemDeps {
+    resolveReceive(instanceId: string): ReceiveMap | null | undefined;
+    resolveStats(instanceId: string): PoolStatMap | undefined;
+    getStat(itemId: string, stat: string): number | null;
+    spatial: CombatSpatialDeps;
+    drainStatByEffect?: Record<string, string>;
+    onLethal?(instanceId: string, ctx: LethalContext): void;
+}
+export interface EffectSystem {
+    canReceive(instanceId: string, effect: string): string | null;
+    preview(input: SingleTargetEffectInput): number;
+    applyEffect(input: EffectInput): EffectResult[];
+}
+export declare function createEffectSystem(deps: EffectSystemDeps): EffectSystem;

package/dist/combat/effects.js

@@ -0,0 +1,108 @@
+import { applyPoolDelta } from "../scene/entityStats.js";
+import { distanceBetween } from "../scene/spatial.js";
+const DEFAULT_DRAIN_STAT = "damage";
+export function createEffectSystem(deps) {
+    function resolveRule(instanceId, effect) {
+        return deps.resolveReceive(instanceId)?.[effect] ?? null;
+    }
+    function baseDrainMagnitude(effect, via) {
+        if (via?.amount !== undefined)
+            return via.amount;
+        if (via?.item === undefined)
+            return 0;
+        const statName = deps.drainStatByEffect?.[effect] ?? DEFAULT_DRAIN_STAT;
+        return deps.getStat(via.item, statName) ?? 0;
+    }
+    function modifiedDrainMagnitude(magnitude, rule) {
+        let result = magnitude;
+        for (const reduction of Object.values(rule.modifiers ?? {})) {
+            result *= 1 - reduction;
+        }
+        return result;
+    }
+    function canReceive(instanceId, effect) {
+        const rule = resolveRule(instanceId, effect);
+        if (rule === null)
+            return "not-receivable";
+        const stats = deps.resolveStats(instanceId);
+        if (stats === undefined)
+            return "unknown-instance";
+        const anyPoolAboveMin = rule.order.some((statId) => {
+            const stat = stats[statId];
+            return stat !== undefined && stat.current > stat.min;
+        });
+        if (!anyPoolAboveMin)
+            return "pools-depleted";
+        return null;
+    }
+    function drainPools(instanceId, effect, rule, stats, drainMagnitude) {
+        const applied = [];
+        const lastStatId = rule.order[rule.order.length - 1];
+        let remaining = drainMagnitude;
+        let lethal = false;
+        for (const statId of rule.order) {
+            if (remaining === 0)
+                break;
+            const before = stats[statId];
+            if (before === undefined)
+                continue;
+            const result = applyPoolDelta(stats, statId, -remaining);
+            if (result.status === "rejected")
+                continue;
+            stats[statId] = result.stat;
+            const delta = result.stat.current - before.current;
+            if (delta !== 0)
+                applied.push({ statId, delta });
+            remaining += delta;
+            if (statId === lastStatId && drainMagnitude > 0 && result.hitMin)
+                lethal = true;
+        }
+        return { instanceId, effect, applied, lethal };
+    }
+    function applyTo(instanceId, effect, via, from, scale) {
+        if (canReceive(instanceId, effect) !== null)
+            return null;
+        const rule = resolveRule(instanceId, effect);
+        const stats = deps.resolveStats(instanceId);
+        if (rule === null || stats === undefined)
+            return null;
+        const drainMagnitude = modifiedDrainMagnitude(baseDrainMagnitude(effect, via) * scale, rule);
+        const result = drainPools(instanceId, effect, rule, stats, drainMagnitude);
+        if (result.lethal)
+            deps.onLethal?.(instanceId, { from, via, effect });
+        return result;
+    }
+    return {
+        canReceive,
+        preview(input) {
+            const rule = resolveRule(input.to, input.effect);
+            if (rule === null)
+                return 0;
+            return modifiedDrainMagnitude(baseDrainMagnitude(input.effect, input.via), rule);
+        },
+        applyEffect(input) {
+            if ("to" in input) {
+                const result = applyTo(input.to, input.effect, input.via, input.from, 1);
+                return result === null ? [] : [result];
+            }
+            const falloff = input.falloff ?? "none";
+            const los = input.los ?? true;
+            const results = [];
+            for (const instanceId of deps.spatial.inRadius(input.at, input.radius)) {
+                if (los && !deps.spatial.hasLineOfSight(input.at, instanceId))
+                    continue;
+                let scale = 1;
+                if (falloff === "linear") {
+                    const position = deps.spatial.positionOf(instanceId);
+                    if (position === undefined)
+                        continue;
+                    scale = Math.max(0, 1 - distanceBetween(input.at, position) / input.radius);
+                }
+                const result = applyTo(instanceId, input.effect, input.via, input.from, scale);
+                if (result !== null)
+                    results.push(result);
+            }
+            return results;
+        },
+    };
+}

package/dist/combat/projectiles.d.ts

@@ -0,0 +1,45 @@
+import type { EntityPosition } from "../scene/entityStore.js";
+import type { Aim } from "../scene/spatial.js";
+import type { CombatSpatialDeps, EffectResult, EffectSystem, EffectVia } from "./effects.js";
+export interface ProjectileShotInput {
+    from: string;
+    via: EffectVia;
+    aim: Aim;
+    effect: string;
+}
+export interface RaycastHit {
+    instanceId: string;
+    distance: number;
+    at: EntityPosition;
+}
+export type Raycast = (from: string, aim: Aim, range: number) => RaycastHit[];
+export interface ProjectileSystemDeps {
+    effects: EffectSystem;
+    spatial: CombatSpatialDeps;
+    getStat(itemId: string, stat: string): number | null;
+    raycast?: Raycast;
+    now?: () => number;
+}
+export interface ProjectilePrediction {
+    hits: {
+        instanceId: string;
+        distance: number;
+    }[];
+    blocked?: boolean;
+}
+export type SettleResult = {
+    status: "settled";
+    shotId: string;
+    at: [number, number, number];
+    hits: EffectResult[];
+} | {
+    status: "rejected";
+    shotId: string;
+    reason: string;
+};
+export interface ProjectileSystem {
+    willHitProjectile(input: ProjectileShotInput): ProjectilePrediction;
+    fireProjectile(input: ProjectileShotInput): string;
+    settleProjectile(shotId: string): SettleResult;
+}
+export declare function createProjectileSystem(deps: ProjectileSystemDeps): ProjectileSystem;

package/dist/combat/projectiles.js

@@ -0,0 +1,156 @@
+const DEFAULT_RANGE = 100;
+const DEFAULT_PROJECTILE_SPEED = 15;
+const GRAVITY = 9.8;
+const BASE_HIT_RADIUS = 0.5;
+function normalize(vector) {
+    const length = Math.sqrt(vector[0] * vector[0] + vector[1] * vector[1] + vector[2] * vector[2]);
+    if (length === 0)
+        return null;
+    return [vector[0] / length, vector[1] / length, vector[2] / length];
+}
+function aimDirection(aim) {
+    if ("origin" in aim)
+        return normalize(aim.direction);
+    const cosPitch = Math.cos(aim.pitch);
+    return [Math.sin(aim.yaw) * cosPitch, Math.sin(aim.pitch), Math.cos(aim.yaw) * cosPitch];
+}
+function aimSpreadDeg(aim) {
+    return "origin" in aim ? 0 : aim.spread ?? 0;
+}
+export function createProjectileSystem(deps) {
+    const shots = new Map();
+    let shotCounter = 0;
+    const now = deps.now ?? (() => Date.now());
+    function itemStat(via, stat) {
+        return via.item === undefined ? null : deps.getStat(via.item, stat);
+    }
+    function shotOrigin(from, aim) {
+        return "origin" in aim ? aim.origin : deps.spatial.positionOf(from);
+    }
+    function withWeaponSpread(via, aim) {
+        if ("origin" in aim || aim.spread !== undefined)
+            return aim;
+        const spread = itemStat(via, "spread");
+        return spread === null ? aim : { ...aim, spread };
+    }
+    const raycast = deps.raycast ??
+        ((from, aim, range) => {
+            const origin = shotOrigin(from, aim);
+            if (origin === undefined)
+                return [];
+            const direction = aimDirection(aim);
+            if (direction === null)
+                return [];
+            const spreadRad = (aimSpreadDeg(aim) * Math.PI) / 180;
+            const hits = [];
+            for (const instanceId of deps.spatial.inRadius(origin, range)) {
+                if (instanceId === from)
+                    continue;
+                const position = deps.spatial.positionOf(instanceId);
+                if (position === undefined)
+                    continue;
+                const dx = position[0] - origin[0];
+                const dy = position[1] - origin[1];
+                const dz = position[2] - origin[2];
+                const along = dx * direction[0] + dy * direction[1] + dz * direction[2];
+                if (along <= 0 || along > range)
+                    continue;
+                const px = dx - direction[0] * along;
+                const py = dy - direction[1] * along;
+                const pz = dz - direction[2] * along;
+                const perpendicular = Math.sqrt(px * px + py * py + pz * pz);
+                if (perpendicular > BASE_HIT_RADIUS + Math.tan(spreadRad) * along)
+                    continue;
+                hits.push({ instanceId, distance: along, at: position });
+            }
+            return hits.sort((a, b) => a.distance - b.distance);
+        });
+    function resolveRange(via) {
+        return itemStat(via, "range") ?? DEFAULT_RANGE;
+    }
+    function isBallistic(via) {
+        return itemStat(via, "projectile.fuseTime") !== null || itemStat(via, "explosion.radius") !== null;
+    }
+    function ballisticSettlePoint(input) {
+        const origin = shotOrigin(input.from, input.aim) ?? [0, 0, 0];
+        const direction = aimDirection(input.aim) ?? [0, 0, 1];
+        const speed = itemStat(input.via, "projectile.speed") ?? DEFAULT_PROJECTILE_SPEED;
+        const gravityScale = itemStat(input.via, "projectile.gravity") ?? 1;
+        const fuseTime = itemStat(input.via, "projectile.fuseTime");
+        const gravity = GRAVITY * gravityScale;
+        const verticalSpeed = direction[1] * speed;
+        const flightCap = fuseTime ?? resolveRange(input.via) / speed;
+        const impactTime = gravity > 0
+            ? (verticalSpeed + Math.sqrt(verticalSpeed * verticalSpeed + 2 * gravity * Math.max(0, origin[1]))) / gravity
+            : flightCap;
+        const flightTime = Math.min(impactTime, flightCap);
+        const settledY = Math.max(0, origin[1] + verticalSpeed * flightTime - 0.5 * gravity * flightTime * flightTime);
+        return [
+            origin[0] + direction[0] * speed * flightTime,
+            settledY,
+            origin[2] + direction[2] * speed * flightTime,
+        ];
+    }
+    function predictHits(input) {
+        const aim = withWeaponSpread(input.via, input.aim);
+        const rawHits = raycast(input.from, aim, resolveRange(input.via));
+        const visible = rawHits.filter((hit) => deps.spatial.hasLineOfSight(input.from, hit.instanceId));
+        return { rawHits, visible };
+    }
+    function settledAt(input, hits) {
+        const first = hits[0];
+        if (first !== undefined)
+            return [first.at[0], first.at[1], first.at[2]];
+        const origin = shotOrigin(input.from, input.aim);
+        const direction = origin === undefined ? null : aimDirection(input.aim);
+        if (origin === undefined || direction === null)
+            return [0, 0, 0];
+        const range = resolveRange(input.via);
+        return [origin[0] + direction[0] * range, origin[1] + direction[1] * range, origin[2] + direction[2] * range];
+    }
+    return {
+        willHitProjectile(input) {
+            const { rawHits, visible } = predictHits(input);
+            const prediction = {
+                hits: visible.map(({ instanceId, distance }) => ({ instanceId, distance })),
+            };
+            if (rawHits.length > 0 && visible.length === 0)
+                prediction.blocked = true;
+            return prediction;
+        },
+        fireProjectile(input) {
+            shotCounter += 1;
+            const shotId = `shot_${shotCounter}`;
+            shots.set(shotId, { input, firedAt: now(), settled: false });
+            return shotId;
+        },
+        settleProjectile(shotId) {
+            const shot = shots.get(shotId);
+            if (shot === undefined)
+                return { status: "rejected", shotId, reason: "unknown-shot" };
+            if (shot.settled)
+                return { status: "rejected", shotId, reason: "already-settled" };
+            shot.settled = true;
+            const { input } = shot;
+            if (isBallistic(input.via)) {
+                return { status: "settled", shotId, at: ballisticSettlePoint(input), hits: [] };
+            }
+            const { visible } = predictHits(input);
+            const receivable = visible.filter((hit) => deps.effects.canReceive(hit.instanceId, input.effect) === null);
+            const pellets = Math.max(1, Math.round(itemStat(input.via, "pellets") ?? 1));
+            const hits = [];
+            if (receivable.length > 0) {
+                for (let pellet = 0; pellet < pellets; pellet++) {
+                    const target = receivable[pellet % receivable.length];
+                    hits.push(...deps.effects.applyEffect({
+                        from: input.from,
+                        to: target.instanceId,
+                        effect: input.effect,
+                        via: input.via,
+                    }));
+                }
+            }
+            return { status: "settled", shotId, at: settledAt(input, receivable), hits };
+        },
+    };
+}

package/dist/commands/commandRegistry.d.ts

@@ -0,0 +1,23 @@
+export interface CommandRejection {
+    reason: string;
+}
+export interface CommandDefinition<TState, TInput> {
+    validate?(state: TState, input: TInput): CommandRejection | null;
+    apply(state: TState, input: TInput): TState;
+}
+export type CommandResult<TState> = {
+    status: "applied";
+    state: TState;
+} | {
+    status: "rejected";
+    reason: string;
+} | {
+    status: "unknown-command";
+};
+export interface CommandRegistry<TState> {
+    define<TInput>(name: string, definition: CommandDefinition<TState, TInput>): void;
+    has(name: string): boolean;
+    names(): string[];
+    run(state: TState, name: string, input: unknown): CommandResult<TState>;
+}
+export declare function createCommandRegistry<TState>(): CommandRegistry<TState>;

package/dist/commands/commandRegistry.js

@@ -0,0 +1,26 @@
+export function createCommandRegistry() {
+    const definitions = new Map();
+    return {
+        define(name, definition) {
+            if (definitions.has(name)) {
+                throw new Error(`Command "${name}" is already defined.`);
+            }
+            definitions.set(name, definition);
+        },
+        has(name) {
+            return definitions.has(name);
+        },
+        names() {
+            return Array.from(definitions.keys());
+        },
+        run(state, name, input) {
+            const definition = definitions.get(name);
+            if (!definition)
+                return { status: "unknown-command" };
+            const rejection = definition.validate?.(state, input) ?? null;
+            if (rejection)
+                return { status: "rejected", reason: rejection.reason };
+            return { status: "applied", state: definition.apply(state, input) };
+        },
+    };
+}