Crates - extensible 3D puzzle game.
Copyright (C) 2008-2010  Octaspire (www.octaspire.com)

This program is free software: you  can  redistribute  it  and/or
modify  it  under  the terms of the GNU General Public License as
published by the Free Software Foundation, either  version  3  of
the License, or (at your option) any later version.

This  program  is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the  implied  warranty  of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.


CONTENTS
---------

1.  INTRODUCTION
2.  SYSTEM REQUIREMENTS
3.  CONTROLS
4.  CONFIGURATION OPTIONS
5.  FURTHER INFORMATION
6.  CREDITS
7.  SOME CRATE SYMBOLS
8.  NOTES
9.  BUGS
10. SOURCE DIRECTORY TREE


1. INTRODUCTION
----------------

Crates  is  a  three dimensional puzzle game. It consists of mis-
sions that consist of levels. To  pass  a level,  you  must  move
player  to  the  exit  by interacting with the different kinds of
crates in the level.  Before that you must also collect  all  the
keys and toggle all the toggles that the level might contain. Ev-
ery level has a password that makes it possible to continue play-
ing  from  that  level  whenever you want, but if you want to get
your name in the hall of fame, you must play the whole mission at
one  go. On that case, the faster you are, the better is your po-
sition in the hall of fame.

Crates is  extensible,  meaning that  it  can  be  extended quite
easily with new missions, levels, game entities (crates) and game
states.  All the missions, levels, game entities, game states and
configuration of the  game engine  are  implemented as plain text
Lua-scripts.  So,  if you know  Lua, you can modify or write  new
missions,  levels,  game entities  and  game states with any text
editor, without any development tools.  Crates is also skinnable,
meaning that you can change the look and feel of the game (or the
theme of the game) easily in the configuration file.   New  skins
(themes), can be created with any image editor and added  to  the
game  just  by   dropping  them   in   new  subdirectory  to  the
resources/textures-directory. Crates is also relocatable, meaning
that it  (the directory containing the game and resources) can be
moved to new location and/or used without installation;  it  will
always know where it is and find the resources it needs.

Crates is controlled with a keyboard or a gamepad. Passwords  can
be written faster with the alphanumeric keys of the keyboard or a
little slower by using the D-pad of gamepad to select the letters
one at a time.  The default buttons of the gamepad and many other
settings of the game can be changed in a configuration file  con-
fig.lua in the resources-directory of the game. Sound effects are
disabled as a default, and if you want to enable them you can  do
it  by changing setting config.sounds from false into true in the
configuration file. See the configuration file for the other con-
figurable settings.

Player is moved around with a keyboard or a gamepad. It continues
movement until something stops it. It can be moved only  when  it
is  not  already moving - you cannot change player's direction if
it is moving. If nothing stops it, it will fly out of  the  level
and the level is restarted.


2. SYSTEM REQUIREMENTS
-----------------------

    - GNU/Linux, Microsoft Windows, Mac OS X or FreeBSD
    - 3  MB free hard disk space
    - 17 MB free RAM available
    - Accelerated graphics hardware
    - Sound card
    - Keyboard or Gamepad

Game is currently tested only in Ubuntu GNU/Linux, Arch GNU/Linux,
Windows XP, Mac OS X and FreeBSD. Other versions might come later.
For Windows there is an installer  available  that  installs  and
uninstalls  a binary version  of  the game  automatically.    For
GNU/Linux,  Mac OS X  and  FreeBSD  there isn’t currently such an
installer (might come later),  so in these systems game needs  to
be compiled  from  the  source  code using CMake (cross-platform,
open-source build system). Install it first, if you don't already
have it. It can probably be installed with your  system's package
manager,  or you can get  a binary version  or  source code  from
http://www.cmake.org/cmake/resources/software.html.  Then install
development versions of the latest  stable versions  of   SDL 1.2,
SDL_mixer 1.2,  libpng,  zlib  and Lua 5.1. Then use CMake and the
provided CMakeListst.txt to build crates.  Note  that   in-source
builds are not allowed.   See  file  INSTALL  for  more  thorough
explanation.


3. CONTROLS
------------

Game is controlled with a keyboard or a gamepad. The default con-
trols are listed below. The default buttons  of  gamepad  can  be
changed in the configuration file.

  Keyboard          Action          Gamepad
  ------------------------------------------
  Esc      Exit to previous state   Button-9
  Return           Accept           Button-1
  R            Restart level        Button-10
  Arrows            Move            D-pad (also sticks)


