@forgeax/engine-vfx-render 0.1.2

package/dist/index.mjs

@@ -0,0 +1,1572 @@
+import { frustum } from '@forgeax/engine-math';
+import { RenderFeatureStageFailedError, RENDER_FEATURE_VERTEX_LAYOUTS, RenderFeaturePreparationFailedError } from '@forgeax/engine-render';
+import { Transform } from '@forgeax/engine-scene';
+import { err, ok } from '@forgeax/engine-types';
+import { VFX_GPU_RUNTIME_RESOURCE_KEY, vfxGpuEffectContribution, vfxGpuRuntimePlugin, resolveVfxDataInterfaces, ParticleEffectPlayer } from '@forgeax/engine-vfx';
+import { getAssetRegistryResolver } from '@forgeax/engine-assets-runtime/internal';
+import { createWorldContext } from '@forgeax/engine-ecs';
+
+// src/feature/event-resources.ts
+var VFX_EVENT_INPUT_BYTES = 32;
+var VFX_EVENT_BYTES = 32;
+var VFX_EVENT_COUNTER_BYTES = 16;
+function channelFanOut(emitter, channel) {
+  return Math.max(
+    1,
+    ...(emitter.events ?? []).filter((event) => event.channel === channel).map((event) => event.fanOut)
+  );
+}
+function eventInputCapacity(emitter) {
+  return Math.max(
+    1,
+    (emitter.channels ?? []).reduce((total, channel) => total + channel.capacity, 0)
+  );
+}
+function eventCapacity(emitter) {
+  const capacity = (emitter.channels ?? []).reduce(
+    (total, channel) => total + channel.capacity * channelFanOut(emitter, channel.id),
+    0
+  );
+  return Math.max(1, Math.min(emitter.capacity, capacity));
+}
+function channelKey(channel) {
+  let hash = 2166136261;
+  for (const code of channel) {
+    hash ^= code.codePointAt(0) ?? 0;
+    hash = Math.imul(hash, 16777619);
+  }
+  return hash >>> 0;
+}
+function encodeEventInputs(intent) {
+  const capacity = eventInputCapacity(intent.emitter);
+  const data = new ArrayBuffer(capacity * VFX_EVENT_INPUT_BYTES);
+  const bytes = new Uint8Array(data);
+  bytes.fill(255);
+  const view = new DataView(data);
+  for (const [index, input] of intent.channelInputs.entries()) {
+    if (index >= capacity) break;
+    const offset = index * VFX_EVENT_INPUT_BYTES;
+    view.setFloat32(offset, input.payload.position[0], true);
+    view.setFloat32(offset + 4, input.payload.position[1], true);
+    view.setFloat32(offset + 8, input.payload.position[2], true);
+    view.setFloat32(offset + 16, input.payload.strength, true);
+    view.setUint32(offset + 20, input.sequence, true);
+    view.setUint32(offset + 24, channelKey(input.channel), true);
+    view.setUint32(offset + 28, channelFanOut(intent.emitter, input.channel), true);
+  }
+  return bytes;
+}
+function eventCounterData() {
+  return new Uint8Array(VFX_EVENT_COUNTER_BYTES);
+}
+var 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"
+});
+function createTopologyResourcePlan(renderer) {
+  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;
+  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 - 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" } : {},
+    ...value.kind === "trail" ? { historyLength: value.historyLength } : {},
+    ...value.kind === "beam" ? { endpointField: "velocity" } : {}
+  });
+}
+function topologyCapacitySnapshot(plan, input) {
+  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)
+  };
+}
+function particleMaterialPass(kind, material) {
+  const pass = material?.passes?.find((candidate) => candidate.name === `particle-${kind}`);
+  return {
+    shader: pass?.program.module ?? PARTICLE_SHADER_IDENTIFIERS[kind],
+    ...pass?.renderState === void 0 ? {} : { renderState: pass.renderState }
+  };
+}
+function particleMaterialUsesSceneDepth(contract) {
+  return contract === "group-0-resource" || contract === "view-with-resource";
+}
+function particleMaterialUsesBindings(material) {
+  return (material?.parameters?.length ?? 0) > 0;
+}
+function floatAttribute(value) {
+  if (value instanceof Float32Array) return value;
+  if (value instanceof Uint16Array) return Float32Array.from(value);
+  return value === void 0 ? new Float32Array() : new Float32Array(value);
+}
+function canonicalMeshVertices(mesh) {
+  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 target2 = index * 12;
+    result.set(positions.subarray(index * 3, index * 3 + 3), target2);
+    result.set(
+      normals.length >= index * 3 + 3 ? normals.subarray(index * 3, index * 3 + 3) : [0, 0, 1],
+      target2 + 3
+    );
+    result.set(
+      uvs.length >= index * 2 + 2 ? uvs.subarray(index * 2, index * 2 + 2) : [0, 0],
+      target2 + 6
+    );
+    result.set(
+      tangents.length >= index * 4 + 4 ? tangents.subarray(index * 4, index * 4 + 4) : [1, 0, 0, 1],
+      target2 + 8
+    );
+  }
+  return result;
+}
+
+// src/feature/stage-plan.ts
+var MANAGED_STAGES = /* @__PURE__ */ new Set(["spawn", "update", "scan", "compact"]);
+var RESOURCE_NAMES = /* @__PURE__ */ new Set([
+  "particles",
+  "runtime",
+  "aliveIndices",
+  "counters",
+  "indirect",
+  "scratch",
+  "billboardInstances",
+  "channelInputs",
+  "events",
+  "eventCounters"
+]);
+var STAGE_ID = /^[a-z][a-z0-9-]{0,31}$/;
+var ENTRY_POINT = /^forgeax_vfx_stage_[a-z][a-z0-9-]{0,31}_main$/;
+var MAX_ITERATIONS = 64;
+function failure(code, stageId, hint) {
+  return { ok: false, error: { code, stageId, hint } };
+}
+function stableStage(stage) {
+  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
+  };
+}
+function validatedStagePlan(reflection, generation) {
+  const source = reflection ?? [];
+  const ids = /* @__PURE__ */ new Set();
+  const stages = [];
+  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 = /* @__PURE__ */ new Set();
+    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 = /* @__PURE__ */ new Set();
+  const visited = /* @__PURE__ */ new Set();
+  const ordered = [];
+  const visit = (stage) => {
+    if (visited.has(stage.id)) return void 0;
+    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 === void 0) {
+        return {
+          code: "stage-dependency-invalid",
+          stageId: stage.id,
+          hint: "declare every stage dependency or use a managed stage"
+        };
+      }
+      const error = visit(dependencyStage);
+      if (error !== void 0) return error;
+    }
+    visiting.delete(stage.id);
+    visited.add(stage.id);
+    ordered.push(stage);
+    return void 0;
+  };
+  for (const stage of stages) {
+    const error = visit(stage);
+    if (error !== void 0) return { ok: false, error };
+  }
+  const normalized = Object.freeze(ordered);
+  return {
+    ok: true,
+    value: Object.freeze({
+      stages: normalized,
+      fingerprint: JSON.stringify(normalized),
+      generation
+    })
+  };
+}
+function stageDispatches(plan, workgroups, bindings) {
+  return plan.stages.map((stage) => ({
+    entryPoint: stage.entryPoint,
+    workgroups: [workgroups],
+    bindings
+  }));
+}
+function observeStagePlan(candidate, generation, lastKnownGoodStage) {
+  if (candidate.ok) {
+    return {
+      validatedStagePlan: candidate.value,
+      stageReadiness: candidate.value.stages.map((stage) => ({
+        id: stage.id,
+        state: "ready",
+        generation,
+        lastKnownGoodGeneration: generation,
+        retryable: false
+      })),
+      stageOutput: candidate.value.stages.length === 0 ? "empty" : "active",
+      lastKnownGoodStage: candidate.value.stages.length === 0 ? lastKnownGoodStage === void 0 ? void 0 : {
+        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 === void 0 ? {} : { lastKnownGoodGeneration: lastKnownGoodStage.generation },
+        retryable: true,
+        error: candidate.error.code
+      }
+    ],
+    stageOutput: lastKnownGoodStage === void 0 ? "empty" : "last-known-good",
+    lastKnownGoodStage: lastKnownGoodStage === void 0 ? void 0 : {
+      fingerprint: lastKnownGoodStage.fingerprint,
+      generation: lastKnownGoodStage.generation
+    }
+  };
+}
+function stageRecoveryReadiness(plan, generation, recovery) {
+  return plan.stages.map((stage) => ({
+    id: stage.id,
+    state: recovery === "stale" ? "stale" : "rebuilding",
+    generation,
+    lastKnownGoodGeneration: plan.generation,
+    retryable: true,
+    error: recovery
+  }));
+}
+
+// src/feature/gpu-particle-feature.ts
+var IDENTITY = "forgeax.vfx-render.gpu-particles";
+var WORKGROUP_SIZE = 256;
+var PARTICLE_BYTES = 80;
+var BILLBOARD_INSTANCE_BYTES = 31 * 4;
+var MESH_INSTANCE_BYTES = 28 * 4;
+var COUNTERS_BYTES = 24;
+var RUNTIME_BYTES = 72 * 4;
+var MAX_TICK_RINGS = 8;
+var IDENTITY_MATRIX = new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]);
+function createVfxRenderInspectSnapshot(input) {
+  return {
+    topology: input.topology,
+    counters: { capacity: input.capacity, produced: input.produced, dropped: input.dropped },
+    stageReadiness: input.stageReadiness,
+    providerReadiness: input.providerReadiness,
+    gpuTiming: input.gpuTiming
+  };
+}
+function resolveBillboardAdvancedState(renderer, sample) {
+  if (renderer.softParticle !== void 0 && !sample.depthAvailable) {
+    return err({
+      code: "vfx-renderer-depth-missing",
+      expected: "a scene-depth provider for soft particles",
+      hint: "attach the scene-depth data interface or disable soft particles",
+      detail: { path: "renderer.softParticle" }
+    });
+  }
+  const sheet = renderer.textureSheet;
+  const frameCount = sheet?.frameCount ?? (sheet === void 0 ? 1 : sheet.columns * sheet.rows);
+  const frameIndex = sheet === void 0 || sheet.frameRate === 0 ? 0 : Math.min(
+    frameCount - 1,
+    Math.max(0, Math.floor(Math.max(0, sample.age) * sheet.frameRate))
+  );
+  const softParticleFade = renderer.softParticle === void 0 ? 1 : Math.max(
+    0,
+    Math.min(
+      1,
+      (sample.sceneDepth - sample.particleDepth) / renderer.softParticle.fadeDistance
+    )
+  );
+  return ok({
+    frameIndex,
+    pivot: renderer.pivot ?? [0, 0],
+    softParticleFade,
+    sortingKey: renderer.sorting === "back-to-front" ? sample.particleDepth : 0
+  });
+}
+function topologyRecoveryHint(topology, reason) {
+  if (reason === "capacity")
+    return `${topology} capacity overflow was bounded; increase its explicit capacity`;
+  if (reason === "broken")
+    return `${topology} continuity broke; inspect its explicit source key and keep the last valid segment`;
+  if (reason === "degenerate")
+    return `${topology} produced no drawable segment; preserve zero output and inspect source endpoints`;
+  return `${topology} device resources recovered from the last known good generation`;
+}
+function finite(value, fallback) {
+  return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+function vector(value, fallback, size) {
+  return Array.isArray(value) ? Array.from({ length: size }, (_, index) => finite(value[index], fallback[index] ?? 0)) : fallback;
+}
+function runtimeData(intent, camera, material, localToWorld, renderer, rendererIndex = 0) {
+  const storage = new ArrayBuffer(RUNTIME_BYTES);
+  const floats = new Float32Array(storage);
+  const words = new Uint32Array(storage);
+  floats[0] = intent.fixedDelta;
+  words[1] = intent.phaseTick;
+  words[2] = intent.seed;
+  words[3] = intent.playCycle;
+  words[4] = intent.emitter.capacity;
+  words[5] = intent.spawnCount;
+  words[6] = intent.firstParticleId;
+  words[7] = intent.emitter.renderers.length;
+  floats.set(camera.viewProjection, 8);
+  floats.set(camera.right, 24);
+  floats.set(camera.up, 28);
+  const values = material?.values ?? {};
+  floats.set(vector(values.baseColor, [1, 1, 1, 1], 4), 32);
+  const emissive = vector(values.emissive, [0, 0, 0], 3);
+  floats.set(emissive, 36);
+  floats[39] = finite(values.emissiveIntensity, 0);
+  floats[40] = finite(values.metallic, 0);
+  floats[41] = finite(values.roughness, 0.5);
+  floats[42] = finite(values.clearcoat, 0);
+  floats[43] = finite(values.clearcoatRoughness, 0.5);
+  floats.set(localToWorld, 44);
+  words[60] = rendererIndex;
+  words[61] = renderer?.kind === "trail" ? renderer.historyLength : 0;
+  words[62] = renderer?.kind === "ribbon" || renderer?.kind === "trail" || renderer?.kind === "beam" ? renderer.capacity : intent.emitter.capacity;
+  words[63] = renderer?.kind === "billboard" && renderer.sorting === "back-to-front" ? 2 : renderer?.kind === "billboard" && renderer.sorting === "emitter" ? 1 : 0;
+  floats[64] = renderer?.kind === "billboard" ? renderer.pivot?.[0] ?? 0 : renderer?.kind === "ribbon" || renderer?.kind === "trail" || renderer?.kind === "beam" ? renderer.width ?? 0.1 : 0.1;
+  floats[65] = renderer?.kind === "billboard" ? renderer.pivot?.[1] ?? 0 : 0;
+  floats[66] = renderer?.kind === "billboard" ? renderer.softParticle?.fadeDistance ?? 0 : 0;
+  const sheet = renderer?.kind === "billboard" ? renderer.textureSheet : void 0;
+  floats[68] = sheet?.columns ?? 1;
+  floats[69] = sheet?.rows ?? 1;
+  floats[70] = sheet?.frameRate ?? 0;
+  floats[71] = sheet?.frameCount ?? (sheet === void 0 ? 1 : sheet.columns * sheet.rows);
+  return new Uint8Array(storage);
+}
+function emitterTransform(world, intent) {
+  if (intent.emitter.space === "world") return IDENTITY_MATRIX;
+  const transform = world.get(intent.player, Transform);
+  return transform.ok ? transform.value.world : IDENTITY_MATRIX;
+}
+function emitterVisible(intent, camera, localToWorld) {
+  const bounds = intent.emitter.bounds;
+  const center = bounds.kind === "sphere" ? bounds.center : [
+    (bounds.min[0] + bounds.max[0]) * 0.5,
+    (bounds.min[1] + bounds.max[1]) * 0.5,
+    (bounds.min[2] + bounds.max[2]) * 0.5
+  ];
+  const radius = bounds.kind === "sphere" ? bounds.radius : Math.hypot(
+    (bounds.max[0] - bounds.min[0]) * 0.5,
+    (bounds.max[1] - bounds.min[1]) * 0.5,
+    (bounds.max[2] - bounds.min[2]) * 0.5
+  );
+  const matrix = (index) => localToWorld[index] ?? 0;
+  const worldPosition = new Float32Array([
+    matrix(0) * center[0] + matrix(4) * center[1] + matrix(8) * center[2] + matrix(12),
+    matrix(1) * center[0] + matrix(5) * center[1] + matrix(9) * center[2] + matrix(13),
+    matrix(2) * center[0] + matrix(6) * center[1] + matrix(10) * center[2] + matrix(14)
+  ]);
+  const scale = Math.max(
+    Math.hypot(matrix(0), matrix(1), matrix(2)),
+    Math.hypot(matrix(4), matrix(5), matrix(6)),
+    Math.hypot(matrix(8), matrix(9), matrix(10))
+  );
+  const planes = frustum.fromViewProjection(frustum.create(), camera.viewProjection);
+  return frustum.intersectsSphere(planes, worldPosition, radius * scale);
+}
+function resetData(size) {
+  return new Uint8Array(size);
+}
+function target(targets, kind) {
+  return targets.find((entry) => entry.kind === kind);
+}
+function missingMeshPreparation(guid) {
+  return new RenderFeaturePreparationFailedError(
+    IDENTITY,
+    -1,
+    "asset-load",
+    "vertex-data",
+    `mesh:${guid}`,
+    "asset-not-ready",
+    "next-frame"
+  );
+}
+function materialResourceKey(shader) {
+  return shader.replaceAll(/[^a-zA-Z0-9_.:-]/g, "_");
+}
+function requiresSceneDepth(intent) {
+  return (intent.emitter.reflection.dataInterfaces ?? []).some(
+    (requirement) => requirement.kind === "scene-depth"
+  );
+}
+function gpuParticleRenderFeature(options) {
+  const worldIds = /* @__PURE__ */ new WeakMap();
+  let nextWorldId = 0;
+  const states = /* @__PURE__ */ new Map();
+  let lastObservation = Object.freeze({
+    frameNumber: -1,
+    dispatches: 0,
+    indirectDraws: 0,
+    subjectOutputs: 0
+  });
+  const keyOf = (world, intent) => {
+    let worldId = worldIds.get(world);
+    if (worldId === void 0) {
+      worldId = nextWorldId++;
+      worldIds.set(world, worldId);
+    }
+    return `${worldId}:${intent.player}:${intent.emitter.id}`;
+  };
+  const stateFor = (world, intent) => {
+    const key = keyOf(world, intent);
+    let state = states.get(key);
+    if (state !== void 0 && state.fingerprint !== intent.programFingerprint) {
+      states.delete(key);
+      state = void 0;
+    }
+    if (state !== void 0) return state;
+    const fingerprint = intent.programFingerprint.slice(0, 12).replaceAll(":", "_");
+    state = {
+      world,
+      player: intent.player,
+      emitterId: intent.emitter.id,
+      fingerprint: intent.programFingerprint,
+      capacity: intent.emitter.capacity,
+      names: `gpu.${key.replaceAll(":", ".")}.${fingerprint}`,
+      rings: [],
+      projections: [],
+      draws: [],
+      depthSampledDraws: [],
+      colorTarget: void 0,
+      depthTarget: void 0,
+      indirectInitialized: false,
+      culled: false,
+      stageReadiness: [],
+      stageOutput: "empty"
+    };
+    states.set(key, state);
+    return state;
+  };
+  return {
+    identity: IDENTITY,
+    requiredCapabilities: ["compute", "indirectDrawing"],
+    requiredMaterialShaders: Object.values(PARTICLE_SHADER_IDENTIFIERS),
+    extract: (context) => {
+      const extracted = [];
+      for (const world of context.worlds) {
+        if (!world.hasResource(VFX_GPU_RUNTIME_RESOURCE_KEY)) continue;
+        const camera = options.camera.read(world);
+        if (camera === void 0) continue;
+        const runtime = world.getResource(VFX_GPU_RUNTIME_RESOURCE_KEY);
+        const intents = runtime.snapshot().filter((intent) => {
+          if (options.playerConsumption?.isEnabled(world, intent.player) === false) return false;
+          const requirements = intent.emitter.reflection.dataInterfaces ?? [];
+          if (requirements.length === 0) return true;
+          return options.dataInterfaces?.resolve(requirements, intent.instanceGeneration).ok === true;
+        });
+        extracted.push({ world, runtime, camera, intents });
+      }
+      return ok({ worlds: extracted, frameNumber: context.frameNumber });
+    },
+    prepare: (frame, context) => {
+      const gpu = context.gpu;
+      if (gpu === void 0) {
+        return err(new RenderFeatureStageFailedError(IDENTITY, -1, "prepare", "renderer-recover"));
+      }
+      let pendingProgramError;
+      const preparedIntents = [];
+      for (const entry of frame.worlds) {
+        for (const intent of entry.intents) {
+          const key = keyOf(entry.world, intent);
+          let state = states.get(key);
+          const candidate = validatedStagePlan(
+            intent.emitter.reflection.stages,
+            intent.instanceGeneration
+          );
+          if (!candidate.ok) {
+            if (state === void 0) {
+              return err(new RenderFeatureStageFailedError(IDENTITY, -1, "prepare", "next-frame"));
+            }
+            const observation2 = observeStagePlan(
+              candidate,
+              intent.instanceGeneration,
+              state.lastKnownGoodStage
+            );
+            state.stagePlan = observation2.validatedStagePlan;
+            state.stageReadiness = observation2.stageReadiness;
+            state.stageOutput = observation2.stageOutput;
+            continue;
+          }
+          if (state !== void 0 && state.fingerprint !== intent.programFingerprint) {
+            states.delete(key);
+            state = void 0;
+          }
+          state ??= stateFor(entry.world, intent);
+          const observation = observeStagePlan(
+            candidate,
+            intent.instanceGeneration,
+            state.lastKnownGoodStage
+          );
+          state.stagePlan = observation.validatedStagePlan;
+          state.lastKnownGoodStage = candidate.value;
+          state.stageReadiness = observation.stageReadiness;
+          state.stageOutput = observation.stageOutput;
+          const program = gpu.prepareProgram(`${state.names}.program`, {
+            wgsl: intent.emitter.wgsl,
+            entryPoints: intent.emitter.reflection.entryPoints,
+            bindings: intent.emitter.reflection.bindings
+          });
+          if (!program.ok) {
+            if (program.error.code !== "render-feature-preparation-failed" || program.error.detail.recovery !== "next-frame") {
+              return program;
+            }
+            pendingProgramError ??= program.error;
+          }
+          preparedIntents.push({ entry, intent, state });
+        }
+      }
+      if (pendingProgramError !== void 0) return err(pendingProgramError);
+      let pendingGraphicsError;
+      for (const { entry, intent, state } of preparedIntents) {
+        if (intent.reset) state.indirectInitialized = false;
+        state.lastIntent = intent;
+        const base = state.names;
+        const program = gpu.prepareProgram(`${base}.program`, {
+          wgsl: intent.emitter.wgsl,
+          entryPoints: intent.emitter.reflection.entryPoints,
+          bindings: intent.emitter.reflection.bindings
+        });
+        if (!program.ok) return program;
+        const prepare = (name, size, usage, data) => gpu.prepareBuffer(`${base}.${name}`, {
+          size,
+          usage,
+          ...data === void 0 ? {} : { data }
+        });
+        const particles = prepare(
+          "particles",
+          state.capacity * PARTICLE_BYTES,
+          ["storage"],
+          intent.reset ? resetData(state.capacity * PARTICLE_BYTES) : void 0
+        );
+        if (!particles.ok) return particles;
+        const aliveIndices = prepare("alive-indices", state.capacity * 4, ["storage"]);
+        if (!aliveIndices.ok) return aliveIndices;
+        const counters = prepare(
+          "counters",
+          COUNTERS_BYTES,
+          ["storage"],
+          intent.reset ? resetData(COUNTERS_BYTES) : void 0
+        );
+        if (!counters.ok) return counters;
+        const indirect = prepare("indirect", Math.max(1, intent.emitter.renderers.length) * 20, [
+          "storage",
+          "indirect"
+        ]);
+        if (!indirect.ok) return indirect;
+        const scratchBytes = (state.capacity * 2 + Math.ceil(state.capacity / WORKGROUP_SIZE)) * 4;
+        const scratch = prepare(
+          "scratch",
+          scratchBytes,
+          ["storage"],
+          intent.reset ? resetData(scratchBytes) : void 0
+        );
+        if (!scratch.ok) return scratch;
+        const billboardInstances = prepare(
+          "billboard-instances",
+          state.capacity * Math.max(BILLBOARD_INSTANCE_BYTES, MESH_INSTANCE_BYTES),
+          ["storage", "vertex"]
+        );
+        if (!billboardInstances.ok) return billboardInstances;
+        const events = prepare(
+          "events",
+          eventCapacity(intent.emitter) * VFX_EVENT_BYTES,
+          ["storage"],
+          intent.reset ? resetData(eventCapacity(intent.emitter) * VFX_EVENT_BYTES) : void 0
+        );
+        if (!events.ok) return events;
+        const initialEventInputs = prepare(
+          "event-inputs",
+          eventInputCapacity(intent.emitter) * VFX_EVENT_INPUT_BYTES,
+          ["storage"],
+          encodeEventInputs(intent)
+        );
+        if (!initialEventInputs.ok) return initialEventInputs;
+        state.refs = {
+          program: program.value,
+          particles: particles.value,
+          aliveIndices: aliveIndices.value,
+          counters: counters.value,
+          indirect: indirect.value,
+          scratch: scratch.value,
+          billboardInstances: billboardInstances.value,
+          eventInputs: initialEventInputs.value,
+          events: events.value
+        };
+        const ringIndex = intent.tick % MAX_TICK_RINGS;
+        const runtime = gpu.prepareBuffer(`${base}.runtime.${ringIndex}`, {
+          size: RUNTIME_BYTES,
+          usage: ["uniform"],
+          data: runtimeData(intent, entry.camera, void 0, emitterTransform(entry.world, intent))
+        });
+        if (!runtime.ok) return runtime;
+        const refs = state.refs;
+        const updatedEventInputs = gpu.prepareBuffer(`${base}.event-inputs`, {
+          size: eventInputCapacity(intent.emitter) * VFX_EVENT_INPUT_BYTES,
+          usage: ["storage"],
+          data: encodeEventInputs(intent)
+        });
+        if (!updatedEventInputs.ok) return updatedEventInputs;
+        const bindings = gpu.prepareBindings(`${base}.bindings.${ringIndex}`, {
+          program: refs.program,
+          entries: [
+            { binding: 0, buffer: refs.particles },
+            { binding: 1, buffer: runtime.value },
+            { binding: 2, buffer: refs.aliveIndices },
+            { binding: 3, buffer: refs.counters },
+            { binding: 4, buffer: refs.indirect },
+            { binding: 5, buffer: refs.scratch },
+            { binding: 6, buffer: refs.billboardInstances },
+            { binding: 8, buffer: updatedEventInputs.value },
+            { binding: 9, buffer: refs.events }
+          ]
+        });
+        if (!bindings.ok) return bindings;
+        state.rings[ringIndex] = {
+          runtime: runtime.value,
+          bindings: bindings.value
+        };
+      }
+      for (const [key, state] of states) {
+        const extracted = frame.worlds.find((entry) => entry.world === state.world);
+        if (extracted === void 0 || !extracted.runtime.hasPlayer(state.player)) {
+          states.delete(key);
+          continue;
+        }
+        if (options.playerConsumption?.isEnabled(state.world, state.player) === false) {
+          state.projections = [];
+          state.draws = [];
+          state.depthSampledDraws = [];
+          state.colorTarget = void 0;
+          state.depthTarget = void 0;
+          continue;
+        }
+        const intent = state.lastIntent;
+        const refs = state.refs;
+        if (intent === void 0 || refs === void 0) continue;
+        const retained = gpu.retainBindings([
+          ...state.rings.flatMap((ring) => ring === void 0 ? [] : [ring.bindings]),
+          ...state.projections.map((projection) => projection.ring.bindings)
+        ]);
+        if (!retained.ok) return retained;
+        if (!extracted.runtime.isEmitterSessionEnabled(state.player, state.emitterId)) {
+          state.projections = [];
+          state.draws = [];
+          state.depthSampledDraws = [];
+          continue;
+        }
+        const renderers = intent.emitter.renderers;
+        if (renderers.length === 0) continue;
+        const localToWorld = emitterTransform(state.world, intent);
+        const visible = emitterVisible(intent, extracted.camera, localToWorld);
+        extracted.runtime.setEmitterCameraVisibility(state.player, state.emitterId, visible);
+        const currentIntents = extracted.intents.filter(
+          (candidate) => candidate.player === state.player && candidate.emitter.id === state.emitterId
+        );
+        if (!visible) {
+          state.culled = true;
+          state.projections = [];
+          state.draws = [];
+          state.depthSampledDraws = [];
+          continue;
+        }
+        if (state.culled && intent.emitter.simulationWhenCulled === "restart-on-visible" && !currentIntents.some((candidate) => candidate.reset)) {
+          state.projections = [];
+          state.draws = [];
+          state.depthSampledDraws = [];
+          continue;
+        }
+        state.culled = false;
+        const colorTarget = target(context.targets, "scene-color");
+        const depthTarget = target(context.targets, "scene-depth");
+        const softParticle = requiresSceneDepth(intent);
+        if (softParticle && depthTarget === void 0) continue;
+        const eventRing = state.rings[intent.tick % MAX_TICK_RINGS];
+        if (eventRing === void 0) continue;
+        const meshes = renderers.map(
+          (renderer) => renderer.kind === "mesh" ? options.mesh?.read(state.world, renderer.mesh) : void 0
+        );
+        const missingMesh = renderers.find(
+          (renderer, index) => renderer.kind === "mesh" && meshes[index]?.submeshes[renderer.submesh ?? 0] === void 0
+        );
+        if (missingMesh?.kind === "mesh") {
+          pendingGraphicsError ??= missingMeshPreparation(missingMesh.mesh);
+          continue;
+        }
+        const indirectWords = new Uint32Array(renderers.length * 5);
+        for (const [index, renderer] of renderers.entries()) {
+          const mesh = meshes[index];
+          const submesh = renderer.kind === "mesh" ? mesh?.submeshes[renderer.submesh ?? 0] : void 0;
+          const topologyPlan = renderer.kind === "ribbon" || renderer.kind === "trail" || renderer.kind === "beam" ? createTopologyResourcePlan(renderer) : void 0;
+          if (topologyPlan !== void 0 && !topologyPlan.ok)
+            return err(new RenderFeatureStageFailedError(IDENTITY, -1, "prepare", "next-frame"));
+          indirectWords[index * 5] = renderer.kind === "billboard" ? 6 : renderer.kind === "ribbon" || renderer.kind === "trail" || renderer.kind === "beam" ? 6 : mesh?.indices === void 0 ? submesh?.vertexCount ?? 0 : submesh?.indexCount ?? 0;
+          indirectWords[index * 5 + 2] = renderer.kind === "mesh" && mesh?.indices !== void 0 ? submesh?.indexOffset ?? 0 : 0;
+        }
+        const indirectInit = gpu.prepareBuffer(`${state.names}.indirect`, {
+          size: Math.max(1, renderers.length) * 20,
+          usage: ["storage", "indirect"],
+          ...state.indirectInitialized ? {} : { data: indirectWords }
+        });
+        if (!indirectInit.ok) return indirectInit;
+        state.indirectInitialized = true;
+        const draws = [];
+        const depthSampledDraws = [];
+        const projections = [];
+        for (const [rendererIndex, renderer] of renderers.entries()) {
+          const isBillboard = renderer.kind === "billboard";
+          const isTopology = renderer.kind === "ribbon" || renderer.kind === "trail" || renderer.kind === "beam";
+          const topologyPlan = isTopology ? createTopologyResourcePlan(renderer) : void 0;
+          if (topologyPlan !== void 0 && !topologyPlan.ok)
+            return err(new RenderFeatureStageFailedError(IDENTITY, -1, "prepare", "next-frame"));
+          const mesh = meshes[rendererIndex];
+          const submesh = renderer.kind === "mesh" ? mesh?.submeshes[renderer.submesh ?? 0] : void 0;
+          const indexFormat = mesh?.indices instanceof Uint32Array ? "uint32" : "uint16";
+          let material = options.material?.read(state.world, renderer.material);
+          if (material !== void 0) {
+            const resolvedMaterial = context.graphics.resolveMaterialAsset(material);
+            if (!resolvedMaterial.ok) {
+              pendingGraphicsError ??= resolvedMaterial.error;
+              continue;
+            }
+            material = resolvedMaterial.value;
+          }
+          const materialPass = particleMaterialPass(renderer.kind, material);
+          const materialKey = materialResourceKey(materialPass.shader);
+          const samplesSceneDepth = particleMaterialUsesSceneDepth(
+            context.graphics.getMaterialShaderBindingContract(materialPass.shader)
+          );
+          const particleBlend = renderer.kind === "billboard" ? renderer.blend : "alpha";
+          const projectionInstances = gpu.prepareBuffer(
+            `${state.names}.renderer.${rendererIndex}.instances`,
+            {
+              size: isTopology ? topologyPlan?.ok ? topologyPlan.value.vertexBytes : 0 : state.capacity * (isBillboard ? BILLBOARD_INSTANCE_BYTES : MESH_INSTANCE_BYTES),
+              usage: ["storage", "vertex"]
+            }
+          );
+          if (!projectionInstances.ok) return projectionInstances;
+          const projectionHistory = gpu.prepareBuffer(
+            `${state.names}.renderer.${rendererIndex}.history`,
+            {
+              size: renderer.kind === "trail" ? Math.max(16, renderer.capacity * renderer.historyLength * 16) : 16,
+              usage: ["storage"],
+              ...intent.reset ? {
+                data: resetData(
+                  renderer.kind === "trail" ? Math.max(16, renderer.capacity * renderer.historyLength * 16) : 16
+                )
+              } : {}
+            }
+          );
+          if (!projectionHistory.ok) return projectionHistory;
+          const projectionRuntime = gpu.prepareBuffer(
+            `${state.names}.renderer.${rendererIndex}.runtime`,
+            {
+              size: RUNTIME_BYTES,
+              usage: ["uniform"],
+              data: runtimeData(
+                { ...intent, fixedDelta: 0, spawnCount: 0 },
+                extracted.camera,
+                material,
+                localToWorld,
+                renderer,
+                rendererIndex
+              )
+            }
+          );
+          if (!projectionRuntime.ok) return projectionRuntime;
+          const projectionBindings = gpu.prepareBindings(
+            `${state.names}.renderer.${rendererIndex}.bindings`,
+            {
+              program: refs.program,
+              entries: [
+                { binding: 0, buffer: refs.particles },
+                { binding: 1, buffer: projectionRuntime.value },
+                { binding: 2, buffer: refs.aliveIndices },
+                { binding: 3, buffer: refs.counters },
+                { binding: 4, buffer: refs.indirect },
+                { binding: 5, buffer: projectionHistory.value },
+                { binding: 6, buffer: projectionInstances.value },
+                { binding: 8, buffer: refs.eventInputs },
+                { binding: 9, buffer: refs.events }
+              ]
+            }
+          );
+          if (!projectionBindings.ok) return projectionBindings;
+          projections.push({
+            kind: renderer.kind,
+            instances: projectionInstances.value,
+            ring: {
+              runtime: projectionRuntime.value,
+              bindings: projectionBindings.value
+            },
+            workgroups: Math.ceil(
+              (renderer.kind === "trail" ? renderer.capacity * Math.max(1, renderer.historyLength - 1) : renderer.kind === "ribbon" || renderer.kind === "beam" ? renderer.capacity : state.capacity) / WORKGROUP_SIZE
+            ),
+            ...renderer.kind === "trail" ? { historyWorkgroups: Math.ceil(renderer.capacity / WORKGROUP_SIZE) } : {},
+            ...renderer.kind === "billboard" ? { sorting: renderer.sorting ?? "none" } : {}
+          });
+          const pipeline = context.graphics.preparePipeline(
+            `${state.names}.renderer.${rendererIndex}.${renderer.kind}.pipeline.${materialKey}`,
+            {
+              shader: materialPass.shader,
+              vertexLayout: isBillboard ? RENDER_FEATURE_VERTEX_LAYOUTS.billboardMaterialInstance : isTopology ? RENDER_FEATURE_VERTEX_LAYOUTS.topologySegmentInstance : RENDER_FEATURE_VERTEX_LAYOUTS.meshGeometryMaterialInstance,
+              colorFormats: [colorTarget?.format ?? "rgba8unorm-srgb"],
+              ...depthTarget === void 0 ? {} : { depthFormat: depthTarget.format },
+              sampleCount: colorTarget?.sampleCount ?? 1,
+              topology: submesh?.topology ?? "triangle-list",
+              ...mesh?.indices === void 0 ? {} : { indexFormat },
+              ...materialPass.renderState !== void 0 ? { renderState: materialPass.renderState } : isBillboard || isTopology ? {
+                renderState: {
+                  cullMode: "none",
+                  depthCompare: "less-equal",
+                  depthWriteEnabled: softParticle || isTopology ? false : particleBlend === "opaque-cutout",
+                  ...particleBlend === "opaque-cutout" ? {} : {
+                    blend: {
+                      color: {
+                        srcFactor: "one",
+                        dstFactor: particleBlend === "additive" ? "one" : "one-minus-src-alpha",
+                        operation: "add"
+                      },
+                      alpha: {
+                        srcFactor: "one",
+                        dstFactor: "one-minus-src-alpha",
+                        operation: "add"
+                      }
+                    }
+                  }
+                }
+              } : {}
+            }
+          );
+          if (!pipeline.ok) {
+            if (pipeline.error.code !== "render-feature-preparation-failed" || pipeline.error.detail.recovery !== "next-frame") {
+              return pipeline;
+            }
+            pendingGraphicsError ??= pipeline.error;
+            continue;
+          }
+          const graphicsBindings = context.graphics.prepareBindings(
+            `${state.names}.renderer.${rendererIndex}.${renderer.kind}.binding.${materialKey}`,
+            {
+              pipeline: pipeline.value,
+              values: {
+                group: 0,
+                shader: materialPass.shader,
+                ...samplesSceneDepth && depthTarget !== void 0 ? { sceneDepth: depthTarget } : {}
+              }
+            }
+          );
+          if (!graphicsBindings.ok) return graphicsBindings;
+          const materialBindings = !particleMaterialUsesBindings(material) ? void 0 : context.graphics.prepareBindings(
+            `${state.names}.renderer.${rendererIndex}.${renderer.kind}.material-binding.${materialKey}`,
+            {
+              pipeline: pipeline.value,
+              values: {
+                group: 1,
+                material: {
+                  world: frame.worlds.findIndex((entry) => entry.world === state.world),
+                  guid: renderer.material
+                }
+              }
+            }
+          );
+          if (materialBindings !== void 0 && !materialBindings.ok) return materialBindings;
+          const drawBindings = [
+            graphicsBindings.value,
+            ...materialBindings === void 0 ? [] : [materialBindings.value]
+          ];
+          if (isBillboard || isTopology) {
+            const vertexData2 = context.graphics.prepareVertexData(
+              `${state.names}.${isTopology ? renderer.kind : "billboard"}.vertices`,
+              {
+                layout: isTopology ? RENDER_FEATURE_VERTEX_LAYOUTS.topologySegmentInstance : RENDER_FEATURE_VERTEX_LAYOUTS.billboardMaterialInstance,
+                buffer: projectionInstances.value
+              }
+            );
+            if (!vertexData2.ok) return vertexData2;
+            const draw = {
+              kind: "draw-indirect",
+              pipeline: pipeline.value,
+              bindings: drawBindings,
+              vertexData: [{ slot: 0, resource: vertexData2.value }],
+              command: { buffer: refs.indirect, offset: rendererIndex * 20 }
+            };
+            (samplesSceneDepth ? depthSampledDraws : draws).push(draw);
+            continue;
+          }
+          if (mesh === void 0) {
+            return err(new RenderFeatureStageFailedError(IDENTITY, -1, "prepare", "next-frame"));
+          }
+          const geometryData = canonicalMeshVertices(mesh);
+          const geometryBuffer = gpu.prepareBuffer(
+            `${state.names}.renderer.${rendererIndex}.mesh.geometry-buffer`,
+            {
+              size: geometryData.byteLength,
+              usage: ["vertex"],
+              data: geometryData
+            }
+          );
+          if (!geometryBuffer.ok) return geometryBuffer;
+          const geometry = context.graphics.prepareVertexData(
+            `${state.names}.renderer.${rendererIndex}.mesh.geometry`,
+            {
+              layout: RENDER_FEATURE_VERTEX_LAYOUTS.meshGeometryMaterialInstance,
+              buffer: geometryBuffer.value
+            }
+          );
+          if (!geometry.ok) return geometry;
+          const instances = context.graphics.prepareVertexData(
+            `${state.names}.renderer.${rendererIndex}.mesh.instances`,
+            {
+              layout: RENDER_FEATURE_VERTEX_LAYOUTS.meshGeometryMaterialInstance,
+              buffer: projectionInstances.value
+            }
+          );
+          if (!instances.ok) return instances;
+          const indexBuffer = mesh.indices === void 0 ? void 0 : gpu.prepareBuffer(`${state.names}.renderer.${rendererIndex}.mesh.index-buffer`, {
+            size: mesh.indices.byteLength,
+            usage: ["index"],
+            data: mesh.indices
+          });
+          if (indexBuffer !== void 0 && !indexBuffer.ok) return indexBuffer;
+          const indices = indexBuffer === void 0 ? void 0 : context.graphics.prepareIndexData(
+            `${state.names}.renderer.${rendererIndex}.mesh.indices`,
+            {
+              format: indexFormat,
+              buffer: indexBuffer.value
+            }
+          );
+          if (indices !== void 0 && !indices.ok) return indices;
+          const vertexData = [
+            { slot: 0, resource: geometry.value },
+            { slot: 1, resource: instances.value }
+          ];
+          draws.push(
+            indices === void 0 ? {
+              kind: "draw-indirect",
+              pipeline: pipeline.value,
+              bindings: drawBindings,
+              vertexData,
+              command: { buffer: refs.indirect, offset: rendererIndex * 20 }
+            } : {
+              kind: "draw-indexed-indirect",
+              pipeline: pipeline.value,
+              bindings: drawBindings,
+              vertexData,
+              indexData: { resource: indices.value, format: indexFormat },
+              command: { buffer: refs.indirect, offset: rendererIndex * 20 }
+            }
+          );
+        }
+        state.projections = projections;
+        state.draws = draws;
+        state.depthSampledDraws = depthSampledDraws;
+        state.colorTarget = colorTarget;
+        state.depthTarget = depthTarget;
+      }
+      if (pendingGraphicsError !== void 0) return err(pendingGraphicsError);
+      return ok(void 0);
+    },
+    contribute: (frame, context) => {
+      let dispatchCount = 0;
+      let indirectDrawCount = 0;
+      let subjectOutputCount = 0;
+      for (const state of states.values()) {
+        const refs = state.refs;
+        const firstProjection = state.projections[0];
+        if (refs === void 0) continue;
+        const extracted = frame.worlds.find((entry) => entry.world === state.world);
+        if (extracted === void 0) continue;
+        if (options.playerConsumption?.isEnabled(state.world, state.player) === false) continue;
+        if (!extracted.runtime.isEmitterSessionEnabled(state.player, state.emitterId)) continue;
+        const currentIntents = extracted.intents.filter(
+          (intent) => intent.player === state.player && intent.emitter.id === state.emitterId
+        );
+        const intents = currentIntents.some(
+          (intent) => intent.programFingerprint === state.fingerprint
+        ) ? currentIntents.filter((intent) => intent.programFingerprint === state.fingerprint) : state.lastIntent === void 0 ? [] : [state.lastIntent];
+        const groups = Math.ceil(state.capacity / WORKGROUP_SIZE);
+        const dispatches = intents.flatMap((intent) => {
+          const bindings = state.rings[intent.tick % MAX_TICK_RINGS]?.bindings;
+          if (bindings === void 0) return [];
+          return [
+            { entryPoint: "forgeax_vfx_spawn_main", workgroups: [groups], bindings },
+            { entryPoint: "forgeax_vfx_update_main", workgroups: [groups], bindings },
+            ...stageDispatches(
+              state.stagePlan ?? {
+                stages: [],
+                generation: intent.instanceGeneration
+              },
+              groups,
+              bindings
+            ),
+            { entryPoint: "forgeax_vfx_scan_blocks_main", workgroups: [groups], bindings },
+            {
+              entryPoint: "forgeax_vfx_scan_block_offsets_main",
+              workgroups: [1],
+              bindings
+            },
+            { entryPoint: "forgeax_vfx_add_offsets_main", workgroups: [groups], bindings },
+            { entryPoint: "forgeax_vfx_compact_main", workgroups: [groups], bindings },
+            {
+              entryPoint: "forgeax_vfx_event_main",
+              workgroups: [Math.ceil(eventInputCapacity(intent.emitter) / 64)],
+              bindings
+            }
+          ];
+        });
+        for (const projection of state.projections) {
+          if (projection.kind === "billboard" && projection.sorting === "back-to-front") {
+            dispatches.push({
+              entryPoint: "forgeax_vfx_sort_main",
+              workgroups: [1],
+              bindings: projection.ring.bindings
+            });
+          }
+          if (projection.kind === "trail") {
+            dispatches.push({
+              entryPoint: "forgeax_vfx_trail_history_main",
+              workgroups: [projection.historyWorkgroups ?? 1],
+              bindings: projection.ring.bindings
+            });
+          }
+          dispatches.push({
+            entryPoint: projection.kind === "billboard" ? "forgeax_vfx_billboard_main" : projection.kind === "mesh" ? "forgeax_vfx_mesh_main" : `forgeax_vfx_${projection.kind}_main`,
+            workgroups: [projection.workgroups],
+            bindings: projection.ring.bindings
+          });
+        }
+        const passBindings = firstProjection?.ring.bindings ?? intents.map((intent) => state.rings[intent.tick % MAX_TICK_RINGS]?.bindings).find((bindings) => bindings !== void 0);
+        if (passBindings === void 0 || dispatches.length === 0) continue;
+        const computePassIdentity = `${state.names}.simulate-and-project`;
+        const compute = context.staging.addComputePass(computePassIdentity, {
+          program: refs.program,
+          bindings: passBindings,
+          dispatches
+        });
+        if (!compute.ok) return compute;
+        dispatchCount += dispatches.length;
+        for (const intent of intents) {
+          extracted.runtime.markEventDispatched(state.player, intent.eventCounters);
+        }
+        for (const [drawKind, passDraws] of [
+          ["regular", state.draws],
+          ["depth-sampled", state.depthSampledDraws]
+        ]) {
+          if (passDraws.length === 0) continue;
+          const samplesDepth = drawKind === "depth-sampled";
+          const draw = context.staging.addGraphicsPass(
+            `${state.names}.draw.${drawKind}`,
+            {
+              attachments: {
+                colors: [
+                  {
+                    resource: state.colorTarget ?? "swapchain",
+                    format: state.colorTarget?.format ?? "rgba8unorm-srgb",
+                    loadOp: "load",
+                    storeOp: "store"
+                  }
+                ],
+                ...state.depthTarget === void 0 ? {} : {
+                  depthStencil: {
+                    resource: state.depthTarget,
+                    format: state.depthTarget.format,
+                    depthLoadOp: "load",
+                    depthStoreOp: "store"
+                  }
+                }
+              },
+              ...state.depthTarget === void 0 || !samplesDepth ? {} : { sampledTargets: [state.depthTarget] },
+              temporalCoverage: "reactive",
+              draws: passDraws
+            },
+            { dependsOn: [{ featureIdentity: IDENTITY, passIdentity: computePassIdentity }] }
+          );
+          if (!draw.ok) return draw;
+          indirectDrawCount += passDraws.filter(
+            (record) => record.kind === "draw-indirect" || record.kind === "draw-indexed-indirect"
+          ).length;
+          subjectOutputCount += passDraws.length;
+        }
+      }
+      for (const entry of frame.worlds) {
+        const last = entry.intents.at(-1);
+        if (last !== void 0) entry.runtime.commit(last.sequence);
+      }
+      lastObservation = Object.freeze({
+        frameNumber: frame.frameNumber,
+        dispatches: dispatchCount,
+        indirectDraws: indirectDrawCount,
+        subjectOutputs: subjectOutputCount
+      });
+      return ok(void 0);
+    },
+    recover: () => {
+      const runtimes = /* @__PURE__ */ new Set();
+      for (const state of states.values()) {
+        if (!state.world.hasResource(VFX_GPU_RUNTIME_RESOURCE_KEY)) continue;
+        runtimes.add(state.world.getResource(VFX_GPU_RUNTIME_RESOURCE_KEY));
+      }
+      for (const runtime of runtimes) runtime.recover();
+      states.clear();
+      return ok(void 0);
+    },
+    dispose: () => {
+      states.clear();
+      lastObservation = Object.freeze({
+        frameNumber: -1,
+        dispatches: 0,
+        indirectDraws: 0,
+        subjectOutputs: 0
+      });
+      return ok(void 0);
+    },
+    inspect: () => lastObservation
+  };
+}
+function duplicate(token, providerId) {
+  return {
+    code: "vfx-data-interface-duplicate",
+    expected: "at most one provider for each reflected Data Interface token",
+    hint: `remove provider ${providerId} or the existing provider for ${token} and retry`,
+    detail: { token, providerId }
+  };
+}
+function availableProvider(token, kind, bindingType, source) {
+  return {
+    id: `${token}-provider`,
+    token,
+    kind,
+    bindingType,
+    provide: (generation) => {
+      if (!source.available(generation)) {
+        return err({
+          code: "vfx-data-interface-missing",
+          expected: `an available ${kind} provider for ${token}`,
+          hint: `make ${token} available for generation ${generation} and retry rendering`,
+          detail: { token, providerId: `${token}-provider` }
+        });
+      }
+      const resource = {
+        token,
+        kind,
+        bindingType,
+        generation
+      };
+      return ok(resource);
+    }
+  };
+}
+function createCameraProvider(source) {
+  return availableProvider("vfx:camera", "camera", "uniform", source);
+}
+function createSceneDepthProvider(source) {
+  return availableProvider("vfx:scene-depth", "scene-depth", "sampled-depth", source);
+}
+function createVfxDataInterfaceRegistry(initialProviders = []) {
+  const entries = /* @__PURE__ */ new Map();
+  let registrationError;
+  let lastSnapshot;
+  const registry = {
+    get providers() {
+      return Object.freeze([...entries.values()]);
+    },
+    get snapshot() {
+      return lastSnapshot;
+    },
+    register(provider) {
+      if (entries.has(provider.token)) {
+        const error = duplicate(provider.token, provider.id);
+        registrationError ??= error;
+        return err(error);
+      }
+      entries.set(provider.token, provider);
+      return ok(void 0);
+    },
+    resolve(requirements, generation) {
+      const result = registrationError === void 0 ? resolveVfxDataInterfaces(requirements, [...entries.values()], generation) : err(registrationError);
+      lastSnapshot = Object.freeze({ generation, result });
+      return result;
+    }
+  };
+  for (const provider of initialProviders) registry.register(provider);
+  return registry;
+}
+function installVfxRuntimeDecoder(registry) {
+  return registry.installDecoder(vfxGpuEffectContribution.kind, vfxGpuEffectContribution.decoder);
+}
+function failure2(code, expected, hint, cause) {
+  return { code, expected, hint, detail: { cause } };
+}
+function controlFailure(code, expected, hint, detail = {}) {
+  return { code, expected, hint, detail };
+}
+function createVfxRuntimeHost(options) {
+  const decoderLeases = /* @__PURE__ */ new WeakMap();
+  const worlds = /* @__PURE__ */ new WeakMap();
+  const pausedPlayers = /* @__PURE__ */ new WeakMap();
+  let nextGeneration = 1;
+  const dataInterfaces = createVfxDataInterfaceRegistry(options.providers);
+  const readRenderAsset = (world, guid, kind) => {
+    const attached = worlds.get(world);
+    if (attached === void 0) return void 0;
+    const key = `${kind}:${guid.toLowerCase()}`;
+    const cached = attached.renderAssets.get(key);
+    if (cached?.kind === kind) return cached;
+    const resolved = attached.resolver?.lookup(guid);
+    if (resolved?.kind === kind) {
+      attached.renderAssets.set(key, resolved);
+      return resolved;
+    }
+    if (!attached.pendingRenderAssets.has(key)) {
+      const epoch = attached.catalogEpoch;
+      const request = attached.assets.load(guid, kind).then((result) => {
+        if (!result.ok || worlds.get(world) !== attached || attached.catalogEpoch !== epoch)
+          return;
+        attached.renderAssets.set(key, result.value);
+      }).catch(() => void 0);
+      attached.pendingRenderAssets.set(key, request);
+      void request.finally(() => {
+        if (attached.pendingRenderAssets.get(key) === request) {
+          attached.pendingRenderAssets.delete(key);
+        }
+      });
+    }
+    return void 0;
+  };
+  const feature = gpuParticleRenderFeature({
+    camera: options.camera,
+    dataInterfaces,
+    material: { read: (world, guid) => readRenderAsset(world, guid, "material") },
+    mesh: { read: (world, guid) => readRenderAsset(world, guid, "mesh") },
+    playerConsumption: {
+      isEnabled: (world, player) => !pausedPlayers.get(world)?.has(player)
+    }
+  });
+  return {
+    feature,
+    dataInterfaces,
+    inspect: (world) => {
+      const attached = worlds.get(world);
+      if (attached === void 0 || !world.hasResource(VFX_GPU_RUNTIME_RESOURCE_KEY))
+        return void 0;
+      const runtime = world.getResource(VFX_GPU_RUNTIME_RESOURCE_KEY);
+      return Object.freeze({
+        generation: attached.generation,
+        renderGeneration: runtime.renderGeneration,
+        players: runtime.inspectPlayers(),
+        diagnostics: runtime.diagnostics()
+      });
+    },
+    acquireControl: (world) => {
+      const attached = worlds.get(world);
+      if (attached === void 0) {
+        return err(
+          controlFailure(
+            "vfx-host-control-world-detached",
+            "an attached VFX Runtime World",
+            "attach the World to this VfxRuntimeHost before acquiring controls"
+          )
+        );
+      }
+      const requestedGeneration = attached.generation;
+      const withRuntime = (player, action) => {
+        const current = worlds.get(world);
+        if (current === void 0) {
+          return err(
+            controlFailure(
+              "vfx-host-control-world-detached",
+              `VFX host generation ${requestedGeneration} to remain attached`,
+              "reacquire controls after the World is attached again",
+              { requestedGeneration }
+            )
+          );
+        }
+        if (current.generation !== requestedGeneration) {
+          return err(
+            controlFailure(
+              "vfx-host-control-stale-generation",
+              `VFX host generation ${requestedGeneration}`,
+              "discard this stale control lease and acquire one from the current host generation",
+              { requestedGeneration, currentGeneration: current.generation }
+            )
+          );
+        }
+        if (!world.hasResource(VFX_GPU_RUNTIME_RESOURCE_KEY)) {
+          return err(
+            controlFailure(
+              "vfx-host-control-runtime-unavailable",
+              "the attached World to own its VFX GPU runtime resource",
+              "repair the host attachment before retrying the preview command",
+              { requestedGeneration, currentGeneration: current.generation }
+            )
+          );
+        }
+        if (!world.get(player, ParticleEffectPlayer).ok) {
+          return err(
+            controlFailure(
+              "vfx-host-control-player-unavailable",
+              "a live entity with ParticleEffectPlayer in the attached World",
+              "discard the stale player handle or target a VFX player owned by this World",
+              { requestedGeneration, currentGeneration: current.generation, player }
+            )
+          );
+        }
+        return ok(action(world.getResource(VFX_GPU_RUNTIME_RESOURCE_KEY)));
+      };
+      const control = {
+        generation: requestedGeneration,
+        replay: ({ player, replayInput }) => withRuntime(player, (runtime) => {
+          runtime.replay(player, replayInput);
+          return Object.freeze({ state: "queued", generation: requestedGeneration });
+        }),
+        setEmitterSessionEnabled: ({ player, emitterId, enabled }) => withRuntime(player, (runtime) => {
+          runtime.setEmitterSessionEnabled(player, emitterId, enabled);
+          return Object.freeze({
+            state: enabled ? "enabled" : "disabled",
+            generation: requestedGeneration
+          });
+        }),
+        setPlayerRenderConsumption: ({ player, enabled }) => withRuntime(player, () => {
+          let paused = pausedPlayers.get(world);
+          if (enabled) {
+            paused?.delete(player);
+            if (paused !== void 0 && paused.size === 0) pausedPlayers.delete(world);
+          } else {
+            paused ??= /* @__PURE__ */ new Set();
+            paused.add(player);
+            pausedPlayers.set(world, paused);
+          }
+          return Object.freeze({
+            state: enabled ? "enabled" : "paused",
+            generation: requestedGeneration
+          });
+        })
+      };
+      return ok(Object.freeze(control));
+    },
+    resolveDataInterfaces: ({ requirements, generation }) => dataInterfaces.resolve(requirements, generation),
+    attachWorld: async ({ world, assets }) => {
+      if (worlds.has(world)) return ok({ state: "already-attached" });
+      if (!decoderLeases.has(assets)) {
+        try {
+          decoderLeases.set(assets, installVfxRuntimeDecoder(assets));
+        } catch (cause) {
+          return err(
+            failure2(
+              "vfx-host-loader-install-failed",
+              "the VFX owner decoder to be installed once in the runtime core",
+              "remove a conflicting particle-effect decoder and retry attachWorld",
+              cause
+            )
+          );
+        }
+      }
+      let pluginContext;
+      try {
+        pluginContext = await createWorldContext(world, [
+          vfxGpuRuntimePlugin(
+            options.maxQueuedTicks === void 0 ? {} : { maxQueuedTicks: options.maxQueuedTicks }
+          )
+        ]);
+      } catch (cause) {
+        return err(
+          failure2(
+            "vfx-host-world-attach-failed",
+            "the World FixedUpdate VFX intent producer to install",
+            "repair the reported World registration conflict and retry",
+            cause
+          )
+        );
+      }
+      let resolver;
+      try {
+        resolver = getAssetRegistryResolver(assets);
+      } catch {
+        resolver = void 0;
+      }
+      const attached = {
+        assets,
+        resolver,
+        pluginContext,
+        generation: nextGeneration++,
+        renderAssets: /* @__PURE__ */ new Map(),
+        pendingRenderAssets: /* @__PURE__ */ new Map(),
+        catalogEpoch: typeof assets.snapshot === "function" ? assets.snapshot().epoch : 0,
+        unsubscribeAssets: () => {
+        }
+      };
+      const subscribe = assets.subscribe;
+      if (subscribe !== void 0) {
+        attached.unsubscribeAssets = subscribe((snapshot) => {
+          if (snapshot.epoch === attached.catalogEpoch) return;
+          attached.catalogEpoch = snapshot.epoch;
+          attached.renderAssets.clear();
+          attached.pendingRenderAssets.clear();
+        });
+      }
+      worlds.set(world, attached);
+      return ok({ state: "attached" });
+    },
+    detachWorld: async ({ world }) => {
+      const attached = worlds.get(world);
+      if (attached === void 0) return ok({ state: "not-attached" });
+      try {
+        await attached.pluginContext.fiber.dispose();
+      } catch (cause) {
+        return err(
+          failure2(
+            "vfx-host-world-detach-failed",
+            "the VFX FixedUpdate producer to detach exactly once",
+            "inspect the World schedule and retry detachWorld",
+            cause
+          )
+        );
+      }
+      pausedPlayers.delete(world);
+      attached.unsubscribeAssets();
+      attached.renderAssets.clear();
+      attached.pendingRenderAssets.clear();
+      worlds.delete(world);
+      return ok({ state: "detached" });
+    }
+  };
+}
+
+export { PARTICLE_SHADER_IDENTIFIERS, VFX_EVENT_BYTES, VFX_EVENT_COUNTER_BYTES, VFX_EVENT_INPUT_BYTES, createCameraProvider, createSceneDepthProvider, createTopologyResourcePlan, createVfxDataInterfaceRegistry, createVfxRenderInspectSnapshot, createVfxRuntimeHost, encodeEventInputs, eventCapacity, eventCounterData, eventInputCapacity, gpuParticleRenderFeature, installVfxRuntimeDecoder, observeStagePlan, resolveBillboardAdvancedState, stageDispatches, stageRecoveryReadiness, topologyCapacitySnapshot, topologyRecoveryHint, validatedStagePlan };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map