Original Editor: Jv_map

Modifications and additions: Innkeeper
-------------------------------------------------------------------------------

This tutorial describes a way to add ambient sounds to your map which can be area location dependant and meanwhile have a soundtrack playing in the background. Following this tutorial, you can lower the volume of background noise when you enter a building or change it to something different that is appropriate, such as entering a bombed church with the sound of birds flying around occasionally. Another cool feature for single player maps would be to change the music when things get exciting. There are drawbacks for using some sounds in multiplayer maps as will be discussed. Innkeeper has made a tutorial map demonstrating the contents of this tutorial as well as a couple of other things. You can download it here.

-------------------------------------------------------------------------------
Ambient Sounds
-------------------------------------------------------------------------------

Music file

The easiest way to add an ambient sound is to use the 'global/ambient.scr' script file. (Note: There is an error in the 'ambient.scr' that is shipped with the game. Interior sounds will not work if there are no exterior sounds, but I will show you later how to fix it. See Appendix A ). This script file uses triggers to determine what sounds should be played when a player is at a specific location. So what you have to do is place trigger_multiples in locations where you want the ambient sound to change. Make different triggers for interior and exterior sounds.

All ambient sounds are in the 'sound/amb_stereo' folder. If you wish to use an ambient sound that is not in this folder or not even supplied by the game, it must be placed in this folder to work. The sound file can not be in the .pk3 file for your map, which makes distributing your map just a little more difficult. You should add a 'readme.txt' or something explaining that the extra .mp3s with you distribution must be placed in this directory.

A music file looks like the following: (music/m4l1.mus)

path sound/amb_stereo

normal Amb_M4_CountryExt_03.mp3 // Default
aux1 Amb_M4_CountryExt_03.mp3 // Exterior 1 - this is for all exteriors
aux2 Amb_M4_CountryExt_03.mp3 // Interior 1 - this is for the residential interiors
aux4 Amb_M4_ChurchInt_02.mp3 // Interior 2 - this is for the church interior
aux6 Amb_M4_Basement_01.mp3 // Interior 3 - this is for the safehouse interior

!normal volume 0.8
!normal loop
!normal fadetime 2

!aux1 volume 0.8
!aux1 loop
!aux1 fadetime 2

!aux2 volume 0.6
!aux2 loop
!aux2 fadetime 2

!aux4 volume 0.8
!aux4 loop
!aux4 fadetime 2

!aux6 volume 1.2
!aux6 loop
!aux6 fadetime 2

This is a music file with five ambient sounds, 'normal', 'aux1', 'aux2', 'aux4', and 'aux6', though 'normal' and 'aux1' are the same sounds in this example. The first section contains the sounds to be used. The section with the explanation marks sets values related to the sounds such as volume and fade time. You will probably want your sounds to loop so add '!aux# loop' to every sound you use so that the sounds don't quit at the end of the mp3. Amb_M4_CountryExt_03.mp3 is only 2 minutes and 38 seconds long and you may run around outside longer than that. The fadetime is the time in seconds that you will hear a cross-fade when switching sounds, for example, if you set the fadetime 2 and enter a building, you will hear the exterior sound fading out for 2 seconds and the interior sound fading in for 2 seconds at the same time. In most cases you will get the best result if you give all the sounds the same fadetime.

There is a limit of 15 .mp3s that can be used. They break down as follows:

Action, suspense, mystery, success, failure, surprise, special and aux7 are not handled in 'ambient.scr' and normal is only set the first pass through the script. These are used elsewhere, such as failure, when a player is killed. I'm not sure how action, suspense, mystery, success, surprise, special and aux7 are used, but if I find out, I will update this tutorial.

As you will notice, all aux sounds with odd numbers are used for exterior sounds, and even numbers are interior sounds. This is the way 'ambient.scr' handles them, but that is not to say that you could not use all the aux for interior sounds or vice versa.

It appears that the game engine saves the position in the .mp3 file when it changes sounds. This is actually rather neat as you can have your favorite song playing in a room and leave, when you return, the song starts playing again right where it left off.

When you are finished creating your music file, save it in the 'main/music' folder of your map's .pk3 as 'mymapname.mus'.

Now let's set up the triggers in the map to play your sounds. There are several methods that can be used to make triggers.

Method 1
Create a brush where you want to trigger a sound and give it a texture of trigger. With the brush still selected, open the entity window by pressing 'N'. In the upper window select trigger_multiple and double click. In the bottom window you will see 'classname trigger_multiple'. You want to add two more keys. Let's assume that this is to trigger an outside sound. In the key box enter 'targetname' and in the value box enter 'exterior' and press enter. The key / value pair should then show up in the lower window just below 'classname trigger_multiple'. Now add the key / value for the exterior sound you want to trigger. For example if you wish it to be aux5, you would enter the key '#set' and the value '3'. Make sure you press enter. The lower window should now contain the following:

#set	3
classname	trigger_multiple
targetname	exterior

If everything is ok, press 'N' to close the entity window, and then 'Esc' to unselect the brush. If pressing 'N' does not close the window, try clicking somewhere on the 2D map first. Now create other triggers that you want.

Method 2
Right click in the 2D view where you want your trigger and select 'trigger->multiple'. A trigger will be created and you will have to resize and move it to your requirements. Then press 'N' to bring up the entity window. Trigger_multiple will already be selected. Add the keys mentioned in the previous method.

