-------------------------------------------------------------------------

###### Overview:
----------------

ServerModules is a set of modularized QuakeC modifications.
The range of applicability is restricted to deathmatch games.
The modifications require an installation on the server only. 
They are based on QuakeC version 1.06 and may be used by
1.01, 1.05a and 1.06 deathmatch servers.

-------------------------------------------------------------------------

###### Modules:
---------------

Module Admin:
   Allows remote server administration.
   By typing the correct sequence of impulse a player may gain root
   privileges.
   Root may then perform administration tasks like:
     - changing to the next level
     - jumping to any of the original id levels.
     - kicking players
     - restarting the server
     - changing the values of parameters like fraglimit, timelimit,
       noexit, gravity and friction.
     - toggling flags in the teamplay variable, thereby enabling
       or disabling certain modules.
     - changing the team membership of players when playing CTF.
   The following commands are provided to perform this tasks:
       root-nextlevel
       root-level
       root-kick
       root-restart
       root-fraglimit
       root-timelimit
       root-noexit
       root-gravity 
       root-friction
       root-teams
       root-teamplay
       root-logout
   Most of the commands are self explanatory. The command
   'root-teams' should be used to assign players to teams, the 
   command 'root-teamplay' should be used to modify the 'teamplay'
   variable. Note that for obvious reasons most changes of the 
   'teamplay' variable act on the following levels only, not on the
   current one.
   Finally, when typing 'root-logout' root loses its privileges.

Module Burn:
   Allows players to burn.
   Players may start to burn if being bombarded by certain weapons,
   including drones (see module Drone), the weldgun (see module
   WeldGun) and shrapnel missiles (see module Shrapnel).
   Three flavours of burning exist. The first causes little damage,
   the third hurts significantly. A player burning mildly may
   start to burn worse if hit again by incendiary ammunition. 
   Fire is extinguished automatically after a certain period of time
   or if the burning player jumps into sufficiently deep water.
   A burning player may infect other players in the vicinity.

Module CTF:
   Allows to play 'Capture the Flag' teamplay. 
   The general rules for playing 'Capture the Flag' 
   are the same as those found in the original CTF server patch
   created by Dave Kirsch (zoid@mindlink.bc.ca). They are
   explained in detail on "http://quake.threewave.com/".
   However, there are some differences compared to version 2.51
   of Dave Kirsch's CTF package. The most important are:
      - Flag carriers carry the flag on their back, making it easy
        to identify them.
      - Players are allowed to change teams when they are dead or
        when they are observers.
        To do so a  player should simply type for instance 'color 5'.
        This causes him to change teams, with a pants color of his
        new team and a shirt color of 5.
        The server administrator may, however restrict this default 
        behaviour:
          - by removing a certain flag from the 'teamplay' variable
            in the file 'autoexec.cfg' a player changing his color
            will only join the other team if the other team is weaker 
            than the current one. 
          - by removing another flag from the 'teamplay' variable
            it is possible to disable team changes completely.
      - There is no need to patch the original id levels
        to include flags and weapons at the bases.
        All the information about flags, additional items,
        disabled doors/teleporters is done in the source
        code of the CTF module.
      - Players are allowed to change their color when they are 
        alive; the server only enfores the color of the player's
        pants to be the team color.
        It is, however, not possible to change team membership by 
        changing colors when the player is alive (not even for a 
        split of a second) since the server handles team membership
        in a different way.
   Please note that the data used to turn regular deathmatch levels 
   into a CTF playable maps was taken from Dave Kirsch's CTF package
   "3wave251.zip" and was only slightly modified here and there.
   I'd like to thank Dave Kirsch (and all the other authors) for the
   lot of work they put into the map conversions and for including this
   data in "3wave251.zip".

