@forgeax/engine-vfx-render 0.1.2

package/src/feature/particle-resources.ts

@@ -0,0 +1,203 @@
+import type { RenderFeatureMaterialShaderBindingContract } from '@forgeax/engine-render';
+import {
+  err,
+  type MaterialAsset,
+  type MaterialRenderState,
+  type MeshAsset,
+  ok,
+  type Result,
+} from '@forgeax/engine-types';
+import type { ParticleRendererSource } from '@forgeax/engine-vfx';
+
+type ParticleRendererKind = ParticleRendererSource['kind'];
+type ParticleTopologyRenderer = Extract<ParticleRendererSource, { readonly capacity: number }>;
+type ParticleTopologyKind = ParticleTopologyRenderer['kind'];
+
+export const PARTICLE_SHADER_IDENTIFIERS = Object.freeze({
+  billboard: 'forgeax::vfx-render.particles.billboard',
+  mesh: 'forgeax::vfx-render.particles.mesh',
+  ribbon: 'forgeax::vfx-render.particles.ribbon',
+  trail: 'forgeax::vfx-render.particles.trail',
+  beam: 'forgeax::vfx-render.particles.beam',
+});
+
+export interface TopologyResourcePlan {
+  readonly topology: ParticleTopologyKind;
+  readonly capacity: number;
+  readonly vertexBytes: number;
+  readonly indexBytes: number;
+  readonly indirectBytes: number;
+  readonly resourceKey: string;
+  readonly historyLength?: number;
+  readonly stripKey?: 'alive-index';
+  readonly endpointField?: 'velocity';
+}
+
+export interface TopologyResourceError {
+  readonly code: 'vfx-topology-resource-invalid';
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: { readonly path: string };
+}
+
+export function createTopologyResourcePlan(
+  renderer: unknown,
+): Result<TopologyResourcePlan, TopologyResourceError> {
+  if (renderer === null || typeof renderer !== 'object' || Array.isArray(renderer))
+    return err({
+      code: 'vfx-topology-resource-invalid',
+      expected: 'a topology renderer object',
+      hint: 'declare a ribbon, trail, or beam renderer',
+      detail: { path: 'renderer' },
+    });
+  const value = renderer as Partial<ParticleRendererSource> & Record<string, unknown>;
+  if (value.kind !== 'ribbon' && value.kind !== 'trail' && value.kind !== 'beam')
+    return err({
+      code: 'vfx-topology-resource-invalid',
+      expected: 'ribbon, trail, or beam',
+      hint: 'do not alias topology output to billboard or mesh',
+      detail: { path: 'renderer.kind' },
+    });
+  if (
+    typeof value.capacity !== 'number' ||
+    !Number.isInteger(value.capacity) ||
+    value.capacity <= 0 ||
+    value.capacity > 65536
+  )
+    return err({
+      code: 'vfx-topology-resource-invalid',
+      expected: 'capacity in the range 1..65536',
+      hint: 'bound topology resources before allocating them',
+      detail: { path: 'renderer.capacity' },
+    });
+  const capacity = value.capacity;
+  if (value.kind === 'ribbon' && value.stripKey !== 'alive-index')
+    return err({
+      code: 'vfx-topology-resource-invalid',
+      expected: "stripKey 'alive-index'",
+      hint: 'use the managed alive-list order until a custom WGSL topology stage owns grouping',
+      detail: { path: 'renderer.stripKey' },
+    });
+  if (
+    value.kind === 'trail' &&
+    (typeof value.historyLength !== 'number' ||
+      !Number.isInteger(value.historyLength) ||
+      value.historyLength <= 0 ||
+      value.historyLength > 256)
+  )
+    return err({
+      code: 'vfx-topology-resource-invalid',
+      expected: 'historyLength in the range 1..256',
+      hint: 'bound trail history storage',
+      detail: { path: 'renderer.historyLength' },
+    });
+  if (value.kind === 'beam' && value.endpointField !== 'velocity')
+    return err({
+      code: 'vfx-topology-resource-invalid',
+      expected: "endpointField 'velocity'",
+      hint: 'use the managed velocity endpoint until a custom WGSL topology stage owns endpoints',
+      detail: { path: 'renderer.endpointField' },
+    });
+  const vertexStride = 12 * 4;
+  const segments =
+    value.kind === 'trail' ? capacity * Math.max(1, (value.historyLength as number) - 1) : capacity;
+  return ok({
+    topology: value.kind,
+    capacity,
+    vertexBytes: Math.max(vertexStride, segments * vertexStride),
+    indexBytes: 0,
+    indirectBytes: 20,
+    resourceKey: `vfx-topology-${value.kind}`,
+    ...(value.kind === 'ribbon' ? { stripKey: 'alive-index' as const } : {}),
+    ...(value.kind === 'trail' ? { historyLength: value.historyLength as number } : {}),
+    ...(value.kind === 'beam' ? { endpointField: 'velocity' as const } : {}),
+  });
+}
+
+export interface TopologyCapacityInput {
+  readonly requested: number;
+  readonly produced: number;
+  readonly degenerate?: number;
+}
+
+export function topologyCapacitySnapshot(plan: TopologyResourcePlan, input: TopologyCapacityInput) {
+  const produced = Math.max(0, Math.min(plan.capacity, input.produced));
+  const requested = Math.max(0, input.requested);
+  return {
+    topology: plan.topology,
+    capacity: plan.capacity,
+    produced,
+    dropped: Math.max(0, requested - produced),
+    overflow: Math.max(0, requested - plan.capacity),
+    degenerate: Math.max(0, input.degenerate ?? 0),
+  } as const;
+}
+
+export interface ParticleMaterialPass {
+  readonly shader: string;
+  readonly renderState?: MaterialRenderState;
+}
+
+/**
+ * Resolve the one material pass that is meaningful for a particle projection.
+ * A regular Forward pass is intentionally ignored: VFX vertex layouts are a
+ * different contract, so silently accepting it would compile the wrong input
+ * shape and make authored particle shaders appear to work while never running.
+ */
+export function particleMaterialPass(
+  kind: ParticleRendererKind,
+  material: MaterialAsset | undefined,
+): ParticleMaterialPass {
+  const pass = material?.passes?.find((candidate) => candidate.name === `particle-${kind}`);
+  return {
+    shader: pass?.program.module ?? PARTICLE_SHADER_IDENTIFIERS[kind],
+    ...(pass?.renderState === undefined
+      ? {}
+      : { renderState: pass.renderState as MaterialRenderState }),
+  };
+}
+
+/** Scene-depth is a shader binding contract, not a renderer-kind convention. */
+export function particleMaterialUsesSceneDepth(
+  contract: RenderFeatureMaterialShaderBindingContract | 'view-with-resource',
+): boolean {
+  return contract === 'group-0-resource' || contract === 'view-with-resource';
+}
+
+/** True when the authored particle shader consumes the standard material bind group. */
+export function particleMaterialUsesBindings(material: MaterialAsset | undefined): boolean {
+  return (material?.parameters?.length ?? 0) > 0;
+}
+
+function floatAttribute(value: ArrayBuffer | Float32Array | Uint16Array | undefined): Float32Array {
+  if (value instanceof Float32Array) return value;
+  if (value instanceof Uint16Array) return Float32Array.from(value);
+  return value === undefined ? new Float32Array() : new Float32Array(value);
+}
+
+export function canonicalMeshVertices(mesh: MeshAsset): Float32Array {
+  if (mesh.vertices.length > 0 && mesh.vertices.length % 12 === 0) return mesh.vertices;
+  const positions = floatAttribute(mesh.attributes.position);
+  const vertexCount = Math.floor(positions.length / 3);
+  const normals = floatAttribute(mesh.attributes.normal);
+  const uvs = floatAttribute(mesh.attributes.uv);
+  const tangents = floatAttribute(mesh.attributes.tangent);
+  const result = new Float32Array(vertexCount * 12);
+  for (let index = 0; index < vertexCount; index += 1) {
+    const target = index * 12;
+    result.set(positions.subarray(index * 3, index * 3 + 3), target);
+    result.set(
+      normals.length >= index * 3 + 3 ? normals.subarray(index * 3, index * 3 + 3) : [0, 0, 1],
+      target + 3,
+    );
+    result.set(
+      uvs.length >= index * 2 + 2 ? uvs.subarray(index * 2, index * 2 + 2) : [0, 0],
+      target + 6,
+    );
+    result.set(
+      tangents.length >= index * 4 + 4 ? tangents.subarray(index * 4, index * 4 + 4) : [1, 0, 0, 1],
+      target + 8,
+    );
+  }
+  return result;
+}

