Sound

From Blue Mars Developer Guidebook

Jump to: navigation, search
There are security restrictions on this article

Contents

Overview

Sound designers use the FMOD Designer tool (version 1.07.23) to create a sound project, and within it, sound events and event groups.


To examine sound assets, see the Sandbox Manual

To play sounds attached to entities, use the Entity sound functions.

These functions are in the Sound table. See Game/Scripts/Entities/sound for examples (and consider using existing sound entities where appropriate)

Sound Events

A sound events consists of on or more sound assets combined with various properties, like looping, 2D or 3D, radius and attenuation. Sound events can be packaged in event groups, that can be preloaded and freed all at once, and assigned to one ore more semantic categories.

Sound events are referenced by Path/projectname:groupname:eventname. For example, the Golf minigame uses:

Sound/minigaime_golf:golf_sfx:applause

Preferably, all path, project, event and group names should be lower-case.

Precaching sounds is optional, but avoids a small delay before sounds play.

Precache(groupAndSoundName,PrecacheFlags)
precaches the sound used by a sound definition.
example - Game/Scripts/Entities/Sound/RandomSoundVolume.lua
groupAndSoundName -
PrecacheFlags - can be one or more of the bit flags
SOUND_PRECACHE_LOAD_SOUND
SOUND_PRECACHE_LOAD_GROUP
SOUND_PRECACHE_LOAD_STAY_IN_MEMORY
SOUND_PRECACHE_LOAD_UNLOAD_AFTER_PLAY

When a sound asset has been loaded and is played, the the resulting sound can be queried and controlled by referencing a unique sound ID.

Play(name, pos, soundFlags, semanticFlags)
loads and plays a sound event
returns a unique ID for the sound
name - full name of the sound event
pos - position of sound
soundFlags - one or more sound flags
semanticFlags - one or more semantic flags
example - Game/Scripts/Entities/Doors/Door.lua
PlayEx(name ,pos, soundFlags, volume, minRadius, maxRadius, semantic)
Like Play, but with more parameters
returns a unique ID for the sound
name - full name of the sound event
pos - position of sound
soundFlags - one or more sound flags
semanticFlags - one or more semantic flags
volume' - initial sound volume, ranges from 0-1
minRadius - minimum distance of sound, sound is attenuated below this
maxRadius- maximum distance of sound, sound is not heard beyond this distance
semantic - one or more semantic flags
example - Game/Scripts/Entities/Sound/RandomSoundVolume.lua

The sound flags parameter is a combination of one or more of the following bit flags:

SOUND_DEFAULT_3D
combines SOUND_CULLING and SOUND_OBSTRUCTION
SOUND_LOOP
SOUND_2D
SOUND_3D
SOUND_STEREO
SOUND_STREAM
streamed WAV
SOUND_RELATIVE
sound position moves relative to player
SOUND_RADIUS
sound has a radius with custom attenuation calculation
SOUND_DOPPLER
use doppler effect
SOUND_NO_SW_ATTENUATION
don't use software attenuation
SOUND_MUSIC
pure music sound
SOUND_OUTDOOR
play only if the listener is outdoor
SOUND_INDOOR
play only if the listener is indoor
SOUND_UNSCALABLE
can be scaled separately from master volume
SOUND_CULLING
use sound occlusion, based on VisAreas
SOUND_LOAD_SYNCRHONOUSLY
load the sound synchronously (default is asynchronous)
SOUND_FADE_OUT_UNDERWATER
SOUND_OBSTRUCTION
use sound obstruction, based on ray-world intersection
SOUND_SELFMOVING
sound automatically moves according to direction vector
SOUND_START_PAUSED
start sound in paused state - call to unpause is needed to really play
SOUND_VOICE
sound is used as a voice (sub-titles and lip-sync can be applied)
SOUND_EVENT
sound is used as a sound event
SOUND_VOLUMESCALEMISSIONHINT

The semantic flags paramter is a combination of one or more of the following:

