@forgeax/engine-vfx 0.1.2

package/src/data-interface.ts

@@ -0,0 +1,181 @@
+import { err, ok, type Result } from '@forgeax/engine-types';
+
+export type VfxDataInterfaceKind = keyof VfxDataInterfaceBindingTypeByKind;
+
+export type VfxDataInterfaceToken = `vfx:${VfxDataInterfaceKind}`;
+
+export type VfxDataInterfaceBindingType = VfxDataInterfaceBindingTypeByKind[VfxDataInterfaceKind];
+
+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 {
+  readonly token: VfxDataInterfaceToken;
+  readonly kind: VfxDataInterfaceKind;
+  readonly binding: number;
+  readonly bindingType: VfxDataInterfaceBindingType;
+  readonly lifetime: VfxDataInterfaceLifetime;
+}
+
+export interface VfxDataInterfaceResource {
+  readonly token: VfxDataInterfaceToken;
+  readonly kind: VfxDataInterfaceKind;
+  readonly bindingType: VfxDataInterfaceBindingType;
+  readonly generation: number;
+}
+
+export interface VfxDataInterfaceErrorDetail {
+  readonly token: VfxDataInterfaceToken;
+  readonly providerId?: string;
+  readonly expectedGeneration?: number;
+  readonly actualGeneration?: number;
+  readonly expectedBindingType?: VfxDataInterfaceBindingType;
+  readonly actualBindingType?: VfxDataInterfaceBindingType;
+}
+
+export interface VfxDataInterfaceError {
+  readonly code:
+    | 'vfx-data-interface-missing'
+    | 'vfx-data-interface-wrong-type'
+    | 'vfx-data-interface-stale'
+    | 'vfx-data-interface-duplicate';
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: VfxDataInterfaceErrorDetail;
+}
+
+export type VfxDataInterfaceProvider<K extends VfxDataInterfaceKind = VfxDataInterfaceKind> = {
+  readonly id: string;
+  readonly token: `vfx:${K}`;
+  readonly kind: K;
+  readonly bindingType: VfxDataInterfaceBindingTypeByKind[K];
+  readonly provide: (generation: number) => Result<VfxDataInterfaceResource, VfxDataInterfaceError>;
+};
+
+export interface VfxDataInterfaceResolution {
+  readonly generation: number;
+  readonly readiness: 'ready';
+  readonly resources: readonly VfxDataInterfaceResource[];
+}
+
+function failure(
+  code: VfxDataInterfaceError['code'],
+  requirement: VfxDataInterfaceRequirement,
+  expected: string,
+  hint: string,
+  detail: Omit<VfxDataInterfaceErrorDetail, 'token'> = {},
+): VfxDataInterfaceError {
+  return { code, expected, hint, detail: { token: requirement.token, ...detail } };
+}
+
+export function resolveVfxDataInterfaces(
+  requirements: readonly VfxDataInterfaceRequirement[],
+  providers: readonly VfxDataInterfaceProvider[],
+  generation: number,
+): Result<VfxDataInterfaceResolution, VfxDataInterfaceError> {
+  const byToken = new Map<VfxDataInterfaceToken, VfxDataInterfaceProvider>();
+  for (const provider of providers) {
+    const prior = byToken.get(provider.token);
+    if (prior !== undefined) {
+      const requirement = requirements.find((entry) => entry.token === provider.token) ?? {
+        token: provider.token,
+        kind: provider.kind,
+        binding: -1,
+        bindingType: provider.bindingType,
+        lifetime: 'generation',
+      };
+      return err(
+        failure(
+          'vfx-data-interface-duplicate',
+          requirement,
+          'at most one provider for each reflected Data Interface token',
+          `remove duplicate providers ${prior.id} and ${provider.id} and retry`,
+          { providerId: provider.id },
+        ),
+      );
+    }
+    byToken.set(provider.token, provider);
+  }
+
+  const resources: VfxDataInterfaceResource[] = [];
+  for (const requirement of requirements) {
+    const provider = byToken.get(requirement.token);
+    if (provider === undefined) {
+      return err(
+        failure(
+          'vfx-data-interface-missing',
+          requirement,
+          `a registered ${requirement.kind} provider for ${requirement.token}`,
+          `register ${requirement.token} for generation ${generation} before starting the effect`,
+        ),
+      );
+    }
+    if (provider.kind !== requirement.kind || provider.bindingType !== requirement.bindingType) {
+      return err(
+        failure(
+          'vfx-data-interface-wrong-type',
+          requirement,
+          `${requirement.kind} with ${requirement.bindingType} binding semantics`,
+          `replace provider ${provider.id} with a ${requirement.token} provider matching reflection`,
+          {
+            providerId: provider.id,
+            expectedBindingType: requirement.bindingType,
+            actualBindingType: provider.bindingType,
+          },
+        ),
+      );
+    }
+    const provided = provider.provide(generation);
+    if (!provided.ok) return provided;
+    const resource = provided.value;
+    if (resource.token !== requirement.token || resource.kind !== requirement.kind) {
+      return err(
+        failure(
+          'vfx-data-interface-wrong-type',
+          requirement,
+          `${requirement.kind} resource for ${requirement.token}`,
+          `repair provider ${provider.id} so its resource matches its reflected token`,
+          { providerId: provider.id },
+        ),
+      );
+    }
+    if (resource.bindingType !== requirement.bindingType) {
+      return err(
+        failure(
+          'vfx-data-interface-wrong-type',
+          requirement,
+          `resource binding type ${requirement.bindingType}`,
+          `repair provider ${provider.id} resource binding metadata`,
+          {
+            providerId: provider.id,
+            expectedBindingType: requirement.bindingType,
+            actualBindingType: resource.bindingType,
+          },
+        ),
+      );
+    }
+    if (resource.generation !== generation) {
+      return err(
+        failure(
+          'vfx-data-interface-stale',
+          requirement,
+          `a resource from generation ${generation}`,
+          `refresh provider ${provider.id} for generation ${generation} before rendering`,
+          {
+            providerId: provider.id,
+            expectedGeneration: generation,
+            actualGeneration: resource.generation,
+          },
+        ),
+      );
+    }
+    resources.push(resource);
+  }
+  return ok({ generation, readiness: 'ready', resources: Object.freeze(resources) });
+}

