<?xml version="1.0" standalone="no"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
          "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
          <!ENTITY % pingusstuff SYSTEM "pingus.ent">
          %pingusstuff;
          ]>
<refentry id="pingus"> 
  <refmeta>
    <refentrytitle>
      <application>pingus</application>
    </refentrytitle>
    <manvolnum>6</manvolnum>
    <refmiscinfo class="version">&pingus_version;</refmiscinfo>
    <refmiscinfo class="author">&pingus_version;</refmiscinfo>
    <refmiscinfo class="manual">User Commands</refmiscinfo>
    <refmiscinfo class="source">pingus</refmiscinfo>
  </refmeta>

  <refnamediv>
    <refname>
      <application>pingus</application>
    </refname>
    <refpurpose>
      A puzzle game where you have to save penguins
    </refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <cmdsynopsis>
      <command>pingus</command>
      <arg choice="opt" rep="repeat">OPTION</arg>
      <arg choice="opt">FILE</arg>   
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>Description</title>
    <para>
      Pingus is a side-scrolling puzzle game where the player has to
      guide a group of penguins from the entrance of a level to the
      exit, in between the path is blocked by numerous obstacles and
      dangers that the player has to overcome by assigning actions to
      the penguins.
    </para>
  </refsect1>

  <refsect1>
    <title>Options</title>
    <refsect2>
      <title>General Options</title>

      <variablelist>
        <varlistentry>
          <term>-h, --help</term>
          <listitem>
            <para>Displays this help</para>
          </listitem>
        </varlistentry>

        <varlistentry>      
          <term>-V, --version</term>
          <listitem>
            <para>Print version number and exit</para>
          </listitem>
        </varlistentry>

        <varlistentry>      
          <term>-v, --verbose</term> 
          <listitem>
            <para>Enable info level log output</para>
          </listitem>
        </varlistentry>

        <varlistentry>      
          <term>-D, --debug</term>
          <listitem>
            <para>Enable debug level log output</para>
          </listitem>
        </varlistentry>

        <varlistentry>      
          <term>-Q, --quiet</term>       
          <listitem>
            <para>Disable all log output</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </refsect2>

    <refsect2>
      <title>Display Options</title>
      <variablelist>
        <varlistentry>
          <term>-w, --window</term>
          <listitem>
            <para>Start in Window Mode</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>-f, --fullscreen</term>
          <listitem>
            <para>Start in Fullscreen</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>-r, --renderer=RENDERER</term>
          <listitem>
            <para>
              Use the given renderer, defaults to sdl. Available renderers are:
            </para>
            <variablelist>
              <varlistentry>
                <term>sdl</term>
                <listitem>
                  <para>A simple software renderer based on SDL, this
                    is the default and the safest options.</para>
                </listitem>
              </varlistentry>
              <varlistentry>
                <term>opengl</term>
                <listitem>
                  <para>The OpenGL renderer will use hardware
                    acceleration to render the graphics, it is much
                    faster then the SDL renderer and recommended when
                    the hardware supports OpenGL.</para>
                </listitem>
              </varlistentry>
              <varlistentry>
                <term>delta</term>
                <listitem>
                  <para>The delta renderer uses SDL for rendering and
                    doesn't use hardware acceleration, it will however
                    try to increase rendering performance by only re
                    rendering screen elements that have changed. Using
                    the delta renderer will disable some effects such
                    as scrolling background to allow maximum
                    benefits.</para>
                </listitem>
              </varlistentry>
            </variablelist>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>-g, --geometry=WIDTHxHEIGHT</term>
          <listitem>
            <para>Set the window resolution for pingus (default:
              800x600). Note that <option>--geometry</option> only
              applies to the window resolution, for the fullscreen
              resolution
              use <option>--fullscreen-resolution</option></para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>-R, --fullscreen-resolution=WIDTHxHEIGHT</term>
          <listitem>
            <para>Set the resolution used in fullscreen mode (default: 800x600)</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>--software-cursor</term>
          <listitem>
            <para>Enable software cursor</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </refsect2>

    <refsect2>
      <title>Game Options</title>
      <variablelist>
        <varlistentry>
          <term>--no-auto-scrolling</term>
          <listitem>
            <para>Disable automatic scrolling. Automatic scrolling
              will cause the screen to scroll whenever the mouse reaches
              the border of the screen. Automatic scrolling will only be
              active in fullscreen mode or when mouse-grab is
              enabled.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>--drag-drop-scrolling</term>
          <listitem>
            <para>Enable drag'n drop scrolling. By default Pingus will
              use a rubber-band scrolling where the scroll speed
              depends on how far away the cursor is from the position
              when the mouse button has been clicked. In drag&amp;drop
              mode scrolling will behave more like in traditional GUI
              applications such as Gimp, where clicking the scroll
              button will 'pick up' the playfield and allow to move it
              around till it is released again.</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </refsect2>

    <refsect2>
      <title>Sound Options</title>
      <variablelist>
        <varlistentry>
          <term>-s, --disable-sound</term>
          <listitem>
            <para>Disable sound</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>-m, --disable-music</term>
          <listitem>
            <para>Disable music</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </refsect2>

    <refsect2>
      <title>Language Options</title>
      <variablelist>

        <varlistentry>
          <term>-l, --language=LANG</term>
          <listitem>
            <para>Select language to use with Pingus</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>--list-languages</term>
          <listitem>
            <para>List all available languages</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </refsect2>

    <refsect2>
      <title>Editor Options</title>
      <variablelist>
        <varlistentry>
          <term>-e, --editor</term>
          <listitem>
            <para>Loads the level editor</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </refsect2>

    <refsect2>
      <title>Directory Options</title>
      <variablelist>
        <varlistentry>
          <term>-d, --datadir=DIR</term>
          <listitem>
            <para>Load game datafiles from DIR</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>-u, --userdir=DIR</term>
          <listitem>
            <para>Load config files and store savegames in DIR</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>-a, --addon=DIR</term>
          <listitem>
            <para>Load game modifications from DIR. Files in DIR will
              be used instead of the files in found in the main datadir
              of Pingus, thus allowing to modifications, such as sprites
              replacements, additional levels, etc. to the game, without
              changing the main data files.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>--no-cfg-file</term>
          <listitem>
            <para>Don't read ~/.pingus/config</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>-c, --config=FILE</term>
          <listitem>
            <para>Read config from FILE</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>--controller=FILE</term>
          <listitem>
            <para>Uses the controller given in FILE</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </refsect2>

    <refsect2>
      <title>Debug Options</title>
      <variablelist>
        <varlistentry>
          <term>--developer-mode</term>
          <listitem>
            <para>Enables some special features for developers</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>-t, --speed=SPEED</term>
          <listitem>
            <para>Set the game speed (0=fastest, >0=slower)</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>-k, --fps=FPS</term>
          <listitem>
            <para>Set the desired game framerate (frames per second)</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>--tile-size=INT</term>
          <listitem>
            <para>Set the size of the map tiles (default: 32)</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </refsect2>
  </refsect1>


  <refsect1>
    <title>Keyboard Shortcuts</title>
    <refsect2>
      <title>Gameplay</title>
      <para>
        All gameplay related keyboard shortcuts are configurable via a
        controller config file, see <option>--controller</option>
        and <filename>controller/default.scm</filename>.
      </para>
      <variablelist>
        <varlistentry>
          <term><keycombo><keycap>Space</keycap></keycombo></term>
          <listitem>
            <para>
              Activate fast-forward mode.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><keycombo><keycap>P</keycap></keycombo></term>
          <listitem>
            <para>
              Pause the game.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><keycombo><keycap>S</keycap></keycombo></term>
          <listitem>
            <para>
              Advance the game by a single frame.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><keycombo><keycap>A</keycap></keycombo></term>
          <listitem>
            <para>
              Activate armageddon.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><keycombo><keycap>Escape</keycap></keycombo></term>
          <listitem>
            <para>
              Leave the current screen/level.
            </para>
          </listitem>
        </varlistentry>

      </variablelist>
    </refsect2>

    <refsect2>
      <title>Engine</title>
      <variablelist>
        <varlistentry>
          <term><keycombo><keycap>F10</keycap></keycombo></term>
          <listitem>
            <para>
              Show/hide the FPS counter.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><keycombo><keycap>Alt</keycap> <keycap>Return</keycap></keycombo></term>
          <term><keycombo><keycap>F11</keycap></keycombo></term>
          <listitem>
            <para>
              Switch to fullscreen/window mode.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><keycombo><keycap>Ctrl</keycap> <keycap>g</keycap></keycombo></term>
          <listitem>
            <para>
              Toggle mouse grab, when active, the mouse can not leave the window.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><keycombo><keycap>Ctrl</keycap> <keycap>o</keycap></keycombo></term>
          <term><keycombo><keycap>F5</keycap></keycombo></term>
          <listitem>
            <para>
              Show the option menu.
            </para>
          </listitem>
        </varlistentry>

        <!--
           <varlistentry>
             <term><keycombo><keycap>F6</keycap></keycombo></term>
             <listitem>
               <para>
                 Show the AddOn Menu
               </para>
             </listitem>
           </varlistentry>
           -->

        <varlistentry>
          <term><keycombo><keycap>F12</keycap></keycombo></term>
          <listitem>
            <para>
              Make a screenshot. Screenshots are stored
              in <filename>~/.pingus/screenshots/</filename>.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><keycombo><keycap>Ctrl</keycap> <keycap>m</keycap></keycombo></term>
          <listitem>
            <para>
              Toggle the developer mode, see <option>--developer-mode</option>
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><keycombo><keycap>c</keycap></keycombo> (only in developer-mode)</term>
          <listitem>
            <para>
              Show the collision map overlayed over the regular groundmap.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><keycombo><keycap>k</keycap></keycombo> (only in developer-mode)</term>
          <listitem>
            <para>
              Clear the screen for delta mode debugging.
            </para>
          </listitem>
        </varlistentry>
        
      </variablelist>
    </refsect2>
  </refsect1>

  <refsect1>
    <title>Actions</title>
    <variablelist>
      <varlistentry>
        <term>Basher</term>
        <listitem>
          <para>
            The Basher will to a horizontal dig, leaving behind it a
            tunnel. It is not able to dig through metal.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>      
        <term>Blocker</term>
        <listitem>
          <para>
            The Blocker will stop and stay in position, directing
            other penguins to turn around when they reach him.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Bomber</term>
        <listitem>
          <para>
            The Bomber will blow up on the spot and take a bit of
            surrounding ground with it.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Bridger</term>
        <listitem>
          <para>
            The Bridger will build a small bridge, useful for crossing
            small chasm.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Climber</term>
        <listitem>
          <para>
            The Climber actions allows a Pingu to travel upwards a
            vertical wall. Unlike other actions the climber action is
            a permanent addition to the Pingus ability.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Digger</term>
        <listitem>
          <para>
            The Digger will dig a hole into the ground. It can't dig
            through metal.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Floater</term>
        <listitem>
          <para>
            The Floater action will give a penguin a small propeller
            that lets him gently glide down from great heights that
            would otherwise be deadly.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Jumper</term>
        <listitem>
          <para>
            The Jumper will let the Pingu do a big leap forward,
            allowing him to cross chasm and small vertical obstacles.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Miner</term>
        <listitem>
          <para>
            The Miner will dig a diagonal hole into the ground.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Slider</term>
        <listitem>
          <para>
            The Slider will make a tiny leap forward, gliding on its
            belly for a short while, allowing the Pingu to make it
            through narrow tunnels.
          </para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1>
    <title>Copyright</title>
    <para>
      Copyright (C) 1998-2011 Ingo Ruhnke <email>grumbel@gmail.com</email>
      See the file AUTHORS for a complete list of contributors.
      Pingus comes with ABSOLUTELY NO WARRANTY. This is free software, and you are
      welcome to redistribute it under certain conditions; see the file COPYING for details.
    </para>
  </refsect1>

  <refsect1>
    <title>See also</title>
    <para>
      http://pingus.seul.org
    </para>
  </refsect1>
</refentry>
