@jgengine/core 0.26.0 → 0.27.0

package/dist/progression/gearScore.js

@@ -0,0 +1,59 @@
+import { lootStatContributions } from "../loot/lootGen.js";
+/**
+ * Score a whole loadout with one documented formula:
+ *
+ * `slotScore = Σ_stat value × weight × (lowerIsBetter ? -1 : 1) + levelWeight × level + rarityScore[rarity]`
+ *
+ * `score = Σ slotScore - emptySlotPenalty × emptySlots`, and `byStat` sums the stat term alone. The
+ * stat term is `scoreLootStats`, the same weight policy `compareLootItems` uses, so an item swap and
+ * a loadout total agree. Ties are exact; nothing here reads a clock or RNG.
+ *
+ * @capability gear-score score a loadout from stat weights, level, rarity and slot coverage
+ */
+export function gearScore(set, options = {}) {
+    const bySlot = {};
+    const byStat = {};
+    const levelWeight = options.levelWeight ?? 0;
+    const rarityScores = options.rarityScore ?? {};
+    const emptySlotPenalty = options.emptySlotPenalty ?? 0;
+    let total = 0;
+    let items = 0;
+    for (const slot of Object.keys(set).sort()) {
+        const item = set[slot];
+        if (item === null || item === undefined)
+            continue;
+        let slotScore = 0;
+        const contributions = lootStatContributions(item.stats, options);
+        for (const stat of Object.keys(contributions)) {
+            const contribution = contributions[stat];
+            slotScore += contribution;
+            byStat[stat] = (byStat[stat] ?? 0) + contribution;
+        }
+        if (levelWeight !== 0 && item.level !== undefined)
+            slotScore += levelWeight * item.level;
+        if (item.rarity !== undefined)
+            slotScore += rarityScores[item.rarity] ?? 0;
+        bySlot[slot] = slotScore;
+        total += slotScore;
+        items += 1;
+    }
+    const expected = options.expectedSlots ?? [];
+    const emptySlots = expected.filter((slot) => set[slot] === null || set[slot] === undefined);
+    total -= emptySlotPenalty * emptySlots.length;
+    return {
+        score: total,
+        bySlot,
+        byStat,
+        items,
+        average: items === 0 ? 0 : total / items,
+        coverage: expected.length === 0 ? 1 : (expected.length - emptySlots.length) / expected.length,
+        emptySlots,
+    };
+}
+/** Compare two loadouts; negative means `a` scores lower. */
+export function compareGearSets(a, b, options = {}) {
+    const scoreA = gearScore(a, options);
+    const scoreB = gearScore(b, options);
+    const delta = scoreB.score - scoreA.score;
+    return { a: scoreA, b: scoreB, delta, better: delta === 0 ? "equal" : delta > 0 ? "b" : "a" };
+}

package/dist/progression/skillTree.d.ts

