This is heroes.info, produced by makeinfo version 4.6 from heroes.texi.

INFO-DIR-SECTION Games
START-INFO-DIR-ENTRY
* Heroes: (heroes).              A Nibbles clone, just better.
* heroeslvl: (heroes)heroeslvl.  Inspect Heroes levels.
END-INFO-DIR-ENTRY

   This file documents Heroes, a Nibbles clone, just better.

   Copyright 2000, 2001  Alexandre Duret-Lutz

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the sections entitled "Copying" and "GNU General Public License"
are included exactly as in the original, and provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Free Software Foundation.


File: heroes.info,  Node: Top,  Next: Copying,  Prev: (dir),  Up: (dir)

Heroes
******

This document describes Heroes, a Nibbles clone, just better.

   This document applies to Heroes version 0.21.

* Menu:

* Copying::                     Your rights.
* Overview::                    Heroes in brief and contact information.
* Installation::                Installing Heroes.
* Running::                     Running Heroes.
* heroeslvl::                   Inspect Heroes levels.
* Index::                       A menu covering many topics.

 --- The Detailed Node Listing ---

Overview of Heroes

* Getting Heroes::              Where to download Heroes from.
* Mailing lists::               Where to talk about Heroes..
* Bug Reporting::               Sending bugs, suggestions, contributions.
* People::                      Contributors
* History::                     History of the DOS version.

Installation of Heroes

* Libraries::                   Libraries Heroes can link with.
* configure::                   Generic configure instructions.
* configure options::           Configure options specific to heroes.
* Relocatable package::         Building a relocatable package.
* Machines::                    Architectures where Heroes is known to work.

Running Heroes

* Invoking heroes::             Heroes launch-time options.
* Environment::                 Environment variables used by Heroes.
* heroesrc::                    Heroes configuration file.
* Global score file::           Sharing a global score file.
* Game::                        Game rules.
* Level editor::                How to create new levels.
* Troubleshooting::             Common problems.

Level editor

* editor-keys::                 Key used in the level editor.
* editor-clicks::               How mouse is used in the editor.
* tunnels::                     How to setup a tunnel.
* sprites::                     How to setup a sprite.
* animations::                  How to setup animations.
* departures::                  How to setup departures.

`heroeslvl'

* Invoking heroeslvl::          heroeslvl launch-time options


File: heroes.info,  Node: Copying,  Next: Overview,  Prev: Top,  Up: Top

Heroes Copying Conditions
*************************

Heroes is "free"; this means that everyone is free to use it and free
to redistribute it on a free basis.  Heroes is not in the public domain;
it is copyrighted and there are restrictions on its distribution, but
these restrictions are designed to permit everything that a good
cooperating citizen would want to do.  What is not allowed is to try to
prevent others from further sharing any version of Heroes that they
might get from you.

   Specifically, we want to make sure that you have the right to give
away copies of Heroes, that you receive source code or else can get it
if you want it, that you can change Heroes or use pieces of it in new
free programs(1), and that you know you can do these things.

   To make sure that everyone has such rights, we have to forbid you to
deprive anyone else of these rights.  For example, if you distribute
copies of Heroes, you must give the recipients all the rights that you
have.  You must make sure that they, too, receive or can get the source
code.  And you must tell them their rights.

   Also, for our own protection, we must make certain that everyone
finds out that there is no warranty for Heroes.  If these programs are
modified by someone else and passed on, we want their recipients to know
that what they have is not what we distributed, so that any problems
introduced by others will not reflect on our reputation.

   The precise conditions of the license for Heroes are found in the
GNU General Public License that accompanies it.

   ---------- Footnotes ----------

   (1) For instance, this section was stolen from the documentation of
GNU Texinfo.


File: heroes.info,  Node: Overview,  Next: Installation,  Prev: Copying,  Up: Top

Overview of Heroes
******************

Heroes is similar to the "Tron" and "Nibbles" games of yore, but
includes many graphical improvements and new game features.

   In it, you must maneuver a small vehicle around a world and collect
powerups while avoiding obstacles, your opponents' trails, and even
your own trail.

   There are five game modes available.  Quest is the classical
Nibbles, in Death Match you start with very long tails a must kill your
opponents, in Kill'em All you must run over lemmings moving on the
ground, in Time Cash or Color modes you must collect money or pyramids
of color.  Heroes features 12 original sound tracks, 94 levels (in 10
different tile sets) plus a level editor.

   Heroes source code originates from an original MS-DOS game but has
been heavily modified to enhance the portability and some new features
have been added.  MS-DOS support has been lost by the meantime.  The
original MS-DOS version can still be found on the Internet but is
unmaintained and should be considered obsolete.

   The current development focus on cleaning the code and port the game
to available operating systems.  Our objective is to release the version
1.0 as a clean and portable base that would allow further important
works such as network support or programmable vehicles.

* Menu:

* Getting Heroes::              Where to download Heroes from.
* Mailing lists::               Where to talk about Heroes..
* Bug Reporting::               Sending bugs, suggestions, contributions.
* People::                      Contributors
* History::                     History of the DOS version.


File: heroes.info,  Node: Getting Heroes,  Next: Mailing lists,  Prev: Overview,  Up: Overview

Getting Heroes
==============

Where to fetch new releases?
----------------------------

Heroes development is powered by the free services offered by
SourceForge to the Open-Source community.  The web page of Heroes is
`http://heroes.sourceforge.net/'.

   The latest releases of Heroes is always uploaded to SourceForge and
available from `http://sourceforge.net/projects/heroes/'.  Announces
are sent to the `heroes-announce' mailing list (*note Mailing lists::).

   Source code releases are also uploaded to Ibiblio (formerly MetaLab,
and Sunsite)) in `/pub/linux/games'; see the Ibiblio mirror list
(http://ibiblio.org/pub/linux/MIRRORS.html) to find your nearest
mirror.  You will have to wait three or four days to have the files
available on Ibiblio after a release.

   A public CVS server is also accessible.  See
`http://sourceforge.net/cvs/?group_id=7982' for details.

What to download?
-----------------

Heroes is distributed as five packages with independent version
numbering and release schedule.

`heroes'
     The source code, info file, and man page.

`heroes-data'
     The level data (level maps, sprites, etc.)

`heroes-sound-tracks'
     Sound tracks for the game (.xm files).

`heroes-sound-effects'
     The sound effects for the game (.wav files).

`heroes-hq-sound-tracks'
     High quality sound tracks (.xm files), they will replace some
     sound-tracks from `heroes-sound-track'.


   The two first packages are required, the others are optional.

   The game has been so split because the data and sound files are big
and don't evolve as often as the code does.  It would therefore be
unfair to bloat the bandwidth by requiring the mirrors and users to
download everything on each release.


File: heroes.info,  Node: Mailing lists,  Next: Bug Reporting,  Prev: Getting Heroes,  Up: Overview

Mailing lists.
==============

Three mailing lists are available for you to report bugs, discuss about
the game or get announcements of new releases.

