@forgeax/engine-assets-runtime 0.1.6 → 0.1.19

package/src/material/runtime-shader.ts

@@ -22,7 +22,7 @@ export function materialParametersToParamSchema(
       ? ENGINE_INJECTED_TEXTURE_FIELDS
       : undefined;
   return parameters.flatMap((parameter): ParamSchemaEntry[] => {
-    if (parameter.static || parameter.type === 'bool') return [];
+    if (parameter.type === 'bool') return [];
     if (parameter.type === 'texture') {
       if (engineInjectedTextureFields?.has(parameter.name) === true) return [];
       return [{ name: parameter.name, type: 'texture2d' }];

package/src/mipmap-generator.ts

@@ -45,7 +45,7 @@
 //   - `numMipLevels` is pure (no device argument); the WeakMap lookup only
 //     happens at pipeline-create time.
 
-import { err, ok, type Result, RhiError } from '@forgeax/engine-rhi';
+import { err, ok, type Result, RhiError, type RhiRenderPassEncoder } from '@forgeax/engine-rhi';
 
 /**
  * Subset of `RhiDevice` consumed by the mipmap utility (charter F2: only
@@ -448,3 +448,45 @@ export function blitMipmapsSync(
 
   return recordMipmapBlit<RhiError>(device, texture, levels, pipeline, cache);
 }
+
+/** Encode one prewarmed mip level into a caller-owned graph render pass. */
+export function encodeMipmapLevel(
+  device: MipmapBlitDevice,
+  pass: RhiRenderPassEncoder,
+  sourceView: unknown,
+  format: GPUTextureFormat,
+): Result<void, RhiError> {
+  const cache = deviceCache.get(device);
+  if (cache === undefined) {
+    return err(
+      new RhiError({
+        code: 'rhi-not-available',
+        expected: 'mipmap pipeline cache prewarmed for the graph device before encoding',
+        hint: 'call prewarmMipmapPipeline(device, formats) at renderer.ready',
+      }),
+    );
+  }
+  const pipeline = cache.pipelines.get(format);
+  if (pipeline === undefined) {
+    return err(
+      new RhiError({
+        code: 'rhi-not-available',
+        expected: `mipmap pipeline for format ${format} prewarmed`,
+        hint: `format ${format} was not prewarmed; add it to the renderer prewarm list`,
+      }),
+    );
+  }
+  const bindGroup = device.createBindGroup({
+    label: 'mipmap-graph-bind-group',
+    layout: cache.layout,
+    entries: [
+      { binding: 0, resource: { kind: 'sampler', value: cache.sampler } },
+      { binding: 1, resource: { kind: 'textureView', value: sourceView } },
+    ],
+  });
+  if (!bindGroup.ok) return bindGroup;
+  pass.setPipeline(pipeline);
+  pass.setBindGroup(0, bindGroup.value);
+  pass.draw(3, 1, 0, 0);
+  return ok(undefined);
+}

package/src/registry/instantiate.ts

@@ -78,16 +78,26 @@ function catalogEntriesForFence(registry: AssetRegistry): readonly CatalogEntry[
     if (record.sourcePath === undefined) continue;
     const candidate = { ...record, guid, sourcePath: record.sourcePath } as CatalogEntry;
     const current = byGuid.get(guid.toLowerCase());
-    if (
-      current === undefined ||
-      (current.publication === undefined && candidate.publication !== undefined)
-    ) {
+    if (current === undefined || candidate.publication !== undefined) {
+      // A persisted Scene fence is captured from the complete pack-index
+      // publication at save time. If the CatalogReplica is still carrying its
+      // previous tuple during the watcher handoff, keep the same pack-index
+      // authority here or the freshly reopened scene will reject its own
+      // mount with asset-generation-fence-mismatch.
       byGuid.set(guid.toLowerCase(), candidate);
     }
   }
   return [...byGuid.values()];
 }
 
+/** Derive a publication fence from the registry's unified live projections. */
+export function scenePublicationFenceFromRegistry(
+  registry: AssetRegistry,
+  outputGuid: string,
+): Result<ScenePublicationFence, ScenePublicationFenceError> {
+  return scenePublicationFenceFromCatalog(catalogEntriesForFence(registry), outputGuid);
+}
+
 /**
  * Post-spawn hook contract (D-1). A hook runs after instantiate spawns the
  * scene subtree; the shipped implementation is runtime's `postSpawnResolveJoints`

package/src/registry/load-by-guid.ts

@@ -104,7 +104,7 @@ export async function loadByGuid<T = Asset>(
 }
 
 function cookedRecordFromPayload(payload: Record<string, unknown>): unknown {
-  if (payload.schemaVersion === 'material-cook/2') return payload;
+  if (payload.schemaVersion === 'material-cook/3') return payload;
   if (payload.cooked !== null && typeof payload.cooked === 'object') return payload.cooked;
   if (payload.record !== null && typeof payload.record === 'object') return payload.record;
   return undefined;

package/src/registry/validate-material.ts

@@ -112,6 +112,100 @@ export function validateMaterialPasses(
   return null;
 }
 
+type TransmissionParameter =
+  | 'transmission'
+  | 'ior'
+  | 'thickness'
+  | 'attenuationColor'
+  | 'attenuationDistance'
+  | 'transmissionTexture'
+  | 'thicknessTexture';
+
+function transmissionError(
+  material: string,
+  parameter: TransmissionParameter,
+  reason: 'non-finite' | 'range' | 'shape' | 'blend' | 'depth-write',
+  actual?: unknown,
+): MaterialError {
+  return createMaterialError('material-transmission-contract-invalid', {
+    code: 'material-transmission-contract-invalid',
+    material,
+    parameter,
+    reason,
+    ...(actual === undefined ? {} : { actual }),
+  });
+}
+
+function validateTransmissionNumber(
+  material: string,
+  values: Record<string, unknown>,
+  parameter: 'transmission' | 'ior' | 'thickness' | 'attenuationDistance',
+  minimum: number,
+  maximum?: number,
+): MaterialError | null {
+  const value = values[parameter];
+  if (value === undefined) return null;
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    return transmissionError(material, parameter, 'non-finite', value);
+  }
+  if (value < minimum || (maximum !== undefined && value > maximum)) {
+    return transmissionError(material, parameter, 'range', value);
+  }
+  return null;
+}
+
+export function validateMaterialTransmissionContract(asset: MaterialAsset): MaterialError | null {
+  const material = (asset.values?.materialName as string | undefined) ?? '<unnamed>';
+  const values = (asset.values ?? {}) as Record<string, unknown>;
+  const numericChecks: ReadonlyArray<
+    ['transmission' | 'ior' | 'thickness' | 'attenuationDistance', number, number | undefined]
+  > = [
+    ['transmission', 0, 1],
+    ['ior', 1, undefined],
+    ['thickness', 0, undefined],
+    ['attenuationDistance', Number.MIN_VALUE, undefined],
+  ];
+  for (const [parameter, minimum, maximum] of numericChecks) {
+    const error = validateTransmissionNumber(material, values, parameter, minimum, maximum);
+    if (error !== null) return error;
+  }
+  const attenuationColor = values.attenuationColor;
+  if (attenuationColor !== undefined) {
+    if (
+      !Array.isArray(attenuationColor) ||
+      attenuationColor.length !== 3 ||
+      attenuationColor.some(
+        (value) => typeof value !== 'number' || !Number.isFinite(value) || value < 0 || value > 1,
+      )
+    ) {
+      return transmissionError(material, 'attenuationColor', 'shape', attenuationColor);
+    }
+  }
+  for (const parameter of ['transmissionTexture', 'thicknessTexture'] as const) {
+    const value = values[parameter];
+    if (
+      value !== undefined &&
+      typeof value !== 'string' &&
+      !(typeof value === 'number' && Number.isInteger(value) && value >= 0) &&
+      (typeof value !== 'object' || value === null || Array.isArray(value))
+    ) {
+      return transmissionError(material, parameter, 'shape', value);
+    }
+  }
+  const transmission = values.transmission;
+  if (typeof transmission === 'number' && transmission > 0) {
+    for (const pass of asset.passes ?? []) {
+      if (pass.renderState?.blend !== undefined) {
+        return transmissionError(material, 'transmission', 'blend');
+      }
+      if (pass.renderState?.depthWriteEnabled === true) {
+        return transmissionError(material, 'transmission', 'depth-write');
+      }
+    }
+  }
+  return null;
+}
+
 export interface MaterialEffectiveRootIdentity {
   readonly guid: string;
   readonly layoutIdentity: string;
@@ -121,11 +215,10 @@ export function validateMaterialCookIdentity(
   record: Pick<CookedMaterialRecord, 'guid' | 'receipt'>,
   root: MaterialEffectiveRootIdentity,
 ): MaterialError | null {
-  const actual = record.receipt.layoutIdentity;
+  const actual = record.receipt.identity.layoutIdentity;
   if (
     actual !== root.layoutIdentity ||
-    (record.receipt as { readonly derivedInterface?: { readonly layoutIdentity?: string } })
-      .derivedInterface?.layoutIdentity !== root.layoutIdentity
+    record.receipt.derivedInterface.layoutIdentity !== root.layoutIdentity
   ) {
     return createMaterialError('material-derived-interface-mismatch', {
       code: 'material-derived-interface-mismatch',