@forgeax/engine-geometry 0.1.2

package/dist/vertex-attribute-layout.d.ts

@@ -0,0 +1,90 @@
+import { AssetError, type Result, type VertexAttributeMap, type VertexAttributePackDetail } from '@forgeax/engine-types';
+declare const ATTRIBUTE_FORMAT_MAP: {
+    readonly position: "float32x3";
+    readonly normal: "float32x3";
+    readonly uv: "float32x2";
+    readonly tangent: "float32x4";
+    readonly skinIndex: "uint16x4";
+    readonly skinWeight: "float32x4";
+    readonly uv1: "float32x2";
+    readonly uv2: "float32x2";
+    readonly uv3: "float32x2";
+    readonly uv4: "float32x2";
+    readonly uv5: "float32x2";
+    readonly uv6: "float32x2";
+    readonly uv7: "float32x2";
+    readonly color: "float32x4";
+};
+type AttributeKey = keyof typeof ATTRIBUTE_FORMAT_MAP;
+export interface GpuVertexBufferLayoutEntry {
+    readonly arrayStride: number;
+    readonly attributes: ReadonlyArray<{
+        readonly shaderLocation: number;
+        readonly offset: number;
+        readonly format: string;
+    }>;
+    readonly stepMode?: 'vertex' | 'instance' | undefined;
+}
+/**
+ * Build a non-skin `VertexAttributeMap` carrying exactly `uvSetCount` UV sets
+ * (set 0 = `uv`, then `uv1..uv{uvSetCount-1}`). `deriveVertexBufferLayout`
+ * reads only key presence, so the zero-length typed-array values are sentinels.
+ *
+ * feat-20260629-multi-uv-set-support: the forward record stage owns only the
+ * mesh's `uvSetCount` (a scalar threaded through MeshGpuHandles), not the
+ * original `MeshAsset.attributes` map. It synthesizes the map here so the
+ * material PSO's vertex layout includes the real @location(6+) attributes and
+ * its stride matches the interleaved buffer (a mesh with 2 real UV sets has a
+ * 56 B stride; a 48 B PSO layout against it puts every vertex after the first
+ * off-screen). uvSetCount <= 1 yields the canonical 4-attribute single-UV map.
+ */
+export declare function buildMeshAttributeMapForUvSets(uvSetCount: number): VertexAttributeMap;
+export declare function deriveVertexBufferLayout(map: VertexAttributeMap, opts?: {
+    shaderUvSetCount?: number;
+}): GpuVertexBufferLayoutEntry[];
+/** Build the GPU descriptor from an immutable projection, adding only shader UV aliases. */
+export declare function deriveVertexBufferLayoutFromProjection(projection: VertexLayoutProjection, opts?: {
+    shaderUvSetCount?: number;
+}): GpuVertexBufferLayoutEntry[];
+export interface VertexLayoutProjectionAttribute {
+    readonly key: AttributeKey;
+    readonly shaderLocation: number;
+    readonly offset: number;
+    readonly format: (typeof ATTRIBUTE_FORMAT_MAP)[AttributeKey];
+    readonly byteLength: number;
+}
+/** Immutable geometry-owned projection consumed by packers and GPU consumers. */
+export interface VertexLayoutProjection {
+    readonly schemaVersion: 1;
+    readonly attributes: readonly VertexLayoutProjectionAttribute[];
+    readonly mask: number;
+    readonly arrayStride: number;
+    readonly digest: string;
+}
+/** Derive the one canonical immutable layout projection for a vertex map. */
+export declare function deriveVertexLayoutProjection(map: VertexAttributeMap): VertexLayoutProjection;
+export interface PackedVertexAttributes {
+    readonly projection: VertexLayoutProjection;
+    readonly vertices: Float32Array;
+}
+export declare class VertexAttributePackError extends AssetError {
+    readonly detail: VertexAttributePackDetail;
+    constructor(detail: VertexAttributePackDetail);
+}
+export interface VertexLayoutProjectionMaskError {
+    readonly code: 'vertex-layout-mask-invalid';
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: {
+        readonly mask: number;
+        readonly knownMask: number;
+        readonly unknownMask: number;
+        readonly reason: 'empty' | 'unknown-bits';
+    };
+}
+/** Rebuild the canonical projection from a packed wire mask without a second schema. */
+export declare function deriveVertexLayoutProjectionFromMask(mask: number): Result<VertexLayoutProjection, VertexLayoutProjectionMaskError>;
+/** Pack tightly-owned attributes into the projection's canonical interleaved bytes. */
+export declare function packInterleavedVertexAttributes(map: VertexAttributeMap, vertexCount: number): Result<PackedVertexAttributes, VertexAttributePackError>;
+export {};
+//# sourceMappingURL=vertex-attribute-layout.d.ts.map

