@jgengine/core 0.9.0 → 0.11.0

package/dist/item/itemgen.d.ts

@@ -0,0 +1,163 @@
+/**
+ * One selectable option in a generation step's pool: a stable `id` used in provenance and pinning,
+ * the payload `value` a chosen option contributes, and an optional relative `weight` (default 1).
+ */
+export interface GenOption<V = unknown> {
+    id: string;
+    value: V;
+    weight?: number;
+}
+/**
+ * Read-only view of the choices resolved so far, threaded into a later step's pool, constraint,
+ * weight function, or transform so a decision can depend on earlier picks (dependent choice).
+ */
+export interface GenChoices {
+    /** Whether a step has resolved to a (non-skipped) option. */
+    has(step: string): boolean;
+    /** The chosen option id for a step, or undefined if unresolved or skipped. */
+    optionId(step: string): string | undefined;
+    /** The chosen option value for a step, or undefined if unresolved or skipped. */
+    value<V = unknown>(step: string): V | undefined;
+}
+/**
+ * A step's candidate options: a fixed list, or a function of the choices resolved so far so pools
+ * can narrow to earlier picks (a slot pool that depends on a chosen category).
+ */
+export type GenPool<V = unknown> = readonly GenOption<V>[] | ((choices: GenChoices) => readonly GenOption<V>[]);
+/**
+ * One decision point in a {@link GenSchema}: pick a single option from a pool, honoring an optional
+ * constraint, dependent weighting, selection mode, and optionality. Steps resolve in array order.
+ */
+export interface GenStep<V = unknown> {
+    id: string;
+    pool: GenPool<V>;
+    /** `"weighted"` (default) picks proportional to weight; `"uniform"` ignores weight and picks evenly. */
+    select?: "weighted" | "uniform";
+    /** Constraint: only options for which this returns true are eligible, given the earlier choices. */
+    accept?: (option: GenOption<V>, choices: GenChoices) => boolean;
+    /** Override an option's weight as a function of earlier choices; falls back to `option.weight ?? 1`. */
+    weightOf?: (option: GenOption<V>, choices: GenChoices) => number;
+    /** When no option is eligible, skip this step instead of failing or backtracking. */
+    optional?: boolean;
+}
+/**
+ * Mutation surface a {@link GenTransform} uses to derive numeric fields after choices resolve.
+ * Every `set`/`add`/`mul` is captured as a {@link GenFieldRecord}, and `rng` is the same injected
+ * stream the choices drew from, so rolled derivations stay deterministic and explainable.
+ */
+export interface TransformApi {
+    readonly choices: GenChoices;
+    readonly rng: () => number;
+    /** Current value of a field, or 0 if unset. */
+    get(field: string): number;
+    /** Replace a field's value, recording the change. */
+    set(field: string, value: number, note?: string): void;
+    /** Add to a field's value, recording the change. */
+    add(field: string, amount: number, note?: string): void;
+    /** Multiply a field's value, recording the change. */
+    mul(field: string, factor: number, note?: string): void;
+}
+/**
+ * A named derivation over the numeric field bag, applied in schema order after all choices resolve
+ * (affix rolls, level scaling, budget spend). Each field mutation it makes is recorded as provenance.
+ */
+export interface GenTransform {
+    id: string;
+    apply: (api: TransformApi) => void;
+}
+/**
+ * The resolved-but-unvalidated draft passed to each {@link GenValidator}: the step choices, their
+ * values, and the transformed fields. Returning false from any validator rerolls the whole
+ * generation up to the attempt budget.
+ */
+export interface GenDraft {
+    choices: Readonly<Record<string, string>>;
+    values: Readonly<Record<string, unknown>>;
+    fields: Readonly<Record<string, number>>;
+}
+/** A final-assembly check over a {@link GenDraft}; false triggers a whole-pipeline reroll. */
+export type GenValidator = (draft: GenDraft) => boolean;
+/**
+ * Provenance for one resolved step: which option stuck, its effective weight, how many options were
+ * eligible after constraints, and how many eligible options backtracking rejected before this one.
+ * A skipped optional step is recorded with an empty `optionId`.
+ */
+export interface GenChoiceRecord {
+    step: string;
+    optionId: string;
+    weight: number;
+    eligible: number;
+    rerolls: number;
+}
+/** Provenance for one field mutation a transform made: which transform, field, op, and before/after. */
+export interface GenFieldRecord {
+    transform: string;
+    field: string;
+    op: "set" | "add" | "mul";
+    from: number;
+    to: number;
+    note?: string;
+}
+/**
+ * The full explanation of a generated result: how many whole-pipeline attempts it took, every step
+ * choice, and every field mutation. Plain, serializable data for UI, debugging, balancing, and
+ * regeneration.
+ */
+export interface GenProvenance {
+    attempts: number;
+    choices: readonly GenChoiceRecord[];
+    fields: readonly GenFieldRecord[];
+}
+/**
+ * A successful generation: the step-to-option map, step-to-value map, transformed numeric fields,
+ * and the {@link GenProvenance} that explains them. Entirely serializable; round-trips through
+ * save/load and multiplayer sync unchanged.
+ */
+export interface GenResult {
+    choices: Readonly<Record<string, string>>;
+    values: Readonly<Record<string, unknown>>;
+    fields: Readonly<Record<string, number>>;
+    provenance: GenProvenance;
+}
+/**
+ * The outcome of {@link generate}: either a successful {@link GenResult}, or a failure carrying the
+ * reason (`"unsatisfiable"` — constraints left no valid assignment; `"rejected"` — validators kept
+ * rejecting drafts) and the attempts spent.
+ */
+export type GenOutcome = {
+    ok: true;
+    result: GenResult;
+} | {
+    ok: false;
+    reason: "unsatisfiable" | "rejected";
+    attempts: number;
+};
+/**
+ * A caller-defined generation schema over plain data: ordered choice steps, optional field
+ * transforms, optional validators, and bounded reroll/backtracking budgets. Genre-agnostic — it
+ * carries no built-in notion of rarity, element, weapon, or name; those are caller step and option ids.
+ */
+export interface GenSchema {
+    steps: readonly GenStep[];
+    transforms?: readonly GenTransform[];
+    validate?: readonly GenValidator[];
+    /** Max whole-pipeline attempts when a validator rejects a draft (default 24). */
+    maxAttempts?: number;
+    /** Max option picks the backtracking search may spend satisfying constraints in one attempt (default 1024). */
+    maxPicks?: number;
+}
+/** Per-call options for {@link generate}. */
+export interface GenerateOptions {
+    /** Force a step to a specific option id, consuming no rng for it (a requested rarity or family). */
+    pin?: Readonly<Record<string, string>>;
+}
+/**
+ * Run a caller-defined {@link GenSchema} against an injected `rng` into a deterministic, serializable
+ * {@link GenResult} with full provenance. Composes weighted/uniform choice, dependent choice,
+ * constraints with bounded backtracking, field transforms, and validation reroll over plain data —
+ * the generic seam procedural loot, affix, and modular-part rollers assemble on. Identical schema,
+ * seed, and pins reproduce an identical result across server/client and save/load.
+ *
+ * @capability item-generation compose constraints, weighted pools, transforms, and provenance into a deterministic generated item
+ */
+export declare function generate(schema: GenSchema, rng: () => number, options?: GenerateOptions): GenOutcome;