package/src/feature/stage-plan.ts

@@ -0,0 +1,282 @@
+import type { RenderFeatureGpuBindingsRef, RenderFeatureGpuDispatch } from '@forgeax/engine-render';
+import type { VfxGpuStageReflection } from '@forgeax/engine-vfx';
+
+const MANAGED_STAGES = new Set(['spawn', 'update', 'scan', 'compact']);
+const RESOURCE_NAMES = new Set([
+  'particles',
+  'runtime',
+  'aliveIndices',
+  'counters',
+  'indirect',
+  'scratch',
+  'billboardInstances',
+  'channelInputs',
+  'events',
+  'eventCounters',
+]);
+const STAGE_ID = /^[a-z][a-z0-9-]{0,31}$/;
+const ENTRY_POINT = /^forgeax_vfx_stage_[a-z][a-z0-9-]{0,31}_main$/;
+const MAX_ITERATIONS = 64;
+
+export interface VfxValidatedStage {
+  readonly id: string;
+  readonly entry: string;
+  readonly entryPoint: string;
+  readonly domain: 'particle';
+  readonly resources: readonly {
+    readonly name: string;
+    readonly access: VfxGpuStageReflection['resources'][number]['access'];
+  }[];
+  readonly dependsOn: readonly string[];
+  readonly iterationBudget: number;
+}
+
+export interface VfxStageReadiness {
+  readonly id: string;
+  readonly state: 'ready' | 'candidate-rejected' | 'stale' | 'rebuilding';
+  readonly generation: number;
+  readonly lastKnownGoodGeneration?: number;
+  readonly retryable: boolean;
+  readonly error?: string;
+}
+
+export interface VfxStagePlanObservation {
+  readonly validatedStagePlan: VfxValidatedStagePlan;
+  readonly stageReadiness: readonly VfxStageReadiness[];
+  readonly stageOutput: 'active' | 'last-known-good' | 'empty';
+  readonly lastKnownGoodStage:
+    | { readonly fingerprint: string; readonly generation: number }
+    | undefined;
+}
+
+export interface VfxValidatedStagePlan {
+  readonly stages: readonly VfxValidatedStage[];
+  readonly fingerprint: string;
+  readonly generation: number;
+}
+
+export interface VfxStagePlanError {
+  readonly code:
+    | 'stage-id-invalid'
+    | 'stage-entry-point-invalid'
+    | 'stage-domain-invalid'
+    | 'stage-resource-invalid'
+    | 'stage-dependency-invalid'
+    | 'stage-cycle'
+    | 'stage-budget-invalid';
+  readonly stageId: string;
+  readonly hint: string;
+}
+
+export type VfxStageRecovery = 'device-loss' | 'stale';
+
+function failure(
+  code: VfxStagePlanError['code'],
+  stageId: string,
+  hint: string,
+): { ok: false; error: VfxStagePlanError } {
+  return { ok: false, error: { code, stageId, hint } };
+}
+
+function stableStage(stage: VfxGpuStageReflection): VfxValidatedStage {
+  return {
+    id: stage.id,
+    entry: stage.entry,
+    entryPoint: stage.entryPoint,
+    domain: stage.domain,
+    resources: Object.freeze(
+      stage.resources.map((resource) => ({ name: resource.name, access: resource.access })),
+    ),
+    dependsOn: Object.freeze([...stage.dependsOn]),
+    iterationBudget: stage.iterationBudget,
+  };
+}
+
+/** Validate the compiler reflection before a RenderFeature can contribute it. */
+export function validatedStagePlan(
+  reflection: VfxGpuStageReflection[] | readonly VfxGpuStageReflection[] | undefined,
+  generation: number,
+):
+  | { readonly ok: true; readonly value: VfxValidatedStagePlan }
+  | { readonly ok: false; readonly error: VfxStagePlanError } {
+  const source = reflection ?? [];
+  const ids = new Set<string>();
+  const stages: VfxValidatedStage[] = [];
+  for (const stage of source) {
+    if (!STAGE_ID.test(stage.id) || ids.has(stage.id)) {
+      return failure(
+        'stage-id-invalid',
+        stage.id,
+        'recook the effect with unique bounded stage ids',
+      );
+    }
+    ids.add(stage.id);
+    if (stage.domain !== 'particle' || MANAGED_STAGES.has(stage.domain)) {
+      return failure('stage-domain-invalid', stage.id, 'use the managed particle dispatch domain');
+    }
+    if (!ENTRY_POINT.test(stage.entryPoint)) {
+      return failure(
+        'stage-entry-point-invalid',
+        stage.id,
+        'use the compiler-generated stage entry point',
+      );
+    }
+    if (
+      !Number.isInteger(stage.iterationBudget) ||
+      stage.iterationBudget < 1 ||
+      stage.iterationBudget > MAX_ITERATIONS
+    ) {
+      return failure(
+        'stage-budget-invalid',
+        stage.id,
+        'use an integer iteration budget from 1 through 64',
+      );
+    }
+    const resources = new Set<string>();
+    for (const resource of stage.resources) {
+      if (
+        !RESOURCE_NAMES.has(resource.name) ||
+        !['read', 'write', 'read-write'].includes(resource.access)
+      ) {
+        return failure(
+          'stage-resource-invalid',
+          stage.id,
+          'declare only managed VFX resources with a supported access mode',
+        );
+      }
+      if (resources.has(resource.name)) {
+        return failure(
+          'stage-resource-invalid',
+          stage.id,
+          'declare each managed VFX resource once',
+        );
+      }
+      resources.add(resource.name);
+    }
+    stages.push(stableStage(stage));
+  }
+  const byId = new Map(stages.map((stage) => [stage.id, stage]));
+  const visiting = new Set<string>();
+  const visited = new Set<string>();
+  const ordered: VfxValidatedStage[] = [];
+  const visit = (stage: VfxValidatedStage): VfxStagePlanError | undefined => {
+    if (visited.has(stage.id)) return undefined;
+    if (visiting.has(stage.id))
+      return {
+        code: 'stage-cycle',
+        stageId: stage.id,
+        hint: 'remove the stage dependency cycle and recook the effect',
+      };
+    visiting.add(stage.id);
+    for (const dependency of stage.dependsOn) {
+      if (MANAGED_STAGES.has(dependency)) continue;
+      const dependencyStage = byId.get(dependency);
+      if (dependencyStage === undefined) {
+        return {
+          code: 'stage-dependency-invalid',
+          stageId: stage.id,
+          hint: 'declare every stage dependency or use a managed stage',
+        };
+      }
+      const error = visit(dependencyStage);
+      if (error !== undefined) return error;
+    }
+    visiting.delete(stage.id);
+    visited.add(stage.id);
+    ordered.push(stage);
+    return undefined;
+  };
+  for (const stage of stages) {
+    const error = visit(stage);
+    if (error !== undefined) return { ok: false, error };
+  }
+  const normalized = Object.freeze(ordered);
+  return {
+    ok: true,
+    value: Object.freeze({
+      stages: normalized,
+      fingerprint: JSON.stringify(normalized),
+      generation,
+    }),
+  };
+}
+
+export function stageDispatches(
+  plan: VfxValidatedStagePlan,
+  workgroups: number,
+  bindings: RenderFeatureGpuBindingsRef,
+): readonly RenderFeatureGpuDispatch[] {
+  return plan.stages.map((stage) => ({
+    entryPoint: stage.entryPoint,
+    workgroups: [workgroups] as const,
+    bindings,
+  }));
+}
+
+export function observeStagePlan(
+  candidate: ReturnType<typeof validatedStagePlan>,
+  generation: number,
+  lastKnownGoodStage: VfxValidatedStagePlan | undefined,
+): VfxStagePlanObservation {
+  if (candidate.ok) {
+    return {
+      validatedStagePlan: candidate.value,
+      stageReadiness: candidate.value.stages.map((stage) => ({
+        id: stage.id,
+        state: 'ready' as const,
+        generation,
+        lastKnownGoodGeneration: generation,
+        retryable: false,
+      })),
+      stageOutput: candidate.value.stages.length === 0 ? 'empty' : 'active',
+      lastKnownGoodStage:
+        candidate.value.stages.length === 0
+          ? lastKnownGoodStage === undefined
+            ? undefined
+            : {
+                fingerprint: lastKnownGoodStage.fingerprint,
+                generation: lastKnownGoodStage.generation,
+              }
+          : { fingerprint: candidate.value.fingerprint, generation },
+    };
+  }
+  const retained = lastKnownGoodStage ?? { stages: [], fingerprint: '', generation };
+  return {
+    validatedStagePlan: retained,
+    stageReadiness: [
+      {
+        id: candidate.error.stageId,
+        state: 'candidate-rejected',
+        generation,
+        ...(lastKnownGoodStage === undefined
+          ? {}
+          : { lastKnownGoodGeneration: lastKnownGoodStage.generation }),
+        retryable: true,
+        error: candidate.error.code,
+      },
+    ],
+    stageOutput: lastKnownGoodStage === undefined ? 'empty' : 'last-known-good',
+    lastKnownGoodStage:
+      lastKnownGoodStage === undefined
+        ? undefined
+        : {
+            fingerprint: lastKnownGoodStage.fingerprint,
+            generation: lastKnownGoodStage.generation,
+          },
+  };
+}
+
+export function stageRecoveryReadiness(
+  plan: VfxValidatedStagePlan,
+  generation: number,
+  recovery: VfxStageRecovery,
+): readonly VfxStageReadiness[] {
+  return plan.stages.map((stage) => ({
+    id: stage.id,
+    state: recovery === 'stale' ? ('stale' as const) : ('rebuilding' as const),
+    generation,
+    lastKnownGoodGeneration: plan.generation,
+    retryable: true,
+    error: recovery,
+  }));
+}

