                             QTeam 2.5 beta 1
                           by Quake Innovations

                         Map Design Documentation

Email        : Gary Griggs, qteam@stomped.com
Website      : http://qteam.stomped.com

I. Overview 

This document is geared towards people who want to design new maps to work
with QTeam. If all you want to do is play the game look at the text files,
client.txt and server.txt.

Congratulations on your decision to make maps for QTeam! The QTeam map design
package will give you all the information you need to create maps for Capture
the Flag, DeathTag, Capture the Shambler, Paintball, King of the Hill, 
Scavenger Hunt, and QFragFest. The large number of options that can be 
encoded into the maps for each game ensures that you can make your map
unique. Also provided in this package are a number of custom textures 
that you can use for marking areas in a map for specific teams.

Please refer to the CLIENT.TXT and SERVER.TXT documentation for more
information on running QTeam and playing the different games.

For the QTeam server and client packages, extra QTeam maps, and our other
products, please visit our website at http://qteam.stomped.com.

I. Overview by game mode

QTeam supports seven types of games although with the available options the
same game can be made radically different! 

A) Capture the Flag (CTF)

   In this game, teams must retrieve flags and return them to a base in order
   to score points. The map designer can take advantage of the following 
   options: 2-8 teams, any number of flags per team, any number of bases
   per team, different values for flags and bases, team weapons, team doors,
   shared flags and bases, dynamically sizing maps. Further details on the
   options is found later in this document.

   What can you do with these features? Here are just a few examples of
   combinations that will make for exciting games:

   1) Make a Standard CTF map that has allows for two teams, red and blue,
      and has one flag for each team, and one base for each team. 
   2) Make a 4 team CTF map that has one flag that is centered in a map
      and 1 base for each team, spread about the map. The action will be
      fast and furious as many players will be in the same vicinity 
      chasing the only flag carrier in the game.
   3) Make a 2 team CTF map that has one flag for each team and one base for
      each team, plus a bonus flag that either team can pick up.
   4) Make a 3 team CTF map that has the following items:

            1 flag per team worth 1 point 
            1 flag per team worth 2 points
            1 base per team worth 1 point
            1 base per team worth 2 points
            1 shared flag worth 3 points
            1 shared base worth 3 points

      The flags and bases should be placed such that the higher the value,
      the harder it is to reach. The players can carry more than one flag,
      so their worth increases with each picked up. Upon returning to base,
      the teams score is increased by the value of the flags the player
      was carrying multiplied by the base value. With a setup like this,
      a team must think about a strategy for scoring the most points. 
      Should they go for the easier and lower point items or take a risk
      and go for the gold?

B) Death Tag

   In this game, teams must work together to retrieve a flag. 

   The key differences between this mode and CTF mode are that there are no
   bases (you score immediately when you touch a flag) and the flag CANNOT
   be reached without the assistance of a teammate.

   The same options available for CTF maps are available in Death Tag
   maps also with the exception of placing bases. 

C) Scavenger Hunt

   In this game, teams must race to pick up as many flags as they can 
   before all the flags in the map have been picked up. The game ends when
   all flags in the map have been retrieved. The winner is the team that
   has retrieved the most flags or optionally the most points if flags
   are assigned different point values.

   The key differences between this mode and CTF mode are that there are no
   bases (you score immediately when you pick up the flag) and the game
   always ends on its own when all the flags have been retrieved.

D) Paintball

   In this game which is very similar to a regular deathmatch game, play 
   proceeds in a series of elimination rounds. A round is completed when only
   one team is left alive (there can be more than one player on this team).

   The flag and base options available in CTF are not available in paintball
   but team doors, team weapons, and most importantly, dynamically sizing
   maps are still supported. Additionally, there's support for holding cells
   to place eliminated players while they wait for a round to end (the 
   default is for them to go into observer mode).

E) Capture the Shambler

   In this game, teams must fight for control of the one shambler in the map
   and must lead him back to base. The shambler fights for the team he's on
   and follows the team leader. The other teams are constantly fighting to
   regain control of the shambler.

   Note, maps must be designed to include enough space for a shambler to move
   to any of the bases. 

F) King of the Hill

   In this timed game, a team must fight to occupy an area of a map
   (the 'Hill'). The winner is the team that has occupied the hill the
   when the game ends. The other teams of course will constantly be
   trying to infiltrate. All of the map options with the exception of flags
   are applicable to this game mode.

II. Map option details

