@forgeax/engine-geometry 0.1.20 → 0.1.21

package/dist/mesh-builder.d.ts

@@ -0,0 +1,28 @@
+import { AssetError, type MeshAsset, type MeshMaterialSlot, type PrimitiveTopology, type Result, type Submesh, type VertexAttributeMap } from '@forgeax/engine-types';
+/** Input shape for one independently drawn submesh. */
+export type MeshBuilderSubmesh = Partial<Submesh> & {
+    readonly topology?: PrimitiveTopology;
+};
+/** All authoring facts accepted by {@link createMeshBuilder}. */
+export interface MeshBuilderOptions {
+    readonly attributes?: VertexAttributeMap;
+    readonly indices?: ArrayLike<number>;
+    readonly submeshes?: readonly MeshBuilderSubmesh[];
+    readonly materialSlots?: readonly MeshMaterialSlot[];
+}
+export interface MeshBuilder {
+    /** Append one equally-cardinal attribute batch to the accumulated source. */
+    appendVertices(attributes: VertexAttributeMap): Result<void, AssetError>;
+    /** Append raw index values; width is derived during build. */
+    appendIndices(indices: ArrayLike<number>): Result<void, AssetError>;
+    /** Add a draw range; omitted ranges are completed from the final source. */
+    addSubmesh(submesh: MeshBuilderSubmesh): Result<void, AssetError>;
+    /** Derive one immutable MeshAsset from the accumulated source. */
+    build(): Result<MeshAsset, AssetError>;
+}
+/**
+ * Create a geometry-owned builder. All derived facts are computed once in
+ * `build()` from the accumulated canonical attribute source.
+ */
+export declare function createMeshBuilder(options?: MeshBuilderOptions): MeshBuilder;
+//# sourceMappingURL=mesh-builder.d.ts.map

package/dist/mesh-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mesh-builder.d.ts","sourceRoot":"","sources":["../src/mesh-builder.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,UAAU,EAEV,KAAK,SAAS,EACd,KAAK,gBAAgB,EAErB,KAAK,iBAAiB,EACtB,KAAK,MAAM,EACX,KAAK,OAAO,EACZ,KAAK,kBAAkB,EACxB,MAAM,uBAAuB,CAAC;AAiD/B,uDAAuD;AACvD,MAAM,MAAM,kBAAkB,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG;IAClD,QAAQ,CAAC,QAAQ,CAAC,EAAE,iBAAiB,CAAC;CACvC,CAAC;AAEF,iEAAiE;AACjE,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,UAAU,CAAC,EAAE,kBAAkB,CAAC;IACzC,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC;IACrC,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACnD,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAC;CACtD;AAED,MAAM,WAAW,WAAW;IAC1B,6EAA6E;IAC7E,cAAc,CAAC,UAAU,EAAE,kBAAkB,GAAG,MAAM,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;IACzE,8DAA8D;IAC9D,aAAa,CAAC,OAAO,EAAE,SAAS,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;IACpE,4EAA4E;IAC5E,UAAU,CAAC,OAAO,EAAE,kBAAkB,GAAG,MAAM,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;IAClE,kEAAkE;IAClE,KAAK,IAAI,MAAM,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;CACxC;AAyND;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,kBAAuB,GAAG,WAAW,CAwJ/E"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgeax/engine-geometry",
-  "version": "0.1.20",
+  "version": "0.1.21",
   "private": false,
   "type": "module",
   "license": "Apache-2.0",
