@forgeax/engine-geometry 0.1.2

package/src/index.ts

@@ -0,0 +1,52 @@
+// @forgeax/engine-geometry - single-import barrel.
+//
+// AI users get the procedural geometry factories under one namespace import,
+// each returning `Result<MeshAsset, AssetError>` (charter F1 single-entry
+// indexability; P3 explicit failure). Alongside them: the vertex attribute
+// layout SSOT (deriveVertexBufferLayout / buildMeshAttributeMapForUvSets /
+// GpuVertexBufferLayoutEntry) and the tangent helper (computeTangentVec4)
+// consumed by the runtime pipeline + material layers.
+//
+// Attribute layout (all factories): position (3 floats) + normal (3 floats) +
+// uv (2 floats), expanded to the 12-float runtime layout (adds tangent vec4)
+// by meshFromInterleaved / PROCEDURAL_FLOATS_PER_VERTEX.
+
+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,
+  PROCEDURAL_FLOATS_PER_VERTEX,
+} from './box';
+export { createCapsuleGeometry } from './capsule';
+export { createConeGeometry } from './cone';
+export { createCylinderGeometry } from './cylinder';
+export {
+  compute2dBounds,
+  create2dGeometry,
+  create2dRingGeometry,
+  type Shape2d,
+  type Shape2dBounds,
+  type Shape2dMeshOptions,
+  type Shape2dPose,
+  type Vec2,
+} from './dim2';
+export { createPlaneGeometry } from './plane';
+export { createSphereGeometry } from './sphere';
+export { computeTangentVec4 } from './tangent';
+export { createTorusGeometry } from './torus';
+export {
+  buildMeshAttributeMapForUvSets,
+  deriveVertexBufferLayout,
+  deriveVertexBufferLayoutFromProjection,
+  deriveVertexLayoutProjection,
+  deriveVertexLayoutProjectionFromMask,
+  type GpuVertexBufferLayoutEntry,
+  type PackedVertexAttributes,
+  packInterleavedVertexAttributes,
+  VertexAttributePackError,
+  type VertexLayoutProjection,
+  type VertexLayoutProjectionAttribute,
+  type VertexLayoutProjectionMaskError,
+} from './vertex-attribute-layout';

package/src/plane.ts

