*==============================================================*
* TeamFortress v1.2								tfortmap.txt   *
*==============================================================*
Introduction
------------

If you haven't read the readme.txt by now, please do.

This file contains details about making Maps specifically
for TeamFortress. You don't need to know these details to 
play the game, even on a TeamFortress Map.

If you do make a TeamFortressMap, could you mail us and tell us? 
We'd like to create a collection of TeamFortressMaps on the 
WWW page (http://minyos.its.rmit.edu.au/~cookj)

The first map using these specs is available on the www page now.
Don't forget you can simply view the .bsp file to look at the
entities inside the map.

It just shows a simple use of these to make a Capture-The-Flag map.
It could easily be expanded to have multiple flags, with multiple
places to have them taken to, in certain orders...etc

More info on anything mentioned here may be in the readme.txt

Oh, and some variables we use for the Goal entities are variables
used for completely different things for other entities. We did
this to preserve variable space.

Robin and John.

------------------------------
TeamFortressMap Specification
------------------------------
Apart from being a normal map, TeamFortress Maps 
have the following changes:

	Auto Detection
	Team SpawnPoints
	Armor 				 (Still to be Done. :)

	Goals
	GoalItems
	Timer Goals

----------------------------------------------------------------------------
Auto Detection
----------------------------------------------------------------------------
TeamFortress maps will be automatically detected by the TeamFortress patch
if you put an entity in the map with a classname of "info_tfdetect".
This makes TeamFortress automatically turn on the FORTRESSMAP toggleflag,
and turn on teamplay.
In the future, this entity will be used to automatically set _any_
toggleflag, and some other stuff.

Also, once the TeamFortress map has been detected, the patch will look
for any spawnpoints dedicated to teams (see below).
If it finds any, it will look for the highest team number that is used.
Once found, it will limit anybody attempting to join a team to that 
number.
E.g. If the highest team number used by a Team Spawnpoint is 3, then
	 the patch will only allow players to join teams 1, 2, and 3.

----------------------------------------------------------------------------
Team Spawnpoints
----------------------------------------------------------------------------
There is now a new entity for Team Spawnpoints. Team Spawnpoints are used
to make players only spawn in points designated for their team. Use it
to make players spawn inside their own base/fortress.
The entity is called "info_player_teamspawn", and the "team_no" variable
sets the team_no that owns this spawnpoint.

----------------------------------------------------------------------------
Goal Summary / Terminology
----------------------------------------------------------------------------
Goals are the really fun things you can do with TeamFortressMaps.
A goal is simply an entity you place in a map. It is then handled
in the game based on the flags you give it. They're essentially
more complex triggers. I've kept all the code separate from 
the triggers tho, to allow us to toggle the use of them ingame.
The flags and variables set for a Goal allow us to create powerful
maps without changing the QuakeC code at all.
-----------
Goals 
-----------
Goals are always in one of the following states:

ACTIVE	:	The goal has been activated in some way. 
			It cannot be touched by a player.
			Active goals return to the INACTIVE state based on their
			result criteria, or when they're forced into INACTIVE state
			by another goal.

INACTIVE:	The goal is not active. 
			It can be touched by players, and if the players meet the 
			activation criteria, the goal moves	to the ACTIVE state.

REMOVED :	The goal is not active.
			It cannot be touched by players.
			Removed goals can still be activated by other goals, in which
			case they move to the ACTIVE state.
			Removed goals can be restored to the INACTIVE by being restored
			by another goal.

Terminology
-----------

activated	: Goal moves to the ACTIVE state
inactivate	: If the Goal is in ACTIVE state, it moves to the INACTIVE state
removed		: Goal moves to the REMOVED state
restored	: If the Goal is in REMOVED state, it moves to the INACTIVE state

returned	: GoalItems can be returned to their starting point, based on
			  a number of settings.

Goal Group  : A group of goals that can be altered as one.

Activating Player(AP): The player who either touched the Goal, or set the
					   detpack which touched the Goal.

Actions
-------
When goals go to ACTIVE state, they can perform various actions.
These include:

	- Increase the score of the team the AP belongs to.
	- Display a message to all players
	- Display a message just to the AP

	- Alter the AP's health/ammo/armor/powerups

	- Give the AP a GoalItem
	- Remove a GoalItem from an AP

	- Activate another goal, applying the bonuses of the goal to the AP
	- Activate another goal, without applying the bonuses of the goal to the AP
	- Inactivate another goal
	- Remove another goal
	- Restore another goal

	- Activate a goal if all the goals in a goal group are now ACTIVE
	- Activate a group of goals
	- Inactivate a group of goals
	- Remove a group of goals
	- Restore a group of goals

	- Display team's scores and End the Level

Activation
----------
Goals can be activated in one of the following ways:

	- Touched by a player
	- Touched by a detpack explosion
	- Activated by another Goal
	- Activated by a Goal Group command from another Goal

Additionally, the AP's details can be checked.
This allows you to have goals that are only activated if:

	- The AP is of a particular class
	- The AP has a particular GoalItem
	- The AP is of a particular team

Inactivation
------------
Goals can be inactivated in one of the following ways:

	- Inactivated after being ACTIVE for a specified time
	- Inactivated by another Goal
	- Inactivated by a Goal Group command from another Goal

Also, some goals are marked as Multiple Goals. They return to INACTIVE
state immediately after they become ACTIVE.

Removal
-------
Goals can be removed in one of the following ways:

	- Removed after being activated
	- Removed by another Goal
	- Removed by a Goal Group command from another Goal

Restoration
-----------
Goals can be restored in one of the following ways:

	- Restored by a GoalItem when it Returns (See below).
	- Restored by another Goal
	- Restored by a Goal Group command from another Goal

---------
GoalItems
---------
GoalItems are items that players can carry around.
GoalItems can be placed directly into a map, where a player
can collect them as usual.
Also, on activation, Goals can give/remove GoalItems from the AP.
The details of players attempting to collect the GoalItems can
also be checked.
This allows you to have GoalItems that can only be picked up if:

	- The Player is of a particular class
	- The Player has a particular GoalItem
	- The Player is of a particular team

GoalItems can be returned to their starting position in any of the
following circumstances:

	- When it's dropped by a dying player
	- When it's removed from an AP by a Goal activation
	- When it's untouched for a specified time

-----------
Timer Goals
-----------
There is also a special type of goal called a Timer Goal. TG's 
have a Timer Delay. TG's start INACTIVE, and then every Timer
Delay seconds they activate, do their results, and inactivate.
They can also be forced to activate by other Goals. They cannot
be activated by player or detpack touches.
N.B. When a TG goes ACTIVE, it does not have any AP, and hence
	 _cannot_ do any operations on players, or _activate_ other goals.

N.B. When a TG is forced to activate by another goal, they reset
	 their internal timer that decides when they are next going
	 to activate. 
	 E.g. If a TG with a setting of 5 seconds is forced to activate,
		  it will reset it's  timer, and still activate 5 seconds after
		  it was forced to activate.

So, as a quick summary, TG's can have their state altered as 
usual by other goals, and when they activate, they can:

	- Display a message to all players

	- Inactivate another goal
	- Remove another goal
	- Restore another goal

	- Inactivate a group of goals
	- Remove a group of goals
	- Restore a group of goals

	- Display team's scores and End the Level

At the moment, TG's are handled in an ugly way, so be extremely 
careful when using them. The next release of this should have them 
wrapped up in a neat little package, where you can't do 
anything wrong with them :)

