@jgengine/shell 0.7.0 → 0.8.0

package/dist/render/modelRender.js

@@ -0,0 +1,79 @@
+import * as THREE from "three";
+import { clone as cloneSkinned } from "three/examples/jsm/utils/SkeletonUtils.js";
+export const PAINT_TEXTURE_SIZE = 512;
+export function cloneModelScene(source) {
+    const clone = cloneSkinned(source);
+    clone.traverse((node) => {
+        const mesh = node;
+        if (!mesh.isMesh)
+            return;
+        mesh.material = Array.isArray(mesh.material)
+            ? mesh.material.map((material) => material.clone())
+            : mesh.material.clone();
+    });
+    return clone;
+}
+function isMeshStandardMaterial(material) {
+    return material.isMeshStandardMaterial === true;
+}
+export function standardMaterialsOf(root) {
+    const materials = [];
+    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 (isMeshStandardMaterial(material))
+                materials.push(material);
+    });
+    return materials;
+}
+export function createPaintCanvas(seed, size = PAINT_TEXTURE_SIZE) {
+    const canvas = document.createElement("canvas");
+    canvas.width = size;
+    canvas.height = size;
+    const context = canvas.getContext("2d");
+    const seedImage = seed.map?.image;
+    if (seedImage !== undefined && seedImage.width) {
+        context.drawImage(seedImage, 0, 0, size, size);
+    }
+    else {
+        context.fillStyle = `#${seed.color.getHexString()}`;
+        context.fillRect(0, 0, size, size);
+    }
+    const texture = new THREE.CanvasTexture(canvas);
+    texture.colorSpace = seed.map?.colorSpace ?? THREE.SRGBColorSpace;
+    return { canvas, context, texture };
+}
+export function drawPaintStrokes(paint, strokes) {
+    const { canvas, context, texture } = paint;
+    for (const stroke of strokes) {
+        context.fillStyle = stroke.color;
+        context.beginPath();
+        context.arc(stroke.u * canvas.width, (1 - stroke.v) * canvas.height, stroke.radius * canvas.width, 0, Math.PI * 2);
+        context.fill();
+    }
+    texture.needsUpdate = true;
+}
+export function applyPaintTexture(root, paint) {
+    for (const material of standardMaterialsOf(root)) {
+        material.map = paint.texture;
+        material.needsUpdate = true;
+    }
+}
+export function syncPaintCanvas(paint, seedColor, strokes, drawnCount) {
+    if (strokes.length < drawnCount) {
+        const { canvas, context } = paint;
+        context.clearRect(0, 0, canvas.width, canvas.height);
+        context.fillStyle = `#${seedColor.getHexString()}`;
+        context.fillRect(0, 0, canvas.width, canvas.height);
+        drawPaintStrokes(paint, strokes);
+        return strokes.length;
+    }
+    if (strokes.length > drawnCount) {
+        drawPaintStrokes(paint, strokes.slice(drawnCount));
+        return strokes.length;
+    }
+    return drawnCount;
+}

package/dist/terrain/index.d.ts

@@ -6,5 +6,5 @@ export { TerraformBrushCursor, type TerraformBrushCursorProps } from "./Terrafor
 export { createGrassBladeGeometry, resolveGrassBladeGeometryOptions, resolveGrassRange, type GrassBladeGeometryOptions, type GrassRange, type ResolvedGrassBladeGeometryOptions, } from "./grassGeometry.js";
 export { createGrassMaterial, DEFAULT_GRASS_WIND, resolveGrassWind, type GrassMaterialHandle, type GrassMaterialOptions, type GrassShaderUniforms, type GrassWindOptions, } from "./grassMaterial.js";
 export { createSeededRandom, hashNoise2, seedToUint32, type TerrainSeed } from "./random.js";
-export { createFieldGroundGeometry, createProceduralGroundGeometry, createProceduralTerrainSampler, resolveTerrainSegments, resolveTerrainSize, toNoiseFieldConfig, type FieldGroundOptions, type ProceduralTerrainConfig, type ResolvedTerrainSegments, type ResolvedTerrainSize, type TerrainArea, type TerrainHeightSampler, type TerrainVertexColorOptions, } from "./terrainMath.js";
+export { createFieldGroundGeometry, createProceduralGroundGeometry, createProceduralTerrainSampler, normalizeHeightBlend, resolveTerrainSegments, resolveTerrainSize, toNoiseFieldConfig, type FieldGroundOptions, type ProceduralTerrainConfig, type ResolvedTerrainSegments, type ResolvedTerrainSize, type TerrainArea, type TerrainHeightSampler, type TerrainVertexColorOptions, } from "./terrainMath.js";
 export { arenaField, flatField, fractalNoise, noiseField, resolveGroundStep, resolveTerrainField, valueNoise, withNormal, type FractalNoiseConfig, type NoiseFieldConfig, type TerrainField, type TerrainNormal, } from "@jgengine/core/world/terrain";

package/dist/terrain/index.js

@@ -6,5 +6,5 @@ export { TerraformBrushCursor } from "./TerraformBrushCursor.js";
 export { createGrassBladeGeometry, resolveGrassBladeGeometryOptions, resolveGrassRange, } from "./grassGeometry.js";
 export { createGrassMaterial, DEFAULT_GRASS_WIND, resolveGrassWind, } from "./grassMaterial.js";
 export { createSeededRandom, hashNoise2, seedToUint32 } from "./random.js";