`heroes-bugs@lists.sourceforge.net'
     A public mailing list for bug reports.

     subscription page
     (http://lists.sourceforge.net/mailman/listinfo/heroes-bugs).

`heroes-discuss@lists.sourceforge.net'
     A public mailing list for discussion (questions, criticism,
     suggestions, contributions, ...) on the game.

     subscription page
     (http://lists.sourceforge.net/mailman/listinfo/heroes-discuss).

`heroes-announce@lists.sourceforge.net'
     A read-only and low traffic list for announcements of Heroes
     releases.  Mails posted to this list are also forwarded to
     `heroes-discuss' so you don't need to subscribe to both lists.

     subscription page
     (http://lists.sourceforge.net/mailman/listinfo/heroes-announce).


File: heroes.info,  Node: Bug Reporting,  Next: People,  Prev: Mailing lists,  Up: Overview

Reporting bugs, sending suggestions or contribution
===================================================

We welcome bug reports or suggestions for Heroes (either program,
documentation, or data files).  This program will get better only if you
report the problems you encounter.  Please email them to
<heroes-bugs@lists.sourceforge.net> or
<heroes-discuss@lists.sourceforge.net>.  For bug reports, please
include enough information to reproduce the problem, if possible.
Useful information include:

   * the version number of Heroes.

   * hardware, operating system (and OS distribution), and compiler
     versions.

   * any unusual options you gave to `configure'.

   * the actions necessary to reproduce the bug.

   * a description of the problem (sometimes, a snapshot may be a good
     description) and of the behavior you are expecting (this is not
     always obvious for everyone)

   * a trace of the game, as given by running Heroes with the
     `HEROES_DEBUG' environment variable set (to `all', for instance).

   * a stack trace of the crash, if you compiled the game with debugging
     options (see below).

   * anything else that you think would be helpful.


   When in doubt whether something is needed or not, include it.  It's
better to include too much than to leave out something important.

   To get useful core dumps, `./configure' with `--enable-debug' and
`--disable-sound'.

   Patches are most welcome; if possible, please make them with `diff
-u' (*note Unified Format: (diff.info)Unified Format.) or `diff -c'
(*note Context Format: (diff.info)Context Format.) and include
`ChangeLog' entries (*note Change Log: (emacs-e20)Change Log.).

   When sending email, please do not encode or split the messages in any
way if possible; it's much easier to deal with one plain text message,
however large, than many small ones.

   Do not hesitate to contribute.  This is YOUR game and the GPL allows
you to apply any modifications you want to the game (provided that you
keep those modifications under the GPL).  There are numerous places
where you can contribute: you can hack the code (the TODO file can give
you ideas but should not be seen as a limit), design new levels, create
new drawings (e.g. new sets of tiles), track some new music or add your
personal touch here and there.


File: heroes.info,  Node: People,  Next: History,  Prev: Bug Reporting,  Up: Overview

People
======

Heroes would not be what it is presently without the following people.

Authors
-------

   * Alexandre Duret-Lutz <duret_g@epita.fr>

     Wrote the original source code, ported it to GNU/Linux and created
     a few levels.

   * Romual Genevois <rgenevois@besancon.net>

     Had the idea of that game, designed most of it, drew the graphics,
     created most of the levels.

   * Alexandre Liverneaux <alex.livernaux@wanadoo.fr>

     Composed the soundtracks.

   * Philippe Meisburger <philmeis@mail.dotcom.fr>

     Composed the soundtracks and created some levels.


Contributors
------------

   * Pierre Baillet <octplane@via.ecp.fr>

     Support for non-8bits depth video mode with LibGGI.

   * Uwe Hermann <uh1763@bingo-ev.de>

     Clean-ups and portability fixes.

   * Ingo van Lil <inguin@gmx.de>

     Latin-1 characters in fonts.


Translators
-----------

   * Hermann J. Beackers <beckers@st-oneline.de> (German)

   * Jos Boersema <joshb@xs4all.nl> (Dutch)

   * Luzemario Dantas Rocha <luza.solucao@uol.com.br> (Brazilian
     Portuguese)

   * Alessandro Dotti <alessandro.dotti@libero.it> (Italian)

   * Alexandre Duret-Lutz <duret_g@epita.fr> (French)

   * Ingo van Lil <inguin@gmx.de> (German)

Packagers
---------

   * Daniel Burrows <Daniel_Burrows@brown.edu> (Debian GNU/Linux)

   * Jean Delvare <delvare@ensicaen.ismra.fr> (RPM & Slackware Linux)

   * Eugenia Loli-Queru <eloli@hotmail.com> (BeOS)

   * Pascal Rigaux <pixel@mandrakesoft.com> (Linux-Mandrake)

   * Maxim Sobolev <sobomax@FreeBSD.org> (FreeBSD)

Porters
-------

   * Ste'phane Denis <S.Denis@darkworks.com> (Win/Visual C)

   * Mattias Engdegaard <f91-men@nada.kth.se> (Solaris)

   * Maxim Sobolev <sobomax@FreeBSD.org> (FreeBSD)

   More people are listed in the file `THANKS' at the top level of the
Heroes tarball.


File: heroes.info,  Node: History,  Prev: People,  Up: Overview

History of the DOS version
==========================

The next paragraphs are extracted from the DOS version of Heroes.

   We started this game in summer 96. The idea came form Guen.  At this
moment, we were only three: Guen, Toalnkor (now known as Tnk) and me
(Pollux); Alexel joined us one year later.  The development was going
quite slow (it took us two years actually) mainly because of our
studies.  Maybe the fact that Guen and me communicated by (snail-)mail
was another slowing down factor.  I sent more than 60 letters to Guen
during this two years !  During the first year, we decided to sell the
game.  We made a demo version (with only 10 levels, no editor, and an
order form), and a CD version (with songs remixed on audio track, but
not used in the game).  Our main issue was the price of Midas' license
(the sound engine used); we were also hesitating on the way we should
distribute Heroes (shall we do it shareware or commercial ?).  Finally,
after a couple of wasted months we decided to spread it freeware (Enjoy
!), because we thought that no one would really like to buy such a game
today; today where 3D rules.

   Now let's talk about the content of the game.  At first, Tnk decided
to make some four channels songs in the old original mod format.  As
there were only two scores done and we were waiting for the next tunes,
we used some songs from Clawz just to vary. These were 'overtaking' and
'hibakusha2' and gave a better taste to the game.  So we removed old
Tnk's songs and he was asked to make some more Clawz-like musics. By the
time, Alexel joined and came with 10 channels XM, thus all tunes are now
8 or 10 channels XM... There were 13 tunes in the game (for a total of
2.88Mb unpacked), these are the intro tune, the menu tune, the 10
levels, and the end tune (you can't hear the later without finishing
the quest game); most of them have been done by Alexel.

   All sprites and pictures were drawn by Guen.  He first made some
level-tiles and a set of hand-done previews of the game before any other
work get started (I guess he has a few other projects at this state of
development at home).  These screens and tiles were used to make the
level editor.  Actually I learned C while making this editor so there
is some piece of code I am not proud of into (and also in the game).
When it was nearly done, I started to code the game.  The first thing
done was the introduction, and then came the multi-directional
scroller.  I remember that the first level which was loaded was sized
4x4 and wrapped in all directions; this was very small but at this time
there were no tails and the vehicles were crossing the walls...

   Most of the levels were done by Guen. But Tnk and I also did some.
Guen made a cleanup of all the levels we made: some were relegated in
the EXTRALVL directory, other were simply erased. We aimed to spread
the game with 100 of them, but as it is going late and that we are not
going to sell the game anymore I don't know how many levels there will
be.


File: heroes.info,  Node: Installation,  Next: Running,  Prev: Overview,  Up: Top

Installation of Heroes
**********************

* Menu:

* Libraries::                   Libraries Heroes can link with.
* configure::                   Generic configure instructions.
* configure options::           Configure options specific to heroes.
* Relocatable package::         Building a relocatable package.
* Machines::                    Architectures where Heroes is known to work.


File: heroes.info,  Node: Libraries,  Next: configure,  Prev: Installation,  Up: Installation

Needed Libraries
================

Heroes can be configured to use several libraries to handle display,
sound output and joystick support.  Following is a list of supported
libraries (hopefully you won't have to install all of them but just a
subset).

   * LibGGI (General Graphic Interface) can be used as a display and
     keyboard driver. Get it from `http://www.ggi-project.org/'.

   * LibGII (General Input Interface) will provide joystick support
     (the game can be compiled without).  Get it from
     `http://www.ggi-project.org/'.  It is needed by LibGGI, by the way.

   * SDL can be used as a display and keyboard driver.  Recent
     revisions will also provide support for joysticks.  Get it from
     `http://www.libsdl.org/'.

   * Allegro, a game programming library, can be used as a display,
     keyboard, and joystick driver.  `http://alleg.sourceforge.net/'.

   * LibMikMod is a sound library. You don't need it if you want to
     compile Heroes without sound support.  Get it from
     `http://www.mikmod.org/' or from
     `ftp://ftp.ibiblio.org/pub/linux/apps/sound/libs/'.  If you
     install LibMikMod from sources you may want to compile LibMikMod
     without Alsa support (*note Troubleshooting::).

   * SDL_Mixer is an alternative sound engine that can be used only if
     you use SDL as display driver. You don't need it if you want to
     compile Heroes without sound support.  Get it from
     `http://www.devolution.com/~slouken/SDL/projects/SDL_mixer/'.


   To summarize, install at least LibGGI, SDL, or Allegro to get video
output and keyboard handling.  Install LibGII to get joystick support,
unless you use a recent SDL or Allegro.  And install LibMikMod (or
SDL_mixer if you have SDL) if you want sound output.

   My personal preference goes to LibGGI/LibGII and LibMikMod which give
you more control over the drivers used.  On the other hand, SDL seems
better at doing full screen display and is maintained actively.  Allegro
is quite new on Unix.

   Heroes also supports memory debugging libraries, such as `dmalloc' or
`efence'.  See the `--enable-mem-debug' option in section *Note
configure options::.


File: heroes.info,  Node: configure,  Next: configure options,  Prev: Libraries,  Up: Installation

configure generic instructions
==============================

To be filled.


File: heroes.info,  Node: configure options,  Next: Relocatable package,  Prev: configure,  Up: Installation

configure options for Heroes
============================

`configure' will do its best to find the libraries and functions needed
by the game.  Still, you may give several options to `configure' to
help it, or to fine tune special features of Heroes.

`--enable-html-doc[=DIR]'
     Build and install html documentation in directory `DIR'.  If `DIR'
     is not given, install in `$datadir/heroes/doc'.

`--disable-sound'
     Turn off sound support. Sound is enabled by default, unless no
     sound engine is found).

