@forgeax/engine-sdk 0.5.0-dev.15093.89d287422343 → 0.5.0-dev.15095.c10283ee6c8f

package/sdk/skills/forgeax-engine-cli/SKILL.md

@@ -199,9 +199,10 @@ document.fonts.ready. Projects must bundle the same Web fonts; system font fallb
 parity.
 
 Use --deterministic for local/remote pixel or color comparisons. The CLI opens ?forgeaxCapture=1;
-App publishes document.documentElement.dataset.forgeaxFrameSubmitted after an actual renderer submission
-and dispatches forgeax:frame-submitted on Canvas. The CLI waits for that signal and non-flat canvas crop, then
-for document.documentElement.dataset.forgeaxCaptureReady = 'true'. Before readiness, the game must pin
+App retains the submitted frame facts on canvas.forgeaxFrameProgress after an actual renderer submission
+and dispatches forgeax:frame-submitted on Canvas as a future-only notification. The CLI reads the snapshot
+and waits for a non-flat canvas crop before accepting the game's
+`document.documentElement.dataset.forgeaxCaptureReady = 'true'` checkpoint. Before readiness, the game must pin
 random seed, logical frame, state, and project fonts. Viewport, DPR, and elapsed time alone do not establish parity.
 
 For continuous playthroughs, reuse one session; repeated one-shot capture restarts the page and World:

package/sdk/skills/forgeax-engine-debug/SKILL.md

