PyRunner Level Editing Guide
============================

    This document explains how to create your own PyRunner levels.  It also
includes some guidelines to follow to make sure your level is fun and
challenging.

    Also explained is the procedure for creating custom artwork, for organizing
your levels into new PyRunner "adventures", and for installing newly-downloaded
levels, adventures, and artwork.

    Map Data File Format
    --------------------

    PyRunner maps are defined by a simple text file using the familiar
keyword/option pair syntax.  Map files typically have the extension of .lev so
they are easy to find.  In addition to keyword/option pairs, map files can
contain comments.  Comments are lines that start with a semicolon (;).  (The
semicolon must be the first character on the line.  End-of-line comments are
not allowed).  Blank lines are also permitted.

    The next two sections will describe the various keywords allowed.  The map
keyword is discussed first, along with a detailed list of objects permitted on
the map.  Following that is a list of options that can be set to affect map
behaviour.

    Defining the Map
    ----------------

    Obviously the most important part of the map data file is the map itself.
The map is defined by a grid of symbols that for the most part correspond to
objects on the screen.

    The map keyword is used to define a row of objects on the map.
Consequently, there must be several lines with map keywords in each map file.
Ordering is dependent on positioning within the map file, so the first map line
will fill the top row of the screen, the next map line will fill the second
row, etc.

    Map sizes are fixed at 40x22.  This means that a proper map file will be 22
map lines, each with 40 symbols on them.  Extra map lines and extra symbols on
a map line will be ignored.  If trailing rows or columns are not specified,
they will be filled with empty symbols.  However, it is recommended that you
ALWAYS specify a complete map.

    Here is a typical map line:

map  .......=########%%%%%%#####|..........".

    As mentioned, each symbol on a map line represents an object on the screen.
The representative symbols are chosen to give you a visual approximation of how
the map will be shown on the screen.  (Think of it as an ASCII-art picture of
the map!)

    There are three classes of map symbols.  Each will be discussed separately.
The provided map files have a handy index of symbols at the bottom of the file.


    The first class of symbols represent regular objects.  Regular object appear on
screen as soon as the level starts and have no special properties.  It is
assumed you are familiar with what each object is used for.  If not, read
howtoplay.txt before continuing.  The symbols for regular objects are:

    Empty Space         .
    Diggable Floor      #
    Permanent Floor     %
    Ladder              =
    Bar                 -
    Pole                |
    Gold                $
    Left One-Way Gate   <  [1]
    Right One-Way Gate  >  [1]
    Switch              /
    Spikes              ^
    Player Start        @  [2]
    Enemy Start         !  [3]
    Enemy Regen. Point  ?  [4]
    Exit Point          0  [5]

    Footnotes:

    [1] The direction specified in the map file is the direction the one-way
gate will have when it first appears.  Switches toggle all one-way gates to
the opposite direction.

    [2] Every level must have ONE AND ONLY ONE player start point.  This is the
point where the runner begins the level (either when first reaching the level
or after dying).  It does not display anything on the screen, showing up
instead as an empty space.

    [3] The number of enemy start points determines the number of enemies on
the level.  For a level with no enemies, don't specify any enemy start points.
You can have as many enemy starts (and thus enemies) as you like, but try not
to get carried away.  Enemy starts show up as empty spaces.

    [4] Enemy regeneration points specify where enemies can regenerate after
they are killed.  They show up as empty spaces.  If you have specified enemy
start points you MUST specify AT LEAST ONE regeneration point.  If you specify
more than one, a point will be chosen at random each time an enemy regenerates.
Note that there is no need to have at least as many points as you have enemies,
because only one enemy can regenerate at a time.

    [5] Exits appear immediately but don't become active until all stages have
been completed.  If you want to keep the location of the exit secret, use an
after-stage object (see below).


    The next class of objects are false objects.  False objects look like their
counterpart regular objects, but behave as if they were empty spaces.  In
addition to not doing anything, they can also be dug under.  For most objects,
this is one of the primary clues to a user that an object is false.

    Used correctly, false objects add an element of challenge and surprise to a
