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. You can define your own classes of
objects using the Free Hero Mesh programming language.

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/or GNU-specific
functions; I may be willing to accept contributions if this can be fixed)

* SQLite version 3 (a recent version). Add a symlink to the sqlite3.o file
into the same directory with the source files.

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

* The smallxrm is required. It is included with this package; you must
compile smallxrm.c as smallxrm.o (one way is "bash smallxrm.c").

* Colour display, with resolution at least 640x480 (preferably more), and
at least 256 colours

* Keyboard and mouse, with three mouse buttons (the mouse wheel is not
needed and is not used, but it is OK if you have it)

The distributor should edit man6/heromesh.str in order to correctly
specify the directory containing the documentation files.

Before using it, you must create a file called .heromeshrc in your home
directory; you may use default.heromeshrc to start with, and then customize
it as you wish.

If compiled with "./compile p" then it is installed as "bin/heromesh"
(relative to the current directory, which should be the directory where
the source files are) and installs "bin/current.heromeshrc" as well (if it
does not already exist; it won't overwrite an existing file). In this case,
it can be used as a "portable app" mode.

There are optional runtime features that may require other programs in
order to use them, but that you can ignore if you do not use them. Such
optional features include:

* If you want to import/export pictures, you will need an implementation
of farbfeld. ImageMagick 7 includes an implementation of farbfeld, so if
you have that, then that will work. There are also other implementations,
such as the original "farbfeld" package, and Farbfeld Utilities.

* If you want to use the clipboard functions, you will need xclip or some
other program to interact the clipboard with stdin/stdout.

(The X window system is not necessarily required; you can use any system
that can be used with SDL.)


=== Documentation ===

Free Hero Mesh includes the following documentation files (plain text):

* ARCHITECTURE: Describes the source code of Free Hero Mesh. This is only
relevant if you wish to modify Free Hero Mesh, or if you want to look up
something in the code and want to know what file to look at.

* README: This file. Describes how to find the Fossil repository, the
installation, documentation, discussion/community.

* bindings.doc: Describes the configuration of key/mouse bindings.

* class.doc: This document describes the Free Hero Mesh programming
language. Read this if you want to define your own classes of objects.

* commandline.doc: Describes the command-line arguments. The man page
also describes the command-line arguments, although the commandline.doc
file has a more elaborate description.

* config.doc: Describes the configuration options for Free Hero Mesh.

* export.doc: The level export format is described in this file; it can
be used for importing as well as exporting.

* picedit.doc: Describes the picture editor.

* puzzleset.doc: Describes wat makes up a puzzle set.

* sql.doc: This file lists and documents each of the SQL functions and SQL
tables that are available. This is not relevant to programming the rules
of the game; it is used for user customization.


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

There is also the IRC channel #freeheromesh on Libera. Logs of this IRC
are available at:

  https://logs.esolangs.org/libera-freeheromesh/


=== License ===

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


=== Frequently asked questions ===

(If you have any more questions, please ask.)

** Is it any good?

 I suppose it is a matter of opinion, isn't it?

** It says "FATAL: Failed to open xclass file (No such file or directory)"
when trying to load the puzzle set. How to load it correctly?

 You must use the base name. For example, if the puzzle set files are
 named "sokoban.xclass", "sokoban.class", "sokoban.level", and
 "sokoban.solution", then you must type "heromesh sokoban" to load it.

** How to access the NNTP?

 You can use a NNTP client program, often called a "newsreader" program.
 Many email programs can also do NNTP, including Mozilla Thunderbird.
 There are also specialized NNTP programs, including Pan and bystand.
 (Some are text, some are binary, and some are hybrid; you will need one
 that supports text or hybrid.)

** Is there documentation with tutorial or introduction?

 I like the kind of documentation that the existing one is, although I
 am aware that some people prefer a different style. Someone who is better
 at writing that different style should do so and contribute please.