----------------
Order of Actions
----------------
You don't really need to know the order in which the actions are applied,
but here it is anyway:

Screen Flash

Display Broadcast Message
Display Personal Message
Increase Team Score

Apply Stats to AP
Apply Powerups to AP
Update Ammo display

Give GoalItem to AP 	(if any)
Remove GoalItem from AP (if any)

End Level				(if set)

Goal Group Checking
	Activate another Goal if all Goals in Group are active	(if set)
	Activate all goals in a Group							(if set)
	Inactivate all goals in a Group							(if set)
	Remove all goals in a Group								(if set)
	Restore all goals in a Group							(if set)

Active Another Goal		(if any)
Remove Another Goal		(if any)
Restore Another Goal	(if any)
Inactivate Another Goal	(if any)

----
N.B. The Group Goal alterations are applied _before_ the single goal 
	 alterations. This is so you can do things like: 
	 Inactivate an entire group, and then activate one goal in that group.
	 Remove an entire group, and then restore one goal in that group.

----------------------------------------------------------------------------
Goal Technical Info
----------------------------------------------------------------------------
Goal behaviour is entirely defined by the variables of the Goal object
when it is spawned at the start of the level. These variables are set
in the map file. Just add up the flags that you want and set the 
variable to that. 
E.g. If you want a goal that can be activated by a Player touch(1) and
	 a detpack explosion(2), you would set the "goal_activation" variable
	 to 3.
