@marble.fun/track-catalog 3.0.0

package/src/pages/play/race/race-physics.ts

@@ -0,0 +1,16 @@
+export {
+  CONTACT_NATURAL_FREQUENCY,
+  createMarblePhysicsState,
+  createRacePhysicsWorld,
+  configureRacePhysicsWorld,
+  FIXED_TIMESTEP,
+  initializeRacePhysics,
+  MAX_RACE_SECONDS,
+  MAX_RACE_TICKS,
+  updateMarblePhysicsState,
+  type MarblePhysicsState,
+  type MutablePhysicsVector3,
+  type PhysicsCourse,
+  type PhysicsTrackPose,
+  type PhysicsTrackProjection,
+} from '@marble.fun/physics-engine'

package/src/pages/play/race/race-playback.ts

@@ -0,0 +1,41 @@
+// UI playback labels map directly to deterministic simulation time. Rapier
+// still advances at 120 Hz; 1x simply consumes two fixed steps per 60 Hz frame.
+export const STANDARD_RACE_TIME_SCALE = 1
+export const MIN_RACE_TIME_SCALE = 0.25
+export const MAX_RACE_TIME_SCALE = 3
+export const RACE_COUNTDOWN_SECONDS = 3
+
+export function playbackRateToTimeScale(playbackRate: number): number {
+  return playbackRate * STANDARD_RACE_TIME_SCALE
+}
+
+export function advanceRaceCountdown(secondsRemaining: number, realDeltaSeconds: number): number {
+  if (!Number.isFinite(realDeltaSeconds) || realDeltaSeconds <= 0) return secondsRemaining
+  return Math.max(0, secondsRemaining - realDeltaSeconds)
+}
+
+export function synchronizedRaceIntroState(
+  durationSeconds: number,
+  synchronizedElapsedMs: number,
+  synchronizedIntroElapsedMs?: number,
+): { countdownSeconds: number; elapsedSeconds: number; phase: 'countdown' | 'touring' } {
+  const finiteDuration = Number.isFinite(durationSeconds) ? Math.max(0, durationSeconds) : 0
+  const secondsUntilStart = Number.isFinite(synchronizedElapsedMs)
+    ? Math.max(0, -synchronizedElapsedMs / 1_000)
+    : finiteDuration
+  const synchronizedWindowSeconds =
+    synchronizedIntroElapsedMs !== undefined &&
+    Number.isFinite(synchronizedIntroElapsedMs) &&
+    Number.isFinite(synchronizedElapsedMs)
+      ? Math.max(0.001, (synchronizedIntroElapsedMs - synchronizedElapsedMs) / 1_000)
+      : undefined
+  const elapsedSeconds =
+    synchronizedWindowSeconds === undefined
+      ? Math.max(0, Math.min(finiteDuration, finiteDuration - secondsUntilStart))
+      : finiteDuration * Math.max(0, Math.min(1, synchronizedIntroElapsedMs! / 1_000 / synchronizedWindowSeconds))
+  return {
+    countdownSeconds: Math.min(RACE_COUNTDOWN_SECONDS, secondsUntilStart),
+    elapsedSeconds,
+    phase: secondsUntilStart <= RACE_COUNTDOWN_SECONDS ? 'countdown' : 'touring',
+  }
+}

package/src/pages/play/race/race-rolling-audio.ts