A) Defining global game parameters & game info :

     The following tags belong in the worldspawn section of your map file

     qtmversion

       This defines the version of QTeam for which a map was designed. This 
       will allow all future versions of QTeam to continue working correctly
       with all maps. This is a required field.

     qtmgame

       Here's the complicated one. This line tells QTeam which game options
       you want to use. It's a single value that you find via some simple
       multiplication and addition.  To find it, simply add the values to
       the total. This is a required field.


       FRAGLIMIT = bits 0-6
                    Once the frags for any team hit this number, the game
                    ends. Simply choose your limit, and add it to your total.
                    A fraglimit of 0 means there is no limit and the game
                    will not end because of the score. 

                    Specifying a fraglimit in the map only provides a default
                    for game play; The fraglimit can be overridden at the
                    command line or console, using the fraglimit variable.

                    The fraglimit is only used for game modes 0 and 4

       DM TYPE   = bit 7
                    Whether the map should be played using old DM or alt DM
                    rules. Alt DM is the pick-up-a-weapon-and-it-disappears
                    type of DM.  Old DM keeps the weapons there for someone
                    else to pick up, but not you.

                    Alt DM is 0, old DM 1.  Multiply this by 128, and add it
                    to the total.

       MAX TEAMS = bits 8-11
                    This specifies the maximum number of teams that can play
                    on the map. Can be any number from 2-8. 
                    
                    Multiply the maximum number of teams you want by 256 and
                    add it to your total. 

       GAME MODE = bits 12-15
                    Take the game mode you want, and multiply it by 4096,
                    then add it to the total.  Valid game modes are:

           0 = Death Tag
               Immediate score on score object pickup
               Objects use qtmrespawn to determine their respawn time
               Game ends at fraglimit, if fraglimit > 0

           1 = Scavenger Hunt 
               Immediate score on score object pickup
               Objects don't respawn
               Game ends when all objects retrieved

           2 = Scavenger Hunt/CTF (Combines features of both)
               Objects picked up must be returned to a base
               Objects respawn only if the player carrying them dies but
                  not if the objects have been successfully returned to
                  the base. 
               Game ends when all the objects have been retrieved

           4 = CTF (Standard and Enhanced)
               Objects picked up must be returned to a base
               Objects respawn when player carrying them returns them to 
                  the base or the player dies.
               Game ends at fraglimit, if fraglimit > 0

           5 = Capture the Shambler
          14 = King of the Hill
          15 = Paintball

       So, basically, the equation looks like this:

            qtmgame = fraglimit + ( (DM * 128) + (TEAMS * 256) + (MODE * 4096) )

       Which means a game with a fraglimit of 50, alt DM, with 2 teams and game
       mode 3 would result in "qtmgame" "16946".

      Note:
           All objects retrieved details: If objects are allocated to a team
           then the team has to retrieve all their objects. If scoring 
           objects are open (not tagged for specific team) then all the
           objects need to be retrieved. If there is a mix then all team
           objects must be retrieved as well as all open objects (which can
           be retrieved by any team).

     qtmintro1 ... qtmintro10

       These messages will display when a client first connects with the
       server but after the QTeam banner message. The messages are 
       centerprinted and there is a two second interval between each message.
       These are optional fields.

     qtmdamageadj
       This feature was designed for Death Tag games (see QTag or QTag2)
       but can be used in any game. This is an optional field.

       A multiplier that adjusts the damage for acid or slime. Fudging the
       damage is useful to ensure players without an environmental biosuit
       cannot reach a scoring object. Reminder: The biosuit does not fully
       protect player from lava but does protect fully from slime. 

       eg. A value of .33 does one-third the damage of regular slime or lava
           A value of 4   does four times damage of regular slime or lava
  
