Script bindings: Sound and music¶

Verified against: SLUS_212.15 (NTSC-U, SHA1 e9cb2cc49aa046b9e494313dce2f5038ed17b2f4).

Bindings for sound effects, ambient emitters, music tracks and sound configuration: 51 in all. Conventions, the other categories and how to read an entry are on the masterlist.

Binding	Returns	Scripts	Boot	Mission 1	Evidence
`AddAmbientEmitter`	number	0	no	no	inferred
`AddAmbientSound`	-	1	yes	no	confirmed (code)
`AddAmbientSoundEmitter`	number	10	no	no	confirmed (code)
`AddAmbientSoundEmitter2`	number	58	no	yes	confirmed (code)
`DuplicateSoundMaterials`	-	3	yes	no	confirmed (code)
`EnableAmbientEmitter`	-	15	no	no	confirmed (code)
`NewAnimSlots`	-	3	yes	no	confirmed (code)
`NewAnimSound`	-	3	yes	no	confirmed (code)
`NewMaterialSlots`	-	3	yes	no	confirmed (code)
`NewMaterialSound`	-	3	yes	no	confirmed (code)
`PlayAmbientEmitter`	-	0	no	no	inferred
`PreLoadObjectSound`	-	3	no	no	confirmed (code)
`SetAmbientEmitterPositions`	-	53	no	yes	confirmed (code)
`SetAmbientEmitterVolumeMod`	-	3	no	no	confirmed (code)
`SetAmbientTrackVolume`	-	8	yes	yes	confirmed (code)
`SetNumberOfMaterialSlots`	-	6	yes	no	confirmed (code)
`SetupRadio`	-	4	no	no	confirmed (code)
`SndAllocateCharacterVoices`	-	1	yes	no	confirmed (code)
`SndCfgMusicInfo`	-	1	yes	no	confirmed (code)
`SndEnableMusicDuck`	-	1	no	no	confirmed (code)
`SndFadeOut`	-	0	no	no	inferred
`SndLoadBank`	-	19	no	no	confirmed (code)
`SndLoadMatrix`	-	2	yes	no	confirmed (code)
`SndSetCommandSoundPercent`	-	1	yes	no	confirmed (code)
`SndSetListener`	-	20	yes	yes	confirmed (code)
`SndSetNIDuck`	-	2	no	no	confirmed (code)
`SndSetPitchMod`	-	1	no	no	confirmed (code)
`SoundCfgInterfaceSound`	-	1	yes	no	confirmed (code)
`SoundDisableCombatMusic`	-	1	no	no	confirmed (code)
`SoundEnableEffects`	-	14	yes	no	confirmed (code)
`SoundEnableSystemMusic`	-	89	no	no	confirmed (code)
`SoundLoopMusicTrack`	-	87	yes	yes	confirmed (code)
`SoundPauseSound`	-	36	no	no	confirmed (code)
`SoundPlay`	number	17	no	no	confirmed (code)
`SoundPlay2D`	number	50	yes	no	confirmed (code)
`SoundPlayAmbientTrack`	-	84	no	yes	confirmed (code)
`SoundPlayCommand`	number	60	no	no	confirmed (code)
`SoundPlayMusicTrack`	-	8	no	no	confirmed (code)
`SoundPreLoad`	number	3	no	no	confirmed (code)
`SoundPreLoadScene`	-	0	no	no	inferred
`SoundSetEffect`	-	3	yes	no	confirmed (code)
`SoundSetMusicStateCallback`	-	1	no	no	confirmed (code)
`SoundSetMusicTrack`	-	73	no	no	confirmed (code)
`SoundSetMusicVolume`	-	50	yes	no	confirmed (code)
`SoundSetSoundVolume`	-	2	no	no	confirmed (code)
`SoundSetSystemMusicState`	-	8	no	no	confirmed (code)
`SoundStart`	-	3	no	no	confirmed (code)
`SoundStop`	-	0	no	no	confirmed (code)
`SoundStopAmbientTrack`	-	28	no	yes	confirmed (code)
`SoundStopMusicTrack`	-	90	yes	yes	confirmed (code)
`StartObjectSound`	-	0	no	no	confirmed (code)

AddAmbientEmitter¶

AddAmbientEmitter(pos, index, arg3, range, arg5, arg6) -> number

#	Argument	Read as	Meaning
1	`pos`	table of 3 numbers (t[1]..t[3])	Position {x, y, z}; written back.
2	`index`	number, truncated to an integer	Ambient-table entry (or sound id) to play.
3	`arg3`	number, truncated to an unsigned integer	A number passed on; meaning not traced.
4	`range`	number (single precision)	A float passed on; inferred to be the range in metres.
5	`arg5`	number, truncated to an unsigned integer	A number passed on; meaning not traced.
6	`arg6`	number, truncated to an unsigned integer	A number passed on; meaning not traced.

Returns number: The emitter's id.

Adds a point ambient emitter at one position (the same code as AddAmbientSoundEmitter with both points equal).

Notes. No script calls it.

Evidence: inferred; detail: brief
Wrapper 0x00372350 (registered by RegisterBindings); calls 0x00113b28
Used by no script on the disc
Coney: not implemented

AddAmbientSound¶

AddAmbientSound(index, sound)

#	Argument	Read as	Meaning
1	`index`	number, truncated to an integer	Entry in the ambient sound table (0 upwards); global.lua fills hundreds of entries.
2	`sound`	string	Sound name for that entry.

Returns nothing.

