Игровое аудио — Sound, голоса, шины
Звуковые эффекты для игр: Sound — клип, декодированный заранее, а audio.play() сразу пускает его
в микс — много одновременно, с питчем, случайными вариантами и приоритетами — через шины с
громкостью, эхом и реверберацией. Звуки приложения (тап по кнопке, сигнал, музыка) играют через
AudioPlayer, на любом хосте; audio — микшер игрового движка: только десктоп и iOS,
на Android, в вебе и в веб-плеере — немой no-op.
- сыграть звуковой эффект в игре — выстрел, прыжок, подбор монеты (
audio.play) - каждый раз играть другой звук шага или удара (варианты)
- зациклить звук двигателя или ветра и менять его питч на ходу (
Voice) - плавно увести звук в тишину или запустить что-то, когда он доиграл (
ended) - задать отдельную громкость музыке, эффектам и звукам UI (шины)
- добавить звукам реверберацию, эхо или приглушающий low-pass-фильтр
- не дать важным звукам оборваться, когда играет много сразу (
priority) - глушить эффекты на паузе, понижать их тон в замедлении
- откатиться на
AudioPlayerтам, где игровое аудио не работает - проверить в headless-тесте, что звук сыграл (
expect.audio)
Платформы: iOS (варианты движка full, 2d и core), десктоп; не на Android, не в вебе и не в веб-плеере — проверяй audio.supported.
Обзор
const main = async () => {
const click = await Sound.load(asset('./sfx/click.wav'))
const steps = await Sound.load([asset('./sfx/step1.wav'), asset('./sfx/step2.wav'), asset('./sfx/step3.wav')])
const hum = await Sound.load(asset('./sfx/hum.wav'))
audio.play(click, { bus: 'ui' }) // запустил и забыл
audio.play(steps, { volume: 0.6, pitch: 0.9 + Math.random() * 0.2 }) // случайный вариант при каждом play
const engine = audio.play(hum, { loop: true, fade: 0.5 }) // держим Voice, чтобы управлять им
engine.pitch = 1.3
engine.addEventListener('ended', () => console.log('engine off'))
setTimeout(() => engine.stop({ fade: 1 }), 3000)
audio.bus('sfx').reverb = 'cave'
audio.bus('music').volume = 0.5
}
main()Где работает игровое аудио: audio.supported
audio.supported говорит, микширует ли этот хост игровое аудио: true на десктопном хосте и на
iOS, как только движок открыл аудиоустройство, false на Android, в вебе и в веб-плеере. Без него
ничего не бросает исключений: Sound.load сразу резолвится в немой клип (ready === false) без
загрузки, play возвращает уже завершённый Voice, каждый сеттер — no-op. Где звук должен быть
слышен на любом хосте, откатывайся на AudioPlayer:
const main = async () => {
const coinUrl = asset('./sfx/coin.wav')
const coin = await Sound.load(coinUrl) // немой клип там, где audio.supported равен false
const playCoin = () => { // игра вызывает это при каждом подборе
if (audio.supported) audio.play(coin)
else new AudioPlayer(coinUrl).play() // Android, веб: плеер платформы
}
playCoin()
}
main()Оболочка iOS-приложения несёт самый маленький вариант движка, которого хватает её бандлу, а в
варианте 3d (его выбирают для приложения с 3D, но без 2D) игрового аудио нет: чтобы оно было,
задай "ios": { "variant": "full" } в app.json. Приложение-вьюер le.codes на iOS работает на
варианте full.
iOS-хост не задаёт категорию аудиосессии, так что действует умолчание Apple, пока плагин, который пишет звук (audio-recorder, speech, webrtc), не задаст свою: переключатель «Звонок/Бесшумно» глушит игровое аудио, а в фоне звук останавливается.
Загружай звуки до того, как они зазвучат: Sound.load
Загрузи каждый эффект один раз, до старта уровня: Sound.load скачивает файл и декодирует весь
клип, так что последующий play стартует мгновенно и ничего не стоит.
Sound.load(src: string | string[], options?: { stereo?: boolean }): Promise<Sound>
sound.duration // секунды (первого варианта); 0 для немого клипа
sound.channels // 1, или 2 с { stereo: true }
sound.variants // из скольких файлов он загружен
sound.urls // источники, как переданы
sound.ready // false без аудио хоста или после dispose()
sound.disposed // true после dispose()
sound.dispose() // освободить декодированный клип сейчас; играющие его голоса сразу останавливаются. Идемпотентноsrc — всё, что принимает fetch: asset('./x.wav'), удалённый URL. WAV, MP3 и OGG Vorbis;
файл, который не декодируется, отклоняет промис (Sound.load: <url>: cannot decode (wav / mp3 / ogg vorbis)). Декодирование идёт вне главного потока.
Клип декодируется в моно, если не передан { stereo: true }: моно — то, что пространственно
размещает 3D-источник, и то, чем эффекты и так являются. Оставь стерео для 2D-подложек и эмбиентов;
стереоклипы играют на своём, меньшем пуле голосов.
Sound держит весь клип в памяти как 32-битный float на частоте движка — 192 КБ на секунду моно
при 48 кГц, вдвое больше в стерео (audio.stats.clipBytes). Он живёт всё время работы приложения:
потеря ссылки ничего не освобождает. Делай dispose() тому, что завершённому уровню больше не
нужно. Музыка, озвучка и длинные треки — дело AudioPlayer, медиаплеера платформы:
один файл на плеер.
Случайные варианты: шаги, удары
Загрузи массив файлов, чтобы каждый раз играл другой: каждый play выбирает вариант случайно и,
когда их три и больше, никогда не повторяет один и тот же дважды подряд — шаги, удары, рикошеты.
const main = async () => {
const steps = await Sound.load([asset('./sfx/step1.wav'), asset('./sfx/step2.wav'), asset('./sfx/step3.wav')])
const footstep = () => // вызывай каждый раз, когда нога касается земли
audio.play(steps, { volume: 0.6, pitch: 0.9 + Math.random() * 0.2 }) // вариант, чуть сдвинутый по высоте
footstep()
}
main()Звуковой эффект в игре: audio.play
В игре audio.play сразу запускает загруженный Sound — выстрел, прыжок, монету — и возвращает его
Voice. Клик кнопки в приложении — это AudioPlayer: на Android и в вебе audio
молчит.
audio.play(sound: Sound, options?: {
volume?: number // линейное усиление; по умолчанию 1 (больше 1 усиливает)
pitch?: number // скорость воспроизведения, 0.01 … 10: 2 = на октаву выше и вдвое быстрее; по умолчанию 1
loop?: boolean // по умолчанию false
bus?: string // по умолчанию 'sfx'
priority?: number // перевешивает меньшие числа, когда пул полон; по умолчанию 0
fade?: number // fade-in, секунды; по умолчанию 0
startAt?: number // секунды от начала клипа; по умолчанию 0
pan?: number // -1 слева … 1 справа; по умолчанию 0
}): Voice
audio.stopAll(fade?: number) // каждый голос на каждой шине; fade в секундах, по умолчанию 0const main = async () => {
const jump = await Sound.load(asset('./sfx/jump.wav')) // загрузить один раз, до старта уровня
Input.on('keydown', (e) => {
if (e.code !== 'Space' || e.repeat) return
audio.play(jump, { volume: 0.8 }) // запустил и забыл: доиграет до конца
})
}
main()audio.play — 2D: звучит одинаково, что бы ни делала камера, размещается только через pan. Для
звука в точке мира — эмиттеры на узлах, зоны реверберации, слушатель — используй
3D-аудио (AudioSource, audio.playAt), на том же движке.
Слишком много звуков сразу: пул голосов и priority
Движок микширует не более 80 моно- и 20 стереоголосов одновременно и ничего не аллоцирует на
каждый play. Когда пул полон, новый звук забирает слот играющего голоса с меньшим или равным
priority: сначала самый низкий приоритет, затем одиночные звуки раньше циклов, затем самый тихий,
затем самый старый. Вытесненный голос завершается (ended срабатывает, audio.stats.stolen его
считает). Если у каждого играющего голоса приоритет выше, новый звук отклоняется: play возвращает
уже завершённый голос.
Давай музыкальным подложкам, циклам двигателя и диалогам priority выше, чем пулям и шагам:
const main = async () => {
const hum = await Sound.load(asset('./sfx/engine.wav'))
const shot = await Sound.load(asset('./sfx/shot.wav'))
const engine = audio.play(hum, { loop: true, priority: 5 }) // перевешивает любой выстрел
for (let i = 0; i < 100; i++) audio.play(shot) // очередь: больше 80 моноголосов
console.log('engine', engine.playing, 'cut off', audio.stats.stolen) // engine true, cut off 21
}
main()Зациклить звук и менять его на ходу: Voice
Держи Voice, который вернул audio.play, чтобы менять звук, пока он играет — двигатель, чей питч
следует за скоростью, нарастающий ветер, — и чтобы его остановить.
voice.playing // true, пока играет; false, когда закончился, остановлен или был отобран
voice.time // секунды от начала клипа
voice.volume = 0.5 // вживую, те же единицы, что в опциях
voice.pitch = 1.2
voice.pan = -1 // только 2D-голоса
voice.stop(options?: { fade?: number }) // секунды; по умолчанию 0 (сразу)
voice.addEventListener('ended', () => { }) // один раз: клип закончился, stop() или пул забрал слотconst main = async () => {
const hum = await Sound.load(asset('./sfx/engine.wav'))
class EngineSound extends System<'engineSound'> {
speed = 0 // м/с: задаёт код машины
private voice: Voice
onAttach() { this.voice = audio.play(hum, { loop: true, fade: 0.5 }) } // держим Voice
update() { this.voice.pitch = 0.8 + Math.min(this.speed / 30, 1) } // 0.8 на холостых … 1.8 на 30 м/с
onDetach() { this.voice.stop({ fade: 0.3 }) }
}
const scene = new Scene().system(EngineSound)
scene.open()
scene.engineSound.speed = 15 // питч 1.3 со следующего кадра
}
main()Voice — билет в пул движка, а не ресурс: потеря его ничего не освобождает, а одиночный звук,
который никто не держит, играет до конца. Как только голос завершён, playing читается как false
и его сеттеры ничего не делают — его слот, возможно, уже играет другой звук.
Затухание и действие по окончании звука: stop, ended
voice.stop({ fade }) плавно завершает цикл; событие ended сообщает, что голос завершён, — вешай
на него то, что идёт дальше, например уровень, который стартует, когда отыграл обратный отсчёт.
const main = async () => {
const countdown = await Sound.load(asset('./sfx/countdown.wav'))
const wind = await Sound.load(asset('./sfx/wind.wav'), { stereo: true })
const intro = audio.play(countdown, { bus: 'ui' })
intro.addEventListener('ended', () => { // добавляй при запуске
console.log('GO') // здесь стартует уровень
const ambience = audio.play(wind, { loop: true, fade: 2 }) // нарастает за 2 с
setTimeout(() => ambience.stop({ fade: 3 }), 30000) // затухает за 3 с
})
}
main()ended срабатывает на кадре после завершения голоса — после stop() сразу, не дожидаясь fade.
Добавляй слушатель при запуске: добавленный после завершения голоса никогда не сработает. Голос,
который так и не заиграл (нет аудио хоста, Sound после dispose, отклонённый play), завершён с
самого начала, и слушатель, добавленный к нему, срабатывает немедленно — так что цепочка вроде этой
работает и там, где audio.supported равен false.
Отдельная громкость для музыки, эффектов и UI: audio.bus
Каждый голос играет через микшерную шину, так что одна настройка делает громче, тише или выключает целую группу звуков — эффекты, музыку, клики UI, — как это делают звуковые настройки игры.
audio.bus(name: string): Bus // 'master' | 'sfx' | 'music' | 'ui' | 'voice', или своя
audio.master // audio.bus('master')
bus.name
bus.volume = 0.7 // линейное усиление; по умолчанию 1
bus.muted = true // по умолчанию false
bus.lowpass = 1200 // частота среза в Гц, 20 … 20000; null = выкл (по умолчанию)
bus.echo = { delay: 0.35, decay: 0.4, mix: 0.3 } // null = выкл (по умолчанию)
bus.reverb = 'hall' // пресет, параметры или null = выкл (по умолчанию)
bus.stopAll(fade?: number) // голоса, играющие на этой шине; fade в секундахconst main = async () => {
const shot = await Sound.load(asset('./sfx/shot.wav'))
const settings = { music: 0.4, effects: 0.8, interface: false } // что сохранил экран настроек
audio.bus('music').volume = settings.music
audio.bus('sfx').volume = settings.effects
audio.bus('ui').muted = !settings.interface
audio.play(shot) // на 'sfx', шине по умолчанию: на 0.8
}
main()Голос играет на sfx, если play (или его источник) не назвал другую шину; каждая
другая шина идёт в master. Пять шин выше существуют с самого начала; любое другое имя создаёт шину
при первом обращении — до 11 своих (16 всего). Сверх этого audio.bus() предупреждает и возвращает
шину, которая ничего не делает, а голоса, отправленные на неё, играют на sfx. Bus получается
только из audio.bus(); чтение настройки возвращает то, что было установлено.
опечатка в имени шины — не ошибка: она тихо создаёт новую шину. А stopAll() на шине
останавливает голоса, игравшие на ней, а не голоса шин, которые в неё идут:
audio.master.stopAll() — это не audio.stopAll().
AudioPlayer в этот микшер не входит — кроме десктопного хоста, где он играет
через шину music: audio.bus('music') достаёт до него только там. В остальных местах задавай
собственный volume плеера.
Реверберация, эхо и приглушение: эффекты шины
Шина может окрасить всё, что на ней играет: реверберация пещеры или зала, эхо в каньоне, low-pass,
который приглушает звук под водой. Цепочка инсертов идёт low-pass → эхо → реверберация; изменения
сглаживаются, так что переключение reverb в дверном проёме не щёлкает.
lowpass— частота среза в Гц, 20 … 20000: чем ниже, тем глуше.echo—delayсекунд между повторами (до 2),decayобратная связь 0 … 0.95 (сколько повторов выживает),mixдоля «мокрого» сигнала 0 … 1. Отсутствующие поля: 0.3 / 0.4 / 0.3.reverb— имя пресета или{ roomSize, damping, width, mix, preDelay }:roomSize0 (чулан) … 1 (собор),dampingпотеря высоких частот 0 … 1,widthстереоширина хвоста 0 … 1,mixдоля «мокрого» сигнала 0 … 1,preDelayсекунды до хвоста (до 0.25). Отсутствующие поля берутся изroom.
REVERB_PRESETS содержит шесть пресетов как параметры:
| пресет | roomSize | damping | width | mix | preDelay (с) |
|---|---|---|---|---|---|
room |
0.45 | 0.6 | 0.8 | 0.18 | 0.005 |
bathroom |
0.55 | 0.15 | 0.6 | 0.35 | 0.002 |
hall |
0.82 | 0.4 | 1.0 | 0.3 | 0.025 |
cave |
0.9 | 0.25 | 1.0 | 0.45 | 0.04 |
arena |
0.95 | 0.5 | 1.0 | 0.3 | 0.06 |
outdoor |
0.3 | 0.8 | 1.0 | 0.06 | 0 |
const main = async () => {
const shot = await Sound.load(asset('./sfx/shot.wav'))
const sfx = audio.bus('sfx')
sfx.reverb = 'cave' // игрок заходит в пещеру
sfx.echo = { delay: 0.35, decay: 0.4, mix: 0.25 }
audio.play(shot) // слышен с хвостом и эхом пещеры
setTimeout(() => { // через 5 с — под водой
sfx.reverb = { ...REVERB_PRESETS.cave, mix: 0.2 } // пресет, но «суше»
sfx.echo = null // выкл
sfx.lowpass = 800 // Гц: глухо
}, 5000)
}
main()AudioZone подменяет реверберацию шины, пока слушатель внутри неё.
Пауза и замедление: Time.paused, Time.scale
Пауза игры глушит её эффекты: Time.paused (или Time.scale = 0) делает шину sfx mute, но не
замораживает её — её голоса продолжают идти неслышно, и одиночный звук может закончиться во время
паузы. Все остальные шины продолжают играть, так что меню паузы сохраняет свои клики ui и свою
music. С audio.timeScalePitch = true Time.scale, отличный от 1, ещё и меняет питч шины sfx
(замедление понижает тон каждого эффекта; 0.1 … 4×); по умолчанию false.
const main = async () => {
const hum = await Sound.load(asset('./sfx/engine.wav'))
const scene = new Scene() // игровые часы доходят до микшера через 3D-движок
scene.open()
audio.timeScalePitch = true // замедление ещё и понижает тон эффектов
audio.play(hum, { loop: true }) // на 'sfx'
Input.on('keydown', (e) => {
if (e.code === 'Escape') Time.paused = !Time.paused // 'sfx' молчит, 'ui' и 'music' играют дальше
if (e.code === 'KeyT') Time.scale = Time.scale === 1 ? 0.3 : 1 // bullet time: медленнее и ниже
})
}
main()игровые часы доходят до аудиодвижка через 3D-движок — это действует, как только существует
Scene. Игра только на 2D (Scene2D) на паузе ничего не глушит: сам задавай
audio.bus('sfx').muted = Time.paused везде, где игра встаёт на паузу или продолжается.
Голоса и занятая память: audio.stats
audio.stats читает счётчики движка — для отладочного оверлея или лога производительности:
играющие голоса, голоса, обрезанные полным пулом, клипы в памяти.
audio.stats: {
voicesPlaying: number // живые голоса; голос, затухающий после stop(), уже не считается
voicesMono: number
voicesStereo: number
stolen: number // голоса, вытесненные полным пулом с момента старта движка
clips: number // декодированные клипы в памяти
clipBytes: number // их размер в байтах
peak: number // пик выхода master за последнюю секунду-две, линейный (1 = полная шкала)
sampleRate: number // частота микширования движка, Гц
listenerZone: number // зона реверберации, в которой слушатель (0 = нет) — см. 3D-аудио
zoneBlend: number // насколько глубоко внутри, 0 … 1
hrtfVoices: number // голоса, которые прямо сейчас рендерятся бинаурально — см. 3D-аудио
}Каждое чтение запрашивает у движка свежий объект. Без аудио хоста — всё нули.
Проверка в тесте, что звук сыграл: expect.audio
Headless-флоу (lecodes render / lecodes test без --sim или --desktop) записывает игровое
аудио, а не микширует его: audio.supported равен true, Sound загружается сразу с duration 0,
а одиночный звук там никогда не заканчивается (голос завершают только stop() и audio.stopAll()),
так что его ended не срабатывает. Шаг проверяет это через expect.audio: played проходит, как
только какой-нибудь play до этого момента использовал клип, чей источник содержит этот текст,
playing — число ещё не завершённых голосов. Для игры, которая по Space играет
asset('./sfx/jump.wav'):
{ "steps": [
{ "frames": 10, "expect": { "audio": { "playing": 0 } } },
{ "key": "Space", "ms": 50, "expect": { "audio": { "played": "jump" } } }
] }expect.audio проверяется только headless. Безоконный сервер (--sim) запускает настоящий движок
без аудиоустройства: загрузки, пул и stats настоящие, но голоса не продвигаются, так что одиночный
звук там никогда не заканчивается, — а декодирование занимает реальное время, пока кадры идут без
ограничения, так что дай загрузкам длинный шаг frames.