SOUND_SEMANTIC_AMBIENCE
SOUND_SEMANTIC_AMBIENCE_ONESHOT
SOUND_SEMANTIC_PHYSICS_COLLISION
SOUND_SEMANTIC_DIALOG
SOUND_SEMANTIC_MP_CHAT
SOUND_SEMANTIC_PHYSICS_GENERAL
SOUND_SEMANTIC_HUD
SOUND_SEMANTIC_FLOWGRAPH
SOUND_SEMANTIC_LIVING_ENTITY
SOUND_SEMANTIC_MECHANIC_ENTITY
SOUND_SEMANTIC_NANOSUIT
SOUND_SEMANTIC_SOUNDSPOT
SOUND_SEMANTIC_PARTICLE
SOUND_SEMANTIC_AI_PAIN_DEATH
SOUND_SEMANTIC_AI_READABILITY
SOUND_SEMANTIC_AI_READABILITY_RESPONSE
SOUND_SEMANTIC_TRACKVIEW
SOUND_SEMANTIC_PROJECTILE
SOUND_SEMANTIC_VEHICLE
SOUND_SEMANTIC_WEAPON
SOUND_SEMANTIC_EXPLOSION
SOUND_SEMANTIC_PLAYER_FOLEY
SOUND_SEMANTIC_PLAYER_FOLEY_VOICE
SOUND_SEMANTIC_ANIMATION
IsPlaying(id)
returns boolean indicating whether the sound is still playing
id - sound ID
example - Game/Scripts/Entities/actor/BasicActor.lua - DoPainSounds checks if pain sound is still playing
GetSoundLength(id)
returns length of sound stream in milliseconds - 0 if looping
id - sound ID
example - Game/Scripts/AI/Behaviors/Personalities/SHARED/Jobs/Job_GenericIdle.lua
SetParameterValue(soundID,parameterName,parameterValue)
set sound event parameter value
soundID - ID of the sound
parameterName - string parameter name, e.g. "pitch"
parameterValue - float parameter value
example - Game/Scripts/Entities/Sound/RandomSoundVolume.lua
LoadSound(soundEvent,soundFlags,volume)
load a 2D sound, without playing
return the sound ID or nil if unsuccessful
soundEvent - the sound event name
soundFlags - optional, one or more sound flags, defaults to 0
volume - optional, initial sound volume, from 0-1
examples - none (removed in Game/Scripts/Entities/Sound/MissionHint.lua)
Load3DSound(soundEvent, soundFlags, volume, minDistance, maxDistance, priority, groups)
load a 3D sound, without playing
return the sound ID or nil if unsuccessful
soundEvent - the sound event name
soundFlags - optional, one or more sound flags, defaults to 0
volume - optional, initial sound volume, from 0-1
minDistance - optional, minimum sound distance, attenuated if closer
maxDistance - optional, maximum sound distance, not heard if beyond
priority - optional, sound priority
groups;; - optional, groups
examples - Game/Scripts/AI/Behaviors/Personalities/SHARED/Jobs/Job_GenericIdle.lua
LoadStreamSound(soundEvent)
load a streaming sound without playing
returns the sound ID or nil if unsuccessful
soundEvent - name of the sound event
flags - optional, sound flags to use (automatically added to FLAG_SOUND_STREAM)
examples - none
PlaySound(soundID,volume)
starts playing a sound, looping if enabled
no return value
soundID -
volume - optional, volume at which to play the sound, defaults to 1.0
example - Game/Scripts/Entities/Physics/Rope.lua
SetSoundPaused(soundID,paused)
set the pause state of a sound
no return value
soundID - the sound ID
paused - true to pause, false to unpause
example - Game/Scripts/Entities/Sound/AmbientVolume.lua
StopSound(soundID)
stop playing a sound
no return value
soundID - the sound ID
example - Game/Scripts/Entities/Sound/RandomSoundVolume.lua