@@ -0,0 +1,129 @@
+import type { AbilityCastType } from "../combat/abilityKit.js";
+import type { StatModifierSet } from "../stats/statModifiers.js";
+/** One node that must be at or above `rank` for a node or synergy to open; `rank` defaults to `1`. */
+export interface SkillRequirement {
+    nodeId: string;
+    rank?: number;
+}
+/** An action a node or synergy unlocks, shaped to bind straight into `createAbilityKit`'s slot config. */
+export interface SkillActiveDef {
+    id: string;
+    cooldownMs?: number;
+    resourceCost?: number;
+    castType?: AbilityCastType;
+    /** Slot ids whose shared cooldown this action joins. */
+    groups?: readonly string[];
+}
+/**
+ * One authored tree node. Every field except `id` is optional data, so a game states its own tree:
+ * what a rank costs, what must come first, the passive it folds in and the actions it opens.
+ */
+export interface SkillNodeDef<TStat extends string = string> {
+    id: string;
+    /** Grouping for balance and UI; nodes with no branch share `""`. */
+    branch?: string;
+    /** Points one rank of this node costs (default `1`). */
+    cost?: number;
+    /** Ranks this node holds (default `1`). */
+    maxRank?: number;
+    /** Nodes and minimum ranks that must be spent before this node opens at all. */
+    requires?: readonly SkillRequirement[];
+    /** Points that must already sit in this node's branch, excluding this node's own ranks. */
+    requiresPointsInBranch?: number;
+    /** Nodes that cannot be ranked alongside this one — the exclusivity that makes builds differ. */
+    excludes?: readonly string[];
+    /** Passive stats one rank adds; multiplicative entries compound per rank. */
+    passives?: StatModifierSet<TStat>;
+    /** Actions unlocked by one or more ranks. */
+    actives?: readonly SkillActiveDef[];
+    /** Free-form tags for caller filters and UI. */
+    tags?: readonly string[];
+}
+/**
+ * A payoff that exists only when two or more nodes are ranked together. This is what rewards
+ * breadth over dumping every point into one branch.
+ */
+export interface SkillSynergyDef<TStat extends string = string> {
+    id: string;
+    /** At least two distinct nodes, each at or above its required rank. */
+    requires: readonly SkillRequirement[];
+    /** Passive stats added once while the synergy is live. */
+    passives?: StatModifierSet<TStat>;
+    /** Actions unlocked while the synergy is live. */
+    actives?: readonly SkillActiveDef[];
+    tags?: readonly string[];
+}
+/** Everything {@link createSkillTree} reads: nodes, optional synergies, and starting points. */
+export interface SkillTreeConfig<TStat extends string = string> {
+    nodes: readonly SkillNodeDef<TStat>[];
+    synergies?: readonly SkillSynergyDef<TStat>[];
+    /** Points the character starts with (default `0`). */
+    points?: number;
+}
+/** Why a spend was refused; each reason is reachable from authored data, so a UI can say which rule bit. */
+export type SkillSpendReason = "unknown-node" | "max-rank" | "no-points" | "requires" | "branch-points" | "excluded";
+/** The outcome of one spend or legality check: what it costs and the balance after it, or the rule that stopped it. */
+export type SkillSpendResult = {
+    ok: true;
+    spent: number;
+    pointsAvailable: number;
+} | {
+    ok: false;
+    reason: SkillSpendReason;
+    detail: string;
+};
+/** The whole outcome of a build: merged passives, unlocked actions, live synergies and point accounting. */
+export interface SkillResolution<TStat extends string = string> {
+    /** Merged passives: node passives per rank, then synergy passives, in config order. */
+    stats: StatModifierSet<TStat>;
+    /** Every unlocked action in config order, deduplicated by id. */
+    actives: readonly SkillActiveDef[];
+    activeIds: readonly string[];
+    /** Ids of the synergies currently satisfied, in config order. */
+    synergies: readonly string[];
+    /** Rank held per node, keyed by node id and sorted for a stable readout. */
+    ranks: Readonly<Record<string, number>>;
+    pointsSpent: number;
+    pointsAvailable: number;
+}
+/** Saved tree state: unspent points and the rank of every ranked node. */
+export interface SkillTreeState {
+    points: number;
+    ranks: Record<string, number>;
+}
+/** A live skill tree over one authored config, with respec, snapshot/restore and an optional devtools probe. */
+export interface SkillTree<TStat extends string = string> {
+    rank(nodeId: string): number;
+    pointsAvailable(): number;
+    /** Points currently committed, counting each node's `cost` per rank. */
+    pointsSpent(): number;
+    pointsInBranch(branch: string): number;
+    grantPoints(amount: number): void;
+    canSpend(nodeId: string): SkillSpendResult;
+    /** Spend one rank of `nodeId`, charging its `cost`; refused without mutation when a rule blocks it. */
+    spend(nodeId: string): SkillSpendResult;
+    /** Refund every spent point and clear every rank. Returns the exact number refunded. */
+    respec(): {
+        refunded: number;
+        pointsAvailable: number;
+    };
+    resolved(): SkillResolution<TStat>;
+    snapshot(): SkillTreeState;
+    /** Replace state from a save; refuses without mutation when it names unknown nodes or malformed counts. */
+    restore(next: SkillTreeState): boolean;
+    /** Drop the devtools probe registered by `devtoolsName`. Safe to call twice. */
+    dispose(): void;
+}
+/** Check tree data before play; throws `RangeError` naming the offending node, requirement or synergy. */
+export declare function assertSkillTreeConfig<TStat extends string>(config: SkillTreeConfig<TStat>): void;
+/**
+ * A data-authored skill tree: nodes carry a point cost, prerequisites, passives and unlocked actions,
+ * synergies pay off two or more nodes together, and `respec` refunds exactly the points spent. Spend
+ * against `canSpend` for a reason a UI can show; read `resolved()` for the stat modifiers and action
+ * list to feed `createStats` / `createAbilityKit`.
+ *
+ * @capability skill-tree spend, refuse and refund points over an authored tree with passives, actives and synergies
+ */
+export declare function createSkillTree<TStat extends string = string>(config: SkillTreeConfig<TStat>, options?: {
+    devtoolsName?: string;
+}): SkillTree<TStat>;

