@jgengine/shell 0.26.0 → 0.27.0

package/CHANGELOG.md

@@ -26,6 +26,50 @@ 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.27.0
+
+### Migrate
+
+- **Bump lockstep SDK packages to `^0.27.0`:** `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.24.0`; `@jgengine/github` is `0.14.0`.
+
+### Added
+
+- `rollLoot` (`@jgengine/core/loot/lootGen`) rolls a named item from a caller `LootCatalog`: bases with mount slots, parts, affix pools, weighted rarity tiers, manufacturer personalities and a `levelScale` curve. Stats are `base × rarity.statScale × levelScale`, then part stats/multipliers, maker `bias`/`scale`, then additive and multiplicative affixes; additive affix rolls scale with level, multiplicative ones do not.
+- `createLootRoller` wraps a validated catalog with roll counts per rarity, `snapshot()`/`restore()`/`reset()` and an optional devtools probe; `assertLootCatalog` rejects duplicate ids, unresolvable pools, empty item slots and a non-ascending level curve at construction.
+- `validateLootItem` returns coded issues (`unknown-base`, `manufacturer-base`, `missing-slot-part`, `part-category`, `unknown-affix`, `empty-name`, …) and `compareLootItems` returns sorted per-stat deltas plus a weighted score with caller-named `lowerIsBetter` stats.
+- `lootWeaponDefinition` (`@jgengine/core/loot/lootWeapon`) projects a rolled item onto a `WeaponDefinition` through a caller stat map, so a generated gun runs in `createWeaponSystem` after `assertWeaponDefinition`.
+- `defineXpCurve` (`@jgengine/core/gameplay`) resolves one authored growth rule (`flat`, `linear`, `power`, `geometric`, `table`) plus a `maxLevel` cap into per-level thresholds, lifetime totals, a plain-words rule string and a `leveling` track.
+- `createSkillTree` spends and refunds points over authored nodes with `cost`, `requires`, `excludes`, passives, actives and multi-node `synergies`; `resolved()` returns the stat modifiers and actions, and state snapshots/restores as `{ points, ranks }`.
+- `gearScore` / `compareGearSets` score a whole loadout from stat weights, level, rarity and slot coverage.
+- `lootStatContributions` and `scoreLootStats` expose the weight policy `compareLootItems` already used.
+- `createEquipment` (`@jgengine/core/inventory/equipment`) wears gear by slot: slot defs declare accepted kinds and the slots they block, item defs declare the slots an item may occupy, a filled slot swaps and hands back the replaced item, and a two-handed item and the slot it blocks cannot both be filled. `state()` / `restore()` round-trip the worn set; a devtools probe reports filled slots.
+- `characterLoad` and `canCarry` (`@jgengine/core/inventory/carryLoad`) weigh carried inventories plus worn gear against a capacity and hand back the shared encumbrance bands (tier, `moveMultiplier`, sprint/jump gates, `remaining`), so a stash left out of `carried` adds no weight.
+- `fitShapedItem` (`@jgengine/core/inventory/shapedGrid`) places a shaped item at its first fit or names why not: `too-large` (with both sizes), `no-space`, `budget-exceeded`.
+- `InventorySet.snapshot()` / `restore()` / `reset()` (`@jgengine/core/inventory/inventoryModel`) save and reload every declared inventory as detached plain data, so a bag and a stash never share live slots.
+- `splitStack` takes an optional stack `limit`, rejecting `over-stack` instead of merging past the max stack.
+- `createLaneGraph` and `laneGraphFromDocument` (`@jgengine/core/world`) read an authored lane graph out of the scene document: `traffic_lane` paths are one directed span each, `road` paths (the street bake) become a lane per direction split where streets cross, `traffic_intersection` markers carry signal phases and right-of-way in `meta`, and `traffic_parking` markers place kerbside spots.
+- `createTraffic` (`@jgengine/core/world`) runs cars on that graph: IDM car following and braking, one car at a time through each intersection box behind a signal phase or first-come right-of-way, lane changes across authored neighbours, parking that reserves a spot, deterministic injected variety, `snapshot`/`restore`, and a devtools probe.
+- `Traffic.setDemand(count)` is the fleet target; the time-of-day curve stays the caller's policy.
+- `applyVehicleParts` (`@jgengine/core/world`) composes data-driven tuning parts onto a `KinematicVehicleTuning` — stat multipliers/addends applied in install order plus an optional tire grip curve — and returns the composed tuning, the installed ids, and a `VehicleFeel` (top speed, drive, brakes, turn rate, handbrake grip, and the grip curve's peak/slide). `withPart` swaps a part within its slot and `feelOf` reads the numbers out of any tuning.
+- `createVehicleDamage` (`@jgengine/core/world`) is fixed-zone crash damage wired to handling and visuals: impacts accumulate into discrete stages, each stage costs grip/drive/brakes/top speed/drag and pulls the steering (`effect`), and each zone shows one bounded dent (`deformation`) that never exceeds its authored `deform`. Parts can detach at a set stage, a total impulse can disable the vehicle, and `snapshot`/`restore` resume mid-crash. `damagedTuning` and `damagedAxis` fold the effect into a tuning or an input, and `modifiers()` carries it as per-tick overrides.
+- `KinematicVehicleTuning.weightTransfer` (`@jgengine/core/world`) adds load-transfer grip: longitudinal transfer under braking/traction and lateral transfer under cornering cut the tire grip curve (tire load sensitivity), so braking into a corner holds less slide than coasting through it. Each tick reports `weightTransfer` and `loadGrip`; omitting the block keeps the previous flat-grip model exactly.
+- `KinematicVehicleModifiers.gripScale` scales the grip curve for one tick, mirroring `VehicleDynamicsModifiers.gripScale` so a damage layer drives either sim.
+- `decal` scene kind (`@jgengine/core/world/decalKind`) and its renderer (`@jgengine/shell/scene/DecalRenderer`): dirt, cracks, paint and blood decals authored as placed markers, draped on the live terrain or standing on an authored tilt, with a deterministic procedural texture per style+seed.
+- `TerrainMaterialLayer.material` (`@jgengine/core/world/terraform`): a material library name whose scanned color map paints that terrain layer. The runtime samples up to four layer maps at each layer's `tiling` and blends them through the authored mask weights (`createTerrainDetailMaterial`'s `layerMaps`), so painted terrain blends between authored layers instead of tiling one flat map.
+- `grass_field` volumes now paint a ground-cover mat under their blades (`groundCover` rule, `@jgengine/shell/terrain/GrassCover`), so an authored patch reads as turf rather than bare ground with stubble. `GrassEnvironmentConfig.groundCover` does the same for `grass()` patches.
+- `ModelConfig.wind` (`@jgengine/core/game/playableGame`) and `applyModelWind` (`@jgengine/shell/render/modelWind`): per-model foliage sway with height-ramped travel, shared gust clock and per-model strength/speed/direction.
+
+### Fixed
+
+- The player shell re-renders only for the ctx slices it reads — the possessed entity and the touch control mode — instead of on every `ctx` write. Subscribing the shell root to the raw ctx version reconciled the canvas, the whole actor tree and the HUD on each per-frame entity pose write, which is what `subscribeMembership` and the markers' imperative `useFrame` pose reads exist to avoid (#625). Scrap Signal: 86.6 ms → 16.7 ms per frame at the same 621 draws; Harbor Heat: 102.8 ms → 46.2 ms at the same ~7.2k draws.
+- The `ocean()` environment feature passes the live ground to its shader, so the sea shades shallow→deep and its shoreline foam band lands where the bed meets the surface.
+
+### Numbers
+
+- Test catalog (60/25/10/4/1 rarity weights) over 10,000 drops at level 20, fixed seed: common 59.41% (target 60%), uncommon 25.66% (25%), rare 9.58% (10%), epic 4.20% (4%), legendary 1.15% (1%); every tier inside its 4σ binomial bound. All 10,000 items validated with zero issues and composed names (e.g. `Voss Rare Long Keen Lightframe of Reach`, `Tallow Long Lightframe`, `Voss Snub Lightframe of Steadying`).
+- Level curve `[[1,1],[15,1.6],[30,2.4],[60,4]]`: a level-60 roll's base and additive affix values are 4× the same seed at level 1; maker personalities move the same roll (`Voss` +power/−cadence, `Tallow` the reverse).
+- A rolled epic projects to a hitscan `WeaponDefinition` (rate, damage, integer magazine capacity, spread, range), passes `assertWeaponDefinition`, and its first `tick` fires one shot and one impact through `createDamageRuntime` with the rolled capacity spent.
+
 ## 0.26.0
 
 ### Migrate