package/dist/vertex-attribute-layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vertex-attribute-layout.d.ts","sourceRoot":"","sources":["../src/vertex-attribute-layout.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@forgeax/engine-geometry",
+  "version": "0.1.2",
+  "private": false,
+  "type": "module",
+  "license": "Apache-2.0",
+  "sideEffects": false,
+  "description": "Procedural mesh geometry factories + vertex attribute layout SSOT for forgeax-engine.",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@forgeax/engine-ecs": "0.1.2",
+    "@forgeax/engine-math": "0.1.2",
+    "@forgeax/engine-pack": "0.1.2",
+    "@forgeax/engine-types": "0.1.2"
+  },
+  "forgeax": {
+    "metrics": {
+      "bundle-size": {
+        "enabled": true,
+        "path": "dist/index.mjs",
+        "compression": "gzip"
+      },
+      "fps": {
+        "enabled": false,
+        "reason": "pure-function geometry library, no runtime canvas; fps reported by hello-triangle / hello-cube apps"
+      },
+      "bench": {
+        "enabled": false,
+        "reason": "procedural geometry factories run once at asset-build time, not per-frame; no CI micro-benchmark warranted"
+      },
+      "gate": {
+        "enabled": false,
+        "reason": "no package-level binary gate; smoke gate covered by hello-* / learn-render apps that consume the factories"
+      },
+      "spike-report": {
+        "enabled": false,
+        "reason": "not a spike package; geometry extracted from runtime in feat-20260704-runtime-tier1-decomposition"
+      }
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run"
+  }
+}

package/src/__tests__/asset-owner.unit.test.ts

