Headcannon Game Engine Script Commands - Sound
Index:
Music:
(D) (E) | _PlayMusic |
(D) (E) | _PlayTempMusic |
(D) (E) | _PlayJingle |
(D) (E) | _PauseMusic |
(D) (E) | _ContinueMusic |
(D) (E) | _FadeMusic |
(D) (E) | _SetMusicVol |
(D) (E) | _XM_SetSpeedMod |
(D) (E) | _XM_SetPitchMod |
(D) (E) | _XM_SetChanMute |
(D) (E) | _XM_SetEventFunc |
(D) (E) | _XM_DoEffect |
Sound Effects:
(D) (E) | _PlaySound |
(D) (E) | _StopSound |
(D) (E) | _PauseSFX |
(D) (E) | _ContinueSFX |
(D) (E) | _FadeSFX |
(D) (E) | _SetSFXVol |
(D) (E) | _PlaySound_CurrPlayer |
(D) (E) | _PlaySound_FetchedPlayer |
(D) (E) | _StopSound_CurrPlayer |
(D) (E) | _StopSound_FetchedPlayer |
(D) (E) | _PlaySound_CurrObject |
(D) (E) | _PlaySound_FetchedObject |
(D) (E) | _StopSound_CurrObject |
(D) (E) | _StopSound_FetchedObject |
Descriptions:
Music:
_PlayMusic
(ALL) (REG) (Example)
Plays the given Music.
Bit 1 of the "GameFlags" Register is updated to reflect which type of
Music is being played.
Parameters:
- Music ID
The ID number of the desired Music within its "Music Def
The "G", "Z", and "A" tags may be used to reference Music that was loaded as Game-global,
"Zone"-specific, or "Act"-specific, respectively.
The "R" or "r" tags may be used to obtain the ID value from a Register.
_PlayTempMusic
(ALL) (REG) (Example)
Temporarily loads a Music from the specified
"Music Def" file and plays it.
Bit 1 of the "GameFlags" Register is updated to reflect which type of
Music is being played.
Parameters:
- Filename Text ID
ID number of the Text string that contains the filename of the
"Music Def" to load
When this Command is used by a Status Script Function,
this ID references a Status Script Text
When this Command is used by any other Function, it references Text from a Game Def
or a Zone Def. In this case, the "G" and "Z" tags may be used to reference "Game" and "Zone" Texts, respectively
The "R" or "r" tags may be used to obtain the ID value from a Register.
The filename in the Text string must be relative to the "Program Folder", not to the folder that contains
the file in which they appear.
- Music ID
ID number of the desired music in the specified "Music Def"
The "R" or "r" tags may be used to obtain the ID value from a Register.
_PlayJingle
(ALL) (REG) (Example)
Plays the given Music as a "Jingle". The currently-playing Music will be temporarily stopped, as will all sound effects,
and no new Music or sound effect is allowed to play until the Jingle is finished. When the Jingle finishes, the music that
was playing before the Jingle was started will continue from the point at which it was interrupted. If a new Music was set to
play while the Jingle was in effect, that music will then start from its beginning. Jingles can, however, be interrupted
by another Jingle.
Note:"Musics" that can be played as a Jingle must be loaded as type 0 or type 4 (Non-repeating single WAV or OGG Vorbis files, respectively),
as Jingles are intended to play only once and then yield back to the original Music. XM Files also can not be played as Jingles.
Parameters:
- Music ID
The ID number of the desired Music within its "Music Def
The "G", "Z", and "A" tags may be used to reference Music that was loaded as Game-global,
"Zone"-specific, or "Act"-specific, respectively.
The "R" or "r" tags may be used to obtain the ID value from a Register.
_PauseMusic
(ALL) (Example)
Suspends Music play.
Parameters:
None
_ContinueMusic
(ALL) (Example)
Resumes Music play.
Parameters:
None
_FadeMusic
(ALL) (REG) (Example)
Fades the Music volume up or down to the Target Volume.
Parameters:
- Target Volume
This value specifies the volume to which the Music should fade (valid range 0-64)
The "R" or "r" tags may be used to obtain the value from a Register.
_SetMusicVol
(ALL) (REG) (Example)
Immediately sets the Music Volume to the specified value.
Parameters:
- Volume
This value specifies the new Music volume(valid range 0-64)
The "R" or "r" tags may be used to obtain the value from a Register.
_XM_SetSpeedMod
(ALL) (REG) (Example)
Sets the speed modifier that is used when an XM Music is playing.
Parameters:
- Modifier
This value is used to calculate a new "Beats Per Minute" rate for the song
For positive values: BPM * ((Modifier + 8) / 8)
For negative values: BPM / ((Modifier + 8) / 8)
The "R" or "r" tags may be used to obtain the value from a Register.
_XM_SetPitchMod
(ALL) (REG) (Example)
Sets the pitch modifier that is used when an XM Music is playing.
Parameters:
- Modifier
This value is used as a "FineTune" offset when calculating note frequencies
64 "FineTune" values is one full note
The "R" or "r" tags may be used to obtain the value from a Register.
_XM_SetChanMute
(ALL) (REG) (Example)
Sets the "Mute" status on the given XM Channel.
Parameters:
- Chan
This value specifies the Channel whose "Mute" status should be modified.
XM Channel IDs start at 1, not 0.
The "R" or "r" tags may be used to obtain the value from a Register.
- Mute
This value specifies the "Mute" status to apply to the given Channel:
0 | - | _Off | - | Unmuted; the Channel will play sound |
1 | - | _On | - | Muted; the Channel will not play sound |
The "R" or "r" tags may be used to obtain the value from a Register.
_XM_SetEventFunc
(ALL) (REG) (Example)
Sets the current "XM Event Function", a Game Function to run whenever a "Zxx" event is encountered in an XM song.
This Function is only run once each time the effect is encountered, and should not break.
Parameters:
- FuncID
This is the ID number of the Game Def or Zone Def Function
to run when the "Zxx" effect occurs
The "G", "Z", and "A" tags may be used to reference Functions loaded as "Game-global", "Zone"-specific, and "Act"-specific, respectively
The "R" or "r" tags may be used to obtain the value from a Register.
_XM_DoEffect
(ALL) (REG) (Example)
Causes the specified XM Effect to be triggered as if it were used by the song itself.
This Command is generally only used in "XM Event Functions" to trigger Effects for the Channel that called it, but may be used in any other Function to trigger events that affect the whole song, and not just one Channel.
Parameters:
- Effect
This value is the "Effect ID" (not "name") of the Effect to trigger
The "R" or "r" tags may be used to obtain the value from a Register.
- Parameter
This value is the "Effect Parameter" to pass along with the Effect ID
The "R" or "r" tags may be used to obtain the value from a Register.
Sound Effects:
_PlaySound
(ALL) (REG) (Example)
Plays the given Sound Effect.
Parameters:
- Sound ID
The ID number of the desired Sound Effect within its "Sound Effect Def".
The "G", "Z", and "A" tags may be used to reference Sound Effects that were loaded as Game-global,
"Zone"-specific, or "Act"-specific, respectively.
The "R" or "r" tags may be used to obtain the ID value from a Register.
- Flag
This value specifies how to play the given Sound Effect:
0 | - | _Snd_Once | - | Play once |
1 | - | _Snd_Repeat | - | Loop infinitely |
_StopSound
(ALL) (REG) (Example)
Stops the given sound from playing
Parameters:
- Sound ID
The ID number of the desired Sound Effect within its "Sound Effect Def".
The "G", "Z", and "A" tags may be used to reference Sound Effects that were loaded as Game-global,
"Zone"-specific, or "Act"-specific, respectively.
The "R" or "r" tags may be used to obtain the ID value from a Register.
_PauseSFX
(ALL) (Example)
Suspends Sound Effect play.
Parameters:
None
_ContinueSFX
(ALL) (Example)
Resumes Sound Effect play.
Parameters:
None
_FadeSFX
(ALL) (REG) (Example)
Fades the Sound Effect volume up or down to the Target Volume.
Parameters:
- Target Volume
This value specifies the volume to which the Sound Effects should fade (valid range 0-64)
The "R" or "r" tags may be used to obtain the value from a Register.
_SetSFXVol
(ALL) (REG) (Example)
Immediately sets the Sound Effect Volume to the specified value.
Parameters:
- Volume
This value specifies the new Sound Effect volume(valid range 0-64)
The "R" or "r" tags may be used to obtain the value from a Register.
_PlaySound_CurrPlayer
_PlaySound_FetchedPlayer
(ALL) (Example)
Plays a Sound Effect referenced by the Player's Sound Effect Reference Listing.
The "_CurrPlayer" versions retrieve the reference from the "Current Player".
The "_FetchedPlayer" versions retrieve the reference from the Player "Fetched" to "Reference 0".
Parameters:
- Entry ID
ID number of the entry within the Player's Sound Effect Reference Listing that references the desired Sound Effect
The lower-case "s" tag may be used (as in "s6") to reference an entry in the Custom Sound Effect Reference Listing. Otherwise,
the ID is taken as an entry in the Required Sound Effect Reference Listing.
The "R" or "r" tags may be used to obtain the ID value from a Register.
- Flag
This value specifies how to play the given Sound Effect:
0 | - | _Snd_Once | - | Play once |
1 | - | _Snd_Repeat | - | Loop infinitely |
2 | - | _Snd_Overpower | - | "Overpower" (Music and other SFX are suspended until this Sound finishes playing) |
_StopSound_CurrPlayer
_StopSound_FetchedPlayer
(ALL) (Example)
Stops a Sound Effect referenced by the Player's Sound Effect Reference Listing.
The "_CurrPlayer" versions retrieve the reference from the "Current Player".
The "_FetchedPlayer" versions retrieve the reference from the Player "Fetched" to "Reference 0".
Parameters:
- Entry ID
ID number of the entry within the Player's Sound Effect Reference Listing that references the desired Sound Effect
The lower-case "s" tag may be used (as in "s6") to reference an entry in the Custom Sound Effect Reference Listing. Otherwise,
the ID is taken as an entry in the Required Sound Effect Reference Listing.
The "R" or "r" tags may be used to obtain the ID value from a Register.
_PlaySound_CurrObject
_PlaySound_FetchedObject
(ALL) (Example)
Plays a Sound Effect referenced by the Object's Sound Effect Reference Listing.
The "_CurrObject" versions retrieve the reference from the "Current Object".
The "_FetchedObject" versions retrieve the reference from the Object "Fetched" to "Reference 0".
Parameters:
- Entry ID
ID number of the entry within the Object's Sound Effect Reference Listing that references the desired Sound Effect
The "R" or "r" tags may be used to obtain the ID value from a Register.
- Flag
This value specifies how to play the given Sound Effect:
0 | - | _Snd_Once | - | Play once |
1 | - | _Snd_Repeat | - | Loop infinitely |
2 | - | _Snd_Overpower | - | "Overpower" (Music and other SFX are suspended until this Sound finishes playing) |
_StopSound_CurrObject
_StopSound_FetchedObject
(ALL) (Example)
Stops a Sound Effect referenced by the Object's Sound Effect Reference Listing.
The "_CurrObject" versions retrieve the reference from the "Current Object".
The "_FetchedObject" versions retrieve the reference from the Object "Fetched" to "Reference 0".
Parameters:
- Entry ID
ID number of the entry within the Object's Sound Effect Reference Listing that references the desired Sound Effect
The "R" or "r" tags may be used to obtain the ID value from a Register.
Examples:
#_PlayMusic ;Play Game-global Music 4
: G4 ;Game-global Music 4
; ----------
#_PlayMusic ;Play "Zone"-specific Music 6
: Z6 ;"Zone"-specific Music 6
; ----------
#_PlayMusic ;Play "Act"-specific Music 3
: A3 ;"Act"-specific Music 3
; ----------
#_PlayMusic ;Play the Music whose ID is stored in "User Register" 1
: R1 ;Music whose ID is stored in "User Register" 1
_PlayTempMusic
(Description)
#_PlayTempMusic ;Temporarily load and play the music at ID 0 in the Music Def given by Game-global Text 4
: G4 ;(TextID) Game-global Text 4
: 0 ;(MusID) Music ID 0 in the Music Def referenced by the given Text
; ----------
#_PlayTempMusic ;Temporarily load and play the music at the ID that is stored in "User Register 9" from the Music Def given by the Text whose ID is stored in "User Register 8"
: R8 ;(TextID) Text whose ID is stored in "User Register" 8
: R9 ;(MusID) Music whose ID 0 in the Music Def referenced by the given Text is stored in "User Register" 9
_PlayJingle
(Description)
#_PlayJingle ;Play Game-global Music 4 as a "Jingle", temporarily interrupting the current Music and silencing Sound Effects
: G4 ;Game-global Music 4
; ----------
#_PlayJingle ;Play "Zone"-specific Music 6 as a "Jingle", temporarily interrupting the current Music and silencing Sound Effects
: Z6 ;"Zone"-specific Music 6
; ----------
#_PlayJingle ;Play "Act"-specific Music 3 as a "Jingle", temporarily interrupting the current Music and silencing Sound Effects
: A3 ;"Act"-specific Music 3
; ----------
#_PlayMusic ;Play the Music whose ID is stored in "User Register" 1 as a "Jingle", temporarily interrupting the current Music and silencing Sound Effects
: R1 ;Music whose ID is stored in "User Register" 1
_PauseMusic
(Description)
#_PauseMusic ;Suspend Music Playback
_ContinueMusic
(Description)
#_ContinueMusic ;Resume Music Playback
_FadeMusic
(Description)
#_FadeMusic ;Fade music out to silence
: 0 ;Minimum (Silent)
; ----------
#_FadeMusic ;Fade music in to full volume
: 64 ;Maximum
; ----------
#_FadeMusic ;Fade music to the volume value stored in "User Register" 15
: R15 ;Value stored in "User Register" 15
_SetMusicVol
(Description)
#_SetMusicVol ;Immediately set Music volume to silence
: 0 ;Minimum (Silent)
; ----------
#_SetMusicVol ;Immediately set Music volume to full
: 64 ;Maximum
; ----------
#_SetMusicVol ;Immediately set Music volume to the value stored in "User Register" 3
: R3 ;Value stored in "User Register" 3
_XM_SetSpeedMod
(Description)
#_XM_SetSpeedMod ;Set XM Speed Modifier to 0 [no modifier] for normal speed
: 0 ;(Speed) Normal Speed (BPM)
; ----------
#_XM_SetSpeedMod ;Set XM Speed Modifier to 8 for double speed
: 8 ;(Speed) Double Speed (BPM * ((8+8)/8))
; ----------
#_XM_SetSpeedMod ;Set XM Speed Modifier to -8 for half speed
: -8 ;(Speed) Half Speed (BPM / ((8+8)/8))
; ----------
#_XM_SetSpeedMod ;Set XM Speed Modifier to the value stored in "User Register" 27
: u27 ;(Speed) Value stored in "User Register" 27
_XM_SetPitchMod
(Description)
#_XM_SetPitchMod ;Set XM Pitch Modifier to 0 [no modifier] for normal Pitch
: 0 ;(Pitch) Normal Pitch (BPM)
; ----------
#_XM_SetPitchMod ;Set XM Pitch Modifier to 64 to pitch up by 1 note
: 64 ;(Pitch) 64 "FineTunes" (one note)
; ----------
#_XM_SetPitchMod ;Set XM Pitch Modifier to -64 to pitch down by 1 note
: -64 ;(Pitch) -64 "FineTunes" (one note)
; ----------
#_XM_SetPitchMod ;Set XM Pitch Modifier to the value stored in "User Register" 11
: u11 ;(Pitch) Value stored in "User Register" 11
_XM_SetChanMute
(Description)
#_XM_SetChanMute ;Set Channel 0 of the currently-playing XM song to "Muted"
: 1 ;(Chan) XM Channel 1
: 1 ;(Mute) Mute; inaudible
; ----------
#_XM_SetChanMute ;Set Channel 9 of the currently-playing XM song to "Unmuted"
: 9 ;(Chan) XM Channel 2
: 0 ;(Mute) Unmute; audible
; ----------
#_XM_SetChanMute ;Set the "Mute" status of the Channel whose ID is stored in "User Register" 4 to the Value stored in "User Register" 5"
: R4 ;(Chan) Channel whose ID is stored in "User Register" 4
: R5 ;(Mute) Value stored in "User Register" 5"
_XM_SetEventFunc
(Description)
#_XM_SetEventFunc ;Set Game-global Function 13 to run whenever an XM song encounters a "Zxx" Effect
: G13 ;(FuncID) Game-global Function 13
; ----------
#_XM_SetEventFunc ;Set "Zone"-specific Function 2 to run whenever an XM song encounters a "Zxx" Effect
: Z2 ;(FuncID) "Zone"-specific Function 2
; ----------
#_XM_SetEventFunc ;Set "Act"-specific Function 0 to run whenever an XM song encounters a "Zxx" Effect
: A0 ;(FuncID) "Act"-specific Function 0
; ----------
#_XM_SetEventFunc ;Set the Function whose ID is stored in "User Register" 7 to run whenever an XM song encounters a "Zxx" Effect
: R7 ;(FuncID) Function whose ID is stored in "User Register" 7
_XM_DoEffect
(Description)
#_XM_DoEffect ;Call XM Effect $0B with Parameter of 4 [Branch to Pattern 4] to run on the Channel that triggered the Event Function
: $0B ;(Effect) XM Effect $0B (Pattern Branch)
: 4 ;(Param) Parameter value of 4 (For "Branch", Branch to Pattern 4)
; ----------
#_XM_DoEffect ;Call the XM Effect whose ID is stored in "User Register" 1 with the Parameter Value stored in "User Register" 2 to run on the Channel that triggered the Event Function
: R1 ;(Effect) XM Effect whose ID is stored in "User Register" 1
: R2 ;(Param) Value stored in "User Register" 2
Sound Effects:
#_PlaySound ;Play Game-global Sound Effect 38 once
: G38 ;(ID) Game-global Sound Effect 38
:_Snd_Once ;(Loop)
; ----------
#_PlaySound ;Play and loop "Zone"-specific Sound Effect 5
: Z5 ;(ID) "Zone"-specific Sound Effect 5
:_Snd_Loop ;(Loop)
; ----------
#_PlaySound ;Play "Act"-specific Sound Effect 1, causing music and all other Sounds to suspend until this Sound Effect is finished
: A1 ;(ID) "Act"-specific Sound Effect 1<
:_Snd_Overpower ;(Loop)
; ----------
#_PlaySound ;Play the Sound Effect whose ID is stored in "User Register" 6 once
: R6 ;(ID) Value stored in "User Register" 6
:_Snd_Once ;(Loop)
_StopSound
(Description)
#_StopSound ;Stop "Zone"-specific Sound Effect 3
: Z3 ;(ID) "Zone"-specific Sound Effect 3
; ----------
#_StopSound ;Stop the Sound Effect whose ID is stored in "User Register" 18 once
: R18 ;(ID) Value stored in "User Register" 18
_PauseSFX
(Description)
#_PauseSFX ;Suspend Sound Effect Playback
_ContinueSFX
(Description)
#_ContinueSFX ;Resume Sound Effect Playback
_FadeSFX
(Description)
#_FadeSFX ;Fade Sound Effects out to silence
: 0 ;Minimum (Silent)
; ----------
#_FadeSFX ;Fade Sound Effects in to full volume
: 64 ;Maximum
; ----------
#_FadeSFX ;Fade Sound Effects to the volume value stored in "User Register" 15
: R15 ;Value stored in "User Register" 15
_SetSFXVol
(Description)
#_SetSFXVol ;Immediately set Sound Effect volume to silence
: 0 ;Minimum (Silent)
; ----------
#_SetSFXVol ;Immediately set Sound Effect volume to full
: 64 ;Maximum
; ----------
#_SetSFXVol ;Immediately set Sound Effect volume to the value stored in "User Register" 3
: R3 ;Value stored in "User Register" 3
_PlaySound_CurrPlayer
_PlaySound_FetchedPlayer
(Description)
#_PlaySound_CurrPlayer ;Play and loop the Sound referenced by entry 1 in the Sound Reference List for the "Current Player"
: 1 ;(ID) Sound referenced by entry 1 in the Sound Reference List for the "Current Player"<
:_Snd_Loop ;(Loop)
; ----------
#_PlaySound_FetchedPlayer ;Play the Sound referenced by the Sound Reference List entry whose value is stored in "User Register" 6 for the Player "Fetched" to "Reference 0" once
: R6 ;(ID) Value stored in "User Register" 6
:_Snd_Once ;(Loop)
_StopSound_CurrPlayer
_StopSound_FetchedPlayer
(Description)
#_StopSound_CurrPlayer ;Stop the Sound referenced by entry 1 in the Sound Reference List for the "Current Player"
: 1 ;(ID) Sound referenced by entry 1 in the Sound Reference List for the "Current Player"<
; ----------
#_StopSound_FetchedPlayer ;Stop the Sound referenced by the Sound Reference List entry whose value is stored in "User Register" 6 for the Player "Fetched" to "Reference 0"
: R6 ;(ID) Value stored in "User Register" 6
_PlaySound_CurrObject
_PlaySound_FetchedObject
(Description)
#_PlaySound_CurrObject ;Play and loop the Sound referenced by entry 3 in the Sound Reference List for the "Current Object"
: 3 ;(ID) Sound referenced by entry 3 in the Sound Reference List for the "Current Object"<
:_Snd_Once ;(Loop)
; ----------
#_PlaySound_FetchedObject ;Play the Sound referenced by the Sound Reference List entry whose value is stored in "User Register" 21 for the Object "Fetched" to "Reference 0" once
: R21 ;(ID) Value stored in "User Register" 21
:_Snd_Loop ;(Loop)
_StopSound_CurrObject
_StopSound_FetchedObject
(Description)
#_StopSound_CurrObject ;Stop the Sound referenced by entry 3 in the Sound Reference List for the "Current Object"
: 3 ;(ID) Sound referenced by entry 3 in the Sound Reference List for the "Current Object"<
; ----------
#_StopSound_FetchedObject ;Stop the Sound referenced by the Sound Reference List entry whose value is stored in "User Register" 21 for the Object "Fetched" to "Reference 0"
: R21 ;(ID) Value stored in "User Register" 21