Skip to content

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:

Terminal window
cd /d C:\dev\mygame

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.

  1. Copy the beep. It is generated PCM audio supplied with the engine, under the engine’s MIT licence:

    Terminal window
    mkdir game\content\waves
    copy external\labrador\samples\audio\source\ping.wav game\content\waves\ping_wav.wav

    copy ends with 1 file(s) copied. If mkdir says the folder already exists, continue. If copy cannot find the source, check that the prompt is in C:\dev\mygame and that the full engine is still in external\labrador. source\ping.wav is the original WAV, not the packed tones.xwb beside the audio sample’s manifest.

  2. List it in the game’s manifest. Open:

    Terminal window
    notepad game\content\manifest.json

    In an unchanged starter, replace its contents with this version. If your manifest already has other groups, keep them and add the wave group at the end of the assets list, 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 neither ping_wav.json nor an .xwb file. 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.

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:

Terminal window
notepad game\CMakeLists.txt
  1. 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.

  2. 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_BUILD
    COMMAND "${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.

  3. Put the WAV in a Windows release. Search for install(DIRECTORY content/fonts and add a line after it:

    install(DIRECTORY content/fonts DESTINATION .)
    install(DIRECTORY content/waves DESTINATION .)

    Save and close Notepad. The browser branch already embeds content at /, so it needs no second embed option.

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.

  1. Add the sound-bank header. Open:

    Terminal window
    notepad game\states\hello_state.h

    Search for #include "engine/app/application.h" and add this line below it:

    Add the sound-bank include
    #include "engine/audio/sound_bank.h"
  2. 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.
    labrador::SoundBank* ping_wav_bank_ = nullptr;

    Save and close the header.

  3. Resolve the two names once. Open:

    Terminal window
    notepad game\states\hello_state.cpp

    Search for RenderResources* resources =. The starter’s line is:

    samples/minimal/states/hello_state.cpp
    RenderResources* resources = this->app_->render_resources();

    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_wav for a direct WAV asset. A spelling mistake fails here at startup, rather than becoming a key that silently does nothing.

  4. Play on the pressed edge. Search for const Keyboard& keyboard = *this->app_->keyboard(); and add this block immediately after it:

    Play once on Space
    if (keyboard.pressed(Key::space))
    {
    this->ping_wav_bank_->play_wave(this->ping_wav_, 0.4f);
    }

    Save and close the file. pressed is 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.4f is 40% volume. Do not play sound from draw().

Quit a running copy before building. In the same prompt:

Terminal window
cmake --build --preset x64-debug && ctest --preset x64-debug && out\build\x64-debug\game\MyGame.exe

The 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.

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:

Terminal window
copy /y "%USERPROFILE%\Downloads\my sound.wav" game\content\waves\ping_wav.wav
cmake --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 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.

  • The startup message says kind wave was not registered. Check the development-version notice at the top. A v0.3.0 engine cannot load this new asset kind. The retained XWB guide works with that release.
  • The message names a missing ping_wav.wav. Check game\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 in init against the manifest and filename. Preserve the wave group 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.

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.

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.

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.

  • 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 tones XWB bank; follow the bank walkthrough when continuing that example.

Development documentation (unreleased). Built from Labrador aceb130 of 2026-11-20.

All documentation versions