-export { createFieldGroundGeometry, createProceduralGroundGeometry, createProceduralTerrainSampler, resolveTerrainSegments, resolveTerrainSize, toNoiseFieldConfig, } from "./terrainMath.js";
+export { createFieldGroundGeometry, createProceduralGroundGeometry, createProceduralTerrainSampler, normalizeHeightBlend, resolveTerrainSegments, resolveTerrainSize, toNoiseFieldConfig, } from "./terrainMath.js";
 export { arenaField, flatField, fractalNoise, noiseField, resolveGroundStep, resolveTerrainField, valueNoise, withNormal, } from "@jgengine/core/world/terrain";

package/dist/terrain/terrainMath.d.ts

@@ -27,6 +27,7 @@ export interface TerrainVertexColorOptions {
     waterline?: THREE.ColorRepresentation;
     waterlineHeight?: number;
 }
+export declare function normalizeHeightBlend(height: number, minHeight: number, maxHeight: number): number;
 export declare function resolveTerrainSize(size?: TerrainArea): ResolvedTerrainSize;
 export declare function resolveTerrainSegments(segments?: ProceduralTerrainConfig["segments"]): ResolvedTerrainSegments;
 export declare function toNoiseFieldConfig(config?: ProceduralTerrainConfig): NoiseFieldConfig;

package/dist/terrain/terrainMath.js

@@ -1,6 +1,12 @@
 import { noiseField } from "@jgengine/core/world/terrain";
 import * as THREE from "three";
 import {} from "./random.js";
+export function normalizeHeightBlend(height, minHeight, maxHeight) {
+    const range = maxHeight - minHeight;
+    if (range <= 1e-6)
+        return 0.5;
+    return THREE.MathUtils.clamp((height - minHeight) / range, 0, 1);
+}
 export function resolveTerrainSize(size = 40) {
     return typeof size === "number" ? { width: size, depth: size } : { width: size[0], depth: size[1] };
 }