An example goal may look like this:
{
	"classname" 		"info_tfgoal"
  	"origin"    		"-196 -8 -228"
	"goal_no"   		"6"
	"group_no"  		"2"
	"wait"      		"5"
	"goal_activation" 	"1"
	"goal_result" 		"2"
	"message"   		"Goal!\n"
}
This goal would print "Goal!" when activated. It would then stay
active for 5 seconds, during which time it could not be activated
again. It would then move back to INACTIVE state.
Don't worry! It's actually fairly easy :)
N.B. Bit descriptions marked with (*) are dangerous, and should
	 be handled with care.

The variables of the Goals are handled as follows:

	classname 	:	"info_tfgoal"
	netname		:	Message broadcasted when this goal is activated, if any.
				    Don't forget to put the \n at the end of it.
	message		:	Message displayed to the activating player, if any.
				    Don't forget to put the \n at the end of it.
	killtarget	:	Message broadcasted if the goal	kills the activating
					player. It is appended to the name of the player.
					E.g. deathtype = " gets killed by a goal!\n" displays
						 Bro gets killed by a goal!
					Not needed if this goal doesn't do damage to a player.
					Don't forget to put the \n at the end of it. 
	count		:	Score the team of the player who activates this goal gets.
					Use negative numbers for penalty goals.
	goal_no		:	A unique number ID identifying this goal. Used to make
					references to this goal in other goals.
	group_no	:	The number of the goal group this goal belongs to.
	
All the following attributes are applied to the attributes of
the player who activates the goal. (e.g. the self.health is added to
the health of the player who activates the goal)
	health		 :	Use negative values to hurt the player
	armortype	 : 	Use negative values to remove armor % reduction
	armorvalue	 :	Use negative values to remove armor
	frags		 :	Use negative values to lower frag count
	ammo_shells  :	Use negative values to remove ammo
	ammo_nails   :	Use negative values to remove ammo
	ammo_rockets : 	Use negative values to remove ammo
	ammo_cells   :	Use negative values to remove ammo
	ammo_medikit :	Use negative values to remove ammo
	ammo_detpack :	Use negative values to remove ammo

Note A:	After applying all these values to the player who activated the
		goal, the playerclass limitations of the player are applied. So
		if you set the health of the activating player over that allowed,
		by his/her playerclass, it will then be lowered to the max_health
		for that playerclass.

TeamFortress Grenades can be given/removed to/from the player by setting
the following two variables.
	no_grenades_1	:	Use negative values to remove grenades
	no_grenades_2	:	Use negative values to remove grenades

And finally, the following attributes are added to the global time
and applied to player who activated the goal. (e.g. if the goal's
invincible_finished is 5, then they player who activated the goal will
get invincibility for 5 seconds after activating the goal.)
	invincible_finished		:	Pentagram of Protection 	
	invisible_finished		:	Ring of Shadows
	super_damage_finished	:	Quad Damage
	radsuit_finished		:	Environmental Suit

---------------------------
Goal Activation
---------------------------
The "goal_activation" of the goals determine how the goal is activated. 
The bitfields are as follows:

Activation Details
	1	:	Activated when touched by a player.
	2	:	Activated when touched by a detpack explosion.