package/dist/progression/skillTree.js

@@ -0,0 +1,265 @@
+import { devtools } from "../devtools/devtools.js";
+const DEFAULT_BRANCH = "";
+function check(condition, message) {
+    if (!condition)
+        throw new RangeError(message);
+}
+function requirementRank(requirement) {
+    return requirement.rank ?? 1;
+}
+function mergePassives(target, source, ranks) {
+    if (source === undefined || ranks <= 0)
+        return;
+    for (const stat of Object.keys(source)) {
+        const modifier = source[stat];
+        if (modifier === undefined)
+            continue;
+        const entry = target[stat] ?? {};
+        if (modifier.add !== undefined)
+            entry.add = (entry.add ?? 0) + modifier.add * ranks;
+        if (modifier.multiply !== undefined)
+            entry.multiply = (entry.multiply ?? 1) * modifier.multiply ** ranks;
+        target[stat] = entry;
+    }
+}
+/** Check tree data before play; throws `RangeError` naming the offending node, requirement or synergy. */
+export function assertSkillTreeConfig(config) {
+    check(config.nodes.length > 0, "Skill tree needs at least one node");
+    const nodes = new Map();
+    for (const node of config.nodes) {
+        check(node.id.trim() !== "", "Skill node id must not be empty");
+        check(!nodes.has(node.id), `Skill node "${node.id}" is declared twice`);
+        nodes.set(node.id, node);
+    }
+    for (const node of config.nodes) {
+        const cost = node.cost ?? 1;
+        const maxRank = node.maxRank ?? 1;
+        check(Number.isInteger(cost) && cost >= 1, `Skill node "${node.id}" cost must be an integer >= 1`);
+        check(Number.isInteger(maxRank) && maxRank >= 1, `Skill node "${node.id}" maxRank must be an integer >= 1`);
+        const branchPoints = node.requiresPointsInBranch ?? 0;
+        check(Number.isInteger(branchPoints) && branchPoints >= 0, `Skill node "${node.id}" requiresPointsInBranch must be an integer >= 0`);
+        for (const requirement of node.requires ?? [])
+            requireNode(nodes, node.id, requirement);
+        for (const excluded of node.excludes ?? []) {
+            check(excluded !== node.id, `Skill node "${node.id}" cannot exclude itself`);
+            check(nodes.has(excluded), `Skill node "${node.id}" excludes unknown node "${excluded}"`);
+        }
+    }
+    const synergyIds = new Set();
+    for (const synergy of config.synergies ?? []) {
+        check(synergy.id.trim() !== "", "Skill synergy id must not be empty");
+        check(!synergyIds.has(synergy.id), `Skill synergy "${synergy.id}" is declared twice`);
+        synergyIds.add(synergy.id);
+        const distinct = new Set(synergy.requires.map((requirement) => requirement.nodeId));
+        check(distinct.size >= 2, `Skill synergy "${synergy.id}" must require at least two different nodes`);
+        for (const requirement of synergy.requires)
+            requireNode(nodes, synergy.id, requirement);
+    }
+    check(Number.isInteger(config.points ?? 0) && (config.points ?? 0) >= 0, "Skill tree points must be an integer >= 0");
+}
+function requireNode(nodes, owner, requirement) {
+    const target = nodes.get(requirement.nodeId);
+    if (target === undefined)
+        throw new RangeError(`"${owner}" requires unknown node "${requirement.nodeId}"`);
+    const rank = requirementRank(requirement);
+    check(Number.isInteger(rank) && rank >= 1, `"${owner}" requires an integer rank >= 1 of "${requirement.nodeId}"`);
+    const maxRank = target.maxRank ?? 1;
+    check(rank <= maxRank, `"${owner}" requires rank ${rank} of "${requirement.nodeId}", which holds ${maxRank}`);
+}
+/**
+ * A data-authored skill tree: nodes carry a point cost, prerequisites, passives and unlocked actions,
+ * synergies pay off two or more nodes together, and `respec` refunds exactly the points spent. Spend
+ * against `canSpend` for a reason a UI can show; read `resolved()` for the stat modifiers and action
+ * list to feed `createStats` / `createAbilityKit`.
+ *
+ * @capability skill-tree spend, refuse and refund points over an authored tree with passives, actives and synergies
+ */
+export function createSkillTree(config, options = {}) {
+    assertSkillTreeConfig(config);
+    const nodes = new Map();
+    for (const node of config.nodes)
+        nodes.set(node.id, node);
+    const blockedBy = new Map();
+    const block = (from, target) => {
+        const list = blockedBy.get(from);
+        if (list === undefined)
+            blockedBy.set(from, [target]);
+        else if (!list.includes(target))
+            list.push(target);
+    };
+    for (const node of config.nodes) {
+        for (const excluded of node.excludes ?? []) {
+            block(node.id, excluded);
+            block(excluded, node.id);
+        }
+    }
+    const synergies = config.synergies ?? [];
+    const branchOf = (node) => node.branch ?? DEFAULT_BRANCH;
+    const ranks = new Map();
+    let points = config.points ?? 0;
+    let cache = null;
+    const rank = (nodeId) => ranks.get(nodeId) ?? 0;
+    const pointsSpent = () => {
+        let total = 0;
+        for (const [nodeId, count] of ranks)
+            total += (nodes.get(nodeId)?.cost ?? 1) * count;
+        return total;
+    };
+    const pointsInBranch = (branch) => {
+        let total = 0;
+        for (const node of nodes.values()) {
+            if (branchOf(node) === branch)
+                total += rank(node.id);
+        }
+        return total;
+    };
+    const readSnapshot = () => {
+        const out = {};
+        for (const [nodeId, count] of ranks)
+            if (count > 0)
+                out[nodeId] = count;
+        return { points, ranks: out };
+    };
+    const canSpend = (nodeId) => {
+        const node = nodes.get(nodeId);
+        if (node === undefined)
+            return { ok: false, reason: "unknown-node", detail: `no node "${nodeId}"` };
+        const cost = node.cost ?? 1;
+        const maxRank = node.maxRank ?? 1;
+        if (rank(nodeId) >= maxRank)
+            return { ok: false, reason: "max-rank", detail: `"${nodeId}" is already at rank ${maxRank}` };
+        if (points < cost)
+            return { ok: false, reason: "no-points", detail: `"${nodeId}" costs ${cost}, ${points} available` };
+        for (const requirement of node.requires ?? []) {
+            const needed = requirementRank(requirement);
+            if (rank(requirement.nodeId) < needed) {
+                return { ok: false, reason: "requires", detail: `"${nodeId}" needs rank ${needed} of "${requirement.nodeId}"` };
+            }
+        }
+        const branchPoints = node.requiresPointsInBranch ?? 0;
+        if (branchPoints > 0) {
+            const invested = pointsInBranch(branchOf(node)) - rank(nodeId);
+            if (invested < branchPoints) {
+                return { ok: false, reason: "branch-points", detail: `"${nodeId}" needs ${branchPoints} points in branch "${branchOf(node)}"` };
+            }
+        }
+        for (const excluded of blockedBy.get(nodeId) ?? []) {
+            if (rank(excluded) > 0)
+                return { ok: false, reason: "excluded", detail: `"${nodeId}" cannot be ranked beside "${excluded}"` };
+        }
+        return { ok: true, spent: cost, pointsAvailable: points - cost };
+    };
+    const resolve = () => {
+        const stats = {};
+        const actives = [];
+        const seenActives = new Set();
+        const addActives = (list) => {
+            for (const active of list ?? []) {
+                if (seenActives.has(active.id))
+                    continue;
+                seenActives.add(active.id);
+                actives.push({ ...active });
+            }
+        };
+        for (const node of nodes.values()) {
+            const count = rank(node.id);
+            if (count <= 0)
+                continue;
+            mergePassives(stats, node.passives, count);
+            addActives(node.actives);
+        }
+        const live = [];
+        for (const synergy of synergies) {
+            const satisfied = synergy.requires.every((requirement) => rank(requirement.nodeId) >= requirementRank(requirement));
+            if (!satisfied)
+                continue;
+            live.push(synergy.id);
+            mergePassives(stats, synergy.passives, 1);
+            addActives(synergy.actives);
+        }
+        const ranksOut = {};
+        for (const nodeId of [...ranks.keys()].sort())
+            ranksOut[nodeId] = rank(nodeId);
+        return {
+            stats,
+            actives,
+            activeIds: actives.map((active) => active.id),
+            synergies: live,
+            ranks: ranksOut,
+            pointsSpent: pointsSpent(),
+            pointsAvailable: points,
+        };
+    };
+    const probe = options.devtoolsName === undefined
+        ? null
+        : devtools.probes.register(options.devtoolsName, () => {
+            const resolved = resolve();
+            return {
+                pointsAvailable: resolved.pointsAvailable,
+                pointsSpent: resolved.pointsSpent,
+                ranks: resolved.ranks,
+                synergies: resolved.synergies,
+                actives: resolved.activeIds,
+            };
+        });
+    const tree = {
+        rank,
+        pointsAvailable: () => points,
+        pointsSpent,
+        pointsInBranch,
+        grantPoints(amount) {
+            if (!Number.isInteger(amount) || amount <= 0)
+                return;
+            points += amount;
+            cache = null;
+        },
+        canSpend,
+        spend(nodeId) {
+            const result = canSpend(nodeId);
+            if (!result.ok)
+                return result;
+            points -= result.spent;
+            ranks.set(nodeId, rank(nodeId) + 1);
+            cache = null;
+            return { ok: true, spent: result.spent, pointsAvailable: points };
+        },
+        respec() {
+            const refunded = pointsSpent();
+            points += refunded;
+            ranks.clear();
+            cache = null;
+            return { refunded, pointsAvailable: points };
+        },
+        resolved() {
+            cache ??= resolve();
+            return cache;
+        },
+        snapshot: readSnapshot,
+        restore(next) {
+            if (!Number.isInteger(next.points) || next.points < 0)
+                return false;
+            if (next.ranks === null || typeof next.ranks !== "object")
+                return false;
+            const restored = new Map();
+            for (const [nodeId, count] of Object.entries(next.ranks)) {
+                const node = nodes.get(nodeId);
+                if (node === undefined)
+                    return false;
+                if (!Number.isInteger(count) || count < 0 || count > (node.maxRank ?? 1))
+                    return false;
+                if (count > 0)
+                    restored.set(nodeId, count);
+            }
+            points = next.points;
+            ranks.clear();
+            for (const [nodeId, count] of restored)
+                ranks.set(nodeId, count);
+            cache = null;
+            return true;
+        },
+        dispose() {
+            probe?.();
+        },
+    };
+    return tree;
+}