@@ -66,7 +72,7 @@ function buildGroundGeometry(size, segments, sampler, opts) {
             positions[index + 2] = z;
             uvs[uvIndex] = u;
             uvs[uvIndex + 1] = v;
-            const blend = THREE.MathUtils.clamp((y - minHeight) / (maxHeight - minHeight), 0, 1);
+            const blend = normalizeHeightBlend(y, minHeight, maxHeight);
             const color = low.clone().lerp(high, blend);
             if (waterline !== null && y <= (colors.waterlineHeight ?? 0))
                 color.lerp(waterline, 0.65);
@@ -133,7 +139,7 @@ export function createProceduralGroundGeometry(config = {}, colors = {}) {
             positions[index + 2] = z;
             uvs[uvIndex] = u;
             uvs[uvIndex + 1] = v;
-            const blend = THREE.MathUtils.clamp((y - minHeight) / (maxHeight - minHeight), 0, 1);
+            const blend = normalizeHeightBlend(y, minHeight, maxHeight);
             const color = low.clone().lerp(high, blend);
             if (waterline !== null && y <= (colors.waterlineHeight ?? 0))
                 color.lerp(waterline, 0.65);

package/dist/touch/TouchControlsOverlay.d.ts

@@ -0,0 +1,18 @@
+import { type MutableRefObject } from "react";
+import { type TouchScheme } from "@jgengine/core/input/touchScheme";
+export interface TouchCodeSink {
+    onCodeDown(code: string): void;
+    onCodeUp(code: string): void;
+}
+export declare function TouchPlaySurface({ scheme, sink, yawRef, pitchRef, maxPitch, onPrimaryTap, }: {
+    scheme: TouchScheme;
+    sink: TouchCodeSink;
+    yawRef: MutableRefObject<number>;
+    pitchRef: MutableRefObject<number>;
+    maxPitch: number;
+    onPrimaryTap: () => void;
+}): import("react").JSX.Element;
+export declare function TouchControlsDock({ scheme, sink }: {
+    scheme: TouchScheme;
+    sink: TouchCodeSink;
+}): import("react").JSX.Element;

package/dist/touch/TouchControlsOverlay.js

@@ -0,0 +1,173 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useMemo, useRef } from "react";
+import { createGestureSurfaceTracker } from "@jgengine/core/input/gestureSurface";
+import { createTouchGestureTracker } from "@jgengine/core/input/touchGestures";
+import { touchCode } from "@jgengine/core/input/touchScheme";
+import { GameIcon, iconForAction, isGameIconName } from "@jgengine/react/gameIcons";
+const JOYSTICK_SIZE = 132;
+const JOYSTICK_THUMB = 52;
+const JOYSTICK_DEADZONE = 0.28;
+const JOYSTICK_AXIS_THRESHOLD = 0.42;
+const LOOK_TAP_TUNING = { tapMoveThresholdPx: 12, tapMaxMs: 280, longPressMs: 450 };
+function pressOnce(sink, action) {
+    const code = touchCode(action);
+    sink.onCodeDown(code);
+    sink.onCodeUp(code);
+}
+export function TouchPlaySurface({ scheme, sink, yawRef, pitchRef, maxPitch, onPrimaryTap, }) {
+    const pointerIdRef = useRef(null);
+    const gestureTracker = useMemo(() => (scheme.gestures === null ? null : createGestureSurfaceTracker(scheme.gestures)), [scheme]);
+    const lookTracker = useMemo(() => (scheme.look ? createTouchGestureTracker(LOOK_TAP_TUNING) : null), [scheme]);
+    const release = (event) => {
+        if (event.pointerId !== pointerIdRef.current)
+            return;
+        pointerIdRef.current = null;
+    };
+    return (_jsx("div", { className: "absolute inset-0 touch-none", onPointerDown: (event) => {
+            if (event.pointerType !== "touch" || pointerIdRef.current !== null)
+                return;
+            pointerIdRef.current = event.pointerId;
+            event.currentTarget.setPointerCapture(event.pointerId);
+            if (lookTracker !== null)
+                lookTracker.begin(event.clientX, event.clientY, performance.now());
+            else
+                gestureTracker?.begin(event.clientX, event.clientY, performance.now());
+        }, onPointerMove: (event) => {
+            if (event.pointerId !== pointerIdRef.current)
+                return;
+            event.stopPropagation();
+            if (lookTracker !== null) {
+                const delta = lookTracker.move(event.clientX, event.clientY);
+                if (delta !== null) {
+                    yawRef.current -= delta.dx * scheme.lookSensitivity;
+                    pitchRef.current = Math.max(-maxPitch, Math.min(maxPitch, pitchRef.current - delta.dy * scheme.lookSensitivity));
+                }
+                return;
+            }
+            for (const action of gestureTracker?.move(event.clientX, event.clientY) ?? [])
+                pressOnce(sink, action);
+        }, onPointerUp: (event) => {
+            if (event.pointerId !== pointerIdRef.current)
+                return;
+            event.stopPropagation();
+            release(event);
+            if (lookTracker !== null) {
+                if (lookTracker.end(performance.now()) === "tap") {
+                    if (scheme.gestures?.tap !== undefined)
+                        pressOnce(sink, scheme.gestures.tap);
+                    else
+                        onPrimaryTap();
+                }
+                return;
+            }
+            for (const action of gestureTracker?.end(event.clientX, event.clientY, performance.now()) ?? []) {
+                pressOnce(sink, action);
+            }
+        }, onPointerCancel: (event) => {
+            release(event);
+            lookTracker?.cancel();
+            gestureTracker?.cancel();
+        } }));
+}
+function joystickDirections(joystick, nx, ny) {
+    const active = new Set();
+    if (Math.hypot(nx, ny) < JOYSTICK_DEADZONE)
+        return active;
+    if (joystick.up !== null && ny < -JOYSTICK_AXIS_THRESHOLD)
+        active.add(joystick.up);
+    if (joystick.down !== null && ny > JOYSTICK_AXIS_THRESHOLD)
+        active.add(joystick.down);
+    if (joystick.left !== null && nx < -JOYSTICK_AXIS_THRESHOLD)
+        active.add(joystick.left);
+    if (joystick.right !== null && nx > JOYSTICK_AXIS_THRESHOLD)
+        active.add(joystick.right);
+    return active;
+}
+function VirtualJoystick({ joystick, sink }) {
+    const baseRef = useRef(null);
+    const thumbRef = useRef(null);
+    const pointerIdRef = useRef(null);
+    const activeRef = useRef(new Set());
+    const applyVector = (clientX, clientY) => {
+        const base = baseRef.current;
+        const thumb = thumbRef.current;
+        if (base === null || thumb === null)
+            return;
+        const rect = base.getBoundingClientRect();
+        const radius = rect.width / 2;
+        let nx = (clientX - rect.left - radius) / radius;
+        let ny = (clientY - rect.top - radius) / radius;
+        const length = Math.hypot(nx, ny);
+        if (length > 1) {
+            nx /= length;
+            ny /= length;
+        }
+        const travel = radius - JOYSTICK_THUMB / 2;
+        thumb.style.transform = `translate(${nx * travel}px, ${ny * travel}px)`;
+        const next = joystickDirections(joystick, nx, ny);
+        for (const action of activeRef.current) {
+            if (!next.has(action))
+                sink.onCodeUp(touchCode(action));
+        }
+        for (const action of next) {
+            if (!activeRef.current.has(action))
+                sink.onCodeDown(touchCode(action));
+        }
+        activeRef.current = next;
+    };
+    const releaseAll = () => {
+        pointerIdRef.current = null;
+        for (const action of activeRef.current)
+            sink.onCodeUp(touchCode(action));
+        activeRef.current = new Set();
+        if (thumbRef.current !== null)
+            thumbRef.current.style.transform = "translate(0px, 0px)";
+    };
+    return (_jsx("div", { ref: baseRef, className: "pointer-events-auto relative flex touch-none select-none items-center justify-center rounded-full border border-white/20 bg-white/10 backdrop-blur-sm", style: { width: JOYSTICK_SIZE, height: JOYSTICK_SIZE }, onPointerDown: (event) => {
+            if (pointerIdRef.current !== null)
+                return;
+            pointerIdRef.current = event.pointerId;
+            event.currentTarget.setPointerCapture(event.pointerId);
+            applyVector(event.clientX, event.clientY);
+        }, onPointerMove: (event) => {
+            if (event.pointerId !== pointerIdRef.current)
+                return;
+            event.stopPropagation();
+            applyVector(event.clientX, event.clientY);
+        }, onPointerUp: (event) => {
+            if (event.pointerId !== pointerIdRef.current)
+                return;
+            event.stopPropagation();
+            releaseAll();
+        }, onPointerCancel: () => releaseAll(), children: _jsx("div", { ref: thumbRef, className: "rounded-full border border-white/30 bg-white/25", style: { width: JOYSTICK_THUMB, height: JOYSTICK_THUMB } }) }));
+}
+function touchButtonIcon(button) {
+    if (button.icon === false)
+        return null;
+    if (button.icon !== null && isGameIconName(button.icon))
+        return button.icon;
+    return iconForAction(button.action);
+}
+function TouchActionButton({ button, sink }) {
+    const pointerIdRef = useRef(null);
+    const icon = touchButtonIcon(button);
+    const releaseIfHeld = () => {
+        if (pointerIdRef.current === null)
+            return;
+        pointerIdRef.current = null;
+        sink.onCodeUp(touchCode(button.action));
+    };
+    return (_jsx("button", { type: "button", "aria-label": button.label, className: "pointer-events-auto flex h-14 w-14 touch-none select-none items-center justify-center rounded-full border border-white/25 bg-white/10 text-center text-[10px] font-semibold uppercase leading-tight tracking-wide text-white/90 backdrop-blur-sm active:border-white/50 active:bg-white/30", onPointerDown: (event) => {
+            if (pointerIdRef.current !== null)
+                return;
+            pointerIdRef.current = event.pointerId;
+            event.currentTarget.setPointerCapture(event.pointerId);
+            sink.onCodeDown(touchCode(button.action));
+        }, onPointerUp: (event) => {
+            event.stopPropagation();
+            releaseIfHeld();
+        }, onPointerCancel: () => releaseIfHeld(), onContextMenu: (event) => event.preventDefault(), children: icon !== null ? _jsx(GameIcon, { name: icon, size: 26 }) : _jsx("span", { className: "px-1", children: button.label }) }));
+}
+export function TouchControlsDock({ scheme, sink }) {
+    return (_jsxs("div", { className: "pointer-events-none absolute inset-x-0 bottom-0 z-40 flex items-end justify-between gap-4 px-5", style: { paddingBottom: "calc(env(safe-area-inset-bottom, 0px) + 20px)" }, children: [_jsx("div", { children: scheme.joystick !== null ? _jsx(VirtualJoystick, { joystick: scheme.joystick, sink: sink }) : null }), _jsx("div", { className: "flex max-w-[60%] flex-wrap items-end justify-end gap-3", children: scheme.buttons.map((button) => (_jsx(TouchActionButton, { button: button, sink: sink }, button.action))) })] }));
+}

package/dist/water/OceanShader.d.ts

@@ -1,2 +1,2 @@
-export declare const oceanVertexShader = "\nuniform float uTime;\nuniform vec2 uWaveDirections[6];\nuniform vec4 uWaveParams[6];\nuniform float uChoppiness;\nuniform float uFoamThreshold;\nuniform float uFoamSoftness;\nuniform float uFoamCoverage;\n\nvarying vec3 vWorldPosition;\nvarying vec3 vNormal;\nvarying float vCrest;\nvarying float vWaveHeight;\n\nvoid main() {\n  vec3 displaced = position;\n  vec3 tangent = vec3(1.0, 0.0, 0.0);\n  vec3 bitangent = vec3(0.0, 0.0, 1.0);\n  float crest = 0.0;\n\n  for (int i = 0; i < 6; i++) {\n    vec2 direction = normalize(uWaveDirections[i]);\n    vec4 wave = uWaveParams[i];\n    float k = wave.x;\n    float amplitude = wave.y;\n    float steepness = wave.z;\n    float omega = wave.w;\n    float phase = k * dot(direction, position.xz) - omega * uTime;\n    float sine = sin(phase);\n    float cosine = cos(phase);\n    float horizontal = steepness * amplitude * uChoppiness;\n    displaced.x += horizontal * direction.x * cosine;\n    displaced.z += horizontal * direction.y * cosine;\n    displaced.y += amplitude * sine;\n    float common = horizontal * k * sine;\n    tangent += vec3(-common * direction.x * direction.x, amplitude * k * direction.x * cosine, -common * direction.x * direction.y);\n    bitangent += vec3(-common * direction.x * direction.y, amplitude * k * direction.y * cosine, -common * direction.y * direction.y);\n    crest = max(crest, smoothstep(uFoamThreshold, uFoamThreshold + uFoamSoftness, sine * steepness + uFoamCoverage * 0.35));\n  }\n\n  vNormal = normalize(cross(bitangent, tangent));\n  vCrest = crest;\n  vWaveHeight = displaced.y;\n  vec4 worldPosition = modelMatrix * vec4(displaced, 1.0);\n  vWorldPosition = worldPosition.xyz;\n  gl_Position = projectionMatrix * viewMatrix * worldPosition;\n}\n";
+export declare const oceanVertexShader = "\nuniform float uTime;\nuniform vec2 uWaveDirections[6];\nuniform vec4 uWaveParams[6];\nuniform float uChoppiness;\nuniform float uFoamThreshold;\nuniform float uFoamSoftness;\nuniform float uFoamCoverage;\n\nvarying vec3 vWorldPosition;\nvarying vec3 vNormal;\nvarying float vCrest;\nvarying float vWaveHeight;\n\nvoid main() {\n  vec3 displaced = position;\n  vec3 tangent = vec3(1.0, 0.0, 0.0);\n  vec3 bitangent = vec3(0.0, 0.0, 1.0);\n  float crest = 0.0;\n\n  for (int i = 0; i < 6; i++) {\n    vec2 direction = normalize(uWaveDirections[i]);\n    vec4 wave = uWaveParams[i];\n    float k = wave.x;\n    float amplitude = wave.y;\n    float steepness = wave.z;\n    float omega = wave.w;\n    float phase = k * dot(direction, position.xz) - omega * uTime;\n    float sine = sin(phase);\n    float cosine = cos(phase);\n    float horizontal = steepness * amplitude * uChoppiness;\n    displaced.x += horizontal * direction.x * cosine;\n    displaced.z += horizontal * direction.y * cosine;\n    displaced.y += amplitude * sine;\n    float slopeTerm = horizontal * k * sine;\n    tangent += vec3(-slopeTerm * direction.x * direction.x, amplitude * k * direction.x * cosine, -slopeTerm * direction.x * direction.y);\n    bitangent += vec3(-slopeTerm * direction.x * direction.y, amplitude * k * direction.y * cosine, -slopeTerm * direction.y * direction.y);\n    crest = max(crest, smoothstep(uFoamThreshold, uFoamThreshold + uFoamSoftness, sine * steepness + uFoamCoverage * 0.35));\n  }\n\n  vNormal = normalize(cross(bitangent, tangent));\n  vCrest = crest;\n  vWaveHeight = displaced.y;\n  vec4 worldPosition = modelMatrix * vec4(displaced, 1.0);\n  vWorldPosition = worldPosition.xyz;\n  gl_Position = projectionMatrix * viewMatrix * worldPosition;\n}\n";
 export declare const oceanFragmentShader = "\nuniform vec3 uShallowColor;\nuniform vec3 uDeepColor;\nuniform vec3 uCrestColor;\nuniform vec3 uFoamColor;\nuniform float uOpacity;\nuniform float uFresnelStrength;\nuniform float uHorizonBlend;\nuniform float uFoamIntensity;\n\nvarying vec3 vWorldPosition;\nvarying vec3 vNormal;\nvarying float vCrest;\nvarying float vWaveHeight;\n\nvoid main() {\n  vec3 normal = normalize(vNormal);\n  vec3 viewDirection = normalize(cameraPosition - vWorldPosition);\n  float fresnel = pow(1.0 - max(dot(normal, viewDirection), 0.0), 4.5);\n  float depthMix = smoothstep(-1.8, 1.6, vWaveHeight);\n  vec3 waterColor = mix(uDeepColor, uShallowColor, depthMix);\n  waterColor = mix(waterColor, uCrestColor, smoothstep(0.15, 1.2, vWaveHeight) * 0.28);\n  waterColor = mix(waterColor, vec3(0.86, 0.95, 1.0), fresnel * uFresnelStrength);\n  float horizon = smoothstep(0.0, 1.0, 1.0 - abs(normal.y));\n  waterColor = mix(waterColor, uShallowColor, horizon * uHorizonBlend);\n  float foam = clamp(vCrest * uFoamIntensity, 0.0, 1.0);\n  vec3 color = mix(waterColor, uFoamColor, foam);\n  gl_FragColor = vec4(color, uOpacity);\n}\n";

package/dist/water/OceanShader.js

@@ -32,9 +32,9 @@ void main() {
     displaced.x += horizontal * direction.x * cosine;
     displaced.z += horizontal * direction.y * cosine;
     displaced.y += amplitude * sine;
-    float common = horizontal * k * sine;
-    tangent += vec3(-common * direction.x * direction.x, amplitude * k * direction.x * cosine, -common * direction.x * direction.y);
-    bitangent += vec3(-common * direction.x * direction.y, amplitude * k * direction.y * cosine, -common * direction.y * direction.y);
+    float slopeTerm = horizontal * k * sine;
+    tangent += vec3(-slopeTerm * direction.x * direction.x, amplitude * k * direction.x * cosine, -slopeTerm * direction.x * direction.y);
+    bitangent += vec3(-slopeTerm * direction.x * direction.y, amplitude * k * direction.y * cosine, -slopeTerm * direction.y * direction.y);
     crest = max(crest, smoothstep(uFoamThreshold, uFoamThreshold + uFoamSoftness, sine * steepness + uFoamCoverage * 0.35));
   }
 

package/dist/world/DataObjects.d.ts

@@ -0,0 +1,44 @@
+import { type ReactNode } from "react";
+import * as THREE from "three";
+/**
+ * Renders one placed 3D object per data item — a 3D bar chart, a heatmap, a city
+ * of buildings, a crowd. By default each item is an extruded box (all boxes share
+ * one `InstancedMesh`, so hundreds cost one draw call), sized and colored from the
+ * item; `renderItem` swaps the box for arbitrary content (a sprite, a GLB, a full
+ * entity). Genre-agnostic: the caller owns the data `T`, this owns the placement.
+ */
+export interface DataObjectsProps<T> {
+    data: readonly T[];
+    /** World `[x, z]` for an item (placed on the ground plane). */
+    position: (item: T, index: number) => readonly [number, number];
+    /** Box height (Y-scale) for an item. */
+    height: (item: T, index: number) => number;
+    /** Box color for an item (any CSS/hex/THREE color). */
+    color: (item: T, index: number) => THREE.ColorRepresentation;
+    /** Footprint on X and Z. Default 0.28. */
+    cellSize?: number;
+    /** Index of the highlighted item, painted with `hoverColor`. */
+    hovered?: number | null;
+    hoverColor?: THREE.ColorRepresentation;
+    /** Called with the item index under the pointer, or null on exit. */
+    onHover?: (index: number | null) => void;
+    /** Staggered grow-in; restarts whenever `data` identity changes. */
+    grow?: {
+        duration?: number;
+        delay?: (item: T, index: number) => number;
+    };
+    castShadow?: boolean;
+    receiveShadow?: boolean;
+    /**
+     * Render arbitrary content per item instead of an instanced box — a sprite, a
+     * GLB, a full entity. The layout positions each on the ground at its `[x, z]`
+     * and hands you the resolved `height` to size against (e.g. one walking figure
+     * per unit of value). When set, the instanced-box path is bypassed.
+     */
+    renderItem?: (item: T, index: number, info: {
+        x: number;
+        z: number;
+        height: number;
+    }) => ReactNode;
+}
+export declare function DataObjects<T>({ data, position, height, color, cellSize, hovered, hoverColor, onHover, grow, castShadow, receiveShadow, renderItem, }: DataObjectsProps<T>): import("react").JSX.Element;

package/dist/world/DataObjects.js

@@ -0,0 +1,75 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useFrame } from "@react-three/fiber";
+import { useEffect, useMemo, useRef } from "react";
+import * as THREE from "three";
+function clamp01(v) {
+    return v < 0 ? 0 : v > 1 ? 1 : v;
+}
+export function DataObjects({ data, position, height, color, cellSize = 0.28, hovered = null, hoverColor = "#ffffff", onHover, grow, castShadow = true, receiveShadow = true, renderItem, }) {
+    const meshRef = useRef(null);
+    const dummy = useMemo(() => new THREE.Object3D(), []);
+    const geometry = useMemo(() => new THREE.BoxGeometry(1, 1, 1), []);
+    const material = useMemo(() => new THREE.MeshStandardMaterial({ roughness: 0.62, metalness: 0.04 }), []);
+    const hover = useMemo(() => new THREE.Color(hoverColor), [hoverColor]);
+    const startRef = useRef(null);
+    const capacity = data.length;
+    const layout = useMemo(() => {
+        const positions = new Float32Array(capacity * 2);
+        const targets = new Float32Array(capacity);
+        const delays = new Float32Array(capacity);
+        const colors = [];
+        data.forEach((item, i) => {
+            const [x, z] = position(item, i);
+            positions[i * 2] = x;
+            positions[i * 2 + 1] = z;
+            targets[i] = height(item, i);
+            delays[i] = grow?.delay?.(item, i) ?? 0;
+            colors.push(new THREE.Color(color(item, i)));
+        });
+        return { positions, targets, delays, colors };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [data]);
+    useEffect(() => {
+        startRef.current = null;
+    }, [data]);
+    useEffect(() => () => {
+        geometry.dispose();
+        material.dispose();
+    }, [geometry, material]);
+    const duration = grow?.duration ?? 0;
+    useFrame((state) => {
+        const mesh = meshRef.current;
+        if (mesh === null)
+            return;
+        if (startRef.current === null)
+            startRef.current = state.clock.elapsedTime;
+        const elapsed = state.clock.elapsedTime - startRef.current;
+        const { positions, targets, delays, colors } = layout;
+        for (let i = 0; i < capacity; i += 1) {
+            const grown = duration <= 0 ? 1 : clamp01((elapsed - delays[i]) / duration);
+            const eased = 1 - Math.pow(1 - grown, 3);
+            const h = Math.max(targets[i] * eased, 0.001);
+            dummy.position.set(positions[i * 2], h / 2, positions[i * 2 + 1]);
+            dummy.scale.set(cellSize, h, cellSize);
+            dummy.updateMatrix();
+            mesh.setMatrixAt(i, dummy.matrix);
+            mesh.setColorAt(i, i === hovered ? hover : colors[i]);
+        }
+        mesh.instanceMatrix.needsUpdate = true;
+        if (mesh.instanceColor !== null)
+            mesh.instanceColor.needsUpdate = true;
+    });
+    function handleMove(event) {
+        if (onHover === undefined)
+            return;
+        event.stopPropagation();
+        onHover(event.instanceId ?? null);
+    }
+    if (renderItem !== undefined) {
+        return (_jsx("group", { children: data.map((item, i) => {
+                const [x, z] = position(item, i);
+                return (_jsx("group", { position: [x, 0, z], children: renderItem(item, i, { x, z, height: height(item, i) }) }, i));
+            }) }));
+    }
+    return (_jsx("instancedMesh", { ref: meshRef, args: [geometry, material, Math.max(capacity, 1)], castShadow: castShadow, receiveShadow: receiveShadow, frustumCulled: false, onPointerMove: onHover === undefined ? undefined : handleMove, onPointerOut: onHover === undefined ? undefined : () => onHover(null) }, capacity));
+}

package/dist/world/GridWorldScene.d.ts

@@ -0,0 +1,10 @@
+import type { WorldFeature } from "@jgengine/core/world/features";
+export interface GridWorldSceneProps {
+    feature: WorldFeature;
+}
+/**
+ * Data-driven renderer for the `biomes()`/`voxel()`/`plots()`/`tilemap()` world-feature kinds
+ * (#207.1): one `InstancedMesh` of extruded, colored boxes built from each feature's declared
+ * `cells`, following the same direct-buffer pattern as `InstancedBodies`.
+ */
+export declare function GridWorldScene({ feature }: GridWorldSceneProps): import("react").JSX.Element | null;

package/dist/world/GridWorldScene.js

@@ -0,0 +1,54 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useMemo, useRef } from "react";
+import * as THREE from "three";
+import { resolveGridInstances } from "@jgengine/core/world/gridInstances";
+function isGridWorldFeature(feature) {
+    return (feature.kind === "biomes" || feature.kind === "voxel" || feature.kind === "plots" || feature.kind === "tilemap");
+}
+/**
+ * Data-driven renderer for the `biomes()`/`voxel()`/`plots()`/`tilemap()` world-feature kinds
+ * (#207.1): one `InstancedMesh` of extruded, colored boxes built from each feature's declared
+ * `cells`, following the same direct-buffer pattern as `InstancedBodies`.
+ */
+export function GridWorldScene({ feature }) {
+    const instances = useMemo(() => (isGridWorldFeature(feature) ? resolveGridInstances(feature) : []), [feature]);
+    const meshRef = useRef(null);
+    const geometry = useMemo(() => new THREE.BoxGeometry(1, 1, 1), []);
+    const material = useMemo(() => new THREE.MeshStandardMaterial({ roughness: 0.9, metalness: 0 }), []);
+    const instanceColor = useMemo(() => new THREE.InstancedBufferAttribute(new Float32Array(Math.max(instances.length, 1) * 3), 3), [instances.length]);
+    useEffect(() => {
+        const mesh = meshRef.current;
+        if (mesh === null)
+            return;
+        mesh.instanceColor = instanceColor;
+        mesh.count = instances.length;
+        const m = mesh.instanceMatrix.array;
+        const c = instanceColor.array;
+        const color = new THREE.Color();
+        for (let i = 0; i < instances.length; i += 1) {
+            const instance = instances[i];
+            const o = i * 16;
+            m[o] = instance.scale[0];
+            m[o + 5] = instance.scale[1];
+            m[o + 10] = instance.scale[2];
+            m[o + 12] = instance.position[0];
+            m[o + 13] = instance.position[1];
+            m[o + 14] = instance.position[2];
+            m[o + 15] = 1;
+            color.set(instance.color);
+            const co = i * 3;
+            c[co] = color.r;
+            c[co + 1] = color.g;
+            c[co + 2] = color.b;
+        }
+        mesh.instanceMatrix.needsUpdate = true;
+        instanceColor.needsUpdate = true;
+    }, [instances, instanceColor]);
+    useEffect(() => () => {
+        geometry.dispose();
+        material.dispose();
+    }, [geometry, material]);
+    if (instances.length === 0)
+        return null;
+    return (_jsx("instancedMesh", { ref: meshRef, args: [geometry, material, instances.length], castShadow: true, receiveShadow: true }));
+}