SetSoundVolume(soundID, volume)
set the volume of a sound
no return value
soundID - the sound ID
volume - volume, from 0.0-1.0
example - Game/Scripts/Entities/Sound/AmbientVolume.lua
GetSoundVolume(soundID)
returns the volume of a sound, or zero if not a valid sound ID
soundID - the sound ID
example - Game/Scripts/Entities/Sound/AmbientVolume.lua
SetSoundLoop(soundID, loop)
enable/disable looping of a sound
no return value
'soundID - the sound ID
loop - 0 to disable, 1 to enable
example - Game/Scripts/Entities/Sound/MissionHint.lua
SetSoundFrequency(soundID, frequency)
sets the pitch of a sound
no return value
soundID - the sound ID
frequency - an interger from 0-1000
examples - none
SetSoundPitching(soundID, pitching)
sets automatic pitching amount for a sound
no return value
soundID - the sound ID
pitching - a float
SetSoundRelative(soundID, relative)
enables/disables relative positioning of sound
no return value
soundID - the sound ID
relative - true to enable, false to disable (position must be reset after this)
example - none
SetSoundPosition(soundID,pos)
set the position of a sound source
soundID - the sound ID
pos - the new position, a vector
example - Game/Scripts/Entities/Physics/Rope.lua
SetSoundSpeed(soundID, velocity)
set the velocity of a sound source
no return value
soundID - the sound ID
velocity - a vector
example - none
SetMinMaxDistance(soundID,min,max)
set distance attenuation of a sound
no return value
soundID - the sound ID
min - minimum distance, sound is attenuated below this
max - sound is inaudible beyond this
example - Game/Scripts/Entities/Sound/SoundSpot.lua
SetFadeTime(soundID,fadeGoal,fadeTime)
set the fade time of a sound
no return value
soundID - the sound ID
fadeGoal - 0.0 to fade out, 1.0 to fade in
fadeTime - fade time in milliseconds
example - Game/Scripts/Entities/Sound/AmbientVolume.lua
SetMasterVolumeScale(volume)
set the volume scale for all sounds wiht FLAG_SOUND_SCALABLE
volume - a float
SetPauseAllPlaying(pause)
pause - boolean, true to pause, false to unpause
FxEnable(soundID,effectNumber)
enable FX for this sound
must be called after each play
soundID - sound ID
effectNumber
example - none

Audio Device

DeactivateAudioDevice()
deactivate audio device so wavebanks can be overwritten
ActivateAudioDevice
reactivate the audio device

Groups

AddToScaleGroup
RemoveFromScaleGroup
SetGroupScale
SOUNDSCALE_MASTER
SOUNDSCALE_SCALEABLE
SOUNDSCALE_DEAFNESS
SOUNDSCALE_UNDERWATER
SOUNDSCALE_MISSIONHINT

EAX

For reverb effects. See Game/Scripts/Entities/Sound/ReverbVolume.lua

RegisterWeightedEaxEnvironment(name,fullEffectWhenInside)
registers an EAX preset area as being activate
morphing of multiple preset areas is done internally
overwrites previous registration of this preset
'name - name of the preset, a string
fullEffectWhenInside - optional, boolean
UpdateWeightedEaxEnvironment(name,weight)
updates a preset area with a blending ratio
name - preset name, a string
weight - new blending ratio, 0.0-1.0
UnregisterWeightedEaxEnvironment(name)
unregisters an active EAX preset area
name - the preset name

Attenuation

SetDirectionalAttenuation(pos,dir,cone)
sets parameters for directional attenuation (for directional microphone effect)
no return value
pos - position
dir - direction
code - optional, cone in radians. If zero, effect is disabled.
example - none
GetDirectionalAttenuationMaxScale()
returns the maximum sound-enhance-factor to use in binoculars as a "graphic equalizer"
example - none

Music

A music theme and its various moods are specified in an XML file. If you have Crysis, you can examine the music XML file in the music.pak file.

LoadMusic(file)
loads a music XML file
file - pathname to the file, a string
UnloadMusic
SerializeMusicInternal
SetMusicTheme
EndMusicTheme
SetMusicMood
SetDefaultMusicMood
GetMusicThemes
GetMusicMoods
AddMusicMoodEvent
IsInMusicTheme
IsInMusicMood
GetMusicStatus
SetMenuMusic
PlayStinger
PlayPattern
SetMasterMusicEffectsVolume(volume)
set music volume
no return value
volume - a float

Misc

SetSoundRatio
SetWeatherConditions
Silence()
stops all sounds and music
example - none
UnloadProjects()
unloads all project so that wavebanks and project files can be overwritten
example - none

Moods

See Game/Scripts/Entities/Sound/SoundMoodVolume.lua for examples.

RegisterSoundMood(mood)
registers a sound mood to be activately processed, starting with a 0 fade value
mood - mood name, a string
UpdateSoundMood(mood,fade,fadeTime)
updates the fade value of a registered mood
mood - mood name
fade - fade value
fadeTime - fade time in milliseconds
GetSoundMoodFade(mood)
returns current fade value of a registered mood
mood - mood name
UnregisterSoundMood(mood)
unregister a sound mood and remove it from the the active set
mood - mood name

Multi Listener

CreateListener
RemoveListener
SetListener
Problems with this wiki page? Contact us either by: Support Email or Support Ticket System

Blue Mars Guidebook Privacy Policy
Blue Mars Guidebook Community Guidelines

Personal tools