Source documentation

[Jeffrey Nowakowski <jeffno@ccs.neu.edu>]

We really need some documentation on the source code.  Just a general
overview about how it all works.  Sure, you can spend hours looking at
the source (and you will have to even with documentation), but it
would be so much faster to read an overview.

I'd like to figure out how the network and packets work, so I can do
some work on viewing recordings (being able to jump around and being
able to make cuts).  I've been putting it off because I don't know how
packets work, and don't really want to spend time tracing through the
code without a guide.  I know there are people on this list that have
an in depth understanding of the network code.  It'd be great if they
could save me and others some time and write an overview.

I've spoken with Carlos about this awhile back, and I know he has some
personal documentation he has written to help himself out.  I've done
the same, and I'm sure others have as well.  So, to get the ball
rolling, I'm going to dump what I've written here.  Hopefully others
will do the same.

It's not meant for distrubition; it's meant as a starting point.  If
we start throwing documentation on this list eventually we'll have
enough to start piecing things together.

Very rough doc notes follow.

-Jeff

Server Processes
================

netrekd: (aka newstartd) Listens for incoming clients that want to connect to
          the server.  Reads the .ports file which tells it what programs
          to run when a client connects.  Normally, forks an ntserv process
          for each client, but handles other things such as the player list
          for the metaserver.

ntserv: Communicates with the client.  Will start daemon if shared memory
        doesn't exist.  Each player has their own ntserv process.

daemon: Maintains the game state.  Will start robots like hockey if .sysdef
        option is set.


Shared Memory
=============
Contains the game state.  This is updated by both ntserv and the daemon.
Updated by newstartd as well? (for queues?)

Globals
=======

data.c/h: Holds global data.  Lotsa crap.

Queues
======

Robots
======
Started through .sysdef when the server starts, or through a player vote.

If through .sysdef, the daemon forks the robot when daemon is started.

If through a vote, the robot is forked at the time of the vote.

Both the daemon and the robot run at the same time.  The daemon handles the
general game engine (moving players, firing weapons, etc).  The robot then
handles extra things like keeping track of the game clock, or modifies the
behavior of the game by messing with the shared memory (like in hockey).

Configuring the server
======================

Game speed:
-----------
UPDATE
REALITY


.sysdef
-------
Read on server startup.  readsysdefaults() in ntserv/daemonII.c, ntserv/main.c

.features
---------

config.h.in
--------------
#defines

ntserv/defs.h
-------------
#defines

keycomp/defs.h
--------------
Same as ntserv/defs.h, but SURREND=5 instead of 4?  Should be link to
ntserv instead?  What is kecomp/ used for?

getship.c
---------
Contains ship stats.  How does SHIP in .sysdefs affect?

Messages
========
see also command_questions.txt

messages are handled by ntserv.  daemon doesn't touch them.  robots
need to handle messages to check commands (using gencmds.c).

socket.c, parseIgnore(): takes care of :D (ignore doosh mess), :M (ignore
                         multi-line macro, pig call (5 spaces sent to yerself),
                         and :[ita] messages (ignore player).


Sample Scenario:
================
Short packets?
TCP/IP
UDP

Player A shoots a torp: Packet arrives, handled by..

Debugging/Error Messages:
=========================
ERRORS (why no date?), stdout/err for different processes.  ERRORS
not usable in all processes?  ERROR() doesn't seem to work in robots
(puck, basep, etc); perror() does though.