README file for new audio system

1) The actual audio is now organized differently, as follows:

	a) ALL WAV effects are in one directory, 'audio/effects'
	b) ALL music in the game (i.e., not credits yet) is in OGG/Vorbis
		format.
	c) ALL music is divided into exactly two directories:
		i) 'audio/music/bs' is for all bardsongs
		ii) 'audio/music/env' is for all environment audio

2) Config file format has changed.  The rules for the new format are:

	A config file is a set of lines, each being a comment, specified
	by a '#' in the first column, or of exactly the following format:

	<keyword> <arg1> [<arg2> [<arg3>]]

	Keywords are:

	'main', followed by one argument, specifies the main background music
	(i.e., OGG file) for the environment - argument is relative path to the
	file (i.e., 'audio/env/town0.ogg')

	'intro', followed by one argument, specifies an intro music (i.e., OGG
	file) for the environment.  This intro will be played exactly once, and
	will be followed by the 'main' music.  The argument is the relative path
	to the file (i.e., 'audio/env/treasure.ogg')

	'random', followed by two arguments, specifies a randomly played effect
	(i.e., WAV file) for the environment.  The first argument is the relative
	path to the file (i.e., 'audio/effects/rooster.wav'), and the second
	argument is the probability, in chances out of 1000, that this particular
	effect will be played in at a particular random check.  Good values are
	between 5 and 50.

	'timed', followed by three arguments, specifies a timed played effect
	(i.e., WAV file) for the environment.  The first argument is the relative
	path to the file (i.e., 'audio/effects/belltoll2.wav'), the second
	argument is the time, in 24-hour 'hh:mm' format, at which the effect
	should be played.  The third argument is the tolerance, in minutes, applied
	to the time above - i.e, how many minutes following the above time is still
	'close enough'.  It is *STRONGLY* recommended that this value be at least 1,
	good values are probably 5-10 for most things.

	'named', followed by two arguments, specifies a named effect (i.e., a WAV
	file) for the environment.  Named effects will be played when called
	explicitly - for now, only in the main code, eventually there will be
	scripting support.  This is what we'll use for things like sword swishes,
	spell effects, etc.  The first argument is the relative path to the file
	(i.e., 'audio/effects/wolf1.wav'), and the second is the name for the effect
	(i.e., 'Wolf').

3) Config files live (generally, at least) in the 'audio/config' directory

4) Bard song config file format remains unchanged.

5) Main audio config format is changed.  The main audio config file can be found
	as 'data/audio.dat'.  The rules for the new format are:

	A config file is a set of lines, each being a comment, specified
	by a '#' in the first column, or of exactly the following format:

	<keyword> <arg1> [<arg2>]

	Keywords are:

	'bardsongs', followed by one argument, specifies the location of the
	master bard song config file (who's format has not changed).  The
	argument is the relative path to said config file (i.e.,
	'audio/config/bardsong.dat').

	'rain', followed by one argument, specifies the root location of the
	three rain effect files.  These files are named 'rain1.wav', 'rain2.wav'
	and 'rain3.wav', and must reside in the directory pointed to by this
	directive.  The argument is the relative path (i.e., 'audio/effects').

	'env', followed by two arguments, specifies a named environment.  The
	first argument is the relative path to the config file (i.e.,
	'audio/config/WeaponShop.dat'), and the second argument is the name
	of the environment (i.e., 'WeaponShop').  These names are then used
	either in the code, or in scripts, to specify audio environments.  Maps
	point directly to environment config files, as before.

	'global', followed by a single argument, specifies the relative path to
	the global environment config file (i.e., 'audio/config/global.dat').
	This config file (technically, a full environment) is really only used
	for named effects that are common throughout the game, such as the
	various death sounds, weapon sounds, etc.  If a named effect is requested,
	and it's not found in the currently active Environment, the global
	environment is checked before returning failure.

Questions/comments, let me know.  Enjoy ;-)

Justin
04/12/2002