==========================================================================================

			USING AMBIENT SOUNDS with RISEN3D Risen3D v220

								GMJ December 2015

==========================================================================================
 WHAT ARE THEY?
==========================================================================================

 An 'Ambient sound' or ambient is one that plays according to a predefined set of rules
 and is independent of any action of the player other than the relative position of each,
 which is used to calculate the volume.  Thus the sound of falling water as you approach
 a waterfall or the the sound of a fan going or lightning in the background would all be
 examples of an Ambient sound.  Adding these can enhance a map considerably.


==========================================================================================
 HOW DO I GET THEM INTO THE MAP?
==========================================================================================

 An Ambient sound is a MapThing, but, it does not move, cannot be seen (is never rendered)
 and can't be killed - its sole purpose in life is to tell RISEN3D to play a certain
 sound and at what position in the map it should be heard.  Ambient Things are assigned a
 number between 14001 and 14064 inclusive and are placed in the map at the point from which you want
 the sound to play.

 From this it can be seen that up to 64 ambient Things can be designated.  As such each
 can have its own unique set of arguments.

 Things with the same number can be inserted multiple times. The limit for the number
 of Things is 256.

==========================================================================================
 HOW DO I ASSIGN A SOUND TO A THING?
==========================================================================================

 This is done using a plain text script that can be written using Notepad.  The script's
 name is not important and can be anything you like.  In the script there are certain
 actions that can be performed.  Not all of these are to do with Ambient sound Things,
 some are just to help with standard sound management which are discussed further on.

 When complete the script is added to the pwad using the lumpname SNDINFO.


==========================================================================================
 DEFINING AMBIENTS IN A SCRIPT.
==========================================================================================

 1)	LOGICAL NAMES

 The first step is to assign a lumpname to a logicalname.  You can use any name
 for the logicalname other than reserved names for sound replacement (see further
 down) It also must not use more than 31 characters.  If you are going to define
 an ambient later on in the script using a sound whose lumpname is (say) CREAKYST
 then before doing so you must link this to a logicalname e.g.

 creakysteps CREAKYST

 from then on if you want to reference this sound in the script you must use
 the logical name creakysteps.  You can, of course, use the same name as the
 lumpname, e.g.

 CREAKYST CREAKYST

 but either way it must be defined.

 2)	AMBIENTS

 An Ambient can take four different types namely;

 CONTINUOUS, PERIODIC, RANDOM or ONCE.

 These allow the sound to be handled in different ways and are much as their
 names imply.  For a waterfall sound, for example, the CONTINUOUS sound would be
 required.  For a siren that, perhaps, is not something that you would want playing
 continuously, with no break, but instead with a fixed delay between each instance
 then PERIODIC would be used.  For a sound like lightning, where you want it to be
 repeated but with a random delay between each instance then you would use RANDOM.

 All types have a basic definition i.e.;

 $AMBIENT <num> <logicalname> [point [atten] | surround | [world]]
	<continuous | random <minsecs> <maxsecs> | periodic <secs>>
	<volume>

 <num>

 A number must uniquely be assigned and fall in the range 1 to 64.  The number links
 it to a Thing.  The Thing uses the type number 14000 + the ambient number.  Thus,
 if you put a Thing in your map and give it the type number 14001 then RISEN3D will
 expect this to convey the x, y co-ordinates of an Ambient sound.  To define what the
 sound should be and how it should behave then you would need an $AMBIENT 1 etc...
 definition in your script.


 <logicalname>

 The next argument is the logicalname that links to the lumpname of the sound.


 POINT [ <atten> | SURROUND | WORLD]

 POINT is optional and can take a value or the keywords SURROUND or WORLD

 Note that a sound will be played from an Ambient Thing's position.

 SURROUND or WORLD are included for script compatibility but are not
 differentiated.  They set the attenuation to 0 so the sound will be
 heard over the entire map. Alternatively POINT 0 could be used.

 Examples;

	$AMBIENT 1 lname POINT 1.0 etc.
		is the same as
	$AMBIENT 1 lname 1.0 etc.
		is the same as
	$AMBIENT 1 lname etc.

	$AMBIENT 1 lname POINT 0.0 etc.
		is the same as
	$AMBIENT 1 lname 0.0 etc.
		is the same as
	$AMBIENT 1 lname SURROUND etc.
		is the same as
	$AMBIENT 1 lname WORLD etc.

 <atten> - attenuation

 This covers the range 0.0 to 3.0.

 NOTE: attenuation does not change the volume; it is used to vary the distance
       over which a sound is heard and rolls off.

 A value of 1 will mean the distances and roll off values will use the normal
 defaults.

 Values between 0 and less than 1 will extend the range with 0 meaning the
 sound will be heard unattenuated over the whole map.

 A value between greater than 1 and 3 will reduce the distance over which the
 sound can be heard.

 
 -------------------------------
 CONTINUOUS
 -------------------------------

 This is the simplest type to define and just needs the volume to be set.  It does not
 have any type values.  The full definition then becomes;

 $AMBIENT <num> <sound> [point [atten]] CONTINUOUS <volume>

 -------------------------------
 PERIODIC
 -------------------------------

 A periodic sound will need a further argument defining the time between each instance
 of the sound to be played.  This is a time in seconds.  The full definition is;

 $AMBIENT <num> <logicalname> [point [atten]] PERIODIC <delay to replay> <volume>

 -------------------------------
 RANDOM
 -------------------------------

 This is similar to periodic but the program will need to know the minimum and maximum
 limits of a time to randomly select before replaying the sound. This is defined as;

 $AMBIENT <num> <logicalname> [point [atten]] RANDOM <min delay> <max delay> <volume>


 <once | random <minsecs> <maxsecs> | periodic <secs>>

 -------------------------------
 ONCE
 -------------------------------

 This is used with LINE TRIGGERED AMBIENTS.  The full definition is;

 $AMBIENT <num> <sound> [point [atten]] ONCE <volume>

 <continuous | random <minsecs> <maxsecs> | periodic <secs>>

 To see when to use this type see LINE TRIGGERED AMBIENTS further down.


 <volume>

 Is defined as a value between 0.0 and 1.0.  1.0 is maximum.  0.0 is supported for
 mathematical expediency but otherwise has no use.  Sounds with no volume are
 never played.

 <delay> any type

 Can be any number up to 936.0 representing time in seconds.  The maximum is therefore
 15:36 (minutes:secs).  0.01 should be 10mS but since timing is based on 35 ticks per
 second then the smallest time interval is 1/35 of a sec.  The nearest value to
 multiples of this will apply.


