@jgengine/core 0.12.0 → 0.13.0

package/dist/game/partAnimation.js

@@ -0,0 +1,147 @@
+/**
+ * Procedural animation for part-composed (rig-less) models — characters kit-bashed from
+ * primitives/`ModelPart`s with no skeleton or clips. Pure, deterministic curve sampling:
+ * the same (time, speed, phase, flinch, death) input always yields the same pose, so
+ * replays and multi-client renders stay in lockstep and the hot path allocates nothing
+ * when an `out` pose is reused.
+ */
+const DEFAULT_STRIDE_HZ = 1.6;
+const DEFAULT_SWING_RAD = 0.7;
+const DEFAULT_BOB_AMP = 0.04;
+const DEFAULT_SWAY_RAD = 0.05;
+const DEFAULT_WALK_SPEED = 2;
+const DEFAULT_FLINCH_RAD = 0.35;
+const DEFAULT_TOPPLE_RAD = Math.PI / 2;
+const IDLE_BREATHE_HZ = 0.45;
+const TWO_PI = Math.PI * 2;
+function clamp01(value) {
+    return value < 0 ? 0 : value > 1 ? 1 : value;
+}
+function zeroPose(out) {
+    out.position[0] = 0;
+    out.position[1] = 0;
+    out.position[2] = 0;
+    out.rotation[0] = 0;
+    out.rotation[1] = 0;
+    out.rotation[2] = 0;
+    out.scale[0] = 1;
+    out.scale[1] = 1;
+    out.scale[2] = 1;
+    return out;
+}
+/** Volume-conserving vertical squash: compress y by `amount`, bulge x/z by half of it. */
+function applySquash(out, amount) {
+    out.scale[1] *= 1 - amount;
+    const bulge = 1 + amount * 0.5;
+    out.scale[0] *= bulge;
+    out.scale[2] *= bulge;
+}
+/** A reusable identity pose (zero offsets, unit scale). */
+export function createPartPose() {
+    return { position: [0, 0, 0], rotation: [0, 0, 0], scale: [1, 1, 1] };
+}
+/**
+ * Deterministic per-character stride phase in [0, 1) from an id (e.g. the entity instance id),
+ * so a crowd of identical part-composed characters doesn't animate in lockstep.
+ */
+export function partMotionPhase(id) {
+    let hash = 0;
+    for (let index = 0; index < id.length; index += 1)
+        hash = (hash * 31 + id.charCodeAt(index)) >>> 0;
+    return (hash % 1000) / 1000;
+}
+const SPLAT_FLATTEN = 0.7;
+/**
+ * Sample the character-root pose: walk bob, idle breathe/sway, backward hit flinch, and death —
+ * a sideways topple by default, or a flatten-out splat with `deathStyle: "splat"`. With
+ * `squashAmp > 0` the body also squashes and stretches (footfall squash, jelly idle breathe,
+ * flinch squash pulse), volume-conserving. A driver applies this to the group wrapping the
+ * whole composition (base model plus parts) — limbs ride along, as they would on a real torso.
+ *
+ * @capability part-motion sample the root bob/sway/squash/flinch/death pose for a rig-less part-composed character
+ */
+export function sampleBodyPose(input, params, out = createPartPose()) {
+    zeroPose(out);
+    const walkSpeed = params?.walkSpeed ?? DEFAULT_WALK_SPEED;
+    const strideHz = params?.strideHz ?? DEFAULT_STRIDE_HZ;
+    const bobAmp = params?.bobAmp ?? DEFAULT_BOB_AMP;
+    const swayRad = params?.swayRad ?? DEFAULT_SWAY_RAD;
+    const squashAmp = params?.squashAmp ?? 0;
+    const death = clamp01(input.death);
+    const alive = 1 - death;
+    const walk = clamp01(input.speed / walkSpeed) * alive;
+    const idle = (1 - walk) * alive;
+    const stride = TWO_PI * (input.timeSec * strideHz + input.phase);
+    const breathe = TWO_PI * (input.timeSec * IDLE_BREATHE_HZ + input.phase);
+    const step = Math.abs(Math.sin(stride));
+    // Double-bounce bob: the body rises on each step, twice per stride cycle.
+    out.position[1] = step * bobAmp * walk + Math.sin(breathe) * bobAmp * 0.5 * idle;
+    out.rotation[2] = Math.sin(breathe) * swayRad * idle;
+    out.rotation[0] = -clamp01(input.flinch) * (params?.flinchRad ?? DEFAULT_FLINCH_RAD) * alive;
+    if (squashAmp > 0) {
+        // Footfall squash: deepest where the bob is lowest (step ≈ 0), released at the top of the step.
+        applySquash(out, (1 - step) * squashAmp * walk);
+        // Jelly breathe: idle scale oscillation, gentler than a footfall.
+        applySquash(out, Math.sin(breathe) * squashAmp * 0.4 * idle);
+        // Flinch reads as a squash pulse on a soft body.
+        applySquash(out, clamp01(input.flinch) * squashAmp * alive);
+    }
+    if ((params?.deathStyle ?? "topple") === "splat") {
+        applySquash(out, death * SPLAT_FLATTEN);
+    }
+    else {
+        out.rotation[2] += death * (params?.toppleRad ?? DEFAULT_TOPPLE_RAD);
+    }
+    return out;
+}
+/**
+ * Sample one part's pose offset by role: counter-phase leg/arm swing driven by speed, a head
+ * counter-sway, tail wag, and wing flap. Offsets are added onto the part's authored
+ * position/rotation. Motion fades to zero as `death` ramps so the topple reads as one piece.
+ *
+ * @capability part-motion sample a limb/head/tail/wing pose offset for a role-tagged ModelPart
+ */
+export function samplePartPose(role, input, params, out = createPartPose()) {
+    zeroPose(out);
+    const walkSpeed = params?.walkSpeed ?? DEFAULT_WALK_SPEED;
+    const strideHz = params?.strideHz ?? DEFAULT_STRIDE_HZ;
+    const swingRad = params?.swingRad ?? DEFAULT_SWING_RAD;
+    const swayRad = params?.swayRad ?? DEFAULT_SWAY_RAD;
+    const alive = 1 - clamp01(input.death);
+    const walk = clamp01(input.speed / walkSpeed) * alive;
+    const idle = (1 - walk) * alive;
+    const stride = TWO_PI * (input.timeSec * strideHz + input.phase);
+    const breathe = TWO_PI * (input.timeSec * IDLE_BREATHE_HZ + input.phase);
+    switch (role) {
+        case "leg.l":
+            out.rotation[0] = Math.sin(stride) * swingRad * walk;
+            break;
+        case "leg.r":
+            out.rotation[0] = Math.sin(stride + Math.PI) * swingRad * walk;
+            break;
+        case "arm.l":
+            // Arms counter their same-side leg, at slightly lower amplitude.
+            out.rotation[0] = Math.sin(stride + Math.PI) * swingRad * 0.8 * walk;
+            out.rotation[2] = Math.sin(breathe) * swayRad * idle;
+            break;
+        case "arm.r":
+            out.rotation[0] = Math.sin(stride) * swingRad * 0.8 * walk;
+            out.rotation[2] = -Math.sin(breathe) * swayRad * idle;
+            break;
+        case "head":
+            out.rotation[2] = -Math.sin(breathe) * swayRad * idle;
+            out.rotation[1] = Math.sin(stride) * swayRad * 0.5 * walk;
+            out.rotation[0] = -clamp01(input.flinch) * 0.5 * (params?.flinchRad ?? DEFAULT_FLINCH_RAD) * alive;
+            break;
+        case "tail":
+            out.rotation[1] = Math.sin(stride) * swingRad * 0.5 * walk + Math.sin(breathe) * swayRad * 2 * idle;
+            break;
+        case "wing.l":
+            out.rotation[2] = Math.abs(Math.sin(stride)) * swingRad * walk + Math.sin(breathe) * swayRad * idle;
+            break;
+        case "wing.r":
+            out.rotation[2] = -Math.abs(Math.sin(stride)) * swingRad * walk - Math.sin(breathe) * swayRad * idle;
+            break;
+    }
+    return out;
+}