B) Defining a scoring object (flag)

     The score object has a classname of item_score and supports the
     following tags. If the frags tag is missing then the object is worth one
     point. If the team tag is missing, the object can be picked up by
     any team. If the game mode specifies that objects respawn according to
     the qtmrespawn tag and this tag is not specified then the respawn time
     will be set at 5 seconds. Each map can support 1 or more scoring objects
     and they each can have different properties. Also, the number of scoring
     objects per team is not limited to one.

     team

       Player that touches this entity either gets immediate credit or
       stores the flag so he/she can return it to a base. If the player 
       touches a flag that belongs to another team nothing happens.
       
       Team = Color number + 1. No team tag or team = 0 means that any team
       can pick up the scoring object (Shared Flag). See Team Color section
       below for more details.

     frags

       Number of points this object is worth. If this tag is not used, the
       object will be worth one point.
 
     qtmrespawn

       Sets the respawn time of the object if the game play allows for
       respawning objects and the respawn countdown is supposed to occur when
       the object is picked up and not an immediate respawn in flag mode if
       the carrier dies or the flag is returned to the base. The granularity 
       of the respawn timer is 5 seconds. 

       bit  0    = Random? 0=No, 1=Yes
       bits 1-6  = Respawn time, or if random then beginning of range
                   Value must be >= 1
       bits 7-12 = Respawn time, or if random then end of range
                   Value must be >= 1

     model

       Chooses the model. You can use a built in model or supply
       your own along with map. The default model is progs/end1.mdl
       which is a rune for users that don't have the QTeam client package
       and a QTeam flag for those who do.

     skin

       Chooses the skin for specified model. For example, if you use
       "model" "progs/armor.mdl" to select the armor model, then
       "skin" "2" will make it the red armor.

     noise

       Chooses the sound to be played on pickup. You can use a built in sound
       or supply your own with map. The default sound is misc/runekey.wav

C) Defining a base
	
     You need to define an entity with classname trigger_multiple and use
     the qtmmisc tag to mark it as a base when the map is for Capture the
     Flag or Capture the Shambler. Because the trigger_multiple allows a 
     brush the base is not limited to the shape of a box.

     team

       Team that touches this entity gets a point.	Team = Color number + 1.
       No team tag or team = 0 means that any team can bring their flags 
       back to this base. See Team Color section below for more details.

     qtmmisc

       bit 0 = Must be set to 1 for a base

     frags

       Allows a Base Value multiplier to be specified. The worth of flags
       the player is carrying is multiplied by this amount. In Capture the
       Shambler mode, the Shambler's leader is always worth 1 point. 
       With this, multiple bases for each team or shared bases can be
       established that use the multiplier as a difficulty factor. The
       easy to reach bases have a smaller multiplier and the harder to
       reach bases have a larger multiplier. 

       If the "frags" key is not set, bases have a multiplier of 1.

D) Dynamically sizing maps

   Triggers for player counts, team formation, team abandonment are provided
   allowing for opening and closing of doors and automatic teleportation of 
   players out of closed areas. Of course these same triggers can be used
   by innovative map designers for other purposes.

   When the events specified below occur, QTeam creates a trigger_relay,
   sets the target field to the corresponding targetname for the event,
   and automatically triggers it. Thus, all entities within the .bsp file
   with a matching targetname field will get triggered. In paintball mode,
   the qtm_playercount_stepdown events will occur as people are eliminated
   or leave the game, and at the beginning of a round, all
   qtm_playercount_stepup commands will be sequenced through, starting with
   the last stepdown.

   Event                        targetname
   ------                       ----------
   Red Team create              qtm_createteam_red
   Blue Team create             qtm_createteam_blue
   .
   .
   .
   Red Team abandoned           qtm_dropteam_red
   Blue Team abandoned          qtm_dropteam_blue
   .
   .
   .
   Moved from 1 to 2 players    qtm_playercount_stepup_2
   Moved from 3 to 2 players    qtm_playercount_stepdown_2
   Moved from 2 to 3 players    qtm_playercount_stepup_3
   Moved from 4 to 3 players    qtm_playercount_stepdown_3
   .
   .
   .
   Moved from 14 to 15 players  qtm_playercount_stepup_15
   Moved from 16 to 15 players  qtm_playercount_stepdown_15
   Moved from 15 to 16 players  qtm_playercount_stepup_16

   Dynamically sizing maps

   Use "qtmmisc" tag, bit 2 to define a trigger_multiple as a zone.
   Anyone in a closed zone is automatically teleported to an open zone.
   Zones start closed. Use the QTeam event trigger defined above to 
   open and close it.

   All info_player_deathmatch entities within a closed zone are inactive.
   All info_player_deathmatch entities in a zone must also be marked with
   a targetname to toggle it on and off.

   The sample map files demonstrate how DSM can be implemented. 

