@jgengine/core 0.38.0 → 0.38.2

package/CHANGELOG.md

@@ -26,6 +26,53 @@ At publish, rename this heading to the new version and mirror the entries into
 `packages/core/src/meta/changelog.ts` (the typed `CHANGELOG` export).
 -->
 
+## 0.38.2
+
+### Migrate
+
+- **Bump lockstep SDK packages to `^0.38.2`:** `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.35.2`; `@jgengine/github` is `0.25.2`.
+
+### Added
+
+- `requestSceneCapture` and `requestSceneThumbnail` (`@jgengine/shell/render/sceneCapture`) ask the live scene for a frame or a save-card thumbnail. A request waits for `SceneCaptureBinding` to mount, waits for the canvas to paint, retries a blank read and resolves with the image or a stated failure (`no-binding`, `no-frame`, `undecodable`), so a game stops polling for the binding and waiting frames before a save screenshot.
+- `registerSceneCapture` (`@jgengine/shell/render/sceneCapture`) lets a host that owns its own canvas hand the capture path a reader.
+- `createDownedState` (`@jgengine/core/combat/downed`) exposes `restore(next)`, the counterpart to `snapshot()`, so a saved bleed-out resumes with the same remaining seconds, revive progress, phase and banner timer instead of being rebuilt around a guessed countdown.
+
+### Changed
+
+- Pin Games to the 0.38.1 adoption
+- `GameMenu`'s `style` and `detailStyle` accept `--jg-*` custom properties (`GameMenuStyle`), so a game passes `{ "--jg-menu-surface-radius": "12px" }` without a cast.
+- `GameMenu` sets `pointer-events: auto` on its own root while its painted backdrop stays `none`, so a menu inside a HUD wrapper that passes clicks through to the scene no longer has dead buttons.
+- `check-stateful-ratchet` skips a factory carrying `// stateless: <reason>`, the named case for a catalog whose only closure state is an index of its own config. `createBuildSocketCatalog` declares it instead of being baselined.
+
+### Fixed
+
+- `bun run shoot` refuses a scene shot whose page has no 3D canvas, and scores rendered geometry inside the canvas region before writing the file. `bun run shoot <game> --view <name>` defaults to `--mode ui`, which renders the game's HUD preview over a CSS backdrop and creates no canvas; the whole-frame flat test was skipped without a region and the backdrop's full-screen paint withheld the viewport verdict, so a HUD-only frame was written with exit 0.
+- `countStaticBatchDraws` (`@jgengine/shell/world/staticObjectBatches`) counts the draws the static batches submit, so a variant level with no instance in a cell and a cell the camera culled are no longer reported as draws. `submitInstanceCount` (`@jgengine/shell/render/submittedDraws`) is the one place the batch, scatter, proxy and authored-primitive paths set an instance count and its visibility, and three issues a draw only when both say there is something to draw.
+- `createCastRunner.state()` carries the cast's `moveTolerance`, `moveDeadzone` and `movedTotal`, and `restore(next)` resumes it. A cast saved mid-fight used to come back with a fresh movement budget, so the caster could walk further than the ability allowed.
+- `createDecayMeterSet.serialize()` / `restore(next)` carry each meter's value, base rate and `setRateModifier` multiplier. A save used to drop a tuned rate, so a cold biome's faster warmth drain reset to the config rate on load.
+- `createAreaEffectField.restore(state)`, `createSelectionBookmarks.restore(snapshot)` and `createPlotPermissions.restore(snapshot)` are the state-in counterparts to their existing `serialize()` / `snapshot()`; restoring into a live field releases the members the saved state does not carry.
+- `check-stateful-ratchet` names the round-trip gap separately and caps it: a `snapshot()` with no `restore()`/`reset()` fails as `round-trip` debt, `--write` refuses to raise that ceiling, and a group paid below its ceiling must lower it. `createDownedState` was baselined when the ratchet shipped and never revisited; the restores in this release take the baseline from 113 entries to 93 and the `round-trip` ceiling from 8 to 2.
+
+## 0.38.1
+
+### Migrate
+
+- **Bump lockstep SDK packages to `^0.38.1`:** `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.35.1`; `@jgengine/github` is `0.25.1`.
+- Nothing to migrate. `variantLevels()` was renamed to `ModelVariantConfig.shadows` before any release shipped it, so no published version ever exported it and no consumer can be holding one. A level that wants to stop paying the near level's shadow cost writes `{ url, shadows: "none" }`; leaving `shadows` out keeps the model's own answer.
+
+### Added
+
+- `ModelVariantConfig.shadows` (`@jgengine/core/world/modelLod`): a model variant level declares its own shadow participation as a plain field, `"inherit" | "cast" | "receive" | "both" | "none"`. `"inherit"`, the default, keeps the model's own `shadows`, so every existing model draws as before; a far level set to `"none"` leaves the shadow pass while still drawing its mesh.
+- `ModelShadowMode` (`@jgengine/core/world/modelLod`) names the four-value shadow vocabulary, and `ModelConfig.shadows` uses it.
+- `variantLevelModel` (`@jgengine/shell/render/singleVariantLod`) is the one place that resolves what a level draws and how it shadows; the single prop, batched prop and scatter paths all ask it, so a level's asset and its shadow answer cannot disagree.
+
+### Fixed
+
+- `SaveSlotsPane` cards are one box each: equal tracks, `grid-auto-rows: 1fr`, a card edge that reads over a bright scene, and a name that ellipsises instead of widening the card. A save with a long name and one with none produce the same card box.
+- `GameMenu` puts the primary verbs on their own scrim, so their labels stay legible over whatever the live scene is showing instead of relying on a text shadow.
+- The theme emits three menu tokens the slot card and the verb surface read: `--jg-menu-card-height` (`clamp(244px, 27vh, 300px)`), `--jg-menu-card-thumb` (`clamp(88px, 14vh, 160px)`) and `--jg-menu-surface-radius` (`8px`). A game overrides them in its own `HudTheme` instead of patching the menu components.
+
 ## 0.38.0
 
 ### Migrate