AP Details
	4	:	AP must be carrying a GoalItem. 
			The ID of the GoalItem is specified in "items_allowed". 
	8	:	AP must be of a specific class. 
			The	class is specified in the "playerclass" variable of the goal.
	16	:	AP must be of a specific team. 
			The	team is specified in the "team_no" variable.
    32  :	This goal is a Timer Goal. See Timer Goals above.
   			The Timer Delay is specified in the "search_time" variable. 


---------------------------
Goal Results
---------------------------
The "goal_result" of the goals determine how the goal behaves when it is 
activated, and the results of it's activation. 
The bitfields are as follows:

Respawn behaviour
	1	:	The goal immediately removed after it is activated.
	2	:	The goal stays ACTIVE for the amount of time in the "wait",
			and is then inactivated.

GoalItem behaviour
	4	:	The goal gives a GoalItem to the AP.
			The ID of the GoalItem is specified in "items". 
	8   :	The goal removes a GoalItem from the player if they have it,
			The ID of the GoalItem is specified in "axhitme".

Goal behaviour
	16	:	Activate a goal.
			The ID of the Goal is specified in "impulse". 
	32	:	InActivate a goal.
			The ID of the Goal is specified in "distance". 
	64  : 	Remove a goal.
			The ID of the Goal is specified in "waitmin". 
	128	:	Restore a goal.
			The ID of the Goal is specified in "waitmax". 
	256	:	If this is set, the goal activated by (16) adds it's bonuses
			to the activating player's stats.

Miscellaneous
	512 :	Display teamscores, fire intermission, and end the level

----
Note A: If neither (1) or (2) are set, then the goal is a Multiple Goal.
		After it activates, it will automatically inactivate.
		This is not always a good idea. When a player runs over an entity,
		the touch function will usually be run about 6 or 7 times, so the
		player will activate the goal multiple times. If you want a player
		to be able to activate it over and over again, make it respawn 
		every 2-3 seconds.
		This is especially dangerous if the goal gives out an item on
		activation, since you will end up with a _lot_ of items.
		Of course, you may want this for a goal that is activated remotely
		by another goal at certain times.

Note B: (16) through to (128) allow you to alter the state of other goals.
		If you want multiple goals altered by this goal, you probably
		want to use a goal group instead. See below.

Note C:	When a goal is activated by another goal, _no_ checking is done
		based on the "goal_activation" variable of the target goal. It is
		simply activated. The AP who activated the original goal is used
		as the activator for all the goals, but the stats of the activated
		goal are only added to the player's if (256) is set on the first
		goal. 
		GoalItems are always given.

---------------------------
Goal Groups
---------------------------
Goal groups allow you to do operations of multiple goals in one go.
The "group_no" of a Goal defines the ID of goal group it is in.
Any goal group operation affects all goals with the specified ID.
A goal's "goal_group" specifies what operations, if any, it performs
on any goal groups.
The bitfields are as follows:
	1	:	If all goals in the group specified by the ID in "height" are 
			currently activated, activate a goal.
			The ID of the Goal is specified in "last_impulse". 
	2	:	Activate all goals in a group
			The ID of the Group is specified in "aflag". 
	4	:	Inactivate all goals in a group
			The ID of the Group is specified in "dmg". 
	8	:	Remove all goals in a group
			The ID of the Group is specified in "cnt". 
	16	:	Restore all the goals in a group
			The ID of the Group is specified in "pausetime". 

----
Note A: When a goal is activated by another goal, _no_ checking is done
		based on the "goal_activation" variable of the target goal. It is
		simply activated. The AP who activated the original goal is used
		as the activator for all the group goals.
		Bonuses of goals in groups are _never_ applied to the activating player.
		GoalItems are always given.

