Free Hero Mesh

=== Overall working ===

The main function handles command-line arguments and initializes most
stuff. This then calls the game or editor as appropriate, which will
handle the respective functions.

The UI of the game play (including solution replay) and the behaviour of
the game are separated from each other. The game UI calls the execution
module to update the game state for the given sequence of inputs, which
then returns the new state, and whether or not the game has ended.

The loading and display of pictures and text is handled in its own file.


=== Files ===

bindings.c: Loads key/mouse bindings and handles SDL key/mouse events to
execute the bindings; most functions that can be bound are executed by
the module that calls this though, rather than being handled by bindings.c
directly. This module finds and decodes the correct binding, and whatever
command it specifies to execute is delegated to the calling module. This
file also includes a few global functions which keys can be bound to, such
as executing external programs, and displaying messages.

class.c: Contains code for loading class definition files. It also has the
"get_message_ptr" function, which is called by exec.c.

cursorshapes.h: Contains the X cursor shapes.

edit.c: The level editor. Also contains code for saving levels, and for
writing the contents of lumps of the level files.

exec.c: The main part of the game engine; the behaviour of the game is
implemented in this file. Also includes execution of P-codes. Execution
may Throw (using a macro) in case of an error, which results in the loss
of game.

function.c: Defines SQL functions and virtual tables.

heromesh.h: Contains structures, macros, and function and variables for
Free Hero Mesh, which can be used by multiple files.

game.c: The game play. The game behaviour is implemented in exec.c; this
one just handles the input and display, and solution replay, and any move
which is made calls exec.c to execute the mode. It contains one function
(locate_me) which is called by exec.c.

instruc/instruc.h/instruc.js: The "instruc" file contains a list of the
keywords and internal operator names used in the class definitions. Some
of these are only used internally, although most are available directly
as keywords. Many are also opcodes in the compiled P-code, although some
are only used as keywords, which are handled during class loading. The
instruc.js program generates instruc.h from instruc.

keyicons.xbm: Graphics for key icons. These are used to display the replay
list on the left side of the screen.

main.c: Contains code for start-up, and for initializing and dealing with
the user cache database.

mbtofhm.c: The converter from Hero Mesh to Free Hero Mesh. This is not
compiled into Free Hero Mesh; it is a separate program.

pcfont.h: Contains the graphics for the PC character set.

picedit.c: The picture editor.

picture.c: Contains initialization of graphics, and everything to draw
graphics on the screen, including icons and text. It also contains the
code for loading icons, for displaying popup messages, and scrollbars.

quarks/quarks.h/quarks.js: The "quarks" file contains names of predefined
quarks for use with the resource manager. The quarks.js program converts
quarks into quarks.h.

smallxrm.c/smallxrm.h: An implementation of the X resource manager. This
can be used independently from Free Hero Mesh.


=== Invariants ===

All game state changes which persist across turns and can affect the
behaviour of the game MUST be deterministic, depending only on the level
data, the player's inputs, the previous state, and the class definitions.
The game state MUST remain unchanged if entering the input into the replay
list is suppressed (which it will be if IgnoreKey is used), unless it
results in an immediate loss of game.


=== Miscellaneous ===

Free Hero Mesh uses the PC character set. All contributions shall use this
character set (of which ASCII is a subset).

Free Hero Mesh is a puzzle game engine for grid-based puzzle games with
levels, strictly based on changing game state due to the sequence of
inputs, e.g. Sokoban and Hero Hearts.

It is also designed to be compatible with EKS Hero Mesh puzzle sets, which
must be converted to Free Hero Mesh using the provided "mbtofhm" program.
However, Free Hero Mesh adds a lot of new features and bug fixes compared
with EKS Hero Mesh, many of which have already been implemented, and many
of which have not been implemented yet.

It is available in a Fossil repository; there are two sources:

* Main: http://zzo38computer.org/fossil/heromesh.ui

* Mirror: http://chiselapp.com/user/zzo38/repository/freeheromesh

(The main source is more often updated. The changes to the main copy will
occasionally be pushed to the mirror. Contributions are not accepted at
the mirror directly; they must be made in the main repository first.)


=== Installation ===

Currently, there isn't much of this; contributions will be accepted.
There is a shell script for compiling it available, though.

Requirements:

* Linux (it should hopefully work on other POSIX systems, although this is
untested; it might use some Linux-specific functions, and I may be willing
to accept contributions if this can be fixed)

* SQLite version 3 (a recent version)

* SDL1.x (the compatibility layers have not been tested with this
software; if you have tested it please report it, and you may contribute
patches to fix it)

* A C compiler, with GNU extensions (tested with GCC; it has not been
tested with Clang, but I expect it to work; report it if it doesn't work)

* If you wish to alter some of the files, Node.js or a compatible
JavaScript runtime is required for compiling these files (you do not need
this if you do not wish to modify Free Hero Mesh)


=== Community/discussion ===

For discussion of Free Hero Mesh, use the NNTP server. This is a newsgroup
in the zzo38computer.org NNTP server, named:

  un2.org.zzo38computer.soft.freeheromesh

You may use it for:

* Announcements about Free Hero Mesh

* Questions about the use of Free Hero Mesh

* Questions about the implementation of Free Hero Mesh

* If you made up your own puzzle sets, to link to them

* To comment on other puzzle sets

* Bug reports

* Feature requests

* Patches

* Contributions to documentation, including this file

* Anything else related to Free Hero Mesh, that I may have missed

You may also post bug reports and feature requests using the ticketing
system on the Fossil repository.


=== License ===

Free Hero Mesh is public domain. See the LICENSE file for details.


=== Frequently asked questions ===

(Nothing yet. If you have any questions, please ask.)