Play a sound in your game
This page adds one WAV file to your game and plays it when you press Space. It uses the engine’s own short beep first, then shows how to replace it with your sound. There is no bank-packing step or XWBTool installation.
Start from the game in Make a first change,
using a fresh copy or its backup step before these edits. Space is unused by
the ordinary starter; another guide may already have assigned it a job in
your modified game. This walkthrough uses the starter’s HelloState.
Use the x64 Native Tools Command Prompt in your project folder:
cd /d C:\dev\mygameAdd the WAV and its manifest entry
Section titled “Add the WAV and its manifest entry”The wave kind reads one .wav file into a loaded SoundBank. The file,
bank, wave and persistent effect all use the same name, without .wav.
Here that name is ping_wav.
-
Copy the beep. It is generated PCM audio supplied with the engine, under the engine’s MIT licence:
Terminal window mkdir game\content\wavescopy external\labrador\samples\audio\source\ping.wav game\content\waves\ping_wav.wavcopyends with1 file(s) copied.Ifmkdirsays the folder already exists, continue. Ifcopycannot find the source, check that the prompt is inC:\dev\mygameand that the full engine is still inexternal\labrador.source\ping.wavis the original WAV, not the packedtones.xwbbeside the audio sample’s manifest. -
List it in the game’s manifest. Open:
Terminal window notepad game\content\manifest.jsonIn an unchanged starter, replace its contents with this version. If your manifest already has other groups, keep them and add the
wavegroup at the end of theassetslist, with a comma between groups:game\content\manifest.json {"assets": [{"kind": "font","directory": "./fonts/","names": ["jetbrains_mono_bold_16"]},{"kind": "wave","directory": "./waves/","names": ["ping_wav"]}]}Save and close Notepad. The entry means
waves/ping_wav.wav; you need neitherping_wav.jsonnor an.xwbfile. Assets are required by default. A missing or malformed required WAV stops loading with its name and path. Keep that default while following the guide so a mistake is reported.
Copy, embed and install the file
Section titled “Copy, embed and install the file”The Windows executable reads content beside itself. The browser build embeds
the whole content folder, and needs to link again when the WAV changes.
The release install also needs the new directory.
Open the game’s build file:
notepad game\CMakeLists.txt-
Track changes to the browser’s embedded WAV. Search with Ctrl+F for
jetbrains_mono_bold_16.spritefont. Add the new path after that line:"${CMAKE_CURRENT_SOURCE_DIR}/content/fonts/jetbrains_mono_bold_16.spritefont""${CMAKE_CURRENT_SOURCE_DIR}/content/waves/ping_wav.wav"Keep any paths another guide added. This list makes the browser page link again when the WAV changes; embedding the folder alone does not do that.
-
Copy the directory beside the Windows program. Search for
add_dependencies(MyGame game_content)and paste this block immediately above it:add_custom_command(TARGET game_content POST_BUILDCOMMAND "${CMAKE_COMMAND}" -E copy_directory_if_different"${CMAKE_CURRENT_SOURCE_DIR}/content/waves""$<TARGET_FILE_DIR:MyGame>/waves"VERBATIM)The existing manifest and font copy commands stay in place.
-
Put the WAV in a Windows release. Search for
install(DIRECTORY content/fontsand add a line after it:install(DIRECTORY content/fonts DESTINATION .)install(DIRECTORY content/waves DESTINATION .)Save and close Notepad. The browser branch already embeds
contentat/, so it needs no second embed option.
Resolve once, then play on Space
Section titled “Resolve once, then play on Space”HelloState keeps a borrowed bank pointer and the handle of its one wave.
The application owns AudioResources, which owns the bank and outlives this
state. The guide loads it once and never replaces it while that pointer is
in use. Looking up the names happens in init; playing happens in update.
-
Add the sound-bank header. Open:
Terminal window notepad game\states\hello_state.hSearch for
#include "engine/app/application.h"and add this line below it:Add the sound-bank include #include "engine/audio/sound_bank.h" -
Keep the bank and wave handle. Search for
hint_ = nullptr;and add:Keep the bank and wave handle // Borrowed from the application's AudioResources, which outlives this state.Save and close the header.
-
Resolve the two names once. Open:
Terminal window notepad game\states\hello_state.cppSearch for
RenderResources* resources =. The starter’s line is:samples/minimal/states/hello_state.cpp Add these lines after it:
Resolve the WAV asset this->ping_wav_bank_ = this->app_->audio_resources()->sound_bank("ping_wav");this->ping_wav_ = this->ping_wav_bank_->resolve_wave("ping_wav");The first name is the bank added by the manifest. The second is the wave in it. Both are
ping_wavfor a direct WAV asset. A spelling mistake fails here at startup, rather than becoming a key that silently does nothing. -
Play on the pressed edge. Search for
const Keyboard& keyboard = *this->app_->keyboard();and add this block immediately after it:Play once on Space {this->ping_wav_bank_->play_wave(this->ping_wav_, 0.4f);}Save and close the file.
pressedis true for the step when Space goes down, so holding the key does not launch a new sound every step. Each new press starts a separate one-shot; quick presses may overlap.0.4fis 40% volume. Do not play sound fromdraw().
Build, test and try it
Section titled “Build, test and try it”Quit a running copy before building. In the same prompt:
cmake --build --preset x64-debug && ctest --preset x64-debug && out\build\x64-debug\game\MyGame.exeThe changed build file makes CMake configure again. The ordinary starter’s
two tests remain MyGameTests and MyGameSmokeTests; both must pass. The
smoke test loads the required WAV, so a missing file or bad name fails before
the ordinary game starts. It does not establish that speakers produced sound.
Click the game window, then press Space. The short beep should play. The starter’s original on-screen hint still names its original controls; Space is the control this page adds. Escape still opens the quit question and Enter still answers yes.
If the test fails, read the first message under ***Failed; the later
Errors while running CTest line only repeats that a test failed.
Read a build error explains compiler
errors. If something fails covers the file and name
checks below.
Use your own sound
Section titled “Use your own sound”Replace game\content\waves\ping_wav.wav with a WAV you may distribute,
keeping that name, then build again. For example, change the first path in:
copy /y "%USERPROFILE%\Downloads\my sound.wav" game\content\waves\ping_wav.wavcmake --build --preset x64-debug/y replaces the existing file. Keep the original of your own sound somewhere
of your own too. The manifest and C++ handles stay the same. The Windows
build copies the replacement; the browser build relinks because its path is
in LINK_DEPENDS.
The direct reader supports ordinary little-endian RIFF/WAVE PCM,
8-bit unsigned or 16-bit signed, mono or stereo, at 8,000–96,000 Hz.
An .mp3 renamed to .wav is still an MP3. Float, 24-bit PCM, compressed WAV,
WAVE_FORMAT_EXTENSIBLE and unsupported loop forms are refused with the path
and reason. Export ordinary 16-bit PCM from your audio editor, or use the
conversion instructions in the bank guide.
Copy the converted WAV directly; the new route needs no subsequent bank pack.
A sound that keeps playing
Section titled “A sound that keeps playing”A direct wave asset also creates one persistent effect instance with the
same name. Resolve it once with resolve_effect("ping_wav"), then use
play_effect, pause_effect, resume_effect and stop_effect when your game
needs a retained voice. Audio
explains those transitions. Looping a short beep repeats it until stopped;
choose content intended to loop before adding music.
The WAV’s optional supported smpl loop is a region in frames. A looping
effect plays from the beginning and then repeats that region; without a
region, it repeats the whole wave. This is in-memory playback, and a longer
track increases the page download and decoded memory cost.
Music, bank memory and the page download
keeps those limits separate from streaming.
If something fails
Section titled “If something fails”- The startup message says kind
wavewas not registered. Check the development-version notice at the top. Av0.3.0engine cannot load this new asset kind. The retained XWB guide works with that release. - The message names a missing
ping_wav.wav. Checkgame\content\waves\ping_wav.wav, the manifest’s./waves/and the native copy command. The program reads the build directory’s copy. A stale old file there may remain after deleting only the source copy. - The reader refuses its format or chunks. Export the supported PCM format above. The file’s extension does not determine its encoding.
- The bank or wave was not loaded. Check both
"ping_wav"names ininitagainst the manifest and filename. Preserve thewavegroup if another guide later replaces the manifest.
Required assets are the default. An explicitly optional unavailable sound
may instead report a diagnostic and produce a silent bank; audible() means
loaded content, and is not listening evidence. Do not make the asset optional
to hide a mistake in this walkthrough.
No sound, and no error
Section titled “No sound, and no error”Click the game’s window so it receives the key. Check Windows’ output and volume mixer, and that you built the ordinary XAudio2 preset rather than a null-audio configuration. A missing output may leave the backend silent; after reconnecting, try the key again once recovery has had an update. The sample’s source tone has a modest level, and the example uses volume 0.4. Loaded content and state tests do not establish audible output: try the sound on the speakers or headphones you intend to use.
In the browser build
Section titled “In the browser build”Build for the browser packages the same content
folder. Serve the page over HTTP, click its canvas and press Space. That
trusted key gives Web Audio its first activating gesture and asks the game
to play the WAV. Escape alone does not unlock audio. A one-shot requested
before activation is dropped; a retained playing effect waits for activation.
Browser audio and the first gesture
has the full rule.
What is checked
Section titled “What is checked”The opt-in tools/consumer_check/wav_fixture.py reads this page’s four C++
paste blocks and applies them to an assembled development starter. It also
copies the original WAV, adds the manifest/build changes and an extra
MyGameWaveTests executable checking loaded content and named refusal of
missing or malformed required WAVs. The default starter keeps its ordinary
two-test shape. The fixture’s browser route uses trusted
Space,Escape,Enter keys and still requires the game’s real quit callback.
The fixture prepares source; a successful preparation is not a build or playback result. Run the commands in the consumer-check README and retain the actual native/browser results when qualifying a revision. Listening and physical output acceptance remain separate from automated loading and playback-state checks.
Where to go next
Section titled “Where to go next”- Audio covers sound groups, levels, retained voices, bank memory and browser activation.
- Play sounds from an XWB bank preserves multi-wave bank authoring and the released starter’s route.
- Settings and saves uses the
tonesXWB bank; follow the bank walkthrough when continuing that example.
Development documentation (unreleased). Built from Labrador aceb130 of 2026-11-20.