Files
aego/modules/audio/script.go
T
sanspie 50be5c04bc
ci-platforms / darwin amd64 smoke (push) Skipped
GitHub / linux amd64 native GitHub-hosted native CI: success
ci-platforms / windows amd64 smoke (push) Skipped
GitHub / windows amd64 native GitHub-hosted native CI: success
GitHub / darwin arm64 native GitHub-hosted native CI: success
GitHub / darwin amd64 native GitHub-hosted native CI: success
ci / checks (push) Failing after 1h21m34s
ci / native-authoring (push) Skipped
ci-platforms / darwin arm64 smoke (push) Skipped
github-native / gitea-pending (push) Skipped
github-native / darwin amd64 native (push) Skipped
github-native / linux amd64 native (push) Skipped
github-native / windows amd64 native (push) Skipped
github-native / darwin arm64 native (push) Skipped
github-native / gitea-result (push) Skipped
ci / build (amd64, linux, ubuntu-24.04) (push) Successful in 12m4s
ci / release (push) Skipped
Stage 12.5: Art Workspace and asset authoring
Add dockable Art tools, animation and previews, guarded asset workflows,
and the Web Asset Studio built on the shared Art Core. Expand English and
Russian documentation, interactive Try scenes, examples and editor icons.

Add audio waveform navigation, source analysis, guarded previews and a
browser Worker mixer. Preserve source changes and recovery with bounded
checks, and strengthen native, browser and interoperability CI.

Prepare version 0.12.5 and manually built native artifact candidates.
Fix the production site image demo build dependency.
Reuse immutable scene indices when capturing keyframes.
Wait for real Persist save/load completion in component tests.
Stabilize browser Game View captures outside pointer hover.
Aseprite interchange and persistent Audio EDL recovery remain limited;
the artifact workflow does not publish releases or change stable.
2026-11-15 10:37:50 +03:00

167 lines
7.7 KiB
Go