Module Drone:
   Provides homing missiles to be shot by the grenade launcher.
   Drones search for targets once every second, preferring those
   which are most easily reached.
   To find potential targets hidden behind corners launched drones
   first fly on a straight trajectory for about one second, then 
   start to adjust their velocity as required to reach the target. 
   A Drone will target its owner if better target can not be found.
   Flying drones can be shot down, most easily with the shotgun
   or by nearby explosions.
   A player can only have four drones in air simultaneously. 
   Launching a fifth one causes the self destruction of an older
   drone.
   Golden keys of targeted players are lit to indicate that they
   are hunted.
   To fire drones the player has to select the grenade launcher
   twice. The player's silver key is lit if the grenade launcher 
   fires drones.
   This is not an 'allround' weapon. It is a very specialized
   weapon which sometimes provides the only way to attack an enemy
   which can not be attacked directly.

Module ExitRules:
   Disallows to exit a level too early.
   Players can only exit a level
      - if at least one player has reached a minimum number of frags
        (which is 40 by default).
      - and if a certain time has passed on the current level (which
        is 1 minute by default).
   These ExitRules may be disabled by voting (see Module Vote).
   The ExitRules valid for the current level are displayed when
   the player enters the level.
   Levels like 'dm1'-'dm6','start' and 'end' don't impose ExitRules.

Module Hook:
   This is a throwable hook, attached to a chain and allowing the
   player to climb or swing.
   To use it the player should add the lines
      alias +hook     "impulse 98"
      alias -hook     "impulse 97"
      bind <desired key> +hook
   to "autoexec.cfg".
   Pressing <desired key> will throw the hook.
   Releasing <desired key> will deactivate the hook.

Module KickSuicider:
   Players suiciding twice within two minutes are kicked out of the
   game.

Module Lightning:
   This module reduces the damage done when discharging the lighning gun
   under water. Furthermore it improves the sound of the lightning gun
   and causes a lighning gun discharge to happen only if the gun is 
   really under water.

Module Init:
   Allows client side initialization when connecting to the server
   by causing the client to execute a sequence of 'init' commands.
   Example: 
      A player puts the following lines into his autexec.cfg:
         alias init    init01
         alias init01 "init-nextcall; alias init init02; echo successful;"
         alias init02 "init-nextskin; alias init init03; " // skin  2
         alias init03 "init-nextskin; alias init init04; " // skin  3
         alias init04 "init-nextskin; alias init init05; " // skin  4
         alias init05 "init-nextskin; alias init init06; " // skin  5
         alias init06 "init-nextcall; alias init init07; color 3; "
         alias init07 "               alias init init01; "
      These lines cause that a short time after the player connected
      to the server
         - he is assigned the skin number 5.
         - his color changes to 3.
   How it works:
      The server first tells the client to execute the command 'init'.
      The client executes 'init' which includes either 'init-nextskin'
      or 'init-nextcall', both of which tell the server to again let
      the client execute the command 'init'. This continues until in 
      the example above the empty assignment 'init07' terminates the
      sequence. Apart from triggering the next step 'init-nextskin'
      also increases the skin number by one.

Module LevelSelect:
   Allows to specify which levels are offered on the server and in which
   order they are to be played.
   By default this module is used to modify the original level order
   such that instead of the end level the level sequence dm2-...-dm6-end
   is played when selecting the end map on the start level (the players
   must exit the levels dm1-dm6 and end by voting (see Module Vote)).

Module Messages:
   Allows to selectively enable or disable messages about picking up ammo,
   armor, backpacks, keys, health, powerups and weapons. 
   Also some 'centerprinted' messages triggered by secrets and doors
   can be switched of.
   By default all these messages are suppressed.

Module Motd: 
   When connecting to the server a message-of-the-day may be 
   center-printed to the player's screen.
   A moment later, information about local server settings and
   extensions is dumped to the player's console.

Module Observer:
   As observer you just watch what's happening, without interacting
   with other players or with the environment.
   This especially means that other players will not notice you when you
   are an observer.
   As observer you can
      - fly around. 
      - switch to another observation point by pressing 'fire'.
      - join the game as regular player by pressing 'jump'.
   You can turn into an observer by pressing 'fire' when you
   are dead.
   When you connect to the server you automatically start as observer.
   The command 'help-observer' provides help on the observer mode.

Module Protect:
   Protects respawning players.
   The protection ends automatically after a certain amount of time
   or if the player shoots or picks up a weapon, armor or a powerup.

