@forgeax/engine-vfx 0.1.28 → 0.1.29

package/dist/index.mjs

@@ -8,13 +8,13 @@ var particleEffectContribution = {
   decoder: {
     async decode({ envelope }) {
       const payload = envelope.payload;
-      if (payload.kind === "particle-effect" && payload.schemaVersion === 2 && payload.emitters.length === payload.program.emitters.length && payload.programFingerprint === payload.program.fingerprint) {
+      if (payload.kind === "particle-effect" && payload.schemaVersion === 3 && payload.program.format === "forgeax-vfx-program-3" && payload.emitters.length === payload.program.emitters.length && payload.programFingerprint === payload.program.fingerprint) {
         return ok(payload);
       }
       return err({
         code: "asset-package-invalid",
-        expected: "a schema v2 particle payload matching its cooked program",
-        hint: "recook the particle effect atomically with its GPU program",
+        expected: "a schemaVersion 3 particle payload matching its cooked Program v3",
+        hint: "cold-cook the legacy payload with the Program v3 compiler and publish atomically",
         detail: { guid: envelope.guid, reason: "particle owner validation failed" }
       });
     }
@@ -22,31 +22,26 @@ var particleEffectContribution = {
 };
 
 // src/authoring-descriptor.ts
-var CAPABILITIES = Object.freeze([
+var V3_CAPABILITIES = Object.freeze([
   Object.freeze({ id: "wgsl-behavior", state: "executable" }),
   Object.freeze({ id: "multi-emitter", state: "executable" }),
   Object.freeze({ id: "deterministic-replay", state: "executable" }),
   Object.freeze({ id: "emitter-visibility", state: "executable" }),
-  Object.freeze({
-    id: "runtime-parameters",
-    state: "partial",
-    reason: "reflected and packed, but not yet bound to managed author WGSL"
-  }),
-  Object.freeze({
-    id: "custom-attributes",
-    state: "partial",
-    reason: "reflected without executable per-particle custom storage"
-  }),
+  Object.freeze({ id: "runtime-parameters", state: "executable" }),
+  Object.freeze({ id: "custom-attributes", state: "executable" }),
+  Object.freeze({ id: "renderer-semantics", state: "executable" }),
+  Object.freeze({ id: "material-particle-inputs", state: "executable" }),
   Object.freeze({
     id: "data-interfaces",
     state: "partial",
-    reason: "requirements resolve provider readiness without author resource bindings"
+    reason: "camera, single-sample scene depth, and noise require generation-owned providers"
   })
 ]);
 function isVfxGpuEffectAsset(value) {
   if (typeof value !== "object" || value === null) return false;
   const candidate = value;
-  return candidate.kind === "particle-effect" && candidate.schemaVersion === 2 && typeof candidate.guid === "string" && candidate.guid.length > 0 && typeof candidate.program === "object" && candidate.program !== null && candidate.program.format === "forgeax-vfx-program-2" && typeof candidate.program.fingerprint === "string" && Array.isArray(candidate.program.emitters);
+  const program = candidate.program;
+  return candidate.kind === "particle-effect" && candidate.schemaVersion === 3 && typeof candidate.guid === "string" && candidate.guid.length > 0 && typeof program === "object" && program !== null && program.format === "forgeax-vfx-program-3" && typeof program.fingerprint === "string" && Array.isArray(program.emitters);
 }
 function label(path) {
   const leaf = path.split(".").at(-1) ?? path;
@@ -243,7 +238,7 @@ function describeVfxGpuEffect(effect) {
   return Object.freeze({
     version: 1,
     assetGuid: effect.guid,
-    schemaVersion: 2,
+    schemaVersion: effect.schemaVersion,
     artifactFingerprint: effect.program.fingerprint,
     emitters: Object.freeze(effect.program.emitters.map(emitterNode)),
     timeline: Object.freeze(
@@ -257,7 +252,7 @@ function describeVfxGpuEffect(effect) {
       )
     ),
     dependencies: dependencies(effect),
-    capabilities: CAPABILITIES
+    capabilities: V3_CAPABILITIES
   });
 }
 var PARTICLE_CODE_DEFAULT_MODULE_ID = "forgeax_vfx::default";
@@ -326,8 +321,8 @@ function parseStageResources(value, path, stageId) {
   const resources = [];
   const names = /* @__PURE__ */ new Set();
   for (const item of value.split(",")) {
-    const [name, access, extra] = item.split(":");
-    if (name === void 0 || access === void 0 || extra !== void 0 || !STAGE_RESOURCE_NAMES.has(name) || access !== "read" && access !== "write" && access !== "read-write" || names.has(name)) {
+    const [name, access, extra2] = item.split(":");
+    if (name === void 0 || access === void 0 || extra2 !== void 0 || !STAGE_RESOURCE_NAMES.has(name) || access !== "read" && access !== "write" && access !== "read-write" || names.has(name)) {
       return stageInvalid(
         path,
         "known resources with unique read, write, or read-write access",
@@ -408,8 +403,8 @@ function parseVfxStageDeclarations(source) {
 }
 function parseEmitter(value, index, ids) {
   const path = `emitters[${index}]`;
-  if (!record(value)) return invalid(path, "a v2 emitter object");
-  const extra = allowed(value, [
+  if (!record(value)) return invalid(path, "a Program v3 emitter object");
+  const extra2 = allowed(value, [
     "id",
     "capacity",
     "backend",
@@ -422,7 +417,7 @@ function parseEmitter(value, index, ids) {
     "events",
     "simulationWhenCulled"
   ]);
-  if (extra !== void 0) return invalid(`${path}.${extra}`, "a v2 emitter field");
+  if (extra2 !== void 0) return invalid(`${path}.${extra2}`, "a Program v3 emitter field");
   if (!text(value.id) || ids.has(value.id)) return invalid(`${path}.id`, "a unique non-empty id");
   const id = value.id;
   ids.add(id);
@@ -722,20 +717,12 @@ function parseEmitter(value, index, ids) {
   }
   return ok(value);
 }
-function parseParticleEffectSourceV2(value) {
+function parseParticleEffectSourceStructure(value) {
   if (!record(value)) return invalid("$", "a particle effect source object");
-  if (value.schemaVersion !== 2) {
-    return err({
-      code: "vfx-source-version-unsupported",
-      expected: "ParticleEffectSource schemaVersion 2",
-      hint: "migrate code behavior to WGSL and recook; v1 is not interpreted at runtime",
-      detail: { path: "schemaVersion" }
-    });
-  }
-  const extra = allowed(value, ["schemaVersion", "emitters"]);
-  if (extra !== void 0) return invalid(extra, "a root field: emitters");
+  const extra2 = allowed(value, ["schemaVersion", "emitters"]);
+  if (extra2 !== void 0) return invalid(extra2, "a root field: emitters");
   if (!Array.isArray(value.emitters) || value.emitters.length === 0) {
-    return invalid("emitters", "at least one v2 emitter");
+    return invalid("emitters", "at least one Program v3 emitter");
   }
   const ids = /* @__PURE__ */ new Set();
   const emitters = [];
@@ -768,16 +755,297 @@ function parseParticleEffectSourceV2(value) {
   }
   return ok(
     Object.freeze({
-      schemaVersion: 2,
+      schemaVersion: 3,
       emitters: Object.freeze(emitters)
     })
   );
 }
-function defineParticleEffectSourceV2(source) {
-  const parsed = parseParticleEffectSourceV2(source);
+var PARTICLE_RENDERER_SEMANTICS = Object.freeze({
+  billboard: Object.freeze([
+    "position",
+    "color",
+    "size",
+    "rotation",
+    "age",
+    "subImage",
+    "sort",
+    "visibility"
+  ]),
+  mesh: Object.freeze(["position", "color", "orientation", "scale", "visibility"]),
+  ribbon: Object.freeze(["position", "color", "width"]),
+  trail: Object.freeze(["position", "color", "width", "taper"]),
+  beam: Object.freeze(["position", "endpoint", "color", "width"])
+});
+function coreAttribute(name) {
+  return { source: "core", name };
+}
+function defaultParticleRendererAttributes(kind) {
+  switch (kind) {
+    case "billboard":
+      return {
+        position: coreAttribute("position"),
+        color: coreAttribute("color"),
+        size: coreAttribute("sprite_size"),
+        rotation: coreAttribute("sprite_rotation"),
+        age: coreAttribute("age"),
+        visibility: coreAttribute("alive")
+      };
+    case "mesh":
+      return {
+        position: coreAttribute("position"),
+        color: coreAttribute("color"),
+        orientation: coreAttribute("mesh_orientation"),
+        scale: coreAttribute("mesh_scale"),
+        visibility: coreAttribute("alive")
+      };
+    case "ribbon":
+      return {
+        position: coreAttribute("position"),
+        color: coreAttribute("color")
+      };
+    case "trail":
+      return {
+        position: coreAttribute("position"),
+        color: coreAttribute("color")
+      };
+    case "beam":
+      return {
+        position: coreAttribute("position"),
+        endpoint: coreAttribute("velocity"),
+        color: coreAttribute("color")
+      };
+  }
+}
+function record2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function fail(path, expected) {
+  return err({
+    code: "vfx-source-invalid",
+    expected,
+    hint: `repair ${path} and recook the Program v3 particle effect`,
+    detail: { path }
+  });
+}
+function extra(value, allowed2) {
+  const keys = new Set(allowed2);
+  return Object.keys(value).find((key) => !keys.has(key));
+}
+var CORE_NAMES = /* @__PURE__ */ new Set([
+  "position",
+  "age",
+  "velocity",
+  "lifetime",
+  "color",
+  "sprite_size",
+  "sprite_rotation",
+  "sub_image",
+  "mesh_orientation",
+  "mesh_scale",
+  "material_random",
+  "id",
+  "alive"
+]);
+function validateAttributes(value, path) {
+  if (value === void 0) return ok(void 0);
+  if (!record2(value)) return fail(path, "a semantic-to-attribute object");
+  for (const [semantic, reference] of Object.entries(value)) {
+    if (!record2(reference) || reference.source !== "core" && reference.source !== "custom") {
+      return fail(`${path}.${semantic}`, "{ source: 'core' | 'custom', name: string }");
+    }
+    if (typeof reference.name !== "string" || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(reference.name)) {
+      return fail(`${path}.${semantic}.name`, "a non-empty identifier");
+    }
+    if (reference.source === "core" && !CORE_NAMES.has(reference.name)) {
+      return fail(`${path}.${semantic}.name`, "a VfxParticle core attribute");
+    }
+    const referenceExtra = extra(reference, ["source", "name"]);
+    if (referenceExtra !== void 0)
+      return fail(`${path}.${semantic}.${referenceExtra}`, "source and name only");
+  }
+  return ok(value);
+}
+function validateMaterialInputs(value, path) {
+  if (value === void 0) return ok(void 0);
+  if (!Array.isArray(value) || value.length > 4 || value.some((entry) => typeof entry !== "string" || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(entry))) {
+    return fail(path, "at most four unique particle input names");
+  }
+  if (new Set(value).size !== value.length) return fail(path, "unique particle input names");
+  return ok(Object.freeze([...value]));
+}
+function rendererAllowed(kind) {
+  const common = [
+    "kind",
+    "material",
+    "enabled",
+    "capacity",
+    "overflow",
+    "width",
+    "attributes",
+    "materialInputs"
+  ];
+  switch (kind) {
+    case "billboard":
+      return [...common, "blend", "textureSheet", "pivot", "softParticle", "sorting"];
+    case "mesh":
+      return [
+        "kind",
+        "material",
+        "mesh",
+        "submesh",
+        "enabled",
+        "attributes",
+        "materialInputs",
+        "lighting",
+        "castShadows",
+        "receiveShadows"
+      ];
+    case "ribbon":
+      return [...common, "stripKey", "twist", "facing"];
+    case "trail":
+      return [...common, "historyLength", "taper"];
+    case "beam":
+      return [...common, "endpointField", "taper"];
+    default:
+      return ["kind"];
+  }
+}
+function asStructureRenderer(value) {
+  const common = ["kind", "material", "enabled", "capacity", "overflow", "width"];
+  const result = {};
+  for (const key of common) if (value[key] !== void 0) result[key] = value[key];
+  switch (value.kind) {
+    case "billboard":
+      for (const key of ["blend", "textureSheet", "pivot", "softParticle"])
+        if (value[key] !== void 0) result[key] = value[key];
+      if (value.sorting === "view-depth" || value.sorting === "view-distance")
+        result.sorting = "back-to-front";
+      else if (value.sorting === "custom-ascending" || value.sorting === "custom-descending")
+        result.sorting = "emitter";
+      else if (value.sorting !== void 0) result.sorting = value.sorting;
+      break;
+    case "mesh":
+      for (const key of ["mesh", "submesh"])
+        if (value[key] !== void 0) result[key] = value[key];
+      break;
+    case "ribbon":
+      result.stripKey = value.stripKey;
+      break;
+    case "trail":
+      result.historyLength = value.historyLength;
+      break;
+    case "beam":
+      result.endpointField = value.endpointField;
+      break;
+  }
+  return result;
+}
+function validateRenderer(value, emitterIndex, index) {
+  const path = `emitters[${emitterIndex}].renderers[${index}]`;
+  if (!record2(value) || typeof value.kind !== "string" || typeof value.material !== "string") {
+    return fail(path, "a Program v3 renderer object");
+  }
+  const unknown = extra(value, rendererAllowed(value.kind));
+  if (unknown !== void 0)
+    return fail(`${path}.${unknown}`, "a supported Program v3 renderer field");
+  if (value.lighting !== void 0 && value.lighting !== "unlit" && value.lighting !== "standard")
+    return fail(`${path}.lighting`, "unlit or standard");
+  for (const field2 of ["castShadows", "receiveShadows"]) {
+    if (value[field2] !== void 0 && typeof value[field2] !== "boolean")
+      return fail(`${path}.${field2}`, "a boolean");
+  }
+  for (const field2 of ["twist", "taper"]) {
+    if (value[field2] !== void 0 && (typeof value[field2] !== "number" || !Number.isFinite(value[field2])))
+      return fail(`${path}.${field2}`, "a finite number");
+  }
+  if (value.facing !== void 0 && value.facing !== "camera" && value.facing !== "velocity" && value.facing !== "custom")
+    return fail(`${path}.facing`, "camera, velocity, or custom");
+  if (value.sorting !== void 0 && value.kind === "billboard" && !["none", "view-depth", "view-distance", "custom-ascending", "custom-descending"].includes(
+    value.sorting
+  ))
+    return fail(`${path}.sorting`, "a Program v3 sorting mode");
+  const attrs = validateAttributes(value.attributes, `${path}.attributes`);
+  if (!attrs.ok) return attrs;
+  if (attrs.value !== void 0) {
+    for (const semantic of Object.keys(attrs.value)) {
+      if (!PARTICLE_RENDERER_SEMANTICS[value.kind]?.includes(
+        semantic
+      )) {
+        return fail(
+          `${path}.attributes.${semantic}`,
+          "a semantic supported by this renderer topology"
+        );
+      }
+    }
+  }
+  const inputs = validateMaterialInputs(value.materialInputs, `${path}.materialInputs`);
+  if (!inputs.ok) return inputs;
+  return ok({
+    ...value,
+    ...attrs.value === void 0 ? {} : { attributes: attrs.value },
+    ...inputs.value === void 0 ? {} : { materialInputs: inputs.value }
+  });
+}
+function parseParticleEffectSourceV3(value) {
+  if (!record2(value)) return fail("$", "a Program v3 particle effect source object");
+  if (value.schemaVersion !== 3) {
+    return err({
+      code: "vfx-source-version-unsupported",
+      expected: "ParticleEffectSource schemaVersion 3",
+      hint: "cold-cook the source with the Program v3 compiler; older versions are not executable",
+      detail: { path: "schemaVersion" }
+    });
+  }
+  const rootExtra = extra(value, ["schemaVersion", "emitters"]);
+  if (rootExtra !== void 0) return fail(rootExtra, "schemaVersion and emitters only");
+  if (!Array.isArray(value.emitters) || value.emitters.length === 0)
+    return fail("emitters", "at least one Program v3 emitter");
+  const renderers = /* @__PURE__ */ new Map();
+  for (const [emitterIndex, emitter] of value.emitters.entries()) {
+    if (record2(emitter) && Array.isArray(emitter.renderers)) {
+      const parsed2 = [];
+      for (const [index, renderer] of emitter.renderers.entries()) {
+        const result = validateRenderer(renderer, emitterIndex, index);
+        if (!result.ok) return result;
+        parsed2.push(result.value);
+      }
+      renderers.set(typeof emitter.id === "string" ? emitter.id : String(renderers.size), parsed2);
+    }
+  }
+  const structuralInput = {
+    schemaVersion: 3,
+    emitters: value.emitters.map((emitter) => {
+      if (!record2(emitter)) return emitter;
+      return {
+        ...emitter,
+        renderers: Array.isArray(emitter.renderers) ? emitter.renderers.map(
+          (renderer) => record2(renderer) ? asStructureRenderer(renderer) : renderer
+        ) : emitter.renderers
+      };
+    })
+  };
+  const parsed = parseParticleEffectSourceStructure(structuralInput);
+  if (!parsed.ok) return parsed;
+  const emitters = parsed.value.emitters.map((emitter) => ({
+    ...emitter,
+    renderers: renderers.get(emitter.id) ?? []
+  }));
+  return ok(Object.freeze({ schemaVersion: 3, emitters: Object.freeze(emitters) }));
+}
+function defineParticleEffectSourceV3(source) {
+  const parsed = parseParticleEffectSourceV3(source);
   if (!parsed.ok) throw new TypeError(`${parsed.error.code}: ${parsed.error.expected}`);
   return source;
 }
+function expectedResourceKind(kind) {
+  switch (kind) {
+    case "camera":
+      return "buffer";
+    case "scene-depth":
+    case "noise":
+      return "texture-view";
+  }
+}
 function failure(code, requirement, expected, hint, detail = {}) {
   return { code, expected, hint, detail: { token: requirement.token, ...detail } };
 }
@@ -859,6 +1127,44 @@ function resolveVfxDataInterfaces(requirements, providers, generation) {
         )
       );
     }
+    const expectedKind = expectedResourceKind(requirement.kind);
+    if (resource.resource === void 0) {
+      return err(
+        failure(
+          "vfx-data-interface-missing",
+          requirement,
+          `${requirement.kind} backed by a resident ${expectedKind} resource`,
+          `refresh provider ${provider.id} with a generation-owned resource before dispatch`,
+          { providerId: provider.id, expectedResourceKind: expectedKind }
+        )
+      );
+    }
+    if (resource.resource.kind !== expectedKind) {
+      return err(
+        failure(
+          "vfx-data-interface-wrong-type",
+          requirement,
+          `${requirement.kind} backed by a ${expectedKind} resource`,
+          `repair provider ${provider.id} so its opaque resource matches the reflected binding kind`,
+          {
+            providerId: provider.id,
+            expectedResourceKind: expectedKind,
+            actualResourceKind: resource.resource.kind
+          }
+        )
+      );
+    }
+    if (requirement.sampleCount !== void 0 && resource.sampleCount !== requirement.sampleCount) {
+      return err(
+        failure(
+          "vfx-data-interface-wrong-type",
+          requirement,
+          `a scene-depth resource with sampleCount=${requirement.sampleCount}`,
+          `provide a single-sample scene depth target for ${provider.id}; MSAA resolve is not implicit`,
+          { providerId: provider.id }
+        )
+      );
+    }
     if (resource.generation !== generation) {
       return err(
         failure(
@@ -886,8 +1192,8 @@ var VECTOR_LENGTH = {
   "vec3<f32>": 3,
   "vec4<f32>": 4
 };
-function fieldList(reflection) {
-  return [...reflection.parameters.fields, ...reflection.custom.fields];
+function fieldList(reflection, includeCustom = false) {
+  return includeCustom ? [...reflection.parameters.fields, ...reflection.custom.fields] : reflection.parameters.fields;
 }
 function zeroValue(type) {
   const length = VECTOR_LENGTH[type];
@@ -898,7 +1204,7 @@ function valueMatches(type, value) {
   if (length === 1) return typeof value === "number" && Number.isFinite(value);
   return Array.isArray(value) && value.length === length && value.every((component) => typeof component === "number" && Number.isFinite(component));
 }
-function fail(code, path, expected, hint, actual) {
+function fail2(code, path, expected, hint, actual) {
   return err({
     code,
     expected,
@@ -907,18 +1213,26 @@ function fail(code, path, expected, hint, actual) {
   });
 }
 function validateReflection(reflection) {
-  if (reflection.version !== 1 || typeof reflection.fingerprint !== "string" || !reflection.fingerprint.startsWith("sha256:")) {
-    return fail(
+  if (reflection.version !== 3 || typeof reflection.fingerprint !== "string" || !reflection.fingerprint.startsWith("sha256:")) {
+    return fail2(
       "vfx-reflection-invalid",
       "reflection",
-      "a version 1 reflection with a sha256 fingerprint",
+      "a version 3 reflection with a sha256 fingerprint",
+      "recook the effect with the current VFX compiler"
+    );
+  }
+  if (reflection.core.name !== "VfxParticle" || reflection.core.stride !== 112 || reflection.core.fields.length === 0 || reflection.customLayout.name !== "VfxCustom" || reflection.customLayout.stride < 0 || reflection.customLayout.lanes < 0) {
+    return fail2(
+      "vfx-reflection-invalid",
+      "reflection.core",
+      "Program v3 Core and Custom layouts derived from the particle schema",
       "recook the effect with the current VFX compiler"
     );
   }
   const names = /* @__PURE__ */ new Set();
   for (const field2 of fieldList(reflection)) {
     if (names.has(field2.name)) {
-      return fail(
+      return fail2(
         "vfx-reflection-invalid",
         field2.name,
         "unique field names across parameters and custom data",
@@ -937,20 +1251,23 @@ function defaultsFor(reflection) {
   return Object.freeze(defaults);
 }
 function validateMap(reflection, values) {
-  const fields2 = new Map(fieldList(reflection).map((field2) => [field2.name, field2]));
+  return validateMapAgainstFields(fieldList(reflection), values);
+}
+function validateMapAgainstFields(reflectedFields, values) {
+  const fields2 = new Map(reflectedFields.map((field2) => [field2.name, field2]));
   for (const name of Object.keys(values)) {
     const field2 = fields2.get(name);
     if (field2 === void 0) {
-      return fail(
+      return fail2(
         "vfx-value-unknown-field",
         name,
-        "a field declared by VfxParameters or VfxCustom",
+        "a field declared by the selected VFX data scope",
         `remove ${name} or declare it in the authored WGSL struct`,
         values[name]
       );
     }
     if (!valueMatches(field2.type, values[name])) {
-      return fail(
+      return fail2(
         "vfx-value-type-mismatch",
         name,
         field2.type,
@@ -974,13 +1291,28 @@ function createVfxEffectContract(reflection) {
   const checked = validateReflection(reflection);
   if (!checked.ok) throw new TypeError(checked.error.hint);
   const defaults = defaultsFor(reflection);
-  const fields2 = fieldList(reflection);
   const customBase = reflection.parameters.size;
-  const packedSize = customBase + reflection.custom.size;
+  const parameterSize = reflection.parameters.size;
+  const customStride = reflection.customLayout.stride;
+  const packedSize = customBase;
+  const packFields = (values, selected, size, baseOffset) => {
+    const checkedValues = validateMapAgainstFields(selected, values);
+    if (!checkedValues.ok) return checkedValues;
+    const bytes = new Uint8Array(size);
+    const view = new DataView(bytes.buffer);
+    for (const field2 of selected) {
+      const value = checkedValues.value[field2.name];
+      if (value === void 0) continue;
+      writeValue(view, baseOffset + field2.offset, field2.type, value);
+    }
+    return ok(bytes);
+  };
   return {
     reflection,
     fingerprint: reflection.fingerprint,
     packedSize,
+    parameterSize: reflection.parameters.size,
+    customStride,
     defaults,
     createValues(initial = {}) {
       const merged = { ...defaults, ...initial };
@@ -990,17 +1322,13 @@ function createVfxEffectContract(reflection) {
       return validateMap(reflection, values);
     },
     pack(values) {
-      const checkedValues = validateMap(reflection, values);
-      if (!checkedValues.ok) return checkedValues;
-      const bytes = new Uint8Array(packedSize);
-      const view = new DataView(bytes.buffer);
-      for (const field2 of fields2) {
-        const value = checkedValues.value[field2.name];
-        if (value === void 0) continue;
-        const base = reflection.parameters.fields.includes(field2) ? 0 : customBase;
-        writeValue(view, base + field2.offset, field2.type, value);
-      }
-      return ok(bytes);
+      return packFields(values, reflection.parameters.fields, parameterSize, 0);
+    },
+    packParameters(values) {
+      return packFields(values, reflection.parameters.fields, parameterSize, 0);
+    },
+    packCustom(values) {
+      return packFields(values, reflection.custom.fields, customStride, 0);
     }
   };
 }
@@ -1009,14 +1337,15 @@ function validateVfxEffectValues(reflection, values) {
 }
 
 // src/gpu-program.ts
-var VFX_GPU_PROGRAM_FORMAT = "forgeax-vfx-program-2";
+var VFX_GPU_PROGRAM_FORMAT = "forgeax-vfx-program-3";
+var VFX_GPU_PROGRAM_FORMAT_V3 = VFX_GPU_PROGRAM_FORMAT;
 var VFX_GPU_PROGRAM_ARTIFACT_KEY = "particle-effect/program.json";
 
 // src/gpu-loader.ts
 function failure2(code, guid, path, expected, hint) {
   return err({ code, expected, hint, detail: { guid, path } });
 }
-function record2(value) {
+function record3(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 function hex(bytes) {
@@ -1031,9 +1360,15 @@ async function fingerprint(bytes) {
 }
 function validReflectionLayout(value) {
   if (value === void 0) return true;
-  if (!record2(value) || value.version !== 1) return false;
-  if (!record2(value.parameters) || !Array.isArray(value.parameters.fields)) return false;
-  if (!record2(value.custom) || !Array.isArray(value.custom.fields)) return false;
+  if (!record3(value) || value.version !== 3) return false;
+  if (!record3(value.parameters) || !Array.isArray(value.parameters.fields)) return false;
+  if (!record3(value.custom) || !Array.isArray(value.custom.fields)) return false;
+  if (value.version === 3) {
+    if (!record3(value.core) || value.core.name !== "VfxParticle" || value.core.stride !== 112) {
+      return false;
+    }
+    if (!record3(value.customLayout) || value.customLayout.name !== "VfxCustom") return false;
+  }
   return typeof value.fingerprint === "string" && value.fingerprint.startsWith("sha256:");
 }
 function stableLayouts(emitters) {
@@ -1041,26 +1376,40 @@ function stableLayouts(emitters) {
   return fingerprints.every((fingerprint2) => fingerprint2 === fingerprints[0]);
 }
 function validEmitter(value) {
-  const reflection = record2(value) && record2(value.reflection) ? value.reflection : void 0;
+  const reflection = record3(value) && record3(value.reflection) ? value.reflection : void 0;
   const layout = reflection !== void 0 ? reflection.layout : void 0;
-  return record2(value) && typeof value.id === "string" && typeof value.module === "string" && value.module.length > 0 && Number.isInteger(value.capacity) && value.capacity > 0 && record2(value.backend) && value.backend.required === "gpu" && Object.keys(value.backend).length === 1 && typeof value.wgsl === "string" && value.wgsl.length > 0 && record2(value.reflection) && validReflectionLayout(layout) && Array.isArray(value.reflection.entryPoints) && value.reflection.entryPoints.includes("forgeax_vfx_spawn_main") && value.reflection.entryPoints.includes("forgeax_vfx_compact_main") && value.reflection.entryPoints.includes("forgeax_vfx_billboard_main") && value.reflection.entryPoints.includes("forgeax_vfx_mesh_main") && value.reflection.entryPoints.includes("forgeax_vfx_ribbon_main") && value.reflection.entryPoints.includes("forgeax_vfx_trail_main") && value.reflection.entryPoints.includes("forgeax_vfx_beam_main");
+  return record3(value) && typeof value.id === "string" && typeof value.module === "string" && value.module.length > 0 && Number.isInteger(value.capacity) && value.capacity > 0 && record3(value.backend) && value.backend.required === "gpu" && Object.keys(value.backend).length === 1 && typeof value.wgsl === "string" && value.wgsl.length > 0 && record3(value.reflection) && validReflectionLayout(layout) && Array.isArray(value.reflection.entryPoints) && value.reflection.entryPoints.includes("forgeax_vfx_spawn_main") && value.reflection.entryPoints.includes("forgeax_vfx_compact_main") && value.reflection.entryPoints.includes("forgeax_vfx_billboard_main") && value.reflection.entryPoints.includes("forgeax_vfx_mesh_main") && value.reflection.entryPoints.includes("forgeax_vfx_ribbon_main") && value.reflection.entryPoints.includes("forgeax_vfx_trail_main") && value.reflection.entryPoints.includes("forgeax_vfx_beam_main") && layout !== void 0 && record3(layout) && Array.isArray(reflection?.bindings) && Array.isArray(reflection?.dataInterfaces) && Array.isArray(reflection?.renderers) && Array.isArray(reflection?.resources);
 }
 var vfxGpuEffectPackLoader = {
   kind: "particle-effect",
   async load(input, _context) {
-    if (input.payload.kind !== "particle-effect" || input.payload.schemaVersion !== 2 || !Array.isArray(input.payload.emitters) || typeof input.payload.programFingerprint !== "string" || !record2(input.payload.program)) {
+    const schemaVersion = input.payload.schemaVersion;
+    if (schemaVersion !== 3) {
       return failure2(
-        "vfx-asset-v2-invalid",
+        "vfx-asset-version-unsupported",
+        input.guid,
+        "schemaVersion",
+        "schemaVersion 3 / forgeax-vfx-program-3",
+        "cold-cook the older source and publish a Program v3 payload; older versions are not executable"
+      );
+    }
+    const invalidCode = "vfx-asset-v3-invalid";
+    const missingCode = "vfx-asset-v3-program-missing";
+    const fingerprintCode = "vfx-asset-v3-fingerprint-mismatch";
+    const expectedFormat = VFX_GPU_PROGRAM_FORMAT_V3;
+    if (input.payload.kind !== "particle-effect" || !Array.isArray(input.payload.emitters) || typeof input.payload.programFingerprint !== "string" || !record3(input.payload.program)) {
+      return failure2(
+        invalidCode,
         input.guid,
         "payload",
-        "a schemaVersion 2 particle payload with its complete program and fingerprint",
-        "migrate behavior to WGSL and recook; the runtime does not interpret v1"
+        "a schemaVersion 3 particle payload with its complete Program v3 and fingerprint",
+        "cold-cook the source with the current VFX compiler and retry the load"
       );
     }
     const artifact = input.artifacts[VFX_GPU_PROGRAM_ARTIFACT_KEY];
     if (artifact === void 0) {
       return failure2(
-        "vfx-asset-v2-program-missing",
+        missingCode,
         input.guid,
         VFX_GPU_PROGRAM_ARTIFACT_KEY,
         "the asset-local cooked VFX program",
@@ -1072,26 +1421,26 @@ var vfxGpuEffectPackLoader = {
       decoded = JSON.parse(new TextDecoder().decode(artifact.bytes));
     } catch {
       return failure2(
-        "vfx-asset-v2-invalid",
+        invalidCode,
         input.guid,
         VFX_GPU_PROGRAM_ARTIFACT_KEY,
         "canonical JSON program bytes",
         "recook the particle effect and retry the load"
       );
     }
-    if (!record2(decoded) || decoded.format !== VFX_GPU_PROGRAM_FORMAT || !Array.isArray(decoded.emitters) || !decoded.emitters.every(validEmitter) || !stableLayouts(decoded.emitters)) {
+    if (!record3(decoded) || decoded.format !== expectedFormat || !Array.isArray(decoded.emitters) || !decoded.emitters.every((emitter) => validEmitter(emitter)) || !stableLayouts(decoded.emitters)) {
       return failure2(
-        "vfx-asset-v2-invalid",
+        invalidCode,
         input.guid,
         VFX_GPU_PROGRAM_ARTIFACT_KEY,
-        `a ${VFX_GPU_PROGRAM_FORMAT} managed GPU program`,
+        `a ${expectedFormat} managed GPU program`,
         "recook with the current VFX compiler ABI"
       );
     }
     const decodedEmitters = decoded.emitters;
-    if (input.payload.program.format !== VFX_GPU_PROGRAM_FORMAT || input.payload.program.fingerprint !== input.payload.programFingerprint || !Array.isArray(input.payload.program.emitters)) {
+    if (input.payload.program.format !== expectedFormat || input.payload.program.fingerprint !== input.payload.programFingerprint || !Array.isArray(input.payload.program.emitters)) {
       return failure2(
-        "vfx-asset-v2-invalid",
+        invalidCode,
         input.guid,
         "payload.program",
         "the complete canonical program matching payload.programFingerprint",
@@ -1101,7 +1450,7 @@ var vfxGpuEffectPackLoader = {
     const actualFingerprint = await fingerprint(artifact.bytes);
     if (actualFingerprint !== input.payload.programFingerprint) {
       return failure2(
-        "vfx-asset-v2-fingerprint-mismatch",
+        fingerprintCode,
         input.guid,
         "payload.programFingerprint",
         "payload and program artifact fingerprints to match",
@@ -1109,7 +1458,7 @@ var vfxGpuEffectPackLoader = {
       );
     }
     const emitters = input.payload.emitters.map((value) => {
-      if (!record2(value) || typeof value.id !== "string" || !Number.isInteger(value.capacity)) {
+      if (!record3(value) || typeof value.id !== "string" || !Number.isInteger(value.capacity)) {
         return void 0;
       }
       return { id: value.id, capacity: value.capacity };
@@ -1118,7 +1467,7 @@ var vfxGpuEffectPackLoader = {
       (value, index) => value?.id !== decodedEmitters[index]?.id || value?.capacity !== decodedEmitters[index]?.capacity
     )) {
       return failure2(
-        "vfx-asset-v2-invalid",
+        invalidCode,
         input.guid,
         "payload.emitters",
         "payload emitter identities and capacities to match the program",
@@ -1129,11 +1478,11 @@ var vfxGpuEffectPackLoader = {
       Object.freeze({
         guid: input.guid,
         kind: "particle-effect",
-        schemaVersion: 2,
+        schemaVersion: 3,
         programFingerprint: actualFingerprint,
         emitters: Object.freeze(emitters),
         program: Object.freeze({
-          format: VFX_GPU_PROGRAM_FORMAT,
+          format: expectedFormat,
           fingerprint: actualFingerprint,
           emitters: Object.freeze(decodedEmitters)
         })
@@ -1489,9 +1838,27 @@ var VfxGpuRuntime = class {
   diagnostics() {
     return this.#diagnostics;
   }
+  /**
+   * Visit every live emitter source.  The renderer uses this on render frames
+   * where pause/restart culling has no pending simulation intent, so a camera
+   * move back into the bounds can refresh visibility before the next tick.
+   */
+  forEachEmitterSource(visitor) {
+    for (const [player, state] of this.#players) {
+      for (const emitter of state.emitters) visitor({ player, emitter });
+    }
+  }
   lastCommitted(player) {
     return this.#lastCommitted.get(player);
   }
+  /**
+   * Return the last submitted fixed-tick state for one emitter.  Renderers
+   * retain this projection between fixed ticks; simulation intents are a
+   * queue, while a drawable emitter remains live until the player is reset.
+   */
+  lastCommittedEmitter(player, emitterId) {
+    return this.#lastCommittedByEmitter.get(player)?.get(emitterId);
+  }
   inspectPlayers() {
     return Object.freeze(
       [...this.#players.keys()].sort((left, right) => Number(left) - Number(right)).flatMap((player) => {
@@ -1646,24 +2013,46 @@ var VfxGpuRuntime = class {
     }
     this.#replayRequests.add(player);
   }
-  commit(sequence) {
+  /**
+   * Acknowledge queued intents. A scalar acknowledges the contiguous prefix;
+   * an array acknowledges only those terminal sequences, which lets unrelated
+   * player/emitter streams progress while another stream is deferred. When the
+   * renderer supplies `publishedSequences`, only intents that reached GPU
+   * submission update the retained last-committed projection; skipped intents
+   * are queue acknowledgements, not new GPU state.
+   */
+  commit(sequence, publishedSequences) {
+    const prefix = typeof sequence === "number" ? sequence : void 0;
+    const acknowledged = typeof sequence === "number" ? void 0 : new Set(sequence);
+    const published = publishedSequences === void 0 ? void 0 : new Set(publishedSequences);
     const committedPlayers = /* @__PURE__ */ new Set();
+    const retained = [];
     for (const intent of this.#intents) {
-      if (intent.sequence > sequence) break;
-      const state = this.#players.get(intent.player);
-      if (state !== void 0) state.hasCommitted = true;
-      this.#lastCommitted.set(intent.player, intent);
-      let emitters = this.#lastCommittedByEmitter.get(intent.player);
-      if (emitters === void 0) {
-        emitters = /* @__PURE__ */ new Map();
-        this.#lastCommittedByEmitter.set(intent.player, emitters);
+      const shouldAcknowledge = prefix === void 0 ? acknowledged?.has(intent.sequence) === true : intent.sequence <= prefix;
+      if (!shouldAcknowledge) {
+        retained.push(intent);
+        continue;
       }
-      emitters.set(intent.emitter.id, intent);
+      const state = this.#players.get(intent.player);
       committedPlayers.add(intent.player);
+      if (published === void 0 || published.has(intent.sequence)) {
+        if (state !== void 0) state.hasCommitted = true;
+        const priorCommitted = this.#lastCommitted.get(intent.player);
+        if (priorCommitted === void 0 || priorCommitted.sequence < intent.sequence) {
+          this.#lastCommitted.set(intent.player, intent);
+        }
+        let emitters = this.#lastCommittedByEmitter.get(intent.player);
+        if (emitters === void 0) {
+          emitters = /* @__PURE__ */ new Map();
+          this.#lastCommittedByEmitter.set(intent.player, emitters);
+        }
+        const priorEmitter = emitters.get(intent.emitter.id);
+        if (priorEmitter === void 0 || priorEmitter.sequence < intent.sequence) {
+          emitters.set(intent.emitter.id, intent);
+        }
+      }
     }
-    const retained = this.#intents.findIndex((intent) => intent.sequence > sequence);
-    if (retained < 0) this.#intents.length = 0;
-    else if (retained > 0) this.#intents.splice(0, retained);
+    this.#intents.splice(0, this.#intents.length, ...retained);
     for (const player of committedPlayers) {
       this.#clearDiagnostics(player, "vfx-intent-queue-overflow");
     }
@@ -1749,11 +2138,11 @@ var VfxGpuRuntime = class {
       const resolved = world.sharedRefs.resolve(
         input.effect
       );
-      if (!resolved.ok || resolved.value.schemaVersion !== 2) {
+      if (!resolved.ok || resolved.value.schemaVersion !== 3) {
         this.#report({
           code: "vfx-effect-unavailable",
-          expected: "a loaded schemaVersion 2 GPU particle effect",
-          hint: "load and recook the effect before the first FixedUpdate",
+          expected: "a loaded schemaVersion 3 GPU particle effect",
+          hint: "cold-cook the legacy effect as Program v3 before the first FixedUpdate",
           detail: { player: input.player }
         });
         continue;
@@ -1761,8 +2150,9 @@ var VfxGpuRuntime = class {
       this.#clearDiagnostics(input.player, "vfx-effect-unavailable");
       const previous = this.#players.get(input.player);
       const replayRequested = this.#replayRequests.delete(input.player);
-      const restart = previous === void 0 || previous.effect !== input.effect || previous.seed !== input.seed || replayRequested || !previous.playing && input.playing;
-      const state = restart ? {
+      const restartRequested = previous === void 0 || previous.effect !== input.effect || previous.seed !== input.seed || replayRequested || !previous.playing && input.playing;
+      const restart = restartRequested;
+      const state = restartRequested ? {
         effect: input.effect,
         assetGuid: resolved.value.guid,
         programFingerprint: resolved.value.program.fingerprint,
@@ -1776,16 +2166,21 @@ var VfxGpuRuntime = class {
         playCycles: resolved.value.program.emitters.map(() => (previous?.playCycle ?? -1) + 1),
         cameraVisible: resolved.value.program.emitters.map(() => true),
         phaseTicks: resolved.value.program.emitters.map(() => 0),
-        hasCommitted: false
+        hasCommitted: false,
+        pendingResets: resolved.value.program.emitters.map(() => false)
       } : previous;
       this.#players.set(input.player, state);
       state.playing = input.playing;
-      if (!input.playing && !replayRequested) continue;
+      if (!input.playing && !replayRequested) {
+        if (restart) state.pendingResets.fill(true);
+        continue;
+      }
       const queuedForPlayer = this.#intents.reduce(
         (count, intent) => count + (intent.player === input.player ? 1 : 0),
         0
       );
       if (queuedForPlayer >= this.#maxQueuedTicks * Math.max(1, resolved.value.program.emitters.length)) {
+        if (restart) state.pendingResets.fill(true);
         if (state.hasCommitted) {
           this.#report({
             code: "vfx-intent-queue-overflow",
@@ -1797,13 +2192,17 @@ var VfxGpuRuntime = class {
         continue;
       }
       const instance = this.#instances.get(input.player) ?? this.#createInstance(input.player, resolved.value);
-      if (instance === void 0) continue;
+      if (instance === void 0) {
+        if (restart) state.pendingResets.fill(true);
+        continue;
+      }
       const hasActiveEmitter = resolved.value.program.emitters.some((emitter) => {
         if (!this.isEmitterSessionEnabled(input.player, emitter.id)) return false;
         const cameraVisible = this.#cameraVisibility.get(`${input.player}:${emitter.id}`) ?? true;
         return cameraVisible || emitter.simulationWhenCulled === "continue";
       });
       if (!hasActiveEmitter) {
+        if (restart) state.pendingResets.fill(true);
         for (const [index, emitter] of resolved.value.program.emitters.entries()) {
           state.cameraVisible[index] = this.#cameraVisibility.get(`${input.player}:${emitter.id}`) ?? true;
         }
@@ -1813,6 +2212,7 @@ var VfxGpuRuntime = class {
       this.#replayInputs.delete(input.player);
       const committed = replayInput === void 0 ? instance.commit({ seed: input.seed, tick }) : instance.replay(replayInput);
       if (!committed.ok) {
+        if (restart) state.pendingResets.fill(true);
         this.#report({
           code: "vfx-instance-commit-failed",
           expected: "the current typed instance values to pack into the reflected GPU block",
@@ -1827,8 +2227,15 @@ var VfxGpuRuntime = class {
         const cameraVisible = this.#cameraVisibility.get(`${input.player}:${emitter.id}`) ?? true;
         const becameVisible = cameraVisible && state.cameraVisible[index] === false;
         state.cameraVisible[index] = cameraVisible;
-        if (!this.isEmitterSessionEnabled(input.player, emitter.id)) continue;
-        if (!cameraVisible && emitter.simulationWhenCulled !== "continue") continue;
+        const emitterRestart = restart || state.pendingResets[index] === true;
+        if (!this.isEmitterSessionEnabled(input.player, emitter.id)) {
+          if (emitterRestart) state.pendingResets[index] = true;
+          continue;
+        }
+        if (!cameraVisible && emitter.simulationWhenCulled !== "continue") {
+          if (emitterRestart) state.pendingResets[index] = true;
+          continue;
+        }
         const visibilityRestart = becameVisible && emitter.simulationWhenCulled === "restart-on-visible";
         if (visibilityRestart) {
           state.elapsed[index] = 0;
@@ -1842,7 +2249,7 @@ var VfxGpuRuntime = class {
           emitter,
           previousElapsed,
           previousElapsed + delta,
-          restart || visibilityRestart,
+          emitterRestart || visibilityRestart,
           state.rateRemainders[index] ?? 0
         );
         state.rateRemainders[index] = scheduled.remainder;
@@ -1862,7 +2269,7 @@ var VfxGpuRuntime = class {
             player: input.player,
             emitter,
             programFingerprint: resolved.value.program.fingerprint,
-            reset: restart || visibilityRestart,
+            reset: emitterRestart || visibilityRestart,
             fixedDelta: delta,
             phaseTick,
             tick,
@@ -1885,6 +2292,7 @@ var VfxGpuRuntime = class {
         );
         state.elapsed[index] = previousElapsed + delta;
         state.phaseTicks[index] = phaseTick + 1;
+        state.pendingResets[index] = false;
       }
     }
     for (const player of this.#players.keys()) {
@@ -1895,12 +2303,16 @@ var VfxGpuRuntime = class {
     const layout = effect.program.emitters.find(
       (emitter) => emitter.reflection.layout !== void 0
     )?.reflection.layout;
-    const reflection = layout ?? {
-      version: 1,
-      parameters: { name: "VfxParameters", fields: [], size: 0, alignment: 1 },
-      custom: { name: "VfxCustom", fields: [], size: 0, alignment: 1 },
-      fingerprint: effect.program.fingerprint.startsWith("sha256:") ? effect.program.fingerprint : `sha256:${effect.program.fingerprint}`
-    };
+    if (layout === void 0) {
+      this.#report({
+        code: "vfx-effect-unavailable",
+        expected: "a Program v3 emitter reflection layout",
+        hint: "recook the effect with Program v3 reflection before starting the player",
+        detail: { player }
+      });
+      return void 0;
+    }
+    const reflection = layout;
     try {
       const instance = new ParticleEffectInstance(createVfxEffectContract(reflection), {
         channels: effect.program.emitters.flatMap((emitter) => emitter.channels ?? [])
@@ -1990,6 +2402,124 @@ function vfxGpuRuntimePlugin(options = {}) {
   };
 }
 
-export { PARTICLE_CODE_DEFAULT_MODULE_ID, PARTICLE_STAGE_RESOURCE_NAMES, ParticleEffectInstance, ParticleEffectPlayer, VFX_GPU_PROGRAM_ARTIFACT_KEY, VFX_GPU_PROGRAM_FORMAT, VFX_GPU_RUNTIME_RESOURCE_KEY, VfxGpuRuntime, createParticleEffectInstance, createVfxEffectContract, createVfxInspectSnapshot, defineParticleEffectSourceV2, describeVfxGpuEffect, isVfxGpuEffectAsset, loadVfxGpuEffect, parseParticleEffectSourceV2, parseVfxStageDeclarations, particleEffectContribution, resolveVfxDataInterfaces, validateVfxEffectValues, vfxGpuEffectContribution, vfxGpuEffectPackLoader, vfxGpuRuntimePlugin };
+// src/particle-layout.ts
+var CORE_FIELDS = Object.freeze([
+  { name: "position", type: "vec3<f32>", offset: 0, size: 12, alignment: 16 },
+  { name: "age", type: "f32", offset: 12, size: 4, alignment: 4 },
+  { name: "velocity", type: "vec3<f32>", offset: 16, size: 12, alignment: 16 },
+  { name: "lifetime", type: "f32", offset: 28, size: 4, alignment: 4 },
+  { name: "color", type: "vec4<f32>", offset: 32, size: 16, alignment: 16 },
+  { name: "sprite_size", type: "vec2<f32>", offset: 48, size: 8, alignment: 8 },
+  { name: "sprite_rotation", type: "f32", offset: 56, size: 4, alignment: 4 },
+  { name: "sub_image", type: "f32", offset: 60, size: 4, alignment: 4 },
+  { name: "mesh_orientation", type: "vec4<f32>", offset: 64, size: 16, alignment: 16 },
+  { name: "mesh_scale", type: "vec3<f32>", offset: 80, size: 12, alignment: 16 },
+  { name: "material_random", type: "f32", offset: 92, size: 4, alignment: 4 },
+  { name: "id", type: "u32", offset: 96, size: 4, alignment: 4 },
+  { name: "alive", type: "u32", offset: 100, size: 4, alignment: 4 }
+]);
+var VFX_PARTICLE_CORE_LAYOUT = Object.freeze({
+  name: "VfxParticle",
+  fields: CORE_FIELDS,
+  size: 112,
+  alignment: 16,
+  stride: 112,
+  fingerprint: "sha256:9e3c1566f6d0600cedb94bd3c4b76c4e7c456fd563b37065220d4e33cf83c777"
+});
+var VFX_PARTICLE_CORE_STRIDE = VFX_PARTICLE_CORE_LAYOUT.stride;
+var CORE_FIELD_BY_NAME = new Map(CORE_FIELDS.map((field2) => [field2.name, field2]));
+function vfxParticleCoreField(name) {
+  const field2 = CORE_FIELD_BY_NAME.get(name);
+  if (field2 === void 0) throw new Error(`unknown VFX particle core field ${name}`);
+  return field2;
+}
+function vfxParticleCoreWgsl() {
+  return [
+    "struct VfxParticle {",
+    ...CORE_FIELDS.map((field2) => `  ${field2.name}: ${field2.type},`),
+    "}"
+  ].join("\n");
+}
+var VALUE_LAYOUT = {
+  f32: { alignment: 4, size: 4 },
+  i32: { alignment: 4, size: 4 },
+  u32: { alignment: 4, size: 4 },
+  "vec2<f32>": { alignment: 8, size: 8 },
+  "vec3<f32>": { alignment: 16, size: 12 },
+  "vec4<f32>": { alignment: 16, size: 16 }
+};
+function alignUp(value, alignment) {
+  return Math.ceil(value / alignment) * alignment;
+}
+function deriveVfxCustomLayout(struct, maxLanes = 4) {
+  if (struct.name !== "VfxCustom") {
+    throw new TypeError(`expected VfxCustom reflection, received ${struct.name}`);
+  }
+  const fields2 = [];
+  let offset = 0;
+  let alignment = 1;
+  for (const field2 of struct.fields) {
+    const layout = VALUE_LAYOUT[field2.type];
+    offset = alignUp(offset, layout.alignment);
+    fields2.push({ ...field2, offset, size: layout.size, alignment: layout.alignment });
+    offset += layout.size;
+    alignment = Math.max(alignment, layout.alignment);
+  }
+  const size = fields2.length === 0 ? 0 : alignUp(offset, alignment);
+  const stride = size;
+  const lanes = Math.ceil(stride / 16);
+  if (lanes > maxLanes) {
+    throw new RangeError(`VfxCustom consumes ${lanes} vec4 lanes; maximum is ${maxLanes}`);
+  }
+  return Object.freeze({
+    name: "VfxCustom",
+    fields: Object.freeze(fields2),
+    size,
+    alignment,
+    stride,
+    lanes
+  });
+}
+function finite2(value) {
+  return Number.isFinite(value);
+}
+function encodeVfxParticleCore(value) {
+  const bytes = new Uint8Array(VFX_PARTICLE_CORE_STRIDE);
+  const view = new DataView(bytes.buffer);
+  const write = (name, values) => {
+    const field2 = vfxParticleCoreField(name);
+    for (const component of values) {
+      if (!finite2(component)) throw new TypeError(`non-finite VFX particle field ${name}`);
+      if (field2.type === "u32" && (!Number.isInteger(component) || component < 0 || component > 4294967295)) {
+        throw new RangeError(`u32 VFX particle field ${name} is outside its valid range`);
+      }
+    }
+    for (let index = 0; index < values.length; index += 1) {
+      const component = values[index] ?? 0;
+      if (field2.type === "u32") view.setUint32(field2.offset + index * 4, component, true);
+      else view.setFloat32(field2.offset + index * 4, component, true);
+    }
+  };
+  write("position", value.position);
+  write("age", [value.age]);
+  write("velocity", value.velocity);
+  write("lifetime", [value.lifetime]);
+  write("color", value.color);
+  write("sprite_size", value.sprite_size);
+  write("sprite_rotation", [value.sprite_rotation]);
+  write("sub_image", [value.sub_image]);
+  write("mesh_orientation", value.mesh_orientation);
+  write("mesh_scale", value.mesh_scale);
+  write("material_random", [value.material_random]);
+  write("id", [value.id]);
+  write("alive", [value.alive]);
+  return bytes;
+}
+function normalizedVfxParticleAge(age, lifetime) {
+  if (!finite2(age) || !finite2(lifetime) || lifetime <= 0) return 0;
+  return Math.min(1, Math.max(0, age / lifetime));
+}
+
+export { PARTICLE_CODE_DEFAULT_MODULE_ID, PARTICLE_RENDERER_SEMANTICS, PARTICLE_STAGE_RESOURCE_NAMES, ParticleEffectInstance, ParticleEffectPlayer, VFX_GPU_PROGRAM_ARTIFACT_KEY, VFX_GPU_PROGRAM_FORMAT, VFX_GPU_PROGRAM_FORMAT_V3, VFX_GPU_RUNTIME_RESOURCE_KEY, VFX_PARTICLE_CORE_LAYOUT, VFX_PARTICLE_CORE_STRIDE, VfxGpuRuntime, createParticleEffectInstance, createVfxEffectContract, createVfxInspectSnapshot, defaultParticleRendererAttributes, defineParticleEffectSourceV3, deriveVfxCustomLayout, describeVfxGpuEffect, encodeVfxParticleCore, isVfxGpuEffectAsset, loadVfxGpuEffect, normalizedVfxParticleAge, parseParticleEffectSourceV3, parseVfxStageDeclarations, particleEffectContribution, resolveVfxDataInterfaces, validateVfxEffectValues, vfxGpuEffectContribution, vfxGpuEffectPackLoader, vfxGpuRuntimePlugin, vfxParticleCoreField, vfxParticleCoreWgsl };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map