S_StartSound
Jump to navigation
Jump to search
native static void S_StartSound(Sound sound_id, int channel, int flags = 0, float volume = 1, float attenuation = ATTN_NORM, float pitch = 0.0, float startTime = 0.0)
Usage
Plays a sound, similar to A_StartSound, but not attached to an actor. This can be called in any scope, and, in contrast to A_StartSound, can be played from UI, for example, from a custom menu. However, this sound cannot originate from a point in the world.
| Note: Audio files can NOT be played directly from ZScript. A sound must be defined in SNDINFO first, then its SNDINFO name can be referenced in ZScript. |
Parameters
The parameters are similar to those used by A_StartSound, but with different names and sometimes different defaults.
- Sound sound_id
- The sound to play, as defined in SNDINFO.
- int channel
- CHAN_AUTO (0) — Explicitly plays the sound with the CHANF_OVERLAP flag enabled (even if it's not passed). This means that all sounds passed to this channel will play over each other, never interrupting one another. Before GZDoom 4.4.0 CHAN_AUTO used to pick the first unoccupied channel, but this behavior was dropped when the ability to play multiple sounds on the same channel was added.
- CHAN_WEAPON (1)
- CHAN_VOICE (2)
- CHAN_ITEM (3)
- CHAN_BODY (4) — The default for A_StartSound / A_PlaySound (but not S_StartSound), for historical reasons.
- CHAN_5 (5)
- CHAN_6 (6)
- CHAN_7 (7)
- Note: these channels are global (since this function is not called by an actor), an in contrast to A_StartSound will not cause one sound to stop another. (Clarificaton needed: Do these serve any purpose?)
- int flags
- Adjusts how the sound is played. While the same flags as those used by A_StartSound can be passed, not all of them have a meaningful effect since S_StartSound isn't played from an actor. Multiple flags can be combined with
|:- CHANF_DEFAULT — No flags (default).
- CHANF_UI — Sound isn't preserved in saves and will play while the game is paused.
- CHANF_TRANSIENT — Sound isn't preserved in saves.
- CHANF_FORCE — Play the sound even if it will be immediately paused upon doing so.
- CHANF_LOOP — Loops the sound. Note, if the function is called multiple times with the this flag, the sounds will keep looping and overlaying, causing distortions.
- Other flags used by A_StartSound are not supported by S_StartSound; this includes CHANF_LOOPING and CHANF_NOSTOP: when S_StartSound is called, it will ALWAYS play the sound and will not be aware of other sounds that may be playing due to an earlier S_StartSound call.
- double volume
- The volume of the sound, which ranges from 0 to 1.0. Default 1.0.
- double attenuation
- Does nothing, since the sound has no origin point.
- double pitch
- The sound pitch to play the sound with. Default is 0, which means the engine uses whatever pitch shift (range) that is defined in SNDINFO, if any. For non-zero values anything lower than 1.0 will slow down the sound, while higher values speed it up.
- double startTime
- Sets how much of the sound to skip when starting. The value can be anywhere between 0 and 1.0, translating to 0% to 100%. Default is 0.
Examples
|
Note: This article lists no examples. If you make use of this feature in your own project(s) or know of any basic examples that could be shared, please add them. This will make it easier to understand for future authors seeking assistance. Your contributions are greatly appreciated. |