package/dist/progression/xpCurve.d.ts

@@ -0,0 +1,60 @@
+import { type LevelProgress, type LevelingTrack } from "../game/progression.js";
+/** Named rule a level threshold grows by. `flat` repeats `step`; `linear` adds `growthRate` per level; `power` uses `level ^ growthRate`; `geometric` multiplies by `growthRate`; `table` reads `table`. */
+export type XpGrowthRule = "flat" | "linear" | "power" | "geometric" | "table";
+/**
+ * Authorable XP curve data. Thresholds are generated from one growth rule, so a game states its
+ * curve and its cap instead of hand-writing a table it cannot rebalance, and every consumer of the
+ * same data agrees on the numbers.
+ */
+export interface XpCurveDef {
+    growth: XpGrowthRule;
+    /** XP needed for the first level-up (from `startLevel` to `startLevel + 1`). */
+    step: number;
+    /** Growth parameter: added XP per level (`linear`), the exponent (`power`) or the ratio (`geometric`). Ignored by `flat` and `table`. */
+    growthRate?: number;
+    /** Explicit thresholds for `growth: "table"`, index `0` being the first level-up. */
+    table?: readonly number[];
+    /** Highest reachable level. */
+    maxLevel: number;
+    /** First level of the curve (default `1`). */
+    startLevel?: number;
+    /** Rounding of generated thresholds (default `ceil`, so no level costs a fraction of XP). */
+    round?: "floor" | "ceil" | "round";
+}
+/** One row of a resolved curve: the threshold at `level`, and the lifetime XP it sits at. */
+export interface XpLevelStep {
+    level: number;
+    /** XP that leaves this level; `0` at the cap. */
+    xpForLevel: number;
+    /** XP accumulated from `startLevel` to reach `level`; `0` at the first level. */
+    totalXp: number;
+}
+/** A resolved, validated {@link XpCurveDef}: thresholds, lifetime totals, a stated rule, and a leveling track bound to the same numbers. */
+export interface XpCurve {
+    /** Detached copy of the curve data, safe to save or send to a client. */
+    readonly def: XpCurveDef;
+    readonly maxLevel: number;
+    readonly startLevel: number;
+    /** The growth rule written out, e.g. `"power: 80 x level^1.45, ceil (levels 1-40)"`. */
+    readonly rule: string;
+    /** XP the given level requires to advance; `0` at or past `maxLevel`. */
+    xpForLevel(level: number): number;
+    /** Lifetime XP needed to reach `level` from `startLevel`. */
+    totalXpFor(level: number): number;
+    /** Resolve accumulated XP into a settled level, surplus and next threshold. */
+    levelForXp(totalXp: number): LevelProgress;
+    /** Every level of the curve with its threshold and lifetime XP. */
+    table(): readonly XpLevelStep[];
+    /** A `leveling` track configured with these exact thresholds and cap, for stat-adapter grants. */
+    track(): LevelingTrack;
+}
+/** Check curve data before use; throws `RangeError` naming the offending field. */
+export declare function assertXpCurve(def: XpCurveDef): void;
+/**
+ * Resolve authored XP curve data: the threshold per level, the lifetime XP it sits at, a plain-words
+ * growth rule, and the level an XP total reaches under the cap. One data record with one growth rule
+ * keeps a rebalance in the save-visible definition rather than in formulas scattered across a game.
+ *
+ * @capability xp-curve resolve an authored xp growth rule into per-level thresholds, totals and a level cap
+ */
+export declare function defineXpCurve(def: XpCurveDef): XpCurve;