==========================================================================================
 WHAT ARE $WORLDS - WHY ARE THEY DEFINED SEPARATELY?
==========================================================================================

 $WORLD logicalgroupname [BBOX <length> <width> <xoff> <yoff>] { <list> }

 A useful further keyword is $WORLD.  This allows a random selection from a list of sounds
 that can then be played individually in sequence.

 The list should be comprised of previously defined random ambients using their
 logical names.

 In the game a sound from this list will be selected at random and then played. When the
 sounds own random delay has expired another random selection will be made from the list
 and so on.

 This differs from individually selected sounds as only one sound will be playing from
 the list at a time.  They can also uniquely have a bounding box defined allowing an area
 of no attenuation to be applied before rolling off (assuming their attenuation is not
 set to 0).

 NOTE: A pre-defined ambient put in the world list will no longer play independently.

 In the example script shown below the pre-defined ambients numbers 25, 26 and 27
 are randomly selected.  If you wanted them to be heard everywhere in the map then
 you would define each ambient to have an attenuation of 0.0 and then list them
 simply as;

 $WORLD world/ambient { world/ambient1 world/ambient2 world/ambient3 }

 NOTE: Risen3D v220 BBOX support removed


==========================================================================================
 LINE TRIGGERED AMBIENTS
==========================================================================================

 Ambients can be triggered when lines are activated by linking them specifically
 to a line with a special.

 To do this put a THING type 13901 to 13964 on the linedef.  The number chosen
 in the last two digits will cause an ambient to be chosen with the same last
 two digits.  Hence 13902, for example, will trigger an ambient sound defined
 with THING 14002.

 Three special values are also recognised where a line is only required to
 trigger an Ambient.  These are;

 8090	use
 8091	gun (impact)
 8092	walkover

 Note that a THING type 139xx must be put on a line with a special else it will
 be ignored.  If a linedef has its special zeroed on triggering then the ambient
 can only be triggered once - the same as the action associated with the linedef.

 If normal Ambients are used then once triggered they will stay active.  To get
 an Ambient to play once on each trigger then define it using ONCE.

 E.g.;

 $AMBIENT 1  DRSPLIT1 POINT 1.0 ONCE 1.0

 NOTE: If the linetrigger is a MODEL trigger type then it may be more appropriate
       to use a sound link with this type rather than an Ambient.

       See  ADDING LINETRIGGER SOUNDS in R3D_ModelSwitch.txt