Method 3
This can be used for duplicating triggers. With a trigger selected, press ctrl-space, 'Clone Selection Exact', and move the trigger to the appropriate place. This new trigger will have the same targetname and #set as the one you just had selected.

Below is a list of the keys / values that you will use.

A few ideas about placing triggers: You need not and shouldn't make one large trigger for each area that is to use a particular sound. This would cause a thread in 'ambient.scr' to run constantly, using processing power not needed. Use a brush just big enough to cover any method of entering the area. Included with the example map is a modified ambient script that corrects this flaw. If you want to change sounds from one room to another, connected by an opening, place the two triggers at least far enough apart the player can't trigger both at the same time. The player is 32 units square.

If you wish to have an ambient sound start as soon as the player spawns, just place a small trigger inside the 'info_player_start'.

Using 'ambient.scr' in multiplayer maps is not recommended. Whenever any player sets off a trigger, every player will hear the ambient sounds change, giving away the area where a player is.

Script file

Now you must make sure that you add:

exec global/ambient.scr mymapname

to your map’s script between level waittill prespawn and level waittill spawn.

-------------------------------------------------------------------------------
Music
-------------------------------------------------------------------------------

Music works a little different in MOHAA. As you can have only one .mus file playing at a time, you'll need a different system for the background music. You can use the 'tm' commands for this. The following music commands are available:

tmstart
tmstartloop
tmstop
playsong
playmp3
stopmp3

I have no idea why the commands in italic are included in the game. None of them are used in the original MOHAA scripts. The only commands you need are the ones that start with 'tm', and in most cases you'll want to use 'tmstartloop' to start a looping music. To start or change the music playing in the background by script, you need for example, the following lines:

wait 2
$player stufftext "tmstartloop sound/music/mus_04b_suspense.mp3"

below 'level waittill spawn' in your map script. I found that if I didn't add the 'wait' before the $player line, that the music would not work on the first spawn. The stufftext command means 'put this text in the player's console'. Background music is not implemented by default in multiplayer maps, but you can add it if you want to. You need to process the stufftext command to all players, for example use the following script.

level waittill spawn
wait 2

for(local.playernum = 1; local.playernum <= $player.size; local.playernum++)
{
$player[local.playernum] stufftext "tmstartloop sound/music/mus_04b_suspense.mp3"
}

Note that this is not a completely bug free method, as players don't join at the same time. You could for instance run this code in a while loop the whole time to start the music for everyone on the server.

To stop the music in single player mode use:

$player stufftext "tmstop"

and for multiplayer mode use:

for(local.playernum = 1; local.playernum <= $player.size; local.playernum++)
{
$player[local.playernum] stufftext "tmstop"
}

to stop the music in multiplayer mode.

-------------------------------------------------------------------------------
Final Notes
-------------------------------------------------------------------------------

I think this is all you need to know to get ambient sounds and music in both single player and multiplayer maps. If you don't need location depended ambient sounds you can also use

soundtrack mymapname

This will only play the 'normal' music, no 'aux' musics. You then don't have to create any triggers and don't need the global/ambient.scr in your script, but you will need a .mus file. If you have any problems with the things mentioned above, feel free to either contact me or post at the forums

If you use at least one exterior trigger the following is not necessary.

With as much work that goes into making games such as MOHAA, it is not surprising that errors exist, but this one does surprise me. It's a simple error; the musiclevel thread is not called in the code block that sets up the interior sounds. To fix it, open 'ambient.scr' in a text editor and go down to line 50. You should see the following:

Add the line indicated for line 50. This calls 'musiclevel', a thread further down in the script file, which actually changes the sounds.

Now go down to line 82 and add the lines in yellow.

If there were no interior triggers, you want to thread the musiclevel here. But if there are, it has already been done, so no need to do it again.

With changes made, save the file with a name like 'ambientsound.scr' and put it in your .pk3 file in the folder 'main/global'. If you save it with the same filename, you will have a conflict with the one in 'pak0.pk3'. You could make the change in the 'pak0.pk3' but that will not help the map if you distribute it.

Now you must make sure that you add:

exec global/ambientsound.scr mymapname

to your map's script between level waittill prespawn and level waittill spawn.

-------------------------------------------------------------------------------
Personal note from Innkeeper
-------------------------------------------------------------------------------

I can be a code Nazi at times and I guess it's coming out of me now. Looking through the scripts that come with MOHAA, there must not have been any code reviews with respect to coding style guidelines. I saw in one file, "!! USE TABS !!", ARRRRGGGG. I hate tabs because some will use them and others won't, and when you load something into your favorite editor and have spaces and tabs that were set to something other than what the previous writer used, the formatting goes to hell and it's hard to follow. Tabs have their place in word documents. My issue with tabs is the tab character, not indention.

Another thing that helps is if you will put curly braces ({ }) around a block of code even if it is one line. It's a great visual reference that the code relates to the line before it. If you add a line of code to the block, or a quick debug message, you will have to do it anyway.

Indention is another thing! In the above example, lines 54 to 57, 'else' is the same level of nesting as 'if' is. It should not be indented! Could be that someone was using tabs in the past ;).

I'll get off my soapbox now. Thanks for reading.

[ Download the Example Map ]

Need any help : Ask in the Forum