package/dist/world/WorldHud.d.ts

@@ -1,6 +1,10 @@
-export declare function WorldEntityBars({ statId, height }: {
+import type { SceneEntity } from "@jgengine/core/scene/entityStore";
+import type { CatalogEntityRole } from "@jgengine/core/runtime/gameContext";
+export declare function WorldEntityBars({ statId, height, roles, resolveRole, }: {
     statId: string;
     height?: number;
+    roles?: readonly CatalogEntityRole[];
+    resolveRole?: (entity: SceneEntity) => CatalogEntityRole | undefined;
 }): import("react").JSX.Element;
 export declare function WorldFloatText({ height, lifeMs }: {
     height?: number;

package/dist/world/WorldHud.js

@@ -3,6 +3,7 @@ import { Html, Line } from "@react-three/drei";
 import { useFrame, useThree } from "@react-three/fiber";
 import { useEffect, useMemo, useRef, useState } from "react";
 import * as THREE from "three";
+import { worldHealthBarAllowsRole } from "@jgengine/core/game/playableGame";
 import { useGameContext } from "@jgengine/react/provider";
 import { useEntityStat, useSceneEntities } from "@jgengine/react/hooks";
 import { resolveFloatTextStyle } from "./floatTextStyle.js";
@@ -15,11 +16,14 @@ function EntityBar({ entity, statId, height }) {
     const percent = range <= 0 ? 0 : Math.max(0, Math.min(1, (stat.current - stat.min) / range));
     return (_jsx(Html, { position: [entity.position[0], entity.position[1] + height, entity.position[2]], center: true, distanceFactor: 12, zIndexRange: [20, 0], children: _jsx("div", { className: "h-2.5 w-28 overflow-hidden rounded-sm border border-black/70 bg-black/70 shadow", children: _jsx("div", { className: "h-full bg-gradient-to-r from-rose-600 to-red-400", style: { width: `${percent * 100}%` } }) }) }));
 }
-export function WorldEntityBars({ statId, height = 2.2 }) {
+export function WorldEntityBars({ statId, height = 2.2, roles, resolveRole, }) {
     const ctx = useGameContext();
     const entities = useSceneEntities();
     const playerId = ctx.player.userId;
-    return (_jsx(_Fragment, { children: entities.map((entity) => entity.id === playerId ? null : (_jsx(EntityBar, { entity: entity, statId: statId, height: height }, entity.id))) }));
+    return (_jsx(_Fragment, { children: entities
+            .filter((entity) => entity.id !== playerId)
+            .filter((entity) => worldHealthBarAllowsRole(roles, resolveRole?.(entity)))
+            .map((entity) => (_jsx(EntityBar, { entity: entity, statId: statId, height: height }, entity.id))) }));
 }
 function FloatTextItem({ event, lifeMs }) {
     const [shown, setShown] = useState(false);

package/dist/world/WorldItems.js

@@ -1,18 +1,37 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Html, Line } from "@react-three/drei";
-import { useMemo } from "react";
+import { useMemo, useRef } from "react";
+import { useFrame } from "@react-three/fiber";
 import { resolveWorldItemPresentation } from "@jgengine/core/game/worldItem";
 import { useGameContext } from "@jgengine/react/provider";
 import { useWorldItems } from "@jgengine/react/hooks";
 import { POINTER_ENTITY_KEY } from "../pointer/pointerService.js";
 const DEFAULT_BEAM_HEIGHT = 2.5;
 const FALLBACK_COLOR = "#e5e7eb";
+const REST_HEIGHT = 0.32;
+const SPAWN_DURATION = 0.4;
 function WorldItemMarker({ instanceId, position, color, beam, label, beamHeight, }) {
     const beamPoints = useMemo(() => [
         [0, 0, 0],
         [0, beamHeight, 0],
     ], [beamHeight]);
-    return (_jsxs("group", { position: [position[0], position[1], position[2]], userData: { [POINTER_ENTITY_KEY]: instanceId }, children: [_jsxs("mesh", { "rotation-x": -Math.PI / 2, "position-y": 0.03, children: [_jsx("ringGeometry", { args: [0.26, 0.4, 24] }), _jsx("meshBasicMaterial", { color: color, transparent: true, opacity: 0.85 })] }), _jsxs("mesh", { "position-y": 0.32, children: [_jsx("octahedronGeometry", { args: [0.22, 0] }), _jsx("meshStandardMaterial", { color: color, emissive: color, emissiveIntensity: 0.6 })] }), beam ? _jsx(Line, { points: beamPoints, color: color, lineWidth: 2, transparent: true, opacity: 0.55 }) : null, label !== undefined && label.length > 0 ? (_jsx(Html, { position: [0, beamHeight + 0.2, 0], center: true, distanceFactor: 12, zIndexRange: [15, 0], children: _jsx("div", { className: "whitespace-nowrap rounded-sm border px-1.5 py-0.5 text-[11px] font-bold shadow", style: { borderColor: color, color, backgroundColor: "rgba(10,10,14,0.75)" }, children: label }) })) : null] }));
+    // Drop animation: the gem leaps up on spawn, settles, then idles with a slow
+    // spin + hover so a fresh drop reads as "something just fell here". Age is
+    // accumulated from frame deltas (Date.now is unavailable to keep runs pure).
+    const gemRef = useRef(null);
+    const ageRef = useRef(0);
+    useFrame((_state, delta) => {
+        const gem = gemRef.current;
+        if (gem === null)
+            return;
+        const age = ageRef.current + delta;
+        ageRef.current = age;
+        const spawn = age < SPAWN_DURATION ? Math.sin((age / SPAWN_DURATION) * Math.PI) * 0.35 : 0;
+        const bob = Math.sin(age * 2.2) * 0.06;
+        gem.position.y = REST_HEIGHT + bob + spawn;
+        gem.rotation.y = age * 1.6;
+    });
+    return (_jsxs("group", { position: [position[0], position[1], position[2]], userData: { [POINTER_ENTITY_KEY]: instanceId }, children: [_jsxs("mesh", { "rotation-x": -Math.PI / 2, "position-y": 0.03, children: [_jsx("ringGeometry", { args: [0.26, 0.4, 24] }), _jsx("meshBasicMaterial", { color: color, transparent: true, opacity: 0.85 })] }), _jsx("group", { ref: gemRef, "position-y": REST_HEIGHT, children: _jsxs("mesh", { children: [_jsx("octahedronGeometry", { args: [0.22, 0] }), _jsx("meshStandardMaterial", { color: color, emissive: color, emissiveIntensity: 0.6 })] }) }), beam ? _jsx(Line, { points: beamPoints, color: color, lineWidth: 2, transparent: true, opacity: 0.55 }) : null, label !== undefined && label.length > 0 ? (_jsx(Html, { position: [0, beamHeight + 0.2, 0], center: true, distanceFactor: 12, zIndexRange: [15, 0], children: _jsx("div", { className: "whitespace-nowrap rounded-sm border px-1.5 py-0.5 text-[11px] font-bold shadow", style: { borderColor: color, color, backgroundColor: "rgba(10,10,14,0.75)" }, children: label }) })) : null] }));
 }
 /** Rarity→beam/color/label render binding + loot-filter overlay (#32/#33) for every dropped `worldItem`. */
 export function WorldItems({ config }) {