package/src/feature/topologies/beam.ts

@@ -0,0 +1,41 @@
+import { ok, type Result } from '@forgeax/engine-types';
+
+export interface BeamTopologyInput {
+  readonly capacity: number;
+  readonly endpointField: 'velocity';
+}
+
+export interface BeamTopologyOutput {
+  readonly topology: 'beam';
+  readonly vertexCount: number;
+  readonly indexCount: number;
+  readonly indirectVertexCount: number;
+  readonly dropped: number;
+  readonly degenerate: number;
+}
+
+export function buildBeamTopology(
+  input: BeamTopologyInput,
+  requested: number,
+  degenerate = 0,
+): Result<BeamTopologyOutput, never> {
+  const produced = Math.min(input.capacity, Math.max(0, requested));
+  return ok({
+    topology: 'beam',
+    vertexCount: produced * 2,
+    indexCount: produced * 6,
+    indirectVertexCount: produced * 6,
+    dropped: Math.max(0, requested - produced),
+    degenerate: Math.max(0, degenerate),
+  });
+}
+
+export function beamIsDegenerate(
+  start: readonly [number, number, number],
+  endpoint: readonly [number, number, number],
+): boolean {
+  const dx = endpoint[0] - start[0];
+  const dy = endpoint[1] - start[1];
+  const dz = endpoint[2] - start[2];
+  return dx * dx + dy * dy + dz * dz <= 1e-10;
+}