@@ -0,0 +1,97 @@
+import { World } from '@forgeax/engine-ecs';
+import { BUILTIN_BASE, handleSlot } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { meshAssetDecoder } from '../assets/mesh-decoder';
+import { createPrimitiveMesh } from '../assets/primitive-mesh';
+import { createBoxGeometry } from '../box';
+import { deriveVertexBufferLayout } from '../vertex-attribute-layout';
+
+describe('geometry asset owner direct contract', () => {
+  it('decodes the finite authored procedural descriptor into a fresh MeshAsset', async () => {
+    const result = await meshAssetDecoder.decode({
+      envelope: {
+        guid: '019f0000-0000-7000-8000-000000000001',
+        kind: 'mesh',
+        payload: { geometry: 'procedural-cube' } as never,
+        refs: [],
+        artifacts: {},
+      },
+      artifacts: { read: async () => ({ ok: false, error: new Error('unused') }) as never },
+      signal: new AbortController().signal,
+    });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.kind).toBe('mesh');
+    expect(result.value.vertices.length).toBe(24 * 12);
+    expect(result.value.aabb).toEqual(Float32Array.from([-0.5, -0.5, -0.5, 0.5, 0.5, 0.5]));
+  });
+
+  it('publishes primitive payload, AABB and the derived vertex layout together', () => {
+    const result = createBoxGeometry(2, 4, 6);
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.kind).toBe('mesh');
+    expect(result.value.aabb).toEqual(Float32Array.from([-1, -2, -3, 1, 2, 3]));
+    expect(result.value.attributes.position).toBeInstanceOf(Float32Array);
+    const layout = deriveVertexBufferLayout(result.value.attributes);
+    expect(layout).toHaveLength(1);
+    expect(layout[0]).toMatchObject({ arrayStride: 48 });
+    expect(layout[0]?.attributes).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ shaderLocation: 0, format: 'float32x3' }),
+        expect.objectContaining({ shaderLocation: 1, format: 'float32x3' }),
+        expect.objectContaining({ shaderLocation: 2, format: 'float32x2' }),
+      ]),
+    );
+  });
+
+  it('returns a structured error for an invalid primitive instead of a partial payload', () => {
+    const result = createBoxGeometry(0, 1, 1);
+
+    expect(result).toMatchObject({ ok: false, error: { code: 'asset-parse-failed' } });
+  });
+
+  it('creates fresh primitive payloads and lets each World own its shared handle', () => {
+    const firstPayload = createPrimitiveMesh('cube').unwrap();
+    const secondPayload = createPrimitiveMesh('cube').unwrap();
+    const firstWorld = new World();
+    const secondWorld = new World();
+
+    expect(secondPayload).not.toBe(firstPayload);
+
+    const firstHandle = firstWorld.internSharedRef('MeshAsset', firstPayload);
+    const repeatedHandle = firstWorld.internSharedRef('MeshAsset', firstPayload);
+    const secondHandle = secondWorld.internSharedRef('MeshAsset', secondPayload);
+
+    expect(repeatedHandle).toBe(firstHandle);
+    expect(handleSlot(firstHandle)).toBe(BUILTIN_BASE);
+    expect(handleSlot(secondHandle)).toBe(BUILTIN_BASE);
+    expect(firstWorld.sharedRefs.resolve(firstHandle)).toEqual({ ok: true, value: firstPayload });
+    expect(secondWorld.sharedRefs.resolve(secondHandle)).toEqual({
+      ok: true,
+      value: secondPayload,
+    });
+    expect(firstWorld.sharedRefs.refcount(firstHandle)).toBe(1);
+    expect(secondWorld.sharedRefs.refcount(secondHandle)).toBe(1);
+  });
+
+  it('preserves the six former primitive payload shapes without static handles', () => {
+    const expectations = {
+      cube: { vertices: 24 * 12, indices: 36 },
+      triangle: { vertices: 3 * 12, indices: 3 },
+      quad: { vertices: 4 * 12, indices: 6 },
+      sphere: { vertices: 17 * 13 * 12, indices: 1056 },
+      cylinder: { vertices: 70 * 12, indices: 192 },
+      'nine-slice-quad': { vertices: 16 * 12, indices: 54 },
+    } as const;
+
+    for (const [kind, expected] of Object.entries(expectations)) {
+      const mesh = createPrimitiveMesh(kind as keyof typeof expectations).unwrap();
+      expect(mesh.vertices.length, kind).toBe(expected.vertices);
+      expect(mesh.indices?.length, kind).toBe(expected.indices);
+      expect(mesh.aabb, kind).toBeDefined();
+    }
+  });
+});

package/src/__tests__/dim2.test.ts