@@ -22,10 +22,10 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@forgeax/engine-ecs": "0.1.20",
-    "@forgeax/engine-math": "0.1.20",
-    "@forgeax/engine-pack": "0.1.20",
-    "@forgeax/engine-types": "0.1.20"
+    "@forgeax/engine-ecs": "0.1.21",
+    "@forgeax/engine-math": "0.1.21",
+    "@forgeax/engine-pack": "0.1.21",
+    "@forgeax/engine-types": "0.1.21"
   },
   "forgeax": {
     "metrics": {

package/src/__tests__/mesh-builder.integration.test.ts

@@ -0,0 +1,58 @@
+import type { AssetDecoderInput, MeshAsset } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { meshAssetDecoder } from '../assets/mesh-decoder.js';
+import { createMeshBuilder } from '../mesh-builder.js';
+
+function decode(mesh: MeshAsset) {
+  const context = {
+    envelope: { guid: 'mesh-builder', kind: 'mesh', payload: mesh, refs: [], artifacts: {} },
+    artifacts: { read: async () => ({ ok: false as const, error: new Error('not used') }) },
+  } as unknown as AssetDecoderInput<MeshAsset>;
+  return meshAssetDecoder.decode(context);
+}
+
+describe('MeshBuilder -> MeshAsset decoder', () => {
+  it('feeds a position-only builder output through the existing decoder', async () => {
+    const built = createMeshBuilder({
+      attributes: { position: new Float32Array([0, 0, 0, 1, 0, 0, 0, 1, 0]) },
+    }).build();
+    expect(built.ok).toBe(true);
+    if (!built.ok) return;
+    const decoded = await decode(built.value);
+    expect(decoded.ok).toBe(true);
+    if (decoded.ok) expect(decoded.value.aabb).toEqual(built.value.aabb);
+  });
+
+  it('preserves multiple submesh topology and material slots at the consumer boundary', async () => {
+    const built = createMeshBuilder({
+      attributes: {
+        position: new Float32Array([0, 0, 0, 1, 0, 0, 0, 1, 0, 2, 0, 0, 3, 0, 0, 2, 1, 0]),
+      },
+      indices: [0, 1, 2, 3, 4, 5],
+      materialSlots: [{ slotName: 'base' }, { slotName: 'accent' }],
+      submeshes: [
+        {
+          indexOffset: 0,
+          indexCount: 3,
+          vertexCount: 3,
+          topology: 'triangle-list',
+          materialSlot: 0,
+        },
+        {
+          indexOffset: 3,
+          indexCount: 3,
+          vertexCount: 3,
+          topology: 'triangle-list',
+          materialSlot: 1,
+        },
+      ],
+    }).build();
+    expect(built.ok).toBe(true);
+    if (!built.ok) return;
+    const decoded = await decode(built.value);
+    expect(decoded.ok).toBe(true);
+    if (!decoded.ok) return;
+    expect(decoded.value.submeshes).toEqual(built.value.submeshes);
+    expect(decoded.value.materialSlots).toEqual(built.value.materialSlots);
+  });
+});

package/src/__tests__/mesh-builder.unit.test.ts

@@ -0,0 +1,96 @@
+import { describe, expect, it } from 'vitest';
+import { createMeshBuilder } from '../mesh-builder.js';
+
+const trianglePositions = new Float32Array([-1, -2, -3, 4, 5, 6, 0, 2, 1]);
+
+describe('createMeshBuilder', () => {
+  it('derives position-only layout, AABB, index width, and default submesh', () => {
+    const result = createMeshBuilder({
+      attributes: { position: trianglePositions },
+      indices: [0, 1, 2],
+    }).build();
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.attributes).toEqual({ position: trianglePositions });
+    expect(result.value.indices).toBeInstanceOf(Uint16Array);
+    expect(result.value.aabb).toEqual(Float32Array.of(-1, -2, -3, 4, 5, 6));
+    expect(result.value.submeshes).toEqual([
+      { indexOffset: 0, indexCount: 3, vertexCount: 3, topology: 'triangle-list', materialSlot: 0 },
+    ]);
+    expect(result.value.materialSlots).toEqual([{ slotName: 'Default' }]);
+    expect(result.value.vertices).toEqual(trianglePositions);
+  });
+
+  it('packs the complete canonical attribute set without a caller-owned layout', () => {
+    const result = createMeshBuilder({
+      attributes: {
+        position: trianglePositions,
+        normal: new Float32Array([0, 0, 1, 0, 0, 1, 0, 0, 1]),
+        uv: new Float32Array([0, 0, 1, 0, 0, 1]),
+        tangent: new Float32Array([1, 0, 0, 1, 1, 0, 0, 1, 1, 0, 0, 1]),
+        color: new Float32Array([1, 0, 0, 1, 0, 1, 0, 1, 0, 0, 1, 1]),
+      },
+      indices: new Uint16Array([0, 1, 2]),
+    }).build();
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.vertices.byteLength).toBe(3 * 64);
+    expect(result.value.attributes.color).toEqual(
+      new Float32Array([1, 0, 0, 1, 0, 1, 0, 1, 0, 0, 1, 1]),
+    );
+  });
+
+  it('chooses Uint32 at the first index beyond the Uint16 range', () => {
+    const positions = new Float32Array(65_537 * 3);
+    positions[65_536 * 3] = 10;
+    const result = createMeshBuilder({
+      attributes: { position: positions },
+      indices: [0, 65_535, 65_536],
+    }).build();
+    expect(result.ok).toBe(true);
+    if (result.ok) expect(result.value.indices).toBeInstanceOf(Uint32Array);
+  });
+
+  it('returns structured errors for missing attributes, cardinality, indices, and ranges', () => {
+    const missingPosition = createMeshBuilder({
+      attributes: { normal: new Float32Array(3) },
+    }).build();
+    expect(missingPosition.ok).toBe(false);
+    if (!missingPosition.ok) expect(missingPosition.error.code).toBe('asset-invalid-value');
+
+    const mismatched = createMeshBuilder({
+      attributes: { position: trianglePositions, normal: new Float32Array(3) },
+    }).build();
+    expect(mismatched.ok).toBe(false);
+    if (!mismatched.ok) expect(mismatched.error.detail).toMatchObject({ field: 'normal' });
+
+    const outOfBounds = createMeshBuilder({
+      attributes: { position: trianglePositions },
+      indices: [0, 1, 3],
+    }).build();
+    expect(outOfBounds.ok).toBe(false);
+    if (!outOfBounds.ok) expect(outOfBounds.error.detail).toMatchObject({ field: 'indices' });
+
+    const invalidRange = createMeshBuilder({
+      attributes: { position: trianglePositions },
+      indices: [0, 1, 2],
+      submeshes: [{ indexOffset: 2, indexCount: 2, vertexCount: 3, topology: 'triangle-list' }],
+    }).build();
+    expect(invalidRange.ok).toBe(false);
+    if (!invalidRange.ok)
+      expect(invalidRange.error.detail).toMatchObject({ field: 'submeshes[0]' });
+  });
+
+  it('copies accumulated source data and preserves built output immutability', () => {
+    const source = new Float32Array(trianglePositions);
+    const builder = createMeshBuilder({ attributes: { position: source } });
+    const first = builder.build();
+    expect(first.ok).toBe(true);
+    source[0] = 99;
+    const second = builder.build();
+    expect(second.ok).toBe(true);
+    if (!first.ok || !second.ok) return;
+    expect(first.value.attributes.position).toEqual(trianglePositions);
+    expect(second.value.attributes.position).toEqual(trianglePositions);
+  });
+});