Module Random:
   Randomizes positions of items.
   The randomizer knows four groups of items:
       AMMO:     shells, nails, rockets, cells and health boxes
       WEAPON:   all weapons
       POWERUP:  armors, quad damage, invisibility, invincibility,
                 and superhealth
   The randomizer mixes only items within the same group.
   Randomization doesn't affect the biosuit.
  
Module Rank:
   The command 'rank' displays a sorted ranking table with entries 
   in the format
      X TOTAL = KILLS DEATHS ACCIDENTS = PLAYER
   where
       X         = letter 'D' if the player is dead, letter 'O' if
                   the player is an observer
       PLAYER    = the name of the player
       TOTAL     = his total score
       KILLS     = how many he killed    
       DEATHS    = how often he got killed by other players
       ACCIDENTS = number of self-caused, deathly accidents
   A Suicide counts as double-accident.
   The default formula for calculating TOTAL is
       TOTAL     = 3*KILLS - DEATHS - 3*ACCIDENTS
   The command 'help-rank' provides help on the format of the ranking
   table and should explain the (local) formula used to calculate the 
   total score as well.

Module ServerConsole:
   Does nothing except except of printing some messages to the server
   console when a player suicides, is killed, enters the game or is 
   telefragged by another player.

Module ServerHelp:
   Provides the command 'server-help', used to display some help on
   server settings and extensions in the player console.

Module Shrapnel:
   Provides splintering missiles to be shot by the rocket launcher.
   Once a splintering missile hits a massive object it defragments
   into a few splinters. The high-speed, burning fragments move
   on straight trajectories but are reflected by every massive object,
   causing an explosion on the object's surface. Players hit by the
   missile or by its fragments may start to burn (see module Burn).
   To fire shrapnel missiles the player has to select the rocket
   launcher twice. The player's silver key is lit if the rocket
   launcher operates in 'sharapnel missile' mode.
   This is not an 'allround' weapon; its main intent is to clean
   rooms or other areas from a safe distance.

Module Skin:
   This is a slightly improved version of Dennis Noordsij's 
   (lnoordsi@inter.NL.net) Multiskin, which allows players to use
   different skins (see also section Acknowledgements below).
   The improvements have the effect that
      - corpses show the correct skin.
      - skins are preserved  across level changings (so that players 
        have to choose their skin only once).
      - the commands 'skin-next' and 'skin-prev' may be used to change
        the skin.
      - the command 'help-skin' provides some help about available
        commands.
      - names for Multiskin-1.1 skins and for Top20Skins-1.0 skins are 
        shown when the player chooses a skin.
   Players certainly still have to use proper player and player-head 
   model files containing the actual skins to be displayed. 
   ServerModules supports
      - the MultiSkin 1.1 PLAYER.MDL file which may be found on 
        Dennis Noordsij's QuakeC page: 
           http://web.inter.NL.net/users/L.J.Noordsij/qc.htm
      - the Top20Skins PLAYER.MDL and H_PLAYER.MDL file included in the
        skin collection
           ftp://ftp.cdrom.com/pub/quake/graphics/mdl/top20skins-3.zip
        When using this set of skins gibbed heads will show the correct
        skin also.

Module Telefrag:
   Reduces the risk of getting telefragged by respawning players.
   When a player respawns the module tries to find a spot which is not
   occupied by another player. If such a spot is available the player
   will respawn there. Only if no such spot is found the player will
   respawn in occupied space, thereby telefragging another player.
   Note that telefragging caused by players leaving teleporters is not
   affected.

Module Vote:
   Allows players to vote.
   Players may use the console commands
      vote-exit:      to vote for exiting a level immediately.
      vote-exitrules: to vote for disabling the rules imposed by
                      the module ExitRules.
   Votes are counted every few seconds. 
   Voting for exiting allows to leave levels which don't provide an
   exit.
   Voting via 'vote-exit' and 'vote-exitrules' may both be used to 
   override the ExitRules for the current level.
   The console command 'help-vote' provides some help on available
   voting options, the command 'votes' displays current voting
   statistics.

