SoundDef system functions. 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
}

dist_min / dist_max sets the radius where the sound fades out. The sound is at maximum volume inside 'dist_min' radius, and it completely silent after 'dist_max' radius.
The no_occlusion key tells the engine not to take level geometry in to account when calculating volume.
'volume' is the volume inside the inner radius of the sound.
The last line sets the actual sound file to play.

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!

Classes
struct	sound_t
	A sound sample of a sentences.txt word sequence. More...

Functions
void	_SndLog (string functionName, string msg)

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

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

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

int	SoundDef_Precache (string sndDef)
	Force the precache of a soundDef file.

void	SoundDef_Play (entity targetEntity, int sndChannel, string sndDef)
	Play a soundDef on a given target entity.

void	SoundDef_PlayAt (vector worldPos, string sndDef)
	Play a soundDef a a given location.

void	SoundDef_PlayLocal (string shader)
	Client-side only: Play a sound locally, outside the game world.

void	SoundDef_Update (entity targetEntity, int sndChannel, int sndSample, float desiredVolume)
	Client-side only: Update the sound parameters on a given entity.

int	SoundDef_GetID (string sndDef)

void	SoundDef_Stop (entity target, float chan)
	Stops sounds on a given channel, on a target entity.

void	SoundDef_DebugList ()
	Called by listSoundDef.

Macros
#define	SndLog(...)
	Logs an sound system specific log message.

#define	SndEntLog(...)
	Logs an sound specific entity class log message.

Variables
float	maxspeed

float	flags

var logLevel_t	autocvar_s_logLevel = LOGLEVEL_DEFAULT

Function Documentation

◆ _SndEntLog()

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

◆ _SndLog()

void _SndLog	(	string	functionName,
		string	msg )

◆ SoundDef_DebugList()

void SoundDef_DebugList ( )

Called by listSoundDef.

◆ SoundDef_GetID()

int SoundDef_GetID ( string sndDef )

◆ SoundDef_Init()

void SoundDef_Init ( void )

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

◆ SoundDef_Play()

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

Play a soundDef on a given target entity.

◆ SoundDef_PlayAt()

void SoundDef_PlayAt	(	vector	worldPos,
		string	sndDef )

Play a soundDef a a given location.

◆ SoundDef_PlayLocal()

void SoundDef_PlayLocal ( string shader )

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

◆ SoundDef_Precache()

int SoundDef_Precache ( string sndDef )

Force the precache of a soundDef file.

◆ SoundDef_Shutdown()

void SoundDef_Shutdown ( void )

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

◆ SoundDef_Stop()

void SoundDef_Stop	(	entity	target,
		float	chan )

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

◆ SoundDef_Update()

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

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

Macro Definition Documentation

◆ SndEntLog

#define SndEntLog ( ... )

Value:

if (autocvar_s_logLevel >= LOGLEVEL_DEBUG) _SndEntLog(classname, __FUNC__, num_for_edict(this), sprintf(__VA_ARGS__))

autocvar_s_logLevel

var logLevel_t autocvar_s_logLevel

Definition soundDef.h:116

_SndEntLog

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

Definition soundDef.h:133

Logs an sound specific entity class log message.

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

Parameters

...	contains a formatted string containing a description.

◆ SndLog

#define SndLog ( ... )

Value:

if (autocvar_s_logLevel >= LOGLEVEL_DEBUG) _SndLog(__FUNC__, sprintf(__VA_ARGS__))

_SndLog

void _SndLog(string functionName, string msg)

Definition soundDef.h:118

Logs an sound system specific log message.