.TH HEROMESH 6 "December 22, 2020"
.so man6/heromesh.str
.SH NAME
heromesh \- Free Hero Mesh (a puzzle game engine)
.SH SYNOPSYS
.B heromesh
.RI "[" "options" "] " "basename" " [" "resources" "]"
.SH DESCRIPTION
Free Hero Mesh is a puzzle game engine, for turn-based grid-based puzzle games.
It is fully deterministic and depends only on the sequence of inputs, not on time or randomness.
Free Hero Mesh allows you to define your own classes of objects using the included programming language.
.PP
The "basename" above is the filename of the puzzle set without the extension.
A puzzle set consists of four files (except composite puzzle sets).
.PP
The "resources" above is optional resources to override, in the X resource manager format.
.SH OPTIONS
.IP -C
Dump all class data.
.IP -H
Dump the hash table.
.IP -L
Display all tokens being read from the class definition file.
.IP -O
Output a solution Hamster archive with private solutions to stdout and then terminate.
.IP -U
Enable experimental/unstable features.
.IP -a
Autotest levels, ensuring that the provided solution is valid.
.IP -c
Only load classes and then terminate.
This can be used to verify that the class definition file does not contain syntax errors.
You can also use it with some other options to display details.
.IP -e
Start the level editor.
.IP -f
Only flush the user cache and then terminate.
.IP -h
Disable portable mode;
always use the HOME environment variable to find the files.
.IP -i
Batch import levels.
Accepts the level data (in the export format) from stdin.
.IP -n
Create a new puzzle set.
The class definition file and image set must already exist.
.IP -p
Start the picture editor.
.IP -r
Open in read-only mode.
.IP -t
Enable message tracing.
.IP -v
More verbose error logging.
.IP -x
Does not start the GUI; instead, accepts SQL statements from stdin.
.IP -z
Load a composite puzzle set.
In this case, pass the full file name instead only the base name.
.IP -+
Load the level whose ID number is specified by the "level" resource.
.SH FILES
A puzzle set consists of four files, with filename suffixes
.BR ".class" ", " ".xclass" ", " ".level" ", and " ".solution" "."
A composite puzzle set consists of a single file.
.TP
.I ~/.heromeshrc
The configuration file, in X resource manager format.
.TP
.I ~/.heromeshsession
A SQLite database containing user cache data.
.TP
.I \*[Document_Dir]/*.doc
Documentation.
.PP
The files it expects to find in the home directory may be looked for elsewhere if portable mode is used.
.SH ENVIRONMENT
.TP
.B HEROMESH_PREFIX
If defined, force portable mode.
This value is used as the prefix to find the files.
(It may include a file name prefix as well as a directory path.)
.TP
.B HOME
The home directory; used to find .heromeshrc and .heromeshsession files.
.PP
Any of the SDL environment variables can also be used.
.SH "PORTABLE MODE"
There is a "portable mode" available.
The following rules are used to determine if portable mode should be used:
.PP
1. If the -h switch is specified, use home mode.
.PP
2. If the HEROMESH_PREFIX environment variable is nonempty, use portable mode.
.PP
3. If argv[0] contains a forward slash, use portable mode.
In this case, the files are named "current.heromeshrc" and "current.heromeshsession" in the directory where the executable file is found.
.PP
4. Otherwise, use home mode.