Playing Audio

Sometimes, you want to play sound effects and music inside the game. Here's how.

Adding audio files to the game

If you're contributing to the base game, you can add audio files to the game by placing them anywhere in the Content folder inside the SociallyDistant project. At this time, only WAV files with a sample rate at or below 48000Hz are supported.

Make sure to keep things organized, and to name the audio file something concise and descriptive. For example, for a Hollywood-style data reading sound effect, you could place it in Content/Audio/SFX/DataRead.wav.

Where to place audio files

Audio files should be placed under the Content/Audio directory. Sound effects should be placed under the SFX sub-folder, and songs under the BGM folder.

Dealing with licensed sound effects

Do not commit licensed sound effects or other licensed assets to a public branch or repo. Doing so is subject to deletion from this GitLab instance without warning, as distributing source assets is generally against most audio and music licenses.

Instead, you should keep these assets in a separate, private repository similar to how Career Mode is maintained. Inside that private repo, you should create a dedicated branch to store licensed assets in. We will not accept merge requests from branches containing licensed assets.

Playing Music

Now for the actually fun part. If you've added a song to the game, or have an existing song you want the game to play, here's how.

Using Event Bus

You can post a PlaySongEvent to the game's Event Bus. The PlaySongEvent accepts a resource path and an optional boolean indicating whether the song should loop. Songs loop by default.

EventBus.Post(new PlaySongEvent("/Core/Career/Audio/BGM/PsyOp"));

When specifying the resource path, do not include the file extension of the audio file.

Using sdsh scripts

Use the bgm command, specifying the same style of resource path as above. This command only works in mission scripts.

bgm /Core/Career/Audio/BGM/PsyOp

Using the bgm command changes the default background music of the game, meaning that the same song will play when the current user logs back in.

By modifying Protected World State

If you are contributing directly to the SociallyDistant project, you can modify the DefaultBackgroundMusicPath value in the world's protected state. This cannot be done in mods. This is what the bgm command does behind the scenes.

Playing Sounds

You will more than likely want to play sound effects rather than music. There are two ways to play sound effects.

Using the Event Bus

You can post a PlaySoundEvent to the Event Bus to play sound effects. Like PlaySongEvent, the PlaySoundEvent constructor accepts a resource path.

EventBus.Post(new PlaySoundEvent("/Core/Audio/SFX/DataRead"));

Using the SoundScheme API

Most common interface sounds can be played by using the SoundScheme.PlayGuiSound(GuiSoundName) static method. You should prefer this over PlaySoundEvent when playing common interface sounds, since the resource paths are managed by the game itself. This also allows the player to change the sound scheme.

SoundScheme.PlayGuiSound(GuiSoundName.Bell);

Missing audio files don't crash the game

Attempting to play a missing song or sound effect will not cause any kind of error. This is by design, allowing the game code to request to play licensed sounds without the assets actually being present.

If you attempt to play a missing sound or one that can't load, the game will log a warning and simply play nothing.