----------------------------------------------------------------------------
Goal Items
----------------------------------------------------------------------------
GoalItems do not have to be given to a player by a Goal activation.
The variables of the GoalItems are as follows:

	classname 	:	"item_tfgoal"
	netname  	:	Name of this GoalItem.
	message		:	Message broadcasted when this goalitem is retrieved, if any.
				    Don't forget to put the \n at the end of it.
	deathtype	:	Message displayed to a player when they get the Item, if any.
				    Don't forget to put the \n at the end of it.
	noise		:	A .wav file played when the item is collected, if any. 
					Make sure it's a .wav file you've got. It's probably 
					best to use one of Quake's .wavs. 
					It defaults to the key pickup.
	mdl			:	The .mdl file used for this item. Make sure it's a .mdl
					file you've got. It's probably best to use one of Quake's
					.mdls. It defaults to the silver key.
	goal_no		:	A unique number identifying this GoalItem. Used to make
					references to this Item in goals.

GoalItems themselves have various bitfields to depict the GoalItem's
behaviour. The bitfields are stored in the GoalItem's "goal_activation"
variable, and are:

Carrying Details
	1	:	Any player carrying this item will glow.
	2	:	Any player carrying this item will move at half-speed.
(*)	4	:	When a player carrying this is killed, the item will be dropped

Returning
	8	:	Return the item	if dropped by a dying player
	16	:	Return the item if removed from a player by a goal activation.
	32	:	Return the item if removed from the map by the action of (256).
	64	:	When this item is returned to it's original position, restore
			a goal. The ID of the Goal is specified in "impulse". 

Pickup Details
	128	:	Player must be carrying a GoalItem to get this item. 
			The ID of the GoalItem is specified in "items_allowed". 
	256	:	Player must be of a specific class to get this GoalItem.
			The	class is specified in the "playerclass" variable of the goal.
	512	:	Player must be of a specific team to get this GoalItem.
			The	team is specified in the "team_no" variable.

Miscellaneous
   1024 :	GoalItem does not exist until given to a player by a Goal
   2048 :	Remove GoalItem if left untouched after being dropped by a player
			for more than the number of minutes specified in the "delay" variable.

----
Note A: (4) is dangerous. If you have goals giving out this item multiple
		times, make sure the item is getting removed somehow, or you could
		end up with too many items on the map.

Note B: The Pickup details (128)(256)(512) are only used when a player picks
		up this item directly. If this item is given to an AP by a goal, these
		are ignored.

Note C:	If (1024) is set, the GoalItem is not actually placed in the map at the
		start of the level.	Once a player activates the Goal that gives this 
		item to him/her, it will be spawned. Use this bit for items that 
		will never actually be seen by the player, or for items that are never 
		seen until they're dropped by a dying player carrying them. If this 
		bit is set, and (4) is not set, then you don't need to specify a
		.mdl file, since this item will never be seen.

Note D: (2048) allows you to make items that are untouched for a while
		disappear. This should be set if you have Goals that give out
		multiple copies of GoalItems that are dropped when players carrying
		them are killed. Otherwise you could end up with too many entities
		on the map :)
		If you have a GoalItem that is only given out once and is dropped
		when players with it die, you will probably want to set this flag
		and flag (32), so that if it falls in lava or something, it'll 
		be returned.
		The time it takes before it is removed can be set in the "delay"
		variable. It defaults to 2 minutes if you don't specify one.

---------------------------
Future Additions
---------------------------
Goals need to be attached to triggers, so that activations of a goal
can fire a standard Quake trigger, and vice versa.
Also, goals need to be able to be triggered when they take 
a certain amount of damage.
Timer Goals need to be smarter. I'd like them to be able to somehow
get an AP, and let them activate other goals. Maybe even activate
goals using All the players on a map...

---------------------------
Hopefully, I'll release a map soon that will look crap,
but it'll have lots of gratuitous use of goals, showing the
sort of things that can be done with them.

In the meantime, muck around with them.
I haven't been able to test everything extensively, so any
comments, suggestions, and bug reports are welcome as
usual.
In fact, this is probably the first chunk of code I've that
took far longer to test than it did to write!

So far, I've tested everything fairly well except Timer Goals and
Goal Groups. If you use either of these, and see strange behaviour,
please mail me and tell me.
You may just want to wait a week or so before using either of these
instead. It should only take me a 3-4 days to test them well myself,
and add in attachment to standard Quake triggers.

And if you think of any more things goals could do when activated,
please don't hesitate to mail them to me.

Robin.