@jgengine/shell 0.25.0 → 0.27.0

package/dist/render/SceneLighting.js

@@ -1,5 +1,6 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useLayoutEffect, useRef } from "react";
+import { useFrame } from "@react-three/fiber";
 import { CascadedShadows, DEFAULT_SHADOW_RADIUS } from "./CascadedShadows.js";
 const DEFAULT_BACKDROP_FOG_COLOR = "#1a1c22";
 /** Default cap for combined dynamic point and spot lights. */
@@ -26,12 +27,12 @@ function resolveDynamicLights(lighting) {
 function usesCascades(entry) {
     return (entry.castShadow ?? false) && (entry.cascades ?? 1) > 1;
 }
-function DirectionalShadowLight({ entry, profile }) {
+function DirectionalShadowLight({ entry, profile, modulation }) {
     const resolved = profile === undefined ? entry : { ...entry, shadowMapSize: entry.shadowMapSize ?? profile.shadowMapSize, cascades: entry.cascades ?? profile.cascades };
     if (usesCascades(resolved)) {
-        return _jsx(CascadedShadows, { entry: resolved });
+        return _jsx(CascadedShadows, { entry: resolved, modulation: modulation });
     }
-    return _jsx(SingleShadowLight, { entry: resolved });
+    return _jsx(SingleShadowLight, { entry: resolved, modulation: modulation });
 }
 /**
  * Refresh a directional light's shadow projection after its frustum bounds change.
@@ -42,11 +43,19 @@ function DirectionalShadowLight({ entry, profile }) {
 export function syncShadowProjection(light) {
     light.shadow.camera.updateProjectionMatrix();
 }
-function SingleShadowLight({ entry }) {
+function SingleShadowLight({ entry, modulation }) {
     const lightRef = useRef(null);
     const size = entry.shadowCameraSize ?? 40;
     const far = Math.max(200, size * 6);
     const mapSize = entry.shadowMapSize ?? 1024;
+    const baseIntensity = entry.intensity ?? 1.3;
+    useFrame(() => {
+        const light = lightRef.current;
+        if (light === null || modulation === undefined)
+            return;
+        light.intensity = baseIntensity * modulation.sunFactor;
+        light.color.set(modulation.sunColor);
+    });
     useLayoutEffect(() => {
         if (lightRef.current !== null)
             syncShadowProjection(lightRef.current);
@@ -60,13 +69,25 @@ function SingleShadowLight({ entry }) {
     }, [mapSize]);
     return (_jsx("directionalLight", { ref: lightRef, position: [entry.position[0], entry.position[1], entry.position[2]], intensity: entry.intensity ?? 1.3, color: entry.color, castShadow: entry.castShadow ?? false, "shadow-mapSize-width": mapSize, "shadow-mapSize-height": mapSize, "shadow-camera-left": -size, "shadow-camera-right": size, "shadow-camera-top": size, "shadow-camera-bottom": -size, "shadow-camera-near": 0.5, "shadow-camera-far": far, "shadow-bias": entry.shadowBias ?? -0.0004, "shadow-normalBias": entry.shadowNormalBias ?? 0.02, "shadow-radius": entry.shadowRadius ?? DEFAULT_SHADOW_RADIUS }));
 }
-export function ConfiguredLighting({ lighting, profile }) {
+export function ConfiguredLighting({ lighting, profile, modulation, }) {
     const dynamic = resolveDynamicLights(lighting);
-    return (_jsxs(_Fragment, { children: [lighting.ambient !== undefined ? (_jsx("ambientLight", { color: lighting.ambient.color, intensity: lighting.ambient.intensity ?? 0.55 })) : null, lighting.hemisphere !== undefined ? (_jsx("hemisphereLight", { args: [
+    const ambientRef = useRef(null);
+    const hemisphereRef = useRef(null);
+    const baseAmbient = lighting.ambient?.intensity ?? 0.55;
+    const baseHemisphere = lighting.hemisphere?.intensity ?? 0.55;
+    useFrame(() => {
+        if (modulation === undefined)
+            return;
+        if (ambientRef.current !== null)
+            ambientRef.current.intensity = baseAmbient * modulation.ambientFactor;
+        if (hemisphereRef.current !== null)
+            hemisphereRef.current.intensity = baseHemisphere * modulation.ambientFactor;
+    });
+    return (_jsxs(_Fragment, { children: [lighting.ambient !== undefined ? (_jsx("ambientLight", { ref: ambientRef, color: lighting.ambient.color, intensity: baseAmbient })) : null, lighting.hemisphere !== undefined ? (_jsx("hemisphereLight", { ref: hemisphereRef, args: [
                     lighting.hemisphere.skyColor ?? "#bfe3ff",
                     lighting.hemisphere.groundColor ?? "#4c6b34",
-                    lighting.hemisphere.intensity ?? 0.55,
-                ] })) : null, (lighting.directional ?? []).map((entry, index) => (_jsx(DirectionalShadowLight, { entry: entry, profile: profile }, index))), dynamic.point.map((entry, index) => (_jsx("pointLight", { position: [entry.position[0], entry.position[1], entry.position[2]], intensity: entry.intensity ?? 1, color: entry.color, distance: entry.distance ?? 0, decay: entry.decay ?? 2, castShadow: entry.castShadow ?? false }, index))), dynamic.spot.map((entry, index) => (_jsx("spotLight", { position: [entry.position[0], entry.position[1], entry.position[2]], intensity: entry.intensity ?? 1, color: entry.color, distance: entry.distance ?? 0, decay: entry.decay ?? 2, angle: entry.angle ?? Math.PI / 6, penumbra: entry.penumbra ?? 0, castShadow: entry.castShadow ?? false, "target-position": [...(entry.target ?? [0, 0, 0])] }, index)))] }));
+                    baseHemisphere,
+                ] })) : null, (lighting.directional ?? []).map((entry, index) => (_jsx(DirectionalShadowLight, { entry: entry, profile: profile, ...(index === 0 && modulation !== undefined ? { modulation } : {}) }, index))), dynamic.point.map((entry, index) => (_jsx("pointLight", { position: [entry.position[0], entry.position[1], entry.position[2]], intensity: entry.intensity ?? 1, color: entry.color, distance: entry.distance ?? 0, decay: entry.decay ?? 2, castShadow: entry.castShadow ?? false }, index))), dynamic.spot.map((entry, index) => (_jsx("spotLight", { position: [entry.position[0], entry.position[1], entry.position[2]], intensity: entry.intensity ?? 1, color: entry.color, distance: entry.distance ?? 0, decay: entry.decay ?? 2, angle: entry.angle ?? Math.PI / 6, penumbra: entry.penumbra ?? 0, castShadow: entry.castShadow ?? false, "target-position": [...(entry.target ?? [0, 0, 0])] }, index)))] }));
 }
 export function BackdropFog({ fog }) {
     if (fog === undefined)

package/dist/render/authoredGrade.d.ts

@@ -0,0 +1,11 @@
+import type { DocumentColorGrade } from "@jgengine/core/editor/environment";
+import type { ResolvedGameLook } from "@jgengine/core/render/lookPreset";
+/**
+ * Folds a scene document's authored grade into the resolved look. The document is the authoring
+ * source, so its baked LUT and exposure range win over the game's static post config, and everything
+ * the document left unauthored stays exactly as the game or look preset set it. With no authored
+ * grade the look comes back untouched (same identity), so an ungraded game mounts the pipeline it
+ * always mounted.
+ * @internal
+ */
+export declare function withAuthoredGrade(look: ResolvedGameLook, grade: DocumentColorGrade | undefined): ResolvedGameLook;

package/dist/render/authoredGrade.js

@@ -0,0 +1,26 @@
+/**
+ * Folds a scene document's authored grade into the resolved look. The document is the authoring
+ * source, so its baked LUT and exposure range win over the game's static post config, and everything
+ * the document left unauthored stays exactly as the game or look preset set it. With no authored
+ * grade the look comes back untouched (same identity), so an ungraded game mounts the pipeline it
+ * always mounted.
+ * @internal
+ */
+export function withAuthoredGrade(look, grade) {
+    if (grade === undefined)
+        return look;
+    const post = look.postProcessing ?? { toneMapping: "agx", bloom: false };
+    const graded = grade.lut === undefined
+        ? post
+        : { ...post, grade: { ...(typeof post.grade === "object" ? post.grade : {}), lut: { cube: grade.lut } } };
+    if (grade.autoExposure === undefined) {
+        return { ...look, postProcessing: graded };
+    }
+    return {
+        ...look,
+        postProcessing: {
+            ...graded,
+            autoExposure: { ...(typeof graded.autoExposure === "object" ? graded.autoExposure : {}), ...grade.autoExposure },
+        },
+    };
+}

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/presentationLook.d.ts

@@ -0,0 +1,15 @@
+import type { DocumentColorGrade } from "@jgengine/core/editor/environment";
+import { type GameLookInput, type ResolvedGameLook } from "@jgengine/core/render/lookPreset";
+import { type SkyEnvironmentDescriptor } from "@jgengine/core/world/features";
+/** The look the shell renders, resolved once per authored value. @internal */
+export interface PresentationLook {
+    look: ResolvedGameLook;
+    backdropSky: SkyEnvironmentDescriptor | undefined;
+}
+/**
+ * Resolve a game's look preset and backdrop sky, keeping one identity until an authored value
+ * changes. The post chain, sky dome and lighting rebuild on identity, so a fresh object per
+ * render recompiled every pass each frame.
+ * @internal
+ */
+export declare function usePresentationLook(input: GameLookInput, authoredGrade: DocumentColorGrade | undefined): PresentationLook;

package/dist/render/presentationLook.js

@@ -0,0 +1,18 @@
+import { useMemo } from "react";
+import { resolveGameLook } from "@jgengine/core/render/lookPreset";
+import { sky as resolveSkyDescriptor } from "@jgengine/core/world/features";
+import { withAuthoredGrade } from "./authoredGrade.js";
+/**
+ * Resolve a game's look preset and backdrop sky, keeping one identity until an authored value
+ * changes. The post chain, sky dome and lighting rebuild on identity, so a fresh object per
+ * render recompiled every pass each frame.
+ * @internal
+ */
+export function usePresentationLook(input, authoredGrade) {
+    const { look, lighting, backdrop, postProcessing, hasWorldSky } = input;
+    return useMemo(() => {
+        const resolved = withAuthoredGrade(resolveGameLook({ look, lighting, backdrop, postProcessing, hasWorldSky }), authoredGrade);
+        const sky = resolved.backdrop?.sky;
+        return { look: resolved, backdropSky: sky === undefined ? undefined : resolveSkyDescriptor(sky) };
+    }, [look, lighting, backdrop, postProcessing, hasWorldSky, authoredGrade]);
+}

package/dist/render/stableTextureSet.d.ts

@@ -0,0 +1,9 @@
+/** Whether two texture sets hold the same roles and texture instances. @internal */
+export declare function sameTextureSet(a: unknown, b: unknown): boolean;
+/**
+ * Keep one texture-set identity while its roles and texture instances are unchanged. The drei
+ * loader hands back a fresh keyed object per render, and materials built from it rebuilt and
+ * recompiled their shaders every frame.
+ * @internal
+ */
+export declare function useStableTextureSet<T extends object>(textures: T): T;

package/dist/render/stableTextureSet.js

@@ -0,0 +1,24 @@
+import { useRef } from "react";
+/** Whether two texture sets hold the same roles and texture instances. @internal */
+export function sameTextureSet(a, b) {
+    if (a === b)
+        return true;
+    if (typeof a !== "object" || typeof b !== "object" || a === null || b === null)
+        return false;
+    const keys = Object.keys(a);
+    if (keys.length !== Object.keys(b).length)
+        return false;
+    return keys.every((key) => a[key] === b[key]);
+}
+/**
+ * Keep one texture-set identity while its roles and texture instances are unchanged. The drei
+ * loader hands back a fresh keyed object per render, and materials built from it rebuilt and
+ * recompiled their shaders every frame.
+ * @internal
+ */
+export function useStableTextureSet(textures) {
+    const stable = useRef(textures);
+    if (!sameTextureSet(stable.current, textures))
+        stable.current = textures;
+    return stable.current;
+}

package/dist/render/triplanarMaterial.d.ts

@@ -0,0 +1,52 @@
+import type { MaterialAsset } from "@jgengine/core/material/materialAsset";
+import * as THREE from "three";
+/** Inputs for {@link applyTriplanarProjection}. */
+export interface TriplanarProjectionOptions {
+    /** Metres one texture tile covers in world space. Must be finite and positive. */
+    tileMetres: number;
+    /** Blend sharpness between the three projections; 4 keeps corners soft, 8 is decisive. */
+    sharpness?: number;
+    /** Normal strength applied to each projection's tangent-space perturbation. */
+    normalScale?: number;
+}
+/**
+ * The GLSL the triplanar path injects, split by chunk. Exposed so a test can prove the patch
+ * samples by world position instead of `vMapUv`, and so a reader can audit the projection.
+ * @internal
+ */
+export declare function triplanarChunks(): {
+    vertexPars: string;
+    vertexNormal: string;
+    vertexPosition: string;
+    fragmentPars: string;
+    color: string;
+    roughness: string;
+    normal: string;
+    ao: string;
+};
+/**
+ * Projects a standard material's maps from world position instead of mesh UVs, so world geometry
+ * without a `uv` attribute still renders a textured PBR surface. Instanced meshes project in their
+ * instanced world space. Skinned meshes keep the bind-pose normal for the blend weights, which is
+ * close enough for the static world surfaces this path exists for.
+ */
+export declare function applyTriplanarProjection(material: THREE.MeshStandardMaterial, options: TriplanarProjectionOptions): THREE.MeshStandardMaterial;
+/**
+ * Render a serializable material asset — one built by `libraryMaterialAsset`, or authored in the
+ * editor — with world-space triplanar projection, so world geometry needs no UVs. Tile size
+ * defaults to the asset's own `physicalSize`, which the shared library sets per surface.
+ * @capability material-triplanar render a material asset on world geometry without UVs
+ */
+export declare function useTriplanarAssetMaterial(asset: MaterialAsset, options?: {
+    tileMetres?: number;
+    sharpness?: number;
+    normalScale?: number;
+}): THREE.MeshStandardMaterial;
+/** Mounts {@link useTriplanarAssetMaterial} on a mesh; the R3F renderer owns disposal. */
+export declare function TriplanarAssetMaterial({ asset, ...options }: {
+    asset: MaterialAsset;
+} & {
+    tileMetres?: number;
+    sharpness?: number;
+    normalScale?: number;
+}): import("react").JSX.Element;