@@ -39,11 +39,26 @@ Pack path and the existing exact-target capture. One-level Equirect sources do
 not expose Renderer-owned IBL roughness mips. Follow RHI Debug first for an
 unexplained rendering failure; see the [View texture gate](../../scripts/ci/README.md#concurrent-local-sessions-and-the-gpu-lease).
 
+For View UV layouts or material primitive/navigation failures, run
+`tools/view/scripts/verify-resource-preview-lifecycle.mjs` and inspect its UV and
+material PNGs plus exact target diagnostics. The maintained workspace shard owns
+this real-browser journey. A script syntax error routes to the View probe owner;
+preserve its runtime assertions while repairing startup. Follow RHI Debug first
+for unexplained rendered output.
+
 For a blank MCP View with React error #527, run its emitted frontend startup gate
 through the View contracts owner. The MCP builder resolves React and React DOM
 from View's installed dependencies; inspect that owner before changing startup
 deadlines. Continue through the full game-3d/Play/Stop gate after repair.
 
+For a View shard reaching its job deadline, inspect emitted stage seconds before
+changing a timeout. Keep Game 3D's stdio and native workspace journeys together
+in its own lane; contracts/plugin/TS share another. Preserve complete JS/TS
+live/cold chains, four actual jobs and all assertions; see the
+[Engine/View integration roster](../../scripts/ci/README.md#failure-recovery).
+An artifact-only transport failure requires a same-source rerun, not a weaker
+success aggregate.
+
 For a View startup Host disconnect, read the failed probe's Backend diagnostics
 under `artifacts/view-integration/<probe>/` before assigning a renderer cause.
 The CI owner matches native daemon spawn records to the failed child and retains

package/sdk/skills/forgeax-engine-sdk/SDK-AGENTS.md

@@ -134,10 +134,10 @@ pnpm exec forgeax project capture --headless true --backend software --require-u
 
 This uses source-development assets and browser compositor screenshots; retain adapter/error sidecar evidence.
 For cross-machine comparison, add --deterministic and pin game state in forgeaxCapture mode.
-App's actual frame-submitted event projects to
-document.documentElement.dataset.forgeaxFrameSubmitted and the Canvas
-forgeax:frame-submitted event. Capture waits for Engine submission and non-flat Canvas pixels,
-then the game's forgeaxCaptureReady checkpoint. Elapsed waiting is
+App retains submitted and completed facts on `canvas.forgeaxFrameProgress` and dispatches
+the Canvas `forgeax:frame-submitted` event as a future-only notification. Capture reads the
+snapshot and waits for non-flat Canvas pixels, then the game's forgeaxCaptureReady checkpoint.
+Elapsed waiting is
 only extra settling, not a deterministic frame or substitute for pixel evidence.
 Use a Node/Bun SDK command-client scenario for input, assertions, and multiple checkpoints in one session.
 Open browser once, drive native session.page, and call session.capture(name)

package/sdk/skills/forgeax-engine-sdk/SDK-README.md

@@ -92,8 +92,9 @@ Bundle the same Web fonts; do not rely on matching system fonts.
 For cross-machine color regression, use --deterministic and ?forgeaxCapture=1. Games pin random
 seed/logical frame/fonts and set readiness only after Canvas/UI stabilize:
 document.documentElement.dataset.forgeaxCaptureReady = 'true'. App also publishes
-forgeaxFrameSubmitted after actual Renderer submission and dispatches
-forgeax:frame-submitted. The CLI waits for Engine submission/non-flat output before the game marker.
+`canvas.forgeaxFrameProgress.submitted` after actual Renderer submission and dispatches
+`forgeax:frame-submitted` as a future-only notification. The CLI reads the canvas snapshot and
+waits for non-flat output before the game marker.
 wait-ms adds settling after these handshakes; it does not identify a deterministic frame.
 
 For continuous captures, keep one Vite/Xvfb/Chrome/Page/World session and use named ready markers

package/sdk/skills/forgeax-engine-sdk/references/browser-capture-and-local-engine.md

@@ -11,14 +11,14 @@ The readiness chain is explicit:
 
 ```mermaid
 flowchart LR
-  A[Renderer submits frame] --> B[data-forgeax-frame-submitted]
+  A[Renderer submits frame] --> B[canvas.forgeaxFrameProgress.submitted]
   B --> C[non-flat Canvas witness]
   C --> D[optional named game checkpoint]
   D --> E[compositor settle]
   E --> F[full viewport PNG and run.json]
 ```
 
-The Engine publishes `data-forgeax-frame-submitted` after a real renderer submission. A deterministic game may additionally set `data-forgeax-capture-ready` to `true` or a checkpoint name. `--wait-ms` is only extra compositor settle time after those signals; it is not the game-readiness authority.
+The Engine retains submitted and completed frame facts on the owner Canvas as `forgeaxFrameProgress`. Its `forgeax:frame-submitted` Canvas event is a future-only notification; it does not replay an earlier submission. A deterministic game may additionally set `data-forgeax-capture-ready` to `true` or a checkpoint name. `--wait-ms` is only extra compositor settle time after those signals; it is not the game-readiness authority.
 
 ```bash
 forgeax project capture --backend auto --require-ui --deterministic \

package/sdk/templates/empty/package.json

@@ -40,7 +40,7 @@
     }
   },
   "dependencies": {
-    "@forgeax/engine": "0.5.0-dev.15093.89d287422343"
+    "@forgeax/engine": "0.5.0-dev.15095.c10283ee6c8f"
   },
   "devDependencies": {
     "@types/node": "20.19.40",

package/sdk/templates/empty/pnpm-lock.yaml

@@ -167,8 +167,8 @@ importers:
   .:
     dependencies:
       '@forgeax/engine':
-        specifier: 0.5.0-dev.15093.89d287422343
-        version: 0.5.0-dev.15093.89d287422343(48eb1dc1d1b0f9a6a9ad276467f438dc)
+        specifier: 0.5.0-dev.15095.c10283ee6c8f
+        version: 0.5.0-dev.15095.c10283ee6c8f(48eb1dc1d1b0f9a6a9ad276467f438dc)
     devDependencies:
       '@types/node':
         specifier: 20.19.40
@@ -528,8 +528,8 @@ packages:
   '@fontsource-variable/noto-sans-sc@5.3.0':
     resolution: {integrity: sha512-lNar1dF7Ik/lHNPo/7JWG0TolXY29LtsqYgMvEysooZ5bsO9uH4shJmRrwyJ3PjyTPljhpMJEK0jDuLSU4vJ1w==, tarball: https://registry.npmjs.org/@fontsource-variable/noto-sans-sc/-/noto-sans-sc-5.3.0.tgz}
 
-  '@forgeax/engine@0.5.0-dev.15093.89d287422343':
-    resolution: {integrity: sha512-+zzY53UNxLfS83MBaNfwWVnquqRAqObpsnXGIsYfC4ogdXTg3fbfCTn/VKq2ENl126jxycX1bQwEl18CIx00Rw==}
+  '@forgeax/engine@0.5.0-dev.15095.c10283ee6c8f':
+    resolution: {integrity: sha512-Nqhf+87EZBjq+TrsevtiTbAKYCHu2ys9gG3f6eMkINluzE0c58u4EWRkthA1iy35k0xfMUopuVbEDEbuY26aog==}
     hasBin: true
     bundledDependencies:
       - '@deepseek-ai/cordis'
@@ -611,6 +611,7 @@ packages:
       - '@forgeax/engine-vite-plugin-rhi-debug'
       - '@forgeax/engine-vite-plugin-shader'
       - '@forgeax/engine-wgpu-wasm'
+      - core-js-pure
 
   '@jridgewell/sourcemap-codec@1.6.0':
     resolution: {integrity: sha512-T7jf+5zgsZHwNJ4lvQ7/aezbyk0nNX+zJVWpmHA7VYsEx7a7qr5Rg5IbtJFqkgze5Y2sruq1RUY8Q837Od7iFw==, tarball: https://registry.npmjs.org/@jridgewell/sourcemap-codec/-/sourcemap-codec-1.6.0.tgz}
@@ -861,9 +862,6 @@ packages:
   convert-source-map@2.0.0:
     resolution: {integrity: sha512-Kvp459HrV2FEJ1CAsi1Ku+MY3kasH19TFykTz2xWmMeq6bk2NU3XXvfJ+Q61m0xktWwt+1HSYf3JZsTms3aRJg==, tarball: https://registry.npmjs.org/convert-source-map/-/convert-source-map-2.0.0.tgz}
 
-  core-js-pure@3.50.0:
-    resolution: {integrity: sha512-6GP3Pxz4IKyWjAfa747vIu/jilB5z29JWROLqH/b+pXVcpgh6tM06ZIBwSuglgVqzDYURhOK6oEzTrG0bCHitA==, tarball: https://registry.npmjs.org/core-js-pure/-/core-js-pure-3.50.0.tgz}
-
   css-select@7.0.0:
     resolution: {integrity: sha512-snmjEVXy+1LnwXdxhYvTMj1d9tOh4HxkA1YmoayVBeeyR2C14Pum7fcxJIm4SswYspVy866eYNwlH6xC3/VH5g==, tarball: https://registry.npmjs.org/css-select/-/css-select-7.0.0.tgz}
     engines: {node: '>=20.19.0'}
@@ -1623,7 +1621,7 @@ snapshots:
 
   '@fontsource-variable/noto-sans-sc@5.3.0': {}
 
-  '@forgeax/engine@0.5.0-dev.15093.89d287422343(48eb1dc1d1b0f9a6a9ad276467f438dc)':
+  '@forgeax/engine@0.5.0-dev.15095.c10283ee6c8f(48eb1dc1d1b0f9a6a9ad276467f438dc)':
     dependencies:
       '@bokuweb/zstd-wasm': 0.0.27
       '@deepseek-ai/cosmokit': 1.8.5
@@ -1645,7 +1643,6 @@ snapshots:
       acorn: 8.16.0
       ajv: 8.20.0
       chokidar: 4.0.3
-      core-js-pure: 3.50.0
       css-tree: 3.2.1
       draco3dgltf: 1.5.7
       earcut: 3.2.4
@@ -1914,8 +1911,6 @@ snapshots:
 
   convert-source-map@2.0.0: {}
 
-  core-js-pure@3.50.0: {}
-
   css-select@7.0.0:
     dependencies:
       boolbase: 2.0.0

package/sdk/templates/empty/pnpm-workspace.yaml

@@ -3,8 +3,6 @@ allowBuilds:
   '@forgeax/engine-codec': true
   '@forgeax/engine-fbx': true
   '@forgeax/engine-wgpu-wasm': true
-  # Its postinstall only prints a funding notice.
-  core-js-pure: false
   esbuild: true
   webgpu: true
 

package/sdk/templates/game-3d/assets/__tests__/uv-primitives.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, it } from 'vitest';
+import type { MeshAsset } from '@forgeax/engine/types';
+import pack from '../uv-primitives.pack.ts';
+
+async function meshes(): Promise<Record<string, MeshAsset>> {
+  const result = await pack.build(undefined as never);
+  if (!result.ok) throw result.error;
+  return result.value as Record<string, MeshAsset>;
+}
+
+type Point = readonly [number, number];
+function overlap(a: readonly Point[], b: readonly Point[]): boolean {
+  for (const triangle of [a, b]) {
+    for (let edge = 0; edge < 3; edge += 1) {
+      const start = triangle[edge]!;
+      const end = triangle[(edge + 1) % 3]!;
+      const axis = [end[1] - start[1], start[0] - end[0]];
+      const project = (points: readonly Point[]) => points.map(([u, v]) => u * axis[0]! + v * axis[1]!);
+      const pa = project(a);
+      const pb = project(b);
+      if (Math.min(Math.max(...pa), Math.max(...pb)) - Math.max(Math.min(...pa), Math.min(...pb)) <= 1e-9) return false;
+    }
+  }
+  return true;
+}
+
+describe('UV primitives authoring', () => {
+  it('produces exactly three deterministic fixed meshes', async () => {
+    const first = await meshes();
+    expect(Object.keys(first)).toEqual(['mesh/triangular-ramp', 'mesh/half-cylinder', 'mesh/quarter-cylinder']);
+    expect(await meshes()).toEqual(first);
+  });
+
+  for (const [key, count, volume, islandCount] of [
+    ['mesh/triangular-ramp', 8, 4, 5],
+    ['mesh/half-cylinder', 132, 32 * Math.sin(Math.PI / 32), 4],
+    ['mesh/quarter-cylinder', 68, 16 * Math.sin(Math.PI / 32), 5],
+  ] as const) {
+    it(`${key}: closed, outward, nondegenerate, with separated proportional UV islands`, async () => {
+      const mesh = (await meshes())[key]!;
+      const positions = mesh.attributes.position as Float32Array;
+      const normals = mesh.attributes.normal as Float32Array;
+      const uv = mesh.attributes.uv as Float32Array;
+      const indices = mesh.indices!;
+      expect(indices.length / 3).toBe(count);
+      for (const value of uv) expect(value).toBeGreaterThan(0);
+      for (const value of uv) expect(value).toBeLessThan(1);
+      const triangles: Point[][] = [];
+      const edges = new Map<string, number>();
+      const density: number[] = [];
+      const parent = Array.from({ length: positions.length / 3 }, (_, i) => i);
+      const root = (i: number): number => parent[i] === i ? i : root(parent[i]!);
+      const pointKey = (i: number) => Array.from(positions.slice(i * 3, i * 3 + 3), (v) => v.toFixed(5)).join(',');
+      let signedVolume = 0;
+      for (let index = 0; index < indices.length; index += 3) {
+        const ids = [indices[index]!, indices[index + 1]!, indices[index + 2]!];
+        const [a, b, c] = ids.map((id) => Array.from(positions.slice(id * 3, id * 3 + 3)));
+        const ab = b!.map((v, axis) => v - a![axis]!);
+        const ac = c!.map((v, axis) => v - a![axis]!);
+        const cross = [ab[1]! * ac[2]! - ab[2]! * ac[1]!, ab[2]! * ac[0]! - ab[0]! * ac[2]!, ab[0]! * ac[1]! - ab[1]! * ac[0]!];
+        const area = Math.hypot(...cross) / 2;
+        expect(area).toBeGreaterThan(1e-6);
+        expect(cross.reduce((sum, v, axis) => sum + v * normals[ids[0]! * 3 + axis]!, 0)).toBeGreaterThan(0);
+        signedVolume += (a![0]! * (b![1]! * c![2]! - b![2]! * c![1]!) + a![1]! * (b![2]! * c![0]! - b![0]! * c![2]!) + a![2]! * (b![0]! * c![1]! - b![1]! * c![0]!)) / 6;
+        const triangle: Point[] = ids.map((id) => [uv[id * 2]!, uv[id * 2 + 1]!]);
+        const [u, v, w] = triangle;
+        const uvArea = Math.abs((v![0] - u![0]) * (w![1] - u![1]) - (v![1] - u![1]) * (w![0] - u![0])) / 2;
+        expect(uvArea).toBeGreaterThan(1e-7);
+        density.push(uvArea / area);
+        triangles.push(triangle);
+        for (let edge = 0; edge < 3; edge += 1) {
+          const current = ids[edge]!;
+          const next = ids[(edge + 1) % 3]!;
+          parent[root(current)] = root(next);
+          const edgeKey = [pointKey(current), pointKey(next)].sort().join('|');
+          edges.set(edgeKey, (edges.get(edgeKey) ?? 0) + 1);
+        }
+      }
+      expect(signedVolume).toBeCloseTo(volume, 5);
+      expect([...edges.values()].every((uses) => uses === 2)).toBe(true);
+      expect(new Set(parent.map((_, i) => root(i))).size).toBe(islandCount);
+      expect(Math.max(...density) / Math.min(...density)).toBeLessThan(1.003);
+      for (let a = 0; a < triangles.length; a += 1) {
+        for (let b = a + 1; b < triangles.length; b += 1) expect(overlap(triangles[a]!, triangles[b]!)).toBe(false);
+      }
+    });
+  }
+});

package/sdk/templates/game-3d/assets/uv-primitives.pack.ts

@@ -0,0 +1,155 @@
+import { meshFromInterleaved } from '@forgeax/engine/geometry';
+import { definePack, definePackageId } from '@forgeax/engine/pack/source';
+import { ok } from '@forgeax/engine/types';
+import { assetGuid, PACKAGE_IDS } from './shared/asset-refs.ts';
+
+type Point = readonly [number, number, number];
+type Uv = readonly [number, number];
+interface Island {
+  vertices: number[];
+  indices: number[];
+  width: number;
+  height: number;
+}
+
+const HEIGHT = 2;
+const RADIUS = 1;
+const GUTTER = 0.12;
+
+function face(points: readonly Point[], normal: Point, uvs: readonly Uv[], width: number, height: number): Island {
+  return {
+    vertices: points.flatMap((point, index) => [...point, ...normal, ...uvs[index]!]),
+    indices: points.length === 3 ? [0, 1, 2] : [0, 1, 2, 0, 2, 3],
+    width,
+    height,
+  };
+}
+
+const rectangleUvs = (width: number, height: number): Uv[] => [[0, 0], [width, 0], [width, height], [0, height]];
+
+function ramp(): Island[] {
+  const a: Point = [-1, 0, -1];
+  const b: Point = [1, 0, -1];
+  const c: Point = [1, 0, 1];
+  const d: Point = [-1, 0, 1];
+  const e: Point = [-1, HEIGHT, 1];
+  const f: Point = [1, HEIGHT, 1];
+  const slope = Math.hypot(2, HEIGHT);
+  return [
+    face([a, b, c, d], [0, -1, 0], rectangleUvs(2, 2), 2, 2),
+    face([a, b, f, e], [0, 2 / slope, -HEIGHT / slope], rectangleUvs(2, slope), 2, slope),
+    face([d, c, f, e], [0, 0, 1], rectangleUvs(2, HEIGHT), 2, HEIGHT),
+    face([a, d, e], [-1, 0, 0], [[0, 0], [2, 0], [2, HEIGHT]], 2, HEIGHT),
+    face([b, c, f], [1, 0, 0], [[0, 0], [2, 0], [2, HEIGHT]], 2, HEIGHT),
+  ];
+}
+
+function cylinderSector(angle: number, segments: number): Island[] {
+  const arcLength = RADIUS * angle;
+  const strip: Island = { vertices: [], indices: [], width: arcLength, height: HEIGHT };
+  const capWidth = angle === Math.PI ? 2 * RADIUS : RADIUS;
+  const caps = [0, HEIGHT].map((y): Island => {
+    const normal: Point = [0, y === 0 ? -1 : 1, 0];
+    const offsetX = angle === Math.PI ? RADIUS : 0;
+    const vertices = [0, y, 0, ...normal, offsetX, 0];
+    const indices: number[] = [];
+    for (let step = 0; step <= segments; step += 1) {
+      const theta = angle * step / segments;
+      const x = RADIUS * Math.cos(theta);
+      const z = RADIUS * Math.sin(theta);
+      vertices.push(x, y, z, ...normal, offsetX + x, z);
+      if (step > 0) indices.push(0, step, step + 1);
+    }
+    return { vertices, indices, width: capWidth, height: RADIUS };
+  });
+
+  // Each angular column is shared along the curved surface, including its UV seam endpoints.
+  for (let step = 0; step <= segments; step += 1) {
+    const theta = angle * step / segments;
+    const x = Math.cos(theta);
+    const z = Math.sin(theta);
+    for (const y of [0, HEIGHT]) {
+      strip.vertices.push(RADIUS * x, y, RADIUS * z, x, 0, z, RADIUS * theta, y);
+    }
+    if (step < segments) {
+      const current = step * 2;
+      strip.indices.push(current, current + 2, current + 3, current, current + 3, current + 1);
+    }
+  }
+
+  const diameter: Island = { vertices: [], indices: [0, 2, 3, 0, 3, 1, 2, 4, 5, 2, 5, 3], width: 2 * RADIUS, height: HEIGHT };
+  for (const x of [RADIUS, 0, -RADIUS]) {
+    for (const y of [0, HEIGHT]) diameter.vertices.push(x, y, 0, 0, 0, -1, RADIUS - x, y);
+  }
+  const cuts = angle === Math.PI
+    ? [diameter]
+    : [
+      face([[0, 0, 0], [RADIUS, 0, 0], [RADIUS, HEIGHT, 0], [0, HEIGHT, 0]], [0, 0, -1], rectangleUvs(RADIUS, HEIGHT), RADIUS, HEIGHT),
+      face([[0, 0, 0], [0, 0, RADIUS], [0, HEIGHT, RADIUS], [0, HEIGHT, 0]], [-1, 0, 0], rectangleUvs(RADIUS, HEIGHT), RADIUS, HEIGHT),
+    ];
+  return [...caps, strip, ...cuts];
+}
+
+function buildMesh(islands: readonly Island[], rowWidth: number) {
+  const vertices: number[] = [];
+  const indices: number[] = [];
+  let x = GUTTER;
+  let y = GUTTER;
+  let rowHeight = 0;
+  let atlasWidth = 0;
+  for (const island of islands) {
+    if (x > GUTTER && x + island.width + GUTTER > rowWidth) {
+      x = GUTTER;
+      y += rowHeight + GUTTER;
+      rowHeight = 0;
+    }
+    const base = vertices.length / 8;
+    for (let offset = 0; offset < island.vertices.length; offset += 8) {
+      vertices.push(...island.vertices.slice(offset, offset + 6), island.vertices[offset + 6]! + x, island.vertices[offset + 7]! + y);
+    }
+    indices.push(...island.indices.map((index) => index + base));
+    x += island.width + GUTTER;
+    atlasWidth = Math.max(atlasWidth, x);
+    rowHeight = Math.max(rowHeight, island.height);
+  }
+
+  // One uniform scale preserves texel density and the circular cap shapes across all islands.
+  const atlasHeight = y + rowHeight + GUTTER;
+  const extent = Math.max(atlasWidth, atlasHeight);
+  for (let offset = 0; offset < vertices.length; offset += 8) {
+    vertices[offset + 6] = (vertices[offset + 6]! + (extent - atlasWidth) / 2) / extent;
+    vertices[offset + 7] = (vertices[offset + 7]! + (extent - atlasHeight) / 2) / extent;
+  }
+  for (let offset = 0; offset < indices.length; offset += 3) {
+    const a = indices[offset]! * 8;
+    const b = indices[offset + 1]! * 8;
+    const c = indices[offset + 2]! * 8;
+    const ab = [0, 1, 2].map((axis) => vertices[b + axis]! - vertices[a + axis]!);
+    const ac = [0, 1, 2].map((axis) => vertices[c + axis]! - vertices[a + axis]!);
+    const cross = [ab[1]! * ac[2]! - ab[2]! * ac[1]!, ab[2]! * ac[0]! - ab[0]! * ac[2]!, ab[0]! * ac[1]! - ab[1]! * ac[0]!];
+    const alignment = cross.reduce((sum, value, axis) => sum + value * (vertices[a + 3 + axis]! + vertices[b + 3 + axis]! + vertices[c + 3 + axis]!), 0);
+    if (alignment < 0) [indices[offset + 1], indices[offset + 2]] = [indices[offset + 2]!, indices[offset + 1]!];
+  }
+  const result = meshFromInterleaved(new Float32Array(vertices), new Uint32Array(indices));
+  if (!result.ok) return result;
+  return ok({ ...result.value, materialSlots: [{ slotName: 'Surface', defaultMaterial: assetGuid(PACKAGE_IDS.materials, 'material/white') }] });
+}
+
+export default definePack({
+  schemaVersion: '2.0.0',
+  packageId: definePackageId('01a15d30-7190-7000-8000-000000000000'),
+  name: 'Game 3D / UV Primitives',
+  build: () => {
+    const triangularRamp = buildMesh(ramp(), 6.5);
+    if (!triangularRamp.ok) return triangularRamp;
+    const halfCylinder = buildMesh(cylinderSector(Math.PI, 32), 4.5);
+    if (!halfCylinder.ok) return halfCylinder;
+    const quarterCylinder = buildMesh(cylinderSector(Math.PI / 2, 16), 3.5);
+    if (!quarterCylinder.ok) return quarterCylinder;
+    return ok({
+      'mesh/triangular-ramp': triangularRamp.value,
+      'mesh/half-cylinder': halfCylinder.value,
+      'mesh/quarter-cylinder': quarterCylinder.value,
+    });
+  },
+});

package/sdk/templates/game-3d/docs/feedback.md

@@ -3,6 +3,15 @@
 记录开发期间确认的 Engine、SDK、模板、构建、资产、运行时或浏览器问题。该文件会和根
 `README.md` 一起原样进入 Web ZIP；不要写入 token、密码、私有 URL 或其他敏感信息。
 
+### 2026-10-21 — Local worktree project check cannot resolve template lockfile
+
+- Scope: local template dependency verification
+- Reproduction: run `node packages/devkit/dist/cli.mjs project check --root templates/game-3d --json` from the mesh-uv-preview Engine worktree.
+- Expected: verify the installed Game 3D dependency closure.
+- Actual: `project-pnpm-record-unreadable` reports a missing `templates/pnpm-lock.yaml`; the verifier selects the containing templates directory for its pnpm record.
+- Evidence: the same project's TypeScript check and all 44 tests pass; the native View Catalog publishes all three `uv-primitives.pack.ts` outputs and renders the half-cylinder with its UV0 layout.
+- Status: open — local project-check environment limitation; no dependency files or verification policy were changed to bypass it.
+
 ### 2026-10-20 — Showcase contact shadows lost after inheriting camera-wide CSM coverage
 
 - Scope: template

package/sdk/templates/game-3d/docs/uv-primitives.md

@@ -0,0 +1,38 @@
+# UV primitives
+
+`assets/uv-primitives.pack.ts` is a fixed, build-time procedural Pack with exactly
+three mesh outputs. It uses the project's existing white material and the normal
+Pack producer, Catalog and mesh preview path. No runtime generator is installed.
+
+| Source key | Shape | Triangles | UV0 islands |
+|:--|:--|--:|--:|
+| `mesh/triangular-ramp` | 2 x 2 x 2 triangular prism | 8 | 5 |
+| `mesh/half-cylinder` | Radius 1, height 2, 180 degrees, 32 arc segments | 132 | 4 |
+| `mesh/quarter-cylinder` | Radius 1, height 2, 90 degrees, 16 arc segments | 68 | 5 |
+
+Y is up. Cylindrical caps retain their semicircle/quarter-circle outlines and
+radial triangle fans. The curved surface unwraps by arc length into a continuous
+rectangular strip with matching angular columns. Cut faces have separate planar
+islands; the half-cylinder's diameter is split at the cap center to keep the solid
+watertight. Normals are smooth on the arc and hard at cap/cut boundaries.
+
+All UV0 islands are inside 0-1 without overlap, with one uniform physical scale
+and 0.12 model-unit gutters before normalization. There is no extra UV channel:
+select **UV channel 0** in View. The small difference between curved strip and
+faceted triangle area is bounded by the 5.625-degree angular sampling.
+
+The layout follows the seam/unwrapping/island packing principles described in
+[Epic's UV tools documentation](https://dev.epicgames.com/documentation/en-us/unreal-engine/uvs-category-in-unreal-engine).
+The reference images guide the shape and topology, not stored geometry data.
+
+Template disposition: retain the existing runtime/controller, player/animation,
+scene composition, materials, lighting, UI and template tests because this task
+adds inspection assets to the Game 3D capability reference, not a new game.
+Only the three requested meshes and their tests/documentation are added.
+
+Local validation on 2026-10-21: all 44 project tests and `tsc --noEmit` pass.
+The native producer publishes all three outputs in the live Game 3D Catalog;
+View renders the half-cylinder and its four UV0 islands. `asset verify` admits
+the Pack source identity, but that command alone does not execute generation.
+The separate `project check` dependency-record limitation is recorded in
+`feedback.md`.

package/sdk/templates/game-3d/package.json

@@ -40,7 +40,7 @@
     }
   },
   "dependencies": {
-    "@forgeax/engine": "0.5.0-dev.15093.89d287422343"
+    "@forgeax/engine": "0.5.0-dev.15095.c10283ee6c8f"
   },
   "devDependencies": {
     "@types/node": "20.19.40",

package/sdk/templates/game-3d/pnpm-lock.yaml

@@ -167,8 +167,8 @@ importers:
   .:
     dependencies:
       '@forgeax/engine':
-        specifier: 0.5.0-dev.15093.89d287422343
-        version: 0.5.0-dev.15093.89d287422343(48eb1dc1d1b0f9a6a9ad276467f438dc)
+        specifier: 0.5.0-dev.15095.c10283ee6c8f
+        version: 0.5.0-dev.15095.c10283ee6c8f(48eb1dc1d1b0f9a6a9ad276467f438dc)
     devDependencies:
       '@types/node':
         specifier: 20.19.40
@@ -528,8 +528,8 @@ packages:
   '@fontsource-variable/noto-sans-sc@5.3.0':
     resolution: {integrity: sha512-lNar1dF7Ik/lHNPo/7JWG0TolXY29LtsqYgMvEysooZ5bsO9uH4shJmRrwyJ3PjyTPljhpMJEK0jDuLSU4vJ1w==, tarball: https://registry.npmjs.org/@fontsource-variable/noto-sans-sc/-/noto-sans-sc-5.3.0.tgz}
 
-  '@forgeax/engine@0.5.0-dev.15093.89d287422343':
-    resolution: {integrity: sha512-+zzY53UNxLfS83MBaNfwWVnquqRAqObpsnXGIsYfC4ogdXTg3fbfCTn/VKq2ENl126jxycX1bQwEl18CIx00Rw==}
+  '@forgeax/engine@0.5.0-dev.15095.c10283ee6c8f':
+    resolution: {integrity: sha512-Nqhf+87EZBjq+TrsevtiTbAKYCHu2ys9gG3f6eMkINluzE0c58u4EWRkthA1iy35k0xfMUopuVbEDEbuY26aog==}
     hasBin: true
     bundledDependencies:
       - '@deepseek-ai/cordis'
@@ -611,6 +611,7 @@ packages:
       - '@forgeax/engine-vite-plugin-rhi-debug'
       - '@forgeax/engine-vite-plugin-shader'
       - '@forgeax/engine-wgpu-wasm'
+      - core-js-pure
 
   '@jridgewell/sourcemap-codec@1.6.0':
     resolution: {integrity: sha512-T7jf+5zgsZHwNJ4lvQ7/aezbyk0nNX+zJVWpmHA7VYsEx7a7qr5Rg5IbtJFqkgze5Y2sruq1RUY8Q837Od7iFw==, tarball: https://registry.npmjs.org/@jridgewell/sourcemap-codec/-/sourcemap-codec-1.6.0.tgz}
@@ -861,9 +862,6 @@ packages:
   convert-source-map@2.0.0:
     resolution: {integrity: sha512-Kvp459HrV2FEJ1CAsi1Ku+MY3kasH19TFykTz2xWmMeq6bk2NU3XXvfJ+Q61m0xktWwt+1HSYf3JZsTms3aRJg==, tarball: https://registry.npmjs.org/convert-source-map/-/convert-source-map-2.0.0.tgz}
 
-  core-js-pure@3.50.0:
-    resolution: {integrity: sha512-6GP3Pxz4IKyWjAfa747vIu/jilB5z29JWROLqH/b+pXVcpgh6tM06ZIBwSuglgVqzDYURhOK6oEzTrG0bCHitA==, tarball: https://registry.npmjs.org/core-js-pure/-/core-js-pure-3.50.0.tgz}
-
   css-select@7.0.0:
     resolution: {integrity: sha512-snmjEVXy+1LnwXdxhYvTMj1d9tOh4HxkA1YmoayVBeeyR2C14Pum7fcxJIm4SswYspVy866eYNwlH6xC3/VH5g==, tarball: https://registry.npmjs.org/css-select/-/css-select-7.0.0.tgz}
     engines: {node: '>=20.19.0'}
@@ -1623,7 +1621,7 @@ snapshots:
 
   '@fontsource-variable/noto-sans-sc@5.3.0': {}
 
-  '@forgeax/engine@0.5.0-dev.15093.89d287422343(48eb1dc1d1b0f9a6a9ad276467f438dc)':
+  '@forgeax/engine@0.5.0-dev.15095.c10283ee6c8f(48eb1dc1d1b0f9a6a9ad276467f438dc)':
     dependencies:
       '@bokuweb/zstd-wasm': 0.0.27
       '@deepseek-ai/cosmokit': 1.8.5
@@ -1645,7 +1643,6 @@ snapshots:
       acorn: 8.16.0
       ajv: 8.20.0
       chokidar: 4.0.3
-      core-js-pure: 3.50.0
       css-tree: 3.2.1
       draco3dgltf: 1.5.7
       earcut: 3.2.4
@@ -1914,8 +1911,6 @@ snapshots:
 
   convert-source-map@2.0.0: {}
 
-  core-js-pure@3.50.0: {}
-
   css-select@7.0.0:
     dependencies:
       boolbase: 2.0.0

package/sdk/templates/game-3d/pnpm-workspace.yaml

@@ -3,8 +3,6 @@ allowBuilds:
   '@forgeax/engine-codec': true
   '@forgeax/engine-fbx': true
   '@forgeax/engine-wgpu-wasm': true
-  # Its postinstall only prints a funding notice.
-  core-js-pure: false
   esbuild: true
   webgpu: true
 

package/sdk/templates/game-3d/scripts/runtime-vase-probe.mjs

@@ -5,9 +5,15 @@ import { join } from 'node:path';
 /** Shared by Preview and the generated DevKit project's main/Worker browser gates. */
 export async function probeRuntimeVase(page, read, evidenceDir, capture = options => page.screenshot(options)) {
   const settleRender = async () => {
-    const before = await page.evaluate(() => Number(document.documentElement.dataset.forgeaxFrameSubmitted ?? 0));
-    await page.waitForFunction(frame => Number(document.documentElement.dataset.forgeaxFrameSubmitted ?? 0) >= frame + 2,
-      before, { timeout: 60_000 });
+    const before = await page.evaluate(
+      () => document.querySelector('canvas')?.forgeaxFrameProgress?.submitted?.frameId ?? 0,
+    );
+    await page.waitForFunction(
+      (previousFrameId) =>
+        (document.querySelector('canvas')?.forgeaxFrameProgress?.submitted?.frameId ?? 0) >= previousFrameId + 2,
+      before,
+      { timeout: 60_000 },
+    );
   };
   const panel = page.getByRole('region', { name: 'Runtime vase' });
   await panel.waitFor({ timeout: 120_000 });

package/sdk/toolchain/cli-runtime/package.json

@@ -4,7 +4,7 @@
   "type": "module",
   "packageManager": "pnpm@12.10.1",
   "dependencies": {
-    "@forgeax/engine": "0.5.0-dev.15093.89d287422343",
-    "@forgeax/view": "0.5.0-dev.15093.89d287422343"
+    "@forgeax/engine": "0.5.0-dev.15095.c10283ee6c8f",
+    "@forgeax/view": "0.5.0-dev.15095.c10283ee6c8f"
   }
 }