@marble.fun/track-catalog 3.0.0

package/src/pages/play/race/track-appearance-rope-wall.ts

@@ -0,0 +1,443 @@
+import * as THREE from 'three'
+
+import { VisualTorusGeometry, VisualTubeGeometry } from '../../../three/visual-geometry'
+import { mergeGeometries } from 'three/examples/jsm/utils/BufferGeometryUtils.js'
+
+import { ROPE_WALL_SUPPORTED_THEME_IDS } from '../../../three/rope-wall-appearance'
+import { TRACK_RAIL_WALL_THICKNESS } from './track-definition'
+import {
+  canonicalWallFrameAt,
+  type CanonicalWallRun,
+  type RawWallFrame,
+} from './track-surface-topology'
+import { woodenFenceHeight, woodenFencePostCount, WOODEN_FENCE_HEIGHT_RATIO } from './track-fence-architecture'
+
+export type RopeWallPathFrame = RawWallFrame
+export type RopeWallPathRun = CanonicalWallRun
+
+export interface RopeWallMaterials {
+  rope: THREE.Material
+  timber: THREE.Material
+  timberEndGrain: THREE.Material
+}
+
+const HANGER_SPACING = 0.58
+const CABLE_SEGMENTS = 8
+const HANDRAIL_HEIGHT = 0.79
+const LOWER_CABLE_HEIGHT = 0.2
+const OUTWARD_OFFSET = 0.075
+
+/**
+ * Builds the side wall of a hand-lashed rope bridge: substantial timber
+ * uprights, wrapped rope collars, sagging handrail and lower cables, dense
+ * vertical suspension ties, knots, and irregular loose ends. The continuous
+ * wall created by the track builder remains the only collision geometry.
+ */
+export function addRopeWallVisual(
+  root: THREE.Group,
+  id: string,
+  runs: readonly RopeWallPathRun[],
+  wallHeight: number,
+  materials: RopeWallMaterials,
+): THREE.Group | undefined {
+  const visualHeight = woodenFenceHeight(wallHeight)
+  const postMatrices: THREE.Matrix4[] = []
+  const handrailMatrices: THREE.Matrix4[] = []
+  const lowerCableMatrices: THREE.Matrix4[] = []
+  const hangerMatrices: THREE.Matrix4[] = []
+  const lashingMatrices: THREE.Matrix4[] = []
+  const crossLashingMatrices: THREE.Matrix4[] = []
+  const knotMatrices: THREE.Matrix4[] = []
+  const tailMatrices: THREE.Matrix4[] = []
+
+  for (const [runIndex, run] of runs.entries()) {
+    if (run.frames.length < 2) continue
+    // Rope dressing has a small authored stand-off from the canonical wall
+    // boundary. The topology itself remains shared with every other theme.
+    const canonicalRun: CanonicalWallRun = { ...run, frames: run.frames.map(frame => ({
+      ...frame,
+      base: frame.base
+        .clone()
+        .addScaledVector(frame.outward, TRACK_RAIL_WALL_THICKNESS / 2 + 0.025)
+        .addScaledVector(frame.up, -0.03),
+    })) }
+    const totalLength = canonicalRun.length
+    if (totalLength <= 0.001) continue
+    const postCount = woodenFencePostCount(totalLength, visualHeight)
+    const posts = Array.from({ length: postCount }, (_, postIndex) =>
+      canonicalWallFrameAt(canonicalRun, (postIndex / (postCount - 1)) * totalLength),
+    )
+
+    posts.forEach((frame, postIndex) => {
+      const seed = deterministic(`${id}:${runIndex}:${postIndex}`)
+      const postHeight = visualHeight
+      const lean = (seed - 0.5) * 0.11
+      const postRotation = frameQuaternion(frame.tangent, frame.up)
+      postRotation.premultiply(new THREE.Quaternion().setFromAxisAngle(frame.tangent, lean))
+      postMatrices.push(
+        new THREE.Matrix4().compose(
+          frame.base.clone().addScaledVector(frame.up, postHeight / 2 - 0.025),
+          postRotation,
+          new THREE.Vector3(0.96 + seed * 0.16, postHeight, 0.96 + seed * 0.16),
+        ),
+      )
+
+      for (const [anchorHeight, scaleY] of [
+        [visualHeight * HANDRAIL_HEIGHT, 1],
+        [visualHeight * LOWER_CABLE_HEIGHT, 0.78],
+      ] as const) {
+        lashingMatrices.push(
+          new THREE.Matrix4().compose(
+            frame.base.clone().addScaledVector(frame.up, anchorHeight),
+            postRotation,
+            new THREE.Vector3(1.02 + seed * 0.08, scaleY, 1.02 + seed * 0.08),
+          ),
+        )
+      }
+      appendCrossLashings(crossLashingMatrices, frame, visualHeight * LOWER_CABLE_HEIGHT)
+    })
+
+    for (let postIndex = 0; postIndex < posts.length - 1; postIndex += 1) {
+      const start = posts[postIndex]!
+      const end = posts[postIndex + 1]!
+      const spanLength = start.base.distanceTo(end.base)
+      appendSaggingCable(handrailMatrices, start, end, visualHeight * HANDRAIL_HEIGHT, visualHeight * 0.12)
+      appendSaggingCable(lowerCableMatrices, start, end, visualHeight * LOWER_CABLE_HEIGHT, visualHeight * 0.035)
+
+      const hangerCount = Math.max(3, Math.ceil(spanLength / HANGER_SPACING))
+      for (let hangerIndex = 1; hangerIndex < hangerCount; hangerIndex += 1) {
+        const progress = hangerIndex / hangerCount
+        const upper = cablePoint(start, end, progress, visualHeight * HANDRAIL_HEIGHT, visualHeight * 0.12)
+        const lower = cablePoint(start, end, progress, visualHeight * LOWER_CABLE_HEIGHT, visualHeight * 0.035)
+        appendCylinderMatrix(hangerMatrices, upper, lower, 0.015)
+
+        const frame = interpolateFrame(start, end, progress)
+        const knotRotation = frameQuaternion(frame.tangent, frame.up).multiply(
+          new THREE.Quaternion().setFromAxisAngle(new THREE.Vector3(1, 0, 0), Math.PI / 2),
+        )
+        for (const point of [upper, lower]) {
+          knotMatrices.push(new THREE.Matrix4().compose(point, knotRotation, new THREE.Vector3(1, 1, 1)))
+        }
+
+        if ((hangerIndex + postIndex + runIndex) % 2 === 0) {
+          const tailLength = 0.13 + deterministic(`${id}:${runIndex}:${postIndex}:${hangerIndex}:tail`) * 0.19
+          const tailEnd = lower
+            .clone()
+            .addScaledVector(frame.up, -tailLength)
+            .addScaledVector(frame.tangent, (deterministic(`${id}:${hangerIndex}:sway`) - 0.5) * 0.09)
+          appendCylinderMatrix(tailMatrices, lower, tailEnd, 0.016)
+        }
+      }
+    }
+  }
+
+  if (postMatrices.length === 0 || handrailMatrices.length === 0) return undefined
+  const group = new THREE.Group()
+  group.name = `${id}-rope-wall`
+  group.userData.themeOnly = [...ROPE_WALL_SUPPORTED_THEME_IDS]
+  group.userData.decorative = true
+  group.userData.visualOnly = true
+  group.userData.construction = 'hand-lashed-suspension-bridge-wall'
+  group.userData.wallHeightRatio = WOODEN_FENCE_HEIGHT_RATIO
+
+  group.add(
+    instancedBatch(`${id}-rope-wall-timber-posts`, createHandHewnPostGeometry(), materials.timber, postMatrices),
+    instancedBatch(
+      `${id}-rope-wall-timber-post-caps`,
+      createHandHewnPostCapGeometry(),
+      materials.timberEndGrain,
+      postMatrices,
+    ),
+    instancedBatch(
+      `${id}-rope-wall-handrail-cable`,
+      createBraidedRopeSegmentGeometry(0.028, 0.024),
+      materials.rope,
+      handrailMatrices,
+    ),
+    instancedBatch(
+      `${id}-rope-wall-lower-cable`,
+      createBraidedRopeSegmentGeometry(0.023, 0.019),
+      materials.rope,
+      lowerCableMatrices,
+    ),
+    instancedBatch(
+      `${id}-rope-wall-vertical-hangers`,
+      createBraidedRopeSegmentGeometry(0.011, 0.009, 2),
+      materials.rope,
+      hangerMatrices,
+    ),
+    instancedBatch(`${id}-rope-wall-post-lashings`, createRopeLashingGeometry(), materials.rope, lashingMatrices),
+    instancedBatch(
+      `${id}-rope-wall-cross-lashings`,
+      createBraidedRopeSegmentGeometry(0.013, 0.011, 2),
+      materials.rope,
+      crossLashingMatrices,
+    ),
+    instancedBatch(
+      `${id}-rope-wall-hanger-knots`,
+      withAuthoredMaterialUv(new VisualTorusGeometry(0.057, 0.016, 5, 9)),
+      materials.rope,
+      knotMatrices,
+    ),
+    instancedBatch(
+      `${id}-rope-wall-loose-ends`,
+      createBraidedRopeSegmentGeometry(0.0085, 0.0075, 2),
+      materials.rope,
+      tailMatrices,
+    ),
+  )
+  root.add(group)
+  return group
+}
+
+function createHandHewnPostGeometry(): THREE.BufferGeometry {
+  const sides = 12
+  const levels = [-0.5, -0.34, 0.3, 0.5] as const
+  const positions: number[] = []
+  const uvs: number[] = []
+  const metricUvs: number[] = []
+  const indices: number[] = []
+
+  for (const [levelIndex, y] of levels.entries()) {
+    for (let side = 0; side < sides; side += 1) {
+      const angle = (side / sides) * Math.PI * 2
+      const irregularity = 1 + Math.sin(side * 4.37 + levelIndex * 2.11) * 0.055
+      const taper = levelIndex === 0 ? 1.08 : levelIndex === levels.length - 1 ? 0.91 : 1
+      const topChip = 0
+      positions.push(
+        Math.cos(angle) * 0.225 * irregularity * taper,
+        y + topChip,
+        Math.sin(angle) * 0.225 * irregularity * taper,
+      )
+      uvs.push(side / sides, levelIndex / (levels.length - 1))
+      metricUvs.push(side / sides, levelIndex / (levels.length - 1), 1, 1)
+    }
+  }
+
+  for (let level = 0; level < levels.length - 1; level += 1) {
+    for (let side = 0; side < sides; side += 1) {
+      const next = (side + 1) % sides
+      const lower = level * sides
+      const upper = (level + 1) * sides
+      indices.push(lower + side, upper + side, lower + next, lower + next, upper + side, upper + next)
+    }
+  }
+
+  const bottomCenter = positions.length / 3
+  positions.push(0, levels[0], 0)
+  uvs.push(0.5, 0.5)
+  metricUvs.push(0.5, 0.5, 1, 1)
+  for (let side = 0; side < sides; side += 1) {
+    indices.push(bottomCenter, side, (side + 1) % sides)
+  }
+
+  const geometry = new THREE.BufferGeometry()
+  geometry.setAttribute('position', new THREE.Float32BufferAttribute(positions, 3))
+  geometry.setAttribute('uv', new THREE.Float32BufferAttribute(uvs, 2))
+  geometry.setAttribute('themeNetUv', new THREE.Float32BufferAttribute(metricUvs, 4))
+  geometry.setIndex(indices)
+  geometry.computeVertexNormals()
+  geometry.computeBoundingBox()
+  geometry.computeBoundingSphere()
+  geometry.name = 'hand-hewn-rope-wall-post-geometry'
+  return geometry
+}
+
+function createHandHewnPostCapGeometry(): THREE.BufferGeometry {
+  const sides = 12
+  const positions: number[] = []
+  const uvs: number[] = []
+  const metricUvs: number[] = []
+  const indices: number[] = []
+
+  for (let side = 0; side < sides; side += 1) {
+    const angle = (side / sides) * Math.PI * 2
+    const irregularity = 1 + Math.sin(side * 4.37 + 3 * 2.11) * 0.055
+    const topChip = 0
+    const x = Math.cos(angle) * 0.225 * irregularity * 0.91
+    const z = Math.sin(angle) * 0.225 * irregularity * 0.91
+    positions.push(x, 0.5008 + topChip, z)
+    const u = x / 0.51 + 0.5
+    const v = z / 0.51 + 0.5
+    uvs.push(u, v)
+    metricUvs.push(u, v, 1, 1)
+  }
+  const center = positions.length / 3
+  positions.push(0, 0.5008, 0)
+  uvs.push(0.5, 0.5)
+  metricUvs.push(0.5, 0.5, 1, 1)
+  for (let side = 0; side < sides; side += 1) {
+    indices.push(center, (side + 1) % sides, side)
+  }
+
+  const geometry = new THREE.BufferGeometry()
+  geometry.setAttribute('position', new THREE.Float32BufferAttribute(positions, 3))
+  geometry.setAttribute('uv', new THREE.Float32BufferAttribute(uvs, 2))
+  geometry.setAttribute('themeNetUv', new THREE.Float32BufferAttribute(metricUvs, 4))
+  geometry.setIndex(indices)
+  geometry.computeVertexNormals()
+  geometry.computeBoundingBox()
+  geometry.computeBoundingSphere()
+  geometry.name = 'hand-hewn-rope-wall-post-cap-geometry'
+  return geometry
+}
+
+function createRopeLashingGeometry(): THREE.TubeGeometry {
+  const turns = 4.25
+  const points = Array.from({ length: 38 }, (_, index) => {
+    const progress = index / 37
+    const angle = progress * Math.PI * 2 * turns
+    const radius = 0.247 + Math.sin(progress * Math.PI * 6) * 0.006
+    return new THREE.Vector3(Math.cos(angle) * radius, (progress - 0.5) * 0.2, Math.sin(angle) * radius)
+  })
+  const geometry = withAuthoredMaterialUv(
+    new VisualTubeGeometry(new THREE.CatmullRomCurve3(points), 48, 0.032, 7, false),
+  )
+  geometry.name = 'hand-wrapped-rope-lashing-geometry'
+  return geometry
+}
+
+function createBraidedRopeSegmentGeometry(helixRadius: number, strandRadius: number, turns = 3): THREE.BufferGeometry {
+  const segments = 30
+  const strands = Array.from({ length: 3 }, (_, strandIndex) => {
+    const phase = (strandIndex / 3) * Math.PI * 2
+    const points = Array.from({ length: segments + 1 }, (_, index) => {
+      const progress = index / segments
+      const angle = phase + progress * Math.PI * 2 * turns
+      return new THREE.Vector3(Math.cos(angle) * helixRadius, progress - 0.5, Math.sin(angle) * helixRadius)
+    })
+    return new VisualTubeGeometry(new THREE.CatmullRomCurve3(points), segments, strandRadius, 6, false)
+  })
+  const geometry = mergeGeometries(strands, false)
+  strands.forEach(strand => strand.dispose())
+  if (!geometry) throw new Error('Failed to build braided rope geometry.')
+  geometry.name = 'three-strand-braided-rope-segment-geometry'
+  return withAuthoredMaterialUv(geometry)
+}
+
+function appendCrossLashings(matrices: THREE.Matrix4[], frame: RopeWallPathFrame, anchorHeight: number): void {
+  for (const face of [-1, 1] as const) {
+    const center = frame.base
+      .clone()
+      .addScaledVector(frame.up, anchorHeight - 0.12)
+      .addScaledVector(frame.outward, face * 0.235)
+    const upperLeft = center.clone().addScaledVector(frame.tangent, -0.18).addScaledVector(frame.up, 0.15)
+    const upperRight = center.clone().addScaledVector(frame.tangent, 0.18).addScaledVector(frame.up, 0.15)
+    const lowerLeft = center.clone().addScaledVector(frame.tangent, -0.18).addScaledVector(frame.up, -0.15)
+    const lowerRight = center.clone().addScaledVector(frame.tangent, 0.18).addScaledVector(frame.up, -0.15)
+    appendCylinderMatrix(matrices, upperLeft, lowerRight, 0.035)
+    appendCylinderMatrix(matrices, upperRight, lowerLeft, 0.035)
+  }
+  for (const face of [-1, 1] as const) {
+    const center = frame.base
+      .clone()
+      .addScaledVector(frame.up, anchorHeight - 0.12)
+      .addScaledVector(frame.tangent, face * 0.235)
+    const upperLeft = center.clone().addScaledVector(frame.outward, -0.18).addScaledVector(frame.up, 0.15)
+    const upperRight = center.clone().addScaledVector(frame.outward, 0.18).addScaledVector(frame.up, 0.15)
+    const lowerLeft = center.clone().addScaledVector(frame.outward, -0.18).addScaledVector(frame.up, -0.15)
+    const lowerRight = center.clone().addScaledVector(frame.outward, 0.18).addScaledVector(frame.up, -0.15)
+    appendCylinderMatrix(matrices, upperLeft, lowerRight, 0.035)
+    appendCylinderMatrix(matrices, upperRight, lowerLeft, 0.035)
+  }
+}
+
+function withAuthoredMaterialUv<T extends THREE.BufferGeometry>(geometry: T): T {
+  const uv = geometry.getAttribute('uv')
+  if (!uv) return geometry
+  const materialUvs: number[] = []
+  for (let index = 0; index < uv.count; index += 1) {
+    materialUvs.push(uv.getX(index), uv.getY(index), 1, 1)
+  }
+  geometry.setAttribute('themeNetUv', new THREE.Float32BufferAttribute(materialUvs, 4))
+  return geometry
+}
+
+function appendSaggingCable(
+  matrices: THREE.Matrix4[],
+  start: RopeWallPathFrame,
+  end: RopeWallPathFrame,
+  height: number,
+  sag: number,
+): void {
+  let previous = cablePoint(start, end, 0, height, sag)
+  for (let segment = 1; segment <= CABLE_SEGMENTS; segment += 1) {
+    const progress = segment / CABLE_SEGMENTS
+    const next = cablePoint(start, end, progress, height, sag)
+    appendCylinderMatrix(matrices, previous, next, 0.014)
+    previous = next
+  }
+}
+
+function cablePoint(
+  start: RopeWallPathFrame,
+  end: RopeWallPathFrame,
+  progress: number,
+  height: number,
+  sag: number,
+): THREE.Vector3 {
+  const frame = interpolateFrame(start, end, progress)
+  return frame.base
+    .clone()
+    .addScaledVector(frame.up, height - Math.sin(progress * Math.PI) * sag)
+    .addScaledVector(frame.outward, OUTWARD_OFFSET)
+}
+
+function appendCylinderMatrix(
+  matrices: THREE.Matrix4[],
+  start: THREE.Vector3,
+  end: THREE.Vector3,
+  overlap: number,
+): void {
+  const direction = end.clone().sub(start)
+  const length = direction.length()
+  if (length <= 0.001) return
+  matrices.push(
+    new THREE.Matrix4().compose(
+      start.clone().lerp(end, 0.5),
+      new THREE.Quaternion().setFromUnitVectors(new THREE.Vector3(0, 1, 0), direction.normalize()),
+      new THREE.Vector3(1, length + overlap, 1),
+    ),
+  )
+}
+
+function instancedBatch(
+  name: string,
+  geometry: THREE.BufferGeometry,
+  material: THREE.Material | THREE.Material[],
+  matrices: readonly THREE.Matrix4[],
+): THREE.InstancedMesh {
+  const mesh = new THREE.InstancedMesh(geometry, material, matrices.length)
+  mesh.name = name
+  mesh.userData.decorative = true
+  mesh.userData.visualOnly = true
+  mesh.castShadow = true
+  mesh.receiveShadow = true
+  matrices.forEach((matrix, index) => mesh.setMatrixAt(index, matrix))
+  mesh.instanceMatrix.needsUpdate = true
+  return mesh
+}
+
+function interpolateFrame(start: RopeWallPathFrame, end: RopeWallPathFrame, progress: number): RopeWallPathFrame {
+  const tangent = start.tangent.clone().lerp(end.tangent, progress).normalize()
+  const up = start.up.clone().lerp(end.up, progress).normalize()
+  const outward = start.outward.clone().lerp(end.outward, progress)
+  outward.addScaledVector(tangent, -outward.dot(tangent)).addScaledVector(up, -outward.dot(up)).normalize()
+  return { base: start.base.clone().lerp(end.base, progress), tangent, up, outward }
+}
+
+function frameQuaternion(tangent: THREE.Vector3, up: THREE.Vector3): THREE.Quaternion {
+  const y = up.clone().normalize()
+  const x = tangent.clone().addScaledVector(y, -tangent.dot(y)).normalize()
+  const z = new THREE.Vector3().crossVectors(x, y).normalize()
+  return new THREE.Quaternion().setFromRotationMatrix(new THREE.Matrix4().makeBasis(x, y, z))
+}
+
+function deterministic(seed: string): number {
+  let hash = 2_166_136_261
+  for (const character of seed) {
+    hash ^= character.charCodeAt(0)
+    hash = Math.imul(hash, 16_777_619)
+  }
+  return (hash >>> 0) / 4_294_967_296
+}