package/src/feature/topologies/ribbon.ts

@@ -0,0 +1,31 @@
+import { ok, type Result } from '@forgeax/engine-types';
+
+export interface RibbonTopologyInput {
+  readonly capacity: number;
+  readonly stripKey: 'alive-index';
+}
+
+export interface RibbonTopologyOutput {
+  readonly topology: 'ribbon';
+  readonly vertexCount: number;
+  readonly indexCount: number;
+  readonly indirectVertexCount: number;
+  readonly dropped: number;
+  readonly brokenStrips: number;
+}
+
+export function buildRibbonTopology(
+  input: RibbonTopologyInput,
+  requested: number,
+  brokenStrips = 0,
+): Result<RibbonTopologyOutput, never> {
+  const produced = Math.min(input.capacity, Math.max(0, requested));
+  return ok({
+    topology: 'ribbon',
+    vertexCount: produced * 2,
+    indexCount: Math.max(0, produced - 1) * 6,
+    indirectVertexCount: Math.max(0, produced - 1) * 6,
+    dropped: Math.max(0, requested - produced),
+    brokenStrips: Math.max(0, brokenStrips),
+  });
+}

package/src/feature/topologies/trail.ts

@@ -0,0 +1,43 @@
+import { ok, type Result } from '@forgeax/engine-types';
+
+export interface TrailTopologyInput {
+  readonly capacity: number;
+  readonly historyLength: number;
+}
+
+export interface TrailTopologyOutput {
+  readonly topology: 'trail';
+  readonly vertexCount: number;
+  readonly indexCount: number;
+  readonly indirectVertexCount: number;
+  readonly dropped: number;
+  readonly brokenTrails: number;
+}
+
+export function buildTrailTopology(
+  input: TrailTopologyInput,
+  requested: number,
+  brokenTrails = 0,
+): Result<TrailTopologyOutput, never> {
+  const produced = Math.min(input.capacity, Math.max(0, requested));
+  const segments = Math.max(0, input.historyLength - 1);
+  return ok({
+    topology: 'trail',
+    vertexCount: produced * input.historyLength * 2,
+    indexCount: produced * segments * 6,
+    indirectVertexCount: produced * segments * 6,
+    dropped: Math.max(0, requested - produced),
+    brokenTrails: Math.max(0, brokenTrails),
+  });
+}
+
+export function trailContinuityBreaks(
+  samples: readonly { readonly id: number; readonly connected: boolean }[],
+): number {
+  let breaks = 0;
+  for (let index = 1; index < samples.length; index += 1) {
+    if (samples[index]?.id !== samples[index - 1]?.id || samples[index]?.connected === false)
+      breaks += 1;
+  }
+  return breaks;
+}