tutorial.doc

This document is a tutorial of the use of Free Hero Mesh. (It is provided
for the benefit of users who want it; some people have requested it. My
own opinion is that the other documentation is better. If you have any
concerns about this documentation or how to improve it, please do so.)

(NOTE: This tutorial is incomplete.)


=== Installation ===

1. Compile it (if it is not already compiled). See README file for details
about compilation. I will assume it called "heromesh" and is in the PATH.

2. Copy "default.heromeshrc" into a file in the home directory called
".heromeshrc" (if in portable mode, instead put it in the same directory
as the executable file and call it "current.heromeshrc".

3. (Optional) Customize the configuration file. (This document assumes
the default key/mouse bindings, but you may customize them if desired.)
This file is a plain text file and can be edited in any text editor; see
config.doc and bindings.doc for details about the configuration file.

4. Make up puzzle set (using the instructions below).

5. You can edit and test levels, classes, etc.

6. You can publish the composite puzzle set file if desired.


=== Making the puzzle set ===

1. Decide the base name of the puzzle set, which should not include a dot,
nor should spaces be included (underscores and hyphens are OK, if it does
not start with a hyphen). The names of the four files of this puzzle set
will then be that base name followed by ".xclass", ".class", ".level",
and ".solution".

2. Make the picture file and class definition file, in either order.

  a. Write the class definition file in any text editor (e.g. vi or emacs).
  See class.doc for details of this format, or see sokoban.class for a
  simple example.

  b. Make the pictures; use "heromesh -p" and then the base name of the
  puzzle set. This brings up the picture editor.

3. Run "heromesh -n" and the base name, to create an empty level file and
empty solution file.

4. Run "heromesh -e" and the base name, to load the level editor, to make
up a level. You can then save by CTRL+S and test by CTRL+P to play this
level; if you solve it, push CTRL+S to record the solution. This only
saves the puzzles in the user cache database and not to the puzzle set
files (unless the .autoSave option is set).

5. (You can skip this step if the .autoSave option is set.) Run "heromesh
-f" and the base name, to write the changes to the puzzle set files.

6. (Optional) Once you have finished, you may wish to make a composite
puzzle set file. Use "har c" and then the names of the files that make up
the puzzle set and then ">" and the file name for the composite puzzle set,
to make up the composite puzzle set file. You can then use "heromesh -z"
and the full file name of the composite puzzle set, to load it. Note that
a composite puzzle set is read-only; to edit it, you must split them into
separate files again.

The below sections describe them more elaborately, with examples. For the
purpose of this example, the new puzzle set will be called "example".


=== Picture editing ===

Enter the command at the UNIX shell:

  heromesh -p example

This will load the list of pictures in the puzzle set (for the purpose of
editing), which is initially empty.

By default, it will use the same default picture size that you have set in
the configuration file. However, you may set the picture size yourself
instead for all pictures. To do this, push F6. For this example, push F6
and then enter 24 at the prompt and push enter. You can specify multiple
sizes; for this example there aren't any so just push enter again.

Push F1 to add a new picture, and then enter its name. For example, name
it HERO by typing in HERO and push enter.

Now the picture editing screen is displayed. Push D for drawing, and then
you can draw the picture in the grid by the mouse. Click in the colour
palette with the left button to select the colour to use for drawing,
and click in the picture grid with the left button to draw pixels (you
can hold down the button to draw many pixels). The right button erases.
Once you are finished, push escape to return to the list.

For this example, add two more pictures named BOX and BACKGROUND in the
same way as above.

Once you are finished all of them, push escape again to save and quit.
(If you want to edit again later, follow all of the same steps as above,
but push F3 instead of F1 if you want to edit an existing picture instead
of adding a new one.)

See picedit.doc for further details about the working of picture editor.


=== Class editing ===

Create a plain ASCII text file with the puzzle set name and ".class"
suffix. (Use any text editor of your choice. Ensure that the file format
is plain text, and do not include a byte order mark.) For this example,
it will be named "example.class", and will contain the following text:

  ; Example class definitions.

  ($Hero
    (Image "HERO")
    Player
    Input
    (Density 25)
    (Height 10)
    (Strength 1)
    (Rook Move)
  )

  ($Background
    (Image "BACKGROUND")
    (Density 100)
  )

  ($Box
    (Image "BOX")
    (Density 30)
    (Height 10)
    Shovable
    (Weight 1)
  )

This defines three classes, named $Hero, $Background, and $Box.

Explanation:

* A semicolon denotes a comment until the end of the line. (This is allowed
anywhere outside of string literals.)

* Each block in parentheses starts with the class name; the
class name always starts with a dollar sign.

* The (Image) blocks specify the name of the picture of that class, which
are the same names as specified in the picture editor.

For the $Hero class:

* "Player" means that an object of this class is the "player" object.

* "Input" means that key input will be sent to objects of this class.

* "(Density 25)" means that the stacking level of objects within a grid
cell is 25 for this class. Higher numbers are lower stacking levels, and
are drawn behind objects with lower density numbers. (If you do not specify
the density number, then it will be zero by default).

* "(Height 10)" means that other objects cannot move on top of it unless
their Climb is at least 10 (in this example, the Climb is not specified for
any class, giving them the default value of zero).

* "(Strength 1)" means that the total Weight of all objects that it moves
(including itself) cannot exceed 1.

* "(Rook Move)" defines the keyboard message for the cases of the four
arrow keys; if any one is pushed, "Move" is executed after pushing the
direction on the stack. This will cause the Hero to move in the direction
of the arrow pushed.

For the $Background class:

* "(Density 100)" makes it drawn behind the $Hero and $Box classes.

* The Height is left at the default of zero so that other objects can move
into its location.

For the $Box class:

* "(Density 30)" defines the Density between $Hero and $Background. (It is
also acceptable to be the same as $Hero.)

* "(Height 10)" works like it does for the $Hero class.

* "Shovable" allows other objects that move into it to attempt to push it
out of the way.

* "(Weight 1)" sets its Weight to 1, as described above for Strength. In
this case, it prevents the Hero from moving multiple Boxes at once.

(A note about movement: A grid cell that contains no objects at all acts
like a wall for most purposes, so for this simple example there is no
$Wall class. If you wanted one, you could define one with a large Height
so that other objects cannot move there.)

See class.doc for further details about class definitions.


=== Level editing ===

First you must create the empty level and solution files. To do this, enter
at the UNIX shell:

  heromesh -n example

This creates files named "example.level" and "example.solution". There will
be initially a single blank level.

To start the level editor:

  heromesh -e example

Now the level editor screen is displayed.

Initially, the grid dimensions is 1x1, which is too small. You must resize
the grid; push R and then type the new size. For this example, type 16x16
and push enter, to set the grid size to 16x16.

Now, push the space bar to display the class selection menu. Select the
Background class and push enter.

For this example, let's assume we want the entire grid filled with the
background, so push F to fill with the selected class. (You can click with
the right button to delete some if you want to add walls.)

Now you can add the Hero. Push space bar again and select Hero.

Add the Hero by clicking with the left button on the appropriate grid cell.

Now add some boxes, by pushing space bar, select Box, and enter, and you
can click wherever you want to put the boxes.

Next, set the title of the level. Push CTRL+T and enter some text, and
push F2 to save the title.

Once you are finished, push CTRL+S to save, and then CTRL+P to switch to
the game play. Now you can push arrows and it should move. You can push
CTRL+E to go back into the editor, ESCAPE to restart the level, or CTRL+Q
to quit Free Hero Mesh.

See edit.doc for further details about use of the level editor.


=== Composite puzzle sets ===

(To follow these instructions, you will need to compile the "har" program,
which is the file "misc/har.c" in the source code repository.)

A puzzle set can be a "composite puzzle set", which puts everything into
a single file. If you want to do this, then:

  heromesh -f example
  har c example.xclass example.class example.level example.solution > example.fhm

Now, to run the composite puzzle set:

  heromesh -z example.fhm

You only need to distribute example.fhm and not the other four files.

A composite puzzle set is read-only. If you want to edit it then you must
decompose it. This can be done by typing:

  cat example.fhm | har x example.xclass example.class example.level example.solution

Now it can be used like a noncomposite puzzle set, again.