@forgeax/engine-vfx-render 0.0.0-dev.8d955ade1c79

package/dist/index.mjs

@@ -0,0 +1,1308 @@
+import { frustum } from '@forgeax/engine-math';
+import { Transform } from '@forgeax/engine-scene';
+import { err, ok } from '@forgeax/engine-types';
+import { VFX_GPU_RUNTIME_RESOURCE_KEY, vfxGpuEffectContribution, vfxGpuEffectPackLoader, vfxGpuRuntimePlugin, resolveVfxDataInterfaces, ParticleEffectPlayer } from '@forgeax/engine-vfx';
+import { getAssetRegistryResolver } from '@forgeax/engine-assets-runtime';
+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);
+}
+
+// ../render/src/errors/render.ts
+var renderFeatureRecoveryHintByRecovery = {
+  "next-frame": (featureIdentity, stage) => `correct '${featureIdentity}' ${stage} data and retry on the next frame`,
+  "renderer-recover": (featureIdentity, _stage) => `wait for renderer recovery before retrying '${featureIdentity}'`,
+  registration: (featureIdentity, _stage) => `correct '${featureIdentity}' registration before retrying`
+};
+var RenderFeatureStageFailedError = class extends Error {
+  code = "render-feature-stage-failed";
+  expected;
+  hint;
+  detail;
+  constructor(featureIdentity, order, stage, recovery) {
+    const expected = `feature '${featureIdentity}' completes its ${stage} stage without an error`;
+    const hint = renderFeatureRecoveryHintByRecovery[recovery](featureIdentity, stage);
+    super(`render feature '${featureIdentity}' failed during ${stage}`);
+    this.name = "RenderFeatureStageFailedError";
+    this.expected = expected;
+    this.hint = hint;
+    this.detail = { featureIdentity, order, stage, recovery };
+  }
+};
+var RENDER_FEATURE_VERTEX_LAYOUTS = Object.freeze({
+  positionSizeColorInstance: "position-size-color-instance",
+  billboardMaterialInstance: "billboard-material-instance",
+  topologySegmentInstance: "topology-segment-instance",
+  meshGeometryMaterialInstance: "mesh-geometry-material-instance"
+});
+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 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 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;
+}
+
+// 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 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,
+    stageOutput: input.stageOutput ?? "empty",
+    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 worldCenter = 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, worldCenter, radius * scale);
+}
+function resetData(size) {
+  return new Uint8Array(size);
+}
+function requiresSceneDepth(intent) {
+  return (intent.emitter.reflection.dataInterfaces ?? []).some(
+    (requirement) => requirement.kind === "scene-depth"
+  );
+}
+function planFailure() {
+  return new RenderFeatureStageFailedError(IDENTITY, -1, "plan", "next-frame");
+}
+function planName(value, maxLength = 24) {
+  const normalized = value.toLowerCase().replaceAll(/[^a-z0-9.-]/g, "-");
+  return (normalized.length === 0 ? "unnamed" : normalized).slice(0, maxLength);
+}
+function computeBindingEntries(intent, resources) {
+  const declared = new Set(
+    (intent.emitter.reflection.bindings[0]?.entries ?? []).filter((entry) => entry.buffer !== void 0).map((entry) => entry.binding)
+  );
+  return Object.entries(resources).flatMap(
+    ([binding, resource]) => declared.has(Number(binding)) ? [{ binding: Number(binding), resource }] : []
+  );
+}
+function simulationDispatches(intent, stages) {
+  const groups = Math.max(1, Math.ceil(intent.emitter.capacity / WORKGROUP_SIZE));
+  return [
+    { kind: "direct", entryPoint: "forgeax_vfx_spawn_main", workgroups: [groups] },
+    { kind: "direct", entryPoint: "forgeax_vfx_update_main", workgroups: [groups] },
+    ...stages.stages.map((stage) => ({
+      kind: "direct",
+      entryPoint: stage.entryPoint,
+      workgroups: [groups]
+    })),
+    { kind: "direct", entryPoint: "forgeax_vfx_scan_blocks_main", workgroups: [groups] },
+    { kind: "direct", entryPoint: "forgeax_vfx_scan_block_offsets_main", workgroups: [1] },
+    { kind: "direct", entryPoint: "forgeax_vfx_add_offsets_main", workgroups: [groups] },
+    { kind: "direct", entryPoint: "forgeax_vfx_compact_main", workgroups: [groups] },
+    {
+      kind: "direct",
+      entryPoint: "forgeax_vfx_event_main",
+      workgroups: [Math.max(1, Math.ceil(eventInputCapacity(intent.emitter) / 64))]
+    }
+  ];
+}
+function gpuParticleRenderFeature(options) {
+  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 ?? [];
+          return requirements.length === 0 || options.dataInterfaces?.resolve(requirements, intent.instanceGeneration).ok === true;
+        });
+        extracted.push({ world, runtime, camera, intents });
+      }
+      return ok({ worlds: extracted, frameNumber: context.frameNumber });
+    },
+    plan: (frame, context) => {
+      const resources = [];
+      const passes = [];
+      const dispatchedIntents = /* @__PURE__ */ new Set();
+      const colorTarget = context.targets.find((candidate) => candidate.kind === "color") ?? context.targets.find((candidate) => candidate.kind === "swapchain");
+      const depthTarget = context.targets.find((candidate) => candidate.kind === "depth");
+      for (const [worldIndex, entry] of frame.worlds.entries()) {
+        for (const [intentIndex, intent] of entry.intents.entries()) {
+          if (!entry.runtime.isEmitterSessionEnabled(intent.player, intent.emitter.id)) continue;
+          const localToWorld = emitterTransform(entry.world, intent);
+          const visible = emitterVisible(intent, entry.camera, localToWorld);
+          entry.runtime.setEmitterCameraVisibility(intent.player, intent.emitter.id, visible);
+          if (!visible) continue;
+          if (requiresSceneDepth(intent) && depthTarget === void 0) continue;
+          const stagePlan = validatedStagePlan(
+            intent.emitter.reflection.stages,
+            intent.instanceGeneration
+          );
+          if (!stagePlan.ok) return err(planFailure());
+          const prefix = `vfx.w-${worldIndex}.i-${intentIndex}.${planName(intent.emitter.id)}`;
+          const program = `${prefix}.compute-program`;
+          const particles = `${prefix}.particles`;
+          const runtime = `${prefix}.runtime`;
+          const aliveIndices = `${prefix}.alive-indices`;
+          const counters = `${prefix}.counters`;
+          const indirect = `${prefix}.indirect`;
+          const scratch = `${prefix}.scratch`;
+          const sharedInstances = `${prefix}.shared-instances`;
+          const eventInputs = `${prefix}.event-inputs`;
+          const events = `${prefix}.events`;
+          const bindings = `${prefix}.simulation-bindings`;
+          const capacity = intent.emitter.capacity;
+          const renderers = intent.emitter.renderers;
+          const meshes = renderers.map(
+            (renderer) => renderer.kind === "mesh" ? options.mesh?.read(entry.world, renderer.mesh) : void 0
+          );
+          const indirectWords = new Uint32Array(Math.max(1, renderers.length) * 5);
+          for (const [rendererIndex, renderer] of renderers.entries()) {
+            const mesh = meshes[rendererIndex];
+            const submesh = renderer.kind === "mesh" ? mesh?.submeshes[renderer.submesh ?? 0] : void 0;
+            if (renderer.kind === "mesh" && submesh === void 0) return err(planFailure());
+            if ((renderer.kind === "ribbon" || renderer.kind === "trail" || renderer.kind === "beam") && !createTopologyResourcePlan(renderer).ok) {
+              return err(planFailure());
+            }
+            indirectWords[rendererIndex * 5] = renderer.kind === "mesh" ? mesh?.indices === void 0 ? submesh?.vertexCount ?? 0 : submesh?.indexCount ?? 0 : 6;
+            indirectWords[rendererIndex * 5 + 2] = renderer.kind === "mesh" && mesh?.indices !== void 0 ? submesh?.indexOffset ?? 0 : 0;
+          }
+          const scratchBytes = (capacity * 2 + Math.ceil(capacity / WORKGROUP_SIZE)) * 4;
+          const eventInputBytes = Math.max(
+            4,
+            eventInputCapacity(intent.emitter) * VFX_EVENT_INPUT_BYTES
+          );
+          const eventBytes = Math.max(4, eventCapacity(intent.emitter) * VFX_EVENT_BYTES);
+          resources.push(
+            {
+              kind: "compute-program",
+              name: program,
+              program: {
+                wgsl: intent.emitter.wgsl,
+                entryPoints: intent.emitter.reflection.entryPoints,
+                bindings: intent.emitter.reflection.bindings
+              }
+            },
+            {
+              kind: "buffer",
+              name: particles,
+              size: capacity * PARTICLE_BYTES,
+              usage: ["storage"],
+              ...intent.reset ? { data: resetData(capacity * PARTICLE_BYTES) } : {}
+            },
+            { kind: "buffer", name: aliveIndices, size: capacity * 4, usage: ["storage"] },
+            {
+              kind: "buffer",
+              name: counters,
+              size: COUNTERS_BYTES,
+              usage: ["storage"],
+              ...intent.reset ? { data: resetData(COUNTERS_BYTES) } : {}
+            },
+            {
+              kind: "buffer",
+              name: indirect,
+              size: indirectWords.byteLength,
+              usage: ["storage", "indirect"],
+              data: indirectWords
+            },
+            {
+              kind: "buffer",
+              name: scratch,
+              size: scratchBytes,
+              usage: ["storage"],
+              ...intent.reset ? { data: resetData(scratchBytes) } : {}
+            },
+            {
+              kind: "buffer",
+              name: sharedInstances,
+              size: capacity * Math.max(BILLBOARD_INSTANCE_BYTES, MESH_INSTANCE_BYTES),
+              usage: ["storage", "vertex"]
+            },
+            {
+              kind: "buffer",
+              name: eventInputs,
+              size: eventInputBytes,
+              usage: ["storage"],
+              data: encodeEventInputs(intent)
+            },
+            {
+              kind: "buffer",
+              name: events,
+              size: eventBytes,
+              usage: ["storage"],
+              ...intent.reset ? { data: resetData(eventBytes) } : {}
+            },
+            {
+              kind: "buffer",
+              name: runtime,
+              size: RUNTIME_BYTES,
+              usage: ["uniform"],
+              data: runtimeData(intent, entry.camera, void 0, localToWorld)
+            },
+            {
+              kind: "compute-bindings",
+              name: bindings,
+              program,
+              entries: computeBindingEntries(intent, {
+                0: particles,
+                1: runtime,
+                2: aliveIndices,
+                3: counters,
+                4: indirect,
+                5: scratch,
+                6: sharedInstances,
+                8: eventInputs,
+                9: events
+              })
+            }
+          );
+          const entryPoints = new Set(intent.emitter.reflection.entryPoints);
+          const dispatches = simulationDispatches(intent, stagePlan.value).filter(
+            (dispatch) => entryPoints.has(dispatch.entryPoint)
+          );
+          if (dispatches.length > 0) {
+            passes.push({
+              kind: "compute",
+              name: `${prefix}.simulate`,
+              program,
+              bindings,
+              dispatches
+            });
+            dispatchedIntents.add(intent);
+          }
+          for (const [rendererIndex, renderer] of renderers.entries()) {
+            const rendererPrefix = `${prefix}.renderer-${rendererIndex}`;
+            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(planFailure());
+            const material = options.material?.read(entry.world, renderer.material);
+            const materialPass = particleMaterialPass(renderer.kind, material);
+            const mesh = meshes[rendererIndex];
+            const submesh = renderer.kind === "mesh" ? mesh?.submeshes[renderer.submesh ?? 0] : void 0;
+            const indexFormat = mesh?.indices instanceof Uint32Array ? "uint32" : "uint16";
+            const instances = `${rendererPrefix}.instances`;
+            const history = `${rendererPrefix}.history`;
+            const projectionRuntime = `${rendererPrefix}.runtime`;
+            const projectionBindings = `${rendererPrefix}.compute-bindings`;
+            const vertexLayout = isBillboard ? RENDER_FEATURE_VERTEX_LAYOUTS.billboardMaterialInstance : isTopology ? RENDER_FEATURE_VERTEX_LAYOUTS.topologySegmentInstance : RENDER_FEATURE_VERTEX_LAYOUTS.meshGeometryMaterialInstance;
+            const instanceBytes = isTopology ? topologyPlan?.value.vertexBytes ?? 16 : capacity * (isBillboard ? BILLBOARD_INSTANCE_BYTES : MESH_INSTANCE_BYTES);
+            const historyBytes = renderer.kind === "trail" ? Math.max(16, renderer.capacity * renderer.historyLength * 16) : 16;
+            resources.push(
+              {
+                kind: "buffer",
+                name: instances,
+                size: instanceBytes,
+                usage: ["storage", "vertex"]
+              },
+              {
+                kind: "buffer",
+                name: history,
+                size: historyBytes,
+                usage: ["storage"],
+                ...intent.reset ? { data: resetData(historyBytes) } : {}
+              },
+              {
+                kind: "buffer",
+                name: projectionRuntime,
+                size: RUNTIME_BYTES,
+                usage: ["uniform"],
+                data: runtimeData(
+                  { ...intent, fixedDelta: 0, spawnCount: 0 },
+                  entry.camera,
+                  material,
+                  localToWorld,
+                  renderer,
+                  rendererIndex
+                )
+              },
+              {
+                kind: "compute-bindings",
+                name: projectionBindings,
+                program,
+                entries: computeBindingEntries(intent, {
+                  0: particles,
+                  1: projectionRuntime,
+                  2: aliveIndices,
+                  3: counters,
+                  4: indirect,
+                  5: history,
+                  6: instances,
+                  8: eventInputs,
+                  9: events
+                })
+              }
+            );
+            const projectionDispatches = [];
+            const pushProjection = (entryPoint, workgroups) => {
+              if (!entryPoints.has(entryPoint)) return;
+              projectionDispatches.push({
+                kind: "direct",
+                entryPoint,
+                workgroups: [Math.max(1, workgroups)]
+              });
+            };
+            if (isBillboard && renderer.sorting === "back-to-front") {
+              pushProjection("forgeax_vfx_sort_main", 1);
+            }
+            if (renderer.kind === "trail") {
+              pushProjection(
+                "forgeax_vfx_trail_history_main",
+                Math.ceil(renderer.capacity / WORKGROUP_SIZE)
+              );
+            }
+            const projectionCount = renderer.kind === "trail" ? renderer.capacity * Math.max(1, renderer.historyLength - 1) : isTopology ? renderer.capacity : capacity;
+            pushProjection(
+              renderer.kind === "billboard" ? "forgeax_vfx_billboard_main" : renderer.kind === "mesh" ? "forgeax_vfx_mesh_main" : `forgeax_vfx_${renderer.kind}_main`,
+              Math.ceil(projectionCount / WORKGROUP_SIZE)
+            );
+            if (projectionDispatches.length > 0) {
+              passes.push({
+                kind: "compute",
+                name: `${rendererPrefix}.project`,
+                program,
+                bindings: projectionBindings,
+                dispatches: projectionDispatches
+              });
+            }
+            const graphicsProgram = `${rendererPrefix}.graphics-program`;
+            const graphicsBindings = `${rendererPrefix}.graphics-bindings`;
+            const vertexData = `${rendererPrefix}.vertex-data`;
+            const renderState = isBillboard && depthTarget !== void 0 ? { ...materialPass.renderState ?? {}, depthWriteEnabled: false } : materialPass.renderState;
+            resources.push(
+              {
+                kind: "graphics-program",
+                name: graphicsProgram,
+                program: {
+                  shader: materialPass.shader,
+                  vertexLayout,
+                  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 },
+                  ...renderState === void 0 ? {} : { renderState }
+                }
+              },
+              {
+                kind: "graphics-bindings",
+                name: graphicsBindings,
+                program: graphicsProgram,
+                values: {
+                  group: 0,
+                  runtime: projectionRuntime,
+                  instances,
+                  ...isBillboard ? { sceneDepthBinding: 1 } : {}
+                },
+                ...isBillboard && depthTarget !== void 0 ? { logicalTargets: { sceneDepth: depthTarget.name } } : {}
+              },
+              { kind: "vertex-data", name: vertexData, layout: vertexLayout, buffer: instances }
+            );
+            const drawBindings = [graphicsBindings];
+            if (particleMaterialUsesBindings(material)) {
+              const materialBindings = `${rendererPrefix}.material-bindings`;
+              resources.push({
+                kind: "graphics-bindings",
+                name: materialBindings,
+                program: graphicsProgram,
+                values: {
+                  group: 1,
+                  material: { world: worldIndex, guid: renderer.material }
+                }
+              });
+              drawBindings.push(materialBindings);
+            }
+            const vertexBindings = [];
+            let indexData;
+            if (renderer.kind === "mesh") {
+              if (mesh === void 0) return err(planFailure());
+              const geometryBuffer = `${rendererPrefix}.geometry-buffer`;
+              const geometry = `${rendererPrefix}.geometry`;
+              const geometryData = canonicalMeshVertices(mesh);
+              resources.push(
+                {
+                  kind: "buffer",
+                  name: geometryBuffer,
+                  size: geometryData.byteLength,
+                  usage: ["vertex"],
+                  data: geometryData
+                },
+                {
+                  kind: "vertex-data",
+                  name: geometry,
+                  layout: vertexLayout,
+                  buffer: geometryBuffer
+                }
+              );
+              vertexBindings.push(
+                { slot: 0, resource: geometry },
+                { slot: 1, resource: vertexData }
+              );
+              if (mesh.indices !== void 0) {
+                const indexBuffer = `${rendererPrefix}.index-buffer`;
+                const indices = `${rendererPrefix}.indices`;
+                resources.push(
+                  {
+                    kind: "buffer",
+                    name: indexBuffer,
+                    size: mesh.indices.byteLength,
+                    usage: ["index"],
+                    data: mesh.indices
+                  },
+                  {
+                    kind: "index-data",
+                    name: indices,
+                    format: indexFormat,
+                    buffer: indexBuffer
+                  }
+                );
+                indexData = { resource: indices, format: indexFormat };
+              }
+            } else {
+              vertexBindings.push({ slot: 0, resource: vertexData });
+            }
+            passes.push({
+              kind: "raster",
+              name: `${rendererPrefix}.raster`,
+              colorAttachments: [
+                {
+                  target: colorTarget?.name ?? "swapchain",
+                  loadOp: "load",
+                  storeOp: "store"
+                }
+              ],
+              ...depthTarget === void 0 ? {} : {
+                depthStencilAttachment: {
+                  target: depthTarget.name,
+                  depthLoadOp: "load",
+                  depthStoreOp: "store"
+                }
+              },
+              ...isBillboard && depthTarget !== void 0 ? { sampledTargets: [depthTarget.name] } : {},
+              draws: [
+                {
+                  program: graphicsProgram,
+                  bindings: drawBindings,
+                  vertexData: vertexBindings,
+                  ...indexData === void 0 ? {} : { indexData },
+                  draw: {
+                    kind: indexData === void 0 ? "draw-indirect" : "draw-indexed-indirect",
+                    resource: indirect,
+                    offset: rendererIndex * 20
+                  }
+                }
+              ]
+            });
+          }
+        }
+      }
+      for (const entry of frame.worlds) {
+        for (const intent of entry.intents) {
+          if (dispatchedIntents.has(intent)) {
+            entry.runtime.markEventDispatched(intent.player, intent.eventCounters);
+          }
+        }
+        const lastIntent = entry.intents.at(-1);
+        if (lastIntent !== void 0) entry.runtime.commit(lastIntent.sequence);
+      }
+      return ok({ resources, passes });
+    }
+  };
+}
+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 registries = /* @__PURE__ */ new WeakSet();
+  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;
+    if ("lookup" in attached.assets) {
+      const lookup = attached.assets.lookup;
+      const legacy = lookup.call(attached.assets, guid);
+      if (legacy?.kind === kind) {
+        attached.renderAssets.set(key, legacy);
+        return legacy;
+      }
+    }
+    const resolved = attached.resolver?.lookup(guid);
+    if (resolved?.kind === kind) {
+      attached.renderAssets.set(key, resolved);
+      return resolved;
+    }
+    if ("load" in attached.assets && typeof attached.assets.load === "function" && !attached.pendingRenderAssets.has(key)) {
+      const epoch = attached.catalogEpoch;
+      const load = attached.assets.load;
+      const request = 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 (!registries.has(assets)) {
+        try {
+          if ("loaders" in assets) {
+            assets.loaders.registerPackLoader(vfxGpuEffectPackLoader);
+          } else if ("installDecoder" in assets) {
+            assets.installDecoder(vfxGpuEffectContribution.kind, vfxGpuEffectContribution.decoder);
+          } else {
+            throw new TypeError("VFX assets registry exposes neither loaders nor installDecoder");
+          }
+          registries.add(assets);
+        } catch (cause) {
+          return err(
+            failure2(
+              "vfx-host-loader-install-failed",
+              "the v2 VFX loader to be registered once",
+              "remove a conflicting particle-effect loader 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;
+      if (!("loaders" in assets) && "installDecoder" in assets) {
+        try {
+          resolver = getAssetRegistryResolver(assets);
+        } catch {
+          resolver = void 0;
+        }
+      }
+      const attached = {
+        assets,
+        resolver,
+        pluginContext,
+        generation: nextGeneration++,
+        renderAssets: /* @__PURE__ */ new Map(),
+        pendingRenderAssets: /* @__PURE__ */ new Map(),
+        catalogEpoch: "snapshot" in assets && typeof assets.snapshot === "function" ? assets.snapshot().epoch : 0,
+        unsubscribeAssets: () => {
+        }
+      };
+      if ("subscribe" in assets && typeof assets.subscribe === "function") {
+        attached.unsubscribeAssets = assets.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