@forgeax/engine-render 0.1.2

package/src/assets/asset-decoders.ts

@@ -0,0 +1,158 @@
+import { validateCookedMaterialRecord } from '@forgeax/engine-pack';
+import {
+  type AssetDecoderContribution,
+  type AssetKind,
+  type AssetLoadError,
+  err,
+  MATERIAL_TEXTURE_SLOTS,
+  type MaterialAsset,
+  ok,
+  type RenderPipelineAsset,
+  type SamplerAsset,
+} from '@forgeax/engine-types';
+
+function invalid(guid: string, expected: string, reason: string) {
+  return err({
+    code: 'asset-package-invalid' as const,
+    expected,
+    hint: 'recook the render asset and publish its complete cooked payload',
+    detail: { guid, reason },
+  });
+}
+
+function record(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function validMaterial(value: unknown): value is MaterialAsset {
+  if (!record(value) || value.kind !== 'material') return false;
+  if (value.cooked !== undefined && !validateCookedMaterialRecord(value.cooked).ok) {
+    return false;
+  }
+  if (value.passes !== undefined && !Array.isArray(value.passes)) return false;
+  if (value.parameters !== undefined && !Array.isArray(value.parameters)) return false;
+  return value.values === undefined || record(value.values);
+}
+
+function resolveMaterialWireRef(
+  value: unknown,
+  refs: readonly string[],
+  field: string,
+  guid: string,
+): ReturnType<typeof ok<string | number>> | ReturnType<typeof err<AssetLoadError>> {
+  if (typeof value !== 'number') return ok(value as string | number);
+  if (!Number.isSafeInteger(value) || value < 0 || refs[value] === undefined) {
+    return err<AssetLoadError>({
+      code: 'asset-package-invalid',
+      expected: `${field} to reference a GUID through the material Pack refs[] table`,
+      hint: 'recook the material so every texture or sampler ref has a matching refs[] entry',
+      detail: { guid, reason: `${field} refs[${value}] is out of bounds` },
+    });
+  }
+  return ok(refs[value] as string);
+}
+
+function resolveMaterialWireRefs(
+  value: MaterialAsset,
+  refs: readonly string[],
+  guid: string,
+): ReturnType<typeof ok<MaterialAsset>> | ReturnType<typeof err<AssetLoadError>> {
+  if (refs.length === 0) return ok(value);
+
+  let changed = false;
+  let parent = value.parent;
+  if (typeof parent === 'number') {
+    const resolved = resolveMaterialWireRef(parent, refs, 'parent', guid);
+    if (!resolved.ok) return resolved;
+    parent = resolved.value as unknown as MaterialAsset['parent'];
+    changed = true;
+  }
+
+  if (value.values === undefined) {
+    return changed ? ok({ ...value, ...(parent === undefined ? {} : { parent }) }) : ok(value);
+  }
+
+  const textureFields = new Set(
+    value.parameters === undefined
+      ? MATERIAL_TEXTURE_SLOTS
+      : value.parameters
+          .filter((parameter) => parameter.type === 'texture')
+          .map((parameter) => parameter.name),
+  );
+  const values = { ...value.values };
+  for (const [field, raw] of Object.entries(values)) {
+    if (typeof raw === 'number' && textureFields.has(field)) {
+      const resolved = resolveMaterialWireRef(raw, refs, field, guid);
+      if (!resolved.ok) return resolved;
+      values[field] = resolved.value as NonNullable<MaterialAsset['values']>[string];
+      changed = true;
+      continue;
+    }
+    if (!record(raw)) continue;
+    const rawRecord = raw as unknown as Record<string, unknown>;
+    let rewritten: Record<string, unknown> | undefined;
+    for (const key of ['texture', 'sampler'] as const) {
+      if (!(key in rawRecord)) continue;
+      const resolved = resolveMaterialWireRef(rawRecord[key], refs, `${field}.${key}`, guid);
+      if (!resolved.ok) return resolved;
+      if (resolved.value !== rawRecord[key]) {
+        rewritten ??= { ...rawRecord };
+        rewritten[key] = resolved.value;
+        changed = true;
+      }
+    }
+    if (rewritten !== undefined) {
+      values[field] = rewritten as unknown as NonNullable<MaterialAsset['values']>[string];
+    }
+  }
+  return ok(changed ? { ...value, ...(parent === undefined ? {} : { parent }), values } : value);
+}
+
+export const materialContribution: AssetDecoderContribution<MaterialAsset, 'material'> = {
+  kind: { kind: 'material' } as AssetKind<MaterialAsset, 'material'>,
+  consumer: 'Render MaterialScene',
+  decoder: {
+    async decode({ envelope }) {
+      if (!validMaterial(envelope.payload)) {
+        return invalid(
+          envelope.guid,
+          'a material payload with cooked passes, parameters, and values',
+          'material owner validation failed',
+        );
+      }
+      return resolveMaterialWireRefs(envelope.payload, envelope.refs, envelope.guid);
+    },
+  },
+};
+
+export const samplerContribution: AssetDecoderContribution<SamplerAsset, 'sampler'> = {
+  kind: { kind: 'sampler' } as AssetKind<SamplerAsset, 'sampler'>,
+  consumer: 'Render DeviceScope',
+  decoder: {
+    async decode({ envelope }) {
+      return envelope.payload.kind === 'sampler'
+        ? ok(envelope.payload)
+        : invalid(envelope.guid, 'a sampler payload', 'sampler owner validation failed');
+    },
+  },
+};
+
+export const renderPipelineContribution: AssetDecoderContribution<
+  RenderPipelineAsset,
+  'render-pipeline'
+> = {
+  kind: { kind: 'render-pipeline' } as AssetKind<RenderPipelineAsset, 'render-pipeline'>,
+  consumer: 'Render Pipeline',
+  decoder: {
+    async decode({ envelope }) {
+      const payload = envelope.payload;
+      return payload.kind === 'render-pipeline' && payload.pipelineId.trim().length > 0
+        ? ok(payload)
+        : invalid(
+            envelope.guid,
+            'a render-pipeline payload with a pipelineId',
+            'render-pipeline owner validation failed',
+          );
+    },
+  },
+};

package/src/assets/render-asset-port.ts

@@ -0,0 +1,44 @@
+import type { ShaderRegistry } from '@forgeax/engine-shader';
+import type { Asset } from '@forgeax/engine-types';
+
+/** Render-only projection supplied by the owner of decoded asset payloads. */
+export interface RenderAssetResolver {
+  readonly epoch: number;
+  lookup<T extends Asset>(guid: string): T | undefined;
+  guidOf(asset: Asset): string | undefined;
+}
+
+export interface RenderAssetPort {
+  readonly epoch: number;
+  readonly shaderRegistry: ShaderRegistry;
+  lookup<T extends Asset>(guid: string): T | undefined;
+  guidOf(asset: Asset): string | undefined;
+  materialShaderTextureFieldNames(shaderId: string): readonly string[];
+}
+
+export function createRenderAssetPort(
+  shaderRegistry: ShaderRegistry,
+  resolver: RenderAssetResolver = emptyResolver,
+): RenderAssetPort {
+  return {
+    get epoch() {
+      return resolver.epoch;
+    },
+    shaderRegistry,
+    lookup: <T extends Asset>(guid: string) => resolver.lookup<T>(guid),
+    guidOf: (asset: Asset) => resolver.guidOf(asset),
+    materialShaderTextureFieldNames(shaderId: string): readonly string[] {
+      const artifact = shaderRegistry.findMaterialArtifact(shaderId);
+      if (!artifact.ok) return [];
+      return artifact.value.paramSchema
+        .filter((parameter) => parameter.type === 'texture2d')
+        .map((parameter) => parameter.name);
+    },
+  };
+}
+
+const emptyResolver: RenderAssetResolver = Object.freeze({
+  epoch: 0,
+  lookup: () => undefined,
+  guidOf: () => undefined,
+});

package/src/assets/resolve-render-asset.ts

@@ -0,0 +1,13 @@
+import type { World } from '@forgeax/engine-ecs';
+import type { Asset, Handle, Result } from '@forgeax/engine-types';
+
+export type RenderAssetResolutionError =
+  ReturnType<World['sharedRefs']['resolve']> extends Result<unknown, infer E> ? E : never;
+
+/** Resolve a render handle through the World that owns its shared-reference lifetime. */
+export function resolveRenderAsset<T extends Asset>(
+  world: World,
+  handle: Handle<string, 'shared'>,
+): Result<T, RenderAssetResolutionError> {
+  return world.sharedRefs.resolve<string, T>(handle) as Result<T, RenderAssetResolutionError>;
+}

package/src/authoring.ts

@@ -0,0 +1,24 @@
+// Optional authoring features intentionally live outside the base render vocabulary.
+export * from './components/glyph-text';
+export * from './components/sprite-animation';
+export * from './components/sprite-instances';
+export * from './components/sprite-playback-mode';
+export * from './components/sprite-region-override';
+export * from './components/tile-layer';
+export * from './components/tilemap';
+export { glyphTextLayoutSystem, resetGlyphBakeCache } from './glyph-text-layout-system';
+export {
+  Materials,
+  materialTextureValue,
+  SPRITE_PREMULTIPLIED_ALPHA_BLEND,
+} from './materials';
+export {
+  getTransparentSortConfig,
+  setTransparentSortConfig,
+  TRANSPARENT_SORT_MODE_DISTANCE,
+  TRANSPARENT_SORT_MODE_LAYER_Y,
+  TRANSPARENT_SORT_MODE_LAYER_YZ,
+  TRANSPARENT_SORT_MODE_LAYER_Z,
+  type TransparentSortConfig,
+} from './systems/transparent-sort-config';
+export { tilemapChunkExtractSystem } from './tilemap-chunk-extract-system';