package/dist/item/itemgen.js

@@ -0,0 +1,151 @@
+import { pickUniform, pickWeighted } from "../random/pick.js";
+function makeChoicesView(chosen) {
+    const find = (step) => {
+        for (const c of chosen)
+            if (c.step === step && !c.skipped)
+                return c;
+        return undefined;
+    };
+    return {
+        has: (step) => find(step) !== undefined,
+        optionId: (step) => find(step)?.optionId,
+        value: (step) => find(step)?.value,
+    };
+}
+function poolFor(pool, choices) {
+    return typeof pool === "function" ? pool(choices) : pool;
+}
+/**
+ * Run a caller-defined {@link GenSchema} against an injected `rng` into a deterministic, serializable
+ * {@link GenResult} with full provenance. Composes weighted/uniform choice, dependent choice,
+ * constraints with bounded backtracking, field transforms, and validation reroll over plain data —
+ * the generic seam procedural loot, affix, and modular-part rollers assemble on. Identical schema,
+ * seed, and pins reproduce an identical result across server/client and save/load.
+ *
+ * @capability item-generation compose constraints, weighted pools, transforms, and provenance into a deterministic generated item
+ */
+export function generate(schema, rng, options = {}) {
+    const maxAttempts = schema.maxAttempts ?? 24;
+    const maxPicks = schema.maxPicks ?? 1024;
+    const pin = options.pin;
+    let lastReason = "unsatisfiable";
+    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+        const chosen = [];
+        const view = makeChoicesView(chosen);
+        let picks = 0;
+        const weightGetter = (step) => (option) => step.weightOf !== undefined ? step.weightOf(option, view) : option.weight ?? 1;
+        const solve = (index) => {
+            if (index >= schema.steps.length)
+                return true;
+            const step = schema.steps[index];
+            const pinId = pin?.[step.id];
+            if (pinId !== undefined) {
+                const option = poolFor(step.pool, view).find((candidate) => candidate.id === pinId);
+                if (option === undefined)
+                    return false;
+                chosen.push({
+                    step: step.id,
+                    optionId: option.id,
+                    value: option.value,
+                    weight: weightGetter(step)(option),
+                    eligible: 1,
+                    rerolls: 0,
+                    skipped: false,
+                });
+                if (solve(index + 1))
+                    return true;
+                chosen.pop();
+                return false;
+            }
+            const accept = step.accept;
+            let remaining = poolFor(step.pool, view).filter((option) => accept === undefined || accept(option, view));
+            const eligibleCount = remaining.length;
+            if (eligibleCount === 0) {
+                if (step.optional !== true)
+                    return false;
+                chosen.push({ step: step.id, optionId: "", value: undefined, weight: 0, eligible: 0, rerolls: 0, skipped: true });
+                if (solve(index + 1))
+                    return true;
+                chosen.pop();
+                return false;
+            }
+            let tried = 0;
+            while (remaining.length > 0) {
+                if (picks >= maxPicks)
+                    return false;
+                picks += 1;
+                const picked = step.select === "uniform"
+                    ? pickUniform(rng, remaining)
+                    : pickWeighted(rng, remaining, weightGetter(step));
+                if (picked === undefined)
+                    return false;
+                chosen.push({
+                    step: step.id,
+                    optionId: picked.id,
+                    value: picked.value,
+                    weight: weightGetter(step)(picked),
+                    eligible: eligibleCount,
+                    rerolls: tried,
+                    skipped: false,
+                });
+                if (solve(index + 1))
+                    return true;
+                chosen.pop();
+                remaining = remaining.filter((option) => option !== picked);
+                tried += 1;
+            }
+            return false;
+        };
+        if (!solve(0)) {
+            lastReason = "unsatisfiable";
+            continue;
+        }
+        const choices = {};
+        const values = {};
+        const choiceRecords = [];
+        for (const entry of chosen) {
+            choiceRecords.push({
+                step: entry.step,
+                optionId: entry.optionId,
+                weight: entry.weight,
+                eligible: entry.eligible,
+                rerolls: entry.rerolls,
+            });
+            if (entry.skipped)
+                continue;
+            choices[entry.step] = entry.optionId;
+            values[entry.step] = entry.value;
+        }
+        const fields = {};
+        const fieldRecords = [];
+        const record = (transform, op, field, from, to, note) => {
+            fields[field] = to;
+            const entry = { transform, field, op, from, to };
+            if (note !== undefined)
+                entry.note = note;
+            fieldRecords.push(entry);
+        };
+        for (const transform of schema.transforms ?? []) {
+            const api = {
+                choices: view,
+                rng,
+                get: (field) => fields[field] ?? 0,
+                set: (field, value, note) => record(transform.id, "set", field, fields[field] ?? 0, value, note),
+                add: (field, amount, note) => record(transform.id, "add", field, fields[field] ?? 0, (fields[field] ?? 0) + amount, note),
+                mul: (field, factor, note) => record(transform.id, "mul", field, fields[field] ?? 0, (fields[field] ?? 0) * factor, note),
+            };
+            transform.apply(api);
+        }
+        const draft = { choices, values, fields };
+        const validators = schema.validate ?? [];
+        if (!validators.every((validate) => validate(draft))) {
+            lastReason = "rejected";
+            continue;
+        }
+        return {
+            ok: true,
+            result: { choices, values, fields, provenance: { attempts: attempt, choices: choiceRecords, fields: fieldRecords } },
+        };
+    }
+    return { ok: false, reason: lastReason, attempts: maxAttempts };
+}