@@ -0,0 +1,78 @@
+// @forgeax/engine-runtime - Procedural Plane geometry (M3 / w8).
+//
+// Mirrors Three.js r184 PlaneGeometry: createPlaneGeometry(width, height,
+// widthSegments?, heightSegments?) -> Result<MeshAsset, AssetError>. The plane
+// lies on the XY plane with +Z normal (standard three.js orientation).
+// Degenerate parameters fail-fast with AssetError('asset-parse-failed').
+//
+// Related: requirements §AC-06 / §AC-14; plan-strategy §M3 + D-P5;
+//          plan-tasks.json w8 acceptanceCheck.
+
+import type { AssetError, MeshAsset } from '@forgeax/engine-types';
+import { err, type Result } from '@forgeax/engine-types';
+import { degenerate, FACTORY_FLOATS_PER_VERTEX, meshFromInterleaved } from './box';
+
+export function createPlaneGeometry(
+  width: number,
+  height: number,
+  widthSegments: number = 1,
+  heightSegments: number = 1,
+): Result<MeshAsset, AssetError> {
+  if (width <= 0 || height <= 0) {
+    return err(degenerate(`width=${width}, height=${height}`));
+  }
+  const ws = widthSegments | 0;
+  const hs = heightSegments | 0;
+  if (ws < 1 || hs < 1) {
+    return err(degenerate(`widthSegments=${ws}, heightSegments=${hs}`));
+  }
+
+  const halfW = width / 2;
+  const halfH = height / 2;
+  const gridX1 = ws + 1;
+  const gridY1 = hs + 1;
+  const segW = width / ws;
+  const segH = height / hs;
+
+  const vertexCount = gridX1 * gridY1;
+  const indexCount = ws * hs * 6;
+  const vertices = new Float32Array(vertexCount * FACTORY_FLOATS_PER_VERTEX);
+  const indices = new Uint32Array(indexCount);
+
+  let vIdx = 0;
+  for (let iy = 0; iy < gridY1; iy++) {
+    const y = iy * segH - halfH;
+    for (let ix = 0; ix < gridX1; ix++) {
+      const x = ix * segW - halfW;
+      const base = vIdx * FACTORY_FLOATS_PER_VERTEX;
+      vertices[base + 0] = x;
+      vertices[base + 1] = -y;
+      vertices[base + 2] = 0;
+      vertices[base + 3] = 0;
+      vertices[base + 4] = 0;
+      vertices[base + 5] = 1;
+      vertices[base + 6] = ix / ws;
+      // UV.v uses the WebGPU top-left convention (V=0 = image top).
+      vertices[base + 7] = iy / hs;
+      vIdx++;
+    }
+  }
+
+  let iIdx = 0;
+  for (let iy = 0; iy < hs; iy++) {
+    for (let ix = 0; ix < ws; ix++) {
+      const a = ix + gridX1 * iy;
+      const b = ix + gridX1 * (iy + 1);
+      const c = ix + 1 + gridX1 * (iy + 1);
+      const d = ix + 1 + gridX1 * iy;
+      indices[iIdx++] = a;
+      indices[iIdx++] = b;
+      indices[iIdx++] = d;
+      indices[iIdx++] = b;
+      indices[iIdx++] = c;
+      indices[iIdx++] = d;
+    }
+  }
+
+  return meshFromInterleaved(vertices, indices);
+}

package/src/sphere.ts

@@ -0,0 +1,82 @@
+// @forgeax/engine-runtime - Procedural Sphere geometry (M3 / w8).
+//
+// Mirrors Three.js r184 SphereGeometry signature:
+// createSphereGeometry(radius, widthSegments?, heightSegments?) ->
+// Result<MeshAsset, AssetError>. Degenerate parameters (radius <= 0, widthSegments
+// < 3, heightSegments < 2) fail-fast with AssetError('asset-parse-failed').
+//
+// Related: requirements §AC-06 / §AC-14; plan-strategy §M3 + D-P5;
+//          plan-tasks.json w8 acceptanceCheck.
+
+import type { AssetError, MeshAsset } from '@forgeax/engine-types';
+import { err, type Result } from '@forgeax/engine-types';
+import { degenerate, FACTORY_FLOATS_PER_VERTEX, meshFromInterleaved } from './box';
+
+export function createSphereGeometry(
+  radius: number,
+  widthSegments: number = 16,
+  heightSegments: number = 12,
+): Result<MeshAsset, AssetError> {
+  if (radius <= 0) return err(degenerate(`radius=${radius}`));
+  const ws = widthSegments | 0;
+  const hs = heightSegments | 0;
+  if (ws < 3) return err(degenerate(`widthSegments=${ws}; minimum 3`));
+  if (hs < 2) return err(degenerate(`heightSegments=${hs}; minimum 2`));
+
+  const vertexCount = (ws + 1) * (hs + 1);
+  const indexCount = ws * hs * 6;
+  const vertices = new Float32Array(vertexCount * FACTORY_FLOATS_PER_VERTEX);
+  const indices = new Uint32Array(indexCount);
+
+  let vIdx = 0;
+  for (let iy = 0; iy <= hs; iy++) {
+    const v = iy / hs;
+    const phi = v * Math.PI;
+    for (let ix = 0; ix <= ws; ix++) {
+      const u = ix / ws;
+      const theta = u * Math.PI * 2;
+      const x = -radius * Math.cos(theta) * Math.sin(phi);
+      const y = radius * Math.cos(phi);
+      const z = radius * Math.sin(theta) * Math.sin(phi);
+      const nx = x / radius;
+      const ny = y / radius;
+      const nz = z / radius;
+      const base = vIdx * FACTORY_FLOATS_PER_VERTEX;
+      vertices[base + 0] = x;
+      vertices[base + 1] = y;
+      vertices[base + 2] = z;
+      vertices[base + 3] = nx;
+      vertices[base + 4] = ny;
+      vertices[base + 5] = nz;
+      vertices[base + 6] = u;
+      // UV.v uses the WebGPU top-left convention (V=0 = image top).
+      vertices[base + 7] = v;
+      vIdx++;
+    }
+  }
+
+  let iIdx = 0;
+  const stride = ws + 1;
+  for (let iy = 0; iy < hs; iy++) {
+    for (let ix = 0; ix < ws; ix++) {
+      const a = iy * stride + ix + 1;
+      const b = iy * stride + ix;
+      const c = (iy + 1) * stride + ix;
+      const d = (iy + 1) * stride + ix + 1;
+      if (iy !== 0) {
+        indices[iIdx++] = a;
+        indices[iIdx++] = b;
+        indices[iIdx++] = d;
+      }
+      if (iy !== hs - 1) {
+        indices[iIdx++] = b;
+        indices[iIdx++] = c;
+        indices[iIdx++] = d;
+      }
+    }
+  }
+
+  // trim unused tail (pole rows contribute fewer triangles than the prealloc estimate)
+  const trimmed = indices.slice(0, iIdx);
+  return meshFromInterleaved(vertices, trimmed);
+}