package audio
import (
"aego/asset"
"aego/core/mathx"
"aego/data"
"aego/script/abi"
"aego/script/bind"
)
func live(c *bind.Ctx) *Service {
if c.World == nil {
return nil
}
return Of(c.World)
}
func need(c *bind.Ctx) *Service {
s := live(c)
if s == nil {
c.Fail("audio plays only during Play")
}
return s
}
func installScript(m *bind.Module, mod *Module) {
bind.Enum[Bus](m, "Bus", bind.Member("Master", BusMaster), bind.Member("Music", BusMusic), bind.Member("Sfx", BusSfx),
bind.Member("UI", BusUI), bind.Member("Ambience", BusAmbience), bind.Member("Voice", BusVoice))
bind.Enum[Steal](m, "Steal", bind.Member("Oldest", StealOldest), bind.Member("Quietest", StealQuietest), bind.Member("None", StealNone))
bind.Enum[PauseWith](m, "PauseWith", bind.Member("Game", PauseGame), bind.Member("Never", PauseNever))
bind.Describe(m, "Bus", bind.Doc("Bus is a mixer bus: Master, Music, Sfx, UI, Ambience or Voice."))
bind.Describe(m, "Steal", bind.Doc("Steal is what an audio event does at Max Voices: stop the oldest voice, stop the quietest, or skip the new play."))
bind.Describe(m, "PauseWith", bind.Doc("PauseWith decides whether a sound pauses with the game or keeps playing."))
bind.Struct[Options](m, "PlayOptions", bind.Doc("PlayOptions tune one play. Volume and Pitch 0 mean 1; Bus Master plays on the bus of the clip; Unscaled keeps playing while the game is paused."))
bind.Handle(m, "Sound", true, soundOf, Sound.key,
bind.Doc("Sound is a playing sound. yield s waits until it ends; a nil or finished sound is done. It is a presentation event: wait for game logic with a timer, not a sound."))
bind.Func1(m, "Play", func(c *bind.Ctx, clip ClipRef) Sound {
if s := need(c); s != nil {
return s.Play(clip.ID, Options{}, c.Node)
}
return 0
}, bind.Doc("Play plays a clip on its bus. The sound stops when the node of the script is destroyed."), bind.Params("clip"), bind.Example("audio.Play(Coin)"))
bind.Func2(m, "PlayWith", func(c *bind.Ctx, clip ClipRef, o Options) Sound {
if s := need(c); s != nil {
return s.Play(clip.ID, o, c.Node)
}
return 0
}, bind.Doc("PlayWith plays a clip with options."), bind.Params("clip", "options"),
bind.Example("audio.PlayWith(Step, audio.PlayOptions{Volume: 0.5, Pitch: 1.1})"))
bind.Func2(m, "PlayAt", func(c *bind.Ctx, clip ClipRef, p mathx.Vec2) Sound {
if s := need(c); s != nil {
return s.PlayAt(clip.ID, p, Options{}, c.Node)
}
return 0
}, bind.Doc("PlayAt plays a clip at a world position, fading and panning with the distance to the listener."), bind.Params("clip", "position"))
bind.Func1(m, "PlayEvent", func(c *bind.Ctx, ev data.Ref[Event]) Sound {
if s := need(c); s != nil {
return s.PlayEvent(ev.ID, c.Node)
}
return 0
}, bind.Doc("PlayEvent plays an audio event; a spatial event follows the node of the script."), bind.Params("event"), bind.Example("audio.PlayEvent(Jump)"))
bind.Func2(m, "PlayEventAt", func(c *bind.Ctx, ev data.Ref[Event], p mathx.Vec2) Sound {
if s := need(c); s != nil {
return s.PlayEventAt(ev.ID, p, c.Node)
}
return 0
}, bind.Doc("PlayEventAt plays an audio event at a world position."), bind.Params("event", "position"))
bind.Func2(m, "Music", func(c *bind.Ctx, clip ClipRef, fade float32) Sound {
if s := need(c); s != nil {
return s.Music(clip.ID, fade)
}
return 0
}, bind.Doc("Music loops a clip on the music bus, crossfading from the music that played over seconds."), bind.Params("clip", "seconds"),
bind.Example("audio.Music(Theme, 1.5)"))
bind.Proc1(m, "StopMusic", func(c *bind.Ctx, fade float32) {
if s := live(c); s != nil {
s.StopMusic(fade)
}
}, bind.Doc("StopMusic fades the music out over seconds."), bind.Params("seconds"))
bind.Func1(m, "BusVolume", func(c *bind.Ctx, b Bus) float32 {
return mod.BusVolume(b)
}, bind.Doc("BusVolume returns the session volume of a bus set by SetBusVolume; the player's settings are separate."), bind.Params("bus"))
bind.Proc2(m, "SetBusVolume", func(c *bind.Ctx, b Bus, v float32) {
mod.SetBusVolume(b, v)
}, bind.Doc("SetBusVolume sets the session volume of a bus, on top of the player's settings; it is not saved."), bind.Params("bus", "volume"))
bind.Proc2(m, "Mute", func(c *bind.Ctx, b Bus, on bool) {
mod.SetBusMuted(b, on)
}, bind.Doc("Mute silences a bus for this session."), bind.Params("bus", "on"))
bind.Func1(m, "Builtin", func(c *bind.Ctx, name string) ClipRef {
id, ok := asset.BuiltinAudioNamed(name)
if !ok {
c.Fail("audio: there is no built-in clip " + name + "; the built-in clips are Beep, Click, Hum and Melody")
return ClipRef{}
}
return ClipRef{ID: id}
}, bind.Doc("Builtin returns a clip that ships with the engine: Beep, Click, Hum (loopable) or Melody (loopable)."),
bind.Params("name"), bind.Example(`audio.Play(audio.Builtin("Beep"))`))
bind.Func0(m, "ListenerPosition", func(c *bind.Ctx) mathx.Vec2 {
if s := live(c); s != nil {
return s.Listener()
}
return mathx.Vec2{}
}, bind.Doc("ListenerPosition returns the last effective listener position in world space, or zero outside Play. It includes the camera fallback when no listener is active."))
bind.Func1(m, "WorldBusGain", func(c *bind.Ctx, bus Bus) float32 {
return live(c).WorldBusGain(bus)
}, bind.Doc("WorldBusGain returns the last zone-selected world-layer target for a bus, or 1 outside Play. It is not the ramped mixer output or the player's settings."), bind.Params("bus"))
bind.Proc1(m, "Pause", func(c *bind.Ctx, on bool) {
if s := live(c); s != nil {
s.PauseAll(on)
}
}, bind.Doc("Pause pauses or resumes every sound of this world."), bind.Params("on"))
hm := m.Registry().HandleMethods(KindSound)
bind.Func1(hm, "Done", func(c *bind.Ctx, h Sound) bool {
s := live(c)
return s == nil || s.Done(h)
}, bind.Doc("Done reports whether the sound ended, was stopped or is nil."))
bind.Func1(hm, "Playing", func(c *bind.Ctx, h Sound) bool {
s := live(c)
return s != nil && s.Playing(h)
}, bind.Doc("Playing reports whether the sound is audible now: not done, not stopping and not paused."))
bind.Proc1(hm, "Stop", func(c *bind.Ctx, h Sound) {
if s := live(c); s != nil {
s.Stop(h, 0)
}
}, bind.Doc("Stop ends the sound with a short fade."))
bind.Proc2(hm, "StopFade", func(c *bind.Ctx, h Sound, sec float32) {
if s := live(c); s != nil {
s.Stop(h, sec)
}
}, bind.Doc("StopFade fades the sound out over seconds."), bind.Params("seconds"))
bind.Proc1(hm, "Pause", func(c *bind.Ctx, h Sound) {
if s := live(c); s != nil {
s.Pause(h, true)
}
}, bind.Doc("Pause holds the sound where it is."))
bind.Proc1(hm, "Resume", func(c *bind.Ctx, h Sound) {
if s := live(c); s != nil {
s.Pause(h, false)
}
}, bind.Doc("Resume continues a paused sound."))
bind.Proc2(hm, "SetVolume", func(c *bind.Ctx, h Sound, v float32) {
if s := live(c); s != nil {
s.SetVolume(h, v)
}
}, bind.Doc("SetVolume changes the volume with a short ramp."), bind.Params("volume"))
bind.Proc2(hm, "SetPitch", func(c *bind.Ctx, h Sound, p float32) {
if s := live(c); s != nil {
s.SetPitch(h, p)
}
}, bind.Doc("SetPitch changes speed and pitch, 0.25 to 4."), bind.Params("pitch"))
bind.Proc2(hm, "SetPan", func(c *bind.Ctx, h Sound, p float32) {
if s := live(c); s != nil {
s.SetPan(h, p)
}
}, bind.Doc("SetPan pans a sound that is not spatial, -1 to 1."), bind.Params("pan"))
bind.Func1(hm, "Position", func(c *bind.Ctx, h Sound) float32 {
if s := live(c); s != nil {
return s.Position(h)
}
return 0
}, bind.Doc("Position returns the seconds played, within the loop for a looping sound."))
bind.Signal(hm, "Completed", []abi.TypeRef{abi.T(abi.Bool)}, bind.Params("finished"),
bind.Doc("Completed runs once when the sound ends: finished is false after Stop, when it was cut off, or when its node died."))
}