Module WeldGun:
   Provides a weapon which spits burning blobs of a magnesium-steel
   mixture in rapid succession.
   The blobs cause small explosions on the surface of whatever they
   hit.
   Players hit by burning blobs may start to burn (see module Burn).
   This weapon overrides the nailgun. Selecting the nailgun twice 
   causes it to shoot ordinary spikes instead.
   The player's silver key is lit if the weldgun is active.
    
-------------------------------------------------------------------------

###### Bugs/Unwanted Features:
------------------------------

# Drones which just bounced or which stay close to walls can not be
  shot down by other projectiles (like those fired by the shotgun or
  nailgun). This is a Quake restriction and can not be changed.
  Such drones are, however, still sensitive to explosions.
# Occasionally drones leave/enter the level through walls. Again, this
  is due to Quake limitations.
# Observers occasionally get stuck or start in a position from which they
  can't move away. If this happens just press 'fire' to jump to another 
  place or use the command 'observer-noclip' to free yourself.
  Observers may also get stuck when passing teleporters with buggy
  target spots. The only examples I know so far are
    - level e1m1: the teleporter leading to the pentagramm of protection.  
    - level end: the teleporter leading to a spot from which the player
                 falls down into the water.
  Again, just press 'fire' to jump to another place or use the command
  'observer-teleport'.

-------------------------------------------------------------------------

###### HOW TO INSTALL:
----------------------

This section assumes that you are a server administrator.

# TESTING:
------------
  For testing purposes you may first want to try the precompiled "progs.dat".
  To do so just follow instructions in the two sections
  "EXTRACTING THE ARCHIVE" and "STARTING THE SERVER" below. You can skip all
  intermediate sections.

# CUSTOMIZATION:
------------------
  This version of ServerModules is based on Quake 1.06.
  The sources included in this archive are self-contained.
  If you only want to make minor changes you merely have to
  edit and recompile the sources contained in this archive.
  Note that most of the monster sources are not included
  here since they are not needed to compile ServerModules.

# EXTRACTING THE ARCHIVE
------------------------
  Assuming that the quake executable lives in the directory
  "c:\games\quake\", you should unzip the archive in the directory
  "c:\games\quake\".
  This creates the subdirectory "c:\games\quake\modules". The sources
  of "ServerModules" are located in "c:\games\quake\modules\src"

# PREPARING AUTOEXEC.CFG
------------------------
  Some server properties are triggered by the variable 'teamplay'
  defined in the file "c:\games\quake\modules\autoexec.cfg".
  Please modify the defaults there according to your wishes.

# ENABLING/DISABLING MODULES
----------------------------
  To disable/enable specific modules and settings not already specified
  via the 'teamplay' variable you should edit the "use_module_*"
  constants in file "_modules.qh".
  By default you'll find there
     float use_module_admin			= 1;
     float use_module_burn			= 1;
     float use_module_ctf			= 1;
     float use_module_drone			= 1;
     float use_module_exitrules			= 1;
     float use_module_hook			= 1;
     float use_module_init			= 0;
     float use_module_kicksuicider		= 1;
     float use_module_levelselect		= 1;
     float use_module_lightning			= 1;
     float use_module_messages			= 1;
     float use_module_motd			= 1;
     float use_module_observer			= 1;
     float use_module_protect			= 1;
     float use_module_rank			= 1;
     float use_module_random			= 1;
     float use_module_serverhelp		= 1;
     float use_module_skin			= 1;
     float use_module_serverconsole		= 1;
     float use_module_shrapnel			= 1;
     float use_module_telefrag			= 1;
     float use_module_vote			= 1;
     float     use_submodule_vote_exit		= 1;
     float     use_submodule_vote_exitrules	= 1;
     float use_module_weldgun			= 1;
     float do_protect_team_health		= 1; 
     float do_protect_team_armor		= 1;
  which means that except of module 'Init' all modules are enabled.
  The" use_submodule_vote_*" constants above enable/disable submodules
  of the the module 'Vote'. Setting  use_submodule_vote_exit" disables
  voting for exiting but voting for overriding ExitRules will
  still be allowed.
  Note that not all of the settings have any effect since the 'teamplay'
  variable will override some of the above specifications.

