How to Play PyRunner
====================

    To run PyRunner, change to the PyRunner directory and type:

python pyrunner.py

    Next, type in a name to be used for the high scores.  NOTE:  You are
currently limited to those keys which can be typed unshifted on your keyboard.
Press ENTER to register your name, and then get ready to play!

    NOTE:  You can include the name of the adventure (.gam) file on the command
line if you wish.  Otherwise, PyRunner will play the adventure in the file
pyrunner.gam.

    Licence
    -------

    PyRunner is distributed under the GNU GPL.  See the file COPYING for
licence details.

    Introduction
    ------------

    PyRunner is a simple game in which your goal as player is to try to collect
all the gold on each level and exit safely.  Normally, there'd be some kind of
storyline providing a reason for this, but in this case you can make up your
own.

    Your character is the _runner_, which you move around the _map_.  Each map
constitutes a _level_ of the game.  Maps are filled with objects -- some
dangerous, some helpful.  The objects in the map are explained in the next
section.

    While moving around the map, you will almost certainly find that you need
to dig out some of the floors.  This allows you to reach gold and other things
which may be hidden in between floors.  You cannot dig immediately under the
runner, but you can dig to either side provided something is not in your way.
It's important to remember this, or you can trap yourself very easily!  If you
get stuck, you will have to restart the level with the restart key - this costs
you a life!  Note that you can only dig regular floors.  Other objects,
including permanent floors, cannot be dug out.

    Dug floors will regenerate after a short time.  On some levels, you may
only be allowed to have a certain number of floors dug out at once.  (A story
would really be helpful for explaining this, but just accept it.)  If you dig
too much you will have to wait until a floor regenerates before you can dig
again.  On some levels, you may not even be allowed to dig at all!

    Throughout the level you may also encounter _enemies_.  If we had a story,
enemies would probably be described as guards whose task it is to prevent you
from getting the gold.  Enemies should be avoided as their touch is lethal.
Neither you or the enemies carry weapons, however you can use your digging
ability to trap enemies.  If a floor regenerates over an enemy, the enemy will
die.  Killing enemies is often less valuable than trapping them, because a dead
enemy will regenerate and come after you again.  Enemies can pick up one piece
of gold each.  Enemies may drop their gold at random, and will always drop it
when they start to fall (unless something is in the way).

    The player has the ability to survive falls of any height, thus you need
not worry about how far you fall.  It is far more important to know /what/ you
are falling onto.  If you fall onto an enemy, spikes, or into a pit with no
escape, you will die.

    Once you have collected all the gold, you must exit the level.  On some
levels this can be done by moving to the topmost row of the map.  On other
levels, you must find exit squares to exit the levels.  Still other levels
allow both options.  Check the status bar (described later) to find out where
you need to exit.  If you are having trouble completing a level, you may be
able to ask for a hint at the expense of some score.  (In hints, LtoR means
from left to right, and RtoL means right to left.)

    Note that on some levels, there may be more than one gold-collecting stage,
or none at all (i.e. you can exit immediately when you get to an exit point).
Again, watch the status line.  Some levels offer bonus gold which appears
after all of the main gold has been collected but does not have to be picked up
before exiting.  Again, check the status display.

    Different maps have different properties.  As already mentioned, maps may
or may not allow you to exit at the top and may have a variable number of
gold-collecting stages.  Your "dig limit" can also vary.  Other options include
"wrapping", either horizontally, vertically, or both.  On wrapping levels, if
you try to move off the screen you will move to the other side.  (Think of
these levels as being cylindrical or spherical.)  Finally, some levels may flip
the gates when all of the gold collecting stages are completed.  This is
usually used to inhibit your progress or allow previously trapped enemies to be
freed.

    Your objective is to finish the entire PyRunner "adventure".  An adventure
is simply a grouping of levels organized into a .gam file.  Each adventure has
its own rankings associated with it, and when you finish the adventure (or die
trying) your score will be permanently entered into the rankings where you can
see how you did compared to previous attempts.

    Controls
    --------

    These are the default controls used to play PyRunner:

    Arrows - Move the runner.

    Left Ctrl - Dig to the left of the runner.

    Left Alt - Dig to the right of the runner.

    H   - Request the next hint.

    P   - Pause the game.  Press again to resume.

    R   - Restart the current level.  Use this if you get stuck and cannot get