package/dist/area/areaEffectField.d.ts

@@ -115,6 +115,13 @@ export interface AreaEffectField<P> {
     clear(): AreaEffectEvent<P>[];
     /** Snapshot the persistent membership lifecycle for save/load; shapes are transient and re-supplied via `setSource`. */
     serialize(): AreaFieldState<P>;
+    /**
+     * Replace sources and membership with a {@link serialize} result — the save/load counterpart.
+     * Sources come back on a sentinel shape, so re-`setSource` live shapes before the next `step`.
+     * Members the restored state does not carry leave with reason `"cleared"`; survivors keep their
+     * refresh phase without an enter/leave churn.
+     */
+    restore(state: AreaFieldState<P>): AreaEffectEvent<P>[];
 }
 /**
  * Build a continuous area-effect field. Drive it with `setSource` (once per live source per tick, so

package/dist/area/areaEffectField.js

@@ -30,8 +30,9 @@ function shapeContains(shape, point) {
  */
 export function createAreaEffectField(state) {
     const sources = new Map();
-    if (state !== undefined) {
-        for (const source of state.sources) {
+    function applyState(next) {
+        sources.clear();
+        for (const source of next.sources) {
             sources.set(source.id, {
                 shape: SENTINEL_SHAPE,
                 payload: source.payload,
@@ -41,12 +42,14 @@ export function createAreaEffectField(state) {
                 members: new Map(),
             });
         }
-        for (const membership of state.memberships) {
+        for (const membership of next.memberships) {
             sources.get(membership.sourceId)?.members.set(membership.receiverId, {
                 sinceRefreshMs: membership.sinceRefreshMs,
             });
         }
     }
+    if (state !== undefined)
+        applyState(state);
     function leaveAll(rec, sourceId, reason) {
         const events = [];
         for (const receiverId of rec.members.keys()) {
@@ -171,5 +174,19 @@ export function createAreaEffectField(state) {
             }
             return out;
         },
+        restore(next) {
+            const kept = new Set(next.memberships.map((membership) => `${membership.sourceId}\u0000${membership.receiverId}`));
+            const events = [];
+            for (const [sourceId, rec] of sources) {
+                for (const receiverId of [...rec.members.keys()]) {
+                    if (kept.has(`${sourceId}\u0000${receiverId}`))
+                        continue;
+                    rec.members.delete(receiverId);
+                    events.push({ kind: "leave", sourceId, receiverId, stackKey: rec.stackKey, payload: rec.payload, reason: "cleared" });
+                }
+            }
+            applyState(next);
+            return events;
+        },
     };
 }

package/dist/combat/castRunner.d.ts

@@ -20,6 +20,12 @@ export interface CastBarSnapshot {
     remainingMs: number;
     /** Fill fraction in `[0, 1]` for the cast bar. */
     fraction: number;
+    /** Movement budget this cast was begun with; `Infinity` for a cast that tolerates travel. */
+    moveTolerance: number;
+    /** The caster's noise floor this cast was begun with. */
+    moveDeadzone: number;
+    /** Travel already spent against `moveTolerance` (sub-deadzone jitter excluded). */
+    movedTotal: number;
 }
 export type CastInterruptReason = "moved" | "cancelled" | "replaced";
 export type CastEvent = {
@@ -40,7 +46,14 @@ export interface CastRunner {
     /** Start a cast; `false` while one is already in flight (interrupt or let it finish first). */
     begin(config: CastConfig): boolean;
     casting(): boolean;
+    /** The in-flight cast's timing and remaining move budget, or `null` when idle. */
     state(): CastBarSnapshot | null;
+    /**
+     * Replace the in-flight cast with a snapshot from {@link state} — resuming a saved cast with the
+     * movement already spent against its budget, or clearing it with `null`. The derived `fraction`
+     * and `remainingMs` are recomputed; everything else is kept as saved.
+     */
+    restore(next: CastBarSnapshot | null): void;
     /** Interrupt the in-flight cast now; returns the interruption event, or `null` when idle. */
     interrupt(reason?: CastInterruptReason): CastEvent | null;
     /**

package/dist/combat/castRunner.js

@@ -16,6 +16,9 @@ export function createCastRunner() {
             elapsedMs: active.elapsedMs,
             remainingMs: Math.max(0, active.castTimeMs - active.elapsedMs),
             fraction,
+            moveTolerance: active.moveTolerance,
+            moveDeadzone: active.moveDeadzone,
+            movedTotal: active.movedTotal,
         };
     }
     return {
@@ -34,6 +37,20 @@ export function createCastRunner() {
         },
         casting: () => active !== null,
         state: snapshot,
+        restore(next) {
+            if (next === null) {
+                active = null;
+                return;
+            }
+            active = {
+                abilityId: next.abilityId,
+                castTimeMs: Math.max(0, next.castTimeMs),
+                moveTolerance: next.moveTolerance,
+                moveDeadzone: Math.max(0, next.moveDeadzone),
+                elapsedMs: Math.max(0, next.elapsedMs),
+                movedTotal: Math.max(0, next.movedTotal),
+            };
+        },
         interrupt(reason = "cancelled") {
             if (active === null)
                 return null;

package/dist/combat/downed.d.ts

@@ -30,7 +30,10 @@ export interface DownedState {
     phase(instanceId: string): DownedPhase;
     get(instanceId: string): DownedEntry | null;
     clear(instanceId: string): void;
+    /** Every tracked entity's phase, remaining bleed-out, revive progress and banner timer. */
     snapshot(): Record<string, DownedEntry>;
+    /** Replaces the tracked entities, resuming a saved bleed-out where it left off. */
+    restore(next: Record<string, DownedEntry>): void;
 }
 /**
  * A downed/bleed-out state that ticks toward death and that teammates can revive before the timer runs out.

package/dist/combat/downed.js

@@ -105,5 +105,16 @@ export function createDownedState(config) {
                 out[instanceId] = { ...entry };
             return out;
         },
+        restore(next) {
+            entries.clear();
+            for (const [instanceId, entry] of Object.entries(next)) {
+                entries.set(instanceId, {
+                    phase: entry.phase,
+                    bleedoutRemaining: entry.bleedoutRemaining,
+                    reviveProgress: entry.reviveProgress,
+                    bannerRemaining: entry.bannerRemaining,
+                });
+            }
+        },
     };
 }

package/dist/game/playableGame.d.ts

@@ -3,8 +3,8 @@ import type { AmbienceZoneDef } from "../audio/ambience.js";
 import type { AudioBusDef, SoundDef } from "../audio/audioFalloff.js";
 import type { AudioOcclusionConfig } from "../audio/occlusion.js";
 import type { MusicTheme } from "../audio/music.js";
-import type { ModelVariantLodConfig } from "../world/modelLod.js";
-export type { ModelVariantConfig, ModelVariantLodConfig } from "../world/modelLod.js";
+import type { ModelShadowMode, ModelVariantLodConfig } from "../world/modelLod.js";
+export type { ModelShadowMode, ModelVariantConfig, ModelVariantLodConfig } from "../world/modelLod.js";
 import type { UiCueOverrides } from "../audio/uiCues.js";
 import type { FeedbackCueOverrides } from "../audio/feedbackCues.js";
 import type { NoticeFeedConfig } from "./notices.js";
@@ -278,7 +278,7 @@ export interface ModelConfig {
     /** Hide named visual subtrees on this instance before placement measurement. Exact runtime names or unique original imported names resolve without removing bones or changing the cached model; missing or ambiguous names warn and leave existing visibility unchanged. Malformed lists reject before model or texture allocation. Omit or pass [] to retain imported visibility. */
     hiddenNodes?: readonly string[];
     /** Shadow participation of every mesh in the model. Default `"both"` (casts and receives); `"none"` for foliage cards, decals, or viewmodels that must never shadow the world. */
-    shadows?: "cast" | "receive" | "both" | "none";
+    shadows?: ModelShadowMode;
     /**
      * 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 —

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.38.0";
+export declare const VERSION = "0.38.2";
 /** 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,47 @@
 /** Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating. */
-export const VERSION = "0.38.0";
+export const VERSION = "0.38.2";
 /** Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`). */
 export const CHANGELOG = {
+    "0.38.2": {
+        migrate: [
+            "Bump lockstep SDK packages to `^0.38.2`: `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.35.2`; `@jgengine/github` is `0.25.2`.",
+        ],
+        added: [
+            "`requestSceneCapture` and `requestSceneThumbnail` (`@jgengine/shell/render/sceneCapture`) ask the live scene for a frame or a save-card thumbnail. A request waits for `SceneCaptureBinding` to mount, waits for the canvas to paint, retries a blank read and resolves with the image or a stated failure (`no-binding`, `no-frame`, `undecodable`), so a game stops polling for the binding and waiting frames before a save screenshot.",
+            "`registerSceneCapture` (`@jgengine/shell/render/sceneCapture`) lets a host that owns its own canvas hand the capture path a reader.",
+            "`createDownedState` (`@jgengine/core/combat/downed`) exposes `restore(next)`, the counterpart to `snapshot()`, so a saved bleed-out resumes with the same remaining seconds, revive progress, phase and banner timer instead of being rebuilt around a guessed countdown.",
+        ],
+        changed: [
+            "Pin Games to the 0.38.1 adoption",
+            "`GameMenu`'s `style` and `detailStyle` accept `--jg-*` custom properties (`GameMenuStyle`), so a game passes `{ \"--jg-menu-surface-radius\": \"12px\" }` without a cast.",
+            "`GameMenu` sets `pointer-events: auto` on its own root while its painted backdrop stays `none`, so a menu inside a HUD wrapper that passes clicks through to the scene no longer has dead buttons.",
+            "`check-stateful-ratchet` skips a factory carrying `// stateless: <reason>`, the named case for a catalog whose only closure state is an index of its own config. `createBuildSocketCatalog` declares it instead of being baselined.",
+            "`bun run shoot` refuses a scene shot whose page has no 3D canvas, and scores rendered geometry inside the canvas region before writing the file. `bun run shoot <game> --view <name>` defaults to `--mode ui`, which renders the game's HUD preview over a CSS backdrop and creates no canvas; the whole-frame flat test was skipped without a region and the backdrop's full-screen paint withheld the viewport verdict, so a HUD-only frame was written with exit 0.",
+            "`countStaticBatchDraws` (`@jgengine/shell/world/staticObjectBatches`) counts the draws the static batches submit, so a variant level with no instance in a cell and a cell the camera culled are no longer reported as draws. `submitInstanceCount` (`@jgengine/shell/render/submittedDraws`) is the one place the batch, scatter, proxy and authored-primitive paths set an instance count and its visibility, and three issues a draw only when both say there is something to draw.",
+            "`createCastRunner.state()` carries the cast's `moveTolerance`, `moveDeadzone` and `movedTotal`, and `restore(next)` resumes it. A cast saved mid-fight used to come back with a fresh movement budget, so the caster could walk further than the ability allowed.",
+            "`createDecayMeterSet.serialize()` / `restore(next)` carry each meter's value, base rate and `setRateModifier` multiplier. A save used to drop a tuned rate, so a cold biome's faster warmth drain reset to the config rate on load.",
+            "`createAreaEffectField.restore(state)`, `createSelectionBookmarks.restore(snapshot)` and `createPlotPermissions.restore(snapshot)` are the state-in counterparts to their existing `serialize()` / `snapshot()`; restoring into a live field releases the members the saved state does not carry.",
+            "`check-stateful-ratchet` names the round-trip gap separately and caps it: a `snapshot()` with no `restore()`/`reset()` fails as `round-trip` debt, `--write` refuses to raise that ceiling, and a group paid below its ceiling must lower it. `createDownedState` was baselined when the ratchet shipped and never revisited; the restores in this release take the baseline from 113 entries to 93 and the `round-trip` ceiling from 8 to 2.",
+        ],
+        removed: [],
+    },
+    "0.38.1": {
+        migrate: [
+            "Bump lockstep SDK packages to `^0.38.1`: `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.35.1`; `@jgengine/github` is `0.25.1`.",
+            "Nothing to migrate. `variantLevels()` was renamed to `ModelVariantConfig.shadows` before any release shipped it, so no published version ever exported it and no consumer can be holding one. A level that wants to stop paying the near level's shadow cost writes `{ url, shadows: \"none\" }`; leaving `shadows` out keeps the model's own answer.",
+        ],
+        added: [
+            "`ModelVariantConfig.shadows` (`@jgengine/core/world/modelLod`): a model variant level declares its own shadow participation as a plain field, `\"inherit\" | \"cast\" | \"receive\" | \"both\" | \"none\"`. `\"inherit\"`, the default, keeps the model's own `shadows`, so every existing model draws as before; a far level set to `\"none\"` leaves the shadow pass while still drawing its mesh.",
+            "`ModelShadowMode` (`@jgengine/core/world/modelLod`) names the four-value shadow vocabulary, and `ModelConfig.shadows` uses it.",
+            "`variantLevelModel` (`@jgengine/shell/render/singleVariantLod`) is the one place that resolves what a level draws and how it shadows; the single prop, batched prop and scatter paths all ask it, so a level's asset and its shadow answer cannot disagree.",
+        ],
+        changed: [
+            "`SaveSlotsPane` cards are one box each: equal tracks, `grid-auto-rows: 1fr`, a card edge that reads over a bright scene, and a name that ellipsises instead of widening the card. A save with a long name and one with none produce the same card box.",
+            "`GameMenu` puts the primary verbs on their own scrim, so their labels stay legible over whatever the live scene is showing instead of relying on a text shadow.",
+            "The theme emits three menu tokens the slot card and the verb surface read: `--jg-menu-card-height` (`clamp(244px, 27vh, 300px)`), `--jg-menu-card-thumb` (`clamp(88px, 14vh, 160px)`) and `--jg-menu-surface-radius` (`8px`). A game overrides them in its own `HudTheme` instead of patching the menu components.",
+        ],
+        removed: [],
+    },
     "0.38.0": {
         migrate: [
             "Bump lockstep SDK packages to `^0.38.0`: `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.35.0`; `@jgengine/github` is `0.25.0`.",

package/dist/scene/selectionBookmarks.d.ts

@@ -56,6 +56,8 @@ export interface SelectionBookmarks {
     prune(isValid: (id: string) => boolean): SelectionPruneResult;
     /** A plain-data copy of every bookmark — the exact input {@link createSelectionBookmarks} restores. */
     serialize(): SelectionBookmarkSnapshot;
+    /** Replace every bookmark with a {@link serialize} snapshot — re-deduped, empty sets dropped. */
+    restore(snapshot: SelectionBookmarkSnapshot): void;
 }
 /**
  * Create a keyed bookmark store, optionally restored from a {@link serialize}

package/dist/scene/selectionBookmarks.js

@@ -18,13 +18,16 @@ function dedupe(ids) {
  */
 export function createSelectionBookmarks(snapshot) {
     const groups = new Map();
-    if (snapshot !== undefined) {
-        for (const [key, ids] of Object.entries(snapshot.bookmarks)) {
+    function load(next) {
+        groups.clear();
+        for (const [key, ids] of Object.entries(next.bookmarks)) {
             const list = dedupe(ids);
             if (list.length > 0)
                 groups.set(key, list);
         }
     }
+    if (snapshot !== undefined)
+        load(snapshot);
     return {
         bind(key, ids) {
             const list = dedupe(ids);
@@ -94,6 +97,7 @@ export function createSelectionBookmarks(snapshot) {
         serialize: () => ({
             bookmarks: Object.fromEntries([...groups].map(([key, list]) => [key, [...list]])),
         }),
+        restore: load,
     };
 }
 /**

package/dist/survival/decayMeter.d.ts

@@ -32,6 +32,18 @@ export interface DecayMeterState {
     /** 0..1 fill. */
     fraction: number;
 }
+/**
+ * The whole persisted state of a {@link DecayMeterSet}: every meter's value plus the play-time rate
+ * changes `setRate` and `setRateModifier` applied. A save that carries only values resumes a tuned
+ * meter at its config rate, which is how a cold biome's faster warmth drain vanished on load.
+ */
+export interface DecayMeterSetState {
+    values: DecayMeterValues;
+    /** Current base rate per meter id, including any `setRate` override. */
+    rates: Record<string, number>;
+    /** Rate multiplier per meter id from `setRateModifier`; a missing id means `1`. */
+    modifiers: Record<string, number>;
+}
 /** Set of named survival meters (hunger/thirst/…) that drain and refill over game time. */
 export interface DecayMeterSet {
     /** Drain/fill every meter by `rate * rateModifier * dt`. Call once per game tick. */
@@ -46,14 +58,21 @@ export interface DecayMeterSet {
     setRateModifier(id: string, multiplier: number): void;
     /** Moodles for every crossed threshold, worst-first per meter. */
     moodles(): Moodle[];
-    /** True while any threshold with the given severity (or worse) is active — cheap game gate. */
+    /** Every meter's numeric state for a HUD — the display view; {@link serialize} is the save pair. */
     snapshot(): Record<string, DecayMeterState>;
+    /** Values, base rates and rate modifiers — the full state to persist; see {@link restore}. */
+    serialize(): DecayMeterSetState;
+    /**
+     * Put a {@link serialize} result back: values, base rates and rate modifiers. Meters the state
+     * omits keep their current value and rate, and a modifier it omits is cleared.
+     */
+    restore(next: DecayMeterSetState): void;
     ids(): readonly string[];
 }
 /**
- * Plain-data meter values: `meter id → current value`. This is the whole serialized
- * form — it drops straight into a `defineGame` state record and round-trips through
- * save/load and multiplayer sync with no closure to rebuild.
+ * Plain-data meter values: `meter id → current value`. The value half of a save — a tuned meter
+ * also needs its rate and rate modifiers, which {@link DecayMeterSetState} carries and
+ * {@link createDecayMeterSet}'s `serialize`/`restore` hand back and forth.
  */
 export type DecayMeterValues = Record<string, number>;
 /**

package/dist/survival/decayMeter.js

@@ -160,6 +160,29 @@ export function createDecayMeterSet(configs) {
         snapshot() {
             return decayMeterSnapshot(values, defs);
         },
+        serialize() {
+            const rates = {};
+            for (const def of defs)
+                rates[def.id] = def.rate;
+            return { values: { ...values }, rates, modifiers: { ...modifiers } };
+        },
+        restore(next) {
+            const restored = {};
+            for (const def of defs) {
+                const rate = next.rates[def.id];
+                if (rate !== undefined)
+                    def.rate = rate;
+                const modifier = next.modifiers[def.id];
+                if (modifier === undefined)
+                    delete modifiers[def.id];
+                else
+                    modifiers[def.id] = modifier;
+                const value = next.values[def.id];
+                if (value !== undefined)
+                    restored[def.id] = value;
+            }
+            values = restored;
+        },
         ids() {
             return order;
         },

package/dist/world/buildPermissions.d.ts

@@ -26,6 +26,8 @@ export interface PlotPermissions {
     setGuild(guildId: string | null, role?: BuildRole): void;
     transferOwner(userId: string): void;
     snapshot(): PlotPermissionSnapshot;
+    /** Replace owner, guild and grants from a {@link snapshot}; plot identity stays the config's. */
+    restore(next: PlotPermissionSnapshot): void;
 }
 export declare function createPlotPermissions(config: PlotPermissionConfig): PlotPermissions;
 export type ContributionGoal = Readonly<Record<string, number>>;

package/dist/world/buildPermissions.js

@@ -52,6 +52,16 @@ export function createPlotPermissions(config) {
                 ...(guildRole === undefined ? {} : { guildRole }),
             };
         },
+        restore(next) {
+            ownerId = next.ownerId;
+            guildId = next.guildId;
+            guildRole = next.guildRole;
+            roles.clear();
+            for (const [userId, role] of Object.entries(next.roles)) {
+                if (userId !== next.ownerId)
+                    roles.set(userId, role);
+            }
+        },
     };
 }
 export function createContributionPool(goal) {

package/dist/world/buildSockets.js

@@ -82,6 +82,7 @@ export function pieceSocketsFromModel(sockets, kindOf, yawOf) {
  *
  * @capability build-socket-catalog data-driven named-socket snap catalog for modular base building
  */
+// stateless: pieces, rules and their lookup indexes are built once from `config` and never written after the factory returns, so the constructor is the whole state
 export function createBuildSocketCatalog(config) {
     const cellSize = config.cellSize ?? 1;
     const pieces = new Map();

package/dist/world/modelLod.d.ts

@@ -1,10 +1,18 @@
 import type { LodBand } from "./lod.js";
-/** One mesh level of a {@link ModelVariantLodConfig}: a full or decimated GLB and how far it draws. */
+/** How a model, or one of its variant levels, takes part in the shadow pass. */
+export type ModelShadowMode = "cast" | "receive" | "both" | "none";
+/** One mesh level of a {@link ModelVariantLodConfig}: a full or decimated GLB, how far it draws and how it shadows. */
 export interface ModelVariantConfig {
     /** GLB url for this level — the source asset for the near level, a decimated asset for the far ones. */
     url: string;
     /** Furthest distance in metres from the camera this level draws. The last level omits it and covers everything beyond the level before it. */
     maxDistance?: number;
+    /**
+     * This level's shadow participation. `"inherit"` (the default) keeps the model's own `shadows`, so a
+     * level that says nothing draws exactly as it did before levels could choose. A far level set to
+     * `"none"` leaves the shadow pass entirely while still drawing its mesh.
+     */
+    shadows?: ModelShadowMode | "inherit";
 }
 /**
  * Ordered mesh detail levels for one model, switched per instance by camera distance. The first level

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/core",
-  "version": "0.38.0",
+  "version": "0.38.2",
   "description": "jgengine core — pure-TypeScript game framework SDK (npm @jgengine/core). Entity stores, commands, combat, inventory, multiplayer seams. Zero dependencies. Not an ECS. Agent skills ship in the tarball. https://jgengine.com",
   "keywords": [
     "jgengine",

package/skills/jgengine/api.md

@@ -6,7 +6,7 @@
 
 - `CHANGELOG` (const): const CHANGELOG: Record<string, ChangelogEntry> — Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`).
 - `ChangelogEntry` (interface): interface ChangelogEntry — One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md).
-- `VERSION` (const): const VERSION: "0.38.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.38.2" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/authoring
 
@@ -285,7 +285,7 @@
 
 - `CHANGELOG` (const): const CHANGELOG: Record<string, ChangelogEntry> — Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`).
 - `ChangelogEntry` (interface): interface ChangelogEntry — One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md).
-- `VERSION` (const): const VERSION: "0.38.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.38.2" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/runtime/adapter
 

package/skills/jgengine-combat/api.md

@@ -389,7 +389,7 @@
 
 ## @jgengine/core/combat/castRunner
 
-- `CastBarSnapshot` (interface): interface CastBarSnapshot { abilityId: string; castTimeMs: number; elapsedMs: number; remainingMs: number; fraction: number } — ⚠ undocumented
+- `CastBarSnapshot` (interface): interface CastBarSnapshot { abilityId: string; castTimeMs: number; elapsedMs: number; remainingMs: number; fraction: number; moveTolerance: number; moveDeadzone: number; movedTotal: number } — ⚠ undocumented
 - `CastConfig` (interface): interface CastConfig { abilityId: string; castTimeMs: number; moveTolerance?: number; moveDeadzone?: number } — ⚠ undocumented
 - `CastEvent` (type): type CastEvent = | { kind: "completed"; abilityId: string } | { kind: "interrupted"; abilityId: string; reason: CastInterruptReason } — ⚠ undocumented
 - `CastInterruptReason` (type): type CastInterruptReason = "moved" | "cancelled" | "replaced" — ⚠ undocumented

package/skills/jgengine-gameplay/api.md

@@ -922,7 +922,8 @@
 - `ModelMaterialOverride` (interface): interface ModelMaterialOverride extends MaterialSurfaceParameters — Per-entity PBR material override (#151.3) applied to every standard or physical material in the model's cloned scene graph.
 - `ModelPart` (interface): interface ModelPart — Static child model stacked at a fixed local offset under its parent's transform — no bone/rig resolution, unlike `ModelAttachment`. Assembles a compound entity (e.g. a modular castle wall + tower + roof) from several single-mesh kit pieces.
 - `ModelRimLight` (interface): interface ModelRimLight — Fresnel rim-light term added on top of a model's lighting — see {@link ModelMaterialOverride.rim}.
-- `ModelVariantConfig` (interface): interface ModelVariantConfig — One mesh level of a {@link ModelVariantLodConfig}: a full or decimated GLB and how far it draws.
+- `ModelShadowMode` (type): type ModelShadowMode = "cast" | "receive" | "both" | "none" — How a model, or one of its variant levels, takes part in the shadow pass.
+- `ModelVariantConfig` (interface): interface ModelVariantConfig — One mesh level of a {@link ModelVariantLodConfig}: a full or decimated GLB, how far it draws and how it shadows.
 - `ModelVariantLodConfig` (interface): interface ModelVariantLodConfig — Ordered mesh detail levels for one model, switched per instance by camera distance. The first level is the full mesh the model's own `url` names; every later level is a cheaper asset. A tree line uses this so near trees keep their full mesh while far ones draw a decimated copy of the same species.
 - `ModelWindConfig` (interface): interface ModelWindConfig — Wind sway for a foliage model; see {@link ModelConfig.wind}.
 - `MovementCommitFrame` (interface): interface MovementCommitFrame — One frame's movement resolution handed to `PlayerMovementConfig.beforeCommit`.
@@ -1341,7 +1342,7 @@
 - `DEFAULT_RIDE_RATING_RANGE` (const): const DEFAULT_RIDE_RATING_RANGE: RideRatingRange — A 0–10 rating scale, the usual shape of a ride catalog. Override it when a park rates differently.
 - `DEFAULT_TOUCH_STYLE` (const): const DEFAULT_TOUCH_STYLE: TouchStyle — Skin used when neither the game nor the player picks one.
 - `DecayMeterSet` (interface): interface DecayMeterSet — Set of named survival meters (hunger/thirst/…) that drain and refill over game time.
-- `DecayMeterValues` (type): type DecayMeterValues = Record<string, number> — Plain-data meter values: `meter id → current value`. This is the whole serialized form — it drops straight into a `defineGame` state record and round-trips through save/load and multiplayer sync with no closure to rebuild.
+- `DecayMeterValues` (type): type DecayMeterValues = Record<string, number> — Plain-data meter values: `meter id → current value`. The value half of a save — a tuned meter also needs its rate and rate modifiers, which {@link DecayMeterSetState} carries and {@link createDecayMeterSet}'s `serialize`/`restore` hand back and forth.
 - `DecayModifier` (type): type DecayModifier = number | Record<string, number> — Rate multiplier for {@link decayMeters}: one scalar applied to every meter (a member's metabolism, a game-mode harshness dial) or a per-meter record (cold biome → warmth only). `1` / omitted leaves the base rates unscaled.
 - `DefendMissionOptions` (interface): interface DefendMissionOptions extends ComposedMissionOptions — Options for {@link defendMission}: hold a position, scored by what is left standing.
 - `DeliveryEntry` (interface): interface DeliveryEntry { id: string; userId: string; inventoryId: string; items: readonly ItemStack[]; deliverAt: number } — ⚠ undocumented
@@ -2877,8 +2878,9 @@
 
 - `DecayMeterConfig` (interface): interface DecayMeterConfig { id: string; max: number; min?: number; start?: number; rate: number; thresholds?: readonly MeterThreshold[] } — ⚠ undocumented · used by `createDecayMeterSet`: Named decay meters — hunger, thirst, oxygen, sanity, warmth, stamina.
 - `DecayMeterSet` (interface): interface DecayMeterSet — Set of named survival meters (hunger/thirst/…) that drain and refill over game time.
+- `DecayMeterSetState` (interface): interface DecayMeterSetState — The whole persisted state of a {@link DecayMeterSet}: every meter's value plus the play-time rate changes `setRate` and `setRateModifier` applied. A save that carries only values resumes a tuned meter at its config rate, which is how a cold biome's faster warmth drain vanished on load.
 - `DecayMeterState` (interface): interface DecayMeterState { id: string; value: number; max: number; min: number; fraction: number } — ⚠ undocumented · used by `decayMeterSnapshot`: Numeric state for every meter, keyed by id — the pure counterpart to {@link DecayMeterSet.snapshot}.
-- `DecayMeterValues` (type): type DecayMeterValues = Record<string, number> — Plain-data meter values: `meter id → current value`. This is the whole serialized form — it drops straight into a `defineGame` state record and round-trips through save/load and multiplayer sync with no closure to rebuild.
+- `DecayMeterValues` (type): type DecayMeterValues = Record<string, number> — Plain-data meter values: `meter id → current value`. The value half of a save — a tuned meter also needs its rate and rate modifiers, which {@link DecayMeterSetState} carries and {@link createDecayMeterSet}'s `serialize`/`restore` hand back and forth.
 - `DecayModifier` (type): type DecayModifier = number | Record<string, number> — Rate multiplier for {@link decayMeters}: one scalar applied to every meter (a member's metabolism, a game-mode harshness dial) or a per-meter record (cold biome → warmth only). `1` / omitted leaves the base rates unscaled.
 - `MeterThreshold` (interface): interface MeterThreshold { id: string; label: string; at: number; when: "below" | "above"; severity?: MoodleSeverity; icon?: string } — ⚠ undocumented
 - `createDecayMeterSet` (function): function createDecayMeterSet(configs: readonly DecayMeterConfig[]): DecayMeterSet — Named decay meters — hunger, thirst, oxygen, sanity, warmth, stamina. Each drains (or recovers) on game-time `dt` at a configurable rate, refills from consumables or actions, and raises moodle statuses at thresholds. Rate modifiers let the environment drive them (colder → faster warmth loss; toxic biome → oxygen drops), so a game reads an environment field then calls `setRateModifier`.

package/skills/jgengine-world/api.md

@@ -2655,7 +2655,7 @@
 - `ModelAssetRef` (interface): interface ModelAssetRef { url: string; anchor?: "center" | "origin"; dims?: ModelDims; collisionMesh?: CollisionMeshData; space?: AssetSpace; clips?: readonly string[] } — ⚠ undocumented · used by `createHostedWorldSessionAsync` (@jgengine/core/runtime/hostedWorldSession): Build a hosted session from an asynchronous persistence backend.
 - `ModelDims` (interface): interface ModelDims — Measured horizontal footprint, footprint center, and lowest Y of a model in model space.
 - `ModelNode` (interface): interface ModelNode — Generic named-socket reader for loaded 3D models. Walks a node tree (any object with `.name`, `.position`, and `.children` — structurally satisfied by `THREE.Object3D`) and collects the local offsets of nodes whose name marks an attachment point. Genre-agnostic: wire anchors on a pylon, muzzle/hand mounts on a character, hardpoints on a ship, seat/decal slots on furniture — anything an artist tags with an empty in the GLB. Pure data (no three.js import), so it lives in core.
-- `ModelVariantConfig` (interface): interface ModelVariantConfig — One mesh level of a {@link ModelVariantLodConfig}: a full or decimated GLB and how far it draws.
+- `ModelVariantConfig` (interface): interface ModelVariantConfig — One mesh level of a {@link ModelVariantLodConfig}: a full or decimated GLB, how far it draws and how it shadows.
 - `ModelVariantLodConfig` (interface): interface ModelVariantLodConfig — Ordered mesh detail levels for one model, switched per instance by camera distance. The first level is the full mesh the model's own `url` names; every later level is a cheaper asset. A tree line uses this so near trees keep their full mesh while far ones draw a decimated copy of the same species.
 - `ModelVariantSelector` (interface): interface ModelVariantSelector — Per-instance distance switch over a model's detail levels: one answer per id, held across a boundary until the instance clears it.
 - `ModelVariantSelectorState` (interface): interface ModelVariantSelectorState — Plain JSON state of a {@link ModelVariantSelector}: each id's current level index.
@@ -4041,7 +4041,8 @@
 ## @jgengine/core/world/modelLod
 
 - `DEFAULT_VARIANT_HYSTERESIS` (const): const DEFAULT_VARIANT_HYSTERESIS: 6 — Metres an instance must travel past a switch boundary before it changes level unless the model declares its own.
-- `ModelVariantConfig` (interface): interface ModelVariantConfig — One mesh level of a {@link ModelVariantLodConfig}: a full or decimated GLB and how far it draws.
+- `ModelShadowMode` (type): type ModelShadowMode = "cast" | "receive" | "both" | "none" — How a model, or one of its variant levels, takes part in the shadow pass.
+- `ModelVariantConfig` (interface): interface ModelVariantConfig — One mesh level of a {@link ModelVariantLodConfig}: a full or decimated GLB, how far it draws and how it shadows.
 - `ModelVariantLodConfig` (interface): interface ModelVariantLodConfig — Ordered mesh detail levels for one model, switched per instance by camera distance. The first level is the full mesh the model's own `url` names; every later level is a cheaper asset. A tree line uses this so near trees keep their full mesh while far ones draw a decimated copy of the same species.
 - `ModelVariantSelector` (interface): interface ModelVariantSelector — Per-instance distance switch over a model's detail levels: one answer per id, held across a boundary until the instance clears it.
 - `ModelVariantSelectorState` (interface): interface ModelVariantSelectorState — Plain JSON state of a {@link ModelVariantSelector}: each id's current level index.