			       Paintball 1.0
			   by Quake Innovations

			Server Side Documentation

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

Table of Contents

   I.    Overview 
   II.   Server options
   III.  Remote Administration of a Paintball server
   IV.   Requirements of clients

I. Overview

   This document describes how to setup as a Paintball Quake server. If you
   do not already know what a Quake server this document probably does not
   apply to you. This document assumes that the reader is familiar with
   running Quake and Quake servers, setting command line options, and the
   differences between client side and server side. 

   If all you want to do is play Paintball over the internet then you only
   need to read client.txt that came with Paintball. If you aren't yet
   familiar with Quake, please review the documentation that came with Quake
   first.

II. Server Options

   Paintball allows the server owner and operators to change many aspects 
   of its operation, both through the command line interface, server.cfg
   for QuakeWorld servers (optional, QW servers can still use the command
   line), and through the remote administration interface. Settings changed
   through remote adminstration options only last until the server goes down
   so this is not meant for permanent settings.

   If you want permanent settings then these options need to be passed using
   console variables (via command line or server.cfg). Unfortunately Quake
   does does not allow for creating new console variables so we are forced
   to use existing console variables and in most cases this means using them
   for multiple purposes. You'll probably find this confusing, so read
   closely!

   QuakeWorld server administrators should also consult the sample 
   server.cfg provided for additional server settings for Paintball.

   A) Game mode

      0 = No CTF. This is the default
      1 = 1 Flag CTF
      2 = 2 Flag CTF

      The value calculated here is passed on the command line using the
      teamplay variable. Remember that the teamplay variable is used for
      multiple purposes so you must add the game mode value to all the 
      other values that must be passed using teamplay.

      eg. Run battle.bsp in 1 flag CTF mode. 

	  The teamplay value will be 1 because we don't need to pass any
	  other information using teamplay. This means that for all other
	  options that use teamplay, we will get the defaults. 

	  winquake -dedicated 16 -game pball +teamplay 1 +map battle

      eg. Server administrator wants to disable automatic team join for 
	  players and enable 2 Flag CTF. Run the server on map battle.

	  1024 +        Force user to select their team
	  2         2 Flag CTF
	  ------
	  1026

	  winquake -dedicated 16 -game pball +teamplay 1026 +map battle

      For technical people: Game mode is passed in bits 0-3 of teamplay

   B) Map rotation

      Most servers will want to automatically change the maps running on 
      the server so players don't get bored. Map rotation allows the server
      to automatically switch to a new map after a specified amount of time 
      has elapsed or a team has reached the specified number of frags. The
      Quake console variables timelimit and fraglimit are used for this
      purpose. 

      Here's a list of the available map rotations. Note that there is no
      support for adding custom maps into a rotation; only the maps that
      ship with Paintball 1.0 can be used. If you want to load a custom map
      you can do so but you will not have map rotation and will need to 
      manually switch maps. 

      0  = No rotation. This is the default
      1  = hellsurv, battle
      2  = hellsurv, battle, jitpbal3
      3  = battle,jitpbal3
      4  = battle,ksplat2
      5  = hellsurv, battle, jitpbal3, luchpb
      6  = hellsurv, battle, luchpb
      7  = hellsurv, luchpb
      8  = battle,ksplat2,jitpbal3
      9  = qmelee10,jitpbal2
      10 = qmelee10,jitpbal2,ksplat2
      15 = All maps

      Multiply this value by 16

      The value calculated here is passed on the command line using the
      teamplay variable. Remember that the teamplay variable is used for
      multiple purposes so you must add the map rotation value to all the 
      other values that must be passed using teamplay.

      Note that you currently must specify an initial map to load on the
      command line or server.cfg and it must be one of the maps in the 
      desired rotation. Additionally, it must be typed in lower case and 
      must not have the .bsp extension appended. 

      eg. Start a 2 flag CTF game that rotates through maps hellsurv, 
	  battle, and jitpbal3, and switches to the next map when a team
	  reaches a score of 50.

	  2 * 16 +    Map rotation value for hellsurv, battle, jitpbal3 is 2
		      Multiply by 16 per the instructions
	  2           2 Flag CTF
	  ---------
	  34

	  winquake -game pball +teamplay 34 +fraglimit 50 +map hellsurv

      eg. Start a 1 flag CTF game that rotates through all the Paintball 1.0
	  maps, switches to the next map after playing 15 minutes on a map
	  or a team reaches a score of 75, whichever comes first and disables
	  friendly fire. The initial map will be ksplat2.

	  15 * 16 +   Map rotation value all maps is 15
		      Multiply by 16 per the instructions
	  1       +   1 Flag CTF
	  512         Friendly fire off, I don't want teammates to kill me!
	  ----------
	  753

	  winquake -dedicated 16 -game pball +teamplay 753 +fraglimit 75
	    +timelimit 15 +map ksplat2 

      For technical people: Map rotation is passed in bits 4-7 of teamplay
 
   C) Friendly Fire
   
      In all game modes, friendly fire controls whether a user can harm his
      teammates. When friendly fire is disabled, a user can harm members of
      the other teams but not his teammates. The default is enabled which
      means a player will hurt whoever he hits, regardless of team.

      0 (default)   = Friendly fire is allowed
      512           = Friendly fire is not allowed

      The value calculated here is passed on the command line using the
      teamplay variable. Remember that the teamplay variable is used for
      multiple purposes so you must add the friendly fire value to all the 
      other values that must be passed using teamplay.

      eg. Start a 2 flag CTF game that loads a custom map, let's call it
	  pbtest. Because we're loading a custom map, map rotation is not
	  allowed. We want to disable friendly fire because we hate teammates
	  killing us!

	  0 * 16 +    No map rotation is 0 
		      Multiply by 16 per the instructions 
	  2       +   2 Flag CTF
	  512         Friendly fire off, I don't want teammates to kill me!
	  ----------
	  514

	  Did anyone guess that 0 * 16 would turn out to be zero? :)

	  winquake -dedicated 16 -game pball +teamplay 514 +map pbtest 

      For technical people: Friendly fire is passed in bit 8 of teamplay

   D) Automatic revival of players

      In a Paintball game, when a player is eliminated, he will be setup
      to respawn 60 seconds later, unless of course the round ends. This
      is the default.

      0 (default)   = Players will be revived 60 seconds after being killed
      2048          = Players will be out until the next round begins

      The value calculated here is passed on the command line using the
      teamplay variable. Remember that the teamplay variable is used for
      multiple purposes so you must add the automatic revival value to all
      the other values that must be passed using teamplay.

      eg. Start a 2 flag CTF game that runs hellsurv but man, oh, man, get
	  rid of that nasty revival crap. The way I play paintball in
	  real life, players are out until the game is over!

	  2       +   2 Flag CTF
	  2048        Automatic revival off
	  ----------
	  2050

	  winquake -dedicated 16 -game pball +teamplay 2050 +map hellsurv

      For technical people: Automatic revival is passed in bit 10 of teamplay

   E) Team Auto-Join

      The default behavior is to automatically add clients just connecting
      to the team with the least number of players. This happens a few
      seconds after they connect so they have time to use the observer 
      command and remain an observer during a match. 

      0 (default) = Players will be automatically placed on a team
      1024        = Players must choose their team
  
      The value calculated here is passed on the command line using the
      teamplay variable. Remember that the teamplay variable is used for
      multiple purposes so you must add auto-join value to all the other
      values that must be passed using teamplay.

      eg. Start a 1 flag CTF game that runs jitpbal2. Turn off automatic
	  revival and team auto-join. 

	  1        +  1 flag CTF
	  2048     +  Automatic revival off
	  1024        Players must choose their own team
	  ----------
	  3073

	  winquake -dedicated 16 -game pball +teamplay 3073 +map jitpball2

      For technical people: Team auto-join is passed in bit 9 of teamplay

   F) Remote Administration: Level 1 password (op)

      You need a password in order to gain access to certain remote 
      administration features (see Section III for a description of using
      remote administration). Although there is a default password you will
      not want to leave it set to the default because other people accessing
      your server will know it.

      QuakeWorld also has remote administration capabilities that provide
      many features not found in the Paintball remote administration, however
      it does not have equivalents for all features. The two remote
      administration methods can coexist. Please see the QuakeWorld
      documentation on how to use its remote administration features.

      The console variable used to pass the master password to Quake varies
      according to whether you are running a QuakeWorld or a non QuakeWorld
      server. In either case, the first step is to calculate the password
      value. Get ready, these numbers get big, Big, BIG!!! You will almost
      certainly need a calculator to figure this out. You will also need to
      know how to convert between hexadecimal and decimal in order to 
      proceed. If you do not understand how to do this then you may require
      the help of a friend with more technical experience.

      For non QuakeWorld
      ------------------

      The default level 1 password is 4132. It is strongly recommended that
      you change from the default.

      1) First, think of a four digit password using the digits 0-8. This
	 password must be different than the password chosen for the level 
	 2 password.

	 Here are a few examples of valid passwords
	     6736
	     8256
	     4637

		 Here are a few examples of invalid passwords:
	     1239      Invalid because it contains a 9
	     62523     Invalid because it is too long
	     137       Invalid because it is too short
	     8a13      Invalid because it contains an a

      2) Consider the password chosen as a hexadecimal value and convert it
	 to decimal. 

      3) Multiply by 256

      4) The value just calculated is passed on the command line using the
	 deathmatch variable. Remember that the deathmatch variable may be
	 used for other purposes so you must add the value to all the other
	 values that must be passed using deathmatch.

	   eg. Set the level 1 password to 6736
	       
	       * 6736 in hex = 26422 in decimal
	       * Multiply by 256 = 6764032 (Can you say BIG???!!!)
	       * Doesn't look like I need to set anything else in deathmatch
		 so I must be all set!

	   winquake -dedicated 16 -game pball +teamplay 2 +deathmatch 6764032
	     +map battle

      For technical people, set bits 8-31 of deathmatch to the decimal value 
      of the password.


      For QuakeWorld
      --------------
      See the sample server.cfg for setting up the level 1 password.

   G) Remote Administration: Level 2 password (master)

      You need a password in order to gain access to certain remote 
      administration features (see Section III for a description of using
      remote administration). Although there is a default password you will
      not want to leave it set to the default because other people accessing
      your server will know it.

      QuakeWorld also has remote administration capabilities that provide
      many features not found in the Paintball remote administration, however
      it does not have equivalents for all features. The two remote
      administration methods can coexist. Please see the QuakeWorld
      documentation on how to use its remote administration features.

      The console variable used to pass the master password to Quake varies
      according to whether you are running a QuakeWorld or a non QuakeWorld
      server. In either case, the first step is to calculate the password
      value. Get ready, these numbers get big, Big, BIG!!! You will almost
      certainly need a calculator to figure this out. You will also need to
      know how to convert between hexadecimal and decimal in order to 
      proceed. If you do not understand how to do this then you may require
      the help of a friend with more technical experience.

      For non QuakeWorld
      ------------------

      The default level 1 password is 6145. It is strongly recommended that
      you change from the default.

      1) First, think of a four digit password using the digits 0-8. This
	 password must be different than the password chosen for the level 
	 1 password.

	 Here are a few examples of valid passwords
	     6736
	     8256
	     4637

		 Here are a few examples of invalid passwords:
	     1239      Invalid because it contains a 9
	     62523     Invalid because it is too long
	     137       Invalid because it is too short
	     8a13      Invalid because it contains an a

      2) Consider the password chosen as a hexadecimal value and convert it
	 to decimal. 

      3) Multiply by 256

      4) The value just calculated is passed on the command line using the
	 temp1 variable. Remember that the temp1 variable may be used for
	 other purposes so you must add the value to all the other values
	 that must be passed using temp1. 

	   eg. Set the level 2 password to 8256
	       
	       * 8256 in hex = 33366 in decimal
	       * Multiply by 256 = 8541696 (Can you say BIG???!!!)
	       * Doesn't look like I need to set anything else in temp1
		 so I must be all set!

	   winquake -dedicated 16 -game pball +teamplay 2 +temp1 8541696
	     +map battle

      For technical people, you are passing the decimal value of the password 
      in bits 8-31 of temp1
      

      For QuakeWorld
      --------------
      See the sample server.cfg for setting up the level 2 password.

