@jgengine/core 0.10.0 → 0.12.0

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;

package/dist/math/scalar.js

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

package/dist/meta/changelog.d.ts

@@ -1,8 +1,11 @@
-export declare const VERSION = "0.10.0";
+/** Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating. */
+export declare const VERSION = "0.12.0";
+/** One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md). */
 export interface ChangelogEntry {
     migrate: readonly string[];
     added: readonly string[];
     changed: readonly string[];
     removed: readonly string[];
 }
+/** Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`). */
 export declare const CHANGELOG: Record<string, ChangelogEntry>;

package/dist/meta/changelog.js

@@ -1,14 +1,51 @@
-export const VERSION = "0.10.0";
+/** Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating. */
+export const VERSION = "0.12.0";
+/** Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`). */
 export const CHANGELOG = {
+    "0.12.0": {
+        migrate: [
+            "Bump lockstep SDK packages to ^0.12.0: @jgengine/{core,react,ws,node,sql,convex,shell,editor,assets}. CLI jgengine is 0.9.0; @jgengine/github is unchanged.",
+            "Author games through defineGame from @jgengine/shell — the single public authoring entry. Core's constructor was renamed defineGame → defineGameDefinition (@jgengine/core/game/defineGame); only hosts and tooling call it. GamePlayer/GamePlayerShell are @internal; GameHost is the documented mount and owns the editor summon (?mode=editor, F2+E, dev save endpoint) — delete per-game editor bootstraps.",
+            "Declare worlds with world({ id, ground: { mode, size, surface? }, physics? }) from @jgengine/core/world/place (flat/round/voxel/board). environment() still works as the legacy consumption path for editor-written scene data — nothing required for existing games; author dressing in the editor.",
+        ],
+        added: [
+            "world() place API (#1178) — @jgengine/core/world/place: ground mode/size discriminated at type and runtime (flat {x,z} with Infinity, round {radius}, voxel generator domain, board {x,y} cells); ground.surface matter/feel laws; per-place physics over the game default; multiple worlds per game; shell PlaceScene substrate rendering; seeds via seedForPlace.",
+            "@jgengine/shell/gameKit — happy-path authoring surface: authoring, mount, stores, systems, authored-scene helpers, HUD primitives, seeded rng.",
+            "Portable generic stat pools — @jgengine/core/stats/statPool (bounded named pools: health, energy, heat, ammo…); entity stats rebuilt on them; recipe in skill jgengine-combat.",
+            "Auction-house economy primitives (#1086) — @jgengine/core/economy/auctionBook: timed bid auctions, escrowed bids, outbid refunds, optional buyout, anti-snipe extension, settlement with house cut; plus market price history.",
+            "Portable minimap marker sources — core world seam for game minimaps; recipe in skill jgengine-ui.",
+            "Unified seed-driven path network + city generation v2 (#1103, #1106) — street/block/building dials, zone bands, presets, junction geometry, road-derived parcels; shell renders real intersections, curbs, lane lines, tunnels, bridge decks.",
+            "Mesh-accurate hitboxes (#1075), auto-fit colliders from model bounds (#1072), movement obstruction from fitted boxes + compound-box openings (#1077).",
+            "Editor overhaul (#1110) — materials/lighting/scripting/animation/multiplayer workspaces, command palette, minimap bake (#1036), GLB thumbnails, hierarchy DnD/keys/context/visibility-lock, multi-select inspector, console RPC, asset drag-place, ortho projection, pivot modes, play chrome.",
+            "Editor authoring pipeline — entity definitions and starter catalogs (#1012), Data-tab catalogs/schema fields (#1043), promote authored scene folder to runnable game (#1011), shared trigger primitive with goal/win rules (#1013), asset import rewrites game/assets.ts (#1042).",
+        ],
+        changed: [
+            "npx jgengine create scaffolds a thin infinite flat world() place (no more 96m meadow); editor blankWorld drops pre-baked seeded grass — dressing belongs in editor.scene.json.",
+            "Environment studio visual-quality pass; grass fields no longer rebuild geometry per frame (#1090).",
+        ],
+        removed: [],
+    },
+    "0.11.0": {
+        migrate: [
+            "Bump lockstep SDK packages to ^0.11.0: @jgengine/{core,react,ws,node,sql,convex,shell,editor,assets}. CLI jgengine and @jgengine/github may lag on their own version lines.",
+            "Nothing required — classic loop.onTick fan-out still runs after systems. Prefer moving per-frame work into defineGame({ systems: [...] }) with defineSystem (@jgengine/core/game/defineSystem); install a system with feature: \"quest\" (etc.) instead of a redundant features flag.",
+        ],
+        added: [
+            "Composable game systems (#842) — defineSystem / compileSystemSchedule / composeGameLoop / installSystems. defineGame({ systems }) is the single authoring path: fixed / frame / interval / event-only / manual ticks, multi-subscribe channels, deterministic stage order + optional before/after/dependsOn, system-owned save / replicate / reset / dispose. Installing a system activates its feature without a separate flag. GameLoop gains optional onReset / onDispose. ctx.game.registerSave / registerReplicate for system modules. Adopters: tower-guard, claudecraft (runtime without a giant tick fan-out).",
+        ],
+        changed: [],
+        removed: [],
+    },
     "0.10.0": {
         migrate: [
-            "Bump every @jgengine/* dependency to ^0.10.0 (the eight packages version in lockstep).",
+            "Bump lockstep SDK packages to ^0.10.0: @jgengine/{core,react,ws,node,sql,convex,shell,editor,assets}. CLI jgengine and @jgengine/github may lag on their own version lines.",
             "Nothing to change for existing games — the shared mobile-composition system (viewport allocation, region collision, --jg-* viewport vars) is wired automatically by the shell; HudPanels inside a HudCanvas register themselves. Legacy orientation: \"landscape\" | \"portrait\" keeps its advisory dismissible-hint behavior.",
             "Opt a driving/landscape game into the strict gate: replace advisory orientation with the contract form orientation: { mobile: \"landscape-required\" } (rules: any · portrait/landscape advisory · portrait-required/landscape-required · unsupported). In portrait the engine shows a polished RotateDeviceScreen, suppresses input, freezes the sim, and unmounts the HUD/controls until the device is landscape.",
             "Declare HUD intent where useful: HudPanel gains priority (critical/secondary/tertiary), mobileBehavior (hidden unmounts on phones, transient softens collision), allowOverlapWith, and collisionGroup — all optional; omitting them keeps prior behavior.",
             "Mobile validation now also fails on overlap: bun run shoot <game> --device mobile|mobile-landscape|both exits non-zero on forbidden inter-element collisions, naming both regions.",
         ],
         added: [
+            "Authored behavior triggers — schema'd `on`/`action` meta vocabulary on editor volumes and markers (`registerTriggerAction`, `collectAuthoredTriggers`, `createAuthoredTriggerRuntime`, `pointInVolume` in `@jgengine/core/scene/authoredTriggers` / `@jgengine/core/world`). Games declare typed actions via ParamSchema; the editor inspector renders trigger fields; runtime watches enter/exit/interact and dispatches to handlers. studio-showcase adopts with an announce zone.",
             "Shared mobile layout composition — @jgengine/core/ui/gameLayout (resolveLayoutMode, intersects, overlapArea, detectLayoutCollisions, computeGameplayRect, LayoutRegion, GameViewportLayout) and @jgengine/core/ui/orientation (resolveOrientationRequirement, orientationGateActive, MobileOrientationRule); @jgengine/react adds GameViewportProvider (mounted by the shell), hooks (useGameViewportLayout, useGameLayoutMode, useGameOrientation, useReservedControlZones, useLayoutCollisions, useRegisterLayoutRegion), and a headless RotateDeviceScreen. The provider tracks window.visualViewport, publishes --jg-viewport-*/--jg-visual-viewport-*/--jg-safe-* CSS vars, resolves the explicit layout mode, and detects forbidden region overlaps.",
             "Mandatory orientation contract — PlayableGame.orientation accepts { mobile: <rule> }; landscape-required/portrait-required render an engine-owned rotate gate that blocks gameplay (input suppressed, simulation frozen, HUD/controls unmounted), self-correcting when the device is turned. Reduced-motion and safe-area respected; visualViewport-sized for mobile Safari/PWA.",
             "Reserved touch-control zones — the touch dock registers its joystick / action-cluster / utility rectangles (runtime-measured) as control regions, so HUD placement and collision validation know exactly where controls sit.",

package/dist/movement/avoidance.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Local collision avoidance: nudge a set of circular agents apart so they stop
+ * overlapping, kept deliberately separate from route planning so a game can
+ * pair it with nav paths, flow fields, direct seek, or vehicle steering. It is a
+ * short symmetric relaxation (Jacobi position correction) over a bounded uniform
+ * hash grid — each agent only tests the 3×3 cells around it, so cost scales with
+ * local density, never O(n²) across the whole world. Corrections are summed per
+ * agent and applied after each pass, so the result is order-independent and
+ * deterministic for a given agent list. Different radii and per-agent weights
+ * (inverse mass; `0` = immovable anchor/obstacle) are honored.
+ */
+import type { Vec2 } from "./formation.js";
+/** A circular agent that avoidance may push on the XZ plane. */
+export interface AvoidanceAgent {
+    /** Current XZ position; reassigned in place by {@link resolveLocalAvoidance}. */
+    position: Vec2;
+    /** Collision radius (world units). */
+    radius: number;
+}
+/** Tuning for {@link resolveLocalAvoidance}. */
+export interface LocalAvoidanceOptions {
+    /** Relaxation passes; more converges denser packs. Default `2`. */
+    iterations?: number;
+    /** Fraction of each overlap resolved per pass, `0..1`. Lower is softer/less jittery. Default `1`. */
+    strength?: number;
+    /** Extra gap enforced beyond the two radii (world units). Default `0`. */
+    padding?: number;
+    /**
+     * Per-agent inverse mass, parallel to the agent list. `0` pins an agent
+     * (obstacle/leader); a heavier agent (smaller value) yields less. Omitted or
+     * negative entries default to `1`. Two pinned agents never push each other.
+     */
+    weights?: readonly number[];
+}
+/**
+ * Resolve overlaps in `agents` in place and return how many overlapping pairs
+ * remained on the final pass (`0` = fully separated). Uses a bounded uniform
+ * hash grid sized to the largest agent, so only nearby agents are ever compared.
+ * Deterministic: corrections are accumulated then applied per pass, independent
+ * of agent order. Pass `weights` to pin or differentially push agents.
+ *
+ * @capability local-avoidance bounded deterministic local collision avoidance for moving agents
+ * @consumer squad/crowd movement — keep grouped agents from overlapping without a whole-world scan
+ */
+export declare function resolveLocalAvoidance(agents: AvoidanceAgent[], options?: LocalAvoidanceOptions): number;