=============================================
Open Jedi Project Animation Event Information
=============================================

$Revision: 1.1 $

========================
0000 - Table of Contents
========================

	0000..................Table of Contents
	0001..................Introduction
	     0001.1...........Limitations
	0002..................Standard Animevents
	0003..................Ambient Model Sounds
	0004..................Examples



===================
0001 - Introduction
===================

	The animevents.cfgs are a very powerful config files allow you quickly and easily add new sound effects, visual effect, (OJP only) ambient model sounds.  OJP has gone thru the MP animevent code and fixed/added code to give you full access to these powers.

	OJP Powered animevents.cfg Features:

	- Set foodsteps sounds for animations.

	- Set any sound and some special effects to any part of any animation.

	- Set two seperate ambient sounds (breathing, equipment beeping, etc).

	- You can merge in other animevents.cfg by using a "include filename" in your animevents.cfg files.  Be sure to do all your includes before doing any animevent declarations.

	- animevents are client side so players can choose which animevents.cfg they use.

	To use an animevents.cfg, just place it (or create one) in the model folder for the model you want it to play for.  It doesn't have to be in the same pk3 as the model.  If you want the animevent.cfg to apply to all the player models, just place your animevents.cfg in the /models/players/_humaniod folder.

	There are two catagories for animation events:
		UPPEREVENTS - Effects that are linked to the torso animations.
		LOWEREVENTS - Effects that are linked to the leg animations.

--------------------
0001.1 - Limitations
--------------------

	- Only one animevent of each type is allowed for each frame of animation.  For ambient sounds, you're allow one UPPEREVENTS ambient and one LOWERSEVENTS.  If there's more than the allowed limit of any animevent, the last declared event will be used.  

 

==========================
0002 - Standard Animevents
==========================

	(Most of this section was copied from one of Raven's animevents.cfg files.)

	Sound Effects
	Format: animID AEV_SOUNDCHAN framenum soundpath channel randomlow randomhi chancetoplay
 
	animID = Animation enum/name
	AEV_SOUNDCHAN = tells game which type of event it is (so it knows what to do with the following data)
	framenum = Frame into sequence where event should start
	channel = sound channel on which to play the sound.
	soundpath = path to the sound to play 
			%d - Means the next 2 numbers are the random range. For example, if you want to play laser1, laser2 or laser3, use "laser%d 1 3") 	
			* - Means that this sound file is to be played from the model's individual sound set.  For example, it you want the model's taunt1 sound to be played, you'd use "*taunt1.mp3"
	randomlow = low number for sound variant (if no variant, use 0)
	randomhi = high number for sound variant (if no variant, use 0)
	chancetoplay = probability event will play (0 = always, 1-99 is percentage of chance to play)

	Footsteps 
	format: animID AEV_FOOTSTEP framenum footstepType chancetoplay
	
	animID = Animation enum/name
	AEV_FOOTSTEP = tells game which type of event it is (so it knows what to do with the following data)
	framenum = Frame into sequence where event should start
	footstepType = FOOTSTEP_R, FOOTSTEP_L, FOOTSTEP_HEAVY_R or FOOTSTEP_HEAVY_L
	chancetoplay = probability event will play (0 = always, 1-99 is percentage of chance to play)

	Notes:  Footsteps should only be used for LOWEREVENTS.

 	Special Effects
	Format: animID AEV_EFFECT framenum effectpath boltName chancetoplay

 	animID = Animation enum/name
 	AEV_EFFECT = tells game which type of event it is (so it knows what to do with the following data)
 	framenum = Frame into sequence where event should start
 	effectpath = path to the .efx file you want to play - if you put "special" it will play the hard-coded in-engine effect specified in the next field (usually boltName)
 	boltName = bolt (if any) to play the effect on.  If none use "none" or "NULL" - if you put "special" in the effectpath, this is the name of the hard-coded in-engine effect to do and the next field is how many milliseconds to do it for
	chancetoplay = probability event will play (0 = always, 1-99 is percentage of chance to play) - if you put "special" in the effectpath, this is how many milliseconds to do the hard-coded in-engine effect for



===========================
0003 - Ambient Model Sounds
===========================

	Ambient models sounds are sounds that are played at set intervals while the model is ingame and alive.  Good uses for this feature are Vader's breathing, equipment beeping, etc.  Althou ambients are not linked to the animations they are sorted in the UPPEREVENTS and LOWEREVENTS for ease of use.  Each model may have one UPPEREVENTS ambient sound and one LOWEREVENTS ambient sound.

	Ambient Sounds
	Format: AEV_AMBIENT intervals randomfactor Channels soundpath randomlow randomhi chancetoplay
	
	AEV_AMBIENT = tells game which type of event it is (so it knows what to do with the following data)
	intervals = The base time between attempts to play this sound.  This is affected by the random factor at runtime (in msecs.  This needs to be set (taking in account the randomfactor) so that the time intervals are never shorter than the length of the sound file.  If you don't do this correctly, your ambient sounds will overlap and sound terrible.
	randomfactor = This gives a random factor to the time between sound attempts (in msecs).  The base time is added or subtracted by a random number between 0 and randomfactor.  This needs to be set (taking in account the intervals) so that the time intervals are never shorter than the length of the sound file.  If you don't do this correctly, your ambient sounds will overlap and sound terrible.
	channel = sound channel on which to play the sound.
	soundpath = path to the sound to play 
			%d - Means the next 2 numbers are the random range. For example, if you want to play laser1, laser2 or laser3, use "laser%d 1 3") 	
			* - Means that this sound file is to be played from the model's individual sound set.  For example, it you want the model's taunt1 sound to be played, you'd use "*taunt1.mp3"
	randomlow = low number for sound variant (if no variant, use 0)
	randomhi = high number for sound variant (if no variant, use 0)
	chancetoplay = probability event will play (0 = always, 1-99 is percentage of chance to play)

	Examples:

	AEV_AMBIENT          5000            0 CHAN_AUTO         *taunt%d.mp3                             1 3  50
	
	This ambient plays a random taunt (taunt 1, 2, or 3) of this model every 5 secs (5000 msecs) 50% of the time.

	AEV_AMBIENT          5000            1000 CHAN_AUTO         *land1.mp3                             0 0  0
	
	This ambient is set to play the breathing effect for cheshire_arco_vader's Lord Vader model.  It plays the breathing sound file every 4-6 seconds.



===============
0004 - Examples
===============


-----
//Use the default humanoid sounds plus an extra taunt for when this model misses a grapple attack and 
//also randomly say a taunt every once in a while.
include _humanoid

UPPEREVENTS
{
	BOTH_KYLE_MISS       AEV_SOUNDCHAN   1 CHAN_AUTO         *taunt%d.mp3                             1 3  0
}

LOWEREVENTS
{
	AEV_AMBIENT          5000            0 CHAN_AUTO         *taunt%d.mp3                             1 3  50
}