III. Remote Administration:

   People in the game are either ops or peons.  Typing NAMES in
   the game, will display who is an op, and who isn't.  Ops have an
   @ beside their name, and master ops have two '@'s.

   ]NAMES
   1-@@Cyberdog (T:5 F:54)
   2-TX_Outlaw (T:5 F:-99)
   3-Calrathan (T:14 F:12)

   The T: is the team that the person belongs to, which is the color of
   the player's pants + 1.
   F: is the frags.

   In all these commands, you can either enter the name, or the number.

   To gain ops in a game, you must use the OP command :

   1) type OP
   2) press the ` key (top left) to remove the console
   3) enter the code using the number keys 1-8 (see below for code)

   There are two codes that you can enter, the master code, and the
   normal op code.  The master code should not be disclosed to anyone.

   Paintball supports two op levels, so that level 1 ops cannot actually
   crash the server regardless of what they do.  This means that remote
   users could be made level 1 ops without fear that they will end up
   crashing the server. 

   It is quite easy for master ops to crash the server.

   Ops get new commands. The number of new commands depends on what
   level of ops you are:

   Normal               Master
   -----------------------------------
   KCK                  All of Normal commands
   GIB                  SHUTDOWN
   OP                   COMMAND
   DEOP                 CHPASSWD
   NEWMAP               CHMPASSWD
   CHCVAR
   DROPFLAG
   REVIVE
   FFIRE
   AUTOJOIN

   Normal op commands
   ==================

   To use the first four commands, type the command on its own, it will
   then list all the people in the game.  Type the number of the player
   you wish to act upon.  and the
   command will act on that user.

   e.g.

   ]GIB
   1-@@Cyberdog (T:5 F:54)
   2-@Jitspoe (T:14 F:34)
   3-Twink[CC] (T:14 F:-99)
   Please type name or number to Gib or cancel
   Enter first digit
   ]0
   Enter second digit
   ]3
   Twink[CC] kills himself with paint?

   NEWMAP
   ------

   Newmap allows an op to change the current level. It is entirely menu
   operated, and designed so that ops with level 1 cannot accidently
   enter in a level that the server doesnt have, and therefore crash it
   If you are a Master Op, then you get an addional menu option, where
   you can enter in a level name manually. But be careful that the level
   does exist in the /maps directory!

   e.g.

   ]NEWMAP

   Please choose map :
   0 - Cancel
   1 - qmelee10
   2 - battle
   .
   .
   6 - luchpb\n");
   7 - ksplat2\n");
   ]2

   Map battle.bsp will be loaded

   CHCVAR
   ------

   ChCvar allows normal ops to change a Cvar such as TEAMPLAY or
   DEATHMATCH.  This is also menu operated.

   REVIVE
   ------

   REVIVE allows toggling of the automatic revival of eliminated players
   during a paintball round, 60 seconds after their death. This option 
   defaults to on and can be changed at the command line.
   option is on.

   FFIRE
   -----

   FFIRE allows toggling of the friendly fire option. This option
   determines whether you can affect your teammate's health. It does 
   not affect your ability to harm yourself.
   
    
   AUTOJOIN
   --------

   AUTOJOIN allows toggling of team auto-join. This option determines
   whether players are automatically put on a team upon connecting to
   the server.
   
   Master op Commands
   ==================

   SHUTDOWN
   --------

   Shutdown shuts the server down. You get no warning, so use with
   care.

   COMMAND
   -------

   This very powerful command allows you to type any command you like
   on the server console.

   e.g.

   ]command
   Please enter name "<command>";execute
   ]name "sv_gravity 100";execute
   Paragon renamed to sv_gravity 100
   sv_gravity 100 renamed to Paragon
   "sv_gravity" changed to "100"
   ]

   Your name is temporarily changed but will be reset after the command
   completes.  Due to an built in Quake limit, the maximum
   number of characters in the command is 15. Change maps using the
   NEWMAP instead of through COMMAND.

   NEWMAP
   ------

   Newmap allows an op to change the current level. It is entirely menu
   operated, and designed so that ops with level 1 cannot accidently
   enter in a level that the server doesnt have, and therefore crash it
   If you are a Master Op, then you get an addional menu option, where
   you can enter in a level name manually. But be careful that the level
   does exist in the /maps directory!

   e.g.

   ]NEWMAP

   Please choose map :
   0 - Cancel
   1 - qmelee10
   2 - battle
   .
   .
   7 - ksplat2\n");
   8 - Enter Map manually.
   ]8
   ]name
   ]name is "cyberdog"
   ]name "testmap"
   ]name
   ]name is "testmap";
   ]execute

   You should wait until the name change is effective before typing execute
   otherwise the server will attempt to load an invalid map.

   -------------------------------------------------------------------
   DO NOT USE THE 'MAP' COMMAND. If you do, it will disconnect all the
   players, wipe out all per player information, such as who is an op.
   Use NEWMAP instead.
   -------------------------------------------------------------------

   CHPASSWD and CHMPASSWD
   ----------------------

   The default passwords are : 4132 for the normal ops
			       6145 for master ops.

   It is recommended that if you are running a server on the internet,
   that you change the default passwords to something else.

   You can change the passwords for ops and master ops either at the command
   line or by using the CHPASSWD and CHMPASSWD commands, however changing
   via CHPASSWD and CHPASSWD will only take effect for the current
   execution of Quake; if you quit the server and restart the default
   passwords will again be in effect. If you want to make permanent 
   changes, use the command line.

   To change the passwords at the command line, please see the section
   entitled Server Options.

   To change the password in the game, type CHPASSWD, and then enter
   each digit one at a time with a carriage return in between each.
   A password consists of four digits using the digits 0-8.

   CHMPASSWD will change the level 1 (normal ops) password.
   CHMPASSWD will change the level 2 (master ops) password.

IV. Requirements of clients

    All clients connecting to your server must have the Paintball 1.0
    package running:

       1) For reg Quake,
	  <quake executable> -game pball.

       2) For QuakeWorld,
	  qwcl +gamedir pball.

