@marble.fun/track-catalog 3.0.0

package/src/pages/play/race/track-mechanisms.ts

@@ -0,0 +1,1350 @@
+import RAPIER from '@dimforge/rapier3d-deterministic-compat'
+import {
+  ReboundPhysicsMechanism,
+  ConveyorPhysicsMechanism,
+  RisingWallPhysicsMechanism,
+  FlipperBankPhysicsMechanism,
+  SplitterPhysicsMechanism,
+  SPLITTER_CYCLE_SECONDS_RANGE,
+  SPLITTER_MAX_TIP_SPEED,
+  type SplitterMotionProfile,
+  VortexPhysicsMechanism,
+} from '@marble.fun/physics-engine'
+export { SPLITTER_CYCLE_SECONDS_RANGE, SPLITTER_MAX_TIP_SPEED } from '@marble.fun/physics-engine'
+import * as THREE from 'three'
+
+import { VisualSphereGeometry, VisualCylinderGeometry, VisualTorusGeometry } from '../../../three/visual-geometry'
+
+import type { MaterialSurfaceTreatment, TrackAppearanceDetailStyle } from '../../../three/track-theme'
+import { visualQualityPolicy, type VisualQualityPolicy } from '../../../three/visual-quality'
+
+import { FIXED_TIMESTEP } from './race-physics'
+import type {
+  ConveyorPieceDefinition,
+  DipperPieceDefinition,
+  ReboundPieceDefinition,
+  FlipperBankPieceDefinition,
+  PortalPieceDefinition,
+  RisingWallForestPieceDefinition,
+  SplitterPieceDefinition,
+  TrackVector,
+  TurntablePieceDefinition,
+  VortexPieceDefinition,
+} from './track-definition'
+import { trackSurfaceBasis } from './track-surface-basis'
+import { markDynamicTrackShadowRoot } from './track-shadow-batching'
+import { risingWallExposedHeight } from '../../track-lab/rising-wall-layout'
+import { addWildWestMineLiftFrame, decorateWildWestMineLiftShelf, WILD_WEST_THEME_ID } from './wild-west-mine-lift'
+import { addJungleTempleLiftSkin, decorateJungleTempleShelf, JUNGLE_TEMPLE_THEME_ID } from './jungle-temple-lift'
+import {
+  addPortalDerivedElevatorSkins,
+  decoratePortalDerivedElevatorShelf,
+  EGYPT_ELEVATOR_THEME_ID,
+  JAPAN_ELEVATOR_THEME_ID,
+  SPACE_ELEVATOR_THEME_ID,
+} from './portal-derived-elevator-skins'
+import { createReboundVisualFactory } from './rebound-visual'
+import {
+  createPortalEndpointVisual,
+  PORTAL_LIVE_VIEW_FADE_START_RATIO,
+  portalLiveViewBlend,
+  positionFixedPortalViewCamera,
+  renderFixedPortalView,
+  type PortalEndpointVisual,
+} from './portal-visual'
+import { PORTAL_LIVE_VIEW_HEIGHT, PORTAL_LIVE_VIEW_WIDTH } from './portal-proportions'
+import { SPACE_STATION_PORTAL_FRAME_THEME_ID } from './space-station-portal-frame'
+import {
+  createEndPivotedFlipperPaddleVisual,
+  createFlipperHubVisual,
+  createFlipperPaddleVisual,
+} from '../../track-lab/flipper-component'
+
+export type FloorSurfaceTreatment = MaterialSurfaceTreatment & {
+  material: THREE.Material
+  themeId: string | readonly string[]
+}
+
+export interface TrackMaterials {
+  /** Active theme identity used to gate theme-specific visual geometry. */
+  activeThemeId?: string
+  /** Track Lab keeps reusable theme geometry resident so theme changes do not rebuild pieces. */
+  prebuildThemeVariants?: boolean
+  top: THREE.Material
+  edge: THREE.Material
+  rail: THREE.Material
+  railBacking: THREE.Material
+  /** Transparent visual shell used only by the open shared rope wall. */
+  ropeWallBacking?: THREE.Material
+  rope?: THREE.Material
+  ropeWallEndGrain?: THREE.Material
+  ropeWallTimber?: THREE.Material
+  structure: THREE.Material
+  moving: THREE.Material
+  signal: THREE.Material
+  hazard: THREE.Material
+  portal: THREE.Material
+  energy: THREE.Material
+  railroad?: THREE.Material
+  /** Geometry family selected by the independent rail/overlay appearance. */
+  railDetailStyle?: TrackAppearanceDetailStyle
+  railroadTimber?: THREE.Material
+  obstacle?: THREE.Material
+  /** Generic obstacle trim/end-cap role; Japanese Sakura binds dark gunmetal here. */
+  obstacleAccent?: THREE.Material
+  /** Generic obstacle mounting/base role; Japanese Sakura binds dark gunmetal here. */
+  obstacleBase?: THREE.Material
+  /** Rectangular flipper-bar role; Japanese Sakura binds polished silver here. */
+  flipperPrimary?: THREE.Material
+  /** Flipper base/hub role; Japanese Sakura binds dark gunmetal here. */
+  flipperSecondary?: THREE.Material
+  mineTimber?: THREE.Material
+  coveredMineTimber?: THREE.Material
+  coveredMineIron?: THREE.Material
+  portalIron?: THREE.Material
+  support?: THREE.Material
+  bone?: THREE.Material
+  floorSurfaceTreatment?: FloorSurfaceTreatment
+  /** Theme-gated treatments kept resident so a material-only theme swap can reveal them. */
+  floorSurfaceTreatments?: readonly FloorSurfaceTreatment[]
+  supportMetal?: THREE.Material
+  wildWestBrass?: THREE.Material
+  jungleTempleStone?: THREE.Material
+  jungleTempleFacade?: THREE.Material
+  jungleTempleTimber?: THREE.Material
+  jungleTemplePlatform?: THREE.Material
+  jungleTempleMoss?: THREE.Material
+  jungleTempleBronze?: THREE.Material
+  stoneTrackBlock?: THREE.Material
+  egyptPortalSandstone?: THREE.Material
+  egyptPortalCarvedSandstone?: THREE.Material
+  egyptPortalAgedGold?: THREE.Material
+  egyptPyramidLimestone?: THREE.Material
+  egyptPyramidGold?: THREE.Material
+  sakuraCastleTimber?: THREE.Material
+  sakuraCastleMasonry?: THREE.Material
+  sakuraCastleKawara?: THREE.Material
+  sakuraPortalFoundationStone?: THREE.Material
+  sakuraBridgeTimber?: THREE.Material
+  sakuraBridgeHardware?: THREE.Material
+  spaceStationWallPanel?: THREE.Material
+  spaceStationWallChassis?: THREE.Material
+  spaceStationWallRib?: THREE.Material
+  spaceStationWallTrim?: THREE.Material
+  spaceStationWallLight?: THREE.Material
+  spaceStationCenterGuide?: THREE.Material
+  spaceStationFloorDeck?: THREE.Material
+}
+
+export interface PortalTeleportEvent {
+  slotId: string
+  portalId: string
+  tick: number
+  entryPosition: THREE.Vector3
+  exitPosition: THREE.Vector3
+  exitDirection: THREE.Vector3
+}
+
+export interface TrackRenderBudget {
+  portalViewsRemaining: number
+  portalCandidateKey?: string
+}
+
+export interface TrackPortalRenderCandidate {
+  key: string
+  score: number
+}
+
+export interface TrackMechanismVisualAdapter {
+  readonly id: string
+  readonly type: string
+  readonly bodyCount: number
+  readonly colliderCount: number
+  readonly sensorCount: number
+  portalRenderCandidate?(mainCamera: THREE.Camera): TrackPortalRenderCandidate | undefined
+  invalidatePortalViewCache?(): void
+  prepareRender?(
+    renderer: THREE.WebGLRenderer,
+    scene: THREE.Object3D,
+    mainCamera: THREE.Camera,
+    budget?: TrackRenderBudget,
+  ): void
+  setVisualQualityPolicy?(policy: VisualQualityPolicy): void
+  dispose?(): void
+}
+
+function toVector3(value: TrackVector): THREE.Vector3 {
+  return new THREE.Vector3(value[0], value[1], value[2])
+}
+
+function toRapierRotation(quaternion: THREE.Quaternion): RAPIER.Rotation {
+  return { x: quaternion.x, y: quaternion.y, z: quaternion.z, w: quaternion.w }
+}
+
+function createPortalRenderTarget(name: string, scale: number): THREE.WebGLRenderTarget {
+  const target = new THREE.WebGLRenderTarget(
+    Math.max(1, Math.round(PORTAL_LIVE_VIEW_WIDTH * scale)),
+    Math.max(1, Math.round(PORTAL_LIVE_VIEW_HEIGHT * scale)),
+    {
+      depthBuffer: true,
+      stencilBuffer: false,
+      minFilter: THREE.LinearFilter,
+      magFilter: THREE.LinearFilter,
+      generateMipmaps: false,
+    },
+  )
+  target.texture.name = name
+  target.texture.colorSpace = THREE.SRGBColorSpace
+  return target
+}
+
+export const FLIPPER_BANK_MAX_TIP_SPEED = 4.5
+
+function flipperMaterialsFor(materials: TrackMaterials): { primary: THREE.Material; secondary: THREE.Material } {
+  const fallback = materials.moving
+  return {
+    primary: materials.flipperPrimary ?? fallback,
+    secondary: materials.flipperSecondary ?? fallback,
+  }
+}
+
+function surfaceRotation(direction: TrackVector): THREE.Quaternion {
+  const basis = trackSurfaceBasis(direction)
+  return new THREE.Quaternion().setFromRotationMatrix(
+    new THREE.Matrix4().makeBasis(toVector3(basis.right), toVector3(basis.up), toVector3(basis.forward).negate()),
+  )
+}
+
+class SplitterMechanism implements TrackMechanismVisualAdapter {
+  readonly type = 'splitter'
+  readonly bodyCount = 1
+  readonly colliderCount = 4
+  readonly sensorCount = 1
+  private readonly physics: SplitterPhysicsMechanism
+  private readonly visual: THREE.Group
+
+  constructor(
+    readonly id: string,
+    world: RAPIER.World,
+    root: THREE.Group,
+    definition: SplitterPieceDefinition,
+    motion: SplitterMotionProfile,
+    materials: TrackMaterials,
+    existingVisual?: THREE.Group,
+  ) {
+    const center = toVector3(definition.center)
+    this.physics = new SplitterPhysicsMechanism(id, world, definition, motion)
+    const dimensions = {
+      length: definition.barLength,
+      width: definition.barDepth,
+      height: definition.barHeight,
+    }
+    const componentMaterials = flipperMaterialsFor(materials)
+    this.visual =
+      existingVisual ??
+      createEndPivotedFlipperPaddleVisual(
+        `${id}-splitter-paddle`,
+        componentMaterials.primary,
+        dimensions,
+        componentMaterials.secondary,
+        `${id}-splitter-hub`,
+        0,
+      )
+    this.visual.userData.cycleSecondsRange = [
+      Math.max(this.physics.minimumCycleSeconds, SPLITTER_CYCLE_SECONDS_RANGE[0]),
+      Math.max(this.physics.minimumCycleSeconds, SPLITTER_CYCLE_SECONDS_RANGE[1]),
+    ]
+    this.visual.userData.maximumTipSpeed = SPLITTER_MAX_TIP_SPEED
+    this.visual.userData.motionProfile = 'seeded-smooth-variable-cycle-sweep'
+    this.visual.userData.rapierBodyType = 'kinematic-position'
+    this.visual.userData.sweepPhaseCycles = this.physics.sweepPhaseCycles
+    this.visual.userData.initialSide = this.physics.initialSide
+    this.visual.position.copy(center)
+    this.visual.frustumCulled = false
+    markDynamicTrackShadowRoot(this.visual)
+    if (!existingVisual) root.add(this.visual)
+  }
+}
+
+class RisingWallForestMechanism implements TrackMechanismVisualAdapter {
+  readonly type = 'rising-wall-forest'
+  readonly bodyCount: number
+  readonly colliderCount: number
+  readonly sensorCount = 0
+  private readonly physics: RisingWallPhysicsMechanism
+  private readonly visuals: THREE.Mesh[] = []
+
+  constructor(
+    readonly id: string,
+    world: RAPIER.World,
+    private readonly definition: RisingWallForestPieceDefinition,
+    simulationKey: string,
+    root: THREE.Group,
+    materials: TrackMaterials,
+    existingVisuals?: readonly THREE.Mesh[],
+  ) {
+    const reusesExistingVisuals = existingVisuals?.length === definition.anchors.length
+    this.physics = new RisingWallPhysicsMechanism(id, world, definition, simulationKey)
+    this.bodyCount = this.physics.bodyCount
+    this.colliderCount = this.physics.colliderCount
+    const basis = trackSurfaceBasis(definition.direction)
+    const slotUp = toVector3(basis.up)
+    const slotRotation = surfaceRotation(definition.direction)
+    const wallGeometry = reusesExistingVisuals
+      ? undefined
+      : new THREE.BoxGeometry(definition.wallWidth, definition.wallHeight, definition.wallDepth)
+    const slotGeometry = reusesExistingVisuals
+      ? undefined
+      : new THREE.BoxGeometry(definition.wallWidth + 0.14, 0.035, definition.wallDepth + 0.14)
+    definition.anchors.forEach((anchor, wallIndex) => {
+      const fraction = this.physics.heights[wallIndex]!
+      const wall = reusesExistingVisuals
+        ? existingVisuals![wallIndex]!
+        : new THREE.Mesh(wallGeometry!, materials.obstacle ?? materials.hazard)
+      if (!reusesExistingVisuals) {
+        wall.name = `${id}-wall-${wallIndex}`
+        wall.castShadow = true
+        wall.receiveShadow = true
+        root.add(wall)
+        const slot = new THREE.Mesh(slotGeometry!, materials.obstacleBase ?? materials.signal)
+        slot.name = `${id}-wall-slot-${wallIndex}`
+        slot.position.copy(toVector3(anchor.position)).addScaledVector(slotUp, 0.018)
+        slot.quaternion.copy(slotRotation)
+        slot.receiveShadow = true
+        root.add(slot)
+      }
+      wall.userData.risingWallVisual = {
+        anchor: [...anchor.position],
+        up: [...this.physics.up],
+        wallHeight: definition.wallHeight,
+      }
+      markDynamicTrackShadowRoot(wall)
+      this.visuals.push(wall)
+      this.updateWallVisual(wallIndex, fraction)
+    })
+  }
+
+  private updateWallVisual(index: number, fraction: number): void {
+    const exposedHeight = risingWallExposedHeight(this.definition.wallHeight, fraction)
+    const wall = this.visuals[index]!
+    wall.position
+      .copy(toVector3(this.definition.anchors[index]!.position))
+      .addScaledVector(toVector3(this.physics.up), exposedHeight / 2)
+    wall.quaternion.set(...this.physics.rotation)
+    wall.scale.set(1, exposedHeight / this.definition.wallHeight, 1)
+    wall.visible = exposedHeight > 0.001
+  }
+}
+
+export { deterministicPortalExitVariation } from '@marble.fun/physics-engine'
+
+class PortalMechanism implements TrackMechanismVisualAdapter {
+  readonly type = 'portal'
+  readonly bodyCount = 0
+  readonly colliderCount = 0
+  readonly sensorCount = 0
+  private readonly visual: THREE.Group
+  private readonly entryVisual: PortalEndpointVisual
+  private readonly exitVisual: PortalEndpointVisual
+  private readonly liveTargets: Partial<Record<'entry' | 'exit', THREE.WebGLRenderTarget>> = {}
+  private readonly liveCamera = new THREE.PerspectiveCamera(62, 1, 0.08, 260)
+  private readonly liveViewProjection = new THREE.Matrix4()
+  private readonly liveViewFrustum = new THREE.Frustum()
+  private readonly liveViewBounds = new THREE.Sphere()
+  private readonly liveViewProjectedCenter = new THREE.Vector3()
+  private readonly liveViewWorldQuaternion = new THREE.Quaternion()
+  private readonly liveViewWorldNormal = new THREE.Vector3()
+  private readonly liveViewCameraPosition = new THREE.Vector3()
+  private readonly liveViewToCamera = new THREE.Vector3()
+  private qualityPolicy: VisualQualityPolicy
+  private readonly portalColor: string
+
+  constructor(
+    readonly id: string,
+    root: THREE.Group,
+    definition: PortalPieceDefinition,
+    materials: TrackMaterials,
+    qualityPolicy: VisualQualityPolicy,
+    existingVisuals?: { entry: PortalEndpointVisual; exit: PortalEndpointVisual },
+  ) {
+    this.qualityPolicy = qualityPolicy
+    this.portalColor = definition.color
+    this.visual = new THREE.Group()
+    this.visual.name = `${id}-portal-pair`
+    const activeThemeId = materials.activeThemeId
+    const endpointMaterials = {
+      activeThemeId,
+      structure: materials.structure,
+      timber: materials.mineTimber ?? materials.structure,
+      metal: materials.portalIron ?? materials.railroad ?? materials.edge,
+      portal: materials.portal,
+      energy: materials.energy,
+      jungle:
+        activeThemeId === JUNGLE_TEMPLE_THEME_ID
+          ? {
+              stone: materials.jungleTempleStone ?? materials.structure,
+              facade: materials.jungleTempleFacade ?? materials.railBacking,
+              bronze: materials.jungleTempleBronze ?? materials.signal,
+              foliage: materials.jungleTempleMoss ?? materials.structure,
+            }
+          : undefined,
+      egypt:
+        activeThemeId === EGYPT_ELEVATOR_THEME_ID
+          ? {
+              sandstone: materials.egyptPortalSandstone ?? materials.structure,
+              carvedStone: materials.egyptPortalCarvedSandstone ?? materials.railBacking,
+              agedGold: materials.egyptPortalAgedGold ?? materials.signal,
+            }
+          : undefined,
+      sakura:
+        activeThemeId === JAPAN_ELEVATOR_THEME_ID
+          ? {
+              vermilion: materials.sakuraBridgeTimber ?? materials.structure,
+              plaster: materials.railBacking,
+              foundationStone: materials.sakuraPortalFoundationStone ?? materials.structure,
+              kawara: materials.sakuraCastleKawara ?? materials.edge,
+              hardware: materials.sakuraBridgeHardware ?? materials.portalIron ?? materials.edge,
+            }
+          : undefined,
+      spaceStation:
+        activeThemeId === SPACE_STATION_PORTAL_FRAME_THEME_ID
+          ? {
+              chassis: materials.spaceStationWallChassis ?? materials.railBacking,
+              panel: materials.spaceStationWallPanel ?? materials.rail,
+              rib: materials.spaceStationWallRib ?? materials.structure,
+              trim: materials.spaceStationWallTrim ?? materials.edge,
+              light: materials.spaceStationWallLight ?? materials.energy,
+            }
+          : undefined,
+    }
+    this.entryVisual =
+      existingVisuals?.entry ??
+      createPortalEndpointVisual(`${id}-entry`, 'live-window', definition.color, endpointMaterials)
+    this.exitVisual =
+      existingVisuals?.exit ??
+      createPortalEndpointVisual(`${id}-exit`, 'live-window', definition.color, endpointMaterials)
+    if (!existingVisuals) {
+      for (const [endpoint, center, direction] of [
+        [this.entryVisual, toVector3(definition.entryVisualCenter), toVector3(definition.entryVisualDirection)],
+        [this.exitVisual, toVector3(definition.exitVisualCenter), toVector3(definition.exitVisualDirection)],
+      ] as const) {
+        const rotation = new THREE.Quaternion().setFromUnitVectors(new THREE.Vector3(0, 0, 1), direction.normalize())
+        endpoint.group.position.copy(center)
+        endpoint.group.quaternion.copy(rotation)
+        this.visual.add(endpoint.group)
+      }
+      root.add(this.visual)
+    }
+    this.entryVisual.setFallback(this.portalColor)
+    this.exitVisual.setFallback(this.portalColor)
+    this.configureLiveTargets()
+  }
+
+  dispose(): void {
+    this.disposeLiveTargets()
+  }
+
+  setVisualQualityPolicy(policy: VisualQualityPolicy): void {
+    if (this.qualityPolicy === policy) return
+    this.qualityPolicy = policy
+    this.disposeLiveTargets()
+    this.entryVisual.setFallback(this.portalColor)
+    this.exitVisual.setFallback(this.portalColor)
+    this.configureLiveTargets()
+  }
+
+  invalidatePortalViewCache(): void {
+    this.entryVisual.setFallback(this.portalColor)
+    this.exitVisual.setFallback(this.portalColor)
+  }
+
+  prepareRender(
+    renderer: THREE.WebGLRenderer,
+    scene: THREE.Object3D,
+    mainCamera: THREE.Camera,
+    budget: TrackRenderBudget = { portalViewsRemaining: 2 },
+  ): void {
+    // Rift animation is independent of destination-camera rendering.
+    const renderTimeMs = globalThis.performance.now()
+    this.entryVisual.update(renderTimeMs / 1_000)
+    this.exitVisual.update(renderTimeMs / 1_000)
+    if (budget.portalViewsRemaining <= 0) return
+    if (!this.liveTargets.entry && !this.liveTargets.exit) return
+    const candidate = this.portalRenderCandidate(mainCamera)
+    if (!candidate || (budget.portalCandidateKey && candidate.key !== budget.portalCandidateKey)) return
+    const endpoint: 'entry' | 'exit' = candidate.key.endsWith(':entry') ? 'entry' : 'exit'
+    const previousTarget = renderer.getRenderTarget()
+    const previousXr = renderer.xr.enabled
+    const previousEntryVisibility = this.entryVisual.group.visible
+    const previousExitVisibility = this.exitVisual.group.visible
+    this.entryVisual.group.visible = false
+    this.exitVisual.group.visible = false
+    renderer.xr.enabled = false
+    this.liveCamera.layers.mask = mainCamera.layers.mask
+    try {
+      if (endpoint === 'entry' && this.liveTargets.entry && budget.portalViewsRemaining > 0) {
+        this.renderRemoteView(
+          renderer,
+          scene,
+          mainCamera,
+          this.exitVisual.group,
+          this.liveTargets.entry,
+        )
+        this.entryVisual.setLiveTexture(this.liveTargets.entry.texture)
+        this.entryVisual.setLiveBlend(portalLiveViewBlend(candidate.score))
+        budget.portalViewsRemaining -= 1
+      } else if (endpoint === 'exit' && this.liveTargets.exit && budget.portalViewsRemaining > 0) {
+        this.renderRemoteView(
+          renderer,
+          scene,
+          mainCamera,
+          this.entryVisual.group,
+          this.liveTargets.exit,
+        )
+        this.exitVisual.setLiveTexture(this.liveTargets.exit.texture)
+        this.exitVisual.setLiveBlend(portalLiveViewBlend(candidate.score))
+        budget.portalViewsRemaining -= 1
+      }
+    } finally {
+      renderer.setRenderTarget(previousTarget)
+      renderer.xr.enabled = previousXr
+      this.entryVisual.group.visible = previousEntryVisibility
+      this.exitVisual.group.visible = previousExitVisibility
+    }
+  }
+
+  portalRenderCandidate(mainCamera: THREE.Camera): TrackPortalRenderCandidate | undefined {
+    if (!this.liveTargets.entry && !this.liveTargets.exit) return undefined
+    mainCamera.updateWorldMatrix(true, false)
+    this.liveViewProjection.multiplyMatrices(mainCamera.projectionMatrix, mainCamera.matrixWorldInverse)
+    this.liveViewFrustum.setFromProjectionMatrix(this.liveViewProjection)
+    const rawEntryScore = this.liveTargets.entry ? this.endpointScreenRatio(this.entryVisual, mainCamera) : 0
+    const rawExitScore = this.liveTargets.exit ? this.endpointScreenRatio(this.exitVisual, mainCamera) : 0
+    this.entryVisual.setLiveBlend(portalLiveViewBlend(rawEntryScore))
+    this.exitVisual.setLiveBlend(portalLiveViewBlend(rawExitScore))
+    const entryScore =
+      !this.entryVisual.screen.userData.liveTextureReady && rawEntryScore >= PORTAL_LIVE_VIEW_FADE_START_RATIO
+        ? rawEntryScore
+        : 0
+    const exitScore =
+      !this.exitVisual.screen.userData.liveTextureReady && rawExitScore >= PORTAL_LIVE_VIEW_FADE_START_RATIO
+        ? rawExitScore
+        : 0
+    if (entryScore <= 0 && exitScore <= 0) return undefined
+    return entryScore >= exitScore
+      ? { key: `${this.id}:entry`, score: entryScore }
+      : { key: `${this.id}:exit`, score: exitScore }
+  }
+
+  private endpointScreenRatio(endpoint: PortalEndpointVisual, camera: THREE.Camera): number {
+    let ancestor: THREE.Object3D | null = endpoint.screen
+    while (ancestor) {
+      if (!ancestor.visible) return 0
+      ancestor = ancestor.parent
+    }
+    if (!camera.layers.test(endpoint.screen.layers)) return 0
+    endpoint.screen.updateWorldMatrix(true, false)
+    if (!endpoint.screen.geometry.boundingSphere) endpoint.screen.geometry.computeBoundingSphere()
+    const localBounds = endpoint.screen.geometry.boundingSphere
+    if (!localBounds) return 0
+    this.liveViewBounds.copy(localBounds).applyMatrix4(endpoint.screen.matrixWorld)
+    if (!this.liveViewFrustum.intersectsSphere(this.liveViewBounds)) return 0
+    this.liveViewProjectedCenter.copy(this.liveViewBounds.center).project(camera)
+    if (
+      Math.abs(this.liveViewProjectedCenter.x) > 1 ||
+      Math.abs(this.liveViewProjectedCenter.y) > 1 ||
+      this.liveViewProjectedCenter.z < -1 ||
+      this.liveViewProjectedCenter.z > 1
+    ) {
+      return 0
+    }
+    endpoint.group.getWorldQuaternion(this.liveViewWorldQuaternion)
+    this.liveViewWorldNormal.set(0, 0, 1).applyQuaternion(this.liveViewWorldQuaternion)
+    camera.getWorldPosition(this.liveViewCameraPosition)
+    this.liveViewToCamera.subVectors(this.liveViewCameraPosition, this.liveViewBounds.center)
+    const distance = Math.max(0.001, this.liveViewToCamera.length())
+    if (this.liveViewWorldNormal.dot(this.liveViewToCamera) <= 0) return 0
+    return this.liveViewBounds.radius / distance
+  }
+
+  private renderRemoteView(
+    renderer: THREE.WebGLRenderer,
+    scene: THREE.Object3D,
+    viewerCamera: THREE.Camera,
+    destination: THREE.Group,
+    target: THREE.WebGLRenderTarget,
+  ): void {
+    positionFixedPortalViewCamera(
+      this.liveCamera,
+      viewerCamera,
+      destination,
+      target.width / target.height,
+    )
+    renderFixedPortalView(renderer, scene, this.liveCamera, target)
+  }
+
+  private releaseLiveTargetTexture(endpoint: PortalEndpointVisual, target: THREE.WebGLRenderTarget | undefined): void {
+    if (!target || !(endpoint.screen.material instanceof THREE.MeshBasicMaterial)) return
+    if (endpoint.screen.material.map !== target.texture) return
+    endpoint.screen.material.map = null
+    endpoint.screen.material.needsUpdate = true
+  }
+
+  private configureLiveTargets(): void {
+    if (this.qualityPolicy.portal.mode === 'static') return
+    const scale = this.qualityPolicy.portal.renderTargetScale
+    this.liveTargets.entry = createPortalRenderTarget(`${this.id}-entry-window`, scale)
+    this.liveTargets.exit = createPortalRenderTarget(`${this.id}-exit-window`, scale)
+  }
+
+  private disposeLiveTargets(): void {
+    this.releaseLiveTargetTexture(this.entryVisual, this.liveTargets.entry)
+    this.releaseLiveTargetTexture(this.exitVisual, this.liveTargets.exit)
+    this.liveTargets.entry?.dispose()
+    this.liveTargets.exit?.dispose()
+    delete this.liveTargets.entry
+    delete this.liveTargets.exit
+  }
+}
+
+const FLIPPER_LOCAL_UP = new THREE.Vector3(0, 1, 0)
+
+class FlipperBankMechanism implements TrackMechanismVisualAdapter {
+  readonly type = 'flipper-bank'
+  readonly bodyCount: number
+  readonly colliderCount: number
+  readonly sensorCount = 0
+  private readonly physics: FlipperBankPhysicsMechanism
+
+  constructor(
+    readonly id: string,
+    world: RAPIER.World,
+    root: THREE.Group,
+    definition: FlipperBankPieceDefinition,
+    simulationKey: string,
+    materials: TrackMaterials,
+    existingVisuals?: readonly THREE.Group[],
+  ) {
+    const reusesExistingVisuals = existingVisuals?.length === definition.mounts.length
+    this.physics = new FlipperBankPhysicsMechanism(id, world, definition, simulationKey)
+    this.bodyCount = this.physics.bodyCount
+    this.colliderCount = this.physics.colliderCount
+
+    const dimensions = {
+      length: definition.paddleLength,
+      width: definition.paddleWidth,
+      height: definition.paddleHeight,
+    }
+    const flipperMaterials = flipperMaterialsFor(materials)
+    definition.mounts.forEach((mount, index) => {
+      const tangent = toVector3(mount.direction ?? definition.direction).normalize()
+      const right = new THREE.Vector3(tangent.z, 0, -tangent.x).normalize()
+      const up = new THREE.Vector3().crossVectors(tangent, right).normalize()
+      const state = this.physics.flippers[index]!
+      const baseRotation = new THREE.Quaternion(...state.baseRotation)
+      const hubRotation = new THREE.Quaternion().setFromUnitVectors(FLIPPER_LOCAL_UP, up)
+      const hinge = toVector3(state.hinge)
+      const bodyPosition = state.body.translation()
+      const center = new THREE.Vector3(bodyPosition.x, bodyPosition.y, bodyPosition.z)
+
+      const visual =
+        (reusesExistingVisuals ? existingVisuals![index] : undefined) ??
+        createFlipperPaddleVisual(`${id}-paddle-${index + 1}`, flipperMaterials.primary, dimensions)
+      visual.position.copy(center)
+      visual.quaternion.copy(baseRotation)
+      visual.userData.maximumTipSpeed = FLIPPER_BANK_MAX_TIP_SPEED
+      visual.userData.strikeSeconds = this.physics.strikeTicks * FIXED_TIMESTEP
+      visual.userData.returnSeconds = this.physics.returnTicks * FIXED_TIMESTEP
+      visual.userData.motionProfile = 'deterministic-bounded-strike'
+      markDynamicTrackShadowRoot(visual)
+      if (!reusesExistingVisuals) root.add(visual)
+
+      if (!reusesExistingVisuals) {
+        const hub = createFlipperHubVisual(`${id}-hub-${index + 1}`, flipperMaterials.secondary, dimensions)
+        hub.position.copy(hinge)
+        hub.quaternion.copy(hubRotation)
+        hub.castShadow = true
+        hub.receiveShadow = true
+        root.add(hub)
+      }
+
+      void visual
+    })
+  }
+}
+
+class ReboundMechanism implements TrackMechanismVisualAdapter {
+  readonly type = 'rebound'
+  readonly bodyCount: number
+  readonly colliderCount: number
+  readonly sensorCount = 0
+  private readonly physics: ReboundPhysicsMechanism
+
+  constructor(
+    readonly id: string,
+    world: RAPIER.World,
+    root: THREE.Group,
+    definition: ReboundPieceDefinition,
+    materials: TrackMaterials,
+    existingVisuals?: readonly THREE.Group[],
+  ) {
+    const reusesExistingVisuals = existingVisuals?.length === definition.mounts.length
+    this.physics = new ReboundPhysicsMechanism(id, world, definition)
+    this.bodyCount = this.physics.bodyCount
+    this.colliderCount = this.physics.colliderCount
+    const createVisual = createReboundVisualFactory({
+      reboundLength: definition.reboundLength,
+      reboundWidth: definition.reboundWidth,
+      reboundHeight: definition.reboundHeight,
+      bodyMaterial: materials.obstacle ?? materials.hazard,
+      accentMaterial: materials.obstacleAccent ?? materials.railroad ?? materials.edge,
+    })
+
+    definition.mounts.forEach((_mount, index) => {
+      const state = this.physics.rebounds[index]!
+      const bodyPosition = state.body.translation()
+      const bodyRotation = state.body.rotation()
+
+      const visual = (reusesExistingVisuals ? existingVisuals![index] : undefined) ?? createVisual()
+      visual.name = `${id}-rebound-${index}`
+      visual.position.set(bodyPosition.x, bodyPosition.y, bodyPosition.z)
+      visual.quaternion.set(bodyRotation.x, bodyRotation.y, bodyRotation.z, bodyRotation.w)
+      visual.frustumCulled = false
+      markDynamicTrackShadowRoot(visual)
+      if (!reusesExistingVisuals) root.add(visual)
+
+      void visual
+    })
+  }
+}
+
+class TurntableMechanism implements TrackMechanismVisualAdapter {
+  readonly type = 'turntable'
+  readonly bodyCount = 1
+  readonly colliderCount = 3
+  readonly sensorCount = 1
+  private readonly body: RAPIER.RigidBody
+  private readonly visual: THREE.Group
+  private readonly center: THREE.Vector3
+  private readonly baseRotation: THREE.Quaternion
+  private readonly rotation = new THREE.Quaternion()
+
+  constructor(
+    readonly id: string,
+    world: RAPIER.World,
+    root: THREE.Group,
+    definition: TurntablePieceDefinition,
+    materials: TrackMaterials,
+  ) {
+    if (definition.routeAngles.length < 2) {
+      throw new Error(`Turntable ${id} requires at least two route angles`)
+    }
+    const tangent = toVector3(definition.direction).normalize()
+    const right = new THREE.Vector3(tangent.z, 0, -tangent.x).normalize()
+    const up = new THREE.Vector3().crossVectors(tangent, right).normalize()
+    this.baseRotation = new THREE.Quaternion().setFromRotationMatrix(new THREE.Matrix4().makeBasis(right, up, tangent))
+    // Sink the rotating disk by its half-height so its top is exactly flush
+    // with the authored entry rail. This avoids a hidden curb at the rim.
+    this.center = toVector3(definition.center).addScaledVector(up, -0.11)
+    this.rotation
+      .copy(this.baseRotation)
+      .multiply(new THREE.Quaternion().setFromAxisAngle(FLIPPER_LOCAL_UP, definition.routeAngles[0]!))
+
+    this.body = world.createRigidBody(
+      RAPIER.RigidBodyDesc.kinematicPositionBased()
+        .setTranslation(this.center.x, this.center.y, this.center.z)
+        .setRotation(toRapierRotation(this.rotation)),
+    )
+    world.createCollider(
+      RAPIER.ColliderDesc.cylinder(0.11, definition.radius).setFriction(0.18).setRestitution(0.01),
+      this.body,
+    )
+    const guideLength = definition.radius * 0.95
+    for (const side of [-1, 1] as const) {
+      world.createCollider(
+        RAPIER.ColliderDesc.cuboid(0.11, definition.wallHeight / 2, guideLength / 2)
+          .setTranslation(side * (definition.channelWidth / 2 - 0.11), definition.wallHeight / 2 + 0.1, guideLength / 2)
+          .setFriction(0.08)
+          .setRestitution(0.02),
+        this.body,
+      )
+    }
+    world.createCollider(
+      RAPIER.ColliderDesc.ball(definition.triggerRadius)
+        .setTranslation(this.center.x + up.x * 0.48, this.center.y + up.y * 0.48, this.center.z + up.z * 0.48)
+        .setSensor(true),
+    )
+
+    this.visual = new THREE.Group()
+    this.visual.name = `${id}-rotating-channel`
+    this.visual.position.copy(this.center)
+    this.visual.quaternion.copy(this.rotation)
+    this.visual.frustumCulled = false
+    const disk = new THREE.Mesh(
+      new VisualCylinderGeometry(definition.radius, definition.radius, 0.22, 36),
+      materials.structure,
+    )
+    disk.castShadow = true
+    disk.receiveShadow = true
+    this.visual.add(disk)
+    const guideGeometry = new THREE.BoxGeometry(0.22, definition.wallHeight, guideLength)
+    for (const side of [-1, 1] as const) {
+      const guide = new THREE.Mesh(guideGeometry, materials.hazard)
+      guide.position.set(side * (definition.channelWidth / 2 - 0.11), definition.wallHeight / 2 + 0.1, guideLength / 2)
+      guide.castShadow = true
+      guide.receiveShadow = true
+      this.visual.add(guide)
+    }
+    const hub = new THREE.Mesh(
+      new VisualCylinderGeometry(0.48, 0.48, definition.wallHeight + 0.34, 24),
+      materials.signal,
+    )
+    hub.position.y = definition.wallHeight / 2 + 0.1
+    hub.castShadow = true
+    this.visual.add(hub)
+    markDynamicTrackShadowRoot(this.visual)
+    root.add(this.visual)
+
+    const rimGroup = new THREE.Group()
+    rimGroup.name = `${id}-fixed-rim`
+    rimGroup.position.copy(this.center)
+    rimGroup.quaternion.copy(this.baseRotation)
+    const rim = new THREE.Mesh(new VisualTorusGeometry(definition.radius + 0.16, 0.14, 10, 40), materials.signal)
+    rim.rotation.x = Math.PI / 2
+    rim.castShadow = true
+    rimGroup.add(rim)
+    root.add(rimGroup)
+  }
+}
+
+class DipperMechanism implements TrackMechanismVisualAdapter {
+  readonly type = 'dipper'
+  readonly bodyCount = 1
+  readonly colliderCount = 3
+  readonly sensorCount = 1
+  private readonly body: RAPIER.RigidBody
+  private readonly visual: THREE.Group
+  private readonly hinge: THREE.Vector3
+  private readonly baseRotation: THREE.Quaternion
+
+  constructor(
+    readonly id: string,
+    world: RAPIER.World,
+    root: THREE.Group,
+    definition: DipperPieceDefinition,
+    materials: TrackMaterials,
+  ) {
+    const tangent = toVector3(definition.direction).normalize()
+    const right = new THREE.Vector3(tangent.z, 0, -tangent.x).normalize()
+    const up = new THREE.Vector3().crossVectors(tangent, right).normalize()
+    this.hinge = toVector3(definition.hinge)
+    const trigger = this.hinge
+      .clone()
+      .addScaledVector(tangent, definition.length * 0.58)
+      .addScaledVector(up, 0.62)
+    this.baseRotation = new THREE.Quaternion().setFromRotationMatrix(new THREE.Matrix4().makeBasis(right, up, tangent))
+
+    this.body = world.createRigidBody(
+      RAPIER.RigidBodyDesc.kinematicPositionBased()
+        .setTranslation(this.hinge.x, this.hinge.y, this.hinge.z)
+        .setRotation(toRapierRotation(this.baseRotation)),
+    )
+    const floorThickness = 0.22
+    world.createCollider(
+      RAPIER.ColliderDesc.cuboid(definition.width / 2, floorThickness / 2, definition.length / 2)
+        .setTranslation(0, -floorThickness / 2, definition.length / 2)
+        .setFriction(0.62)
+        .setRestitution(0.01),
+      this.body,
+    )
+    for (const side of [-1, 1] as const) {
+      world.createCollider(
+        RAPIER.ColliderDesc.cuboid(0.12, definition.wallHeight / 2, definition.length / 2)
+          .setTranslation(side * (definition.width / 2 - 0.12), definition.wallHeight / 2, definition.length / 2)
+          .setFriction(0.08)
+          .setRestitution(0.01),
+        this.body,
+      )
+    }
+    world.createCollider(
+      RAPIER.ColliderDesc.ball(definition.triggerRadius)
+        .setTranslation(trigger.x, trigger.y, trigger.z)
+        .setSensor(true),
+    )
+
+    this.visual = new THREE.Group()
+    this.visual.name = `${id}-lowering-cup`
+    this.visual.position.copy(this.hinge)
+    this.visual.quaternion.copy(this.baseRotation)
+    this.visual.frustumCulled = false
+    const floor = new THREE.Mesh(
+      new THREE.BoxGeometry(definition.width, floorThickness, definition.length),
+      materials.structure,
+    )
+    floor.position.set(0, -floorThickness / 2, definition.length / 2)
+    floor.castShadow = true
+    floor.receiveShadow = true
+    this.visual.add(floor)
+    const sideGeometry = new THREE.BoxGeometry(0.24, definition.wallHeight, definition.length)
+    for (const side of [-1, 1] as const) {
+      const wall = new THREE.Mesh(sideGeometry, materials.hazard)
+      wall.position.set(side * (definition.width / 2 - 0.12), definition.wallHeight / 2, definition.length / 2)
+      wall.castShadow = true
+      wall.receiveShadow = true
+      this.visual.add(wall)
+    }
+    const counterweight = new THREE.Mesh(new VisualSphereGeometry(0.68, 20, 14), materials.signal)
+    counterweight.position.set(0, definition.wallHeight * 0.72, -0.72)
+    counterweight.castShadow = true
+    this.visual.add(counterweight)
+    markDynamicTrackShadowRoot(this.visual)
+    root.add(this.visual)
+
+    const support = new THREE.Group()
+    support.name = `${id}-support`
+    support.position.copy(this.hinge)
+    support.quaternion.copy(this.baseRotation)
+    const axle = new THREE.Mesh(new VisualCylinderGeometry(0.22, 0.22, definition.width + 0.6, 18), materials.signal)
+    axle.rotation.z = Math.PI / 2
+    axle.castShadow = true
+    support.add(axle)
+    root.add(support)
+  }
+}
+
+class ConveyorMechanism implements TrackMechanismVisualAdapter {
+  readonly type = 'conveyor'
+  readonly bodyCount: number
+  readonly colliderCount: number
+  readonly sensorCount = 0
+  private readonly bottom: THREE.Vector3
+  private readonly top: THREE.Vector3
+  private readonly height: number
+  private readonly baseRotation: THREE.Quaternion
+  private readonly physics: ConveyorPhysicsMechanism
+
+  constructor(
+    readonly id: string,
+    world: RAPIER.World,
+    root: THREE.Group,
+    definition: ConveyorPieceDefinition,
+    phase: number,
+    materials: TrackMaterials,
+    existingVisuals?: readonly THREE.Mesh[],
+  ) {
+    const reusesCanonicalVisuals = existingVisuals?.length === definition.shelfCount
+    this.physics = new ConveyorPhysicsMechanism(id, world, definition, phase)
+    this.bottom = toVector3(definition.bottom)
+    this.top = toVector3(definition.top)
+    this.height = this.physics.height
+    this.bodyCount = this.physics.bodyCount
+    this.colliderCount = this.physics.colliderCount
+    this.baseRotation = new THREE.Quaternion(...this.physics.baseRotation)
+
+    const towerCenterY = (this.bottom.y + this.top.y) / 2
+    const towerHeight = this.height + 1
+    const wallThickness = 0.24
+    const activeThemeId = materials.activeThemeId
+    for (const side of [-1, 1] as const) {
+      const position = this.bottom
+        .clone()
+        .add(
+          new THREE.Vector3(
+            side * (definition.width / 2 - wallThickness / 2),
+            towerCenterY - this.bottom.y,
+            0,
+          ).applyQuaternion(this.baseRotation),
+        )
+      if (!reusesCanonicalVisuals) {
+        const wall = new THREE.Mesh(
+          new THREE.BoxGeometry(wallThickness, towerHeight, definition.shelfDepth + 0.16),
+          materials.jungleTempleStone ?? materials.rail,
+        )
+        wall.name = `${id}-side-${side < 0 ? 'left' : 'right'}`
+        wall.position.copy(position)
+        wall.quaternion.copy(this.baseRotation)
+        wall.castShadow = true
+        wall.receiveShadow = true
+        wall.userData.themeHidden = [
+          JUNGLE_TEMPLE_THEME_ID,
+          EGYPT_ELEVATOR_THEME_ID,
+          JAPAN_ELEVATOR_THEME_ID,
+          SPACE_ELEVATOR_THEME_ID,
+        ]
+        root.add(wall)
+      }
+    }
+
+    const outputWallBottom = this.bottom.y - 0.2
+    const outputWallTop = definition.releaseHeight - 0.3
+    const outputWallHeight = outputWallTop - outputWallBottom
+    const outputWallPosition = this.bottom
+      .clone()
+      .add(
+        new THREE.Vector3(
+          0,
+          outputWallBottom + outputWallHeight / 2 - this.bottom.y,
+          -definition.shelfDepth / 2 + wallThickness / 2,
+        ).applyQuaternion(this.baseRotation),
+      )
+    if (!reusesCanonicalVisuals) {
+      const outputWall = new THREE.Mesh(
+        new THREE.BoxGeometry(definition.width, outputWallHeight, wallThickness),
+        materials.jungleTempleStone ?? materials.rail,
+      )
+      outputWall.name = `${id}-release-wall`
+      outputWall.position.copy(outputWallPosition)
+      outputWall.quaternion.copy(this.baseRotation)
+      outputWall.castShadow = true
+      outputWall.receiveShadow = true
+      outputWall.userData.themeHidden = [
+        JUNGLE_TEMPLE_THEME_ID,
+        EGYPT_ELEVATOR_THEME_ID,
+        JAPAN_ELEVATOR_THEME_ID,
+        SPACE_ELEVATOR_THEME_ID,
+      ]
+      root.add(outputWall)
+    }
+
+    const mineLiftMaterials = {
+      timber:
+        activeThemeId === WILD_WEST_THEME_ID ? (materials.mineTimber ?? materials.structure) : materials.structure,
+      iron: activeThemeId === WILD_WEST_THEME_ID ? (materials.railroad ?? materials.edge) : materials.edge,
+      signal: materials.signal,
+    }
+    const jungleTempleMaterials = {
+      stone:
+        activeThemeId === JUNGLE_TEMPLE_THEME_ID ? (materials.jungleTempleStone ?? materials.rail) : materials.rail,
+      facade:
+        activeThemeId === JUNGLE_TEMPLE_THEME_ID
+          ? (materials.jungleTempleFacade ?? materials.jungleTempleStone ?? materials.rail)
+          : materials.rail,
+      timber:
+        activeThemeId === JUNGLE_TEMPLE_THEME_ID
+          ? (materials.jungleTempleTimber ?? materials.structure)
+          : materials.structure,
+      platform:
+        activeThemeId === JUNGLE_TEMPLE_THEME_ID
+          ? (materials.jungleTemplePlatform ?? materials.moving)
+          : materials.moving,
+      moss:
+        activeThemeId === JUNGLE_TEMPLE_THEME_ID
+          ? (materials.jungleTempleMoss ?? materials.structure)
+          : materials.structure,
+      accent:
+        activeThemeId === JUNGLE_TEMPLE_THEME_ID
+          ? (materials.jungleTempleBronze ?? materials.signal)
+          : materials.signal,
+    }
+    const portalDerivedMaterials = {
+      egypt: {
+        get sandstone() {
+          return materials.egyptPortalSandstone ?? materials.rail
+        },
+        get carvedStone() {
+          return materials.egyptPortalCarvedSandstone ?? materials.rail
+        },
+        get pyramidStone() {
+          return materials.egyptPyramidLimestone ?? materials.railBacking
+        },
+        get pyramidGold() {
+          return materials.egyptPyramidGold ?? materials.egyptPortalAgedGold ?? materials.signal
+        },
+        get bronze() {
+          return materials.edge
+        },
+        get gold() {
+          return materials.egyptPortalAgedGold ?? materials.signal
+        },
+        get paving() {
+          return materials.top
+        },
+        get signal() {
+          return materials.signal
+        },
+      },
+      japan: {
+        vermilion:
+          activeThemeId === JAPAN_ELEVATOR_THEME_ID
+            ? (materials.sakuraBridgeTimber ?? materials.structure)
+            : materials.structure,
+        timber:
+          activeThemeId === JAPAN_ELEVATOR_THEME_ID
+            ? (materials.sakuraCastleTimber ?? materials.moving)
+            : materials.moving,
+        plaster: materials.railBacking,
+        stone:
+          activeThemeId === JAPAN_ELEVATOR_THEME_ID
+            ? (materials.sakuraPortalFoundationStone ?? materials.sakuraCastleMasonry ?? materials.structure)
+            : materials.structure,
+        kawara:
+          activeThemeId === JAPAN_ELEVATOR_THEME_ID
+            ? (materials.sakuraCastleKawara ?? materials.structure)
+            : materials.structure,
+        hardware:
+          activeThemeId === JAPAN_ELEVATOR_THEME_ID
+            ? (materials.sakuraBridgeHardware ?? materials.edge)
+            : materials.edge,
+        signal: materials.signal,
+      },
+      space: {
+        chassis:
+          activeThemeId === SPACE_ELEVATOR_THEME_ID
+            ? (materials.spaceStationWallChassis ?? materials.structure)
+            : materials.structure,
+        panel:
+          activeThemeId === SPACE_ELEVATOR_THEME_ID
+            ? (materials.spaceStationWallPanel ?? materials.rail)
+            : materials.rail,
+        rib:
+          activeThemeId === SPACE_ELEVATOR_THEME_ID
+            ? (materials.spaceStationWallRib ?? materials.structure)
+            : materials.structure,
+        trim:
+          activeThemeId === SPACE_ELEVATOR_THEME_ID
+            ? (materials.spaceStationWallTrim ?? materials.edge)
+            : materials.edge,
+        light:
+          activeThemeId === SPACE_ELEVATOR_THEME_ID
+            ? (materials.spaceStationWallLight ?? materials.energy)
+            : materials.energy,
+      },
+    }
+
+    if (!reusesCanonicalVisuals) {
+      const beltBandGeometry = new THREE.BoxGeometry(0.3, this.height, 0.16)
+      for (const side of [-1, 1] as const) {
+        const beltBand = new THREE.Mesh(beltBandGeometry, materials.jungleTempleTimber ?? materials.structure)
+        beltBand.name = `${id}-vertical-belt-${side < 0 ? 'left' : 'right'}`
+        beltBand.position
+          .copy(this.bottom)
+          .add(
+            new THREE.Vector3(
+              side * (definition.width / 2 - 0.55),
+              towerCenterY - this.bottom.y,
+              definition.shelfDepth / 2 + 0.12,
+            ).applyQuaternion(this.baseRotation),
+          )
+        beltBand.quaternion.copy(this.baseRotation)
+        beltBand.castShadow = true
+        beltBand.receiveShadow = true
+        beltBand.userData.themeHidden = [
+          JUNGLE_TEMPLE_THEME_ID,
+          EGYPT_ELEVATOR_THEME_ID,
+          JAPAN_ELEVATOR_THEME_ID,
+          SPACE_ELEVATOR_THEME_ID,
+        ]
+        root.add(beltBand)
+      }
+
+      const drumGeometry = new VisualCylinderGeometry(0.55, 0.55, definition.width - 0.7, 20)
+      for (const [label, y] of [
+        ['bottom', this.bottom.y],
+        ['top', this.top.y],
+      ] as const) {
+        const drum = new THREE.Mesh(drumGeometry, materials.jungleTempleTimber ?? materials.signal)
+        drum.name = `${id}-${label}-drum`
+        const verticalOffset = label === 'bottom' ? -0.55 : 0.55
+        drum.position
+          .copy(this.bottom)
+          .add(
+            new THREE.Vector3(0, y + verticalOffset - this.bottom.y, definition.shelfDepth / 2 + 0.2).applyQuaternion(
+              this.baseRotation,
+            ),
+          )
+        drum.quaternion
+          .copy(this.baseRotation)
+          .multiply(new THREE.Quaternion().setFromAxisAngle(new THREE.Vector3(0, 0, 1), Math.PI / 2))
+        drum.castShadow = true
+        drum.userData.decorative = true
+        drum.userData.themeHidden = [
+          WILD_WEST_THEME_ID,
+          JUNGLE_TEMPLE_THEME_ID,
+          EGYPT_ELEVATOR_THEME_ID,
+          JAPAN_ELEVATOR_THEME_ID,
+          SPACE_ELEVATOR_THEME_ID,
+        ]
+        root.add(drum)
+      }
+
+      if (activeThemeId === WILD_WEST_THEME_ID)
+        addWildWestMineLiftFrame(root, {
+          id,
+          bottom: this.bottom,
+          rotation: this.baseRotation,
+          width: definition.width,
+          height: this.height,
+          depth: definition.shelfDepth,
+          releaseHeight: definition.releaseHeight - this.bottom.y,
+          materials: mineLiftMaterials,
+        })
+      if (activeThemeId === JUNGLE_TEMPLE_THEME_ID)
+        addJungleTempleLiftSkin(root, {
+          id,
+          bottom: this.bottom,
+          rotation: this.baseRotation,
+          width: definition.width,
+          height: this.height,
+          depth: definition.shelfDepth,
+          releaseHeight: definition.releaseHeight - this.bottom.y,
+          materials: jungleTempleMaterials,
+        })
+      addPortalDerivedElevatorSkins(root, {
+        activeThemeId,
+        id,
+        bottom: this.bottom,
+        rotation: this.baseRotation,
+        width: definition.width,
+        height: this.height,
+        depth: definition.shelfDepth,
+        releaseHeight: definition.releaseHeight - this.bottom.y,
+        materials: portalDerivedMaterials,
+      })
+    }
+
+    const shelfThickness = 0.2
+    for (let index = 0; index < definition.shelfCount; index += 1) {
+      const body = this.physics.bodies[index]!
+      const bodyPosition = body.translation()
+      const bodyRotation = body.rotation()
+      const position = new THREE.Vector3(bodyPosition.x, bodyPosition.y, bodyPosition.z)
+      const shelfRotation = new THREE.Quaternion(bodyRotation.x, bodyRotation.y, bodyRotation.z, bodyRotation.w)
+      const visual = reusesCanonicalVisuals
+        ? existingVisuals![index]!
+        : new THREE.Mesh(
+            new THREE.BoxGeometry(definition.width - 0.56, shelfThickness, definition.shelfDepth),
+            materials.jungleTemplePlatform ?? materials.moving,
+          )
+      visual.name ||= `${id}-shelf-${index + 1}`
+      visual.position.copy(position)
+      visual.quaternion.copy(shelfRotation)
+      visual.castShadow = true
+      visual.receiveShadow = true
+      markDynamicTrackShadowRoot(visual)
+      if (!reusesCanonicalVisuals) {
+        if (activeThemeId === WILD_WEST_THEME_ID)
+          decorateWildWestMineLiftShelf(
+            visual,
+            `${id}-shelf-${index + 1}`,
+            definition.width - 0.56,
+            definition.shelfDepth,
+            mineLiftMaterials,
+          )
+        if (activeThemeId === JUNGLE_TEMPLE_THEME_ID)
+          decorateJungleTempleShelf(
+            visual,
+            `${id}-shelf-${index + 1}`,
+            definition.width - 0.56,
+            definition.shelfDepth,
+            jungleTempleMaterials,
+          )
+        decoratePortalDerivedElevatorShelf(
+          visual,
+          `${id}-shelf-${index + 1}`,
+          definition.width - 0.56,
+          definition.shelfDepth,
+          portalDerivedMaterials,
+          activeThemeId,
+        )
+        root.add(visual)
+      }
+    }
+  }
+}
+
+export function createSplitterMechanism(
+  world: RAPIER.World,
+  root: THREE.Group,
+  definition: SplitterPieceDefinition,
+  motion: SplitterMotionProfile,
+  materials: TrackMaterials,
+  existingVisual?: THREE.Group,
+): TrackMechanismVisualAdapter {
+  return new SplitterMechanism(definition.id, world, root, definition, motion, materials, existingVisual)
+}
+
+export function createRisingWallForestMechanism(
+  world: RAPIER.World,
+  root: THREE.Group,
+  definition: RisingWallForestPieceDefinition,
+  simulationKey: string,
+  materials: TrackMaterials,
+  existingVisuals?: readonly THREE.Mesh[],
+): TrackMechanismVisualAdapter {
+  return new RisingWallForestMechanism(
+    definition.id,
+    world,
+    definition,
+    simulationKey,
+    root,
+    materials,
+    existingVisuals,
+  )
+}
+
+export function createVortexMechanism(
+  world: RAPIER.World,
+  definition: VortexPieceDefinition,
+): TrackMechanismVisualAdapter {
+  return new VortexPhysicsMechanism(definition.id, world, definition)
+}
+
+export function createPortalMechanism(
+  root: THREE.Group,
+  definition: PortalPieceDefinition,
+  materials: TrackMaterials,
+  qualityPolicy: VisualQualityPolicy = visualQualityPolicy('quality'),
+  existingVisuals?: { entry: PortalEndpointVisual; exit: PortalEndpointVisual },
+): TrackMechanismVisualAdapter {
+  return new PortalMechanism(definition.id, root, definition, materials, qualityPolicy, existingVisuals)
+}
+
+export function createConveyorMechanism(
+  world: RAPIER.World,
+  root: THREE.Group,
+  definition: ConveyorPieceDefinition,
+  phase: number,
+  materials: TrackMaterials,
+  existingVisuals?: readonly THREE.Mesh[],
+): TrackMechanismVisualAdapter {
+  return new ConveyorMechanism(definition.id, world, root, definition, phase, materials, existingVisuals)
+}
+
+export function createFlipperBankMechanism(
+  world: RAPIER.World,
+  root: THREE.Group,
+  definition: FlipperBankPieceDefinition,
+  simulationKey: string,
+  materials: TrackMaterials,
+  existingVisuals?: readonly THREE.Group[],
+): TrackMechanismVisualAdapter {
+  return new FlipperBankMechanism(definition.id, world, root, definition, simulationKey, materials, existingVisuals)
+}
+
+export function createReboundMechanism(
+  world: RAPIER.World,
+  root: THREE.Group,
+  definition: ReboundPieceDefinition,
+  materials: TrackMaterials,
+  existingVisuals?: readonly THREE.Group[],
+): TrackMechanismVisualAdapter {
+  return new ReboundMechanism(definition.id, world, root, definition, materials, existingVisuals)
+}
+
+export function createTurntableMechanism(
+  world: RAPIER.World,
+  root: THREE.Group,
+  definition: TurntablePieceDefinition,
+  materials: TrackMaterials,
+): TrackMechanismVisualAdapter {
+  return new TurntableMechanism(definition.id, world, root, definition, materials)
+}
+
+export function createDipperMechanism(
+  world: RAPIER.World,
+  root: THREE.Group,
+  definition: DipperPieceDefinition,
+  materials: TrackMaterials,
+): TrackMechanismVisualAdapter {
+  return new DipperMechanism(definition.id, world, root, definition, materials)
+}