package/dist/game/playableGame.d.ts

@@ -10,6 +10,7 @@ import type { HudPlatform, HudViewportConfig } from "../ui/hudScale.js";
 import type { PositionedPrompt } from "../interaction/proximityPrompt.js";
 import type { CatalogEntityRole, GameContext, GameContextContent } from "../runtime/gameContext.js";
 import type { ModelDims } from "../scene/assetCatalog.js";
+import type { PartMotionParams, PartRole } from "./partAnimation.js";
 import type { CollisionMeshData } from "../scene/collisionMesh.js";
 import type { SkyEnvironmentConfig } from "../world/features.js";
 import type { VisibilityConfig } from "../visibility/config.js";
@@ -163,6 +164,14 @@ export interface ModelPart {
     rotation?: [number, number, number];
     /** Uniform scale of the part under the parent's transform. Default 1. */
     scale?: number;
+    /**
+     * Semantic motion role for a rig-less part-composed character (see `game/partAnimation`).
+     * Tagging any part enables the shell's procedural driver on an entity model: legs and arms swing
+     * counter-phase with movement speed, the head counter-sways, tails wag, wings flap, and the whole
+     * composition gains walk bob, idle breathe, hit flinch, and a death topple. Untagged parts stay
+     * static kit pieces.
+     */
+    role?: PartRole;
 }
 export interface ModelConfig {
     url: string;
@@ -178,12 +187,21 @@ export interface ModelConfig {
     collisionMesh?: CollisionMeshData;
     /** Per-entity PBR tint/finish override (#151.3); cloned onto each `MeshStandardMaterial` in the model so shared GLTF caches stay untouched. */
     material?: ModelMaterialOverride;
-    /** Plays a GLTF animation clip on the model when the source has any (skinned or not); omit to render the rig's bind pose. */
-    animation?: ModelAnimationConfig;
+    /**
+     * Plays a GLTF animation clip on the model when the source has any (skinned or not).
+     * A model resolved from a catalog id whose index carries `clips` animates automatically —
+     * semantic clip roles build the idle/walk/run states and hit/death/attack one-shots (see
+     * `defaultAnimationForClips`). `"auto"` forces that derivation, `"none"` opts out (bind pose),
+     * and an explicit config always wins. Omit on an inline (non-catalog) config to render the
+     * rig's bind pose.
+     */
+    animation?: ModelAnimationConfig | "auto" | "none";
     /** Props/weapons parented to named bones on this model's rig; each follows its bone through animation. */
     attachments?: readonly ModelAttachment[];
-    /** Static kit-of-parts pieces stacked at fixed local offsets — no bone/rig involved. Use this for a compound entity assembled from several modular meshes (a castle keep from base + mid + roof pieces); use `attachments` for props parented to an animated rig's bones. */
+    /** Static kit-of-parts pieces stacked at fixed local offsets — no bone/rig involved. Use this for a compound entity assembled from several modular meshes (a castle keep from base + mid + roof pieces); use `attachments` for props parented to an animated rig's bones. Tag parts with a `role` to procedurally animate a rig-less character composition. */
     parts?: readonly ModelPart[];
+    /** Tuning for the procedural part-motion driver when any part carries a `role`; omit for defaults. */
+    partMotion?: PartMotionParams;
 }
 export interface ObjectStyle {
     color?: string;
@@ -286,7 +304,19 @@ export interface PresentationEffectsConfig {
 }
 /** How a screenshot host reaches live gameplay in this game — the data behind `shoot --mode play`. */
 export interface GameCaptureConfig {
-    /** Commands run (in order, via `ctx.game.commands.run`) right after boot when a capture host requests the play screen — the same commands the start-menu buttons dispatch. A bare string runs with a default input; the object form carries the input a command needs (e.g. `[{ name: "class.select", input: { classId: "siren" } }, "startRun"]`). A name the game never registers fails the capture loudly instead of shipping a menu screenshot. */
+    /**
+     * Commands run (in order, via `ctx.game.commands.run`) right after boot when a capture host requests the
+     * play screen — the same commands the start-menu buttons dispatch. A bare string runs with a default input;
+     * the object form carries the input a command needs (e.g. `[{ name: "class.select", input: { classId: "siren" } }, "startRun"]`).
+     * A name the game never registers fails the capture loudly instead of shipping a menu screenshot.
+     *
+     * Timing contract: these dispatch **once**, synchronously, at `onContextReady` — after `onNewPlayer` but
+     * before any async boot work it kicked off has settled. If the game restores state asynchronously (a
+     * whole-world save load, network hydration) and that restore resets the same "started" gate these commands
+     * flip, the restore lands *after* the play commands and re-shows the menu — the capture then fails with a
+     * start menu still on screen even though `play` is declared. Make such a restore preserve an already-live
+     * session (skip the reset when the start gate is already set) so it does not bounce capture back to the title.
+     */
     play?: readonly (string | {
         name: string;
         input?: unknown;
@@ -362,12 +392,15 @@ export interface PlayableGame<TUi = unknown, TWorldOverlay = unknown, TRenderEnt
      * declares one of the given roles (default: all); `maxDistance` hides nameplates beyond this many
      * world units from the player (default 40). Headless: skin every part via `className`/`data-*` hooks
      * on `WorldNameplates` (`@jgengine/shell/world/WorldHud`) — this flag only turns the readout on and
-     * scopes which entities it covers.
+     * scopes which entities it covers. Set `showHealth: false` for a name-only plate when a game already
+     * draws the HP bar itself (its own HUD, or `worldHealthBars`) — otherwise the nameplate's built-in bar
+     * stacks a second health bar over every entity.
      */
     nameplates?: boolean | {
         statId?: string;
         roles?: readonly CatalogEntityRole[];
         maxDistance?: number;
+        showHealth?: boolean;
     };
     /**
      * Combat presentation stack mounted inside the 3D canvas (telegraphs, spell VFX, retained VFX,

package/dist/game/progression.d.ts

@@ -76,7 +76,7 @@ export interface LevelingStatAccess {
         max?: number;
     }): unknown;
 }
-/** A resolved leveling track: the immutable `maxLevel`/`startLevel`, the `xpForLevel` threshold lookup, a pure `resolve`, and `grantXp` which writes back through a {@link LevelingStatAccess} and fires an `onLevelUp` callback. */
+/** A resolved leveling track: the immutable `maxLevel`/`startLevel`, the `xpForLevel` threshold lookup, a pure `resolve`, and `grantXp` which writes back through a {@link LevelingStatAccess} and fires `onLevelUp` once for every reached level in ascending order. */
 export interface LevelingTrack {
     readonly maxLevel: number;
     readonly startLevel: number;
@@ -89,7 +89,7 @@ export interface LevelingTrack {
  * returned {@link LevelingTrack} resolves how many levels a given xp total earns
  * (rolling over surplus xp, capping at `maxLevel`) and, via `grantXp`, writes the
  * new level/xp back through a {@link LevelingStatAccess} and fires `onLevelUp` for
- * each level gained. Reach for this instead of hand-tracking xp thresholds; pair
+ * each level gained in ascending order. Reach for this instead of hand-tracking xp thresholds; pair
  * it with `resource-pool` (mana/stamina) and `ability-bar` (cooldowns) for a hero.
  *
  * @capability leveling-track grant XP, resolve level-ups against a curve, and write level+xp stats back through a stat adapter

package/dist/game/progression.js

@@ -69,7 +69,7 @@ export function curve(spec) {
  * returned {@link LevelingTrack} resolves how many levels a given xp total earns
  * (rolling over surplus xp, capping at `maxLevel`) and, via `grantXp`, writes the
  * new level/xp back through a {@link LevelingStatAccess} and fires `onLevelUp` for
- * each level gained. Reach for this instead of hand-tracking xp thresholds; pair
+ * each level gained in ascending order. Reach for this instead of hand-tracking xp thresholds; pair
  * it with `resource-pool` (mana/stamina) and `ability-bar` (cooldowns) for a hero.
  *
  * @capability leveling-track grant XP, resolve level-ups against a curve, and write level+xp stats back through a stat adapter
@@ -128,7 +128,9 @@ export function leveling(config) {
         access.set(userId, xpStat, { current: progress.xp, max: progress.xpMax });
         if (progress.levelsGained > 0) {
             access.set(userId, levelStat, { current: progress.level });
-            onLevelUp?.(progress.level);
+            for (let reached = level.current + 1; reached <= progress.level; reached += 1) {
+                onLevelUp?.(reached);
+            }
         }
         return progress.levelsGained;
     };

package/dist/inventory/inventoryModel.d.ts

@@ -35,25 +35,41 @@ export type MoveResult = {
     status: "rejected";
     reason: "invalid-slot" | "empty-slot" | "wrong-kind" | "no-space";
 };
+/** Outcome of {@link splitStack}: the new state, or a rejection reason. */
+export type SplitResult = {
+    status: "ok";
+    state: InventoryState;
+} | {
+    status: "rejected";
+    reason: "invalid-slot" | "empty-slot" | "invalid-amount" | "no-space" | "slot-occupied";
+};
 /**
  * A bag of stackable items supporting add, remove, count, and move — the base inventory model.
  *
  * @capability inventory-grid a bag of stackable items with add, remove, and move
-  * @internal
-  */
+ */
 export declare function createEmptyInventory(layout: InventoryLayout): InventoryState;
-/** @internal */
+/** Add `count` of `itemId` — into a specific `options.slot`, or auto-stacked across free/partial slots. Rejects on no space or wrong kind. */
 export declare function putItem(state: InventoryState, layout: InventoryLayout, traits: ItemTraits, itemId: string, count: number, options?: {
     slot?: number;
 }): PutResult;
-/** @internal */
+/** Remove `count` of `itemId`, draining from the last matching stacks first. Rejects if fewer than `count` are held. */
 export declare function takeItem(state: InventoryState, itemId: string, count: number): TakeResult;
-/** @internal */
+/** Total quantity of `itemId` summed across every stack in the inventory. */
 export declare function countItem(state: InventoryState, itemId: string): number;
-/** @internal */
+/** True when the inventory holds at least `count` of `itemId`. */
 export declare function hasItem(state: InventoryState, itemId: string, count: number): boolean;
-/** @internal */
+/** Move the stack at `fromSlot` to `toSlot` (or auto-stack when omitted) — swapping, merging with remainder, or relocating across two inventories. Rejects on empty source, wrong kind, or no space. */
 export declare function moveItem(from: InventoryState, fromSlot: number, to: InventoryState, toLayout: InventoryLayout, traits: ItemTraits, toSlot?: number): MoveResult;
+/**
+ * Splits `amount` off the stack in `slot` into `toSlot` (or the first empty slot when `toSlot` is
+ * omitted). Limit-agnostic: it does not consult {@link ItemTraits}, so a same-item target merges by
+ * simple addition. Rejects an empty source, `amount <= 0`, `amount >= stack count` (a split must
+ * leave both sides non-empty), no free slot, or a target holding a different item.
+ *
+ * @capability inventory-split split a stack into a target or first-empty slot
+ */
+export declare function splitStack(state: InventoryState, slot: number, amount: number, toSlot?: number): SplitResult;
 export interface InventorySet<TId extends string> {
     put(id: TId, itemId: string, count: number, options?: {
         slot?: number;
@@ -65,5 +81,5 @@ export interface InventorySet<TId extends string> {
     state(id: TId): InventoryState;
     replaceState(id: TId, state: InventoryState): void;
 }
-/** @internal */
+/** Build a keyed set of named inventories from their `layouts`, sharing one `traits` table — the stateful façade over put/take/move/count. */
 export declare function createInventorySet<TId extends string>(layouts: Record<TId, InventoryLayout>, traits: ItemTraits): InventorySet<TId>;

package/dist/inventory/inventoryModel.js

@@ -2,8 +2,7 @@
  * A bag of stackable items supporting add, remove, count, and move — the base inventory model.
  *
  * @capability inventory-grid a bag of stackable items with add, remove, and move
-  * @internal
-  */
+ */
 export function createEmptyInventory(layout) {
     return { slots: new Array(layout.slots).fill(null) };
 }
@@ -82,13 +81,13 @@ function explicitPut(state, layout, traits, itemId, count, slot) {
     slots[slot] = { itemId, count: newCount };
     return { status: "ok", state: { slots } };
 }
-/** @internal */
+/** Add `count` of `itemId` — into a specific `options.slot`, or auto-stacked across free/partial slots. Rejects on no space or wrong kind. */
 export function putItem(state, layout, traits, itemId, count, options) {
     if (options?.slot !== undefined)
         return explicitPut(state, layout, traits, itemId, count, options.slot);
     return autoPut(state, layout, traits, itemId, count);
 }
-/** @internal */
+/** Remove `count` of `itemId`, draining from the last matching stacks first. Rejects if fewer than `count` are held. */
 export function takeItem(state, itemId, count) {
     if (count <= 0)
         return { status: "ok", state };
@@ -107,7 +106,7 @@ export function takeItem(state, itemId, count) {
     }
     return { status: "ok", state: { slots } };
 }
-/** @internal */
+/** Total quantity of `itemId` summed across every stack in the inventory. */
 export function countItem(state, itemId) {
     let total = 0;
     for (const slot of state.slots)
@@ -115,11 +114,11 @@ export function countItem(state, itemId) {
             total += slot.count;
     return total;
 }
-/** @internal */
+/** True when the inventory holds at least `count` of `itemId`. */
 export function hasItem(state, itemId, count) {
     return countItem(state, itemId) >= count;
 }
-/** @internal */
+/** Move the stack at `fromSlot` to `toSlot` (or auto-stack when omitted) — swapping, merging with remainder, or relocating across two inventories. Rejects on empty source, wrong kind, or no space. */
 export function moveItem(from, fromSlot, to, toLayout, traits, toSlot) {
     if (fromSlot < 0 || fromSlot >= from.slots.length)
         return { status: "rejected", reason: "invalid-slot" };
@@ -171,7 +170,47 @@ export function moveItem(from, fromSlot, to, toLayout, traits, toSlot) {
         to: sameInventory ? { slots: fromSlots } : { slots: toSlots },
     };
 }
-/** @internal */
+/**
+ * Splits `amount` off the stack in `slot` into `toSlot` (or the first empty slot when `toSlot` is
+ * omitted). Limit-agnostic: it does not consult {@link ItemTraits}, so a same-item target merges by
+ * simple addition. Rejects an empty source, `amount <= 0`, `amount >= stack count` (a split must
+ * leave both sides non-empty), no free slot, or a target holding a different item.
+ *
+ * @capability inventory-split split a stack into a target or first-empty slot
+ */
+export function splitStack(state, slot, amount, toSlot) {
+    if (slot < 0 || slot >= state.slots.length)
+        return { status: "rejected", reason: "invalid-slot" };
+    const source = state.slots[slot];
+    if (source === null)
+        return { status: "rejected", reason: "empty-slot" };
+    if (amount <= 0 || amount >= source.count)
+        return { status: "rejected", reason: "invalid-amount" };
+    let target = toSlot;
+    if (target === undefined) {
+        target = state.slots.findIndex((s) => s === null);
+        if (target === -1)
+            return { status: "rejected", reason: "no-space" };
+    }
+    else {
+        if (target < 0 || target >= state.slots.length)
+            return { status: "rejected", reason: "invalid-slot" };
+        if (target === slot)
+            return { status: "rejected", reason: "slot-occupied" };
+        const dest = state.slots[target];
+        if (dest !== null && dest.itemId !== source.itemId)
+            return { status: "rejected", reason: "slot-occupied" };
+    }
+    const slots = state.slots.slice();
+    const dest = slots[target];
+    slots[slot] = { itemId: source.itemId, count: source.count - amount };
+    slots[target] =
+        dest === null || dest === undefined
+            ? { itemId: source.itemId, count: amount }
+            : { itemId: source.itemId, count: dest.count + amount };
+    return { status: "ok", state: { slots } };
+}
+/** Build a keyed set of named inventories from their `layouts`, sharing one `traits` table — the stateful façade over put/take/move/count. */
 export function createInventorySet(layouts, traits) {
     const states = new Map();
     for (const id of Object.keys(layouts)) {

package/dist/meta/changelog.d.ts

@@ -1,5 +1,5 @@
 /** Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating. */
-export declare const VERSION = "0.12.0";
+export declare const VERSION = "0.13.0";
 /** One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md). */
 export interface ChangelogEntry {
     migrate: readonly string[];

package/dist/meta/changelog.js

@@ -1,7 +1,31 @@
 /** Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating. */
-export const VERSION = "0.12.0";
+export const VERSION = "0.13.0";
 /** Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`). */
 export const CHANGELOG = {
+    "0.13.0": {
+        migrate: [
+            "Bump lockstep SDK packages to ^0.13.0: @jgengine/{core,react,ws,node,sql,convex,shell,editor,assets}. CLI jgengine is 0.10.0; @jgengine/github is unchanged.",
+            "Nothing required — additive release. Two overridable defaults changed in the player's favor: offline games persist to localStorage automatically (#1207) and rigged catalog assets animate by default via clip metadata + semantic clip roles (#1209); opt out explicitly if a game relied on the old behavior.",
+        ],
+        added: [
+            "Drop-in inventory grid, window manager, and character sheet (#1220) — @jgengine/react InventoryGrid (drag/stack/split), toggleable windows backed by @jgengine/core/ui/panelModel, CharacterSheet paperdoll; all HudTheme-skinnable.",
+            "Serializable runtime snapshots (#1179) — capture/restore live runtime state including magazine state (@jgengine/core/combat/magazine) and stat modifiers.",
+            "Portable weapon plumbing (#1211) — @jgengine/core/combat/weaponFire composes trigger → magazine → spread → projectile/hitscan as data.",
+            "Portable leveling (#1206) and portable damage-pool access (#1208) as genre-agnostic game-context seams.",
+            "Named combat VFX presets (#1204) — @jgengine/core/combat/vfxPresets; a visible attack is one line.",
+            "Runtime-measured render-bounds hitboxes (#1227) — colliders wrap what the shell actually mounts.",
+            "Procedural part motion for rig-less part-composed characters (#1222); squash & stretch and death splat (#1229).",
+            "City fabric (#1191) — streetGenerator + cityGenerator, editor bake verb, street-aware lots, road junctions, grounding.",
+            "jgengine recipe CLI (#1214, #1231) — vetted wired compositions, compile-pinned against the SDK.",
+            "Editor/debug modes mirrored to the URL with an editor exit (#1203); dependency-free WebGL screenshot script in the game template (#1202).",
+        ],
+        changed: [
+            "Offline games persist to localStorage by default (#1207); rigged assets animate by default (#1209).",
+            "RTS camera pan inversion fixed (#1228); sprite raycast warning silenced and duplicate nameplate health bars removed (#1194); scaffolded F2+E editor Tailwind @source renders its theme (#1195).",
+            "Outside-game DX: stat-pool no-op stability, camera-transparent decor, cleaner install/version output, headless UI-intent seam (#1223).",
+        ],
+        removed: [],
+    },
     "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.",

package/dist/runtime/context/combat.js

@@ -2,6 +2,7 @@ import { createDeathSystem, deathReasonFromEffect } from "../../combat/death.js"
 import { createEffectSystem, } from "../../combat/effects.js";
 import { createProjectileSystem } from "../../combat/projectiles.js";
 import { createVfxInstanceStore } from "../../game/vfxInstance.js";
+import { createEntityStatsApi } from "../../scene/entityStats.js";
 import { notifyAfter } from "../../store/changeSignal.js";
 import { createCombatFx } from "./combatFx.js";
 import { applyLethalLoot, isLocalPlayerKill } from "./deathLoot.js";
@@ -30,7 +31,7 @@ export function createCombatSubsystem(d) {
     });
     const effects = notifyAfter(createEffectSystem({
         resolveReceive: (instanceId) => catalogEntry(instanceId)?.receive,
-        resolveStats: (instanceId) => statsByInstance.get(instanceId),
+        statPools: createEntityStatsApi((instanceId) => statsByInstance.get(instanceId)),
         getStat: weapon.getStat,
         spatial: combatSpatial,
         onLethal(instanceId, lethalCtx) {

package/dist/runtime/context/combatFx.js

@@ -1,5 +1,6 @@
 import { resolveHitReaction } from "../../combat/hitReaction.js";
 import { pointInTelegraph } from "../../combat/telegraph.js";
+import { resolveVfxPreset } from "../../combat/vfxPresets.js";
 /** @internal */
 export function createCombatFx(d) {
     const { entities, events, time } = d;
@@ -52,17 +53,26 @@ export function createCombatFx(d) {
         const from = resolveVfxPoint(input.from) ?? to;
         if (from === undefined)
             return;
+        // A named preset fills in kind/color/defaults; any field on the call still wins. With no
+        // preset and no explicit kind/color the resolver falls back to a visible spark rather than
+        // emitting an invalid (blank) burst — so a bare `vfx({ from, to })` still shows something.
+        const resolved = resolveVfxPreset(input.preset, {
+            ...(input.kind === undefined ? {} : { kind: input.kind }),
+            ...(input.color === undefined ? {} : { color: input.color }),
+            ...(input.durationMs === undefined ? {} : { durationMs: input.durationMs }),
+            ...(input.radius === undefined ? {} : { radius: input.radius }),
+        });
         const event = {
             id: vfxSeq++,
-            kind: input.kind,
-            color: input.color,
+            kind: resolved.kind,
+            color: resolved.color,
             from,
-            durationMs: input.durationMs ?? vfxDefaultDurationMs[input.kind],
+            durationMs: resolved.durationMs ?? vfxDefaultDurationMs[resolved.kind],
         };
         if (to !== undefined)
             event.to = to;
-        if (input.radius !== undefined)
-            event.radius = input.radius;
+        if (resolved.radius !== undefined)
+            event.radius = resolved.radius;
         events.emit("combat.vfx", event);
     }
     let telegraphSeq = 0;

package/dist/runtime/context/scene.d.ts

@@ -4,7 +4,7 @@ import { type BodyBind } from "../../scene/bodyBind.js";
 import { type EntityStatsApi, type StatValueMap } from "../../scene/entityStats.js";
 import { type EntityPosition, type EntityStore, type SceneEntity, type SpawnOptions } from "../../scene/entityStore.js";
 import { type Forms } from "../../scene/form.js";
-import { type EntityColliderSet } from "../../scene/colliders.js";
+import { type EntityColliderSet, type MeasuredBounds } from "../../scene/colliders.js";
 import { type ObjectStore } from "../../scene/objectStore.js";
 import { type PaintLayer } from "../../scene/paintLayer.js";
 import { type SceneRaycastApi } from "../../scene/sceneRaycast.js";
@@ -41,6 +41,7 @@ export interface SceneSubsystem {
     objectColliders: Map<string, EntityColliderSet>;
     entityCollidersOf: (instanceId: string) => EntityColliderSet | null;
     objectCollidersOf: (instanceId: string) => EntityColliderSet | null;
+    reportEntityBounds: (kind: string, bounds: MeasuredBounds | null) => boolean;
     entityVisualScaleOf: (instanceId: string) => number;
     forms: Forms;
     paintLayer: PaintLayer;

package/dist/runtime/context/scene.js

@@ -2,7 +2,7 @@ import { createBodyBind } from "../../scene/bodyBind.js";
 import { createEntityStatsApi, seedStatValues, } from "../../scene/entityStats.js";
 import { createEntityStore, } from "../../scene/entityStore.js";
 import { createForms } from "../../scene/form.js";
-import { fittedEntityColliders, fittedObjectColliders, scaledEntityColliders, scaledObjectColliders, } from "../../scene/colliders.js";
+import { fittedEntityColliders, fittedObjectColliders, measuredEntityColliders, measuredObjectColliders, scaledEntityColliders, scaledObjectColliders, } from "../../scene/colliders.js";
 import { raycastObjects, raycastObjectsAll } from "../../scene/objectQuery.js";
 import { createObjectStore, objectVisualScale } from "../../scene/objectStore.js";
 import { createPaintLayer } from "../../scene/paintLayer.js";
@@ -82,6 +82,36 @@ export function createSceneSubsystem(d) {
         fittedObjectByCatalogId.set(catalogId, fitted);
         return fitted;
     }
+    const measuredEntityByKind = new Map();
+    const measuredObjectByCatalogId = new Map();
+    function reportEntityBounds(kind, bounds) {
+        if (bounds === null) {
+            const existed = measuredEntityByKind.delete(kind);
+            if (existed)
+                signalNotify();
+            return existed;
+        }
+        const measured = measuredEntityColliders(bounds);
+        if (measured === null)
+            return false;
+        measuredEntityByKind.set(kind, measured);
+        signalNotify();
+        return true;
+    }
+    function reportObjectBounds(catalogId, bounds) {
+        if (bounds === null) {
+            const existed = measuredObjectByCatalogId.delete(catalogId);
+            if (existed)
+                signalNotify();
+            return existed;
+        }
+        const measured = measuredObjectColliders(bounds);
+        if (measured === null)
+            return false;
+        measuredObjectByCatalogId.set(catalogId, measured);
+        signalNotify();
+        return true;
+    }
     function entityCollidersOf(instanceId) {
         const override = entityColliders.get(instanceId);
         if (override !== undefined)
@@ -94,6 +124,9 @@ export function createSceneSubsystem(d) {
             const fitted = fittedEntitySetFor(kind);
             if (fitted !== null)
                 return fitted;
+            const measured = measuredEntityByKind.get(kind);
+            if (measured !== undefined)
+                return measured;
         }
         const scale = entry?.scale;
         if (scale !== undefined && scale !== 1)
@@ -118,6 +151,9 @@ export function createSceneSubsystem(d) {
         const fitted = fittedObjectSetFor(object.catalogId);
         if (fitted !== null)
             return fitted;
+        const measured = measuredObjectByCatalogId.get(object.catalogId);
+        if (measured !== undefined)
+            return measured;
         if (object.visual?.scale === undefined)
             return null;
         return scaledObjectColliders(objectVisualScale(object.visual));
@@ -254,6 +290,7 @@ export function createSceneSubsystem(d) {
             signalNotify();
         },
         collidersOf: objectCollidersOf,
+        reportBounds: reportObjectBounds,
         selection: objectSelection,
     };
     return {
@@ -272,6 +309,7 @@ export function createSceneSubsystem(d) {
         objectColliders,
         entityCollidersOf,
         objectCollidersOf,
+        reportEntityBounds,
         entityVisualScaleOf,
         forms,
         paintLayer,