package/dist/item/modularItem.d.ts

@@ -26,6 +26,11 @@ export type InstallResult = {
     reason: "unknown-slot" | "wrong-category" | "slot-occupied";
 };
 export declare function slotById(def: ModularItemDef, slotId: string): MountSlotDef | null;
+/**
+ * Attach parts into an item's mount slots and resolve the combined stats.
+ *
+ * @capability modular-item attach parts into item mount slots to compute combined stats
+ */
 export declare function slotAccepts(slot: MountSlotDef, category: string): boolean;
 export declare function install(def: ModularItemDef, installed: readonly InstalledPart[], slotId: string, part: PartDef): InstallResult;
 export declare function uninstall(installed: readonly InstalledPart[], slotId: string): readonly InstalledPart[];

package/dist/item/modularItem.js

@@ -1,6 +1,11 @@
 export function slotById(def, slotId) {
     return def.slots.find((s) => s.id === slotId) ?? null;
 }
+/**
+ * Attach parts into an item's mount slots and resolve the combined stats.
+ *
+ * @capability modular-item attach parts into item mount slots to compute combined stats
+ */
 export function slotAccepts(slot, category) {
     return typeof slot.accepts === "string" ? slot.accepts === category : slot.accepts.includes(category);
 }

package/dist/item/use.d.ts

