@jgengine/shell 0.9.0 → 0.10.0

package/dist/postfx/PostProcessing.js

@@ -0,0 +1,82 @@
+import { useFrame, useThree } from "@react-three/fiber";
+import { useEffect, useMemo } from "react";
+import * as THREE from "three";
+import { EffectComposer, RenderPass, UnrealBloomPass } from "three-stdlib";
+import { OutputPass } from "three/examples/jsm/postprocessing/OutputPass.js";
+import { GTAOPass } from "three/examples/jsm/postprocessing/GTAOPass.js";
+import { createGradePass } from "./gradeShader.js";
+const TONE_MAPPING = {
+    aces: THREE.ACESFilmicToneMapping,
+    agx: THREE.AgXToneMapping,
+    reinhard: THREE.ReinhardToneMapping,
+    cineon: THREE.CineonToneMapping,
+    linear: THREE.LinearToneMapping,
+    none: THREE.NoToneMapping,
+};
+/**
+ * Mounts an `EffectComposer` inside the shell Canvas and takes over rendering
+ * (priority-1 `useFrame`, which disables R3F auto-render) to run the configured
+ * post chain: RenderPass → GTAO → UnrealBloom → OutputPass → Grade. Rendered only
+ * when `PlayableGame.postProcessing` is set, so games without it draw unchanged.
+ */
+export function PostProcessing({ config }) {
+    const gl = useThree((s) => s.gl);
+    const scene = useThree((s) => s.scene);
+    const camera = useThree((s) => s.camera);
+    const size = useThree((s) => s.size);
+    const built = useMemo(() => {
+        const width = Math.max(1, size.width);
+        const height = Math.max(1, size.height);
+        const target = new THREE.WebGLRenderTarget(width, height, {
+            type: THREE.HalfFloatType,
+            samples: 2,
+        });
+        const composer = new EffectComposer(gl, target);
+        composer.addPass(new RenderPass(scene, camera));
+        if (config.ao !== undefined && config.ao !== false) {
+            const ao = new GTAOPass(scene, camera, width, height);
+            ao.blendIntensity = config.ao.blend ?? 1;
+            ao.updateGtaoMaterial({
+                radius: config.ao.radius ?? 1.8,
+                distanceExponent: 1,
+                thickness: config.ao.distanceFalloff ?? 3.6,
+                scale: config.ao.intensity ?? 2.4,
+                samples: 16,
+            });
+            composer.addPass(ao);
+        }
+        if (config.bloom !== false) {
+            const b = config.bloom ?? {};
+            composer.addPass(new UnrealBloomPass(new THREE.Vector2(width, height), b.strength ?? 0.32, b.radius ?? 0.55, b.threshold ?? 0.85));
+        }
+        composer.addPass(new OutputPass());
+        let grade = null;
+        if (config.grade !== false) {
+            grade = createGradePass(config.grade ?? {});
+            composer.addPass(grade);
+        }
+        return { composer, grade };
+    }, [gl, scene, camera, config, size.width, size.height]);
+    useEffect(() => {
+        const prevTone = gl.toneMapping;
+        const prevExposure = gl.toneMappingExposure;
+        gl.toneMapping = TONE_MAPPING[config.toneMapping ?? "aces"];
+        gl.toneMappingExposure = config.exposure ?? 1;
+        return () => {
+            gl.toneMapping = prevTone;
+            gl.toneMappingExposure = prevExposure;
+        };
+    }, [gl, config.toneMapping, config.exposure]);
+    useEffect(() => {
+        const { composer } = built;
+        composer.setPixelRatio(gl.getPixelRatio());
+        composer.setSize(size.width, size.height);
+        return () => composer.dispose();
+    }, [built, gl, size.width, size.height]);
+    useFrame((_, delta) => {
+        if (built.grade !== null)
+            built.grade.uniforms.uTime.value += delta;
+        built.composer.render(delta);
+    }, 1);
+    return null;
+}

package/dist/postfx/gradeShader.d.ts