@@ -0,0 +1,616 @@
+import type RAPIER from '@dimforge/rapier3d-deterministic-compat'
+import * as THREE from 'three'
+
+import { isGameAudioEnabled } from '../../../audio/game-audio-preference'
+import type { MarbleEntity } from './marble-entity'
+
+const ROLL_SOURCE = '/audio/sfx/marble-roll.mp3'
+const COLLISION_SOURCE = '/audio/sfx/marble-collision.mp3'
+const TELEPORT_SOURCE = '/audio/sfx/teleport.mp3'
+const REBOUND_SOURCE = '/audio/sfx/boing.mp3'
+const RISING_WALL_CONTACT_SOURCE = '/audio/sfx/metalcontact.mp3'
+const CONE_CONTACT_SOURCE = '/audio/sfx/cones.mp3'
+const FLIPPER_ACCELERATING_HIT_SOURCE = '/audio/sfx/metalping.mp3'
+const WATER_ENTRY_SOURCE = '/audio/sfx/water-entry.mp3'
+const WATER_ROLL_SOURCE = '/audio/sfx/water-roll-loop.mp3'
+const MIN_ROLL_SPEED = 0.32
+const FULL_ROLL_SPEED = 8.5
+const MAX_PLAYBACK_SPEED = 18
+export const RACE_ROLLING_MASTER_GAIN = 0.88
+export const RACE_COLLISION_MASTER_GAIN = 0.6
+export const PORTAL_TELEPORT_MASTER_GAIN = 0.48
+export const REBOUND_HIT_MASTER_GAIN = 0.42
+export const RISING_WALL_CONTACT_MASTER_GAIN = 0.34
+export const CONE_CONTACT_MASTER_GAIN = 0.32
+export const FLIPPER_ACCELERATING_HIT_MASTER_GAIN = 0.13
+export const WATER_ENTRY_MASTER_GAIN = 0.34
+export const WATER_ROLLING_MASTER_GAIN = 0.62
+export const RISING_WALL_CONTACT_PLAYBACK_RATE = 1.12
+export const CONE_CONTACT_PLAYBACK_RATE = 1.48
+/** Approved mix shared by Test Run and the authoritative live race. */
+export const RACE_ROLLING_MIX_GAIN = 0.38
+export const RACE_COLLISION_MIX_GAIN = 0.65
+const GAIN_RESPONSE = 15
+const MAX_ONE_SHOTS = 6
+const MAX_COLLISION_ONE_SHOTS = 4
+const MAX_FEATURE_ONE_SHOTS = 2
+const IMPACT_COOLDOWN_STEPS = 8
+const MIN_IMPACT_IMPULSE = 0.8
+const FULL_IMPACT_IMPULSE = 14
+
+interface LoopVoice {
+  source?: AudioBufferSourceNode
+  gainNode?: GainNode
+  panNode?: StereoPannerNode
+  gain: number
+  targetGain: number
+  playbackRate: number
+  position: THREE.Vector3
+}
+
+interface PendingImpact {
+  gain: number
+  playbackRate: number
+  position: THREE.Vector3
+}
+
+interface ActiveOneShot {
+  source: AudioBufferSourceNode
+  gainNode: GainNode
+  panNode: StereoPannerNode
+  path: string
+  startedAt: number
+}
+
+export interface OneShotVoice {
+  path: string
+  startedAt: number
+}
+
+/**
+ * Reuse the oldest matching voice before consuming another slot. If the
+ * bounded pool is full, feature sounds replace a generic collision first so
+ * one noisy contact category cannot silence every later mechanism sound.
+ */
+export function oneShotVoiceReplacement(voices: readonly OneShotVoice[], path: string): number | undefined {
+  const matching = voices
+    .map((voice, index) => ({ voice, index }))
+    .filter(entry => entry.voice.path === path)
+    .sort((left, right) => left.voice.startedAt - right.voice.startedAt)
+  const sourceLimit = path === COLLISION_SOURCE ? MAX_COLLISION_ONE_SHOTS : MAX_FEATURE_ONE_SHOTS
+  if (matching.length >= sourceLimit) return matching[0]?.index
+  if (voices.length < MAX_ONE_SHOTS) return undefined
+
+  if (path !== COLLISION_SOURCE) {
+    const oldestCollision = voices
+      .map((voice, index) => ({ voice, index }))
+      .filter(entry => entry.voice.path === COLLISION_SOURCE)
+      .sort((left, right) => left.voice.startedAt - right.voice.startedAt)[0]
+    if (oldestCollision) return oldestCollision.index
+  }
+  return voices
+    .map((voice, index) => ({ voice, index }))
+    .sort((left, right) => left.voice.startedAt - right.voice.startedAt)[0]?.index
+}
+
+export interface RollingAudioMix {
+  gain: number
+  playbackRate: number
+}
+
+export interface CollisionAudioMix {
+  gain: number
+  playbackRate: number
+}
+
+export interface RaceAudioFeatures {
+  water?: boolean
+  portals?: boolean
+  rebounds?: boolean
+  risingWalls?: boolean
+  cones?: boolean
+  flippers?: boolean
+}
+
+export function waterRollingAudioMix(linearSpeed: number, inWater: boolean): RollingAudioMix {
+  if (!inWater || linearSpeed < 0.25) return { gain: 0, playbackRate: 0.88 }
+  const response = smoothstep((linearSpeed - 0.25) / 5.75)
+  return { gain: response, playbackRate: THREE.MathUtils.lerp(0.88, 1.16, response) }
+}
+
+export function waterEntryGain(linearSpeed: number): number {
+  return THREE.MathUtils.lerp(0.48, 1, smoothstep(linearSpeed / 12))
+}
+
+function smoothstep(value: number): number {
+  const clamped = THREE.MathUtils.clamp(value, 0, 1)
+  return clamped * clamped * (3 - 2 * clamped)
+}
+
+export function rollingAudioMix(
+  linearSpeed: number,
+  angularSpeed: number,
+  radius: number,
+  grounded: boolean,
+): RollingAudioMix {
+  if (!grounded || linearSpeed < MIN_ROLL_SPEED || angularSpeed <= 0 || radius <= 0) {
+    return { gain: 0, playbackRate: 0.72 }
+  }
+  const rollingSpeed = Math.min(linearSpeed, angularSpeed * radius * 1.2)
+  return {
+    gain: smoothstep((rollingSpeed - MIN_ROLL_SPEED) / (FULL_ROLL_SPEED - MIN_ROLL_SPEED)),
+    playbackRate: THREE.MathUtils.lerp(
+      0.72,
+      1.58,
+      smoothstep((rollingSpeed - MIN_ROLL_SPEED) / (MAX_PLAYBACK_SPEED - MIN_ROLL_SPEED)),
+    ),
+  }
+}
+
+export function collisionAudioMix(contactImpulse: number): CollisionAudioMix {
+  const gain = smoothstep((contactImpulse - MIN_IMPACT_IMPULSE) / (FULL_IMPACT_IMPULSE - MIN_IMPACT_IMPULSE))
+  return { gain, playbackRate: THREE.MathUtils.lerp(0.88, 1.15, gain) }
+}
+
+/** Lightweight race mixer: decoded buffers + stereo pan, with no media-element or HRTF graph. */
+export class RaceRollingAudio {
+  private context?: AudioContext
+  private readonly ownsContext: boolean
+  private readonly buffers = new Map<string, Promise<AudioBuffer | undefined>>()
+  private readonly voices: LoopVoice[]
+  private readonly waterVoices: LoopVoice[]
+  private readonly waterStates: boolean[]
+  private readonly waterEntryCooldownSeconds: number[]
+  private readonly activeOneShots = new Set<ActiveOneShot>()
+  private readonly activeContactKeys = new Set<string>()
+  private readonly impactCooldownSteps: number[]
+  private readonly pendingImpacts: PendingImpact[] = []
+  private readonly pendingTeleports: THREE.Vector3[] = []
+  private readonly pendingReboundHits: THREE.Vector3[] = []
+  private readonly pendingRisingWallContacts: THREE.Vector3[] = []
+  private readonly pendingConeContacts: THREE.Vector3[] = []
+  private readonly pendingFlipperAcceleratingHits: THREE.Vector3[] = []
+  private readonly listenerPosition = new THREE.Vector3()
+  private readonly listenerRight = new THREE.Vector3()
+  private readonly listenerForward = new THREE.Vector3()
+  private readonly sourcePosition = new THREE.Vector3()
+  private readonly sourceOffset = new THREE.Vector3()
+  private enabled: boolean
+  private readonly rollingGain: number
+  private readonly collisionGain: number
+  private readonly features: RaceAudioFeatures
+  private disposed = false
+  private readonly startedSources: Record<string, number> = {}
+  private bufferFailures = 0
+
+  diagnostics() {
+    return {
+      enabled: this.enabled,
+      contextState: this.context?.state ?? 'not-created',
+      startedSources: { ...this.startedSources },
+      audibleLoops: [...this.voices, ...this.waterVoices].filter(
+        voice => voice.source && (voice.gainNode?.gain.value ?? 0) > 0.0001,
+      ).length,
+      activeOneShots: this.activeOneShots.size,
+      bufferFailures: this.bufferFailures,
+    }
+  }
+
+  constructor(
+    voiceCount: number,
+    enabled = isGameAudioEnabled(),
+    rollingGain = 1,
+    collisionGain = rollingGain,
+    features: RaceAudioFeatures = {},
+    context?: AudioContext,
+  ) {
+    this.context = context
+    this.ownsContext = context === undefined
+    this.enabled = enabled
+    this.rollingGain = THREE.MathUtils.clamp(rollingGain, 0, 1)
+    this.collisionGain = THREE.MathUtils.clamp(collisionGain, 0, 1)
+    this.features = features
+    this.voices = Array.from({ length: voiceCount }, () => this.createLoopState())
+    this.waterVoices = features.water ? Array.from({ length: voiceCount }, () => this.createLoopState()) : []
+    this.waterStates = Array.from({ length: voiceCount }, () => false)
+    this.waterEntryCooldownSeconds = Array.from({ length: voiceCount }, () => 0)
+    this.impactCooldownSteps = Array.from({ length: voiceCount }, () => 0)
+  }
+
+  setEnabled(enabled: boolean): void {
+    this.enabled = enabled
+    if (!enabled) this.silenceImmediately()
+  }
+
+  queuePortalTeleport(position: THREE.Vector3): void {
+    if (!this.canQueue(this.features.portals, this.pendingTeleports)) return
+    this.pendingTeleports.push(position.clone())
+  }
+
+  queueReboundHit(position: THREE.Vector3): void {
+    if (!this.canQueue(this.features.rebounds, this.pendingReboundHits)) return
+    this.pendingReboundHits.push(position.clone())
+  }
+
+  queueRisingWallContact(position: THREE.Vector3): void {
+    if (!this.canQueue(this.features.risingWalls, this.pendingRisingWallContacts)) return
+    this.pendingRisingWallContacts.push(position.clone())
+  }
+
+  queueConeContact(position: THREE.Vector3): void {
+    if (!this.canQueue(this.features.cones, this.pendingConeContacts)) return
+    this.pendingConeContacts.push(position.clone())
+  }
+
+  queueFlipperAcceleratingHit(position: THREE.Vector3): void {
+    if (!this.canQueue(this.features.flippers, this.pendingFlipperAcceleratingHits)) return
+    this.pendingFlipperAcceleratingHits.push(position.clone())
+  }
+
+  queueCollisionImpact(impulse: number, position: THREE.Vector3): void {
+    if (this.disposed || !this.enabled) return
+    const mix = collisionAudioMix(impulse)
+    if (mix.gain <= 0) return
+    if (this.pendingImpacts.length < MAX_ONE_SHOTS) this.pendingImpacts.push({ ...mix, position: position.clone() })
+  }
+
+  captureCollisions(
+    world: RAPIER.World,
+    marbles: readonly MarbleEntity[],
+    audible = true,
+    specializedAudioColliderHandles: ReadonlySet<number> = new Set(),
+  ): void {
+    if (this.disposed) return
+    const currentContactKeys = new Set<string>()
+    this.impactCooldownSteps.forEach((cooldown, index) => {
+      this.impactCooldownSteps[index] = Math.max(0, cooldown - 1)
+    })
+    marbles.forEach((marble, marbleIndex) => {
+      const collider = marble.body.collider(0)
+      world.contactPairsWith(collider, other => {
+        if (specializedAudioColliderHandles.has(other.handle)) return
+        const contactKey = `${Math.min(collider.handle, other.handle)}:${Math.max(collider.handle, other.handle)}`
+        if (currentContactKeys.has(contactKey)) return
+        let strongestImpulse = 0
+        world.contactPair(collider, other, manifold => {
+          for (let index = 0; index < manifold.numContacts(); index += 1) {
+            strongestImpulse = Math.max(strongestImpulse, Math.abs(manifold.contactImpulse(index)))
+          }
+        })
+        if (strongestImpulse <= 0) return
+        currentContactKeys.add(contactKey)
+        if (this.activeContactKeys.has(contactKey) || (this.impactCooldownSteps[marbleIndex] ?? 0) > 0) return
+        if (audible) {
+          const translation = marble.body.translation()
+          this.queueCollisionImpact(strongestImpulse, new THREE.Vector3(translation.x, translation.y, translation.z))
+        }
+        this.impactCooldownSteps[marbleIndex] = IMPACT_COOLDOWN_STEPS
+      })
+    })
+    this.activeContactKeys.clear()
+    currentContactKeys.forEach(key => this.activeContactKeys.add(key))
+  }
+
+  update(
+    deltaSeconds: number,
+    active: boolean,
+    world: RAPIER.World | undefined,
+    marbles: readonly MarbleEntity[],
+    visualRoot: THREE.Object3D,
+    camera: THREE.Camera,
+    waterByMarble: readonly boolean[] = [],
+    groundedByMarble: readonly boolean[] = [],
+  ): void {
+    if (this.disposed || !this.enabled || !active || document.visibilityState === 'hidden' || !world) {
+      this.fadeLoops(deltaSeconds, false)
+      return
+    }
+    const context = this.ensureContext()
+    if (context.state === 'suspended') void context.resume().catch(() => undefined)
+    camera.getWorldPosition(this.listenerPosition)
+    camera.getWorldDirection(this.listenerForward)
+    this.listenerRight.crossVectors(this.listenerForward, camera.up).normalize()
+    this.flushOneShots(visualRoot)
+
+    let audibleRolls = 0
+    let audibleWater = 0
+    this.voices.forEach((voice, index) => {
+      this.waterEntryCooldownSeconds[index] = Math.max(0, (this.waterEntryCooldownSeconds[index] ?? 0) - deltaSeconds)
+      const marble = marbles[index]
+      if (!marble) {
+        voice.targetGain = 0
+        return
+      }
+      const velocity = marble.body.linvel()
+      const angularVelocity = marble.body.angvel()
+      const linearSpeed = Math.hypot(velocity.x, velocity.y, velocity.z)
+      const angularSpeed = Math.hypot(angularVelocity.x, angularVelocity.y, angularVelocity.z)
+      const inWater = waterByMarble[index] === true
+      const mix = rollingAudioMix(
+        linearSpeed,
+        angularSpeed,
+        marble.tuning.radius,
+        groundedByMarble[index] ?? this.isGrounded(world, marble),
+      )
+      voice.targetGain = mix.gain * (inWater ? 0.22 : 1)
+      voice.playbackRate = mix.playbackRate
+      this.writeWorldPosition(voice.position, marble, visualRoot)
+      if (voice.targetGain > 0) audibleRolls += 1
+
+      const waterVoice = this.waterVoices[index]
+      if (!waterVoice) return
+      const waterMix = waterRollingAudioMix(linearSpeed, inWater)
+      waterVoice.targetGain = waterMix.gain
+      waterVoice.playbackRate = waterMix.playbackRate
+      waterVoice.position.copy(voice.position)
+      if (waterVoice.targetGain > 0) audibleWater += 1
+      if (inWater && !this.waterStates[index] && (this.waterEntryCooldownSeconds[index] ?? 0) <= 0) {
+        this.playOneShot(
+          WATER_ENTRY_SOURCE,
+          waterEntryGain(linearSpeed) * WATER_ENTRY_MASTER_GAIN,
+          0.96,
+          voice.position,
+        )
+        this.waterEntryCooldownSeconds[index] = 0.45
+      }
+      this.waterStates[index] = inWater
+    })
+    const rollPackGain = audibleRolls > 0 ? 1 / audibleRolls ** 0.25 : 1
+    const waterPackGain = audibleWater > 0 ? 1 / audibleWater ** 0.2 : 1
+    this.updateLoopSet(
+      this.voices,
+      ROLL_SOURCE,
+      deltaSeconds,
+      RACE_ROLLING_MASTER_GAIN * rollPackGain * this.rollingGain,
+    )
+    this.updateLoopSet(
+      this.waterVoices,
+      WATER_ROLL_SOURCE,
+      deltaSeconds,
+      WATER_ROLLING_MASTER_GAIN * waterPackGain * this.rollingGain,
+    )
+  }
+
+  dispose(): void {
+    if (this.disposed) return
+    this.disposed = true
+    this.silenceImmediately()
+    if (this.ownsContext) void this.context?.close()
+    this.context = undefined
+    this.buffers.clear()
+  }
+
+  private createLoopState(): LoopVoice {
+    return { gain: 0, targetGain: 0, playbackRate: 1, position: new THREE.Vector3() }
+  }
+
+  private canQueue(feature: boolean | undefined, queue: readonly unknown[]): boolean {
+    return !this.disposed && this.enabled && feature === true && queue.length < 2
+  }
+
+  private ensureContext(): AudioContext {
+    this.context ??= new AudioContext({ latencyHint: 'playback' })
+    return this.context
+  }
+
+  private loadBuffer(path: string): Promise<AudioBuffer | undefined> {
+    const existing = this.buffers.get(path)
+    if (existing) return existing
+    const promise = fetch(path)
+      .then(response => (response.ok ? response.arrayBuffer() : Promise.reject(new Error(`Audio ${response.status}`))))
+      .then(bytes => (this.disposed ? undefined : this.ensureContext().decodeAudioData(bytes)))
+      .catch(() => {
+        // A transient fetch/decode failure must not permanently mute this
+        // sound for the rest of the race.
+        this.bufferFailures += 1
+        this.buffers.delete(path)
+        return undefined
+      })
+    this.buffers.set(path, promise)
+    return promise
+  }
+
+  private updateLoopSet(voices: readonly LoopVoice[], path: string, deltaSeconds: number, masterGain: number): void {
+    const alpha = 1 - Math.exp(-GAIN_RESPONSE * Math.max(0, deltaSeconds))
+    voices.forEach(voice => {
+      voice.gain = THREE.MathUtils.lerp(voice.gain, voice.targetGain * masterGain, alpha)
+      if (voice.gain < 0.0001) voice.gain = 0
+      if (voice.targetGain > 0 && !voice.source) void this.startLoop(voice, path)
+      if (voice.source) voice.source.playbackRate.value = voice.playbackRate
+      if (voice.gainNode) voice.gainNode.gain.value = voice.gain * this.distanceGain(voice.position)
+      if (voice.panNode) voice.panNode.pan.value = this.stereoPan(voice.position)
+      if (voice.gain === 0 && voice.targetGain === 0) this.stopLoop(voice)
+    })
+  }
+
+  private async startLoop(voice: LoopVoice, path: string): Promise<void> {
+    const buffer = await this.loadBuffer(path)
+    if (!buffer || this.disposed || voice.source || voice.targetGain <= 0) return
+    const context = this.ensureContext()
+    const source = context.createBufferSource()
+    const gainNode = context.createGain()
+    const panNode = context.createStereoPanner()
+    source.buffer = buffer
+    source.loop = true
+    source.playbackRate.value = voice.playbackRate
+    gainNode.gain.value = voice.gain
+    panNode.pan.value = this.stereoPan(voice.position)
+    source.connect(gainNode).connect(panNode).connect(context.destination)
+    voice.source = source
+    voice.gainNode = gainNode
+    voice.panNode = panNode
+    source.start()
+    this.startedSources[path] = (this.startedSources[path] ?? 0) + 1
+  }
+
+  private stopLoop(voice: LoopVoice): void {
+    voice.source?.stop()
+    voice.source?.disconnect()
+    voice.gainNode?.disconnect()
+    voice.panNode?.disconnect()
+    voice.source = undefined
+    voice.gainNode = undefined
+    voice.panNode = undefined
+  }
+
+  private flushOneShots(visualRoot: THREE.Object3D): void {
+    this.pendingImpacts
+      .sort((left, right) => right.gain - left.gain)
+      .forEach(impact => {
+        this.writeEventPosition(impact.position, visualRoot)
+        this.playOneShot(
+          COLLISION_SOURCE,
+          impact.gain * RACE_COLLISION_MASTER_GAIN * this.collisionGain,
+          impact.playbackRate,
+          impact.position,
+        )
+      })
+    this.flushFeature(this.pendingTeleports, TELEPORT_SOURCE, PORTAL_TELEPORT_MASTER_GAIN, 1, visualRoot)
+    this.flushFeature(this.pendingReboundHits, REBOUND_SOURCE, REBOUND_HIT_MASTER_GAIN, 1, visualRoot)
+    this.flushFeature(
+      this.pendingRisingWallContacts,
+      RISING_WALL_CONTACT_SOURCE,
+      RISING_WALL_CONTACT_MASTER_GAIN,
+      RISING_WALL_CONTACT_PLAYBACK_RATE,
+      visualRoot,
+    )
+    this.flushFeature(
+      this.pendingConeContacts,
+      CONE_CONTACT_SOURCE,
+      CONE_CONTACT_MASTER_GAIN,
+      CONE_CONTACT_PLAYBACK_RATE,
+      visualRoot,
+    )
+    this.flushFeature(
+      this.pendingFlipperAcceleratingHits,
+      FLIPPER_ACCELERATING_HIT_SOURCE,
+      FLIPPER_ACCELERATING_HIT_MASTER_GAIN,
+      1,
+      visualRoot,
+    )
+    this.pendingImpacts.length = 0
+  }
+
+  private flushFeature(
+    queue: THREE.Vector3[],
+    path: string,
+    gain: number,
+    rate: number,
+    visualRoot: THREE.Object3D,
+  ): void {
+    queue.forEach(position => {
+      this.writeEventPosition(position, visualRoot)
+      this.playOneShot(path, gain * this.collisionGain, rate, position)
+    })
+    queue.length = 0
+  }
+
+  private async playOneShot(path: string, gain: number, playbackRate: number, position: THREE.Vector3): Promise<void> {
+    const buffer = await this.loadBuffer(path)
+    if (!buffer || this.disposed || !this.enabled) return
+    const activeVoices = [...this.activeOneShots]
+    const replacementIndex = oneShotVoiceReplacement(activeVoices, path)
+    if (replacementIndex !== undefined) this.stopOneShot(activeVoices[replacementIndex]!)
+    const context = this.ensureContext()
+    const source = context.createBufferSource()
+    const gainNode = context.createGain()
+    const panNode = context.createStereoPanner()
+    source.buffer = buffer
+    source.playbackRate.value = playbackRate
+    gainNode.gain.value = gain * this.distanceGain(position)
+    panNode.pan.value = this.stereoPan(position)
+    source.connect(gainNode).connect(panNode).connect(context.destination)
+    const voice: ActiveOneShot = { source, gainNode, panNode, path, startedAt: context.currentTime }
+    this.activeOneShots.add(voice)
+    source.addEventListener(
+      'ended',
+      () => {
+        this.releaseOneShot(voice)
+      },
+      { once: true },
+    )
+    source.start()
+    this.startedSources[path] = (this.startedSources[path] ?? 0) + 1
+  }
+
+  private releaseOneShot(voice: ActiveOneShot): void {
+    if (!this.activeOneShots.delete(voice)) return
+    voice.source.disconnect()
+    voice.gainNode.disconnect()
+    voice.panNode.disconnect()
+  }
+
+  private stopOneShot(voice: ActiveOneShot): void {
+    if (!this.activeOneShots.has(voice)) return
+    voice.source.stop()
+    this.releaseOneShot(voice)
+  }
+
+  private writeWorldPosition(target: THREE.Vector3, marble: MarbleEntity, visualRoot: THREE.Object3D): void {
+    const translation = marble.body.translation()
+    target.set(translation.x, translation.y, translation.z)
+    visualRoot.localToWorld(target)
+  }
+
+  private writeEventPosition(position: THREE.Vector3, visualRoot: THREE.Object3D): void {
+    this.sourcePosition.copy(position)
+    visualRoot.localToWorld(this.sourcePosition)
+    position.copy(this.sourcePosition)
+  }
+
+  private stereoPan(position: THREE.Vector3): number {
+    this.sourceOffset.copy(position).sub(this.listenerPosition)
+    const distance = Math.max(5, this.sourceOffset.length())
+    return THREE.MathUtils.clamp(this.sourceOffset.dot(this.listenerRight) / distance, -1, 1)
+  }
+
+  private distanceGain(position: THREE.Vector3): number {
+    const distance = position.distanceTo(this.listenerPosition)
+    return 1 / (1 + Math.max(0, distance - 5) * 0.025)
+  }
+
+  private isGrounded(world: RAPIER.World, marble: MarbleEntity): boolean {
+    const collider = marble.body.collider(0)
+    let grounded = false
+    world.contactPairsWith(collider, other => {
+      if (grounded) return
+      world.contactPair(collider, other, manifold => {
+        if (manifold.numSolverContacts() > 0) grounded = true
+      })
+    })
+    return grounded
+  }
+
+  private fadeLoops(deltaSeconds: number, canStart: boolean): void {
+    this.voices.forEach(voice => {
+      voice.targetGain = canStart ? voice.targetGain : 0
+    })
+    this.waterVoices.forEach(voice => {
+      voice.targetGain = canStart ? voice.targetGain : 0
+    })
+    this.updateLoopSet(this.voices, ROLL_SOURCE, deltaSeconds, RACE_ROLLING_MASTER_GAIN * this.rollingGain)
+    this.updateLoopSet(this.waterVoices, WATER_ROLL_SOURCE, deltaSeconds, WATER_ROLLING_MASTER_GAIN * this.rollingGain)
+  }
+
+  private silenceImmediately(): void {
+    this.voices.forEach(voice => {
+      voice.gain = 0
+      voice.targetGain = 0
+      this.stopLoop(voice)
+    })
+    this.waterVoices.forEach(voice => {
+      voice.gain = 0
+      voice.targetGain = 0
+      this.stopLoop(voice)
+    })
+    this.activeOneShots.forEach(voice => this.stopOneShot(voice))
+    this.pendingImpacts.length = 0
+    this.pendingTeleports.length = 0
+    this.pendingReboundHits.length = 0
+    this.pendingRisingWallContacts.length = 0
+    this.pendingConeContacts.length = 0
+    this.pendingFlipperAcceleratingHits.length = 0
+    this.waterStates.fill(false)
+    this.waterEntryCooldownSeconds.fill(0)
+  }
+}