`--disable-joystick'
     Do not include joystick support in the game.  Joystick support is
     enabled by default, unless you don't have GII or joystick support
     in SDL.

`--with-sdl[=DIR]'
     Specify that you want to link with SDL.  This is the default if
     LibGGI is not installed.  If you installed SDL in some
     non-standard place, you can specify the installation path as an
     argument.  For example:
          ./configure --with-sdl=/home/adl/usr
     `configure' will then look for `/home/adl/usr/bin/sdl-config' and
     configure Heroes accordingly.

`--with-ggi[=DIR]'
     Link with LibGGI.  This is the default if LibGGI is installed.  If
     you installed LibGGI in some non-standard place, you can specify
     the installation path as an argument

`--with-allegro[=DIR]'
     Link with Allegro.  This is the default is neither LibGGI not SDL
     can be used.  If you installed Allegro in some non-standard place,
     you can specify the installation path as an argument

`--with-mikmod[=DIR]'
     Use LibMikMod four sound output.  This is the default if LibMikMod
     is installed and LibGGI have been selected.  You may specify where
     LibMikMod is installed using the optional argument.

`--with-sdl-mixer[=DIR]'
     Use SDL_mixer for sound output.  This is the default if SDL_mixer
     is installed and SDL has been selected.  You may specify where
     SDL_mixer is installed using the optional argument.  Using this
     option implies `--with-sdl'.

`--disable-heroes-debug'
     Turn off tracing support.  See the description of the
     `HEROES_DEBUG' variable (*note Environment::).  This is enabled by
     default to facilitate bug reporting.  Using this options should
     reduce the size of the resulting binary, and speed up the game by
     an indiscernible amount.


   The following options are for developing purpose.  The default
configuration should be suitable for end users (i.e. players) but people
attempting to hack the code may want debugging symbols or compiler
warnings.

`--enable-debug'
`--disable-debug'
     This is a three state option.  The default is to compile with
     debugging symbols: this produce bigger binaries but allow to get
     helpfull coredumps, without slowing down the game.  You may want
     to use `--enable-debug' to include more debugging data and turn on
     some debugging code.  Use `--disable-debug' to turn this off.
     Translators: you _do want_ to turn this option on, really!  Because
     the debugging code includes some checks on the translated messages.

`--disable-optimizations'
     Turn off compiler optimizations options.  This can ease debugging.
     If you want to supply your own optimizations options, use
     something like `--enable-optimizations='-O3 -march=pentium''.

`--enable-warnings'
     Try to turn on a large bunch of compiler warnings.

`--enable-assert'
     Turn on some assertions squattered over the source code.  This can
     slow down things a bit.

`--enable-devel'
     Is a shorthand for `--enable-debug --disable-optimizations
     --enable-warnings --enable-assert'.

`--with-mpatrol'
     Link with MPatrol, a `malloc()' debugger.

`--with-mtrace'
     Use GNU libc's `mtrace()' facility to check `malloc()' usage.

`--with-dmalloc'
     Link with Dmalloc, a `malloc()' debugger.

`--with-efence'
     Link with Electric Fence, a `malloc()' debugger.

`--enable-mem-debug'
     Check for `mtrace()', Dmalloc, or Electric Fence.  Use the first
     found.

`--enable-gprof'
     Enable profiling support with `gcc', you need `gprof' to inspect
     the file resulting from a run of Heroes.

`--disable-display'
     This disable all screen output, making the game rather unplayable.
     This suppress decencies over third party libraries like GGI or SDL,
     therefore you may find it useful with some debugging tools like
     checkergcc.



File: heroes.info,  Node: Relocatable package,  Next: Machines,  Prev: configure options,  Up: Installation

Building a relocatable package
==============================

"Relocation" refers to the ability to install or move the game in a
directory which is different from the one it has been configured for.
This usually happens if you create a binary package for Heroes and
don't know in advance where the user will unpack it.  This section
describe how Heroes find for his files, in order to allow relocatable
packages.  Most people don't need to read this section, only packagers
might be interested.

   The values of the `./configure' options you used to specify