@@ -0,0 +1,4 @@
+import { ShaderPass } from "three-stdlib";
+import type { GradeConfig } from "@jgengine/core/render/postProcessing";
+/** Build the display-space colour-grade pass (lift/gain/gamma, saturation, vignette, grain). Advance `uniforms.uTime.value` each frame to animate the grain. */
+export declare function createGradePass(config?: GradeConfig): ShaderPass;

package/dist/postfx/gradeShader.js

@@ -0,0 +1,64 @@
+import * as THREE from "three";
+import { ShaderPass } from "three-stdlib";
+const DEFAULT_LIFT = [0.012, 0.01, 0.018];
+const DEFAULT_GAIN = [1.05, 1.02, 0.98];
+const DEFAULT_GAMMA = 0.96;
+const DEFAULT_SATURATION = 1.12;
+const DEFAULT_VIGNETTE = 0.2;
+const DEFAULT_GRAIN = 0.012;
+const fragmentShader = /* glsl */ `
+  uniform sampler2D tDiffuse;
+  uniform vec3 uLift;
+  uniform vec3 uGain;
+  uniform float uGamma;
+  uniform float uSaturation;
+  uniform float uVignette;
+  uniform float uGrain;
+  uniform float uTime;
+  varying vec2 vUv;
+
+  float hash(vec2 p) {
+    return fract(sin(dot(p, vec2(12.9898, 78.233))) * 43758.5453);
+  }
+
+  void main() {
+    vec3 c = texture2D(tDiffuse, vUv).rgb;
+    c = c + uLift;
+    c = c * uGain;
+    c = pow(max(c, 0.0), vec3(uGamma));
+    float luma = dot(c, vec3(0.2126, 0.7152, 0.0722));
+    c = mix(vec3(luma), c, uSaturation);
+    vec2 d = vUv - 0.5;
+    float vig = 1.0 - uVignette * smoothstep(0.6, 0.95, dot(d, d) * 2.2);
+    c *= vig;
+    float g = (hash(vUv + fract(uTime)) - 0.5) * uGrain * 2.0;
+    c += g;
+    gl_FragColor = vec4(clamp(c, 0.0, 1.0), 1.0);
+  }
+`;
+const vertexShader = /* glsl */ `
+  varying vec2 vUv;
+  void main() {
+    vUv = uv;
+    gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
+  }
+`;
+/** Build the display-space colour-grade pass (lift/gain/gamma, saturation, vignette, grain). Advance `uniforms.uTime.value` each frame to animate the grain. */
+export function createGradePass(config = {}) {
+    const lift = config.lift ?? DEFAULT_LIFT;
+    const gain = config.gain ?? DEFAULT_GAIN;
+    return new ShaderPass({
+        uniforms: {
+            tDiffuse: { value: null },
+            uLift: { value: new THREE.Vector3(lift[0], lift[1], lift[2]) },
+            uGain: { value: new THREE.Vector3(gain[0], gain[1], gain[2]) },
+            uGamma: { value: config.gamma ?? DEFAULT_GAMMA },
+            uSaturation: { value: config.saturation ?? DEFAULT_SATURATION },
+            uVignette: { value: config.vignette ?? DEFAULT_VIGNETTE },
+            uGrain: { value: config.grain ?? DEFAULT_GRAIN },
+            uTime: { value: 0 },
+        },
+        vertexShader,
+        fragmentShader,
+    });
+}

package/dist/terrain/CarvedTerrain.d.ts

@@ -1,4 +1,5 @@
 import { type ThreeElements } from "@react-three/fiber";
+import * as THREE from "three";
 import type { TerrainField } from "@jgengine/core/world/terrain";
 import { type FieldGroundOptions } from "./terrainMath.js";
 export interface CarvedTerrainProps extends Omit<ThreeElements["mesh"], "args" | "children" | "geometry" | "material"> {
@@ -12,6 +13,8 @@ export interface CarvedTerrainProps extends Omit<ThreeElements["mesh"], "args" |
     paletteAt?: FieldGroundOptions["paletteAt"];
     roughness?: number;
     metalness?: number;
+    /** Override the default vertex-colour material (e.g. a procedural detail material). The caller owns its lifecycle; it is not disposed here. */
+    surfaceMaterial?: THREE.Material;
     /** Bump after a runtime carve/deposit to re-mesh the deformed surface. */
     epoch?: number;
 }
