@forgeax/engine-import 0.0.0-dev.8d955ade1c79

package/src/__tests__/mesh-bin.test.ts

@@ -0,0 +1,102 @@
+import { packMeshBinV4 } from '@forgeax/engine-import';
+import { decodeMeshBinHeader } from '@forgeax/engine-pack';
+import { AssetGuid } from '@forgeax/engine-pack/guid';
+import { describe, expect, it } from 'vitest';
+
+function buildPayload(vertexCount: number, extraUvCount: number, hasSkin: boolean) {
+  const baseFpv = hasSkin ? 18 : 12;
+  const fpv = baseFpv + extraUvCount * 2;
+  const vertices = new Float32Array(vertexCount * fpv);
+  for (let i = 0; i < vertices.length; i++) vertices[i] = i * 0.1;
+  const attributes: Record<string, unknown> = {
+    position: new Float32Array(vertexCount * 3),
+    normal: new Float32Array(vertexCount * 3),
+    uv: new Float32Array(vertexCount * 2),
+    tangent: new Float32Array(vertexCount * 4),
+  };
+  for (let set = 1; set <= extraUvCount; set++) {
+    attributes[`uv${set}`] = new Float32Array(vertexCount * 2);
+  }
+  if (hasSkin) {
+    attributes.skinIndex = new Uint16Array(vertexCount * 4);
+    attributes.skinWeight = new Float32Array(vertexCount * 4);
+  }
+  return { vertices, indices: new Uint16Array([0, 1, 2]), attributes };
+}
+
+describe('mesh-bin v4 roundtrip contract', () => {
+  it.each([
+    [0, false, 1],
+    [1, false, 2],
+    [2, false, 3],
+    [7, false, 8],
+    [1, true, 2],
+  ])('records canonical projection for %i extra UV sets and skin=%s', (extra, skin, uvSets) => {
+    const result = packMeshBinV4(buildPayload(4, extra, skin), `gltf://mesh/${extra}/${skin}`);
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    const header = decodeMeshBinHeader(result.value, `gltf://mesh/${extra}/${skin}`);
+    expect(header.ok).toBe(true);
+    if (!header.ok) return;
+    expect(header.value.version).toBe(4);
+    expect(header.value.projectionVersion).toBe(1);
+    expect(header.value.vertexCount).toBe(4);
+    expect(header.value.stride).toBe((skin ? 18 + extra * 2 : 12 + extra * 2) * 4);
+    expect(header.value.mask).toBeGreaterThan(0);
+    expect(uvSets).toBeGreaterThan(0);
+  });
+
+  it('stores canonical interleaved bytes and material refs as indexes', () => {
+    const guid = '019d0000-0000-7000-8000-000000000005';
+    const parsed = AssetGuid.parse(guid);
+    if (!parsed.ok) throw new Error('fixture guid must parse');
+    const payload = {
+      vertices: new Float32Array([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]),
+      indices: new Uint16Array([0, 1, 2]),
+      attributes: {
+        position: new Float32Array([1, 2, 3]),
+        normal: new Float32Array([4, 5, 6]),
+        uv: new Float32Array([7, 8]),
+        tangent: new Float32Array([9, 10, 11, 12]),
+      },
+      submeshes: [
+        {
+          indexOffset: 0,
+          indexCount: 3,
+          vertexCount: 1,
+          topology: 'triangle-list' as const,
+          materialSlot: 0,
+        },
+      ],
+      materialSlots: [
+        { slotName: 'Body', sourceKey: 'gltf:material:0', defaultMaterial: parsed.value },
+      ],
+    };
+    const result = packMeshBinV4(payload, 'gltf://color', [guid]);
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    const header = decodeMeshBinHeader(result.value, 'gltf://color');
+    expect(header.ok).toBe(true);
+    if (!header.ok) return;
+    const jsonOffset = 80 + header.value.vertexBytes + header.value.indexBytes;
+    const json = new TextDecoder().decode(
+      result.value.subarray(jsonOffset, jsonOffset + header.value.jsonBytes),
+    );
+    expect(JSON.parse(json).materialSlots).toEqual([
+      { slotName: 'Body', sourceKey: 'gltf:material:0', defaultMaterialRef: 0 },
+    ]);
+    expect(json).not.toContain(guid);
+    expect(Array.from(result.value.subarray(80, 80 + payload.vertices.byteLength))).toEqual(
+      Array.from(new Uint8Array(payload.vertices.buffer)),
+    );
+  });
+
+  it('returns a closed error without bytes for invalid stride cardinality', () => {
+    const payload = buildPayload(2, 0, false);
+    const result = packMeshBinV4({ ...payload, vertexCount: 3 }, 'gltf://invalid');
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error.sourceKey).toBe('gltf://invalid');
+    expect(result.error.recovery).toContain('re-cook');
+  });
+});