package/dist/progression/xpCurve.js

@@ -0,0 +1,141 @@
+import { evalCurve, leveling } from "../game/progression.js";
+function check(condition, message) {
+    if (!condition)
+        throw new RangeError(message);
+}
+function curveDefOf(def) {
+    switch (def.growth) {
+        case "flat":
+            return { kind: "const", value: def.step };
+        case "linear":
+            return { kind: "linear", base: def.step, per: def.growthRate ?? 0 };
+        case "power":
+            return { kind: "power", base: def.step, exponent: def.growthRate ?? 1 };
+        case "geometric":
+            return { kind: "geometric", base: def.step, ratio: def.growthRate ?? 1 };
+        case "table":
+            return null;
+    }
+}
+function describeRule(def, startLevel) {
+    const round = def.round ?? "ceil";
+    const span = `levels ${startLevel}-${def.maxLevel}`;
+    switch (def.growth) {
+        case "flat":
+            return `flat: ${def.step} xp per level, ${round} (${span})`;
+        case "linear":
+            return `linear: ${def.step} + ${def.growthRate ?? 0} x (level - ${startLevel}), ${round} (${span})`;
+        case "power":
+            return `power: ${def.step} x level^${def.growthRate ?? 1}, ${round} (${span})`;
+        case "geometric":
+            return `geometric: ${def.step} x ${def.growthRate ?? 1}^(level - ${startLevel}), ${round} (${span})`;
+        case "table":
+            return `table: ${def.table?.length ?? 0} thresholds (${span})`;
+    }
+}
+/** Check curve data before use; throws `RangeError` naming the offending field. */
+export function assertXpCurve(def) {
+    const startLevel = def.startLevel ?? 1;
+    check(Number.isInteger(startLevel) && startLevel >= 1, `XP curve startLevel must be an integer >= 1; got ${String(def.startLevel)}`);
+    check(Number.isInteger(def.maxLevel) && def.maxLevel > startLevel, `XP curve maxLevel must be an integer above startLevel ${startLevel}; got ${String(def.maxLevel)}`);
+    check(Number.isFinite(def.step) && def.step > 0, `XP curve step must be positive; got ${String(def.step)}`);
+    if (def.growth === "linear") {
+        check(Number.isFinite(def.growthRate ?? 0) && (def.growthRate ?? 0) >= 0, "XP curve linear growthRate must be finite and >= 0");
+    }
+    if (def.growth === "power") {
+        check(Number.isFinite(def.growthRate ?? 1) && (def.growthRate ?? 1) > 0, "XP curve power growthRate must be positive");
+    }
+    if (def.growth === "geometric") {
+        check(Number.isFinite(def.growthRate ?? 1) && (def.growthRate ?? 1) > 0, "XP curve geometric growthRate must be positive");
+    }
+    if (def.growth === "table") {
+        const needed = def.maxLevel - startLevel;
+        check((def.table?.length ?? 0) >= needed, `XP curve table needs ${needed} thresholds for ${needed} level-ups`);
+        for (const value of def.table ?? [])
+            check(Number.isFinite(value) && value > 0, `XP curve table values must be positive; got ${String(value)}`);
+    }
+}
+/**
+ * Resolve authored XP curve data: the threshold per level, the lifetime XP it sits at, a plain-words
+ * growth rule, and the level an XP total reaches under the cap. One data record with one growth rule
+ * keeps a rebalance in the save-visible definition rather than in formulas scattered across a game.
+ *
+ * @capability xp-curve resolve an authored xp growth rule into per-level thresholds, totals and a level cap
+ */
+export function defineXpCurve(def) {
+    assertXpCurve(def);
+    const startLevel = def.startLevel ?? 1;
+    const maxLevel = def.maxLevel;
+    const round = def.round ?? "ceil";
+    const growthCurve = curveDefOf(def);
+    const rawThreshold = (level) => {
+        if (growthCurve === null) {
+            const index = level - startLevel;
+            const table = def.table ?? [];
+            return table[Math.min(index, table.length - 1)] ?? 0;
+        }
+        const relative = level - startLevel + 1;
+        const x = growthCurve.kind === "linear" || growthCurve.kind === "geometric" ? relative - 1 : relative;
+        return evalCurve({ ...growthCurve, round }, x);
+    };
+    const xpForLevel = (level) => {
+        if (level >= maxLevel)
+            return 0;
+        const clamped = Math.max(startLevel, Math.min(level, maxLevel - 1));
+        return Math.max(1, rawThreshold(clamped));
+    };
+    const totalXpFor = (level) => {
+        const clamped = Math.max(startLevel, Math.min(level, maxLevel));
+        let total = 0;
+        for (let current = startLevel; current < clamped; current += 1)
+            total += xpForLevel(current);
+        return total;
+    };
+    const readTable = () => {
+        const rows = [];
+        let total = 0;
+        for (let level = startLevel; level <= maxLevel; level += 1) {
+            const threshold = xpForLevel(level);
+            rows.push({ level, xpForLevel: threshold, totalXp: total });
+            total += threshold;
+        }
+        return rows;
+    };
+    const copy = {
+        growth: def.growth,
+        step: def.step,
+        maxLevel,
+        startLevel,
+        round,
+        ...(def.growthRate === undefined ? {} : { growthRate: def.growthRate }),
+        ...(def.table === undefined ? {} : { table: [...def.table] }),
+    };
+    let trackCache = null;
+    const buildTrack = () => leveling({
+        // `steps` indexes by level number, so the array is level-addressed rather than offset.
+        xpForLevel: {
+            kind: "steps",
+            values: Array.from({ length: maxLevel + 1 }, (_, level) => xpForLevel(Math.max(startLevel, level))),
+        },
+        maxLevel,
+        startLevel,
+        thresholdMode: "perLevel",
+    });
+    return {
+        def: copy,
+        maxLevel,
+        startLevel,
+        rule: describeRule(copy, startLevel),
+        xpForLevel,
+        totalXpFor,
+        levelForXp(totalXp) {
+            trackCache ??= buildTrack();
+            return trackCache.resolve(startLevel, totalXp);
+        },
+        table: readTable,
+        track() {
+            trackCache ??= buildTrack();
+            return trackCache;
+        },
+    };
+}

package/dist/scene/builtinSceneKinds.js

@@ -13,6 +13,7 @@ import { registerWaterKind } from "../world/waterKind.js";
 import { registerGrassKind } from "../world/grassKind.js";
 import { registerSoilKind } from "../world/soilKind.js";
 import { registerPoleLineKind } from "../world/poleLineKind.js";
+import { registerDecalKind } from "../world/decalKind.js";
 import { registerBuildingGenerator } from "../world/buildingGenerator.js";
 import { registerCityKind } from "../world/cityKind.js";
 import { describeScatterCoverage, densityCoverage } from "../world/scatterCoverage.js";
@@ -80,5 +81,6 @@ export function registerBuiltinSceneKinds() {
     registerSoilKind();
     registerCityKind();
     registerPoleLineKind();
+    registerDecalKind();
     registerBuildingGenerator();
 }