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 (or you can compile it from
source with the desired options; the default options will do, although it
is safe to omit the deprecated functions and to set SQLITE_DQS=0).
* 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", or you
can use gcc or clang with the options you want).
* 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. (This does not
affect the working of Free Hero Mesh itself; it only affects the man page.)
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.
* codepage.doc: Describes the use of code pages and the file format of the
codepage.har file.
* 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.
* edit.doc: Describes the use of the level editor.
* export.doc: The level export format is described in this file; it can
be used for importing as well as exporting.
* game.doc: Describes the game play and the controls for the game play.
* man6/heromesh.6: Man page; includes information about command-line
arguments, environment variables, and link to further documentation.
(You should install this in your man pages directory.)
* man6/heromesh.str: Must be installed in the same directory as the
man6/heromesh.6 file. The distributor should change this to point to
the correct directories where the files are stored; these directories
will be mentioned in the man page
* misc/mbform.doc: Describes the .mb file format for Hero Mesh. (Not
directly relevant to Free Hero Mesh. It contains information that was
used for writing the converter, and may be of interest to some readers
for other purposes, but is neither used nor does it contain anything
that is needed for users or developers of Free Hero Mesh.)
* picedit.doc: Describes the picture editor.
* puzzleset.doc: Describes what 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, and for performing batch
operations when editing, and for producing reports.
=== Other files ===
Free Hero Mesh also includes the following other files, which are not the
source code files, compilation files, or documentation files:
* codepage.har: Contains fonts for code pages. Code page 437 is included
inside of the executable file and does not need this file; this file is
only needed for code pages other than 437.
* default.heromeshrc: An example configuration file which you can customize
for your own use. You should at least set the proper paths to the files.
* imgtofhm.c: Converts pictures into the Free Hero Mesh format. The command
line arguments are: the maximum number of pictures, the lump name prefix,
and then the transparency colour (in hex format) (optional). It receives
the pictures in farbfeld format in a vertical strip from stdin, and writes
the Hamster archive to stdout (which can be appended to a .xclass file).
* mbtofhm.c: Converter from Everett Kaser's MESH engine into Free Hero
Mesh. Give the base name of the output files as the command-line argument,
and receives the .mb file from stdin.
* misc/har.c: A small C program for dealing with Hamster archives. This is
not properly a part of Free Hero Mesh (and is not needed in order to use
or compile Free Hero Mesh), but is included since it is likely to be useful
for some users (e.g. to copy pictures/sounds between puzzle sets).
* misc/sokoban.tar.gz: Example puzzle set.
* smallxrm.c and smallxrm.h: This is an implementation of the X resource
manager which is used in Free Hero Mesh but can also be used in other
programs independently from Free Hero Mesh.
(The files in the misc/ directory are not part of Free Hero Mesh nor are
they needed by Free Hero Mesh, but are provided for convenience. They can
safely be ignored or deleted if you are not using them.)
=== 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/
There is also a Matrix chat, which is linked with the IRC. It is:
https://matrix.to/#/#freeheromesh:libera.chat
(Note: I have not tried the Matrix chat and I do not know if it works.)
=== 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.
(This assumes that the file is in the current directory. If it isn't,
then you must also specify the directory name, in addition to the puzzle
set base name.)
You may also use a composite puzzle set. In this case, use the -z switch
and pass the name including the file name suffix.
** 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.
** Are any libre puzzle sets currently available?
Not yet (as of this writing). However, anyone can contribute them; I
would be interested to see what you can come up with! (I am also working
on my own puzzle sets, too.)
** Hero Hearts puzzles will cause errors when a Bomb or Missile explodes,
and won't display Roller animations correctly.
The first problem is a bug in Hero Hearts (which occasionally causes a
GPF in the Windows version, but not always, due to race conditions). This
can be corrected by changing the line that says "From =%objFrom" in the
#EXPLO_ANIM message block of the $Fire class to "From $Grenade is if
From else 0 then =%objFrom".
The second problem is not a bug, but a bad design in Hero Hearts, which
Free Hero Mesh does not emulate. (This problem is purely visual, though.)
To fix it, add "(Synchronize 0 4 8)" at the beginning of the file, and
then add ":onoff %off if STOP Image 0 0 Animate else 0 Image Synchronize
then" to the end of the INIT message block of the $Roller class and then
add "=:onoff" at the end of the #ENABLE, #DISABLE, and #TOGGLE blocks.
** Some levels of the SANDY1 puzzle set fail with a "Type mismatch" error
before any moves are made.
This is the fault of the author(s) of those levels. The $SwitchFloor
class expects Misc1 to be a number, but somehow the level author put a
class name there instead.
** Level 11 of the CHESSMAZ puzzle set fails with a "Type mismatch" error
before any moves are made.
It attempts to perform arithmetic on object references to generate random
numbers. The generation of random numbers is not allowed (as it would
break the replay feature).
** The provided solutions of some of the Falling Hero levels with Closer
Seekers do not work.
I have no idea what's wrong, but I can confirm that this is true.
(If anyone can figure out what is wrong, please tell me.)
** There is a segmentation fault.
This is a bug in Free Hero Mesh; segmentation faults should never occur.
Please report it so that it can be fixed. Ensure that your bug report
includes all information needed for reproducing the bug, including the
compiler options you used. (If you can fix it yourself, do so and then
post the patch so that I can review it. You will still need to report
the bug; a patch does not substitute for a bug report.)
** Can the inventory and move list be displayed at the same time?
This feature is planned, but has not been implemented yet. (If you can
help by providing a patch or ideas about it, that might help.)
** Is there a table of contents of the levels?
This feature is planned, but has not been implemented yet. (If you can
help by providing a patch or ideas about it, that might help.)
** Why is there both Busy and UserSignal flags even though both flags do
the same thing?
It is because Everett Kaser designed the MESH engine that way, but I
don't know why it was designed that way. If you do not like to have
both flags, then you do not have to use both.
** What is the MIME type and UTI for Free Hero Mesh?
None is officially assigned, but unofficially, a composite puzzle set
can use the following MIME type:
application/freeheromesh.composite+hamarc
Optional parameters for this MIME type are "codepage" which is a IBM
code page number, and "version" which is the version of Free Hero Mesh
(same as the numbers of the {version} macro). Both are optional.
MIME types for the other file formats are not defined.
The UTI for a Free Hero Mesh composite puzzle set file is:
org.zzo38computer.freeheromesh.composite
This UTI conforms to the following other UTIs:
com.hamsterrepublic.lumped
public.data
** If would be very helpful if you could put more information and in
particular screenshots on the Fossil main page, or at the very least link
to screenshots, or create a non-Fossil webpage to show the project. They
say a picture is worth a thousand words, but in this case I think no
number of words will ever substitute for an image.
You are probably correct. Once suitable screenshots are available, I can
do this, and also add other information if needed.
** It didn't compile using the script, and/or there are compiler warnings,
and/or some changes were required.
If the warnings and other issues with compilation are posted on the NNTP,
then it can be properly discussed, and then a better compilation code can
be written. Proper packaging for different distributions can also be
discussed. Please provide the following information:
- What compiler you used (including the version)
- What operating system you are using (including the version, and the
distribution of Linux, if you are using any)
- What version of SQLite and SDL you are using
- What changes you made to the program code, if any
- What warnings you got, if any
- Whether or not the program worked after doing these things
One issue is that the version of SQLite in the system package manager
might (depending on the system) not be updated as often as it should be.
There is no guarantee that newer versions of Free Hero Mesh will not use
features of newer versions of SQLite (or depend on bug fixes), although
it also might not. (However, I think it is unlikely that newer versions
of SQLite will break it.)
** Apparently in the original you can right click on objects to read
descriptions?
In Free Hero Mesh, this function is mapped to the middle instead of
right button by default, but the mapping can be redefined. (By default
in Free Hero Mesh, the right button accesses the inspection menu,
allowing inspecting the variables of objects at that location.)
** What's the X resource manager code for? Clipboard access?
The user configuration settings are in X resource manager format.
Free Hero Mesh doesn't depend on the X window system; the X resource
manager is actually not a part of the X window system, just it is
commonly used with it. Xlib includes a part of the X resource manager,
but Free Hero Mesh does not use Xlib (and even if it did, Xlib lacks
an equivalent of the xrm_init_quarks function).
Clipboard access is done using external programs; if the X window
system is used, then this will usually be "xclip". This is configured
in the user configuration file, so if you are not using the X window
system then you can change it to the appropriate commands for whatever
you are using on your computer.