# REMOTE SERVER ADMINISTRATION
------------------------------
  Choose your password for remote server administration if you are using
  module 'Admin'. To do so please consult the section 'Defaults' found
  at the beginning of the file '_admin.qc'.

# MESSAGE OF THE DAY
--------------------
  To change the message-of-the-day displayed when a player connects to
  the server you should edit the file "_motd.qc" and change the variable 
  'motd_motd' in the function 'MotdInit'.

# LEVEL SELECTION
-----------------
  The Module 'LevelSelect' allows to specify which maps are offered on
  the server and in which order they are played.
  To achieve this the function 'LevelSelectSelectLevel' in the file
  "_levsel.qc" is used. The file also contains a commented example
  which tells you how to set up you own conditions (for instance how
  to exclude certain not-so-good maps).
  By default this module is set up so that everything works like in
  the original version of Quake, except that when a player selects
  the 'end' level the map sequence 'dm1'-...-'dm6'-'end' is played
  instead.

# PROVIDING HELP FOR PLAYERS
----------------------------
  To change the help text about server settings (which is displayed when
  connecting to a server or when typing 'help-server') just edit
  the function 'ServerHelpShowServerSettings' in the file "_servhlp.qc".

# PROVIDING MORE HELP FOR PLAYERS
---------------------------------
  If you want to inform players about more special properties of your 
  server have a look at the function 'ModulesShowInfo' in the file 
  "_modules.qc". You can freely add your own messages there.

# MISCELLANEOUS
---------------
  - The module 'Messages' by default takes care that a player receives no
    messages when picking up ammunition, armor,  etc.
    If you want to allow for some or all of these messages you should edit
    the file "_message.qh" and change the value of the flag 'messages_flag'.
  - Changing the formula used by the module 'Rank' for calculating the total
    score requires you to edit the function 'RankCountEvent' in the file
    "_rank.qc" in an obvious way.
  - Updating the module 'Skin' may become desirable if new skins become
    available in the file "player.mdl" which is distributed as part of the
    MultiSkin package. The changes you will have to make are trivial,
    just consult the file "_skin.qc".

# COMPILING THE SOURCES
-----------------------
  Copy the executable of the QuakeC compiler into the directory
  "c:\games\quake\modules\src".
  Change directory to "c:\games\quake\modules\src" and start the compiler.
  This will generate the file "c:\games\quake\modules\progs.dat".

# STARTING THE SERVER
---------------------
  Change directory to "c:\games\quake" and type
     quake -game modules -listen 2
  If you're sure that everything works as expected start your
  dedicated server as usual, for instance by typing
     quake -game modules -dedicated 8 +map e1m2
  or according to your wishes.

-------------------------------------------------------------------------
      
###### Resources Used:
----------------------

The following impulses are used:

    impulse 200    for command 'skin-next'
    impulse 201    for command 'skin-prev'
    impulse 202    for command 'help-skin'
    impulse 203    for command 'rank'
    impulse 204    for command 'help-rank'
    impulse 205    for command 'help-observer'
    impulse 206    for command 'observer-noclip'
    impulse 207    for command 'help-server'
    impulse 208    for command 'init-nextcall'
    impulse 209    for command 'init-nextskin'
    impulse 210    for command 'help-exitrules'
    impulse 211    for command 'help-vote'
    impulse 212    for command 'votes'
    impulse 213    for command 'vote-exit'
    impulse 214    for command 'vote-exitrules'
    impulse 215    for command 'help-drone'
    impulse 216    for command 'help-shrapnel'
    impulse 217    for command 'help-weld'
    impulse 218    for command 'help-modules'
    impulse 98     to throw the hook.
    impulse 97     to release the hook.
    impulse 219    for command 'help-hook'

-------------------------------------------------------------------------

###### Files:
-------------

