@jgengine/shell 0.19.0 → 0.22.0

package/dist/terrain/grassGeometry.js

@@ -24,6 +24,7 @@ export function resolveGrassBladeGeometryOptions(options = {}) {
         edgeFeather: Math.max(0, options.edgeFeather ?? 1.5),
         exclude: options.exclude ?? [],
         heightAt: options.heightAt ?? (() => 0),
+        coverageAt: options.coverageAt ?? (() => 1),
     };
 }
 /** Tuft instances needed to carry `bladeCount` blades at `tuftBlades` blades per tuft. @internal */
@@ -123,7 +124,7 @@ export function createGrassBladeGeometry(options = {}) {
             const d = Math.max(Math.abs(x - zone.center[0]) - zone.half[0], Math.abs(z - zone.center[1]) - zone.half[1]);
             heightScale *= Math.min(1, Math.max(0, d / Math.max(0.001, zone.feather ?? 1.5)));
         }
-        heights[index] = heightScale;
+        heights[index] = heightScale * Math.max(0, Math.min(1, resolved.coverageAt(x, z)));
         widths[index] = randomRange(random, resolved.width);
         bend[index] = randomRange(random, resolved.bend);
         phase[index] = random() * Math.PI * 2;
@@ -140,3 +141,58 @@ export function createGrassBladeGeometry(options = {}) {
     geometry.boundingSphere = new THREE.Sphere(new THREE.Vector3(0, 0, 0), Math.max(size.width, size.depth) * 0.75 + resolved.height[1]);
     return geometry;
 }
+/** Partition one existing seeded bake into at most 64 draws without resampling any tuft. @internal */
+export function createGrassGeometryChunks(options = {}) {
+    const source = createGrassBladeGeometry(options);
+    const size = resolveTerrainSize(options.area ?? 40);
+    const columns = Math.max(1, Math.min(8, Math.ceil(size.width / 16)));
+    const rows = Math.max(1, Math.min(8, Math.ceil(size.depth / 16)));
+    const buckets = Array.from({ length: columns * rows }, () => []);
+    const offsets = source.getAttribute("instanceOffset");
+    if (source.instanceCount === 0)
+        return [{ geometry: source, indices: new Uint32Array(), roots: new THREE.Box3(), bounds: new THREE.Box3(), bladeExtent: 0 }];
+    for (let i = 0; i < source.instanceCount; i++) {
+        const x = Math.max(0, Math.min(columns - 1, Math.floor(size.width > 0 ? (offsets.getX(i) / size.width + 0.5) * columns : 0)));
+        const z = Math.max(0, Math.min(rows - 1, Math.floor(size.depth > 0 ? (offsets.getZ(i) / size.depth + 0.5) * rows : 0)));
+        buckets[z * columns + x].push(i);
+    }
+    const vary = source.getAttribute("bladeVary");
+    const bendScale = source.getAttribute("bladeBendScale");
+    const bladeOffset = source.getAttribute("bladeOffset");
+    let heightScale = 0, widthScale = 0, bendFactor = 0, radius = 0;
+    for (let i = 0; i < vary.count; i++) {
+        heightScale = Math.max(heightScale, Math.abs(vary.getY(i)));
+        widthScale = Math.max(widthScale, Math.abs(vary.getZ(i)));
+        bendFactor = Math.max(bendFactor, Math.abs(bendScale.getX(i)));
+        radius = Math.max(radius, Math.hypot(bladeOffset.getX(i), bladeOffset.getY(i)));
+    }
+    const point = new THREE.Vector3();
+    const chunks = buckets.filter((indices) => indices.length > 0).map((indices) => {
+        const geometry = new THREE.InstancedBufferGeometry();
+        geometry.setIndex(source.index);
+        for (const [name, attribute] of Object.entries(source.attributes)) {
+            if (!(attribute instanceof THREE.InstancedBufferAttribute)) {
+                geometry.setAttribute(name, attribute);
+                continue;
+            }
+            const values = new Float32Array(indices.length * attribute.itemSize);
+            for (let i = 0; i < indices.length; i++) {
+                values.set(attribute.array.subarray(indices[i] * attribute.itemSize, (indices[i] + 1) * attribute.itemSize), i * attribute.itemSize);
+            }
+            geometry.setAttribute(name, new THREE.InstancedBufferAttribute(values, attribute.itemSize));
+        }
+        const roots = new THREE.Box3();
+        let extent = radius;
+        for (const i of indices) {
+            roots.expandByPoint(point.set(offsets.getX(i), offsets.getY(i), offsets.getZ(i)));
+            const height = Math.abs(source.getAttribute("instanceHeight").getX(i)) * heightScale;
+            const bend = Math.abs(source.getAttribute("instanceBend").getX(i)) * bendFactor;
+            const width = Math.abs(source.getAttribute("instanceWidth").getX(i)) * widthScale * 1.2;
+            extent = Math.max(extent, radius + width + height * (1 + bend * 1.18));
+        }
+        geometry.instanceCount = indices.length;
+        return { geometry, indices: Uint32Array.from(indices), roots, bounds: roots.clone(), bladeExtent: extent };
+    });
+    source.dispose();
+    return chunks;
+}

