Nuclide
Software Development Kit for id Tech
Sound Definitions

SoundDef system functions. More...

Classes

struct  snd_t
 A soundDef aka 'sound shader' type. More...
 
struct  sound_t
 A sound sample of a sentences.txt word sequence. More...
 

Macros

#define SndLog(...)   if (autocvar_s_logLevel >= LOGLEVEL_DEBUG) _SndLog(__FUNC__, sprintf(__VA_ARGS__))
 Logs an sound system specific log message. More...
 
#define SndEntLog(...)   if (autocvar_s_logLevel >= LOGLEVEL_DEBUG) _SndEntLog(classname, __FUNC__, num_for_edict(this), sprintf(__VA_ARGS__))
 Logs an sound specific entity class log message. More...
 

Functions

void _SndLog (string functionName, string msg)
 
void _SndEntLog (string className, string functionName, float edictNum, string warnMessage)
 
void Sound_Init (void)
 Called by the client inside CSQC_Init(), and on the server inside init(). More...
 
void Sound_Shutdown (void)
 Called by CSQC_Shutdown() and in theory, somewhere on the server. More...
 
int Sound_Precache (string sndDef)
 Force the precache of a soundDef file. More...
 
void Sound_Play (entity targetEntity, int sndChannel, string sndDef)
 Play a soundDef on a given target entity. More...
 
void Sound_PlayAt (vector worldPos, string sndDef)
 Play a soundDef a a given location. More...
 
void Sound_PlayLocal (string shader)
 Client-side only: Play a sound locally, outside the game world. More...
 
void Sound_Update (entity targetEntity, int sndChannel, int sndSample, float desiredVolume)
 Client-side only: Update the sound parameters on a given entity. More...
 
int Sound_GetID (string sndDef)
 
void Sound_Stop (entity target, int chan)
 Stops sounds on a given channel, on a target entity. More...
 
void Sound_DebugList ()
 Called by listSoundDef. More...
 

Variables

float maxspeed
 
float flags
 
var logLevel_t autocvar_s_logLevel = LOGLEVEL_DEFAULT
 
var hashtable g_hashsounds
 Global hash table for name > soundDef id lookup. More...
 
typedef enumflags
 Enumeration of valid sound flags. More...
 
snd_tg_sounds
 Pointer to the global soundDef table. More...
 
int g_sounds_count
 Total amount of registered soundDef entries. More...
 

Detailed Description

SoundDef system functions.

SoundDefs

Nuclide mimics the sound defintion spec from id Tech 4 somewhat, albeit with some changes/enhancements. We call them soundDefs.

The elevator pitch**: To allow for more control over the sounds than what was previously allowed in id Tech engines we also allow designers to drop sounds into the game without having to set some common parameters every time.

Instead of directly calling which .wav or .ogg file to play, we tell it to play the single name of a sound def. For example: c1_sentry_loader_in* which can be located in any text file ending with the **.sndshd** file extension inside the sound/ directory.

c1_sentry_loader_in
{
dist_min 10
dist_max 25
no_occlusion
volume 0.25
sample sound/movers/comm1/sentry_loader_in.wav
}

Let's take a look at another one:

emetal_impacts
{
dist_min 5
dist_max 45
volume 0.5
sample sound/impact/ambient_impacts/emetal_01.wav
sample sound/impact/ambient_impacts/emetal_02.wav
sample sound/impact/ambient_impacts/emetal_03.wav
sample sound/impact/ambient_impacts/emetal_04.wav
sample sound/impact/ambient_impacts/emetal_05.wav
}

This one has multiple sound files specified, which means that Nuclide will randomly choose one to play.

Commands

Key Value Description
attenuation idle/static/none/normal Changes the sound's attenuation, aka playback radius/distance. This essentially just changes dist_max.
dist_min <float> Sets the minimum playback distance in quake units.
dist_max <float> Sets the maximum playback distance in quake units.
volume <float> Sets the playback volume. 0.0 - 1.0 range.
shakes <float> Will shake the screen with an intensity specified. Play around with this, 256 is a good starting value.
pitch <float> Will set a specific pitch change. 0.0 - 2.0 range most commonly, but there's wiggle room.
pitch_min <float> Will set a minimum pitch instead of an exact one. This means it'll play a random pitch between min and max.
pitch_max <float> Will set a maximum pitch instead of an exact one. This means it'll play a random pitch between min and max.
offset <float> Sound sample offset in seconds.
looping none Sound set to force loop, regardless of sound markers in file.
nodups none Don't play duplicate samples in sequence.
global none Play samples everywhere.
private none Play samples privately onto the entity that it gets played on.
no_reverb none Disable any EAX on samples in this def.
omnidirectional none Samples won't play from any particular direction.
follow none Samples will move alongside the entity it's being played on
footstep none Determines sample volume based upon the speed of the entity.
distshader <string> Which sound def to play to everyone who is out of playback reach of this one.
sample <string> Adds a sample to play to the list. Will only play one at a time.

