@marble.fun/track-catalog 3.0.0

package/src/pages/play/race/track-appearance-canopy.ts

@@ -0,0 +1,946 @@
+import * as THREE from 'three'
+
+import { VisualCylinderGeometry, VisualBoxGeometry } from '../../../three/visual-geometry'
+
+import type { TrackAppearanceCanopyStyle } from '../../../three/track-theme'
+
+export interface AppearanceCanopyFrame {
+  point: THREE.Vector3
+  tangent: THREE.Vector3
+  right: THREE.Vector3
+  up: THREE.Vector3
+  width: number
+}
+
+export interface AppearanceCanopyMaterials {
+  wall: THREE.Material
+  timber: THREE.Material
+  metal: THREE.Material
+  sakuraKawara?: THREE.Material
+  sakuraPlaster?: THREE.Material
+  sakuraMasonry?: THREE.Material
+}
+
+interface Beam {
+  start: THREE.Vector3
+  end: THREE.Vector3
+  width: number
+  depth: number
+}
+
+interface Fastener {
+  point: THREE.Vector3
+  outward: THREE.Vector3
+}
+
+export interface CanopySection {
+  frame: AppearanceCanopyFrame
+  leftEave: THREE.Vector3
+  ridge: THREE.Vector3
+  rightEave: THREE.Vector3
+}
+
+interface CoveredRun {
+  frames: AppearanceCanopyFrame[]
+  touchesStart: boolean
+  touchesEnd: boolean
+}
+
+export interface AppearanceCanopyOptions {
+  capStart?: boolean
+  capEnd?: boolean
+}
+
+const LOCAL_UP = new THREE.Vector3(0, 1, 0)
+export const WILD_WEST_COVERED_MINE_CANOPY_ID = 'wild-west.covered-mine-canopy'
+export const JAPANESE_SAKURA_ROOFED_GATE_CANOPY_ID = 'japanese-sakura.roofed-gate-canopy'
+/** The standard six-unit covered-mine roof rises 0.92 wu over a 3.32 wu half-span. */
+export const WILD_WEST_COVERED_MINE_ROOF_PITCH = 0.92 / 3.32
+
+/**
+ * Intersections and Vortices have no single covered corridor. Start and finish
+ * pieces intentionally remain plain race terminals. Their walls still accept
+ * ordinary visual appearances, but roof presets would add architecture where
+ * none should exist.
+ */
+export function supportsTrackAppearanceCanopy(runtimeKind: string): boolean {
+  return runtimeKind !== 'intersection' && runtimeKind !== 'vortex' && runtimeKind !== 'start' && runtimeKind !== 'finish'
+}
+
+export function appearanceCanopyStyle(
+  material: THREE.Material,
+  appearanceId?: string,
+): TrackAppearanceCanopyStyle | undefined {
+  if (appearanceId === WILD_WEST_COVERED_MINE_CANOPY_ID) return 'wild-west-covered-mine'
+  if (appearanceId === JAPANESE_SAKURA_ROOFED_GATE_CANOPY_ID) return 'japanese-sakura-roofed-gate'
+  const style = material.userData.themeAppearanceCanopyStyle
+  return style === 'wild-west-covered-mine' || style === 'japanese-sakura-roofed-gate'
+    ? style
+    : undefined
+}
+
+export function addTrackAppearanceCanopy(
+  root: THREE.Group,
+  id: string,
+  frames: readonly AppearanceCanopyFrame[],
+  negativeWallSegments: readonly boolean[],
+  positiveWallSegments: readonly boolean[],
+  materials: AppearanceCanopyMaterials,
+  style: TrackAppearanceCanopyStyle | undefined,
+  options: AppearanceCanopyOptions = {},
+): void {
+  if (!style || frames.length < 2) return
+  const runs = collectCoveredRuns(frames, negativeWallSegments, positiveWallSegments)
+  if (runs.length === 0) return
+
+  if (style === 'wild-west-covered-mine') {
+    runs.forEach((run, index) =>
+      addWildWestCoveredMine(root, `${id}-canopy-${index + 1}`, run.frames, materials, {
+        includeStartSupport: !run.touchesStart || options.capStart !== false,
+        includeEndSupport: !run.touchesEnd || options.capEnd !== false,
+      }),
+    )
+    return
+  }
+  if (style === 'japanese-sakura-roofed-gate') {
+    runs.forEach((run, index) =>
+      addSakuraRoofedGate(root, `${id}-canopy-${index + 1}`, run.frames, materials, {
+        includeStartSupport: !run.touchesStart || options.capStart !== false,
+        includeEndSupport: !run.touchesEnd || options.capEnd !== false,
+      }),
+    )
+  }
+}
+
+function collectCoveredRuns(
+  frames: readonly AppearanceCanopyFrame[],
+  negativeWallSegments: readonly boolean[],
+  positiveWallSegments: readonly boolean[],
+): CoveredRun[] {
+  const runs: CoveredRun[] = []
+  let runStart: number | undefined
+  for (let segment = 0; segment <= frames.length - 1; segment += 1) {
+    const covered = Boolean(negativeWallSegments[segment] && positiveWallSegments[segment])
+    if (covered && runStart === undefined) runStart = segment
+    if (covered || runStart === undefined) continue
+    const runFrames = frames.slice(runStart, segment + 1)
+    if (runFrames.length >= 2) {
+      runs.push({
+        frames: runFrames.map(cloneFrame),
+        touchesStart: runStart === 0,
+        touchesEnd: segment === frames.length - 1,
+      })
+    }
+    runStart = undefined
+  }
+  return runs
+}
+
+function cloneFrame(frame: AppearanceCanopyFrame): AppearanceCanopyFrame {
+  return {
+    point: frame.point.clone(),
+    tangent: frame.tangent.clone(),
+    right: frame.right.clone(),
+    up: frame.up.clone(),
+    width: frame.width,
+  }
+}
+
+function sampleFrames(frames: readonly AppearanceCanopyFrame[], spacing: number): AppearanceCanopyFrame[] {
+  const distances = [0]
+  for (let index = 0; index < frames.length - 1; index += 1) {
+    distances.push(distances.at(-1)! + frames[index]!.point.distanceTo(frames[index + 1]!.point))
+  }
+  const length = distances.at(-1) ?? 0
+  const count = Math.max(2, Math.ceil(length / spacing) + 1)
+  return Array.from({ length: count }, (_, sampleIndex) => {
+    const target = (sampleIndex / (count - 1)) * length
+    let segment = 0
+    while (segment < distances.length - 2 && distances[segment + 1]! < target) segment += 1
+    const segmentLength = distances[segment + 1]! - distances[segment]!
+    const progress = segmentLength <= 0.000_001 ? 0 : (target - distances[segment]!) / segmentLength
+    return interpolateFrame(frames[segment]!, frames[segment + 1]!, progress)
+  })
+}
+
+function interpolateFrame(
+  start: AppearanceCanopyFrame,
+  end: AppearanceCanopyFrame,
+  progress: number,
+): AppearanceCanopyFrame {
+  const tangent = start.tangent.clone().lerp(end.tangent, progress).normalize()
+  const rightHint = start.right.clone().lerp(end.right, progress)
+  rightHint.addScaledVector(tangent, -rightHint.dot(tangent))
+  if (rightHint.lengthSq() < 0.000_001) rightHint.crossVectors(start.up, tangent)
+  const right = rightHint.normalize()
+  const up = new THREE.Vector3().crossVectors(tangent, right).normalize()
+  const upHint = start.up.clone().lerp(end.up, progress)
+  if (up.dot(upHint) < 0) {
+    right.negate()
+    up.negate()
+  }
+  return {
+    point: start.point.clone().lerp(end.point, progress),
+    tangent,
+    right,
+    up,
+    width: THREE.MathUtils.lerp(start.width, end.width, progress),
+  }
+}
+
+interface SupportOptions {
+  includeStartSupport: boolean
+  includeEndSupport: boolean
+}
+
+function supportSections<T>(sections: readonly T[], options: SupportOptions): { section: T; index: number }[] {
+  return sections.flatMap((section, index) => {
+    if (index === 0 && !options.includeStartSupport) return []
+    if (index === sections.length - 1 && !options.includeEndSupport) return []
+    return [{ section, index }]
+  })
+}
+
+function addOpenPortSupportInsets(
+  frames: readonly AppearanceCanopyFrame[],
+  options: SupportOptions,
+): AppearanceCanopyFrame[] {
+  const inset = 0.32
+  const result = [...frames]
+  if (!options.includeStartSupport) {
+    const start = result[0]!
+    const next = result[1]!
+    const distance = start.point.distanceTo(next.point)
+    if (distance > inset * 1.25) result.splice(1, 0, interpolateFrame(start, next, inset / distance))
+  }
+  if (!options.includeEndSupport) {
+    const previous = result.at(-2)!
+    const end = result.at(-1)!
+    const distance = previous.point.distanceTo(end.point)
+    if (distance > inset * 1.25) {
+      result.splice(result.length - 1, 0, interpolateFrame(previous, end, 1 - inset / distance))
+    }
+  }
+  return result
+}
+
+function addWildWestCoveredMine(
+  root: THREE.Group,
+  id: string,
+  runFrames: readonly AppearanceCanopyFrame[],
+  materials: AppearanceCanopyMaterials,
+  supportOptions: SupportOptions,
+): void {
+  const eaveHeight = 2.8
+  const makeSection = (frame: AppearanceCanopyFrame): CanopySection => {
+    const halfSpan = frame.width / 2 + 0.32
+    const ridgeHeight = eaveHeight + halfSpan * WILD_WEST_COVERED_MINE_ROOF_PITCH
+    return {
+      frame,
+      leftEave: frame.point.clone().addScaledVector(frame.right, -halfSpan).addScaledVector(LOCAL_UP, eaveHeight),
+      ridge: frame.point.clone().addScaledVector(LOCAL_UP, ridgeHeight),
+      rightEave: frame.point.clone().addScaledVector(frame.right, halfSpan).addScaledVector(LOCAL_UP, eaveHeight),
+    }
+  }
+  const sections = addOpenPortSupportInsets(sampleFrames(runFrames, 3.35), supportOptions).map(makeSection)
+  const roofSections = sampleFrames(runFrames, 0.55).map(makeSection)
+  const timbers: Beam[] = []
+  const braces: Beam[] = []
+  const eaveFascias: Beam[] = []
+  const ridgeCaps: Beam[] = []
+  const ironStraps: Beam[] = []
+  const hardwarePlates: Beam[] = []
+  const fasteners: Fastener[] = []
+  const supported = supportSections(sections, supportOptions)
+  let portalFrameCount = 0
+  for (const { section, index } of supported) {
+    const halfSpan = section.frame.width / 2 + 0.32
+    const leftBase = section.frame.point.clone().addScaledVector(section.frame.right, -halfSpan).addScaledVector(LOCAL_UP, -0.15)
+    const rightBase = section.frame.point.clone().addScaledVector(section.frame.right, halfSpan).addScaledVector(LOCAL_UP, -0.15)
+    const isPortalBent =
+      (!supportOptions.includeStartSupport && index === 1) ||
+      (!supportOptions.includeEndSupport && index === sections.length - 2)
+    if (isPortalBent) portalFrameCount += 1
+    const postWidth = 0.38 + (isPortalBent ? 0.035 : 0)
+    const rafterWidth = 0.28 + (isPortalBent ? 0.025 : 0)
+    timbers.push(
+      beam(leftBase, section.leftEave, postWidth, postWidth),
+      beam(rightBase, section.rightEave, postWidth, postWidth),
+      beam(section.leftEave, section.ridge, rafterWidth, rafterWidth * 0.9),
+      beam(section.ridge, section.rightEave, rafterWidth, rafterWidth * 0.9),
+      beam(section.leftEave, section.rightEave, 0.34, 0.3),
+    )
+    for (const side of [-1, 1] as const) {
+      const postCenter = section.frame.point.clone().addScaledVector(section.frame.right, side * halfSpan)
+      ironStraps.push(
+        beam(
+          postCenter.clone().addScaledVector(section.frame.tangent, -0.14).addScaledVector(LOCAL_UP, 0.42),
+          postCenter.clone().addScaledVector(section.frame.tangent, 0.14).addScaledVector(LOCAL_UP, 0.42),
+          postWidth + 0.1,
+          postWidth + 0.1,
+        ),
+      )
+      hardwarePlates.push(
+        beam(
+          postCenter.clone().addScaledVector(section.frame.tangent, -0.15).addScaledVector(LOCAL_UP, eaveHeight - 0.12),
+          postCenter.clone().addScaledVector(section.frame.tangent, 0.15).addScaledVector(LOCAL_UP, eaveHeight - 0.12),
+          postWidth + 0.12,
+          0.065,
+        ),
+      )
+      const outward = section.frame.right.clone().multiplyScalar(side).normalize()
+      for (const tangentOffset of [-0.11, 0.11]) {
+        for (const height of [eaveHeight - 0.23, eaveHeight - 0.01]) {
+          fasteners.push({
+            point: postCenter
+              .clone()
+              .addScaledVector(section.frame.tangent, tangentOffset)
+              .addScaledVector(LOCAL_UP, height)
+              .addScaledVector(outward, postWidth / 2 + 0.04),
+            outward,
+          })
+        }
+      }
+    }
+  }
+  for (let index = 0; index < sections.length - 1; index += 1) {
+    const current = sections[index]!
+    const next = sections[index + 1]!
+    eaveFascias.push(
+      beam(current.leftEave, next.leftEave, 0.36, 0.34),
+      beam(current.rightEave, next.rightEave, 0.36, 0.34),
+    )
+    ridgeCaps.push(beam(current.ridge, next.ridge, 0.3, 0.24))
+    for (const side of [-1, 1] as const) {
+      const startEave = side < 0 ? current.leftEave : current.rightEave
+      const endEave = side < 0 ? next.leftEave : next.rightEave
+      braces.push(
+        beam(
+          startEave.clone().addScaledVector(LOCAL_UP, -0.92),
+          startEave.clone().lerp(endEave, 0.28).addScaledVector(LOCAL_UP, -0.12),
+          0.145,
+          0.13,
+        ),
+        beam(
+          endEave.clone().addScaledVector(LOCAL_UP, -0.92),
+          endEave.clone().lerp(startEave, 0.28).addScaledVector(LOCAL_UP, -0.12),
+          0.145,
+          0.13,
+        ),
+      )
+    }
+  }
+
+  const timberMesh = addBeamBatch(
+    root,
+    `${id}-mine-timbers`,
+    timbers,
+    materials.timber,
+    'rocky-mountain-wild-west',
+    false,
+    true,
+  )
+  const braceMesh = addBeamBatch(
+    root,
+    `${id}-mine-braces`,
+    braces,
+    materials.timber,
+    'rocky-mountain-wild-west',
+    false,
+    true,
+  )
+  addBeamBatch(
+    root,
+    `${id}-mine-longitudinal-timbers`,
+    eaveFascias,
+    materials.timber,
+    'rocky-mountain-wild-west',
+    false,
+    true,
+  )
+  addBeamBatch(
+    root,
+    `${id}-mine-ridge-cap`,
+    ridgeCaps,
+    materials.metal,
+    'rocky-mountain-wild-west',
+    false,
+    true,
+  )
+  addBeamBatch(
+    root,
+    `${id}-mine-iron-straps`,
+    ironStraps,
+    materials.metal,
+    'rocky-mountain-wild-west',
+    false,
+    true,
+  )
+  for (const mesh of [timberMesh, braceMesh]) {
+    if (!mesh) continue
+    mesh.userData.canopySectionCount = sections.length
+    mesh.userData.canopySupportSectionCount = supported.length
+    mesh.userData.canopyPortalFrameCount = portalFrameCount
+  }
+  addBeamBatch(
+    root,
+    `${id}-mine-iron-brackets`,
+    hardwarePlates,
+    materials.metal,
+    'rocky-mountain-wild-west',
+    false,
+    true,
+  )
+  addFastenerBatch(root, `${id}-mine-iron-fasteners`, fasteners, materials.metal, 'rocky-mountain-wild-west')
+  addRoofSheets(root, `${id}-corrugated-roof`, roofSections, materials.metal, materials.metal)
+}
+
+export function addRoofSheets(
+  root: THREE.Group,
+  id: string,
+  sections: readonly CanopySection[],
+  material: THREE.Material,
+  patchMaterial: THREE.Material,
+): void {
+  const vertices: number[] = []
+  const indices: number[] = []
+  const uvs: number[] = []
+  const edgeCaps: Beam[] = []
+  const corrugationRibs: Beam[] = []
+  const distances = [0]
+  for (let index = 0; index < sections.length - 1; index += 1) {
+    distances.push(distances.at(-1)! + sections[index]!.frame.point.distanceTo(sections[index + 1]!.frame.point))
+  }
+  const roofThickness = 0.1
+  const topLift = 0.055
+  const undersideDrop = roofThickness - topLift
+  const addFace = (
+    points: readonly [THREE.Vector3, THREE.Vector3, THREE.Vector3, THREE.Vector3],
+    startDistance: number,
+    endDistance: number,
+    reverse: boolean,
+  ): void => {
+    const offset = vertices.length / 3
+    points.forEach(point => vertices.push(point.x, point.y, point.z))
+    uvs.push(0, startDistance, 1, startDistance, 0, endDistance, 1, endDistance)
+    if (reverse) indices.push(offset, offset + 1, offset + 2, offset + 1, offset + 3, offset + 2)
+    else indices.push(offset, offset + 2, offset + 1, offset + 1, offset + 2, offset + 3)
+  }
+  for (let index = 0; index < sections.length - 1; index += 1) {
+    const current = sections[index]!
+    const next = sections[index + 1]!
+    for (const [startA, startB, endA, endB] of [
+      [current.leftEave, current.ridge, next.leftEave, next.ridge],
+      [current.ridge, current.rightEave, next.ridge, next.rightEave],
+    ] as const) {
+      const topPoints = [startA, startB, endA, endB].map(point =>
+        point.clone().addScaledVector(LOCAL_UP, topLift),
+      ) as unknown as readonly [THREE.Vector3, THREE.Vector3, THREE.Vector3, THREE.Vector3]
+      const undersidePoints = [startA, startB, endA, endB].map(point =>
+        point.clone().addScaledVector(LOCAL_UP, -undersideDrop),
+      ) as unknown as readonly [THREE.Vector3, THREE.Vector3, THREE.Vector3, THREE.Vector3]
+      addFace(topPoints, distances[index]!, distances[index + 1]!, false)
+      addFace(undersidePoints, distances[index]!, distances[index + 1]!, true)
+    }
+    const leftTopStart = current.leftEave.clone().addScaledVector(LOCAL_UP, topLift)
+    const leftTopEnd = next.leftEave.clone().addScaledVector(LOCAL_UP, topLift)
+    const leftBottomStart = current.leftEave.clone().addScaledVector(LOCAL_UP, -undersideDrop)
+    const leftBottomEnd = next.leftEave.clone().addScaledVector(LOCAL_UP, -undersideDrop)
+    const rightTopStart = current.rightEave.clone().addScaledVector(LOCAL_UP, topLift)
+    const rightTopEnd = next.rightEave.clone().addScaledVector(LOCAL_UP, topLift)
+    const rightBottomStart = current.rightEave.clone().addScaledVector(LOCAL_UP, -undersideDrop)
+    const rightBottomEnd = next.rightEave.clone().addScaledVector(LOCAL_UP, -undersideDrop)
+    addFace(
+      [leftBottomStart, leftTopStart, leftBottomEnd, leftTopEnd],
+      distances[index]!,
+      distances[index + 1]!,
+      false,
+    )
+    addFace(
+      [rightTopStart, rightBottomStart, rightTopEnd, rightBottomEnd],
+      distances[index]!,
+      distances[index + 1]!,
+      false,
+    )
+    edgeCaps.push(
+      beam(leftTopStart, leftTopEnd, 0.055, 0.06),
+      beam(
+        current.ridge.clone().addScaledVector(LOCAL_UP, topLift + 0.02),
+        next.ridge.clone().addScaledVector(LOCAL_UP, topLift + 0.02),
+        0.085,
+        0.075,
+      ),
+      beam(rightTopStart, rightTopEnd, 0.055, 0.06),
+    )
+  }
+  for (const section of sections) {
+    corrugationRibs.push(
+      beam(
+        section.leftEave.clone().addScaledVector(LOCAL_UP, topLift + 0.015),
+        section.ridge.clone().addScaledVector(LOCAL_UP, topLift + 0.015),
+        0.038,
+        0.045,
+      ),
+      beam(
+        section.ridge.clone().addScaledVector(LOCAL_UP, topLift + 0.015),
+        section.rightEave.clone().addScaledVector(LOCAL_UP, topLift + 0.015),
+        0.038,
+        0.045,
+      ),
+    )
+  }
+  const geometry = new THREE.BufferGeometry()
+  geometry.setAttribute('position', new THREE.Float32BufferAttribute(vertices, 3))
+  geometry.setAttribute('uv', new THREE.Float32BufferAttribute(uvs, 2))
+  geometry.setIndex(indices)
+  geometry.computeVertexNormals()
+  geometry.userData.canopyLayout = 'layered-continuous-gabled-ribbon'
+  geometry.userData.canopySectionCount = sections.length
+  geometry.userData.roofThickness = roofThickness
+  const roof = new THREE.Mesh(geometry, material)
+  roof.name = id
+  decorate(roof, 'rocky-mountain-wild-west', 'covered-mine-roof')
+  root.add(roof)
+  addBeamBatch(
+    root,
+    `${id}-edge-caps`,
+    edgeCaps,
+    material,
+    'rocky-mountain-wild-west',
+    false,
+    true,
+  )
+  addBeamBatch(
+    root,
+    `${id}-raised-seams`,
+    corrugationRibs,
+    material,
+    'rocky-mountain-wild-west',
+    false,
+    true,
+  )
+  addRoofPatchPanels(root, `${id}-weathered-patch-panels`, sections, patchMaterial, topLift + 0.025)
+}
+
+function addRoofPatchPanels(
+  root: THREE.Group,
+  name: string,
+  sections: readonly CanopySection[],
+  material: THREE.Material,
+  lift: number,
+): void {
+  const vertices: number[] = []
+  const indices: number[] = []
+  const uvs: number[] = []
+  const thickness = 0.035
+  let panelCount = 0
+
+  const appendPanel = (corners: readonly [THREE.Vector3, THREE.Vector3, THREE.Vector3, THREE.Vector3]): void => {
+    const top = corners.map(point => point.clone().addScaledVector(LOCAL_UP, lift)) as unknown as readonly [
+      THREE.Vector3,
+      THREE.Vector3,
+      THREE.Vector3,
+      THREE.Vector3,
+    ]
+    const bottom = top.map(point => point.clone().addScaledVector(LOCAL_UP, -thickness)) as unknown as readonly [
+      THREE.Vector3,
+      THREE.Vector3,
+      THREE.Vector3,
+      THREE.Vector3,
+    ]
+    const faces = [
+      [top[0], top[1], top[2], top[3]],
+      [bottom[1], bottom[0], bottom[3], bottom[2]],
+      [bottom[0], top[0], bottom[2], top[2]],
+      [top[1], bottom[1], top[3], bottom[3]],
+      [bottom[0], bottom[1], top[0], top[1]],
+      [top[2], top[3], bottom[2], bottom[3]],
+    ] as const
+    for (const face of faces) {
+      const offset = vertices.length / 3
+      face.forEach(point => vertices.push(point.x, point.y, point.z))
+      uvs.push(0, 0, 1, 0, 0, 1, 1, 1)
+      indices.push(offset, offset + 2, offset + 1, offset + 1, offset + 2, offset + 3)
+    }
+    panelCount += 1
+  }
+
+  const segmentCount = sections.length - 1
+  const selectedSegments = Array.from(
+    new Set(
+      segmentCount >= 8
+        ? [Math.floor(segmentCount * 0.28), Math.floor(segmentCount * 0.72)]
+        : [Math.floor(segmentCount * 0.5)],
+    ),
+  )
+  for (const index of selectedSegments) {
+    const current = sections[index]!
+    const next = sections[index + 1]!
+    const seed = deterministic(`${name}:${index}`)
+    const side = (index + (seed > 0.5 ? 1 : 0)) % 2 === 0 ? 'left' : 'right'
+    const startProgress = 0.08 + seed * 0.12
+    const endProgress = 0.72 + deterministic(`${name}:${index}:end`) * 0.18
+    const startOuter = side === 'left' ? current.leftEave : current.ridge
+    const startInner = side === 'left' ? current.ridge : current.rightEave
+    const endOuter = side === 'left' ? next.leftEave : next.ridge
+    const endInner = side === 'left' ? next.ridge : next.rightEave
+    appendPanel([
+      startOuter.clone().lerp(startInner, startProgress),
+      startOuter.clone().lerp(startInner, endProgress),
+      endOuter.clone().lerp(endInner, startProgress),
+      endOuter.clone().lerp(endInner, endProgress),
+    ])
+  }
+  if (panelCount === 0) return
+  const geometry = new THREE.BufferGeometry()
+  geometry.setAttribute('position', new THREE.Float32BufferAttribute(vertices, 3))
+  geometry.setAttribute('uv', new THREE.Float32BufferAttribute(uvs, 2))
+  geometry.setIndex(indices)
+  geometry.computeVertexNormals()
+  geometry.userData.canopyPatchPanelCount = panelCount
+  geometry.userData.canopyPatchThickness = thickness
+  const patches = new THREE.Mesh(geometry, material)
+  patches.name = name
+  decorate(patches, 'rocky-mountain-wild-west', 'covered-mine-roof-patches')
+  root.add(patches)
+}
+
+function addSakuraRoofedGate(
+  root: THREE.Group,
+  id: string,
+  runFrames: readonly AppearanceCanopyFrame[],
+  materials: AppearanceCanopyMaterials,
+  supportOptions: SupportOptions,
+): void {
+  const themeId = 'japanese-sakura-lake'
+  const vermilion = materials.wall
+  const kawara = materials.sakuraKawara ?? materials.metal
+  const masonry = materials.sakuraMasonry ?? materials.metal
+  const supportFrames = addOpenPortSupportInsets(sampleFrames(runFrames, 1.86), supportOptions)
+  const supported = supportSections(supportFrames, supportOptions)
+  const roofFrames = sampleFrames(runFrames, 0.34)
+  const supports: Beam[] = []
+  const lowerRails: Beam[] = []
+  const feet: Beam[] = []
+  const bolts: THREE.Vector3[] = []
+
+  for (const { section: frame } of supported) {
+    const halfSpan = frame.width / 2 + 0.18
+    const leftBase = frame.point.clone().addScaledVector(frame.right, -halfSpan).addScaledVector(LOCAL_UP, -0.08)
+    const rightBase = frame.point.clone().addScaledVector(frame.right, halfSpan).addScaledVector(LOCAL_UP, -0.08)
+    const leftFootBase = frame.point.clone().addScaledVector(frame.right, -halfSpan).addScaledVector(frame.up, -0.08)
+    const rightFootBase = frame.point.clone().addScaledVector(frame.right, halfSpan).addScaledVector(frame.up, -0.08)
+    const leftTop = frame.point.clone().addScaledVector(frame.right, -halfSpan).addScaledVector(LOCAL_UP, 2.58)
+    const rightTop = frame.point.clone().addScaledVector(frame.right, halfSpan).addScaledVector(LOCAL_UP, 2.58)
+    supports.push(
+      beam(leftBase, leftTop, 0.34, 0.38),
+      beam(rightBase, rightTop, 0.34, 0.38),
+      beam(
+        frame.point.clone().addScaledVector(frame.right, -(halfSpan + 0.34)).addScaledVector(LOCAL_UP, 2.58),
+        frame.point.clone().addScaledVector(frame.right, halfSpan + 0.34).addScaledVector(LOCAL_UP, 2.58),
+        0.28,
+        0.42,
+      ),
+      beam(
+        frame.point.clone().addScaledVector(frame.right, -halfSpan).addScaledVector(LOCAL_UP, 2.32),
+        frame.point.clone().addScaledVector(frame.right, halfSpan).addScaledVector(LOCAL_UP, 2.32),
+        0.18,
+        0.34,
+      ),
+    )
+    feet.push(
+      beam(leftFootBase, leftFootBase.clone().addScaledVector(frame.up, 0.22), 0.64, 0.62),
+      beam(rightFootBase, rightFootBase.clone().addScaledVector(frame.up, 0.22), 0.64, 0.62),
+    )
+    bolts.push(
+      leftBase.clone().addScaledVector(LOCAL_UP, 0.76).addScaledVector(frame.tangent, 0.22),
+      leftTop.clone().addScaledVector(LOCAL_UP, -0.42).addScaledVector(frame.tangent, 0.22),
+      rightBase.clone().addScaledVector(LOCAL_UP, 0.76).addScaledVector(frame.tangent, 0.22),
+      rightTop.clone().addScaledVector(LOCAL_UP, -0.42).addScaledVector(frame.tangent, 0.22),
+    )
+  }
+
+  for (let index = 0; index < supportFrames.length - 1; index += 1) {
+    const current = supportFrames[index]!
+    const next = supportFrames[index + 1]!
+    for (const side of [-1, 1] as const) {
+      const currentHalfSpan = current.width / 2 + 0.18
+      const nextHalfSpan = next.width / 2 + 0.18
+      lowerRails.push(
+        beam(
+          current.point
+            .clone()
+            .addScaledVector(current.right, side * currentHalfSpan)
+            .addScaledVector(LOCAL_UP, 0.56),
+          next.point
+            .clone()
+            .addScaledVector(next.right, side * nextHalfSpan)
+            .addScaledVector(LOCAL_UP, 0.56),
+          0.18,
+          0.18,
+        ),
+      )
+    }
+  }
+
+  const supportMesh = addBeamBatch(root, `${id}-sakura-vermilion-frames`, supports, vermilion, themeId, false)
+  const lowerRailMesh = addBeamBatch(
+    root,
+    `${id}-sakura-vermilion-lower-rails`,
+    lowerRails,
+    vermilion,
+    themeId,
+    false,
+    true,
+  )
+  const footMesh = addBeamBatch(root, `${id}-sakura-masonry-feet`, feet, masonry, themeId, false)
+  addJointBatch(root, `${id}-sakura-gunmetal-bolts`, bolts, materials.metal, themeId, 'sakura-gate-hardware', 0.065)
+  if (supportMesh) {
+    supportMesh.userData.themeRole = 'sakura-roofed-gate-frame'
+    supportMesh.userData.canopySectionCount = roofFrames.length
+    supportMesh.userData.canopySupportSectionCount = supported.length
+  }
+  if (lowerRailMesh) {
+    lowerRailMesh.userData.themeRole = 'sakura-roofed-gate-lower-rail'
+    lowerRailMesh.userData.canopyLowerRailSegmentCount = lowerRails.length
+  }
+  if (footMesh) footMesh.userData.themeRole = 'sakura-roofed-gate-surface-aligned-foot'
+
+  const roofSections = roofFrames.map(frame => {
+    const halfSpan = frame.width / 2 + 0.82
+    return {
+      frame,
+      leftEave: frame.point.clone().addScaledVector(frame.right, -halfSpan).addScaledVector(LOCAL_UP, 2.6),
+      ridge: frame.point.clone().addScaledVector(LOCAL_UP, 3.5),
+      rightEave: frame.point.clone().addScaledVector(frame.right, halfSpan).addScaledVector(LOCAL_UP, 2.6),
+    }
+  })
+  addSakuraRoofBacking(root, `${id}-sakura-kawara-backing`, roofSections, kawara, themeId)
+  addSakuraRoofTiles(root, `${id}-sakura-kawara-tiles`, roofSections, kawara, themeId)
+}
+
+function addSakuraRoofBacking(
+  root: THREE.Group,
+  name: string,
+  sections: readonly CanopySection[],
+  material: THREE.Material,
+  themeId: string,
+): void {
+  const positions: number[] = []
+  const uvs: number[] = []
+  const indices: number[] = []
+  const distances = [0]
+  for (let index = 0; index < sections.length - 1; index += 1) {
+    distances.push(distances.at(-1)! + sections[index]!.frame.point.distanceTo(sections[index + 1]!.frame.point))
+  }
+  const append = (points: readonly THREE.Vector3[], startDistance: number, endDistance: number, reverse: boolean) => {
+    const offset = positions.length / 3
+    points.forEach(point => positions.push(point.x, point.y, point.z))
+    uvs.push(0, startDistance, 1, startDistance, 0, endDistance, 1, endDistance)
+    indices.push(
+      ...(reverse
+        ? [offset, offset + 1, offset + 2, offset + 1, offset + 3, offset + 2]
+        : [offset, offset + 2, offset + 1, offset + 1, offset + 2, offset + 3]),
+    )
+  }
+  for (let index = 0; index < sections.length - 1; index += 1) {
+    const current = sections[index]!
+    const next = sections[index + 1]!
+    for (const [a, b, c, d] of [
+      [current.leftEave, current.ridge, next.leftEave, next.ridge],
+      [current.ridge, current.rightEave, next.ridge, next.rightEave],
+    ] as const) {
+      append(
+        [a, b, c, d].map(point => point.clone().addScaledVector(LOCAL_UP, 0.02)),
+        distances[index]!,
+        distances[index + 1]!,
+        false,
+      )
+      append(
+        [a, b, c, d].map(point => point.clone().addScaledVector(LOCAL_UP, -0.09)),
+        distances[index]!,
+        distances[index + 1]!,
+        true,
+      )
+    }
+  }
+  const geometry = new THREE.BufferGeometry()
+  geometry.setAttribute('position', new THREE.Float32BufferAttribute(positions, 3))
+  geometry.setAttribute('uv', new THREE.Float32BufferAttribute(uvs, 2))
+  geometry.setIndex(indices)
+  geometry.computeVertexNormals()
+  geometry.userData.canopyLayout = 'continuous-sakura-kawara-backing'
+  geometry.userData.canopySectionCount = sections.length
+  const roof = new THREE.Mesh(geometry, material)
+  roof.name = name
+  decorate(roof, themeId, 'sakura-kawara-roof-backing')
+  root.add(roof)
+}
+
+function addSakuraRoofTiles(
+  root: THREE.Group,
+  name: string,
+  sections: readonly CanopySection[],
+  material: THREE.Material,
+  themeId: string,
+): void {
+  // The roof backing supplies the solid surface; tiles only need a curved outer shell.
+  const tileGeometry = new VisualCylinderGeometry(0.5, 0.5, 1, 4, 1, true, 0, Math.PI)
+  const tilesPerSection = 8
+  const tiles = new THREE.InstancedMesh(tileGeometry, material, sections.length * tilesPerSection)
+  tiles.name = name
+  let tileIndex = 0
+  for (const section of sections) {
+    for (const side of [-1, 1] as const) {
+      const eave = side < 0 ? section.leftEave : section.rightEave
+      for (let segment = 0; segment < 4; segment += 1) {
+        const startProgress = Math.max(0, segment / 4 - 0.018)
+        const endProgress = Math.min(1, (segment + 1) / 4 + 0.035)
+        const start = section.ridge.clone().lerp(eave, startProgress).addScaledVector(LOCAL_UP, 0.09)
+        const end = section.ridge.clone().lerp(eave, endProgress).addScaledVector(LOCAL_UP, 0.09)
+        const direction = end.clone().sub(start)
+        const length = direction.length()
+        const align = new THREE.Quaternion().setFromUnitVectors(LOCAL_UP, direction.normalize())
+        align.multiply(new THREE.Quaternion().setFromAxisAngle(LOCAL_UP, side < 0 ? Math.PI : 0))
+        tiles.setMatrixAt(
+          tileIndex++,
+          new THREE.Matrix4().compose(
+            start.clone().lerp(end, 0.5),
+            align,
+            new THREE.Vector3(0.21, length, 0.21),
+          ),
+        )
+      }
+    }
+  }
+  tiles.instanceMatrix.needsUpdate = true
+  tiles.userData.canopySectionCount = sections.length
+  tiles.userData.kawaraTileCount = tiles.count
+  tiles.userData.mirroredRoofSides = true
+  decorate(tiles, themeId, 'sakura-kawara-tile-shell')
+  root.add(tiles)
+
+  const eaveGeometry = new VisualCylinderGeometry(0.5, 0.5, 1, 12)
+  const eaveCaps = new THREE.InstancedMesh(eaveGeometry, material, sections.length * 2)
+  eaveCaps.name = `${name}-scalloped-eaves`
+  let capIndex = 0
+  for (const section of sections) {
+    for (const eave of [section.leftEave, section.rightEave]) {
+      const quaternion = new THREE.Quaternion().setFromUnitVectors(LOCAL_UP, section.frame.tangent)
+      eaveCaps.setMatrixAt(
+        capIndex++,
+        new THREE.Matrix4().compose(
+          eave.clone().addScaledVector(LOCAL_UP, 0.075),
+          quaternion,
+          new THREE.Vector3(0.27, 0.12, 0.27),
+        ),
+      )
+    }
+  }
+  eaveCaps.instanceMatrix.needsUpdate = true
+  decorate(eaveCaps, themeId, 'sakura-kawara-eave-cap')
+  root.add(eaveCaps)
+
+  const ridge: Beam[] = []
+  for (let index = 0; index < sections.length - 1; index += 1) {
+    ridge.push(beam(sections[index]!.ridge, sections[index + 1]!.ridge, 0.3, 0.3))
+  }
+  const ridgeMesh = addBeamBatch(root, `${name}-ridge`, ridge, material, themeId, true)
+  if (ridgeMesh) ridgeMesh.userData.themeRole = 'sakura-kawara-ridge'
+}
+
+function beam(start: THREE.Vector3, end: THREE.Vector3, width: number, depth: number): Beam {
+  return { start, end, width, depth }
+}
+
+function addBeamBatch(
+  root: THREE.Group,
+  name: string,
+  beams: readonly Beam[],
+  material: THREE.Material,
+  themeId: string,
+  rounded: boolean,
+  beveled = false,
+): THREE.InstancedMesh | undefined {
+  if (beams.length === 0) return undefined
+  const geometry = rounded
+    ? new VisualCylinderGeometry(0.5, 0.62, 1, 7)
+    : beveled
+      ? new VisualBoxGeometry(1, 1, 1, 2, 0.08)
+      : new THREE.BoxGeometry(1, 1, 1)
+  const mesh = new THREE.InstancedMesh(geometry, material, beams.length)
+  mesh.name = name
+  beams.forEach((item, index) => {
+    const direction = item.end.clone().sub(item.start)
+    const length = direction.length()
+    const quaternion = new THREE.Quaternion().setFromUnitVectors(LOCAL_UP, direction.normalize())
+    mesh.setMatrixAt(
+      index,
+      new THREE.Matrix4().compose(
+        item.start.clone().lerp(item.end, 0.5),
+        quaternion,
+        new THREE.Vector3(item.width, length, item.depth),
+      ),
+    )
+  })
+  mesh.instanceMatrix.needsUpdate = true
+  decorate(mesh, themeId, rounded ? 'sakura-kawara-ridge' : 'covered-mine-timber')
+  root.add(mesh)
+  return mesh
+}
+
+function addFastenerBatch(
+  root: THREE.Group,
+  name: string,
+  fasteners: readonly Fastener[],
+  material: THREE.Material,
+  themeId: string,
+): THREE.InstancedMesh | undefined {
+  if (fasteners.length === 0) return undefined
+  const geometry = new VisualCylinderGeometry(0.045, 0.045, 0.045, 12)
+  const mesh = new THREE.InstancedMesh(geometry, material, fasteners.length)
+  mesh.name = name
+  fasteners.forEach(({ point, outward }, index) => {
+    const quaternion = new THREE.Quaternion().setFromUnitVectors(LOCAL_UP, outward.clone().normalize())
+    mesh.setMatrixAt(index, new THREE.Matrix4().compose(point, quaternion, new THREE.Vector3(1, 1, 1)))
+  })
+  mesh.instanceMatrix.needsUpdate = true
+  decorate(mesh, themeId, 'covered-mine-fasteners')
+  root.add(mesh)
+  return mesh
+}
+
+function addJointBatch(
+  root: THREE.Group,
+  name: string,
+  points: readonly THREE.Vector3[],
+  material: THREE.Material,
+  themeId: string,
+  role: string,
+  radius: number,
+): void {
+  if (points.length === 0) return
+  const mesh = new THREE.InstancedMesh(new THREE.DodecahedronGeometry(radius, 0), material, points.length)
+  mesh.name = name
+  points.forEach((point, index) => mesh.setMatrixAt(index, new THREE.Matrix4().makeTranslation(...point.toArray())))
+  mesh.instanceMatrix.needsUpdate = true
+  decorate(mesh, themeId, role)
+  root.add(mesh)
+}
+
+function decorate(object: THREE.Object3D, themeId: string, role: string): void {
+  object.userData.themeOnly = themeId
+  object.userData.themeRole = role
+  object.userData.decorative = true
+  object.castShadow = true
+  object.receiveShadow = true
+}
+
+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
+}