out.  You will lose your current life.

    Esc - Exit immediately.

    It is not currently possible to change the control assignments
interactively (within the game), but you can change the keys by modifying the
Python source code for PyRunner.  To do this, look for the keystroke processing
code near the bottom of the file pyrunner.py.  You will see constants like
K_LEFT, K_DOWN, K_LCTRL, etc.  Change these constants to those of the desired
new controls.  For a list of constants, see the pygame documentation for the
constants (a.k.a. locals) module.

    Joystick control is not yet supported.

    Objects
    -------

    These are the objects you will see on the map.  A brief description of
their appearance is given, but keep in mind that the exact appearance may vary
from level to level.

    Most objects can appear after all gold is collected, to either help or
hinder your progress towards an exit.

    WARNING:  It is possible for most types of objects to be false!  False
objects are merely projections and behave exactly like empty spaces.  Be aware
of the digging rules and other properties of objects as they will help you
identify false objects.  (For example, if you can dig underneath a ladder, the
ladder must be false.)  False objects cannot appear during a level, that is
anything that is false will appear when you begin the level only.

    Empty Space - Space in which there is nothing, and you are free to move
into.

    Floor - Looks more like a brick wall.  These are standard floors which will
support you, and can be dug out if needed.  You can not dig spaces under floors
without first removing the topmost floor.  Note that although called floors,
they may also be used as walls.

    Permanent Floor - Appears as a solid block.  These are just like floors
except they cannot be dug out.  Obviously, spaces under permanent floors cannot
be dug.  May also be used as walls.

    Gold - Looks like a small box with stripes.  This is what you are trying to
collect.  To collect gold, simply move over the gold and it will disappear.
(False gold will NOT disappear.)  You can dig under gold if needed.

    Ladder - You can climb up and down these, or step off at any point.  You
can also stand on top of a ladder to use it like a bridge.  Spaces under
ladders cannot be dug.

    Bar - A horizontal pole that lets you swing hand-over-hand across it.  You
can drop down from bars if desired.  Bars are not supportive, so you can not
"tightrope walk" across one.  You may dig under bars, and may dig even if you
are hanging from one.

    Pole - A vertical pole that you can slide down in a controlled manner
(stepping off if needed), but cannot ascend.  If you fall onto a pole from the
top you will be able to stand on it and use it as a floor.  Poles cannot be dug
under.

    One-way Gates - Spaces of a distinct colour with an arrow on it.  You may
not move through a one-way gate in the direction opposite the one shown by the
arrow.  However, if you are inside a one-way gate you can "abort" your one-way
trip by backing out of it.  One-way gates can be toggled by both the player and
enemies using switches.  Note that one-way gates are not floor-like so they
cannot support the player.  One-way gates cannot be dug under.

    Switches - Switches look like small control panels and cause one-way gates
to reverse direction.  To activate a switch. stand beside one and attempt to
dig it.  For this reason, switches cannot be dug under.  Note that any enemy
may also activate a switch!

    Spikes - Spikes are lethal and will kill the player and enemies on contact.
Spikes cannot be dug under if you are standing beside them.

    Exits - Appear as square "vortexes" with the word EXIT on them.  On any
level which has them, exit squares will let you leave the map and go on to the
next level.  They work even if exiting at the top of the map is an option.
When inactive (i.e. before you can exit), exit squares effectively behave like
one-way gates except of course that they do not restrict your movement in any
direction.

    Runner - The runner is your character, and appears as a small white stick
figure.

    Enemy - Enemies look just like the runner except they are a different
colour.  Coming into contact with an enemy is deadly.  However, in some cases
(most notably when an enemy is trapped in a single square) you may use an
enemy's head as a bridge safely, without falling.

    Enemy Regeneration Point - While not visible, you should know that enemies
may only regenerate from predesignated points.  Normally these are at the top
of the map, but they don't have to be.  If there are more than one of these
points, one will be chosen at random.  It is often helpful to learn where these
points are before progressing to later stages of levels.

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

    The following options will affect how a level plays.  All options are