4. CONFIGURATION OPTIONS
------------------------

Many game options, like toggling between fullscreen and windowed
mode, changing display resolution or window size, turning sound
effects and music on or off, and so so, can be changed by
modifying file 'resources/config.lua'.


5. FURTHER INFORMATION
-----------------------

The man-directory contains one or more manuals that can be useful
for  GNU/Linux, Mac OS X  and FreeBSD users. The crates  homepage
www.octaspire.com/crates/  contains  also more  information.  You
might find there  new missions, extensions and other  new content
for crates also.


6. CREDITS
-----------

Crates is written in the programming languages C and Lua. It uses
SDL,  SDL_mixer,  libpng, zlib and OpenGL. Sound effects are made
using ZynAddSubFX Software Synthesizer and Audacity.  Some of the
graphics are made with GIMP and some with Inkscape.  Textures are
drawn/edited  with  GIMP.   The background image used in menus is
created and rendered with Blender.  Some of the textures  contain
(possibly  modified) parts from the public domain Blender Texture
Disc.  The image for the font texture is generated  automatically
with  a  Java  program.     Textures   for     the   Waymark-skin
(resources/textures/waymark)  are  based  on  free  game graphics
(Sinistar.zip) released under the Creative Commons Attribution 3.0
License at lostgarden.com.   Textures  in  the  Waymark-skin  are
modified versions, not the originals. See lostgarden.com for  the
originals:     "Iron Plague, a Sinistar clone" art by Daniel Cook
(Lostgarden.com).  Music  is  by  Kevin MacLeod (incompetech.com)
Licensed      under      Creative    Commons    "Attribution 3.0"
http://creativecommons.org/licenses/by/3.0/  and  was modified by
downsampling it and converting it to Ogg Vorbis file format using
Audacity.


7. SOME CRATE SYMBOLS
----------------------

The  listing  below contains some symbols for the different kinds
of crates. These are used when building missions and  levels  for
the game.

  activeenemy        AE
  ambushenemy        ME
  automaticsteelbomb AB
  automaton          AU
  block              XX
  bomb               BB
  counter            ##
  exit               @@
  inversecounter     !#
  key                $$
  passiveenemy       PE
  player             &&
  pullere            >>
  pulleren           >^
  pulleres           >.
  pullerew           <>
  pullern            ^^
  pullerns           ^.
  pullernw           <^
  pullers            ..
  pullersw           <.
  pullerw            <<
  pusherensw         P+
  remotecontrol      RC
  slopeen            |_
  slopees            |"
  slopewn            _|
  slopews            "|
  steelbomb          SB
  switch             SW
  teleport           TP
  toggle             []
  trigger            !!
  turnstilee         T>
  turnstilen         T^
  turnstiles         T.
  turnstilew         T<
  turnstilee1        1>
  turnstilen1        1^
  turnstiles1        1.
  turnstilew1        1<


8. NOTES
---------

Crates uses Semantic Versioning 2.0.0 version numbering scheme
starting from version 0.7.2.


9. BUGS
--------

If   you   find  a  bug,   please   see   the   crates   homepage
www.octaspire.com/crates/    for   up-to-date   instructions   on
reporting bugs.

Please note that if  you  enable  sounds  and  your  systems  has
PulseAudio,  the SDL(_mixer) + PulseAudio combination might cause
problems at least on some  GNU/Linux-systems.   See  for  example
"the  pulseaudio  hack".  For  example, at the time of writing in
Ubuntu, if your system has SDL with ALSA option (libsdl1.2debian-
alsa)  installed,  sounds  might  be crackling, channels will ebb
away and game will get jammed when you try to  quit  playing.  In
this  case  removing libsdl1.2debian-alsa and installing SDL with
PulseAudio options (libsdl1.2debian-pulseaudio) instead helped.


10. SOURCE DIRECTORY TREE
-------------------------