==========================================================================================
 SOUND REPLACEMENT
==========================================================================================

 The other function provided for in SNDINFO is where you want to assign a different
 sound to an existing sound.  E.g.

 doors/dr1_open   METALDRO

 In this example we are replacing one of the door opening sounds with the a new sound.
 Normally any sounds that need to be replaced are just put in the pwad with the same
 lumpname - these will then take precedence.  But this method can be alternatively
 used if available from the list below.

 In one particular case, however, the chaingun's sound can't be replaced by just
 inserting a replacement lumpname without affecting the pistol sound as well as,
 in DOOM, they share the same sound.  This can be overcome using SNDINFO with the
 following definition;

 weapons/chngun   DMACHGUN

 This will uniquely replace just the machine gun sound leaving the pistol sound
 unaffected.

 The current list of pre-defined logical names set in RISEN3D are;

 "weapons/sawup"
 "weapons/sawidle"
 "weapons/sawfull"
 "weapons/sawhit"
 "weapons/pistol"
 "weapons/shotgf"
 "weapons/shotgr"
 "weapons/sshotf"
 "weapons/sshoto"
 "weapons/sshotc"
 "weapons/sshotl"
 "weapons/chngun"
 "weapons/rocklx"
 "weapons/rocklf"
 "weapons/plasmaf"
 "weapons/bfgf"
 "plats/pt1_strt"
 "plats/pt1_stop"
 "plats/pt1_mid"
 "doors/dr1_open"
 "doors/dr1_clos"
 "doors/dr2_open"
 "doors/dr2_clos"
 "world/barrelx"
 "world/drip"
 "world/watersplash"
 "world/sludgegloop"
 "world/lavasizzle"
 "misc/secret"
 "misc/w_pkup"
 "misc/p_pkup"
 "misc/i_pkup"
 "misc/k_pkup"
 "misc/spawn"
 "misc/chat"
 "misc/chat2"

 These may be extended later.

 When defining your own logical names for use in a script avoid prefixing them
 with weapons/ or plats/ etc.  This will then ensure there are no problems should
 the prefixed name list be extended at a later date.


==========================================================================================
 INSERTION OF ITEMS - SNDINFO LUMP
==========================================================================================

 To use a script file then just import it into the pwad using the lump name SNDINFO.

 To see a working example then download xtheateriiiRisen3D from www.sbsoftware.com.

 An editor can be used to see what's going on.

==========================================================================================
 SAMPLE SNDINFO SCRIPT (used in xtheateriiiRisen3D.wad)
 This script uses logical names which are the same as their associated lumpnames.
==========================================================================================

// RANDOM          
// PERIODIC        
// CONTINUOUS      
// POINT  (positional)      
// SURROUND
// $ambient <num> 
//          <logical name> 
//          [point [atten]|surround] 
//          <type> [secs] <relative volume>


DRSPLIT1 DRSPLIT1   //Door split
DRSLIDE1 DRSLIDE1   //Door Slide
DROTATE1 DROTATE1   //Door Rotate
DRENTRY1 DRENTRY1   //Door Entry
DWPSND1  DWPSND1    //bolt sound
DWIND1   DWIND1     //wind random

DDRIP1   DDRIP1     //water drip
DHOWL1   DHOWL1     //howling noise
CHALLNGE CHALLNGE   //challenge
SCORE    SCORE      //clock started
WIND1    WIND1      //more wind random
ELECTRIC ELECTRIC
QUAKE    QUAKE

CREAKY-1 CREAKY-1
METALDRO METALDRO

WATCHTIK WATCHTIK
WATCHTOK WATCHTOK

THUNDERB THUNDERB
TM-POUR  TM-POUR
THUNDERA THUNDERA
RAINMORE RAINMORE
POUR     POUR
ELECTRI1 ELECTRI1

HOWITZER HOWITZER

LAUGH1   LAUGH1
LAUGH2   LAUGH2
LAUGH4   LAUGH4
LAUGH5   LAUGH5

CHANCE1  CHANCE1
CHANCE%  CHANCE%

MACHINE  MACHINE

// just all here to order them - not all used for ambients 

$AMBIENT 1  DRSPLIT1 POINT 1.0 PERIODIC 35.0 1.0
$AMBIENT 2  DRSLIDE1 POINT 1.0 PERIODIC 35.0 1.0
$AMBIENT 3  DROTATE1 POINT 1.0 PERIODIC 35.0 1.0
$AMBIENT 4  DRENTRY1 POINT 1.0 PERIODIC 35.0 1.0
$AMBIENT 5  DWPSND1  POINT 1.0 PERIODIC 35.0 1.0

