<?xml version='1.0'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<book>
  <info>
    <title>Magicor manual</title>
    <author><firstname>Peter</firstname><surname>Gebauer</surname></author>
    <copyright><year>2006-2007</year><holder>Peter Gebauer</holder></copyright>
  </info>
  <preface id="preface">
    <title>Magicor, the puzzle game</title>
    <informaltable frame='none'>
      <tgroup cols='2' align='left' colsep='1' rowsep='1'>
        <tbody>
          <row>
            <entry>
              <mediaobject>
                <imageobject>
                  <imagedata fileref="screenshot01.png"/>
                </imageobject>
              </mediaobject>
            </entry>
            <entry>
              This is a fast-paced puzzle game that you can play for five 
              minutes or hours, depending on how much time you have and how
              much you like it. The objective is to extinguish burning fires
              using already blocks of ice, either created by the player or the
              game itself. Although learning the game physics and controls is
              easy, solving some of the levels is not.
            </entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>
    <para>
      The game is free (as in freedom of speech), licensed as Public Domain,
      and it has been developed using all free tools and libraries on 
      free platforms. Enjoy it! (note: the game is also ported to Windows,
      thanks Claudio!) See link 
      <link linkend="license" endterm="license.title"/> 
      for license information.
    </para>
  </preface>
  <chapter id="objective">
    <title>Game objective</title>
    <para>
      The objective of the game is to extinguish all bunring fires. You do
      this by pushing or dropping ice blocks so they collide with the fire
      using the player.
    </para>
    <table frame="none" id="common_objects">
      <title>Common objects in the game</title>
      <tgroup cols='2' align='left'>
        <colspec colname='type'/>
        <colspec colname='image'/>
        <tbody>
          <row>
            <entry>Player</entry>
            <entry>
              <mediaobject>
                <imageobject>
                  <imagedata fileref="player.png"/>
                </imageobject>
              </mediaobject>
            </entry>
          </row>
          <row>
            <entry>Ice block</entry>
            <entry>
              <mediaobject>
                <imageobject>
                  <imagedata fileref="ice.png"/>
                </imageobject>
              </mediaobject>
            </entry>
          </row>
          <row>
            <entry>Fire</entry>
            <entry>
              <mediaobject>
                <imageobject>
                  <imagedata fileref="fire.png"/>
                </imageobject>
              </mediaobject>
            </entry>
          </row>
        </tbody>
      </tgroup>
    </table>
    <para>
      To push an ice block you need only walk towards it, try to walk through
      it even, the player will kick the ice block once in contact with it and
      the block will slide until it hits a wall or falls down.
    </para>
    <mediaobject>
      <imageobject>
        <imagedata fileref="screenshot02.png"/>
      </imageobject>
      <caption>
        <para>Like the arrows suggest, just walk towards the ice block.</para>
      </caption>
    </mediaobject>
    <mediaobject>
      <imageobject>
        <imagedata fileref="screenshot03.png"/>
      </imageobject>
      <caption>
        <para>
          Try walking past the ice block, the player will kick it and the
          ice block will slide towards the fire, eventually hitting it and
          thus extinguishing it.
        </para>
      </caption>
    </mediaobject>
    <para>
      That is how you push/slide an already existing block of ice, but the
      player can also create and destroy ice blocks. The player is limited
      to creating and destroying ice blocks <emphasis>below</emphasis> the
      player left and right sides.
    </para>
    <mediaobject>
      <imageobject>
        <imagedata fileref="screenshot04.png"/>
      </imageobject>
      <caption>
        <para>
          A clear case of having to create ones own ice blocks. Just walk
          up to the ledge and press the action button. The tutorial arrows
          indicate that something needs to be done no less than four times.
        </para>
      </caption>
    </mediaobject>
    <mediaobject>
      <imageobject>
        <imagedata fileref="screenshot05.png"/>
      </imageobject>
      <caption>
        <para>
          *Swosh* and there's the newly created block of ice. The block
          will freeze stuck to the ledge so the player can safely stand on it.
        </para>
      </caption>
    </mediaobject>
    <mediaobject>
      <imageobject>
        <imagedata fileref="screenshot06.png"/>
      </imageobject>
      <caption>
        <para>
          The player has now created a walking bridge of connected ice blocks
          all the way to above the fire.
        </para>
      </caption>
    </mediaobject>
    <mediaobject>
      <imageobject>
        <imagedata fileref="screenshot07.png"/>
      </imageobject>
      <caption>
        <para>
          We step back one unit and sever the connection by the destroying a
          block of ice so that the rightmost ice block will be disconnected. 
          Once disconnected the ice block will start to fall towards the fire.
          Again, when hitting the fire it will be extinguished; mission 
          accomplished!
        </para>
      </caption>
    </mediaobject>
    <para>
      Pushing ice blocks can only be done if the ice block has no obstacles
      on the other side. Even another ice block will stop an ice block from
      being pushed.
    </para>
    <mediaobject>
      <imageobject>
        <imagedata fileref="screenshot08.png"/>
      </imageobject>
      <caption>
        <para>
          These ice blocks are too heavy to push.
        </para>
      </caption>
    </mediaobject>
    <mediaobject>
      <imageobject>
        <imagedata fileref="screenshot09.png"/>
      </imageobject>
      <caption>
        <para>
          So the player simply climbs up. Note that the player can only climb
          on top of blocks that are reachable. (one block worth of height)
        </para>
      </caption>
    </mediaobject>
    <para>
      Once on top of ice blocks you can destroy one of them or jump down on 
      the other side. This climbing behaviour is activated every time you try
      to push an ice block that is next to another ice block or a solid ledge.
    </para>
    <para>
      An explanation of falling blocks: unless single ice blocks (or even a
      row of connected ice blocks) is supported by solids below or connected
      to solids, it will start to fall until it hits a solid, is destroyed
      or falls into obvlivion (below screen visibility).
    </para>
  </chapter>

  <chapter id="complicating">
    <title>Complicating the game</title>
    <para>
      You didn't think all levels would be as easy as the tutorial ones, did
      you? There are several additional elements to make solving the levels
      more difficult.
    </para>
    <table frame="none" id="additional_objects">
      <title>Some additional objects</title>
      <tgroup cols='2' align='left'>
        <colspec colname='type'/>
        <colspec colname='image'/>
        <colspec colname='description'/>
        <tbody>
          <row>
            <entry>Spikes</entry>
            <entry>
              <mediaobject>
                <imageobject>
                  <imagedata fileref="spikes.png"/>
                </imageobject>
              </mediaobject>
            </entry>
            <entry>
              These are nearly invisible, burried into solids. If the player or
              an ice block is near this trap, spikes will shoot out killing
              the player or destroying the ice block.
            </entry>
          </row>
          <row>
            <entry>Active lava</entry>
            <entry>
              <mediaobject>
                <imageobject>
                  <imagedata fileref="lava.png"/>
                </imageobject>
              </mediaobject>
            </entry>
            <entry>
              Active lava will kill the player and destroy ice if touched.
            </entry>
          </row>
          <row>
            <entry>Dormant lava</entry>
            <entry>
              <mediaobject>
                <imageobject>
                  <imagedata fileref="dormant-lava.png"/>
                </imageobject>
              </mediaobject>
            </entry>
            <entry>
              This type of dormant lava is harmless to both player and
              ice blocks, but beware: lava can be ignited if a burning fire
              should happen to touch it, making it active, lethal lava.
            </entry>
          </row>
        </tbody>
      </tgroup>
    </table>
    <para>
      To make things even worse many levels will have moving enemies that will
      kill the player on touch. Lucky for the player, these enemies can be
      destroyed by squishing them between an ice block and a solid or another
      ice block. Depending on the level theme these enemies move and look
      differently, below are some examples.
    </para>
    <table frame="none" id="enemy_examples">
      <title>Enemy examples</title>
      <tgroup cols='2' align='left'>
        <colspec colname='type'/>
        <colspec colname='image'/>
        <tbody>
          <row>
            <entry>Scarab (from Egypt theme)</entry>
            <entry>
              <mediaobject>
                <imageobject>
                  <imagedata fileref="scarab.png"/>
                </imageobject>
              </mediaobject>
            </entry>
          </row>
          <row>
            <entry>Blob (from Space theme)</entry>
            <entry>
              <mediaobject>
                <imageobject>
                  <imagedata fileref="blob.png"/>
                </imageobject>
              </mediaobject>
            </entry>
          </row>
        </tbody>
      </tgroup>
    </table>
    <para>
      As you can see, with the additional, very dangerous objects this game
      can become quite complicated in spite of it's simple physics engine.
      Many levels will require logic and timing in addition to a heap of
      intuition. Good luck!
    </para>
  </chapter>

  <chapter id="configs">
    <title>Configuration</title>
    <para>
      There are several ways to configure Magicor; edit configuration file,
      add command line options or use the in-game options menu.
    </para>
    <table frame="none" id="options">
      <title>Enemy examples</title>
      <tgroup cols='2' align='left'>
        <colspec colname='type'/>
        <colspec colname='image'/>
        <tbody>
          <row>
            <entry>Fullscreen</entry>
            <entry>True for fullscren, false for windowed.</entry>
          </row>
          <row>
            <entry>Eyecandy</entry>
            <entry>Set to false to disable extra nice graphical effects.</entry>
          </row>
          <row>
            <entry>Sound</entry>
            <entry>
              Set to false to disable sound. (if both sound and
              music are disabled, audio will not be initialized at all)
            </entry>
          </row>
          <row>
            <entry>Music</entry>
            <entry>
              Set to false to disable music. (if both sound and
              music are disabled, audio will not be initialized at all)
            </entry>
          </row>
          <row>
            <entry>Sound vol</entry>
            <entry>
              Set the sound volume from 0 (silent) to 100 (loud).
            </entry>
          </row>
          <row>
            <entry>Music vol</entry>
            <entry>
              Set the music volume from 0 (silent) to 100 (loud).
            </entry>
          </row>
          <row>
            <entry>Joystick</entry>
            <entry>
              Toggle joystick support. If disabled the joystick will not
              be initialized at all.
            </entry>
          </row>
        </tbody>
      </tgroup>
    </table>
    <section id="configs-options">
      <title>In-game options</title>
      <para>
        The in-game options screen will give you the following options:
        <itemizedlist>
          <listitem><para>Fullscreen (toggle using action)</para></listitem>
          <listitem><para>Eyecandy (toggle using action)</para></listitem>
          <listitem><para>Sound (toggle using action)</para></listitem>
          <listitem><para>Music (toggle using action)</para></listitem>
          <listitem><para>Sound vol (change using left/right)</para></listitem>
          <listitem><para>Music vol (change using left/right)</para></listitem>
          <listitem><para>Keyboard controls (enter submenu using action)</para></listitem>
          <listitem><para>Joystick controls (enter submenu using action)</para></listitem>
        </itemizedlist>
      </para>
    </section>
    <section id="configs-controls">
      <title>Controls</title>
      <para>
        <itemizedlist>
          <listitem><para>Up (move up in menus)</para></listitem>
          <listitem><para>Down (move down in menus)</para></listitem>
          <listitem><para>Left (move player left or change menu option)</para></listitem>
          <listitem><para>Right (move player right or change menu option)</para></listitem>
          <listitem><para>Action (create/destroy ice, toggle or select menu option)</para></listitem>
          <listitem><para>Start (obsolete, use Action instead)</para></listitem>
          <listitem><para>Escape (activate/deactivate menu; only customizable for joystick, always ESCAPE-key for keyboard controls)</para></listitem>
        </itemizedlist>
      </para>
    </section>
    <section>
      <title>Configuration files</title>
      <para>
        The global configuration file should be located in
        <emphasis>/etc/magicor.conf</emphasis> or
        <emphasis>/usr/local/etc/magicor.conf</emphasis> on GNU and BSD
        systems.
      </para>
      <para>
        The personal/user-specific configuration file is found in
        <emphasis>~/.magicor/magicor.conf</emphasis> and it will override
        any global settings.
      </para>
      <para>
        Regardless of platform and global/user-specific configuration, the
        contents of it will be the same. Here's a typical example:
      </para>
      <para>
        <screen>
