@jgengine/shell 0.13.0 → 0.15.0-next.0

package/dist/terrain/ProceduralGround.js

@@ -1,17 +1,15 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import {} from "@react-three/fiber";
-import { useEffect, useMemo } from "react";
 import * as THREE from "three";
+import { useDisposable } from "../render/useDisposable.js";
 import { createProceduralGroundGeometry } from "./terrainMath.js";
 export function ProceduralGround({ terrain, colors, roughness = 0.94, metalness = 0, receiveShadow = true, ...meshProps }) {
-    const geometry = useMemo(() => createProceduralGroundGeometry(terrain, colors), [colors, terrain]);
-    const material = useMemo(() => new THREE.MeshStandardMaterial({
+    const geometry = useDisposable(() => createProceduralGroundGeometry(terrain, colors), [colors, terrain]);
+    const material = useDisposable(() => new THREE.MeshStandardMaterial({
         color: "#ffffff",
         roughness,
         metalness,
         vertexColors: true,
     }), [metalness, roughness]);
-    useEffect(() => () => geometry.dispose(), [geometry]);
-    useEffect(() => () => material.dispose(), [material]);
     return _jsx("mesh", { ...meshProps, geometry: geometry, material: material, receiveShadow: receiveShadow });
 }

package/dist/terrain/grassMaterial.d.ts

@@ -5,6 +5,12 @@ export interface GrassWindOptions {
     speed?: number;
     gustScale?: number;
     flutter?: number;
+    /**
+     * Layered rolling gust field: three phase-offset directional waves (one carrying a cross-wind
+     * component) instead of a single sine, so visible wave fronts sweep the meadow. Default true.
+     * `false` restores the single-sine gust. Compile-time variation — folded into the program cache key.
+     */
+    layered?: boolean;
 }
 /** Camera-distance fade band: tufts thin out between `start` and `end` meters, so the instance budget spends where the camera lives. */
 export interface GrassDistanceFadeOptions {
@@ -18,7 +24,7 @@ export interface GrassMaterialOptions {
     colorGround?: THREE.ColorRepresentation;
     colorVariation?: number;
     wind?: GrassWindOptions | false;
-    /** Distance thinning; `false` disables. Default fades between 35 m and 95 m. */
+    /** Distance thinning; `false` disables. Default fades between 55 m and 150 m so meadows read expansive. */
     distanceFade?: GrassDistanceFadeOptions | false;
     /** 0..1 blend of blade normals toward straight-up — lit like a soft carpet instead of dark individual planes. Default 0.6. */
     normalLift?: number;
@@ -43,7 +49,7 @@ export interface GrassMaterialHandle {
     uniforms: GrassShaderUniforms;
 }
 export declare const DEFAULT_GRASS_WIND: Required<GrassWindOptions>;
-/** Default camera-distance fade band: tufts start thinning at 35 m and are gone by 95 m. */
+/** Default camera-distance fade band: tufts start thinning at 55 m and are gone by 150 m so the meadow reads deep. */
 export declare const DEFAULT_GRASS_DISTANCE_FADE: Required<GrassDistanceFadeOptions>;
 /** @internal */
 export declare function resolveGrassWind(wind: GrassWindOptions | false | undefined): Required<GrassWindOptions>;

package/dist/terrain/grassMaterial.js

@@ -5,11 +5,12 @@ export const DEFAULT_GRASS_WIND = {
     speed: 1.6,
     gustScale: 0.16,
     flutter: 0.08,
+    layered: true,
 };
-/** Default camera-distance fade band: tufts start thinning at 35 m and are gone by 95 m. */
+/** Default camera-distance fade band: tufts start thinning at 55 m and are gone by 150 m so the meadow reads deep. */
 export const DEFAULT_GRASS_DISTANCE_FADE = {
-    start: 35,
-    end: 95,
+    start: 55,
+    end: 150,
 };
 function normalizeWindDirection(direction) {
     const vector = new THREE.Vector2(direction[0], direction[1]);
@@ -25,6 +26,7 @@ export function resolveGrassWind(wind) {
         speed: wind?.speed ?? DEFAULT_GRASS_WIND.speed,
         gustScale: wind?.gustScale ?? DEFAULT_GRASS_WIND.gustScale,
         flutter: wind?.flutter ?? DEFAULT_GRASS_WIND.flutter,
+        layered: wind?.layered ?? DEFAULT_GRASS_WIND.layered,
     };
 }
 /** @internal */
@@ -122,7 +124,15 @@ void jgComputeGrassBlade() {
   float st = sin(instanceYaw);
   vec3 tuftOffset = vec3(bladeOffset.x * ct + bladeOffset.y * st, 0.0, -bladeOffset.x * st + bladeOffset.y * ct);
   float gustPhase = dot(instanceOffset.xz, uWindDirection) * uWindGustScale + uTime * uWindSpeed + instancePhase;
-  float gust = sin(gustPhase) * 0.7 + sin(gustPhase * 0.43 + 2.4) * 0.3;
+${wind.layered
+            ? `  // Layered rolling gust field: three phase-offset directional waves, one carrying a cross-wind
+  // term, so coherent wave fronts sweep across the meadow instead of every tuft waving in place.
+  vec2 windPerp = vec2(-uWindDirection.y, uWindDirection.x);
+  float crossPhase = dot(instanceOffset.xz, windPerp) * uWindGustScale * 0.6;
+  float gust = sin(gustPhase) * 0.55
+    + sin(gustPhase * 0.53 + crossPhase + 2.1) * 0.32
+    + sin(gustPhase * 1.7 + crossPhase * 0.4 + 4.3) * 0.13;`
+            : `  float gust = sin(gustPhase) * 0.7 + sin(gustPhase * 0.43 + 2.4) * 0.3;`}
   float flutter = sin(uTime * 7.5 + instancePhase * 2.7 + bladeVary.w * 6.2832) * uWindFlutter;
   vec2 windOffset = uWindDirection * (gust * uWindStrength + flutter) * t * t * (0.4 + 0.6 * bladeVary.y);
   jgGrassPosition = instanceOffset + tuftOffset + yawedPosition + vec3(windOffset.x, 0.0, windOffset.y);
@@ -156,8 +166,17 @@ grassColor *= mix(1.0 - uColorVariation, 1.0 + uColorVariation, vGrassColorMix);
 grassColor = mix(uColorGround, grassColor, smoothstep(0.0, 0.55, vGrassBladeT));
 grassColor = mix(grassColor, uColorGround * 1.04, vGrassFade * 0.6);
 diffuseColor.rgb = grassColor;
+`)
+            .replace("#include <lights_fragment_end>", `
+#include <lights_fragment_end>
+// Warm tip sheen / backscatter: blade tips lift toward a warm glow, scaled by how strongly the
+// fragment is directly lit — a cheap stand-in for sun shining through the canopy, no extra lights.
+float jgTipMask = smoothstep(0.55, 1.0, vGrassBladeT);
+float jgLit = clamp(dot(reflectedLight.directDiffuse, vec3(0.3333)) * 1.6, 0.0, 1.0);
+reflectedLight.directDiffuse += vec3(0.34, 0.28, 0.12) * jgTipMask * jgLit * (1.0 - vGrassFade * 0.7);
 `);
     };
-    material.customProgramCacheKey = () => `jgengine-grass-${wind.strength}-${wind.flutter}`;
+    // Only the layered-gust branch changes the compiled shader source, so it is the sole compile-time key.
+    material.customProgramCacheKey = () => `jgengine-grass-${wind.layered ? "layered" : "single"}`;
     return { material, uniforms };
 }

package/dist/terrain/index.d.ts

@@ -7,5 +7,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, normalizeHeightBlend, 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 TerrainSurfaceColorOptions, 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/terrainDetailMaterial.js

@@ -43,6 +43,7 @@ export function createTerrainDetailMaterial(detail, textures) {
     const hasTexture = textures !== undefined && detail.material !== undefined;
     const repeat = detail.material?.repeat ?? 4;
     const strength = detail.material?.strength ?? 1;
+    const tint = detail.material?.tint ?? 1;
     const uniforms = {
         uRockColor: { value: new THREE.Color(detail.rockColor) },
         uSandColor: { value: new THREE.Color(detail.sandColor) },
@@ -61,6 +62,7 @@ export function createTerrainDetailMaterial(detail, textures) {
                 uMatAo: { value: textures.ao },
                 uMatRepeat: { value: Math.max(0.01, repeat) },
                 uMatStrength: { value: strength },
+                uMatTint: { value: tint },
             }
             : {}),
     };
@@ -87,13 +89,20 @@ uniform sampler2D uMatNormal;
 uniform sampler2D uMatRoughness;
 uniform sampler2D uMatAo;
 uniform float uMatRepeat;
-uniform float uMatStrength;`
+uniform float uMatStrength;
+uniform float uMatTint;`
             : "";
         const materialColorGlsl = hasTexture
             ? `
 vec2 jgMatUv = jgWp / uMatRepeat;
 vec3 jgMatColor = texture2D(uMatColor, jgMatUv).rgb;
-jgCol = mix(jgCol, jgMatColor, uMatStrength);`
+// Two separable jobs. GRAIN: the map's luminance relative to its own mid-grey shades the authored
+// colour, which is what makes ground read as a surface. TINT: how much of the map's own hue
+// replaces that colour — at 1 the biome palette, macro sweeps, and slope rock underneath are simply
+// painted over, and a whole region collapses to the texture's single hue.
+float jgMatLum = dot(jgMatColor, vec3(0.2126, 0.7152, 0.0722));
+jgCol *= mix(1.0, clamp(jgMatLum / 0.35, 0.55, 1.7), uMatStrength * (1.0 - uMatTint));
+jgCol = mix(jgCol, jgMatColor, uMatStrength * uMatTint);`
             : "";
         const materialRoughnessGlsl = hasTexture
             ? `

package/dist/terrain/terrainMath.d.ts

@@ -27,6 +27,35 @@ export interface TerrainVertexColorOptions {
     waterline?: THREE.ColorRepresentation;
     waterlineHeight?: number;
 }
+/**
+ * Slope/noise surface shading laid over the height lerp so untextured ground reads like terrain
+ * instead of a smooth two-tone gradient. All knobs are optional with sane defaults; every field is
+ * a pure function of vertex position (+ `seed`), so the coloring is stable across rebuilds and tests.
+ */
+export interface TerrainSurfaceColorOptions {
+    /** 0..1 darkening + desaturation on steep faces (slope sampled from neighbor heights). Default 0.5; 0 disables. */
+    slopeStrength?: number;
+    /** 0..1 amplitude of deterministic hash mottling (brightness jitter per patch). Default 0.14; 0 disables. */
+    mottleStrength?: number;
+    /** World-space frequency of the mottling lattice (cells per meter). Default 0.12. */
+    mottleScale?: number;
+    /** Seed for the mottling hash. Same seed → identical mottling. Default 1. */
+    seed?: TerrainSeed;
+}
+interface ResolvedTerrainSurfaceColorOptions {
+    slopeStrength: number;
+    mottleStrength: number;
+    mottleScale: number;
+    seed: TerrainSeed;
+}
+/** @internal */
+export declare const DEFAULT_TERRAIN_SURFACE_COLOR: ResolvedTerrainSurfaceColorOptions;
+/**
+ * Layer the slope darkening and hash mottling onto an already height-lerped vertex color, in place.
+ * `slope01` is the 0..1 steepness at the vertex; `x,z` seed the deterministic mottling.
+ * @internal
+ */
+export declare function applyTerrainSurfaceShading(color: THREE.Color, x: number, z: number, slope01: number, surface: ResolvedTerrainSurfaceColorOptions): void;
 /** @internal */
 export declare function normalizeHeightBlend(height: number, minHeight: number, maxHeight: number): number;
 /** @internal */
@@ -51,6 +80,8 @@ export interface FieldGroundOptions {
     heightRange?: readonly [min: number, max: number];
     /** Sampled per vertex when set; `colors` still supplies `waterlineHeight` and the fallback. */
     paletteAt?: TerrainPaletteSampler;
+    /** Slope/noise surface shading over the height lerp. Omit for the default terrain look; pass `{ slopeStrength: 0, mottleStrength: 0 }` for a flat gradient. */
+    surface?: TerrainSurfaceColorOptions;
 }
 /**
  * Mesh any `TerrainField` — including a `CarvableField` with craters/mounds written into it — into a
@@ -59,5 +90,11 @@ export interface FieldGroundOptions {
   * @internal
   */
 export declare function createFieldGroundGeometry(field: TerrainField, options?: FieldGroundOptions): THREE.BufferGeometry;
-/** @internal */
+/**
+ * Meshes the built-in procedural noise terrain into a vertex-coloured ground. A thin wrapper over the
+ * shared {@link buildGroundGeometry}: same height lerp, plus slope-aware shading and hash mottling
+ * seeded from `config.seed` so the plain ground reads like terrain rather than a two-tone gradient.
+ * @internal
+ */
 export declare function createProceduralGroundGeometry(config?: ProceduralTerrainConfig, colors?: TerrainVertexColorOptions): THREE.BufferGeometry;
+export {};

package/dist/terrain/terrainMath.js

@@ -1,6 +1,62 @@
 import { noiseField } from "@jgengine/core/world/terrain";
 import * as THREE from "three";
-import {} from "./random.js";
+import { hashNoise2 } from "./random.js";
+/** @internal */
+export const DEFAULT_TERRAIN_SURFACE_COLOR = {
+    slopeStrength: 0.5,
+    mottleStrength: 0.14,
+    mottleScale: 0.12,
+    seed: 1,
+};
+function resolveSurfaceColor(surface) {
+    return {
+        slopeStrength: THREE.MathUtils.clamp(surface?.slopeStrength ?? DEFAULT_TERRAIN_SURFACE_COLOR.slopeStrength, 0, 1),
+        mottleStrength: THREE.MathUtils.clamp(surface?.mottleStrength ?? DEFAULT_TERRAIN_SURFACE_COLOR.mottleStrength, 0, 1),
+        mottleScale: Math.max(0, surface?.mottleScale ?? DEFAULT_TERRAIN_SURFACE_COLOR.mottleScale),
+        seed: surface?.seed ?? DEFAULT_TERRAIN_SURFACE_COLOR.seed,
+    };
+}
+/** Smoothed value noise on the integer hash lattice — continuous, seamless, and a pure function of `x,z`. */
+function groundValueNoise(x, z, scale, seed) {
+    const sx = x * scale;
+    const sz = z * scale;
+    const xi = Math.floor(sx);
+    const zi = Math.floor(sz);
+    const xf = sx - xi;
+    const zf = sz - zi;
+    const u = xf * xf * (3 - 2 * xf);
+    const w = zf * zf * (3 - 2 * zf);
+    const n00 = hashNoise2(xi, zi, seed);
+    const n10 = hashNoise2(xi + 1, zi, seed);
+    const n01 = hashNoise2(xi, zi + 1, seed);
+    const n11 = hashNoise2(xi + 1, zi + 1, seed);
+    const nx0 = n00 + (n10 - n00) * u;
+    const nx1 = n01 + (n11 - n01) * u;
+    return nx0 + (nx1 - nx0) * w;
+}
+/**
+ * Layer the slope darkening and hash mottling onto an already height-lerped vertex color, in place.
+ * `slope01` is the 0..1 steepness at the vertex; `x,z` seed the deterministic mottling.
+ * @internal
+ */
+export function applyTerrainSurfaceShading(color, x, z, slope01, surface) {
+    if (surface.mottleStrength > 0 && surface.mottleScale > 0) {
+        // Two octaves: broad patchiness plus a finer break-up. Centered on 0.5 so it only jitters brightness.
+        const broad = groundValueNoise(x, z, surface.mottleScale, surface.seed);
+        const fine = groundValueNoise(x + 41.7, z - 19.3, surface.mottleScale * 3.1, surface.seed);
+        const mottle = broad * 0.65 + fine * 0.35;
+        color.multiplyScalar(1 + (mottle - 0.5) * 2 * surface.mottleStrength);
+    }
+    if (surface.slopeStrength > 0 && slope01 > 0) {
+        // Steep faces read as exposed earth: pull toward luminance (desaturate) then darken.
+        const slopeK = THREE.MathUtils.clamp(slope01 * surface.slopeStrength, 0, 1);
+        const lum = color.r * 0.299 + color.g * 0.587 + color.b * 0.114;
+        color.r = THREE.MathUtils.lerp(color.r, lum, slopeK * 0.5);
+        color.g = THREE.MathUtils.lerp(color.g, lum, slopeK * 0.5);
+        color.b = THREE.MathUtils.lerp(color.b, lum, slopeK * 0.5);
+        color.multiplyScalar(1 - 0.4 * slopeK);
+    }
+}
 /** @internal */
 export function normalizeHeightBlend(height, minHeight, maxHeight) {
     const range = maxHeight - minHeight;
@@ -49,11 +105,17 @@ export function createFieldGroundGeometry(field, options = {}) {
         center: [cx, cz],
         heightRange: options.heightRange,
         paletteAt: options.paletteAt,
+        surface: options.surface,
     });
 }
 function buildGroundGeometry(size, segments, sampler, opts) {
     const colors = opts.colors;
     const paletteAt = opts.paletteAt;
+    const surface = resolveSurfaceColor(opts.surface);
+    const shadeSlope = surface.slopeStrength > 0;
+    // Neighbor spacing for the finite-difference slope estimate — one grid cell per axis.
+    const slopeStepX = shadeSlope ? Math.max(1e-3, size.width / Math.max(1, segments.x)) : 0;
+    const slopeStepZ = shadeSlope ? Math.max(1e-3, size.depth / Math.max(1, segments.z)) : 0;
     const vertexCountX = segments.x + 1;
     const vertexCountZ = segments.z + 1;
     const positions = new Float32Array(vertexCountX * vertexCountZ * 3);
@@ -91,6 +153,15 @@ function buildGroundGeometry(size, segments, sampler, opts) {
             const color = low.clone().lerp(high, blend);
             if (waterline !== null && y <= (colors.waterlineHeight ?? 0))
                 color.lerp(waterline, 0.65);
+            let slope01 = 0;
+            if (shadeSlope) {
+                // Bounded per-vertex finite difference (4 extra samples) — build-time only, no per-frame scan.
+                const dhx = (sampler(x + slopeStepX, z) - sampler(x - slopeStepX, z)) / (2 * slopeStepX);
+                const dhz = (sampler(x, z + slopeStepZ) - sampler(x, z - slopeStepZ)) / (2 * slopeStepZ);
+                const grad = Math.hypot(dhx, dhz);
+                slope01 = grad / (grad + 1);
+            }
+            applyTerrainSurfaceShading(color, x, z, slope01, surface);
             colorValues[colorIndex] = color.r;
             colorValues[colorIndex + 1] = color.g;
             colorValues[colorIndex + 2] = color.b;
@@ -124,71 +195,22 @@ function buildGroundGeometry(size, segments, sampler, opts) {
     geometry.computeBoundingSphere();
     return geometry;
 }
-/** @internal */
+/**
+ * Meshes the built-in procedural noise terrain into a vertex-coloured ground. A thin wrapper over the
+ * shared {@link buildGroundGeometry}: same height lerp, plus slope-aware shading and hash mottling
+ * seeded from `config.seed` so the plain ground reads like terrain rather than a two-tone gradient.
+ * @internal
+ */
 export function createProceduralGroundGeometry(config = {}, colors = {}) {
     const size = resolveTerrainSize(config.size);
     const segments = resolveTerrainSegments(config.segments);
     const sampler = createProceduralTerrainSampler(config);
-    const vertexCountX = segments.x + 1;
-    const vertexCountZ = segments.z + 1;
-    const positions = new Float32Array(vertexCountX * vertexCountZ * 3);
-    const uvs = new Float32Array(vertexCountX * vertexCountZ * 2);
-    const colorValues = new Float32Array(vertexCountX * vertexCountZ * 3);
-    const indices = new Uint32Array(segments.x * segments.z * 6);
-    const low = new THREE.Color(colors.low ?? "#30402c");
-    const high = new THREE.Color(colors.high ?? "#7f8b50");
-    const waterline = colors.waterline === undefined ? null : new THREE.Color(colors.waterline);
-    const minHeight = (config.baseOffset ?? 0) - (config.height ?? 1.4) * 1.2;
-    const maxHeight = (config.baseOffset ?? 0) + (config.height ?? 1.4) * 1.2;
-    let index = 0;
-    let uvIndex = 0;
-    let colorIndex = 0;
-    for (let zIndex = 0; zIndex < vertexCountZ; zIndex += 1) {
-        const v = zIndex / segments.z;
-        const z = (v - 0.5) * size.depth;
-        for (let xIndex = 0; xIndex < vertexCountX; xIndex += 1) {
-            const u = xIndex / segments.x;
-            const x = (u - 0.5) * size.width;
-            const y = sampler(x, z);
-            positions[index] = x;
-            positions[index + 1] = y;
-            positions[index + 2] = z;
-            uvs[uvIndex] = u;
-            uvs[uvIndex + 1] = v;
-            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);
-            colorValues[colorIndex] = color.r;
-            colorValues[colorIndex + 1] = color.g;
-            colorValues[colorIndex + 2] = color.b;
-            index += 3;
-            uvIndex += 2;
-            colorIndex += 3;
-        }
-    }
-    let triangleIndex = 0;
-    for (let zIndex = 0; zIndex < segments.z; zIndex += 1) {
-        for (let xIndex = 0; xIndex < segments.x; xIndex += 1) {
-            const a = zIndex * vertexCountX + xIndex;
-            const b = a + 1;
-            const c = a + vertexCountX;
-            const d = c + 1;
-            indices[triangleIndex] = a;
-            indices[triangleIndex + 1] = c;
-            indices[triangleIndex + 2] = b;
-            indices[triangleIndex + 3] = b;
-            indices[triangleIndex + 4] = c;
-            indices[triangleIndex + 5] = d;
-            triangleIndex += 6;
-        }
-    }
-    const geometry = new THREE.BufferGeometry();
-    geometry.setAttribute("position", new THREE.BufferAttribute(positions, 3));
-    geometry.setAttribute("uv", new THREE.BufferAttribute(uvs, 2));
-    geometry.setAttribute("color", new THREE.BufferAttribute(colorValues, 3));
-    geometry.setIndex(new THREE.BufferAttribute(indices, 1));
-    geometry.computeVertexNormals();
-    geometry.computeBoundingSphere();
-    return geometry;
+    const base = config.baseOffset ?? 0;
+    const span = (config.height ?? 1.4) * 1.2;
+    return buildGroundGeometry(size, segments, sampler, {
+        colors,
+        center: [0, 0],
+        heightRange: [base - span, base + span],
+        surface: { seed: config.seed ?? DEFAULT_TERRAIN_SURFACE_COLOR.seed },
+    });
 }

package/dist/touch/TouchControlsOverlay.d.ts

@@ -1,8 +1,10 @@
 import { type MutableRefObject } from "react";
-import { type TouchScheme, type TouchStyle } from "@jgengine/core/input/touchScheme";
+import { type TouchJoystickVariant, type TouchScheme, type TouchStyle } from "@jgengine/core/input/touchScheme";
 export interface TouchCodeSink {
     onCodeDown(code: string): void;
     onCodeUp(code: string): void;
+    /** Analog per-action magnitudes (0..1) from the joystick's continuous vector; `null` when the stick is released. Optional so bespoke docks that only press buttons need not care. */
+    onAnalog?(values: Readonly<Record<string, number>> | null): void;
 }
 /**
  * Thumb-arc placement for primary buttons around the bottom-right corner:
@@ -29,10 +31,12 @@ export declare function TouchPlaySurface({ scheme, sink, yawRef, pitchRef, maxPi
     maxPitch: number;
     onPrimaryTap: () => void;
 }): import("react").JSX.Element;
-export declare function TouchControlsDock({ scheme, sink, style, scale, }: {
+export declare function TouchControlsDock({ scheme, sink, style, scale, joystickVariant, }: {
     scheme: TouchScheme;
     sink: TouchCodeSink;
     /** Player-selected skin; falls back to the scheme's game default. */
     style?: TouchStyle;
     scale?: number;
+    /** Player-selected joystick behavior (Settings → Controls). Default `floating`. */
+    joystickVariant?: TouchJoystickVariant;
 }): import("react").JSX.Element;

package/dist/touch/TouchControlsOverlay.js

@@ -10,7 +10,9 @@ const ACTIONS_ZONE = { id: "control:actions", kind: "control", collisionPolicy:
 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;
+/** Radial deflection below which the stick reads as centered; travel past it rescales to 0..1 so analog output starts from zero instead of jumping. */
+const JOYSTICK_DEADZONE = 0.16;
+/** Digital fallback codes fire past this per-axis deflection — kept for edge-detection consumers (`justPressed`); analog movement itself flows through `onAnalog`. */
 const JOYSTICK_AXIS_THRESHOLD = 0.42;
 const LOOK_TAP_TUNING = { tapMoveThresholdPx: 12, tapMaxMs: 280, longPressMs: 450 };
 const BUTTON_SIZE = 56;
@@ -242,11 +244,60 @@ function joystickDirections(joystick, nx, ny) {
         active.add(joystick.right);
     return active;
 }
+/**
+ * Per-action analog magnitudes for a stick deflection: radial deadzone, then travel rescaled to
+ * 0..1 and split across the joystick's four mapped actions. This is what actually moves the
+ * player — the digital codes above only exist for edge-detection consumers.
+ */
+function joystickAnalogValues(joystick, nx, ny) {
+    const values = {};
+    const assign = (action, magnitude) => {
+        if (action !== null)
+            values[action] = magnitude;
+    };
+    const length = Math.hypot(nx, ny);
+    let dx = 0;
+    let dy = 0;
+    if (length >= JOYSTICK_DEADZONE) {
+        const travel = Math.min(1, (length - JOYSTICK_DEADZONE) / (1 - JOYSTICK_DEADZONE));
+        dx = (nx / length) * travel;
+        dy = (ny / length) * travel;
+    }
+    assign(joystick.up, Math.max(0, -dy));
+    assign(joystick.down, Math.max(0, dy));
+    assign(joystick.left, Math.max(0, -dx));
+    assign(joystick.right, Math.max(0, dx));
+    return values;
+}
+/** Shared drag state machine for both joystick variants: converts pointer travel around an origin into digital edge codes + analog magnitudes, and releases both on lift. */
+function useJoystickDrag(joystick, sink) {
+    const activeRef = useRef(new Set());
+    const applyNormalized = (nx, ny) => {
+        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;
+        sink.onAnalog?.(joystickAnalogValues(joystick, nx, ny));
+    };
+    const release = () => {
+        for (const action of activeRef.current)
+            sink.onCodeUp(touchCode(action));
+        activeRef.current = new Set();
+        sink.onAnalog?.(null);
+    };
+    return { applyNormalized, release };
+}
 function VirtualJoystick({ joystick, sink, tokens, scale = 1, }) {
     const baseRef = useRef(null);
     const thumbRef = useRef(null);
     const pointerIdRef = useRef(null);
-    const activeRef = useRef(new Set());
+    const drag = useJoystickDrag(joystick, sink);
     const size = JOYSTICK_SIZE * scale;
     const thumbSize = JOYSTICK_THUMB * scale;
     const applyVector = (clientX, clientY) => {
@@ -265,22 +316,11 @@ function VirtualJoystick({ joystick, sink, tokens, scale = 1, }) {
         }
         const travel = radius - thumbSize / 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;
+        drag.applyNormalized(nx, ny);
     };
     const releaseAll = () => {
         pointerIdRef.current = null;
-        for (const action of activeRef.current)
-            sink.onCodeUp(touchCode(action));
-        activeRef.current = new Set();
+        drag.release();
         if (thumbRef.current !== null)
             thumbRef.current.style.transform = "translate(0px, 0px)";
     };
@@ -302,6 +342,85 @@ function VirtualJoystick({ joystick, sink, tokens, scale = 1, }) {
             releaseAll();
         }, onPointerCancel: () => releaseAll(), children: _jsx("div", { ref: thumbRef, className: "rounded-full", style: { width: thumbSize, height: thumbSize, ...tokens.joyThumb } }) }));
 }
+/** Capture-zone footprint of the floating joystick — generous around the dock corner, but bounded so it never blankets HUD elements further up the screen (the zone eats pointer events). */
+const FLOATING_ZONE_WIDTH = "min(42vw, 300px)";
+const FLOATING_ZONE_HEIGHT = "min(40vh, 260px)";
+/**
+ * The floating joystick variant: its dock corner is an invisible capture zone with a faint
+ * resting ring for discoverability; the stick spawns centered under wherever the thumb lands and
+ * follows the same deadzone/analog math as the fixed stick. The modern mobile-shooter default —
+ * the hand never has to find a fixed target mid-fight.
+ */
+function FloatingJoystick({ joystick, sink, tokens, scale = 1, }) {
+    const pointerIdRef = useRef(null);
+    const originRef = useRef(null);
+    const baseRef = useRef(null);
+    const thumbRef = useRef(null);
+    const [engaged, setEngaged] = useState(false);
+    const drag = useJoystickDrag(joystick, sink);
+    const size = JOYSTICK_SIZE * scale;
+    const thumbSize = JOYSTICK_THUMB * scale;
+    const radius = size / 2;
+    const applyVector = (clientX, clientY) => {
+        const origin = originRef.current;
+        const thumb = thumbRef.current;
+        if (origin === null || thumb === null)
+            return;
+        let nx = (clientX - origin.x) / radius;
+        let ny = (clientY - origin.y) / radius;
+        const length = Math.hypot(nx, ny);
+        if (length > 1) {
+            nx /= length;
+            ny /= length;
+        }
+        const travel = radius - thumbSize / 2;
+        thumb.style.transform = `translate(${nx * travel}px, ${ny * travel}px)`;
+        drag.applyNormalized(nx, ny);
+    };
+    const releaseAll = () => {
+        pointerIdRef.current = null;
+        originRef.current = null;
+        setEngaged(false);
+        drag.release();
+        if (thumbRef.current !== null)
+            thumbRef.current.style.transform = "translate(0px, 0px)";
+    };
+    return (_jsxs("div", { className: "pointer-events-auto relative touch-none select-none", style: { width: FLOATING_ZONE_WIDTH, height: FLOATING_ZONE_HEIGHT }, onPointerDown: (event) => {
+            if (pointerIdRef.current !== null)
+                return;
+            pointerIdRef.current = event.pointerId;
+            event.currentTarget.setPointerCapture(event.pointerId);
+            const zone = event.currentTarget.getBoundingClientRect();
+            // Clamp the spawn point so the whole base stays inside the zone.
+            const x = Math.min(Math.max(event.clientX, zone.left + radius), zone.right - radius);
+            const y = Math.min(Math.max(event.clientY, zone.top + radius), zone.bottom - radius);
+            originRef.current = { x, y };
+            setEngaged(true);
+            const base = baseRef.current;
+            if (base !== null) {
+                base.style.left = `${x - zone.left - radius}px`;
+                base.style.top = `${y - zone.top - radius}px`;
+            }
+            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", { className: "pointer-events-none absolute rounded-full transition-opacity", style: {
+                    width: size,
+                    height: size,
+                    left: 0,
+                    bottom: 0,
+                    opacity: engaged ? 0 : 0.4,
+                    ...tokens.joyBase,
+                } }), _jsx("div", { ref: baseRef, className: "pointer-events-none absolute flex items-center justify-center rounded-full", style: { width: size, height: size, visibility: engaged ? "visible" : "hidden", ...tokens.joyBase }, children: _jsx("div", { ref: thumbRef, className: "rounded-full", style: { width: thumbSize, height: thumbSize, ...tokens.joyThumb } }) })] }));
+}
 function touchButtonIcon(button) {
     if (button.icon === false)
         return null;
@@ -446,7 +565,7 @@ function bucketByAnchor(buttons) {
     }
     return map;
 }
-export function TouchControlsDock({ scheme, sink, style, scale = 1, }) {
+export function TouchControlsDock({ scheme, sink, style, scale = 1, joystickVariant = "floating", }) {
     const tokens = STYLE_TOKENS[style ?? scheme.style];
     const layout = scheme.layout;
     const docked = scheme.buttons.filter((button) => button.anchor === null);
@@ -461,7 +580,7 @@ export function TouchControlsDock({ scheme, sink, style, scale = 1, }) {
     useRegisterLayoutRegion(UTILITY_ZONE, utilityRef, utility.length > 0);
     const actionsColumn = layout.actions === "left" || layout.actions === "right";
     const utilityColumn = layout.utility === "left" || layout.utility === "right";
-    return (_jsxs(ResolvedLayout, { children: [scheme.joystick !== null ? (_jsx(AnchoredSlot, { anchor: layout.movement, slotRef: joystickRef, children: _jsx(VirtualJoystick, { joystick: scheme.joystick, sink: sink, tokens: tokens, scale: scale }) })) : null, primary.length > 0 ? (_jsx(AnchoredSlot, { anchor: layout.actions, slotRef: actionsRef, children: ARC_ANCHORS.has(layout.actions) ? (_jsx(ThumbArcCluster, { buttons: primary, sink: sink, tokens: tokens, scale: scale })) : (_jsx(StackCluster, { buttons: primary, utility: [], sink: sink, tokens: tokens, column: actionsColumn, scale: scale })) })) : null, utility.length > 0 ? (_jsx(AnchoredSlot, { anchor: layout.utility, slotRef: utilityRef, children: _jsx(StackCluster, { buttons: [], utility: utility, sink: sink, tokens: tokens, column: utilityColumn, scale: scale }) })) : null, [...extras.entries()].map(([anchor, bucket]) => (_jsx(AnchoredSlot, { anchor: anchor, children: _jsx(StackCluster, { buttons: bucket.primary, utility: bucket.utility, sink: sink, tokens: tokens, column: anchor === "left" || anchor === "right", scale: scale }) }, anchor)))] }));
+    return (_jsxs(ResolvedLayout, { children: [scheme.joystick !== null ? (_jsx(AnchoredSlot, { anchor: layout.movement, slotRef: joystickRef, children: joystickVariant === "floating" ? (_jsx(FloatingJoystick, { joystick: scheme.joystick, sink: sink, tokens: tokens, scale: scale })) : (_jsx(VirtualJoystick, { joystick: scheme.joystick, sink: sink, tokens: tokens, scale: scale })) })) : null, primary.length > 0 ? (_jsx(AnchoredSlot, { anchor: layout.actions, slotRef: actionsRef, children: ARC_ANCHORS.has(layout.actions) ? (_jsx(ThumbArcCluster, { buttons: primary, sink: sink, tokens: tokens, scale: scale })) : (_jsx(StackCluster, { buttons: primary, utility: [], sink: sink, tokens: tokens, column: actionsColumn, scale: scale })) })) : null, utility.length > 0 ? (_jsx(AnchoredSlot, { anchor: layout.utility, slotRef: utilityRef, children: _jsx(StackCluster, { buttons: [], utility: utility, sink: sink, tokens: tokens, column: utilityColumn, scale: scale }) })) : null, [...extras.entries()].map(([anchor, bucket]) => (_jsx(AnchoredSlot, { anchor: anchor, children: _jsx(StackCluster, { buttons: bucket.primary, utility: bucket.utility, sink: sink, tokens: tokens, column: anchor === "left" || anchor === "right", scale: scale }) }, anchor)))] }));
 }
 function ResolvedLayout({ children }) {
     return _jsx("div", { className: "pointer-events-none absolute inset-0 z-40", children: children });