S_StartSoundAt
Jump to navigation
Jump to search
native static void S_StartSoundAt(Vector3 pos, 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 attached to a poisition, not an actor. Like S_StartSound, this can be called in any scope and from any Object.
| 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 and S_StartSound.
- Vector3 pos
- The world position to play the sound from.
- 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_StartSoundAt 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
- This is a positive value that specifies how quickly the sound fades with distance from its source. The exact formula for attenuation is: attenuation = default max hearable distance / desired max hearable distance. So, for example, in Doom the default max hearable distance is 1200; with attenuation of 20 the max hearable distance for the sound will be 60 map units (1200 / 20 = 60). This argument also accepts the following predefined constants:
- ATTN_NONE — Plays the sound globally at the specified volume, disregarding distance.
- ATTN_NORM — Uses the close_dist and clipping_dist fields defined in the sound definition. Default.
- ATTN_IDLE — Uses Doom's normal default sound attenuation behavior.
- ATTN_STATIC — Fades quickly (inaudible from 512 units).
- 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. |