package/dist/GamePlayerShell.d.ts

@@ -1,6 +1,14 @@
 import { type GameContext } from "@jgengine/core/runtime/gameContext";
 import type { ShellMultiplayer } from "./multiplayer.js";
 import type { PlayableGame } from "./registry.js";
+/**
+ * Re-render the shell root only for the ctx slices it reads: the entity the local player possesses,
+ * and the active touch-control mode. Subscribing to the raw ctx version instead reconciled the
+ * canvas, the whole actor tree and the HUD on every per-frame pose and store write — the churn
+ * `subscribeMembership` and imperative `useFrame` pose reads exist to keep out of React (#625).
+ * @internal
+ */
+export declare function useShellRootResubscribe(ctx: GameContext | null, userId: string): void;
 export { applyMotionImpulses } from "@jgengine/core/runtime/motionIntents";
 export { nearbyObstacles } from "@jgengine/core/movement/movementModel";
 export { resolvePhysicsTuning } from "@jgengine/core/movement/playerMovement";

package/dist/GamePlayerShell.js

@@ -47,6 +47,19 @@ const DEV_USER_ID = "dev-player";
 const DEBUG_PARAM = "debug";
 const NO_SUBSCRIBE = () => () => undefined;
 const ZERO_VERSION = () => 0;
+function shellRootSnapshot(ctx, userId) {
+    return `${ctx.player.possession.active(userId)}|${activeTouchControlsMode(ctx) ?? ""}`;
+}
+/**
+ * Re-render the shell root only for the ctx slices it reads: the entity the local player possesses,
+ * and the active touch-control mode. Subscribing to the raw ctx version instead reconciled the
+ * canvas, the whole actor tree and the HUD on every per-frame pose and store write — the churn
+ * `subscribeMembership` and imperative `useFrame` pose reads exist to keep out of React (#625).
+ * @internal
+ */
+export function useShellRootResubscribe(ctx, userId) {
+    useSyncExternalStore(ctx?.subscribe ?? NO_SUBSCRIBE, () => (ctx === null ? "" : shellRootSnapshot(ctx, userId)), () => "");
+}
 export { applyMotionImpulses } from "@jgengine/core/runtime/motionIntents";
 export { nearbyObstacles } from "@jgengine/core/movement/movementModel";
 export { resolvePhysicsTuning } from "@jgengine/core/movement/playerMovement";