package/src/__tests__/owner-chain.integration.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from 'vitest';
+import { createImportProduct } from '../import-product.js';
+
+describe('Import owner chain', () => {
+  it('hands one complete terminal product to the next owner', () => {
+    const result = createImportProduct({
+      assets: [
+        {
+          guid: '019e3969-1d48-7c3b-ac24-6d68f457065f',
+          kind: 'texture',
+          payload: { kind: 'texture' },
+          refs: [],
+          artifacts: {},
+        },
+      ],
+      sourceDependencies: ['hero.png'],
+      refs: [],
+      artifacts: {},
+      receipts: [],
+      diagnostics: [],
+      sourceRevision: 'sha256:hero',
+      sourceKey: 'hero/albedo',
+    });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value).toMatchObject({
+        sourceRevision: 'sha256:hero',
+        sourceKey: 'hero/albedo',
+        refs: [],
+        artifacts: {},
+        receipts: [],
+        diagnostics: [],
+      });
+    }
+  });
+});

package/src/__tests__/scriptable-pack-host.unit.test.ts

@@ -0,0 +1,86 @@
+import { AssetGuid } from '@forgeax/engine-pack/guid';
+import type { ScanSourceDeclaration } from '@forgeax/engine-pack/scanner';
+import type {
+  Asset,
+  AssetGuid as AssetGuidType,
+  ImportContext,
+  Importer,
+} from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { ImporterRegistry } from '../importer-registry.js';
+import { declaredPackExternalOutputs } from '../scriptable-pack-host.js';
+
+const GUID = '019ffa97-0000-7000-8000-000000000001';
+
+function parseGuid(value: string): AssetGuidType {
+  const parsed = AssetGuid.parse(value);
+  if (!parsed.ok) throw parsed.error;
+  return parsed.value;
+}
+
+describe('ScriptablePack external Meta staging', () => {
+  it('imports ordinary Meta dependencies into the current staged generation', async () => {
+    const importer: Importer = {
+      key: 'fixture',
+      import: async (ctx: ImportContext) => ({
+        ok: true,
+        value: {
+          assets: [
+            {
+              guid: ctx.subAssets[0]?.guid ?? GUID,
+              kind: 'mesh',
+              payload: {
+                kind: 'mesh',
+                vertices: new Float32Array([0, 1, 2]),
+                attributes: {},
+                submeshes: [],
+                materialSlots: [],
+              } satisfies Asset,
+              refs: [],
+              artifacts: {},
+            },
+          ],
+          sourceDependencies: [],
+        },
+      }),
+    };
+    const registry = new ImporterRegistry();
+    registry.register(importer);
+    const declaration = {
+      format: 'meta.json',
+      sourcePath: '/project/assets/model.bin.meta.json',
+      sourceRevision: 'sha256:meta',
+      value: {
+        schemaVersion: '1.0.0',
+        kind: 'external-asset-package',
+        importer: 'fixture',
+        source: 'model.bin',
+        importSettings: {},
+        subAssets: [{ guid: GUID, sourceIndex: 0, kind: 'mesh' }],
+      },
+    } satisfies Extract<ScanSourceDeclaration, { readonly format: 'meta.json' }>;
+
+    const outputs = await declaredPackExternalOutputs(
+      new Map([[declaration.sourcePath, declaration]]),
+      [],
+      [parseGuid(GUID)],
+      {
+        importerRegistry: registry,
+        fsForImport: {
+          readSource: async () => ({ ok: true as const, value: new Uint8Array([1, 2, 3]) }),
+        },
+        assetPaths: {},
+      },
+    );
+
+    expect(outputs).toHaveLength(1);
+    const output = outputs[0];
+    expect(output).toBeDefined();
+    if (output === undefined) return;
+    expect(AssetGuid.format(output.guid)).toBe(GUID);
+    expect(output.asset).toMatchObject({ kind: 'mesh' });
+    expect(Array.from((output.asset as Asset & { vertices: Float32Array }).vertices)).toEqual([
+      0, 1, 2,
+    ]);
+  });
+});