Power to the developer

Unlike the implementation in id Tech 4, all of the sound defs handling is done in the game-logic and is therefore exposed to all developers. Some mods may want to hook AI callbacks into the system, or create visual effects when commands are called by a sound def. The possibilities are endless!

Macro Definition Documentation

◆ SndEntLog

#define SndEntLog (   ...)    if (autocvar_s_logLevel >= LOGLEVEL_DEBUG) _SndEntLog(classname, __FUNC__, num_for_edict(this), sprintf(__VA_ARGS__))

Logs an sound specific entity class log message.

The console variable s_developer has to be 1 for them to be visible.

Parameters
description(...)contains a formatted string containing a description.

◆ SndLog

#define SndLog (   ...)    if (autocvar_s_logLevel >= LOGLEVEL_DEBUG) _SndLog(__FUNC__, sprintf(__VA_ARGS__))

Logs an sound system specific log message.

The console variable s_developer has to be 1 for them to be visible.

Parameters
description(...)contains a formatted string containing a description.

Function Documentation

◆ _SndEntLog()

void _SndEntLog ( string  className,
string  functionName,
float  edictNum,
string  warnMessage 
)

◆ _SndLog()

void _SndLog ( string  functionName,
string  msg 
)

◆ Sound_DebugList()

void Sound_DebugList ( )

Called by listSoundDef.

◆ Sound_GetID()

int Sound_GetID ( string  sndDef)

◆ Sound_Init()

void Sound_Init ( void  )

Called by the client inside CSQC_Init(), and on the server inside init().

◆ Sound_Play()

void Sound_Play ( entity  targetEntity,
int  sndChannel,
string  sndDef 
)

Play a soundDef on a given target entity.

◆ Sound_PlayAt()

void Sound_PlayAt ( vector  worldPos,
string  sndDef 
)

Play a soundDef a a given location.

◆ Sound_PlayLocal()

void Sound_PlayLocal ( string  shader)

Client-side only: Play a sound locally, outside the game world.

◆ Sound_Precache()

int Sound_Precache ( string  sndDef)

Force the precache of a soundDef file.

◆ Sound_Shutdown()

void Sound_Shutdown ( void  )

Called by CSQC_Shutdown() and in theory, somewhere on the server.

◆ Sound_Stop()

void Sound_Stop ( entity  target,
int  chan 
)

Stops sounds on a given channel, on a target entity.

◆ Sound_Update()

void Sound_Update ( entity  targetEntity,
int  sndChannel,
int  sndSample,
float  desiredVolume 
)

Client-side only: Update the sound parameters on a given entity.

Variable Documentation

◆ autocvar_s_logLevel

var logLevel_t autocvar_s_logLevel = LOGLEVEL_DEFAULT

◆ enumflags

typedef enumflags
Initial value:
{
SNDFL_LOOPING,
SNDFL_NODUPS,
SNDFL_GLOBAL,
SNDFL_NOREVERB,
SNDFL_OMNI,
SNDFL_PRIVATE,
SNDFL_STEP,
SNDFL_FOLLOW,
SNDFL_ALERTS
} soundFlag_t

Enumeration of valid sound flags.

forceloop don't random the samples no attenuation skip reverb volume on all channels is equal only play on target volume is calculated from entity speed sample follows entity as it plays this sounds alerts AI, takes distance into account

◆ flags

float flags

◆ g_hashsounds

var hashtable g_hashsounds

Global hash table for name > soundDef id lookup.

◆ g_sounds

snd_t* g_sounds

Pointer to the global soundDef table.

◆ g_sounds_count

int g_sounds_count

Total amount of registered soundDef entries.

◆ maxspeed

float maxspeed