@@ -330,7 +343,8 @@ export function GamePlayerShell({ playable, multiplayer: rawMultiplayer = null,
     useEffect(() => {
         wrapperRef.current?.focus();
     }, [ctx]);
-    useSyncExternalStore(ctx?.subscribe ?? (() => () => undefined), ctx?.version ?? (() => 0), ctx?.version ?? (() => 0));
+    // The shell root re-renders only for the ctx slices it reads — see {@link useShellRootResubscribe}.
+    useShellRootResubscribe(ctx, userId);
     if (ctx === null)
         return _jsx("div", { className: "h-full w-full bg-neutral-950" });
     if (join.status !== "joined")

package/dist/environment/EnvironmentScene.js

@@ -1,5 +1,5 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useMemo, useRef } from "react";
+import { useCallback, useEffect, useMemo, useRef } from "react";
 import { useFrame } from "@react-three/fiber";
 import { PresentationAssetBoundary } from "../presentationRecovery.js";
 import { PresentationRecoveredDraw, useRecoverableTexture } from "../presentationRecovery3d.js";
@@ -18,14 +18,16 @@ import { buildAuthoredRoadNetwork, RoadRibbons } from "./RoadRibbons.js";
 import { terrainGroundColorSampler } from "./terrainGroundColor.js";
 import { InstancedBuildings } from "../structures/GeneratedBuilding.js";
 import { GrassField } from "../terrain/GrassField.js";
+import { GrassCover } from "../terrain/GrassCover.js";
 import { CarvedTerrain } from "../terrain/CarvedTerrain.js";
 import { createTerrainDetailMaterial } from "../terrain/terrainDetailMaterial.js";
+import { MAX_TERRAIN_LAYER_MAPS } from "../terrain/terrainDetailMaterial.js";
 import { useTerrainQuality } from "../terrain/terrainQuality.js";
 import { createTerrainPaintTextures, packTerrainPaintWeights } from "../terrain/terrainSurfaces.js";
 import { Ocean } from "../water/Ocean.js";
 import { RainField } from "../weather/RainField.js";
 import { SnowField } from "../weather/SnowField.js";
-function TexturedTerrainGround({ detail, layout, }) {
+function TexturedTerrainGround({ detail, layout, layerMaps, }) {
     const maps = detail.material.maps;
     const textures = useRecoverableTexture({
         color: maps.color,
@@ -42,9 +44,44 @@ function TexturedTerrainGround({ detail, layout, }) {
         }
     }, [textures]);
     const quality = useTerrainQuality();
-    const material = useDisposable(() => createTerrainDetailMaterial(detail, textures, { paint: layout.paint, quality }).material, [detail, textures, layout.paint, quality]);
+    const material = useDisposable(() => createTerrainDetailMaterial(detail, textures, { paint: layout.paint, quality, ...(layerMaps === undefined ? {} : { layerMaps }) }).material, [detail, textures, layout.paint, quality, layerMaps]);
     return (_jsxs(_Fragment, { children: [_jsx(PresentationRecoveredDraw, {}), _jsx(CarvedTerrain, { field: layout.field, size: layout.size, segments: layout.segments, colors: layout.colors, heightRange: layout.heightRange, paletteAt: layout.paletteAt, center: layout.center, roughness: 0.94, surfaceMaterial: material })] }));
 }
+/** 1×1 white PNG: binds a valid sampler for a painted layer that has no scanned map. */
+const NO_LAYER_MAP = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==";
+/**
+ * Scanned color maps for up to {@link MAX_TERRAIN_LAYER_MAPS} painted terrain layers, loaded through
+ * the shared recoverable texture path and tiled at each layer's own authored metres. The URL is
+ * authored data (`TerrainMaterialLayer.materialUrl`), resolved by the editor from a library name, so
+ * the renderer never reaches into the asset pipeline.
+ */
+function useTerrainLayerMaps(paint) {
+    const urls = useMemo(() => Array.from({ length: MAX_TERRAIN_LAYER_MAPS }, (_, index) => {
+        const url = paint?.slots[index + 1]?.materialUrl;
+        return url === undefined || url.length === 0 ? NO_LAYER_MAP : url;
+    }), [paint]);
+    const textures = useRecoverableTexture({ layer1: urls[0], layer2: urls[1], layer3: urls[2], layer4: urls[3] });
+    useEffect(() => {
+        for (const texture of Object.values(textures)) {
+            texture.colorSpace = THREE.SRGBColorSpace;
+            texture.wrapS = THREE.RepeatWrapping;
+            texture.wrapT = THREE.RepeatWrapping;
+            texture.needsUpdate = true;
+        }
+    }, [textures]);
+    const slots = paint?.slots;
+    return useMemo(() => {
+        if (slots === undefined)
+            return undefined;
+        return Array.from({ length: MAX_TERRAIN_LAYER_MAPS }, (_, index) => {
+            const slot = slots[index + 1];
+            if (slot?.materialUrl === undefined)
+                return undefined;
+            const texture = textures[`layer${index + 1}`];
+            return texture === undefined ? undefined : { color: texture, tileMetres: slot.tileMetres };
+        });
+    }, [slots, textures]);
+}
 function TerrainGround({ terrain, field, center, sculpt, }) {
     const detailEnabled = terrain.detail !== false;
     const paint = useMemo(() => {
@@ -79,12 +116,13 @@ function TerrainGround({ terrain, field, center, sculpt, }) {
     }, [terrain.baseHeight, terrain.height]);
     const resolvedDetail = useMemo(() => (terrain.detail === false ? undefined : resolveTerrainDetail(terrain.detail, terrain.waterLevel)), [terrain.detail, terrain.waterLevel]);
     const quality = useTerrainQuality();
+    const layerMaps = useTerrainLayerMaps(paint);
     const proceduralMaterial = useMemo(() => resolvedDetail === undefined || resolvedDetail.material !== undefined
         ? undefined
-        : createTerrainDetailMaterial(resolvedDetail, undefined, { paint, quality }).material, [resolvedDetail, paint, quality]);
+        : createTerrainDetailMaterial(resolvedDetail, undefined, { paint, quality, ...(layerMaps === undefined ? {} : { layerMaps }) }).material, [resolvedDetail, paint, quality, layerMaps]);
     useEffect(() => () => proceduralMaterial?.dispose(), [proceduralMaterial]);
     if (resolvedDetail?.material !== undefined) {
-        return (_jsx(PresentationAssetBoundary, { children: _jsx(TexturedTerrainGround, { detail: resolvedDetail, layout: { field, size, segments: terrain.segments, colors, heightRange, paletteAt, paint, center } }) }));
+        return (_jsx(PresentationAssetBoundary, { children: _jsx(TexturedTerrainGround, { detail: resolvedDetail, layout: { field, size, segments: terrain.segments, colors, heightRange, paletteAt, paint, center }, ...(layerMaps === undefined ? {} : { layerMaps }) }) }));
     }
     return (_jsx(CarvedTerrain, { field: field, size: size, segments: terrain.segments, colors: colors, heightRange: heightRange, paletteAt: paletteAt, paintColorAt: paintColorAt, center: center, roughness: 0.94, surfaceMaterial: proceduralMaterial }));
 }
@@ -100,7 +138,7 @@ function Vegetation({ grass, field, groundColor, }) {
     const wind = useMemo(() => ({ strength: grass.windStrength }), [grass.windStrength]);
     const colorBase = grass.colors[0];
     const colorTip = grass.colors[grass.colors.length - 1];
-    return (_jsx("group", { position: [cx, 0, cz], children: _jsx(GrassField, { area: area, count: Math.max(1500, Math.min(250000, Math.ceil(grass.density * grass.area.w * grass.area.d))), density: grass.density, seed: grass.seed, bladeHeight: grass.bladeHeight, bladeWidth: grass.bladeWidth, bladeBend: grass.bladeBend, tuftRadius: grass.tuftRadius, colorVariation: grass.colorVariation, normalLift: grass.normalLift, heightAt: heightAt, colorBase: colorBase, colorTip: colorTip, colorGround: groundColor, wind: wind, edgeFeather: Math.min(8, Math.max(1.5, Math.min(grass.area.w, grass.area.d) * 0.12)), frustumCulled: true }) }));
+    return (_jsxs("group", { position: [cx, 0, cz], children: [_jsx(GrassCover, { area: area, seed: typeof grass.seed === "number" ? grass.seed : 1, colorBase: colorBase ?? "#3f7d2d", colorTip: colorTip ?? "#66a83f", strength: grass.groundCover ?? 0.9, edgeFeather: Math.min(8, Math.max(1.5, Math.min(grass.area.w, grass.area.d) * 0.12)), heightAt: heightAt, coverageAt: () => 1 }), _jsx(GrassField, { area: area, count: Math.max(1500, Math.min(250000, Math.ceil(grass.density * grass.area.w * grass.area.d))), density: grass.density, seed: grass.seed, bladeHeight: grass.bladeHeight, bladeWidth: grass.bladeWidth, bladeBend: grass.bladeBend, tuftRadius: grass.tuftRadius, colorVariation: grass.colorVariation, normalLift: grass.normalLift, heightAt: heightAt, colorBase: colorBase, colorTip: colorTip, colorGround: groundColor, wind: wind, edgeFeather: Math.min(8, Math.max(1.5, Math.min(grass.area.w, grass.area.d) * 0.12)), frustumCulled: true })] }));
 }
 /** Terrain color under a grass patch center — so blade roots blend into the ground they stand on. */
 function vegetationGroundColor(terrain, field, grass, sculpt) {
@@ -142,19 +180,24 @@ function DynamicWater({ ocean }) {
     const groupRef = useRef(null);
     const [x, z] = ocean.position ?? [0, 0];
     const config = useOceanConfig(ocean);
+    const depthAt = useCallback((lx, lz) => ocean.levelAt(ctx.time.now()) - ctx.world.ground.sampleHeight(x + lx, z + lz), [ctx.time.now, ctx.world.ground, ocean.levelAt, x, z]);
     useFrame(() => {
         if (groupRef.current !== null)
             groupRef.current.position.y = ocean.levelAt(ctx.time.now());
     });
-    return (_jsx("group", { ref: groupRef, position: [0, ocean.level, 0], children: _jsx(Ocean, { position: [x, 0, z], config: config }) }));
+    return (_jsx("group", { ref: groupRef, position: [0, ocean.level, 0], children: _jsx(Ocean, { position: [x, 0, z], config: config, depthAt: depthAt }) }));
 }
 function Water({ ocean }) {
+    const ctx = useGameContext();
     const [x, z] = ocean.position ?? [0, 0];
     const config = useOceanConfig(ocean);
+    // The ocean descriptor has no depth field: sample the live ground so the sheet shades
+    // shallow→deep and the shoreline foam band lands where the bed meets the surface.
+    const depthAt = useCallback((lx, lz) => ocean.level - ctx.world.ground.sampleHeight(x + lx, z + lz), [ctx.world.ground, ocean.level, x, z]);
     if (ocean.levelAt !== undefined) {
         return _jsx(DynamicWater, { ocean: ocean });
     }
-    return _jsx(Ocean, { position: [x, ocean.level, z], config: config });
+    return _jsx(Ocean, { position: [x, ocean.level, z], config: config, depthAt: depthAt });
 }
 function Structures({ structures, field }) {
     const placements = useMemo(() => resolveStructureBuildings(structures).map((building) => ({

package/dist/render/decalGeometry.d.ts

@@ -0,0 +1,26 @@
+import type { TerrainHeightSampler } from "../terrain/terrainMath.js";
+/** Inputs for {@link createDecalDrapeGeometry}. */
+export interface DecalDrapeOptions {
+    /** Decal edge length in metres. */
+    size: number;
+    rotationY: number;
+    heightAt: TerrainHeightSampler;
+    /** Height above the sampled ground, metres. */
+    lift: number;
+    /** Grid resolution per axis; defaults to 12 (bounded, decals are small). */
+    segments?: number;
+}
+/** Baked vertex/index buffers for one draped ground decal. */
+export interface DecalDrapeGeometry {
+    positions: Float32Array;
+    normals: Float32Array;
+    uvs: Float32Array;
+    indices: Uint32Array;
+}
+/**
+ * A ground decal's draped quad: an `size`² patch rotated by `rotationY`, every vertex lifted onto
+ * the live terrain so a stain follows a curb or a camber instead of floating over it or sinking
+ * through it. Bounded to one small grid — decals are metres, not patches.
+ * @internal
+ */
+export declare function createDecalDrapeGeometry(options: DecalDrapeOptions): DecalDrapeGeometry;

package/dist/render/decalGeometry.js

@@ -0,0 +1,54 @@
+/**
+ * A ground decal's draped quad: an `size`² patch rotated by `rotationY`, every vertex lifted onto
+ * the live terrain so a stain follows a curb or a camber instead of floating over it or sinking
+ * through it. Bounded to one small grid — decals are metres, not patches.
+ * @internal
+ */
+export function createDecalDrapeGeometry(options) {
+    const segments = Math.max(2, Math.min(24, Math.floor(options.segments ?? 12)));
+    const half = options.size / 2;
+    const cos = Math.cos(options.rotationY);
+    const sin = Math.sin(options.rotationY);
+    const cols = segments + 1;
+    const positions = new Float32Array(cols * cols * 3);
+    const normals = new Float32Array(cols * cols * 3);
+    const uvs = new Float32Array(cols * cols * 2);
+    const eps = Math.max(0.05, options.size / segments / 2);
+    for (let iz = 0; iz < cols; iz += 1) {
+        for (let ix = 0; ix < cols; ix += 1) {
+            const lx = -half + (ix / segments) * options.size;
+            const lz = -half + (iz / segments) * options.size;
+            const x = lx * cos + lz * sin;
+            const z = -lx * sin + lz * cos;
+            const index = iz * cols + ix;
+            positions[index * 3] = x;
+            positions[index * 3 + 1] = options.heightAt(x, z) + options.lift;
+            positions[index * 3 + 2] = z;
+            const hx = options.heightAt(x + eps, z) - options.heightAt(x - eps, z);
+            const hz = options.heightAt(x, z + eps) - options.heightAt(x, z - eps);
+            const length = Math.hypot(hx, 2 * eps, hz) || 1;
+            normals[index * 3] = -hx / length;
+            normals[index * 3 + 1] = (2 * eps) / length;
+            normals[index * 3 + 2] = -hz / length;
+            uvs[index * 2] = ix / segments;
+            uvs[index * 2 + 1] = 1 - iz / segments;
+        }
+    }
+    const indices = new Uint32Array(segments * segments * 6);
+    let cursor = 0;
+    for (let iz = 0; iz < segments; iz += 1) {
+        for (let ix = 0; ix < segments; ix += 1) {
+            const a = iz * cols + ix;
+            const b = a + 1;
+            const c = a + cols;
+            const d = c + 1;
+            indices[cursor++] = a;
+            indices[cursor++] = c;
+            indices[cursor++] = b;
+            indices[cursor++] = b;
+            indices[cursor++] = c;
+            indices[cursor++] = d;
+        }
+    }
+    return { positions, normals, uvs, indices };
+}

package/dist/render/decalTexture.d.ts

@@ -0,0 +1,13 @@
+import type { DecalStyle } from "@jgengine/core/world/decalKind";
+/** Row-major RGBA bytes plus their edge length, ready for a `THREE.DataTexture`. */
+export interface DecalTextureData {
+    size: number;
+    data: Uint8Array;
+}
+/**
+ * The deterministic procedural texture behind one decal style. Same style+seed always bakes the
+ * same bytes; the renderer uploads it once as a `DataTexture`, so no scan is pulled and no game
+ * ships stain art it cannot inspect. Alpha is the coverage; colour is the stain itself.
+ * @internal
+ */
+export declare function createDecalTexture(style: DecalStyle, seed: string, size?: number): DecalTextureData;

package/dist/render/decalTexture.js

@@ -0,0 +1,114 @@
+function hash(x, y, seed) {
+    let h = Math.imul(x | 0, 374761393) ^ Math.imul(y | 0, 668265263) ^ Math.imul(seed | 0, 2246822519);
+    h = Math.imul(h ^ (h >>> 13), 1274126177);
+    return ((h ^ (h >>> 16)) >>> 0) / 4294967296;
+}
+function smooth(t) {
+    return t * t * (3 - 2 * t);
+}
+function noise(x, y, seed) {
+    const xi = Math.floor(x);
+    const yi = Math.floor(y);
+    const tx = smooth(x - xi);
+    const ty = smooth(y - yi);
+    const a = hash(xi, yi, seed);
+    const b = hash(xi + 1, yi, seed);
+    const c = hash(xi, yi + 1, seed);
+    const d = hash(xi + 1, yi + 1, seed);
+    return (a + (b - a) * tx) * (1 - ty) + (c + (d - c) * tx) * ty;
+}
+function fbm(x, y, seed) {
+    return noise(x, y, seed) * 0.62 + noise(x * 2.1 + 7.3, y * 2.1 - 3.1, seed + 11) * 0.26 + noise(x * 4.3 - 1.7, y * 4.3 + 5.9, seed + 23) * 0.12;
+}
+function seedOf(text) {
+    let h = 2166136261;
+    for (let i = 0; i < text.length; i += 1) {
+        h ^= text.charCodeAt(i);
+        h = Math.imul(h, 16777619);
+    }
+    return h >>> 0;
+}
+function smoothstep(edge0, edge1, x) {
+    const t = Math.min(1, Math.max(0, (x - edge0) / (edge1 - edge0 || 1e-6)));
+    return t * t * (3 - 2 * t);
+}
+/**
+ * The deterministic procedural texture behind one decal style. Same style+seed always bakes the
+ * same bytes; the renderer uploads it once as a `DataTexture`, so no scan is pulled and no game
+ * ships stain art it cannot inspect. Alpha is the coverage; colour is the stain itself.
+ * @internal
+ */
+export function createDecalTexture(style, seed, size = 128) {
+    const seedNumber = seedOf(seed.length > 0 ? seed : style);
+    const data = new Uint8Array(size * size * 4);
+    for (let y = 0; y < size; y += 1) {
+        for (let x = 0; x < size; x += 1) {
+            const u = x / size - 0.5;
+            const v = y / size - 0.5;
+            const r = Math.hypot(u, v) * 2;
+            const n = fbm(u * 5 + 13.1, v * 5 - 7.7, seedNumber);
+            let alpha = 0;
+            let red = 0;
+            let green = 0;
+            let blue = 0;
+            if (style === "dirt") {
+                const grain = fbm(u * 17 + 3.3, v * 17 + 9.1, seedNumber + 5);
+                alpha = smoothstep(0.5, 0.62, n) * (1 - smoothstep(0.55, 1, r)) * (0.55 + grain * 0.45);
+                const shade = 0.75 + grain * 0.5;
+                red = 0.36 * shade;
+                green = 0.29 * shade;
+                blue = 0.19 * shade;
+            }
+            else if (style === "blood") {
+                const splatter = fbm(u * 7 - 2.2, v * 7 + 4.4, seedNumber);
+                const main = smoothstep(0.46, 0.58, splatter) * (1 - smoothstep(0.6, 1, r));
+                // Satellite droplets: 26 seeded points, each a soft dark ring.
+                let drops = 0;
+                for (let i = 0; i < 26; i += 1) {
+                    const a = hash(i, 3, seedNumber) * Math.PI * 2;
+                    const d = 0.08 + hash(i, 7, seedNumber) * 0.42;
+                    const radius = 0.012 + hash(i, 11, seedNumber) * 0.03;
+                    const dist = Math.hypot(u - Math.cos(a) * d, v - Math.sin(a) * d);
+                    drops = Math.max(drops, 1 - smoothstep(radius * 0.6, radius, dist));
+                }
+                alpha = Math.max(main, drops);
+                const shade = 0.8 + splatter * 0.35;
+                red = 0.46 * shade;
+                green = 0.055 * shade;
+                blue = 0.045 * shade;
+            }
+            else if (style === "paint") {
+                const body = smoothstep(0.44, 0.55, n) * (1 - smoothstep(0.7, 1, r));
+                const streak = smoothstep(0.38, 0.52, fbm(u * 22 + 1.7, v * 5 + 8.3, seedNumber + 3)) * smoothstep(0.2, 0.9, v + 0.5) * 0.5;
+                alpha = Math.max(body, streak * (1 - smoothstep(0.5, 0.9, r)));
+                const shade = 0.86 + n * 0.22;
+                red = 0.84 * shade;
+                green = 0.8 * shade;
+                blue = 0.72 * shade;
+            }
+            else {
+                // Cracks: six warped radial lines plus two branches, faded toward the rim.
+                let line = 0;
+                for (let i = 0; i < 8; i += 1) {
+                    const base = (i / 8) * Math.PI * 2 + hash(i, 1, seedNumber) * 0.7;
+                    const wobble = (fbm(u * 9 + i * 3.1, v * 9 - i * 2.3, seedNumber + i) - 0.5) * 0.5;
+                    const angle = Math.atan2(v, u);
+                    const delta = Math.abs(Math.atan2(Math.sin(angle - base - wobble), Math.cos(angle - base - wobble)));
+                    const width = 0.022 + hash(i, 5, seedNumber) * 0.02;
+                    line = Math.max(line, (1 - smoothstep(0, width, delta * Math.max(0.05, r))) * (1 - smoothstep(0.45, 1, r)));
+                }
+                const grit = fbm(u * 30 + 4.1, v * 30 - 2.8, seedNumber + 9) * 0.35;
+                alpha = Math.max(line, grit * smoothstep(0.35, 0.7, n) * (1 - smoothstep(0.6, 1, r)));
+                red = 0.13;
+                green = 0.12;
+                blue = 0.11;
+            }
+            const index = (y * size + x) * 4;
+            data[index] = Math.round(Math.min(1, red) * 255);
+            data[index + 1] = Math.round(Math.min(1, green) * 255);
+            data[index + 2] = Math.round(Math.min(1, blue) * 255);
+            data[index + 3] = Math.round(Math.min(1, alpha) * 255);
+        }
+    }
+    return { size, data };
+}

package/dist/render/modelWind.d.ts

@@ -0,0 +1,28 @@
+import * as THREE from "three";
+import type { ModelWindConfig } from "@jgengine/core/game/playableGame";
+/** Shared gust clock every foliage material reads; advanced once per frame by `WindClock`. */
+export declare const windClock: {
+    value: number;
+};
+/** Shared gust direction (XZ); a model may override it with its own authored direction. */
+export declare const windDirection: THREE.Vector2;
+/** Resolved sway settings baked into one material. */
+export interface ResolvedModelWind {
+    strength: number;
+    speed: number;
+    height: number;
+    direction: THREE.Vector2;
+}
+/** Fully-defaulted sway settings for a model. @internal */
+export declare function resolveModelWind(wind: ModelWindConfig | false | undefined, fallbackHeight: number): ResolvedModelWind | null;
+/**
+ * Compiles height-ramped wind sway into a standard material's vertex shader. Idempotent per
+ * material; the clock and direction are shared module uniforms, so the whole scene advances with
+ * one write per frame and no per-material bookkeeping.
+ * @capability model-wind sway a foliage model in the shared gust field
+ */
+export declare function applyModelWind(material: THREE.MeshStandardMaterial, wind: ResolvedModelWind): THREE.MeshStandardMaterial;
+/** Applies wind to every standard material under a cloned model. @internal */
+export declare function applyModelWindToScene(root: THREE.Object3D, wind: ModelWindConfig | false | undefined, fallbackHeight?: number): void;
+/** Advances the shared gust clock once per frame; mount one per 3D world. */
+export declare function WindClock(): null;

package/dist/render/modelWind.js

@@ -0,0 +1,103 @@
+import * as THREE from "three";
+import { useFrame } from "@react-three/fiber";
+/** Shared gust clock every foliage material reads; advanced once per frame by `WindClock`. */
+export const windClock = { value: 0 };
+/** Shared gust direction (XZ); a model may override it with its own authored direction. */
+export const windDirection = new THREE.Vector2(1, 0.35).normalize();
+const WIND_KEY = "jgWind";
+/** Fully-defaulted sway settings for a model. @internal */
+export function resolveModelWind(wind, fallbackHeight) {
+    if (wind === false || wind === undefined)
+        return null;
+    const strength = wind.strength ?? 0.35;
+    if (!Number.isFinite(strength) || strength < 0)
+        throw new Error("Model wind strength must be finite and non-negative");
+    const speed = wind.speed ?? 1;
+    if (!Number.isFinite(speed) || speed <= 0)
+        throw new Error("Model wind speed must be finite and positive");
+    const height = wind.height ?? fallbackHeight;
+    if (!Number.isFinite(height) || height <= 0)
+        throw new Error("Model wind height must be finite and positive");
+    const direction = new THREE.Vector2(wind.direction?.[0] ?? windDirection.x, wind.direction?.[1] ?? windDirection.y);
+    if (direction.lengthSq() === 0)
+        direction.set(1, 0);
+    direction.normalize();
+    return { strength, speed, height, direction };
+}
+const VERTEX_PARS = /* glsl */ `
+uniform float uJgWindTime;
+uniform vec2 uJgWindDir;
+uniform float uJgWindStrength;
+uniform float uJgWindSpeed;
+uniform float uJgWindHeight;`;
+// Height-ramped sway in object space, phased by the instance's world position so neighbouring
+// plants move on different gusts. Trunks (low vertices) barely move; fronds ride the full travel.
+const VERTEX_SWAY = /* glsl */ `#include <begin_vertex>
+{
+  float jgWindT = clamp(position.y / max(uJgWindHeight, 0.001), 0.0, 1.0);
+  float jgWindRamp = jgWindT * jgWindT;
+  #ifdef USE_INSTANCING
+    vec3 jgWindWorld = (instanceMatrix * vec4(transformed, 1.0)).xyz;
+  #else
+    vec3 jgWindWorld = (modelMatrix * vec4(transformed, 1.0)).xyz;
+  #endif
+  float jgWindPhase = dot(jgWindWorld.xz, vec2(0.17, 0.13)) + uJgWindTime * uJgWindSpeed;
+  float jgWindGust = sin(jgWindPhase) * 0.6 + sin(jgWindPhase * 0.47 + 2.3) * 0.4;
+  float jgWindFlutter = sin(uJgWindTime * 6.3 + jgWindWorld.x * 0.9 + jgWindWorld.z * 1.3) * 0.18;
+  vec2 jgWindPush = uJgWindDir * (jgWindGust + jgWindFlutter) * uJgWindStrength * jgWindRamp;
+  transformed.x += jgWindPush.x;
+  transformed.z += jgWindPush.y;
+}`;
+/**
+ * Compiles height-ramped wind sway into a standard material's vertex shader. Idempotent per
+ * material; the clock and direction are shared module uniforms, so the whole scene advances with
+ * one write per frame and no per-material bookkeeping.
+ * @capability model-wind sway a foliage model in the shared gust field
+ */
+export function applyModelWind(material, wind) {
+    if (material.userData[WIND_KEY] !== undefined)
+        return material;
+    const uniforms = {
+        uJgWindTime: windClock,
+        uJgWindDir: { value: wind.direction.clone() },
+        uJgWindStrength: { value: wind.strength },
+        uJgWindSpeed: { value: wind.speed },
+        uJgWindHeight: { value: wind.height },
+    };
+    material.userData[WIND_KEY] = uniforms;
+    const previousCompile = material.onBeforeCompile;
+    const previousKey = material.customProgramCacheKey;
+    material.onBeforeCompile = (shader, renderer) => {
+        previousCompile.call(material, shader, renderer);
+        Object.assign(shader.uniforms, uniforms);
+        shader.vertexShader = shader.vertexShader
+            .replace("#include <common>", `#include <common>\n${VERTEX_PARS}`)
+            .replace("#include <begin_vertex>", VERTEX_SWAY);
+    };
+    material.customProgramCacheKey = () => `${previousKey.call(material)}|jg-wind:v1`;
+    material.needsUpdate = true;
+    return material;
+}
+/** Applies wind to every standard material under a cloned model. @internal */
+export function applyModelWindToScene(root, wind, fallbackHeight = 4) {
+    const resolved = resolveModelWind(wind, fallbackHeight);
+    if (resolved === null)
+        return;
+    root.traverse((node) => {
+        const mesh = node;
+        if (!mesh.isMesh)
+            return;
+        const list = Array.isArray(mesh.material) ? mesh.material : [mesh.material];
+        for (const material of list) {
+            if (material.isMeshStandardMaterial === true)
+                applyModelWind(material, resolved);
+        }
+    });
+}
+/** Advances the shared gust clock once per frame; mount one per 3D world. */
+export function WindClock() {
+    useFrame(({ clock }) => {
+        windClock.value = clock.getElapsedTime();
+    });
+    return null;
+}

package/dist/render/useModelInstance.d.ts

@@ -1,7 +1,7 @@
 import { Group, type Object3D } from "three";
 import type { ModelConfig } from "@jgengine/core/game/playableGame";
 /** Model loading, placement, shadows and animation for a custom renderer. */
-export type ModelInstanceConfig = Pick<ModelConfig, "url" | "scale" | "targetHeight" | "y" | "anchor" | "dims" | "shadows" | "animation" | "hiddenNodes" | "surfaceDetail">;
+export type ModelInstanceConfig = Pick<ModelConfig, "url" | "scale" | "targetHeight" | "y" | "anchor" | "dims" | "shadows" | "animation" | "hiddenNodes" | "surfaceDetail" | "wind">;
 /** Caller-owned styling runs on the isolated clone, never the loader cache. */
 export interface ModelInstanceOptions {
     instanceId?: string;

package/dist/render/useModelInstance.js

@@ -5,6 +5,7 @@ import { parseModelHiddenNodes } from "@jgengine/core/editor/modelNodeVisibility
 import { measureLocalBounds } from "./measureBounds.js";
 import { detectKtx2Support, sharedGltfLoader } from "./modelLoad.js";
 import { cloneModelScene, disposeModelScene, modelPlacementTransform } from "./modelRender.js";
+import { applyModelWindToScene } from "./modelWind.js";
 import { useModelAnimation } from "./useModelAnimation.js";
 import { applyModelNodeVisibility, modelHiddenNodesKey } from "./modelNodeVisibility.js";
 /**
@@ -26,6 +27,7 @@ export function useModelInstance(model, options = {}) {
         const content = cloneModelScene(gltf.scene, { shadows: model.shadows, surfaceDetail: model.surfaceDetail });
         try {
             configure?.(content);
+            applyModelWindToScene(content, model.wind, model.wind === false || model.wind === undefined ? 4 : model.wind.height ?? 4);
             for (const diagnostic of applyModelNodeVisibility(content, hiddenNodes))
                 console.warn(`Model ${model.url} hiddenNodes: ${diagnostic.message}`);
             const scene = new Group().add(content);
@@ -35,7 +37,7 @@ export function useModelInstance(model, options = {}) {
             disposeModelScene(content);
             throw error;
         }
-    }, [gltf.scene, model.shadows, model.surfaceDetail, configure, hiddenNodesKey]);
+    }, [gltf.scene, model.shadows, model.surfaceDetail, model.wind, configure, hiddenNodesKey]);
     const placement = useMemo(() => modelPlacementTransform(scene, model, bindBounds), [scene, bindBounds, model.scale, model.targetHeight, model.y, model.anchor, model.dims]);
     useEffect(() => () => disposeModelScene(content), [content]);
     useModelAnimation(content, gltf.animations, model.animation, instanceId);

package/dist/scatter/scatterModels.js

@@ -3,6 +3,7 @@ import { parseModelHiddenNodes } from "@jgengine/core/editor/modelNodeVisibility
 import { applyMaterialOverride } from "../materialOverride.js";
 import { cloneModelScene, disposeModelScene, ownModelMaterial } from "../render/modelRender.js";
 import { applyModelSurface } from "../render/modelSurface.js";
+import { applyModelWindToScene } from "../render/modelWind.js";
 /** The scale + position offset a `ModelConfig` applies before any per-instance transform — same anchor/targetHeight rules as the single-instance entity renderer. */
 function scatterModelBaseTransform(scene, model) {
     let scale = model.scale ?? 1;
@@ -43,6 +44,7 @@ export function buildScatterModelSources(gltfScene, model) {
         throw new Error("Instanced model override maps require an owned texture loader; use EntityModel for authored maps");
     applyModelSurface(gltfScene);
     const root = cloneModelScene(gltfScene, { shadows: model.shadows, surfaceDetail: model.surfaceDetail });
+    applyModelWindToScene(root, model.wind, model.dims?.maxY ?? model.targetHeight ?? 4);
     if (model.material !== undefined)
         applyMaterialOverride(root, model.material, { clone: false, ownMaterial: material => ownModelMaterial(root, material) });
     root.updateMatrixWorld(true);

package/dist/scene/DecalRenderer.d.ts

@@ -0,0 +1,2 @@
+/** Registers the `decal` marker renderer. Called by `registerBuiltinSceneKindRenderers`. @internal */
+export declare function registerDecalRenderer(): void;