@forgeax/engine-vfx 0.1.27 → 0.1.29

package/README.md

@@ -24,10 +24,10 @@ artifact must be cold-cooked instead of being treated as current.
 ## Author source
 
 ```ts
-import { defineParticleEffectSourceV2 } from '@forgeax/engine-vfx';
+import { defineParticleEffectSourceV3 } from '@forgeax/engine-vfx';
 
-export const sparks = defineParticleEffectSourceV2({
-  schemaVersion: 2,
+export const sparks = defineParticleEffectSourceV3({
+  schemaVersion: 3,
   emitters: [{
     id: 'sparks',
     capacity: 100_000,
@@ -57,6 +57,48 @@ A mesh renderer selects exactly one draw surface with `submesh` (default `0`):
 `{ kind: 'mesh', mesh, material, submesh: 2 }`. An out-of-range index fails
 preparation instead of silently drawing another submesh.
 
+## Program v3 data plane
+
+The minimum-fidelity slice exposes a schema-driven Program v3 authoring boundary
+through `defineParticleEffectSourceV3`. Its fixed Core record is 112 bytes
+(`VfxParticle`); effect snapshot values live in `VfxParameters`, while optional
+`VfxCustom` values use a persistent GPU storage record capped at four
+`vec4`-equivalent lanes. The compiler derives the WGSL declarations, reflection,
+host stride, and renderer projections from these schemas. Reflected member
+offsets preserve authored WGSL declaration order. Custom storage array stride
+uses the struct's natural WGSL alignment; the vec4 lane count is a budget,
+not an extra padding requirement (one scalar has a 4-byte stride).
+
+```ts
+import { defineParticleEffectSourceV3 } from '@forgeax/engine-vfx';
+
+export const effect = defineParticleEffectSourceV3({
+  schemaVersion: 3,
+  emitters: [{
+    id: 'embers', capacity: 4096, backend: { required: 'gpu' }, space: 'world',
+    bounds: { kind: 'sphere', center: [0, 0, 0], radius: 8 },
+    schedule: { rate: 120 }, program: { module: 'embers.vfx.wgsl' },
+    renderers: [{
+      kind: 'billboard', material: 'ember-material', sorting: 'view-depth',
+      materialInputs: ['heat'],
+    }],
+  }],
+});
+```
+
+Program v3 keeps the existing bounded `channels`/`events` and sub-emitter
+path. The unused `vfx:channel` Data Interface token is not part of the v3
+vocabulary; `camera`, single-sample `scene-depth`, and `noise` are
+generation-owned resources and must be supplied by the renderer host.
+Scene-depth is intentionally accepted only with `sampleCount: 1`; no implicit
+MSAA resolve is performed.
+
+Mesh renderers expose semantic Quaternion/Scale3 attributes and Standard
+lighting/shadow intent. Billboard, Ribbon, Trail, and Beam retain their
+topology-specific projection paths. Invalid or missing semantic/material input
+references fail at cook time, and undeclared Parameters, Custom, and data
+interface resources do not allocate a GPU binding.
+
 ## Batch B renderers and control
 
 ```ts
@@ -65,7 +107,7 @@ renderers: [
     kind: 'billboard', material: SPARK_MATERIAL, blend: 'additive',
     capacity: 4096, overflow: 'drop-oldest',
     textureSheet: { columns: 4, rows: 4, frameRate: 12 },
-    pivot: [0.5, 0.25], softParticle: { distance: 0.4 }, sorting: 'back-to-front',
+    pivot: [0.5, 0.25], softParticle: { fadeDistance: 0.4 }, sorting: 'view-depth',
   },
   { kind: 'ribbon', stripKey: 'alive-index', capacity: 1024, overflow: 'drop-newest', width: 0.2 },
   { kind: 'trail', historyLength: 8, capacity: 1024, overflow: 'drop-oldest', width: 0.15 },