E) Defining other objects for QTeam play

    The team tag is supported for weapons, powerups, doors, and
    info_player_deathmatch entities.

    weapons, powerups : If the team tag is specified, only players on the
       specified team can pick up the object.
 
    info_player_deathmatch : If the team tag is specified, only players
       on the specified team will respawn at this spot. The map maker must
       ensure that is at least one respawn spot for each team up to the 
       maximum number of teams allowed. If no team tag is used, any player
       can spawn on this spot.

       In paintball mode, if you add the team tag and add 128 to the value, 
       only eliminated players will respawn here, instead of going into
       observer mode.

    doors : If the team tag is specified, only players on the specified team
       will be able to open the door, however once open players on other 
       teams can get through, and there's the possibility of getting stuck.
       The player can always suicide (Guess they deserve that for trying
       to sneak through). A message is printed to the user if they try to open
       a door not marked for their team.

III. Team Colors

     Although Quake has built in support for 13 different colors which can be
     selected for shirts and pants, QTeam supports up to eight teams only and
     enforces team colors. QTeam teams are only solid colors and team colors
     are selected in a builtin order. This means that in a non-frag game
     where their are objects and bases specific to teams, and those items
     need to be marked by a color, you need to be aware of the order. It is
     as follows:

        Rank    Color #    Desciprition     

        1       4          Red
        2       13         Blue
        3       12         Yellow
        4       3          Green
        5       1          Brown
        6       8          Purple
        7       2          Light Blue
        8       5          Gold

IV. Debugging QTeam maps

   To facilitate testing a map that uses some of the advanced map features
   the following debug options are available. To enable debug mode, you need
   to add 128 to the deathmatch setting before loading the map.

    impulse 150 : Prints current origin to requesting client
    impulse 149 : Simulate player entering the game for testing
                  qtm_playercount_stepup events
    impulse 148 : Simulate player leaving the game for testing
				  qtm_playercount_stepdown events
    impulse 145 : Toggle team red in game/ not in game
                  (qtm_createteam_red, qtm_dropteam_red)
    impulse 144 : Toggle team blue in game/ not in game
                  (qtm_createteam_blue, qtm_dropteam_blue)
    impulse 143 : Toggle team yellow in game/ not in game
                  (qtm_createteam_yellow, qtm_dropteam_yellow)
    impulse 142 : Toggle team green in game/ not in game
                  (qtm_createteam_green, qtm_dropteam_green)
    impulse 141 : Toggle team brown in game/ not in game
                  (qtm_createteam_brown, qtm_dropteam_brown)
    impulse 140 : Toggle team purple in game/ not in game
                  (qtm_createteam_purple, qtm_dropteam_purple)
    impulse 139 : Toggle team light blue in game/ not in game
                  (qtm_createteam_lblue, qtm_dropteam_lblue)
    impulse 138 : Toggle team gold in game/ not in game
                  (qtm_createteam_gold, qtm_dropteam_gold)
    impulse 137 : Dump player chain and links to team members
	impulse 133 : Toggle team red took/lost flag
                  (qtm_gotflag_red, qtm_lostflag_red)
	impulse 132 : Toggle team blue took/lost flag
                  (qtm_gotflag_blue, qtm_lostflag_blue)
	impulse 131 : Toggle team yellow took/lost flag
                  (qtm_gotflag_yellow, qtm_lostflag_yellow)
	impulse 130 : Toggle team green took/lost flag
                  (qtm_gotflag_green, qtm_lostflag_green)
	impulse 129 : Toggle team brown took/lost flag
                  (qtm_gotflag_brown, qtm_lostflag_brown)
	impulse 128 : Toggle team lpurple took/lost flag
                  (qtm_gotflag_lpurple, qtm_lostflag_lpurple)
	impulse 127 : Toggle team lblue took/lost flag
                  (qtm_gotflag_lblue, qtm_lostflag_lblue)
	impulse 126 : Toggle team gold took/lost flag
                  (qtm_gotflag_gold, qtm_lostflag_gold)

V. How to use the QTeam textures

   Included in this package is a file named qteam.wad. It includes a number
   of useful textures for designing QTeam maps. The textures are useful in 
   marking bases and paths to bases for the different teams. Accordingly,
   each texture design is available in many different colors. 

   There are two ways to use the textures when designing a map:


   1) Get a copy of a QBSP that can use multiple wads
      QBSP256c is one such example

   2) Merge the wadfile with one of your other wadfiles

      Using Mipdip, Qoole, or similar programs, you can simply pull the
      textures from one wadfile and put them into another.  With Mipdip (the
      recommended program), simply highlight the texture you want to
      transfer, copy it,  bring up the window of the wad you want to place
      the texture in, and paste.

