@forgeax/engine-scene 0.1.4 → 0.1.7

package/src/assets/scene-projection.ts

@@ -1,644 +0,0 @@
-import type { World } from '@forgeax/engine-ecs';
-import { componentSchema } from '@forgeax/engine-ecs/internal';
-import { AssetGuid } from '@forgeax/engine-pack/guid';
-import {
-  type BuiltinAssetKind,
-  type ComponentValuesMap,
-  err,
-  type Handle,
-  type MeshAsset,
-  type MountOverride,
-  ok,
-  type Result,
-  type SceneAsset,
-  type SceneEntity,
-  type SceneInstanceMount,
-  type SkinAsset,
-  toShared,
-} from '@forgeax/engine-types';
-import { worldSetSceneAssetResolver } from '../instances/scene-instances';
-import { sceneAssetWireRefs } from './scene-decoder';
-
-/** World resource key for the scene projection's skin dependency view. */
-export const SCENE_ASSET_SKIN_RESOLVER_RESOURCE_KEY = 'SceneAssetSkinResolver';
-
-/** World resource key for mesh-owned material default resolution. */
-export const SCENE_ASSET_MESH_DEFAULT_RESOLVER_RESOURCE_KEY = 'SceneAssetMeshDefaultResolver';
-
-/**
- * Scene projection output consumed by the renderer's post-instantiate hook.
- * Scene owns the GUID-to-payload dependency view; ECS and Render only depend
- * on this narrow resolver shape.
- */
-export interface SceneAssetSkinResolver {
-  resolveSkinAsset(skeletonHandle: number): SkinAsset | undefined;
-}
-
-/**
- * Render-facing view of material defaults loaded while projecting a scene.
- * MeshAsset keeps these defaults as GUID facts; Render consumes World handles
- * without importing the AssetRegistry or teaching the scene component about
- * renderer policy.
- */
-export interface SceneAssetMeshDefaultResolver {
-  resolveMeshDefaultMaterial(guid: string): number | undefined;
-}
-
-/** Errors raised while projecting a decoded SceneAsset into one World. */
-export type SceneAssetProjectionError =
-  | {
-      readonly code: 'scene-reference-target-unsupported';
-      readonly expected: string;
-      readonly hint: string;
-      readonly detail: { readonly guid: string; readonly target: string; readonly field: string };
-    }
-  | {
-      readonly code: 'scene-reference-kind-mismatch';
-      readonly expected: string;
-      readonly hint: string;
-      readonly detail: {
-        readonly guid: string;
-        readonly target: string;
-        readonly expectedKind: BuiltinAssetKind;
-        readonly actualKind: string;
-        readonly field: string;
-      };
-    }
-  | {
-      readonly code: 'scene-reference-cycle';
-      readonly expected: string;
-      readonly hint: string;
-      readonly detail: { readonly cycle: readonly string[] };
-    }
-  | {
-      readonly code: 'scene-reference-unresolved';
-      readonly expected: string;
-      readonly hint: string;
-      readonly detail: { readonly source: string };
-    };
-
-/** Loader seam supplied by the current App-owned AssetRegistry. */
-export type SceneAssetReferenceLoader<E = unknown> = (
-  guid: string,
-  kind: BuiltinAssetKind,
-) => Promise<Result<unknown, E>>;
-
-const ASSET_KIND_BY_TARGET: Readonly<Record<string, BuiltinAssetKind>> = Object.freeze({
-  MeshAsset: 'mesh',
-  TextureAsset: 'texture',
-  EquirectAsset: 'equirect',
-  SamplerAsset: 'sampler',
-  MaterialAsset: 'material',
-  SceneAsset: 'scene',
-  AudioClipAsset: 'audio',
-  SkinAsset: 'skin',
-  SkeletonAsset: 'skeleton',
-  AnimationClip: 'animation-clip',
-  AnimationGraph: 'animation-graph',
-  FontAsset: 'font',
-  RenderPipelineAsset: 'render-pipeline',
-  TilesetAsset: 'tileset',
-  VideoAsset: 'video',
-  ParticleEffectAsset: 'particle-effect',
-});
-
-type ProjectError<E> = E | SceneAssetProjectionError;
-
-interface ProjectionState<E> {
-  readonly world: World;
-  readonly load: SceneAssetReferenceLoader<E>;
-  readonly assetHandles: Map<string, Handle<string, 'shared'>>;
-  readonly sceneHandles: Map<string, Handle<'SceneAsset', 'shared'>>;
-  readonly skinStore: SceneAssetProjectionStore;
-}
-
-interface SceneAssetProjectionStore {
-  readonly skeletonGuidByHandle: Map<number, string>;
-  readonly skinByGuid: Map<string, SkinAsset>;
-  readonly skinBySkeletonGuid: Map<string, SkinAsset>;
-  readonly resolver: SceneAssetSkinResolver;
-  readonly materialHandleByGuid: Map<string, number>;
-  readonly meshDefaultResolver: SceneAssetMeshDefaultResolver;
-}
-
-const projectionStores = new WeakMap<World, SceneAssetProjectionStore>();
-
-function projectionStoreFor(world: World): SceneAssetProjectionStore {
-  const current = projectionStores.get(world);
-  if (current !== undefined) return current;
-
-  const skeletonGuidByHandle = new Map<number, string>();
-  const skinByGuid = new Map<string, SkinAsset>();
-  const skinBySkeletonGuid = new Map<string, SkinAsset>();
-  const materialHandleByGuid = new Map<string, number>();
-  const resolver: SceneAssetSkinResolver = {
-    resolveSkinAsset(skeletonHandle) {
-      const skeletonGuid = skeletonGuidByHandle.get(skeletonHandle);
-      return skeletonGuid === undefined ? undefined : skinBySkeletonGuid.get(skeletonGuid);
-    },
-  };
-  const meshDefaultResolver: SceneAssetMeshDefaultResolver = {
-    resolveMeshDefaultMaterial(guid) {
-      return materialHandleByGuid.get(guid.toLowerCase());
-    },
-  };
-  const store = {
-    skeletonGuidByHandle,
-    skinByGuid,
-    skinBySkeletonGuid,
-    resolver,
-    materialHandleByGuid,
-    meshDefaultResolver,
-  };
-  projectionStores.set(world, store);
-  world.insertResource(SCENE_ASSET_SKIN_RESOLVER_RESOURCE_KEY, resolver);
-  world.insertResource(SCENE_ASSET_MESH_DEFAULT_RESOLVER_RESOURCE_KEY, meshDefaultResolver);
-  return store;
-}
-
-function projectionError(
-  code: SceneAssetProjectionError['code'],
-  detail: SceneAssetProjectionError['detail'],
-): SceneAssetProjectionError {
-  switch (code) {
-    case 'scene-reference-target-unsupported':
-      return {
-        code,
-        expected: 'every shared SceneAsset field target maps to a built-in Asset kind',
-        hint: 'register the target in the AssetTagMap before projecting the scene',
-        detail: detail as Extract<SceneAssetProjectionError, { code: typeof code }>['detail'],
-      };
-    case 'scene-reference-kind-mismatch':
-      return {
-        code,
-        expected: 'the loaded payload kind matches the component shared-handle target',
-        hint: 'repair the scene refs[] edge or republish the referenced asset',
-        detail: detail as Extract<SceneAssetProjectionError, { code: typeof code }>['detail'],
-      };
-    case 'scene-reference-cycle':
-      return {
-        code,
-        expected: 'an acyclic SceneAsset mount graph',
-        hint: 'remove the circular mount.source reference and republish the scenes',
-        detail: detail as Extract<SceneAssetProjectionError, { code: typeof code }>['detail'],
-      };
-    case 'scene-reference-unresolved':
-      return {
-        code,
-        expected: 'a mount.source GUID that is loadable by the current AssetRegistry',
-        hint: 'publish the child SceneAsset before projecting its parent',
-        detail: detail as Extract<SceneAssetProjectionError, { code: typeof code }>['detail'],
-      };
-  }
-}
-
-function isPayloadOfKind(
-  value: unknown,
-  kind: BuiltinAssetKind,
-): value is { readonly kind: string } {
-  return (
-    typeof value === 'object' &&
-    value !== null &&
-    (value as { readonly kind?: unknown }).kind === kind
-  );
-}
-
-function sharedTarget(fieldType: unknown): string | undefined {
-  if (typeof fieldType !== 'string') return undefined;
-  const match = /^shared<([^>]+)>$/.exec(fieldType);
-  return match?.[1];
-}
-
-function schemaFieldType(field: unknown): unknown {
-  if (typeof field === 'object' && field !== null && 'type' in field) {
-    return (field as { readonly type?: unknown }).type;
-  }
-  return field;
-}
-
-function sharedArrayTarget(fieldType: unknown): string | undefined {
-  if (typeof fieldType !== 'string') return undefined;
-  const match = /^array<shared<([^>]+)>(?:,\s*\d+)? *>$/.exec(fieldType);
-  return match?.[1];
-}
-
-function resolveWireValue<E>(
-  value: unknown,
-  refs: readonly string[] | undefined,
-  location: string,
-): Result<unknown, ProjectError<E>> {
-  if (refs === undefined || typeof value !== 'number') return ok(value);
-  const guid = refs[value];
-  if (!Number.isInteger(value) || guid === undefined) {
-    return err(
-      projectionError('scene-reference-unresolved', {
-        source: `${location} refs[${value}]`,
-      }),
-    );
-  }
-  return ok(guid);
-}
-
-async function projectSharedValue<E>(
-  state: ProjectionState<E>,
-  value: unknown,
-  target: string,
-  field: string,
-): Promise<Result<unknown, ProjectError<E>>> {
-  if (typeof value !== 'string') {
-    if (target === 'MeshAsset' && typeof value === 'number') {
-      const resolved = state.world.sharedRefs.resolve(toShared<'MeshAsset'>(value));
-      if (resolved.ok && isPayloadOfKind(resolved.value, 'mesh')) {
-        const meshDefaults = await projectMeshDefaults(state, resolved.value as MeshAsset, field);
-        if (!meshDefaults.ok) return meshDefaults;
-      }
-    }
-    return ok(value);
-  }
-  const kind = ASSET_KIND_BY_TARGET[target];
-  if (kind === undefined) {
-    return err(
-      projectionError('scene-reference-target-unsupported', {
-        guid: value,
-        target,
-        field,
-      }),
-    );
-  }
-
-  const cacheKey = `${target}:${value.toLowerCase()}`;
-  const cached = state.assetHandles.get(cacheKey);
-  if (cached !== undefined) {
-    if (target === 'SkeletonAsset') {
-      state.skinStore.skeletonGuidByHandle.set(Number(cached), value.toLowerCase());
-    }
-    return ok(cached);
-  }
-
-  const loaded = await state.load(value, kind);
-  if (!loaded.ok) return loaded;
-  if (!isPayloadOfKind(loaded.value, kind)) {
-    return err(
-      projectionError('scene-reference-kind-mismatch', {
-        guid: value,
-        target,
-        expectedKind: kind,
-        actualKind:
-          typeof loaded.value === 'object' && loaded.value !== null && 'kind' in loaded.value
-            ? String((loaded.value as { readonly kind: unknown }).kind)
-            : typeof loaded.value,
-        field,
-      }),
-    );
-  }
-
-  if (target === 'MeshAsset') {
-    const meshDefaults = await projectMeshDefaults(state, loaded.value as MeshAsset, field);
-    if (!meshDefaults.ok) return meshDefaults;
-  }
-
-  const handle = state.world.allocSharedRef(target, loaded.value);
-  state.assetHandles.set(cacheKey, handle);
-  if (target === 'SkeletonAsset') {
-    state.skinStore.skeletonGuidByHandle.set(Number(handle), value.toLowerCase());
-  }
-  return ok(handle);
-}
-
-async function projectMeshDefaults<E>(
-  state: ProjectionState<E>,
-  mesh: MeshAsset,
-  field: string,
-): Promise<Result<void, ProjectError<E>>> {
-  if (!Array.isArray(mesh.materialSlots)) return ok(undefined);
-  for (let slotIndex = 0; slotIndex < mesh.materialSlots.length; slotIndex += 1) {
-    const defaultMaterial = mesh.materialSlots[slotIndex]?.defaultMaterial;
-    if (defaultMaterial === undefined) continue;
-    const guid = AssetGuid.format(defaultMaterial);
-    const projected = await projectSharedValue(
-      state,
-      guid,
-      'MaterialAsset',
-      `${field}.materialSlots[${slotIndex}].defaultMaterial`,
-    );
-    if (!projected.ok) return projected;
-    state.skinStore.materialHandleByGuid.set(guid, Number(projected.value));
-  }
-  return ok(undefined);
-}
-
-async function projectSkinDependencies<E>(
-  state: ProjectionState<E>,
-  asset: SceneAsset,
-): Promise<Result<void, ProjectError<E>>> {
-  for (let index = 0; index < (asset.skinGuids?.length ?? 0); index += 1) {
-    const guid = asset.skinGuids?.[index];
-    if (guid === undefined) continue;
-    const guidKey = guid.toLowerCase();
-    if (state.skinStore.skinByGuid.has(guidKey)) continue;
-
-    const loaded = await state.load(guid, 'skin');
-    if (!loaded.ok) return loaded;
-    if (!isPayloadOfKind(loaded.value, 'skin')) {
-      return err(
-        projectionError('scene-reference-kind-mismatch', {
-          guid,
-          target: 'SkinAsset',
-          expectedKind: 'skin',
-          actualKind:
-            typeof loaded.value === 'object' && loaded.value !== null && 'kind' in loaded.value
-              ? String((loaded.value as { readonly kind: unknown }).kind)
-              : typeof loaded.value,
-          field: `scene.skinGuids[${index}]`,
-        }),
-      );
-    }
-    const skin = loaded.value as SkinAsset;
-    state.skinStore.skinByGuid.set(guidKey, skin);
-    state.skinStore.skinBySkeletonGuid.set(skin.skeletonGuid.toLowerCase(), skin);
-  }
-  return ok(undefined);
-}
-
-async function projectFields<E>(
-  state: ProjectionState<E>,
-  componentName: string,
-  rawFields: Record<string, unknown>,
-  location: string,
-  wireRefs: readonly string[] | undefined,
-): Promise<Result<Record<string, unknown>, ProjectError<E>>> {
-  const component = state.world.components.resolve(componentName);
-  if (component === undefined) return ok({ ...rawFields });
-
-  const fields: Record<string, unknown> = { ...rawFields };
-  for (const [fieldName, value] of Object.entries(rawFields)) {
-    const fieldType = schemaFieldType(componentSchema(component)[fieldName]);
-    const target = sharedTarget(fieldType);
-    if (target !== undefined) {
-      const wireValue = await resolveWireValue<E>(
-        value,
-        wireRefs,
-        `${location}.${componentName}.${fieldName}`,
-      );
-      if (!wireValue.ok) return wireValue;
-      const projected = await projectSharedValue(
-        state,
-        wireValue.value,
-        target,
-        `${location}.${componentName}.${fieldName}`,
-      );
-      if (!projected.ok) return projected;
-      fields[fieldName] = projected.value;
-      continue;
-    }
-
-    const arrayTarget = sharedArrayTarget(fieldType);
-    if (arrayTarget === undefined || !Array.isArray(value)) continue;
-    const projectedValues: unknown[] = [];
-    for (let index = 0; index < value.length; index += 1) {
-      const wireValue = await resolveWireValue<E>(
-        value[index],
-        wireRefs,
-        `${location}.${componentName}.${fieldName}[${index}]`,
-      );
-      if (!wireValue.ok) return wireValue;
-      const projected = await projectSharedValue(
-        state,
-        wireValue.value,
-        arrayTarget,
-        `${location}.${componentName}.${fieldName}[${index}]`,
-      );
-      if (!projected.ok) return projected;
-      projectedValues.push(projected.value);
-    }
-    fields[fieldName] = projectedValues;
-  }
-  return ok(fields);
-}
-
-async function projectComponents<E>(
-  state: ProjectionState<E>,
-  components: Partial<ComponentValuesMap>,
-  location: string,
-  wireRefs: readonly string[] | undefined,
-): Promise<Result<Partial<ComponentValuesMap>, ProjectError<E>>> {
-  const projected: Record<string, Record<string, unknown>> = {};
-  for (const [componentName, rawFields] of Object.entries(components)) {
-    if (typeof rawFields !== 'object' || rawFields === null || Array.isArray(rawFields)) continue;
-    const fields = await projectFields(
-      state,
-      componentName,
-      rawFields as Record<string, unknown>,
-      location,
-      wireRefs,
-    );
-    if (!fields.ok) return fields;
-    projected[componentName] = fields.value;
-  }
-  return ok(projected);
-}
-
-async function projectOverride<E>(
-  state: ProjectionState<E>,
-  override: MountOverride,
-  index: number,
-  wireRefs: readonly string[] | undefined,
-): Promise<Result<MountOverride, ProjectError<E>>> {
-  const component = state.world.components.resolve(override.comp);
-  if (component === undefined) return ok(override);
-
-  if (override.field !== undefined) {
-    const fieldType = schemaFieldType(componentSchema(component)[override.field]);
-    const target = sharedTarget(fieldType);
-    if (target !== undefined) {
-      const wireValue = await resolveWireValue<E>(
-        override.value,
-        wireRefs,
-        `mount override ${index}.${override.comp}.${override.field}`,
-      );
-      if (!wireValue.ok) return wireValue;
-      const value = await projectSharedValue(
-        state,
-        wireValue.value,
-        target,
-        `mount override ${index}.${override.comp}.${override.field}`,
-      );
-      if (!value.ok) return value;
-      return ok({ ...override, value: value.value });
-    }
-    const arrayTarget = sharedArrayTarget(fieldType);
-    if (arrayTarget !== undefined && Array.isArray(override.value)) {
-      const values: unknown[] = [];
-      for (let element = 0; element < override.value.length; element += 1) {
-        const wireValue = await resolveWireValue<E>(
-          override.value[element],
-          wireRefs,
-          `mount override ${index}.${override.comp}.${override.field}[${element}]`,
-        );
-        if (!wireValue.ok) return wireValue;
-        const value = await projectSharedValue(
-          state,
-          wireValue.value,
-          arrayTarget,
-          `mount override ${index}.${override.comp}.${override.field}[${element}]`,
-        );
-        if (!value.ok) return value;
-        values.push(value.value);
-      }
-      return ok({ ...override, value: values });
-    }
-    return ok(override);
-  }
-
-  if (
-    typeof override.value !== 'object' ||
-    override.value === null ||
-    Array.isArray(override.value)
-  ) {
-    return ok(override);
-  }
-  const value = await projectFields(
-    state,
-    override.comp,
-    override.value as Record<string, unknown>,
-    `mount override ${index}`,
-    wireRefs,
-  );
-  if (!value.ok) return value;
-  return ok({ ...override, value: value.value });
-}
-
-async function projectMount<E>(
-  state: ProjectionState<E>,
-  mount: SceneInstanceMount,
-  index: number,
-  visiting: Set<string>,
-  wireRefs: readonly string[] | undefined,
-): Promise<Result<SceneInstanceMount, ProjectError<E>>> {
-  const components =
-    mount.components === undefined
-      ? undefined
-      : await projectComponents(state, mount.components, `mount ${index}`, wireRefs);
-  if (components !== undefined && !components.ok) return components;
-
-  const overrides: MountOverride[] = [];
-  for (let overrideIndex = 0; overrideIndex < (mount.overrides?.length ?? 0); overrideIndex += 1) {
-    const override = mount.overrides?.[overrideIndex];
-    if (override === undefined) continue;
-    const projected = await projectOverride(state, override, overrideIndex, wireRefs);
-    if (!projected.ok) return projected;
-    overrides.push(projected.value);
-  }
-
-  if (typeof mount.source !== 'string') {
-    return ok({
-      ...mount,
-      ...(components === undefined ? {} : { components: components.value }),
-      ...(mount.overrides === undefined ? {} : { overrides }),
-    });
-  }
-
-  const sourceKey = mount.source.toLowerCase();
-  const cached = state.sceneHandles.get(sourceKey);
-  if (cached !== undefined) {
-    return ok({
-      ...mount,
-      source: cached as unknown as number,
-      ...(components === undefined ? {} : { components: components.value }),
-      ...(mount.overrides === undefined ? {} : { overrides }),
-    });
-  }
-  if (visiting.has(sourceKey)) {
-    return err(
-      projectionError('scene-reference-cycle', {
-        cycle: [...visiting, sourceKey],
-      }),
-    );
-  }
-
-  const loaded = await state.load(mount.source, 'scene');
-  if (!loaded.ok) return loaded;
-  if (!isPayloadOfKind(loaded.value, 'scene')) {
-    return err(projectionError('scene-reference-unresolved', { source: mount.source }));
-  }
-
-  visiting.add(sourceKey);
-  const projectedChild = await projectScene(state, loaded.value as SceneAsset, visiting);
-  visiting.delete(sourceKey);
-  if (!projectedChild.ok) return projectedChild;
-
-  const childHandle = state.world.allocSharedRef('SceneAsset', projectedChild.value);
-  state.sceneHandles.set(sourceKey, childHandle);
-  return ok({
-    ...mount,
-    source: childHandle as unknown as number,
-    ...(components === undefined ? {} : { components: components.value }),
-    ...(mount.overrides === undefined ? {} : { overrides }),
-  });
-}
-
-async function projectScene<E>(
-  state: ProjectionState<E>,
-  asset: SceneAsset,
-  visiting: Set<string>,
-): Promise<Result<SceneAsset, ProjectError<E>>> {
-  const skins = await projectSkinDependencies(state, asset);
-  if (!skins.ok) return skins;
-
-  const entities: SceneEntity[] = [];
-  const wireRefs = sceneAssetWireRefs(asset);
-  for (const entity of asset.entities) {
-    const components = await projectComponents(
-      state,
-      entity.components,
-      `entity ${entity.localId as number}`,
-      wireRefs,
-    );
-    if (!components.ok) return components;
-    entities.push({ localId: entity.localId, components: components.value });
-  }
-
-  const mounts: SceneInstanceMount[] = [];
-  for (let index = 0; index < (asset.mounts?.length ?? 0); index += 1) {
-    const mount = asset.mounts?.[index];
-    if (mount === undefined) continue;
-    const projected = await projectMount(state, mount, index, visiting, wireRefs);
-    if (!projected.ok) return projected;
-    mounts.push(projected.value);
-  }
-
-  return ok({
-    kind: 'scene',
-    entities,
-    ...(asset.mounts === undefined ? {} : { mounts }),
-    ...(asset.skinGuids === undefined ? {} : { skinGuids: [...asset.skinGuids] }),
-  });
-}
-
-/**
- * Convert decoded GUID fields and nested SceneAsset mounts into references
- * owned by one World. The AssetRegistry remains a loader; this World-facing
- * projection belongs to Scene and is intentionally explicit at each consumer.
- */
-export async function projectSceneAsset<E = unknown>(
-  world: World,
-  asset: SceneAsset,
-  load: SceneAssetReferenceLoader<E>,
-): Promise<Result<SceneAsset, ProjectError<E>>> {
-  const skinStore = projectionStoreFor(world);
-  worldSetSceneAssetResolver(world, (source) => {
-    if (typeof source === 'number') return ok(toShared<'SceneAsset'>(source));
-    return err(projectionError('scene-reference-unresolved', { source }));
-  });
-  return projectScene(
-    {
-      world,
-      load,
-      assetHandles: new Map(),
-      sceneHandles: new Map(),
-      skinStore,
-    },
-    asset,
-    new Set(),
-  );
-}