@@ -20,4 +23,4 @@ export interface CarvedTerrainProps extends Omit<ThreeElements["mesh"], "args" |
  * Because the geometry samples `field.sampleHeight`, a `CarvableField.carve(...)` shows as a real bowl
  * once `epoch` changes. Pair with `InstancedBodies` to see debris resting in the crater it blasted.
  */
-export declare function CarvedTerrain({ field, size, segments, center, colors, heightRange, paletteAt, roughness, metalness, receiveShadow, epoch, ...meshProps }: CarvedTerrainProps): import("react").JSX.Element;
+export declare function CarvedTerrain({ field, size, segments, center, colors, heightRange, paletteAt, roughness, metalness, surfaceMaterial, receiveShadow, epoch, ...meshProps }: CarvedTerrainProps): import("react").JSX.Element;

package/dist/terrain/CarvedTerrain.js

@@ -8,12 +8,13 @@ import { createFieldGroundGeometry } from "./terrainMath.js";
  * Because the geometry samples `field.sampleHeight`, a `CarvableField.carve(...)` shows as a real bowl
  * once `epoch` changes. Pair with `InstancedBodies` to see debris resting in the crater it blasted.
  */
-export function CarvedTerrain({ field, size, segments, center, colors, heightRange, paletteAt, roughness = 0.95, metalness = 0, receiveShadow = true, epoch = 0, ...meshProps }) {
+export function CarvedTerrain({ field, size, segments, center, colors, heightRange, paletteAt, roughness = 0.95, metalness = 0, surfaceMaterial, receiveShadow = true, epoch = 0, ...meshProps }) {
     const geometry = useMemo(() => createFieldGroundGeometry(field, { size, segments, center, colors, heightRange, paletteAt }), 
     // eslint-disable-next-line react-hooks/exhaustive-deps
     [field, size, segments, center, colors, heightRange, paletteAt, epoch]);
-    const material = useMemo(() => new THREE.MeshStandardMaterial({ color: "#ffffff", roughness, metalness, vertexColors: true }), [metalness, roughness]);
+    const defaultMaterial = useMemo(() => new THREE.MeshStandardMaterial({ color: "#ffffff", roughness, metalness, vertexColors: true }), [metalness, roughness]);
+    const material = surfaceMaterial ?? defaultMaterial;
     useEffect(() => () => geometry.dispose(), [geometry]);
-    useEffect(() => () => material.dispose(), [material]);
+    useEffect(() => () => defaultMaterial.dispose(), [defaultMaterial]);
     return _jsx("mesh", { ...meshProps, geometry: geometry, material: material, receiveShadow: receiveShadow });
 }

package/dist/terrain/terrainDetailMaterial.d.ts

@@ -0,0 +1,14 @@
+import * as THREE from "three";
+import type { ResolvedTerrainDetail } from "@jgengine/core/world/terrain";
+/** The built procedural detail terrain material, ready to mount on the ground mesh. */
+export interface TerrainDetailMaterialHandle {
+    material: THREE.MeshStandardMaterial;
+}
+/**
+ * A `MeshStandardMaterial` whose fragment shader keeps the biome-tinted vertex
+ * colour as the base ground and blends procedural, noise-broken rock (by slope),
+ * sand (by waterline), and snow (by height) over it — textured-reading terrain
+ * with no image assets. Full PBR: lit, shadowed, and fogged like any standard
+ * material, so it composes with the post-processing chain.
+ */
+export declare function createTerrainDetailMaterial(detail: ResolvedTerrainDetail): TerrainDetailMaterialHandle;

package/dist/terrain/terrainDetailMaterial.js

@@ -0,0 +1,90 @@
+import * as THREE from "three";
+const NOISE_GLSL = /* glsl */ `
+float jgHash(vec2 p){ return fract(sin(dot(p, vec2(127.1, 311.7))) * 43758.5453); }
+float jgVNoise(vec2 p){
+  vec2 i = floor(p); vec2 f = fract(p);
+  vec2 u = f * f * (3.0 - 2.0 * f);
+  float a = jgHash(i);
+  float b = jgHash(i + vec2(1.0, 0.0));
+  float c = jgHash(i + vec2(0.0, 1.0));
+  float d = jgHash(i + vec2(1.0, 1.0));
+  return mix(mix(a, b, u.x), mix(c, d, u.x), u.y);
+}
+float jgFbm(vec2 p){
+  float v = 0.0; float amp = 0.5;
+  for (int i = 0; i < 4; i++){ v += amp * jgVNoise(p); p *= 2.0; amp *= 0.5; }
+  return v;
+}
+`;
+/**
+ * A `MeshStandardMaterial` whose fragment shader keeps the biome-tinted vertex
+ * colour as the base ground and blends procedural, noise-broken rock (by slope),
+ * sand (by waterline), and snow (by height) over it — textured-reading terrain
+ * with no image assets. Full PBR: lit, shadowed, and fogged like any standard
+ * material, so it composes with the post-processing chain.
+ */
+export function createTerrainDetailMaterial(detail) {
+    const uniforms = {
+        uRockColor: { value: new THREE.Color(detail.rockColor) },
+        uSandColor: { value: new THREE.Color(detail.sandColor) },
+        uSnowColor: { value: new THREE.Color(detail.snowColor) },
+        uRockSlopeStart: { value: detail.rockSlopeStart },
+        uSnowHeight: { value: detail.snowHeight },
+        uWaterLevel: { value: detail.waterLevel },
+        uDetailScale: { value: Math.max(0.5, detail.detailScale) },
+        uMacroScale: { value: Math.max(0.5, detail.macroScale) },
+        uStrength: { value: detail.strength },
+    };
+    const material = new THREE.MeshStandardMaterial({
+        color: "#ffffff",
+        roughness: detail.roughness,
+        metalness: 0,
+        vertexColors: true,
+    });
+    material.onBeforeCompile = (shader) => {
+        Object.assign(shader.uniforms, uniforms);
+        shader.vertexShader = shader.vertexShader
+            .replace("#include <common>", `#include <common>
+varying vec3 vJgWorldPos;
+varying vec3 vJgWorldNormal;`)
+            .replace("#include <beginnormal_vertex>", `#include <beginnormal_vertex>
+vJgWorldNormal = normalize(mat3(modelMatrix) * objectNormal);`)
+            .replace("#include <begin_vertex>", `#include <begin_vertex>
+vJgWorldPos = (modelMatrix * vec4(transformed, 1.0)).xyz;`);
+        shader.fragmentShader = shader.fragmentShader
+            .replace("#include <common>", `#include <common>
+varying vec3 vJgWorldPos;
+varying vec3 vJgWorldNormal;
+uniform vec3 uRockColor;
+uniform vec3 uSandColor;
+uniform vec3 uSnowColor;
+uniform float uRockSlopeStart;
+uniform float uSnowHeight;
+uniform float uWaterLevel;
+uniform float uDetailScale;
+uniform float uMacroScale;
+uniform float uStrength;
+${NOISE_GLSL}`)
+            .replace("#include <color_fragment>", `#include <color_fragment>
+vec2 jgWp = vJgWorldPos.xz;
+float jgFine = jgFbm(jgWp / uDetailScale);
+float jgMacro = jgFbm(jgWp / uMacroScale);
+float jgSlope = 1.0 - clamp(vJgWorldNormal.y, 0.0, 1.0);
+float jgH = vJgWorldPos.y;
+vec3 jgBase = diffuseColor.rgb;
+jgBase *= mix(1.0 - 0.22 * uStrength, 1.0 + 0.18 * uStrength, jgFine);
+jgBase = mix(jgBase, jgBase * vec3(0.86, 0.9, 0.82), jgMacro * 0.25 * uStrength);
+vec3 jgRock = uRockColor * mix(0.72, 1.15, jgFbm(jgWp / (uDetailScale * 1.7)));
+float jgRockW = smoothstep(uRockSlopeStart, uRockSlopeStart + 0.18, jgSlope) * uStrength;
+vec3 jgCol = mix(jgBase, jgRock, jgRockW);
+vec3 jgSand = uSandColor * mix(0.9, 1.08, jgFine);
+float jgSandW = smoothstep(uWaterLevel + 2.4, uWaterLevel - 0.4, jgH) * (1.0 - jgRockW) * uStrength;
+jgCol = mix(jgCol, jgSand, jgSandW);
+vec3 jgSnow = uSnowColor * mix(0.94, 1.04, jgFine);
+float jgSnowW = smoothstep(uSnowHeight, uSnowHeight + 8.0, jgH) * (1.0 - jgRockW * 0.6) * uStrength;
+jgCol = mix(jgCol, jgSnow, jgSnowW);
+diffuseColor.rgb = jgCol;`);
+    };
+    material.customProgramCacheKey = () => `jgengine-terrain-detail-${detail.rockSlopeStart}-${detail.snowHeight}`;
+    return { material };
+}

package/dist/touch/TouchControlsOverlay.js

@@ -4,6 +4,10 @@ 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";
+import { useRegisterLayoutRegion } from "@jgengine/react/gameViewport";
+const MOVEMENT_ZONE = { id: "control:movement", kind: "control", collisionPolicy: "forbid", collisionGroup: "touch-dock" };
+const ACTIONS_ZONE = { id: "control:actions", kind: "control", collisionPolicy: "forbid", collisionGroup: "touch-dock" };
+const UTILITY_ZONE = { id: "control:utility", kind: "control", collisionPolicy: "warn", collisionGroup: "touch-dock" };
 const JOYSTICK_SIZE = 132;
 const JOYSTICK_THUMB = 52;
 const JOYSTICK_DEADZONE = 0.28;
@@ -275,5 +279,11 @@ function PrimaryButtonCluster({ buttons, sink, scale = 1 }) {
 export function TouchControlsDock({ scheme, sink, scale = 1 }) {
     const primary = scheme.buttons.filter((button) => button.kind !== "utility");
     const utility = scheme.buttons.filter((button) => button.kind === "utility");
-    return (_jsxs("div", { className: "pointer-events-none absolute inset-x-0 bottom-0 z-40", style: { paddingBottom: `calc(env(safe-area-inset-bottom, 0px) + ${DOCK_BASE_PADDING}px)` }, children: [_jsxs("div", { className: "flex items-end justify-between gap-4 px-5", children: [_jsx("div", { children: scheme.joystick !== null ? _jsx(VirtualJoystick, { joystick: scheme.joystick, sink: sink, scale: scale }) : null }), _jsx(PrimaryButtonCluster, { buttons: primary, sink: sink, scale: scale })] }), utility.length > 0 ? (_jsx("div", { className: "pointer-events-none absolute inset-x-0 flex justify-center gap-2", style: { bottom: "calc(env(safe-area-inset-bottom, 0px) + 8px)" }, children: utility.map((button) => (_jsx(TouchUtilityChip, { button: button, sink: sink }, button.action))) })) : null] }));
+    const joystickRef = useRef(null);
+    const actionsRef = useRef(null);
+    const utilityRef = useRef(null);
+    useRegisterLayoutRegion(MOVEMENT_ZONE, joystickRef, scheme.joystick !== null);
+    useRegisterLayoutRegion(ACTIONS_ZONE, actionsRef, primary.length > 0);
+    useRegisterLayoutRegion(UTILITY_ZONE, utilityRef, utility.length > 0);
+    return (_jsxs("div", { className: "pointer-events-none absolute inset-x-0 bottom-0 z-40", style: { paddingBottom: `calc(env(safe-area-inset-bottom, 0px) + ${DOCK_BASE_PADDING}px)` }, children: [_jsxs("div", { className: "flex items-end justify-between gap-4 px-5", children: [_jsx("div", { ref: joystickRef, children: scheme.joystick !== null ? _jsx(VirtualJoystick, { joystick: scheme.joystick, sink: sink, scale: scale }) : null }), _jsx("div", { ref: actionsRef, children: _jsx(PrimaryButtonCluster, { buttons: primary, sink: sink, scale: scale }) })] }), utility.length > 0 ? (_jsx("div", { className: "pointer-events-none absolute inset-x-0 flex justify-center", style: { bottom: "calc(env(safe-area-inset-bottom, 0px) + 8px)" }, children: _jsx("div", { ref: utilityRef, className: "flex gap-2", children: utility.map((button) => (_jsx(TouchUtilityChip, { button: button, sink: sink }, button.action))) }) })) : null] }));
 }

package/dist/world/WorldHud.d.ts

@@ -3,11 +3,13 @@ import type { CatalogEntityRole } from "@jgengine/core/runtime/gameContext";
 export type { WorldBarSample } from "./worldBarSamples.js";
 export { collectWorldBarSamples, paintWorldBarSamples } from "./worldBarSamples.js";
 export { telegraphPulseOpacity } from "./telegraphPulse.js";
-export declare function WorldEntityBars({ statId, height, roles, resolveRole, }: {
+export declare function WorldEntityBars({ statId, height, roles, resolveRole, maxDistance, }: {
     statId: string;
     height?: number;
     roles?: readonly CatalogEntityRole[];
     resolveRole?: (entity: SceneEntity) => CatalogEntityRole | undefined;
+    /** Hide bars for entities farther than this from the player (world units). Default 60. */
+    maxDistance?: number;
 }): import("react").JSX.Element;
 export declare function WorldFloatText({ height, lifeMs }: {
     height?: number;

package/dist/world/WorldHud.js

@@ -5,16 +5,16 @@ import { useEffect, useMemo, useRef, useState } from "react";
 import * as THREE from "three";
 import { useGameContext } from "@jgengine/react/provider";
 import { useCameraShake } from "../camera/shakeChannel.js";
+import { readFirstPersonMuzzle } from "../camera/GameFirstPersonCamera.js";
 import { resolveFloatTextStyle } from "./floatTextStyle.js";
 import { collectWorldBarSamples, paintWorldBarSamples, } from "./worldBarSamples.js";
 import { telegraphPulseOpacity } from "./telegraphPulse.js";
 export { collectWorldBarSamples, paintWorldBarSamples } from "./worldBarSamples.js";
 export { telegraphPulseOpacity } from "./telegraphPulse.js";
-const MUZZLE_HEIGHT = 1.4;
 function pinOverlayToViewport(_el, _camera, size) {
     return [size.width / 2, size.height / 2];
 }
-export function WorldEntityBars({ statId, height = 2.2, roles, resolveRole, }) {
+export function WorldEntityBars({ statId, height = 2.2, roles, resolveRole, maxDistance = 60, }) {
     const ctx = useGameContext();
     const camera = useThree((state) => state.camera);
     const size = useThree((state) => state.size);
@@ -36,7 +36,7 @@ export function WorldEntityBars({ statId, height = 2.2, roles, resolveRole, }) {
             canvas.height = pixelH;
         }
         camera.updateMatrixWorld();
-        collectWorldBarSamples(ctx, statId, height, roles, resolveRole, camera, { width: cssW, height: cssH }, samplesRef.current, projectRef.current);
+        collectWorldBarSamples(ctx, statId, height, roles, resolveRole, camera, { width: cssW, height: cssH }, samplesRef.current, projectRef.current, maxDistance);
         paintWorldBarSamples(canvas, samplesRef.current, dpr);
     });
     return (_jsx(Html, { fullscreen: true, calculatePosition: pinOverlayToViewport, zIndexRange: [20, 0], style: { pointerEvents: "none" }, children: _jsx("canvas", { ref: canvasRef, style: { width: "100%", height: "100%", display: "block", pointerEvents: "none" } }) }));
@@ -157,14 +157,14 @@ export function ProjectileTracers({ lifeMs = 130 }) {
     useEffect(() => {
         const unsub = ctx.game.events.on("projectile.settled", (event) => {
             const id = nextId.current++;
+            const start = new THREE.Vector3(event.origin[0], event.origin[1], event.origin[2]);
+            if (event.from === ctx.player.userId)
+                readFirstPersonMuzzle(start);
             setTracers((current) => [
                 ...current,
                 {
                     id,
-                    points: [
-                        new THREE.Vector3(event.origin[0], event.origin[1] + MUZZLE_HEIGHT, event.origin[2]),
-                        new THREE.Vector3(event.at[0], event.at[1], event.at[2]),
-                    ],
+                    points: [start, new THREE.Vector3(event.at[0], event.at[1], event.at[2])],
                 },
             ]);
             const handle = setTimeout(() => {

package/dist/world/worldBarSamples.d.ts

@@ -22,7 +22,7 @@ export declare function collectWorldBarSamples(ctx: GameContext, statId: string,
 }, viewport: {
     width: number;
     height: number;
-}, into: WorldBarSample[], project: Projectable): number;
+}, into: WorldBarSample[], project: Projectable, maxDistance?: number): number;
 export declare function paintWorldBarSamples(canvas: {
     width: number;
     height: number;

package/dist/world/worldBarSamples.js

@@ -1,12 +1,18 @@
 import { worldHealthBarAllowsRole } from "@jgengine/core/game/playableGame";
-export function collectWorldBarSamples(ctx, statId, height, roles, resolveRole, camera, viewport, into, project) {
+export function collectWorldBarSamples(ctx, statId, height, roles, resolveRole, camera, viewport, into, project, maxDistance = 60) {
     into.length = 0;
     const playerId = ctx.player.userId;
+    const player = ctx.scene.entity.get(playerId);
     for (const entity of ctx.scene.entity.list()) {
         if (entity.id === playerId)
             continue;
         if (!worldHealthBarAllowsRole(roles, resolveRole?.(entity)))
             continue;
+        if (player !== null &&
+            Math.hypot(entity.position[0] - player.position[0], entity.position[2] - player.position[2]) >
+                maxDistance) {
+            continue;
+        }
         const stat = ctx.scene.entity.stats.get(entity.id, statId);
         if (stat === null)
             continue;

package/dist/worldSync.d.ts

@@ -0,0 +1,10 @@
+import type { GameContext } from "@jgengine/core/runtime/gameContext";
+import type { GameRuntimeFeeds } from "@jgengine/core/runtime/transport";
+/**
+ * Client half of host-authoritative play: subscribe to the server-state channel and mirror each authoritative
+ * `WorldSnapshot` (carried in `serverState`) into the local `ctx`, so the game renders the host's world instead
+ * of a locally-simulated one. Pure and transport-agnostic — the backend's `feeds.subscribeServer` is the only
+ * dependency; returns the unsubscribe. The shell attaches this (and gates its local sim) when the game's adapter
+ * opts into `authority: "server"`.
+ */
+export declare function attachWorldSync(feeds: Pick<GameRuntimeFeeds, "subscribeServer">, serverId: string, ctx: Pick<GameContext, "hydrate">): () => void;

package/dist/worldSync.js

@@ -0,0 +1,19 @@
+import { createWorldMirror } from "@jgengine/core/runtime/worldMirror";
+/**
+ * Client half of host-authoritative play: subscribe to the server-state channel and mirror each authoritative
+ * `WorldSnapshot` (carried in `serverState`) into the local `ctx`, so the game renders the host's world instead
+ * of a locally-simulated one. Pure and transport-agnostic — the backend's `feeds.subscribeServer` is the only
+ * dependency; returns the unsubscribe. The shell attaches this (and gates its local sim) when the game's adapter
+ * opts into `authority: "server"`.
+ */
+export function attachWorldSync(feeds, serverId, ctx) {
+    const mirror = createWorldMirror(ctx);
+    return feeds.subscribeServer(serverId, (view) => {
+        if (view === null)
+            return;
+        const snapshot = view.serverState;
+        if (snapshot === null || snapshot === undefined)
+            return;
+        mirror.applyBaseline(view.revision, snapshot);
+    });
+}