Skip to content

Avatar Extended Audio Container

Immutable during runtime!

Mods can not (and should not try to) change sound data stored in one of these components while the game is running. It is optimized for caching for performance reasons.

If you aren't a modder, don't worry about this, it doesn't apply to you. In contrast, if you are a modder, and want to add sounds during runtime for whatever reason, please utilize SoundAPI.

This component contains additional avatar sound effects that can be executed manually or automatically.

Looking at the menu will reveal a number of options that you can customize.

Concept

Menu Might Be Buggy

The menu often spits out warnings about long compute time when resizing. These can be ignored, but may be somewhat inconvenient. There may be other undiagnosed/unfixed issues, because this is still a test.

The component contains one or more sound groups. Sound groups contain basic information on how to play the sound, when it should play, and what sounds are available.

Sound Event Triggers

Sound Event Triggers are named events that the mod will broadcast out. The dropdown allows you to choose which events you want it to react to. All sounds that you can choose are listed with their raw event name i.e. Projectile Damage (hitbullet) - hitbullet is the event name, and as its name implies, this event occurs when you get hit by a bullet.

The component listens to these broadcasts, and if it finds one or more sound groups that receive that event, it will play the sound(s) in the matching group.

Additionally, you can type in custom event names by selecting "Nothing". Erase all of the text in the box and press the Enter key (or click off of the text box) to reset it back to the dropdown menu.

Custom Events

Custom events must be sent by mods

This is kind of a given, but to be punctual, any custom events that you type in won't be sent by this system. It is up to a mod (be it yours or someone else's) to trigger those events. Of course, included events (i.e. hitbullet) are always transmitted.

Naming

Names must follow a certain regex pattern

Names must satisfy this regex pattern: [a-z0-9_\-\.]+(?:(?:\:)[a-z0-9_\-\.]+)? and must be no longer than 50 characters - Some examples are as follows:

  • my_sound-1.a - OK. Lowercase letters, numbers, underscore, minus, and dot are all allowed.
  • mynamespace:mysound - OK. You can create fake namespaces with a colon (:)
  • MySound - Not OK, events must be all lowercase.
  • mynamespace:abc:mysound - Not OK. Only one namespace is allowed.
  • :mysound - Not OK. The namespace separator (:) can only be used between two names.
  • mysound: - See above.

To include multiple sounds in the list, separate entries with a semicolon ;. You can combine vanilla events with custom ones, like hitbullet;otherevent;anotherevent. If you input an incorrect entry, it will be removed (but correct ones will be kept).

It is strongly recommended that you provide a namespace to your private/personal event names. An example of this might be chimera:critdamage. If you have ever seen a resource location in minecraft, it works a bit like that.

Broadcasting

You can use SoundAPI to broadcast sound events yourself.

Technique to Play Sound

Usability Notice

While this is made primarily for the purpose of choosing the sounds that are played, you can also use this for any additional logic related to specific sound events.

In general, if an event is bound to something happening in the game and you need custom logic that demands more information than what the audio callback has to offer, you should be doing that logic before requesting the sound is played. The method to broadcast a sound event returns the objects for all sounds that got played.

The technique to play a sound determines how (and which) sounds get chosen and played. Your options are:

  • Random - Choose one sound out of the list at random.
  • Play All At Once - Play each and every sound out of the list at the same time.
  • Custom - Advanced, see below. Enter a custom name. Your mod must register this name.

If you need special or unique behavior, you can choose Custom. This should be a unique name of your choosing, so long as it is not all whitespace or empty.

Using this requires registering it into the SoundAPI - this is why you want a unique name, so that other mods don't accidentally clash with yours. More information what is possible can be found on the page.

Properties

Sound Name

The name of the sound group. This is suggested for organizational purposes, as well as debugging (if something errors, it will use this name to report which group failed).

Sound Effects

A list of sounds contained within this group. You can drag and drop multiple sounds onto this area and it will add all of them.

Pitch Variation

This slider has a minimum and maximum that you can choose. When sounds play, their pitch will be randomized within this range.

Volume

The volume that sounds are created at. It is recommended to make your audio files at full volume (the wave should touch the top and bottom, if you look at it in Audacity or something similar) and then center this value somewhere around 0.5.

Play Type

When playing the sound, the system can drive this sound. It includes four types that you can combine:

  • Nothing - The sound gets played. That's it. Nothing special.
  • Follow Emitter - Every Update() that the sound is playing, it will be moved to the transform it plays on. By default, this is the avatar's chest.
  • Timescaled Pitch (On Spawn) - When the sound is playing, its pitch is multiplied by the game's timescale, for slow motion sound effects. This is BONELAB's default behavior for most SFX.
  • Timescaled Pitch (Real Time) - When set, On Spawn (above) will be set as well. If this is true, the sound's pitch will also change in realtime every Update() call.

Mixer Group

The target mixer group that should control this sound's volume.

  • Master - The master volume mixer, controlled by the "Master" option in the audio settings of the game.
  • Gunshot - A subgroup of the SFX mixer intended for, as the name implies, gunshot sounds.
  • Music - The music mixer, controlled by the "Music" option in the audio settings of the game.
  • Other SFX - The SFX mixer, controlled by the "Effects" option in the audio settings of the game.

Template Audio Source Prefab

Prefabs Only!

You MUST create a Prefab for your Audio Source. See the Unity Manual for more information on how to create prefabs.

This object provides a template audio source that is cloned to play your sound effect(s). You can use it to set up your own maximum distance and audio curves for sounds in this group, among other settings. While all properties are supported where possible, some are not (namely, the mixer is ignored due to the property above overriding it).

If this is set to nothing, a default exists in the mod's code that will be used, which is identical to the default of Nearby Spatial Source. Note that modifying the presets of the SDK won't work. If you want to edit the provided ones, you'll first have to copy it into a new object, and then make your own prefab with a different name than the ones listed below.

Built in option: Global Source

This audio source plays globally, it has no location in 3D space and plays the same everywhere.

Built in option: Nearby Spatial Source

This is an all-around decent source for most sounds. It was made for suit voiceovers for my Chimera ECLIPSE avatar. Near the emitter's location, it plays in 2D, but as you get further away, it switches into a 3D (positioned) audio source and is affected by environmental factors like reverb.

This type is optimal for sound effects that need to be 2D to the avatar listener, and 3D to any other people that are around you in Fusion (multiplayer) environments.