default_tile = tiles/stone
eyecandy = 1
joystick = 1
music = 1
music_vol = 100
sound = 1
sound_vol = 100
        </screen>
      </para>
      <para>
        Quite simple to follow. "default_tile" can be ignored, but note that
        boolean values are either 0 or 1.
      </para>
    </section>
    <section>
      <title>Command line options</title>
      <para>
        This is the output from running the help-option:
        <screen>
usage: Magicor.py [options]

options:
  -h, --help            show this help message and exit
  -c CONFIGPATH, --config=CONFIGPATH
                        use this default config, default ###CONFIG_PATH###
  -j JOYSTICK, --joystick=JOYSTICK
                        enable/disable joystick
  -m MUSIC, --music=MUSIC
                        enable/disable music
  -s SOUND, --sound=SOUND
                        enable/disable sound
  -f FULLSCREEN, --fullscreen=FULLSCREEN
                        enable/disable fullscreen
        </screen>
      </para>
    </section>
  </chapter>

  <appendix id="license">
    <title id="license.title">Appendix - License</title>
    <para>
      Copyright 2006 Peter Gebauer
      (see README for info on contributed work)
    </para>
    <para>
      This project and all of it's content, regardless of copyright holder, is
      released as Public Domain as stated:
    </para>
    <para>
      The person or persons who have associated work with this document (the
      "Dedicator" or "Certifier") hereby either (a) certifies that, to the
      best of his knowledge, the work of authorship identified is in the
      public domain of the country from which the work is published, or (b)
      hereby dedicates whatever copyright the dedicators holds in the work
      of authorship identified below (the "Work") to the public domain. A
      certifier, moreover, dedicates any copyright interest he may have in
      the associated work, and for these purposes, is described as a
      "dedicator" below.
    </para>
    <para>
      A certifier has taken reasonable steps to verify the copyright status
      of this work. Certifier recognizes that his good faith efforts may not
      shield him from liability if in fact the work certified is not in the
      public domain.
    </para>
    <para>
      Dedicator makes this dedication for the benefit of the public at large
      and to the detriment of the Dedicator's heirs and
      successors. Dedicator intends this dedication to be an overt act of
      relinquishment in perpetuity of all present and future rights under
      copyright law, whether vested or contingent, in the Work. Dedicator
      understands that such relinquishment of all rights includes the
      relinquishment of all rights to enforce (by lawsuit or otherwise)
      those copyrights in the Work.
    </para>
    <para>
      Dedicator recognizes that, once placed in the public domain, the Work
      may be freely reproduced, distributed, transmitted, used, modified,
      built upon, or otherwise exploited by anyone for any purpose,
      commercial or non-commercial, and in any way, including by methods
      that have not yet been invented or conceived.
    </para>
  </appendix>
  <index id="reference">
  </index>
</book>