package/src/effect-contract.ts

@@ -0,0 +1,220 @@
+import { err, ok, type Result } from '@forgeax/engine-types';
+import type { VfxDataInterfaceRequirement } from './data-interface.js';
+
+export type VfxValue = number | readonly number[];
+export type VfxValueMap = Readonly<Record<string, VfxValue>>;
+
+export interface VfxReflectedField {
+  readonly name: string;
+  readonly type: VfxValueType;
+  readonly offset: number;
+  readonly size: number;
+  readonly alignment: number;
+  readonly defaultValue?: VfxValue;
+}
+
+export interface VfxReflectedStruct {
+  readonly name: string;
+  readonly fields: readonly VfxReflectedField[];
+  readonly size: number;
+  readonly alignment: number;
+}
+
+export interface VfxEffectReflection {
+  readonly version: 1;
+  readonly parameters: VfxReflectedStruct;
+  readonly custom: VfxReflectedStruct;
+  readonly dataInterfaces?: readonly VfxDataInterfaceRequirement[];
+  readonly fingerprint: string;
+}
+
+export interface VfxEffectContractErrorDetail {
+  readonly path: string;
+  readonly actual?: unknown;
+}
+
+export interface VfxEffectContractError {
+  readonly code:
+    | 'vfx-value-unknown-field'
+    | 'vfx-value-type-mismatch'
+    | 'vfx-value-not-finite'
+    | 'vfx-reflection-invalid';
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: VfxEffectContractErrorDetail;
+}
+
+export interface VfxEffectContract<Values extends VfxValueMap = VfxValueMap> {
+  readonly reflection: VfxEffectReflection;
+  readonly fingerprint: string;
+  readonly packedSize: number;
+  readonly defaults: Values;
+  createValues(initial?: Partial<Values>): Result<Values, VfxEffectContractError>;
+  validateValues(values: VfxValueMap): Result<Values, VfxEffectContractError>;
+  pack(values: Values): Result<Uint8Array, VfxEffectContractError>;
+}
+
+const VECTOR_LENGTH = {
+  f32: 1,
+  i32: 1,
+  u32: 1,
+  'vec2<f32>': 2,
+  'vec3<f32>': 3,
+  'vec4<f32>': 4,
+};
+
+export type VfxValueType = keyof typeof VECTOR_LENGTH;
+
+function fieldList(reflection: VfxEffectReflection): readonly VfxReflectedField[] {
+  return [...reflection.parameters.fields, ...reflection.custom.fields];
+}
+
+function zeroValue(type: VfxValueType): VfxValue {
+  const length = VECTOR_LENGTH[type];
+  return length === 1 ? 0 : Array.from({ length }, () => 0);
+}
+
+function valueMatches(type: VfxValueType, value: unknown): boolean {
+  const length = VECTOR_LENGTH[type];
+  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: VfxEffectContractError['code'],
+  path: string,
+  expected: string,
+  hint: string,
+  actual?: unknown,
+): Result<never, VfxEffectContractError> {
+  return err({
+    code,
+    expected,
+    hint,
+    detail: actual === undefined ? { path } : { path, actual },
+  });
+}
+
+function validateReflection(reflection: VfxEffectReflection): Result<true, VfxEffectContractError> {
+  if (
+    reflection.version !== 1 ||
+    typeof reflection.fingerprint !== 'string' ||
+    !reflection.fingerprint.startsWith('sha256:')
+  ) {
+    return fail(
+      'vfx-reflection-invalid',
+      'reflection',
+      'a version 1 reflection with a sha256 fingerprint',
+      'recook the effect with the current VFX compiler',
+    );
+  }
+  const names = new Set<string>();
+  for (const field of fieldList(reflection)) {
+    if (names.has(field.name)) {
+      return fail(
+        'vfx-reflection-invalid',
+        field.name,
+        'unique field names across parameters and custom data',
+        'rename the duplicate WGSL field and recook',
+      );
+    }
+    names.add(field.name);
+  }
+  return ok(true);
+}
+
+function defaultsFor<Values extends VfxValueMap>(reflection: VfxEffectReflection): Values {
+  const defaults: Record<string, VfxValue> = {};
+  for (const field of fieldList(reflection)) {
+    defaults[field.name] =
+      field.defaultValue === undefined ? zeroValue(field.type) : field.defaultValue;
+  }
+  return Object.freeze(defaults) as Values;
+}
+
+function validateMap<Values extends VfxValueMap>(
+  reflection: VfxEffectReflection,
+  values: VfxValueMap,
+): Result<Values, VfxEffectContractError> {
+  const fields = new Map(fieldList(reflection).map((field) => [field.name, field]));
+  for (const name of Object.keys(values)) {
+    const field = fields.get(name);
+    if (field === undefined) {
+      return fail(
+        'vfx-value-unknown-field',
+        name,
+        'a field declared by VfxParameters or VfxCustom',
+        `remove ${name} or declare it in the authored WGSL struct`,
+        values[name],
+      );
+    }
+    if (!valueMatches(field.type, values[name])) {
+      return fail(
+        'vfx-value-type-mismatch',
+        name,
+        field.type,
+        `provide ${name} as ${field.type}`,
+        values[name],
+      );
+    }
+  }
+  return ok(Object.freeze({ ...values }) as Values);
+}
+
+function writeValue(view: DataView, offset: number, type: VfxValueType, value: VfxValue): void {
+  const values = typeof value === 'number' ? [value] : value;
+  for (let index = 0; index < values.length; index += 1) {
+    const component = values[index] ?? 0;
+    if (type === 'i32') view.setInt32(offset + index * 4, component, true);
+    else if (type === 'u32') view.setUint32(offset + index * 4, component, true);
+    else view.setFloat32(offset + index * 4, component, true);
+  }
+}
+
+export function createVfxEffectContract<Values extends VfxValueMap = VfxValueMap>(
+  reflection: VfxEffectReflection,
+): VfxEffectContract<Values> {
+  const checked = validateReflection(reflection);
+  if (!checked.ok) throw new TypeError(checked.error.hint);
+  const defaults = defaultsFor<Values>(reflection);
+  const fields = fieldList(reflection);
+  const customBase = reflection.parameters.size;
+  const packedSize = customBase + reflection.custom.size;
+  return {
+    reflection,
+    fingerprint: reflection.fingerprint,
+    packedSize,
+    defaults,
+    createValues(initial = {} as Partial<Values>) {
+      const merged = { ...defaults, ...initial };
+      return validateMap<Values>(reflection, merged);
+    },
+    validateValues(values) {
+      return validateMap<Values>(reflection, values);
+    },
+    pack(values) {
+      const checkedValues = validateMap<Values>(reflection, values);
+      if (!checkedValues.ok) return checkedValues;
+      const bytes = new Uint8Array(packedSize);
+      const view = new DataView(bytes.buffer);
+      for (const field of fields) {
+        const value = checkedValues.value[field.name];
+        if (value === undefined) continue;
+        const base = reflection.parameters.fields.includes(field) ? 0 : customBase;
+        writeValue(view, base + field.offset, field.type, value);
+      }
+      return ok(bytes);
+    },
+  };
+}
+
+export function validateVfxEffectValues(
+  reflection: VfxEffectReflection,
+  values: VfxValueMap,
+): Result<VfxValueMap, VfxEffectContractError> {
+  return validateMap(reflection, values);
+}

