@forgeax/engine-vfx 0.1.2

package/src/__tests__/vfx-data-interface-vocabulary-owner.test-d.ts

@@ -0,0 +1,34 @@
+import { describe, expectTypeOf, it } from 'vitest';
+import type {
+  VfxDataInterfaceBindingType,
+  VfxDataInterfaceKind,
+  VfxDataInterfaceProvider,
+  VfxDataInterfaceToken,
+} from '../index.js';
+
+describe('VFX Data Interface vocabulary owner', () => {
+  it('preserves the exact kinds, binding types, and tokens', () => {
+    expectTypeOf<VfxDataInterfaceKind>().toEqualTypeOf<
+      'camera' | 'scene-depth' | 'noise' | 'channel'
+    >();
+    expectTypeOf<VfxDataInterfaceBindingType>().toEqualTypeOf<
+      'uniform' | 'sampled-depth' | 'sampled-float' | 'storage-read'
+    >();
+    expectTypeOf<VfxDataInterfaceToken>().toEqualTypeOf<
+      'vfx:camera' | 'vfx:scene-depth' | 'vfx:noise' | 'vfx:channel'
+    >();
+  });
+
+  it('narrows provider binding types from the selected kind', () => {
+    expectTypeOf<VfxDataInterfaceProvider<'camera'>['bindingType']>().toEqualTypeOf<'uniform'>();
+    expectTypeOf<
+      VfxDataInterfaceProvider<'scene-depth'>['bindingType']
+    >().toEqualTypeOf<'sampled-depth'>();
+    expectTypeOf<
+      VfxDataInterfaceProvider<'noise'>['bindingType']
+    >().toEqualTypeOf<'sampled-float'>();
+    expectTypeOf<
+      VfxDataInterfaceProvider<'channel'>['bindingType']
+    >().toEqualTypeOf<'storage-read'>();
+  });
+});

package/src/__tests__/vfx-performance-contract.unit.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from 'vitest';
+
+describe('VFX performance contract', () => {
+  it('names every Batch B workload and its bounded evidence fields', () => {
+    const capacities = [10_000, 100_000, 1_000_000];
+    expect(capacities).toHaveLength(3);
+    expect({
+      backend: 'dawn-wgpu',
+      warmupFrames: 30,
+      samples: 60,
+      p95: true,
+      p99: true,
+      overflow: true,
+      allocation: true,
+    }).toEqual(
+      expect.objectContaining({ backend: 'dawn-wgpu', p95: true, p99: true, allocation: true }),
+    );
+  });
+});

package/src/__tests__/vfx-value-type-owner.test-d.ts

@@ -0,0 +1,32 @@
+import { describe, expectTypeOf, it } from 'vitest';
+import type { VfxReflectedField, VfxValueType } from '../index.js';
+
+describe('VfxValueType owner contract', () => {
+  it('preserves the exact public six-member vocabulary', () => {
+    expectTypeOf<VfxValueType>().toEqualTypeOf<
+      'f32' | 'i32' | 'u32' | 'vec2<f32>' | 'vec3<f32>' | 'vec4<f32>'
+    >();
+    expectTypeOf<VfxReflectedField['type']>().toEqualTypeOf<VfxValueType>();
+  });
+
+  it('keeps scalar and vector members precisely narrowed', () => {
+    type ScalarTypes = Extract<VfxValueType, 'f32' | 'i32' | 'u32'>;
+    type VectorTypes = Exclude<VfxValueType, ScalarTypes>;
+
+    expectTypeOf<ScalarTypes>().toEqualTypeOf<'f32' | 'i32' | 'u32'>();
+    expectTypeOf<VectorTypes>().toEqualTypeOf<'vec2<f32>' | 'vec3<f32>' | 'vec4<f32>'>();
+  });
+
+  it('rejects values outside the reflected public type declaration', () => {
+    const valid: VfxReflectedField = {
+      name: 'value',
+      type: 'vec4<f32>',
+      offset: 0,
+      size: 16,
+      alignment: 16,
+    };
+    // @ts-expect-error unknown WGSL value types are outside the public declaration.
+    const invalid: VfxReflectedField = { ...valid, type: 'mat4x4<f32>' };
+    void invalid;
+  });
+});

package/src/assets/particle-effect-decoder.ts