package/dist/terrain/grassMaterial.js

@@ -111,7 +111,7 @@ void jgComputeGrassBlade() {
   // triangle blades leave the ground visible between tufts and read as stubble.
   float taper = (1.0 - 0.3 * t) * (1.0 - smoothstep(0.5, 1.0, t) * 0.95);
   // Surviving distant tufts widen to hold silhouette coverage as neighbors thin out.
-  float width = instanceWidth * bladeVary.z * taper * (1.0 + fadeT * 1.4);
+  float width = instanceWidth * bladeVary.z * taper * (1.0 + fadeT * 1.4) * keep;
   float arc = instanceBend * bladeBendScale * t * t;
   vec3 localPosition = vec3(side * width, heightScale * t - arc * heightScale * 0.18, arc * heightScale);
   vec3 localNormal = normalize(vec3(0.0, -instanceBend * bladeBendScale * t, 1.0));
@@ -134,7 +134,7 @@ ${wind.layered
     + 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);
+  vec2 windOffset = uWindDirection * (gust * uWindStrength + flutter) * t * t * (0.4 + 0.6 * bladeVary.y) * keep;
   jgGrassPosition = instanceOffset + tuftOffset + yawedPosition + vec3(windOffset.x, 0.0, windOffset.y);
   // Lifting normals toward straight-up lights the field like a continuous meadow surface —
   // side-lit individual blade planes read as dark stubble, not turf.

package/dist/terrain/index.d.ts

@@ -9,3 +9,4 @@ export { createGrassMaterial, DEFAULT_GRASS_WIND, resolveGrassWind, type GrassMa
 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 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";
+export { createTerrainPaintColorSampler, type TerrainPaintColorSampler, type TerrainPaintSource } from "./terrainPaintColor.js";

package/dist/terrain/index.js

@@ -9,3 +9,4 @@ export { createGrassMaterial, DEFAULT_GRASS_WIND, resolveGrassWind, } from "./gr
 export { createSeededRandom, hashNoise2, seedToUint32 } from "./random.js";
 export { createFieldGroundGeometry, createProceduralGroundGeometry, createProceduralTerrainSampler, normalizeHeightBlend, resolveTerrainSegments, resolveTerrainSize, toNoiseFieldConfig, } from "./terrainMath.js";
 export { arenaField, flatField, fractalNoise, noiseField, resolveGroundStep, resolveTerrainField, valueNoise, withNormal, } from "@jgengine/core/world/terrain";
+export { createTerrainPaintColorSampler } from "./terrainPaintColor.js";

package/dist/terrain/terrainDetailMaterial.d.ts

@@ -7,13 +7,13 @@ export interface TerrainDetailMaterialHandle {
 /**
  * Loaded PBR textures matching a resolved `ResolvedTerrainDetailMaterial.maps`' roles. The caller
  * (a React component, via `useTexture`/`useLoader`) owns loading and disposal; `core` never touches
- * `THREE.Texture` and this shell function never fetches a URL itself.
+ * `THREE.Texture` and this shell function never fetches a URL itself. Omitted AO/roughness skip sampling.
  */
 export interface TerrainDetailMaterialTextures {
     color: THREE.Texture;
     normal: THREE.Texture;
-    roughness: THREE.Texture;
-    ao: THREE.Texture;
+    roughness?: THREE.Texture;
+    ao?: THREE.Texture;
 }
 /**
  * A `MeshStandardMaterial` whose fragment shader keeps the biome-tinted vertex

package/dist/terrain/terrainDetailMaterial.js

@@ -60,8 +60,8 @@ export function createTerrainDetailMaterial(detail, textures) {
             ? {
                 uMatColor: { value: textures.color },
                 uMatNormal: { value: textures.normal },
-                uMatRoughness: { value: textures.roughness },
-                uMatAo: { value: textures.ao },
+                ...(textures.roughness !== undefined ? { uMatRoughness: { value: textures.roughness } } : {}),
+                ...(textures.ao !== undefined ? { uMatAo: { value: textures.ao } } : {}),
                 uMatRepeat: { value: Math.max(0.01, repeat) },
                 uMatStrength: { value: strength },
                 uMatTint: { value: tint },
@@ -88,8 +88,8 @@ vJgWorldPos = (modelMatrix * vec4(transformed, 1.0)).xyz;`);
             ? `
 uniform sampler2D uMatColor;
 uniform sampler2D uMatNormal;
-uniform sampler2D uMatRoughness;
-uniform sampler2D uMatAo;
+${textures.roughness !== undefined ? "uniform sampler2D uMatRoughness;" : ""}
+${textures.ao !== undefined ? "uniform sampler2D uMatAo;" : ""}
 uniform float uMatRepeat;
 uniform float uMatStrength;
 uniform float uMatTint;`
@@ -106,7 +106,7 @@ 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
+        const materialRoughnessGlsl = hasTexture && textures.roughness !== undefined
             ? `
 float jgMatRough = texture2D(uMatRoughness, jgMatUv).g;
 roughnessFactor = mix(roughnessFactor, jgMatRough, uMatStrength);`
@@ -116,7 +116,7 @@ roughnessFactor = mix(roughnessFactor, jgMatRough, uMatStrength);`
 vec2 jgMatNormalXy = texture2D(uMatNormal, jgMatUv).rg * 2.0 - 1.0;
 normal = normalize(normal + vec3(jgMatNormalXy.x, 0.0, jgMatNormalXy.y) * uMatStrength * 0.6);`
             : "";
-        const materialAoGlsl = hasTexture
+        const materialAoGlsl = hasTexture && textures.ao !== undefined
             ? `
 float jgMatAo = texture2D(uMatAo, jgMatUv).r;
 reflectedLight.indirectDiffuse *= mix(1.0, jgMatAo, uMatStrength);`
@@ -178,6 +178,6 @@ ${materialNormalGlsl}`)
             .replace("#include <aomap_fragment>", `#include <aomap_fragment>
 ${materialAoGlsl}`);
     };
-    material.customProgramCacheKey = () => `jgengine-terrain-detail-${detail.rockSlopeStart}-${detail.snowHeight}-${hasTexture ? "tex" : "flat"}`;
+    material.customProgramCacheKey = () => `jgengine-terrain-detail-${detail.rockSlopeStart}-${detail.snowHeight}-${hasTexture ? "tex" : "flat"}-${hasTexture && textures.roughness !== undefined ? "rough" : "scalar"}-${hasTexture && textures.ao !== undefined ? "ao" : "unoccluded"}`;
     return { material };
 }

package/dist/terrain/terrainMath.d.ts

@@ -82,6 +82,8 @@ export interface FieldGroundOptions {
     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;
+    /** Authored paint overrides descriptor shading at painted vertices. */
+    paintColorAt?: (x: number, z: number, out: THREE.Color) => boolean;
 }
 /**
  * Mesh any `TerrainField` — including a `CarvableField` with craters/mounds written into it — into a

package/dist/terrain/terrainMath.js

@@ -106,6 +106,7 @@ export function createFieldGroundGeometry(field, options = {}) {
         heightRange: options.heightRange,
         paletteAt: options.paletteAt,
         surface: options.surface,
+        paintColorAt: options.paintColorAt,
     });
 }
 function buildGroundGeometry(size, segments, sampler, opts) {
@@ -162,6 +163,7 @@ function buildGroundGeometry(size, segments, sampler, opts) {
                 slope01 = grad / (grad + 1);
             }
             applyTerrainSurfaceShading(color, x, z, slope01, surface);
+            opts.paintColorAt?.(x, z, color);
             colorValues[colorIndex] = color.r;
             colorValues[colorIndex + 1] = color.g;
             colorValues[colorIndex + 2] = color.b;

package/dist/terrain/terrainPaintColor.d.ts

@@ -0,0 +1,11 @@
+import * as THREE from "three";
+import type { EditableTerrain } from "@jgengine/core/world/terraform";
+/** Live authored paint channels needed to sample a terrain's material stack without its heightfield. */
+export type TerrainPaintSource = Pick<EditableTerrain, "layers" | "weightsAt" | "surfaceAt">;
+/** Writes authored paint into an existing linear color; returns false for unpainted ground. */
+export type TerrainPaintColorSampler = (x: number, z: number, out: THREE.Color) => boolean;
+/**
+ * Shares layer tint, opacity and linear weighted-color blending between editor and runtime ground.
+ * @capability terrain-paint-color sample authored terrain surfaces and blended layers for shared ground rendering
+ */
+export declare function createTerrainPaintColorSampler(terrain: TerrainPaintSource): TerrainPaintColorSampler;

package/dist/terrain/terrainPaintColor.js

@@ -0,0 +1,47 @@
+import * as THREE from "three";
+import { TERRAIN_MATERIAL_COLORS } from "@jgengine/core/editor/terrainMaterials";
+/**
+ * Shares layer tint, opacity and linear weighted-color blending between editor and runtime ground.
+ * @capability terrain-paint-color sample authored terrain surfaces and blended layers for shared ground rendering
+ */
+export function createTerrainPaintColorSampler(terrain) {
+    const layers = terrain.layers;
+    const colors = layers.map(layer => new THREE.Color(layer.tint ?? TERRAIN_MATERIAL_COLORS[layer.surface] ?? "#7c7f86"));
+    const defaults = new Map(Object.entries(TERRAIN_MATERIAL_COLORS).map(([id, color]) => [id, new THREE.Color(color)]));
+    return (x, z, out) => {
+        const weights = terrain.weightsAt(x, z);
+        if (layers.length > 0 && weights.length === layers.length) {
+            let total = 0, r = 0, g = 0, b = 0;
+            for (let i = 0; i < layers.length; i++) {
+                const weight = weights[i] * (layers[i].opacity ?? 1);
+                if (weight <= 0)
+                    continue;
+                const color = colors[i];
+                r += color.r * weight;
+                g += color.g * weight;
+                b += color.b * weight;
+                total += weight;
+            }
+            if (total > 0) {
+                out.setRGB(r / total, g / total, b / total);
+                return true;
+            }
+            return false;
+        }
+        const surface = terrain.surfaceAt(x, z);
+        if (surface === null)
+            return false;
+        const index = layers.findIndex(layer => layer.surface === surface);
+        if (index >= 0) {
+            if ((layers[index].opacity ?? 1) <= 0)
+                return false;
+            out.copy(colors[index]);
+            return true;
+        }
+        const color = defaults.get(surface);
+        if (color === undefined)
+            return false;
+        out.copy(color);
+        return true;
+    };
+}

package/dist/touch/TouchControlsOverlay.js

@@ -548,8 +548,8 @@ function anchorInset(anchor) {
     }
     return style;
 }
-function AnchoredSlot({ anchor, children, slotRef, }) {
-    return (_jsx("div", { className: "pointer-events-none absolute z-40", style: { ...ANCHOR_POSITION[anchor], ...anchorInset(anchor) }, children: _jsx("div", { ref: slotRef, children: children }) }));
+function AnchoredSlot({ anchor, children, slotRef, movement = false, }) {
+    return (_jsx("div", { className: "pointer-events-none absolute", style: { zIndex: movement ? 10 : 40, ...ANCHOR_POSITION[anchor], ...anchorInset(anchor) }, children: _jsx("div", { ref: slotRef, children: children }) }));
 }
 function bucketByAnchor(buttons) {
     const map = new Map();
@@ -580,8 +580,8 @@ export function TouchControlsDock({ scheme, sink, style, scale = 1, joystickVari
     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: 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)))] }));