package/src/gpu-loader.ts

@@ -0,0 +1,279 @@
+import type { AssetRegistry } from '@forgeax/engine-assets-runtime';
+import type {
+  AssetDecoderContribution,
+  AssetKind,
+  AssetLoadError,
+  LoadContext,
+  Result,
+} from '@forgeax/engine-types';
+import { err, ok } from '@forgeax/engine-types';
+import {
+  VFX_GPU_PROGRAM_ARTIFACT_KEY,
+  VFX_GPU_PROGRAM_FORMAT,
+  type VfxGpuEffectAsset,
+  type VfxGpuEmitterProgram,
+} from './gpu-program.js';
+
+export interface VfxGpuAssetError {
+  readonly code:
+    | 'vfx-asset-v2-invalid'
+    | 'vfx-asset-v2-program-missing'
+    | 'vfx-asset-v2-fingerprint-mismatch';
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: { readonly guid: string; readonly path: string };
+}
+
+interface PackLoaderInput {
+  readonly guid: string;
+  readonly kind: string;
+  readonly payload: Record<string, unknown>;
+  readonly artifacts: Readonly<
+    Record<
+      string,
+      {
+        readonly descriptor: { readonly path: string; readonly mediaType: string };
+        readonly bytes: Uint8Array;
+      }
+    >
+  >;
+}
+
+function failure(
+  code: VfxGpuAssetError['code'],
+  guid: string,
+  path: string,
+  expected: string,
+  hint: string,
+): Result<never, VfxGpuAssetError> {
+  return err({ code, expected, hint, detail: { guid, path } });
+}
+
+function record(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function hex(bytes: ArrayBuffer): string {
+  return [...new Uint8Array(bytes)].map((value) => value.toString(16).padStart(2, '0')).join('');
+}
+
+async function fingerprint(bytes: Uint8Array): Promise<string> {
+  const source = bytes.buffer.slice(
+    bytes.byteOffset,
+    bytes.byteOffset + bytes.byteLength,
+  ) as ArrayBuffer;
+  return `sha256:${hex(await globalThis.crypto.subtle.digest('SHA-256', source))}`;
+}
+
+function validReflectionLayout(value: unknown): boolean {
+  if (value === undefined) return true;
+  if (!record(value) || value.version !== 1) return false;
+  if (!record(value.parameters) || !Array.isArray(value.parameters.fields)) return false;
+  if (!record(value.custom) || !Array.isArray(value.custom.fields)) return false;
+  return typeof value.fingerprint === 'string' && value.fingerprint.startsWith('sha256:');
+}
+
+function stableLayouts(emitters: readonly VfxGpuEmitterProgram[]): boolean {
+  const fingerprints = emitters
+    .map((emitter) => emitter.reflection.layout?.fingerprint)
+    .filter((fingerprint): fingerprint is string => fingerprint !== undefined);
+  return fingerprints.every((fingerprint) => fingerprint === fingerprints[0]);
+}
+
+function validEmitter(value: unknown): value is VfxGpuEmitterProgram {
+  const reflection = record(value) && record(value.reflection) ? value.reflection : undefined;
+  const layout = reflection !== undefined ? reflection.layout : undefined;
+  return (
+    record(value) &&
+    typeof value.id === 'string' &&
+    typeof value.module === 'string' &&
+    value.module.length > 0 &&
+    Number.isInteger(value.capacity) &&
+    (value.capacity as number) > 0 &&
+    record(value.backend) &&
+    value.backend.required === 'gpu' &&
+    Object.keys(value.backend).length === 1 &&
+    typeof value.wgsl === 'string' &&
+    value.wgsl.length > 0 &&
+    record(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')
+  );
+}
+
+export const vfxGpuEffectPackLoader = {
+  kind: 'particle-effect',
+  async load(
+    input: PackLoaderInput,
+    _context: LoadContext,
+  ): Promise<Result<VfxGpuEffectAsset, VfxGpuAssetError>> {
+    if (
+      input.payload.kind !== 'particle-effect' ||
+      input.payload.schemaVersion !== 2 ||
+      !Array.isArray(input.payload.emitters) ||
+      typeof input.payload.programFingerprint !== 'string' ||
+      !record(input.payload.program)
+    ) {
+      return failure(
+        'vfx-asset-v2-invalid',
+        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',
+      );
+    }
+    const artifact = input.artifacts[VFX_GPU_PROGRAM_ARTIFACT_KEY];
+    if (artifact === undefined) {
+      return failure(
+        'vfx-asset-v2-program-missing',
+        input.guid,
+        VFX_GPU_PROGRAM_ARTIFACT_KEY,
+        'the asset-local cooked VFX program',
+        'recook the particle effect and retry the load',
+      );
+    }
+    let decoded: unknown;
+    try {
+      decoded = JSON.parse(new TextDecoder().decode(artifact.bytes));
+    } catch {
+      return failure(
+        'vfx-asset-v2-invalid',
+        input.guid,
+        VFX_GPU_PROGRAM_ARTIFACT_KEY,
+        'canonical JSON program bytes',
+        'recook the particle effect and retry the load',
+      );
+    }
+    if (
+      !record(decoded) ||
+      decoded.format !== VFX_GPU_PROGRAM_FORMAT ||
+      !Array.isArray(decoded.emitters) ||
+      !decoded.emitters.every(validEmitter) ||
+      !stableLayouts(decoded.emitters as VfxGpuEmitterProgram[])
+    ) {
+      return failure(
+        'vfx-asset-v2-invalid',
+        input.guid,
+        VFX_GPU_PROGRAM_ARTIFACT_KEY,
+        `a ${VFX_GPU_PROGRAM_FORMAT} managed GPU program`,
+        'recook with the current VFX compiler ABI',
+      );
+    }
+    const decodedEmitters = decoded.emitters as VfxGpuEmitterProgram[];
+    if (
+      input.payload.program.format !== VFX_GPU_PROGRAM_FORMAT ||
+      input.payload.program.fingerprint !== input.payload.programFingerprint ||
+      !Array.isArray(input.payload.program.emitters)
+    ) {
+      return failure(
+        'vfx-asset-v2-invalid',
+        input.guid,
+        'payload.program',
+        'the complete canonical program matching payload.programFingerprint',
+        'recook the particle effect atomically',
+      );
+    }
+    const actualFingerprint = await fingerprint(artifact.bytes);
+    if (actualFingerprint !== input.payload.programFingerprint) {
+      return failure(
+        'vfx-asset-v2-fingerprint-mismatch',
+        input.guid,
+        'payload.programFingerprint',
+        'payload and program artifact fingerprints to match',
+        'cold-cook the particle asset so payload and artifact publish atomically',
+      );
+    }
+    const emitters = input.payload.emitters.map((value) => {
+      if (!record(value) || typeof value.id !== 'string' || !Number.isInteger(value.capacity)) {
+        return undefined;
+      }
+      return { id: value.id, capacity: value.capacity as number };
+    });
+    if (
+      emitters.some((value) => value === undefined) ||
+      emitters.length !== decodedEmitters.length ||
+      emitters.some(
+        (value, index) =>
+          value?.id !== decodedEmitters[index]?.id ||
+          value?.capacity !== decodedEmitters[index]?.capacity,
+      )
+    ) {
+      return failure(
+        'vfx-asset-v2-invalid',
+        input.guid,
+        'payload.emitters',
+        'payload emitter identities and capacities to match the program',
+        'recook the particle effect atomically',
+      );
+    }
+    return ok(
+      Object.freeze({
+        guid: input.guid,
+        kind: 'particle-effect',
+        schemaVersion: 2,
+        programFingerprint: actualFingerprint,
+        emitters: Object.freeze(emitters as { id: string; capacity: number }[]),
+        program: Object.freeze({
+          format: VFX_GPU_PROGRAM_FORMAT,
+          fingerprint: actualFingerprint,
+          emitters: Object.freeze(decodedEmitters),
+        }),
+      }),
+    );
+  },
+};
+
+/** VFX owner decoder contribution for the single runtime decoder map. */
+export const vfxGpuEffectContribution: AssetDecoderContribution<
+  VfxGpuEffectAsset,
+  'particle-effect'
+> = {
+  kind: { kind: 'particle-effect' } as AssetKind<VfxGpuEffectAsset, 'particle-effect'>,
+  consumer: 'VfxGpuRuntime',
+  decoder: {
+    async decode({ envelope, artifacts }) {
+      const descriptor = envelope.artifacts[VFX_GPU_PROGRAM_ARTIFACT_KEY];
+      const bytes = descriptor === undefined ? undefined : await artifacts.read(descriptor);
+      if (bytes !== undefined && !bytes.ok) return bytes;
+      const result = await vfxGpuEffectPackLoader.load(
+        {
+          guid: envelope.guid,
+          kind: envelope.kind,
+          payload: envelope.payload as unknown as Record<string, unknown>,
+          artifacts:
+            bytes === undefined || descriptor === undefined
+              ? {}
+              : {
+                  [VFX_GPU_PROGRAM_ARTIFACT_KEY]: {
+                    descriptor: { path: descriptor.path, mediaType: descriptor.mediaType },
+                    bytes: bytes.value,
+                  },
+                },
+        },
+        {} as LoadContext,
+      );
+      if (result.ok) return result;
+      const error: AssetLoadError = {
+        code: 'asset-package-invalid',
+        expected: result.error.expected,
+        hint: result.error.hint,
+        detail: { guid: envelope.guid, reason: result.error.code },
+      };
+      return err(error);
+    },
+  },
+};
+
+export async function loadVfxGpuEffect(
+  registry: AssetRegistry,
+  guid: string,
+): Promise<Result<VfxGpuEffectAsset, unknown>> {
+  return registry.load(guid, vfxGpuEffectContribution.kind);
+}