@marble.fun/track-catalog 3.0.0

package/src/pages/play/race/track-appearance-floor-runner.ts

@@ -0,0 +1,206 @@
+import * as THREE from 'three'
+
+import { STANDARD_RAILROAD_HALF_GAUGE } from '../../../three/railroad-appearance'
+import type { RouteNetworkFrame, SurfaceRouteRun } from './track-route-network'
+
+/**
+ * A standard runner occupies the same visual envelope as the established
+ * railway gauge. The floor remains visible on both sides, while narrow lanes
+ * clamp the runner inward instead of widening their authored surface.
+ */
+export const STANDARD_FLOOR_RUNNER_WIDTH = STANDARD_RAILROAD_HALF_GAUGE * 2
+export const FLOOR_RUNNER_EDGE_CLEARANCE = 0.34
+export const FLOOR_RUNNER_BASE_LIFT = 0.008
+export const FLOOR_RUNNER_THICKNESS = 0.024
+export const FLOOR_RUNNER_LATERAL_SEGMENTS = 12
+
+export interface FloorRunnerFrame extends RouteNetworkFrame {
+  point: THREE.Vector3
+  right: THREE.Vector3
+  up: THREE.Vector3
+  tangent: THREE.Vector3
+}
+
+export interface FloorRunnerOptions<Frame extends FloorRunnerFrame> {
+  themeId: string
+  appearanceMaterialId: string
+  surfacePoint(frame: Frame, normalizedLateral: number): THREE.Vector3
+}
+
+interface RunnerRoute<Frame extends FloorRunnerFrame> {
+  route: SurfaceRouteRun<Frame>
+  centers: THREE.Vector3[]
+  distances: number[]
+  totalLength: number
+}
+
+/**
+ * Adds one visual-only carpet/runner batch over canonical routed floor paths.
+ * It never creates colliders and therefore composes with every base floor.
+ */
+export function addCenteredFloorRunnerVisual<Frame extends FloorRunnerFrame>(
+  host: THREE.Group,
+  id: string,
+  routes: readonly SurfaceRouteRun<Frame>[],
+  material: THREE.Material,
+  options: FloorRunnerOptions<Frame>,
+): THREE.Group | undefined {
+  const validRoutes: RunnerRoute<Frame>[] = routes
+    .filter(route => route.frames.length >= 2)
+    .map(route => {
+      const centers = route.frames.map((frame, index) => {
+        const centerOffset = route.centerOffsets[index] ?? 0
+        return options.surfacePoint(frame, (centerOffset * 2) / Math.max(0.001, frame.width))
+      })
+      const distances = [0]
+      for (let index = 1; index < centers.length; index += 1) {
+        distances.push(distances.at(-1)! + centers[index]!.distanceTo(centers[index - 1]!))
+      }
+      return { route, centers, distances, totalLength: distances.at(-1) ?? 0 }
+    })
+    .filter(route => route.totalLength > 0.000_001)
+  if (validRoutes.length === 0) return undefined
+
+  const positions: number[] = []
+  const uvs: number[] = []
+  const netUvs: number[] = []
+  const indices: number[] = []
+  const appendVertex = (point: THREE.Vector3, transverse: number, longitudinal: number, totalLength: number) => {
+    positions.push(point.x, point.y, point.z)
+    uvs.push(transverse, longitudinal)
+    netUvs.push(transverse, longitudinal, 1, totalLength)
+  }
+
+  for (const { route, distances, totalLength } of validRoutes) {
+    const routeOffset = positions.length / 3
+    for (const [index, frame] of route.frames.entries()) {
+      const laneWidth = Math.max(0.001, route.laneWidths[index] ?? frame.width)
+      const width = Math.min(STANDARD_FLOOR_RUNNER_WIDTH, Math.max(0.6, laneWidth - FLOOR_RUNNER_EDGE_CLEARANCE * 2))
+      const halfWidth = width / 2
+      const centerOffset = route.centerOffsets[index] ?? 0
+      const distance = distances[index]!
+      const surfacePoints = Array.from({ length: FLOOR_RUNNER_LATERAL_SEGMENTS + 1 }, (_unused, lateralIndex) => {
+        const transverse = THREE.MathUtils.lerp(-halfWidth, halfWidth, lateralIndex / FLOOR_RUNNER_LATERAL_SEGMENTS)
+        const lateral = ((centerOffset + transverse) * 2) / Math.max(0.001, frame.width)
+        return options.surfacePoint(frame, lateral)
+      })
+      surfacePoints.forEach((surface, lateralIndex) => {
+        const previous = surfacePoints[Math.max(0, lateralIndex - 1)]!
+        const next = surfacePoints[Math.min(surfacePoints.length - 1, lateralIndex + 1)]!
+        const across = next.clone().sub(previous).normalize()
+        const surfaceUp = new THREE.Vector3().crossVectors(frame.tangent, across).normalize()
+        if (surfaceUp.dot(frame.up) < 0) surfaceUp.negate()
+        const transverse = THREE.MathUtils.lerp(-halfWidth, halfWidth, lateralIndex / FLOOR_RUNNER_LATERAL_SEGMENTS)
+        const bottom = surface.clone().addScaledVector(surfaceUp, FLOOR_RUNNER_BASE_LIFT)
+        const top = bottom.clone().addScaledVector(surfaceUp, FLOOR_RUNNER_THICKNESS)
+        appendVertex(top, transverse, distance, totalLength)
+        appendVertex(bottom, transverse, distance, totalLength)
+      })
+    }
+
+    const rowStride = (FLOOR_RUNNER_LATERAL_SEGMENTS + 1) * 2
+    for (let index = 0; index < route.frames.length - 1; index += 1) {
+      const currentRow = routeOffset + index * rowStride
+      const nextRow = currentRow + rowStride
+      for (let lateralIndex = 0; lateralIndex < FLOOR_RUNNER_LATERAL_SEGMENTS; lateralIndex += 1) {
+        const currentTop = currentRow + lateralIndex * 2
+        const currentBottom = currentTop + 1
+        const currentRightTop = currentTop + 2
+        const currentRightBottom = currentBottom + 2
+        const nextTop = nextRow + lateralIndex * 2
+        const nextBottom = nextTop + 1
+        const nextRightTop = nextTop + 2
+        const nextRightBottom = nextBottom + 2
+        indices.push(
+          currentTop,
+          nextTop,
+          currentRightTop,
+          currentRightTop,
+          nextTop,
+          nextRightTop,
+          currentBottom,
+          currentRightBottom,
+          nextBottom,
+          currentRightBottom,
+          nextRightBottom,
+          nextBottom,
+        )
+      }
+      const currentLeftTop = currentRow
+      const currentLeftBottom = currentLeftTop + 1
+      const nextLeftTop = nextRow
+      const nextLeftBottom = nextLeftTop + 1
+      const currentRightTop = currentRow + FLOOR_RUNNER_LATERAL_SEGMENTS * 2
+      const currentRightBottom = currentRightTop + 1
+      const nextRightTop = nextRow + FLOOR_RUNNER_LATERAL_SEGMENTS * 2
+      const nextRightBottom = nextRightTop + 1
+      indices.push(
+        currentLeftTop,
+        currentLeftBottom,
+        nextLeftTop,
+        currentLeftBottom,
+        nextLeftBottom,
+        nextLeftTop,
+        currentRightTop,
+        nextRightTop,
+        currentRightBottom,
+        currentRightBottom,
+        nextRightTop,
+        nextRightBottom,
+      )
+    }
+
+    const start = routeOffset
+    const end = routeOffset + (route.frames.length - 1) * rowStride
+    for (let lateralIndex = 0; lateralIndex < FLOOR_RUNNER_LATERAL_SEGMENTS; lateralIndex += 1) {
+      const startTop = start + lateralIndex * 2
+      const startBottom = startTop + 1
+      const startRightTop = startTop + 2
+      const startRightBottom = startBottom + 2
+      indices.push(startTop, startRightTop, startBottom, startRightTop, startRightBottom, startBottom)
+      const endTop = end + lateralIndex * 2
+      const endBottom = endTop + 1
+      const endRightTop = endTop + 2
+      const endRightBottom = endBottom + 2
+      indices.push(endTop, endBottom, endRightTop, endRightTop, endBottom, endRightBottom)
+    }
+  }
+
+  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(netUvs, 4))
+  geometry.setIndex(indices)
+  geometry.computeVertexNormals()
+  geometry.computeBoundingBox()
+  geometry.computeBoundingSphere()
+  geometry.userData.floorOverlay = 'centered-runner'
+  geometry.userData.visualOnly = true
+  geometry.userData.runnerWidth = STANDARD_FLOOR_RUNNER_WIDTH
+  geometry.userData.runnerThickness = FLOOR_RUNNER_THICKNESS
+  geometry.userData.lateralSegments = FLOOR_RUNNER_LATERAL_SEGMENTS
+  geometry.userData.themeMaterialLongitudinalAxis = 'y'
+
+  const mesh = new THREE.Mesh(geometry, material)
+  mesh.name = `${id}-centered-floor-runner-overlay`
+  mesh.userData.themeOnly = options.themeId
+  mesh.userData.themeRole = 'lane-centered-floor-runner'
+  mesh.userData.appearanceMaterialId = options.appearanceMaterialId
+  mesh.userData.decorative = true
+  mesh.userData.visualOnly = true
+  mesh.castShadow = false
+  mesh.receiveShadow = true
+
+  const group = new THREE.Group()
+  group.name = `${id}-centered-floor-runner`
+  group.userData.themeOnly = options.themeId
+  group.userData.appearance = 'centered-floor-runner'
+  group.userData.representation = 'procedural-routed-surface-overlay'
+  group.userData.visualOnly = true
+  group.userData.drawCallBudget = 1
+  group.userData.routeCount = validRoutes.length
+  group.userData.runMetricLengths = validRoutes.map(route => route.totalLength)
+  group.add(mesh)
+  host.add(group)
+  return group
+}