package/src/tangent.ts

@@ -0,0 +1,320 @@
+// @forgeax/engine-runtime - per-vertex tangent (vec4) helper (M4 / w20).
+//
+// Implements the path A formula (LearnOpenGL section 5.4 + glTF 2.0 vec4
+// shape) for procedural geometry: per-triangle UV-derivative tangent ->
+// face-area-weighted average -> Gram-Schmidt re-orthogonalisation against
+// the supplied per-vertex normal -> handedness sign(det(deltaUV)) packed
+// into the .w channel.
+//
+// Output shape: Float32Array (vertexCount * 4) where each vertex is
+// [tx, ty, tz, w] with `.w` in {+1, -1}. The .w sign is forward-compatible
+// with glTF 2.0 spec / MikkTSpace baker (`B = cross(N, T.xyz) * T.w`),
+// satisfying feat-20260518 risk R-4 mitigation (path A vec4 -> path B
+// shader consumption is a no-op switch).
+//
+// Plan-strategy anchors: section 2 D-2 (path A); D-7 (single-file helper to
+// avoid 30-line per-geometry re-implementation -- SSOT #1 + DRY #2).
+// Knowledge-base anchor: .forgeax-harness/knowledge-base/wiki/normal-mapping-and-tbn.md
+// section 2 (math skeleton) and section 2.2 (per-vertex average +
+// handedness). Risk anchor: R-4 (vec4 + .w forward compatibility).
+//
+// Pure function with shared Result/AssetError vocabulary and no mutable state
+// or side effects. Indices may be Uint16Array, Uint32Array, or
+// undefined (sequential 0..vertexCount-1 -- triangle list). Degenerate
+// triangles (zero area UV; det ~ 0) are skipped from the accumulation;
+// vertices touched only by degenerate triangles fall back to a stable
+// frame: tangent perpendicular to the supplied normal with .w = +1.
+
+import { ASSET_ERROR_HINTS, AssetError, err, ok, type Result } from '@forgeax/engine-types';
+
+const EPSILON = 1e-8;
+
+function tangentInputError(field: string, value: number, reason: string): AssetError {
+  return new AssetError({
+    code: 'asset-parse-failed',
+    expected: `valid tangent topology: ${reason}`,
+    hint: ASSET_ERROR_HINTS['asset-parse-failed'],
+    detail: { field, value, reason },
+  });
+}
+
+function preflightTangentInput(
+  positions: Float32Array,
+  normals: Float32Array,
+  uvs: Float32Array,
+  indices: Uint16Array | Uint32Array | undefined,
+): Result<number, AssetError> {
+  if (positions.length % 3 !== 0) {
+    return err(
+      tangentInputError(
+        'positions',
+        positions.length,
+        'positions.length must be divisible by the position stride of 3',
+      ),
+    );
+  }
+  const vertexCount = positions.length / 3;
+  if (normals.length !== vertexCount * 3) {
+    return err(
+      tangentInputError(
+        'normals',
+        normals.length,
+        `normals.length must equal vertexCount * 3 (${vertexCount * 3})`,
+      ),
+    );
+  }
+  if (uvs.length !== vertexCount * 2) {
+    return err(
+      tangentInputError(
+        'uvs',
+        uvs.length,
+        `uvs.length must equal vertexCount * 2 (${vertexCount * 2})`,
+      ),
+    );
+  }
+  if (indices === undefined) {
+    if (vertexCount % 3 !== 0) {
+      return err(
+        tangentInputError(
+          'positions',
+          vertexCount,
+          'non-indexed vertexCount must be divisible by the triangle size of 3',
+        ),
+      );
+    }
+    return ok(vertexCount);
+  }
+  if (indices.length % 3 !== 0) {
+    return err(
+      tangentInputError(
+        'indices',
+        indices.length,
+        'indices.length must be divisible by the triangle size of 3',
+      ),
+    );
+  }
+  for (let indexPosition = 0; indexPosition < indices.length; indexPosition++) {
+    const index = indices[indexPosition];
+    if (index === undefined || !Number.isInteger(index) || index < 0 || index >= vertexCount) {
+      return err(
+        tangentInputError(
+          'indices',
+          index ?? -1,
+          `indices[${indexPosition}] must be an integer in [0, ${vertexCount})`,
+        ),
+      );
+    }
+  }
+  return ok(vertexCount);
+}
+
+/**
+ * Compute per-vertex tangent (vec4) for a procedural mesh using path A
+ * (UV-derivative + face-area-weighted average + Gram-Schmidt + handedness).
+ *
+ * @param positions Float32Array, vertexCount * 3 (xyz interleaved).
+ * @param normals Float32Array, vertexCount * 3 (xyz interleaved); must be
+ *   pre-normalised by the caller (procedural factories already produce
+ *   unit-length normals at vertex emit time).
+ * @param uvs Float32Array, vertexCount * 2 (uv interleaved).
+ * @param indices optional Uint16Array | Uint32Array triangle list; when
+ *   undefined, sequential triangulation 0,1,2,3,4,5,... is assumed.
+ * @returns `Result<Float32Array, AssetError>` with a Float32Array of
+ *   vertexCount * 4 on success. `.xyz` is the tangent and `.w` is the
+ *   handedness sign in {+1, -1}; malformed topology returns the existing
+ *   `asset-parse-failed` AssetError before working or output buffers exist.
+ *
+ * @remarks
+ * Path A formula (per triangle):
+ * ```
+ * dP1 = p2 - p1; dP2 = p3 - p1
+ * dUV1 = uv2 - uv1; dUV2 = uv3 - uv1
+ * det = dUV1.u * dUV2.v - dUV2.u * dUV1.v
+ * T_face = (dUV2.v * dP1 - dUV1.v * dP2) / det
+ * sign = det >= 0 ? +1 : -1
+ * ```
+ * Per-vertex aggregation: accumulate `T_face * faceArea` into the three
+ * vertices of the triangle; accumulate `sign` (the dominant sign per
+ * vertex wins). After accumulation: Gram-Schmidt against the supplied
+ * normal `T' = normalize(T - dot(T, N) * N)`; repack as vec4 with the
+ * dominant handedness sign.
+ */
+export function computeTangentVec4(
+  positions: Float32Array,
+  normals: Float32Array,
+  uvs: Float32Array,
+  indices?: Uint16Array | Uint32Array,
+): Result<Float32Array, AssetError> {
+  const preflight = preflightTangentInput(positions, normals, uvs, indices);
+  if (!preflight.ok) return preflight;
+  const vertexCount = preflight.value;
+
+  // Working buffers: per-vertex accumulated tangent + accumulated handedness
+  // signed weight (sum of (face area * sign(det))). The dominant sign of
+  // the running sum is the per-vertex .w handedness.
+  const accumT = new Float32Array(vertexCount * 3);
+  const accumSign = new Float32Array(vertexCount);
+
+  const triangleCount = indices !== undefined ? indices.length / 3 : vertexCount / 3;
+
+  for (let tri = 0; tri < triangleCount; tri++) {
+    const i0 = indices !== undefined ? (indices[tri * 3] ?? 0) : tri * 3;
+    const i1 = indices !== undefined ? (indices[tri * 3 + 1] ?? 0) : tri * 3 + 1;
+    const i2 = indices !== undefined ? (indices[tri * 3 + 2] ?? 0) : tri * 3 + 2;
+
+    const p0x = positions[i0 * 3] ?? 0;
+    const p0y = positions[i0 * 3 + 1] ?? 0;
+    const p0z = positions[i0 * 3 + 2] ?? 0;
+    const p1x = positions[i1 * 3] ?? 0;
+    const p1y = positions[i1 * 3 + 1] ?? 0;
+    const p1z = positions[i1 * 3 + 2] ?? 0;
+    const p2x = positions[i2 * 3] ?? 0;
+    const p2y = positions[i2 * 3 + 1] ?? 0;
+    const p2z = positions[i2 * 3 + 2] ?? 0;
+
+    const u0 = uvs[i0 * 2] ?? 0;
+    const v0 = uvs[i0 * 2 + 1] ?? 0;
+    const u1 = uvs[i1 * 2] ?? 0;
+    const v1 = uvs[i1 * 2 + 1] ?? 0;
+    const u2 = uvs[i2 * 2] ?? 0;
+    const v2 = uvs[i2 * 2 + 1] ?? 0;
+
+    const dP1x = p1x - p0x;
+    const dP1y = p1y - p0y;
+    const dP1z = p1z - p0z;
+    const dP2x = p2x - p0x;
+    const dP2y = p2y - p0y;
+    const dP2z = p2z - p0z;
+
+    const dU1 = u1 - u0;
+    const dV1 = v1 - v0;
+    const dU2 = u2 - u0;
+    const dV2 = v2 - v0;
+
+    const det = dU1 * dV2 - dU2 * dV1;
+    if (Math.abs(det) < EPSILON) {
+      // degenerate UV (collinear / zero-area in UV space); skip
+      continue;
+    }
+    const invDet = 1 / det;
+    const tx = invDet * (dV2 * dP1x - dV1 * dP2x);
+    const ty = invDet * (dV2 * dP1y - dV1 * dP2y);
+    const tz = invDet * (dV2 * dP1z - dV1 * dP2z);
+
+    // Face area (cross product magnitude / 2). Used as accumulation weight.
+    const cx = dP1y * dP2z - dP1z * dP2y;
+    const cy = dP1z * dP2x - dP1x * dP2z;
+    const cz = dP1x * dP2y - dP1y * dP2x;
+    const faceArea = 0.5 * Math.sqrt(cx * cx + cy * cy + cz * cz);
+    if (faceArea < EPSILON) continue;
+
+    const signDet = det >= 0 ? 1 : -1;
+    const signedWeight = faceArea * signDet;
+
+    for (const vi of [i0, i1, i2]) {
+      accumT[vi * 3] = (accumT[vi * 3] ?? 0) + tx * faceArea;
+      accumT[vi * 3 + 1] = (accumT[vi * 3 + 1] ?? 0) + ty * faceArea;
+      accumT[vi * 3 + 2] = (accumT[vi * 3 + 2] ?? 0) + tz * faceArea;
+      accumSign[vi] = (accumSign[vi] ?? 0) + signedWeight;
+    }
+  }
+
+  const out = new Float32Array(vertexCount * 4);
+  for (let v = 0; v < vertexCount; v++) {
+    let tx = accumT[v * 3] ?? 0;
+    let ty = accumT[v * 3 + 1] ?? 0;
+    let tz = accumT[v * 3 + 2] ?? 0;
+    const nx = normals[v * 3] ?? 0;
+    const ny = normals[v * 3 + 1] ?? 0;
+    const nz = normals[v * 3 + 2] ?? 0;
+
+    const tLen = Math.sqrt(tx * tx + ty * ty + tz * tz);
+    if (tLen < EPSILON) {
+      // Fallback: pick any direction perpendicular to N. Use the axis
+      // with the smallest |normal component| to maximise numerical
+      // stability of the cross product.
+      const ax = Math.abs(nx);
+      const ay = Math.abs(ny);
+      const az = Math.abs(nz);
+      let rx = 1;
+      let ry = 0;
+      let rz = 0;
+      if (ax <= ay && ax <= az) {
+        rx = 1;
+        ry = 0;
+        rz = 0;
+      } else if (ay <= ax && ay <= az) {
+        rx = 0;
+        ry = 1;
+        rz = 0;
+      } else {
+        rx = 0;
+        ry = 0;
+        rz = 1;
+      }
+      // T = normalize(cross(N, R))
+      tx = ny * rz - nz * ry;
+      ty = nz * rx - nx * rz;
+      tz = nx * ry - ny * rx;
+      const fLen = Math.sqrt(tx * tx + ty * ty + tz * tz) || 1;
+      tx /= fLen;
+      ty /= fLen;
+      tz /= fLen;
+    } else {
+      tx /= tLen;
+      ty /= tLen;
+      tz /= tLen;
+    }
+
+    // Gram-Schmidt: T' = normalize(T - dot(T, N) * N)
+    const dotTN = tx * nx + ty * ny + tz * nz;
+    let gx = tx - dotTN * nx;
+    let gy = ty - dotTN * ny;
+    let gz = tz - dotTN * nz;
+    const gLen = Math.sqrt(gx * gx + gy * gy + gz * gz);
+    if (gLen < EPSILON) {
+      // tangent collinear with normal after accumulation; reuse fallback
+      // basis. Pick perpendicular via the smallest-axis trick again.
+      const ax = Math.abs(nx);
+      const ay = Math.abs(ny);
+      const az = Math.abs(nz);
+      let rx = 1;
+      let ry = 0;
+      let rz = 0;
+      if (ax <= ay && ax <= az) {
+        rx = 1;
+        ry = 0;
+        rz = 0;
+      } else if (ay <= ax && ay <= az) {
+        rx = 0;
+        ry = 1;
+        rz = 0;
+      } else {
+        rx = 0;
+        ry = 0;
+        rz = 1;
+      }
+      gx = ny * rz - nz * ry;
+      gy = nz * rx - nx * rz;
+      gz = nx * ry - ny * rx;
+      const fLen = Math.sqrt(gx * gx + gy * gy + gz * gz) || 1;
+      gx /= fLen;
+      gy /= fLen;
+      gz /= fLen;
+    } else {
+      gx /= gLen;
+      gy /= gLen;
+      gz /= gLen;
+    }
+
+    const accSign = accumSign[v] ?? 0;
+    const w = accSign >= 0 ? 1 : -1;
+
+    out[v * 4] = gx;
+    out[v * 4 + 1] = gy;
+    out[v * 4 + 2] = gz;
+    out[v * 4 + 3] = w;
+  }
+
+  return ok(out);
+}