VI. Sample maps

   1) DSM - Simple map demonstrating dynamically sizing map capabilities 
      only. 

   2) CTFDSM - This sample map demonstrates the implementation of a 
      dynamically map sizing, CTF with multiple team flags, shared flags,
      shared bases, valued flags, and valued bases. CTMDSM.MAP is the map
      file and CTFDSM.TXT is a text file that explains in more depth which
      features are being implemented. 


VII. Map editor extension files

   Extension files are available for some of the Quake map editors to 
   integrate the QTeam specifics with the basic Quake map language. 

   1) QTEAM.QC - This provides the extensions for the popular BSP program

VIII. Reporting problems or requesting enhancements

    Please visit our website at http://qteam.stomped.com

IX. 1 Flag CTF event triggers

    The following new event triggers are supported in QTeam 2.0 for 
    creating status indicators in 1 flag CTF maps to show which team
    has the flag.


    target                 triggers entities with targetname equal <target>
    ------------------     ------------------------------------------------
    qtm_gotflag_red        when red team takes the flag
    qtm_lostflag_red       when red team loses the flag
    qtm_gotflag_blue       when blue team takes the flag
    qtm_lostflag_blue	   when blue team loses the flag
    qtm_gotflag_yellow	   when yellow team takes the flag
    qtm_lostflag_yellow	   when yellow team loses the flag
    qtm_gotflag_green	   when green team takes the flag
    qtm_lostflag_green	   when green team loses the flag
    qtm_gotflag_brown	   when brown team takes the flag
    qtm_lostflag_brown	   when brown team loses the flag
    qtm_gotflag_gold	   when gold team takes the flag
    qtm_lostflag_gold	   when gold team loses the flag
    qtm_gotflag_lblue	   when lblue team takes the flag
    qtm_lostflag_lblue	   when lblue team loses the flag
    qtm_gotflag_purple	   when purple team takes the flag
    qtm_lostflag_purple	   when purple team loses the flag


    As an example, let's consider a 1 flag CTF map that has one status 
    indicator showing which team has the flag. This status indicator 
    could be implemented as follows:

    1) Construct two doors

       a) func_door #1 has a targetname of "reddoor"
          Behind this door is a red texture
       b) func_door #2 has a targetname of "bluedoor"
          Behind this door is a blue texture

       Both doors must initially be closed and can not open because of 
       players trying to use the door (SPAWNFLAG_NOTOUCH).

    2) Construct 4 trigger_relays

       a) trigger_relay #1
          "targetname" "qtm_gotflag_red"
          "target"     "reddoor"
       b) trigger_relay #2
          "targetname" "qtm_lostflag_red"
          "target"     "reddoor"
       c) trigger_relay #3
          "targetname" "qtm_gotflag_blue"
          "target"     "bluedoor"
       d) trigger_relay #4
          "targetname" "qtm_lostflag_blue"
          "target"     "bluedoor"

       With these 4 trigger_relays we essentially have two groups of two,
       each forming a toggle to open and close one of the doors.

    Here's an example scenario of what will happen in the game:

       a) Both doors start closed
       b) Flag is not owned by any team
       c) Red team picks up flag
       d) QTeam fires at entities with a targetname of "qtm_gotflag_red",
          in this case trigger_relay #1
       e) trigger_relay #1 in turn fires at its targets (entities with
          a targetname of "reddoor", in this case func_door #1
       f) func_door #1 opens revealing the red texture which now indicates
          that the red team has the flag.
       g) Flag carrier dies
       d) QTeam fires at entities with a targetname of "qtm_lostflag_red",
          in this case trigger_relay #2
       e) trigger_relay #1 in turn fires at its targets (entities with
          a targetname of "reddoor", in this case func_door #1
       f) func_door #1 closes. Since none of the other status indicator
          doors were open, they are now all shut signalling to players that
          noone has the flag.

       Note that there can never be a qtm_lostflag_x event without there 
       first being a qtm_gotflag_x event. Note also that there will be 
       no other intervening gotflag or lostflag events between a
       qtm_gotflag_x event and a qteam_lostflag_x event. For instance, you 
       will never get a qtm_gotflag_blue trigger in between a 
       qtm_gotflag_red trigger and a qtm_lostflag_red trigger. 

       DEBUGGING: To debug your 1 flag CTF maps with the "Who has the flag"
       trigger functions, set deathmatch 129 before loading your map. This
       allows you to enter a game without having two teams. Once you are in
       the game, you can play with grabbing the flag, returning to base, 
       dying, switching teams, etc., to have QTeam generate the different
       event triggers.