$AMBIENT 7  DDRIP1   POINT 1.0  RANDOM 3.0 10.0 0.5 
$AMBIENT 8  DHOWL1   POINT 1.0  RANDOM 1.0 6.0 1.0
$AMBIENT 9  DWIND1   POINT 1.0  RANDOM 1.0 10.0 1.0  
$AMBIENT 10 WIND1    POINT 1.0  RANDOM 1.0 10.0 1.0
$AMBIENT 11 ELECTRIC POINT 1.0  RANDOM 1.0 10.0 1.0
$AMBIENT 12 QUAKE    POINT 1.0  PERIODIC 35.0 1.0 

$AMBIENT 14 CREAKY-1 POINT 1.0  PERIODIC 35.0 1.0 
$AMBIENT 15 METALDRO POINT 1.0  PERIODIC 35.0 1.0 
$AMBIENT 16 WATCHTIK POINT 1.0  PERIODIC 35.0 1.0 
$AMBIENT 17 THUNDERB POINT 1.0  RANDOM 5.0 35.0 1.0 
$AMBIENT 18 TM-POUR  POINT 1.0  RANDOM 5.0 35.0 1.0 
$AMBIENT 19 THUNDERA POINT 1.0  RANDOM 5.0 35.0 1.0 
$AMBIENT 20 RAINMORE POINT 1.0  RANDOM 5.0 35.0 1.0 
$AMBIENT 21 POUR     POINT 1.0  RANDOM 5.0 35.0 1.0 
$AMBIENT 22 ELECTRI1 POINT 1.0  RANDOM 1.0 10.0 1.0
$AMBIENT 23 HOWITZER POINT 1.0  RANDOM 1.0 10.0 1.0

$AMBIENT 24 MACHINE  POINT 1.0  CONTINUOUS 1.0 

// replace door sounds

doors/dr1_open   METALDRO
doors/dr1_clos   METALDRO

weapons/chngun   DMACHGUN

// WORLD AMBIENTS
// thunder and lightning

world/ambient1 THUNDERA
world/ambient2 WIND1
world/ambient3 THUNDERB

$AMBIENT 25 world/ambient1 POINT 1.0  RANDOM 5.0 35.0 1.0
$AMBIENT 26 world/ambient2 POINT 1.0  RANDOM 5.0 35.0 1.0
$AMBIENT 27 world/ambient3 POINT 1.0  RANDOM 5.0 35.0 1.0

// $WORLD SOUNDS MUST BE RANDOM TYPES

// $WORLD LogicalGroupName { logname1 logname2 etc. }
 
$WORLD world/ambient { world/ambient1 world/ambient2 world/ambient3 }

==========================================================================================
 SAMPLE SNDINFO SCRIPT (used in Herian2.wad)
 This script uses descriptive logical names.
==========================================================================================

beast		dsbeast
deepbell	dsbell
highbell	dsbells
raven		dsbird
insects		dsbugs
chainrattle	dschains
forgehammer	dsclang
crickets1	dscrick1
crickets2	dscrick2
singledrip	dsdrip
repeatdrip	dsdrips
dripdrop	dsdrop
burning		dsfire
frogcroaking	dsfrog
loudgong	dsgong
heartthumping	dsheart
heretichead	dshelmet
hexenkatydid	dskaty
knight		dsknght
mixerturning	dsmixer
rodent		dsmouse
owlhooting	dsowl
raining		dsrain
riverflow	dsriver
fallingrocks	dsrocks
forestwalk	dsrustle
diveinwater	dssplash
steelecho	dssteel1
steelscreech	dssteel2
fallingstone	dsstone
streamflow	dsstream
thunder		dsthnder
waterfall1	dswaterf
waterfall2	dswfall
tornado		dswhirl
windy		dswind1
stormy		dswind2
blaze		dsblaze
boilinglava	dsboil
danger		dsdanger
caution		dsdeep
tunnel		dshollow
nighttime	dsnight
midnight	dsnight
whistle		dswhist
lightning	dsthund
seashore	dssurf
thunderstorm	dsstormy
jungledrums	dsjungle
hurricane	dshurric
eagle		dseagle
crow		dscrow
creak		dscreak
creature	dsape
shiphorn	dshorn

