\\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename pingus.info
@settitle Pingus
@c %**end of header

@dircategory Games
@direntry
* Pingus: (pingus).           Pingus - A free Lemmings Clone
@end direntry

@setchapternewpage off

@ifinfo
This is a short example of a complete Texinfo file.

Copyright @copyright{} 1999 Ingo Ruhnke @email{grumbel@@gmx.de}.
@end ifinfo

@titlepage
@sp 10
@title Pingus
@subtitle Playing and Programming
@author by Ingo Ruhnke @email{grumbel@@gmx.de}

@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1999 Ingo Ruhnke @email{grumbel@@gmx.de}.
@end titlepage
@headings off

@node Top
@top Pingus - guide the little pingus to the exit
@c @contents

$Id: pingus.texi,v 1.7 2000/06/20 20:35:15 grumbel Exp $ 

This TeXInfo documentation is still under development, but it should
contain some usefull informations

@menu
* Introduction::        A small overview of pingus.
* Command-line::        Command-line options
* Actions::             What can the Pingus do?
* Level Editor::        How to use the level editor
* Levels::              A short intro to the inner levelformat
* Directories::         An overview of the directory structure
* Related Reading::     Some other sources of information
@end menu

@node    Introduction
@chapter Introduction

Pingus is a free Lemmings clone covered under the GPL. It is mainly
coded by Ingo Ruhnke @email{grumbel@@pingus.cx}, graphics are mainly
painted by Joel Fauche @email{joel.fauche@@wanadoo.fr}, Craig Timpany
@email{timpany@@es.co.nz} and Michael Mestre
@email{mmestre@@teaser.fr}. For a full list of contributors have a look
at the @file{AUTHORS} file.

The newest version of Pingus can always be found at:

@url{http://www.pingus.cx}

@node    Command-line
@chapter Command-line

@table @code

@item -g GEOMETRY
@itemx --geometry GEOMETRY

Set the screen resolution or the window size to GEOMETRY, where
GEOMETRIE is WIDTHxHEIGHT. For example the option could look like this: 

@example
$ pingus -g 800x600
@end example

If you want to run the game fullscreen, just set the width and height
to the your screen resolution and ask your window manager to hide the
window borders.

@item -V, --version

Prints the version number and exit.

@item -t, --speed SPEED

Set the speed (0 = maximum speed)

@item -v, --verbose VERBOSITY
Sets the verboseness of Pingus to VERBOSITY. The default value is 1 for
the moment.  

@item --disable-intro
Disables the intro.

@item -F, --disable-fullscreen
Disables fullscrenn support and start Pingus in a window if supported by
the display target.

@item -f, --enable-fullscreen
Starts Pingus in fullscreen instead of a window if supported by the
display target (default).

@item -i, --enable-gimmicks
Enables some experimental or useless stuff (out of date). 

@item -d, --datadir PATH
Set the datafile search patch for Pingus to PATH.

@item -l, --level FILE
Directly start the fiven level, without going throu the main menu. Its
not required to use -l or --level, since the last argument will be
allways treat as a level.

@item -b, --print-fps
Prints the number of frames per seconds in the upper upper right corner
of the Statusbar, when the game is running.

@item --fast
Disables the background and the particle throwing, to make the game some
fps faster.

@item -e, --editor
Directly start the editor, without going throu the main menu.

@item --disable-auto-scrolling
Don't scroll the game area when the mouse it at the window border.

@item -p, --play-deme FILE
Loads a demo file and plays it. Demos are automatically recorded to
@file{~/.pingus/demos/}.

@item -s, --enable-sound
Enables sound playback in the game, its only available when Pingus was
compiled with sound support.

@item -m, --enable-music
Enables the backgronud music playback in the game, its only available
when Pingus was compiled with sound support.

@item --audio-format 
Sets the bit bandwidth the sound driver should use. 8bit is recommend
for slower machines.

@item --audio-rate INT
Sets the audio-rate (Hz) to the supplied value, lower values (11000) are
recommend for slower machines.

@item --audio-channels @{1,2@}
Sets the sound support to mone(1) or stereo(2).

@item --audio-buffers INT
Sets the memory size Pingus should use to buffer sound (default: 4096).

@end table

@node    Actions
@chapter Actions

@itemize @bullet

@item Basher

A pingu which got the basher action will start to dig into the wall
in front of him. If the wall ends or the pingu hits solid ground, he
will stop the bashing and continue to walk. The bashing action will be
gone 


@item Blocker

A blocker will turn around all pingus which reach him, no pingu can pass
a blocker. If a pingu was turned into a blocker, he can not get any
other action, he will stay as a blocker until he his turned into a
bomber or until the ground below him is digged away.
        
@item Bomber

If a pingu got this action, he will count down from 50 to 0. If he has
finished the counting, he will blow up and then explode.

@item Builder
A builder will start to build a bridge, but he has only a limited number of
stones so the bridge will not be very large. If the pingu is out of
stones he will turn back into a walker.

@item Climber

A climber is able to walk on walls. He will have this action, ones
applied, forever. Whenever he reaches a wall he will try to walk it up. 


@item Digger

A digger will dig straight into the ground. If he reaches a solid block
or there is no longer any ground under him, he will turn back into a
normal walker.


@item Floater

Normaly a pingu will die when he is falling from a high mountain, but if
he got the floater action, he will use his little propeller to stop his
fast fall and so he can survive the fall.


@item Jumper

If a pingu got the jumper action, he will do a quick jump and than turn
back into a normal when he hit the ground again.


@item Miner

A Miner will dig into the ground, as the digger, but instead of digging
vertically, he will dig diagonal. 


@end itemize

@c --------------------------------------------------------------------------
@node    Level Editor,  ,  Actions, Top
@comment node-name,    next,  previous,      up
@chapter Level Editor

@menu
* Key bindings::    A list of all keys available in the editor
* Tips::            Some tips on how to use the level editor
@end menu

@node Key bindings
@section Key bindings

@table @samp
@item F2
Toggles if animated objects are animated in the editor or not.

@item F3
Toggles the background color

@item F4
Play/Test the level, which is loaded into the editor. The level will
be saved temporary to @file{/tmp/}

@item F5
Load a level from file, the current level is saved temporary to
@file{/tmp/}.

@item F6
Saves the current level.

@item F7 Set checkpoint
Sets a checkpoint, the level is than saved temporary to @file{/tmp/}. It
can be reloaded quickly by pressing F8

@item F8
Restores a previously set checkpoint, the last checkpoint is loaded. The
current stated is saved to @file{/tmp/}, just for the case you accidently
pressed the key.

@item F9
Change the height and width of the level.

@item F10
Change the background image and the background properties of the current
level.

@item Insert
Insert an new object, you will get a sort menu were you can select what
type of object you want to insert.

@item Delele
Removes the marked object

@item RShift
If you move objects around with the cursor keys and you hold down the
right shift key, the objects are moved 10 pixels, instead of 1 pixel.

@item LShift
If the left Shift key is hold down while marking objects with the mouse,
the objects are added to the selection.

@item PgUp
Moves the current object or group one position up.

@item PgDown
Moves the current object or group one position down.

@item Escape
Exit the editor, the current level is temporary saved under '/tmp/'.

@item Cursor keys
Move all marked objects around.

@item A
Add all objects to the selection.

@item D
Duplicate the current selection

@end table

@node Tips
@section Tips

@itemize @bullet

@item Segfaults and other errors

If the editor segfaults or other errors occur while you where building a
level, the level is probably not lost. The editor saves the level on all
critical actions (loading, saving, deletion, checkpointing) to a file in
@file{/tmp/}. You will need to have a look into @file{/tmp/} to see when
the last save has occured. The following command should list the most
recend level:

@example
$ ls -cl /tmp/*pingus.plf | head -n 1
@end example

@item Resources

If you want to insert an object in the editor you need to now the exact
resource name of it, the tab-completion might help, but if you want a
complete list of all resources, you might try the following.  If you
have compiled Pingus yourself, just have a look at the file
@file{global.scr}. If you are using a binary version of Pingus (RPM or
Deb package) then search for a file @file{global.dat} and do the
following:

@example
$ strings global.dat | egrep "^[A-Za-z0-9_/]+/[A-Za-z0-9_/]+$"
@end example

This will give you a complete list of all resources. 

@item Editing Levels files by hand

If you are playing with the level editor you might ask yourself, how you can
add this or that feature (levelname, leveldescription, width,
height,...) to a level, when you don't have a button for it.

The answer might be by some obscure keypress (F1-F10)
or probably you will have to edit the level files yourself. Some intro
to the level format is given in this manual, the syntax should be easy
to understand. If you have questions contact Ingo Ruhnke @email{grumbel@@gmx.de}.

@item Adding selfmade gfx

If you are planning to add new selfmade gfx to a level, you need to add
it to the datafile first. To do this search for the file
@file{global.scr} and edit it, after you edited it run @samp{make}
again. You should now be able to use that gfx inside a level. A more
user friendly methode to add new gfx will be added later.
If you have questions contact Ingo Ruhnke @email{grumbel@@gmx.de}.

@end itemize

@c --------------------------------------------------------------------------
@node    Levels,,,Top
@comment node-name,    next,  previous,      up
@chapter Levels

A pingus level consist basicaly of three (at the moment four, but that
will change) parts: 

@menu
* PLF::     A level describtion file (@file{*.plf})
@end menu

@c --------------------------------------------------------------------------
@node    PLF, ,  Levels, Levels
@section PLF - Pingus Level File

The Pingus Level File (short @strong{PLF}) describes a pingus level. It
is a simple C style ascii file. All images and other data which is
needed is saved as a data file, which as to be compiled with the
@samp{datafile_compiler} from ClanLib, see the man page for more details.
The an example of the PLF file looks as follows:

@example
        ground @{
                maptype = SPOT;
                data = (file)"spot.psm";
                colmap = (resource)"ColMaps/level2";
        @}
        ...
@end example

Its syntax is like this:


@example
        groupname @{
                valueid = (valuecast)value;
                ...
        @}
@end example

Following groupname's are available:

@table @samp
@item global
        @itemize @bullet

        @item

        The upper/left corner of the screen, when the game starts:

@example
        start_x_pos = INT
        start_y_pos = INT
@end example

        @item
        The number of pingus, which will be released in that level:
        number_of_pingus = INT

        @item
        The levelname:
        levelname = STRING

        @item
        A short description of the level:
        description = STRING

        @end itemize
@item ground
This group contains all informations needed to build the ground
map
        @itemize @bullet

        @item
        

        @end itemize
@item background
Sets the file of the foreground, normaly this will be a @file{*.ptm} file.
@item music
Sets the location of the colision map, this will become obsolete if the
PNG loading works and the colision map is generated from the tiles
@item exit
Sets the start positon of the screen.
@item entrance
Sets the number of pingus for this level.
@item trap
Defines the location of a hotspot for the foreground.
@item buttons
Defines the location of a hotspot for the background.
@end table

@node  Directories,,, Top
@chapter  The Directory Structure of Pingus

Pingus can have its levels and other data installed under different
directories. At default the data is installed under
@file{$prefix/share/games/pingus/} and at @file{$home/.pingus/}, you can
expand the search path by adding the directories to PINGUS_DATADIR or by
starting Pingus with the option -d PATH.

@node Related Reading,,, Top
@chapter Related Reading

Nothing here yet.

Have a look at the Pingus webpage at @url{http://pingus.seul.org} for
up to date infos.

@bye