Puts a sound into the ambient sound table that the ambient emitters pick their random sounds from (AddAmbientSoundEmitter2's index and count).

Notes. 0x0010d3c8 stores the name hash at ambient manager +0x1a014 + 4 × index; the index is not range-checked.

Evidence: confirmed (code) at 0x00113810; detail: traced
Wrapper 0x003718d8 (registered by RegisterBindings); calls 0x00113810
Used by 1 of 467 script chunks (1077 references); boot to menu: yes; mission 1: no; result used: no
Coney: implemented

AddAmbientSoundEmitter¶

AddAmbientSoundEmitter(pos1, pos2, index, sound, count, range, plays, minDelay, maxDelay, mode, filter) -> number

#	Argument	Read as	Meaning
1	`pos1`	table of 3 numbers (t[1]..t[3])	First point {x, y, z} of the emitter (emitter `+0x60`); written back.
2	`pos2`	table of 3 numbers (t[1]..t[3])	Second point {x, y, z} (emitter `+0x10`); the same as pos1 for a point source; written back.
3	`index`	number, truncated to an integer	First ambient-table slot to pick from (AddAmbientSound), or -1 to use the sound name.
4	`sound`	string	Sound name when index is -1 (such as a music loop for a radio); hashed, nil for none.
5	`count`	number, truncated to an unsigned integer	Number of consecutive table slots, played in turn.
6	`range`	number (single precision)	Range in metres from pos1; -1 takes the sound's own far distance plus 10.
7	`plays`	number, truncated to an integer	Plays before it switches itself off (`+0x8c`; -1 without limit). The scripts pass 0, which would allow none in modes 1-2; their mode 3 ignores it.
8	`minDelay`	number, truncated to an unsigned integer	Lower bound of the random pause between plays, whole seconds (`+0x86`).
9	`maxDelay`	number, truncated to an unsigned integer	Upper bound of the random pause, whole seconds (`+0x88`); the first pause is drawn between the two at once.
10	`mode`	number, truncated to an unsigned integer	How it plays (`+0x8d`, as AddAmbientSoundEmitter2's mode; the scripts pass 3, a loop while in range).
11	`filter`	number, truncated to an integer	Listener filter 0-2 at `+0x90`; larger values become 0 (the scripts pass 0 or 3, so 3 acts as 0).

Returns number: The emitter's id, for EnableAmbientEmitter and SetAmbientEmitterVolumeMod.

Adds an ambient sound emitter, the older form of AddAmbientSoundEmitter2: every one gets the name particle task. Calling it again with the same sound and first point returns the existing emitter (marking it +0x7c = 1) instead of adding one. The sounds it can play are preloaded when it is added.

Notes. Argument-to-field mapping confirmed (code) through the register and stack passing at 0x00371ce0 (the decompiler hides arguments 10 and 11); the numbers' meaning is confirmed (code) at 0x0010c100 (Sound: ambient emitters).

Evidence: confirmed (code) at 0x00113840, 0x0010cf58, 0x0010cc70; detail: traced
Wrapper 0x00371b18 (registered by RegisterBindings); calls 0x00113840 Sound_AddAmbientEmitter, 0x0010cf58 AmbientManager_AddEmitter, 0x0010cc70 AmbientManager_FindEmitter
Used by 10 of 467 script chunks (13 references); boot to menu: no; mission 1: no; result used: yes
Later in the story: 7 of 28 levels, first level3 (mission 6)
Coney: implemented

AddAmbientSoundEmitter2¶

AddAmbientSoundEmitter2(name, pos1, pos2, index, sound, count, range, plays, minDelay, maxDelay, mode, filter) -> number

#	Argument	Read as	Meaning
1	`name`	string	The emitter's name (such as "tCrickets01"), used by SetAmbientEmitterPositions; a name already used refers to the existing emitter.
2	`pos1`	table of 3 numbers (t[1]..t[3])	The point the range is measured from (emitter `+0x60`); written back.
3	`pos2`	table of 3 numbers (t[1]..t[3])	The point the sounds play from (`+0x10`) until SetAmbientEmitterPositions gives up to five; written back.
4	`index`	number, truncated to an integer	First entry of the ambient sound table (AddAmbientSound) to pick from, or -1 to play the sound named by sound.
5	`sound`	string	Sound name used when index is -1; the scripts pass "" otherwise.
6	`count`	number, truncated to an unsigned integer	How many consecutive table entries, starting at index, the emitter plays in turn (from a random one).
7	`range`	number (single precision)	Range in metres from pos1 within which a listener makes it play (the scripts use 25-70); -1 takes the first sound's far distance + 10.
8	`plays`	number, truncated to an integer	How many times it plays before switching itself off; -1 (what the scripts pass) without limit.
9	`minDelay`	number, truncated to an unsigned integer	Shortest pause between two plays, in whole seconds.
10	`maxDelay`	number, truncated to an unsigned integer	Longest pause between two plays, in whole seconds.
11	`mode`	number, truncated to an unsigned integer	How it plays (`+0x8d`): 1-2 timed one-shots, 3 a loop while in range, 4 timed with an immediate first play, 5 timed and cut after a second, 7 a conversation; the scripts pass 3 or 4.
12	`filter`	number, truncated to an integer	Which players hear it (`+0x90`): 0 those whose `+0x5b7` is clear, 1 those whose it is set, 2 all; larger values become 0. The scripts pass 0.

Returns number: The emitter's id.

Adds a named ambient sound emitter: at random intervals it plays a random sound from part of the ambient table (or one named sound) from its point or points. The levels place their crickets, dogs, wind and machinery this way.

Notes. 0x00113920 → 0x0010cf58. Which argument lands in which emitter field is confirmed (code); the meaning of the numbers is confirmed (code) at the update 0x0010c100 (Sound: ambient emitters). Names containing _DAM_ play only 2-15 s after an AI event, _FHT_ only during fights, and music ones duck under the score.

Evidence: confirmed (code) at 0x00113920; detail: traced
Wrapper 0x00371db0 (registered by RegisterBindings); calls 0x00113920
Used by 58 of 467 script chunks (2230 references); boot to menu: no; mission 1: yes; result used: yes
Later in the story: 23 of 28 levels, first level80 (mission 2)
Coney: implemented

DuplicateSoundMaterials¶

DuplicateSoundMaterials(material1, material2)

#	Argument	Read as	Meaning
1	`material1`	number, truncated to an unsigned integer	First material id.
2	`material2`	number, truncated to an unsigned integer	Second material id.

Returns nothing.

Makes the reverse pair share the sounds of a material pair, so B hitting A sounds like A hitting B; nothing happens when both are the same.

Notes. 0x00116438 copies the slot pointer between the two transposed table cells.

Evidence: confirmed (code) at 0x00113ce8; detail: traced
Wrapper 0x003729c0 (registered by RegisterBindings); calls 0x00113ce8
Used by 3 of 467 script chunks (2225 references); boot to menu: yes; mission 1: no; result used: no
Coney: implemented

EnableAmbientEmitter¶

EnableAmbientEmitter(emitter, on)

#	Argument	Read as	Meaning
1	`emitter`	number, truncated to an integer	Emitter id as returned by AddAmbientSoundEmitter2 (its slot in the ambient manager); not range-checked.
2	`on`	boolean (nil or 0 is false); default true	true (the default) enables the emitter, false silences it.

Returns nothing.

Switches an ambient sound emitter on or off (emitter +0x8c, records of 0xd0 bytes in the ambient manager at audio manager +0x24280). An emitter switched off has its playing sound stopped at its next update and plays nothing more; switched on, it resumes playing at its random intervals while a listener is in range.

Notes. The update is 0x0010c100, at most once a second. An emitter with a limited play count clears the same flag itself when the count runs out; re-enabling it then lets it play on without a limit (count byte at -1), inferred from the code.

Evidence: confirmed (code) at 0x00113bc8, 0x0010d570; detail: traced
Wrapper 0x003726a0 (registered by RegisterBindings); calls 0x00113bc8 Audio_EnableAmbientEmitter, 0x0010d570 AmbientManager_EnableEmitter
Used by 15 of 467 script chunks (43 references); boot to menu: no; mission 1: no; result used: no
Later in the story: 12 of 28 levels, first level95 (the hub)
Coney: implemented

NewAnimSlots¶

NewAnimSlots(animSound, count, columns, tune1, tune2, tune3, tune4, tune5, tune6)

#	Argument	Read as	Meaning
1	`animSound`	number, truncated to an unsigned integer	Animation sound event id (SA.* from enum_preload.lua, such as SA.play_sound_grunt).
2	`count`	number, truncated to an unsigned integer	How many alternative sounds the event has; they play in turn (cursor byte 1, 0x00114800).
3	`columns`	number, truncated to an unsigned integer; default 1	How many sound columns each alternative has, 1-3 (default 1).
4	`tune1`	number (single precision); default 1	Volume of column 1 (record +0x04, default 1; the scripts pass 0.9 for some).
5	`tune2`	number (single precision); default 1	Volume of column 2 (+0x08, default 1).
6	`tune3`	number (single precision); default 1	Volume of column 3 (+0x0c, default 1).
7	`tune4`	number (single precision)	A float (default 0); passed on but not read by 0x00116080.
8	`tune5`	number (single precision)	A float (default 0); as tune4.
9	`tune6`	number (single precision)	A float (default 0); as tune4.

Returns nothing.

Allocates the sound table for one animation sound event (a sound an animation triggers, such as a grunt or a death cry): count alternatives with up to three columns each.

Notes. 0x00116080.

Evidence: confirmed (code) at 0x00113d50; detail: traced
Wrapper 0x00372ad8 (registered by RegisterBindings); calls 0x00113d50
Used by 3 of 467 script chunks (260 references); boot to menu: yes; mission 1: no; result used: no
Coney: implemented

NewAnimSound¶

NewAnimSound(index, animSound, sound1, sound2, sound3)

#	Argument	Read as	Meaning
1	`index`	number, truncated to an unsigned integer	Which alternative to set, 0 to count - 1.
2	`animSound`	number, truncated to an unsigned integer	Animation sound event id (SA.*).
3	`sound1`	string	Sound name for column 1; "none" stores no sound, nil leaves it unchanged.
4	`sound2`	string	Sound name for column 2, as sound1.
5	`sound3`	string	Sound name for column 3, as sound1.

Returns nothing.

Sets the sounds of one alternative of an animation sound event made with NewAnimSlots.

Notes. 0x001162a0.

Evidence: confirmed (code) at 0x00113d88; detail: traced
Wrapper 0x00372c78 (registered by RegisterBindings); calls 0x00113d88
Used by 3 of 467 script chunks (507 references); boot to menu: yes; mission 1: no; result used: no
Coney: implemented

NewMaterialSlots¶

NewMaterialSlots(material1, material2, count, columns, tune1, tune2, tune3, tune4, tune5, tune6)

#	Argument	Read as	Meaning
1	`material1`	number, truncated to an unsigned integer	First material id (MATERIAL.* from enum_preload.lua), such as a weapon or fist.
2	`material2`	number, truncated to an unsigned integer	Second material id, such as the body part or surface hit.
3	`count`	number, truncated to an unsigned integer	How many alternative sounds the pair has; they play in turn, one per hit (cursor byte 2 of the record, 0x001146c0).
4	`columns`	number, truncated to an unsigned integer; default 1	How many sound columns each alternative has, 1-3 (default 1); NewMaterialSound fills them.
5	`tune1`	number (single precision); default 1	Volume of column 1 (record +0x04, default 1), multiplied into the sound's volume when it plays.
6	`tune2`	number (single precision); default 1	Volume of column 2 (+0x08, default 1).
7	`tune3`	number (single precision); default 1	Volume of column 3 (+0x0c, default 1).
8	`tune4`	number (single precision)	A float (default 0); passed on but not read by 0x00115cb0.
9	`tune5`	number (single precision)	A float (default 0); as tune4.
10	`tune6`	number (single precision)	A float (default 0); as tune4.

Returns nothing.

Allocates the sound table for one pair of materials (what hits what): count alternatives with up to three columns of sound names each; config_preload.lua and the sound matrix call it thousands of times.

Notes. 0x00115cb0 (Sound: the sound matrix); the table is a 2D array indexed by the two materials (row stride 0x2fc) in the audio manager's sound table at +0x1e0, allocated from the Level Dynamic & LUA pool.

Evidence: confirmed (code) at 0x00113c58; detail: traced
Wrapper 0x00372700 (registered by RegisterBindings); calls 0x00113c58
Used by 3 of 467 script chunks (2227 references); boot to menu: yes; mission 1: no; result used: no
Coney: implemented

NewMaterialSound¶

NewMaterialSound(index, material1, material2, sound1, sound2, sound3)

#	Argument	Read as	Meaning
1	`index`	number, truncated to an unsigned integer	Which alternative to set, 0 to count - 1.
2	`material1`	number, truncated to an unsigned integer	First material id of the pair.
3	`material2`	number, truncated to an unsigned integer	Second material id of the pair.
4	`sound1`	string	Sound name for column 1; "none" stores no sound, nil leaves it unchanged.
5	`sound2`	string	Sound name for column 2, as sound1.
6	`sound3`	string	Sound name for column 3, as sound1.

Returns nothing.

Sets the sounds of one alternative of a material pair made with NewMaterialSlots; each named sound is also registered with the audio manager (0x00110db0).

Notes. 0x00115ee8.

Evidence: confirmed (code) at 0x00113c98; detail: traced
Wrapper 0x003728c8 (registered by RegisterBindings); calls 0x00113c98
Used by 3 of 467 script chunks (3296 references); boot to menu: yes; mission 1: no; result used: no
Coney: implemented

PlayAmbientEmitter¶

PlayAmbientEmitter(emitter)

#	Argument	Read as	Meaning
1	`emitter`	number, truncated to an integer	Emitter id.

Returns nothing.

Makes an ambient emitter play now, without waiting for its timer.

Notes. No script calls it.

Evidence: inferred; detail: brief
Wrapper 0x00372668 (registered by RegisterBindings); calls 0x00113c30
Used by no script on the disc
Coney: not implemented

PreLoadObjectSound¶

PreLoadObjectSound(object, sound)

#	Argument	Read as	Meaning
1	`object`	number, truncated to an unsigned integer	Handle of a world object (a vehicle, for example); other kinds of object do nothing.
2	`sound`	string	Name of the sound to load for it (a path such as a cutscene sound).

Returns nothing.

Loads a sound positioned on a world object so that StartObjectSound (WorldObject_StartSound, 0x00397998) can start it later: the sound is loaded at the object's position (+0x10) and its handle kept at +0xf8; a sound the object already had is stopped and replaced. The object's record is also pinned (ObjRecord_SetPinned) so it is never streamed out while it carries the sound.

Notes. Only objects whose class reports kind bit 8 accept it (0x00395f38; that these are the placed world objects is inferred). The pin is not undone.

Evidence: confirmed (code) at 0x003978d0; detail: traced
Wrapper 0x0036dd40 (registered by RegisterBindings); calls 0x003978d0 WorldObject_PreloadSound
Used by 3 of 467 script chunks (5 references); boot to menu: no; mission 1: no; result used: no
Later in the story: 2 of 28 levels, first level51 (mission 14)
Coney: not implemented

SetAmbientEmitterPositions¶

SetAmbientEmitterPositions(name, pos1, pos2, pos3, pos4, pos5, count)

#	Argument	Read as	Meaning
1	`name`	string	Name of an emitter made with AddAmbientSoundEmitter2.
2	`pos1`	table of 3 numbers (t[1]..t[3])	Position {x, y, z}; written back.
3	`pos2`	table of 3 numbers (t[1]..t[3])	Position {x, y, z}; written back.
4	`pos3`	table of 3 numbers (t[1]..t[3])	Position {x, y, z}; written back.
5	`pos4`	table of 3 numbers (t[1]..t[3])	Position {x, y, z}; written back.
6	`pos5`	table of 3 numbers (t[1]..t[3])	Position {x, y, z}; written back.
7	`count`	number, truncated to an unsigned integer	How many of the five positions are used (at most 5).

Returns nothing.

Gives a named ambient emitter up to five positions it plays its sounds from, instead of its two points.

Notes. 0x00113a58 → 0x0010d590.

Evidence: confirmed (code) at 0x00113a58; detail: traced
Wrapper 0x00372058 (registered by RegisterBindings); calls 0x00113a58
Used by 53 of 467 script chunks (421 references); boot to menu: no; mission 1: yes; result used: no
Later in the story: 23 of 28 levels, first level80 (mission 2)
Coney: implemented

SetAmbientEmitterVolumeMod¶

SetAmbientEmitterVolumeMod(emitter, volume)

#	Argument	Read as	Meaning
1	`emitter`	number, truncated to an integer	Emitter id, as AddAmbientSoundEmitter or AddAmbientSoundEmitter2 returned (not range-checked).
2	`volume`	number (single precision)	Volume factor, 1 normal and 0 silent (not clamped).

Returns nothing.

Scales the volume of one ambient emitter (its record, 0xd0 bytes at ambient manager +0x80 + 0xd0 × id, keeps the factor at +0x88), and applies it at once to the sound the emitter is playing (+0x74 of its voice), for example a radio turned down.

Notes. The ambient manager is the audio manager +0x24280. That later plays use +0x88 is inferred.

Evidence: confirmed (code) at 0x00113c00, 0x0010d2a0; detail: traced
Wrapper 0x003725f0 (registered by RegisterBindings); calls 0x00113c00 Sound_SetAmbientEmitterVolume, 0x0010d2a0 AmbientEmitter_SetVolume
Used by 3 of 467 script chunks (3 references); boot to menu: no; mission 1: no; result used: no
Later in the story: 3 of 28 levels, first level2 (mission 5)
Coney: implemented

SetAmbientTrackVolume¶

SetAmbientTrackVolume(volume)

#	Argument	Read as	Meaning
1	`volume`	number (single precision)	Volume of the ambience loop, 0-1 (clamped).

Returns nothing.

Sets the volume of the background ambience loop that is playing; does nothing when none is (0x00110cc0).

Evidence: confirmed (code) at 0x00113658; detail: traced
Wrapper 0x003715c0 (registered by RegisterBindings); calls 0x00113658
Used by 8 of 467 script chunks (15 references); boot to menu: yes; mission 1: yes; result used: no
Later in the story: 5 of 28 levels, first level87 (mission 3)
Coney: implemented

SetNumberOfMaterialSlots¶

SetNumberOfMaterialSlots(material1, material2, count)

#	Argument	Read as	Meaning
1	`material1`	number, truncated to an unsigned integer	First material id.
2	`material2`	number, truncated to an unsigned integer	Second material id.
3	`count`	number, truncated to an unsigned integer	How many of the allocated alternatives are used (no more than NewMaterialSlots allocated).

Returns nothing.

Changes how many alternatives a material pair picks from, and restarts its choice.

Notes. 0x00116480.

Evidence: confirmed (code) at 0x00113d18; detail: traced
Wrapper 0x00372a38 (registered by RegisterBindings); calls 0x00113d18
Used by 6 of 467 script chunks (18 references); boot to menu: yes; mission 1: no; result used: no
Later in the story: 1 of 28 levels, first level81 (mission 8)
Coney: implemented

SetupRadio¶

SetupRadio(object, onPickUp, track, onSegment, djLine)

#	Argument	Read as	Meaning
1	`object`	number, truncated to an unsigned integer	Handle of a radio (boom box) world object; not checked, so another handle corrupts that object's record.
2	`onPickUp`	string	Name of a Lua function called with the player's handle when the player picks the radio up (message 0x1b); nil for none.
3	`track`	number, truncated to an integer	Track to start with: an index 1-20 into the radio's 21-track table (0x00512cd8; names on Sound, Radios); 0 or less starts the radio switched off.
4	`onSegment`	string	Name of a Lua function called (no arguments) each time the radio moves on: a DJ link starts, it retunes or the next track starts; nil for none.
5	`djLine`	number, truncated to an integer	When not 0, an index 1-12 into the announcement table (0x00512d30: `vags/music/djlady_01` ... `_12`) played once when the player first comes within 5 m, cutting the track short; the scripts pass the checkpoint, so each chapter has its own announcement. 0 for none.

Returns nothing.

Makes a world object a working radio. Everything it plays is a streamed sound started at the radio's position (PlaySound3DByHash, a positional sound task, not the music player), heard while the player is within 40 m, at half volume while a scene plays: its track, then a random DJ link (70% one of 15 kind-1 clips, 20% kind 0, 10% a dj_rumble clip), then a random next track, and so on; onSegment runs at each change. With djLine the announcement plays when the player first comes within 5 m. Holding R1 while carrying the radio retunes it (a retune sound, then a random track); smashing it silences it for good. The object is pinned (ObjRecord_SetPinned) so it is not recycled. State machine, tables and names: Sound, Radios.

Notes. Record fields (object record via vtable +0x18c): +0x24 sound, +0x28 track, +0x2c next track or announcement, +0x30 state (1 play, 9 off, 3 retune, 0xb pause), +0x34 clip table, +0x36 announcement armed, +0x38 / +0x3c the callbacks. Random next tracks come from the first 12 tracks, 18 once level 84 is complete; after a DJ link a drawn track above 11 plays track 0. Radio_SetMode (0x003ac600) is called only with mode 1 (retune): by Player_UpdateActions (R1 held, carried weapon type 6) and by the smash message. The names of the two DJ-link kinds and of five tracks were not recovered (hashes on the research page).

Evidence: confirmed (code) at 0x003ac4d0, 0x003ad440, 0x003ac7e8; detail: traced
Wrapper 0x00379ea0 (registered by RegisterBindings); calls 0x003ac4d0 Radio_Setup, 0x003ad440 Radio_Update, 0x003ac7e8 Radio_HandleMessage
Used by 4 of 467 script chunks (7 references); boot to menu: no; mission 1: no; result used: no
Later in the story: 3 of 28 levels, first level87 (mission 3)
Coney: implemented

SndAllocateCharacterVoices¶

SndAllocateCharacterVoices(count)

#	Argument	Read as	Meaning
1	`count`	number, truncated to an unsigned integer	Number of characters to allocate voices for (config_preload.lua passes 350).

Returns nothing.

Allocates the character voice table and, for every character and each of its 207 speech commands, counts how many lines exist in the sound data by probing names of the form vags/character/voices//_ (up to 54 each).

Notes. 0x001164a8; each character's record is 0x26d bytes (3 bytes per command: count, ..., percent defaulting to 100).

Evidence: confirmed (code) at 0x00113dd0; detail: traced
Wrapper 0x00372d48 (registered by RegisterBindings); calls 0x00113dd0
Used by 1 of 467 script chunks (1 reference); boot to menu: yes; mission 1: no; result used: no
Coney: implemented

SndCfgMusicInfo¶

SndCfgMusicInfo(track, time, volume, arg4)

#	Argument	Read as	Meaning
1	`track`	string	Music track name (such as "music/").
2	`time`	number, truncated to an unsigned integer	The track's bar length in milliseconds (1,548-3,780 in the configuration): the music player starts and cross-fades tracks on its bar boundaries and fades over whole bars (confirmed (code) at 0x0010dfe0); the values are four beats at the tempo in the track names (inferred).
3	`volume`	number (single precision)	The track's volume, 0-1 (clamped).
4	`arg4`	number (single precision)	A float read but not passed on by 0x00113438 (the configuration never passes it).

Returns nothing.

Configures one music track's volume and timing in the music player's track list; called for every track by config_preload.lua at the legal screen. Tracks not in the list cannot play.

Notes. 0x0010d870 finds the track by name hash and stores the volume and the time.

Evidence: confirmed (code) at 0x00113438; detail: traced
Wrapper 0x00370fd0 (registered by RegisterBindings); calls 0x00113438
Used by 1 of 467 script chunks (303 references); boot to menu: yes; mission 1: no; result used: no
Coney: implemented

SndEnableMusicDuck¶

SndEnableMusicDuck(on)

#	Argument	Read as	Meaning
1	`on`	boolean (nil or 0 is false); default true	true (the default) lets scenes lower the music; false keeps it at full volume. Any non-false value counts as true (one script passes 16).

Returns nothing.

Turns music ducking on or off (audio manager +0x3fab4). While a cinematic scene plays (game state +0x410 not 0) and ducking is on, Music_UpdateVolumes (0x0010e558) multiplies both music streams' volume by the duck level (+0x3fab0, 0.75 from the level load, Level loading).

Notes. Its value at level start is written at 0x001582e0 and 0x0010f618 (not traced). Ducking does not follow speech outside scenes.

Evidence: confirmed (code) at 0x00113390; detail: traced
Wrapper 0x00370fa0 (registered by RegisterBindings); calls 0x00113390 Audio_EnableMusicDuck
Used by 1 of 467 script chunks (2 references); boot to menu: no; mission 1: no; result used: no
Later in the story: 1 of 28 levels, first level54 (mission 16)
Coney: not implemented

SndFadeOut¶

SndFadeOut(sound, time)

#	Argument	Read as	Meaning
1	`sound`	number, truncated to an unsigned integer	Handle of a playing sound (as returned by SoundPlay or SoundPlay2D).
2	`time`	number, truncated to an unsigned integer	Fade time, passed to the sound's fade (units not traced; probably milliseconds).

Returns nothing.

Fades a playing sound out and stops it.

Notes. No script calls it.

Evidence: inferred; detail: brief
Wrapper 0x00370f28 (registered by RegisterBindings); calls 0x00113340
Used by no script on the disc
Coney: not implemented

SndLoadBank¶

SndLoadBank(bank)

#	Argument	Read as	Meaning
1	`bank`	string	Name of a sound bank (such as a level's or a boss's bank), without extension.

Returns nothing.

Loads the named sound bank into sound RAM now (one bank is resident at a time, so it replaces the level's) and resets the pending bank name to none; or, while the audio manager defers bank loads (+0x3fa58, set when gameplay is entered), only records it as the pending bank that level loading loads in place of sound.

Notes. The pending name is 15 characters at +0x3fa48. A bank already current is not reloaded. Banks and who loads them: Sound: banks.

Evidence: confirmed (code) at 0x001133d0, 0x0010fa50, 0x00111618; detail: traced
Wrapper 0x00371130 (registered by RegisterBindings); calls 0x001133d0 Sound_LoadBank, 0x0010fa50 AudioManager_LoadBank, 0x00111618 AudioManager_SetPendingBank
Used by 19 of 467 script chunks (19 references); boot to menu: no; mission 1: no; result used: no
Later in the story: 11 of 28 levels, first level3 (mission 6)
Coney: implemented

SndLoadMatrix¶

SndLoadMatrix(name)

#	Argument	Read as	Meaning
1	`name`	string	Name of the sound matrix, a script that configures the level's sounds: global.lua passes "armies" for levels 60-64 and "sound" otherwise.

Returns nothing.

Selects the level's sound matrix: when the name differs from the current one, the previous set is released and the script _preload is run (through doFile, so _preload.lua).

Notes. 0x00114628: compares with the stored name (64 bytes at audio manager +0x1e0 + 0x23d64), formats "%s_preload" (0x00547d00) and calls 0x003579a0 (doFile's code).

Evidence: confirmed (code) at 0x00113490; detail: traced
Wrapper 0x00371090 (registered by RegisterBindings); calls 0x00113490
Used by 2 of 467 script chunks (3 references); boot to menu: yes; mission 1: no; result used: no
Later in the story: 1 of 28 levels, first level95 (the hub)
Coney: implemented

SndSetCommandSoundPercent¶

SndSetCommandSoundPercent(character, command, percent)

#	Argument	Read as	Meaning
1	`character`	number, truncated to an integer	Character index in the voice table, or -1 for every character.
2	`command`	number, truncated to an unsigned integer	Speech command id (0-206).
3	`percent`	number, truncated to an unsigned integer	Chance in percent (0-100) that the character says a line when the command fires.

Returns nothing.

Sets how often characters speak for a speech command.

Notes. 0x00115bb0 writes byte 2 of the command's 3-byte record.

Evidence: confirmed (code) at 0x00113df8; detail: traced
Wrapper 0x00372d80 (registered by RegisterBindings); calls 0x00113df8
Used by 1 of 467 script chunks (13 references); boot to menu: yes; mission 1: no; result used: no
Coney: implemented

SndSetListener¶

SndSetListener(listener)

#	Argument	Read as	Meaning
1	`listener`	number, truncated to an unsigned integer	What the 3D sound is heard from, stored at audio manager +0x60; the scripts pass 0 (normal) and 1, and once a script value; the meaning of each value is not traced (inferred: 0 the camera, 1 the player).

Returns nothing.

Chooses the listener position for 3D sound.

Notes. Only the store is confirmed (code); the reader of +0x60 is not traced.

Evidence: confirmed (code) at 0x00114018; detail: traced
Wrapper 0x00372e20 (registered by RegisterBindings); calls 0x00114018
Used by 20 of 467 script chunks (53 references); boot to menu: yes; mission 1: yes; result used: no
Later in the story: 11 of 28 levels, first level87 (mission 3)
Coney: implemented

SndSetNIDuck¶

SndSetNIDuck(level)

#	Argument	Read as	Meaning
1	`level`	number (single precision)	Volume factor (0-1) applied while a non-duckable sound plays; default 0.2, the scripts use 0.2 and 0.35.

Returns nothing.

Sets the duck factor (audio manager +0x3faac): while a non-duckable sound plays (such as a scripted line), every duckable directional sound not owned by a player, chiefly the other humans' voices, is scaled by this factor. Higher values duck less.

Notes. Applied in SoundTask_Update (0x0011ad58; Sound: sound tasks); reset to 0.2 on every level load (0x001582e0). Which lines are non-duckable (task +0xa4 = 0; HuSpeakNI's, inferred) is not traced here.

Evidence: confirmed (code) at 0x001133b0; detail: traced
Wrapper 0x003710f8 (registered by RegisterBindings); calls 0x001133b0 Audio_SetNIDuck
Used by 2 of 467 script chunks (4 references); boot to menu: no; mission 1: no; result used: no
Later in the story: 1 of 28 levels, first level95 (the hub)
Coney: implemented

SndSetPitchMod¶

SndSetPitchMod(pitch)

#	Argument	Read as	Meaning
1	`pitch`	number (single precision)	Global pitch factor for the game's sounds, 1.0 normal (one hub script uses 0.65 for a slowed-down effect); not clamped.

Returns nothing.

Sets the audio manager's global pitch factor (+0x3fa5c), which the sound tasks multiply into every playing sound's pitch, so lower values slow and deepen all game sound. It stays until changed again or until the next level load, which resets it to 1.0.

Notes. Reset to 1.0 by mode 1's Enter (0x001582e0) and Exit (0x00158488). Mode 1's update also lowers it towards 0.7 by itself, by 0.7 / (0.9 × the level-end countdown) a frame (0x00158728 at 0x001589c8; inferred: the slow-down as a level ends), and saves and restores it around one other state (0x00158bd4, not traced). Its readers are SoundTask_Update (0x0011b048), 0x0011daa8 and the device 0x0014caf8.

Evidence: confirmed (code) at 0x00113370; detail: traced
Wrapper 0x003710c0 (registered by RegisterBindings); calls 0x00113370 Audio_SetPitchMod
Used by 1 of 467 script chunks (2 references); boot to menu: no; mission 1: no; result used: no
Later in the story: 1 of 28 levels, first level95 (the hub)
Coney: implemented

SoundCfgInterfaceSound¶

SoundCfgInterfaceSound(id, sound)

#	Argument	Read as	Meaning
1	`id`	number, truncated to an integer	Interface sound id (config_preload2.lua sets 1 upwards: 1 AI health, 2 HUD alarm, 3 checkpoint, then menu sounds).
2	`sound`	string	Sound name for that id.

Returns nothing.

Assigns a sound to one of the interface sound cues the HUD and menus play, and registers it with the audio manager.

Notes. 0x001167b8 stores the hash at sound table +0x23cc4 + 4 × id.

Evidence: confirmed (code) at 0x001141b0; detail: traced
Wrapper 0x00372f20 (registered by RegisterBindings); calls 0x001141b0
Used by 1 of 467 script chunks (39 references); boot to menu: yes; mission 1: no; result used: no
Coney: implemented

SoundDisableCombatMusic¶

SoundDisableCombatMusic()

No arguments.

Returns nothing.

Turns the automatic (system) music off, as SoundEnableSystemMusic(false) does: when it was on, game state +0x3f8 is cleared, the playing music fades out or stops (0x0010d9a0, as SoundStopMusicTrack), and the mood is reset (to the forced-change value 3, then 4 while off), so the fight and search tracks stop following the action. When it was already off only the mood timer (+0x3f4) is cleared.

Notes. Scripted tracks (SoundPlayMusicTrack, SoundLoopMusicTrack) still play. SoundEnableSystemMusic(true) turns it back on.

Evidence: confirmed (code) at 0x00113e30, 0x0041a008; detail: traced
Wrapper 0x00371418 (registered by RegisterBindings); calls 0x00113e30, 0x0041a008 GameState_SetSystemMusic
Used by 1 of 467 script chunks (1 reference); boot to menu: no; mission 1: no; result used: no
Later in the story: 1 of 28 levels, first level31 (mission 11)
Coney: not implemented

SoundEnableEffects¶

SoundEnableEffects(on)

#	Argument	Read as	Meaning
1	`on`	boolean (nil or 0 is false); default true	true (the default) enables the sound effects processing (reverb); false turns it off at once.

Returns nothing.

Turns the reverb effect on or off.

Notes. 0x001130c8.

Evidence: confirmed (code) at 0x00114060; detail: traced
Wrapper 0x00372f80 (registered by RegisterBindings); calls 0x00114060
Used by 14 of 467 script chunks (15 references); boot to menu: yes; mission 1: no; result used: no
Later in the story: 13 of 28 levels, first level80 (mission 2)
Coney: implemented

SoundEnableSystemMusic¶

SoundEnableSystemMusic(on)

#	Argument	Read as	Meaning
1	`on`	boolean (nil or 0 is false)	true lets the game choose the music by the situation (calm, fight, hunted); false stops it so the script controls the music.

Returns nothing.

Turns the system music, the game's automatic mood music, on or off (game state +0x3f8, 0x0041a008). On a change it forces a fresh choice of track and at once works out the mood from the player's surroundings (0x0041a060): 1 when an enemy gang near the player's gang is fighting it, 2 when an enemy gang's member is hunting it (goals 0xc, 0x75, 0x76, 0x001696e0), else 0. Turning it off fades out the music (0x0010d9a0).

Notes. Setting the value it already has only clears game state +0x3f4 (not traced). SoundSetMusicTrack turns it on too. Tracks per mood and the fades: Sound.

Evidence: confirmed (code) at 0x00113ea8; detail: traced
Wrapper 0x00371470 (registered by RegisterBindings); calls 0x00113ea8 Sound_EnableSystemMusic
Used by 89 of 467 script chunks (154 references); boot to menu: no; mission 1: no; result used: no
Later in the story: 23 of 28 levels, first level80 (mission 2)
Coney: implemented

SoundLoopMusicTrack¶

SoundLoopMusicTrack(track, flag)

#	Argument	Read as	Meaning
1	`track`	string	Music track name (such as "music/wonderwheel_132b"); must have been configured with SndCfgMusicInfo.
2	`flag`	number, truncated to an unsigned integer; default 1	A byte passed to the music player with the track (default 1); the scripts never pass it, and its meaning is not traced.

Returns nothing.

Starts a music track playing in a loop, replacing what is playing; the front end loops MenuTrack and the Wonder Wheel theme with it. Does nothing while the game state forbids music or when the track is not configured.

Notes. 0x00113590 → 0x00112de0 → 0x0010d8e8 (loop on); 0x0041cf30 is the game-state check.

Overload (registered first; the wrapper above checks its argument types and calls this one when they do not match): Used when the first argument is not a string or there are more than two arguments.

SoundLoopMusicTrack(trackHash, flag)

#	Argument	Read as	Meaning
1	`trackHash`	number, truncated to an unsigned integer	The track's name hash (a number) instead of its name.
2	`flag`	number, truncated to an unsigned integer; default 1	As in the main form (default 1).

Returns nothing.

Wrapper 0x003712d8; calls 0x00113560.

Evidence: confirmed (code) at 0x00113590; detail: traced
Wrapper 0x00371348 (registered by RegisterBindings); calls 0x00113590
Used by 87 of 467 script chunks (183 references); boot to menu: yes; mission 1: yes; result used: no
Later in the story: 20 of 28 levels, first level95 (the hub)
Coney: implemented

SoundPauseSound¶

SoundPauseSound(on)

#	Argument	Read as	Meaning
1	`on`	boolean (nil or 0 is false); default true	true (the default) pauses all game sound, false resumes it.

Returns nothing.

Pauses or resumes every playing voice, for example around a scripted pause or a menu: the audio manager's paused flag (+0x3fa24) is set or cleared and the sound device pauses or resumes all voices; paused sounds continue where they stopped.

Notes. Through the device's slots +0x64 / +0x6c (0x0014c5e0 / 0x0014c600). While paused, pitch updates stop; whether sounds started meanwhile play is not traced.

Evidence: confirmed (code) at 0x00114088, 0x0010fb20, 0x0010fb68; detail: traced
Wrapper 0x00372fb0 (registered by RegisterBindings); calls 0x00114088 Audio_PauseSound, 0x0010fb20 AudioManager_Pause, 0x0010fb68 AudioManager_Resume
Used by 36 of 467 script chunks (139 references); boot to menu: no; mission 1: no; result used: no
Later in the story: 1 of 28 levels, first level95 (the hub)
Coney: implemented

SoundPlay¶

SoundPlay(sound, pos) -> number

#	Argument	Read as	Meaning
1	`sound`	string	Sound name (such as "vags/doors/opengate_01"), hashed with the game's name hash (0x00143f68); see Sound.
2	`pos`	table of 3 numbers (t[1]..t[3])	World position {x, y, z} in metres the sound plays at; written back unchanged.

Returns number: Handle of the playing sound, for SoundStop or SndFadeOut; the null sound handle (0x00598690) when it could not start.

Plays a sound once as a positional (3D) sound at a point in the world, at full caller volume and normal pitch; it is heard with the usual distance falloff and panning to each listener and then ends by itself.

Notes. PlaySound3DByHash (0x0010fdd0) with volume, pitch and a third factor of 1.0 and its last flag 1; a name that is not in the sound list, or no free task, gives the null handle. Converted as unsigned.

Evidence: confirmed (code) at 0x00113680, 0x0010fdd0; detail: traced
Wrapper 0x003715f8 (registered by RegisterBindings); calls 0x00113680 Audio_PlaySoundAt, 0x0010fdd0
Used by 17 of 467 script chunks (27 references); boot to menu: no; mission 1: no; result used: yes
Later in the story: 10 of 28 levels, first level95 (the hub)
Coney: implemented

SoundPlay2D¶

SoundPlay2D(sound) -> number

#	Argument	Read as	Meaning
1	`sound`	string	Sound name (such as "vags/misc/menu8").

Returns number: The sound's handle, or the 'no sound' handle (0x00598690) when the sound could not start.

Plays a sound once without a position (2D, same volume in both speakers), for menus and interface cues.

Notes. 0x001137a8 → 0x0010fcd8.

Evidence: confirmed (code) at 0x001137a8; detail: traced
Wrapper 0x003716f8 (registered by RegisterBindings); calls 0x001137a8
Used by 50 of 467 script chunks (233 references); boot to menu: yes; mission 1: no; result used: no
Later in the story: 17 of 28 levels, first level95 (the hub)
Coney: implemented

SoundPlayAmbientTrack¶

SoundPlayAmbientTrack(track)

#	Argument	Read as	Meaning
1	`track`	string	Name of a looping ambient sound (such as "vags/ambient/city/distant_traffic_loop").

Returns nothing.

Starts the level's background ambience loop, stopping the current one unless it is the same track; the new one fades in over 2 s. In level 82 one particular track is swapped for another.

Notes. 0x00110b18 → 0x00110b60; the ambient track's sound handle is kept at audio manager +0x24274.

Evidence: confirmed (code) at 0x00113608; detail: traced
Wrapper 0x00371570 (registered by RegisterBindings); calls 0x00113608
Used by 84 of 467 script chunks (139 references); boot to menu: no; mission 1: yes; result used: no
Later in the story: 25 of 28 levels, first level80 (mission 2)
Coney: implemented

SoundPlayCommand¶

SoundPlayCommand(human, command, callback, interrupt, target, duckable) -> number

#	Argument	Read as	Meaning
1	`human`	number, truncated to an unsigned integer	Handle of the human who speaks; not a human returns the 'no sound' handle.
2	`command`	number, truncated to an unsigned integer	Speech command id (1-206), the kind of line (Speech); 0 says nothing.
3	`callback`	string	Name of a Lua function called with the speaker's handle when the line ends, or at once when no line plays; nil for none.
4	`interrupt`	boolean (nil or 0 is false); default true	true (the default) cuts off a line the human is saying; false says nothing while one plays.
5	`target`	number, truncated to an unsigned integer; default 4294967295	Handle of a human the speaker looks at for the line's length plus 0.5 s (default NilHandle, none).
6	`duckable`	boolean (nil or 0 is false); default true	true (the default) lets the line be ducked like other sounds; false marks it non-duckable (sound task `+0xa4`), so it ducks the others while it plays.

Returns number: The speech sound's handle, or the 'no sound' handle (0x00598690) when nothing plays.

Makes a human say a line of the given speech command, picked in turn from the human's voice set as Sound describes, positioned at the human. Nothing is said when the human cannot speak (+0x199), its voice set has no line for the command, the chance roll fails or a scene is playing.

Notes. The last flag is the play call's last argument (0x00111f78 stores it at task +0xa4; +0xa0 cleared when false). The callback is not called when the human is invalid, cannot speak, or is already speaking with interrupt false.

Evidence: confirmed (code) at 0x001140d8, 0x002205e0, 0x0021e400; detail: traced
Wrapper 0x00372fe0 (registered by RegisterBindings); calls 0x001140d8 Sound_PlayHumanCommand, 0x002205e0 Human_SayCommand, 0x0021e400 Human_PlaySpeech
Used by 60 of 467 script chunks (97 references); boot to menu: no; mission 1: no; result used: yes
Later in the story: 9 of 28 levels, first level87 (mission 3)
Coney: implemented

SoundPlayMusicTrack¶

SoundPlayMusicTrack(track, callback)

#	Argument	Read as	Meaning
1	`track`	string	Music track name (as `music/in_the_city`), hashed with the game's name hash; it must have been configured with SndCfgMusicInfo.
2	`callback`	string	Name of a Lua function to call when the track reaches its end, or nil.

Returns nothing.

Plays a music track once (not looped) through Music_Play with a fade of one bar (Sound: music): the track preloads on the free stream pair, starts at once when nothing plays or on the current track's next bar boundary (the old one fading out), and when its stream ends the callback is called. Does nothing while the game state forbids music or when the track is not in the configured list.

Notes. 0x00113510 hashes the name (0x00143f68) and calls Music_Play(player, hash, loop 0, callback, 1 bar) via 0x00112e08. The system music, if on, can replace the track on its next mood change. The string form is the one the scripts use.

Overload (registered first; the wrapper above checks its argument types and calls this one when they do not match): Used when the first argument is not a string or there are more than two arguments: the same call with a precomputed hash.

SoundPlayMusicTrack(trackHash, callback)

#	Argument	Read as	Meaning
1	`trackHash`	number, truncated to an unsigned integer	The track's name hash (a number) instead of its name.
2	`callback`	string	Name of a Lua function to call when the track ends, or nil.

Returns nothing.

Wrapper 0x003711d0; calls 0x001134e0.

Evidence: confirmed (code) at 0x00113510, 0x00112e08, 0x0010d8e8, 0x0010dfe0; detail: traced
Wrapper 0x00371230 (registered by RegisterBindings); calls 0x00113510, 0x00112e08, 0x0010d8e8 Music_Play, 0x0010dfe0 MusicChannel_Update
Used by 8 of 467 script chunks (11 references); boot to menu: no; mission 1: no; result used: no
Later in the story: 5 of 28 levels, first level31 (mission 11)
Coney: implemented

SoundPreLoad¶

SoundPreLoad(sound, pos) -> number

#	Argument	Read as	Meaning
1	`sound`	string	Sound name, hashed with the game's name hash (0x00143f68) as for SoundPlay.
2	`pos`	table of 3 numbers (t[1]..t[3])	World position {x, y, z} in metres the sound will play at; written back unchanged.

Returns number: Handle of the prepared sound, for SoundStart; the null sound handle (0x00598690) when it could not be prepared.

Prepares a positional sound at a point without starting it: a sound task is set up at full volume and normal pitch with no attached object (0x00111f78, as the scene-sound preload does), so that SoundStart can start it later with no loading delay.

Notes. A global flag (0x00512c14) is held at 1 while the task is made (inferred: tells the task code not to start it). Converted as unsigned. A prepared sound never started keeps its task (not traced when it is freed).

Evidence: confirmed (code) at 0x00113700, 0x001101b8, 0x00111f78; detail: traced
Wrapper 0x00371768 (registered by RegisterBindings); calls 0x00113700 Audio_PreloadSoundAt, 0x001101b8, 0x00111f78
Used by 3 of 467 script chunks (4 references); boot to menu: no; mission 1: no; result used: yes
Later in the story: 3 of 28 levels, first level5 (mission 7)
Coney: implemented

SoundPreLoadScene¶

SoundPreLoadScene(sound)

#	Argument	Read as	Meaning
1	`sound`	string	Name of a scene's sound.

Returns nothing.

Preloads a cutscene's sound (0x0010ff68).

Notes. No script calls it.

Evidence: inferred; detail: brief
Wrapper 0x00373118 (registered by RegisterBindings); calls 0x00114178
Used by no script on the disc
Coney: not implemented

SoundSetEffect¶

SoundSetEffect(effect, depth, delay, feedback)

#	Argument	Read as	Meaning
1	`effect`	number, truncated to an integer	Reverb type in the PS2 sound library's numbering (inferred): the scripts use 1 (room) and 5 (hall).
2	`depth`	number (single precision)	Effect depth (wet level), a float such as 0.1-0.2.
3	`delay`	number, truncated to an integer	Effect delay, an integer (0 or 50), for the echo/delay types (inferred).
4	`feedback`	number, truncated to an integer	Effect feedback, an integer (0 or 50) (inferred).

Returns nothing.

Sets the reverb effect applied to game sound, on both sound processor cores.

Notes. 0x00114028 → 0x00113000 calls the sound device twice (cores 0 and 1). The argument meanings follow the PS2 reverb parameters and are inferred.

Evidence: confirmed (code) at 0x00114028; detail: traced
Wrapper 0x00372e58 (registered by RegisterBindings); calls 0x00114028
Used by 3 of 467 script chunks (4 references); boot to menu: yes; mission 1: no; result used: no
Later in the story: 16 of 28 levels, first level80 (mission 2)
Coney: implemented

SoundSetMusicStateCallback¶

SoundSetMusicStateCallback(callback)

#	Argument	Read as	Meaning
1	`callback`	string	Name of the Lua function to call (copied, at most 31 characters, to `W_GameState + 0x384`), or nil to clear it.

Returns nothing.

Registers a Lua function that the system-music update (0x0010e7d0) calls as f(oldMood, newMood) whenever it acts on a mood change (game state +0x40c: 0, 1 or 2, inferred idle, fight, search) or a forced re-pick; the call comes after the new mood's track is started. Only one callback is kept; a new call replaces it.

Notes. Not called while the music update is deferred (0x00512c7c + 0x82c); a forced re-pick passes the same mood twice. A name that is not a Lua function is skipped silently. Moods: sound.md#system-music.

Evidence: confirmed (code) at 0x00113ff0, 0x0041b4c0, 0x0041b520; detail: traced
Wrapper 0x00371540 (registered by RegisterBindings); calls 0x00113ff0, 0x0041b4c0 GameState_SetMusicStateCallback, 0x0041b520 GameState_CallMusicStateCallback
Used by 1 of 467 script chunks (2 references); boot to menu: no; mission 1: no; result used: no
Later in the story: 1 of 28 levels, first level55 (mission 17)
Coney: not implemented

SoundSetMusicTrack¶

SoundSetMusicTrack(slot, track1, track2, track3)

#	Argument	Read as	Meaning
1	`slot`	number, truncated to an integer	The system-music mood the tracks are for: 0 calm, 1 fight, 2 hunted (the moods 0x0041a060 picks); not range-checked.
2	`track1`	string	Name of a music track, or nil or an empty string for none.
3	`track2`	string	A second track for the same mood, or nil.
4	`track3`	string	A third track, or nil.

Returns nothing.

Sets the tracks the system music picks from for one mood and turns the system music on. The non-empty names are hashed (CRC-32, table 0x005d91e0) and stored in order, up to three, in the music player's mood table (0x0010e9e0); when the mood is the one playing, a new pick is forced. Each time the mood changes the player plays a random one of the mood's tracks, looping.

Notes. Empty names are skipped, so the tracks pack to the front; a mood given no tracks stops the music when chosen. The names are not checked against the loaded track list. Also sets audio manager +0xcc = 1 (not traced). The mood names are inferred from 0x0041a060's tests. Sound.

Evidence: confirmed (code) at 0x00113ed0; detail: traced
Wrapper 0x003714a0 (registered by RegisterBindings); calls 0x00113ed0 Sound_SetMusicTrack
Used by 73 of 467 script chunks (275 references); boot to menu: no; mission 1: no; result used: no
Later in the story: 21 of 28 levels, first level80 (mission 2)
Coney: implemented

SoundSetMusicVolume¶

SoundSetMusicVolume(volume)

#	Argument	Read as	Meaning
1	`volume`	number (single precision)	Music volume, 0 (silent) to 1 (full); values outside are clamped (one script passes 100, which is full volume).

Returns nothing.

Sets the music player's volume; the change is applied by the music player's update.

Notes. 0x0010e710 stores it at music player +0x5c and sets a changed flag.

Evidence: confirmed (code) at 0x001134b8; detail: traced
Wrapper 0x00371198 (registered by RegisterBindings); calls 0x001134b8
Used by 50 of 467 script chunks (67 references); boot to menu: yes; mission 1: no; result used: no
Later in the story: 8 of 28 levels, first level95 (the hub)
Coney: implemented

SoundSetSoundVolume¶

SoundSetSoundVolume(volume)

#	Argument	Read as	Meaning
1	`volume`	number (single precision)	Read as a number but ignored.

Returns nothing.

Does nothing in this build: the function it calls (0x001140d0) is an empty stub that returns at once, and the wrapper is its only caller.

Notes. A reimplementation can ignore it; the volume the scripts pass has no effect on the original.

Evidence: confirmed (code) at 0x001140d0; detail: traced
Wrapper 0x00371160 (registered by RegisterBindings); calls 0x001140d0 Sound_SetSoundVolume
Used by 2 of 467 script chunks (4 references); boot to menu: no; mission 1: no; result used: no
Later in the story: 1 of 28 levels, first level64 (Armies of the Night 5)
Coney: not implemented

SoundSetSystemMusicState¶

SoundSetSystemMusicState(state)

#	Argument	Read as	Meaning
1	`state`	number, truncated to an integer	Mood to hold: 0 idle, 1 fight, 2 hunted (16-bit); 3 hands the mood back to the game; 4 switches the system music off. The scripts use 0, 1 and 3.

Returns nothing.

Sets the system music's mood (game state +0x40c), which picks the looping track (Sound). A state other than 3 also sets the script-hold flag (+0x3f4), so the game's own mood choice (SystemMusic_UpdateMood: fight when an enemy gang engages the player's, hunted while his gang is hunted, else idle) stops overriding it. State 3 clears the hold and the game chooses again on its next update.

Notes. State 4 (0x00419fc8) calls GameState_SetSystemMusic(0), which stops the music and clears the hold, and leaves the mood at 3. The moods' names come from the game's choice in SystemMusic_UpdateMood (0x0041a0d0).

Evidence: confirmed (code) at 0x00113e60, 0x00419fc8; detail: traced
Wrapper 0x00371438 (registered by RegisterBindings); calls 0x00113e60 Sound_SetSystemMusicState, 0x00419fc8 GameState_SetMusicMood
Used by 8 of 467 script chunks (16 references); boot to menu: no; mission 1: no; result used: no
Later in the story: 5 of 28 levels, first level2 (mission 5)
Coney: implemented

SoundStart¶

SoundStart(sound)

#	Argument	Read as	Meaning
1	`sound`	number, truncated to an unsigned integer	Handle from SoundPreLoad; a handle that no longer resolves to a sound task does nothing.

Returns nothing.

Starts a sound prepared with SoundPreLoad: the handle is resolved to its sound task (0x0010f578) and the task is started (0x00111f40), playing at the position given to SoundPreLoad.

Notes. The same start path is used by scene event 71 on a car (Sound).

Evidence: confirmed (code) at 0x00113780, 0x00110258, 0x00111f40; detail: traced
Wrapper 0x00371868 (registered by RegisterBindings); calls 0x00113780 Audio_StartPreloadedSound, 0x00110258, 0x00111f40
Used by 3 of 467 script chunks (4 references); boot to menu: no; mission 1: no; result used: no
Later in the story: 3 of 28 levels, first level5 (mission 7)
Coney: implemented

SoundStop¶

SoundStop(sound)

#	Argument	Read as	Meaning
1	`sound`	number, truncated to an unsigned integer	Handle of a playing sound.

Returns nothing.

Stops a sound at once.

Notes. No script calls it.

Evidence: confirmed (code) at 0x001137e8; detail: brief
Wrapper 0x003718a0 (registered by RegisterBindings); calls 0x001137e8
Used by no script on the disc
Coney: not implemented

SoundStopAmbientTrack¶

SoundStopAmbientTrack()

No arguments.

Returns nothing.

Stops the background ambience loop (0x00110c70).

Evidence: confirmed (code) at 0x00113630; detail: traced
Wrapper 0x003715a0 (registered by RegisterBindings); calls 0x00113630
Used by 28 of 467 script chunks (50 references); boot to menu: no; mission 1: yes; result used: no
Later in the story: 18 of 28 levels, first level87 (mission 3)
Coney: implemented

SoundStopMusicTrack¶

SoundStopMusicTrack()

No arguments.

Returns nothing.

Stops the music: each of the music player's three channels that is playing or fading is stopped or faded out according to its state (0x0010d9a0).

Evidence: confirmed (code) at 0x001135e0; detail: traced
Wrapper 0x003713f8 (registered by RegisterBindings); calls 0x001135e0
Used by 90 of 467 script chunks (189 references); boot to menu: yes; mission 1: yes; result used: no
Later in the story: 28 of 28 levels, first level80 (mission 2)
Coney: implemented

StartObjectSound¶

StartObjectSound(object)

#	Argument	Read as	Meaning
1	`object`	number, truncated to an unsigned integer	Handle of a world object that has a sound attached (see PreLoadObjectSound).

Returns nothing.

Starts the sound previously preloaded on a world object.

Notes. No script calls it.

Evidence: confirmed (code) at 0x00397998; detail: brief
Wrapper 0x0036dd08 (registered by RegisterBindings); calls 0x00397998
Used by no script on the disc
Coney: not implemented