+    return (_jsxs(ResolvedLayout, { children: [scheme.joystick !== null ? (_jsx(AnchoredSlot, { anchor: layout.movement, slotRef: joystickRef, movement: true, 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 });
+    return _jsx("div", { className: "pointer-events-none absolute inset-0", children: children });
 }

package/dist/useShellMultiplayerSync.js

@@ -1,5 +1,6 @@
 import { useEffect, useState, useCallback } from "react";
 import { isServerAuthoritative } from "@jgengine/core/runtime/adapter";
+import { bindCommandTransport } from "@jgengine/core/runtime/commandDispatch";
 import { createTransportSessionId } from "@jgengine/core/runtime/transport";
 import { attachWorldSync } from "./worldSync.js";
 /** Joins the multiplayer server for the live context and wires presence, feed relay, and chat sync until teardown. */
@@ -15,6 +16,9 @@ export function useShellMultiplayerSync(ctx, multiplayer, playable, serverIdRef,
         setFailureReason(null);
         let disposed = false;
         const cleanups = [];
+        if (isServerAuthoritative(playable.game.multiplayer)) {
+            cleanups.push(bindCommandTransport(ctx, { transport: multiplayer.backend.transport, serverId: () => serverIdRef.current }));
+        }
         const sessionId = createTransportSessionId();
         void multiplayer.backend.transport
             .joinServer({ gameId: multiplayer.gameId, sessionId })

package/dist/vfx/ParticleField.d.ts

@@ -1,32 +1,35 @@
 import { type ReactElement } from "react";
 import type { ParticleSystem } from "@jgengine/core/vfx/particles";
-/** How particle fragments composite: `additive` for fire/sparks/magic glow, `normal` for smoke/dust. */
+import type { ParticleRenderHint } from "@jgengine/core/vfx/particleDirector";
+/** How particle fragments composite on screen. */
 export type ParticleBlending = "additive" | "normal";
-/** Props for {@link ParticleField}. */
+/** @internal Mutable resource/upload counters read through the shell's supported diagnostics probe. */
+export interface ParticleFieldMetrics {
+    fieldsMounted: number;
+    fieldsUnmounted: number;
+    liveFields: number;
+    attributeBytes: number;
+    totalUploadMs: number;
+    maxUploadMs: number;
+    uploadSamples: number;
+}
+/** Props for the existing pooled particle renderer. */
 export interface ParticleFieldProps {
-    /** The core simulation to render (from `createParticleSystem`). */
     system: ParticleSystem;
-    /**
-     * Advance the simulation each frame with the render delta. Leave `true` for a
-     * fire-and-forget effect; set `false` when your game loop already ticks the
-     * system (so it advances exactly once per fixed step).
-     */
+    /** Disable when an external loop already advances this system. Default true. */
     advance?: boolean;
-    /** Compositing mode. Default `additive` (glowy). */
     blending?: ParticleBlending;
-    /** Pixel-size multiplier applied to every particle's world radius. Default 300. */
+    /** Pixel multiplier for point output. Quad outputs use particle sizes in world units. */
     scale?: number;
-    /** Write depth (occludes particles behind geometry). Default `false` so a glow layer never self-occludes. */
     depthWrite?: boolean;
+    /** Point, instanced sprite, velocity streak, connected ribbon, or ground ripple output. */
+    render?: ParticleRenderHint;
+    /** @internal Optional diagnostics; omitted in production. */
+    metrics?: ParticleFieldMetrics;
 }
 /**
- * Renders a core `ParticleSystem` as a GPU point cloud: one draw call, per-particle
- * size / color / alpha via a soft-round shader, and a `drawRange` clamped to the live
- * count so dead particles cost nothing. The simulation stays engine-side and
- * genre-agnostic; this is purely how it reaches the screen. By default it advances
- * the sim with the frame delta — pass `advance={false}` to drive it from your own
- * fixed loop instead.
- *
- * @capability particle-field render a core particle system as a soft-point GPU cloud with per-particle size, color, and alpha
+ * Render one pooled simulation through a point cloud or instanced quads. Output
+ * selection does not replace spawn, forces, collisions, or deterministic state.
+ * @capability particle-field render a core particle pool as soft points, velocity streaks, connected ribbons, flakes, flames, smoke sprites, or ground ripples
  */
-export declare function ParticleField({ system, advance, blending, scale, depthWrite, }: ParticleFieldProps): ReactElement;
+export declare function ParticleField({ system, advance, blending, scale, depthWrite, render, metrics }: ParticleFieldProps): ReactElement;

package/dist/vfx/ParticleField.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useFrame, useThree } from "@react-three/fiber";
-import { useEffect, useMemo, useRef } from "react";
+import { useEffect, useMemo } from "react";
 import * as THREE from "three";
 const VERTEX_SHADER = /* glsl */ `
   attribute float aSize;
@@ -21,71 +21,189 @@ const FRAGMENT_SHADER = /* glsl */ `
   varying float vAlpha;
   varying vec3 vColor;
   void main() {
-    // Soft round sprite: radial falloff from the point center, discard the corners.
-    vec2 d = gl_PointCoord - vec2(0.5);
-    float r = length(d);
+    float r = length(gl_PointCoord - vec2(0.5));
     if (r > 0.5) discard;
-    float soft = smoothstep(0.5, 0.0, r);
-    gl_FragColor = vec4(vColor, vAlpha * soft);
+    gl_FragColor = vec4(vColor, vAlpha * smoothstep(0.5, 0.0, r));
   }
 `;
+const QUAD_VERTEX = /* glsl */ `
+  attribute vec3 aCenter;
+  attribute vec3 aEnd;
+  attribute vec3 aVelocity;
+  attribute float aId;
+  attribute float aSize;
+  attribute float aAlpha;
+  attribute vec3 aColor;
+  uniform float uShape;
+  uniform float uStretch;
+  varying vec2 vUv;
+  varying float vAlpha;
+  varying vec3 vColor;
+  void main() {
+    vUv = uv;
+    vAlpha = aAlpha;
+    vColor = aColor;
+    vec4 center = modelViewMatrix * vec4(aCenter, 1.0);
+    vec4 view = center;
+    if (uShape == 1.0 || uShape == 5.0) {
+      vec3 end = uShape == 5.0 ? aEnd : aCenter - aVelocity * uStretch;
+      vec4 tail = modelViewMatrix * vec4(end, 1.0);
+      vec2 delta = center.xy - tail.xy;
+      float len = length(delta);
+      vec2 side = len > 0.00001 ? vec2(-delta.y, delta.x) / len : vec2(1.0, 0.0);
+      view = mix(tail, center, uv.y);
+      view.xy += side * position.x * aSize;
+    } else if (uShape == 6.0) {
+      view = modelViewMatrix * vec4(aCenter + vec3(position.x, 0.002, position.y) * aSize * 2.0, 1.0);
+    } else {
+      vec2 corner = position.xy * aSize;
+      if (uShape == 2.0) {
+        float angle = aId * 2.399963;
+        corner = mat2(cos(angle), -sin(angle), sin(angle), cos(angle)) * corner;
+      }
+      if (uShape == 3.0) {
+        corner.y *= 2.7;
+        corner.x += sin(aId * 1.7 + uv.y * 7.0) * aSize * 0.14 * uv.y;
+      }
+      if (uShape == 4.0) corner *= 1.65;
+      view.xy += corner;
+    }
+    gl_Position = projectionMatrix * view;
+  }
+`;
+const QUAD_FRAGMENT = /* glsl */ `
+  uniform float uShape;
+  varying vec2 vUv;
+  varying float vAlpha;
+  varying vec3 vColor;
+  void main() {
+    vec2 d = vUv - 0.5;
+    float alpha;
+    if (uShape == 1.0 || uShape == 5.0) {
+      alpha = smoothstep(0.5, 0.0, abs(d.x)) * smoothstep(0.0, 0.12, vUv.y) * smoothstep(1.0, 0.7, vUv.y);
+    } else if (uShape == 2.0) {
+      float angle = atan(d.y, d.x);
+      float edge = 0.26 + 0.12 * pow(abs(cos(angle * 3.0)), 4.0);
+      alpha = smoothstep(edge, edge * 0.62, length(d));
+    } else if (uShape == 3.0) {
+      float width = (1.0 - vUv.y) * 0.42 + 0.04;
+      alpha = smoothstep(width, 0.0, abs(d.x)) * smoothstep(0.0, 0.18, vUv.y) * smoothstep(1.0, 0.5, vUv.y);
+    } else if (uShape == 6.0) {
+      float r = length(d);
+      alpha = smoothstep(0.07, 0.0, abs(r - 0.38));
+    } else {
+      float r = length(d);
+      alpha = smoothstep(0.5, 0.08, r);
+      if (uShape == 4.0) alpha *= 0.65 + 0.35 * sin(vUv.x * 15.0 + sin(vUv.y * 12.0));
+    }
+    alpha *= vAlpha;
+    if (alpha < 0.001) discard;
+    gl_FragColor = vec4(vColor, alpha);
+  }
+`;
+const SHAPES = { point: 0, streak: 1, flake: 2, flame: 3, smoke: 4, ribbon: 5, ripple: 6 };
 /**
- * Renders a core `ParticleSystem` as a GPU point cloud: one draw call, per-particle
- * size / color / alpha via a soft-round shader, and a `drawRange` clamped to the live
- * count so dead particles cost nothing. The simulation stays engine-side and
- * genre-agnostic; this is purely how it reaches the screen. By default it advances
- * the sim with the frame delta — pass `advance={false}` to drive it from your own
- * fixed loop instead.
- *
- * @capability particle-field render a core particle system as a soft-point GPU cloud with per-particle size, color, and alpha
+ * Render one pooled simulation through a point cloud or instanced quads. Output
+ * selection does not replace spawn, forces, collisions, or deterministic state.
+ * @capability particle-field render a core particle pool as soft points, velocity streaks, connected ribbons, flakes, flames, smoke sprites, or ground ripples
  */
-export function ParticleField({ system, advance = true, blending = "additive", scale = 300, depthWrite = false, }) {
-    const pointsRef = useRef(null);
+export function ParticleField({ system, advance = true, blending = "additive", scale = 300, depthWrite = false, render, metrics }) {
     const dpr = useThree((state) => state.viewport.dpr);
-    const { geometry, material } = useMemo(() => {
-        const initial = system.buffers();
-        const max = initial.positions.length / 3;
-        const geo = new THREE.BufferGeometry();
-        geo.setAttribute("position", new THREE.BufferAttribute(new Float32Array(max * 3), 3));
-        geo.setAttribute("aSize", new THREE.BufferAttribute(new Float32Array(max), 1));
-        geo.setAttribute("aColor", new THREE.BufferAttribute(new Float32Array(max * 3), 3));
-        geo.setAttribute("aAlpha", new THREE.BufferAttribute(new Float32Array(max), 1));
-        geo.setDrawRange(0, 0);
-        const mat = new THREE.ShaderMaterial({
-            vertexShader: VERTEX_SHADER,
-            fragmentShader: FRAGMENT_SHADER,
-            uniforms: { uScale: { value: scale } },
-            transparent: true,
-            depthWrite,
-            blending: blending === "additive" ? THREE.AdditiveBlending : THREE.NormalBlending,
-        });
-        return { geometry: geo, material: mat };
-    }, [system, scale, depthWrite, blending]);
+    const shape = render?.shape ?? "point";
+    const quad = shape !== "point";
+    const { geometry, material, indexById } = useMemo(() => {
+        const max = system.buffers().positions.length / 3;
+        const geo = quad ? new THREE.InstancedBufferGeometry() : new THREE.BufferGeometry();
+        if (quad) {
+            geo.setAttribute("position", new THREE.Float32BufferAttribute([-0.5, -0.5, 0, 0.5, -0.5, 0, 0.5, 0.5, 0, -0.5, 0.5, 0], 3));
+            geo.setAttribute("uv", new THREE.Float32BufferAttribute([0, 0, 1, 0, 1, 1, 0, 1], 2));
+            geo.setIndex([0, 1, 2, 0, 2, 3]);
+            geo.setAttribute("aCenter", new THREE.InstancedBufferAttribute(new Float32Array(max * 3), 3));
+            geo.setAttribute("aEnd", new THREE.InstancedBufferAttribute(new Float32Array(max * 3), 3));
+            geo.setAttribute("aVelocity", new THREE.InstancedBufferAttribute(new Float32Array(max * 3), 3));
+            geo.setAttribute("aId", new THREE.InstancedBufferAttribute(new Float32Array(max), 1));
+            geo.instanceCount = 0;
+        }
+        else {
+            geo.setAttribute("position", new THREE.BufferAttribute(new Float32Array(max * 3), 3));
+            geo.setDrawRange(0, 0);
+        }
+        const attribute = (array, size) => quad ? new THREE.InstancedBufferAttribute(array, size) : new THREE.BufferAttribute(array, size);
+        geo.setAttribute("aSize", attribute(new Float32Array(max), 1));
+        geo.setAttribute("aColor", attribute(new Float32Array(max * 3), 3));
+        geo.setAttribute("aAlpha", attribute(new Float32Array(max), 1));
+        const mat = new THREE.ShaderMaterial({ vertexShader: quad ? QUAD_VERTEX : VERTEX_SHADER, fragmentShader: quad ? QUAD_FRAGMENT : FRAGMENT_SHADER,
+            uniforms: { uScale: { value: scale }, uShape: { value: SHAPES[shape] }, uStretch: { value: render?.stretch ?? 0.08 } },
+            transparent: true, depthWrite, side: THREE.DoubleSide,
+            blending: blending === "additive" ? THREE.AdditiveBlending : THREE.NormalBlending });
+        return { geometry: geo, material: mat, indexById: new Map() };
+    }, [system, quad, shape, scale, depthWrite, blending]);
     useEffect(() => {
+        const bytes = Object.values(geometry.attributes).reduce((total, attribute) => total + attribute.array.byteLength, geometry.index?.array.byteLength ?? 0);
+        if (metrics !== undefined) {
+            metrics.fieldsMounted++;
+            metrics.liveFields++;
+            metrics.attributeBytes += bytes;
+        }
         return () => {
             geometry.dispose();
             material.dispose();
+            if (metrics !== undefined) {
+                metrics.fieldsUnmounted++;
+                metrics.liveFields--;
+                metrics.attributeBytes -= bytes;
+            }
         };
-    }, [geometry, material]);
+    }, [geometry, material, metrics]);
     useFrame((_, delta) => {
+        const started = metrics === undefined ? 0 : performance.now();
         if (advance)
             system.update(Math.min(delta, 0.1));
         const buffers = system.buffers();
         const count = buffers.count;
-        const pos = geometry.getAttribute("position");
-        const size = geometry.getAttribute("aSize");
-        const color = geometry.getAttribute("aColor");
-        const alpha = geometry.getAttribute("aAlpha");
-        pos.array.set(buffers.positions.subarray(0, count * 3));
-        size.array.set(buffers.sizes.subarray(0, count));
-        color.array.set(buffers.colors.subarray(0, count * 3));
-        alpha.array.set(buffers.alphas.subarray(0, count));
-        pos.needsUpdate = true;
-        size.needsUpdate = true;
-        color.needsUpdate = true;
-        alpha.needsUpdate = true;
-        geometry.setDrawRange(0, count);
+        const upload = (name, values, n) => {
+            const attr = geometry.getAttribute(name);
+            attr.array.set(values.subarray(0, n));
+            attr.needsUpdate = true;
+        };
+        upload(quad ? "aCenter" : "position", buffers.positions, count * 3);
+        upload("aSize", buffers.sizes, count);
+        upload("aColor", buffers.colors, count * 3);
+        upload("aAlpha", buffers.alphas, count);
+        if (quad) {
+            upload("aVelocity", buffers.velocities, count * 3);
+            const end = geometry.getAttribute("aEnd");
+            const ids = geometry.getAttribute("aId");
+            if (shape === "ribbon") {
+                for (let i = 0; i < count; i++)
+                    indexById.set(buffers.ids[i], i);
+                for (const id of indexById.keys()) {
+                    const index = indexById.get(id);
+                    if (index >= count || buffers.ids[index] !== id)
+                        indexById.delete(id);
+                }
+            }
+            for (let i = 0; i < count; i++) {
+                ids.setX(i, buffers.ids[i]);
+                const previousIndex = shape === "ribbon" ? indexById.get(buffers.ids[i] - 1) : undefined;
+                const source = previousIndex === undefined ? buffers.previousPositions : buffers.positions;
+                const offset = (previousIndex ?? i) * 3;
+                end.setXYZ(i, source[offset], source[offset + 1], source[offset + 2]);
+            }
+            end.needsUpdate = true;
+            ids.needsUpdate = true;
+            geometry.instanceCount = count;
+        }
+        else
+            geometry.setDrawRange(0, count);
         material.uniforms.uScale.value = scale * dpr;
+        material.uniforms.uStretch.value = render?.stretch ?? 0.08;
+        if (metrics !== undefined) {
+            const elapsed = performance.now() - started;
+            metrics.totalUploadMs += elapsed;
+            metrics.maxUploadMs = Math.max(metrics.maxUploadMs, elapsed);
+            metrics.uploadSamples++;
+        }
     });
-    return _jsx("points", { ref: pointsRef, geometry: geometry, material: material, frustumCulled: false });
+    return quad ? _jsx("mesh", { geometry: geometry, material: material, frustumCulled: false }) : _jsx("points", { geometry: geometry, material: material, frustumCulled: false });
 }