|
Updated: October 6th 2003
Overview of a typical soundscript
Below is an example soundscript, in a very small font. We will go over
the various codes and sections in chapters to follow. For now, examine
the following code and orient yourself to the general layout.
>>When someone is in the driver seat, this sound is played.
** Sound pathname with relative references for mod name and sound
quality
newPatch
####################
### Engine Start ###
####################
load @ROOT/Sound/@RTD/DesertCombat/Humvee/Humvee_Start.wav
minDistance 1
dopplerOff
priority -2
*** Distance Volume ***
beginEffect
controlDestination Volume
controlSource Distance
envelope Ramp
param 50
param 100
param 1
param -1
endEffect
>> Sound played at low engine output.
##############
### Lo RPM ###
##############
load @ROOT/Sound/@RTD/DesertCombat/Humvee/Humvee_Low.wav
loop
volume 1
minDistance 2 ** Sound begins fading naturally
2m from source.
relativePosition 0/0/0
priority 8
*** Engine start ***
beginEffect
controlDestination Volume
controlSource Time
envelope Ramp
param 0.2
param 0.8 ** Sound
fades from silence to full volume between 0.2 and 0.8 seconds after engine
start.
param 0
param 1
endEffect
*** Engine Pitch ***
beginEffect
controlDestination Pitch
controlSource Default
envelope Linear
param 0.9
param 0.8
endEffect
*** Distance Volume ***
beginEffect
controlDestination Volume
controlSource Distance
envelope Ramp
param 15
param 65
param 1
param -1
endEffect
*** Engine Volume ***
beginEffect
controlDestination Volume
controlSource Default
envelope Ramp
param 0
param .9
param 1
param -1
endEffect
*** Engine stop ***
beginEffect
controlDestination Volume
controlSource TimeRelease
envelope Ramp
param 0
param 0.2 **
Sound fades so silence and terminates 0.2 seconds after after engine stops.
param 1
param -1
endEffect
>>Sound played after engine picks up speed.
################
### Hi RPM 1 ###
################
load @ROOT/Sound/@RTD/DesertCombat/Humvee/Humvee_Medium.wav
loop
minDistance 8
relativePosition 0/0/0 **
Sound origin is centered on vehicle. Values are x/y/z.
priority 8
*** Engine start ***
beginEffect
controlDestination Volume
controlSource Time
envelope Ramp
param 0.2
param 0.8
param 0
param 1
endEffect
*** Engine Pitch ***
beginEffect
controlDestination Pitch **Sound
pitch is set relative to vehicle speed.
controlSource Speed
envelope Linear
param 0.4
param 0.01
endEffect
*** Distance Volume ***
beginEffect
controlDestination Volume
controlSource Distance
envelope Ramp
param 25
param 150 **Volume
ramp that fades sound from full to zero between 25 and 150m.
param 1
param -1
endEffect
*** Engine Volume ***
beginEffect
controlDestination Volume
controlSource Default
envelope Ramp
param 0
param .2
param 0
param 1
endEffect
*** Engine stop ***
beginEffect
controlDestination Volume
controlSource TimeRelease
envelope Ramp
param 0
param 0.2
param 1
param -1
endEffect
>>Sound played while engine is at high
output.
>>This is a short range sound that only modifies the current
engine sound playing in HiRPM1.
################
### Hi RPM 2 ###
################
load @ROOT/Sound/@RTD/DesertCombat/Humvee/Humvee_High.wav
volume 1
loop **Chosen
.wav will loop forever until terminated
minDistance 2
relativePosition 0/0/0
priority 8 **On a scale of –10
to 10, this sound has a priority of 8 when competing for sound channel
use with other overlapping sounds.
*** Engine start ***
beginEffect
controlDestination Volume
controlSource Time
envelope Ramp
param 0.2
param 0.8
param 0
param 1
endEffect
*** Engine Pitch ***
beginEffect
controlDestination Pitch
controlSource Default
envelope Linear
param 0.75
param 0.25
endEffect
*** Distance Volume ***
beginEffect
controlDestination Volume
controlSource Distance
envelope Ramp
param 25
param 65
param 1
param -1
endEffect
*** Engine Volume ***
beginEffect
controlDestination Volume
controlSource Default
envelope Ramp
param 0
param .5 **Engine
sound is silent at engine idle and fades to full volume when engine output
is at 50%.
param 0
param 1
endEffect
*** Engine stop ***
beginEffect
controlDestination Volume
controlSource TimeRelease
envelope Ramp
param 0
param 0.2
param 1
param -1
endEffect
>>Sound played while engine is idling.
############
### Idle ###
############
load @ROOT/Sound/@RTD/DesertCombat/Humvee/Humvee_Idle.wav
loop
minDistance 2
relativePosition 0/0/0
priority 8
*** Engine start ***
beginEffect
controlDestination Volume
controlSource Time
envelope Ramp
param 0.2
param 0.8
param 0
param 1
endEffect
*** Engine Pitch ***
beginEffect
controlDestination Pitch
controlSource Default
envelope Ramp
param 0
param 0.25
param 1
param 0.2
endEffect
*** Engine Volume ***
beginEffect
controlDestination Volume
controlSource Default
envelope Ramp
param 0
param 0.9
param 1
param -1 **
Idle sound begins at full volume and fades to silence as engine approaches
90% output.
endEffect
*** Distance Volume ***
beginEffect
controlDestination Volume
controlSource Distance
envelope Ramp
param 5
param 50
param 1
param -1
endEffect
*** Engine stop ***
beginEffect
controlDestination Volume
controlSource TimeRelease
envelope Ramp
param 0
param 0.2
param 1
param -1
endEffect
>>Sound played when drivers seat is abandoned.
###################
### Engine Stop ###
###################
load @ROOT/Sound/@RTD/DesertCombat/Humvee/Humvee_Stop.wav
minDistance 2
trigger Release
**Sound waits to be played until the
vehicle is “released”
dopplerOff
priority -2
*** Distance Volume ***
beginEffect
controlDestination Volume
controlSource Distance
envelope Ramp
param 50
param 100
param 1
param -1
endEffect
Soundscript Titles
Consider the following code:
###################
### Engine Stop ###
###################
load @ROOT/Sound/@RTD/DesertCombat/Humvee/Humvee_Stop.wav
minDistance 2
The area set in ### is a soundscript title. They are
used throughout the soundscript to identify the sections both to the scripter
and to the engine itself.
My suggestion is to start with a soundscript from the original BF1942
files and work from there. Use only titles defined in those soundscripts.
As we will see later, there is a way to add comments to your soundscripts,
which will never interfere with the flow or function of the script. So
in my experience it is best to consider soundscript titles a necessary
evil. Just use them as they appear in the original files and use your
own comments to label the sections as you need.
Soundscript structure
As you can see from the example soundscript above, there is a specific
structure that is usually adhered to. A soundscript section will always
be initiated by the declaration of a sound, using the load command. If
it is an entirely new section, the command newPatch preceeds the load
command. Then, sound parameters follow, such as the declaration of loops,
stereo, and volume properties. Finally, adjustment ramps are declared,
which modify the sound further in accordance to the behavior of the vehicle.
Here is an example layout of a soundscript section:
- NewPatch
- Load the .wav using the proper path
- Declarations section. Define the priority, master volume, looping, stereo,
etc.
- Adjustment ramps. Apply adjustments to pitch and volume according to
time, vehicle speed, engine rpms, distance, etc.
You will notice in the example soundscript provided at the beginning,
that there can be several sounds loaded under one newPatch command. Keep
in mind that newPatch is used to speak to the soundscript interpreter,
and defines the functional sections of the soundscript. It separates out
a reload section from a firing section, for instance.
Loading a sound also has a functional action, and all commands that follow
the loading of a sound are applied to that sound only. Remember that newPatch
separates different functional sections within a soundscript, so you may
load several sounds within a newPatch section. There is no known limit
to the number of sounds you may load for each section.
There is no set rule as to where commands such as stereo, loop, mindistance,
etc. must be stated following the load command. For organization’s
sake, they are usually all declared immediately following the use of the
load command.
As a final note, the location of soundscript sections, separated by newPatch
commands, does not seem to be pre-ordained. You should have freedom over
placement of the primary soundscript sections. However, it is usually
wise to copycat original BF1942 soundscript structure.
Soundscript commands
newPatch Using
this command alerts the script interpreter that a new sound section has
begun. Use of this command is more important for some sounds than others.
For some soundscripts, using many newPatch commands to separate out sections
is essential. For others, there is only a need for one of these commands.
You need not declare a newPatch for every sound that you load. If you
want sounds to be played simultaneously or sequentially, you will usually
group them together under one newPatch. The command newPatch is only used
to communicate with the interpreter, so it may recognize different sections
of the soundscript.
load <path>:
The load command calls forth a sound to be played
from a given path. Once a sound is loaded, all code that follows will
affect that sound, until another load command is issued. The load command
can use relative pathnames to automatically pick from a certain path.
Here are some examples:
@Root:The
root directory of the current mod
@RTD: The
sound quality chosen by the player
@Language: The
language chosen by the player
stereo: If
the sound you are going to use is in stereo, you must alert the script
of this. Use of stereo sounds negates any directional quality of the sound.
If you are in range to hear it, the sound will always sound as though
it occurred at your position.
minDistance <#>:
Mindistance is a greatly speculated upon and misunderstood
command. In my experience, mindistance is the distance at which the sound
begins to naturally lose volume. If you use no volume commands on your
sound, the game will still cause it to lose volume over distance. Setting
a high mindistance increases the radius at which the sound will maintain
high volume on its own.
dopplerOff: Doppler
is the raising / lowering of pitch according to the speed at which an
object is approaching / departing. The engine assumes that doppler is
active unless you deactivate it through use of this command.
priority <#>: Depending
on your sound card, you can only have 32-64 sounds playing at one time.
In the middle of a firefight there are definitely more sounds being called
for than the sound card can handle. Therefore priorities must be set as
to which sounds will be heard while others are not. All overlapping sounds
are in constant competition for being heard. You assign every sound a
priority number ranging from –10 to 10, 10 being highest. There
is a priority 11 but that is reserved only for radio commands. Good decisions
made on sound priorities are essential for an effective sound environment.
loop: If you want your sound to be played on an infinite loop, you will
want to add this command. You can still control the audibility of the
sound using other commands and especially with volume ramps and time delays.
There is no command to loop a sound a selected number of times. However,
with smart use of time / volume parameters you can still have good control
over how a sound is played.
relativePosition <x/y/z>: You
can define where on the vehicle the sound will originate from. The format
of the position is x/y/z (left/right, above/below, forwards/backwards).
Care must be taken in the positioning of the sound, as a soundscript is
often called from a specific component of the vehicle and not the vehicle
itself. For example, a jet engine soundscript is called from the engine,
and therefore a position of 0/0/0 will place the sound origin on the center
of the engine object.
volume <#>:
You may set the sound’s
master volume peak directly using this command. The volume value ranges
from zero (silent) to one (full volume). All further volume adjustments
to the sound will be made relative to the master volume adjustment. So,
for example, if a sound’s master volume is set to 0.5, and then
is later modified to fade to 0.5 volume in a volume ramp, the end volume
will be 0.25.
randomStartPitch<min/max>: With
this command, you may set the sound to be played at a randomly selected
pitch every time it is used. The first parameter is the minimum pitch
value, the second is the maximum pitch value. It is difficult to explain
the mathematics of the pitch parameters, as each follows its own set of
rules. But as an example: randomStartPitch 0.75 / 0.25 sets a pitch range
from 0.75 of the normal pitch to 1.25 of the normal pitch. The first is
a raw factor to be multiplied, the second is to be added to 1 and then
multiplied.
stop finishSample: This
command is only used in conjunction with looping sounds. It tells the
sound to play through the .wav completely before ending, even if the sound
source ceases its activity. This is commonly used in automatic firearms
so that quick taps of the trigger do not cause “half-shots”
to be heard.
randomPlay: This
command requires the use of newPatch and at least two loaded sounds. It
allows the section to randomly pick between all sounds within.
triggerVolume: This
command is only used in conjunction with a time-volume ramp. It prevents
a sound from being played immediately upon the execution of a soundscript.
Instead, the sound is begun at the defined moment the time-volume ramp
is set to raise its volume above zero. If you did not use the triggerVolume
command in a time-volume ramp, the sound would begin the moment the soundscript
is run, regardless of when it is meant to be played. You would end up
with the sound volume being raised from zero in the middle of a playing
sound, which in most cases is undesirable.
#include: This
command is used to load another soundscript, which is run in parallel
with the current script. It’s a great way to save time and effort
when multiple soundscripts will be expected to contain identical sections.
It also allows for the execution of special soundscript commands that
do not work well together. Here is an example of the #include command
used for ejected shell cases:
####################
### Shell Bounce ###
####################
newPatch
#include ../../../Common/Sounds/ShellBounce.ssc
***: Use three subsequent asterisks to begin a comment. These are ignored
by the interpreter and are a great way to organize your soundscripts.
Ramps:
Ramps are methods of controlling a sound’s
properties in accordance to a specified control entity. You can adjust
a sound’s pitch according to the speed of the vehicle, for instance.
Or adjust a sound’s volume according to the observer’s distance.
Some ramp controls are set and unchanging. Others are dynamic and vary
according to vehicle performance or other conditions.
A ramp definition consists of a parameter definition and a parameter set.
Consider the following code excerpt:
*** Start Distance Volume ***
beginEffect
controlDestination Volume
controlSource Distance
envelope Ramp
param 50
param 100
param 0
param 1
endEffect
- Parameter definition: In this area, you specify the source of control
and the method of sound adjustment according to that control. In this
excerpt you can see the source of control is Distance, which is the method
of adjustment for the destination Volume. So as distance changes, volume
changes accordingly. Below this section is the parameter set, which defines
two points where the control source and control destination coincide.
An adjustment ramp is then created using these points as a reference.
- Parameter set: In this area, you specify two points at which you will
define the exact values for the control source and control destination.
The order of the parameters is:
Param1 : control source point 1
Param2 : control source point 2
Param3 : control destination point 1
Param4 : control destination point 2
So verbally, the code excerpt is saying: at 50m the sound volume is zero,
at 100m the sound volume is 1 (full volume).
Using this information, the soundscript creates an adjustment ramp to
modify the sound according to its parameters. For points outside of the
parameter set, the points assume the last stated value in the parameter
set. In other words, the angle of the ramp does not continue beyond the
defined start and end points, but rather maintains the same value as the
end points. So, in this example, an observer closer than 50m to the sound
origin will experience a zero volume level, and an observer beyond 100m
will experience a full volume level. The ramp angle does not continue,
but rather remains level according to the last stated value in the parameter
set.
Now consider the next set of code which immediately follows the above
code:
*** Distance Volume ***
beginEffect
controlDestination Volume
controlSource Distance
envelope Ramp
param 200
param 300
param 1
param -1
endEffect
This ramp continues full folume out to 200m. Then, the volume diminishes
to zero at 300m. Note the use of –1 instead of zero to end the sound.
This is called terminating the sound. It tells the sound engine that no
sound will occur outside of the designated range. This is different than
telling the engine that volume is zero beyond the designated range. Without
terminating the sound, it will continue to infinity and occupy sound channels
throughout the map.
IMPORTANT NOTE: You must terminate all
sounds. Failure to do this will result in loss of available sound channels
across the map. If enough active sounds are not given termination commands,
you will experience massive loss of sound channels in-game.
Here is a description of the many sound ramps that
occur in BF1942. This is just a sampling of the more common ramp codes.
Others may exist and it seems that many in-game variables may be used
to control a ramp.
Time delay:
*** Time Volume ***
beginEffect
controlDestination Volume
controlSource Time
envelope Ramp
param 0.77
param 0.77
param 0
param 1
endEffect
trigger Volume
This ramp is used when a sound should not be played until a designated
amount of time has passed. In this example, the sound will be played 0.77
seconds after the sound triggering event has occurred.
Note the use of trigger Volume immediately after the ramp. This command
is used in conjunction with time delay ramps. It forces the sound to start
when the given time has passed, instead of letting the sound start immediately.
If this ramp was missing the trigger Volume command, you would not hear
the sound from the beginning, but rather from the 0.77 second mark of
the .wav. This command will almost always be used in a time delay ramp.
Engine activity volume ramp:
*** Engine Volume ***
beginEffect
controlDestination Volume
controlSource Default
envelope Ramp
param 0
param 0.75
param 0.25
param 1
endEffect
This ramp is used when a sound should be louder / quieter according to
a vehicle’s engine performance. Many vehicle soundscripts use an
array of sounds with such volume ramps, each sound crossfading with another
as the engine power picks up.
Note the controlSource is listed as Default. While there is no absolute
documentation on the exact meaning of Default, it seems to be a combination
of engine RPM and vehicle speed. The range is from 0 (an idle vehicle)
to 1 (a vehicle at maximum power and speed).
This specific ramp tells the sound to play at 25% when the vehicle is
stopped, and increase to full volume when the vehicle engine reaches 75%
of it’s full power.
Engine RPM pitch ramp:
*** Engine Pitch ***
beginEffect
controlDestination Pitch
controlSource Extern #map<Engine::Rpm>
envelope Ramp
param .2
param .6
param 0.70
param 0.30
endEffect
This ramp is used primarily for aircraft to increase
/ decrease a sound’s pitch according to engine RPM. This ramp is
commonly used to adjust an aircraft engine’s pitch as the pilot
increases throttle.
Note the controlSource is listed as Extern #map<Engine::Rpm>. This
control source is a variable taken directly from the vehicle’s engine
properties. It ranges from 0 (at zero throttle) to 1 (full throttle).
Pitch ramps have parameters that are a bit difficult to interpret. The
two parameters are offsets from the standard value of 1 (which is normal
pitch). It is best to think of the pitch parameters graphically, as they
make little sense mathematically. Let me demonstrate:
This particular ramp is set to param3: 0.7 and param4: 0.3. This means
that when the vehicle is at .2 throttle, the pitch will be at 70% of normal.
When the vehicle is at .6 throttle, the pitch will be at 130% of normal.
Parameter 3 is the actual multiplier of the pitch when the control source
is at parameter 1. Parameter 4 is the multiplier above normal pitch when
the control source is at parameter 2. So you would consider a parameter
4 value of 0.3 to mean the pitch is multiplied by 1.3.
Soundscript tips
Here are some important soundscripting tips to
bear in mind.
- All soundscript commands are CASE SENSITIVE! Never forget this. Sound
paths need not be in the proper case. Everything else in your soundscript
must be properly capitalized.
- Priority is god in soundscripting. Reserve high priorities for sounds
that should always be heard over others. Do not let distant sounds have
high priorities. Break up a sound into several different priorities according
to distance.
- As mentioned before, always terminate your sounds. Doublecheck your
soundscript for termination errors before deeming it complete.
- Stereo sounds have their use, but they are of limited worthiness. The
best time to use a stereo sound is when you want to ensure a sound is
always centered on the player’s ears. They are used for 1st person
view in many weapons for this reason, to disregard slight variance in
positioning. Don’t forget that a stereo sound is twice the file
size as a mono. Use them sparingly.
- If two of the same sound overlap, they will cause a phaser effect that
is usually unwanted. Keep in mind all the sound radii for each .wav, and
try to avoid overlapping the same .wav. For some vehicles, the phaser
effect is desirable. Multiple propeller planes fall into this category.
- Remember that mindistance has its own inherit volume / distance ramp
that you have no control over. If your sound is too quiet at a distance,
even if your volume ramp is not set to reduce volume, consider increasing
the mindistance value.
- A soundscripter is always dependant on the coder to include his soundscripts
in the object he is preparing his scripts for. Work with the coder to
determine what components of a vehicle need a soundscript attached to
them.
- Be wary of multiple engined vehicles if you only want a single soundscript
to handle the engine sound. The coder must ensure only one soundscript
is called for.
- If you want a sound to follow a projectile, you will call for a soundscript
in the projectile’s physics.con file. Looping sounds behave better
for projectiles. Even if a sound is long and will not loop properly, still
set it to loop. Otherwise the soundscript distance properties will only
be calculated once and not be updated as the projectile moves. If a sound
does not loop well and you want to deactivate it as soon as it reaches
the end of the .wav, use a time / volume ramp to terminate it.
- For vehicle engines, consider using a single engine sound set for a
broad pitch range depending on the engine power. Then overlay several
smaller looping sounds that activate at different RPM levels. You can
conserve considerable file size by using this method. Reserve a unique
sound for engine idle.
| 
