@forgeax/engine-vfx-render 0.1.27 → 0.1.29

package/src/feature/particle-resources.ts

@@ -2,15 +2,16 @@ import type { RenderFeatureMaterialShaderBindingContract } from '@forgeax/engine
 import {
   err,
   type MaterialAsset,
+  type MaterialParticleInput,
   type MaterialRenderState,
   type MeshAsset,
   ok,
   type Result,
 } from '@forgeax/engine-types';
-import type { ParticleRendererSource } from '@forgeax/engine-vfx';
+import type { ParticleRendererSourceV3 } from '@forgeax/engine-vfx';
 
-type ParticleRendererKind = ParticleRendererSource['kind'];
-type ParticleTopologyRenderer = Extract<ParticleRendererSource, { readonly capacity: number }>;
+type ParticleRendererKind = ParticleRendererSourceV3['kind'];
+type ParticleTopologyRenderer = Extract<ParticleRendererSourceV3, { readonly capacity: number }>;
 type ParticleTopologyKind = ParticleTopologyRenderer['kind'];
 
 export const PARTICLE_SHADER_IDENTIFIERS = Object.freeze({
@@ -21,6 +22,15 @@ export const PARTICLE_SHADER_IDENTIFIERS = Object.freeze({
   beam: 'forgeax::vfx-render.particles.beam',
 });
 
+/** Built-in shader variants with one explicit vec4 material-input lane block. */
+export const PARTICLE_INPUT_SHADER_IDENTIFIERS = Object.freeze({
+  billboard: 'forgeax::vfx-render.particles.billboard-inputs',
+  mesh: 'forgeax::vfx-render.particles.mesh-inputs',
+  ribbon: 'forgeax::vfx-render.particles.ribbon-inputs',
+  trail: 'forgeax::vfx-render.particles.trail-inputs',
+  beam: 'forgeax::vfx-render.particles.beam-inputs',
+});
+
 export interface TopologyResourcePlan {
   readonly topology: ParticleTopologyKind;
   readonly capacity: number;
@@ -50,7 +60,7 @@ export function createTopologyResourcePlan(
       hint: 'declare a ribbon, trail, or beam renderer',
       detail: { path: 'renderer' },
     });
-  const value = renderer as Partial<ParticleRendererSource> & Record<string, unknown>;
+  const value = renderer as Partial<ParticleRendererSourceV3> & Record<string, unknown>;
   if (value.kind !== 'ribbon' && value.kind !== 'trail' && value.kind !== 'beam')
     return err({
       code: 'vfx-topology-resource-invalid',
@@ -138,7 +148,7 @@ export interface ParticleMaterialPass {
   readonly renderState?: MaterialRenderState;
 }
 
-type ParticleBlendMode = Extract<ParticleRendererSource, { readonly kind: 'billboard' }>['blend'];
+type ParticleBlendMode = Extract<ParticleRendererSourceV3, { readonly kind: 'billboard' }>['blend'];
 
 const PARTICLE_PREMULTIPLIED_ALPHA_BLEND: NonNullable<MaterialRenderState['blend']> = {
   color: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
@@ -159,16 +169,200 @@ const PARTICLE_ADDITIVE_BLEND: NonNullable<MaterialRenderState['blend']> = {
 export function particleMaterialPass(
   kind: ParticleRendererKind,
   material: MaterialAsset | undefined,
+  hasParticleInputs = false,
 ): ParticleMaterialPass {
   const pass = material?.passes?.find((candidate) => candidate.name === `particle-${kind}`);
+  const renderState =
+    pass?.renderState ??
+    (kind === 'mesh'
+      ? material?.passes?.find((candidate) => {
+          const tags = candidate.renderState?.tags;
+          return (
+            candidate.name === 'forward' ||
+            (typeof tags === 'object' &&
+              tags !== null &&
+              'LightMode' in tags &&
+              tags.LightMode === 'Forward')
+          );
+        })?.renderState
+      : undefined);
   return {
-    shader: pass?.program.module ?? PARTICLE_SHADER_IDENTIFIERS[kind],
-    ...(pass?.renderState === undefined
-      ? {}
-      : { renderState: pass.renderState as MaterialRenderState }),
+    shader:
+      pass?.program.module ??
+      (hasParticleInputs
+        ? PARTICLE_INPUT_SHADER_IDENTIFIERS[kind]
+        : PARTICLE_SHADER_IDENTIFIERS[kind]),
+    ...(renderState === undefined ? {} : { renderState: renderState as MaterialRenderState }),
   };
 }
 
+export interface PreparedParticleMaterialInputs {
+  /** The exact declarations requested by this renderer, in authored order. */
+  readonly definitions: readonly MaterialParticleInput[];
+  /** Number of vec4 lanes reserved in the per-particle instance stream. */
+  readonly lanes: number;
+  /** Byte width of the per-particle input projection. */
+  readonly stride: number;
+}
+
+export interface ParticleMaterialInputPreparationError {
+  readonly code:
+    | 'vfx-material-input-missing'
+    | 'vfx-material-input-wrong-type'
+    | 'vfx-material-input-stale'
+    | 'vfx-material-input-duplicate';
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: {
+    readonly material?: string;
+    readonly name?: string;
+    readonly lane?: number;
+    readonly path?: string;
+  };
+}
+
+const EMPTY_PARTICLE_MATERIAL_INPUTS: PreparedParticleMaterialInputs = Object.freeze({
+  definitions: Object.freeze([]),
+  lanes: 0,
+  stride: 0,
+});
+
+function particleInputFailure(
+  code: ParticleMaterialInputPreparationError['code'],
+  expected: string,
+  hint: string,
+  detail: ParticleMaterialInputPreparationError['detail'],
+): Result<never, ParticleMaterialInputPreparationError> {
+  return err({ code, expected, hint, detail });
+}
+
+function isParticleInputType(value: unknown): value is MaterialParticleInput['type'] {
+  return value === 'f32' || value === 'vec2<f32>' || value === 'vec3<f32>' || value === 'vec4<f32>';
+}
+
+function isParticleInputVisibility(value: unknown): value is MaterialParticleInput['visibility'] {
+  return value === 'vertex' || value === 'fragment' || value === 'vertex-fragment';
+}
+
+function validParticleInput(value: unknown): value is MaterialParticleInput {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return false;
+  const input = value as Record<string, unknown>;
+  return (
+    typeof input.name === 'string' &&
+    /^[A-Za-z_][A-Za-z0-9_]*$/.test(input.name) &&
+    isParticleInputType(input.type) &&
+    isParticleInputVisibility(input.visibility) &&
+    typeof input.lane === 'number' &&
+    Number.isInteger(input.lane) &&
+    input.lane >= 0 &&
+    input.lane < 4
+  );
+}
+
+function sameParticleInput(left: MaterialParticleInput, right: MaterialParticleInput): boolean {
+  return (
+    left.name === right.name &&
+    left.type === right.type &&
+    left.visibility === right.visibility &&
+    left.lane === right.lane
+  );
+}
+
+/**
+ * Validate and prepare the material-side particle-input bridge.
+ *
+ * The returned stride is added to the renderer-owned GPU instance stream; no
+ * CPU mirror or per-frame upload is created. Reflection is required when the
+ * renderer came from a cooked effect so an old material/program pair cannot
+ * silently bind a different input layout.
+ */
+export function prepareParticleMaterialInputs(
+  renderer: ParticleRendererSourceV3,
+  material: MaterialAsset | undefined,
+  reflected?: readonly MaterialParticleInput[],
+): Result<PreparedParticleMaterialInputs, ParticleMaterialInputPreparationError> {
+  const requested = renderer.materialInputs ?? [];
+  if (requested.length === 0) return ok(EMPTY_PARTICLE_MATERIAL_INPUTS);
+  if (new Set(requested).size !== requested.length) {
+    return particleInputFailure(
+      'vfx-material-input-duplicate',
+      'unique particle input names per renderer',
+      'remove the duplicate renderer material input and recook the effect',
+      { material: renderer.material, path: 'renderer.materialInputs' },
+    );
+  }
+  const definitions = material?.particleInputs;
+  if (definitions === undefined) {
+    return particleInputFailure(
+      'vfx-material-input-missing',
+      `material ${renderer.material} to declare particleInputs`,
+      'add the requested typed input to MaterialAsset and recook the material before the VFX effect',
+      { material: renderer.material, path: 'material.particleInputs' },
+    );
+  }
+  const names = new Set<string>();
+  const lanes = new Set<number>();
+  for (const [index, candidate] of definitions.entries()) {
+    if (!validParticleInput(candidate)) {
+      return particleInputFailure(
+        'vfx-material-input-wrong-type',
+        'particleInputs entries with a supported type, visibility, and lane',
+        'repair the material particleInputs declaration and recook it',
+        { material: renderer.material, path: `material.particleInputs[${index}]` },
+      );
+    }
+    if (names.has(candidate.name) || lanes.has(candidate.lane)) {
+      return particleInputFailure(
+        'vfx-material-input-duplicate',
+        'unique particle input names and lanes',
+        'assign one lane to one input name and recook the material',
+        { material: renderer.material, name: candidate.name, lane: candidate.lane },
+      );
+    }
+    names.add(candidate.name);
+    lanes.add(candidate.lane);
+  }
+  const selectedDefinitions: MaterialParticleInput[] = [];
+  for (const name of requested) {
+    const input = definitions.find((candidate) => candidate.name === name);
+    if (input === undefined) {
+      return particleInputFailure(
+        'vfx-material-input-missing',
+        `material ${renderer.material} to declare particle input ${name}`,
+        'add the requested input to MaterialAsset.particleInputs and recook both assets',
+        { material: renderer.material, name, path: 'renderer.materialInputs' },
+      );
+    }
+    selectedDefinitions.push(input);
+  }
+  if (reflected === undefined) {
+    return particleInputFailure(
+      'vfx-material-input-stale',
+      'cooked renderer reflection to carry the material input declarations',
+      'recook the VFX effect with the current material artifact catalog',
+      { material: renderer.material, path: 'effect.reflection.renderers.materialInputDefinitions' },
+    );
+  }
+  for (const input of selectedDefinitions) {
+    const cooked = reflected.find((candidate) => candidate.name === input.name);
+    if (cooked === undefined || !sameParticleInput(input, cooked)) {
+      return particleInputFailure(
+        'vfx-material-input-stale',
+        `the cooked declaration for material input ${input.name} to match MaterialAsset`,
+        'recook the VFX effect and material together so names, types, visibility, and lanes agree',
+        { material: renderer.material, name: input.name, lane: input.lane },
+      );
+    }
+  }
+  const lanesUsed = selectedDefinitions.map((input) => input.lane);
+  const lanesCount = Math.max(...lanesUsed, -1) + 1;
+  return ok({
+    definitions: Object.freeze([...selectedDefinitions]),
+    lanes: lanesCount,
+    stride: lanesCount * 16,
+  });
+}
+
 /**
  * Resolve the default pipeline state for a particle renderer.
  *
@@ -220,8 +414,9 @@ export function particleMaterialUsesBindings(material: MaterialAsset | undefined
 export function particleMaterialSceneDepthBinding(
   contract: RenderFeatureMaterialShaderBindingContract | undefined,
 ): 0 | 1 | undefined {
-  if (contract === 'group-0-resource') return 0;
-  if (contract === 'view-and-scene-depth') return 1;
+  if (contract === 'group-0-resource' || contract === 'render-material-with-scene-depth') return 0;
+  if (contract === 'view-and-scene-depth' || contract === 'render-material-and-scene-depth')
+    return 1;
   return undefined;
 }
 
@@ -257,3 +452,20 @@ export function canonicalMeshVertices(mesh: MeshAsset): Float32Array {
   }
   return result;
 }
+
+// Runtime asset publications are ordinary-object frozen snapshots. Keep the
+// derived 12-float particle vertex stream by that publication identity so a
+// VFX feature with several emitters does not rebuild the same mesh projection
+// on every frame. Mutable hand-authored meshes deliberately bypass this cache;
+// their attribute values remain observable on the next call instead of being
+// hidden behind an object-identity assumption.
+const canonicalMeshVertexCache = new WeakMap<MeshAsset, Float32Array>();
+
+export function canonicalMeshVerticesCached(mesh: MeshAsset): Float32Array {
+  if (!Object.isFrozen(mesh)) return canonicalMeshVertices(mesh);
+  const cached = canonicalMeshVertexCache.get(mesh);
+  if (cached !== undefined) return cached;
+  const derived = canonicalMeshVertices(mesh);
+  canonicalMeshVertexCache.set(mesh, derived);
+  return derived;
+}

package/src/host/data-interface-providers.ts

@@ -14,6 +14,8 @@ export type { VfxDataInterfaceProvider } from '@forgeax/engine-vfx';
 
 export interface VfxDataInterfaceAvailabilitySource {
   readonly available: (generation: number) => boolean;
+  readonly sampleCount?: 1 | 4;
+  readonly resource?: (generation: number) => VfxDataInterfaceResource['resource'] | undefined;
 }
 
 export interface VfxDataInterfaceRegistry {
@@ -60,11 +62,22 @@ function availableProvider<K extends VfxDataInterfaceKind>(
           detail: { token, providerId: `${token}-provider` },
         });
       }
+      const prepared = source.resource?.(generation);
+      if (prepared === undefined) {
+        return err({
+          code: 'vfx-data-interface-missing',
+          expected: `a resident ${kind} resource for ${token}`,
+          hint: `provide the generation-owned ${kind} resource before rendering`,
+          detail: { token, providerId: `${token}-provider` },
+        });
+      }
       const resource: VfxDataInterfaceResource = {
         token,
         kind,
         bindingType,
         generation,
+        ...(source.sampleCount === undefined ? {} : { sampleCount: source.sampleCount }),
+        resource: prepared,
       };
       return ok(resource);
     },
@@ -83,6 +96,12 @@ export function createSceneDepthProvider(
   return availableProvider('vfx:scene-depth', 'scene-depth', 'sampled-depth', source);
 }
 
+export function createNoiseProvider(
+  source: VfxDataInterfaceAvailabilitySource,
+): VfxDataInterfaceProvider<'noise'> {
+  return availableProvider('vfx:noise', 'noise', 'sampled-float', source);
+}
+
 export function createVfxDataInterfaceRegistry(
   initialProviders: readonly VfxDataInterfaceProvider[] = [],
 ): VfxDataInterfaceRegistry {

package/src/host/vfx-runtime-host.ts

@@ -14,6 +14,8 @@ import type {
 } from '@forgeax/engine-types';
 import { err, ok } from '@forgeax/engine-types';
 import type {
+  ParticleEffectInstance,
+  VfxChannelInput,
   VfxDataInterfaceError,
   VfxDataInterfaceProvider,
   VfxDataInterfaceRequirement,
@@ -76,13 +78,15 @@ export interface VfxRuntimeHostControlError {
     | 'vfx-host-control-world-detached'
     | 'vfx-host-control-stale-generation'
     | 'vfx-host-control-runtime-unavailable'
-    | 'vfx-host-control-player-unavailable';
+    | 'vfx-host-control-player-unavailable'
+    | 'vfx-host-control-instance-rejected';
   readonly expected: string;
   readonly hint: string;
   readonly detail: {
     readonly requestedGeneration?: number;
     readonly currentGeneration?: number;
     readonly player?: EntityHandle;
+    readonly causeCode?: string;
   };
 }
 
@@ -113,6 +117,30 @@ export interface VfxRuntimeHostControl {
     },
     VfxRuntimeHostControlError
   >;
+  patchPlayerParameters(input: {
+    readonly player: EntityHandle;
+    readonly values: Partial<VfxValueMap>;
+  }): Result<
+    {
+      readonly state: 'queued';
+      readonly generation: number;
+      readonly parameterGeneration: number;
+      readonly pendingPatchCount: number;
+    },
+    VfxRuntimeHostControlError
+  >;
+  submitChannel(input: {
+    readonly player: EntityHandle;
+    readonly channel: string;
+    readonly payload: VfxChannelInput['payload'];
+    readonly sequence: number;
+  }): Result<
+    {
+      readonly state: 'queued';
+      readonly generation: number;
+    },
+    VfxRuntimeHostControlError
+  >;
 }
 
 export interface VfxRuntimeHost {
@@ -320,6 +348,41 @@ export function createVfxRuntimeHost(options: VfxRuntimeHostOptions): VfxRuntime
         }
         return ok(action(world.getResource<VfxGpuRuntime>(VFX_GPU_RUNTIME_RESOURCE_KEY)));
       };
+      type InstanceAction<T> =
+        | { readonly kind: 'value'; readonly value: T }
+        | { readonly kind: 'error'; readonly causeCode: string };
+      const withInstance = <T>(
+        player: EntityHandle,
+        action: (instance: ParticleEffectInstance) => Result<T, { readonly code: string }>,
+      ): Result<T, VfxRuntimeHostControlError> => {
+        const result = withRuntime(player, (runtime): InstanceAction<T> => {
+          const instance = runtime.getInstance(player);
+          if (instance === undefined) {
+            return { kind: 'error', causeCode: 'vfx-instance-unavailable' };
+          }
+          const outcome = action(instance);
+          return outcome.ok
+            ? { kind: 'value', value: outcome.value }
+            : { kind: 'error', causeCode: outcome.error.code };
+        });
+        if (!result.ok) return result;
+        if (result.value.kind === 'error') {
+          return err(
+            controlFailure(
+              'vfx-host-control-instance-rejected',
+              'the live typed VFX instance to accept this control input',
+              'run one fixed tick or repair the reflected instance contract before retrying',
+              {
+                requestedGeneration,
+                currentGeneration: requestedGeneration,
+                player,
+                causeCode: result.value.causeCode,
+              },
+            ),
+          );
+        }
+        return ok(result.value.value);
+      };
       const control: VfxRuntimeHostControl = {
         generation: requestedGeneration,
         replay: ({ player, replayInput }) =>
@@ -351,6 +414,23 @@ export function createVfxRuntimeHost(options: VfxRuntimeHostOptions): VfxRuntime
               generation: requestedGeneration,
             });
           }),
+        patchPlayerParameters: ({ player, values }) =>
+          withInstance(player, (instance) => {
+            const patched = instance.patch(values);
+            if (!patched.ok) return patched;
+            return ok({
+              state: 'queued' as const,
+              generation: requestedGeneration,
+              parameterGeneration: instance.generation,
+              pendingPatchCount: instance.pendingPatchCount,
+            });
+          }),
+        submitChannel: ({ player, channel, payload, sequence }) =>
+          withInstance(player, (instance) => {
+            const submitted = instance.submit({ channel, payload, sequence });
+            if (!submitted.ok) return submitted;
+            return ok({ state: 'queued' as const, generation: requestedGeneration });
+          }),
       };
       return ok(Object.freeze(control));
     },
@@ -377,7 +457,7 @@ export function createVfxRuntimeHost(options: VfxRuntimeHostOptions): VfxRuntime
           return err(
             failure(
               'vfx-host-loader-install-failed',
-              'the v2 VFX loader to be registered once',
+              'the Program v3 VFX loader to be registered once',
               'remove a conflicting particle-effect loader and retry attachWorld',
               cause,
             ),

package/src/index.ts

@@ -2,6 +2,7 @@
 
 export type { ParticleRenderCamera, ParticleRenderCameraSource } from './feature/camera.js';
 export {
+  encodeEventBuffer,
   encodeEventInputs,
   eventCapacity,
   eventCounterData,
@@ -16,9 +17,15 @@ export {
   resolveBillboardAdvancedState,
   topologyRecoveryHint,
 } from './feature/gpu-particle-feature.js';
+export type {
+  ParticleMaterialInputPreparationError,
+  PreparedParticleMaterialInputs,
+} from './feature/particle-resources.js';
 export {
   createTopologyResourcePlan,
+  PARTICLE_INPUT_SHADER_IDENTIFIERS,
   PARTICLE_SHADER_IDENTIFIERS,
+  prepareParticleMaterialInputs,
   topologyCapacitySnapshot,
 } from './feature/particle-resources.js';
 export type {
@@ -42,6 +49,7 @@ export type {
 } from './host/data-interface-providers.js';
 export {
   createCameraProvider,
+  createNoiseProvider,
   createSceneDepthProvider,
   createVfxDataInterfaceRegistry,
 } from './host/data-interface-providers.js';

package/src/shaders/beam-inputs.wgsl

@@ -0,0 +1,40 @@
+#define_import_path forgeax::vfx-render.particles.beam-inputs
+
+struct BeamInput {
+  @location(0) start: vec3<f32>,
+  @location(1) endpoint: vec3<f32>,
+  @location(2) color: vec4<f32>,
+  @location(3) properties: vec2<f32>,
+  @location(4) particle_inputs: vec4<f32>,
+}
+
+struct VertexOutput {
+  @builtin(position) position: vec4<f32>,
+  @location(0) color: vec4<f32>,
+  @location(2) across: f32,
+}
+
+@vertex
+fn vs_main(input: BeamInput, @builtin(vertex_index) vertexIndex: u32) -> VertexOutput {
+  let corners = array<vec2<f32>, 6>(
+    vec2<f32>(0.0, -1.0), vec2<f32>(1.0, -1.0), vec2<f32>(1.0, 1.0),
+    vec2<f32>(0.0, -1.0), vec2<f32>(1.0, 1.0), vec2<f32>(0.0, 1.0)
+  );
+  let corner = corners[vertexIndex];
+  let delta = input.endpoint.xy - input.start.xy;
+  let normal = normalize(vec2<f32>(-delta.y, delta.x) + vec2<f32>(0.000001, 0.0));
+  let point = mix(input.start, input.endpoint, corner.x);
+  let clipPosition = vec3<f32>(point.xy + normal * corner.y * input.properties.x, point.z);
+  var output: VertexOutput;
+  output.position = vec4<f32>(clipPosition, 1.0);
+  output.across = corner.y;
+  let heat = clamp(input.particle_inputs.x, 0.0, 1.0);
+  output.color = input.color * (0.35 + 0.65 * heat);
+  return output;
+}
+
+@fragment
+fn fs_main(input: VertexOutput) -> @location(0) vec4<f32> {
+  let alpha = input.color.a * (1.0 - smoothstep(0.15, 1.0, abs(input.across)));
+  return vec4<f32>(input.color.rgb * alpha, alpha);
+}

package/src/shaders/beam.wgsl

@@ -10,6 +10,7 @@ struct BeamInput {
 struct VertexOutput {
   @builtin(position) position: vec4<f32>,
   @location(0) color: vec4<f32>,
+  @location(2) across: f32,
   @location(1) clip_position: vec3<f32>,
 }
 
@@ -26,6 +27,7 @@ fn vs_main(input: BeamInput, @builtin(vertex_index) vertexIndex: u32) -> VertexO
   let clipPosition = vec3<f32>(point.xy + normal * corner.y * input.properties.x, point.z);
   var output: VertexOutput;
   output.position = vec4<f32>(clipPosition, 1.0);
+  output.across = corner.y;
   output.color = input.color;
   output.clip_position = clipPosition;
   return output;
@@ -33,7 +35,6 @@ fn vs_main(input: BeamInput, @builtin(vertex_index) vertexIndex: u32) -> VertexO
 
 @fragment
 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;
-  return vec4<f32>(base.rgb * input.color.rgb * alpha, alpha);
+  let alpha = input.color.a * (1.0 - smoothstep(0.15, 1.0, abs(input.across)));
+  return vec4<f32>(input.color.rgb * alpha, alpha);
 }

package/src/shaders/billboard-inputs.wgsl

@@ -0,0 +1,85 @@
+#define_import_path forgeax::vfx-render.particles.billboard-inputs
+@group(0) @binding(0) var scene_depth: texture_depth_2d;
+
+struct VertexOutput {
+  @builtin(position) position: vec4<f32>,
+  @location(0) color: vec4<f32>,
+  @location(1) local: vec2<f32>,
+  @location(2) emissive_intensity: vec4<f32>,
+  @location(3) surface: vec4<f32>,
+  @location(4) sheet_uv: vec2<f32>,
+  @location(5) sheet_frame: f32,
+  @location(6) fade_distance: f32,
+  @location(7) clip_position: vec3<f32>,
+};
+
+fn textureSheetUv(local: vec2<f32>, frame: u32, columns: u32, rows: u32) -> vec2<f32> {
+  let safeColumns = max(columns, 1u);
+  let safeRows = max(rows, 1u);
+  let cell = vec2<u32>(frame % safeColumns, frame / safeColumns);
+  return (local + vec2<f32>(1.0)) * 0.5 / vec2<f32>(f32(safeColumns), f32(safeRows)) +
+    vec2<f32>(f32(cell.x) / f32(safeColumns), f32(cell.y) / f32(safeRows));
+}
+
+fn softParticle(position: vec4<f32>, alpha: f32, fadeDistance: f32) -> f32 {
+  let pixel = vec2<i32>(position.xy);
+  let sceneDepth = textureLoad(scene_depth, pixel, 0);
+  if (fadeDistance <= 0.0) { return select(alpha, 0.0, position.z > sceneDepth); }
+  return alpha * clamp((sceneDepth - position.z) / fadeDistance, 0.0, 1.0);
+}
+
+struct VertexInput {
+  @location(0) position: vec3<f32>,
+  @location(1) right: vec2<f32>,
+  @location(2) up: vec2<f32>,
+  @location(3) particle_color: vec4<f32>,
+  @location(4) base_color: vec4<f32>,
+  @location(5) emissive_intensity: vec4<f32>,
+  @location(6) surface: vec4<f32>,
+  @location(7) advanced: vec4<f32>,
+  @location(8) texture_sheet: vec4<f32>,
+  @location(9) particle_inputs: vec4<f32>,
+};
+
+@vertex
+fn vs_main(input: VertexInput, @builtin(vertex_index) vertex_index: u32) -> VertexOutput {
+  let corners = array<vec2<f32>, 6>(
+    vec2<f32>(-1.0, -1.0), vec2<f32>(1.0, -1.0), vec2<f32>(1.0, 1.0),
+    vec2<f32>(-1.0, -1.0), vec2<f32>(1.0, 1.0), vec2<f32>(-1.0, 1.0)
+  );
+  let corner = corners[vertex_index] + input.advanced.xy * 2.0;
+  var output: VertexOutput;
+  let clipPosition = vec3<f32>(
+    input.position.xy + input.right * corner.x + input.up * corner.y,
+    input.position.z,
+  );
+  output.position = vec4<f32>(clipPosition, 1.0);
+  output.clip_position = clipPosition;
+  let heat = clamp(input.particle_inputs.x, 0.0, 1.0);
+  output.color = input.particle_color * input.base_color * (0.35 + 0.65 * heat);
+  output.local = corner;
+  output.emissive_intensity = input.emissive_intensity;
+  output.surface = input.surface;
+  output.sheet_uv = textureSheetUv(
+    corners[vertex_index], u32(input.advanced.z),
+    u32(input.texture_sheet.x), u32(input.texture_sheet.y),
+  );
+  output.sheet_frame = input.advanced.z;
+  output.fade_distance = input.texture_sheet.z;
+  return output;
+}
+
+@fragment
+fn fs_main(input: VertexOutput) -> @location(0) vec4<f32> {
+  let radius = length(input.local);
+  let edge = 1.0 - smoothstep(0.45, 1.0, radius);
+  let core = 1.0 - smoothstep(0.0, 0.42, radius);
+  let roughness = clamp(input.surface.y, 0.04, 1.0);
+  let clearcoat = clamp(input.surface.z, 0.0, 1.0);
+  let highlight = core * clearcoat * (1.0 - roughness * 0.65);
+  let emissive = input.emissive_intensity.rgb * input.emissive_intensity.a;
+  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;
+  return vec4<f32>(rgb * alpha, alpha);
+}