package/src/__tests__/scriptable-pack-output-producers.unit.test.ts

@@ -0,0 +1,190 @@
+import { AssetGuid } from '@forgeax/engine-pack/guid';
+import type { AssetGuid as AssetGuidType, MaterialAsset, MeshAsset } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import {
+  materialAssetOutputProducer,
+  meshAssetOutputProducer,
+} from '../scriptable-pack-output-producers.js';
+
+function guid(value: string): AssetGuidType {
+  const parsed = AssetGuid.parse(value);
+  if (!parsed.ok) throw parsed.error;
+  return parsed.value;
+}
+
+const MATERIAL_GUID = guid('019ffa97-3000-7000-8000-000000000001');
+const PARENT_GUID = guid('019ffa97-3000-7000-8000-000000000002');
+const TEXTURE_GUID = guid('019ffa97-3000-7000-8000-000000000003');
+const SAMPLER_GUID = guid('019ffa97-3000-7000-8000-000000000004');
+
+describe('ScriptablePack standard output producers', () => {
+  it('packs generated mesh bytes and derives default-material references', async () => {
+    const mesh: MeshAsset = {
+      kind: 'mesh',
+      vertices: new Float32Array([
+        0, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 1, 1, 0, 0, 0, 1, 0, 1, 0, 1, 0, 0, 1, 0, 0, 1, 0, 1, 0, 0,
+        1, 1, 0, 0, 1,
+      ]),
+      indices: new Uint16Array([0, 1, 2]),
+      attributes: {
+        position: new Float32Array(9),
+        normal: new Float32Array(9),
+        uv: new Float32Array(6),
+        tangent: new Float32Array(12),
+      },
+      aabb: new Float32Array([0, 0, 0, 1, 0, 1]),
+      submeshes: [
+        {
+          topology: 'triangle-list',
+          indexOffset: 0,
+          indexCount: 3,
+          vertexCount: 3,
+          materialSlot: 0,
+        },
+      ],
+      materialSlots: [{ slotName: 'Shell', sourceKey: 'shell', defaultMaterial: MATERIAL_GUID }],
+    };
+
+    const result = await meshAssetOutputProducer.produce({
+      guid: '019ffa97-3000-7000-8000-000000000010',
+      sourceKey: 'geometry/shell',
+      asset: mesh,
+    });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.payload).toBe(mesh);
+    expect(result.value.refs).toEqual([
+      {
+        guid: AssetGuid.format(MATERIAL_GUID),
+        sourceField: { fieldName: 'materialSlots', arrayIndex: 0 },
+      },
+    ]);
+    expect(result.value.artifacts.body).toMatchObject({
+      mediaType: 'application/x-forgeax-mesh',
+      assetCodec: { name: 'mesh-binary', version: '4' },
+    });
+    expect(result.value.artifacts.body?.bytes.byteLength).toBeGreaterThan(28);
+  });
+
+  it('projects material GUID fields into one deterministic refs graph', async () => {
+    const material: MaterialAsset = {
+      kind: 'material',
+      parent: PARENT_GUID,
+      parameters: [{ name: 'surface', type: 'texture' }],
+      values: {
+        surface: {
+          texture: TEXTURE_GUID,
+          sampler: SAMPLER_GUID,
+          coordinates: { set: 1, transform: { scale: [2, 2] } },
+        },
+      },
+    };
+
+    const result = await materialAssetOutputProducer.produce({
+      guid: AssetGuid.format(MATERIAL_GUID),
+      sourceKey: 'material/shell',
+      asset: material,
+    });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.refs).toEqual([
+      { guid: AssetGuid.format(PARENT_GUID), sourceField: { fieldName: 'parent' } },
+      {
+        guid: AssetGuid.format(TEXTURE_GUID),
+        sourceField: { componentName: '<material>', fieldName: 'surface' },
+      },
+      {
+        guid: AssetGuid.format(SAMPLER_GUID),
+        sourceField: { componentName: '<material>', fieldName: 'surface.sampler' },
+      },
+    ]);
+    expect(result.value.payload).toEqual({
+      ...material,
+      parent: 0,
+      values: {
+        surface: {
+          texture: 1,
+          sampler: 2,
+          coordinates: { set: 1, transform: { scale: [2, 2] } },
+        },
+      },
+    });
+    expect(result.value.artifacts).toEqual({});
+  });
+
+  it('projects refs while keeping string texture authoring compact', async () => {
+    const material: MaterialAsset = {
+      kind: 'material',
+      parameters: [{ name: 'surface', type: 'texture' }],
+      values: { surface: AssetGuid.format(TEXTURE_GUID) },
+    };
+
+    const result = await materialAssetOutputProducer.produce({
+      guid: AssetGuid.format(MATERIAL_GUID),
+      sourceKey: 'material/compact-surface',
+      asset: material,
+    });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.refs).toEqual([
+      {
+        guid: AssetGuid.format(TEXTURE_GUID),
+        sourceField: { componentName: '<material>', fieldName: 'surface' },
+      },
+    ]);
+    const payload = result.value.payload as { values?: Record<string, unknown> };
+    expect(payload.values).toEqual({ surface: 0 });
+    expect(payload.values?.surface).not.toEqual({
+      texture: 0,
+      coordinates: { set: 0, transform: { offset: [0, 0], scale: [1, 1], rotation: 0 } },
+    });
+  });
+
+  it('projects a string texture shorthand as a ref when parameters are omitted', async () => {
+    const material: MaterialAsset = {
+      kind: 'material',
+      values: { baseColorTexture: AssetGuid.format(TEXTURE_GUID) },
+    };
+
+    const result = await materialAssetOutputProducer.produce({
+      guid: AssetGuid.format(MATERIAL_GUID),
+      sourceKey: 'material/compact-standard',
+      asset: material,
+    });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.refs).toEqual([
+      {
+        guid: AssetGuid.format(TEXTURE_GUID),
+        sourceField: { componentName: '<material>', fieldName: 'baseColorTexture' },
+      },
+    ]);
+    expect((result.value.payload as { values?: Record<string, unknown> }).values).toEqual({
+      baseColorTexture: 0,
+    });
+  });
+
+  it('does not misclassify an ordinary string as a texture when parameters are omitted', async () => {
+    const material: MaterialAsset = {
+      kind: 'material',
+      values: { label: 'authoring-note' },
+    };
+
+    const result = await materialAssetOutputProducer.produce({
+      guid: AssetGuid.format(MATERIAL_GUID),
+      sourceKey: 'material/compact-standard-string',
+      asset: material,
+    });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.refs).toEqual([]);
+    expect((result.value.payload as { values?: Record<string, unknown> }).values).toEqual({
+      label: 'authoring-note',
+    });
+  });
+});

