@jgengine/shell 0.11.0 → 0.13.0

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 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";
+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\nattribute float aDepth;\n\nvarying vec3 vWorldPosition;\nvarying vec3 vNormal;\nvarying float vCrest;\nvarying float vWaveHeight;\nvarying float vDepth;\nvarying vec2 vOceanUv;\n\nvoid main() {\n  vOceanUv = uv;\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  // Waves flatten as the bed shoals so swells die at the shoreline instead of clipping it.\n  float depthDamp = smoothstep(0.05, 1.4, aDepth);\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 * depthDamp;\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  vDepth = aDepth;\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 float uTime;\nuniform vec3 uShallowColor;\nuniform vec3 uDeepColor;\nuniform vec3 uCrestColor;\nuniform vec3 uFoamColor;\nuniform float uOpacity;\nuniform float uFresnelStrength;\nuniform float uHorizonBlend;\nuniform float uFoamIntensity;\nuniform float uDepthRange;\nuniform float uShoreFoamWidth;\nuniform float uSparkle;\nuniform vec3 uSunDirection;\n\nvarying vec3 vWorldPosition;\nvarying vec3 vNormal;\nvarying float vCrest;\nvarying float vWaveHeight;\nvarying float vDepth;\nvarying vec2 vOceanUv;\n\nfloat jgWaterHash(vec2 p) {\n  uvec2 q = uvec2(ivec2(floor(p)));\n  uint x = q.x * 1664525u + q.y * 1013904223u;\n  x = (x ^ (x >> 16u)) * 2246822519u;\n  x = (x ^ (x >> 13u)) * 3266489917u;\n  return float(x ^ (x >> 16u)) * (1.0 / 4294967296.0);\n}\n\nfloat jgWaterNoise(vec2 p) {\n  vec2 i = floor(p);\n  vec2 f = fract(p);\n  vec2 u = f * f * (3.0 - 2.0 * f);\n  float a = jgWaterHash(i);\n  float b = jgWaterHash(i + vec2(1.0, 0.0));\n  float c = jgWaterHash(i + vec2(0.0, 1.0));\n  float d = jgWaterHash(i + vec2(1.0, 1.0));\n  return mix(mix(a, b, u.x), mix(c, d, u.x), u.y);\n}\n\nvoid main() {\n  vec3 viewDirection = normalize(cameraPosition - vWorldPosition);\n\n  // Fine scrolling normal perturbation: two counter-drifting noise layers ripple the surface\n  // between the big Gerstner swells.\n  vec2 wp = vWorldPosition.xz;\n  float ripple1 = jgWaterNoise(wp * 1.7 + vec2(uTime * 0.22, uTime * 0.15));\n  float ripple2 = jgWaterNoise(wp * 3.1 - vec2(uTime * 0.17, uTime * 0.26));\n  vec3 normal = normalize(normalize(vNormal) + vec3(ripple1 - 0.5, 0.0, ripple2 - 0.5) * 0.14);\n\n  // Depth-based body color: warm shallows at the shore ramp falling to the deep tone.\n  float depthMix = smoothstep(0.0, max(uDepthRange, 0.001), vDepth);\n  vec3 waterColor = mix(uShallowColor, uDeepColor, depthMix);\n  waterColor = mix(waterColor, uCrestColor, smoothstep(0.15, 1.2, vWaveHeight) * 0.22);\n\n  // Restrained fresnel: a soft sky tint at grazing angles, never a white-out.\n  float fresnel = pow(1.0 - max(dot(normal, viewDirection), 0.0), 5.0);\n  waterColor = mix(waterColor, vec3(0.62, 0.78, 0.85), min(fresnel * uFresnelStrength, 0.45));\n  float horizon = smoothstep(0.0, 1.0, 1.0 - abs(normal.y));\n  waterColor = mix(waterColor, uShallowColor, horizon * uHorizonBlend * 0.6);\n\n  // Sun glints: sparkle where the perturbed normal mirrors the sun, gated by noise so it\n  // twinkles in cells instead of sheening uniformly.\n  vec3 halfway = normalize(viewDirection + normalize(uSunDirection));\n  float glint = pow(max(dot(normal, halfway), 0.0), 150.0);\n  float glintMask = smoothstep(0.68, 0.92, jgWaterNoise(wp * 2.3 + vec2(uTime * 0.4, -uTime * 0.31)));\n  waterColor += vec3(1.0, 0.98, 0.9) * glint * glintMask * uSparkle;\n\n  // Foam: a noise-eaten shoreline lick plus crest foam. A second, larger noise gates whole\n  // stretches of shoreline so foam laps in patches instead of outlining the bank uniformly.\n  float foamNoise = jgWaterNoise(wp * 2.6 + vec2(uTime * 0.28, uTime * 0.2));\n  float foamStretch = smoothstep(0.3, 0.8, jgWaterNoise(wp * 0.33 + vec2(3.7, 9.2) + vec2(uTime * 0.05, 0.0)));\n  float shoreFoam = (1.0 - smoothstep(0.0, max(uShoreFoamWidth, 0.001), vDepth - foamNoise * uShoreFoamWidth * 0.9))\n    * smoothstep(0.25, 0.75, foamNoise) * (0.2 + 0.6 * foamStretch);\n  float crestFoam = clamp(vCrest * uFoamIntensity, 0.0, 1.0) * smoothstep(0.35, 0.75, foamNoise);\n  float foam = clamp(shoreFoam + crestFoam, 0.0, 1.0);\n  vec3 color = mix(waterColor, uFoamColor, foam);\n\n  // Soft shore: the sheet turns glass-clear over the last stretch of shoaling bed, so the\n  // waterline is a blend into the terrain, not a hard tarp edge.\n  float shoreAlpha = smoothstep(0.0, 0.55, vDepth);\n  float alpha = uOpacity * mix(0.35, 1.0, shoreAlpha) + foam * 0.3;\n  // The sheet's own border always dissolves \u2014 a bounded water plane must never end in a\n  // visible straight cut, whatever the bed underneath is doing.\n  float borderDist = min(min(vOceanUv.x, 1.0 - vOceanUv.x), min(vOceanUv.y, 1.0 - vOceanUv.y));\n  alpha *= smoothstep(0.0, 0.045, borderDist);\n  gl_FragColor = vec4(color, clamp(alpha, 0.0, 1.0));\n}\n";

package/dist/water/OceanShader.js

@@ -7,22 +7,29 @@ uniform float uFoamThreshold;
 uniform float uFoamSoftness;
 uniform float uFoamCoverage;
 
+attribute float aDepth;
+
 varying vec3 vWorldPosition;
 varying vec3 vNormal;
 varying float vCrest;
 varying float vWaveHeight;
+varying float vDepth;
+varying vec2 vOceanUv;
 
 void main() {
+  vOceanUv = uv;
   vec3 displaced = position;
   vec3 tangent = vec3(1.0, 0.0, 0.0);
   vec3 bitangent = vec3(0.0, 0.0, 1.0);
   float crest = 0.0;
+  // Waves flatten as the bed shoals so swells die at the shoreline instead of clipping it.
+  float depthDamp = smoothstep(0.05, 1.4, aDepth);
 
   for (int i = 0; i < 6; i++) {
     vec2 direction = normalize(uWaveDirections[i]);
     vec4 wave = uWaveParams[i];
     float k = wave.x;
-    float amplitude = wave.y;
+    float amplitude = wave.y * depthDamp;
     float steepness = wave.z;
     float omega = wave.w;
     float phase = k * dot(direction, position.xz) - omega * uTime;
@@ -41,12 +48,14 @@ void main() {
   vNormal = normalize(cross(bitangent, tangent));
   vCrest = crest;
   vWaveHeight = displaced.y;
+  vDepth = aDepth;
   vec4 worldPosition = modelMatrix * vec4(displaced, 1.0);
   vWorldPosition = worldPosition.xyz;
   gl_Position = projectionMatrix * viewMatrix * worldPosition;
 }
 `;
 export const oceanFragmentShader = `
+uniform float uTime;
 uniform vec3 uShallowColor;
 uniform vec3 uDeepColor;
 uniform vec3 uCrestColor;
@@ -55,24 +64,83 @@ uniform float uOpacity;
 uniform float uFresnelStrength;
 uniform float uHorizonBlend;
 uniform float uFoamIntensity;
+uniform float uDepthRange;
+uniform float uShoreFoamWidth;
+uniform float uSparkle;
+uniform vec3 uSunDirection;
 
 varying vec3 vWorldPosition;
 varying vec3 vNormal;
 varying float vCrest;
 varying float vWaveHeight;
+varying float vDepth;
+varying vec2 vOceanUv;
+
+float jgWaterHash(vec2 p) {
+  uvec2 q = uvec2(ivec2(floor(p)));
+  uint x = q.x * 1664525u + q.y * 1013904223u;
+  x = (x ^ (x >> 16u)) * 2246822519u;
+  x = (x ^ (x >> 13u)) * 3266489917u;
+  return float(x ^ (x >> 16u)) * (1.0 / 4294967296.0);
+}
+
+float jgWaterNoise(vec2 p) {
+  vec2 i = floor(p);
+  vec2 f = fract(p);
+  vec2 u = f * f * (3.0 - 2.0 * f);
+  float a = jgWaterHash(i);
+  float b = jgWaterHash(i + vec2(1.0, 0.0));
+  float c = jgWaterHash(i + vec2(0.0, 1.0));
+  float d = jgWaterHash(i + vec2(1.0, 1.0));
+  return mix(mix(a, b, u.x), mix(c, d, u.x), u.y);
+}
 
 void main() {
-  vec3 normal = normalize(vNormal);
   vec3 viewDirection = normalize(cameraPosition - vWorldPosition);
-  float fresnel = pow(1.0 - max(dot(normal, viewDirection), 0.0), 4.5);
-  float depthMix = smoothstep(-1.8, 1.6, vWaveHeight);
-  vec3 waterColor = mix(uDeepColor, uShallowColor, depthMix);
-  waterColor = mix(waterColor, uCrestColor, smoothstep(0.15, 1.2, vWaveHeight) * 0.28);
-  waterColor = mix(waterColor, vec3(0.86, 0.95, 1.0), fresnel * uFresnelStrength);
+
+  // Fine scrolling normal perturbation: two counter-drifting noise layers ripple the surface
+  // between the big Gerstner swells.
+  vec2 wp = vWorldPosition.xz;
+  float ripple1 = jgWaterNoise(wp * 1.7 + vec2(uTime * 0.22, uTime * 0.15));
+  float ripple2 = jgWaterNoise(wp * 3.1 - vec2(uTime * 0.17, uTime * 0.26));
+  vec3 normal = normalize(normalize(vNormal) + vec3(ripple1 - 0.5, 0.0, ripple2 - 0.5) * 0.14);
+
+  // Depth-based body color: warm shallows at the shore ramp falling to the deep tone.
+  float depthMix = smoothstep(0.0, max(uDepthRange, 0.001), vDepth);
+  vec3 waterColor = mix(uShallowColor, uDeepColor, depthMix);
+  waterColor = mix(waterColor, uCrestColor, smoothstep(0.15, 1.2, vWaveHeight) * 0.22);
+
+  // Restrained fresnel: a soft sky tint at grazing angles, never a white-out.
+  float fresnel = pow(1.0 - max(dot(normal, viewDirection), 0.0), 5.0);
+  waterColor = mix(waterColor, vec3(0.62, 0.78, 0.85), min(fresnel * uFresnelStrength, 0.45));
   float horizon = smoothstep(0.0, 1.0, 1.0 - abs(normal.y));
-  waterColor = mix(waterColor, uShallowColor, horizon * uHorizonBlend);
-  float foam = clamp(vCrest * uFoamIntensity, 0.0, 1.0);
+  waterColor = mix(waterColor, uShallowColor, horizon * uHorizonBlend * 0.6);
+
+  // Sun glints: sparkle where the perturbed normal mirrors the sun, gated by noise so it
+  // twinkles in cells instead of sheening uniformly.
+  vec3 halfway = normalize(viewDirection + normalize(uSunDirection));
+  float glint = pow(max(dot(normal, halfway), 0.0), 150.0);
+  float glintMask = smoothstep(0.68, 0.92, jgWaterNoise(wp * 2.3 + vec2(uTime * 0.4, -uTime * 0.31)));
+  waterColor += vec3(1.0, 0.98, 0.9) * glint * glintMask * uSparkle;
+
+  // Foam: a noise-eaten shoreline lick plus crest foam. A second, larger noise gates whole
+  // stretches of shoreline so foam laps in patches instead of outlining the bank uniformly.
+  float foamNoise = jgWaterNoise(wp * 2.6 + vec2(uTime * 0.28, uTime * 0.2));
+  float foamStretch = smoothstep(0.3, 0.8, jgWaterNoise(wp * 0.33 + vec2(3.7, 9.2) + vec2(uTime * 0.05, 0.0)));
+  float shoreFoam = (1.0 - smoothstep(0.0, max(uShoreFoamWidth, 0.001), vDepth - foamNoise * uShoreFoamWidth * 0.9))
+    * smoothstep(0.25, 0.75, foamNoise) * (0.2 + 0.6 * foamStretch);
+  float crestFoam = clamp(vCrest * uFoamIntensity, 0.0, 1.0) * smoothstep(0.35, 0.75, foamNoise);
+  float foam = clamp(shoreFoam + crestFoam, 0.0, 1.0);
   vec3 color = mix(waterColor, uFoamColor, foam);
-  gl_FragColor = vec4(color, uOpacity);
+
+  // Soft shore: the sheet turns glass-clear over the last stretch of shoaling bed, so the
+  // waterline is a blend into the terrain, not a hard tarp edge.
+  float shoreAlpha = smoothstep(0.0, 0.55, vDepth);
+  float alpha = uOpacity * mix(0.35, 1.0, shoreAlpha) + foam * 0.3;
+  // The sheet's own border always dissolves — a bounded water plane must never end in a
+  // visible straight cut, whatever the bed underneath is doing.
+  float borderDist = min(min(vOceanUv.x, 1.0 - vOceanUv.x), min(vOceanUv.y, 1.0 - vOceanUv.y));
+  alpha *= smoothstep(0.0, 0.045, borderDist);
+  gl_FragColor = vec4(color, clamp(alpha, 0.0, 1.0));
 }
 `;

package/dist/world/PlaceScene.d.ts

@@ -0,0 +1,11 @@
+import type { PlaceWorldFeature } from "@jgengine/core/world/place";
+/**
+ * The substrate of a place world, rendered plainly: a flat slab or a round planet under the engine
+ * default sky. This is deliberately not a diorama — sky look, foliage, props, and sculpt are scene
+ * content the editor authors; `voxel` grounds are realized by the game's generation systems and
+ * `board` grounds by the game's own 2D face, so both mount nothing here.
+ * @internal
+ */
+export declare function PlaceScene({ feature }: {
+    feature: PlaceWorldFeature;
+}): import("react").JSX.Element | null;

package/dist/world/PlaceScene.js

@@ -0,0 +1,27 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useMemo } from "react";
+import { DefaultSurface } from "../render/defaultSurface.js";
+/** Render extent (m) standing in for an `Infinity` flat-ground axis — far past the default fog. */
+const UNBOUNDED_RENDER_EXTENT = 2048;
+const GROUND_COLOR = "#5c6b52";
+function clampExtent(value) {
+    return Number.isFinite(value) ? value : UNBOUNDED_RENDER_EXTENT;
+}
+/**
+ * The substrate of a place world, rendered plainly: a flat slab or a round planet under the engine
+ * default sky. This is deliberately not a diorama — sky look, foliage, props, and sculpt are scene
+ * content the editor authors; `voxel` grounds are realized by the game's generation systems and
+ * `board` grounds by the game's own 2D face, so both mount nothing here.
+ * @internal
+ */
+export function PlaceScene({ feature }) {
+    const ground = feature.ground;
+    const size = useMemo(() => ground.mode === "flat" ? [clampExtent(ground.size.x), clampExtent(ground.size.z)] : undefined, [ground]);
+    if (ground.mode === "flat" && size !== undefined) {
+        return (_jsxs("mesh", { "rotation-x": -Math.PI / 2, receiveShadow: true, children: [_jsx("planeGeometry", { args: [size[0], size[1]] }), _jsx(DefaultSurface, { color: GROUND_COLOR, roughness: 0.95 })] }));
+    }
+    if (ground.mode === "round") {
+        return (_jsxs("mesh", { position: [0, -ground.size.radius, 0], receiveShadow: true, children: [_jsx("sphereGeometry", { args: [ground.size.radius, 64, 48] }), _jsx(DefaultSurface, { color: GROUND_COLOR, roughness: 0.95 })] }));
+    }
+    return null;
+}

package/dist/world/WorldHud.d.ts

@@ -23,6 +23,8 @@ export interface WorldNameplatesProps {
     maxDistance?: number;
     /** Minimum ms between position/health refreshes — trades smoothness for fewer re-renders at scale. Default 120. */
     tickMs?: number;
+    /** Draw the built-in HP bar under the name. Set `false` for a name-only plate when the game already draws its own health bar (its own HUD, or `worldHealthBars`). Default true. */
+    showHealth?: boolean;
     className?: string;
     nameplateClassName?: string;
     nameClassName?: string;
@@ -39,7 +41,7 @@ export interface WorldNameplatesProps {
  *
  * @capability nameplates billboarded name + HP bar over nearby entities
  */
-export declare function WorldNameplates({ statId, height, roles, resolveRole, maxDistance, tickMs, className, nameplateClassName, nameClassName, barClassName, fillClassName, renderNameplate, }: WorldNameplatesProps): import("react").JSX.Element;
+export declare function WorldNameplates({ statId, height, roles, resolveRole, maxDistance, tickMs, showHealth, className, nameplateClassName, nameClassName, barClassName, fillClassName, renderNameplate, }: WorldNameplatesProps): import("react").JSX.Element;
 /** Props for {@link WorldObjectHighlights}. */
 export interface WorldObjectHighlightsProps {
     /** Ring tint. Default a construction-select amber. */

package/dist/world/WorldHud.js

@@ -50,7 +50,7 @@ export function WorldEntityBars({ statId, height = 2.2, roles, resolveRole, maxD
  *
  * @capability nameplates billboarded name + HP bar over nearby entities
  */
-export function WorldNameplates({ statId = "health", height = 2.3, roles, resolveRole, maxDistance = 40, tickMs = 120, className, nameplateClassName, nameClassName, barClassName, fillClassName, renderNameplate, }) {
+export function WorldNameplates({ statId = "health", height = 2.3, roles, resolveRole, maxDistance = 40, tickMs = 120, showHealth = true, className, nameplateClassName, nameClassName, barClassName, fillClassName, renderNameplate, }) {
     const ctx = useGameContext();
     const camera = useThree((state) => state.camera);
     const size = useThree((state) => state.size);
@@ -83,7 +83,7 @@ export function WorldNameplates({ statId = "health", height = 2.3, roles, resolv
                             color: "#f1f5f9",
                             textShadow: "0 1px 3px rgba(0,0,0,0.9)",
                             whiteSpace: "nowrap",
-                        }, children: sample.name }), sample.percent !== null ? (_jsx("span", { className: barClassName, "data-nameplate-bar": true, style: {
+                        }, children: sample.name }), showHealth && sample.percent !== null ? (_jsx("span", { className: barClassName, "data-nameplate-bar": true, style: {
                             display: "block",
                             width: 78,
                             height: 6,

package/dist/world/WorldScene.js

@@ -4,10 +4,12 @@ import { useEffect, useMemo, useRef } from "react";
 import * as THREE from "three";
 import { objectVisualScale } from "@jgengine/core/scene/objectStore";
 import { WORLD_ITEM_ENTITY_NAME } from "@jgengine/core/game/worldItem";
+import { beginFallbackSeam, endFallbackPass, reportFallbackSeam, } from "@jgengine/core/devtools/fallbackSeams";
 import { useGameContext } from "@jgengine/react/provider";
 import { useSceneEntityIds, useSceneObjectIds, useGameStore, usePlayer, useTarget } from "@jgengine/react/hooks";
 import { colorFromId } from "../worldSky.js";
 import { DefaultSurface, detailMaps } from "../render/defaultSurface.js";
+import { MeasuredBoundsGroup } from "../render/measureBounds.js";
 import { EntitySprite, IsolatedEntityModel } from "../render/SceneModels.js";
 import { resolveModel, resolveEntityModel, tryResolveCatalogModel } from "../render/resolveModel.js";
 import { useRenderVisibility } from "../visibility/CullingProvider.js";
@@ -40,7 +42,7 @@ function EntityMarker({ entity, custom, model, sprite, isLocal, targeted, select
             const live = ctx.scene.entity.get(entityId);
             if (live !== null)
                 onSelect(live);
-        }, children: [selected ? (_jsxs("mesh", { "rotation-x": -Math.PI / 2, "position-y": 0.02, children: [_jsx("ringGeometry", { args: [0.8, 0.95, 32] }), _jsx("meshBasicMaterial", { color: "#34d399", transparent: true, opacity: 0.9 })] })) : null, custom !== undefined && custom !== null ? (custom) : model !== undefined ? (_jsx(IsolatedEntityModel, { model: model, instanceId: entityId, fallback: sprite !== undefined ? _jsx(EntitySprite, { sprite: sprite }) : undefined })) : sprite !== undefined ? (_jsx(EntitySprite, { sprite: sprite })) : role === "prop" ? (_jsxs("mesh", { "position-y": 0.5, castShadow: true, receiveShadow: true, children: [_jsx("sphereGeometry", { args: [0.45, 24, 24] }), _jsx(DefaultSurface, { color: color })] })) : (_jsxs("group", { scale: ctx.scene.entity.visualScaleOf(entityId), children: [_jsxs("mesh", { "position-y": 0.95, castShadow: true, receiveShadow: true, children: [_jsx("capsuleGeometry", { args: [0.35, 1.1, 6, 14] }), _jsx(DefaultSurface, { color: color, roughness: 0.6 })] }), _jsxs("mesh", { position: [0, 1.35, 0.32], children: [_jsx("boxGeometry", { args: [0.16, 0.16, 0.16] }), _jsx("meshStandardMaterial", { color: "#f8fafc" })] })] })), targeted ? (_jsxs("mesh", { "rotation-x": -Math.PI / 2, "position-y": 0.03, children: [_jsx("ringGeometry", { args: [0.6, 0.75, 28] }), _jsx("meshBasicMaterial", { color: "#f87171" })] })) : null] }));
+        }, children: [selected ? (_jsxs("mesh", { "rotation-x": -Math.PI / 2, "position-y": 0.02, children: [_jsx("ringGeometry", { args: [0.8, 0.95, 32] }), _jsx("meshBasicMaterial", { color: "#34d399", transparent: true, opacity: 0.9 })] })) : null, custom !== undefined && custom !== null ? (_jsx(MeasuredBoundsGroup, { target: "entity", measureKey: name, children: custom })) : model !== undefined ? (_jsx(IsolatedEntityModel, { model: model, instanceId: entityId, measure: { target: "entity", key: name }, fallback: sprite !== undefined ? _jsx(EntitySprite, { sprite: sprite }) : undefined })) : sprite !== undefined ? (_jsx(EntitySprite, { sprite: sprite })) : role === "prop" ? (_jsxs("mesh", { "position-y": 0.5, castShadow: true, receiveShadow: true, children: [_jsx("sphereGeometry", { args: [0.45, 24, 24] }), _jsx(DefaultSurface, { color: color })] })) : (_jsxs("group", { scale: ctx.scene.entity.visualScaleOf(entityId), children: [_jsxs("mesh", { "position-y": 0.95, castShadow: true, receiveShadow: true, children: [_jsx("capsuleGeometry", { args: [0.35, 1.1, 6, 14] }), _jsx(DefaultSurface, { color: color, roughness: 0.6 })] }), _jsxs("mesh", { position: [0, 1.35, 0.32], children: [_jsx("boxGeometry", { args: [0.16, 0.16, 0.16] }), _jsx("meshStandardMaterial", { color: "#f8fafc" })] })] })), targeted ? (_jsxs("mesh", { "rotation-x": -Math.PI / 2, "position-y": 0.03, children: [_jsx("ringGeometry", { args: [0.6, 0.75, 28] }), _jsx("meshBasicMaterial", { color: "#f87171" })] })) : null] }));
 }
 function ObjectMarker({ object, custom, model, style, }) {
     const groupRef = useRef(null);
@@ -60,7 +62,7 @@ function ObjectMarker({ object, custom, model, style, }) {
         writeEntityPose(group, live);
         group.visible = visibleRef.current(instanceId);
     });
-    return (_jsx("group", { ref: groupRef, userData: { [POINTER_OBJECT_KEY]: instanceId }, children: custom !== undefined && custom !== null ? (custom) : model !== undefined ? (_jsx(IsolatedEntityModel, { model: model, instanceId: instanceId })) : style?.hidden === true ? null : (_jsxs("mesh", { "position-y": 0.5 * scaleY, scale: [scaleX, scaleY, scaleZ], castShadow: true, receiveShadow: true, children: [_jsx("boxGeometry", { args: [1, 1, 1] }), _jsx(DefaultSurface, { color: color, transparent: opacity < 1, opacity: opacity })] })) }));
+    return (_jsx("group", { ref: groupRef, userData: { [POINTER_OBJECT_KEY]: instanceId }, children: custom !== undefined && custom !== null ? (_jsx(MeasuredBoundsGroup, { target: "object", measureKey: object.catalogId, children: custom })) : model !== undefined ? (_jsx(IsolatedEntityModel, { model: model, instanceId: instanceId, measure: { target: "object", key: object.catalogId } })) : style?.hidden === true ? null : (_jsxs("mesh", { "position-y": 0.5 * scaleY, scale: [scaleX, scaleY, scaleZ], castShadow: true, receiveShadow: true, children: [_jsx("boxGeometry", { args: [1, 1, 1] }), _jsx(DefaultSurface, { color: color, transparent: opacity < 1, opacity: opacity })] })) }));
 }
 function GroundPlane() {
     const geometry = useMemo(() => {
@@ -118,8 +120,12 @@ function RockField() {
     return (_jsx(_Fragment, { children: rocks.map((rock) => (_jsxs("mesh", { position: [rock.x, 0.25 * rock.scale, rock.z], rotation: [0.1, rock.rotation, -0.08], scale: [rock.scale * 1.4, rock.scale * 0.7, rock.scale], castShadow: true, receiveShadow: true, children: [_jsx("dodecahedronGeometry", { args: [0.8, 1] }), _jsx(DefaultSurface, { color: "#6b6f63", roughness: 0.95 })] }, rock.id))) }));
 }
 function WorldEnvironment({ environment: Environment }) {
+    // Dev diagnostic (no-op unless armed): a missing environment component means the default green
+    // ground/rocks stand in for an unauthored scene. Re-zero then report so this is idempotent.
+    beginFallbackSeam("ground");
     if (Environment !== undefined)
         return _jsx(Environment, {});
+    reportFallbackSeam("ground", "noScene");
     return (_jsxs(_Fragment, { children: [_jsx(GroundPlane, {}), _jsx(RockField, {})] }));
 }
 function WorldActors({ entitySprites, entityModels, objectModels, objectStyles, assets, renderEntity, renderObject, selectedIds, hideLocalActor, }) {
@@ -133,22 +139,44 @@ function WorldActors({ entitySprites, entityModels, objectModels, objectStyles,
         const relation = ctx.scene.entity.canReceive(entity.id, "damage") === null ? "hostile" : "friendly";
         ctx.scene.entity.setTarget(controlledId, relation === "hostile" || entity.role === "npc" ? entity.id : null);
     };
+    // Dev diagnostic (no-op unless armed): re-zero the entity/object seams before this render re-tallies
+    // which actors fall back to primitives. Committing the log runs in a useEffect after the render.
+    beginFallbackSeam("entity");
+    beginFallbackSeam("object");
+    useEffect(() => {
+        endFallbackPass();
+    });
     return (_jsxs(_Fragment, { children: [entityIds.map((entityId) => {
                 const entity = ctx.scene.entity.get(entityId);
                 if (entity === null || entity.name === WORLD_ITEM_ENTITY_NAME)
                     return null;
                 if (hideLocalActor && entityId === controlledId)
                     return null;
-                return (_jsx(EntityMarker, { entity: entity, custom: renderEntity?.(entity), model: resolveEntityModel(entityModels?.[entity.name], assets, entity.name), sprite: entitySprites?.[entity.name], isLocal: entityId === controlledId, targeted: entityId === targetId, selected: selectedIds.has(entityId), onSelect: handleSelect }, entityId));
+                const custom = renderEntity?.(entity);
+                const model = resolveEntityModel(entityModels?.[entity.name], assets, entity.name);
+                const sprite = entitySprites?.[entity.name];
+                // Entity models resolve via the hard resolveModel (throws on a present-but-missing id), so
+                // reaching the primitive capsule with no model or sprite means the mapping was omitted.
+                if ((custom === undefined || custom === null) && model === undefined && sprite === undefined) {
+                    reportFallbackSeam("entity", "omittedMapping");
+                }
+                return (_jsx(EntityMarker, { entity: entity, custom: custom, model: model, sprite: sprite, isLocal: entityId === controlledId, targeted: entityId === targetId, selected: selectedIds.has(entityId), onSelect: handleSelect }, entityId));
             }), objectIds.map((instanceId) => {
                 const object = ctx.scene.object.get(instanceId);
                 if (object === null)
                     return null;
+                const custom = renderObject?.(object);
                 const model = resolveModel(objectModels?.[object.catalogId], assets, {
                     seam: "objectModels",
                     key: object.catalogId,
                 }) ?? tryResolveCatalogModel(object.catalogId, assets);
-                return (_jsx(ObjectMarker, { object: object, custom: renderObject?.(object), model: model, style: objectStyles?.[object.catalogId] }, instanceId));
+                const style = objectStyles?.[object.catalogId];
+                // Reaching the primitive box means no model resolved. A present-but-unresolved objectModels
+                // key implies its asset pack is not pulled; an absent key is an omitted (often intended) mapping.
+                if ((custom === undefined || custom === null) && model === undefined && style?.hidden !== true) {
+                    reportFallbackSeam("object", objectModels?.[object.catalogId] === undefined ? "omittedMapping" : "unpulledPack");
+                }
+                return (_jsx(ObjectMarker, { object: object, custom: custom, model: model, style: style }, instanceId));
             })] }));
 }
 export function WorldView({ entitySprites, entityModels, objectModels, objectStyles, environment, assets, renderEntity, renderObject, selectedIds, hideLocalActor, }) {

package/dist/worldSky.d.ts

@@ -1,5 +1,11 @@
 import type { SkyEnvironmentDescriptor, WorldFeature } from "@jgengine/core/world/features";
-/** The world's declared sky, when its world feature is an environment with one (#196.1). @internal */
+/**
+ * The sky in effect for a world feature (#196.1). Environments answer their declared sky; place
+ * worlds (`world()` — substrate + laws, no sky fields) get the engine default sky for 3D grounds,
+ * while `board` grounds get none (the game owns the 2D face it draws). An authored scene document's
+ * sky arrives through `backdrop`/`lighting`, which wins over this at the presentation layer.
+ * @internal
+ */
 export declare function resolveWorldSky(world: WorldFeature | undefined): SkyEnvironmentDescriptor | undefined;
 /** Deterministic HSL color from a stable instance id (default entity/object tint). @internal */
 export declare function colorFromId(id: string): string;

package/dist/worldSky.js

@@ -1,5 +1,15 @@
-/** The world's declared sky, when its world feature is an environment with one (#196.1). @internal */
+/** The engine default sky a 3D place world renders when no sky is authored in its scene document. */
+const PLACE_DEFAULT_SKY = { kind: "sky", preset: "day", timeOfDay: false };
+/**
+ * The sky in effect for a world feature (#196.1). Environments answer their declared sky; place
+ * worlds (`world()` — substrate + laws, no sky fields) get the engine default sky for 3D grounds,
+ * while `board` grounds get none (the game owns the 2D face it draws). An authored scene document's
+ * sky arrives through `backdrop`/`lighting`, which wins over this at the presentation layer.
+ * @internal
+ */
 export function resolveWorldSky(world) {
+    if (world?.kind === "place")
+        return world.ground.mode === "board" ? undefined : PLACE_DEFAULT_SKY;
     return world?.kind === "environment" ? world.sky : undefined;
 }
 /** Deterministic HSL color from a stable instance id (default entity/object tint). @internal */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/shell",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "Game player shell for JGengine: React Three Fiber canvas, orbit camera, input tracking, HUD mounting, GameUiPreview, and a demo game. Consumers supply a GameRegistry.",
   "license": "Apache-2.0",
   "type": "module",
@@ -35,9 +35,9 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@jgengine/core": "^0.11.0",
-    "@jgengine/react": "^0.11.0",
-    "@jgengine/ws": "^0.11.0"
+    "@jgengine/core": "^0.13.0",
+    "@jgengine/react": "^0.13.0",
+    "@jgengine/ws": "^0.13.0"
   },
   "peerDependencies": {
     "@react-three/drei": "^10.0.0",

package/skills/game-design/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: game-design
+description: Design, audit, implement, and validate player experience, loops, systems, progression, and balance.
+---
+
+# Game design
+
+## Ownership
+
+Own the intended player experience and the rules that produce it: fantasy, pillars, verbs, decisions, feedback, loops, resources, progression, challenge, failure, onboarding, and social dynamics. Treat design claims as hypotheses proved by play, not a feature inventory or genre imitation — no genre kits, presets, or archetypes; every game is a custom composition of needs (see [AGENTS.md](../../../AGENTS.md)).
+
+Use `level-design` for spatial realization; route implementation to `jgengine-gameplay`, `jgengine-world`, `jgengine-combat`, `jgengine-ui`, `jgengine-multiplayer` once intent is coherent.
+
+Read [references/application-playbook.md](references/application-playbook.md) only when the task explicitly calls for design depth — a design brief, a redesign, or "make this fun/better" work; it is not a mandatory step of creating a game. Read [references/field-guide.md](references/field-guide.md) when the task needs deeper loop, economy, progression, genre, accessibility, or research guidance.
+
+## Choose the mode
+
+Greenfield: produce a vertical-slice contract (promise, pillars, core decision, loops, progression, failure/recovery) and build the smallest slice testing the riskiest assumption — see playbook §1. Existing game: reconstruct what it actually does from code and play, rank root problems by impact/confidence/reach/effort — see playbook §2.
+
+“Improve with game design” is an implementation request, not just an audit: select the highest-leverage intervention, implement it through shared engine seams, and prove the changed player behavior.
+
+## Required output contract
+
+Every design pass yields an observed journey, a north star (promise, pillars, anti-pillars, core decision), a loop/flow model, a ranked bottleneck list with cited evidence, an intervention stack, a chosen design slice, and acceptance evidence. See [references/application-playbook.md](references/application-playbook.md) for the full contract and execution rules (verb->feedback->consequence chains, loop/progression/challenge discipline, upstream ownership).
+
+## Completion
+
+An audit is not completion for a build/improve request. Finish when the slice is playable, a fresh player can state goal/choice/consequence, failure/recovery behave as intended, and evidence supports the pillars. Use `jgengine-verify` and `workflow` to ship.

package/skills/game-design/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Game Design"
+  short_description: "Design coherent game loops and systems"
+  default_prompt: "Use $game-design to audit or design this game, implement its highest-leverage design slice, and prove the changed player behavior."

package/skills/game-design/references/application-playbook.md

@@ -0,0 +1,170 @@
+# Applying game design
+
+Use this playbook to turn a pitch or an existing game into implemented, testable change. Its purpose is to prevent “design work” from ending as generic advice.
+
+## Contents
+
+1. Greenfield procedure
+2. Existing-game audit
+3. Mandatory models
+4. Ranking interventions
+5. Design-slice specification
+6. Implementation and proof
+7. Failure modes
+
+## 1. Greenfield procedure
+
+### Frame the bet
+
+Write a compact contract before broad code or content:
+
+| Field | Required form |
+| --- | --- |
+| audience/context | prior skills, player count, platform/input, session length, accessibility assumptions |
+| player promise | “The player repeatedly [verb/decision] so they feel [specific experience]” |
+| pillars | two or three observable behaviors or feelings |
+| anti-pillars | experiences the game must not drift toward |
+| core decision | situation, known information, viable options, tradeoff, consequence, recurrence |
+| completion proof | one end-to-end scenario a target player can perform and explain |
+| falsifier | observation that would show the design does not work |
+
+### Build the minimum design
+
+1. Model each core verb from cue through future consequence.
+2. Draw moment, encounter, session, and meta loops.
+3. Draw resources and feedback structures.
+4. Map player skills and progression channels.
+5. Define failure, recovery, stopping, and replay.
+6. Create a content grammar: a small set of mechanics crossed with contexts and constraints.
+7. Select the riskiest assumption and build one vertical design slice around it.
+
+Do not build the entire feature list first. A vertical slice contains real input, meaningful state, feedback, one decision that recurs, failure/recovery, and a downstream consequence.
+
+## 2. Existing-game audit
+
+### Reconstruct reality
+
+Inspect actual code, catalogs, scene documents, UI, tests, captures, and live play. Do not infer the game from its title or README.
+
+Trace four journeys when applicable:
+
+- **first minute:** first input, goal, threat, reward, confusion, and reason to continue
+- **first objective:** learning sequence, decisions, failure, recovery, payoff, and next goal
+- **representative session:** loop renewal, variety, resource pressure, build choices, pacing, and stopping point
+- **campaign/meta:** unlock cadence, content reuse, escalation, economy stability, mastery, and ending/replay
+
+For each journey, record timestamps or event order:
+
+`cue -> player belief -> action -> system response -> feedback -> state change -> next choice`
+
+Mark dead time, repeated decisions, forced actions, hidden consequences, false affordances, unexplained failure, and rewards that do not alter later play.
+
+### Build a system-coupling map
+
+Inventory verbs, enemies/problems, items/tools, progression, economy, quests/objectives, world states, social systems, and failure. For each system ask:
+
+- Which pillar does it serve?
+- Which loop consumes its output?
+- What player decision does it create or transform?
+- Where is it taught, tested, combined, and mastered?
+- What happens if it is removed?
+
+Flag systems that are present but disconnected, content whose only variation is numbers or nouns, and rewards that bypass the core play.
+
+### Diagnose decision density
+
+Do not maximize decisions per second. Find long spans where the player executes an already-solved action without new information, tradeoffs, expression, pressure, or mastery. Measure:
+
+- time to first meaningful decision
+- meaningful decisions per encounter/objective
+- time between new information and commitment
+- percentage of objectives using each verb or decision type
+- repeated content before context changes
+- time from failure to a useful retry
+
+## 3. Mandatory models
+
+### Loop table
+
+| Horizon | Cue/goal | Decision/action | Feedback | State changed | Why repeat? | Failure risk |
+| --- | --- | --- | --- | --- | --- | --- |
+
+Reject any row whose “state changed” or “why repeat” is empty.
+
+### Resource-flow table
+
+| Resource | Source | Store/cap | Spend/convert | Sink | Player decision | Feedback/runaway risk |
+| --- | --- | --- | --- | --- | --- | --- |
+
+Include time, health, space, information, attention, action opportunities, and social trust when relevant.
+
+### Progression table
+
+| Unlock/reward | Channel | New decision or capability | Content it recontextualizes | Risk of invalidation/grind | Proof |
+| --- | --- | --- | --- | --- | --- |
+
+Channels are mastery, access, breadth, power, and expression/status. Passive percentages without a changed decision must justify their place.
+
+### Objective/encounter variety matrix
+
+Cross objective verbs with information state, constraints, enemy/problem behavior, topology, resource pressure, failure condition, and consequence. This exposes campaigns where every mission is the same verb with different nouns.
+
+## 4. Ranking interventions
+
+Separate symptoms from root causes. “Quests are boring” is a symptom. “Every quest uses the same kill-count transition and no objective changes space, resources, or strategy” is a testable cause.
+
+Rank each candidate:
+
+| Candidate | Player behavior changed | Pillar impact | Reach | Evidence/confidence | Effort/risk | Dependencies | Shared owner |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+
+Use three horizons:
+
+- **Minimum correction:** remove the largest contradiction or unblock the loop.
+- **Strong target:** make one representative slice deliver the promise end to end.
+- **Multiplier:** expand the proven grammar across content, progression, social play, or replay.
+
+Choose by leverage, not novelty. Prefer a change that improves many encounters or future games over bespoke content with the same underlying decision.
+
+## 5. Design-slice specification
+
+The selected slice must state:
+
+- before behavior and evidence
+- target behavior and player belief
+- mechanics/dynamics expected to cause the change
+- objective/encounter sequence and pacing beats
+- resources, rewards, failure, recovery, and downstream consequence
+- affected catalogs/config, shared package seams, scene semantics, UI feedback, and tests
+- tuning variables with starting hypotheses and safe bounds
+- explicit non-goals and content held constant
+- acceptance scenario and falsifiers
+
+If another game could use the mechanic, define the package primitive first and adopt it here. Keep game-local code for content and feel.
+
+## 6. Implementation and proof
+
+When the user asks to build or improve:
+
+1. Implement the shared primitive or use an existing capability.
+2. Adopt it in one complete game slice.
+3. Author spatial content through `level-design` and the editor.
+4. Add deterministic tests for transitions, resources, failure, and progression.
+5. Exercise the observable scenario with representative input.
+6. Capture before/after evidence for behavior, not only appearance.
+7. Evaluate the falsifier honestly; revise or remove a failed intervention.
+
+Useful evidence includes time to first decision, objective completion, route choice, build choice, resource state, failure cause, retry time, objective-verb distribution, and a player’s ability to explain goal/action/consequence. Metrics need a named hypothesis; do not optimize them in isolation.
+
+## 7. Failure modes
+
+- producing a long GDD instead of a playable slice
+- listing features without naming changed decisions
+- adding content to a shallow objective grammar
+- using passive progression to disguise unchanged play
+- copying a genre’s surface without its causal dynamics
+- treating more rewards as more motivation
+- fixing comprehension only with text or HUD
+- reporting a diagnosis after the user asked for improvement
+- calling deterministic tests proof that the experience works
+- calling a prettier screenshot proof that the loop works