level.  However, it's really easy to abuse false objects.  Abuse just leads to
player frustration, so don't go down that road.  See the section on Editing
Tips for more guidelines about false objects.

    Not all objects can be false.  Obviously false empty space is the same as
regular empty space.  False one-way gates seem to be useless for anything but
confusion, so they're out.  And of course, false player and enemy start/regen.
points don't make much sense because the player can't see these anyhow.

    Here are the objects that can be false and their symbols:

    Diggable Floor      +
    Permanent Floor     *
    Ladder              "
    Bar                 '
    Pole                :
    Gold                ~  [6]
    Switch              \
    Spikes              &
    Exit Point          _

    Footnotes:

    [6] False gold is not counted in the Gold display on the status line.


    The final class of objects are after-stage objects.  After-stage objects
appear once all of the gold of a particular stage is collected.  If your map
has no stages, these objects will not be used.  If your map only has one stage,
then the second set of after-stage objects won't be used.  After-stage objects
are always optional (but make sure the level is exitable if you aren't adding
anything after a stage).

    All objects can appear after-stage, with two exceptions:  Empty space (for
obvious reasons) and player start (because there can only be one of these and
it has to be available immediately).  The means that enemy start and regen.
points can appear after a stage!  This is useful to add new enemies (to make
escape harder) or to add new regeneration points (say, close to an exit).

    Here are the symbols for after-stage objects.  The first column of symbols
is used to make an object appear after stage 1, and the second column is for
objects that appear after stage 2.

    Diggable Floor      F   f
    Permanent Floor     M   m
    Ladder              L   l
    Bar                 B   b
    Pole                P   p
    Gold                T   t  [7]
    Left One-Way Gate   [   (
    Right One-Way Gate  ]   )
    Switch              W   w
    Spikes              S   s
    Enemy Start         E   e  [8]
    Enemy Regen. Point  R   r  [9]
    Exit Point          X   x  [10]

    Footnotes:

    [7] If the stage just completed was the last one, the gold is considered
bonus gold (worth extra points but not mandatory).

    [8] Enemies will immediately appear at the new enemy start points.

    [9] The new regeneration points will be added to the list of existing
regeneration points.

    [10] If the exit appears after a stage that isn't the last one, it will be
inactive until the last stage is completed.

    Map Options
    -----------

    For each map, you can define a set of options that affect how the map will
be played.  Some options let you add a bit of flavour to your maps, while
others provide information that PyRunner needs to know.

    For binary (on/off) options, you can use any of the following
(case-insensitive) values to indicate true.  Anything else will be treated as
false.

    true
    yes
    1
    on

    The keywords which define the options are listed below.  (*) denotes
default options, which also correspond to the behaviour of the original Lode
Runner game (at least, as far as I can recall).  Although you can omit keywords
defining options for which you want to use the default, it is recommended that
you include all settings for clarity (and in case the defaults ever change).
Exception:  If you don't want to provide hints, you should omit all hint lines.

    NOTE:  meta and hint strings should be 80 characters or less, otherwise
they will wrap around to the top of the screen.

    meta - A short string that should contain the level title and author name,
or other useful information.  This is displayed on the second line of the
status bar until the player requests a hint.

    artwork - Specifies the artwork set the map should use.  See the section
later on Creating Artwork.

    numstages - This can be 0, 1, or 2 and indicates how many gold-collecting
stages the level has.  0 means that the player can exit immediately without
having to collect any gold.  1 (*) means that the player will have to collect
all the gold on screen before being allowed to exit.  2 means that after the
gold on screen is collected, more will appear (as after-stage objects) and that
must also be collected.

    diglimit - The number of floors that may be simultaneously dug out at once.
Set to 0 to allow no digging whatsoever on your level.  Otherwise, provide a
number.  99 (*) is the recommended setting to indicate unlimited digs.  While
the maximum in practice is around 40, using 99 makes it more obvious, and in
future the number 99 may be treated specially.

    exitattop - If true (*), the player can exit the level by reaching the
