A_StartSoundIfNotSame
Jump to navigation
Jump to search
native clearscope void A_StartSoundIfNotSame(sound whattoplay, sound checkagainst', int slot = CHAN_BODY, int flags = 0, double volume = 1.0, double attenuation = ATTN_NORM, double pitch = 0.0, double startTime = 0.0)
Usage
Plays the specified sound only if it is different from the one to check against.
The two sounds are considered different if they have different names. For aliases, the function checks the name of the sound which is referenced by the alias in order to make a decision. A random sound's assigned set of sounds is of no consequence, as the function only checks the sound's name.
Parameters
- Sound whattoplay
- The desired sound to play, as defined in SNDINFO.
- Sound checkagainst
- The sound to compare to, as defined in SNDINFO. If this sound is playing, whattoplay sound will not be played.
- int slot
- The sound slot used for the sound. Unlike A_PlaySound, the slot is not limited to predefined slots and can be any positive number other than 0 (which enables special behavior). The predefined slots are:
- 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, for historical reasons.
- CHAN_5 (5)
- CHAN_6 (6)
- CHAN_7 (7)
- int flags
- Adjusts how the sound is played. Multiple flags can be combined with
|
:- CHANF_DEFAULT — No flags. Default.
- CHANF_LISTENERZ — Play the sound from the listener's Z position instead of the caller's.
- CHANF_MAYBE_LOCAL — Sound is subject to compat_silentpickup and will not play if started by an actor other than the listener when the compatibility flag is enabled.
- CHANF_UI — Sound isn't preserved in saves and will play while the game is paused.
- CHANF_NOPAUSE — Don't pause the sound.
- CHANF_LOOP — Loops the sound.
- CHANF_OVERLAP — Don't stop any sounds in the channel and instead play over them.
- CHANF_LOCAL — Only play the sound if the listener is the one doing so.
- CHANF_NOSTOP — If the channel is occupied, do not play the sound.
- CHANF_TRANSIENT — Sound isn't preserved in saves. Note: As of GZDoom 4.13.1, while the flag is exported to ZScript, the constant for it isn't. Instead, its bit value can be passed directly:
32768
. - CHANF_FORCE — Play the sound even if it will be immediately paused upon doing so.
- CHANF_LOOPING — Combines CHANF_LOOP and CHANF_NOSTOP. It is equivalent to the looping parameter of A_PlaySound.
- 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. |