$AMBIENT 1 beast RANDOM 30.0 60.0 0.6
$AMBIENT 2 deepbell POINT PERIODIC 10.0 1.0
$AMBIENT 3 highbell POINT PERIODIC 15.0 1.0
$AMBIENT 4 raven POINT RANDOM 3.0 12.0 1.0
$AMBIENT 5 insects POINT RANDOM 2.0 5.0 1.0
$AMBIENT 6 chainrattle POINT RANDOM 5.0 10.0 0.6
$AMBIENT 7 forgehammer POINT PERIODIC 10.0 0.7
$AMBIENT 8 crickets1 POINT RANDOM 3.0 9.0 0.8
$AMBIENT 9 crickets2 POINT RANDOM 3.0 9.0 0.8
$AMBIENT 10 singledrip POINT PERIODIC 3.0 0.7
$AMBIENT 11 repeatdrip POINT RANDOM 3.0 7.0 0.9
$AMBIENT 12 dripdrop POINT PERIODIC 4.0 0.7
$AMBIENT 13 burning POINT CONTINUOUS 0.2
$AMBIENT 14 frogcroaking POINT RANDOM 2.0 10.0 1.0
$AMBIENT 15 loudgong POINT PERIODIC 180.0 0.9
$AMBIENT 16 heartthumping POINT PERIODIC 5.0 0.9
$AMBIENT 17 heretichead RANDOM 10.0 20.0 0.5
$AMBIENT 18 hexenkatydid POINT RANDOM 3.0 12.0 0.9
$AMBIENT 19 knight POINT RANDOM 5.0 15.0 0.7
$AMBIENT 20 mixerturning POINT CONTINUOUS 0.5
$AMBIENT 21 rodent POINT RANDOM 5.0 12.0 0.6
$AMBIENT 22 owlhooting POINT PERIODIC 15.0 0.7
$AMBIENT 23 raining POINT CONTINUOUS 0.6
$AMBIENT 24 riverflow POINT CONTINUOUS 1.0
$AMBIENT 25 fallingrocks POINT RANDOM 9.0 18.0 0.7
$AMBIENT 26 forestwalk POINT RANDOM 10.0 25.0 0.7
$AMBIENT 27 diveinwater POINT RANDOM 10.0 30.0 0.8
$AMBIENT 28 steelecho POINT PERIODIC 10.0 0.7
$AMBIENT 29 steelscreech POINT RANDOM 10.0 20.0 0.8
$AMBIENT 30 fallingstone RANDOM 5.0 15.0 0.7
$AMBIENT 31 streamflow POINT CONTINUOUS 1.0
$AMBIENT 32 thunder RANDOM 20.0 60.0 0.8
$AMBIENT 33 waterfall1 POINT CONTINUOUS 1.0
$AMBIENT 34 waterfall2 POINT CONTINUOUS 0.8
$AMBIENT 35 tornado RANDOM 10.0 40.0 0.7
$AMBIENT 36 windy POINT CONTINUOUS 1.0
$AMBIENT 37 stormy POINT CONTINUOUS 1.0
$AMBIENT 38 blaze POINT CONTINUOUS 0.5
$AMBIENT 39 boilinglava POINT CONTINUOUS 0.7
$AMBIENT 40 danger POINT CONTINUOUS 0.8
$AMBIENT 41 caution POINT CONTINUOUS 0.8
$AMBIENT 42 tunnel POINT CONTINUOUS 0.7
$AMBIENT 43 nighttime RANDOM 10.0 30.0 0.7
$AMBIENT 44 midnight POINT CONTINUOUS 0.8
$AMBIENT 45 whistle POINT RANDOM 15.0 30.0 0.8
$AMBIENT 46 lightning RANDOM 15.0 30.0 1.0
$AMBIENT 47 seashore POINT CONTINUOUS 0.9
$AMBIENT 48 thunderstorm RANDOM 5.0 20.0 1.0
$AMBIENT 49 jungledrums POINT CONTINUOUS 1.0
$AMBIENT 50 hurricane POINT CONTINUOUS 0.9
$AMBIENT 51 eagle POINT RANDOM 5.0 15.0 0.9
$AMBIENT 52 crow POINT RANDOM 3.0 15.0 0.9
$AMBIENT 53 creak POINT PERIODIC 10.0 0.8
$AMBIENT 54 creature POINT RANDOM 5.0 15.0 0.9
$AMBIENT 55 shiphorn PERIODIC 30.0 1.0
==========================================================================================


GMJ January 2008