topmost row of the screen in addition to using any exit points.  If false, a
player must get to an exit point (be sure to provide at least one!).  Note that
it does not matter how the player gets to the topmost row.

    flipgates - If true, any one-way gates on screen will be flipped (as if a
switch were pressed) when the last stage is completed.  This is useful to
release trapped enemies or do other things to thwart the player's attempt to
exit.  If false (*), only switches can change gates.  NOTE:  If true,
after-stage gates (i.e. those that appear when the final stage is complete) are
NOT affected by this option.

    horizwrap - If true, the sides of the level will wrap around to each other.
See howtoplay.txt for a more detailed description.  If false (*), the sides of
the screen act the same as permanent floors and will block the player.

    vertwrap - If true, the top and bottom of the level will wrap around to
each other.  Again, see howtoplay.txt.  If false (*), the top and bottom of the
screen behave as permanent floors.

    hint - A short string to display to the player upon request.  Hints are
intended to be small tips to push the player in the right direction, at the
cost of a small penalty in score.  You can provide more than one hint line.  If
you do, hints will be displayed in the order they appear within your level
file, and the user must request each hint separately.  See the Editing Tips for
effective hint-usage guidelines.

    Editing Tips
    ------------

    PyRunner gives you a lot of power for customizing your levels, but if this
power is not used carefully you will end up creating frustrating levels that
just aren't fun to play.  As such, here are some tips to keep in mind:

    - Prime Directive:  All levels should be reliably solvable without
requiring the player to die, and without requiring the player to ask for a
hint.  For example, you should always provide enough diggable floor to get at a
buried gold safely. Reliably means that the player does not have to count on
the enemies, because their behaviour is somewhat random.  Lastly, hints cost
points so they should not be a requirement.  (Also, some players (e.g.
PyRunner's author) like to figure things out entirely themselves).  Levels that
do not meet this criteria will not be accepted for the PyRunner web site.

    - False objects are neat but only when used in moderation.  False objects
are only intended to mislead the player, not to confound the player completely.
A player should ultimately be able to deduce that an object is false without
having to verify it, unless discovering this fact "accidentally" won't directly
kill the player.  Too many false objects will frustrate the player.  Here are
some ways to accomplish this:

        - For ladders, switches, poles, etc. put a diggable floor underneath.
          Normally, you can't dig under these objects so allowing the player
          to try will provide a clue.

        - It is an acceptable tactic to use false floors in situations where it
          is obvious that the player would not otherwise be able to escape.
          The boxes on the right side of sample.lev are an example of this.

        - The opposite tactic, using false gold in places that are obviously
          traps, is acceptable only if it is not mixed with the previous
          tactic.  This way the player can use the Gold count on the status bar
          as the clue.  If the two tactics are combined, then which gold is
          the false one, and which is the real one with the false floor?  The
          player has to guess, and that violates the Prime Directive.

        - False exits are okay provided there is a reasonable chance for the
          player to find the correct one, and that guessing wrong won't kill
          the player.

        - False permanent floors should only be used in non-dangerous
          situations, as a player can't dig one to test if it's real or not.
          (An exception is if you use a false permanent floor to cover a
          diggable area.)

    - In general, after-stage objects should help the player.  Suddenly
throwing up walls and stuff isn't going to make the player very happy.  There
are exceptions (like adding more enemies), of course, but generally the player
should be rewarded for finishing all of the stages.

    - No-stage levels sound dull, but they're great for maze-like puzzles, or
"mad dashes" to an exit.  They can also be used as "bonus levels"; i.e. levels
where the player can just exit immediately or try for some (perhaps
trickily-placed) bonus gold.

    - Two-stage levels are difficult to design but they can be very challenging
and interesting.  If you are going to use a two-stage level your initial screen
will likely need to be very sparse to make sure you have enough room to add new
things later on.

    - Provide hints.  Your first hints should be small tips - gentle nudges in
the right direction.  After that, you can progressively go into more detail.
For example, a good first-stage hint is, "Some gold lies above false floors."
while a later-stage hint might read, "The switch in the top-left corner is the
only real one."  In any case, make sure all your hints have some value because
they cost the player points!

    - Use the wrapping options with care.  It takes extra planning to design a
good level with wrapping.  Make sure all of the "wrapping transitions" make
sense.  With vertical wrapping, watch out for totally empty columns - they will
create a bottomless pit which has no escape!  (You can use this as a feature,
but do so carefully.  For example, if you want to let the player trap enemies
with it, make sure they won't have any gold because if they do there will be no
way to collect it other than falling in the pit itself!)

    - When bundling levels into an adventure, make sure there is enough
gold through the adventure to give the player a few extra runners along the
way.

    - Lastly, and most important, PLAYTEST YOUR LEVEL!!!  If you can't solve
it, chances are nobody else can either.

    Creating Artwork
    ----------------

    If you are so inclined (and sufficiently-skilled) you can create a custom
set of artwork to go with your level, or a series of levels.  Here's how:

    1) Make a new directory within the PyRunner directory.  The name of the new
directory will be the name of your artwork set.

    2) Copy all the files from an existing PyRunner artwork directory into your