@@ -0,0 +1,34 @@
+import {
+  type AssetDecoderContribution,
+  type AssetKind,
+  err,
+  ok,
+  type ParticleEffectAsset,
+} from '@forgeax/engine-types';
+
+export const particleEffectContribution: AssetDecoderContribution<
+  ParticleEffectAsset,
+  'particle-effect'
+> = {
+  kind: { kind: 'particle-effect' } as AssetKind<ParticleEffectAsset, 'particle-effect'>,
+  consumer: 'VfxGpuRuntime',
+  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
+      ) {
+        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',
+        detail: { guid: envelope.guid, reason: 'particle owner validation failed' },
+      });
+    },
+  },
+};

package/src/authoring-descriptor.ts

@@ -0,0 +1,355 @@
+import type { VfxGpuEffectAsset, VfxGpuEmitterProgram } from './gpu-program.js';
+
+export type VfxAuthoringValue =
+  | null
+  | string
+  | number
+  | boolean
+  | readonly VfxAuthoringValue[]
+  | { readonly [key: string]: VfxAuthoringValue };
+
+export interface VfxAuthoringFieldDescriptor {
+  readonly path: string;
+  readonly label: string;
+  readonly value: VfxAuthoringValue;
+  readonly valueType: 'text' | 'number' | 'boolean' | 'vector' | 'object';
+}
+
+export type VfxAuthoringNodeRole =
+  | 'emitter'
+  | 'program'
+  | 'parameters'
+  | 'custom'
+  | 'stage'
+  | 'channel'
+  | 'event'
+  | 'renderer';
+
+export interface VfxAuthoringNodeDescriptor {
+  readonly id: string;
+  readonly role: VfxAuthoringNodeRole;
+  readonly label: string;
+  readonly sourcePath: string;
+  readonly fields: readonly VfxAuthoringFieldDescriptor[];
+  readonly children: readonly VfxAuthoringNodeDescriptor[];
+}
+
+export interface VfxAuthoringEmitterDescriptor extends VfxAuthoringNodeDescriptor {
+  readonly role: 'emitter';
+  readonly module: string;
+}
+
+export interface VfxAuthoringTimelineDescriptor {
+  readonly emitterId: string;
+  readonly rate: number;
+  readonly bursts: readonly { readonly time: number; readonly count: number }[];
+  readonly loopDuration?: number;
+}
+
+export interface VfxAuthoringDependencyDescriptor {
+  readonly kind: 'asset' | 'module' | 'data-interface';
+  readonly identity: string;
+  readonly sourcePath: string;
+}
+
+export interface VfxAuthoringCapabilityDescriptor {
+  readonly id: string;
+  readonly state: 'executable' | 'partial' | 'unavailable';
+  readonly reason?: string;
+}
+
+export interface VfxAuthoringDescriptor {
+  readonly version: 1;
+  readonly assetGuid: string;
+  readonly schemaVersion: 2;
+  readonly artifactFingerprint: string;
+  readonly emitters: readonly VfxAuthoringEmitterDescriptor[];
+  readonly timeline: readonly VfxAuthoringTimelineDescriptor[];
+  readonly dependencies: readonly VfxAuthoringDependencyDescriptor[];
+  readonly capabilities: readonly VfxAuthoringCapabilityDescriptor[];
+}
+
+const CAPABILITIES: readonly VfxAuthoringCapabilityDescriptor[] = 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: 'data-interfaces',
+    state: 'partial',
+    reason: 'requirements resolve provider readiness without author resource bindings',
+  }),
+]);
+
+/** Narrow an AssetRegistry payload without making editor consumers duplicate
+ * the cooked program shape. This deliberately validates the stable producer
+ * discriminants only; detailed artifact validation remains the pack loader's
+ * responsibility. */
+export function isVfxGpuEffectAsset(value: unknown): value is VfxGpuEffectAsset {
+  if (typeof value !== 'object' || value === null) return false;
+  const candidate = value as Partial<VfxGpuEffectAsset>;
+  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)
+  );
+}
+
+function label(path: string): string {
+  const leaf = path.split('.').at(-1) ?? path;
+  return leaf.replaceAll(/([a-z])([A-Z])/g, '$1 $2').replace(/^./, (value) => value.toUpperCase());
+}
+
+function authoringValue(value: unknown): VfxAuthoringValue {
+  if (
+    value === null ||
+    typeof value === 'string' ||
+    typeof value === 'number' ||
+    typeof value === 'boolean'
+  ) {
+    return value;
+  }
+  if (Array.isArray(value)) return Object.freeze(value.map(authoringValue));
+  if (typeof value === 'object') {
+    const out: Record<string, VfxAuthoringValue> = {};
+    for (const [key, child] of Object.entries(value)) out[key] = authoringValue(child);
+    return Object.freeze(out);
+  }
+  return String(value);
+}
+
+function valueType(value: VfxAuthoringValue): VfxAuthoringFieldDescriptor['valueType'] {
+  if (typeof value === 'number') return 'number';
+  if (typeof value === 'boolean') return 'boolean';
+  if (Array.isArray(value) && value.every((entry) => typeof entry === 'number')) return 'vector';
+  if (typeof value === 'object' && value !== null) return 'object';
+  return 'text';
+}
+
+function field(path: string, value: unknown): VfxAuthoringFieldDescriptor {
+  const normalized = authoringValue(value);
+  return Object.freeze({
+    path,
+    label: label(path),
+    value: normalized,
+    valueType: valueType(normalized),
+  });
+}
+
+function fields(
+  path: string,
+  value: object,
+  omit: readonly string[] = [],
+): readonly VfxAuthoringFieldDescriptor[] {
+  const excluded = new Set(omit);
+  return Object.freeze(
+    Object.entries(value)
+      .filter(([key, child]) => !excluded.has(key) && child !== undefined)
+      .map(([key, child]) => field(`${path}.${key}`, child)),
+  );
+}
+
+function node(
+  input: Omit<VfxAuthoringNodeDescriptor, 'children'> & {
+    readonly children?: readonly VfxAuthoringNodeDescriptor[];
+  },
+): VfxAuthoringNodeDescriptor {
+  return Object.freeze({ ...input, children: Object.freeze([...(input.children ?? [])]) });
+}
+
+function reflectionNodes(
+  emitter: VfxGpuEmitterProgram,
+  path: string,
+): VfxAuthoringNodeDescriptor[] {
+  const nodes: VfxAuthoringNodeDescriptor[] = [];
+  const layout = emitter.reflection.layout;
+  if (layout !== undefined && layout.parameters.fields.length > 0) {
+    nodes.push(
+      node({
+        id: `parameters:${emitter.id}`,
+        role: 'parameters',
+        label: layout.parameters.name,
+        sourcePath: `${path}.program`,
+        fields: Object.freeze(
+          layout.parameters.fields.map((entry) =>
+            field(`parameters.${entry.name}`, {
+              type: entry.type,
+              offset: entry.offset,
+              size: entry.size,
+              alignment: entry.alignment,
+              defaultValue: entry.defaultValue ?? null,
+            }),
+          ),
+        ),
+      }),
+    );
+  }
+  if (layout !== undefined && layout.custom.fields.length > 0) {
+    nodes.push(
+      node({
+        id: `custom:${emitter.id}`,
+        role: 'custom',
+        label: layout.custom.name,
+        sourcePath: `${path}.program`,
+        fields: Object.freeze(
+          layout.custom.fields.map((entry) =>
+            field(`custom.${entry.name}`, {
+              type: entry.type,
+              offset: entry.offset,
+              size: entry.size,
+              alignment: entry.alignment,
+              defaultValue: entry.defaultValue ?? null,
+            }),
+          ),
+        ),
+      }),
+    );
+  }
+  for (const stage of emitter.reflection.stages ?? []) {
+    nodes.push(
+      node({
+        id: `stage:${emitter.id}:${stage.id}`,
+        role: 'stage',
+        label: stage.id,
+        sourcePath: `${path}.program`,
+        fields: fields(`stages.${stage.id}`, stage, ['id', 'entryPoint']),
+      }),
+    );
+  }
+  return nodes;
+}
+
+function emitterNode(emitter: VfxGpuEmitterProgram, index: number): VfxAuthoringEmitterDescriptor {
+  const path = `emitters[${index}]`;
+  const children: VfxAuthoringNodeDescriptor[] = [
+    node({
+      id: `program:${emitter.id}`,
+      role: 'program',
+      label: emitter.module,
+      sourcePath: `${path}.program.module`,
+      fields: Object.freeze([
+        field(`${path}.program.module`, emitter.module),
+        field(`${path}.program.imports`, emitter.reflection.imports),
+      ]),
+    }),
+    ...reflectionNodes(emitter, path),
+    ...(emitter.channels ?? []).map((channel, channelIndex) =>
+      node({
+        id: `channel:${emitter.id}:${channel.id}`,
+        role: 'channel',
+        label: channel.id,
+        sourcePath: `${path}.channels[${channelIndex}]`,
+        fields: fields(`${path}.channels[${channelIndex}]`, channel, ['id']),
+      }),
+    ),
+    ...(emitter.events ?? []).map((event, eventIndex) =>
+      node({
+        id: `event:${emitter.id}:${event.id}`,
+        role: 'event',
+        label: event.id,
+        sourcePath: `${path}.events[${eventIndex}]`,
+        fields: fields(`${path}.events[${eventIndex}]`, event, ['id']),
+      }),
+    ),
+    ...emitter.renderers.map((renderer, rendererIndex) =>
+      node({
+        id: `renderer:${emitter.id}:${rendererIndex}`,
+        role: 'renderer',
+        label: `${renderer.kind} renderer`,
+        sourcePath: `${path}.renderers[${rendererIndex}]`,
+        fields: fields(`${path}.renderers[${rendererIndex}]`, renderer, ['kind']),
+      }),
+    ),
+  ];
+  return Object.freeze({
+    id: `emitter:${emitter.id}`,
+    role: 'emitter',
+    label: emitter.id,
+    module: emitter.module,
+    sourcePath: path,
+    fields: Object.freeze([
+      field(`${path}.capacity`, emitter.capacity),
+      field(`${path}.space`, emitter.space),
+      field(`${path}.bounds`, emitter.bounds),
+      field(`${path}.simulationWhenCulled`, emitter.simulationWhenCulled),
+    ]),
+    children: Object.freeze(children),
+  });
+}
+
+function dependencies(effect: VfxGpuEffectAsset): readonly VfxAuthoringDependencyDescriptor[] {
+  const entries: VfxAuthoringDependencyDescriptor[] = [];
+  const seen = new Set<string>();
+  const add = (entry: VfxAuthoringDependencyDescriptor): void => {
+    const key = `${entry.kind}:${entry.identity}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    entries.push(Object.freeze(entry));
+  };
+  for (const [emitterIndex, emitter] of effect.program.emitters.entries()) {
+    const path = `emitters[${emitterIndex}]`;
+    add({ kind: 'module', identity: emitter.module, sourcePath: `${path}.program.module` });
+    for (const identity of emitter.reflection.imports) {
+      add({ kind: 'module', identity, sourcePath: `${path}.program.imports` });
+    }
+    for (const [rendererIndex, renderer] of emitter.renderers.entries()) {
+      add({
+        kind: 'asset',
+        identity: renderer.material,
+        sourcePath: `${path}.renderers[${rendererIndex}].material`,
+      });
+      if (renderer.kind === 'mesh') {
+        add({
+          kind: 'asset',
+          identity: renderer.mesh,
+          sourcePath: `${path}.renderers[${rendererIndex}].mesh`,
+        });
+      }
+    }
+    for (const requirement of emitter.reflection.dataInterfaces ?? []) {
+      add({ kind: 'data-interface', identity: requirement.token, sourcePath: `${path}.program` });
+    }
+  }
+  return Object.freeze(entries);
+}
+
+/** Project the cooked runtime asset into a compiler-free, UI-neutral authoring read model. */
+export function describeVfxGpuEffect(effect: VfxGpuEffectAsset): VfxAuthoringDescriptor {
+  return Object.freeze({
+    version: 1,
+    assetGuid: effect.guid,
+    schemaVersion: 2,
+    artifactFingerprint: effect.program.fingerprint,
+    emitters: Object.freeze(effect.program.emitters.map(emitterNode)),
+    timeline: Object.freeze(
+      effect.program.emitters.map((emitter) =>
+        Object.freeze({
+          emitterId: emitter.id,
+          rate: emitter.schedule.rate,
+          bursts: Object.freeze([...(emitter.schedule.bursts ?? [])]),
+          ...(emitter.schedule.loopDuration === undefined
+            ? {}
+            : { loopDuration: emitter.schedule.loopDuration }),
+        }),
+      ),
+    ),
+    dependencies: dependencies(effect),
+    capabilities: CAPABILITIES,
+  });
+}