Skip to content

Sound API

This module contains methods relative to the extended sound system. The Sound API is used by mods when an avatar has custom sound events, separate from the included events.

This API allows the modder to tell the system to fire those sound events, from which the internal systems will collect and play the sounds just like it would with a vanilla event. The modder does not necessarily need to worry about choosing the sounds (however, this can be done via a custom selector, see the bottom of this page).

Modders will be provided with the list of created GameObjects storing the sound(s) that got played.

Fields

static readonly AudioSelectionDelegate PLAYTYPE_DEFAULT_RANDOM;

This delegate is the default for the "Random" sound technique.

static readonly AudioSelectionDelegate PLAYTYPE_DEFAULT_ALL;

This delegate is the default for the "Play All At Once" sound technique.

Methods

static IList<GameObject> BroadcastSoundEvent(string name, params SLZ.VRMK.Avatar[] toAvatars)

Exceptions...

  • ArgumentNullException - If the name is null or whitespace.
  • ArgumentOutOfRangeException - Argument must be all lowercase, and cannot contain semicolons (;)

Modders can invoke this method to fire a custom event type. It is also possible to fire vanilla events by inputting their event name, but this is not recommended.

If defined, and with at least one non-null entry, the toAvatars parameter determines which avatar receives the event (or, who plays the sound). If undefined, all avatars in the scene, namely including other players if Fusion is active, will play the sound iff that avatar has that sound event in its extended audio container. If the avatar has no container, or does not have this event in its container, it will do nothing.

The function returns a list of every GameObject created to store the played sounds (each sound creates a new object so that it can be driven by its settings). The modder is free to use these as needed (such as by destroying them to stop a sound).

static void RegisterSoundPlayTypeSelectionHandler(string playType, AudioSelectionDelegate @delegate)

Exceptions...

  • ArgumentNullException - If the play type is null, or the delegate is null.
  • InvalidOperationException - If the provided play type has already been registered before.

Use this to register a Custom Sound Technique to the system. When an event fires on a sound group with the provided playType, the provided @delegate will be executed to collect what sounds need to be played, and with what pitches/volumes.

Delegate Types

delegate PlayableSoundData[] AudioSelectionDelegate(SLZ.VRMK.Avatar avatar, string playType, AudioEventType vanillaEvent, string? customEvent, ReadOnlyAudioEntry triggeredGroup);

This delegate executes for a given named Sound Play Technique and returns zero or more sounds for the system to play. Sounds can be collected from the provided triggeredGroup.

This also provides context as to the avatar it is being executed for, and what event (vanilla or custom, but never both at once) it is reacting to.

Types

struct PlayableSoundData

float volume;

The sound will play with this volume.

float pitch;

The sound will play with this pitch.

AudioClip sound;

The actual sound that will be played. This can be any sound; it does not need to be one from the group.

SoundFlags playTechnique;

These flags dictate how the sound behaves in realtime while playing. The default value makes it follow the object it played on, and change pitch in realtime with slow motion.

AudioMixerGroup mixer;

The audio mixer to play on. Defaults to the SFX mixer if null.