directories (such as `--prefix', `--bindir', or `--datadir') are all
transformed into paths relative to PREFIX and then hardcoded into the
Heroes binary.  Because Heroes uses only paths relative to PREFIX, the
relocation process is just a matter of guessing the correct value of
PREFIX at runtime.  This guess is done using various informations
available: first the original value of PREFIX is tried, then PREFIX is
computed from the path to the current binary (`argv[0]') when
available, then the content of the environment variable `PATH' is used
to find the binary and derive PREFIX, finally Heroes assumes it is
running from the BINDIR directory.  The whole process is not garanteed
to succeed, but you can also override those paths with some enivronment
variables (*note Environment::).


File: heroes.info,  Node: Machines,  Prev: Relocatable package,  Up: Installation

Machines
========

Heroes has been reported to compile and run on the following
architectures.  Since Heroes can use SDL, GGI, or Allegro as display
driver, the following list shows the driver which was used.

Linux/i386 (GGI, SDL, or Allegro)
     Should build out of the box.  Packages for some Linux distributions
     are available from the web pages.

     Suse 7.1 users, the libc shipped with your distribution
     (glibc-2.2-7) will crash every time Heroes calls the `ngettext()'
     function.  The workaround is to configure Heroes with `configure
     --with-included-gettext' so that it uses its own version of
     `ngettext()'.

     Red Hat 7.0 users, the compiler shipped with your distribution
     (packaged as `gcc-2.96-54.i386.rpm') is an experimental version
     which is still _bugged_ despite the pile of fixes applied.  It
     actually produces unfaithful code for Heroes, so please use
     another compiler.  Either upgrade to a newer version
     (`gcc-2.96-64.i386.rpm' is known to work) or use the one provided
     by the `kgcc' package.

Linux/m68k (SDL)
     Is reported to work when the sound (`SDL_mixer') is disabled
     (`configure --disable-sound' or `heroes -S').  Any feedback on
     this issue is welcome.  See also the `BUGS' file.

FreeBSD (SDL)
     Should build out of the box.  Packages are available from the web
     pages.

Solaris (SDL)
     Should build out of the box.

Win32/MinGW32 (SDL)
     Can be cross-compiled (native compilation untested).  The script
     used to cross build the Heroes package available on the web page
     is in the subdirectory `arch/mingw32'.

Win32/VisualC (SDL)
     See the files in the `arch/VisualC' subdirectory of the Heroes CVS
     tree.  We used to distribute these files along with the rest of the
     sources, but stopped because they are now completely out-of-date
     (they have not been updated since version 0.7).  However you can
     use them as a start point if you think about compiling Heroes with
     MSVC.

Digital Unix (GGI)
     Should build out of the box.

NetBSD (SDL)
     I had to tweak SDL 1.1.6 to get it working, and also force Heroes'
     configure to use the result of `sdl-config --static-libs' instead
     of `sdl-config --libs'.  Both issues should be fixed today (FIXME:
     need to check).

OpenBSD 2.9 (GGI & SDL)
     It looks like some configure hints need to be given when using
     either libs.

     A build of Heroes configured with GGI will apperently complete
     successfully, however the resulting binary fails to load, with the
     dynamic loader complaining about a missing symbol from libpthread.
     So you'd rather configure Heroes with
          ./configure --with-ggi=/usr/local LDFLAGS=-pthread
     Then Heroes appears to work fine.

     If you prefer to use SDL, things are different. I had to configure
     Heroes with
          ./configure --with-sdl=/usr/local LDFLAGS=-L/usr/X11R6/lib X11BASE=/usr/X11R6
     Unfortunately, the resulting binary froze when initializing SDL (in
     `SDL_init()').  Please send us a note if you are luckier.  FIXME:
     Look how other packages using SDL are built, I'm probably missing
     something.

IRIX 6.5 (SDL)
     Heroes 0.7 has been reported to compile and run with SDL 1.1.3 and
     `gcc' + libraries from `freeware.sgi.com' on IRIX 6.5.

BeOS (SDL)
     Heroes 0.9 has been reported to compile and run out of the box.


   If you got Heroes working on a platform which is not listed here,
please send a notice to <heroes-discuss@lists.sourceforge.net>.


File: heroes.info,  Node: Running,  Next: heroeslvl,  Prev: Installation,  Up: Top

Running Heroes
**************

* Menu:

* Invoking heroes::             Heroes launch-time options.
* Environment::                 Environment variables used by Heroes.
* heroesrc::                    Heroes configuration file.
* Global score file::           Sharing a global score file.
* Game::                        Game rules.
* Level editor::                How to create new levels.
* Troubleshooting::             Common problems.


File: heroes.info,  Node: Invoking heroes,  Next: Environment,  Prev: Running,  Up: Running

`heroes' options
================

Heroes call be launched with various options.

`-v'
`--version'
     Display Heroes version number and copyright informations.

`-h'
`--help'
     Print a help message about these run-time options.

`-q'
`--quiet'
     Disable warning messages.  This can be useful on platform such as
     Windows were such messages will pop up a text window.

`-Q'
`--really-quiet'
     Same as `-q', but disable error messages too.

`-vOPTIONS'
`--verbose=CHANNELS'
     Enable debugging output.  `CHANNELS' can take the same values as
     `HEROES_DEBUG' (*note Environment::).

`-lWORD'
`--list=WORD'
     Show various internal information.  `WORD' can be `debug',
     `levels', `preferences', `resources', `sound-drivers', or
     `sound-tracks'.

     `--list=debug' will list the available debugging channel, to be
     used with `--verbose' or `HEROES_DEBUG' (*note Environment::).

     `--list=levels' displays the list of installed levels (only the
     game levels, not the extra levels).

     `--list=sound-drivers' is used to print LibMikMod's drivers list.
     The expected output is something like this:
          % heroes --list=sound-drivers
          LibMikMod version 3.1.7
          
          Available drivers:
           1 Enlightened sound daemon (EsounD) driver v0.2.12
           2 Advanced Linux Sound Architecture (ALSA) driver v0.3.2
           3 Open Sound System driver v1.5
           4 Raw disk writer (music.raw) v1.1
           5 Wav disk writer (music.wav) v1.2
           6 Piped Output driver v0.1
           7 Standard output driver v1.1
           8 Nosound Driver v3.0

     `--list=resources' will dump the list of file resources.  File
     resources are kinds of aliases used internally to name files and
     directories.  They can be overwritten in you configuration file
     using the `setrsc:' command.  This command will also list the
     original (default) value of the resource if it has been
     overwritten.

     `--list=sound-tracks' will print the list of sound-tracks used in
     the game in a format compatible with the `soundconf:' command
     (*note heroesrc::).

     `--list=preferences' will print the preferences and their values,
     as they would be saved in `~/.heroes/preferences'.

`-d N[,OPTIONS]'
`--driver=N[,OPTIONS]'
     With LibMikMod, specify the driver to use. `N' is the number of the
     driver taken from the output of `heroes --list=sound-drivers'. Use
     `0' for auto-detection.  Additional options can be given to the
     driver, see LibMikMod's `README' file.

     With SDL_mixer, override some audio parameters.  `freq' and
     `buffers' are the two recognized parameters.  Example
          heroes -d freq=11050:buffers=512

`-S'
`--no-sound'
     Disable sound output completely (both sound tracks and sound
     effects).

`-X'
`--no-sfx'
     Disable sound effects only.

`-m'
`--mono'
     Output sound in one single channel.  This has no effect if the
     game is compiled without sound support, of course.

`-8'
`--8bits'
     Output sound in 8bits, rather than 16.  You will need this option
     if you have an old sound card that can't play 16bits samples.

`-i'
`--high-quality'
     When compiled with MikMod, use the high quality software mixer.
     This mixer is somewhat more expensive, but you can expect a better
     sound quality.  When compiled with SDL_mixer, output sound in
     44kHz instead of 22kHz.

`-G OPTIONS'
`--gfx-options=OPTIONS'
     Give additional options to the display driver.

     With GGI applications, the usual way to force the selection of a
     driver is to define the `GGI_DISPLAY' environment variable.  The
     usage and possible values of this variable are documented in the
     file `target.txt' which comes with LibGGI.  If Heroes has been
     compiled with GGI, the option `-G' will bypass the setting of
     `GGI_DISPLAY', as if the variable was overwritten.  For instance
          % heroes -G 'tile:0,0,160,200,(x):160,0,160,200,(x)'
     is equivalant to
          % export GGI_DISPLAY='tile:0,0,160,200,(x):160,0,160,200,(x)'
          % heroes
     except that the former does not modify `GGI_DISPLAY'.  (BTW, the
     above setting uses GGI's tile driver to display Heroes in two
     half-windows... this maybe quite fun to try in two player mode.)

     It is also possible to prevent Heroes' GGI driver to request a 8
     bit mode with `-G not8'.  This is necessary on some uncommon X
     setup to workaround a bug in GGI (*note Troubleshooting::).  Other
     legitimate GGI settings maybe supplied after a colon, as in `-G
     not8:x'.

     As SDL applications are concerned, selection of the video driver is
     achieved through the `SDL_VIDEODRIVER' environment variable.  At
     the time of writting this is not documented in SDL, so you will
     have to either RTFS or guess the possible values.  If Heroes has
     been compiled with SDL, the option `-G' with override the setting
     of `SDL_VIDEODRIVER'.  For instance you could force SDL to use the
     X11 driver with
          % heroes -G x11
     or
          % export SDL_VIDEODRIVER=x11
          % heroes

`-F'
`--full-screen'
     If Heroes is compiled with SDL, this option will turn on full
     screen mode.

     Otherwise, if Heroes is compiled with GGI, this option will allow
     Heroes to use a video mode with any size; i.e., the video surface
     is not constrained to 320x200 and Heroes will just center its
     320x200 output.  The rational is that GGI's DGA driver doesn't
     switch video modes.  So unless your X server run in 320x200 it
     would be hard to use the DGA driver otherwise.  Here is the
     typical settings for "full-screen" DGA output:
          % heroes -G dga -F
     Admittedly the name of `--full-screen' is quite misleading here
     since this option can provide you with a 320x200 stamp centered on
     your 1600x1200 display...

`-2'
`--double'
     Stretch the game twofold before blitting to screen.  This is slow.

`-3'
`--triple'
     Stretch the game threefold before blitting to screen.  This is
     even slower.

`-4'
`--quadruple'
     Stretch the game fourfold before blitting to screen.  This has been
     requested by people which can run `heroes -3' smoothly.

`-e'
`--even-lines'
     Display only even lines, leaving blank scan lines as on real
     arcade monitors.  This will contribute to make options `-2', `-3'
     and `-4' faster.

`--cpu-off'
     Disable computer opponents driving.  The opponents are still there
     (there will always be four players) but they are no more driven:
     they turn when they hit wall.  You won't want to use this options,
     it is here for historical reason: when the game was started in
     1996 this used to suppress some overhead on slow machines.

`--default-scores'
`--default-options'
`--default-saves'
     Don't read the corresponding file, but use default value instead.
     The files will be saved at the end of the game anyway, so you can
     use these options to revert the default value of the given file.
     Another way to do this is simply to delete the file, it will be
     created the next time Heroes run.

`-s'
`--swap-sides'
     Swap sides when playing in two player mode.  The default is to have
     player one on the right and player two on the left, because the
     default key bindings use the arrows for player one and left
     letters keys for player two.

`--no-double-fx'
     Disable superposition of rotozoom and waves.  This is also a
     prehistoric option.  These two visual effects lead to a small
     overhead that one may not want to combine on a slow host.

`-g'
`--go'
     Skip the game introduction, start right on the main menu.

`-J'
`--no-joystick'
     Disable joystick handling.  Most of the time you will use this
     because you don't have a joystick and are annoyed by the warning
     message output when heroes start.



File: heroes.info,  Node: Environment,  Next: heroesrc,  Prev: Invoking heroes,  Up: Running

Environment variables
=====================

`HEROES_DEBUG'
--------------

The very first action of Heroes when it starts is to look the
environment for a `HEROES_DATA_DIR' variable.  If Heroes has been
compiled with the `--enable-heroes-debug' configure option (which is
the default), this variable specify the kind of debug messages that
should be printed out.  Possible values are the following (they can be
printed using the `--list=debug' option).

`SECTION'
     The different parts of the game (introduction, demonstration,
     menus, ...).

`SYSTEM'
     Handling of environment variables, creation of directories,
     initialization of libraries.

`RESOURCE'
     Filename Resources Handling.

`FILE'
     Files And Directories Handling.

`LEVEL'
     Levels Handling.

`SOUND_TRACK'
     Sound Track Events.

`SOUND_EFFECT'
     Sound Effects Events.

`VIDEO'
     Events related to the display interface.

`JOYSTICK'
     Joystick Initialization And Events.

`TIMER'
     Timer Handling.

`MISC'
     Miscellaneous Events.

`FADER'
     Palette Fade Events.

`BONUS'
     Bonus handling.

`ALL'
     All of the above.

   Multiple values can be separated by `:', and a value is negated if
prefixed by `-'.  For example the following command line sets
`HEROES_DEBUG' so that all messages get printed except those related to
timer handling.

     export HEROES_DEBUG=all:-timer

`HEROES_PREFIX'
---------------

The `HEROES_PREFIX' indicate the base directory where Heroes was
installed.  It is equivalant to the `--prefix' option of `configure'.
This variable is not found the default prefix (configured at build
time) will be used, usually this is something like `/usr/local' or
`/usr'.  Type `heroes --list=resources | grep prefix' to see the value
actually used by Heroes.

   Most people don't need to set this variable.  This is only useful if
you got Heroes as a binary distribution and want to move files around.

`HEROES_DATA_DIR'
-----------------

The `HEROES_DATA_DIR' variable may specify the path were the data files
are located.  It thus allows you to relocate the data file.  If this
variable is not found the default path (configured at build time) will
be used.  Run `heroes --list=resources | grep data-dir' to see the
value actually used by Heroes.

   The path to datafiles is adjusted automatically if you set
`HEROES_PREFIX' (because it is a subdirectory of `HEROES_PREFIX'), so
most people don't need to set `HEROES_DATA_DIR'.

`HEROES_LOCALE_DIR'
-------------------

The `HEROES_LOCALE_DIR' variable override the path were the message
catalogs are looked for.  The default value is hardcoded into the
Heroes binary, and you can see it if you run `heroes --list=resources |
grep locale-dir'.

   As for `HEROES_DATA_DIR', changing `HEROES_PREFIX' is usually enough
because `HEROES_LOCALE_DIR' is a subdirectory of `HEROES_PREFIX'.

`HOME'
------

The `HOME' variable is used to locate your home directory.  You can
also use `HEROES_HOME'.


File: heroes.info,  Node: heroesrc,  Next: Global score file,  Prev: Environment,  Up: Running

`~/.heroes/heroesrc'
====================

Each time you start heroes, it tries to read the system-wide
configuration file `heroesrc' (in the `$datadir/heroes/etc/' directory)
and from the `~/.heroes/heroesrc' in your home directory.

`option:'
---------

You can specify options in that file, they will be processed before any
options given on the command line.  Put the word `Options:' in front of
a line, and write the options after (separated by spaces, as on the
command line, except that there is no quoting or variable
substitution).  For example, if you want that Heroes always skip the
introduction, and swap the player sides, add the following line to your
`~/.heroes/heroesrc':

     Options: -g -s

   Multiple `Options:' lines can be given, they are processed in order.

`setenv:'
---------

You can also have line starting with `setenv:', followed by a variable
name and a value (the rest of the line, after the variable name is
taken as the value).  This will setup the corresponding environment
variable.  This provide a way to configure the used libraries.  For
example, to instruct SDL to use its DGA driver, use the following line:
     setenv: SDL_VIDEODRIVER dga

   This may seam redundant with `--gfx-options' and `--driver' but can
be used to configure other libraries.  For example, setup GGI or SDL to
use AAlib (the ASCII art rendering library) and configure AAlib via its
`AAOPTS' variable.

`extradir:'
-----------

Lines starting with `extradir:' are used to specify additional extra
levels directories.

`soundconf:'
------------

The `soundconf:' lines are used to introduce configuration files
defining the sound tracks played by the game.  The format of such files
is as follow:
     ALIAS:FILENAME:TITLE:AUTHOR
     ...
   Where `ALIAS' is the name of the sound track used internally by
Heroes, `FILENAME' is the filename of the sound track you want to be
loaded, `TITLE' is the title of the sound track, and `AUTHOR' is the
person who tracked that music.

   You may give several definitions for the same alias, in which case
only the latest will be used (and of course your configuration file is
read after heroes has setup its default aliases so you can overwrite
them).

   Presently the set of used aliases include
`INTRO',`MENU',`HEROES01',`HEROES02',...,`HEROES10', and `ENDSCROLL'.
You can overwrite them, but you can also define your own aliases: they
will be available in the jukebox menu.

   To give one full example, imagine you want to hear
`/music/2nd-reality.s3m' when you are playing Heroes in the second
world (desert and pyramids).  What you do is this
     % cd ~/.heroes
     % echo "HEROES02:/music/2nd-reality.s3m:\
     Second Reality:Purple Motion" > mymod
     % echo "soundconf: /home/adl/.heroes/mymod" >> heroesrc

   In this example, the configuration file has been put in the
`~/.heroes' directory but you can put it anywhere provided the filename
given after `soundconf:' points to it.

   All that sound configuration stuff should allow you to make drop-in
replacement for heroes modules.  You just make a set of modules
available with a configuration file that any user can get read from its
`~/.heroes/heroesrc'.

   You can run `heroes --list=sound-tracks' to print the list of
sound-tracks used by heroes, and hence verify the correctness of your
configuration.

`setrsc:'
---------

This follow the same format as `setenv' but is used to overwrite some
filenames used by the game.  Heroes internally handles file or
directory names using name aliases called file resources whose values
(actual filenames) can be overwritten by `setrsc' and are subject to
variable expansion.

   The command `heroes --list=resources' will list all the resources
used by the game.  `data-dir' is a special resource which content is
setup from the `HEROES_DATA_DIR' environment variable, or from the path
used to install the files when the game was built. `home-dir' is
initialized from the `HOME' environment variable.

   An example of `setrsc:' usage is to run the game with an alternate
picture file.  Say you are working on a modified version of the main
font used in the game, you can override the installed picture by yours
with the following line.

     setrsc: main-font /home/adl/heroes-dev/tmp/fontem.pcx

`keepsgid:' and `keepsuid:'
---------------------------

By default, if Heroes has a sgid-bit or suid-bit, it will drop all
privileges once the score and saved games are open.  This happens
before the user configuration is read, and therefore before the display
and sound are initialized.

   Sometime you do not want these privileges to be dropped because your
setup requires them.  For instance your display driver might require
read/write access to /dev/mem, or a similar requirement may exist for
the sound library).

   `keepsgid: yes' and `keepsuid: yes' can be used to instruct Heroes