package/src/torus.ts

@@ -0,0 +1,83 @@
+// @forgeax/engine-runtime - Procedural Torus geometry (M3 / w8).
+//
+// Mirrors Three.js r184 TorusGeometry: createTorusGeometry(radius, tube,
+// radialSegments?, tubularSegments?) -> Result<MeshAsset, AssetError>.
+// `radius` is the distance from the torus center to the tube center (ring
+// radius); `tube` is the cross-section (tube) radius. Degenerate parameters
+// fail-fast with AssetError('asset-parse-failed').
+//
+// Related: requirements §AC-06 / §AC-14; plan-strategy §M3 + D-P5;
+//          plan-tasks.json w8 acceptanceCheck.
+
+import type { AssetError, MeshAsset } from '@forgeax/engine-types';
+import { err, type Result } from '@forgeax/engine-types';
+import { degenerate, FACTORY_FLOATS_PER_VERTEX, meshFromInterleaved } from './box';
+
+export function createTorusGeometry(
+  radius: number,
+  tube: number,
+  radialSegments: number = 8,
+  tubularSegments: number = 24,
+): Result<MeshAsset, AssetError> {
+  if (radius <= 0) return err(degenerate(`radius=${radius}`));
+  if (tube <= 0) return err(degenerate(`tube=${tube}`));
+  const rs = radialSegments | 0;
+  const ts = tubularSegments | 0;
+  if (rs < 3) return err(degenerate(`radialSegments=${rs}; minimum 3`));
+  if (ts < 3) return err(degenerate(`tubularSegments=${ts}; minimum 3`));
+
+  const vertexCount = (rs + 1) * (ts + 1);
+  const indexCount = rs * ts * 6;
+  const vertices = new Float32Array(vertexCount * FACTORY_FLOATS_PER_VERTEX);
+  const indices = new Uint32Array(indexCount);
+
+  let vIdx = 0;
+  for (let j = 0; j <= rs; j++) {
+    const v = (j / rs) * Math.PI * 2;
+    const cosV = Math.cos(v);
+    const sinV = Math.sin(v);
+    for (let i = 0; i <= ts; i++) {
+      const u = (i / ts) * Math.PI * 2;
+      const cosU = Math.cos(u);
+      const sinU = Math.sin(u);
+      const x = (radius + tube * cosV) * cosU;
+      const y = (radius + tube * cosV) * sinU;
+      const z = tube * sinV;
+      // normal = normalize(position - center_of_tube_at_u)
+      const centerX = radius * cosU;
+      const centerY = radius * sinU;
+      const nx = x - centerX;
+      const ny = y - centerY;
+      const nz = z;
+      const nlen = Math.sqrt(nx * nx + ny * ny + nz * nz) || 1;
+      const base = vIdx * FACTORY_FLOATS_PER_VERTEX;
+      vertices[base + 0] = x;
+      vertices[base + 1] = y;
+      vertices[base + 2] = z;
+      vertices[base + 3] = nx / nlen;
+      vertices[base + 4] = ny / nlen;
+      vertices[base + 5] = nz / nlen;
+      vertices[base + 6] = i / ts;
+      vertices[base + 7] = j / rs;
+      vIdx++;
+    }
+  }
+
+  let iIdx = 0;
+  for (let j = 1; j <= rs; j++) {
+    for (let i = 1; i <= ts; i++) {
+      const a = (ts + 1) * j + i - 1;
+      const b = (ts + 1) * (j - 1) + i - 1;
+      const c = (ts + 1) * (j - 1) + i;
+      const d = (ts + 1) * j + i;
+      indices[iIdx++] = a;
+      indices[iIdx++] = b;
+      indices[iIdx++] = d;
+      indices[iIdx++] = b;
+      indices[iIdx++] = c;
+      indices[iIdx++] = d;
+    }
+  }
+
+  return meshFromInterleaved(vertices, indices);
+}