@@ -22,4 +22,9 @@ export interface ItemUse<TState> {
     can(state: TState, input: ItemUseInput): ItemUseRejection | null;
     use(state: TState, input: ItemUseInput): ItemUseResult<TState>;
 }
+/**
+ * Use or consume items, applying their effects and per-item cooldowns.
+ *
+ * @capability consumables use/consume items with cooldowns and effects
+ */
 export declare function createItemUse<TState>(resolveUse: (itemId: string) => string | null | undefined): ItemUse<TState>;

package/dist/item/use.js

@@ -1,3 +1,8 @@
+/**
+ * Use or consume items, applying their effects and per-item cooldowns.
+ *
+ * @capability consumables use/consume items with cooldowns and effects
+ */
 export function createItemUse(resolveUse) {
     const handlers = new Map();
     function resolveHandler(itemId) {

package/dist/item/useBehavior.d.ts

@@ -0,0 +1,142 @@
+import type { ItemUseInput } from "./use.js";
+/**
+ * Per-behavior configuration stored on an item as plain data (e.g. charge time,
+ * projectile id). Kept opaque here so no game noun leaks into item core.
+ */
+export type BehaviorConfig = Record<string, unknown>;
+/**
+ * A single behavior's mutable, serializable runtime state (e.g. current charge,
+ * rounds queued). Composed state is a map of these keyed by behavior id.
+ */
+export type BehaviorState = Record<string, unknown>;
+/**
+ * A serialized snapshot of every behavior's state on one item, keyed by
+ * behavior id. Round-trips through JSON so it can live in a saved game.
+ */
+export type SerializedBehaviorState = Record<string, BehaviorState>;
+/**
+ * The reference an item stores for one composed behavior: a stable behavior id,
+ * optional config, and an optional order override. Pure data — the item core
+ * never holds the implementation, only this reference.
+ */
+export interface UseBehaviorRef {
+    id: string;
+    config?: BehaviorConfig;
+    order?: number;
+}
+/**
+ * The context handed to each behavior hook: the shared folded `world`, this
+ * behavior's own `config` and `state` slice, and the triggering use input.
+ */
+export interface UseBehaviorContext<TWorld> {
+    world: TWorld;
+    config: BehaviorConfig;
+    state: BehaviorState;
+    input: ItemUseInput;
+}
+/**
+ * The result of applying one behavior: the (possibly advanced) world, this
+ * behavior's updated state, an optional error that aborts the chain, and an
+ * optional `stop` that ends the chain after a successful apply.
+ */
+export interface UseBehaviorOutcome<TWorld> {
+    world: TWorld;
+    state?: BehaviorState;
+    error?: string;
+    stop?: boolean;
+}
+/** A reason a behavior refused a use, surfaced from `can`. */
+export interface UseBehaviorRejection {
+    reason: string;
+}
+/**
+ * A registered behavior implementation. The combat/game side registers these
+ * (charge, thrown-reload, projectile-replacement, …); the item core only ever
+ * stores a {@link UseBehaviorRef} to one by id. Hooks are the lifecycle: `init`
+ * builds serializable state, `can` gates, `apply` folds the world.
+ */
+export interface UseBehaviorDef<TWorld> {
+    id: string;
+    /** Lower runs first; ties break on the item's ref order. Default 0. */
+    order?: number;
+    /** Capability tokens the host must supply at compose time for this behavior. */
+    requires?: readonly string[];
+    /** Behavior ids that cannot coexist with this one on the same item. */
+    conflicts?: readonly string[];
+    /** Build initial serializable state from config; defaults to an empty object. */
+    init?(config: BehaviorConfig): BehaviorState;
+    /** Gate the use before applying; return a rejection or null to allow. */
+    can?(ctx: UseBehaviorContext<TWorld>): UseBehaviorRejection | null;
+    /** Apply the behavior, folding the shared world and this behavior's state. */
+    apply(ctx: UseBehaviorContext<TWorld>): UseBehaviorOutcome<TWorld>;
+}
+/**
+ * A resolved, ordered composition of behaviors for one item. Dispatch is
+ * transactional: `apply` commits the folded world only if every behavior in the
+ * chain succeeds, otherwise it returns the original world and state plus the
+ * first error.
+ */
+export interface ComposedUse<TWorld> {
+    /** The resolved run order as behavior ids. */
+    order(): readonly string[];
+    /** Fresh per-behavior state for a new item instance, keyed by behavior id. */
+    initialState(): SerializedBehaviorState;
+    /** First rejection across behaviors (in order), or null if all allow the use. */
+    can(world: TWorld, state: SerializedBehaviorState, input: ItemUseInput): UseBehaviorRejection | null;
+    /** Run the chain in order; commit folded world+state only on full success. */
+    apply(world: TWorld, state: SerializedBehaviorState, input: ItemUseInput): {
+        world: TWorld;
+        state: SerializedBehaviorState;
+        error?: string;
+    };
+}
+/**
+ * The outcome of composing an item's behavior refs: either a ready
+ * {@link ComposedUse} or a structured error naming the offending behavior.
+ */
+export type CompositionResult<TWorld> = {
+    status: "ok";
+    composed: ComposedUse<TWorld>;
+} | {
+    status: "error";
+    reason: "unknown-behavior";
+    id: string;
+} | {
+    status: "error";
+    reason: "duplicate-behavior";
+    id: string;
+} | {
+    status: "error";
+    reason: "missing-capability";
+    id: string;
+    capability: string;
+} | {
+    status: "error";
+    reason: "conflict";
+    id: string;
+    conflictsWith: string;
+};
+/**
+ * A registry of use-behavior implementations plus a composer that turns an
+ * item's stored refs into an ordered, conflict-checked {@link ComposedUse}.
+ */
+export interface UseBehaviorRegistry<TWorld> {
+    /** Register behavior implementations; throws on a duplicate id. */
+    register(defs: readonly UseBehaviorDef<TWorld>[]): void;
+    has(id: string): boolean;
+    get(id: string): UseBehaviorDef<TWorld> | null;
+    /** All registered behavior ids, in registration order. */
+    ids(): string[];
+    /** Resolve an item's refs into a composed dispatcher, or a structured error. */
+    compose(refs: readonly UseBehaviorRef[], options?: {
+        capabilities?: readonly string[];
+    }): CompositionResult<TWorld>;
+}
+/**
+ * Create an empty use-behavior registry. Games register their behaviors, then
+ * compose each item's stored refs into a dispatcher whose serializable state
+ * lives with the item.
+ *
+ * @capability item-use-composition compose pluggable, ordered item use-behaviors from serializable references
+ */
+export declare function createUseBehaviorRegistry<TWorld>(): UseBehaviorRegistry<TWorld>;

package/dist/item/useBehavior.js

@@ -0,0 +1,105 @@
+function orderOf(entry) {
+    return entry.ref.order ?? entry.def.order ?? 0;
+}
+/**
+ * Create an empty use-behavior registry. Games register their behaviors, then
+ * compose each item's stored refs into a dispatcher whose serializable state
+ * lives with the item.
+ *
+ * @capability item-use-composition compose pluggable, ordered item use-behaviors from serializable references
+ */
+export function createUseBehaviorRegistry() {
+    const defs = new Map();
+    function compose(refs, options) {
+        const capabilities = new Set(options?.capabilities ?? []);
+        const seen = new Set();
+        const resolved = [];
+        for (const ref of refs) {
+            if (seen.has(ref.id))
+                return { status: "error", reason: "duplicate-behavior", id: ref.id };
+            seen.add(ref.id);
+            const def = defs.get(ref.id);
+            if (def === undefined)
+                return { status: "error", reason: "unknown-behavior", id: ref.id };
+            for (const capability of def.requires ?? []) {
+                if (!capabilities.has(capability))
+                    return { status: "error", reason: "missing-capability", id: ref.id, capability };
+            }
+            resolved.push({ ref, def });
+        }
+        for (const { def } of resolved) {
+            for (const conflict of def.conflicts ?? []) {
+                if (seen.has(conflict))
+                    return { status: "error", reason: "conflict", id: def.id, conflictsWith: conflict };
+            }
+        }
+        const ordered = resolved
+            .map((entry, index) => ({ entry, index }))
+            .sort((a, b) => orderOf(a.entry) - orderOf(b.entry) || a.index - b.index)
+            .map(({ entry }) => entry);
+        const composed = {
+            order() {
+                return ordered.map((entry) => entry.def.id);
+            },
+            initialState() {
+                const state = {};
+                for (const entry of ordered)
+                    state[entry.def.id] = entry.def.init?.(entry.ref.config ?? {}) ?? {};
+                return state;
+            },
+            can(world, state, input) {
+                for (const entry of ordered) {
+                    const rejection = entry.def.can?.({
+                        world,
+                        config: entry.ref.config ?? {},
+                        state: state[entry.def.id] ?? {},
+                        input,
+                    });
+                    if (rejection)
+                        return rejection;
+                }
+                return null;
+            },
+            apply(world, state, input) {
+                let nextWorld = world;
+                const nextState = { ...state };
+                for (const entry of ordered) {
+                    const config = entry.ref.config ?? {};
+                    const ctx = { world: nextWorld, config, state: nextState[entry.def.id] ?? {}, input };
+                    const rejection = entry.def.can?.(ctx);
+                    if (rejection)
+                        return { world, state, error: rejection.reason };
+                    const outcome = entry.def.apply(ctx);
+                    if (outcome.error !== undefined)
+                        return { world, state, error: outcome.error };
+                    nextWorld = outcome.world;
+                    if (outcome.state !== undefined)
+                        nextState[entry.def.id] = outcome.state;
+                    if (outcome.stop === true)
+                        break;
+                }
+                return { world: nextWorld, state: nextState };
+            },
+        };
+        return { status: "ok", composed };
+    }
+    return {
+        register(newDefs) {
+            for (const def of newDefs) {
+                if (defs.has(def.id))
+                    throw new Error(`Use behavior "${def.id}" is already registered.`);
+                defs.set(def.id, def);
+            }
+        },
+        has(id) {
+            return defs.has(id);
+        },
+        get(id) {
+            return defs.get(id) ?? null;
+        },
+        ids() {
+            return [...defs.keys()];
+        },
+        compose,
+    };
+}

package/dist/item/weapon.d.ts

@@ -5,4 +5,9 @@ export declare function getWeaponStat(entry: WeaponEntry | null | undefined, sta
 export interface WeaponStats {
     getStat(itemId: string, stat: string): number | null;
 }
+/**
+ * Resolve per-weapon stat values — damage, fire rate, spread — for combat math.
+ *
+ * @capability weapon-stats resolve per-weapon stat values for combat math
+ */
 export declare function createWeaponStats(resolveEntry: (itemId: string) => WeaponEntry | null | undefined): WeaponStats;

package/dist/item/weapon.js

@@ -9,6 +9,11 @@ export function getWeaponStat(entry, stat) {
     }
     return typeof value === "number" ? value : null;
 }
+/**
+ * Resolve per-weapon stat values — damage, fire rate, spread — for combat math.
+ *
+ * @capability weapon-stats resolve per-weapon stat values for combat math
+ */
 export function createWeaponStats(resolveEntry) {
     return {
         getStat(itemId, stat) {

package/dist/math/scalar.d.ts

@@ -0,0 +1,25 @@
+export { lerp, clamp01, smoothstep } from "../anim/easing.js";
+/** Constrain a value to the inclusive `[min, max]` range.
+ * @internal
+ */
+export declare function clamp(value: number, min: number, max: number): number;
+/** Fraction of the way `value` sits between `from` and `to`; inverse of `lerp`. Returns 0 when the span is empty.
+ * @internal
+ */
+export declare function inverseLerp(from: number, to: number, value: number): number;
+/** Map `value` from the `[inMin, inMax]` range onto `[outMin, outMax]`, optionally clamped to the output range.
+ * @internal
+ */
+export declare function remap(value: number, inMin: number, inMax: number, outMin: number, outMax: number, clamped?: boolean): number;
+/** Euclidean modulo that always returns a non-negative result in `[0, modulus)`, unlike the `%` operator.
+ * @internal
+ */
+export declare function mod(value: number, modulus: number): number;
+/** Step `current` toward `target` by at most `maxDelta`, without overshooting.
+ * @internal
+ */
+export declare function moveTowards(current: number, target: number, maxDelta: number): number;
+/** Wrap `value` into the half-open range `[min, max)`, cycling past either edge.
+ * @internal
+ */
+export declare function wrap(value: number, min: number, max: number): number;