Liquid War 6, a unique multiplayer wargame. Table of Contents ***************** 1 Introduction 1.1 In a nutshell 1.2 Project status 1.3 How you can help 1.3.1 Help GNU 1.3.2 Todo list 2 User's manual 2.1 Mailing lists 2.1.1 General discussion 2.1.2 Announcements 2.1.3 Bugs 2.2 Getting the game 2.2.1 Download source 2.2.2 Download binaries 2.3 Installation 2.3.1 Requirements 2.3.2 Optional libraries 2.3.3 Compiling 2.4 Troubleshooting 2.4.1 Compilation problems 2.4.2 Check installation 2.4.3 Problems running the game 2.5 How to play 2.6 Strategy tips 2.7 User interface 2.8 Network games 2.9 Graphics 2.10 Sound & music 2.11 Config file 2.12 Logs 2.13 Report bugs 3 Hacker's guide 3.1 Designing levels 3.2 Architecture 3.3 About mod-gl 3.4 Compilation tips 3.5 Coding guidelines 3.6 Using the console 3.7 Advanced tweaking 3.8 Writing modules 3.9 Use as a library 3.10 Network protocol 3.11 Using GNU Arch 4 Reference 4.1 Basic options 4.2 Doc options 4.3 Show options 4.4 Path options 4.5 Graphics options 4.6 Sound options 4.7 Network options 4.8 Map parameters 4.8.1 Choosing the map 4.8.2 Map options (options.xml) 4.8.3 Map style (style.xml) 4.9 Advanced settings 4.10 Script hooks 4.11 C to Guile API 4.12 C functions 4.12.1 libcfg 4.12.2 libcli 4.12.3 libcns 4.12.4 libdyn 4.12.5 libgfx 4.12.6 libgui 4.12.7 libhlp 4.12.8 libimg 4.12.9 libker 4.12.10 libldr 4.12.11 libmap 4.12.12 libnet 4.12.13 libp2p 4.12.14 libsnd 4.12.15 libsrv 4.12.16 libsys 4.12.17 libtsk Appendix A 2005 .plan A.1 Complete rewrite A.2 Technologies A.2.1 Script + standard C + assembly A.2.2 OpenGL A.2.3 CSound A.3 Functionnalities A.3.1 Visual enhancements A.3.2 Rules enhancements A.3.3 Hey, you forgot my idea!!! A.4 Road map Appendix B Fanfic B.1 The Battle of Emberlificoted Appendix C GNU GENERAL PUBLIC LICENSE Appendix D GNU Free Documentation License D.1 ADDENDUM: How to use this License for your documents 1 Introduction ************** Read this chapter to discover Liquid War 6. 1.1 In a nutshell ================= Liquid War 6 is a unique multiplayer wargame. Your army is a blob of liquid and you have to try and eat your opponents. Rules are very simple yet original, they have been invented by Thomas Colcombet. It is possible to play alone against the computer but the game is really designed to be played with friends, on a single computer, on a LAN, or on Internet. An older version, Liquid War 5 (http://www.ufoot.org/liquidwar/v5), is available, but is not part of the GNU Project. Only Liquid War 6 is part of the GNU Project (http://www.gnu.org/), it is a complete rewrite. Yor more information, you can read the Wikipedia article (http://en.wikipedia.org/wiki/Liquid_War) about Liquid War. 1.2 Project status ================== As of today, the game is in beta state. It can be installed, and you can toy arround with, but it's far from being complete. What works: * The whole framework is here, some functions are not implemented yet, but the bases are set up, and they are believed solid. The game is very modular, it is designed so that graphics, sound and network backends can be hacked at will. * Documentation. Yes, you're reading it. * Demo-style game. It's possible to launch the game and play against a (very) dumb bot. No human vs human yet. * Maps. A number of interesting maps have already been designed (thanks to Kasper Hviid). In the near future: * Complete solo/local game. The idea is to provide correct gameplay in a local context, wether between friends or against the computer. * Network gaming. In the long run: * Port the game to other platforms. Current version runs on GNU/Linux. * Write new graphical backends so that the game does not require Mesa or any OpenGL-like subsystem. The idea is to get rid of the 3D-accelerator dependency. * Implement all the fancy 3D features, make it possible to play Liquid War 6 on a Moebius ring. * Use the cool features of CSound to provide dynamic, contextualized sounds & musics. * Optimize the bot algorithm, which is probably a complex AI problem. 1.3 How you can help ==================== 1.3.1 Help GNU -------------- Please remember that development of Liquid War 6 is a volunteer effort, and you can also contribute to its development. For information about contributing to the GNU Project, please read How to help GNU (http://www.gnu.org/help/help.html). 1.3.2 Todo list --------------- Here's a short list of todo items. It is probably too early to start hacking the core engine itself, for it is still under heavy development, might undergo major rewrites, and it's hard for documentation to keep up with the reality of the code. However, there are still many things to do. * Write maps. Obviously, this is something which can perfectly be delegated. Experience shows user-contributed maps are, on average, better than maps conceived by the author... * Port the game to Microsoft Windows and/or Mac OS/X. * Translate texts. Liquid War 6 uses GNU gettext, so all messages can be translated. * Install the game, test it, and report bugs. This can seem obvious, but without bug-reports, bugs don't get fixed. * ...any help is welcome. Feel free to join the mailing-lists or contact Christian Mauduit (mailto:ufoot@ufoot.org) if you are interested. 2 User's manual *************** The Liquid War 6 user's manual hopefully contains any usefull information to install the program and play the game. If you just want to enjoy Liquid War 6 without diving into map creation and programming, this is just for you. 2.1 Mailing lists ================= 2.1.1 General discussion ------------------------ The main discussion list is (mailto:help-liquidwar6@gnu.org), and is used to discuss all aspects of Liquid War 6, including installation, development, game strategies, and whatever subject players and hackers might want to talk about, provided it is Liquid War 6 related. If you don't know on which list to subscribe, this is the one. To subscribe to it, please send an empty mail with a Subject: header line of just "subscribe" to the `-request' list, that is (mailto:help-liquidwar6-request@gnu.org). You can also subscribe to the list using the Mailman web interface for help-liquidwar6 (http://lists.gnu.org/mailman/listinfo/help-liquidwar6) and consult help-liquidwar6 archives (http://lists.gnu.org/archive/html/help-liquidwar6/). 2.1.2 Announcements ------------------- Announcements about LiquidWar 6 are made on (mailto:info-liquidwar6@gnu.org). Subscribe to it to be informed of major releases, and other significant news. To subscribe to it, please send an empty mail with a Subject: header line of just "subscribe" to the `-request' list, that is (mailto:info-liquidwar6-request@gnu.org). You can also subscribe to the list using the Mailman web interface for info-liquidwar6 (http://lists.gnu.org/mailman/listinfo/info-liquidwar6) and consult info-liquidwar6 archives (http://lists.gnu.org/archive/html/info-liquidwar6/). Please also consider reading the latest news on Savannah (http://savannah.gnu.org/news/?group=liquidwar6). 2.1.3 Bugs ---------- There is also a special list used for reporting bugs, (mailto:bug-liquidwar6@gnu.org). Please try and describe the bug as precisely as possible. The more accurate the description, the more chances it will get to be fixed. While this is the standard GNU way of reporting bugs, modern SPAM standards make it very hard to filter real bug reports from junk on this list. It is more convenient to report bugs on Savannah (https://savannah.gnu.org/bugs/?func=additem&group=liquidwar6) using a web interface. 2.2 Getting the game ==================== 2.2.1 Download source --------------------- Liquid War 6 can be found on `http://download.savannah.gnu.org/releases/liquidwar6/'. Downloading the latest file from this place, and compile it yourself on your computer with a classical `./configure && make && make install' is the recommended way to install Liquid War 6. Latest work in progress versions can be obtained with GNU Arch. Here's a typical set of commands which will fetch the latest version: tla register-archive http://arch.sv.gnu.org/archives/liquidwar6 tla get -A liquidwar6@sv.gnu.org liquidwar6--beta 2.2.2 Download binaries ----------------------- Some binary packages are available. As of today, only GNU/Linux based systems are supported, through Debian (http://www.debian.org/) `.deb' and Red Hat (http://www.redhat.com/) `RPM' packages. Using these files might save you time installing the game, but installing from source is still the safest and best supported way to install the game, as it is still in beta stage. Binary are also not necessarly available for the latest, most up to date versions of the game. The list of all the available downloads is accessible on `http://www.ufoot.org/liquidwar/v6/download'. Check out the MD5 checksums and GnuPG signatures to verify the integrity and authenticity of the files you download. 2.3 Installation ================ This section covers installation from source. Other ways of installing the program are not described here. 2.3.1 Requirements ------------------ All these libraries are mandatory to compile the game. Liquid War 6 won't compile, let alone run, without them. Some of them could probably be replaced by equivalent tools, but this would certainly require a programming effort and some changes in Liquid War 6 source code. * GNU Make (http://www.gnu.org/software/make/). Liquid War 6 might and certainly does use GNU Make extensions. * GNU C library (http://www.gnu.org/software/libc/). Sounds obvious, but you need a standard C library. It happens that glibc has some rather usefull extensions (yes, as of 2006, some vendors continue to offer C libraries without `snprintf'...) and Liquid War 6 might use them. In a general manner, Liquid War 6 is part of and designed for GNU. * Perl (http://www.perl.com/). Some Makefile commands require Perl. You don't need any Perl devel packages, and you can probably use any Perl 5.x version, since no fancy recent feature of Perl is used. Just plain Perl. * Guile (http://www.gnu.org/software/guile/). Possibly the most required library, since Liquid War 6 is a scheme program which uses a set of functions coded in standard C. You need at least Guile 1.8. * GNU MP (http://gmplib.org/). GMP is a free library for arbitrary precision arithmetic, required by Guile. * ltdl (http://www.gnu.org/software/libtool/). This library, which comes with libtool, provides a portable alternative to `dlopen' and `dlclose'. Check that you have a `/usr/include/ltdl.h' file, or install the corresponding package. * zlib (http://www.zlib.net/). Required by other libraries, but can also be used directly by Liquid War 6 to compress network messages for instance. * expat (http://www.libexpat.org/). Used to read and write XML files, which contain constants and configuration data. * ncurses (http://www.gnu.org/software/ncurses/). Required by readline, needs to be there otherwise readline might not be detected properly on some systems. * GNU readline (http://cnswww.cns.cwru.edu/php/chet/readline/rltop.html). Used to handle input on the console. A simple hack could probably make this dependency optional, but readline is so convenient it might be even better to have it mandatory, the way it is now. * libpng (http://www.libpng.org/pub/png/libpng.html). Liquid War 6 uses libpng to read levels (maps), not to speak of other optional libraries (SDL and the rest) who need it themselves. * libjpeg (http://www.ijg.org/). Maps can also be provided as jpeg files, so libjpeg is required as well. * SQLite 3 (http://www.sqlite.org). Used to handle the list of available servers. 2.3.2 Optional libraries ------------------------ While all these libraries are theorically optional (the game will successfully compile without them), you'll obviously need, for instance, one graphics backend. Otherwise, you'll simply have no display. This is not acceptable. As of today, one can reasonnably consider all SDL-related libraries are required. The rest is truely optional. * Mesa (http://www.mesa3d.org/). This library provides an API similar to OpenGL and enables 2-D and 3-D drawing. * SDL (http://www.libsdl.org/). SDL is used to set up a working OpenGL environnement, and handle input (mouse and keyboard). * SDL_image (http://www.libsdl.org/projects/SDL_image/). This SDL extension is used to read textures and other graphics from disk. * SDL_ttf (http://www.libsdl.org/projects/SDL_ttf/). This SDL extension is used to draw fonts. It is UTF-8 enabled. * libcsound (http://www.csounds.com/). While this tool is not used yet, it is meant to be the final sound backend, as CSounds offers great power to the composer, enabling truely dynamically generated sound & music. * SDL_mixer (http://www.libsdl.org/projects/SDL_mixer/). This SDL extension is used to allow dynamic mixing of sounds, and it also provides a builtin `OGG/Vorbis' file renderer. * libcURL (http://curl.haxx.se/libcurl/). Used to handle HTTP requests, the idea being not to re-invent the wheel but use a robust standards-compliant generic library. 2.3.3 Compiling --------------- Liquid War 6 uses GNU Automake (http://www.gnu.org/software/automake/), Autoconf (http://www.gnu.org/software/autoconf/) and GNU Libtool (http://www.gnu.org/software/libtool/). Once the requirements and optional libraries are installed on your system, run: ./configure make make install Liquid War 6 supports the standard `./configure --prefix=' option (in fact, it supports much more than that) so you can install the game in any directory. 2.4 Troubleshooting =================== 2.4.1 Compilation problems -------------------------- A quick survival guide: * Check that you have all dependencies installed. Also check their version number. Double-check that you have devel packages installed, not only run-time binaries. * Read carefully the output of `./configure'. * Editing `/etc/ld.so.conf' and running `ldconfig' as `root' can help if some dependencies are installed in exotic places. * Check the values of the environment variables `CFLAGS', `LDFLAGS' and `LD_LIBRARY_PATH'. If none of these help, consider reporting a bug, or search the mailing-lists for help. 2.4.2 Check installation ------------------------ Here's a check-list to ensure that your installation is correct: * What was the output of `make install'? * Is the `liquidwar6' binary in your `PATH'? It might be in `/usr/games'. * Run `liquidwar6 --pedigree'. Look at the output. Check the compilation date & time, the prefix, the version number. * Run `liquidwar6 --show-map-dir' and `liquidwar6 --show-mod-dir'. What does it show? Are these absolute paths? Do they exist? What's there? Normally, they should be paths which contain the version number, and be populated with sub-directories and files. 2.4.3 Problems running the game ------------------------------- Now, game looks correctly installed, but you have problems running it. * Run the game from a terminal, not from a Gnome or KDE launcher, you need to see the console output. * Run `liquidwar6 --defaults'. This will reset all options to defaults. * Run `liquidwar6 --test'. This should run a complete test suite, many functions in the game will be tested automatically, and errors reported. * Run `liquidwar6 --show-script-file'. Are you really running the right code? * Game segfaults: try `make uninstall && make clean && make && make install'. Many problems can come from using a wrong shared module, especially with beta versions. * Game (still) segfaults: try `gdb liquidwar6'. Type `run' and watch output. * The dynamic library loader can sometimes have problemes, and does not always report explicit messages on `stdout' or `stderr'. You can change this by modifying some environment variables: `export LD_DEBUG=all'. This is very verbose but does help finding bugs. * Consider compiling the game using `./configure --enable-valgrind' and then run it using Valgrind (http://valgrind.org/). * In the `$HOME/.liquidwar6/' directory, you'll find two files, `log.csv' and `dump.txt'. They might contain valuable information, read them. * Try `find / -type d -a -name "liquidwar6*" 2> /dev/null' to ensure you don't have an old version of Liquid War 6 somewhere else... 2.5 How to play =============== 2.6 Strategy tips ================= 2.7 User interface ================== 2.8 Network games ================= 2.9 Graphics ============ 2.10 Sound & music ================== 2.11 Config file ================ 2.12 Logs ========= 2.13 Report bugs ================ 3 Hacker's guide **************** This hacker's guide is for anyone who is curious about the game, and wants to know how it works. It covers many aspects from simple map creation to technical program internals. A great effort has been done in Liquid War 6 so that it should be much more hackable than previous versions. Any feedback is welcome. 3.1 Designing levels ==================== 3.2 Architecture ================ 3.3 About mod-gl ================ 3.4 Compilation tips ==================== 3.5 Coding guidelines ===================== 3.6 Using the console ===================== 3.7 Advanced tweaking ===================== 3.8 Writing modules =================== 3.9 Use as a library ==================== 3.10 Network protocol ===================== 3.11 Using GNU Arch =================== 4 Reference *********** This chapter is a technical reference. Most of its content is self-generated by the program itself. That is to say, most if its content is already available to you if you have the game installed. Running `liquidwar6 --list' and `liquidwar6 --about=' is very likely to give you the very same informations, the advantage being that you'll be sure the information is up-to-date and corresponds to the exact version of the program you have. However, publishing this in a reader-friendly way is convenient, plus it enables web search engines to harvest the content. 4.1 Basic options ================= -- Command-line option: -about= Will allow you to get informations about a given keyword. Let's say that, for instance, you want informations about the keyword 'map-path'. Simply run 'liquidwar6 -about=map-path'. Note that this internal self-documentation system can describe command line switches as well as XML config file parameters or environment variables, and even some Guile script functions. The '-list' command line switch will give you the list of all available keywords. -- Command-line option: -copyright Returns the copyright notice for the program. -- Command-line option: -defaults Clears the config file and run the game with default settings. The difference with '-reset' is that '-defaults' runs the game, while '-reset' does not. -- Command-line option: -help Returns a short help for the program. -- Command-line option: -list Returns the list of all keywords which can be queried for information. This includes command-line options, environment variables, and so on. This is the companion option of '-about'. Results obtained with '-list' can be passed to '-about'. -- Command-line option: -pedigree Display all build values, these are general constants which can help debugging, tracing what binary you are running, and so on. It's a good idea to take a look at the output of 'pedigree' if you have problems running the game. -- Command-line option: -reset Clears the config file so that the game will run with defaults next time. The idea is to get rid of traces of previous executions. -- Command-line option: -test Runs a (hopefully) complete test suite which will call most internal Liquid War 6 functions and check out wether they work, in a simple context, without any game interference. Usefull for troubleshooting. -- Command-line option: -version Returns the version of the program, as defined by the GNU Coding Standards. 4.2 Doc options =============== -- Command-line option: -example-options-xml Dumps on stdout an example options.xml file. Such a file is normally shipped with the game. It is indeed generated using this command. -- Command-line option: -example-style-xml Dumps on stdout an example style.xml file. Such a file is normally shipped with the game. It is indeed generated using this command. -- Command-line option: -list-aliases List the keyword aliases. These are here for convenience. -- Command-line option: -list-doc List documentation-related command line options. These commands allow you to list all the keywords related to a given domain. -- Command-line option: -list-funcs List the C-functions which are exported to Guile, thus usable in scripts. -- Command-line option: -list-graphics List graphics options (resolution, fullscreen...). -- Command-line option: -list-hooks List user-modifiable hooks. -- Command-line option: -list-input List input (AKA controls) related options. Use these to change keyboard, joystick and mouse settingds. -- Command-line option: -list-map List map-related entries, excluding options.xml and style.xml entries. -- Command-line option: -list-map-options List 'options.xml' entries. These parameters enable you to modify the gameplay. -- Command-line option: -list-map-style List 'style.xml' entries. These parameters enable you to modify the aspect of the game. -- Command-line option: -list-network List network options. -- Command-line option: -list-path List parameters which allow you to override the defaults of the game, and force the game your own file paths and directories. -- Command-line option: -list-players List player-related entries, that is to say 'who plays'. -- Command-line option: -list-quick List quick help entries, this includes the GNU standard options and a few troubleshooting tools. -- Command-line option: -list-show List command-line options which will display on the console many internal parameters. Usefull when debugging. -- Command-line option: -list-sound List sound options (volume...). -- Command-line option: -list-tuning List advanced options which can be used for fine-tuning the game. 4.3 Show options ================ -- Command-line option: -show-build-cflags Shows what value you should put in 'CFLAGS' (environment variable) if you want to compile programs that use Liquid War 6 as a library, and include 'liquidwar6.h'. -- Command-line option: -show-build-codename Shows the codename associated with this version, generally the name of someone famous who is war-related (a general, an emperor...). -- Command-line option: -show-build-configure-args Shows the arguments that have been passed to the GNU Autoconf './configure' script when building the program. This can be very usefull if you want to know how the program has been built. -- Command-line option: -show-build-copyright Shows a very short copyright notice. -- Command-line option: -show-build-datadir Shows the 'datadir' value as passed to the GNU Autoconf './configure' script when compiling the program. Default is '/usr/local/share'. This is the generic, non Liquid War 6 specific data directory. Liquid War 6 related data is stored elsewhere (usually in a sub-directory), see the 'data-dir' switch for more information. 'datadir' is not 'data-dir'. That's the point. -- Command-line option: -show-build-date Shows the date when the binary was compiled. -- Command-line option: -show-build-docdir Shows the 'docdir' value as passed to the GNU Autoconf './configure' script when compiling the program. Default is '/usr/local/share/doc/liquidwar6'. -- Command-line option: -show-build-hostname Shows the name of the host where the binary was compiled. -- Command-line option: -show-build-includedir Shows the 'includedir' value as passed to the GNU Autoconf './configure' script when compiling the program. Default is '/usr/local/include'. -- Command-line option: -show-build-ldflags Shows what value you should put in 'LDFLAGS' (environment variable) if you want to link programs against libliquidwar6. -- Command-line option: -show-build-libdir Shows the 'libdir' value as passed to the GNU Autoconf './configure' script when compiling the program. Default is '/usr/local/lib'. This is the generic, non Liquid War 6 specific library directory. Dedicated Liquid War 6 modules are stored elsewhere (usually in a sub-directory), see the 'mod-dir' switch for more information. -- Command-line option: -show-build-license Shows the license of the program (GNU GPL v3 or later). -- Command-line option: -show-build-localedir Shows the 'localedir' value as passed to the GNU Autoconf './configure' script when compiling the program. Default is '/usr/local/share/locale'. -- Command-line option: -show-build-md5sum Shows the MD5 checksum, which has been calculated from the C source files. Complementary with 'show-build-stamp'. -- Command-line option: -show-build-package-name Shows the package name, that is, 'Liquid War 6'. -- Command-line option: -show-build-package-string Shows the package string, that is, 'Liquid War 6 -- Command-line option: -show-build-package-tarname Shows the package tarname, that is, liquidwar6. -- Command-line option: -show-build-prefix Shows the 'prefix' value as passed to the GNU Autoconf './configure' script when compiling the program. Default is '/usr/local'. -- Command-line option: -show-build-stamp Shows the build stamp. A very usefull value, more precise than the version to track down binaries. It is incremented each time the core C code is updated. It won't reflect all the programs for it does not take scripts in account, but if you are running a work-in-progress version, it might be very convenient to use this to know what your are running exactly. -- Command-line option: -show-build-target-cpu Shows the target CPU, as defined by 'target_cpu' in GNU Autoconf. -- Command-line option: -show-build-target-os Shows the target OS, as defined by 'target_os' in GNU Autoconf. -- Command-line option: -show-build-time Shows the time when the binary was compiled. -- Command-line option: -show-build-top-srcdir Shows the top source directory on the machine where the binary was compiled. -- Command-line option: -show-build-version Shows the version. Note that this is different from the standard GNU 'version' command line option which shows a complete message with a short copyright notice. This one will just return the version, without the package tarname or anything else. -- Command-line option: -show-config-file Shows the config file path. Default is '$HOME/.liquidwar6/config.xml'. -- Command-line option: -show-data-dir Shows the data directory path. This is where the games searches for most of its data,the most important exception being maps, which are stored elsewhere. Default is '/usr/local/share/liquidwar6-/data'. -- Command-line option: -show-default-config-file Shows the default config file path. Default is '$HOME/.liquidwar6/config.xml'. -- Command-line option: -show-default-data-dir Shows the default data directory path. This is where the games searches for most of its data,the most important exception being maps, which are stored elsewhere. Default is '/usr/local/share/liquidwar6-/data'. -- Command-line option: -show-default-log-file Shows the default log file path. Default is '$HOME/.liquidwar6/log.csv'. -- Command-line option: -show-default-map-dir Shows the default map directory. This is where builtin maps are stored. Default is '/usr/local/share/liquidwar6-/map'. -- Command-line option: -show-default-map-path Shows the default map search path. This is where the game searches for maps. It's the combination of command-line arguments and builtin paths. Might return more directories than the one specified in a single 'map-path=dir1:dir2' argument. -- Command-line option: -show-default-mod-dir Shows the default module directory path. This is where all dynamically loaded modules are stored. Default is '/usr/local/lib/liquidwar6-'. -- Command-line option: -show-default-prefix Shows the default prefix used. This should logically be the value passed to the GNU Autoconf ./configure script when building the game. Most other path are deduced from this one. Default is '/usr/local'. -- Command-line option: -show-default-script-file Shows the default main script file path. This file is very important, since the program is more or less a hudge scheme interpreter, and this file is the file loaded by Guile. In short, it is the main program. Default is '/usr/local/share/liquidwar6-/script/liquidwar6.scm'. -- Command-line option: -show-default-user-dir Shows the default user directory path. This is where run-time data, config files, log files, are stored. Default is '$HOME/.liquidwar6/'. -- Command-line option: -show-log-file Shows the log file path. Default is '$HOME/.liquidwar6/log.csv'. -- Command-line option: -show-map-dir Shows the map directory. This is where builtin maps are stored. Default is '/usr/local/share/liquidwar6-/map'. -- Command-line option: -show-map-path Shows the map search path. This is where the game searches for maps. It's the combination of command-line arguments and builtin paths. Might return more directories than the one specified in a single 'map-path=dir1:dir2' argument. -- Command-line option: -show-mod-dir Shows the module directory path. This is where all dynamically loaded modules are stored. Default is '/usr/local/lib/liquidwar6-'. -- Command-line option: -show-prefix Shows the prefix used. This should logically be the value passed to the GNU Autoconf ./configure script when building the game. Most other path are deduced from this one. Default is '/usr/local'. -- Command-line option: -show-script-file Shows the main script file path. This file is very important, since the program is more or less a hudge scheme interpreter, and this file is the file loaded by Guile. In short, it is the main program. Default is '/usr/local/share/liquidwar6-/script/liquidwar6.scm'. -- Command-line option: -show-user-dir Shows the user directory path. This is where run-time data, config files, log files, are stored. Default is '$HOME/.liquidwar6/'. 4.4 Path options ================ -- Command-line option: -config-file= -- Environment variable: LW6_CONFIG_FILE Set the config file path. This enables you to use whatever config file you like, keeping all other informations in the same place. Default is '$HOME/.liquidwar6/config.xml'. -- Command-line option: -data-dir= -- Environment variable: LW6_DATA_DIR Set the data directory. By changing ths value you'll be able to use an alternative data directory. Default is '/usr/local/share/liquidwar6-/data'. -- Command-line option: -log-file= -- Environment variable: LW6_LOG_FILE -- XML key: log-file Set the log file path. This enables you to use whatever log file you like, keeping all other informations in the same place. Default is '$HOME/.liquidwar6/log.csv'. -- Command-line option: -map-dir= -- Environment variable: LW6_MAP_DIR Set the map directory path. By changing this value you'll be able to play with your own maps in your own directory. Note that there are other ways to achieve that, but using this option will work. However, a side effect is that you might not see builtin maps anymore. Default is '/usr/local/share/liquidwar6-/map'. -- Command-line option: -map-path= -- Environment variable: LW6_MAP_PATH -- XML key: map-path Set the map search path. By changing this value you'll be able to play with your own maps in your own directory. This is different from 'map-dir', since it includes 'map-dir', plus it adds a number of other search paths. Unlike most other parameters, the values given from the command-line, from the environment variables, or from the config file, are not overwritten, but appended. That is to say if you specify a 'map-path' with the command-line argument 'map-path=path', but also define the 'LW6_MAP_PATH' value and finally edit 'config.xml' to change the 'map-path' entry in it, you'll end up with the game searching for maps in all these directories. Additionnally, 'map-dir' and '/map' will always be in the list. Any given value can itself include several pathes, separated by the path separator. This separator is ':' on GNU/Linux, and ';' on Microsoft Windows. For instance, on a GNU/Linux box, you could use the command-line argument 'map-path=/foo/bar/map:/home/user/map/:/map'. -- Command-line option: -mod-dir= -- Environment variable: LW6_MOD_DIR Set the module directory path. By changing this you will load dynamic shared libraries (game specific modules such as the graphical backend) from an alternative place. Use this at your own risks, for there can always be a binary incompatibility. You've been warned. Default is '/usr/local/lib/liquidwar6-'. -- Command-line option: -prefix= -- Environment variable: LW6_PREFIX Override the prefix value given to the GNU Autoconf ./configure script when building the game. Not all path will be changed, some of them might remain the same, for instance message translations (localedir). But most game-specific data including maps, graphics, sounds, will be searched according to the new given parameter. Default is '/usr/local'. -- Command-line option: -script-file= -- Environment variable: LW6_SCRIPT_FILE Set the main script file path. This file is very important, since the program is more or less a hudge scheme interpreter, and this file is the file loaded by Guile. In short, it is the main program. Default is '/usr/local/share/liquidwar6-/script/liquidwar6.scm'. -- Command-line option: -user-dir= -- Environment variable: LW6_USER_DIR -- XML key: user-dir Set the user directory path. This is where run-time data, config files, log files, are stored. If you override this value, other parameters such as where the config and log files reside, will change. Default is '$HOME/.liquidwar6'. 4.5 Graphics options ==================== -- Command-line option: -display-fps= -- Environment variable: LW6_DISPLAY_FPS -- XML key: display-fps Set this to 'true' to display the number of frames per second. When this gets too low... play a smaller map, buy a new computer or contribute and hack Liquid War 6 so that it runs faster! -- Command-line option: -fullscreen= -- Environment variable: LW6_FULLSCREEN -- XML key: fullscreen Force the game to fun fullscreen. Note that the graphics backend might ignore this hint. -- Command-line option: -height= -- Environment variable: LW6_HEIGHT -- XML key: height Run the game with the given screen height.Note that the graphics backend might ignore this hint.Use with its companion option 'width'. -- Command-line option: -width= -- Environment variable: LW6_WIDTH -- XML key: width Run the game with the given screen width. Note that the graphics backend might ignore this hint.Use with its companion option 'height'. 4.6 Sound options ================= -- Command-line option: -music-volume= -- Environment variable: LW6_MUSIC_VOLUME -- XML key: music-volume Set the music volume.This is a floating point value.0 is mute.Maximum value is 1. -- Command-line option: -sound-volume= -- Environment variable: LW6_SOUND_VOLUME -- XML key: sound-volume Set the sound volume.This is a floating point value.0 is mute.Maximum value is 1. 4.7 Network options =================== 4.8 Map parameters ================== 4.8.1 Choosing the map ---------------------- -- Command-line option: -chosen-map= -- Environment variable: LW6_CHOSEN_MAP -- XML key: chosen-map The last map chosen by the player, locally. This is the map which will be used for a quick-start game, a local game, or a game started as a server. 4.8.2 Map options (options.xml) ------------------------------- -- Command-line option: -bot-nb-move-steps= -- Environment variable: LW6_BOT_NB_MOVE_STEPS -- XML key: bot-nb-move-steps How many steps a bot move will take. This means, once the bot has chosen a direction, in how many rounds it will go there. Probably a temporary parameter until clever bot behavior is implemented. -- Command-line option: -bot-wait-between-moves= -- Environment variable: LW6_BOT_WAIT_BETWEEN_MOVES -- XML key: bot-wait-between-moves How many rounds a bot will wait before chosing a different destination. Probably a temporary parameter until clever bot behavior is implemented. -- Command-line option: -cursor-pot-init= -- Environment variable: LW6_CURSOR_POT_INIT -- XML key: cursor-pot-init Defines the cursor potential at startup. Not really any reason to change it. Theorically, there could be maps where the default value doesn't fit, but none has been seen yet. -- Command-line option: -fighter-attack= -- Environment variable: LW6_FIGHTER_ATTACK -- XML key: fighter-attack Defines how hard fighters will attack others, that is, in one attack, how many life-points the attacked fighter will loose. Increasing this will cause your opponents to melt faster when you attack them. With a low value, it will take ages to take on your opponents. Different styles of game. Can radically change the gameplay. -- Command-line option: -fighter-defense= -- Environment variable: LW6_FIGHTER_DEFENSE -- XML key: fighter-defense Defines how fast fighters will regenerate after an attack. When this parameter is set low, an attacked fighter, which is very dark and almost dead will take a very long time to regain energy. If the parameter is set high, it can almost instantaneously regain energy. -- Command-line option: -fighter-new-health= -- Environment variable: LW6_FIGHTER_NEW_HEALTH -- XML key: fighter-new-health Defines how healthy fighters will be when they appear on the map. This can be either at the beginning of the game of when a fighter changes team. Setting this low will allow battefields to switch from one side to another very fast, for freshly gained fighters will be feeble and very likely to return to their original camp. -- Command-line option: -max-cursor-pot= -- Environment variable: LW6_MAX_CURSOR_POT -- XML key: max-cursor-pot Defines the maximum cursor potential. Not really any reason to change it. Any high value should produce the same results. Low values might reveal algorithm bugs and inconsistencies. -- Command-line option: -max-cursor-pot-offset= -- Environment variable: LW6_MAX_CURSOR_POT_OFFSET -- XML key: max-cursor-pot-offset Defines the maximum cursor potential offset. The idea is that in some cases, the potential of a cursor can increase in burst mode, for instance to make this cursor more important than others, so that fighters rally to it, neglecting other cursors (talking about a multi-cursor controlled team). This parameter is here to limit this burst effect and avoid bugs. -- Command-line option: -max-map-height= -- Environment variable: LW6_MAX_MAP_HEIGHT -- XML key: max-map-height Allows you to give a maximum map height. When designing a map you might wonder: this is dumb I'm conceiving this map I know its height, why should I limit it? Now think of the play who plays on a old slowish computer with a tiny screen. He might redefine this himself, and does not necessarly wishes to fire Gimp to rescale the map. -- Command-line option: -max-map-surface= -- Environment variable: LW6_MAX_MAP_SURFACE -- XML key: max-map-surface Allows you to give a maximum map surface. Map surface is simply (width * height). This parameter is just here to save you the hassle of defining both 'max-map-width' and 'max-map-height' in a consistent manner. -- Command-line option: -max-map-width= -- Environment variable: LW6_MAX_MAP_WIDTH -- XML key: max-map-width Allows you to give a maximum map width. When designing a map you might wonder: this is dumb I'm conceiving this map I know its width, why should I limit it? Now think of the play who plays on a old slowish computer with a tiny screen. He might redefine this himself, and does not necessarly wishes to fire Gimp to rescale the map. -- Command-line option: -max-nb-teams= -- Environment variable: LW6_MAX_NB_TEAMS -- XML key: max-nb-teams Defines the maximum number of teams who can enter the game. Really makes sense in network games. Default value should fit for most cases. -- Command-line option: -max-round-delta= -- Environment variable: LW6_MAX_ROUND_DELTA -- XML key: max-round-delta This is the companion value of 'round-delta'. Will put an absolute limit to the delta, which (what did you think?) is of course incremented in some cases by the core algorithm. If in doubt, don't touch. -- Command-line option: -max-zone-size= -- Environment variable: LW6_MAX_ZONE_SIZE -- XML key: max-zone-size Defines the maximum zone size, which is an internal and rather technical parameter. The idea is that to optimize things, Liquid War 6 divides the battlefield in squares, where it can, and tries to make these squares as big as possible, the idea being that everywhere in this square, fighters follow the same intructions. Just a technical optimization. The problem is that setting it too high will reveal the optimization and its tradeoffs to the player, who will see the fighter behave strangely, following invisible paths. Plus, it's ugly. Depending on your tastes (speed, look'n'feel) you'll prefer something nice or something fast. Note that anyways passed a certain value, this does not optimize anything anymore. In doubt, don't touch it. -- Command-line option: -min-map-height= -- Environment variable: LW6_MIN_MAP_HEIGHT -- XML key: min-map-height Allows you to give a minimum map height. When designing a map you might wonder: this is dumb I'm conceiving this map I know its height, why should I limit it? Now think of the player who decided to play with highly-defined maps because he has a super calculator and a hudge screen. He might redefine this himself, and does not necessarly wishes to fire Gimp to rescale the map. -- Command-line option: -min-map-surface= -- Environment variable: LW6_MIN_MAP_SURFACE -- XML key: min-map-surface Allows you to give a minimum map surface. Map surface is simply (width * height). This parameter is just here to save you the hassle of defining both 'min-map-width' and 'min-map-height' in a consistent manner. -- Command-line option: -min-map-width= -- Environment variable: LW6_MIN_MAP_WIDTH -- XML key: min-map-width Allows you to give a minimum map width. When designing a map you might wonder: this is dumb I'm conceiving this map I know its width, why should I limit it? Now think of the player who decided to play with highly-defined maps because he has a super calculator and a hudge screen. He might redefine this himself, and does not necessarly wishes to fire Gimp to rescale the map. -- Command-line option: -moves-per-round= -- Environment variable: LW6_MOVES_PER_ROUND -- XML key: moves-per-round Defines how many times fighters move per round. Increasing this will just make fighters move faster, but won't change anything for the rest, that is keyboard and mouse responsivity, and network traffic will stay the same. Multiplying the number of moves per round by the number of rounds per second will give the number of moves per second, which is, in fact, how fast fighters move on the screen. -- Command-line option: -nb-attack-tries= -- Environment variable: LW6_NB_ATTACK_TRIES -- XML key: nb-attack-tries Defines how many tries a fighter will do before giving-up attacking and choosing another behvior (defense). By tries we mean: how many directions it will try. Going North? Going North-West? Setting this to a low value will make fighters somewhat less aggressive. This idea is that they'll prefer to switch to the next option, that is, defense/regeneration, if there's no opponent right in front of them. -- Command-line option: -nb-defense-tries= -- Environment variable: LW6_NB_DEFENSE_TRIES -- XML key: nb-defense-tries Defines how many tries a fighter will do before giving-up attacking and choosing another behavior (do nothing). By tries we mean: how many directions it will try. Going North? Going North-West? Setting this to a low value, you'll need a very compact pack of fighters for regeneration to operate, else fighters will hang arround unhealthy. -- Command-line option: -nb-move-tries= -- Environment variable: LW6_NB_MOVE_TRIES -- XML key: nb-move-tries Defines how many tries a fighter will do before giving-up moving and choosing another behvior (attack or defense). By tries we mean: how many directions it will try. Going North? Going North-West? Setting this to a low value, your fighters will look very stubborn and always try to move in one direction, neglecting the fact that they could dodge. This can lead to queues of fighters and other strange behaviors. On the other hand, setting it too high will cause fighter to always avoid the enemy, and groups of fighters will just pass each other without any fight. Matter of taste. -- Command-line option: -respawn-team= -- Environment variable: LW6_RESPAWN_TEAM -- XML key: respawn-team Defines what to do when a team dies. If set to 0, team disappears forever, if set to 1, team reappears automatically with fresh fighters. It's a deathmatch mode, where the winner is not the one who stays alive the longest time, since it makes no real sens in this case, but the one who has died less often than others. -- Command-line option: -round-delta= -- Environment variable: LW6_ROUND_DELTA -- XML key: round-delta Conditions by how much the cursor potential will be incremented each time gradient is spreaded. Sounds cryptic? It is. The idea is that at each time you move your cursor of 1 pixel, theorically, you'll need in the worst case to move of 1 more pixel to reach any point on the map. Of course this is not true but this is the default asumption, and gradient spread will fix that. Only in Liquid War 6 this is not even the worst case, for you can control your cursor with the mouse and cross walls. Whenever you cross a wall, you might have done a great distance from the fighters' point of view, if the map is a maze. Thus this parameter, which corrects things, experience shows it does give acceptable results to increase the cursor potential by more than one at each turn. Toy arround with this if you find fighters take wrong paths on some given map. If in doubt, don't touch. -- Command-line option: -rounds-per-sec= -- Environment variable: LW6_ROUNDS_PER_SEC -- XML key: rounds-per-sec Defines the overall speed of the game. All other settings being equal, raising this value will cause the game to behave faster. Everything will be faster, except probably the display since your computer will calculate more game positions in a given time and spend more CPU time. It will also increase network traffic. Values between 10 and 50 really make sense. -- Command-line option: -side-attack-factor= -- Environment variable: LW6_SIDE_ATTACK_FACTOR -- XML key: side-attack-factor Defines how hard fighters will attack sideways. It's an algorithm trick, fighters attack by default the opponent right in front, but if there's no fighter there, they will still try to attack someone else, maybe sideways. But doing this their attack is not as strong. This parameter enables you to tune this. This is a percentage. -- Command-line option: -side-defense-factor= -- Environment variable: LW6_SIDE_DEFENSE_FACTOR -- XML key: side-defense-factor Defines how fast fighters will regenerate, when being side by side instead of being right in front of the other. This is a percentage. -- Command-line option: -single-army-surface= -- Environment variable: LW6_SINGLE_ARMY_SURFACE -- XML key: single-army-surface Defines the proportion of the whole available space, which will be occupied by an army at the beginning of the game. You can either imagine playing with almost empty maps, or play very crowded with almost no space left. This is not a percentage, it's in a per-thousand unit. 1000 means full packed, but since it makes no sense, it's forbidden. -- Command-line option: -spreads-per-round= -- Environment variable: LW6_SPREADS_PER_ROUND -- XML key: spreads-per-round Defines how many times the gradient is spread per round. Gradient spread is a very Liquid War 6 specific feature, just remember that the more often you do it, the more accurately fighters will move. That is, you will be sure they really take the shortest path. Usually this does not have much effect, the default value should fit in most cases, but you might want to decrease it on very simple maps where the gradient is obvious, or increase it on complex maps where you want fighters to be real smart. -- Command-line option: -total-armies-surface= -- Environment variable: LW6_TOTAL_ARMIES_SURFACE -- XML key: total-armies-surface Defines the proportion of the whole available space, which can be occupied by all the armies present together. Setting this low, whenever a new team arrives on the map, fighters might be stolen to other teams, otherwise the ame would get too crowded. This allows you to play with reasonnably enough fighters with 2 players, while still allowing interesting gameplay with many players. This is not a percentage, it's in a per-thousand unit. 1000 means full packed, but since it makes no sense, it's forbidden. -- Command-line option: -total-time= -- Environment variable: LW6_TOTAL_TIME -- XML key: total-time Defines the maximum time of the game, in seconds. Note that in some cases, the game can end much earlier if some player has managed to win before the bell rings. Also, technically, this value will be translated into rounds and moves, and the game engine will wait until enough rounds and moves have been played. So if the computer is too slow and the desired speed is not reached, then the game will last for a longer time. -- Command-line option: -x-polarity= -- Environment variable: LW6_X_POLARITY -- XML key: x-polarity Defines how the map will be wrapped on the X (horizontal) axis. If set to 0, nothing is wrapped. If set to 1, the right and left borders are connected, any fighter can disappear on the right border and reappear on the left border, for instance. If set to -1, it will be wrapped but also inversed, that is on a 320x240 map, a fighter disappearing on the left border at position (0,60) will reapper on the right border at position (319,180). You can combine it with 'y-polarity'. -- Command-line option: -y-polarity= -- Environment variable: LW6_Y_POLARITY -- XML key: y-polarity Defines how the map will be wrapped on the Y (vertical) axis. If set to 0, nothing is wrapped. If set to 1, the top and bottom borders are connected, any fighter can disappear on the top border and reappear on the bottom border, for instance. If set to -1, it will be wrapped but also inversed, that is on a 320x240 map, a fighter disappearing on the bottom border at position (40,239) will reapper on the top border at position (280,0). You can combine it with 'x-polarity'. 4.8.3 Map style (style.xml) --------------------------- -- Command-line option: -background-color-alternate-bg= -- Environment variable: LW6_BACKGROUND_COLOR_ALTERNATE_BG -- XML key: background-color-alternate-bg Defines a color which will be used together with background-color-alternate-fg to draw things (animations, sprites, text, whatever) in the background. It should be different enough from background-color-alternate-fg so that one can really distinguish these colors. Will be automatically guessed from the map texture if background-color-auto is set. Can be #RGB, #RGBA, #RRGGBB or #RRGGBBAA. -- Command-line option: -background-color-alternate-fg= -- Environment variable: LW6_BACKGROUND_COLOR_ALTERNATE_FG -- XML key: background-color-alternate-fg Defines a color which will be used to draw things (animations, sprites, text, whatever) in the background. It should be different enough from background-color-alternate-bg so that one can really distinguish these colors. Think of this as the sprite, the text, the whatever-needs-to-be-seen-uses-this color. Will be automatically guessed from the map texture if background-color-auto is set. Can be #RGB, #RGBA, #RRGGBB or #RRGGBBAA. -- Command-line option: -background-color-auto= -- Environment variable: LW6_BACKGROUND_COLOR_AUTO -- XML key: background-color-auto Defines wether background colors should be set automatically from texture colors. If set to true, then the program will try to pick up colors automatically from the texture, and will override the values of the background-color-base-bg, background-color-base-fg, background-color-alternate-bg and background-color-alternate-fg parameters. How these colors are picked up can't be garanteed, so if the map does not have strong contrast or if there can be any form of ambiguity, it's safe to set this to false and define one's own colors. -- Command-line option: -background-color-base-bg= -- Environment variable: LW6_BACKGROUND_COLOR_BASE_BG -- XML key: background-color-base-bg Defines the main background color. This is, for instance, the color which will be used to clear the screen before drawing thing. Will be automatically guessed from the map texture if background-color-auto is set. Can be #RGB, #RGBA, #RRGGBB or #RRGGBBAA. -- Command-line option: -background-color-base-fg= -- Environment variable: LW6_BACKGROUND_COLOR_BASE_FG -- XML key: background-color-base-fg Defines a color which will be used together with background-color-base-bg to compose the background. It can be wise to have a minimum contrast between this color and background-color-base-bg, but it is not mandatory, especially if other colors are manually redefined. Will be automatically guessed from the map texture if background-color-auto is set. Can be #RGB, #RGBA, #RRGGBB or #RRGGBBAA. -- Command-line option: -background-density= -- Environment variable: LW6_BACKGROUND_DENSITY -- XML key: background-density Density of the background animation, that is, for instance, if the background animation is about displaying bubbles, using a high value will display many bubbles. A value of 1.0 corresponds to the default setting. -- Command-line option: -background-speed= -- Environment variable: LW6_BACKGROUND_SPEED -- XML key: background-speed Speed of the background animation, that is, for instance, if the background animation is about displaying bubbles, using a high value will cause bubbles to move very fast. A value of 1.0 corresponds to the default setting. -- Command-line option: -background-style= -- Environment variable: LW6_BACKGROUND_STYLE -- XML key: background-style The background defines, of course, what is displayed at the background, but it also conditions the colors used for other items, such as the menus for instance. Possible values include 'bubbles', 'air', 'fire', 'earth' and 'void'. -- Command-line option: -fighter-scale= -- Environment variable: LW6_FIGHTER_SCALE -- XML key: fighter-scale Defines how wide (in pixels) fighters must be. This parameter is very important and will largely condition the number of fighters on the map. It is used when loading the map. If it is, for instance, set to 1, there will be exactly a fighter per pixel on the screen. That is, if you play 640x480 on an empty map, the maximum fighters you could have is about 300000. The idea is that by changing the resolution, you also define the density of the map. In pratice, this is done in the hope that someone with a slow computer will pick up a low resolution and therefore play small levels. Conversely, someone with a brand new computer with powerfull CPU & GPU will use great resolutions and be happy with many fighters on the map. Still, changing the resolution after loading the map will not affet the number of fighters. Same for network games, the first player, who loads the map, defines its properties according to its own settings. -- Command-line option: -hud-color-auto= -- Environment variable: LW6_HUD_COLOR_AUTO -- XML key: hud-color-auto Defines wether hud colors will be set automatically from background colors. This is a time saver to keep map designers from requiring to redefined every single color in the game. You only need to set background-color-base-bg, background-color-base-fg, background-color-alternate-bg and background-color-alternate-fg. Then hud_color_frame_bg, hud_color_frame_fg, hud_color_text_bg and hud_color_text_fg will be automatically set. -- Command-line option: -hud-color-frame-bg= -- Environment variable: LW6_HUD_COLOR_FRAME_BG -- XML key: hud-color-frame-bg Defines the background color for the hud frame. Ignored if hud-color-auto is set. Can be #RGB, #RGBA, #RRGGBB or #RRGGBBAA. -- Command-line option: -hud-color-frame-fg= -- Environment variable: LW6_HUD_COLOR_FRAME_FG -- XML key: hud-color-frame-fg Defines the foreground color for the hud frame. Ignored if hud-color-auto is set. Can be #RGB, #RGBA, #RRGGBB or #RRGGBBAA. -- Command-line option: -hud-color-text-bg= -- Environment variable: LW6_HUD_COLOR_TEXT_BG -- XML key: hud-color-text-bg Defines the background color for hud text. Ignored if hud-color-auto is set. Can be #RGB, #RGBA, #RRGGBB or #RRGGBBAA. -- Command-line option: -hud-color-text-fg= -- Environment variable: LW6_HUD_COLOR_TEXT_FG -- XML key: hud-color-text-fg Defines the foreground color for hud text. Ignored if hud-color-auto is set. Can be #RGB, #RGBA, #RRGGBB or #RRGGBBAA. -- Command-line option: -hud-style= -- Environment variable: LW6_HUD_STYLE -- XML key: hud-style The hud is where informations about the game are displayed. This means, who is winning, are other status-like informations. Possible values include 'floating' and 'tactical'. -- Command-line option: -keep-ratio= -- Environment variable: LW6_KEEP_RATIO -- XML key: keep-ratio Defines wether the map should keep its ratio, or if it should be stretched to fill the shape of your screen. -- Command-line option: -menu-color-auto= -- Environment variable: LW6_MENU_COLOR_AUTO -- XML key: menu-color-auto Defines wether menu colors will be set automatically from background colors. This is a time saver to keep map designers from requiring to redefined every single color in the game. You only need to set background-color-base-bg, background-color-base-fg, background-color-alternate-bg and background-color-alternate-fg. Then menu_color_default_bg, menu_color_default_fg, menu_color_selected_bg, menu_color_selected_fg, menu_color_disabled_bg and menu_color_disabled_fg will be automatically set. -- Command-line option: -menu-color-default-bg= -- Environment variable: LW6_MENU_COLOR_DEFAULT_BG -- XML key: menu-color-default-bg Defines the default background color for menus. Ignored if menu-color-auto is set. Can be #RGB, #RGBA, #RRGGBB or #RRGGBBAA. -- Command-line option: -menu-color-default-fg= -- Environment variable: LW6_MENU_COLOR_DEFAULT_FG -- XML key: menu-color-default-fg Defines the default foreground color for menus. In fact, this is the main color for menu text, the color used to draw letters in menus. Ignored if menu-color-auto is set. Can be #RGB, #RGBA, #RRGGBB or #RRGGBBAA. -- Command-line option: -menu-color-disabled-bg= -- Environment variable: LW6_MENU_COLOR_DISABLED_BG -- XML key: menu-color-disabled-bg Defines the background color for a disabled menu item. Ignored if menu-color-auto is set. Can be #RGB, #RGBA, #RRGGBB or #RRGGBBAA. -- Command-line option: -menu-color-disabled-fg= -- Environment variable: LW6_MENU_COLOR_DISABLED_FG -- XML key: menu-color-disabled-fg Defines the foreground color for a disabled menu item. Ignored if menu-color-auto is set. Can be #RGB, #RGBA, #RRGGBB or #RRGGBBAA. -- Command-line option: -menu-color-selected-bg= -- Environment variable: LW6_MENU_COLOR_SELECTED_BG -- XML key: menu-color-selected-bg Defines the background color for a selected menu item. Ignored if menu-color-auto is set. Can be #RGB, #RGBA, #RRGGBB or #RRGGBBAA. -- Command-line option: -menu-color-selected-fg= -- Environment variable: LW6_MENU_COLOR_SELECTED_FG -- XML key: menu-color-selected-fg Defines the foreground color for a selected menu item. Ignored if menu-color-auto is set. Can be #RGB, #RGBA, #RRGGBB or #RRGGBBAA. -- Command-line option: -menu-style= -- Environment variable: LW6_MENU_STYLE -- XML key: menu-style The menu style is simply the name of the engine used to power the menu system. The only possible value, for now, is 'cylinder'. -- Command-line option: -system-color-auto= -- Environment variable: LW6_SYSTEM_COLOR_AUTO -- XML key: system-color-auto Defines wether system colors will be set automatically from background colors. This is a time saver to keep map designers from requiring to redefined every single color in the game. You only need to set background-color-base-bg, background-color-base-fg, background-color-alternate-bg and background-color-alternate-fg. Then system_color_bg and system_color_fg will be automatically set. -- Command-line option: -system-color-bg= -- Environment variable: LW6_SYSTEM_COLOR_BG -- XML key: system-color-bg Defines the system background color, used when displaying system info, such as the number of frames per second. Can be #RGB, #RGBA, #RRGGBB or #RRGGBBAA. -- Command-line option: -system-color-fg= -- Environment variable: LW6_SYSTEM_COLOR_FG -- XML key: system-color-fg Defines the system foreground color, used when displaying system info, such as the number of frames per second. This will typically be text color. Can be #RGB, #RGBA, #RRGGBB or #RRGGBBAA. -- Command-line option: -team-color-blue= -- Environment variable: LW6_TEAM_COLOR_BLUE -- XML key: team-color-blue Defines the color for the blue team. Syntax is HTML-like, #RGB or #RRGGBB. -- Command-line option: -team-color-cyan= -- Environment variable: LW6_TEAM_COLOR_CYAN -- XML key: team-color-cyan Defines the color for the cyan team. Syntax is HTML-like, #RGB or #RRGGBB. -- Command-line option: -team-color-green= -- Environment variable: LW6_TEAM_COLOR_GREEN -- XML key: team-color-green Defines the color for the green team. Syntax is HTML-like, #RGB or #RRGGBB. -- Command-line option: -team-color-lightblue= -- Environment variable: LW6_TEAM_COLOR_LIGHTBLUE -- XML key: team-color-lightblue Defines the color for the light blue team. Syntax is HTML-like, #RGB or #RRGGBB. -- Command-line option: -team-color-magenta= -- Environment variable: LW6_TEAM_COLOR_MAGENTA -- XML key: team-color-magenta Defines the color for the magenta team. Syntax is HTML-like, #RGB or #RRGGBB. -- Command-line option: -team-color-orange= -- Environment variable: LW6_TEAM_COLOR_ORANGE -- XML key: team-color-orange Defines the color for the orange team. Syntax is HTML-like, #RGB or #RRGGBB. -- Command-line option: -team-color-pink= -- Environment variable: LW6_TEAM_COLOR_PINK -- XML key: team-color-pink Defines the color for the pink team. Syntax is HTML-like, #RGB or #RRGGBB. -- Command-line option: -team-color-purple= -- Environment variable: LW6_TEAM_COLOR_PURPLE -- XML key: team-color-purple Defines the color for the purple team. Syntax is HTML-like, #RGB or #RRGGBB. -- Command-line option: -team-color-red= -- Environment variable: LW6_TEAM_COLOR_RED -- XML key: team-color-red Defines the color for the red team. Syntax is HTML-like, #RGB or #RRGGBB. -- Command-line option: -team-color-yellow= -- Environment variable: LW6_TEAM_COLOR_YELLOW -- XML key: team-color-yellow Defines the color for the yellow team. Syntax is HTML-like, #RGB or #RRGGBB. -- Command-line option: -use-texture= -- Environment variable: LW6_USE_TEXTURE -- XML key: use-texture Defines wether the map texture should be used. Of course if there's no map texture, the texture... won't be used. But if there is one, this parameter will force the game to ignore it and play with solid colors. This probably won't look as nice as the textured map in most cases, but some players might find it more readable and confortable to play when throwing eye candy away. -- Command-line option: -view-color-auto= -- Environment variable: LW6_VIEW_COLOR_AUTO -- XML key: view-color-auto Defines wether view colors will be set automatically from background colors. This is a time saver to keep map designers from requiring to redefined every single color in the game. You only need to set background-color-base-bg, background-color-base-fg, background-color-alternate-bg and background-color-alternate-fg. Then view_color_cursor_bg, view_color_cursor_fg, view_color_map_bg and view_color_map_fg will be automatically set. -- Command-line option: -view-color-cursor-bg= -- Environment variable: LW6_VIEW_COLOR_CURSOR_BG -- XML key: view-color-cursor-bg Defines the background cursor color. Will typically be used to draw the shape of the cursor. Ignored if view-color-auto is set. Can be #RGB, #RGBA, #RRGGBB or #RRGGBBAA. -- Command-line option: -view-color-cursor-fg= -- Environment variable: LW6_VIEW_COLOR_CURSOR_FG -- XML key: view-color-cursor-fg Defines the foreground cursor color. Will typically be used to draw text in the cursor. Ignored if view-color-auto is set. Can be #RGB, #RGBA, #RRGGBB or #RRGGBBAA. -- Command-line option: -view-color-map-bg= -- Environment variable: LW6_VIEW_COLOR_MAP_BG -- XML key: view-color-map-bg Defines the background map color. If there's no map texture defined or if use-texture is false, this is the color of the places where armies will go. Ignored if view-color-auto is set. Can be #RGB, #RGBA, #RRGGBB or #RRGGBBAA. -- Command-line option: -view-color-map-fg= -- Environment variable: LW6_VIEW_COLOR_MAP_FG -- XML key: view-color-map-fg Defines the foreground map color. If there's no map texture defined or if use-texture is false, this is the color of walls, what armies can't go through. Ignored if view-color-auto is set. Can be #RGB, #RGBA, #RRGGBB or #RRGGBBAA. -- Command-line option: -view-style= -- Environment variable: LW6_VIEW_STYLE -- XML key: view-style The view style conditions which renderer is used for the map, the area where fighters are displayed. This is not the graphics backend. Indeed, the graphics backend defines which technical tool one uses (which library) one runs, wether this parameter says what kind of rendering one wants. -- Command-line option: -zoom= -- Environment variable: LW6_ZOOM -- XML key: zoom Defines the map zoom. If lower than 1.0, map will occupy only a fraction of the screen, if greater than 1.0, some areas will be outside the screen, and the player will need to scroll through it. 4.9 Advanced settings ===================== -- Command-line option: -checkpoint-period= -- Environment variable: LW6_CHECKPOINT_PERIOD -- XML key: checkpoint-period Defines with what period (in msec) system values such as frames per sec, network traffic, and others, will be updated. Default value should fit in most cases. -- Command-line option: -loader-sleep= -- Environment variable: LW6_LOADER_SLEEP -- XML key: loader-sleep Defines how long the loader thread should wait between two polls. Default value should fit in most cases. -- Command-line option: -max-frames-per-sec= -- Environment variable: LW6_MAX_FRAMES_PER_SEC -- XML key: max-frames-per-sec Defines how many frames will be displayed per second. Of course this is a maximum value, if your hardware can't keep up with this value, display will just be slow, no matter what value you define here. Note that you might really wish to have something rather low here, to keep network and 'logic' function responsiveness. Passed 60 frames per second, speed is really only for visual comfort, as Liquid War 6 is now so fast-paced that it requires 200 frames/sec to outperform opponents. -- Command-line option: -max-io-per-display= -- Environment variable: LW6_MAX_IO_PER_DISPLAY -- XML key: max-io-per-display Like 'max-logic-per-display', but input/output related. If too much time is spent on IO stuff, the game will simply drop out and stop processing IO, giving priority to display. Logically, when display is fast, about one IO per display is just enough. -- Command-line option: -max-io-per-sec= -- Environment variable: LW6_MAX_IO_PER_SEC -- XML key: max-io-per-sec Defines how many calls to the internal input/output function there will be during a second. Might condition network responsiveness. Default value should fit in most cases. -- Command-line option: -max-logic-per-display= -- Environment variable: LW6_MAX_LOGIC_PER_DISPLAY -- XML key: max-logic-per-display This is a limit value which will avoid, on slow machines, to spend all the CPU cycles to calculate internal things, and display nothing. While it's important to keep up with other network players for instance, it makes no sense to do it for a long period without showing anything. Thus, this value. Basically, it only helps not being locked-out in an 'I can't quit' nightmare when running fullscreen on a slow machine. -- Command-line option: -max-logic-per-sec= -- Environment variable: LW6_MAX_LOGIC_PER_SEC -- XML key: max-logic-per-sec Defines how many calls to the internal logic() function there will be during a second. This is really an internal value, the actual speed of the game, that is, how fast fighters will move, is defined elsewhere in the map parameters. See 'moves-per-tick' for instance. Default value should fit in most cases. -- Command-line option: -memory-bazooka-eraser= -- Environment variable: LW6_MEMORY_BAZOOKA_ERASER -- XML key: memory-bazooka-eraser The memory eraser is a tool which will systematically fill allocated memory with 'M', and overwrite all allocated bytes with 'F' before freeing memory. It will even handle realloc calls. This is usefull to track bugs. Indeed, with this option enabled, freshly allocated memory will never contain zeroes unless one calls calloc, and if you ever free some memory zone before being done with it, it will be filled with junk and therefore not be usable. The memory bazzooka must be big enough if you want this feature to actually work. -- Command-line option: -memory-bazooka-size= -- Environment variable: LW6_MEMORY_BAZOOKA_SIZE -- XML key: memory-bazooka-size The memory bazooka is a brute-force tool, conceived after a full night spent tracking some memory leak. The idea is to keep a track of all allocated pointers, when the data was allocated (timestamp), where in the code (file, line), and even point out what data there is in that place. A memory bazooka report at the end of the game will just show what's left. There should be nothing. This parameter is here to avoid wasting CPU cycles on a feature which is very debug-oriented and does not really make sense for the casual user. Set it to 0 for best performance, something like 100 might just be helpfull, but 1000000 is the right way to seriously debug code. 4.10 Script hooks ================= 4.11 C to Guile API =================== 4.12 C functions ================ 4.12.1 libcfg ------------- -- Function: int lw6cfg_load (void * CFG_CONTEXT, char * FILENAME) CFG_CONTEXT: a context returned by `lw6cfg_init' FILENAME: a file path, absolute or relative Loads the given config file, and stores its values into the current context. Parameters which are both in the config file and given as command line parameters, will be taken from the command-line. *Return value:* 1 if successfull, 0 if error. -- Function: int lw6cfg_save (void * CFG_CONTEXT, char * FILENAME) CFG_CONTEXT: a context returned by `lw6cfg_init' FILENAME: a file path, absolute or relative Save current options into the given config file. Before saving the file, all command line arguments will be read and will override current values. This means the saved file will contain values given as command line arguments. *Return value:* 1 if successfull, 0 if error. -- Function: void * lw6cfg_init (int ARGC, char * [] ARGV) ARGC: number of command line arguments, as given to `main' ARGV: a list of command line arguments, as given to `main' Initializes a config context object. This object is hidden behind an opaque void * pointer to avoid direct access to its elements. *Return value:* an opaque pointer, must be freed with `lw6cfg_quit'. -- Function: void lw6cfg_quit (void * CFG_CONTEXT) CFG_CONTEXT: a context returned by `lw6cfg_init' Frees a config cfg_context object. You must call this once you're done with the context. *Return value:* none. -- Function: void lw6cfg_reset (int ARGC, char * [] ARGV) ARGC: number of command line arguments, as given to `main' ARGV: a list of command line arguments, as given to `main' Overwrites the config file with defaults. Use this to get rid of old configurations. -- Function: char * lw6cfg_unified_get_value (int ARGC, char * [] ARGV, char * KEY) ARGC: number of command-line args, as passed to `main' ARGV: arry of command-line args, as passed to `main' KEY: the key to query Unified "value" getter, which gets informations from environment variables, command line, and config file. The rules is that the command-line argument always has the last word. It will override any other value. Follows environment variables, which will be used if no command-line argument is supplied. Note that these are "LW6_" prefixed and uppercased environment variables as opposed to lowercased and "dash-separated" keys. Finally, if there's no environment variable, nor any config-file corresponding entry, the value will be searched in the config file. If there's no information in the config file, NULL is returned. *Return value:* a string with the value. Can be NULL. Must be freed. -- Function: char * lw6cfg_unified_get_user_dir (int ARGC, char * [] ARGV) ARGC: number of command-line args, as passed to `main' ARGV: arry of command-line args, as passed to `main' Gets the user dir, taking all parameters in account, that's to say the "LW6_USER_DIR" env value, the "-user-dir" command-line paramater and the "user-dir" config file entry. *Return value:* the directory path, might be NULL, must be freed. -- Function: char * lw6cfg_unified_get_log_file (int ARGC, char * [] ARGV) ARGC: number of command-line args, as passed to `main' ARGV: arry of command-line args, as passed to `main' Gets the user dir, taking all parameters in account, that's to say the "LW6_LOG_FILE" env value, the "-log-file" command-line paramater and the "log-file" config file entry. *Return value:* the directory path, might be NULL, must be freed. -- Function: char * lw6cfg_unified_get_map_path (int ARGC, char * [] ARGV) ARGC: number of command-line args, as passed to `main' ARGV: arry of command-line args, as passed to `main' Gets the user dir, taking all parameters in account, that's to say the "LW6_MAP_PATH" env value, the "-map-path" command-line paramater and the "map-path" config file entry. *Return value:* the directory path, might be NULL, must be freed. 4.12.2 libcli ------------- 4.12.3 libcns ------------- 4.12.4 libdyn ------------- -- Function: lw6dyn_dl_handle_t * lw6dyn_dlopen_backend (int ARGC, char * [] ARGV, char * TOP_LEVEL_LIB, char * BACKEND_NAME) ARGC: the number of command-line arguments as passed to `main' TOP_LEVEL_LIB: the top-level library concerned, this means is it "cli", "gfx", "snd" or "srv". This will tell the function to search for the .so file in the correct subdirectory. Think of this as a category. Opens a .so file corresponding to the given backend, it is capable to search for system libraries installed after "make install" but if not found, it will also search in the current build directory, finding the .so files in hidden .libs subdirectories. *Return value:* a handle to the module, once it's opened. You might still need to call a module specific `init'() function, but it's another story. -- Function: char * lw6dyn_path_find_backend (int ARGC, char * [] ARGV, char * TOP_LEVEL_LIB, char * BACKEND_NAME) ARGC: the number of command-line arguments as passed to `main' TOP_LEVEL_LIB: the top-level library concerned, this means is it "cli", "gfx", "snd" or "srv". This will tell the function to search for the .so file in the correct subdirectory. Think of this as a category. Get the full path to a .so file corresponding to the given backend, it is capable to search for system libraries installed after "make install" but if not found, it will also search in the current build directory, finding the .so files in hidden .libs subdirectories. *Return value:* the full path of the .so file, needs to be freed. 4.12.5 libgfx ------------- 4.12.6 libgui ------------- -- Function: lw6gui_menu_t * lw6gui_menu_new (char * TITLE) TITLE: the string to be displayed, what the user sees. Can be freed after the call is done, function will make a copy internally. Constructs a new menu object. Note that you can always call other functions to modify it afterwards. *Return value:* a pointer to the newly allocated object. -- Function: void lw6gui_menu_free (lw6gui_menu_t * MENU) MENU: a pointer to the menu. Frees the menu, checking if things are OK before doing so. *Return value:* none. -- Function: int lw6gui_menu_memory_footprint (lw6gui_menu_t * MENU) MENU: a pointer to the menu. Gets the memory occupied by the menu. Could be usefull to help a garbage collector taking decisions or reporting erros, for instance. *Return value:* the number of bytes used. -- Function: char * lw6gui_menu_repr (lw6gui_menu_t * MENU) MENU: a pointer to the menu. Constructs a readable description of the object. Usefull for debugging, or to introspect things using scripts, at run-time. Does not necessarly describe all the informations about the object, but helps knowing what it is. *Return value:* a string describing the object, must be freed. -- Function: void lw6gui_menu_set_title (lw6gui_menu_t * MENU, char * TITLE) MENU: a pointer to the menu. TITLE: the new title, you can free it after calling the function, an internal copy will be made. Change the title of the menu. That is to say, its title. Use this function to change the title, don't try to access the struct directly. The idea is to have safe memory management. *Return value:* none -- Function: lw6gui_menuitem_t * lw6gui_menu_get_item (lw6gui_menu_t * MENU, int POSITION) MENU: the menu we want to query POSITION: the order of the item we want Gets the menu item at the given position. First item is 0, last is N-1. Returns a pointer on the real object, not a copy. *Return value:* a pointer to a menu item, NULL if out of range. -- Function: int lw6gui_menu_select (lw6gui_menu_t * MENU, int POSITION, int NOW) MENU: the menu we want to modify POSITION: the position of the item we want to select NOW: the current time, as a timestamp. Selects the item at the given position. Use this function to be sure that only one item is selected, and all other states are consistent. Timestamp is needed for the sake of eye-candy. *Return value:* 1 if success, 0 if failure (out of range). -- Function: int lw6gui_menu_scroll_up (lw6gui_menu_t * MENU) MENU: the menu to scroll Scrolls a menu up, used as a callback for mouse wheel up for instance. The idea is just to decrement the first displayed item index. *Return value:* 1 if OK, 0 if failed (out of range). -- Function: int lw6gui_menu_scroll_down (lw6gui_menu_t * MENU) MENU: the menu to scroll Scrolls a menu down, used as a callback for mouse wheel down for instance. The idea is just to increment the first displayed item index. *Return value:* 1 if OK, 0 if failed (out of range). -- Function: int lw6gui_menu_insert (lw6gui_menu_t * MENU, lw6gui_menuitem_t * MENUITEM, int POSITION, int NOW) MENU: the menu we want to modify MENUITEM: the item to insert POSITION: the position the new item will occupy ("insert before" mode) NOW: the current time, as a timestamp. Inserts the given item in the menu. All items starting at the insert position will be "pushed" (that is, their position incremented by 1). Once the menuitem is inserted, the menu object will take care of memory management and automatically free it when needed. *Return value:* 1 if success, 0 if failure (memory problem, out of range). -- Function: int lw6gui_menu_append (lw6gui_menu_t * MENU, lw6gui_menuitem_t * MENUITEM, int NOW) MENU: the menu we want to modify MENUITEM: the item to insert NOW: the current time, as a timestamp. Appends the given item to the menu. Once the menuitem is appended, the menu object will take care of memory management and automatically free it when needed. *Return value:* 1 if success, 0 if failure (memory problem). -- Function: int lw6gui_menu_remove (lw6gui_menu_t * MENU, int POSITION, int NOW) MENU: the menu we want to modify POSITION: the item to insert NOW: the current time, as a timestamp. Removes an item from the menu. It will automatically be freed. *Return value:* 1 if success, 0 if failure (out of range). -- Function: void lw6gui_menu_update_display_range (lw6gui_menu_t * MENU, int MAX_DISPLAYED_ITEMS) MENU: the menu concerned MAX_DISPLAYED_ITEMS: the maximum number of items to display at once Updates the display range. The reason for having this is that the first item, that is, how far we scroll in a very long menu, depends on the previous position. Plus you have to handle limit cases (begin/end). Thus, this function, which will automatically pick-up a suitable position. Of course, `first_item_displayed' is not necessarly equal to `selected_item'. *Return value:* none. -- Function: int lw6gui_menu_insert_for_id_use (lw6gui_menu_t * MENU, char * LABEL, int VALUE, int ENABLED, int SELECTED, int COLORED, int POSITION, int NOW) MENU: the menu to work on LABEL: the label of the menuitem to append VALUE: the value of the menuitem to append ENABLED: wether the inserted menuitem should be enabled SELECTED: wether the inserted menuitem should be selected COLORED: wether the inserted menuitem should use value as its color NOW: current time (timestamp) Inserts a menu item at the given position. The idea is that the menu item object is automatically constructed on the fly, and an id is returned, which can be passed to '_using_id' menu-related functions. This is typically for using in scripts. The idea is that the script just keeps a copy of the id returned, and can this way operate directly on the menuitem without keeping a pointer, a smob or anything internally. From the C point of view, having a real C structure enables persistent data from one display to the other, and this is nice and conveninent. I acknowledge the prototype is scary. *Return value:* 0 if error, or else an id which will later be used with '_using_id' functions. -- Function: int lw6gui_menu_append_for_id_use (lw6gui_menu_t * MENU, char * LABEL, int VALUE, int ENABLED, int SELECTED, int COLORED, int NOW) MENU: the menu to work on LABEL: the label of the menuitem to append VALUE: the value of the menuitem to append ENABLED: wether the appended menuitem should be enabled SELECTED: wether the appended menuitem should be selected COLORED: wether the appended menuitem should use value as its color NOW: current time (timestamp) Appends a menuitem using the same logic as `lw6gui_menu_insert_for_id_use' that is to say a parameter is returned which can later be used to directly operate on a given menuitem, without having its pointer, and even if its position changes. *Return value:* 0 if error, or else an id which will later be used with '_using_id' functions. -- Function: int lw6gui_menu_remove_using_id (lw6gui_menu_t * MENU, int MENUITEM_ID, int NOW) MENU: the menu to work on MENUITEM_ID: the id of the menuitem to remove NOW: current time (timestamp) Deletes the menuitem with the given id. Very important: the id is not the position. Id are arbitrary numbers that stick to menuitems, but they are not directly linked with the position. This function is practical to use if, for some reason, you don't have the pointer on the menuitem. *Return value:* 1 if success, 0 if failure (out of range). -- Function: void lw6gui_menu_sync_using_id (lw6gui_menu_t * MENU, int MENUITEM_ID, char * LABEL, int VALUE, int ENABLED, int SELECTED, int COLORED, int NOW) MENU: the menu to work on MENUITEM_ID: the id of the menuitem to synchronize NOW: current time (timestamp) Updates the menuitem with the given id. Very important: the id is not the position. Id are arbitrary numbers that stick to menuitems, but they are not directly linked with the position. This function is practical to use if, for some reason, you don't have the pointer on the menuitem. In practice, it's heavily used in the game to transmit informations from the scripts to the core C engine. Additionnaly, this function will automatically synchronize the `selected_item' field of the menu struct. *Return value:* 1 if success, 0 if failure (out of range). -- Function: lw6gui_menuitem_t * lw6gui_menuitem_new (char * LABEL, int VALUE, int ENABLED, int SELECTED, int COLORED) LABEL: the string to be displayed, what the user sees. Can be freed after the call is done, function will make a copy internally. VALUE: the value. No GUI function uses this, this is the "real" value associated to the item. ENABLED: wether the menu item can be selected, used, and so on SELECTED: wether the menu item is the item selected among all menu items. COLORED: wetherr the menu item must, when drawn, be colored according to its value. Constructs a new menuitem object. Note that you can always call other functions to modify these values afterwards, this might change rendering since `lw6gui_menuitem_set_value' or `lw6gui_menuitem_set_label' will, for instance, modify the "when was that item last modified" information. *Return value:* a pointer to the newly allocated object. -- Function: void lw6gui_menuitem_free (lw6gui_menuitem_t * MENUITEM) MENUITEM: a pointer to the menuitem. Frees the menuitem, checking if things are OK before doing so. *Return value:* none. -- Function: int lw6gui_menuitem_memory_footprint (lw6gui_menuitem_t * MENUITEM) MENUITEM: a pointer to the menuitem. Gets the memory occupied by the menuitem. Could be usefull to help a garbage collector taking decisions or reporting erros, for instance. *Return value:* the number of bytes used. -- Function: char * lw6gui_menuitem_repr (lw6gui_menuitem_t * MENUITEM) MENUITEM: a pointer to the menuitem. Constructs a readable description of the object. Usefull for debugging, or to introspect things using scripts, at run-time. Does not necessarly describe all the informations about the object, but helps knowing what it is. *Return value:* a string describing the object, must be freed. -- Function: void lw6gui_menuitem_set_label (lw6gui_menuitem_t * MENUITEM, char * LABEL, int NOW) MENUITEM: a pointer to the menuitem. LABEL: the new label, you can free it after calling the function, an internal copy will be made. NOW: the current time, as a timestamp. Change the label of the menu item. That is to say, what the user sees. Use this function to change the menuitem value, don't try to access the struct directly. The idea is 1) to have safe memory management and 2) to keep the `last_change' member up to date. It can be later used for eye-candy effects. *Return value:* none -- Function: void lw6gui_menuitem_set_value (lw6gui_menuitem_t * MENUITEM, int VALUE, int NOW) MENUITEM: a pointer to the menuitem. NOW: the current time, as a timestamp. Changes the value of a menuitem. This is the internal value, not what the user sees. Use this function to change the menuitem value, don't try to access the struct directly. The idea is to keep the `last_change' member up to date. It can be later used for eye-candy effects. *Return value:* none -- Function: void lw6gui_menuitem_select (lw6gui_menuitem_t * MENUITEM, int NOW) MENUITEM: a pointer to the menuitem. NOW: the current time, as a timestamp. Switches the menuitem to selected state. Use this function, don't try to modify the struct members directly. The idea is to have the `last_select' parameter up to date. It can be later used for eye-candy effects. *Return value:* none -- Function: void lw6gui_menuitem_unselect (lw6gui_menuitem_t * MENUITEM, int NOW) MENUITEM: a pointer to the menuitem. NOW: the current time, as a timestamp. Switches the menuitem to unselected state. Use this function, don't try to modify the struct members directly. The idea is to have the `last_unselect' parameter up to date. It can be later used for eye-candy effects. *Return value:* none -- Function: int lw6gui_menuitem_checksum (lw6gui_menuitem_t * MENUITEM) MENUITEM: the menuitem we want to identify Returns a checksum which can be used to know, for instance, wether the menuitem has changed or not, and if we should redraw it. *Return value:* a checksum. -- Function: int lw6gui_test () Run tests in the gui module. *Return value:* 1 if successfull, 0 if failed. 4.12.7 libhlp ------------- -- Function: int lw6hlp_is_documented (char * KEYWORD) KEYWORD: the keyword we want to check out Checks wether a given keyword is documented or not. *Return value:* 1 if documented, 0 if not. -- Function: char * lw6hlp_about (LW6HLP_TYPE * TYPE, char * KEYWORD) TYPE: the type of the data associated to the keyword, will be written KEYWORD: the keyword we want help about Returns the documentation string associated to a keyword. The keyword might be a command-line option, a Guile function, an XML file entry. Raises a warning if the keyword is undocumented, but never returns NULL, you can use the returned value without checking it. String is localized if a translation is available. It's safe to call this function with type being NULL. *Return value:* a help string, never NULL, must not be freed. Additionnally, type will be updated. -- Function: int lw6hlp_match (char * KEYWORD1, char * KEYWORD2) KEYWORD1: the 1st keyword KEYWORD2: the 2nd keyword Checks wether a keyword matches another. Not only a string comparison, will also try and guess if the error is only about dash "-" replaced by underscode "_", for instance. *Return value:* 1 if matches, 0 if different. -- Function: int lw6hlp_is_listed (char * KEYWORD) KEYWORD: the keyword we want to check out Checks wether a given keyword is listed or not, in any of the know options list. In fact, the answer is just "does this mean anything to Liquid War 6 at all". *Return value:* 1 if listed, 0 if not. -- Function: int lw6hlp_is_listed_here (lw6sys_list_t * LIST, char * KEYWORD) KEYWORD: the keyword we want to check out Checks wether a given keyword is present in the given list or not. *Return value:* 1 if listed, 0 if not. -- Function: lw6sys_list_t * lw6hlp_list () Returns a list of all available keywords. *Return value:* a list containing all the keywords. Strings are not dynamically allocated, you can't modify them. -- Function: void lw6hlp_print_keyword (lw6sys_list_t ** LIST, FILE * F) list: a pointer to a list of keywords f: the file to print the content to Prints all the keywords from the list. One keyword per line. *Return value:* none. -- Function: void lw6hlp_print_content (lw6sys_list_t ** LIST, FILE * F) list: a pointer to a list of keywords f: the file to print the content to Prints all the keywords from the list, with the associated keyword help, to the given file. Output is formatted to fit on the standard terminal/console. *Return value:* none. 4.12.8 libimg ------------- 4.12.9 libker ------------- 4.12.10 libldr -------------- -- Function: int lw6ldr_options_read (lw6map_options_t * OPTIONS, char * DIRNAME) DIRNAME: the directory of the map Read the options (options.xml) of a map. Pointer to options must be valid, and values already initialized, either zeroed or filled in with defaults or custom values. *Return value:* 1 if success, 0 if failed. -- Function: int lw6ldr_options_update (lw6map_options_t * OPTIONS, lw6sys_assoc_t * VALUES) OPTIONS: the options struct to fill with values (read/write parameter) VALUES: an assoc containing strings with the new values Overrides options with values. Pointer to options must be valid, and values already initialized, either zeroed or filled in with defaults or custom values. Not all parameters need be defined in values. It can even be NULL. The idea is just that if something is defined in values, it will override the existing options. *Return value:* 1 if success, 0 if failed. -- Function: int lw6ldr_param_read (lw6map_param_t * PARAM, char * DIRNAME) PARAM: the parameter struct to fill with values (read/write parameter) DIRNAME: the directory of the map Read the parameters associated to a map. Pointer to param must be valid, and values already initialized, either zeroed or filled in with defaults or custom values. *Return value:* 1 if success, 0 if failed. -- Function: int lw6ldr_param_update (lw6map_param_t * PARAM, lw6sys_assoc_t * VALUES) PARAM: the parameter struct to fill with values (read/write parameter) VALUES: an assoc containing strings with the new values Overrides param with values. Pointer to param must be valid, and values already initialized, either zeroed or filled in with defaults or custom values. Not all parameters need be defined in values. It can even be NULL. The idea is just that if something is defined in values, it will override the existing param. *Return value:* 1 if success, 0 if failed. -- Function: void lw6ldr_print_example_options_xml (FILE * F) F: file to output content to Print to a file a typical map options.xml file. *Return value:* none. -- Function: void lw6ldr_print_example_style_xml (FILE * F) F: file to output content to Print to a file a typical map style.xml file. *Return value:* none. -- Function: int lw6ldr_print_examples (char * USER_DIR) USER_DIR: the user directory or at least, a writable one Writes all example XML files in 'user_dir/example/', will create the directory if needed. *Return value:* 1 if success, 0 if failed. -- Function: lw6map_level_t * lw6ldr_read (char * DIRNAME, lw6sys_assoc_t * DEFAULT_PARAM, lw6sys_assoc_t * FORCED_PARAM, lw6sys_wh_t * DISPLAY_SHAPE) DIRNAME: the directory containing the map DEFAULT_PARAM: default parameters, as strings FORCED_PARAM: forced parameters, as strings DISPLAY_SHAPE: the shape of the display output (resolution) Loads a map from dist. The default_param and forced_param can contain values corresponding to options.xml and style.xml entries. Parameters are read in 4 steps. 1st, a default value is picked by the program. 2nd, any value in `default_param' replaces previous values. 3rd, any value in options.xml or style.xml replaces previous values. 4th, any value in `forced_param' replaces previous values. In practice, the `default_param' allows the user to set defaults which can still be overwritten by the map, while `forced_param' is a definitive 'ignore what is is defined in the map' way of doing things. See also `lw6ldr_read_relative'. *Return value:* 1 if success, 0 if failed. -- Function: lw6map_level_t * lw6ldr_read_relative (char * MAP_PATH, char * RELATIVE_PATH, lw6sys_assoc_t * DEFAULT_PARAM, lw6sys_assoc_t * FORCED_PARAM, lw6sys_wh_t * DISPLAY_SHAPE) MAP_PATH: a collection of paths where to find maps RELATIVE_PATH: something which will be appended to a `map_path' member DEFAULT_PARAM: default parameters, as strings FORCED_PARAM: forced parameters, as strings DISPLAY_SHAPE: the shape of the display output (resolution) Reads a map from disk, using the map-path value, which is a collection of paths defined by the command-line, the environment variables, and the config file. `default_param' and `forced_param' work as in the function `lw6ldr_read'. *Return value:* 1 if success, 0 if failure. -- Function: int lw6ldr_style_read (lw6map_style_t * STYLE, char * DIRNAME) DIRNAME: the directory of the map Read the style (style.xml) of a map. Pointer to style must be valid, and values already initialized, either zeroed or filled in with defaults or custom values. *Return value:* 1 if success, 0 if failed. -- Function: int lw6ldr_style_set (lw6map_style_t * STYLE, char * KEY, char * VALUE) STYLE: the style to modify KEY: the key to modify VALUE: the value to affect to the key, as a string Sets one single parameter in a style structure. Value must always be passed as a string, will be converted to the right type automatically when storing it in the structure. *Return value:* 1 if success, 0 if failed. Note that while 0 really means there's a problem, some affectations can fail and return 1, needs to be worked on. -- Function: int lw6ldr_style_update (lw6map_style_t * STYLE, lw6sys_assoc_t * VALUES) STYLE: the style struct to fill with values (read/write parameter) VALUES: an assoc containing strings with the new values Overrides style with values. Pointer to style must be valid, and values already initialized, either zeroed or filled in with defaults or custom values. Not all parameters need be defined in values. It can even be NULL. The idea is just that if something is defined in values, it will override the existing style. *Return value:* 1 if success, 0 if failed. 4.12.11 libmap -------------- -- Function: char * lw6map_to_hexa (lw6map_level_t * LEVEL) Converts a map to something that is later readable by `lw6map_from_hexa' to reproduce the exact same map. Just a serializer. *Return value:* a newly allocated pointer, NULL if conversion failed. -- Function: lw6map_level_t * lw6map_from_hexa (char * HEXA) HEXA: an hexadecimal ASCII string, created by `lw6map_to_hexa' Constructs a map from an hexadecimal string generated by `lw6map_to_hexa'. Just an un-serializer. *Return value:* a new map, might be NULL if string isn't correct. -- Function: lw6map_level_t * lw6map_new () Creates a new empty map. This object is perfectly unusable as is, since it has a 0x0 size, and many things set to "NULL". Still, it's used internally and is the canonical way to create the object, it ensures later calls that set up default parameters, for instance, will succeed. *Return value:* a newly allocated pointer. -- Function: lw6map_level_t * lw6map_defaults () Creates a map, set to defaults. This is usefull mostly for testing, it will just create a dull rectangle plain and uninteresting map, however it's a quick way to have a working object and test stuff on it. *Return value:* a newly allocated map. -- Function: void lw6map_free (lw6map_level_t * LEVEL) Frees a map and releases all its internal ressources. *Return value:* none. -- Function: int lw6map_memory_footprint (lw6map_level_t * LEVEL) Reports how many bytes the map needs, in memory. Note that this is not contiguous memory, it involves a bunch of pointers, and possibly much more... -- Function: char * lw6map_repr (lw6map_level_t * LEVEL) Returns a string describing the map. This is a very short description, use it for logs, and to debug stuff. By no means it's a complete exhaustive description. Still, the string returned should be unique. *Return value:* a dynamically allocated string. 4.12.12 libnet -------------- -- Function: char * lw6net_recv_line_tcp (int SOCK) SOCK: the socket descriptor Receives a line terminated by LF ("\n", chr(10)) or CR/LF ("\r\n", chr(10)chr(13)) on a TCP socket, that is, stream oriented. If there's no complete line available, function returns immediately with NULL. Same if socket is closed, broken, whatever. Only if there's something consistent will the function return non-NULL. *Return value:* a dynamically allocated string with the content received. The tailing (CR)/LF is stripped. -- Function: int lw6net_send_line_tcp (int SOCK, char * LINE) SOCK: the socket descriptor LINE: the line to be sent, without the "\n" at the end Sends a line terminated by LF ("\n", chr(10)) on a TCP socket, that is, stream oriented. The "\n" is automatically added, do not bother sending it. *Return value:* non-zero if success -- Function: char * lw6net_recv_line_udp (int SOCK, char ** INCOMING_IP, int * INCOMING_PORT) SOCK: the socket descriptor INCOMING_IP: the IP address of the sender (returned) INCOMING_PORT: the IP port of the sender (returned) Receives a line terminated by LF ("\n", chr(10)) or CR/LF ("\r\n", chr(10)chr(13)) on a UDP socket, that is, datagram oriented. If there's no complete line available, function returns immediately with NULL. Same if socket is closed, broken, whatever. Only if there's something consistent will the function return non-NULL. By-value parameters allow the caller to know where the data come from. *Return value:* a dynamically allocated string with the content received. The tailing (CR)/LF is stripped. -- Function: int lw6net_send_line_udp (int SOCK, char * LINE, char * IP, int PORT) SOCK: the socket descriptor LINE: the line to be sent, without the "\n" at the end IP: the IP address of the target PORT: the IP port of the target Sends a line terminated by LF ("\n", chr(10)) on a UDP socket, that is, datagram oriented. The "\n" is automatically added, do not bother sending it. *Return value:* the number of bytes sent, 0 if failure -- Function: int lw6net_init (int ARGC, char * [] ARGV) Initializes the low-level network API, you must call this before calling any other network related function, for it allocates a dynamic context which is in turn used by every function. *Return value:* non-zero if success -- Function: void lw6net_quit () Frees memory, joins active threads, and releases everything set up by network code. *Return value:* void 4.12.13 libp2p -------------- 4.12.14 libsnd -------------- 4.12.15 libsrv -------------- 4.12.16 libsys -------------- -- Function: int lw6sys_arg_match (char * KEYWORD, char * ARGV_STRING) KEYWORD: the option to match, without the prefix "-" or "-" ARGV_STRING: the argv value, for instance argv[1] This is an utility function which allow the program to handle options in a uniform manner. Key comparison is insensitive, that is, -option and -OPTION are equivalent. Besides, -option and -OPTION are equivalent too. Liquid War 6 documentation mentions options in lowercase with a double dash (-option) by default, but it's a fact, the program supports variants. This is just for convenience, the philosophy behind this behavior is "be as permissive as possible when interpreting input, and as strict as possible when generating output". In fact, it's even said that Liquid War 6 will accept the argument without any prefix dash as being valid... This is to say running "liquidwar6 -option" is the same as running "liquidwar6 option". But, this is a secret 8-) *Return value:* non zero if it matches, 0 if it doesn't. -- Function: int lw6sys_arg_exists (int ARGC, char * [] ARGV, char * KEYWORD) ARGC: the number of arguments, as passed to `main' ARGV: an array of arguments, as passed to `main' KEYWORD: the keyword to match Parses all command-line arguments, searching for one precise "-key[=...]" entry. *Return value:* 1 if key is present, 0 if not. -- Function: char * lw6sys_arg_get_value (int ARGC, char * [] ARGV, char * KEYWORD) ARGC: the number of arguments, as passed to `main' ARGV: an array of arguments, as passed to `main' KEYWORD: the keyword to match Parses all command-line arguments, searching for one precise "-key=value" pair, and returns the value. *Return value:* a pointer to the value. May be NULL. Must be freed. -- Function: char * lw6sys_arg_get_value_with_env (int ARGC, char * [] ARGV, char * KEYWORD) ARGC: the number of arguments, as passed to `main' ARGV: an array of arguments, as passed to `main' KEYWORD: the keyword to match Parses all command-line arguments, searching for one precise "-key=value" pair, and returns the value. If a corresponding environment variable is available, but no command-line parameter was passed, the environment variable is intepreted. Such environment variables are uppercased, prefixed by "LW6_" and "_" replaces "-". The environment variable will be overriden if the command-line parameter is present. *Return value:* a pointer to the value. May be NULL. Must be freed. -- Function: lw6sys_assoc_t * lw6sys_assoc_new (LW6SYS_FREE_FUNC FREE_FUNC) FREE_FUNC: optional callback used to free memory when stored date is a pointer. Can be NULL when one stores non dynamically allocated data, such as an integer or a static array. Creates an empty assoc. There's a difference between NULL and an empty assoc. The empty assoc would (in Scheme) be '() whereas NULL corresponds to undefined "is not a assoc and will generate errors if you ever call assoc functions on it". Such created assoc are not performant hash tables but slowish "strcmp me for each key" associative arrays, the key being a "char *" string and the value a "void *" pointer. *Return value:* a pointer to the newly allocated associative array. Must be freed with `lw6sys_assoc_free'. -- Function: void lw6sys_assoc_free (lw6sys_assoc_t * ASSOC) ASSOC: the assoc to be freed. The function will cascade delete all elements, using (if not NULL...) the callback passed when first creating the assoc. *Return value:* void -- Function: int lw6sys_assoc_has_key (lw6sys_assoc_t * ASSOC, char * KEY) ASSOC: the assoc to test KEY: the key to search Not a very fast function, since on a "big" assoc, strcmp will be called internally until the key is found. *Return value:* non-zero if there's an entry with the corresponding key. -- Function: void * lw6sys_assoc_get (lw6sys_assoc_t * ASSOC, char * KEY) ASSOC: the assoc to query KEY: the key of which we want the value *Return value:* a void pointer to the data contained in the assoc. Note that the pointer on the actual data is returned, that is, if it's static data, you must not try to free it... As long as memory management is concerned, destroying the assoc will actually free the data if needed. -- Function: void lw6sys_assoc_set (lw6sys_assoc_t ** ASSOC, char * KEY, void * VALUE) ASSOC: the assoc to modify KEY: the key we want to updated VALUE: the new value Sets a value in an associative array. The key pointer need not be persistent, it can be freed after affectation. In fact a new string will be created internally. This is not true for the value, it's hard to find way to copy "any object". So if you want an associative array of strings, key can disappear after calling this function, but not value. The function passed as free_func when creating the assoc will be used to free stuff whenever needed (unset or free). *Return value:* void -- Function: void lw6sys_assoc_unset (lw6sys_assoc_t * ASSOC, char * KEY) ASSOC: the assoc concerned KEY: the key to unset Clears an entry in an associative array. The callback passed when creating the assoc will be called if needed, to free the data automatically. *Return value:* void -- Function: lw6sys_list_t * lw6sys_assoc_keys (lw6sys_assoc_t * ASSOC) ASSOC: the assoc to work on Returns a list containing all the keys of the assoc. The list must be free with lw6sys_list_free by the caller. This lisst copies all the keys of the assoc, so it is safe to use it once the assoc is deleted. However the keys will of course be of little interest in this case. But the program won't segfault. *Return value:* the list of keys. -- Function: void lw6sys_assoc_map (lw6sys_assoc_t * ASSOC, lw6sys_assoc_t_CALLBACK_FUNC FUNC, void * FUNC_DATA) ASSOC: the assoc to work on FUNC: a callback to call on each entry FUNC_DATA: a pointer on some data which will be passed to the callback Executes a function on all assoc items. The func_data parameter allows you to pass extra values to the function, such as a file handler or any variable which can not be inferred from list item values, and you of course do not want to make global... *Return value:* void -- Function: void lw6sys_assoc_sort_and_map (lw6sys_assoc_t * ASSOC, lw6sys_assoc_t_CALLBACK_FUNC FUNC, void * FUNC_DATA) ASSOC: the assoc to work on FUNC: a callback to call on each entry FUNC_DATA: a pointer on some data which will be passed to the callback Executes a function on all assoc items, like `lw6sys_assoc_sort_and_map' but befor doing so, sorts all entries in alphabetical order. *Return value:* void -- Function: lw6sys_assoc_t * lw6sys_assoc_dup (lw6sys_assoc_t * ASSOC, LW6SYS_DUP_FUNC DUP_FUNC) ASSOC: the assoc to duplicate, can be NULL DUP_FUNC: the function which will be called to duplicate data Duplicates an assoc. All keys will be copied so that if the first assoc is deleted, the duplicated one is fine. Additionnaly, dup_func will be called with all data fields. If dup_func is NULL, then data values will simply be copied. This is likely to be usefull when data is not dynamically allocated. *Returned value:* a newly allocated assoc. -- Function: int lw6sys_default_memory_bazooka () Will set up a default memory bazooka, a slow yet convenient tool to track down and hopefully kill memory leaks. Named bazooka after a night wasted to track down an unfoundable leak... BAZOOOOOOKA!!! *Return value:* 1 if success, 0 if failed. -- Function: void lw6sys_clear_memory_bazooka () Clears the memory bazooka. *Return value:* none. -- Function: int lw6sys_set_memory_bazooka_size (int SIZE) SIZE: number of items (calls to malloc) to keep Resizes, the memory bazooka. What's this? It's an inelegant yet efficient tool to track down memory leak. Memory bazooka will keep track of every call to malloc, keeping a trace of what has been malloced, where it has been called (from which file, which line), how much memory was allocated, it will even show you what's at the address in a 0-terminated string-friendly fashion. Of course this slows down the program, so in production, you might set this to 0, but for debugging, a million bazooka is worth the megabytes and CPU cycles it wastes. *Return value:* 1 if success, 0 if failure. -- Function: int lw6sys_get_memory_bazooka_size () The companion of `lw6sys_set_memory_bazooka_size'. This function will return how many calls to malloc can be traced. A return value of 0 indicates that feature is disabled. *Return value:* size of the bazooka array. -- Function: int lw6sys_set_memory_bazooka_eraser (int STATE) STATE: the state of the eraser Sets the memory bazooka eraser state. Note that to really work, it requires the memory bazooka to be "big enough". *Return value:* 1 if activated, 0 if not. Note that the main reason for it not to be activated is if the memory bazooka has zero size. -- Function: int lw6sys_get_memory_bazooka_malloc_count () Provided you have always called the `LW6SYS_MALLOC' an `LW6SYS_CALLOC' to allocate memory, this function will tell you how many times `malloc' has been called. *Return value:* the number of calls to `lw6sys_malloc' or `lw6sys_calloc' since program was started. -- Function: int lw6sys_get_memory_bazooka_free_count () Provided you have always called the `LW6SYS_FREE' macro to free memory, this function will tell you how many times `free' has been called. *Return value:* the number of calls to `lw6sys_free' since program was started. -- Function: int lw6sys_memory_bazooka_report () Reports memory bazooka diagnostics on the console. Carefull, this one is not reentrant, call at the end of your program when all threads are joined. *Return value:* 1 if no allocated stuff left, 0 if there are still malloc'ed stuff -- Function: char * lw6sys_build_get_package_tarname () Returns the name of the package. This is the `PACKAGE_TARNAME' constant defined by the GNU Autoconf ./configure script. While it's always possible to use the defined constant directly, using this function will return the value defined when compiling the binary, not the one you're using when compiling another program relying on Liquid War as a library. *Return value:* a non-NULL string "liquidwar6", must not be freed. -- Function: char * lw6sys_build_get_package_name () Returns the name of the package, in a user friendly form, which can include spaces, for instance. This is the `PACKAGE_NAME' constant defined by the GNU Autoconf ./configure script. While it's always possible to use the defined constant directly, using this function will return the value defined when compiling the binary, not the one you're using when compiling another program relying on Liquid War as a library. *Return value:* a non-NULL string "Liquid War 6", must not be freed. -- Function: char * lw6sys_build_get_package_string () Returns the description of the package. This is the `PACKAGE_STRING' constant defined by the GNU Autoconf ./configure script. It's the concatenation of `PACKAGE_NAME' and `VERSION'. While it's always possible to use the defined constant directly, using this function will return the value defined when compiling the binary, not the one you're using when compiling another program relying on Liquid War as a library. *Return value:* a non-NULL string "Liquid War 6 ", must not be freed. -- Function: char * lw6sys_build_get_version () Returns the version of the program. This is the `VERSION' constant defined by the GNU Autoconf ./configure script. Same as `PACKAGE_VERSION'. Note that while using a function to get `PACKAGE_TARNAME' might seem useless, having both ways to get the version, that is, a function and a constant, is very usefull. Think, for instance, that a dynamically loaded shared library might need to check its own version against the version of the core program. *Return value:* a non-NULL string, which must not be freed. -- Function: char * lw6sys_build_get_codename () Returns the the program codename. This is the little name of the version. It's been decided that all LW6 releases would take the name of a famous general, warrior, whatever. For instance, it could be "Napoleon". *Return value:* a non-NULL string, traditionnally the name of a famous general, someone which has been involved in war. Must not be freed (I mean, the string, not the general). -- Function: char * lw6sys_build_get_stamp () Returns the program stamp. This is like a serial number. It's is not the same as the version. The version is meant to be set to something readable. This is just a cryptic thing, incremented at each ./configure or each developper's "I feel like it needs to be incremented". The idea is just to keep (one more...) track of which source code is build. Ideally, this would be plugged to the source revision control system but this has some drawbacks, including that it would require it to modify files before commiting them, which is not safe, and almost impossible if you sign archives. One more point: this is a string. It's true the return value is actually a string containing the representation of an integer, but because all other build parameters are strings, and because we don't know what the future reserves, it's a string. *Return value:* a non-NULL string like "42", which must not be freed. -- Function: char * lw6sys_build_get_md5sum () Returns an md5 checkum which is caculated from C (.c and .h) source files. This is complementary with the build stamp. By default the stamp will be enough to check what has been compiled, but one can always imagine a case where Bob compiles something a little different than Alice, with the same stamp, incremented by 1 from a common source tree. They apply their own patches, for instance. This md5sum double-checks that two binaries have been built from the same sources. Note that this is not the md5 checksum of the generated binary. Nor does it include any information about scheme scripts and data. *Return value:* a non-NULL string, which must not be freed. -- Function: char * lw6sys_build_get_copyright () Returns a (very) short copyright information about the program. *Return value:* a non-NULL string, single line whithout '\n' at the end. Must not be freed. -- Function: char * lw6sys_build_get_license () Returns the license for the program (GNU GPL v3 or later). *Return value:* a non-NULL string, single line whithout '\n' at the end. Must not be freed. -- Function: char * lw6sys_build_get_configure_args () Returns the arguments passed to the GNU Autoconf ./configure script when buildling the game. Very usefull to know how the binary was generated, that is, what kind of optimizations are peculiar settings it uses. *Return value:* a non-NULL string, which, passed to ./configure again, would hopefully generate the same binary. Must not be freed. -- Function: char * lw6sys_build_get_cflags () Returns the arguments which would allow another program to use liquidwar6 as a library. Typically, pass this to gcc when compiling your sources. Basically contains "-I" switches which tell where the headers are. *Return value:* a non-NULL string, which must not be freed. -- Function: char * lw6sys_build_get_ldflags () Returns the arguments which would allow another program to link against liquidwar6. Pass this to gcc or libtool when compiling your program. Basically contains a "-L" option which says where the library is. Note that this will only allow you to link against the main libliquidwar6 library, but not the dynamically loaded modules. *Return value:* a non-NULL string, which must not be freed. -- Function: char * lw6sys_build_get_hostname () Returns the value return by the standard shell `hostname' command on the machine where the game has been built. Usefull to track binaries and know where do they come from. *Return value:* a non-NULL string, must not be freed. -- Function: char * lw6sys_build_get_date () Returns the compilation date. While this information can easily be obtained with the C `__DATE__' macro, having this function is convenient for it returns a value which is the same for the whole program, and does not possibly change in every file. *Return value:* a non-NULL string, must not be freed. -- Function: char * lw6sys_build_get_time () Returns the compilation date. While this information can easily be obtained with the C `__TIME__' macro, having this function is convenient for it returns a value which is the same for the whole program, and does not possibly change in every file. *Return value:* a non-NULL string, must not be freed. -- Function: char * lw6sys_build_get_target_cpu () Returns the CPU this program is designed for. Convenient on i386 compatible CPUs to know which flavor (i386, i586...) the binary is made for. *Return value:* a non-NULL string, must not be freed. -- Function: char * lw6sys_build_get_target_os () Returns the OS this program is designed for. Usefull for bug reports. *Return value:* a non-NULL string, must not be freed. -- Function: char * lw6sys_build_get_top_srcdir () Returns the top source directory, when the game was built. This can seem useless and non relevant on the end-user's machine, but... it's a must-have for developpers and packagers. Without this, binaries would never find their associated data, especially when building outside the source tree. Or, testing the game would be impossible without installing it, given the fact that most of the code is in scripts that are stored in /usr/local by default, this would be painfull. So this function is here to help finding data within the source tree when the game is not installed yet. Note that the function is rather clever, since it will automatically try to remove useless '../' sequences at the beginning of a possibly relative path. *Return value:* a non-NULL string, must not be freed. -- Function: char * lw6sys_build_get_prefix () Returns the `prefix' value as given to the GNU Autoconf ./configure script. Used to deduce the path to other directories and files. *Return value:* a non-NULL string, "/usr/local" by default. Must not be freed. -- Function: char * lw6sys_build_get_datadir () Returns the `datadir' value defined by the GNU Autoconf ./configure script. This is not the value which can be overriden by the Liquid War 6 specific. "-data-dir" option. `datadir' is usually something like "/usr/local/share" while the actual Liquid War 6 defined data dir is a more profound path which includes the name of the package, its version, and so on. *Return value:* a non-NULL string, "/usr/local/share" by default. Must not be freed. -- Function: char * lw6sys_build_get_libdir () Returns the `libdir' value defined by the GNU Autoconf ./configure script. This is not the value which can be overriden by the Liquid War 6 specific. "-mod-dir" option. `datadir' is usually something like "/usr/local/lib" while the actual Liquid War 6 defined module dir is a more profound path which includes the name of the package, its version, and so on. *Return value:* a non-NULL string, "/usr/local/lib" by default. Must not be freed. -- Function: char * lw6sys_build_get_includedir () Returns the `includedir' value defined by the GNU Autoconf