displayed on the status line (see next section).

    Dig Limit - The number of floors that can be dug at any one time.  Reaching
this limit means you must wait until a floor regenerates before digging again.
Some levels have no dig limit.  A dig limit of 0 means you can't dig at all and
must find alternative ways to complete the level.  A lower dig limit usually
makes the level harder.

    Exit at Top - If enabled, you can exit the map by moving to the topmost
row of squares, or by reaching an exit square if any exit.  If disabled, you
/must/ find an exit square to leave the map.  A level is usually harder when
this option is disabled.

    Horizontal Wrapping - When enabled, moving off one side of the map will
cause you to reappear on the other side.  Otherwise, the sides of the map act
like permanent floors.  Worlds with horizontal wrapping enabled are normally a
bit harder, but in some cases the wrapping can provide an additional escape
route.

    Vertical Wrapping - Similar to horizontal wrapping.  When enabled, moving
off the top of the screen (via a ladder) causes you to appear at the bottom,
and moving off the bottom will put you back at the top.  Note that if Exit at
Top is enabled, it does not matter how you reach the top row.  That is, you can
exit by climbing to it as normal, or by falling/descending from the bottommost
row!  Worlds with vertical wrapping can be particularly difficult because it is
not always easy to wrap ones mind around the concept (pun intended, of
course!).

    Number of Stages - A "stage" consists of collecting all the gold on the
screen.  After each stage, new objects may appear on the map.  Most worlds have
only one stage.  However, a map can have two stages, in which you must collect
all the gold, then more will appear and you have to collect all of that gold
too before being allowed to exit.  Maps can also have zero stages, where your
sole task is to get to the exit and any gold you pickup along the way is a
bonus.  Bonus gold can also appear on maps with one or two stages.  The more
stages, the harder the level (usually).

    Flip Gates After Last Stage - If enabled, all one-way gates will reverse
when the final stage is completed (as if a switch was triggered).  This may be
done to hamper your progress or to release trapped enemies.  In some cases, it
may help you.  For example, if there is a one-way gate that leads to an area
with no exit and no switch, you might have to enter this area last and hope
that the gates will flip when you get the last piece of gold.  If disabled,
gates will not change except through switches.

    Status Bar
    ----------

    The bottom area of the screen serves as a status display, called the status
bar.  It consists of two lines of text.  On the first line are the following
displays:

    Score - Your total score to date.  See the next section on scoring.

    Lives - The number of lives your runner has.  When you run out of lives,
the game is over.

    Digs - The number of squares you may dig at any one time.  This will go
down as you dig, and go up as floors regenerate.  When it reaches 0, you may
not dig until a floor regenerates.

    Gold - The number of gold pieces currently on the map.  Each time you
collect gold, this number will decrease.  When it reaches 0, the stage ends.
If this number is higher than the number of gold pieces visible on screen, at
least one enemy has gold and will have to drop it or be killed with it.  If
this number of lower, at least one of the gold pieces visible is false.

    Stages - The number of stages (gold-collecting rounds) remaining.  When
this reaches 0, you will be able to exit the level.

    Level - The number of the level you are currently playing.

    Lastly, a series of letters will appear when to tell you which options are
enabled.  If a letter is missing it means that the option is disabled.

        H   Horizonal Wrapping
        V   Vertical Wrapping
        T   Exit at Top
        F   Flip Gates After Last Stage

    The second line of the status bar shows the current hint, if one has been
requested.  Otherwise, it shows the title and author of the level, or some
other information that the author wants you to know.

    Scoring
    -------

    100 points for each gold collected.

    200 points for each bonus gold (i.e. gold visible when stages=0).

    10 points for each enemy killed by trapping (in a dug floor).

    1 point for each enemy killed by some other means (e.g. spikes).

    -500 points for each hint requested.  Negative scores are permitted.  Note
that when hints "recycle" (after all have been seen) you will not be deducted
points, so you can freely review all hints.

    50 points bonus for each life remaining when a level is completed.

    1000 points for completing the last level of an adventure.

    Bonus life every 10000 points (this does not affect your score).

    PyRunner maintains a list of rankings for each PyRunner adventure.  When
