anachronox-sdk/docs/SoundOfMusic.html
2002-01-21 00:00:00 +00:00

324 lines
11 KiB
HTML

<html>
<body bgcolor=#000000 text=#999999>
<font size=3>
<FONT FACE="Tahoma">
<center>
<font size=6 color=#ffcc00>
Anachronox Sound and Music Functionality
</font></center>
<br>
<font size=5 color=#ff0000>
Introduction<br></font>
Anachronox uses RAD Gametool's <b>Miles Sound System</b> and Microsoft's <b>DirectMusic</b> to
play sound effects, speech and background music. The file formates we currently support
are .WAV and .MP3 files for the sound effects and speech effect. Background music should
be in the .SEG format, which basically is a MOD format for MIDI. Along with the .SEG file
there should be a corresponding .DLS file which contains all the samples needed in the .SEG
file.
<p>
<font size=5 color=#ff0000>
Sound Effect Functionality<br>
</font>
There are a number of ways to make sounds appear in Anachronox. I will list the <b>APE</b> and <b>Planet</b>
functions first, to later on describe how to make the sound sources an integral part of the actual map.<p>
<font size=4 color=#ff0000>
Sound Effect Functionality in APE:<br>
</font>
From APE, there are basically 4 <b><i>extern</i></b> functions that provide the functionality we need.<p>
<ul>
<li> <b>playsound</b> ( filename{.WAV|.MP3} ) [ entity_id ] [ volume ] [ attenuation ]
<li> <b>loopsound</b> ( filename{.WAV|.MP3} ) [ entity_id ] [ volume ] [ attenuation ]
<li> <b>stopsound</b> ( filename{.WAV|.MP3} )
<li> <b>playanimation</b> ( entity_id ) ( filename )
</ul>
<p>
<table borderwidth="0" width="90%">
<tr>
<th valign="top" width="20%">
<font color=0xDDDD00>
<b>playsound</b> <b>loopsound</b>
</font>
</th>
<td>
<font size=2>
<b>Starts the playback of a sound file. </b>
<p>
One argument is required, which is the relative path and filename of the sound effect to play. The file
extension (.WAV or .MP3) must be supplied. The sound system will scan through first the subdirectory
anoxdata/sound and secondly the directory anoxdata/music if the specified file is not found in the sound directory.
The pathname should therefore be given as, eg, "bricks/engine3.wav". The system will then prepend "anoxdata/sound"
and "anoxdata/music" to the given path and try to load and play the file.<p>
If an <b>entity_id</b> is given, either as a sequence number or a classname, the system will try to locate that
entity in the world and play the sound so it originates from that entity's midpoint.<p>
<b>Volume</b> and <b>attenuation</b> should be a value between 0.0-1.0 and 0.0-4.0 respectively.
<b>volume</b> is an indication on how loud the sound will be played. The default value is 0.5. This makes it
possible to, in certain special cases, pump up the sound volume a little extra to create the effect of something REALLY
big, like an explosion, or similar.
The <b>attenuation</b> value is an indication of how fast the sound will fade with distance. Default value is 2.0.
A smaller value will travel further and a higher value will be cut off faster.<p>
The difference between the two functions is that <b>playsound</b> plays the sound once, while <b>loopsound</b>
repeats the sound indefinitely.<br>
Example:<br>
"<font color=0xAADDDD>extern playsound Bricks/HighwayToHell.mp3</font>" would play your favorite AC/DC song.<br>
"<font color=0xAADDDD>extern loopsound Bricks/HighwayToHell.mp3 ghetto_blaster 1.0 2.0</font>" would locate the entity with
the classname ghetto_blaster and play the same song from the location of that ghetto_blaster at full volume and normal
attenuation. The sound would then loop over and over again and move around the level if the ghetto_blaster is carried
around by another character.
<p><p>
</font>
</td>
</tr>
<tr>
<th valign="top">
<font color=0xDDDD00>
<b>stopsound</b>
</font>
</th>
<td>
<font size=2>
<b>Stops the playback of a sound file. </b>
<p>
The system will loop through all sounds being played and, if it finds the specified filename, will shut it off.
The filename should be the same as the name used to start the sound, but it is case-insensitive.<br>
<b>Example:</b><br>
"<font color=0xAADDDD>extern stopsound Bricks/HighwayToHell.mp3</font>" would stop your favorite AC/DC song.<p>
</td>
</tr>
<tr>
<th valign="top">
<font color=0xDDDD00>
<b>playanimation</b>
</font>
</th>
<td>
<font size=2>
<b>Starts the playback of a lipsynched speech sound. </b>
<p>
<b>entity_id</b> is, as above, either a sequence number or a classname. <b>filename</b> is the filename
of the sound/Magpie file to play WITHOUT file extension. The facial animations work as follows: <p>
The system tried to locate a file with that name, with either a .WAV or .MP3 extension. If the sound
file is found, the Magpie parser tries to locate a file with the same filename, but with a .LIP
extension. If the .LIP file is found, the information is parsed and the morph data in it
is sent to the facial deformation graphics system. If the .LIP file is not found, the system
will generate random lip movement data for the duration of the soundfile's length.
<b>Example:</b><br>
"<font color=0xAADDDD>extern playanimation 132:02 Bricks/dettagoon4</font>" would start the dettagoon4 sound and play
the animation on the entity with the sequence number 132:02, which hopefully should be the Detta goon. :-)
<p>
</table>
<p>
<hr width=80%>
<p>
<font size=4 color=#ff0000>
Sound Effect Functionality in Planet: <br>
</font>
From Planet, there are three sound related commands:<p>
<ul>
<li> <b>soundonce</b> (filename),(channel),(flush),(volume),(attenuation)
<li> <b>soundloop</b> (filename),(channel),(flush),(volume),(attenuation)
<li> <b>soundclear</b> (channel)
</ul>
<p>
<table borderwidth="0" width="90%">
<tr>
<th valign="top" width="20%">
<font color=0xDDDD00>
<b>soundonce</b> <b>soundloop</b>
</font>
</th>
<td>
<font size=2>
<b>Starts the playback of a sound file. </b>
<p>
<b>filename</b>, <b>attenuation</b> and <b>volume</b> are the same as above. However, the <b>channel</b> and <b>flush</b>
arguments deserves some extra mention.<p>
Basically, each entity has 4 virtual channels. This means that we can stack up to 4 sounds on a separate channel and play
them all at once. The <b>channel</b> designates which of these channels to use [0-3]. When <b>soundonce</b> or <b>soundloop</b>
is called with a <b>channel</b> id, the system will perform a check to see if there is another sound playing on that same channel.
<p>
If this is the case, we have a couple of choices. If the sound already playing on the channel has been started with soundloop
and hence is a looping sound, that sound will be stopped immediately and the new sound played on that channel. <p>
If, however, the previous sound wasn't a looping sound, the system will look at the <b>flush</b> flag. If the <b>flush</b> flag is set,
the system will stop the previous sound immediately and start playback of the new sound at once. If the <b>flush</b> flag
is '0', however, the new sound will be put on hold and playback won't start until the previous sound has finished. <p>
This may sound complicated, but it allows for things like "play the car's starting sound(non-looped sound) and que up the
sound of the car's running sound (a looped sound) so it will start immediately after the starting sound has finished".
<p>
</tr>
<tr>
<th valign="top">
<font color=0xDDDD00>
<b>soundclear</b>
</font>
</th>
<td>
<font size=2>
<b>Stops the playback of a sound file. </b>
<p>
<b>channel</b> basically designates which of the entity's virtual channel to shut off.<p><p>
Well, I thought to write more here, but what more can be said? :-)
</tr>
</table>
<p>
<hr width=80%>
<p>
<font size=5 color=#ff0000>
Putting sounds into the actual level<br>
</font>
Since the APE and Planet systems clearly aren't enough to put sounds in levels ;-), we can also do it the Die-Hard,
QuakeII way, ie just putting the sounds into the map file and be done with it. These are the commands that you can
put into the map file, in the definitions of <b>target_speakers</b> and <b>trigger_multiple</b>.
<p>
<ul>
<li><b>noise</b> ( filename )
<li><b>volume</b> ( value )
<li><b>attenuation</b> ( value )
<li><b>spawnflags</b> ( flag)
</ul>
<p>
<table borderwidth="0" width="90%">
<tr>
<th valign="top" width="20%">
<font color=0xDDDD00>
<b>noise</b>
</font>
</th>
<td>
<font size=2>
<b>Specifies the filename of the sound file to play </b>
<p>
The search for the filename you have specified starts in the anoxdata/sounds directory.
<br>
<b>Example:</b><br>
<font color=0xAADDDD>"noise" "global/earthquake1.wav"</font> would set the sound to be an earthquake
<p>
<p>
</tr>
<tr>
<th valign="top">
<font color=0xDDDD00>
<b>volume</b>
</font>
</th>
<td>
<font size=2>
<b>The volume level at which the sound should be played at. Range: 0.0 - 1.0 </b>
<br>
Default is '0.5'. Use a lower setting for sounds that should be more quiet and, guess what?
Use a higher setting for sounds that should dominate the scene more.
<br>
<b>Example:</b><br>
<font color=0xAADDDD>"volume" "0.3"</font> would play the sound real quiet.
<p>
<p>
</td>
</tr>
<tr>
<th valign="top">
<font color=0xDDDD00>
<b>attenuation</b>
</font>
</th>
<td>
<font size=2>
<b>The attenuation level for this sound. Range: 0.0 - 4.0</b>
<br>
Attenuation, or "How the volume fades with the distance from the sound source", is a good
tool to add to the ambient sounds. Defualt is '2.0'. Use a lower value if you want the
sound to be heard further away from the sound source and a higher value if the
volume is to drop fast once you're a bit away from the sound source.<br>
<b>Note:</b> This is purely a fictional value. It has no correspondence in the real world,
so it's hard to tell what it "really" is. :-)
<br>
<b>Example:</b><br>
<font color=0xAADDDD>"attenuation" "0.2"</font> would make the sound be heard very far away.
<p>
<p>
</td>
</tr>
<tr>
<th valign="top">
<font color=0xDDDD00>
<b>spawnflags</b>
</font>
</th>
<td>
<font size=2>
<b>Sets the default behavior of the sound source. Values: '1' or '2'</b>
<br>
A Spawnflag of '1' means that the sound is already playing when you start the level. A flag of '2' means
that the sound source will start looping when it's targeted. (For help on Targetting, target names, origin
and other values that are important to sounds sources, see elsewhere. :-)
<br>
<b>Note:</b> If the "spawnflags" are 0 (zero) or left out all together, the sound will be silent until you target
it and then only play the sound once. (Thanks, Seneca. ;-)<br>
<b>Example:</b><br>
<font color=0xAADDDD>"spawnflags" "2"</font> would make sure the sound was quiet until it was targeted.
<p>
</td>
</tr>
</table>
<p><p><p><p><p><p><p>
<!--- <font size=5 color=#ff0000>
Terms & Definitions (written mostly for coders)<br></font>
-->
</font>
</body>
</html>