@@ -0,0 +1,132 @@
+import {
+  compute2dBounds,
+  create2dGeometry,
+  create2dRingGeometry,
+  PROCEDURAL_FLOATS_PER_VERTEX,
+  type Shape2d,
+} from '@forgeax/engine-geometry';
+import { describe, expect, it } from 'vitest';
+
+const FILLED_SHAPES: readonly Shape2d[] = [
+  { kind: 'circle', radius: 1, resolution: 12 },
+  { kind: 'circular-sector', radius: 1, angle: 1.25, resolution: 12 },
+  { kind: 'circular-segment', radius: 1, angle: 1.25, resolution: 12 },
+  { kind: 'ellipse', halfWidth: 1.5, halfHeight: 0.75, resolution: 12 },
+  { kind: 'annulus', innerRadius: 0.5, outerRadius: 1, resolution: 12 },
+  { kind: 'capsule', radius: 0.35, halfLength: 0.65, resolution: 12 },
+  { kind: 'rhombus', halfWidth: 1.2, halfHeight: 0.8 },
+  { kind: 'rectangle', width: 2, height: 1 },
+  { kind: 'regular-polygon', radius: 1, sides: 6 },
+  {
+    kind: 'triangle',
+    vertices: [
+      [0, 1],
+      [-1, -1],
+      [1, -1],
+    ],
+  },
+];
+
+describe('2D primitive geometry', () => {
+  it('builds every filled Bevy 2D shape as a triangle MeshAsset', () => {
+    for (const shape of FILLED_SHAPES) {
+      const result = create2dGeometry(shape);
+      expect(result.ok, shape.kind).toBe(true);
+      if (!result.ok) continue;
+      expect(result.value.submeshes).toEqual([
+        expect.objectContaining({ topology: 'triangle-list', indexCount: expect.any(Number) }),
+      ]);
+      const submesh = result.value.submeshes[0];
+      expect(submesh).toBeDefined();
+      if (!submesh) continue;
+      expect(result.value.vertices.length).toBe(submesh.vertexCount * PROCEDURAL_FLOATS_PER_VERTEX);
+      const position = result.value.attributes.position;
+      expect(position).toBeInstanceOf(Float32Array);
+      if (!(position instanceof Float32Array)) continue;
+      expect(position.length).toBe(submesh.vertexCount * 3);
+      expect(result.value.aabb).toHaveLength(6);
+    }
+  });
+
+  it('builds segment and polyline as line-list meshes', () => {
+    const segment = create2dGeometry({
+      kind: 'segment',
+      vertices: [
+        [-1, 0],
+        [1, 0],
+      ],
+    });
+    const polyline = create2dGeometry({
+      kind: 'polyline',
+      vertices: [
+        [-1, 0],
+        [0, 1],
+        [1, 0],
+      ],
+    });
+    expect(segment.ok).toBe(true);
+    expect(polyline.ok).toBe(true);
+    if (!segment.ok || !polyline.ok) return;
+    expect(segment.value.submeshes[0]?.topology).toBe('line-list');
+    expect(polyline.value.submeshes[0]?.indexCount).toBe(4);
+  });
+
+  it('builds the closed ring variants from one shape contract', () => {
+    for (const shape of FILLED_SHAPES.filter((candidate) => candidate.kind !== 'annulus')) {
+      const result = create2dRingGeometry(shape, 0.1);
+      expect(result.ok, shape.kind).toBe(true);
+      if (!result.ok) continue;
+      expect(result.value.submeshes[0]?.topology).toBe('triangle-list');
+      expect(result.value.submeshes[0]?.indexCount).toBeGreaterThan(0);
+    }
+  });
+
+  it('fails fast for invalid dimensions and unsupported rings', () => {
+    expect(create2dGeometry({ kind: 'circle', radius: 0 }).ok).toBe(false);
+    expect(create2dGeometry({ kind: 'regular-polygon', radius: 1, sides: 2 }).ok).toBe(false);
+    expect(create2dGeometry({ kind: 'polyline', vertices: [[0, 0]] }).ok).toBe(false);
+    expect(
+      create2dRingGeometry({ kind: 'annulus', innerRadius: 0.2, outerRadius: 1 }, 0.1).ok,
+    ).toBe(false);
+    expect(create2dRingGeometry({ kind: 'circle', radius: 1 }, 1).ok).toBe(false);
+  });
+
+  it('projects circular-mask UVs around a requested texture angle', () => {
+    const shape: Shape2d = {
+      kind: 'circular-sector',
+      radius: 2,
+      angle: Math.PI / 2,
+      resolution: 8,
+    };
+    const result = create2dGeometry(shape, { uv: { kind: 'circular-mask', angle: Math.PI / 2 } });
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    const uv = result.value.attributes.uv;
+    expect(uv).toBeInstanceOf(Float32Array);
+    if (!(uv instanceof Float32Array)) return;
+    for (const value of uv) expect(value).toBeGreaterThanOrEqual(0);
+    for (const value of uv) expect(value).toBeLessThanOrEqual(1);
+    expect(
+      create2dGeometry(
+        { kind: 'rectangle', width: 1, height: 1 },
+        { uv: { kind: 'circular-mask', angle: 0 } },
+      ).ok,
+    ).toBe(false);
+  });
+
+  it('computes transformed AABB and bounding circle from the same shape contract', () => {
+    const result = compute2dBounds(
+      { kind: 'circular-sector', radius: 2, angle: Math.PI / 2, resolution: 16 },
+      { translation: [3, -4], rotation: Math.PI / 2 },
+    );
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.aabb[0]).toBeLessThanOrEqual(3);
+    expect(result.value.aabb[1]).toBeLessThanOrEqual(-4);
+    expect(result.value.aabb[2]).toBeGreaterThanOrEqual(3);
+    expect(result.value.aabb[3]).toBeGreaterThanOrEqual(-4);
+    expect(result.value.circle[0]).toBeCloseTo(3, 4);
+    expect(result.value.circle[1]).toBeCloseTo(-4, 4);
+    expect(result.value.circle[2]).toBeCloseTo(2, 4);
+  });
+});