@@ -92,13 +134,13 @@ scene-depth provider. Capacity overflow is reported through inspection.
 
 fn vfx_spawn(ctx: VfxSpawnContext, particle: ptr<function, VfxParticle>) {
   let angle = vfx_random_spawn(ctx, 0u) * 6.2831853;
-  (*particle).velocity = vec4<f32>(cos(angle), 2.0, sin(angle), 0.0);
+  (*particle).velocity = vec3<f32>(cos(angle), 2.0, sin(angle));
   (*particle).lifetime = 1.5;
 }
 
 fn vfx_update(ctx: VfxUpdateContext, particle: ptr<function, VfxParticle>) {
   (*particle).velocity.y -= 9.8 * ctx.delta;
-  (*particle).size_rotation.z += ctx.delta * 2.0;
+  (*particle).sprite_rotation += ctx.delta * 2.0;
   vfx_integrate(ctx, particle);
 }
 ```
@@ -107,11 +149,13 @@ The managed shell exposes this stable particle surface:
 
 | Field | Meaning |
 |:--|:--|
-| `position.xyz` | Emitter-local or world position; `.w` is available to author code |
-| `velocity.xyz` | Velocity used by `vfx_integrate`; `.w` is available to author code |
+| `position` | Emitter-local or world position |
+| `velocity` | Velocity used by `vfx_integrate` |
 | `color` | Linear HDR color and alpha |
-| `size_rotation.xy` | Billboard width/height; mesh uses `.x` as uniform scale |
-| `size_rotation.z` | Rotation in radians |
+| `sprite_size` | Billboard width/height |
+| `sprite_rotation` | Billboard rotation in radians |
+| `mesh_orientation` / `mesh_scale` | Mesh Quaternion (x, y, z, w) and Scale3 |
+| `material_random` | Stable material random scalar |
 | `age`, `lifetime` | Engine advances age and kills at `age >= lifetime` |
 | `alive` | Set to `0u` for explicit death |
 | `id` | Stable spawn identity for addressable random |
@@ -164,7 +208,8 @@ responsibility.
 
 > [!IMPORTANT]
 > The descriptor is an inspection/read-model contract, not a second authoring
-> language. Source v2 plus `.vfx.wgsl` remain authoritative.
+> language. Program v3 source plus `.vfx.wgsl` is authoritative. Older payloads
+> are rejected at the loader boundary and must be cold-cooked before publication.
 
 ## Runtime invariants
 
@@ -183,6 +228,8 @@ program/layout fingerprints, parameter generation, pending patch count, channel
 counters, `cameraVisible`, `sessionEnabled`, phase/global ticks, schedule, bounds, renderer/stage metadata and the latest
 committed tick intent per emitter. Observation never selects a single global
 “latest intent,” so two players and multi-emitter effects remain distinguishable.
+The renderer may use `forEachEmitterSource()` to refresh frustum visibility from
+live emitters even when a paused player has no pending fixed-tick intent.
 
 ## Culling policy
 
@@ -204,10 +251,11 @@ Camera culling and editor preview masking are independent runtime axes:
 
 | Code | Repair |
 |:--|:--|
-| `vfx-source-version-unsupported` | Migrate behavior to WGSL and cold-cook schema v2 |
+| `vfx-source-version-unsupported` | Migrate behavior to WGSL and cold-cook the supported schema |
 | `vfx-source-invalid` | Repair `detail.path`; unknown and unsupported fields fail closed |
-| `vfx-asset-v2-program-missing` | Republish the asset-local `particle-effect/program.json` artifact |
-| `vfx-asset-v2-fingerprint-mismatch` | Cold-cook payload and program atomically |
+| `vfx-asset-version-unsupported` | Cold-cook the older source and publish a Program v3 payload |
+| `vfx-asset-v3-program-missing` | Republish the Program v3 asset-local `particle-effect/program.json` artifact |
+| `vfx-asset-v3-fingerprint-mismatch` | Cold-cook the v3 payload and program atomically |
 | `vfx-effect-unavailable` | Load the shared effect before the first FixedUpdate |
 | `vfx-intent-queue-overflow` | Recover the Renderer or restart the player; inspect render readiness |
 

package/dist/assets/particle-effect-decoder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"particle-effect-decoder.d.ts","sourceRoot":"","sources":["../../src/assets/particle-effect-decoder.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,wBAAwB,EAI7B,KAAK,mBAAmB,EACzB,MAAM,uBAAuB,CAAC;AAE/B,eAAO,MAAM,0BAA0B,EAAE,wBAAwB,CAC/D,mBAAmB,EACnB,iBAAiB,CAuBlB,CAAC"}
+{"version":3,"file":"particle-effect-decoder.d.ts","sourceRoot":"","sources":["../../src/assets/particle-effect-decoder.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,wBAAwB,EAI7B,KAAK,mBAAmB,EACzB,MAAM,uBAAuB,CAAC;AAE/B,eAAO,MAAM,0BAA0B,EAAE,wBAAwB,CAC/D,mBAAmB,EACnB,iBAAiB,CAwBlB,CAAC"}

package/dist/authoring-descriptor.d.ts

@@ -1,4 +1,4 @@
-import type { VfxGpuEffectAsset } from './gpu-program.js';
+import type { VfxGpuEffectAssetAny } from './gpu-program.js';
 export type VfxAuthoringValue = null | string | number | boolean | readonly VfxAuthoringValue[] | {
     readonly [key: string]: VfxAuthoringValue;
 };
@@ -43,7 +43,7 @@ export interface VfxAuthoringCapabilityDescriptor {
 export interface VfxAuthoringDescriptor {
     readonly version: 1;
     readonly assetGuid: string;
-    readonly schemaVersion: 2;
+    readonly schemaVersion: 3;
     readonly artifactFingerprint: string;
     readonly emitters: readonly VfxAuthoringEmitterDescriptor[];
     readonly timeline: readonly VfxAuthoringTimelineDescriptor[];
@@ -54,7 +54,7 @@ export interface VfxAuthoringDescriptor {
  * the cooked program shape. This deliberately validates the stable producer
  * discriminants only; detailed artifact validation remains the pack loader's
  * responsibility. */
-export declare function isVfxGpuEffectAsset(value: unknown): value is VfxGpuEffectAsset;
+export declare function isVfxGpuEffectAsset(value: unknown): value is VfxGpuEffectAssetAny;
 /** Project the cooked runtime asset into a compiler-free, UI-neutral authoring read model. */
-export declare function describeVfxGpuEffect(effect: VfxGpuEffectAsset): VfxAuthoringDescriptor;
+export declare function describeVfxGpuEffect(effect: VfxGpuEffectAssetAny): VfxAuthoringDescriptor;
 //# sourceMappingURL=authoring-descriptor.d.ts.map

package/dist/authoring-descriptor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"authoring-descriptor.d.ts","sourceRoot":"","sources":["../src/authoring-descriptor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAwB,MAAM,kBAAkB,CAAC;AAEhF,MAAM,MAAM,iBAAiB,GACzB,IAAI,GACJ,MAAM,GACN,MAAM,GACN,OAAO,GACP,SAAS,iBAAiB,EAAE,GAC5B;IAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,iBAAiB,CAAA;CAAE,CAAC;AAElD,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,QAAQ,CAAC;CACzE;AAED,MAAM,MAAM,oBAAoB,GAC5B,SAAS,GACT,SAAS,GACT,YAAY,GACZ,QAAQ,GACR,OAAO,GACP,SAAS,GACT,OAAO,GACP,UAAU,CAAC;AAEf,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;IACpC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,SAAS,2BAA2B,EAAE,CAAC;IACxD,QAAQ,CAAC,QAAQ,EAAE,SAAS,0BAA0B,EAAE,CAAC;CAC1D;AAED,MAAM,WAAW,6BAA8B,SAAQ,0BAA0B;IAC/E,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,SAAS;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC9E,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,gBAAgB,CAAC;IACrD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,YAAY,GAAG,SAAS,GAAG,aAAa,CAAC;IACzD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IACpB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,aAAa,EAAE,CAAC,CAAC;IAC1B,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,QAAQ,EAAE,SAAS,6BAA6B,EAAE,CAAC;IAC5D,QAAQ,CAAC,QAAQ,EAAE,SAAS,8BAA8B,EAAE,CAAC;IAC7D,QAAQ,CAAC,YAAY,EAAE,SAAS,gCAAgC,EAAE,CAAC;IACnE,QAAQ,CAAC,YAAY,EAAE,SAAS,gCAAgC,EAAE,CAAC;CACpE;AAwBD;;;qBAGqB;AACrB,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,iBAAiB,CAc9E;AA4ND,8FAA8F;AAC9F,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,iBAAiB,GAAG,sBAAsB,CAsBtF"}
+{"version":3,"file":"authoring-descriptor.d.ts","sourceRoot":"","sources":["../src/authoring-descriptor.ts"],"names":[],"mappings":"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"}

package/dist/code-source-v3.d.ts

@@ -0,0 +1,101 @@
+import { type Result } from '@forgeax/engine-types';
+import { type ParticleBoundsSource, type ParticleChannelSource, type ParticleCodeSourceError, type ParticleEmitterSourceStructure, type ParticleEventSource, type ParticleRendererOverflowPolicy } from './code-source.js';
+import type { VfxParticleCoreAttribute } from './particle-layout.js';
+/** Renderer sorting modes in Program v3. Segment topology order is unaffected. */
+export type ParticleRendererSortingV3 = 'none' | 'view-depth' | 'view-distance' | 'custom-ascending' | 'custom-descending';
+export type ParticleAttributeRef = {
+    readonly source: 'core';
+    readonly name: VfxParticleCoreAttribute;
+} | {
+    readonly source: 'custom';
+    readonly name: string;
+};
+/**
+ * Renderer fields with a concrete Program v3 projection. Keep this union
+ * execution-backed; renderer.materialInputs is the separate material bridge.
+ */
+export type ParticleRendererSemantic = 'position' | 'color' | 'size' | 'rotation' | 'subImage' | 'age' | 'sort' | 'orientation' | 'scale' | 'visibility' | 'width' | 'taper' | 'endpoint';
+export type ParticleRendererSemanticMap = Readonly<Partial<Record<ParticleRendererSemantic, ParticleAttributeRef>>>;
+export interface ParticleRendererSourceV3Base {
+    readonly material: string;
+    readonly enabled?: boolean;
+    readonly capacity?: number;
+    readonly overflow?: ParticleRendererOverflowPolicy;
+    readonly width?: number;
+    readonly attributes?: ParticleRendererSemanticMap;
+    /** Names must match the cooked MaterialShaderArtifact particleInputs declaration. */
+    readonly materialInputs?: readonly string[];
+}
+export type ParticleRendererSourceV3 = (ParticleRendererSourceV3Base & {
+    readonly kind: 'billboard';
+    readonly blend?: 'additive' | 'alpha' | 'opaque-cutout';
+    readonly textureSheet?: {
+        readonly columns: number;
+        readonly rows: number;
+        readonly frameRate: number;
+        readonly frameCount?: number;
+    };
+    readonly pivot?: readonly [number, number];
+    readonly softParticle?: {
+        readonly fadeDistance: number;
+    };
+    readonly sorting?: ParticleRendererSortingV3;
+}) | (ParticleRendererSourceV3Base & {
+    readonly kind: 'mesh';
+    readonly mesh: string;
+    readonly submesh?: number;
+    readonly lighting?: 'unlit' | 'standard';
+    readonly castShadows?: boolean;
+    readonly receiveShadows?: boolean;
+}) | (ParticleRendererSourceV3Base & {
+    readonly kind: 'ribbon';
+    readonly stripKey: 'alive-index';
+    readonly capacity: number;
+    readonly twist?: number;
+    readonly facing?: 'camera' | 'velocity' | 'custom';
+}) | (ParticleRendererSourceV3Base & {
+    readonly kind: 'trail';
+    readonly historyLength: number;
+    readonly capacity: number;
+    readonly taper?: number;
+}) | (ParticleRendererSourceV3Base & {
+    readonly kind: 'beam';
+    readonly endpointField: 'velocity';
+    readonly capacity: number;
+    readonly taper?: number;
+});
+export interface ParticleEmitterSourceV3 {
+    readonly id: string;
+    readonly capacity: number;
+    readonly backend: {
+        readonly required: 'gpu';
+    };
+    readonly space: 'local' | 'world';
+    readonly bounds: ParticleBoundsSource;
+    readonly schedule: ParticleEmitterSourceStructure['schedule'];
+    readonly program: {
+        readonly module: string;
+    };
+    readonly renderers: readonly ParticleRendererSourceV3[];
+    /** Existing channels/events are intentionally carried unchanged into v3. */
+    readonly channels?: readonly ParticleChannelSource[];
+    readonly events?: readonly ParticleEventSource[];
+    readonly simulationWhenCulled?: ParticleEmitterSourceStructure['simulationWhenCulled'];
+}
+export interface ParticleEffectRootSourceV3 {
+    readonly schemaVersion: 3;
+    readonly emitters: readonly ParticleEmitterSourceV3[];
+}
+export type ParticleEffectSourceV3 = ParticleEffectRootSourceV3;
+/**
+ * Renderer semantic vocabulary shared by source validation and compiler
+ * reflection. Keeping the allowed keys here prevents a parser/compiler drift
+ * where a typo is accepted by one boundary and ignored by the other.
+ */
+export declare const PARTICLE_RENDERER_SEMANTICS: Readonly<Record<ParticleRendererSourceV3['kind'], readonly ParticleRendererSemantic[]>>;
+/** Default mapping for fields with implicit runtime behavior; overrides merge in the compiler. */
+export declare function defaultParticleRendererAttributes(kind: ParticleRendererSourceV3['kind']): ParticleRendererSemanticMap;
+/** Parse the single Program v3 source shape. Older source versions are rejected. */
+export declare function parseParticleEffectSourceV3(value: unknown): Result<ParticleEffectSourceV3, ParticleCodeSourceError>;
+export declare function defineParticleEffectSourceV3<T extends ParticleEffectSourceV3>(source: T): T;
+//# sourceMappingURL=code-source-v3.d.ts.map

package/dist/code-source-v3.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"code-source-v3.d.ts","sourceRoot":"","sources":["../src/code-source-v3.ts"],"names":[],"mappings":"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"}

package/dist/code-source.d.ts

@@ -11,7 +11,8 @@ export type ParticleBoundsSource = {
     readonly radius: number;
 };
 export type ParticleRendererOverflowPolicy = 'drop-newest' | 'drop-oldest';
-export type ParticleRendererSorting = 'none' | 'emitter' | 'back-to-front';
+/** Internal structural projection used while validating the v3 source. */
+export type ParticleRendererSortingStructure = 'none' | 'emitter' | 'back-to-front';
 export interface ParticleTextureSheetSource {
     readonly columns: number;
     readonly rows: number;
@@ -21,7 +22,7 @@ export interface ParticleTextureSheetSource {
 export interface ParticleSoftParticleSource {
     readonly fadeDistance: number;
 }
-export type ParticleRendererSource = {
+export type ParticleRendererSourceStructure = {
     readonly kind: 'billboard';
     readonly material: string;
     readonly blend?: 'additive' | 'alpha' | 'opaque-cutout';
@@ -31,7 +32,7 @@ export type ParticleRendererSource = {
     readonly textureSheet?: ParticleTextureSheetSource;
     readonly pivot?: readonly [number, number];
     readonly softParticle?: ParticleSoftParticleSource;
-    readonly sorting?: ParticleRendererSorting;
+    readonly sorting?: ParticleRendererSortingStructure;
 } | {
     readonly kind: 'mesh';
     readonly material: string;
@@ -92,7 +93,7 @@ export interface ParticleEventSource {
     readonly fanOut: number;
     readonly recursionDepth: number;
 }
-export interface ParticleEmitterSourceV2 {
+export interface ParticleEmitterSourceStructure {
     readonly id: string;
     readonly capacity: number;
     readonly backend: {
@@ -111,16 +112,16 @@ export interface ParticleEmitterSourceV2 {
     readonly program: {
         readonly module: string;
     };
-    readonly renderers: readonly ParticleRendererSource[];
+    readonly renderers: readonly ParticleRendererSourceStructure[];
     readonly channels?: readonly ParticleChannelSource[];
     readonly events?: readonly ParticleEventSource[];
     readonly simulationWhenCulled?: 'continue' | 'pause' | 'restart-on-visible';
 }
-export interface ParticleEffectRootSourceV2 {
-    readonly schemaVersion: 2;
-    readonly emitters: readonly ParticleEmitterSourceV2[];
+export interface ParticleEffectRootSourceStructure {
+    readonly schemaVersion: 3;
+    readonly emitters: readonly ParticleEmitterSourceStructure[];
 }
-export type ParticleEffectSourceV2 = ParticleEffectRootSourceV2;
+export type ParticleEffectSourceStructure = ParticleEffectRootSourceStructure;
 export interface ParticleCodeSourceInvalidDetail {
     readonly path: string;
     readonly emitterId?: string;
@@ -135,6 +136,6 @@ export interface ParticleCodeSourceError {
 }
 /** Parse compiler-owned stage metadata from authored WGSL comments. */
 export declare function parseVfxStageDeclarations(source: string): Result<readonly ParticleStageSource[], ParticleCodeSourceError>;
-export declare function parseParticleEffectSourceV2(value: unknown): Result<ParticleEffectSourceV2, ParticleCodeSourceError>;
-export declare function defineParticleEffectSourceV2<T extends ParticleEffectSourceV2>(source: T): T;
+/** Validate the fields shared by the canonical Program v3 source parser. */
+export declare function parseParticleEffectSourceStructure(value: unknown): Result<ParticleEffectSourceStructure, ParticleCodeSourceError>;
 //# sourceMappingURL=code-source.d.ts.map

package/dist/code-source.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"code-source.d.ts","sourceRoot":"","sources":["../src/code-source.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"code-source.d.ts","sourceRoot":"","sources":["../src/code-source.ts"],"names":[],"mappings":"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"}

package/dist/data-interface.d.ts

@@ -2,11 +2,11 @@ import { type Result } from '@forgeax/engine-types';
 export type VfxDataInterfaceKind = keyof VfxDataInterfaceBindingTypeByKind;
 export type VfxDataInterfaceToken = `vfx:${VfxDataInterfaceKind}`;
 export type VfxDataInterfaceBindingType = VfxDataInterfaceBindingTypeByKind[VfxDataInterfaceKind];
+export type VfxDataInterfaceResourceKind = 'buffer' | 'texture-view' | 'sampler';
 type VfxDataInterfaceBindingTypeByKind = {
     readonly camera: 'uniform';
     readonly 'scene-depth': 'sampled-depth';
     readonly noise: 'sampled-float';
-    readonly channel: 'storage-read';
 };
 export type VfxDataInterfaceLifetime = 'generation';
 export interface VfxDataInterfaceRequirement {
@@ -15,12 +15,26 @@ export interface VfxDataInterfaceRequirement {
     readonly binding: number;
     readonly bindingType: VfxDataInterfaceBindingType;
     readonly lifetime: VfxDataInterfaceLifetime;
+    /** Scene-depth composition is intentionally proven only for single-sample targets. */
+    readonly sampleCount?: 1;
 }
 export interface VfxDataInterfaceResource {
     readonly token: VfxDataInterfaceToken;
     readonly kind: VfxDataInterfaceKind;
     readonly bindingType: VfxDataInterfaceBindingType;
     readonly generation: number;
+    readonly sampleCount?: number;
+    /**
+     * Provider-owned opaque resource. Render owners refine this to their typed
+     * prepared-resource reference; VFX never inspects a backend handle.
+     */
+    readonly resource?: {
+        readonly kind: 'buffer' | 'texture-view' | 'sampler';
+        readonly value: unknown;
+        /** Required when a provider supplies an external buffer to a compute bind group. */
+        readonly size?: number;
+        readonly usage?: 'uniform' | 'storage';
+    };
 }
 export interface VfxDataInterfaceErrorDetail {
     readonly token: VfxDataInterfaceToken;
@@ -29,6 +43,8 @@ export interface VfxDataInterfaceErrorDetail {
     readonly actualGeneration?: number;
     readonly expectedBindingType?: VfxDataInterfaceBindingType;
     readonly actualBindingType?: VfxDataInterfaceBindingType;
+    readonly expectedResourceKind?: VfxDataInterfaceResourceKind;
+    readonly actualResourceKind?: VfxDataInterfaceResourceKind;
 }
 export interface VfxDataInterfaceError {
     readonly code: 'vfx-data-interface-missing' | 'vfx-data-interface-wrong-type' | 'vfx-data-interface-stale' | 'vfx-data-interface-duplicate';

package/dist/data-interface.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"data-interface.d.ts","sourceRoot":"","sources":["../src/data-interface.ts"],"names":[],"mappings":"AAAA,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAE7D,MAAM,MAAM,oBAAoB,GAAG,MAAM,iCAAiC,CAAC;AAE3E,MAAM,MAAM,qBAAqB,GAAG,OAAO,oBAAoB,EAAE,CAAC;AAElE,MAAM,MAAM,2BAA2B,GAAG,iCAAiC,CAAC,oBAAoB,CAAC,CAAC;AAElG,KAAK,iCAAiC,GAAG;IACvC,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,aAAa,EAAE,eAAe,CAAC;IACxC,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;CAClC,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG,YAAY,CAAC;AAEpD,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,KAAK,EAAE,qBAAqB,CAAC;IACtC,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,2BAA2B,CAAC;IAClD,QAAQ,CAAC,QAAQ,EAAE,wBAAwB,CAAC;CAC7C;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,KAAK,EAAE,qBAAqB,CAAC;IACtC,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;IACpC,QAAQ,CAAC,WAAW,EAAE,2BAA2B,CAAC;IAClD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,KAAK,EAAE,qBAAqB,CAAC;IACtC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,2BAA2B,CAAC;IAC3D,QAAQ,CAAC,iBAAiB,CAAC,EAAE,2BAA2B,CAAC;CAC1D;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EACT,4BAA4B,GAC5B,+BAA+B,GAC/B,0BAA0B,GAC1B,8BAA8B,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,2BAA2B,CAAC;CAC9C;AAED,MAAM,MAAM,wBAAwB,CAAC,CAAC,SAAS,oBAAoB,GAAG,oBAAoB,IAAI;IAC5F,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,EAAE,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IACjB,QAAQ,CAAC,WAAW,EAAE,iCAAiC,CAAC,CAAC,CAAC,CAAC;IAC3D,QAAQ,CAAC,OAAO,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,MAAM,CAAC,wBAAwB,EAAE,qBAAqB,CAAC,CAAC;CACnG,CAAC;AAEF,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,SAAS,wBAAwB,EAAE,CAAC;CACzD;AAYD,wBAAgB,wBAAwB,CACtC,YAAY,EAAE,SAAS,2BAA2B,EAAE,EACpD,SAAS,EAAE,SAAS,wBAAwB,EAAE,EAC9C,UAAU,EAAE,MAAM,GACjB,MAAM,CAAC,0BAA0B,EAAE,qBAAqB,CAAC,CAoG3D"}
+{"version":3,"file":"data-interface.d.ts","sourceRoot":"","sources":["../src/data-interface.ts"],"names":[],"mappings":"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"}

package/dist/effect-contract.d.ts

@@ -1,5 +1,6 @@
 import { type Result } from '@forgeax/engine-types';
 import type { VfxDataInterfaceRequirement } from './data-interface.js';
+import type { VfxCustomLayout, VfxParticleCoreLayout } from './particle-layout.js';
 export type VfxValue = number | readonly number[];
 export type VfxValueMap = Readonly<Record<string, VfxValue>>;
 export interface VfxReflectedField {
@@ -17,9 +18,12 @@ export interface VfxReflectedStruct {
     readonly alignment: number;
 }
 export interface VfxEffectReflection {
-    readonly version: 1;
+    /** The single executable particle data ABI. */
+    readonly version: 3;
     readonly parameters: VfxReflectedStruct;
     readonly custom: VfxReflectedStruct;
+    readonly core: VfxParticleCoreLayout;
+    readonly customLayout: VfxCustomLayout;
     readonly dataInterfaces?: readonly VfxDataInterfaceRequirement[];
     readonly fingerprint: string;
 }
@@ -37,10 +41,16 @@ export interface VfxEffectContract<Values extends VfxValueMap = VfxValueMap> {
     readonly reflection: VfxEffectReflection;
     readonly fingerprint: string;
     readonly packedSize: number;
+    /** Bytes in the effect-instance Parameters uniform. */
+    readonly parameterSize: number;
+    /** Bytes in one persistent per-particle Custom record. */
+    readonly customStride: number;
     readonly defaults: Values;
     createValues(initial?: Partial<Values>): Result<Values, VfxEffectContractError>;
     validateValues(values: VfxValueMap): Result<Values, VfxEffectContractError>;
     pack(values: Values): Result<Uint8Array, VfxEffectContractError>;
+    packParameters(values: Values): Result<Uint8Array, VfxEffectContractError>;
+    packCustom(values: VfxValueMap): Result<Uint8Array, VfxEffectContractError>;
 }
 declare const VECTOR_LENGTH: {
     f32: number;

package/dist/effect-contract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"effect-contract.d.ts","sourceRoot":"","sources":["../src/effect-contract.ts"],"names":[],"mappings":"AAAA,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,qBAAqB,CAAC;AAEvE,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;AAClD,MAAM,MAAM,WAAW,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC;AAE7D,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,YAAY,CAAC,EAAE,QAAQ,CAAC;CAClC;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC9C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IACpB,QAAQ,CAAC,UAAU,EAAE,kBAAkB,CAAC;IACxC,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;IACpC,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,2BAA2B,EAAE,CAAC;IACjE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,IAAI,EACT,yBAAyB,GACzB,yBAAyB,GACzB,sBAAsB,GACtB,wBAAwB,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,4BAA4B,CAAC;CAC/C;AAED,MAAM,WAAW,iBAAiB,CAAC,MAAM,SAAS,WAAW,GAAG,WAAW;IACzE,QAAQ,CAAC,UAAU,EAAE,mBAAmB,CAAC;IACzC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,YAAY,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC;IAChF,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC;IAC5E,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,UAAU,EAAE,sBAAsB,CAAC,CAAC;CAClE;AAED,QAAA,MAAM,aAAa;;;;;;;CAOlB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG,MAAM,OAAO,aAAa,CAAC;AAgHtD,wBAAgB,uBAAuB,CAAC,MAAM,SAAS,WAAW,GAAG,WAAW,EAC9E,UAAU,EAAE,mBAAmB,GAC9B,iBAAiB,CAAC,MAAM,CAAC,CAiC3B;AAED,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,mBAAmB,EAC/B,MAAM,EAAE,WAAW,GAClB,MAAM,CAAC,WAAW,EAAE,sBAAsB,CAAC,CAE7C"}
+{"version":3,"file":"effect-contract.d.ts","sourceRoot":"","sources":["../src/effect-contract.ts"],"names":[],"mappings":"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"}

package/dist/gpu-loader.d.ts

@@ -1,8 +1,8 @@
 import type { AssetRegistry as LegacyAssetRegistry, RuntimeAssetRegistry } from '@forgeax/engine-assets-runtime';
 import type { AssetDecoderContribution, LoadContext, Result } from '@forgeax/engine-types';
-import { type VfxGpuEffectAsset } from './gpu-program.js';
+import { type VfxGpuEffectAssetAny } from './gpu-program.js';
 export interface VfxGpuAssetError {
-    readonly code: 'vfx-asset-v2-invalid' | 'vfx-asset-v2-program-missing' | 'vfx-asset-v2-fingerprint-mismatch';
+    readonly code: 'vfx-asset-version-unsupported' | 'vfx-asset-v3-invalid' | 'vfx-asset-v3-program-missing' | 'vfx-asset-v3-fingerprint-mismatch';
     readonly expected: string;
     readonly hint: string;
     readonly detail: {
@@ -24,10 +24,10 @@ interface PackLoaderInput {
 }
 export declare const vfxGpuEffectPackLoader: {
     kind: string;
-    load(input: PackLoaderInput, _context: LoadContext): Promise<Result<VfxGpuEffectAsset, VfxGpuAssetError>>;
+    load(input: PackLoaderInput, _context: LoadContext): Promise<Result<VfxGpuEffectAssetAny, VfxGpuAssetError>>;
 };
 /** VFX owner decoder contribution for the core registry's typed map. */
-export declare const vfxGpuEffectContribution: AssetDecoderContribution<VfxGpuEffectAsset, 'particle-effect'>;
-export declare function loadVfxGpuEffect(registry: LegacyAssetRegistry | RuntimeAssetRegistry, guid: string): Promise<Result<VfxGpuEffectAsset, unknown>>;
+export declare const vfxGpuEffectContribution: AssetDecoderContribution<VfxGpuEffectAssetAny, 'particle-effect'>;
+export declare function loadVfxGpuEffect(registry: LegacyAssetRegistry | RuntimeAssetRegistry, guid: string): Promise<Result<VfxGpuEffectAssetAny, unknown>>;
 export {};
 //# sourceMappingURL=gpu-loader.d.ts.map

package/dist/gpu-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gpu-loader.d.ts","sourceRoot":"","sources":["../src/gpu-loader.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,IAAI,mBAAmB,EACpC,oBAAoB,EACrB,MAAM,gCAAgC,CAAC;AACxC,OAAO,KAAK,EACV,wBAAwB,EAGxB,WAAW,EACX,MAAM,EACP,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAGL,KAAK,iBAAiB,EAEvB,MAAM,kBAAkB,CAAC;AAE1B,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EACT,sBAAsB,GACtB,8BAA8B,GAC9B,mCAAmC,CAAC;IACxC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CACnE;AAED,UAAU,eAAe;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1C,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAC1B,MAAM,CACJ,MAAM,EACN;QACE,QAAQ,CAAC,UAAU,EAAE;YAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;YAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;SAAE,CAAC;QAC3E,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;KAC5B,CACF,CACF,CAAC;CACH;AAuED,eAAO,MAAM,sBAAsB;;gBAGxB,eAAe,YACZ,WAAW,GACpB,OAAO,CAAC,MAAM,CAAC,iBAAiB,EAAE,gBAAgB,CAAC,CAAC;CAmHxD,CAAC;AAEF,wEAAwE;AACxE,eAAO,MAAM,wBAAwB,EAAE,wBAAwB,CAC7D,iBAAiB,EACjB,iBAAiB,CAoClB,CAAC;AAEF,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,mBAAmB,GAAG,oBAAoB,EACpD,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,MAAM,CAAC,iBAAiB,EAAE,OAAO,CAAC,CAAC,CAW7C"}
+{"version":3,"file":"gpu-loader.d.ts","sourceRoot":"","sources":["../src/gpu-loader.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,IAAI,mBAAmB,EACpC,oBAAoB,EACrB,MAAM,gCAAgC,CAAC;AACxC,OAAO,KAAK,EACV,wBAAwB,EAGxB,WAAW,EACX,MAAM,EACP,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAGL,KAAK,oBAAoB,EAE1B,MAAM,kBAAkB,CAAC;AAE1B,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EACT,+BAA+B,GAC/B,sBAAsB,GACtB,8BAA8B,GAC9B,mCAAmC,CAAC;IACxC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CACnE;AAED,UAAU,eAAe;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1C,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAC1B,MAAM,CACJ,MAAM,EACN;QACE,QAAQ,CAAC,UAAU,EAAE;YAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;YAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;SAAE,CAAC;QAC3E,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;KAC5B,CACF,CACF,CAAC;CACH;AAmFD,eAAO,MAAM,sBAAsB;;gBAGxB,eAAe,YACZ,WAAW,GACpB,OAAO,CAAC,MAAM,CAAC,oBAAoB,EAAE,gBAAgB,CAAC,CAAC;CAgI3D,CAAC;AAEF,wEAAwE;AACxE,eAAO,MAAM,wBAAwB,EAAE,wBAAwB,CAC7D,oBAAoB,EACpB,iBAAiB,CAoClB,CAAC;AAEF,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,mBAAmB,GAAG,oBAAoB,EACpD,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,MAAM,CAAC,oBAAoB,EAAE,OAAO,CAAC,CAAC,CAWhD"}