@marble.fun/track-catalog 3.0.0

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

@@ -0,0 +1,1031 @@
+import { geometryDetailProfile } from '../../../three/geometry-detail'
+import * as THREE from 'three'
+
+import { distributePathPattern } from './path-pattern-layout'
+import { addCanonicalWallTerminalSkins } from './track-appearance-wall-terminal'
+import { TRACK_RAIL_WALL_THICKNESS } from './track-definition'
+import {
+  resampleCanonicalWallRun,
+  type CanonicalWallRun,
+  type RawWallFrame,
+} from './track-surface-topology'
+
+export type SakuraCastleWallPathFrame = RawWallFrame
+export type SakuraCastleWallPathRun = CanonicalWallRun
+
+export interface SakuraCastleWallMaterials {
+  timber: THREE.Material
+  masonry: THREE.Material
+  kawara: THREE.Material
+}
+
+const FRAME_SPACING = 1.2 * geometryDetailProfile.ribbonTolerance
+const POST_MAXIMUM_SPACING = 1.2
+const KAWARA_TILE_SPACING = 0.22
+const KAWARA_TILE_ROWS = 2
+const ROOF_HALF_SPAN = 0.27
+const ROOF_RISE = 0.17
+const ROOF_EAVE_LIFT = 0.015
+const CONNECTED_ROOF_SEAM_OVERLAP = 0.03
+let sharedTimberPostGeometry: THREE.BoxGeometry | undefined
+let sharedKawaraTileGeometry: THREE.BufferGeometry | undefined
+
+/**
+ * Adds the visual language selected by the Sakura castle-wall appearance:
+ * masonry sill, timber framing, and a shallow kawara roof. The ordinary wall
+ * mesh remains the plaster body and the only corresponding Rapier collider.
+ */
+export function addSakuraCastleWallVisual(
+  root: THREE.Group,
+  id: string,
+  runs: readonly SakuraCastleWallPathRun[],
+  wallHeight: number,
+  materials: SakuraCastleWallMaterials,
+): THREE.Group | undefined {
+  if (wallHeight <= 0.08) return undefined
+  const group = new THREE.Group()
+  group.name = `${id}-sakura-castle-wall`
+  group.userData.themeOnly = 'japanese-sakura-lake'
+  group.userData.decorative = true
+  group.userData.visualOnly = true
+  group.userData.appearance = 'japanese-sakura-castle-wall'
+
+  const postMatrices: THREE.Matrix4[] = []
+  const railPositions: number[] = []
+  const railUvs: number[] = []
+  const railMetricUvs: number[] = []
+  const railIndices: number[] = []
+  const tileMatrices: THREE.Matrix4[] = []
+  let tilePlacementRunCount = 0
+  let connectedRoofOverlapRunCount = 0
+  let tJunctionRoofOverlapRunCount = 0
+  let tJunctionTileMinimumStartProjection = Number.POSITIVE_INFINITY
+  let runCount = 0
+  const masonryHeight = Math.min(0.27, wallHeight * 0.24)
+  const terminalKey = (frame: SakuraCastleWallPathFrame): string =>
+    frame.base.toArray().map(value => value.toFixed(4)).join(':')
+  const connectedEndOwner = new Map<string, number>()
+  runs.forEach((run, runIndex) => {
+    if (run.endOwnership !== 'connected' || run.frames.length < 2) return
+    const key = terminalKey(run.frames.at(-1)!)
+    if (!connectedEndOwner.has(key)) connectedEndOwner.set(key, runIndex)
+  })
+  const tJunctionConnectedStarts = new Set<number>()
+  runs.forEach((run, runIndex) => {
+    if (run.startOwnership !== 'connected' || run.frames.length < 2) return
+    const start = run.frames[0]!.base
+    const joinsReceiver = runs.some((receiver, receiverIndex) => {
+      if (receiverIndex === runIndex || receiver.frames.length < 2) return false
+      for (let index = 0; index < receiver.frames.length - 1; index += 1) {
+        const segmentStart = receiver.frames[index]!.base
+        const segmentEnd = receiver.frames[index + 1]!.base
+        const segment = segmentEnd.clone().sub(segmentStart).setY(0)
+        const lengthSquared = segment.lengthSq()
+        if (lengthSquared <= 0.000_001) continue
+        const progress = THREE.MathUtils.clamp(
+          start.clone().sub(segmentStart).setY(0).dot(segment) / lengthSquared,
+          0,
+          1,
+        )
+        // T-junction contacts lie inside the receiver segment. Ordinary
+        // end-to-start wall seams remain governed by the cadence phase logic.
+        if (progress <= 0.001 || progress >= 0.999) continue
+        const closest = segmentStart.clone().addScaledVector(segment, progress)
+        const receiverContactTolerance = TRACK_RAIL_WALL_THICKNESS / 2 + 0.001
+        if (
+          closest.setY(start.y).distanceToSquared(start) <=
+          receiverContactTolerance * receiverContactTolerance
+        ) return true
+      }
+      return false
+    })
+    if (joinsReceiver) tJunctionConnectedStarts.add(runIndex)
+  })
+
+  for (const [runIndex, run] of runs.entries()) {
+    if (run.frames.length < 2) continue
+    const canonicalRun = run
+    const frames = resampleCanonicalWallRun(canonicalRun, FRAME_SPACING).frames
+    const distances = pathDistances(frames)
+    const totalLength = distances.at(-1) ?? 0
+    if (totalLength <= 0.001) continue
+    runCount += 1
+    const capStart = run.capStart
+    const capEnd = run.capEnd
+    const ownsConnectedRoofEnd =
+      capEnd || connectedEndOwner.get(terminalKey(canonicalRun.frames.at(-1)!)) === runIndex
+    if (!capEnd && ownsConnectedRoofEnd) connectedRoofOverlapRunCount += 1
+
+    for (const face of [-1, 1] as const) {
+      const masonry = new THREE.Mesh(
+        // The sill is a facade over the canonical plaster backing, so it must
+        // use the exact same path rows. A separately resampled curve uses
+        // different chords and can pass behind the plaster between vertices.
+        createFaceBandGeometry(
+          canonicalRun.frames,
+          canonicalRun.frames.map(frame => frame.distance),
+          canonicalRun.length,
+          face,
+          0.008,
+          masonryHeight,
+          capStart,
+          capEnd,
+        ),
+        materials.masonry,
+      )
+      masonry.name = `${id}-sakura-castle-masonry-${runIndex + 1}-${face < 0 ? 'inside' : 'outside'}`
+      masonry.castShadow = true
+      masonry.receiveShadow = true
+      group.add(masonry)
+
+      // The roof is one continuous sweep over the canonical wall run. The old
+      // sharp-corner split created independently capped roof chunks, leaving
+      // holes and overlaps precisely where curved pieces changed direction.
+      const roofFrames = resampleCanonicalWallRun(canonicalRun, FRAME_SPACING).frames
+      const roofTileFrames = roofFramesWithTJunctionStartOverlap(
+        roofFrames,
+        tJunctionConnectedStarts.has(runIndex),
+      )
+      if (face < 0 && tJunctionConnectedStarts.has(runIndex)) tJunctionRoofOverlapRunCount += 1
+      const roofBackingFrames = roofFramesWithOwnedConnectedEnd(
+        roofTileFrames,
+        capEnd,
+        ownsConnectedRoofEnd,
+      )
+      const roofDistances = pathDistances(roofBackingFrames)
+      const roofLength = roofDistances.at(-1) ?? 0
+      const roof = new THREE.Mesh(
+        createRoofSlopeGeometry(roofBackingFrames, roofDistances, roofLength, wallHeight, face),
+        materials.kawara,
+      )
+      roof.name = `${id}-sakura-castle-kawara-${runIndex + 1}-${face < 0 ? 'inside' : 'outside'}`
+      roof.castShadow = true
+      roof.receiveShadow = true
+      group.add(roof)
+      const fascia = new THREE.Mesh(
+        createRoofEaveFasciaGeometry(roofBackingFrames, roofDistances, roofLength, wallHeight, face),
+        materials.kawara,
+      )
+      fascia.name = `${id}-sakura-castle-kawara-eave-${runIndex + 1}-${face < 0 ? 'inside' : 'outside'}`
+      fascia.castShadow = true
+      fascia.receiveShadow = true
+      group.add(fascia)
+      // Tiles must use the same canonical, uniformly sampled frame field as
+      // the roof sweep. Raw authored frames can contain duplicate seam points
+      // or abrupt basis changes at piece boundaries; sampling those directly
+      // occasionally rotates a tile's slope axis upright.
+      const tileRuns = kawaraTilePlacementRuns(roofTileFrames)
+      const tileMatrixStart = tileMatrices.length
+      for (const tileFrames of tileRuns) {
+        tilePlacementRunCount += 1
+        appendKawaraTileMatrices(
+          tileMatrices,
+          tileFrames,
+          wallHeight,
+          face,
+        )
+      }
+      if (tJunctionConnectedStarts.has(runIndex) && tileMatrices.length > tileMatrixStart) {
+        const terminal = canonicalRun.frames[0]!.base
+        const continuation = canonicalRun.frames[1]!.base.clone().sub(terminal).normalize()
+        for (let matrixIndex = tileMatrixStart; matrixIndex < tileMatrices.length; matrixIndex += 1) {
+          const matrix = tileMatrices[matrixIndex]!
+          const center = new THREE.Vector3().setFromMatrixPosition(matrix)
+          tJunctionTileMinimumStartProjection = Math.min(
+            tJunctionTileMinimumStartProjection,
+            center.clone().sub(terminal).dot(continuation),
+          )
+        }
+      }
+    }
+
+    const ridgeFrames = roofFramesWithOwnedConnectedEnd(
+      roofFramesWithTJunctionStartOverlap(frames, tJunctionConnectedStarts.has(runIndex)),
+      capEnd,
+      ownsConnectedRoofEnd,
+    )
+    const ridgeDistances = pathDistances(ridgeFrames)
+    const ridgeLength = ridgeDistances.at(-1) ?? 0
+    const ridge = new THREE.Mesh(
+      createContinuousKawaraRidgeGeometry(
+        ridgeFrames,
+        ridgeDistances,
+        ridgeLength,
+        wallHeight,
+        capStart,
+        capEnd,
+      ),
+      materials.kawara,
+    )
+    ridge.name = `${id}-sakura-castle-kawara-ridge-${runIndex + 1}`
+    ridge.userData.decorative = true
+    ridge.userData.visualOnly = true
+    ridge.userData.pathConstruction = 'continuous-swept-tube'
+    ridge.castShadow = true
+    ridge.receiveShadow = true
+    group.add(ridge)
+
+    for (const face of [-1, 1] as const) {
+      for (const height of [masonryHeight + 0.045, wallHeight - 0.065]) {
+        appendSweptTimberRail(
+          railPositions,
+          railUvs,
+          railMetricUvs,
+          railIndices,
+          frames,
+          distances,
+          totalLength,
+          face,
+          height,
+          capStart,
+          capEnd,
+        )
+      }
+    }
+  }
+
+  const postPlacements = distributePathPattern(
+    runs.map(run => ({
+      frames: run.frames.map(frame => ({
+        point: frame.base,
+        tangent: frame.tangent,
+        distance: frame.distance,
+      })),
+      length: run.length,
+      closed: run.closed,
+      // A connected wall terminal needs one architectural owner. The upstream
+      // run owns its end and the downstream run omits its start, producing one
+      // continuous vertical timber at the join instead of either a duplicate
+      // pair or the previous empty post bay.
+      includeStart: run.capStart,
+      includeEnd: true,
+    })),
+    {
+      maximumSpacing: POST_MAXIMUM_SPACING,
+      dedupeDistance: 0.025,
+    },
+  )
+  const worldUp = new THREE.Vector3(0, 1, 0)
+  // The masonry sill owns the lower wall band. Timber posts begin at its top
+  // seam (under the lower swept rail) instead of continuing through the
+  // brickwork to the deck.
+  const verticalPostBottom = masonryHeight - 0.03
+  const verticalPostHeight = Math.max(0.12, wallHeight - 0.06 - verticalPostBottom)
+  for (const placement of postPlacements) {
+    const tangent = placement.tangent.clone().setY(0)
+    if (tangent.lengthSq() <= 0.000_001) tangent.set(0, 0, 1)
+    tangent.normalize()
+    const frame: SakuraCastleWallPathFrame = {
+      base: placement.point,
+      tangent,
+      up: worldUp,
+      outward: new THREE.Vector3().crossVectors(tangent, worldUp).normalize(),
+    }
+    postMatrices.push(
+      new THREE.Matrix4().compose(
+        placement.point.clone().addScaledVector(worldUp, verticalPostBottom + verticalPostHeight / 2),
+        verticalFrameQuaternion(frame),
+        new THREE.Vector3(0.11, verticalPostHeight, TRACK_RAIL_WALL_THICKNESS + 0.055),
+      ),
+    )
+  }
+
+  if (runCount === 0) return undefined
+  if (postMatrices.length > 0) {
+    group.add(
+      instancedBatch(
+        `${id}-sakura-castle-timber-posts`,
+        getSharedTimberPostGeometry(),
+        materials.timber,
+        postMatrices,
+        true,
+      ),
+    )
+  }
+  if (railPositions.length > 0) {
+    const rails = new THREE.Mesh(
+      createGeometry(
+        railPositions,
+        railUvs,
+        railMetricUvs,
+        railIndices,
+        'sakura-castle-continuous-timber-rail-geometry',
+      ),
+      materials.timber,
+    )
+    rails.name = `${id}-sakura-castle-timber-rails`
+    rails.userData.decorative = true
+    rails.userData.visualOnly = true
+    rails.userData.pathConstruction = 'continuous-swept-beam'
+    rails.castShadow = true
+    rails.receiveShadow = true
+    group.add(rails)
+  }
+  if (tileMatrices.length > 0) {
+    group.add(
+      instancedBatch(
+        `${id}-sakura-castle-kawara-tiles`,
+        getSharedKawaraTileGeometry(),
+        materials.kawara,
+        tileMatrices,
+        true,
+      ),
+    )
+  }
+  addSakuraCastleTerminalGables(group, `${id}-sakura-castle`, runs, wallHeight, materials.kawara)
+  addCanonicalWallTerminalSkins(group, `${id}-sakura-castle`, runs, masonryHeight, {
+    material: materials.masonry,
+  })
+  const upperTerminalHeight = Math.max(0, wallHeight - masonryHeight)
+  if (upperTerminalHeight > 0.001) {
+    addCanonicalWallTerminalSkins(
+      group,
+      `${id}-sakura-castle-timber`,
+      runs,
+      upperTerminalHeight,
+      {
+        material: materials.timber,
+        verticalOffset: masonryHeight,
+      },
+    )
+  }
+  group.userData.runCount = runCount
+  group.userData.postCount = postMatrices.length
+  group.userData.roofTileCount = tileMatrices.length
+  group.userData.tilePlacementRunCount = tilePlacementRunCount
+  group.userData.connectedRoofOverlapRunCount = connectedRoofOverlapRunCount
+  group.userData.tJunctionRoofOverlapRunCount = tJunctionRoofOverlapRunCount
+  group.userData.tJunctionRoofOverlapDistance = TRACK_RAIL_WALL_THICKNESS / 2 + CONNECTED_ROOF_SEAM_OVERLAP
+  group.userData.tJunctionTileMinimumStartProjection = Number.isFinite(tJunctionTileMinimumStartProjection)
+    ? tJunctionTileMinimumStartProjection
+    : undefined
+  group.userData.roofConstruction = 'continuous-canonical-sweep'
+  group.userData.runTerminalOwnership = runs.map(run => ({
+    start: run.startOwnership,
+    end: run.endOwnership,
+    startBase: run.frames[0]!.base.toArray(),
+    endBase: run.frames.at(-1)!.base.toArray(),
+  }))
+  root.add(group)
+  return group
+}
+
+function addSakuraCastleTerminalGables(
+  root: THREE.Group,
+  id: string,
+  runs: readonly SakuraCastleWallPathRun[],
+  wallHeight: number,
+  material: THREE.Material,
+): void {
+  const positions: number[] = []
+  const indices: number[] = []
+  for (const run of runs) {
+    if (run.closed || run.frames.length < 2) continue
+    for (const [terminal, ownership] of [
+      ['start', run.startOwnership],
+      ['end', run.endOwnership],
+    ] as const) {
+      if (ownership !== 'exposed') continue
+      const frame = terminal === 'start' ? run.frames[0]! : run.frames.at(-1)!
+      const normal = frame.tangent.clone().multiplyScalar(terminal === 'start' ? -1 : 1).normalize()
+      const left = frame.base
+        .clone()
+        .addScaledVector(frame.outward, -ROOF_HALF_SPAN)
+        .addScaledVector(frame.up, wallHeight + ROOF_EAVE_LIFT - 0.03)
+      const ridge = frame.base.clone().addScaledVector(frame.up, wallHeight + ROOF_RISE - 0.03)
+      const right = frame.base
+        .clone()
+        .addScaledVector(frame.outward, ROOF_HALF_SPAN)
+        .addScaledVector(frame.up, wallHeight + ROOF_EAVE_LIFT - 0.03)
+      const offset = positions.length / 3
+      positions.push(...left.toArray(), ...ridge.toArray(), ...right.toArray())
+      const candidate = ridge.clone().sub(left).cross(right.clone().sub(left))
+      if (candidate.dot(normal) >= 0) indices.push(offset, offset + 1, offset + 2)
+      else indices.push(offset, offset + 2, offset + 1)
+    }
+  }
+  if (indices.length === 0) return
+  const geometry = new THREE.BufferGeometry()
+  geometry.name = 'sakura-castle-terminal-gable-geometry'
+  geometry.setAttribute('position', new THREE.Float32BufferAttribute(positions, 3))
+  geometry.setIndex(indices)
+  geometry.computeVertexNormals()
+  const mesh = new THREE.Mesh(geometry, material)
+  mesh.name = `${id}-terminal-gables`
+  mesh.castShadow = true
+  mesh.receiveShadow = true
+  mesh.userData.decorative = true
+  mesh.userData.visualOnly = true
+  root.add(mesh)
+}
+
+function createFaceBandGeometry(
+  frames: readonly SakuraCastleWallPathFrame[],
+  distances: readonly number[],
+  totalLength: number,
+  face: -1 | 1,
+  bottom: number,
+  top: number,
+  extendStart: boolean,
+  extendEnd: boolean,
+): THREE.BufferGeometry {
+  const positions: number[] = []
+  const uvs: number[] = []
+  const metricUvs: number[] = []
+  const indices: number[] = []
+  const faceOffset = face * (TRACK_RAIL_WALL_THICKNESS / 2 + 0.006)
+  frames.forEach((frame, index) => {
+    let facadeOffset = frame.outward.clone().multiplyScalar(faceOffset)
+    if (index > 0 && index < frames.length - 1) {
+      const incoming = frame.base.clone().sub(frames[index - 1]!.base).setY(0)
+      const outgoing = frames[index + 1]!.base.clone().sub(frame.base).setY(0)
+      if (incoming.lengthSq() > 0.000_001 && outgoing.lengthSq() > 0.000_001) {
+        incoming.normalize()
+        outgoing.normalize()
+        const incomingOutward = new THREE.Vector3(incoming.z, 0, -incoming.x)
+        const outgoingOutward = new THREE.Vector3(outgoing.z, 0, -outgoing.x)
+        if (incomingOutward.dot(frame.outward) < 0) incomingOutward.negate()
+        if (outgoingOutward.dot(frame.outward) < 0) outgoingOutward.negate()
+        const miter = incomingOutward.add(outgoingOutward)
+        if (miter.lengthSq() > 0.000_001) {
+          miter.normalize()
+          const projection = Math.max(0.000_001, Math.abs(miter.dot(outgoingOutward)))
+          facadeOffset = miter.multiplyScalar(faceOffset / projection)
+        }
+      }
+    }
+    // Connected wall ends already share the exact canonical connector row.
+    // Extending their facade past that row makes two pieces overlap and lets
+    // one sill protrude below/around the other. The wrap is only required at
+    // a genuinely exposed terminal.
+    const terminalExtension = index === 0 && extendStart
+      ? frame.tangent.clone().normalize().multiplyScalar(-Math.abs(faceOffset))
+      : index === frames.length - 1 && extendEnd
+        ? frame.tangent.clone().normalize().multiplyScalar(Math.abs(faceOffset))
+        : new THREE.Vector3()
+    for (const height of [bottom, top]) {
+      const point = frame.base
+        .clone()
+        .add(facadeOffset)
+        .add(terminalExtension)
+        .addScaledVector(frame.up, height - 0.03)
+      positions.push(point.x, point.y, point.z)
+      uvs.push(distances[index]!, height)
+      metricUvs.push(distances[index]!, height, 1, totalLength)
+    }
+  })
+  appendOrientedStripIndices(indices, positions, frames, frame => frame.outward.clone().multiplyScalar(face))
+  return createGeometry(positions, uvs, metricUvs, indices, 'sakura-castle-masonry-band-geometry')
+}
+
+function createRoofSlopeGeometry(
+  frames: readonly SakuraCastleWallPathFrame[],
+  distances: readonly number[],
+  totalLength: number,
+  wallHeight: number,
+  face: -1 | 1,
+): THREE.BufferGeometry {
+  const positions: number[] = []
+  const uvs: number[] = []
+  const metricUvs: number[] = []
+  const indices: number[] = []
+  const slopeLength = Math.hypot(ROOF_HALF_SPAN, ROOF_RISE - ROOF_EAVE_LIFT)
+  frames.forEach((frame, index) => {
+    const eave = frame.base
+      .clone()
+      .addScaledVector(frame.outward, face * ROOF_HALF_SPAN)
+      .addScaledVector(frame.up, wallHeight + ROOF_EAVE_LIFT - 0.03)
+    const ridge = frame.base.clone().addScaledVector(frame.up, wallHeight + ROOF_RISE - 0.03)
+    for (const [point, crossSlope] of [
+      [eave, slopeLength],
+      [ridge, 0],
+    ] as const) {
+      positions.push(point.x, point.y, point.z)
+      uvs.push(distances[index]!, crossSlope)
+      metricUvs.push(distances[index]!, crossSlope, 1, totalLength)
+    }
+  })
+  appendOrientedStripIndices(indices, positions, frames, frame => frame.up)
+  return createGeometry(positions, uvs, metricUvs, indices, 'sakura-castle-kawara-slope-geometry')
+}
+
+/**
+ * Open wall connectors meet on one docking plane. The run ending at that
+ * plane owns a tiny visual roof underlap; the run starting there stays exact.
+ * This closes transform/curve sampling tolerance without double-owning tiles
+ * or changing the canonical wall and collider boundary.
+ */
+function roofFramesWithOwnedConnectedEnd(
+  frames: readonly SakuraCastleWallPathFrame[],
+  capEnd: boolean,
+  ownsConnectedEnd = true,
+): SakuraCastleWallPathFrame[] {
+  const owned = frames.map(frame => ({
+    base: frame.base.clone(),
+    tangent: frame.tangent.clone(),
+    up: frame.up.clone(),
+    outward: frame.outward.clone(),
+  }))
+  if (!capEnd && ownsConnectedEnd && owned.length > 0) {
+    const end = owned.at(-1)!
+    const previous = owned[Math.max(0, owned.length - 2)]!
+    const continuation = end.base.clone().sub(previous.base)
+    if (continuation.lengthSq() > 0.000_001) {
+      end.base.addScaledVector(continuation.normalize(), CONNECTED_ROOF_SEAM_OVERLAP)
+    }
+  }
+  return owned
+}
+
+function roofFramesWithTJunctionStartOverlap(
+  frames: readonly SakuraCastleWallPathFrame[],
+  overlapsReceiver: boolean,
+): SakuraCastleWallPathFrame[] {
+  const owned = frames.map(frame => ({
+    base: frame.base.clone(),
+    tangent: frame.tangent.clone(),
+    up: frame.up.clone(),
+    outward: frame.outward.clone(),
+  }))
+  if (!overlapsReceiver || owned.length < 2) return owned
+  const start = owned[0]!
+  const next = owned[1]!
+  const continuation = next.base.clone().sub(start.base)
+  if (continuation.lengthSq() <= 0.000_001) return owned
+  start.base.addScaledVector(
+    continuation.normalize(),
+    -(TRACK_RAIL_WALL_THICKNESS / 2 + CONNECTED_ROOF_SEAM_OVERLAP),
+  )
+  return owned
+}
+
+function createRoofEaveFasciaGeometry(
+  frames: readonly SakuraCastleWallPathFrame[],
+  distances: readonly number[],
+  totalLength: number,
+  wallHeight: number,
+  face: -1 | 1,
+): THREE.BufferGeometry {
+  const positions: number[] = []
+  const uvs: number[] = []
+  const metricUvs: number[] = []
+  const indices: number[] = []
+  frames.forEach((frame, index) => {
+    const eave = roofSurfacePoint(frame, wallHeight, face, 1)
+    for (const drop of [0, 0.075]) {
+      const point = eave.clone().addScaledVector(frame.up, -drop)
+      positions.push(point.x, point.y, point.z)
+      uvs.push(distances[index]!, drop)
+      metricUvs.push(distances[index]!, drop, 1, totalLength)
+    }
+  })
+  appendOrientedStripIndices(
+    indices,
+    positions,
+    frames,
+    frame => frame.outward.clone().multiplyScalar(face),
+  )
+  return createGeometry(positions, uvs, metricUvs, indices, 'sakura-castle-kawara-eave-fascia-geometry')
+}
+
+function appendOrientedStripIndices(
+  indices: number[],
+  positions: readonly number[],
+  frames: readonly SakuraCastleWallPathFrame[],
+  desiredNormal: (frame: SakuraCastleWallPathFrame) => THREE.Vector3,
+): void {
+  for (let index = 0; index < frames.length - 1; index += 1) {
+    const current = index * 2
+    const next = current + 2
+    const target = desiredNormal(interpolateFrame(frames[index]!, frames[index + 1]!, 0.5)).normalize()
+    // Curved and graded strips are non-planar quads. Orient each triangle
+    // independently; borrowing the first triangle's winding for the second
+    // made alternating wedges disappear under FrontSide culling.
+    appendTriangleFacing(indices, positions, current, next, current + 1, target)
+    appendTriangleFacing(indices, positions, current + 1, next, next + 1, target)
+  }
+}
+
+function appendTriangleFacing(
+  indices: number[],
+  positions: readonly number[],
+  aIndex: number,
+  bIndex: number,
+  cIndex: number,
+  target: THREE.Vector3,
+): void {
+  const a = vectorAt(positions, aIndex)
+  const normal = vectorAt(positions, bIndex).sub(a).cross(vectorAt(positions, cIndex).sub(a))
+  if (normal.dot(target) >= 0) indices.push(aIndex, bIndex, cIndex)
+  else indices.push(aIndex, cIndex, bIndex)
+}
+
+function createContinuousKawaraRidgeGeometry(
+  frames: readonly SakuraCastleWallPathFrame[],
+  distances: readonly number[],
+  totalLength: number,
+  wallHeight: number,
+  capStart: boolean,
+  capEnd: boolean,
+): THREE.BufferGeometry {
+  const positions: number[] = []
+  const uvs: number[] = []
+  const metricUvs: number[] = []
+  const indices: number[] = []
+  const radius = 0.075
+  const radialSegments = 6
+  const circumference = Math.PI * radius * 2
+
+  frames.forEach((frame, frameIndex) => {
+    const center = frame.base.clone().addScaledVector(frame.up, wallHeight + ROOF_RISE - 0.03)
+    for (let radialIndex = 0; radialIndex < radialSegments; radialIndex += 1) {
+      const angle = (radialIndex / radialSegments) * Math.PI * 2
+      const point = center
+        .clone()
+        .addScaledVector(frame.outward, Math.cos(angle) * radius)
+        .addScaledVector(frame.up, Math.sin(angle) * radius)
+      positions.push(point.x, point.y, point.z)
+      uvs.push(distances[frameIndex]!, radialIndex / radialSegments)
+      metricUvs.push(distances[frameIndex]!, (radialIndex / radialSegments) * circumference, 1, totalLength)
+    }
+  })
+
+  for (let frameIndex = 0; frameIndex < frames.length - 1; frameIndex += 1) {
+    const current = frameIndex * radialSegments
+    const next = current + radialSegments
+    const frame = interpolateFrame(frames[frameIndex]!, frames[frameIndex + 1]!, 0.5)
+    for (let radialIndex = 0; radialIndex < radialSegments; radialIndex += 1) {
+      const following = (radialIndex + 1) % radialSegments
+      const angle = ((radialIndex + 0.5) / radialSegments) * Math.PI * 2
+      const target = frame.outward
+        .clone()
+        .multiplyScalar(Math.cos(angle))
+        .addScaledVector(frame.up, Math.sin(angle))
+        .normalize()
+      appendTriangleFacing(indices, positions, current + radialIndex, next + radialIndex, current + following, target)
+      appendTriangleFacing(indices, positions, current + following, next + radialIndex, next + following, target)
+    }
+  }
+
+  const appendCap = (frameIndex: number, target: THREE.Vector3): void => {
+    const frame = frames[frameIndex]!
+    const center = frame.base.clone().addScaledVector(frame.up, wallHeight + ROOF_RISE - 0.03)
+    const centerIndex = positions.length / 3
+    positions.push(center.x, center.y, center.z)
+    uvs.push(distances[frameIndex]!, 0.5)
+    metricUvs.push(distances[frameIndex]!, circumference / 2, 1, totalLength)
+    const ringStart = frameIndex * radialSegments
+    for (let radialIndex = 0; radialIndex < radialSegments; radialIndex += 1) {
+      const following = (radialIndex + 1) % radialSegments
+      appendTriangleFacing(indices, positions, centerIndex, ringStart + radialIndex, ringStart + following, target)
+    }
+  }
+
+  if (capStart) appendCap(0, frames[0]!.tangent.clone().negate())
+  if (capEnd) appendCap(frames.length - 1, frames.at(-1)!.tangent)
+
+  return createGeometry(positions, uvs, metricUvs, indices, 'sakura-castle-continuous-kawara-ridge-geometry')
+}
+
+function appendSweptTimberRail(
+  positions: number[],
+  uvs: number[],
+  metricUvs: number[],
+  indices: number[],
+  frames: readonly SakuraCastleWallPathFrame[],
+  distances: readonly number[],
+  totalLength: number,
+  face: -1 | 1,
+  height: number,
+  capStart: boolean,
+  capEnd: boolean,
+): void {
+  const firstVertex = positions.length / 3
+  const halfHeight = 0.0425
+  const halfDepth = 0.026
+  const faceOffset = face * (TRACK_RAIL_WALL_THICKNESS / 2 + halfDepth)
+  const crossSections = [
+    [-halfHeight, -halfDepth],
+    [halfHeight, -halfDepth],
+    [halfHeight, halfDepth],
+    [-halfHeight, halfDepth],
+  ] as const
+
+  frames.forEach((frame, frameIndex) => {
+    const center = frame.base
+      .clone()
+      .addScaledVector(frame.outward, faceOffset)
+      .addScaledVector(frame.up, height - 0.03)
+    crossSections.forEach(([vertical, depth], crossIndex) => {
+      const point = center.clone().addScaledVector(frame.up, vertical).addScaledVector(frame.outward, depth)
+      positions.push(point.x, point.y, point.z)
+      uvs.push(distances[frameIndex]!, crossIndex / crossSections.length)
+      metricUvs.push(crossIndex / crossSections.length, distances[frameIndex]!, 1, totalLength)
+    })
+  })
+
+  for (let frameIndex = 0; frameIndex < frames.length - 1; frameIndex += 1) {
+    const current = firstVertex + frameIndex * crossSections.length
+    const next = current + crossSections.length
+    const frame = interpolateFrame(frames[frameIndex]!, frames[frameIndex + 1]!, 0.5)
+    for (let side = 0; side < crossSections.length; side += 1) {
+      const following = (side + 1) % crossSections.length
+      const [verticalA, depthA] = crossSections[side]!
+      const [verticalB, depthB] = crossSections[following]!
+      const target = frame.up
+        .clone()
+        .multiplyScalar(verticalA + verticalB)
+        .addScaledVector(frame.outward, depthA + depthB)
+        .normalize()
+      appendTriangleFacing(indices, positions, current + side, next + side, current + following, target)
+      appendTriangleFacing(indices, positions, current + following, next + side, next + following, target)
+    }
+  }
+
+  const start = firstVertex
+  const end = firstVertex + (frames.length - 1) * crossSections.length
+  if (capStart) {
+    appendTriangleFacing(indices, positions, start, start + 1, start + 2, frames[0]!.tangent.clone().negate())
+    appendTriangleFacing(indices, positions, start, start + 2, start + 3, frames[0]!.tangent.clone().negate())
+  }
+  if (capEnd) {
+    appendTriangleFacing(indices, positions, end, end + 2, end + 1, frames.at(-1)!.tangent)
+    appendTriangleFacing(indices, positions, end, end + 3, end + 2, frames.at(-1)!.tangent)
+  }
+}
+
+function vectorAt(positions: readonly number[], vertex: number): THREE.Vector3 {
+  const offset = vertex * 3
+  return new THREE.Vector3(positions[offset]!, positions[offset + 1]!, positions[offset + 2]!)
+}
+
+function kawaraTilePlacementRuns(
+  frames: readonly SakuraCastleWallPathFrame[],
+): SakuraCastleWallPathFrame[][] {
+  if (frames.length < 3) return [[...frames]]
+  const runs: SakuraCastleWallPathFrame[][] = []
+  let current = [frames[0]!]
+  // Ordinary bends keep one rotating cadence. Only a near-right-angle authored
+  // junction resets placement so no rigid tile bridges across empty space.
+  const sharpCornerCosine = Math.cos(THREE.MathUtils.degToRad(78))
+  for (let index = 1; index < frames.length - 1; index += 1) {
+    const corner = frames[index]!
+    current.push(corner)
+    const incoming = corner.base.clone().sub(frames[index - 1]!.base)
+    const outgoing = frames[index + 1]!.base.clone().sub(corner.base)
+    if (
+      incoming.lengthSq() > 0.000_001 &&
+      outgoing.lengthSq() > 0.000_001 &&
+      incoming.normalize().dot(outgoing.normalize()) < sharpCornerCosine
+    ) {
+      runs.push(current)
+      current = [corner]
+    }
+  }
+  current.push(frames.at(-1)!)
+  runs.push(current)
+  return runs
+}
+
+function appendKawaraTileMatrices(
+  target: THREE.Matrix4[],
+  sourceFrames: readonly SakuraCastleWallPathFrame[],
+  wallHeight: number,
+  face: -1 | 1,
+): void {
+  const distances = pointDistances(sourceFrames.map(frame => roofSurfacePoint(frame, wallHeight, face, 1)))
+  const totalLength = distances.at(-1) ?? 0
+  if (totalLength <= 0.001) return
+  // Rigid tiles never straddle independently generated runs. Every run owns
+  // one half cadence cell at each terminal, so connected tile edges meet at
+  // the canonical seam without either curve projecting a tile backwards into
+  // its neighbour. The continuous roof backing and ridge still own the seam.
+  const startOffset = 0.5
+  const endOffset = 0.5
+  const tileCount = Math.max(
+    1,
+    Math.round(totalLength / KAWARA_TILE_SPACING - startOffset - endOffset + 1),
+  )
+  const intervalCount = startOffset + tileCount - 1 + endOffset
+  const tileArcLength = totalLength / Math.max(0.5, intervalCount)
+  for (let tileIndex = 0; tileIndex < tileCount; tileIndex += 1) {
+    const centerDistance = (startOffset + tileIndex) * tileArcLength
+    const startDistance = Math.max(0, centerDistance - tileArcLength / 2)
+    const endDistance = Math.min(totalLength, centerDistance + tileArcLength / 2)
+    const startFrame = sampleFrame(sourceFrames, distances, startDistance)
+    const endFrame = sampleFrame(sourceFrames, distances, endDistance)
+    const middleFrame = sampleFrame(sourceFrames, distances, centerDistance)
+    const ridge = roofSurfacePoint(middleFrame, wallHeight, face, 0)
+    const eave = roofSurfacePoint(middleFrame, wallHeight, face, 1)
+    // Build one orthonormal roof frame from the canonical centre sample.
+    // Using the curved surface chord as a matrix axis sheared isolated tiles
+    // whenever that chord contained a normal component on the inside of a
+    // bend. Those sheared tiles are the apparent upright fins.
+    const longitudinal = middleFrame.tangent.clone().normalize()
+    const slopeDirection = eave.clone().sub(ridge)
+    slopeDirection.addScaledVector(longitudinal, -slopeDirection.dot(longitudinal))
+    const slopeLength = slopeDirection.length()
+    if (slopeLength <= 0.001) continue
+    slopeDirection.normalize()
+    let surfaceNormal = new THREE.Vector3().crossVectors(slopeDirection, longitudinal).normalize()
+    if (surfaceNormal.dot(middleFrame.up) < 0) {
+      longitudinal.negate()
+      surfaceNormal = new THREE.Vector3().crossVectors(slopeDirection, longitudinal).normalize()
+    }
+    const rotation = new THREE.Quaternion().setFromRotationMatrix(
+      new THREE.Matrix4().makeBasis(longitudinal, surfaceNormal, slopeDirection),
+    )
+
+    for (let row = 0; row < KAWARA_TILE_ROWS; row += 1) {
+      const startFraction = row === 0 ? 0.015 : 0.45
+      const endFraction = row === 0 ? 0.56 : 0.985
+      const centerFraction = (startFraction + endFraction) / 2
+      const startCenter = roofSurfacePoint(startFrame, wallHeight, face, centerFraction)
+      const endCenter = roofSurfacePoint(endFrame, wallHeight, face, centerFraction)
+      const chord = endCenter.clone().sub(startCenter)
+      // Arc length chooses the cadence, but a rigid tile spans the straight
+      // 3D chord between its cell boundaries. Giving it the longer arc length
+      // makes adjacent instances overlap on the short side of a curve. Do not
+      // project the chord onto a rotating frame: that was the steep-slope
+      // shrink bug.
+      const reachesBeyondRun = centerDistance - tileArcLength / 2 < 0 || centerDistance + tileArcLength / 2 > totalLength
+      const tileWidth = reachesBeyondRun
+        ? tileArcLength
+        : Math.max(0.04, Math.min(tileArcLength, chord.length()))
+      const rowLength = slopeLength * (endFraction - startFraction)
+      const center = roofSurfacePoint(middleFrame, wallHeight, face, centerFraction)
+        .addScaledVector(surfaceNormal, 0.012 + row * 0.008)
+      const matrix = new THREE.Matrix4().compose(
+        center,
+        rotation,
+        new THREE.Vector3(tileWidth, 1, rowLength),
+      )
+      target.push(matrix)
+    }
+  }
+}
+
+function roofSurfacePoint(
+  frame: SakuraCastleWallPathFrame,
+  wallHeight: number,
+  face: -1 | 1,
+  slopeFraction: number,
+): THREE.Vector3 {
+  const ridge = frame.base.clone().addScaledVector(frame.up, wallHeight + ROOF_RISE - 0.03)
+  const eave = frame.base
+    .clone()
+    .addScaledVector(frame.outward, face * ROOF_HALF_SPAN)
+    .addScaledVector(frame.up, wallHeight + ROOF_EAVE_LIFT - 0.03)
+  return ridge.lerp(eave, slopeFraction)
+}
+
+function pointDistances(points: readonly THREE.Vector3[]): number[] {
+  const distances = [0]
+  for (let index = 1; index < points.length; index += 1) {
+    distances.push(distances[index - 1]! + points[index]!.distanceTo(points[index - 1]!))
+  }
+  return distances
+}
+
+function getSharedTimberPostGeometry(): THREE.BoxGeometry {
+  if (sharedTimberPostGeometry) return sharedTimberPostGeometry
+  sharedTimberPostGeometry = new THREE.BoxGeometry(1, 1, 1)
+  sharedTimberPostGeometry.name = 'sakura-castle-timber-post-geometry'
+  return sharedTimberPostGeometry
+}
+
+function getSharedKawaraTileGeometry(): THREE.BufferGeometry {
+  if (sharedKawaraTileGeometry) return sharedKawaraTileGeometry
+  const positions: number[] = []
+  const uvs: number[] = []
+  const metricUvs: number[] = []
+  const indices: number[] = []
+  const acrossSegments = 2
+  // Every tile row has the same cross-section and the slope axis is linear,
+  // so the old middle row described the exact same surface twice.
+  const slopeSegments = 1
+  const rowSize = acrossSegments + 1
+  const textureFootprint = 0.4
+  for (let slopeIndex = 0; slopeIndex <= slopeSegments; slopeIndex += 1) {
+    const v = slopeIndex / slopeSegments
+    const z = v - 0.5
+    for (let acrossIndex = 0; acrossIndex <= acrossSegments; acrossIndex += 1) {
+      const u = acrossIndex / acrossSegments
+      const x = u - 0.5
+      const arch = Math.max(0, Math.cos(x * Math.PI)) * 0.032
+      positions.push(x, arch + v * 0.006, z)
+      const rotatedU = v
+      const rotatedV = 1 - u
+      const textureU = 0.5 + (rotatedU - 0.5) * textureFootprint
+      const textureV = 0.5 + (rotatedV - 0.5) * textureFootprint
+      uvs.push(textureU, textureV)
+      // The tile is instanced in its wall-local frame. Mark its authored UVs
+      // so the shared material rotates with each instance instead of falling
+      // back to one world-projected texture direction.
+      metricUvs.push(textureU, textureV, 1, 1)
+    }
+  }
+  for (let slopeIndex = 0; slopeIndex < slopeSegments; slopeIndex += 1) {
+    const currentRow = slopeIndex * rowSize
+    const nextRow = currentRow + rowSize
+    for (let acrossIndex = 0; acrossIndex < acrossSegments; acrossIndex += 1) {
+      const current = currentRow + acrossIndex
+      const next = nextRow + acrossIndex
+      indices.push(current, next, current + 1, current + 1, next, next + 1)
+    }
+  }
+  const geometry = new THREE.BufferGeometry()
+  geometry.name = 'sakura-castle-kawara-tile-geometry'
+  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()
+  sharedKawaraTileGeometry = geometry
+  return sharedKawaraTileGeometry
+}
+
+function createGeometry(
+  positions: number[],
+  uvs: number[],
+  metricUvs: number[],
+  indices: number[],
+  name: string,
+): THREE.BufferGeometry {
+  const geometry = new THREE.BufferGeometry()
+  geometry.name = name
+  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()
+  return geometry
+}
+
+function pathDistances(frames: readonly SakuraCastleWallPathFrame[]): number[] {
+  const distances = [0]
+  for (let index = 1; index < frames.length; index += 1) {
+    distances.push(distances[index - 1]! + frames[index]!.base.distanceTo(frames[index - 1]!.base))
+  }
+  return distances
+}
+
+function sampleFrame(
+  frames: readonly SakuraCastleWallPathFrame[],
+  distances: readonly number[],
+  target: number,
+): SakuraCastleWallPathFrame {
+  let segment = 0
+  while (segment < distances.length - 2 && distances[segment + 1]! < target) segment += 1
+  const length = distances[segment + 1]! - distances[segment]!
+  return interpolateFrame(frames[segment]!, frames[segment + 1]!, length <= 0.000_001 ? 0 : (target - distances[segment]!) / length)
+}
+
+function interpolateFrame(
+  start: SakuraCastleWallPathFrame,
+  end: SakuraCastleWallPathFrame,
+  progress: number,
+): SakuraCastleWallPathFrame {
+  const tangent = start.tangent.clone().lerp(end.tangent, progress).normalize()
+  const up = start.up.clone().lerp(end.up, progress)
+  up.addScaledVector(tangent, -up.dot(tangent)).normalize()
+  const outward = new THREE.Vector3().crossVectors(tangent, up).normalize()
+  const outwardHint = start.outward.clone().lerp(end.outward, progress)
+  if (outward.dot(outwardHint) < 0) outward.negate()
+  return { base: start.base.clone().lerp(end.base, progress), tangent, up, outward }
+}
+
+function verticalFrameQuaternion(frame: SakuraCastleWallPathFrame): THREE.Quaternion {
+  const up = new THREE.Vector3(0, 1, 0)
+  const outward = frame.outward.clone().addScaledVector(up, -frame.outward.dot(up))
+  if (outward.lengthSq() < 0.000_001) outward.crossVectors(frame.tangent, up)
+  outward.normalize()
+  const tangent = new THREE.Vector3().crossVectors(up, outward).normalize()
+  outward.crossVectors(tangent, up).normalize()
+  return new THREE.Quaternion().setFromRotationMatrix(new THREE.Matrix4().makeBasis(tangent, up, outward))
+}
+
+function instancedBatch(
+  name: string,
+  geometry: THREE.BufferGeometry,
+  material: THREE.Material,
+  matrices: readonly THREE.Matrix4[],
+  sharedGeometry = false,
+): THREE.InstancedMesh {
+  const mesh = new THREE.InstancedMesh(geometry, material, matrices.length)
+  mesh.name = name
+  mesh.userData.decorative = true
+  mesh.userData.visualOnly = true
+  mesh.userData.sharedGeometry = sharedGeometry
+  mesh.castShadow = true
+  mesh.receiveShadow = true
+  matrices.forEach((matrix, index) => mesh.setMatrixAt(index, matrix))
+  mesh.instanceMatrix.needsUpdate = true
+  mesh.computeBoundingBox()
+  mesh.computeBoundingSphere()
+  return mesh
+}