                     .====================================.
                     |          Creepcam  v1.0            |
                     |                                    |
                     |  A spectator mode patch for Quake  |
                     |         by Jeff Preshing           |
                     `===================================='

INSTALLATION
============

1) Create a subdirectory called 'creepcam' within your main Quake directory.
   (eg. c:\quake\creepcam\)
2) Unzip the contents of the archive (creepcam.zip) into the new directory.
3) Launch Quake with a command line which includes '-game creepcam'.
   (eg. 'quake -game creepcam')


DESCRIPTION
===========

Creepcam is a new type of spectator mode Quake C patch.  Just like the other
camera patches you might have seen, it allows clients to become invisible
spectators in a deathmatch game.  However, Creepcam uses a new type of
algorithm to automatically follow the players you watch.  You may have
watched other Quake camera patches in action and thought, "Where's the other
guy" or "I would have liked to see where that rocket came from".  Creepcam
remedies these problems by always keeping 2 players on the screen, whenever
one encounters the other.  This gives you a more complete view of the action.


Here are some of its features:

* The camera is always following one player, but swivels around to include
  the other players he encounters in his travels.
* If the camera is filming one player, and another player is about to come
  around the corner, Creepcam predicts this and sets up the viewing angle
  ahead of time.
* If that second player runs into view and then disappears behind a wall
  again, the camera will keep filming both players for a moment in case he
  decides to double back.
* In a crowded room, the Creepcam will aim at more interesting players.
  "More interesting" means people on opposite teams, and people carrying
  loaded rocket launchers.
* Spectators can select who to watch by pressing the fire button.
* Spectators who forget who they're watching can press the jump button to
  make that player's name appear.
* If the primary player being followed gets killed by someone, the camera
  automatically switches to the other guy (optional).
* Multiple spectators can be present, and the server can limit the number
  allowed.
* If multiple spectators are watching the same guy, they will all use the
  same view, to avoid redundant calculations.
* Deathmatch 3 mode.
* Names of cameras do NOT appear on the [Tab] scoreboard.  You can get a list
  of spectators using console commands.
* Players who are being followed by a camera see a flashing REC * display on
  their screen (optional).
* The scoreboard is automatically shown on spectators' screens every 2 mins.
* I took some measures to reduce camera jitter in situations where players
  are running up stairs, or when the camera has to clip in front of a wall
  to keep viewing the player.
* Spectators remain in spectator mode across level changes.
* Automatically kicks annoying people out of the game (repeat suiciders and
  spectate-mode togglers)


Creepcam has several limitations.  It's just something I wrote in Quake C to
make a prototype of the algorithm I had in mind.  I expanded it into a fully
useable patch, but because it runs continuously on the server as interpreted
code, there are a couple of drawbacks:

* Probably the first thing you will think when you see the camera follow
  somebody around for the first time is, "This looks really jittery."  I
  am aware of this and the reasons why it looks that way.  I've done all I
  can to reduce this jitter but certain factors are outside of my control.
  (Read the techie section in this document for more details.)  The upside
  is, when you play back a demo recorded with CreepCam, it looks much
  smoother, no matter how jittery it looked when you first recorded it.
* Creepcam performs a lot of calculations while running, and since it's
  written in Quake C, don't be surprised if the game seems slightly less
  responsive to the other players.  You may find the game choppier/laggier,
  or you may not.  I've tested it on a network of P133's, and it works just
  fine for me.  If you run it on a fast dedicated machine like a P Pro, I'm
  sure it would work great.


Other Creepcam limitations are:

* It is only useful for deathmatch games.  Coop is possible but you won't get
  any interesting views of the monsters.  Single player, nope.
* The camera sets your screen to FOV 90.  Go ahead and widen it after, if you
  like.  The cam just won't make use of the extra viewing range.
* Your SV_MAXSPEED must be set to 320 (the default) because Creepcam uses
  this value in its prediction calculations.


CLIENT COMMANDS
===============

Creepcam has a sort of 'online help system'.  After starting a game, type
"creepcam" at the console to see a list of the commands you can send.  These
commands also work if you bind them to keys.  They are:

  spectate      Turns you into a spectator.
  join          Lets you stop spectating and join the game as a player.
  my-specs      Lists the spectators who are viewing you.
  all-specs     Lists all of the spectator clients in the game.
  show-rec      Toggles the display of REC * if you are being followed.
  autoswitch    Toggles whether the camera switches when player gets killed.
 
  impulse 201   Switches to player in entity slot #1 (use "status" command)
  impulse 202   Switches to player in entity slot #2
  ... etc
             
When you're a spectator, your jump and shoot keys let you browse through
the players available for viewing.  Also, if you set your name to "camera"
before connecting to the game, you will automatically become a spectator when
you connect.


SERVER COMMANDS
===============

Servers can limit the number of allowed spectators using the teamplay variable:

  teamplay xxy  Sets the maximum number of spectators to xx, and y can be 0, 1
                or 2 depending on the teamplay mode you like.  (eg. "teamplay
                31" means at most 3 spectators, with teamplay 1.)  By default,
                if xx is 0, there is no limit to the number of spectators.
                Restart the level after setting this.


TECHNICAL DETAILS
=================

Why does Creepcam look so shaky when you first watch it?  There are a few
reasons.

1. In this patch it is the server's job to tell the spectator clients where
   to go and which angle to face -- this means that the instructions have to
   go through Quake's network protocol.  One of the limitations of this
   protocol is that it strictly uses values between 0 and 255 when assigning
   viewing angles to a client entity.  As a result, every angle the server
   tries to set gets rounded to a multiple of 1.4 degrees (== 360/256).  This
   makes the camera unable to rotate smoothly -- instead, it jumps across 1.4
   degree boundaries to get to its target viewing angle.

   Several other spectator mode patches have this problem.  The KasCam (and
   others), which position a stationary camera on a wall and automatically aim
   directly at a moving player, are really affected by this 1.4 degree
   symptom.

2. A Quake spectator-mode client receives a simultaneous update for the
   camera's position and viewing angle in every network message.
   Unfortunately, it does not process these updates simultaneously.  Rather,
   it seems to update the camera's angle, plus the positions of all other
   entities, all on one screen refresh, and then update the position of its
   own viewpoint on the next screen refresh.  For proof of this, try running
   a dedicated server and set sys_ticrate to 0.3.  Now make a spectator
   client follow one of the other players around -- there are clearly 2
   screen updates which follow every game tic.

   If you are running a network client whose screen refresh rate is much
   faster than the server's game tic rate (for dedicated servers, this usually
   means >20fps), you're going to see some violent shaking when the camera is
   following someone. If you instead run Creepcam on a listen server, where
   the server is in spectator mode, this problem goes away, but of course
   this makes the game less responsive for the real clients.

But hark!  Fear not... for there is a light at the end of this tunnel.  If you
record a demo while using spectator mode, and then play the demo back, almost
all the jitter caused by #1 and #2 above will go away.  Quake's demo playback
engine interpolates the positions and angles of every entity (including the
spectator itself) between game tics.  Basically, this smooths out the problem.
Use Winquake if you want the ability to record client-side demos.

Occasionally, even when watching a demo, I've seen a few hiccups which I can't
attribute to either #1 or #2.  Perhaps I just have some bonehead code in there
somewhere.


BUGS
====

If you notice any glaring bugs, like Quake exiting with a bad message, feel
free to e-mail me about them (address below).  Please include as much
information as you can about what the players were doing, and exactly what the
result was. But DO NOT E-MAIL DEMOS TO ME!  My mail server will just ignore
e-mails that are too big.

[In particular, there's one very bad bug which I can't consistently
reproduce.  Any insight you could offer would be nice.  When I was able to
test this patch with lots of machines, I went nuts switching multiple clients
in and out of spectator mode, switching viewpoints, etc.  Sometimes the game
would end up in a state where some players could walk and shoot right
through other players!  Quake seems to stop doing collision detection between
two players, but those two players can still shoot and bump into everyone
else.  This is strange -- if it's a Quake C bug, I would expect only to see
a player who could walk and shoot right through _everyone_ else.]


THANKS
======

* id Software - hey you guys are good!
* The guys who made Quake DEM specs, Quake network specs, Quakeworld specs,
  Quake BSP specs - incredible reverse engineering work.  Those are some
  great resources!
* The people who helped test it in one of its forms:  dEvIl, Slop, MoFo,
  Jun10r, mOO, slacker, Gamez, Josh, Becky, Eric, Mike, Paul, Chris, Ben,
  Garth, Trent, Ryan.  As far as I can recall.  (Bonus game: guess which
  ones are aliases and which are real names)  Special thanks go out to Jun10r.
  This guy ran a few crippled versions of Creepcam on his public T1 server.
* The people who made other types of spectator patches for Quake.  Seeing
  these patches in action was neat and educational.  I actually browsed
  through the JCam source code to help figure out a huge bug in my own code.
* The other Creep (Creep[BORK]) - for agreeing not to pretend it's his patch.


Jeff Preshing -- aka "Creep"
  Email: jpreshin@uwaterloo.ca
  Web:   http://noether.math.uwaterloo.ca/~jpreshin