.
|-- COPYING                       => License information for crates
|-- HISTORY                       => Listing of changes between versions
|-- INSTALL                       => Installation instructions for all platforms
|-- CMakeLists.txt                => CMake build configuration file for all supported systems
|-- README                        => This file
|-- etc                           => Directory containing misc. more or less useful files
|   `-- crates.nsi                   => NSIS installer script for windows
|-- man                           => Directory containing manual pages for crates
|   |-- man5                         => "File formats and conventions"
|   `-- man6                         => Directory for manuals about "Games"
|       `-- crates.6                    => Manual page for the crates program
|-- resources                     => All the resources of the game
|   |-- config.lua                   => Configuration file for crates
|   |-- entities                     => All the game objects (or crates)
|   |   |-- activeenemy.lua             => Starts hunting the player automatically and actively
|   |   |-- ambushenemy.lua             => Sits and waits for the player to approach within striking distance
|   |   |-- automaticsteelbomb.lua      => Steelbomb that starts countdown automatically
|   |   |-- automaton.lua               => can be programmed to perform multiple different tasks
|   |   |-- block.lua                   => Stops player
|   |   |-- bomb.lua                    => Stops player (max 2 times) and starts countdown
|   |   |-- counter.lua                 => Stops player "count" times
|   |   |-- exit.lua                    => Moves player to the next level or restarts current one
|   |   |-- inversecounter.lua          => Lets player pass "count" times
|   |   |-- key.lua                     => All keys must be picked up
|   |   |-- passiveenemy.lua            => Will only scout some predefined path and won't change this route
|   |   |-- player.lua                  => Player is moved with keyboard or gamepad
|   |   |-- pullere.lua                 => Can be pulled to east            (e)
|   |   |-- pulleren.lua                => Can be pulled to east and north  (en)
|   |   |-- pulleres.lua                => Can be pulled to east and south  (es)
|   |   |-- pullerew.lua                => Can be pulled to east and west   (ew)
|   |   |-- pullern.lua                 => Can be pulled to north           (n)
|   |   |-- pullerns.lua                => Can be pulled to north and south (ns)
|   |   |-- pullernw.lua                => Can be pulled to north and west  (nw)
|   |   |-- pullers.lua                 => Can be pulled to south           (s)
|   |   |-- pullersw.lua                => Can be pulled to south and west  (sw)
|   |   |-- pullerw.lua                 => Can be pulled to west            (w)
|   |   |-- pusherensw.lua              => Can be pushed to all directions  (ensw)
|   |   |-- remotecontrol.lua           => Allows you to move some other crate(s) than player
|   |   |-- slopeen.lua                 => Turns player between east <-> north or stops it
|   |   |-- slopees.lua                 => Turns player between east <-> south or stops it
|   |   |-- slopewn.lua                 => Turns player between west <-> north or stops it
|   |   |-- slopews.lua                 => Turns player between west <-> south or stops it
|   |   |-- steelbomb.lua               => Can withstand unlimited number of collisions and is dangerous
|   |   |-- switch.lua                  => Deactivates its target for some predefined time when depressed
|   |   |-- teleport.lua                => Moves player instantly to some other point in space
|   |   |-- toggle.lua                  => All toggles must be toggled (4 red sides to green)
|   |   |-- trigger.lua                 => Is invisible and will trigger a tracking shot
|   |   |-- turnstilee.lua              => Lets player pass only to east           (e)
|   |   |-- turnstilee1.lua             => Lets player pass only one step to east  (e1)
|   |   |-- turnstilen.lua              => Lets player pass only to north          (n)
|   |   |-- turnstilen1.lua             => Lets player pass only one step to north (n1)
|   |   |-- turnstiles.lua              => Lets player pass only to south          (s)
|   |   |-- turnstiles1.lua             => Lets player pass only one step to south (s1)
|   |   |-- turnstilew.lua              => Lets player pass only to west           (w)
|   |   `-- turnstilew1.lua             => Lets player pass only one step to west  (w1)
|   |-- halloffame                   => Directory containing the Hall of Fame
|   |   |-- default                     => Hall of Fame for the default mission
|   |   `-- tutorial                    => Hall of Fame for the tutorial mission
|   |-- images                       => Directory containing images for icons
|   |   |-- crateslogo16x16x32.ico
|   |   |-- crateslogo16x16x4.ico
|   |   |-- crateslogo16x16x8.ico
|   |   |-- crateslogo24x24x32.ico
|   |   |-- crateslogo24x24x4.ico
|   |   |-- crateslogo24x24x8.ico
|   |   |-- crateslogo48x48x32.ico
|   |   |-- crateslogo48x48x4.ico
|   |   `-- crateslogo48x48x8.ico
|   |-- meshes                       => Directory containing the 3D models
|   |   |-- bottom.lua
|   |   |-- cube.lua
|   |   |-- plate.lua
|   |   `-- player.lua
|   |-- missions                     => New missions can be dropped here
|   |   |-- default.lua                 => The default mission
|   |   `-- tutorial.lua                => The tutorial mission
|   |-- musics                       => Musics for the game, if any
|   |   `-- CambodianOdyssey.ogg        => Song from incompetech.com (downsampled and converted to Ogg)
|   |-- sounds                       => Sound effects for the game
|   |   |-- back.wav
|   |   |-- buzz.wav
|   |   |-- scifi.wav
|   |   |-- select.wav
|   |   |-- thump.wav
|   |   `-- tick.wav
|   |-- states                       => All the game states
|   |   |-- about.lua                   => Displays information about the game
|   |   |-- game.lua                    => In game state where the actual playing happens
|   |   |-- halloffame.lua              => Displays the Hall of Fame
|   |   |-- manual.lua                  => Displays manual (allows x,y scrolling if needed)
|   |   |-- menu.lua                    => Displays the main menu
|   |   |-- mission.lua                 => Displays mission menu
|   |   |-- missionpassed.lua           => After mission is passed
|   |   |-- missionpassedat1go.lua      => After mission is passed in one go
|   |   `-- password.lua                => State where level passwords can be entered
|   `-- textures                     => Textures for the game (subdirectories contain skins)
|       |-- cartoon                     => Textures for the "cartoon"-skin (or theme)
|       |   |-- activeenemy.png            => Texture for activeenemy
|       |   |-- ambushenemy.png            => Texture for ambushenemy
|       |   |-- automaton.png              => Texture for automaton
|       |   |-- bg512x256.png              => Background image for menus
|       |   |-- block.png                  => Texture for block
|       |   |-- bomb.png                   => Texture for bomb
|       |   |-- credits.png                => Contains the credits
|       |   |-- exit.png                   => Texture for exit
|       |   |-- explosion.png              => Texture for explosion
|       |   |-- font.png                   => Texture for the font
|       |   |-- inversecounter.png         => Texture for inversecounter
|       |   |-- key.png                    => Texture for key
|       |   |-- manual1.png                => Contains the manual (in-game) page 1
|       |   |-- manual2.png                => Contains the manual (in-game) page 2
|       |   |-- manual3.png                => Contains the manual (in-game) page 3
|       |   |-- manual4.png                => Contains the manual (in-game) page 4
|       |   |-- passiveenemy.png           => Texture for passiveenemy
|       |   |-- player.png                 => Texture for player
|       |   |-- pullere.png                => Texture for east puller            (e)
|       |   |-- pulleren.png               => Texture for east and north puller  (en)
|       |   |-- pulleres.png               => Texture for east and south puller  (es)
|       |   |-- pullerew.png               => Texture for east and west puller   (ew)
|       |   |-- pullern.png                => Texture for north puller           (n)
|       |   |-- pullerns.png               => Texture for north and south puller (ns)
|       |   |-- pullernw.png               => Texture for north and west puller  (nw)
|       |   |-- pullers.png                => Texture for south puller           (s)
|       |   |-- pullersw.png               => Texture for south and west puller  (sw)
|       |   |-- pullerw.png                => Texture for west puller            (w)
|       |   |-- pusherensw.png             => Texture for all directions pusher  (ensw)
|       |   |-- remotecontrol.png          => Texture for remote control
|       |   |-- slopeen.png                => Texture for east and north slope   (en)
|       |   |-- slopees.png                => Texture for east and south slope   (es)
|       |   |-- slopewn.png                => Texture for west and north slope   (wn)
|       |   |-- slopews.png                => Texture for west and south slope   (ws)
|       |   |-- steelbomb.png              => Texture for steelbomb
|       |   |-- switch.png                 => Texture for switch
|       |   |-- teleport.png               => Texture for teleport
|       |   |-- toggle.png                 => Texture for toggle
|       |   |-- turnstilee.png             => Texture for east turnstile                  (e)
|       |   |-- turnstilee1.png            => Texture for east 1 step turnstile           (e1)
|       |   |-- turnstilen.png             => Texture for east and north turnstile        (en)
|       |   |-- turnstilen1.png            => Texture for east and north 1 step turnstile (en1)
|       |   |-- turnstiles.png             => Texture for east and south turnstile        (es)
|       |   |-- turnstiles1.png            => Texture for east and south 1 step turnstile (es1)
|       |   |-- turnstilew.png             => Texture for east and west turnstile         (ew)
|       |   `-- turnstilew1.png            => Texture for east and west 1 step turnstile  (ew1)
|       `-- waymark                     => Textures for the "Waymark"-skin (or theme)
|           |-- activeenemy.png
|           |-- ambushenemy.png
|           |-- automaton.png
|           |-- bg512x256.png
|           |-- block.png
|           |-- bomb.png
|           |-- credits.png
|           |-- exit.png
|           |-- explosion.png
|           |-- font.png
|           |-- inversecounter.png
|           |-- key.png
|           |-- manual1.png
|           |-- manual2.png
|           |-- manual3.png
|           |-- manual4.png
|           |-- passiveenemy.png
|           |-- player.png
|           |-- pullere.png
|           |-- pulleren.png
|           |-- pulleres.png
|           |-- pullerew.png
|           |-- pullern.png
|           |-- pullerns.png
|           |-- pullernw.png
|           |-- pullers.png
|           |-- pullersw.png
|           |-- pullerw.png
|           |-- pusherensw.png
|           |-- remotecontrol.png
|           |-- slopeen.png
|           |-- slopees.png
|           |-- slopewn.png
|           |-- slopews.png
|           |-- steelbomb.png
|           |-- switch.png
|           |-- teleport.png
|           |-- toggle.png
|           |-- turnstilee.png
|           |-- turnstilee1.png
|           |-- turnstilen.png
|           |-- turnstilen1.png
|           |-- turnstiles.png
|           |-- turnstiles1.png
|           |-- turnstilew.png
|           `-- turnstilew1.png
|-- src                           => C source code for the game (see resources for Lua src)
|   |-- main.c
|   |-- oaudiomanager.c
|   |-- oaudiomanager.h
|   |-- obits.h
|   |-- oconfig.h
|   |-- oconfig.h.in
|   |-- odir.h
|   |-- oentity.c
|   |-- oentity.h
|   |-- oentitymanager.c
|   |-- oentitymanager.h
|   |-- oerror.c
|   |-- oerror.h
|   |-- oevent.c
|   |-- oevent.h
|   |-- ofile.c
|   |-- ofile.h
|   |-- ogame.c
|   |-- ogame.h
|   |-- oglapi.c
|   |-- oglapi.h
|   |-- olevel.c
|   |-- olevel.h
|   |-- oluacapi.c
|   |-- oluacapi.h
|   |-- omap.c
|   |-- omap.h
|   |-- omeshmanager.c
|   |-- omeshmanager.h
|   |-- omessagestack.c
|   |-- omessagestack.h
|   |-- omission.c
|   |-- omission.h
|   |-- omissionmanager.c
|   |-- omissionmanager.h
|   |-- omusicmanager.c
|   |-- omusicmanager.h
|   |-- opngtotexture.c
|   |-- opngtotexture.h
|   |-- optrmap.c
|   |-- optrmap.h
|   |-- optrvector.c
|   |-- optrvector.h
|   |-- oscriptmanager.c
|   |-- oscriptmanager.h
|   |-- osettings.c
|   |-- osettings.h
|   |-- osoundmanager.c
|   |-- osoundmanager.h
|   |-- ostate.c
|   |-- ostate.h
|   |-- ostring.c
|   |-- ostring.h
|   |-- otextmanager.c
|   |-- otextmanager.h
|   |-- otexturemanager.c
|   |-- otexturemanager.h
|   |-- otimer.h
|   |-- otypes.h
|   |-- ovector.c
|   |-- ovector.h
|   |-- ovector3.c
|   |-- ovector3.h
|   |-- oversion.c
|   |-- oversion.h
|   |-- posix                        => Code for POSIX-compliant systems
|   |   |-- freebsd                     => Code for FreeBSD
|   |   |   `-- oexedirname.c
|   |   |-- linux                       => Code for GNU/Linux
|   |   |   `-- oexedirname.c
|   |   |-- macosx                      => Code for Mac OS X
|   |   |   `-- oexedirname.c
|   |   |-- odir.c
|   |   `-- otimer.c
|   |-- utils                        => Directory containing utility programs
|   |   `-- MakeFont.java
|   `-- windows                      => Code for Microsoft Windows
|       |-- odir.c
|       `-- otimer.c
`-- test                          => Directory containing unit tests for crates
    |-- check_omap.c
    |-- check_optrmap.c
    |-- check_optrvector.c
    |-- check_ostring.c
    |-- check_ovector.c
    `-- test.sh                      => Compiles and runs unit tests

24 directories, 253 files