@jgengine/core 0.15.0-next.0 → 0.16.0

package/CHANGELOG.md

@@ -28,6 +28,49 @@ At publish, rename this heading to the new version and mirror the entries into
 
 ### Migrate
 
+### Changed
+
+### Added
+
+### Fixed
+
+## 0.16.0
+
+### Migrate
+
+- **Bump lockstep SDK packages to `^0.16.0`:** `@jgengine/{core,react,ws,node,sql,convex,shell,editor,assets}`. CLI `jgengine` is `0.13.0`; `@jgengine/github` is `0.3.0`.
+- **Placed objects now replicate.** `objects` joined the always-on baseline snapshot modules, so `ctx.hydrate` replaces the client's placed object set with the host's, the way `entities` already did. A game whose peers all run the same authored placement is unaffected; a game that places props on the client only, after hydrate, must move that placement to the host or keep it out of `ctx.scene.object`.
+
+### Changed
+
+- **`GeneratedBuilding`'s `kit` prop is now the `BuildingKit`**; the per-part React escape hatch it used to name moved to `partRenderer`, so `kit` means the same thing on `GeneratedBuilding` and `InstancedBuildings`. Rename the prop if you passed a `BuildingKitRenderer`.
+
+### Added
+
+- **`modelLoadFallbacks()` from `@jgengine/shell/render/modelLoad`** lists every model the shared loader diagnosed as broken and replaced with a magenta placeholder. A placeholder was only ever a console warning, so a shipped game could render one in its starting area and nobody found out until someone looked at a screenshot; a capture host or smoke test can now require the list to be empty. `clearModelLoadFallbacks()` resets it between runs.
+- **`worldHealthBars.occlude` / `WorldHealthBars`+`WorldNameplates` `occlude` prop.** World bars and nameplates are a screen-space overlay drawn outside the WebGL depth buffer, so nothing in the scene can hide them and an enemy's health bar reads straight through the building it stands behind. Set `occlude: true` to drop a bar when world geometry blocks the line from the player to the entity. Default `false` preserves the always-visible behaviour every shipped game currently relies on.
+
+- **`DustField` + `WeatherLayer` mode `"dust"` (`@jgengine/shell/weather`) — wind-borne particulate.** `WeatherLayer` could only do `clear`/`rain`/`snow`/`mixed`, so an arid, volcanic, ashen, or blown-out world had no way to put anything in the air. Dust drifts on horizontal wind with a slow vertical bob rather than falling; `groundBias` packs density toward the surface, motes fade near the top of the volume so recycled ones do not pop against the sky, and faster motes ride higher. Set `dustAlways` to keep it in the air alongside rain or snow instead of replacing them. Defaults `DEFAULT_DUST_COUNT`/`DEFAULT_DUST_DENSITY` sit beside the rain and snow pair.
+
+- **Authored `city` volumes render their near-LOD facades with a `BuildingKit`.** `CityRules.buildingKit` names a kit; a game registers the bound art with `registerBuildingKit(kit)` from `@jgengine/shell/structures/buildingKitRegistry` and the scene document carries only the name, so a city stays portable and free of model paths. Unset or unknown names keep the palette blocks. This puts the whole `city` primitive — not just the `building()` feature — on the kit path.
+- **`BuildingKit` from `@jgengine/core/world/buildingKit`** binds a generated building's facade part slots to real models, so procedural buildings render as an instanced asset kit instead of untextured blocks. `defineBuildingKit({ parts: { wall: ["Wall_A.glb", …] } })` maps a part kind — or a `${facade}.${kind}` slot — to ordered variants that `kit.variant` indexes, with `fit`/`offset`/`rotation`/`scale`/`tint`/`autoOrient` per variant. Kinds a kit leaves unbound keep rendering the palette block, so a partial kit is a valid kit, and `omit` drops a kind entirely. Pass one through `building({ kit })` or straight to `InstancedBuildings`; `buildingKitVariantCounts(kit)` feeds `generateBuilding` so its seeded picks span exactly the models the kit binds.
+- **`generateBuilding`, `generateBuildingDistrict`, and `createBuildingConfig` are now documented public API** (`@jgengine/core/world/buildings`) and appear in `capabilities.md` under `building-generator`.
+- **`capture.views` on `defineGame`** — named framings (`GameCaptureView`: `look`, `lookFrom`, `spawn`, `state`, `run`, `settleMs`) that `shoot <game> --view <name>` and `drive --view <name>` replay exactly, so a before/after pair is the same view by construction. `shoot <game> --list-views` prints what a game declares; an unknown name fails listing them, and any explicit capture flag still wins over the view's value.
+- **`modelLoadIdleMs()` from `@jgengine/shell/render/modelLoad`** reports how long the shared GLB loader has been idle (`0` while a model is in flight). Capture hosts wait on it instead of guessing a settle delay, so an establishing shot no longer races streaming models.
+- **Per-instance state on placed objects** — `SceneObject.state` (opaque `Record`), set through `ctx.scene.object.setState`/`patchState`/`place({ state })`. It survives move/rotate/setVisual, replicates and saves with the object, and round-trips as `RuntimeObjectRow.flags` via `toRuntimeObjectRow`/`fromRuntimeObjectRow` (`@jgengine/core/multiplayer`). A chest's locked flag or a machine's fill level no longer needs a game-owned map keyed by `instanceId`.
+- **`slotInventory` is a working feature** — `ctx.scene.object.slots` gives objects whose catalog entry declares it real per-instance container contents: `layout`/`state`/`count`, `put`/`take`, and `transferIn`/`transferOut` between a player inventory and the object, all validated against the declared slot count, `accepts` kind filter, and stack limits, with neither side mutated on a rejection. Contents live on `SceneObject.slots`, so they replicate and save with the placement.
+- **`loadServerSnapshot` and `persistServerSnapshot` are public** (`@jgengine/convex/server`), and `createGameServerFunctions` also returns `helpers` (`loadSnapshot`, `applyCommand`, `persistSnapshot`, `runCommand`) bound to the same runtimes and auth mode. A host mutation can now pair snapshot work with its own table writes in one transaction; the registered `runCommand` mutation delegates to `helpers.runCommand`, so there is one implementation.
+
+### Fixed
+
+- **Open storefronts are no longer holes through the building.** `generateBuilding` emitted an open ground-floor store as a lone `storefront` panel with no wall behind it, while every upper-floor window was correctly backed by one. Storefront and window materials render at 0.56 opacity and a generated building is a hollow shell, so those bays let you see straight through the building to the world beyond — and open stores only land on the street-facing facade, so a row of shops along a road was the worst case. The bay now emits its wall first, exactly as an upper floor does.
+- **`joinServer`, `flushSave`, `flushDirtyServers`, and the `auto` autosave can write player profiles again.** All four cleared the snapshot's dirty set before handing it to the persist plan, which gates profile writes on exactly that set — so the functions named "flush" flushed the server row and chunks only, and an `onNewPlayer` grant (starting money, starting items) never reached `jgPlayerProfiles`. `joinServer` now persists the snapshot it just marked; the flush paths mark every player dirty first, since hydrating from storage resets the dirty set. `planServerPersist` also clears `dirtyAt` once everything outstanding is written, so a successful flush stops autosave from re-firing forever, and a profile patch no longer clobbers a host-maintained `dirtyAt`.
+
+## 0.15.0
+
+### Migrate
+
+- **Bump lockstep SDK packages to `^0.15.0`:** `@jgengine/{core,react,ws,node,sql,convex,shell,editor,assets}`. CLI `jgengine` is `0.12.0`; `@jgengine/github` is `0.2.0`.
 - **`jgengine create` scaffolds a textured world by default (#1550).** `--world` is now the default and `--no-world` is the opt-out (matching `--no-editor`); `--world` is still accepted. The default scaffold previously emitted untextured proxy geometry, which the AGENTS.md it ships declares a failing result. `create` now also pulls the starter asset packs into `public/models` after install, and never fails the scaffold if that pull cannot run (offline, blocked proxy, `--no-install`) — it prints `npx assets pull starter` in next steps instead, and the emitted AGENTS.md documents the same command. Skip the pull explicitly with `--no-assets`.
 - **Start game code at `@jgengine/shell/gameKit` (#1541).** Prefer that surface for `defineGame`, `GameHost`, stores, systems, authored-scene helpers, and HUD building blocks. `@jgengine/core/authoring` remains for pure core helpers the kit does not re-export but is no longer a competing start-here path.
 - **Every game must now declare its run-phase story — silence is a gate error (#1337).** The run-phase
@@ -73,10 +116,16 @@ At publish, rename this heading to the new version and mirror the entries into
 
 ### Added
 
+- **`advanceStepCadence` (`@jgengine/core/audio/stepCadence`) — distance-driven footstep timing.** Pure state-in/state-out: feed it the ground distance a mover covered this frame and it reports how many steps landed and which foot led, so foley stays locked to distance instead of a wall-clock timer that desyncs the moment speed changes. Configurable stride, per-advance `strideScale` for crouch/sprint, and a shorter first step from rest so walking off is heard immediately.
+- **`resolveMusicState` (`@jgengine/core/audio/musicState`) — combat-reactive soundtrack selection.** The engine could already crossfade themes but nothing decided *when*, so every game re-handrolled the threshold and got a track that flapped as one enemy walked in and out of range. Give it a tier ladder (intensity → theme) and it resolves the theme to play: escalation is immediate, de-escalation waits for the tier's `holdMs` and needs intensity to fall a `release` margin below the tier it is leaving. Pure and serialisable.
+- **Synth voices take a `sustain` (`ToneVoice`/`NoiseVoice`).** Seconds held at full gain before the decay. Default 0 preserves every existing patch. Without it there was no way to author a *sustained* sound at all: every voice decayed to silence inside its duration, so a patch rendered once and looped as an ambient bed pulsed audibly once per loop. Set `sustain` to `duration` for a flat wind, rain, or machine-hum bed that loops seamlessly.
+
 - **`ModelMaterialOverride.rim` — a fresnel rim light on any entity/object model.** `{ color, strength, power }` adds a bright edge where the surface turns away from the viewer, patched into the material's own shader so it shadows, fogs, and tonemaps with the body rather than floating in front of it. This is the standard fix for an actor that shares a value band with its ground: no albedo choice separates a body from terrain lit by the same key, but an edge does. Omit for no rim (default).
 
 ### Fixed
 
+- **Noise voices longer than the shared noise buffer no longer go silent partway through.** The 1-second buffer is sampled from a random offset, so any `NoiseVoice` whose duration exceeded the remainder ran off the end and finished in silence — invisible on short impact bursts, fatal for anything sustained. The source now wraps; the voice still ends on time.
+
 - **`terrain({ detail: { material: { tint } } })` separates a ground texture's grain from its hue.** A detail material's colour map used to replace the terrain's authored colour outright, so the biome palette, macro sweeps, and slope-rock blend under it were painted over and a whole region flattened to the texture's single hue — despite the API documenting that it "blends with, never replaces". `tint` defaults to 1 (the existing behaviour, so no shipped game changes); drop it toward 0 to keep the authored colour and take only the map's light and shade.
 - **`sky({ gradientExponent, cloudiness })` are now authorable — and `sky()` no longer silently drops them.** `gradientExponent` controls how fast the gradient reaches `zenithColor` off the horizon (default 0.65, unchanged): below 1 pulls the zenith hue down into the frame, which is what an eye-level camera in flat terrain actually needs — at the default the sky reads as one horizon-coloured wash however saturated the authored zenith is. `cloudiness` (default 0.35, unchanged) is the procedural cloud-band opacity.
 - **A model that throws while rendering is now reported instead of vanishing (#1588).** `ModelFallbackBoundary` swapped in its fallback (usually nothing) and stayed silent: `probes.fallbacks` stayed empty, no warning was logged, and an entity simply disappeared. It now reports a new `renderError` fallback cause on every failed render and warns once with the model url and the caught error.

package/dist/audio/musicState.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Hysteretic music-state selector: turns a continuous intensity signal (nearby threat,
+ * alert count, chase proximity) into a stable theme id. The engine can already crossfade
+ * a soundtrack; this decides *when*, without the flapping a bare threshold produces when
+ * one enemy walks in and out of range.
+ */
+export interface MusicTier {
+    id: string;
+    /** Theme id passed to `ctx.game.audio.music`; null silences the soundtrack in this tier. */
+    theme: string | null;
+    /** Intensity at or above which this tier may be entered. */
+    enter: number;
+    /** Minimum time in this tier before it may drop to a lower one. Default 0. */
+    holdMs?: number;
+}
+/** The tier ladder plus the release margin that keeps a hovering intensity from flapping between tiers. */
+export interface MusicStateConfig {
+    /** Ordered or unordered; the highest `enter` at or below the intensity wins. */
+    tiers: readonly MusicTier[];
+    /** Intensity must fall this far below a tier's `enter` before leaving it. Default 0.2. */
+    release?: number;
+}
+/** Which tier is playing and when it was entered, on the caller's clock. Serialisable. */
+export interface MusicStateSnapshot {
+    tierId: string | null;
+    /** Timestamp the current tier was entered, on the caller's clock. */
+    sinceMs: number;
+}
+/** The current intensity signal and clock reading for one resolve. */
+export interface MusicStateInput {
+    intensity: number;
+    nowMs: number;
+}
+/** Next state, the theme that should be playing, and whether this advance is the one that changed it. */
+export interface MusicStateResult {
+    state: MusicStateSnapshot;
+    theme: string | null;
+    /** True only on the advance the tier changed — the caller's cue to crossfade. */
+    changed: boolean;
+}
+/** Fresh state with no tier entered, so the first resolve always settles and reports `changed`. */
+export declare function createMusicState(): MusicStateSnapshot;
+/**
+ * Pick the theme for the current intensity. Escalation is immediate; de-escalation waits for the
+ * tier's `holdMs` and needs the intensity to fall a `release` margin below the tier it is leaving.
+ */
+export declare function resolveMusicState(state: MusicStateSnapshot, input: MusicStateInput, config: MusicStateConfig): MusicStateResult;

package/dist/audio/musicState.js

@@ -0,0 +1,38 @@
+/** Fresh state with no tier entered, so the first resolve always settles and reports `changed`. */
+export function createMusicState() {
+    return { tierId: null, sinceMs: 0 };
+}
+function tierById(config, id) {
+    return id === null ? undefined : config.tiers.find((tier) => tier.id === id);
+}
+function highestTierAt(config, intensity) {
+    let best;
+    for (const tier of config.tiers) {
+        if (intensity < tier.enter)
+            continue;
+        if (best === undefined || tier.enter > best.enter)
+            best = tier;
+    }
+    return best;
+}
+/**
+ * Pick the theme for the current intensity. Escalation is immediate; de-escalation waits for the
+ * tier's `holdMs` and needs the intensity to fall a `release` margin below the tier it is leaving.
+ */
+export function resolveMusicState(state, input, config) {
+    const current = tierById(config, state.tierId);
+    const candidate = highestTierAt(config, input.intensity) ?? config.tiers.find((tier) => tier.enter <= 0);
+    if (current !== undefined && candidate !== undefined && candidate.enter < current.enter) {
+        const release = config.release ?? 0.2;
+        const heldLongEnough = input.nowMs - state.sinceMs >= (current.holdMs ?? 0);
+        if (!heldLongEnough || input.intensity > current.enter - release) {
+            return { state, theme: current.theme, changed: false };
+        }
+    }
+    const next = candidate ?? current;
+    if (next === undefined)
+        return { state, theme: null, changed: false };
+    if (next.id === state.tierId)
+        return { state, theme: next.theme, changed: false };
+    return { state: { tierId: next.id, sinceMs: input.nowMs }, theme: next.theme, changed: true };
+}

package/dist/audio/stepCadence.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Distance-driven footstep cadence. Pure state-in/state-out: feed it how far a mover
+ * travelled this frame and it tells you how many steps landed, so foley stays locked to
+ * ground distance instead of a wall-clock timer that desyncs when speed changes.
+ */
+export interface StepCadenceConfig {
+    /** World units travelled per step at `strideScale` 1. */
+    strideDistance: number;
+    /**
+     * Fraction of a stride the first step after standing still lands at, so walking off
+     * from rest is heard immediately rather than half a stride later. Default 0.5.
+     */
+    firstStepFraction?: number;
+}
+/** Cadence bookkeeping between advances — banked distance, last moving state, and the step count whose parity is the foot. */
+export interface StepCadenceState {
+    /** Distance banked toward the next step. */
+    travelled: number;
+    /** Whether the mover was moving last advance — drives the from-rest first step. */
+    moving: boolean;
+    /** Monotonic step counter; its parity is the left/right foot. */
+    steps: number;
+}
+/** What the mover did this advance: ground distance covered, whether feet are planting, and the stride multiplier. */
+export interface StepCadenceInput {
+    /** Ground distance covered since the last advance, in world units. */
+    distance: number;
+    /** False when the mover is airborne, downed, or otherwise not planting feet. */
+    moving: boolean;
+    /** Multiplies `strideDistance` — crouch shortens it, sprint lengthens it. Default 1. */
+    strideScale?: number;
+}
+/** Outcome of one advance: the next state plus how many steps landed and which foot led. */
+export interface StepCadenceResult {
+    state: StepCadenceState;
+    /** Steps that landed this advance — 0 or 1 normally, more only on a very long frame. */
+    steps: number;
+    /** Parity of the first step landed this advance: 0 = left, 1 = right. */
+    foot: 0 | 1;
+}
+/** Fresh cadence state for a mover that is standing still. */
+export declare function createStepCadenceState(): StepCadenceState;
+/**
+ * Bank this advance's distance and report the steps it completed. Pure — same state and input
+ * always give the same result, so footstep timing is testable headless and replays identically.
+ */
+export declare function advanceStepCadence(state: StepCadenceState, input: StepCadenceInput, config: StepCadenceConfig): StepCadenceResult;

package/dist/audio/stepCadence.js

@@ -0,0 +1,29 @@
+/** Fresh cadence state for a mover that is standing still. */
+export function createStepCadenceState() {
+    return { travelled: 0, moving: false, steps: 0 };
+}
+/**
+ * Bank this advance's distance and report the steps it completed. Pure — same state and input
+ * always give the same result, so footstep timing is testable headless and replays identically.
+ */
+export function advanceStepCadence(state, input, config) {
+    const stride = Math.max(config.strideDistance * (input.strideScale ?? 1), Number.EPSILON);
+    if (!input.moving) {
+        return { state: { travelled: 0, moving: false, steps: state.steps }, steps: 0, foot: (state.steps % 2) };
+    }
+    const fromRest = !state.moving;
+    const threshold = fromRest ? stride * (config.firstStepFraction ?? 0.5) : stride;
+    let travelled = state.travelled + Math.max(0, input.distance);
+    let steps = 0;
+    let remaining = threshold;
+    while (travelled >= remaining) {
+        travelled -= remaining;
+        steps += 1;
+        remaining = stride;
+    }
+    return {
+        state: { travelled, moving: true, steps: state.steps + steps },
+        steps,
+        foot: (state.steps % 2),
+    };
+}

package/dist/audio/synth.d.ts

@@ -23,6 +23,13 @@ export interface ToneVoice {
     slideTo?: number;
     /** Attack ramp in seconds. Default 0.012. */
     attack?: number;
+    /**
+     * Seconds held at full gain after the attack, before the decay to silence at `duration`.
+     * Default 0 — a plain percussive decay. Set it to `duration` for a flat, sustained bed:
+     * a looped buffer only reads as continuous if its amplitude does not fall across the loop,
+     * so ambient hums and wind beds need this or they pulse once per loop.
+     */
+    sustain?: number;
 }
 /**
  * A filtered white-noise burst — impacts, whooshes, breath, crackle. Realised
@@ -43,6 +50,11 @@ export interface NoiseVoice {
     decay?: number;
     /** Start offset in seconds from the cue trigger. Default 0. */
     delay?: number;
+    /**
+     * Seconds held at full gain before the decay begins. Default 0. Set it to `duration` for a
+     * flat noise bed (wind, rain, machine roar) that loops without pulsing.
+     */
+    sustain?: number;
 }
 /** One layered voice of a synth cue. */
 export type SynthVoice = ToneVoice | NoiseVoice;

package/dist/game/playableGame.d.ts

@@ -340,6 +340,33 @@ export interface PresentationEffectsConfig {
     shake?: boolean;
 }
 /** How a screenshot host reaches live gameplay in this game — the data behind `shoot --mode play`. */
+/**
+ * One named framing in {@link GameCaptureConfig.views}: everything about a capture except the host-side
+ * viewport (`--device`, `--size`) and `--mode`, which the runner routes on before the game module loads.
+ * Every field mirrors the equivalent capture flag, and an explicit flag on the command line wins over the
+ * shot's value so a declared framing stays a starting point rather than a cage.
+ */
+export interface GameCaptureView {
+    /** One line naming what this shot is for — printed by `shoot <game> --list-views`. */
+    description?: string;
+    /** `--look`: `x,z`, `x,y,z`, `@marker:<id>`, or `@entity:<id>`. */
+    look?: string;
+    /** `--look-from`: `dist[,height[,angle]]`. */
+    lookFrom?: string;
+    /** `--spawn`: `x,y,z` or `x,y,z,yaw`, for a shot framed from the player's vantage instead of a detached camera. */
+    spawn?: string;
+    /** `--state`: a {@link GameCaptureConfig.states} entry to reach before capturing. */
+    state?: string;
+    /** `--run`: commands to dispatch before capturing, when the shot needs staging no declared state covers. */
+    run?: readonly string[];
+    /** `--settle`: milliseconds to wait before the frame, for a shot behind an animation. */
+    settleMs?: number;
+}
+/**
+ * How a game makes itself screenshottable: the commands that reach live play or a named screen, the
+ * framings worth re-capturing, and the progress metrics a bot playtest samples. Declaring these once
+ * is what lets a capture host reproduce a view instead of re-deriving it by hand every run.
+ */
 export interface GameCaptureConfig {
     /**
      * Commands run (in order, via `ctx.game.commands.run`) right after boot when a capture host requests the
@@ -363,6 +390,13 @@ export interface GameCaptureConfig {
         name: string;
         input?: unknown;
     })[]>;
+    /**
+     * Named framings worth re-capturing — the views a reviewer actually asks about (`street`, `keep-exterior`,
+     * `boss-arena`), each pinning the camera, the staging, and the settle for that shot. `shoot <game> --view <name>`
+     * reproduces one exactly, so a before/after pair is the same framing by construction instead of two hand-typed
+     * flag sets that drifted. An unknown name fails the capture listing the declared views.
+     */
+    views?: Record<string, GameCaptureView>;
     /** Extra milliseconds the capture host waits after `play` commands before taking the play-mode screenshot — cover an intro cinematic or spawn-in fade. Default 2500. */
     settleMs?: number;
     /** Bot-playtest read hook: maps live game state to a flat vector of numeric progress metrics the `drive --playtest` harness samples over time (e.g. `{ x, z, score, phase }`). Genre-agnostic — "progress" is whatever the game reports; the engine stays neutral. The harness watches these numbers move under scripted input: any metric changing beyond an epsilon counts as forward progress, all metrics flat past the softlock threshold under active input flags a softlock. Return every value that should count as advancing; omit to opt the game out of the playtest rung. */
@@ -422,6 +456,8 @@ export interface PlayableGame<TUi = unknown, TWorldOverlay = unknown, TRenderEnt
         statId?: string;
         roles?: readonly CatalogEntityRole[];
         maxDistance?: number;
+        /** Hide a bar when world geometry stands between the player and the entity. These bars are a screen-space overlay outside the depth buffer, so by default they draw through walls. Default false. */
+        occlude?: boolean;
     };
     /**
      * Opt in to billboarded nameplates (name + optional HP bar) floating over non-local entities — the

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.15.0-next.0";
+export declare const VERSION = "0.16.0";
 /** One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md). */
 export interface ChangelogEntry {
     migrate: readonly string[];