Liquid War (v5.6.0) - Source code




General remarks
===============


  Modularity
  ----------

    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-(

  Coding style
  ------------

    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:

    * use the GNUish-style indentation - the default Emacs mode in fact

    * prefix global functions / variables / constants / types with lw_
    * <
    * NAME_OF_THE_file
    * >
    * _. For instance, a "do_it" function in myfile.c will be called
      lw_myfile_do_it

    * use capitals for constants, globals and types only. All functions are in
      lowercase with "_" to separate words

    * 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-)

    * use English only for code and comments

    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-/



Source files organization
=========================


  Main game code
  --------------

    Here you'll find the main() function, the main game loop, application-wide
    constants and other global stuff.

    It might be a good start if you want to hack the code.

    * base.h: contains global constants used in many different files.

    * game.c / game.h: contains the main game loop.

    * 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.

  Menus
  -----

    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.

    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-/

    * about.c / about.h: contains the code for the about menu.

    * advanced.c / advanced.h: contains the GUI advanced options menu.

    * connect.c / connect.h: contains code for the "connect" menu which
      displays which players are connected to the server, before the game
      actually starts.

    * controls.c / controls.h: contains the code for the controls menu.

    * graphics.c / graphics.h: code for the graphic options menu.

    * 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.

    * language.c / language.h: contains the code for the "Language" menu.

    * level.c / level.h: contains code for the menu where the player can select
      a level and its options (texture or color).

    * menu.c / menu.h: contains the code for the main menu.

    * netgame.c / netgame.h: contains the code for the net game menu.

    * options.c / options.h: contains the code for the options menu.

    * play.c / play.h: contains the code which ties the menu to the main
      gameloop.

    * rules.c / rules.h: code for the rules menu.

    * score.c / score.h: functions to display the scores at the end of the
      game.

    * speeds.c / speeds.h: contains the code for the speeds menu.

    * team.c / team.h: code for the team menu, where one choses which teams
      will play.

    * volume.c / volume.h: code for the sound menu.

    * wave.c / wave.h: code for the wave menu.

  GUI tools
  ---------

    These files contain various utilities which are used in the menus.

    * 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.

    * back.c / back.h: this modules displays the background image.

    * dialog.c / dialog.h: contains code for standard dialog boxes.

    * error.c / error.h: contains functions to display error messages once the
      game is in graphical mode.

    * help.c / help.h: generic functions to display the various help pages.

  Core algorithm
  --------------

    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!

    It's funny to note that these files have almost not been modified since
    Liquid War 5.0.

    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.

    * fighter.c / fighter.h: contains code to move the armies, once the
      gradient has been calculated.

    * 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...).

    * 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.

    * monster.s / monster.h: assembly functions to speed-up the game. It's a
      replacement for some fighter.c functions.

    * 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.

  Moving cursors
  --------------

    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.

    * 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.

    * move.c / move.h: provides an API to move the cursors.

  User input
  ----------

    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.

    This explains why there's so much code for user input, when one would think
    at first sight that "polling the keyboard is enough".

    * 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.

    * keyboard.c / keyboard.h: contains code to handle key presses.

    * mouse.c / mouse.h: wraps the mouse movements to virtual keyboard keys.
      This way the mouse can be used to control the players.

  Initialisations
  ---------------

    These files contain functions to intialize various game components. 100%
    boring code.

    * 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.

    * army.c / army.h: functions to create the armies, and place them on the
      battlefield.

    * asm.c / asm.h: various constants, macros and utilities to ensure that
      asembly code works correctly.

    * 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.

    * 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.

    * cursor.c / cursor.h: contains the code to init the cursors and place them
      on the battlefield at the beginning of the game.

    * 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.

    * exit.c / exit.h: contains code that is executed when the game ends, it
      shuts down Allegro and displays messages on the console.

    * gfxmode.c / gfxmode.h: contains code to set up the various video modes,
      and defines which modes are available for each platform.

    * init.c / init.h: contains code to initialize Allegro with proper options
      and analyze failures.

    * 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.

  Graphics
  --------

    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.

    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.

    * disp.c / disp.h: contains functions to display the battlefield.

    * 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...

    * glouglou.s / glouglou.h: assembly module, it is a replacement for some
      functions of distor.c. It goes much faster but does the same.

    * 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.

    * 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.

    * pion.c / pion.h: contains code to display the cursors.

    * viewport.c / vieport.h: code to allocate and resize the zone where the
      map is displayed, also called "viewport".

  Sound and music
  ---------------

    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.

    * music.c / music.h: contains the code to control MIDI playback.

    * sound.c / sound.h: functions to play sound.

  Data management
  ---------------

    These functions handle the datafile contents and also the custom data.

    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.

    * 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.

    * 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.

    * maptex.c / maptex.h: contains code to handle the "use default texture"
      option, and associate a map with a given texture automatically.

    * texture.c / texture.h: contains code to handle textures. Textures are
      stored in a special format which uses 5 bits per pixel.

  Random map generator
  --------------------

    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.

    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.

    * 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.

  Time handling
  -------------

    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!

    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.

    * srvtime.c / srvtime.h: code used to handle time on the server, where
      Allegro's functions are not available.

    * ticker.c / ticker.h: sets up a timer callback.

    * time.c / time.h: functions to know how long the game has been running,
      knowing that it can be interrupted.

  In-game utilities
  -----------------

    These are various utilities use to monitor and control the game while one's
    playing.

    * capture.c / capture.h: code used to capture the video output of the game
      and store it in .bmp files while playing.

    * 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.

    * 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.

    * profile.c / profile.h: provides tools to calculate how fast the game is
      runnning and what operations slow it down.

    * watchdog.c / watchdog.h: this module waits for "secret codes" to be typed
      while the game is running, and traps them.

  Command line handling
  ---------------------

    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.

    These utilities are not perfect, but they work, that's all I ask them.

    * basicopt.c / basicopt.h: handles basic command line parameters such as
      "-v" or "-h".

    * parser.c / parser.h: contains code to parse and analyze the command line
      parameters.

    * startup.c / startup.h: analyzes the command line parameters and stores
      them into global variables.

  Locale support
  --------------

    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.

    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.

    * lang.c / lang.h: contains code to handle language dependant stuff.

    * langen.c / langen.h: contains code to handle English specific stuff.

    * langfr.c / langfr.h: contains code to handle French specific stuff.

  Log and various messages
  ------------------------

    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.

    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!

    * log.h: common header for logcli.c and logsrv.c.

    * 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.

    * 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.

    * popupgen.h: common header for popup functions.

    * 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...

  Macros, utilities and string support
  ------------------------------------

    As usual, I needed to prepare a small set of usefull macros.

    * 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.

    * path.c / path.h: code used to handle filenames and paths, for instance
      remove path and file extension from a filename.

    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.

  Byte order and endianess
  ------------------------

    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.

    * 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.

  Thread support
  --------------

    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.

    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.

    I also needed to use some mutexes to prevent crashes in the user interface.

    * mutxdos.c: provides fake mutex support under DOS. This module is here
      only to make compilation easier.

    * mutxgen.h: header for mutxdos.c, mutxunix.c and mutxw32.c.

    * mutxunix.c: provides mutex support on UNIX.

    * mutxw32.c: provides mutex support on Win32.

    * thrddos.c: provides fake thread support under DOS. This module is here
      only to make compilation easier.

    * thrdgen.h: header for thrddos.c, thrdunix.c and thrdw32.c.

    * thrdunix.c: provides thread support on UNIX.

    * thrdw32.c: provides thread support on Win32.

  Launching external programs
  ---------------------------

    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.

    * execgen.h: header for execunix.c and execw32.c.

    * execunix.c: code to launch external programs on UNIX.

    * execw32.c: code to launch external programs on Win32.

  Low-level network code
  ----------------------

    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.

    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.

    This network code is not a masterpiece, it's just a little set of tools
    that have proven to work. That's all.

    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-)

    * dnsutil.c / dnsutil.h: wrapper code to issue DNS requests, without having
      to handle the hostent struct.

    * sock2cli.c: sode used to wrap low-level network function on the client.

    * sock2gen.h: header for sock2cli.c and sock2srv.c.

    * sock2srv.c: code used to wrap low-level network function on the server.

    * sockdos.c: network API for DOS.

    * sockex.c: netowrk routines shared by sockunix and sockw32.

    * sockgen.h: header for sockdos.c, sockunix.c and sockw32.c.

    * sockunix.c: network API for UNIX.

    * sockw32.c: network API for Win32.

  High-level network code
  -----------------------

    These files contains network utilities which are Liquid War specific.

    * chat.c / chat.h: functions used to handle chat messages in network games.

    * keyexch.c / keyexch.h: functions to send and receive keys to the server.
      Used on the client.

    * netconf.c / netconf.h: code to send and receive the config of the clients
      over the network.

    * netkey.c / netkey.h: contains some tools to manipulate key strokes over
      the network.

    * netmap.c / netmap.h: code to send and receive the maps over the network.

    * netmess.c / netmess.h: contains a parser to interpret plain text
      messages. Used when exhanging information over the network.

    * netplay.c / netplay.h: contains the code to set up and start network
      games.

    * network.c / network.h: contains some network related functions and
      constants used on the client.

    * ping.c / ping.h: code used on the client to estimate the average ping
      time with a server.

    * protocol.c / protocol.h: contains the sequence of messages send and
      recevied by the client when connecting on the server.

    * startinf.c / startinf.h: contains struct and tools to handle some network
      informations while starting a network game.

  Communication with the meta-server
  ----------------------------------

    The meta-server is called by both client and server. Basically, the server
    registers itself, and the client asks for a list of servers.

    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.

    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-)

    * httputil.c / httputil.h: low level functions to handle http requests.

    * wwwcli.c / wwwcli.h: code used on the client to communicate with the
      meta-server.

    * wwwsrv.c / wwwsrv.h: code used on the server to communicate with the
      meta-server.

  Server code
  -----------

    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".

    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...

    All the "logic" of the server is coded in these files, the rest is only
    utilities and helper functions.

    * server.c / server.h: main code for the server (equivalent of main.c for
      the client).

    * 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.

    * srvcont.c / srvcont.h: global network controler used on the server.

    * srvteam.c / srvteam.h: code used to handle teams on the server.