new directory.

    3) Edit some or all of the files.  PyRunner uses standard Bitmap (BMP)
files, which can be edited using programs like GIMP (or even Windows' Paint).

    4) Setup your level (or an existing level) to use your new artwork.  See
the description of the artwork setting.

    Creating New Adventures
    -----------------------

    Bundling your levels into new adventures is really easy.  Simply create a
new text file (with the extension .gam) and list the filenames of the levels in
the order you want them to appear, one per line.  That's it!

    NOTE:  If you're only intending to distribute a single level you should
still make a .gam file for it.

    Distributing Levels & Artwork
    -----------------------------

    Distributing your levels is easy.  Just pack the .lev files into an
archive, along with the .gam file.

    If you are distributing more than two or three levels, you should put all
of the level files (and any documentation) in a subdirectory with the same name
as your .gam file, then pack the .gam file in the main directory.  This way, a
person unpacking your archive from their PyRunner directory will have your .gam
file go into their PyRunner directory, and the levels and other stuff into its
own directory.  NOTE:  Be sure your .gam file includes the paths, for example:

adventure/map01.lev
adventure/map02.lev
etc.

    NOTE:  If you include a high score (.sco) file, make sure it goes to the
PyRunner directory (with the .gam file).  Also, make sure the highest scores
are fairly low ("demo scores") that are reasonably easy to beat, not scores
that you got after finishing your entire adventure.  I recommend NOT including
high score files, though.

    Artwork should also be packed into an archive that includes its directory,
as this is how PyRunner finds artwork.  Be sure to include a complete set of
bitmaps, even if you don't change them all.  PyRunner will abort if it can't
find all of the files it needs in an artwork directory.

    Bundling new levels/adventures with artwork can also be done by combining
the two steps above.

    NOTE:  Remember, PyRunner is a portable game that can run on many different
platforms (Windows, Linux, etc.)  Be sure your chosen archive format has
unpackers available on many different platforms.

    Installing Levels & Artwork
    ---------------------------

    To install new levels:

    1) If necessary, unpack the levels into your PyRunner directory.  Most
adventures will be unpacked into their own subdirectory, leaving just the .gam
file in your PyRunner directory.  Some may also include artwork sets which
should also unpack into their own (separate) directories.  (If you've created
your own levels, you can skip this step.)

    2) If a level distribution did not include a .gam file, you will need to
make one.  Just open a text editor and put the filename (and subdirectory, if
needed) on a single line of the file, then save that file as whatever.gam.

    3) That's it!  You can now run the new levels as follows:

python pyrunner.py newlevels.gam

    Note the .gam file on the command line.

    NOTE:  If you want to set the new levels to be your default adventure,
replace the file pyrunner.gam with another .gam file.  Be sure you backup the
pyrunner.gam file that you are replacing first, though!  Also, backup
pyrunner.sco and then replace it with the appropriate .sco file to preserve the
high scores.

    To install downloaded artwork, simply unpack them into their own
subdirectory.  The name of the subdirectory must match the artwork setting on
any levels that plan to use the new artwork.

    (Note that if you are creating your own artwork and followed the
instructions in the "Creating Artwork" section above, your artwork is already
installed and ready to be used.)

-- End of file:  editing.txt --
