@forgeax/engine-vfx-render 0.1.7 → 0.1.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgeax/engine-vfx-render",
-  "version": "0.1.7",
+  "version": "0.1.20",
   "private": false,
   "type": "module",
   "license": "Apache-2.0",
@@ -22,13 +22,13 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@forgeax/engine-assets-runtime": "0.1.7",
-    "@forgeax/engine-ecs": "0.1.7",
-    "@forgeax/engine-math": "0.1.7",
-    "@forgeax/engine-render": "0.1.7",
-    "@forgeax/engine-scene": "0.1.7",
-    "@forgeax/engine-types": "0.1.7",
-    "@forgeax/engine-vfx": "0.1.7"
+    "@forgeax/engine-assets-runtime": "0.1.20",
+    "@forgeax/engine-ecs": "0.1.20",
+    "@forgeax/engine-math": "0.1.20",
+    "@forgeax/engine-render": "0.1.20",
+    "@forgeax/engine-scene": "0.1.20",
+    "@forgeax/engine-types": "0.1.20",
+    "@forgeax/engine-vfx": "0.1.20"
   },
   "devDependencies": {},
   "forgeax": {

package/src/__tests__/fog-producer.integration.test.ts

@@ -8,23 +8,11 @@ function shaderSource(name: (typeof shaderNames)[number]): string {
   return readFileSync(fileURLToPath(new URL(`../shaders/${name}.wgsl`, import.meta.url)), 'utf8');
 }
 
-function count(source: string, pattern: RegExp): number {
-  return source.match(pattern)?.length ?? 0;
-}
-
-describe('VFX Fog producer contract', () => {
-  it('requires one shared Fog call with a world-space ray for every topology', () => {
+describe('VFX volumetric-fog boundary contract', () => {
+  it('keeps analytic fog out of every particle topology', () => {
     for (const name of shaderNames) {
       const source = shaderSource(name);
-      expect(source, name).toMatch(
-        /#import\s+forgeax_view::common::\{[^}]*\bFogViewParams\b[^}]*\bFogRay\b[^}]*\}/,
-      );
-      expect(source, name).toMatch(/#import\s+forgeax_view::fog::\{[^}]*\bapply_fog\b[^}]*\}/);
-      expect(count(source, /\bapply_fog\s*\(/g), name).toBe(1);
-      expect(count(source, /\bFogRay\s*\(/g), name).toBe(1);
-      expect(source, name).toMatch(/world[_A-Za-z]*position|worldPosition/);
-      expect(source, name).toMatch(/ray[_A-Za-z]*distance|distance/);
-      expect(source, name).toMatch(/\.a\b|alpha/);
+      expect(source, name).not.toMatch(/\bFogViewParams\b|\bFogRay\b|\bapply_fog\s*\(/);
       expect(source, name).not.toMatch(/texture_3d|raymarch/i);
     }
   });
@@ -46,15 +34,16 @@ describe('VFX Fog producer contract', () => {
     expect(camera).toContain('viewProjection');
   });
 
-  it('keeps billboard scene-depth soft-particle alpha before Fog mixing', () => {
+  it('keeps billboard scene-depth soft-particle alpha in the final color', () => {
     const billboard = shaderSource('billboard');
     const depthLoad = billboard.indexOf('textureLoad(scene_depth');
     const softParticleCall = billboard.indexOf('softParticle(input.position');
-    const fogCall = billboard.indexOf('apply_fog(');
+    const finalColor = billboard.indexOf('return vec4<f32>(rgb * alpha, alpha);');
 
     expect(depthLoad).toBeGreaterThanOrEqual(0);
     expect(softParticleCall).toBeGreaterThan(depthLoad);
-    expect(fogCall).toBeGreaterThan(softParticleCall);
+    expect(finalColor).toBeGreaterThan(softParticleCall);
     expect(billboard).toContain('input.color.a * edge, input.fade_distance');
+    expect(billboard).not.toContain('apply_fog(');
   });
 });

package/src/__tests__/gpu-host.integration.test.ts

@@ -50,7 +50,10 @@ describe('GPU VFX public host', () => {
     const world = new World();
     const lookups: string[] = [];
     class StatefulAssets {
-      readonly material: MaterialAsset = { kind: 'material', values: {} };
+      readonly material: MaterialAsset = {
+        kind: 'material',
+        passes: [{ name: 'particle-billboard', program: { module: 'custom-depth' } }],
+      };
       readonly loaders = { registerPackLoader: () => {} };
 
       lookup<T extends Asset = Asset>(guid: string): T | undefined {
@@ -118,14 +121,29 @@ describe('GPU VFX public host', () => {
         frameNumber: 1,
       } as never,
       {
-        targets: [],
+        targets: [
+          { name: 'scene-color', kind: 'color', format: 'rgba8unorm-srgb', sampleCount: 1 },
+          { name: 'scene-depth', kind: 'depth', format: 'depth24plus', sampleCount: 1 },
+        ],
         caps: {},
         frame: { frameNumber: 1 },
         generation: 1,
+        materialShaderBindingContract: () => 'group-0-resource',
       } as never,
     );
     expect(planned.ok).toBe(true);
     expect(lookups).toEqual(['material-guid']);
+    if (planned.ok) {
+      expect(planned.value.resources).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({
+            kind: 'graphics-bindings',
+            values: expect.objectContaining({ sceneDepthBinding: 0 }),
+            logicalTargets: { sceneDepth: 'scene-depth' },
+          }),
+        ]),
+      );
+    }
     await host.detachWorld({ world });
   });
 

package/src/__tests__/particle-resources.unit.test.ts

@@ -3,6 +3,7 @@ import { describe, expect, it } from 'vitest';
 import {
   canonicalMeshVertices,
   particleMaterialPass,
+  particleMaterialSceneDepthBinding,
   particleMaterialUsesBindings,
 } from '../feature/particle-resources.js';
 
@@ -53,6 +54,14 @@ describe('particle material pass', () => {
     });
   });
 
+  it('maps renderer shader contracts to their scene-depth binding slots', () => {
+    expect(particleMaterialSceneDepthBinding('group-0-resource')).toBe(0);
+    expect(particleMaterialSceneDepthBinding('view-and-scene-depth')).toBe(1);
+    expect(particleMaterialSceneDepthBinding('group-0')).toBeUndefined();
+    expect(particleMaterialSceneDepthBinding('view-only')).toBeUndefined();
+    expect(particleMaterialSceneDepthBinding('render-material')).toBeUndefined();
+  });
+
   it('does not mistake an ordinary Forward pass for a particle shader', () => {
     const material: MaterialAsset = {
       kind: 'material',

package/src/__tests__/stage-plan.integration.test.ts

@@ -1,6 +1,6 @@
 import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
-import type { RenderFeaturePlan } from '@forgeax/engine-render';
+import { createSceneDataCatalog, type RenderFeaturePlan } from '@forgeax/engine-render';
 import type { VfxGpuTickIntent } from '@forgeax/engine-vfx';
 import { describe, expect, it } from 'vitest';
 import { freezeRenderFeaturePlan } from '../../../render/src/features/plan';
@@ -108,6 +108,12 @@ describe('VFX managed stage execution seam', () => {
           { name: 'scene-color', kind: 'color', format: 'rgba16float', sampleCount: 1 },
           { name: 'scene-depth', kind: 'depth', format: 'depth24plus', sampleCount: 1 },
         ],
+        sceneData: createSceneDataCatalog({
+          featureIdentity: feature.identity,
+          generation: 1,
+          planIdentity: `${feature.identity}:1`,
+          rgba16floatRenderable: true,
+        }),
       },
     );
 

package/src/feature/gpu-particle-feature.ts

@@ -25,6 +25,7 @@ import {
   createTopologyResourcePlan,
   PARTICLE_SHADER_IDENTIFIERS,
   particleMaterialPass,
+  particleMaterialSceneDepthBinding,
   particleMaterialUsesBindings,
 } from './particle-resources.js';
 import type { VfxStagePlanObservation, VfxValidatedStagePlan } from './stage-plan.js';
@@ -346,6 +347,11 @@ export function gpuParticleRenderFeature(
   return {
     identity: IDENTITY,
     requiredCapabilities: ['compute', 'indirectDrawing'],
+    // Generated emitter programs are first-use assets. They must hand a
+    // WebGPU module to the prepared feature pipeline without waiting for the
+    // diagnostic-only getCompilationInfo() round trip; pipeline creation still
+    // validates the module before the pass is submitted.
+    shaderModuleMode: 'immediate',
     requiredMaterialShaders: Object.values(PARTICLE_SHADER_IDENTIFIERS),
     extract: (context) => {
       const extracted: ExtractedWorld[] = [];
@@ -552,6 +558,14 @@ export function gpuParticleRenderFeature(
             const submesh =
               renderer.kind === 'mesh' ? mesh?.submeshes[renderer.submesh ?? 0] : undefined;
             const indexFormat = mesh?.indices instanceof Uint32Array ? 'uint32' : 'uint16';
+            const sceneDepthBinding = isBillboard
+              ? particleMaterialSceneDepthBinding(
+                  context.materialShaderBindingContract?.(materialPass.shader) ??
+                    (materialPass.shader === PARTICLE_SHADER_IDENTIFIERS.billboard
+                      ? 'view-and-scene-depth'
+                      : undefined),
+                )
+              : undefined;
             const instances = `${rendererPrefix}.instances`;
             const history = `${rendererPrefix}.history`;
             const projectionRuntime = `${rendererPrefix}.runtime`;
@@ -690,9 +704,9 @@ export function gpuParticleRenderFeature(
                   group: 0,
                   runtime: projectionRuntime,
                   instances,
-                  ...(isBillboard ? { sceneDepthBinding: 1 } : {}),
+                  ...(sceneDepthBinding === undefined ? {} : { sceneDepthBinding }),
                 },
-                ...(isBillboard && depthTarget !== undefined
+                ...(sceneDepthBinding !== undefined && depthTarget !== undefined
                   ? { logicalTargets: { sceneDepth: depthTarget.name } }
                   : {}),
               },
@@ -784,7 +798,7 @@ export function gpuParticleRenderFeature(
                       depthStoreOp: 'store',
                     },
                   }),
-              ...(isBillboard && depthTarget !== undefined
+              ...(sceneDepthBinding !== undefined && depthTarget !== undefined
                 ? { sampledTargets: [depthTarget.name] }
                 : {}),
               draws: [

package/src/feature/particle-resources.ts

@@ -1,3 +1,4 @@
+import type { RenderFeatureMaterialShaderBindingContract } from '@forgeax/engine-render';
 import {
   err,
   type MaterialAsset,
@@ -161,6 +162,23 @@ export function particleMaterialUsesBindings(material: MaterialAsset | undefined
   return (material?.parameters?.length ?? 0) > 0;
 }
 
+/**
+ * Return the scene-depth binding slot required by a particle material shader.
+ *
+ * Custom particle shaders historically bind only the sampled depth resource at
+ * group(0)/binding(0), while the renderer-owned billboard shader also consumes
+ * the view UBO at binding(0) and therefore uses depth at binding(1). Keep this
+ * choice derived from the renderer contract instead of assuming every
+ * billboard has the built-in layout.
+ */
+export function particleMaterialSceneDepthBinding(
+  contract: RenderFeatureMaterialShaderBindingContract | undefined,
+): 0 | 1 | undefined {
+  if (contract === 'group-0-resource') return 0;
+  if (contract === 'view-and-scene-depth') return 1;
+  return undefined;
+}
+
 function floatAttribute(value: ArrayBuffer | Float32Array | Uint16Array | undefined): Float32Array {
   if (value instanceof Float32Array) return value;
   if (value instanceof Uint16Array) return Float32Array.from(value);

package/src/shaders/beam.wgsl

@@ -1,6 +1,4 @@
 #define_import_path forgeax::vfx-render.particles.beam
-#import forgeax_view::common::{View, FogViewParams, FogRay, view}
-#import forgeax_view::fog::{apply_fog}
 
 struct BeamInput {
   @location(0) start: vec3<f32>,
@@ -15,29 +13,6 @@ struct VertexOutput {
   @location(1) clip_position: vec3<f32>,
 }
 
-fn fogWorldPoint(ndc: vec3<f32>) -> vec3<f32> {
-  let homogeneous = view.inverseViewProj * vec4<f32>(ndc, 1.0);
-  let divisor = select(1.0, homogeneous.w, abs(homogeneous.w) > 0.000001);
-  return homogeneous.xyz / divisor;
-}
-
-fn fogRayFromNdc(ndc: vec3<f32>) -> FogRay {
-  let worldPosition = fogWorldPoint(ndc);
-  let nearPosition = fogWorldPoint(vec3<f32>(ndc.xy, 0.0));
-  let farPosition = fogWorldPoint(vec3<f32>(ndc.xy, 1.0));
-  let perspective = view.temporalProjection.z < 0.5;
-  let perspectiveVector = worldPosition - view.cameraPos;
-  let orthographicVector = farPosition - nearPosition;
-  let direction = normalize(select(orthographicVector, perspectiveVector, perspective));
-  let origin = select(nearPosition, view.cameraPos, perspective);
-  let ray_distance = select(
-    max(dot(worldPosition - nearPosition, direction), 0.0),
-    length(perspectiveVector),
-    perspective,
-  );
-  return FogRay(origin, direction, ray_distance);
-}
-
 @vertex
 fn vs_main(input: BeamInput, @builtin(vertex_index) vertexIndex: u32) -> VertexOutput {
   let corners = array<vec2<f32>, 6>(
@@ -60,10 +35,5 @@ fn vs_main(input: BeamInput, @builtin(vertex_index) vertexIndex: u32) -> VertexO
 fn fs_main(input: VertexOutput) -> @location(0) vec4<f32> {
   let base = vec4<f32>(0.7, 0.2, 1.0, 1.0);
   let alpha = base.a * input.color.a;
-  let fogged = apply_fog(
-    view.fog,
-    fogRayFromNdc(input.clip_position),
-    vec4<f32>(base.rgb * input.color.rgb, alpha),
-  );
-  return vec4<f32>(fogged.rgb * fogged.a, fogged.a);
+  return vec4<f32>(base.rgb * input.color.rgb * alpha, alpha);
 }

package/src/shaders/billboard.wgsl

@@ -1,8 +1,8 @@
 #define_import_path forgeax::vfx-render.particles.billboard
-#import forgeax_view::common::{View, FogViewParams, FogRay, view}
-#import forgeax_view::fog::{apply_fog}
-
-@group(0) @binding(1) var scene_depth: texture_depth_2d;
+// The analytic fog producer was removed from this shader. Billboard
+// soft-particle depth is therefore the sole group-0 resource again, matching
+// the prepared group-0-resource layout and its binding resolver.
+@group(0) @binding(0) var scene_depth: texture_depth_2d;
 
 struct VertexOutput {
   @builtin(position) position: vec4<f32>,
@@ -51,29 +51,6 @@ fn softParticle(position: vec4<f32>, alpha: f32, fadeDistance: f32) -> f32 {
   return alpha * softParticleFactor(position.z, sceneDepth, fadeDistance);
 }
 
-fn fogWorldPoint(ndc: vec3<f32>) -> vec3<f32> {
-  let homogeneous = view.inverseViewProj * vec4<f32>(ndc, 1.0);
-  let divisor = select(1.0, homogeneous.w, abs(homogeneous.w) > 0.000001);
-  return homogeneous.xyz / divisor;
-}
-
-fn fogRayFromNdc(ndc: vec3<f32>) -> FogRay {
-  let worldPosition = fogWorldPoint(ndc);
-  let nearPosition = fogWorldPoint(vec3<f32>(ndc.xy, 0.0));
-  let farPosition = fogWorldPoint(vec3<f32>(ndc.xy, 1.0));
-  let perspective = view.temporalProjection.z < 0.5;
-  let perspectiveVector = worldPosition - view.cameraPos;
-  let orthographicVector = farPosition - nearPosition;
-  let direction = normalize(select(orthographicVector, perspectiveVector, perspective));
-  let origin = select(nearPosition, view.cameraPos, perspective);
-  let ray_distance = select(
-    max(dot(worldPosition - nearPosition, direction), 0.0),
-    length(perspectiveVector),
-    perspective,
-  );
-  return FogRay(origin, direction, ray_distance);
-}
-
 struct VertexInput {
   @location(0) position: vec3<f32>,
   @location(1) right: vec2<f32>,
@@ -127,6 +104,5 @@ fn fs_main(input: VertexOutput) -> @location(0) vec4<f32> {
   let alpha = softParticle(input.position, input.color.a * edge, input.fade_distance);
   let sheetPulse = 0.82 + 0.18 * fract(input.sheet_frame * 0.618 + input.sheet_uv.x + input.sheet_uv.y);
   let rgb = (input.color.rgb + emissive * (0.35 + core * 0.65) + vec3<f32>(highlight)) * sheetPulse;
-  let fogged = apply_fog(view.fog, fogRayFromNdc(input.clip_position), vec4<f32>(rgb, alpha));
-  return vec4<f32>(fogged.rgb * fogged.a, fogged.a);
+  return vec4<f32>(rgb * alpha, alpha);
 }

package/src/shaders/mesh.wgsl

@@ -1,6 +1,4 @@
 #define_import_path forgeax::vfx-render.particles.mesh
-#import forgeax_view::common::{View, FogViewParams, FogRay, view}
-#import forgeax_view::fog::{apply_fog}
 
 struct VertexOutput {
   @builtin(position) position: vec4<f32>,
@@ -26,29 +24,6 @@ struct VertexInput {
   @location(11) surface: vec4<f32>,
 };
 
-fn fogWorldPoint(ndc: vec3<f32>) -> vec3<f32> {
-  let homogeneous = view.inverseViewProj * vec4<f32>(ndc, 1.0);
-  let divisor = select(1.0, homogeneous.w, abs(homogeneous.w) > 0.000001);
-  return homogeneous.xyz / divisor;
-}
-
-fn fogRayFromNdc(ndc: vec3<f32>) -> FogRay {
-  let worldPosition = fogWorldPoint(ndc);
-  let nearPosition = fogWorldPoint(vec3<f32>(ndc.xy, 0.0));
-  let farPosition = fogWorldPoint(vec3<f32>(ndc.xy, 1.0));
-  let perspective = view.temporalProjection.z < 0.5;
-  let perspectiveVector = worldPosition - view.cameraPos;
-  let orthographicVector = farPosition - nearPosition;
-  let direction = normalize(select(orthographicVector, perspectiveVector, perspective));
-  let origin = select(nearPosition, view.cameraPos, perspective);
-  let ray_distance = select(
-    max(dot(worldPosition - nearPosition, direction), 0.0),
-    length(perspectiveVector),
-    perspective,
-  );
-  return FogRay(origin, direction, ray_distance);
-}
-
 @vertex
 fn vs_main(input: VertexInput) -> VertexOutput {
   var output: VertexOutput;
@@ -89,10 +64,6 @@ fn fs_main(input: VertexOutput) -> @location(0) vec4<f32> {
   let specular_color = mix(dielectric, input.color.rgb, metallic);
   let lit = input.color.rgb * diffuse * (1.0 - metallic * 0.55);
   let emissive = input.emissive_intensity.rgb * input.emissive_intensity.a;
-  let fogged = apply_fog(
-    view.fog,
-    fogRayFromNdc(input.clip_position),
-    vec4<f32>(lit + specular_color * specular + vec3<f32>(coat) + emissive, input.color.a),
-  );
-  return vec4<f32>(fogged.rgb * fogged.a, fogged.a);
+  let rgb = lit + specular_color * specular + vec3<f32>(coat) + emissive;
+  return vec4<f32>(rgb * input.color.a, input.color.a);
 }

package/src/shaders/ribbon.wgsl

@@ -1,6 +1,4 @@
 #define_import_path forgeax::vfx-render.particles.ribbon
-#import forgeax_view::common::{View, FogViewParams, FogRay, view}
-#import forgeax_view::fog::{apply_fog}
 
 struct SegmentInput {
   @location(0) start: vec3<f32>,
@@ -15,29 +13,6 @@ struct VertexOutput {
   @location(1) clip_position: vec3<f32>,
 }
 
-fn fogWorldPoint(ndc: vec3<f32>) -> vec3<f32> {
-  let homogeneous = view.inverseViewProj * vec4<f32>(ndc, 1.0);
-  let divisor = select(1.0, homogeneous.w, abs(homogeneous.w) > 0.000001);
-  return homogeneous.xyz / divisor;
-}
-
-fn fogRayFromNdc(ndc: vec3<f32>) -> FogRay {
-  let worldPosition = fogWorldPoint(ndc);
-  let nearPosition = fogWorldPoint(vec3<f32>(ndc.xy, 0.0));
-  let farPosition = fogWorldPoint(vec3<f32>(ndc.xy, 1.0));
-  let perspective = view.temporalProjection.z < 0.5;
-  let perspectiveVector = worldPosition - view.cameraPos;
-  let orthographicVector = farPosition - nearPosition;
-  let direction = normalize(select(orthographicVector, perspectiveVector, perspective));
-  let origin = select(nearPosition, view.cameraPos, perspective);
-  let ray_distance = select(
-    max(dot(worldPosition - nearPosition, direction), 0.0),
-    length(perspectiveVector),
-    perspective,
-  );
-  return FogRay(origin, direction, ray_distance);
-}
-
 @vertex
 fn vs_main(input: SegmentInput, @builtin(vertex_index) vertexIndex: u32) -> VertexOutput {
   let corners = array<vec2<f32>, 6>(
@@ -60,10 +35,5 @@ fn vs_main(input: SegmentInput, @builtin(vertex_index) vertexIndex: u32) -> Vert
 fn fs_main(input: VertexOutput) -> @location(0) vec4<f32> {
   let base = vec4<f32>(0.2, 0.7, 1.0, 0.9);
   let alpha = base.a * input.color.a;
-  let fogged = apply_fog(
-    view.fog,
-    fogRayFromNdc(input.clip_position),
-    vec4<f32>(base.rgb * input.color.rgb, alpha),
-  );
-  return fogged;
+  return vec4<f32>(base.rgb * input.color.rgb * alpha, alpha);
 }

package/src/shaders/trail.wgsl

@@ -1,6 +1,4 @@
 #define_import_path forgeax::vfx-render.particles.trail
-#import forgeax_view::common::{View, FogViewParams, FogRay, view}
-#import forgeax_view::fog::{apply_fog}
 
 struct SegmentInput {
   @location(0) start: vec3<f32>,
@@ -15,29 +13,6 @@ struct VertexOutput {
   @location(1) clip_position: vec3<f32>,
 }
 
-fn fogWorldPoint(ndc: vec3<f32>) -> vec3<f32> {
-  let homogeneous = view.inverseViewProj * vec4<f32>(ndc, 1.0);
-  let divisor = select(1.0, homogeneous.w, abs(homogeneous.w) > 0.000001);
-  return homogeneous.xyz / divisor;
-}
-
-fn fogRayFromNdc(ndc: vec3<f32>) -> FogRay {
-  let worldPosition = fogWorldPoint(ndc);
-  let nearPosition = fogWorldPoint(vec3<f32>(ndc.xy, 0.0));
-  let farPosition = fogWorldPoint(vec3<f32>(ndc.xy, 1.0));
-  let perspective = view.temporalProjection.z < 0.5;
-  let perspectiveVector = worldPosition - view.cameraPos;
-  let orthographicVector = farPosition - nearPosition;
-  let direction = normalize(select(orthographicVector, perspectiveVector, perspective));
-  let origin = select(nearPosition, view.cameraPos, perspective);
-  let ray_distance = select(
-    max(dot(worldPosition - nearPosition, direction), 0.0),
-    length(perspectiveVector),
-    perspective,
-  );
-  return FogRay(origin, direction, ray_distance);
-}
-
 @vertex
 fn vs_main(input: SegmentInput, @builtin(vertex_index) vertexIndex: u32) -> VertexOutput {
   let corners = array<vec2<f32>, 6>(
@@ -68,10 +43,5 @@ fn vs_main(input: SegmentInput, @builtin(vertex_index) vertexIndex: u32) -> Vert
 fn fs_main(input: VertexOutput) -> @location(0) vec4<f32> {
   let base = vec4<f32>(0.8, 0.35, 0.1, 1.0);
   let alpha = base.a * input.color.a;
-  let fogged = apply_fog(
-    view.fog,
-    fogRayFromNdc(input.clip_position),
-    vec4<f32>(base.rgb * input.color.rgb, alpha),
-  );
-  return vec4<f32>(fogged.rgb * fogged.a, fogged.a);
+  return vec4<f32>(base.rgb * input.color.rgb * alpha, alpha);
 }