you finish your game, you will be shown how well your score fared against past
attempts.

    Editing Levels
    --------------

    You can create your own levels for PyRunner using just a text editor!  See
the file editing.txt for complete instructions.  Note that you should play
through at least the default adventure before attempting to make your own
levels, so you can get a good idea of how the various elements of the game
work.

    New levels and artwork can also be downloaded from the PyRunner web site:

    http://members.home.net/paulsid/pyrunner/files.html

    To install new levels, follow the instructions at the bottom of
editing.txt, or any instructions provided with the downloaded level package.

    Playing Tips
    ------------

    Here are some tips to help improve your PyRunner playing ability:

    - Plan a strategy.  It's tempting to just start running around, but if you
stop and have a look around you can locate danger spots, tricky gold to get
(e.g. a gold under four layers of floor), and potential traps (e.g. areas with
no escape).

    - Learn the first fundamental of digging:  Dig a row behind you of
sufficient length, then jump in and dig another row in the opposite direction,
repeating until you get to your goal.  For solid floors, you need a minimum of
n+1 consecutive empty squares to get through n rows of floor (n >= 2).  If you
haven't learn to dig "compactly" yet, give yourself more room.  Don't forget to
include in n any levels below the gold you are going for!

    - Watch out for false objects.  In PyRunner, just about everything can be
false including gold, exits, spikes, and floors.  Use deduction to determine
where false objects lie.  For example, a piece of gold immediately above a
spikes means that either the gold or the spikes are false.  Similarly, gold
sitting in a place with no escape is either false or has a false floor below it
allowing for escape.  The status line should help you determine which object is
the true false one.  (This assumes the level is properly designed, i.e. that it
can be reliably completed without dying unless you make a mistake.  All levels
distributed with PyRunner and those available on the web site meet this
criteria, unless clearly indicated otherwise.)

    - Don't cheat.  While you can always look at a map's data file to see
everything, it isn't a very useful way to play the game.  Besides, it doesn't
always help.  There are some levels that have no false objects and no traps
that are just difficult to get through.  However, if you get stuck, do use the
hint feature.  Ideally, hints will start you off with small tips (e.g. "One of
the floors is false!") and get progressively more revealing.

    - Learn the enemy regeneration points.  Most of the time the enemies will
regenerate at the top of the screen, and most levels have a bottom-to-top
progression.  This means that as you get further through the level you will
have to watch out for regenerating enemies.  In this case it may be better to
simply cut off the enemies (e.g. by digging where they can fall down while you
proceed upwords) than to kill them.

    - Trapping enemies is your greatest weapon.  A dead enemy will be off your
case for a little while, but a trapped enemy is permanently disabled.  Some
levels will have specific areas for trapping enemies (and may even require it
in order to pass the level), and others have areas that will do the job nicely.

    - On wrapping worlds, learn to think circularly.  It's tough to anticipate
enemies coming at you from the opposite side of the screen, or climbing off the
top of the screen to get to the bottom, but learning to do so without having to
think about it is a big advantage.  On vertically wrapping worlds, there is the
added danger of the "bottomless pit" - a column where you can fall infinitely
until you press the restart key.  (Good levels will avoid this or ensure that
such a column, if it exists, can be safely avoided by figuring out the level.)

    - If you get really good and want a special challenge, try changing the
artwork setting of a level to "mixup".  :-)

    Final Words
    -----------

    PyRunner is an open source project.  If you have a level, artwork set, game
patch, or feature addition, please send it to the author:  Paul Sidorsky
<paulsid@home.com>  You can also use the same address to send questions,
comments, and suggestions.

    Visit the PyRunner web site at http://members.home.net/paulsid/pyrunner/
for news, updates, and related files.

    Lastly, please note that PyRunner was an experimental project and is not
high on the author's priority list.  Updates will tend to be infrequent.  That
being said, I do plan to finish the program in the near future, and if I can't
I'll try to find somebody who can.

    Enjoy the game!

-- End of file:  howtoplay.txt --