package/src/__tests__/scriptable-pack-product.contract.test.ts

@@ -0,0 +1,47 @@
+import { AssetGuid } from '@forgeax/engine-pack/guid';
+import { ok } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { buildScriptablePack } from '../scriptable-pack.js';
+import { createStandardAssetOutputProducerRegistry } from '../scriptable-pack-output-producers.js';
+
+const PACKAGE_ID = AssetGuid.parse('019e3969-1d48-7c3b-ac24-6d68f457065e');
+const HERO_GUID = AssetGuid.parse('019e3969-1d48-7c3b-ac24-6d68f457065f');
+
+describe('ScriptablePack terminal product contract', () => {
+  it('keeps one complete product shape for direct and custom producer outputs', async () => {
+    const result = await buildScriptablePack({
+      definition: {
+        schemaVersion: '1.0.0',
+        packageId: PACKAGE_ID.ok ? PACKAGE_ID.value : ({} as never),
+        assets: {
+          hero: { guid: HERO_GUID.ok ? HERO_GUID.value : ({} as never), kind: 'texture' },
+        },
+        externalAssets: {},
+        build: async () =>
+          ok({
+            hero: {
+              kind: 'texture',
+              width: 1,
+              height: 1,
+              format: 'rgba8unorm',
+              data: new Uint8Array(),
+              colorSpace: 'srgb',
+              mipmap: false,
+            },
+          }),
+      },
+      sourcePath: 'hero.pack.ts',
+      outputs: createStandardAssetOutputProducerRegistry(),
+      sourceClosure: [{ path: 'hero.pack.ts', digest: 'sha256:hero' }],
+      authoringContractVersion: 'scriptable-pack-production/1',
+    });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.product).toHaveProperty('refs');
+    expect(result.value.product).toHaveProperty('artifacts');
+    expect(result.value.product).toHaveProperty('receipts');
+    expect(result.value.product).toHaveProperty('diagnostics');
+    expect(result.value.product).toHaveProperty('sourceRevision');
+  });
+});