Scripting API

Scripting API

AudioMix

Class in Abyss.Core, from Abyss.Core.

A game's mix: its buses, as the Audio tab lays them out — settings/audio.json beside the game's assets.

public sealed class AudioMix

Remarks

Master first, sending to the speakers; every other bus sends to Master or to a bus before it, so a sound played on one is mixed through it, through each it sends to, and through Master. A bus is known by an identity the editor gives it, which an Audio Source's Output keeps and which stays with it as it is renamed; a game's code names a bus by its name (PlayOptions.Bus, WorldAudio.SetBusVolume).

A game with no audio.json has Master alone. The engine checks a mix as this does, so one this reads is one it plays (abyss_core::audio::bus).

An identity is never given twice: the file keeps the next one to give, so a bus added after one was taken away is not the bus an Audio Source that played on the old one names. That source plays on Master, as a sound on a bus the mix has not does.

Constructors

AudioMix

public AudioMix()

Master alone, at zero decibels: the mix of a game that has said nothing of one.

Properties

Buses

public IReadOnlyList<AudioBus> Buses { get; }

Its buses, in their order, Master first.

Methods

FileIn

public static string FileIn(string game)

Where a game keeps it: settings/audio.json in its folder.

Parameters

  • game

Read

public static AudioMix Read(string game)

A game's mix; Master alone for one with no audio.json.

Parameters

  • game

Exceptions

  • FormatException: The file is not a mix this build reads, saying why.
  • IOException: The file is there and cannot be read.

Parse

public static AudioMix Parse(string json)

A mix from its text.

Parameters

  • json

Exceptions

  • FormatException: It is not a mix this build reads, saying why.

ToJson

public string ToJson()

The mix as its file holds it, which the engine reads as it is: what each bus says that a bus does not start with.

Write

public void Write(string game)

Writes the mix into a game's folder.

Parameters

  • game

Copy

public AudioMix Copy()

A copy, to change without changing this.

Find

public AudioBus? Find(ulong id)

The bus of identity id, or null.

Parameters

  • id

Named

public AudioBus? Named(string name)

The bus called name, or null; names are matched as they are written.

Parameters

  • name

Add

public AudioBus Add()

Adds a bus after the others, sending to Master: AudioMix.NewBusName, or that and the first number after it no bus is called, under an identity no bus of the mix has had.

Returns The bus added.

Remove

public bool Remove(ulong id)

Takes a bus away — never Master — each bus that sent to it sending to Master.

Parameters

  • id

Returns Whether there was such a bus to take away.

Rename

public string? Rename(ulong id, string name)

Calls a bus name, trimmed, and the first number after it no other bus is called where one is called that; a name of nothing but spaces leaves it as it was, and so does Master's, which is always Master.

Parameters

  • id
  • name

Returns What it is called now.

SetVolume

public void SetVolume(ulong id, float volume)

Turns a bus's fader to volume decibels, held between the least and the most it goes; a volume that is no number is the least.

Parameters

  • id
  • volume

SetMute

public void SetMute(ulong id, bool mute)

Mutes a bus, or lifts its mute.

Parameters

  • id
  • mute

SetSolo

public void SetSolo(ulong id, bool solo)

Solos a bus, or lifts its solo.

Parameters

  • id
  • solo

SetSend

public bool SetSend(ulong id, ulong send)

Has a bus send to send, which must be one before it.

Parameters

  • id
  • send

Returns Whether it could: a bus that is not Master, sending to one before it.

SendsFor

public IEnumerable<AudioBus> SendsFor(ulong id)

The buses a bus may send to: every one before it, Master first; none for Master.

Parameters

  • id

SetBypass

public void SetBypass(ulong id, bool bypass)

Bypasses a bus's effects, each turned dry, or lifts it.

Parameters

  • id
  • bypass

SetFollowsTimeScale

public void SetFollowsTimeScale(ulong id, bool follows)

Makes a bus's sounds, and those of the buses that send to it, follow the game's time scale, or play at their own speed.

Parameters

  • id
  • follows

FollowsTimeScaleThrough

public AudioBus? FollowsTimeScaleThrough(ulong id)

The bus a sound on bus id follows the game's time scale through: the bus itself where it says so, or the nearest it sends to on its way to the speakers that does; null where none does, and for a bus there is not.

Parameters

  • id

AddEffect

public int AddEffect(ulong id, BusEffectKind kind)

Adds an effect of kind at the bottom of a bus's list, every setting where it starts.

Parameters

  • id
  • kind

Returns Where it is in the list, or -1 for a bus there is not.

RemoveEffect

public bool RemoveEffect(ulong id, int index)

Takes a bus's effect index away.

Parameters

  • id
  • index

Returns Whether there was one.

MoveEffect

public bool MoveEffect(ulong id, int from, int to)

Moves a bus's effect from from to to, the others making room.

Parameters

  • id
  • from
  • to

Returns Whether both places are in its list and differ.

SetEffectOn

public bool SetEffectOn(ulong id, int index, bool on)

Ticks a bus's effect index on, or off, turning it dry.

Parameters

  • id
  • index
  • on

Returns Whether there was one.

SetEffectValue

public bool SetEffectValue(ulong id, int index, BusEffectValue value, float amount)

Changes a setting of a bus's effect index, kept to its range.

Parameters

  • id
  • index
  • value
  • amount

Returns Whether there was one with that setting, and the amount was a number.

ResetEffect

public bool ResetEffect(ulong id, int index)

Puts every setting of a bus's effect index back where a new one starts, keeping it on or off.

Parameters

  • id
  • index

Returns Whether there was one.

Constants

FileName

public const string FileName = "audio.json"

The file, under the game's settings folder.

PathName

public const string PathName = "settings/audio.json"

What it is called in a game's folder and in its pack: settings/audio.json.

CurrentVersion

public const int CurrentVersion = 2

The version of the file this build writes, and the newest it reads: 2 since a bus has effects.

Master

public const ulong Master = 0

Master's identity.

LeastVolume

public const float LeastVolume = -80

The quietest a fader goes, in decibels.

MostVolume

public const float MostVolume = 6

The loudest a fader goes, in decibels.

NewBusName

public const string NewBusName = "New Bus"

What a bus added is called, a number after it where that is taken.