<?xml version="1.0"?>
<!DOCTYPE file SYSTEM "file.dtd">
<file title="Source code">

  <chap title="General remarks">
    <part title="Modularity">
      <text>
	Liquid War 5 is basically a big C program. I've splitted
	the source code in many small files for I do not like to
	have to handle big monolithic sources, but this does not
	mean Liquid War is very modular. In fact Liquid War 5
	is quite bloated with global variables and other ugly
	stuff 8-(
      </text>
    </part>
    <part title="Coding style">
      <text>
	To be honest, it's a big mess. You won't find 2 files
	coded in the same maner... OK, I'm exagerating a bit.
	From now I try to make an effort and
	stick to basic rules such as:
      </text>
      <list>
	<elem>
	  use the GNUish-style indentation - the default Emacs mode in fact	  
	</elem>
	<elem>
	  prefix global functions / variables / constants / types with
	  lw_&lt;NAME_OF_THE_file&gt;_. For instance, a "do_it" function
	  in myfile.c will be called lw_myfile_do_it
	</elem>
	<elem>
	  use capitals for constants, globals and types only. All functions
	  are in lowercase with "_" to separate words
	</elem>
	<elem>
	  keep on using 8.3 filenames for .c source files. This is for
	  better DOS integration. DOS version of Liquid War is still
	  maintained, you know 8-)
	</elem>
	<elem>
	  use English only for code and comments
	</elem>
      </list>
      <text>
	I might decide to rename and cleanup everything some day, for
	it would help other coders to understand what I wrote, but well,
	this is certainly not a thrilling task 8-/
      </text>
    </part>
  </chap>

  <chap title="Source files organization">
    <part title="Main game code">
      <text>
	Here you'll find the main() function, the main game
	loop, application-wide constants and other global stuff.
      </text>
      <text>
	It might be a good start if you want to hack the code.
      </text>
      <list>
	<elem>
	  base.h: 
	  contains global constants used in many different files.
	</elem>
	<elem>
	  game.c / game.h: 
	  contains the main game loop.
	</elem>
	<elem>
	  main.c / main.h: 
	  the file where the main C function is declared.
	  Doesn't contain much except calling init functions and
	  running the GUI.
	</elem>
      </list>
    </part>

    <part title="Menus">
      <text>
	The menus are coded using the Allegro GUI system.
	While this system is very powerfull, it's IMHO not adapted to
	very complex GUIs, and one of its drawbacks is that it's not
	so easy to redesign something once you've coded it.
      </text>
      <text>
	Besides, when I started coding the GUI in 1998, I did it
	in a rather ugly way, and now I'm paying for my being lazy
	at that time, since I spent hours coding when I want to
	change something 8-/
      </text>
      <list>
	<elem>
	  about.c / about.h: 
	  contains the code for the about menu.
	</elem>
	<elem>
	  advanced.c / advanced.h: 
	  contains the GUI advanced options menu. 
	</elem>
	<elem>
	  connect.c / connect.h: 
	  contains code for the "connect" menu which displays which players
	  are connected to the server, before the game actually starts.
	</elem>
	<elem>
	  controls.c / controls.h: 
	  contains the code for the controls menu.
	</elem>
	<elem>
	  graphics.c / graphics.h: 
	  code for the graphic options menu.
	</elem>
	<elem>
	  internet.c / internet.h: 
	  contains the code for the "Search for Internet games" menu, where one
	  can pick up a running server automatically with the help of the meta-server.
	</elem>
	<elem>
	  language.c / language.h: 
	  contains the code for the "Language" menu.
	</elem>
	<elem>
	  level.c / level.h: 
	  contains code for the menu where the player
	  can select a level and its options (texture or color).
	</elem>
	<elem>
	  menu.c / menu.h: 
	  contains the code for the main menu.
	</elem>
	<elem>
	  netgame.c / netgame.h: 
	  contains the code for the net game menu.
	</elem>
	<elem>
	  options.c / options.h: 
	  contains the code for the options menu.
	</elem>
	<elem>
	  play.c / play.h: 
	  contains the code which ties the menu to the main gameloop.
	</elem>
	<elem>
	  rules.c / rules.h: 
	  code for the rules menu.
	</elem>
	<elem>
	  score.c / score.h: 
	  functions to display the scores at the end of the game.
	</elem>
	<elem>
	  speeds.c / speeds.h: 
	  contains the code for the speeds menu.
	</elem>
	<elem>
	  team.c / team.h: 
	  code for the team menu, where one choses which teams will play.
	</elem>
	<elem>
	  volume.c / volume.h: 
	  code for the sound menu.
	</elem>
	<elem>
	  wave.c / wave.h: 
	  code for the wave menu.
	</elem>
      </list>
    </part>

    <part title="GUI tools">
      <text>
	These files contain various utilities which are used
	in the menus.
      </text>
      <list>
	<elem>
	  alleg2.c / alleg2.h: 
	  contains some tweaked allegro functions. I wanted to use
	  bitmaps with sevral colors for my fonts, and change some
	  of the allegro default behavior. So rather than modifying
	  the allegro source code right in the library I copied
	  it in this file and then modified it.
	</elem>
	<elem>
	  back.c / back.h: 
	  this modules displays the background image.
	</elem>
	<elem>
	  dialog.c / dialog.h: 
	  contains code for standard dialog boxes.
	</elem>
	<elem>
	  error.c / error.h: 
	  contains functions to display error messages once the game
	  is in graphical mode.
	</elem>
	<elem>
	  help.c / help.h: 
	  generic functions to display the various help pages.
	</elem>
      </list>
    </part>

    <part title="Core algorithm">
      <text>
	Here's *the* interesting part.
	All the rest of the code is just sugar coat to display stuff,
	receive players commands, communicate with other computers,
	handle errors, etc... But the real thing is here!
      </text>
      <text>
	It's funny to note that these files have almost not been
	modified since Liquid War 5.0.
      </text>
      <text>
	It's also interesting to note that they represent a small
	percentage of the total amount of code in the game.
	This tends to prove - and I'm convinced of it - that game
	programming does not only consists in having great ideas,
	but also requires a lot of "dirty" and boring work.
	Honestly, coding an option menu is as boring as
	coding Liquid War algorithm is fun.
      </text>
      <list>
	<elem>
	  fighter.c / fighter.h: 
	  contains code to move the armies, once the gradient has been calculated.
	</elem>
	<elem>
	  grad.c / grad.h: 
	  this module calculates the gradient for each team.
	  One could say it's the "kernel" of the game,
	  since most of the CPU time is spent in this module
	  (except if you have a slow display...).
	</elem>
	<elem>
	  mesh.c / mesh.h: 
	  contains code to set up a usable mesh with a map.
	  Mesh are re-calculated at each time a new game is started,
	  the reason for this being that meshes are *very* big so
	  it would not be reasonnable to save them directly on the HD.
	</elem>
	<elem>
	  monster.s / monster.h: 
	  assembly functions to speed-up the game.
	  It's a replacement for some fighter.c functions.
	</elem>
	<elem>
	  spread.s / spread.h: 
	  contains assembly replacements for some functions of grad.c.
	  These replacements do the same than the original ones from grad.c,
	  but faster. Could still be optimized.
	</elem>
      </list>
    </part>

    <part title="Moving cursors">
      <text>
	It looks like nothing, but moving a cursor and deciding where
	it should go if there's a wall in front of it is not that easy,
	especially if you want things to work nicely.
      </text>
      <list>
	<elem>
	  autoplay.c / autoplay.h: 
	  contains the code for the computer AI.
	  This module simulates keypresses from the computer,
	  then the computer is handled as any other player.
	</elem>
	<elem>
	  move.c / move.h: 
	  provides an API to move the cursors.
	</elem>
      </list>
    </part>

    <part title="User input">
      <text>
	Until 5.4.0, Liquid War did not have network support.
	As it is designed to be multiplayer, one needed to have
	several players on the same computer. The mouse also
	needed to be handled in a special way since cursors
	can *not* pass walls in Liquid War. Additionnally,
	I wanted all input channels (keyboard mouse and joystick)
	to be handled in a unified way.
      </text>
      <text>
	This explains why there's so much code for user input,
	when one would think at first sight that 
	"polling the keyboard is enough".
      </text>
      <list>
	<elem>
	  joystick.c / joystick.h: 
	  contains code to support joystick input. It wraps joystick buttons
	  to virtual keyboard keys, so that joystick and keyboard behave
	  exactly the same.
	</elem>
	<elem>
	  keyboard.c / keyboard.h: 
	  contains code to handle key presses.
	</elem>
	<elem>
	  mouse.c / mouse.h: 
	  wraps the mouse movements to virtual keyboard keys.
	  This way the mouse can be used to control the players.
	</elem>
      </list>
    </part>

    <part title="Initialisations">
      <text>
	These files contain functions to intialize various game
	components. 100% boring code.
      </text>
      <list>
	<elem>
	  area.c / area.h: 
	  contains functions to create the game area.
	  Basically it contains functions to create
	  the data structures in which the level is
	  stored during the game.
	</elem>
	<elem>
	  army.c / army.h: 
	  functions to create the armies, and place them on the
	  battlefield.
	</elem>
	<elem>
	  asm.c / asm.h: 
	  various constants, macros and utilities to
	  ensure that asembly code works correctly.
	</elem>
	<elem>
	  bigdata.c / bigdata.h: 
	  I had a really hard time with the malloc function with DJGPP
	  under Win95 dos box. I tried to have it working for hours and
	  hours but my program kept being buggy. So I decided to allocate
	  the memory myself, in a memory zone I create at startup.
	  This is what this module does: create a huge memory zone
	  and then give parts of it to the rest of the program.
	</elem>
	<elem>
	  config.c / config.h: 
	  contains everything that is related to the game configuration.
	  This module contains in global variables all the parameters
	  that are stored in the config file.
	</elem>
	<elem>
	  cursor.c / cursor.h: 
	  contains the code to init the cursors and place them
	  on the battlefield at the beginning of the game.
	</elem>
	<elem>
	  decal.c / decal.h: 
	  This module makes the link between teams and players.
	  Its coding is quite ugly, for some modules in LW assume
	  that when 2 teams are playing they are always teams 0 and 1.
	  So when 3 teams are playing are playing and the second team loses,
	  one has to make team 2 become team 1.
	  That's what this module is for.
	</elem>
	<elem>
	  exit.c / exit.h: 
	  contains code that is executed when the game ends,
	  it shuts down Allegro and displays messages on the console.
	</elem>
	<elem>
	  gfxmode.c / gfxmode.h: 
	  contains code to set up the various video modes,
	  and defines which modes are available for each platform.
	</elem>
	<elem>
	  init.c / init.h: 
	  contains code to initialize Allegro with proper options and analyze failures.
	</elem>
	<elem>
	  palette.c / palette.h: 
	  contains function to set up the current color palette.
	  Liquid War uses different palettes, depending on what
	  colors are chosen for teams.
	</elem>
      </list>
    </part>

    <part title="Graphics">
      <text>
	Here lies most of the graphic functions in Liquid War.
	There's not that much code since Liquid War's strength
	is not its visual effects, but rather its gameplay.
      </text>
      <text>
	The only "funny" thing is the wave effect. I'm quite
	happy with it, and honestly, I do think it is rather fast,
	given the fact that it uses no 3D hardware at all.
      </text>
      <list>
	<elem>
	  disp.c / disp.h: 
	  contains functions to display the battlefield.
	</elem>
	<elem>
	  distor.c / distor.h: 
	  this module contains code to create the "wave effect".
	  It uses a lot of data tables, and is quite complicated
	  to understand...
	</elem>
	<elem>
	  glouglou.s / glouglou.h: 
	  assembly module, it is a replacement for some functions of distor.c.
	  It goes much faster but does the same.
	</elem>
	<elem>
	  info.c / info.h: 
	  contains code to display the info bar.
	  The info bar is the bar which display the time left and the amount of players
	  for each team while the game is running.
	</elem>
	<elem>
	  message.c / message.h: 
	  provides an API to display messages during the game.
	  Very useful if you want to debug the game: you can trace
	  and display anything.
	</elem>
	<elem>
	  pion.c / pion.h: 
	  contains code to display the cursors.
	</elem>
	<elem>
	  viewport.c / vieport.h: 
	  code to allocate and resize the zone where the map is
	  displayed, also called "viewport".
	</elem>
      </list>
    </part>

    <part title="Sound and music">
      <text>
	Sound and music routines required some encapsulation,
	since the game must be able to run even if the sound and/or
	music did not load correctly.
      </text>
      <list>
	<elem>
	  music.c / music.h: 
	  contains the code to control MIDI playback.
	</elem>
	<elem>
	  sound.c / sound.h: 
	  functions to play sound.
	</elem>
      </list>
    </part>

    <part title="Data management">
      <text>
	These functions handle the datafile contents and
	also the custom data.
      </text>
      <text>
	Note that the various utilities such as liquidwarcol,
	liquidwarmap and liquidwartex do not share code with
	the main executable. This is obviously a design error,
	for liquidwarmap will handle maps in a very poor
	way and is unable to autodetect map errors, whereas
	the game does it rather well. Blame the programmer.
      </text>
      <list>
	<elem>
	  disk.c / disk.h: 
	  contains all the code to access data from the hard drive.
	  In fact, all the HD access is done at startup.
	</elem>
	<elem>
	  map.c / map.h: 
	  contains code to load the maps from a datafile raw data
	  or a user defined bitmap
	  to a usable structure in RAM.
	</elem>
	<elem>
	  maptex.c / maptex.h: 
	  contains code to handle the "use default texture"
	  option, and associate a map with a given texture
	  automatically.
	</elem>
	<elem>
	  texture.c / texture.h: 
	  contains code to handle textures.
	  Textures are stored in a special format which uses
	  5 bits per pixel.
	</elem>
      </list>
    </part>

    <part title="Random map generator">
      <text>
	Liquid War has a "generate random map" feature which is
	available within the game and also as an external program.
	The source code for the external program is in ./utils/lwmapgen
	in Liquid War source distribution. This program has been
	coded by David Redick, is also available on
	"http://www.cs.clemson.edu/~dredick/lwmapgen/"
	and works on GNU/Linux. Compiling this program under DOS
	and/or Windows is untested and unsupported.
      </text>
      <text>
	The random map generator within Liquid War - which of course
	works on any platform support by LW - uses for its greater 
	part the same source code as the external lwmapgen program.
      </text>
      <list>
	<elem>
	  random.c / random.h:
	  wrapper for the map generator written by David Redick.
	  It basically does the same as ./utils/lwmapgen/main.c 
	  except that it does it within Liquid War as it is running
	  and not in an external independant program.
	</elem>
      </list>
    </part>

    <part title="Time handling">
      <text>
	Time handling is fundamental in a game. Time is used for
	visual effects (waves...) during the game, it's used to generate
	some pseudo random stuff, well, it's used everywhere!
      </text>
      <text>
	Note that on the client, I use 2 "different" clocks. The first
	counts the "real" time, in seconds. The second one is counts "rounds" 
	and is incremented by 1 at each game round.
      </text>
      <list>
	<elem>
	  srvtime.c / srvtime.h: 
	  code used to handle time on the server, where Allegro's functions
	  are not available.
	</elem>
	<elem>
	  ticker.c / ticker.h: 
	  sets up a timer callback.
	</elem>
	<elem>
	  time.c / time.h: 
	  functions to know how long the game has been running,
	  knowing that it can be interrupted.
	</elem>
      </list>
    </part>

    <part title="In-game utilities">
      <text>
	These are various utilities use to monitor and control
	the game while one's playing. 
      </text>
      <list>
	<elem>
	  capture.c / capture.h: 
	  code used to capture the video output of the game and store it
	  in .bmp files while playing.
	</elem>
	<elem>
	  checksum.c / checksum.h: 
	  utilities to generate a checksum from a given game state.
	  Used in network code to make sure all the clients stay
	  synchronized.
	</elem>
	<elem>
	  code.c / code.h: 
	  This file contains the code to handle key presses during
	  the game. That's to say the pause key for instance.
	</elem>
	<elem>
	  profile.c / profile.h: 
	  provides tools to calculate how fast the game is runnning
	  and what operations slow it down.
	</elem>
	<elem>
	  watchdog.c / watchdog.h: 
	  this module waits for "secret codes" to be typed while
	  the game is running, and traps them.
	</elem>
      </list>
    </part>

    <part title="Command line handling">
      <text>
	OK, now to all the UNIX guys, I *know* there are many
	ways to do things in a better and simple way than I did.
	But keep in mind that in 1998, under DOS, I had a rotten command
	line and even now I need everything to work on both UNIX and
	Microsoft platforms.
      </text>
      <text>
	These utilities are not perfect, but they work, that's all
	I ask them.
      </text>
      <list>
	<elem>
	  basicopt.c / basicopt.h: 
	  handles basic command line parameters such as "-v" or "-h".
	</elem>
	<elem>
	  parser.c / parser.h: 
	  contains code to parse and analyze the command line parameters.
	</elem>
	<elem>
	  startup.c / startup.h: 
	  analyzes the command line parameters and stores them
	  into global variables.
	</elem>
      </list>
    </part>

    <part title="Locale support">
      <text>
	Liquid War now has locale support. Basically, all the
	labels and texts in the UI are stored in constants.
	There's simply file per language.
      </text>
      <text>
	Note to translators: if you decide to translate the
	menus in another language, keep in mind that all the
	translations must fit in the various buttons and textboxes.
	The best resolution to test this 
	- the one where letters take most place - is 640x480.
      </text>
      <list>
	<elem>
	  lang.c / lang.h: 
	  contains code to handle language dependant stuff.
	</elem>
	<elem>
	  langen.c / langen.h: 
	  contains code to handle English specific stuff.
	</elem>
	<elem>
	  langfr.c / langfr.h: 
	  contains code to handle French specific stuff.
	</elem>
      </list>
    </part>

    <part title="Log and various messages">
      <text>
	OK, the API of the log routines is a piece of crap.
	Now I'm simply too lazy to change it. It works, that's
	all I ask.
      </text>
      <text>
	BTW, there's a clear advantage in using custom-made
	log functions instead of plain calls to "fprintf(stderr,...".
	It might not be obvious for UNIX users, but think about
	Windows. Nothing like a "tail -f" there, nor a proper
	output redirection system. When a user clicks on the
	Liquid War icon, I want "console" information to be logged
	in a file!
      </text>
      <list>
	<elem>
	  log.h: 
	  common header for logcli.c and logsrv.c.
	</elem>
	<elem>
	  logcli.c: 
	  contains code to display messages on the console.
	  It's usefull for console may have different behaviors
	  when the games is used on different platforms.
	  This file is used to compile the client.
	</elem>
	<elem>
	  logsrv.c: 
	  contains code to display messages on the console.
	  This file is used to compile the server, which does not
	  use Allegro at all.
	</elem>
	<elem>
	  popupgen.h:
	  common header for popup functions.
	</elem>
	<elem>
	  popupw32.c:
	  code to handle popup on the Win32 platform. Popups are a must-have
	  under Windows for error diagnostics, since the average Windows user
	  never gives any look at any log file...
	</elem>
      </list>
    </part>

    <part title="Macros, utilities and string support">
      <text>
	As usual, I needed to prepare a small set of usefull macros.
      </text>
      <list>
	<elem>
	  macro.h:
	  contains basic wrappers/macros for
	  snprintf like functions. This mostly to ease up string
	  manipulation which is - as always - a nightmare in standard C.
	</elem>
	<elem>
	  path.c / path.h:
	  code used to handle filenames and paths, for instance remove
	  path and file extension from a filename.
	</elem>
      </list>
      <text>
	It's also important to note that Liquid War uses snprintf instead
	of sprintf, for using the latter is very likely to cause buffer
	overflows. Under Linux glibc provides this function but Microsoft 
	does not provide it natively on Windows. Therefore I used a
	third party snprintf implementation by Mark Martinec:
	"http://www.ijs.si/software/snprintf/" and its source is available
	in the ./utils directory of Liquid War source distribution.
      </text>
    </part>

    <part title="Byte order and endianess">
      <text>
	  As you might know, PC Intel based computers are "little-endian"
	  while Sun Sparc stations and Mac computers are "big-endian".
	  This is an issue for LW since in network games maps are transmitted
	  in binary format. Therefore I needed to set up some
	  (un)serialization fonctions.
      </text>
      <list>
	<elem>
	  serial.c / serial.h:
	  code used to transform integers and map headers into an uniform
	  cross-platform byte stream which is readable by both little and
	  big endian machines.
	</elem>
      </list>
    </part>

    <part title="Thread support">
      <text>
	Liquid War does have thread support, but it is a "limited"
	thread support. I mean that the game is generally monothreaded,
	but a few functions use threads. For instance, calls to
	the meta-server are done within threads.
      </text>
      <text>
	Basically, I do not really enjoy programming in a multithreaded
	environnement. So when possible, I chose the monothread path,
	and used threads only where I simply would not be able to
	find another acceptable solution.
      </text>
      <text>
	I also needed to use some mutexes to prevent crashes in the
	user interface.
      </text>
      <list>
	<elem>
	  mutxdos.c: 
	  provides fake mutex support under DOS.
	  This module is here only to make compilation easier.
	</elem>
	<elem>
	  mutxgen.h: 
	  header for mutxdos.c, mutxunix.c and mutxw32.c.
	</elem>
	<elem>
	  mutxunix.c: 
	  provides mutex support on UNIX.
	</elem>
	<elem>
	  mutxw32.c: 
	  provides mutex support on Win32.
	</elem>
	<elem>
	  thrddos.c: 
	  provides fake thread support under DOS.
	  This module is here only to make compilation easier.
	</elem>
	<elem>
	  thrdgen.h: 
	  header for thrddos.c, thrdunix.c and thrdw32.c.
	</elem>
	<elem>
	  thrdunix.c: 
	  provides thread support on UNIX.
	</elem>
	<elem>
	  thrdw32.c: 
	  provides thread support on Win32.
	</elem>
      </list>
    </part>

    <part title="Launching external programs">
      <text>
	Liquid War might sometimes launch external programs.
	This is (for security reason) not a default behavior and has
	to be activated and configured by yourself, using the "-callback"
	command line option on the server for instance.
      </text>
      <list>
	<elem>
	  execgen.h:
	  header for execunix.c and execw32.c.
	</elem>
	<elem>
	  execunix.c:
	  code to launch external programs on UNIX.
	</elem>
	<elem>
	  execw32.c:
	  code to launch external programs on Win32.
	</elem>
	<elem>
	  exec2.c:
	  code to launch external programs within the client, without any
	  interaction with the user, ie no unwanted popping window for instance.
	</elem>
      </list>
    </part>

    <part title="Low-level network code">
      <text>
	There are network packages for Allegro, but I decided not to
	use them. Socket support is not that hard to implement under UNIX
	and Win32 and besides, I've done it for my job recently, so I just
	knew how to do it.
      </text>
      <text>
	Another reason which decided me to code my own toolbox is that
	I did not want Liquid War to have external dependencies - except
	Allegro of course. This way, UNIX gamers to not have to set up and/or
	download a specific network library. It's also easier to integrate
	the game in projects like Debian if it has few dependencies.
      </text>
      <text>
	This network code is not a masterpiece, it's just a little set
	of tools that have proven to work. That's all.
      </text>
      <text>
	BTW, it's important to notice that when linking with Allegro,
	most blocking UNIX calls ("sleep" or "recv" for instance) stop
	working: they alwasys return immediately. This led me to
	implement weird ugly hacks, like calling "recv" in a loop until
	it gets what it wants... This is theorically and practically
	a performance killer, but I found no other way to fix this.
	And FYI, this is not an Allegro bug, it's a feature 8-)
      </text>
      <list>
	<elem>
	  dnsutil.c / dnsutil.h: 
	  wrapper code to issue DNS requests, without having
	  to handle the hostent struct.
	</elem>
	<elem>
	  sock2cli.c: 
	  sode used to wrap low-level network function on the client.
	</elem>
	<elem>
	  sock2gen.h: 
	  header for sock2cli.c and sock2srv.c.
	</elem>
	<elem>
	  sock2srv.c: 
	  code used to wrap low-level network function on the server.
	</elem>
	<elem>
	  sockdos.c: 
	  network API for DOS.
	</elem>
	<elem>
	  sockex.c: 
	  netowrk routines shared by sockunix and sockw32.
	</elem>
	<elem>
	  sockgen.h: 
	  header for sockdos.c, sockunix.c and sockw32.c.
	</elem>
	<elem>
	  sockunix.c: 
	  network API for UNIX.
	</elem>
	<elem>
	  sockw32.c: 
	  network API for Win32.
	</elem>
      </list>
    </part>

    <part title="High-level network code">
      <text>
	These files contains network utilities 
	which are Liquid War specific.
      </text>
      <list>
	<elem>
	  chat.c / chat.h: 
	  functions used to handle chat messages in network games.
	</elem>
	<elem>
	  keyexch.c / keyexch.h: 
	  functions to send and receive keys to the server. Used on the
	  client.
	</elem>
	<elem>
	  netconf.c / netconf.h: 
	  code to send and receive the config of the clients over the network.
	</elem>
	<elem>
	  netkey.c / netkey.h: 
	  contains some tools to manipulate key strokes over the network.
	</elem>
	<elem>
	  netmap.c / netmap.h: 
	  code to send and receive the maps over the network.
	</elem>
	<elem>
	  netmess.c / netmess.h: 
	  contains a parser to interpret plain text messages. Used when
	  exhanging information over the network.
	</elem>
	<elem>
	  netplay.c / netplay.h: 
	  contains the code to set up and start network games.
	</elem>
	<elem>
	  network.c / network.h: 
	  contains some network related functions and constants used on
	  the client.
	</elem>
	<elem>
	  ping.c / ping.h: 
	  code used on the client to estimate the average ping time
	  with a server.
	</elem>
	<elem>
	  protocol.c / protocol.h: 
	  contains the sequence of messages send and recevied by the
	  client when connecting on the server.
	</elem>
	<elem>
	  startinf.c / startinf.h: 
	  contains struct and tools to handle some network informations while
	  starting a network game.
	</elem>
      </list>
    </part>

    <part title="Communication with the meta-server">
      <text>
	The meta-server is called by both client and server.
	Basically, the server registers itself, and the client
	asks for a list of servers.
      </text>
      <text>
	The meta-server itself is just a set of simple PHP scripts
	with a simple MySQL database. I chose PHP because my
	provider allows execution of PHP pages, that's all.
      </text>
      <text>
	The protocol is *very* basic, and uses HTTP 1.0 for
	requests. Answers are received in plain text, with
	one information per line. There's no garantee that
	this would work with any HTTP server, but experience
	proved that it works with my provider 8-)
      </text>
      <list>
	<elem>
	  httputil.c / httputil.h: 
	  low level functions to handle http requests.
	</elem>
	<elem>
	  wwwcli.c / wwwcli.h: 
	  code used on the client to communicate with the meta-server.
	</elem>
	<elem>
	  wwwsrv.c / wwwsrv.h: 
	  code used on the server to communicate with the meta-server.
	</elem>
      </list>
    </part>

    <part title="Server code">
      <text>
	The Liquid War server is a rather small program. The only
	thing it does is accept new players, transmit map and
	game parameters between them, and then "replicate keys".
      </text>
      <text>
	By "replicate keys" I mean that the server asks each client
	what keys have been pressed during the last round, and
	then dispatches this informations to all clients.
	This implies that the server has absolutely no idea of
	who's loosing, who's winning, etc...
      </text>
      <text>
	All the "logic" of the server is coded in these files,
	the rest is only utilities and helper functions.
      </text>
      <list>
	<elem>
	  server.c / server.h: 
	  main code for the server (equivalent of main.c for the client).
	</elem>
	<elem>
	  srvchan.c / srvchan.h: 
	  code used to handles channels on the server. A channel is associated
	  to a given computer and may manage several teams.
	</elem>
	<elem>
	  srvcont.c / srvcont.h: 
	  global network controler used on the server.
	</elem>
	<elem>
	  srvteam.c / srvteam.h: 
	  code used to handle teams on the server.
	</elem>
      </list>
    </part>
  </chap>

</file>