to keep the s-bit privileges for its whole life.  These commands can
only be used in the system-wide configuration file.


File: heroes.info,  Node: Global score file,  Next: Game,  Prev: heroesrc,  Up: Running

Sharing a global score file
===========================

In its default configuration, Heroes will create a score file in each
user's directory.  However you may want to share a global score file for
many users.  This can easily be done by redefining the filename used by
Heroes to read and write the score file.  This filename is a resource,
so it can be overwritten in an `heroesrc' configuration file.

   If you are the installer of Heroes, you can do this from the system
wide `heroesrc' with a line like the following
     setrsc: score-file $(sys-dir)/scores

   The same considerations apply to saved games (`saved-games-file').

   `$(sys-dir)' is another resource the value of which defaults to
`/var/games/heroes'.  According to the Filesystem Hierarchy Standard
this is the place where you should store modifiable game files.  If you
need to change this, simply add another `setrsc:' line:
     setrsc: sys-dir /site/var/games/heroes
   By the way, you will have to create the `$(sys-dir)' directory
yourself, because Heroes is not smart enough (and probably doesn't have
the right to create that directory anyway).

   Now you have to make several choices regarding the policy for
granting access to that file.  This is a global score files, so you
need to devise a setup which allows Heroes to write that file whoever
run the game.  The most straightforward way to allow this is to create
the `scores' file with `666' permission... you probably don't want to
do this because everybody would be allowed to damage the file.

   A cleaner idea is to create a special user or group to own that file,
and grant `heroes' the appropriate rights (set-user-id or
set-group-id).  Setting `heroes' as a set-user-id program is a security
problem, because if someone manage to get `heroes' to execute arbitrary
code, he can have the game overwriting itself.  So the correct solution
is to set `heroes' as a set-group-id program, and make the score file
writable only by that group.  At worse, if someone manage to break into
`heroes', s/he will only be able to damage the score file.

   Here is a sample setup where `heroes' is configured as a
set-group-id program for a group called ``games'':
     % cd /usr/games && ls -l heroes
     -r-xr-sr-x    1 root     games     2074633 Mar 25 22:29 heroes
     % cd /var/games/heroes && ls -la
     drwxr-xr-x    2 root     games        4096 Mar 25 22:35 ./
     drwxr-xr-x    4 root     root         4096 Mar 25 19:59 ../
     -rw-rw-r--    1 root     games        2291 Mar 25 22:35 scores
   Note that `/var/games/heroes' is not writable by group `games', so
you have to create the file `scores' before Heroes can use it.

   When `heroes' is run as a set-group-id or set-user-id program, it
executes some code to drop this privilege whenever possible.  Basically,
it will revert its effective-group-id and effective-user-id to the
player's group-id and user-id on startup and only switch back to it's
file-group-id and file-user-id when it needs to write to a file in the
`$(sys-dir)' directory.  This is what the `$(sys-dir)' resource is for:
a file which is beyond that directory is opened with the
file-group&user-id (i.e. group `games' in the above example), any other
file is opened using the player's group(s) and user-id.  The visible
consequence is that files created in the `~/.heroes' directory won't be
owned by group `games' (or whatever you chose).

   Finally, note that Heroes does keep track of how a resource has been
setup, and wont switch persona when `$(sys-dir)' or `$(score-file)' has
been setup in a non-trusted way.  Roughly, all hard-coded and
system-wide settings are trusted, while the user's personal settings
are untrusted.


File: heroes.info,  Node: Game,  Next: Level editor,  Prev: Global score file,  Up: Running

Game
====

Heroes has an `INFO' menu, that should describe the different game modes
and options, with pictures and colors.  Please refer to it until this
section is written.


File: heroes.info,  Node: Level editor,  Next: Troubleshooting,  Prev: Game,  Up: Running

Level editor
============

The level editor is available from the `editor' entry in the main menu.
Created levels will be stored in your `~/.heroes/levels' directory.

   This editor is a cut down version of the one that served us to build
all 100 levels of this game.  This one will allow you to construct your
own levels in a quite simplified manner.

   On the left side of the screen, you can see a part of your level.
You can move with keyboard or mouse (read the two next sections).  In
the middle of the screen you can see the set of all the available tiles.
You will pick tiles here to build you level.  And on the right there is
some informations about the level and the selected (orange box) tile.

* Menu:

* editor-keys::                 Key used in the level editor.
* editor-clicks::               How mouse is used in the editor.
* tunnels::                     How to setup a tunnel.
* sprites::                     How to setup a sprite.
* animations::                  How to setup animations.
* departures::                  How to setup departures.


File: heroes.info,  Node: editor-keys,  Next: editor-clicks,  Prev: Level editor,  Up: Level editor

Editor keys
-----------

Here is the list of keys used in the level-editor.  You will have to
learn most of them because most of these actions are available only as
key-bindings.

`<F3>'
     Toggle sprite and vehicle display.

`<F5>'
     Toggle collide tests display.

`<ESC>'
     Quit and save.

`<Ctrl>-<Left>'
`<Ctrl>-<Right>'
`<Ctrl>-<Up>'
`<Ctrl>-<Down>'
`<Ctrl>-<PageUp>'
`<Ctrl>-<PageDown>'
`<Ctrl>-<Home>'
`<Ctrl>-<End>'
     Move the cursor in the tiles side.

`<Left>'
`<Right>'
`<Up>'
`<Down>'
     Move the cursor in the level side.

`<SPC>'
     Copy a tile.

`<d>'
     Setup starting positions on the selected tile.

`<Ctrl>-<f>'
     Fill the whole level with the selected tile.

`<Meta>-<f>'
`<Alt>-<f>'
     Fill the whole level with the two first tiles (for the 10th set of
     tiles).

`<p>'
     Output the level map as a big `pcx' file.  The file is saved in the
     current directory, and the file name is made by appending `.pcx' to
     the level name.

`<s>'
     Copy a sprite, or remove a sprite.

`<t>'
     Select the tile for tunnel destination.

`<RET>'
     View the level map in full screen.

`<Ctrl>-<RET>'
     Play animations.



File: heroes.info,  Node: editor-clicks,  Next: tunnels,  Prev: editor-keys,  Up: Level editor

Editor clicks
-------------

You can select a tiles by clicking on it with the left mouse button.
Keeping this button pulled down will allow you to move the map without
using the keyboard.

   The middle button (if you have one) used in the left side will
temporally select a tile, as if you were using the `t' key.

   The right button, used in the left side, will copy a tile to the
pointed tile, in a way it behaves like the space key.


File: heroes.info,  Node: tunnels,  Next: sprites,  Prev: editor-clicks,  Up: Level editor

Tunnels
-------

Copy your two tiles that are the entrances of your tunnel.  Move the
box-pointer on one, and select it if the `<t>' key (or click on it with
the middle button).  Once you will move the pointer, this tile will
appear in a dashed box.  Move on the second tunnel and click on the
`[GO TO]' box that is on the right of your screen.  Now you have set up
the first way: for now if your were playing on this level you could go
from this place to the dashed one, but from the dashed to this one.  So
you also have to set up the tunnel in the other way: select the current
tiles with `<t>', move on the former and click on `[GO TO]'. That's all.

   Notice that with this technique you can also typeset some kind of
triangular tunnel. Let `A', `B', `C' be the entrances, you could setup
the way like that `A->B', `B->C', and `C->A'.

   The coordinate `0x0' if used for the destination denotes a non-setup
way.  That's why you can't put a tunnel on the `0x0' position.


File: heroes.info,  Node: sprites,  Next: animations,  Prev: tunnels,  Up: Level editor

Sprites
-------

With some set of tiles (like the Egyptian one), there are tiles (like
palm trees) designed to be used as `sprites', i.e. put over others with
transparency. You have to use the `<s>' key for this:

   * copy the ground tile with `<SPC>' or the first button

   * copy the sprite tile with `<s>' (and if you don't see any sprite on
     the level, press `<F3>').


File: heroes.info,  Node: animations,  Next: departures,  Prev: sprites,  Up: Level editor

Animations
----------

You may have noticed that during the game, some tiles are animated:
color cycle (like the speed arrows) or moving objects (ventilators).
Each frame of an animation is actually a separate tile.  The different
tiles of an animations are drawn horizontally in the sets.  To setup an
animation, you just have to select the first one and copy it into your
level.  Optionally, press `<Ctrl>-<RET>' to see the animation.  When
the orange box is on an animated tile, you should find a button on the
right to modify the speed: the greater the number is, the slower the
animation goes.


File: heroes.info,  Node: departures,  Prev: animations,  Up: Level editor

Departures
----------

Select a tile and press the `<d>' key. Then look at the right side,
select a color and click on the arrow you want (if you don't see any
vehicle on the level, press `<F3>').


File: heroes.info,  Node: Troubleshooting,  Prev: Level editor,  Up: Running

Troubleshooting
===============

Video mode
----------

This game was primary made for MS-DOS, with VGA 320x200x8bits display.
If GGI is used to manage the video modes and you run into trouble with
video modes, I suggest you play with a environment variable called
`GGI_DISPLAY' used to select the display used.  LibGGI come with a file
`env.txt' that describes this variable.  As an alternative you may use
heroes' `--gfx-options' option instead of the above variable.  If you
want to force X display, you can add a line
     Options: --gfx-options=X
   in your `~/.heroes/heroesrc' file.  Note: `--gfx-options' has no
effect if you are using SDL.

   We suggest you to run the game under X because in console modes
(libvga, frame buffers, ...) it's easy to get stuck if the game freeze.

   People using an X server that supports 8bit visuals although the
default visual is not 8bit (run `xdpyinfo' to see a list of visuals that
your X server supports) are subject to what is probably a GGI bug.
Basically GGI's X driver fails to allocate the 8bit mode correctly.
The symptom is
     X Error of failed request:  BadMatch (invalid parameter attributes)
       Major opcode of failed request:  1 (X_CreateWindow)
       Serial number of failed request:  24
       Current serial number in output stream:  31
   One workaround is to prevent Heroes from negociating a 8bit video
mode.  Specify `--gfx-options not8' to that effect.  The default visual
depth for your server will then be selected by GGI.  (Of course this is
slower because Heroes internally works in 8bit mode; use of another
display depth involves a conversion.)

Keyboard
--------

There is a menu `KEYS' in the submenu `OPTIONS' that lets you change the
key bindings used during the game.  Please set the keys here before
playing since key codes can vary from place to place (hmm...  is that
right?).

Sound effects
-------------

You may find that there is some delay between an action and the
associated sound effect.  This is because libmikmod is polling in a
buffer and is thus always one buffer ahead in the playback. It is
possible to reduce the size of that buffer using some driver parameters,
please see the section `DRIVER PARAMETERS' of libmikmod's `README'.  For
instance I'm using the OSS driver and I reduce the size of libmikmod's
buffer by running heroes with the line
     Options: -d3,buffer=11,count=4
   in my `~/.heroes/heroesrc' file.  If you can find correct values for
other drivers, please send them to me <duret_g@epita.fr>!

Sound errors
------------

If Heroes try to tell you that:
     Could not initialize sound, reason: Could not set sample size
   That means that MikMod couldn't setup the 16bits output, may be
because your sound card doesn't support that.  Use the `-8' option to
have the game running with 8bits sound output.

   If you get:
     Could not initialize sound, reason: Could not set mono/stereo setting
   You will have to run the game with `-m', because stereo is not
available.

   Remember that you can always put these options in your
`~/.heroes/heroes' file (*note heroesrc::) so that you don't need to
type them every time you run the game.

SegFault when using Alsa drivers with and LibMikMod
---------------------------------------------------

If you are using Alsa 0.5.x drivers(1) Heroes is likely to crash during
it's startup.  This is because the current version of LibMikMod (3.1.9
at the time of writing) lacks support for Alsa 0.5.

   A solution is to run Alsa in OSS-emulation mode: simply run `heroes
-d x' (where x is the OSS driver number printed by `heroes -n') to
force LibMikMod using its OSS(2) interface.

   As a more general solution, you may want to compile LibMikMod
without Alsa support (`./configure --disable-alsa') so that it never
crash for any application.

   ---------- Footnotes ----------

   (1) Alsa is a project to improve the Linux sound subsystem
(See the Alsa page (http://www.alsa-project.org/) for details).

   (2) Open Sound System is a set of device drivers that provide a
uniform API across all the major UNIX architectures.  The Linux kernel
contain free code from the commercial OSS (See this page
(http://www.linux.org.uk/OSS/) for details).


File: heroes.info,  Node: heroeslvl,  Next: Index,  Prev: Running,  Up: Top

`heroeslvl'
***********

`heroeslvl' is a tool that can be used to inspect the content of Heroes
level files.  This is of almost no interest to the usual Heroes player,
but can sometime be helpful to find bugs in levels.

* Menu:

* Invoking heroeslvl::          heroeslvl launch-time options


File: heroes.info,  Node: Invoking heroeslvl,  Prev: heroeslvl,  Up: heroeslvl

`heroeslvl' options
===================

`heroeslvl' takes a list of levels to inspect in argument, and support
the following options.

   When no options are given, `heroeslvl' defaults to `-ipfh'.

`-v'
`--version'
     Display `heroeslvl' version number and copyright informations.

`-h'
`--help'
     Print a help message about these run-time options.

`-p WHAT'
`--print=WHAT'
     Select what information `heroeslvl' should display. `WHAT' can be
     one or more of the following characters.

    `d'
          Print square directions.  Square directions are used on
          tunnel to indicate the entrance direction, and on speed tiles
          to indicate the direction of the acceleration.

    `f'
          Print the filename of each processed file.

    `h'
          Print header information.  This include level size,
          soundtrack and tilesets to use, starting positions...

    `i'
          Print tile details.  This will display a list of all tiles,
          along with some of their attributes (type of the tile, adress
          of its sprite, animation information).

    `t'
          Print square type map.  Display a map of the level, rendering
          each square with a character indicating the square type.

    `T'
          Display the character used as type keys in the `-pt' output.

    `w'
          Print wall map.  Display a map of the level, rendering each
          square with a character indicating the number of neighboring
          walls.  (Walls are just bits indicating the directions that
          can be used to exit from a square; they not always map to
          something visible on the level.)

    `@'
          Print the list of tunnels, with position, direction, and
          destination.


`-i'
`--indent'
     Indent everything but the filenames of each level processed.  Note
     that filenames are only displayed if requested by `-pf'.


File: heroes.info,  Node: Index,  Prev: heroeslvl,  Up: Top

Index
*****

* Menu:

* -2:                                    Invoking heroes.
* -3:                                    Invoking heroes.
* -4:                                    Invoking heroes.
* -8:                                    Invoking heroes.
* -8bits:                                Invoking heroes.
* -cpu-off:                              Invoking heroes.
* -d N[,OPTIONS]:                        Invoking heroes.
* -default-options:                      Invoking heroes.
* -default-saves:                        Invoking heroes.
* -default-scores:                       Invoking heroes.
* -disable-debug:                        configure options.
* -disable-display:                      configure options.
* -disable-heroes-debug:                 configure options.
* -disable-joystick:                     configure options.
* -disable-optimizations:                configure options.
* -disable-sound:                        configure options.
* -double:                               Invoking heroes.
* -driver=N[,OPTIONS]:                   Invoking heroes.
* -e:                                    Invoking heroes.
* -enable-assert:                        configure options.
* -enable-debug:                         configure options.
* -enable-devel:                         configure options.
* -enable-gprof:                         configure options.
* -enable-html-doc[=DIR]:                configure options.
* -enable-mem-debug:                     configure options.
* -enable-warnings:                      configure options.
* -even-lines:                           Invoking heroes.
* -F:                                    Invoking heroes.
* -full-screen:                          Invoking heroes.
* -g:                                    Invoking heroes.
* -G OPTIONS:                            Invoking heroes.
* -gfx-options:                          Troubleshooting.
* -gfx-options=OPTIONS:                  Invoking heroes.
* -go:                                   Invoking heroes.
* -h <1>:                                Invoking heroes.
* -h:                                    Invoking heroeslvl.
* -help <1>:                             Invoking heroeslvl.
* -help:                                 Invoking heroes.
* -high-quality:                         Invoking heroes.
* -i <1>:                                Invoking heroeslvl.
* -i:                                    Invoking heroes.
* -indent:                               Invoking heroeslvl.
* -J:                                    Invoking heroes.
* -list=WORD:                            Invoking heroes.
* -lWORD:                                Invoking heroes.
* -m:                                    Invoking heroes.
* -mono:                                 Invoking heroes.
* -no-double-fx:                         Invoking heroes.
* -no-joystick:                          Invoking heroes.
* -p:                                    Invoking heroeslvl.
* -p@:                                   Invoking heroeslvl.
* -pd:                                   Invoking heroeslvl.
* -pf:                                   Invoking heroeslvl.
* -ph:                                   Invoking heroeslvl.
* -pi:                                   Invoking heroeslvl.
* -print:                                Invoking heroeslvl.
* -pT:                                   Invoking heroeslvl.
* -pt:                                   Invoking heroeslvl.
* -pw:                                   Invoking heroeslvl.
* -Q:                                    Invoking heroes.
* -q:                                    Invoking heroes.
* -quadruple:                            Invoking heroes.
* -quiet:                                Invoking heroes.
* -really-quiet:                         Invoking heroes.
* -s:                                    Invoking heroes.
* -swap-sides:                           Invoking heroes.
* -triple:                               Invoking heroes.
* -v <1>:                                Invoking heroeslvl.
* -v:                                    Invoking heroes.
* -verbose=CHANNELS:                     Invoking heroes.
* -version <1>:                          Invoking heroes.
* -version:                              Invoking heroeslvl.
* -vOPTIONS:                             Invoking heroes.
* -with-allegro:                         configure options.
* -with-dmalloc:                         configure options.
* -with-efence:                          configure options.
* -with-ggi:                             configure options.
* -with-mikmod:                          configure options.
* -with-mpatrol:                         configure options.
* -with-mtrace:                          configure options.
* -with-sdl:                             configure options.
* -with-sdl-mixer[=DIR]:                 configure options.
* allegro:                               Libraries.
* Alsa:                                  Troubleshooting.
* animations:                            animations.
* architecture:                          Machines.
* authors:                               People.
* bug:                                   Bug Reporting.
* bug report:                            Bug Reporting.
* configure generic instructions:        configure.
* configure options for Heroes:          configure options.
* contributing:                          Bug Reporting.
* contributors:                          People.
* copying:                               Copying.
* core dump:                             Bug Reporting.
* delay:                                 Troubleshooting.
* departures:                            departures.
* diff:                                  Bug Reporting.
* display driver:                        Invoking heroes.
* distribution:                          Copying.
* dmalloc:                               configure options.
* download:                              Getting Heroes.
* editor:                                Level editor.
* editor clicks:                         editor-clicks.
* editor keys:                           editor-keys.
* efence:                                configure options.
* environment:                           Environment.
* environment variable:                  heroesrc.
* errors:                                Troubleshooting.
* extra levels directory:                heroesrc.
* extradir:                              heroesrc.
* file resources:                        heroesrc.
* free:                                  Copying.
* full screen:                           Invoking heroes.
* game:                                  Game.
* getting heroes:                        Getting Heroes.
* ggi:                                   Libraries.
* GGI_DISPLAY <1>:                       Invoking heroes.
* GGI_DISPLAY:                           Troubleshooting.
* gii:                                   Libraries.
* gprof:                                 configure options.
* heroes-announce:                       Mailing lists.
* heroes-bugs:                           Mailing lists.
* heroes-discuss:                        Mailing lists.
* HEROES_DATA_DIR:                       Environment.
* HEROES_DEBUG <1>:                      Environment.
* HEROES_DEBUG:                          configure options.
* HEROES_LOCALE_DIR:                     Environment.
* HEROES_PREFIX:                         Environment.
* heroeslvl:                             heroeslvl.
* heroesrc:                              heroesrc.
* history:                               History.
* HOME:                                  Environment.
* ibiblio:                               Getting Heroes.
* index:                                 Index.
* installation:                          Installation.
* Invoking heroeslvl:                    Invoking heroeslvl.
* keepsgid:                              heroesrc.
* keepsuid:                              heroesrc.
* key codes:                             Troubleshooting.
* keyboard:                              Troubleshooting.
* keys:                                  Troubleshooting.
* keys, in editor:                       editor-keys.
* level editor:                          Level editor.
* libggi:                                Libraries.
* libgii:                                Libraries.
* libmikmod:                             Libraries.
* LibMikMod and Alsa:                    Troubleshooting.
* libraries:                             Libraries.
* libsdl:                                Libraries.
* machines:                              Machines.
* metalab:                               Getting Heroes.
* mikmod:                                Libraries.
* mouse, in editor:                      editor-clicks.
* mpatrol:                               configure options.
* mtrace:                                configure options.
* Nibbles:                               Overview.
* options <1>:                           Invoking heroes.
* options:                               heroesrc.
* overview:                              Overview.
* packagers:                             People.
* patch:                                 Bug Reporting.
* relocation:                            Relocatable package.
* rights:                                Copying.
* running:                               Running.
* runtime options:                       Invoking heroes.
* sdl:                                   Libraries.
* SDL_VIDEODRIVER <1>:                   Invoking heroes.
* SDL_VIDEODRIVER:                       heroesrc.
* setenv:                                heroesrc.
* setrsc:                                heroesrc.
* sfx:                                   Troubleshooting.
* sgid <1>:                              Global score file.
* sgid:                                  heroesrc.
* Simple DirectMedia Layer:              Libraries.
* sound driver:                          Invoking heroes.
* sound effects:                         Troubleshooting.
* sound errors:                          Troubleshooting.
* soundconf:                             heroesrc.
* sprites:                               sprites.
* stretching:                            Invoking heroes.
* suggestions:                           Bug Reporting.
* suid <1>:                              heroesrc.
* suid:                                  Global score file.
* sunsite:                               Getting Heroes.
* target.txt:                            Invoking heroes.
* TODO:                                  Bug Reporting.
* translators:                           People.
* Tron:                                  Overview.
* troubleshooting:                       Troubleshooting.
* tunnels:                               tunnels.
* variable:                              heroesrc.
* video mode:                            Troubleshooting.
* X:                                     Troubleshooting.



Tag Table:
Node: Top1168
Node: Copying3298
Ref: Copying-Footnote-14961
Node: Overview5046
Node: Getting Heroes6747
Node: Mailing lists8573
Node: Bug Reporting9580
Node: People11993
Node: History13923
Node: Installation17006
Node: Libraries17487
Node: configure19748
Node: configure options19928
Node: Relocatable package24457
Node: Machines25922
Node: Running29571
Node: Invoking heroes30099
Node: Environment38152
Node: heroesrc41225
Node: Global score file46308
Node: Game50102
Node: Level editor50372
Node: editor-keys51535
Node: editor-clicks52809
Node: tunnels53347
Node: sprites54419
Node: animations54889
Node: departures55583
Node: Troubleshooting55859
Ref: Troubleshooting-Footnote-159785
Ref: Troubleshooting-Footnote-259912
Node: heroeslvl60153
Node: Invoking heroeslvl60526
Node: Index62519

End Tag Table