package/src/assets/mesh-binary.ts

@@ -14,6 +14,7 @@ import type {
 } from '@forgeax/engine-types';
 import { PROCEDURAL_FLOATS_PER_VERTEX } from '../box';
 import {
+  deriveVertexLayoutProjection,
   deriveVertexLayoutProjectionFromMask,
   type VertexLayoutProjection,
 } from '../vertex-attribute-layout';
@@ -400,6 +401,16 @@ export function normalizeMeshPayload(
   if (payload === null || typeof payload !== 'object' || Array.isArray(payload)) return undefined;
   const source = payload as Record<string, unknown>;
   if (source.kind !== 'mesh') return undefined;
+  const sourceAttributes =
+    source.attributes !== null && typeof source.attributes === 'object'
+      ? (source.attributes as VertexAttributeMap)
+      : undefined;
+  const projection =
+    sourceAttributes === undefined ? undefined : deriveVertexLayoutProjection(sourceAttributes);
+  const floatsPerVertex =
+    projection === undefined || projection.attributes.length === 0
+      ? PROCEDURAL_FLOATS_PER_VERTEX
+      : projection.arrayStride / Float32Array.BYTES_PER_ELEMENT;
   return meshFromParts(
     {
       vertices: source.vertices,
@@ -414,7 +425,7 @@ export function normalizeMeshPayload(
         : {}),
       ...(source.morphTargets === undefined ? {} : { morphTargets: source.morphTargets }),
       ...(source.morphWeights === undefined ? {} : { morphWeights: source.morphWeights }),
-      floatsPerVertex: PROCEDURAL_FLOATS_PER_VERTEX,
+      floatsPerVertex,
     },
     refs,
   );

package/src/index.ts

@@ -15,7 +15,6 @@ export type { VertexAttributePackDetail } from '@forgeax/engine-types';
 
 export { meshAssetContribution, meshAssetDecoder, meshAssetKind } from './assets/mesh-decoder';
 export { createPrimitiveMesh, type PrimitiveMeshKind } from './assets/primitive-mesh';
-
 export {
   createBoxGeometry,
   meshFromInterleaved,
@@ -36,6 +35,12 @@ export {
 } from './dim2';
 // Edge factories return Result<MeshAsset, AssetError>; threshold units are degrees.
 export { createEdgesGeometry, createWireframeGeometry } from './edges';
+export {
+  createMeshBuilder,
+  type MeshBuilder,
+  type MeshBuilderOptions,
+  type MeshBuilderSubmesh,
+} from './mesh-builder';
 export { createPlaneGeometry } from './plane';
 export { createSphereGeometry } from './sphere';
 export { computeTangentVec4 } from './tangent';