Scripting API
Scripting API
WorldAudio
Struct in Abyss.Core, from Abyss.Core.
Sound, as a game plays it from its code: a clip played as a 2D sound, at a place in the world, or on an entity, and each sound asked to stop, pause, resume or change. What World.Audio gives.
public readonly struct WorldAudioRemarks
A sound is asked for, and given its Sound at once. It starts at the next frame its clip has landed by, so one asked for while its clip loads starts once it has; a sound asked for in the same frame as another starts with it.
A 3D sound pans by which side of the listener it is on and falls off with its distance from it, by PlayOptions.Rolloff between PlayOptions.MinDistance and PlayOptions.MaxDistance, as much as PlayOptions.SpatialBlend says. Sound is heard from the first entity with an AudioListener, and where none has one, from the game's first camera.
An entity's AudioSource plays its clip as it says, on the entity, when play starts if it plays on awake, and whenever WorldAudio.Play asks; its sound follows what it says as that changes.
Every sound plays on a bus of the game's mix — Master, or the one its options or its Audio Source's Output name — which the Audio tab lays out (AudioMix). A game's code turns a bus and mutes it by its name until play ends, when the mix is the project's again.
In the editor, a game's sounds are paused while its play is paused, and stopped when it stops.
Constructors
WorldAudio
public WorldAudio(World world)Sound, as a game plays it from its code: a clip played as a 2D sound, at a place in the world, or on an entity, and each sound asked to stop, pause, resume or change. What World.Audio gives.
Parameters
world: The world it plays in.
A sound is asked for, and given its Sound at once. It starts at the next frame its clip has landed by, so one asked for while its clip loads starts once it has; a sound asked for in the same frame as another starts with it.
A 3D sound pans by which side of the listener it is on and falls off with its distance from it, by PlayOptions.Rolloff between PlayOptions.MinDistance and PlayOptions.MaxDistance, as much as PlayOptions.SpatialBlend says. Sound is heard from the first entity with an AudioListener, and where none has one, from the game's first camera.
An entity's AudioSource plays its clip as it says, on the entity, when play starts if it plays on awake, and whenever WorldAudio.Play asks; its sound follows what it says as that changes.
Every sound plays on a bus of the game's mix — Master, or the one its options or its Audio Source's Output name — which the Audio tab lays out (AudioMix). A game's code turns a bus and mutes it by its name until play ends, when the mix is the project's again.
In the editor, a game's sounds are paused while its play is paused, and stopped when it stops.
Properties
IsMuted
public bool IsMuted { get; }Whether every sound the game plays is muted; see WorldAudio.SetMuted. Never in a world with no sound.
Methods
Play
public Sound Play(AudioClipId clip, PlayOptions? options = null)Plays a clip as a 2D sound, heard the same wherever the listener is.
Parameters
clipoptions
Exceptions
AbyssException: The id names no clip, or the world has no sound.
PlayAt
public Sound PlayAt(AudioClipId clip, Vector3 position, PlayOptions? options = null)Plays a clip at a point in the world.
Parameters
clippositionoptions
Exceptions
AbyssException: The id names no clip, or the world has no sound.
PlayOn
public Sound PlayOn(ulong entity, AudioClipId clip, PlayOptions? options = null)Plays a clip on an entity, following it as it moves and stopping if it goes.
Parameters
entityclipoptions
Exceptions
AbyssException: The id names no clip, the entity does not exist, or the world has no sound.
Play
public Sound Play(ulong entity)Plays the AudioSource on an entity, as it says, stopping what it played before; the sound it will be, which WorldAudio.SoundOf gives too.
Parameters
entity
Exceptions
AbyssException: The id packs no entity, or the world has no sound.
SoundOf
public Sound SoundOf(ulong entity)The sound the AudioSource on an entity plays, or played last; none for one that has played none.
Parameters
entity
Exceptions
AbyssException: The id packs no entity.
SetMuted
public void SetMuted(bool muted)Mutes every sound the game plays, which go on silent, or lifts the mute: the editor's Mute Audio.
Parameters
muted
HasBus
public bool HasBus(string name)Whether the game's mix has a bus called name, as it is written.
Parameters
name
SetBusVolume
public void SetBusVolume(string bus, float decibels)Turns the bus called bus to decibels, held from -80 to +6 so minus infinity silences it, until play ends; a bus the mix has not is said in the log, and a volume that is no number changes nothing.
Parameters
busdecibels
SetBusVolumeLinear
public void SetBusVolumeLinear(string bus, float linear)Turns the bus called bus to linear, a share of the whole from 0, silent, to 1, its fader at zero decibels, until play ends: what a settings menu's slider gives; see Decibels.FromLinear.
Parameters
buslinear
SetBusMute
public void SetBusMute(string bus, bool muted)Mutes the bus called bus, or lifts its mute, until play ends; a bus the mix has not is said in the log.
Parameters
busmuted
SetBusBypass
public void SetBusBypass(string bus, bool bypassed)Bypasses the effects of the bus called bus, each turned dry, or lifts it, until play ends: what its B button does. A bus the mix has not is said in the log.
Parameters
busbypassed
SetBusEffectEnabled
public void SetBusEffectEnabled(string bus, int index, bool on)Ticks the effect index of the bus called bus on or off, the top one 0, until play ends; one off is turned dry. A bus or an effect there is not is said in the log.
Parameters
busindexon
SetBusEffect
public void SetBusEffect(string bus, int index, BusEffectValue value, float amount, float fade = 0)Turns the setting value of the effect index of the bus called bus, the top one 0, to amount, in the setting's own unit and kept to its range, over fade seconds, until play ends: a Low Pass's cutoff lowered as the camera goes under water.
Parameters
busindexvalueamountfade
A bus or an effect there is not, a setting its kind has not, and a Delay's BusEffectValue.Time, which is set as the bus's tracks are made, change nothing, and the log says so.
BusLevels
public IReadOnlyList<BusLevel> BusLevels()How loud each bus has been since this was last asked, in the mix's order: the loudest sample of each channel as it leaves its fader. Empty in a world with no sound.
Stop
public void Stop(Sound sound, float fadeOut = 0)Stops a sound, fading it out over fadeOut seconds. One that is over is asked nothing.
Parameters
soundfadeOut
Pause
public void Pause(Sound sound, float fadeOut = 0)Pauses a sound, fading it out over fadeOut seconds.
Parameters
soundfadeOut
Resume
public void Resume(Sound sound, float fadeIn = 0)Resumes a paused sound, fading it in over fadeIn seconds.
Parameters
soundfadeIn
SetVolume
public void SetVolume(Sound sound, float volume, float fade = 0)Makes a sound this loud, from 0 to 1, over fade seconds.
Parameters
soundvolumefade
SetPitch
public void SetPitch(Sound sound, float pitch, float fade = 0)Makes a sound this fast and high, 1 as its clip is, over fade seconds.
Parameters
soundpitchfade
SetLooping
public void SetLooping(Sound sound, bool looping)Has a sound loop from now on, or end where its clip does.
Parameters
soundlooping
PositionOf
public double PositionOf(Sound sound)How many seconds into its clip a sound is, playing or paused; zero for one that has not started or is over.
Parameters
sound
StateOf
public SoundState StateOf(Sound sound)How far along a sound is.
Parameters
sound
IsPlaying
public bool IsPlaying(Sound sound)Whether a sound is playing, or waiting for its clip to start.
Parameters
sound