_modules.qh
_modules.qc       Deals with internal structure of ServerModules.
_omit.qc          Contains dummy spawn functions for excluded monsters.
_plystat.qh
_plystat.qc       Deals with internal structure of ServerModules.
_burn.qh          Module Burn (Header)
_burn.qc          Module Burn (Code)
_drone.qh         Module Drone (Header)
_drone.qc         Module Drone (Code)
_exitrls.qh       Module ExitRules (Header)
_exitrls.qc       Module ExitRules (Code)
_hook.qh          Module Hook (Header)
_hook.qc          Module Hook (Code)
_init.qh          Module Init (Header)
_init.qc          Module Init (Code)
_kckscdr.qh       Module KickSuicider (Header)
_kckscdr.qc       Module KickSuicider (Code)
_levsel.qh        Module LevelSelect (Header)
_levsel.qc        Module LevelSelect (Code)
_lightng.qh       Module Lightning (Header)
_lightng.qc       Module Lightning (Code)
_message.qh       Module Messages (Header)
_message.qc       Module Messages (Code)
_motd.qh          Module Motd (Header)
_motd.qc          Module Motd (Code)
_protect.qh       Module Protect (Header)
_protect.qc       Module Protect (Code)
_observe.qc       Module Observer (Header)
_observe.qh       Module Observer (Code)
_random.qh        Module Random (Header)
_random.qc        Module Random (Code)
_rank.qh          Module Rank (Header)
_rank.qc          Module Rank (Code)
_servhlp.qh       Module ServerHelp (Header)
_servhlp.qc       Module ServerHelp (Code)
_servcon.qh       Module ServerConsole (Header)
_servcon.qc       Module ServerConsole (Code)
_shrap.qh         Module Shrapnel (Header)
_shrap.qc         Module Shrapnel (Code)
_skin.qh          Module Skin (Header)
_skin.qc          Module Skin (Code)
_telefrg.qh       Module Telefrag (Header)
_telefrg.qc       Module Telefrag (Code)
_vote.qh          Module Vote (Header)
_vote.qc          Module Vote (Code)
_weld.qh          Module WeldGun (Header)
_weld.qc          Module WeldGun (Code)
_srvmods.pat      Patch file containing all changes to be made
                  to the original QuakeC sources.
_COPYING          GNU General Public License
_MANUAL           Documentation of ServerModules patches.
_CHANGES          History of changes.
_patch.txt        Provides information how to patch and where
                  to get a free copy of the program PATCH.
progs.dat         A precompiled version of the modifications
                  described here.

All standard QuakeC sources needed to compile 'ServerModules'
are included also.

-------------------------------------------------------------------------
      
###### Copyright:
-----------------

/*
**
** Copyright (C) 1996 Johannes Plass
** 
** This program is free software; you can redistribute it and/or modify
** it under the terms of the GNU General Public License as published by
** the Free Software Foundation; either version 2 of the License, or
** (at your option) any later version.
** 
** This program is distributed in the hope that it will be useful,
** but WITHOUT ANY WARRANTY; without even the implied warranty of
** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
** GNU General Public License for more details.
**
** You should have received a copy of the GNU General Public License
** along with this program; if not, write to the Free Software
** Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
** 
** Author:   Johannes Plass (plass@dipmza.physik.uni-mainz.de)
**
*/

-------------------------------------------------------------------------
      
###### Acknowledgements:
------------------------

Module 'Skin' is based on Dennis Noordsij's (lnoordsi@inter.NL.net)
Multiskin QuakeC patch.
Please see Dennis Noordsij's QuakeC page
       http://web.inter.NL.net/users/L.J.Noordsij/qc.htm
for further details about MultiSkin.

Module 'Hook' is based on Perecli Manole's (Perecli@ix.netcom.com)
idea of the "grappling hook".

Jeff Epler (jepler@inetnebr.com) wrote '_patch.txt' which is a
short introduction on how to use and obtain the program PATCH
(which is required to handle diffs like _srvmods.pat).
The file
   ftp://ftp.cdrom.com/pub/quake/quakec/howpatch.txt
should be the most recent version of this short introduction.

Last but not least I'd like to thank Christoph 'AEon Cal.' Loewe
(cloewe@astro.uni-bonn.de) for testing parts of the ServerModules.
Visit his Quake pages on 
   http://aibn91.astro.uni-bonn.de/~cloewe/quake.html
By the way, he's also running Quake servers on 131.220.96.41
and 131.220.96.41:26001; and both are excellent places to die :-)

-------------------------------------------------------------------------
