\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename cursgame.info
@settitle Cursgame Manual 0.1.1
@c %**end of header

@copying
This is a manual to the Cursgame library. It should get you an idea
how to start.

Copyright @copyright{} 2013 Sven Bartscher.

@quotation
Licensed under the EUPL, Version 1.1 or - as soon they
will be approved by the European Commission - subsequent
versions of the EUPL (the "Licence");
You may not use this work except in compliance with the
Licence.
You may obtain a copy of the Licence at:
http://ec.europa.eu/idabc/eupl
@end quotation
@end copying

@titlepage
@title Cursgame manual

@c The following two commands start the copyright page.
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@c Output the table of contents at the beginning.
@contents

@ifnottex
@node Top
@top Cursgame

This manual describes how to use cursgame for writing text-base
games.  You don't have to read the whole manual to use cursgame.  Most
of it is reference material.

This manual applies to cursgame 0.2.0@*
Cursgame is versioned following the guidelines of sermantic versioning
as described on http://semver.org.

If you read this i assume you already installed cursgame and you can
import it in python3. Please also note that cursgame is made for
python3 and may not work in python2.
I also assume that you are known to python3.

This manual begins with a tutorial to Cursgame, followed by chapters
describing the details of the modues of Cursgame. A shorter reference
can be obtained with pydoc or with the builtin help() command.
@end ifnottex

@menu
* Getting started::     This chapter introduces Cursgame.
* Module game::         This chapter describes the game module
* Module map::          This chapter describes the map module
* Module inp::          This chapter describes the inp module
* Module character::    This chapter describes the character module
* Module color::        This chapter describes the color module
* Module field::        This chapter describes the field module
@c * Placeholders::        Placeholders for references not written yet.
* Index::               Index.
@end menu

@node Getting started
@chapter Getting started
This chapter will give you a overview over the capabilities of
Cursgame.
@menu
* Starting a game::     This section describes how to start a game.
* Filling the game::    This section describes what to do after creating  the game
* AIs::                 This section describes how to make AIs possible
@end menu

@node Starting a game
@section Starting a game
@cindex Game class introduction
So the first we might want to know is how to start the game at all.
@subsection Importing
To start the game we have to use the game class, and to do that
we (obviously) need to import it.  The game class is located at
cursgame.game.Game which leads to the following import statement:
@example
import cursgame.game
@end example
or we could have done:
@example
from cursgame.game import Game
@end example
To make access to Game shorter.  In this book i will use the upper way
to make clear where classes and functions come from.  You however are
free to use your preferred way to import stuff.
@subsection Preparing
Before we can make an instance of Game we need to get some other stuff
together. What we exactly need is a Map and an InputHandler.
@cindex Map class introduction
@subsubsection Map
So now you might ask: ``What exactly is this Map good for?'' and i will
answer: ``The Map holds all the objects in the game and is responsible
for writing all the objects onto the screen.''. And instanciating a
Map is easy as it sounds.  First we need to import it from cursgame.map
and then make an instance of it:
@example
import cursgame.map
mp = cursgame.mp.Map((100, 100))
@end example
Seems easy, right?  But if you read carefully you will have noticed
that i gave some parameters to your new map. And you will ask me:
``Hey! What did you tell my map what you didn't tell me?!'' But please
bear with me. I just told your map how big it has to be.  This
parameter can be any iterable --- in this case a tuple --- with
exactly two ints in it telling the dimensions of the map.  So in this
case the argument was (100, 100), so we will get a map with 100x100
fields on it.  And that's all about maps you have to know now.
@cindex InputHandler introduction
@subsubsection InputHandlers
Now you might ask me: ``What is an InputHandler?'' And this time i
will answer without quotation marks. An InputHandler catches key
inputs and calls a function you instructed it to call. More on that
later.  But how do you make an instance of an InputHandler? It's
basically the same as making a Map. But instead of the dimensions it
needs a paremeter telling wether the InputHandler should work
turn-based or in real-time. We will choose turn-based because i don't
like real-time very much. For more on real-time or turn-based,
@pxref{time-mode}. So now let's make an InputHandler:
@example
import cursgame.inp  # Note that the module is called inp so it not
                     # collides with the builtin input
inp = cursgame.inp.InputHandler(False) # False: turn-based
                                       # True: real-time
@end example
And that's all about for now.
@subsection Instanciation
Now we're prepared for instanciating the Game.  We already discussed
how to import the Game. So we only need to make an instance:
@example
game = cursgame.game.Game(mp, inp, 20)
@end example
So now let me explain what the parameters mean.  The first is the Map
we created in the preparation.  The second the InputHandler.  You may
wonder a bit more about the third.  See the Game class by default sets
up a log for you.  In this log you can write messages to the end-user
(or to you when debugging).  The third parameter defines how wide the
log should be.  But be carefull!  If you make the log wider the map
get's smaller, so if you make the log wider than 80 on a lot of
terminals you can't see the map at all!  For more on the log,
@pxref{log}.
@subsection Starting the game
So after all you still want to use cursgame and finally get this damn
game started?  if not please leave now.  Anyone left?  good.  So all
left to do is to call the start method on the Game.  Like this:
@example
game.start()  #Note that we use the instance of the game not the class
@end example
Now you should see a bunch of dots and on the left border of the
screen a bit free space.  The free space is the log discussed earlier
and the dots are the fields on the map.  For now there's nothing to do
because we didn't set up any controls, not even for ending the
game. So to end it you need to press ctrl+c, to end it the hard way.
@subsection The whole thing
If you now have seen some pieces of code and don't know how to put
them together.  Here's the whole code needed to start the game.
@example
import cursgame.game
import cursgame.map
import cursgame.inp

mp = cursgame.map.Map((100, 100))
inp = cusgame.inp.InputHandler(False)
game = cursgame.game.Game(mp, inp, 20)

game.start()
@end example
I hope you see, it's not that much.

@node Filling the game
@section Filling the game
Once you started the game you will see that nothing's going on.  In
this section i will describe what to do to make stuff happen. In this
section we will expand the code from the last chapter.  So i assume
that you did read it.  To follow this section to a working program you
need to insert the code, showed in this section, after the
instanciation of the game and before game.start() is called.

@subsection A player
The first thing we might want to have is a player.  A player is a
subclass of an Obj.  Everything that can be placed in the game and can
act in the game is an Obj.  That's all you need to know about Objs for
now. For creating our player we need to import
@code{cursgame.character}.  What we want from there is the class
Human.  Later you can make your own Obj subclasses, for more on that
@pxref{Objs}.  But for now we will only use the Human.  We create and
place the player like this: 
@example
player = cursgame.character.Human()
mp.place(player, 0, 0)
mp.lookon = player
@end example
Let's go through this line by line:@*
The first line creates an instance of the Human class. This object
instance represents our player.@*
The second line places the player on the map, at the position 0, 0.
This is marked with the last two aguments.  @xref{Map.place}, for more
information on the place function.@*
The third line assigns our player to the lookon variable.  This tells
the game that the screen should be centered at our
player. @xref{Map.lookon}, for more information on this variable.

@cindex InputHandler-instructions introduction
@cindex Instructing the InputHandler in brief
@cindex InputHandler callbacks introduction
@cindex Using the InputHandler in brief
@subsection Control
Now we want to be able to control our player.  To do that we need to
give instructions to the InputHandler. @xref{InputHandler}, for more on InputHandlers.  The
InputHandler holds an dictionary called callbacks (so it is accessable
through inp.callbacks).  Every time an input event is encountered the
InputHandler looks in the dictionary for the event and executes the
result.  So the result should be a callable.  Otherwise an error will
occur.  @code{cursgame.inp} holds a bunch of constants related to
keys.  @xref{key-constants}, for the meaning of the constants.  For
letter-keys it's enough to assign the the function to the unicode of
the letter.
So let's set up basic control for our player:
@example
inp.callbacks[ord('q')] = game.set_end
inp.callbacks[cursgame.inp.KEY_DOWN] = lambda _: player.move(0, 1)
inp.callbacks[cursgame.inp.KEY_LEFT] = lambda _: player.move(-1, 0)
inp.callbacks[cursgame.inp.KEY_UP] = lambda _: player.move(0, -1)
inp.callbacks[cursgame.inp.KEY_RIGHT] = lambda _: player.move(1, 0)
@end example
The first line instructs the InputHandler to end the game if Q is
pressed.  @xref{Ending the game}, for more on @code{game.set_end}.
The other lines are a bit more complicated, but they all follow the
same pattern.  Let's first take a look at the part left of the equal
sign.  @code{inp.callbacks[cursgame.inp.KEY_DOWN]} means that we want
to assign a function that is called when the key related to KEY_DOWN
is pressed.  As you might thought, KEY_DOWN refers to the down-key.
The right side of the equal sign is the place where the real work is
done.  The values of the dictionary must be functions taking exactly
one argument.  When we want to move an Obj (remember our player is an
Obj) we call it's move method. But move takes two arguments, telling
where to move.  So we need to make another function that takes exactly
one function.  That's what the lambda is for.  The one argument we get
isn't in our interest since it contains the key event that was caught
by the InputHandler.  Most of the time we don't need this but it
becomes handy of we assign one function to multiple key-events.  So
basically the right part of the equal sign is a function moving the
player by by (0, 1), which is one field down.  The last three lines
follow the same pattern. @xref{Obj.move}, for more information at
moving player.move.

@cindex Obj metaclass introduction
@subsection Objs
@anchor{Objs}
Now we can move our player. But that's a bit stupid and boring if
there's nothing to see when walking.  In fact there's nothing except
our player, the border of the map and empty fields.  So let's place
some walls.  How do we do that?  First we need to subclass the Obj
class, which is located at @code{cursgame.character}.  So we already
imported it along with the Human.  Allow me to first show you how we
subclass it and then describe what we did:
@example
class Wall(cursgame.character.Obj):
    def __str__(self):
        return "#"

    def activate(self, activater, x, y):
        return False
@end example
And that's all you need for a wall.  It inherits from Obj.  It's
__str__ says how it should be presented on the map.  In this case a
Wall has the # sign as a representation.  Just like Humans have
the @@ sign.  The activate function is called when another Objs wants
to enter the field where this Obj is already.  The return value is
used to determine wether the step on this Obj succedes and the moving
Obj should be moved to the new position.  In this case we simply
return False because it's not allowed to step on walls.
@xref{Obj.activate}, for more on this topic.

@subsubsection Placing the wall
Now we have to place the wall so it has an effect in the game.  This
is simply done by first instanciating it and then placing it. Just
like the player. Here's the code:
@example
wall = Wall()
mp.place(wall, 10, 10)
@end example
This places the wall at 10;10.

@cindex Colors introduction
@cindex Painting Objs
@cindex Painting objects on the screen
@subsubsection Color
Now we can paint our wall.  For that take a brush and a little bit
paint of your favorite color.  Then start the game and paint the wall
on the screen using your brush...  Sounds stupid?  It is!  I prefer
the cursgame-way to paint Objs.  Just like __str__ is used to
determine the textual representation of an Obj the color method is
used to determine the color of an Obj.  For that purpose
@code{cursgame.color} holds a set of color-constants you can
return. Let's take a green wall.  So we add this method to our Wall
class:
@example
    def color(self):
        return cursgame.color.GREEN
@end example
Don't forget to add @code{import cursgame.color} to your imports!  Now
your wall should be green, without making you screen permanently
green!  @xref{colors}, for more on colors.

@node AIs
@section AIs
@cindex write AIs
@cindex make AIs
@cindex how to make an AI
This section describes how to use the AI-loop and what it is.  This
section only describes where Cursgame gives you space for AIs. This
chapter does NOT describe how to write good AIs. Cursgame does not
contain an AI.

@cindex action-loop introduction
@subsection The action-loop
Cursgame contains a so called ``action-loop''. The action-loop is a
list of objects that need to do stuff every frame.  At every
frame/round the game calls the loop method on every Obj in the
action-loop.  It's most often used for giving AI-controlled Objs the
possibility to do stuff.

@subsubsection action-loop example
For using the action-loop we first need an Obj that uses the ai-loop.
What's better for that purpose than an enemy?  (Suggestions please to
the maintainer!)  So let's make an enemy:
@example
class Enemy(chatacter.Obj):
    def __str__(self):
        return "e"

    def color(self):
        return cursgame.color.RED

    def aloop(self):
        # The following code references the global variable player.
        # Please note that i don't consider this good style.
        # If you write your own Cursgame-based programs i suggest
        # keeping your variables somewhere else.
        px, py = player.pos
        sx, sy = self.pos
        if px > sx:
            x = 1
        elif px < sx:
            x = -1
        else:
            x = 0
        if py > sy:
            y = 1
        elif py < sy:
            y = -1
        else:
            y = 0
        self.move(x, y)
@end example
So this is our whole AI, for this very simple Enemy.  The important
part of the Enemy class is the aloop method.  It's very simple, so i
don't describe it in detail.  It just makes the enemy move one step
towards the player.  Now we need to place our enemy:
@example
enemy = Enemy()
mp.place(enemy, 20, 20, True)
@end example
So at first this might doesn't look different from placing a wall or
something else, but it is different!  Note the fourth argument to
mp.place!  It says that our enemy should be placed on the
action-loop.  When we used place before we omitted this argument.  It
defaults to False, so if we don't give it Obj.aloop isn't called!
Please note that the player doesn't need to be on the action-loop for
controlling him.  The InputHandler has other ways to do stuff.

@node Module game
@chapter Module game
This chapter describes the contents of the game module in detail.@*
The game module is imported from: @code{cursgame.game}@*
The game module is located at: @code{cursgame/game.py}

@section The Game class
@cindex Game in detail
@tindex Game
The Game class is at the top of the structures holding the data for
the game.  It holds the Map and the InputHandler.  It also provides
access to the log.

@subsection methods
Here are all methods of the Game class.

@findex Game.__init__
@subsubsection __init__/constructor
The game class takes at instanciation three arguments. The first is
the map. (@xref{Map}.)  The second is the InputHandler
(@xref{InputHandler}.) Since they are both needed for
creating the Game they need to be instanciated before the Game.  The
third argument is the size the log (@pxref{log}) should have.  You can
subclass Game and overwrite methods like described below.

@findex Game.logwrite
@cindex log
@anchor{log}
@subsubsection logwrite
This method takes one string and writes it in the log.  You don't need
to worry about scrolling the log manually.  logwrite does everything
that is needed to print the text you gave on the log on the left side
of the screen.  The log has has a size defined by the logsize
argument.  Note that the logsize is substracted from the size of the
screen used for printing the map. If the text is too long to fit in the
log it is splitted in multiple lines.

@findex Game.refresh
@anchor{Game.refresh}
@subsubsection refresh
This function is called once per frame.  It refreshes the physical
screen.  You shouldn't call it yourself except you're overwriting the
main loop of the game.  It takes two arguments.  The screen where the
map is printed on and the full screen.

@findex Game.loop
@cindex The main loop
@cindex Main loop
@cindex gameflow
@anchor{Game.loop}
@subsubsection loop
This function is called once per frame and does everything that has to
happen in this frame.  You shouldn't call it directly.  You can
override it in a subclass, but you should be carefull!  Your new loop
should at least do everything in this list:
@itemize
@item Call the print method on the Map. @xref{Map}.
@item Refresh the screen. @xref{Game.refresh}.
@item Call get_input. @xref{InputHandler}.
@item Call the action-loop. @xref{Map}.
@item Return wether the game should continue.  True: continue False: end
@end itemize
Please note that it may not be necessary to override the loop
method. By default loop calls the method subloop
(@pxref{Game.subloop}).  It gets two arguments, the screen wehere the
map is printed on and the full screen.

@cindex subloop
@findex Game.subloop
@anchor{Game.subloop}
@subsubsection subloop
This method is called once per frame.  You can override it in a
subclass and do anything you want.  The return value is (by
default, (@pxref{Game.loop}). used to determine wether the game should
continue.  If True is returned the game continues.  If False is
returned the game ends immediately.  This method takes no arguments

@cindex Game class setup
@cindex setup the Game class
@findex Game.user_setup
@subsubsection user_setup
This method is called at the end of the __init__ function.  You can
use it to initialize the game further, without overriding __init__.

@findex Game.run
@subsubsection run
This method is (indirectly) called by the start method
(@pxref{Game.start}).  It initializes the the game to an running
state.  You shouldn't call or override it.  It takes three arguments.
These are automatically created by padwrap (@pxref{padwrap}).  The arguments are in this order: The screen for the map,
the full screen, the screen for the log.

@findex Game.start
@cindex Starting the game
@anchor{Game.start}
@subsubsection start
This method starts the game.  It takes no arguments and starts the
main loop. It runs until the game ends. You shouldn't override, unless
you know what you're doing.

@findex Game.set_end
@cindex Ending the game
@cindex Set end of game
@anchor{Ending the game}
@subsubsection set_end/ending the game
If you call this method the attribute Game.end is set to True. This
means that at the end of the running frame the game ends.  This method
takes on optional argument, which is ignored.  This is handy for use
with InputHandler (since the InputHandler gives one argument to the
callbacks).  Note that you can instead of calling this method you can
just set the variable Game.end to True yourself.  Also note that you
can end the game in the subloop, @pxref{Game.subloop}.

@subsection attributes
Here are all the important attributes of the Game class.

@vindex Game.map
@subsubsection map
This is the Map associated to the game.

@vindex Game.inp
@subsubsection inp
This is the InputHandler associated with the game.

@vindex Game.end
@subsubsection end
This variable marks wether the game should end at the end of the
running frame.  @xref{Ending the game}, for more on ending the game.

@findex padwrap
@anchor{padwrap}
@section padwrap

This function is used by the start method of the game.  It's like
curses.wrapper but it is customized for the use with Cursgame.
Normally you don't want to use this function, since the Game class
handles this itself.

@node Module map
@chapter Module map
This chapter describes the contents of the map module in detail.@*
The map module is imported from @code{cursgame.map}.@*
The map module is located at @code{cursgame/map.py}.

@anchor{Map}
@cindex Map in detail
@tindex Map
@section The Map class
The Map class holds the fields of the game and is responsible for
printing the map on the screen.  Also it carries out the action-loop.
It inherits from dict, since it holds the map-data as a
dictionary. You should rarely subclass it.

@subsection methods
Here are all methods of the Map class.

@findex Map.__init__
@subsubsection __init__/constructor
The Map takes at initialization on argument.  This argument must be an
iterable (usually an tuple) with exactly two arguments.  These two
items define the size of the Map, they must be of type int.

@findex Map.print
@cindex printing the map
@cindex drawing the screen 
@subsubsection print
This method prints the map-data on the screen.  This method can't be
called until the game is created and the map is registered on the
game.  The data is printed at Map.screen.  @xref{Map.screen}.  This
method takes no arguments.

@findex Map.place
@cindex Placing Objs on the map
@anchor{Map.place}
@subsubsection place
This function places an Obj on the Map.  After that the Obj is
displayed on the screen (if in sight) and can act in the game.  This
method takes from three to four arguments.  The first is the Obj to
place on the Map.  The second and third are the x and y coordinates
for the Obj (x first, even if curses has y first!).  The optional
fourth should be a bool, defaults to False and if it's True the Obj is
placed on the action-loop. For more on Objs, @pxref{Obj}
and @ref{Obj}.  For more on the action-loop, @pxref{Map.aloop}.

@findex Map.distance
@cindex Distance between Objs
@subsubsection distance
This method takes two arguments.  Both are Objs. The method then
returns the distance between the Objs.

@findex Map.remove
@cindex Removing objects from the map
@cindex Map --- remove object
@subsubsection remove
This method removes an object from a given position.  It takes three
aguments.  The first is the Obj to remove.  The second and third are
the X and Y coordinates to remove from.

@findex Map.do_aloop
@anchor{Map.aloop}
@subsubsection do_aloop
This method carries out the action-loop.  You shouldn't call it unless
you're overriding the main-loop (@pxref{Game.loop}).

@subsection attributes
Here are the important attributes of the main class.

@vindex Map.x
@vindex Map.y
@subsubsection x/y
These two attributes represent the x and y size of the map.

@vindex Map.screen
@anchor{Map.screen}
@subsubsection screen
This attribute holds the screen the map should print on.  It is None
until the Map is registered on a Game.

@vindex Map.lookon
@cindex Centering the view
@cindex Focus the screen on the player
@anchor{Map.lookon}
@subsubsection lookon
This attribute holds the Obj the screen should be centered on.  You
can change it just by setting this variable to another value.  Changes
to this variable will take effect in the next frame.

@vindex Map.aloop
@subsubsection aloop
This is a list holding all objects on the action-loop.

@vindex Map.game
@subsubsection game
This holds a reference to the game this map is registered on.

@node Module inp
@chapter Module inp
This chapter describes the contents of the inp module in detail.

@findex nothing
@section nothing
This function does --- just like the name says --- nothing.  It takes
a arbitrary count of positional and keyword arguments and returns
None.

@tindex InputHandler
@cindex Getting input
@cindex Input
@cindex Control
@cindex Keyboard
@anchor{InputHandler}
@section InputHandler
The InputHandler waits for input and handles it as it arrives.  It
also controls wether the game runs in real-time or in turn-based
mode.  This might seem a little bit messed up at first.  But it makes
(a little bit) sense if you see that the difference between turn-based
and real-time games only is wether you take input in blocking mode or
not.

@subsection methods
Here are all methods of the InputHandler

@findex InputHandler.__init__
@anchor{time-mode}
@subsubsection __init__/constructor
The InputHandler takes at instanciation one argument.  A float, int or
bool that indicates wether the game should run in real-time or in
turn-based mode.  If it's evaluates to False (e.g. it's 0 or
False), otherwise the given number is waited between the frames (in
seconds).  This means that you can't pass True!

@findex InputHandler.get_input
@subsubsection get_input
This method waits for input and processes it.  Processing means that
the input-event that was catched is lokked up in
InputHandler.callbacks and calls the function returned by the lookup,
with the input-event as first and only argument.

@subsection attributes
Here are all important attributes of the InputHandler listed.

@vindex InputHandler.screen
@subsubsection screen
This variable holds the screen to get input from.  It is None until
the InputHandler is registered on a game.

@vindex InputHandler.blocking
@subsubsection blocking
This variable says wether input should be get in blocking or non
blocking mode.  @xref{time-mode}, for more on that. You can change
this at runtime. This will take effect on the opened window imediately.

@tindex PassiveInput
@cindex lowlevel input
@section PassiveInput
The @code{PassiveInput} class is a alternative @code{InputHandler}.
Instead of catching the input every frame, the @code{PassiveInput}
provides the method @code{get_key} which returns the last pressed key.
PassiveInput inherits from InputHandler.

@subsection methods
Here are all the methods of @code{PassiveInput}

@vindex PassiveInput.get_input
@subsubsection get_input
This method is called in the same situations as the
InputHandler.get_input. But this version doesn't do or return anything
because the input is requested manually by the programmer.

@vindex PassiveInput.get_key
@subsubsection get_key
This method is just some kind of link to curses.screen.getch(). It
returns the last pressed key and returns -1 if no key was pressed and
blocking is True.

@anchor{key-constants}
@section key-constants
This module imports all the key-constants from curses.  Please look at
the python-curses documentation for their meaning.

@node Module character
@chapter Module character
This chapter describes the contents of the character module in
detail.

@tindex Obj
@cindex Objs in detail
@anchor{Obj}
@section Obj
This class is a metaclass for all stuff that can be placed on in the
game.  See the documentation for the abc module for more on
metaclasses.

@subsection methods
Here are all methods of the Obj class.

@findex Obj.__init__
@subsubsection __init__/constructor
Does nothing in your interest. Takes no arguments.

@findex Obj.move
@cindex moving
@cindex change position of Objs
@anchor{Obj.move}
@subsubsection move
Changes the position of the Obj by the two given arguments, relative
to the current position.

@findex Obj.__str__
@cindex Textual representation of Objs
@cindex Symbols
@cindex representations in the game
@anchor{Obj.__str__}
@subsubsection __str__
The return value is used for representing the Obj in the game.  This
is an abstract method, so you need to override it in a subclass.

@findex Obj.color
@cindex Color of an object
@cindex Painting Objs
@anchor{Obj.color}
@subsubsection color
This function should return a valid curses color-code.  These color
codes are defined in the @code{cursgame.color} module.  @xref{colors}.

@findex Obj.activate
@cindex Killing Objs
@cindex Fights
@cindex Pushing Objs
@cindex Colliding Objs
@cindex Obj collision
@anchor{Obj.activate}
@subsubsection activate
This method is called if some other Obj wants to step on the field
this Obj is on.  You can use it to whatever.  It defaults to killing
the object and removing it from the game (including the action-loop if
it's on it).  The return value is used to determine wether the mofing
Obj should be moved or not.  If you return True, the moving Obj is
moved.  If you return False the moving Obj stays where it was.  By
default True is returned, so if you step on an Obj not overriding
activate you step on it and killing it.  You can override it and do
anything you want.  You can even do nothing (for example walls do
nothing except returning False).  If on a Field is more than one Obj
the activate method is only called on the Obj on the top.

@findex Obj.aloop
@cindex What does the action-loop
@subsubsection aloop
This method is called once per frame, if the Obj is placed on the
action-loop.  This is usually the case if you placed it with the last
argument to Map.place as True.

@subsection attributes
Here are all important attributes of the Obj.

@vindex Obj.pos
@cindex Position of Obj
@subsubsection pos
This attribute contains an tuple with the coordinates of the Obj (x
first item).

@vindex Obj.map
@subsubsection map
This variable contains the map this Obj is on.

@vindex Obj.dead
@subsubsection dead
This variable is True when the Obj is dead.  Note that this attribute
doesn't have any effect on Cursgame.  It is only for the user.

@tindex Human
@section Human
This class is a default human.  You obviously don't have to use this
Human and can make you own that fits your needs better. It inherits
from Obj. @xref{Obj}.

@subsection methods
Here are the methods of Human

@findex Human.__str__
@subsubsection __str__
returns @code{"@@"}. @xref{Obj.__str__}.

@findex Human.color
@subsubsection color
returns @code{cursgame.color.BLUE}, which means the Human is displayed
blue.  @xref{Obj.color}.

@node Module color
@chapter Module color
@cindex colors
@anchor{colors}
In this module are constants and a few functions about colors.  To give
an Obj color override it's color method and return the color-code of
the color you want.  @xref{color-codes}.  You can also define you own
colors.  This is documented below.

@anchor{color-codes}
@cindex color codes
@section color-codes
An colorcode in Cursgame is a function returning an int that curses
can interprete as a color.  That they're a function is due to internal
problems of Cursgame.  In the color method you anyway just need to
return the colorcode as they are defined here, without calling them.
The color-codes defined here are:
@itemize
@item WHITE
@item RED
@item GREEN
@item YELLOW
@item BLUE
@item MAGENTA
@item CYAN
@item BLACK
@end itemize

@cindex Defining own colors
@cindex Color defining
@section Defining own colorcons
If you want to define own colorcodes you do it almost the wayy you
would do it in curses.  First you need to register a color-pair with
@code{cursgame.color.init_pair} (Documented in the python-curses
documentation).  Once you registered the pair to curses you can get
the value associated with it with @code{cursgame.color.color_pair}
(Again see curses documentation).  Once you defined a color_pair you
need to make it a valid Cursgame-color-code.  You can do this by
passing the return value of @code{color_pair} to
@code{cursgame.color.make_colorcons}, this function will return the
cursame-color code.

@section Raw-colors
For defining new color pairs you need the raw colors provided by
curses.  The color module imports them under other names than they are
defined in curses.  In Cursgame they are called @code{X_RAW} where
thy are called @code{COLOR_X} in curses.  So for example
@code{cursgame.color.BLACK_RAW} links to @code{curses.COLOR_BLACK}.

@node Module field
@chapter Module field
This chapter describes the field module in detail, but most of the
time you don't have to know much more than that you can access theyr
contents like lists.

@tindex Field
@cindex Fields
@section Field class
The Field class is one field at the Map.  It holds all objects that
are on one position on a Map.  It inherits from @code{list} and you
can access t just like a list.  A field has a __str__ and a color
method that returns the values of the Obj on top of the Field.

@subsection methods
Here are all methods defined in Field.  Note that Field inherits from
@code{list} and has alle the methods from @code{list}.

@findex Field.__init__
@subsubsection __init__/constructor
This method takes two needed and one optional argument.  The two
needed are the coordinates this Field represents.  The optional is a
str that is returned by __str__ if there is no Obj on the Field.

@findex Field.uppest
@subsubsection uppest
This method returns the Obj on top of the Field or None, if the Field
is empty.

@findex Field.__str__
@subsubsection __str__
This returns the str of the Obj on top of the Field.  So the field
looks like the Obj on top of it.  If there is no Obj on the Field it
returns self.defstr.  @xref{Field.defstr}.

@findex Field.color
@subsubsection color
THis method returns the color of the Obj on top of the Field.  So the
field looks like the Obj on top of it.  If there is no Obj on the
Field it returns @code{cursgame.color.WHITE}.  @xref{colors}.

@findex Field.__repr__
@subsubsection __repr__
This returns the representation in the form @code{Field([contents of
field...])}.

@subsection attributes
Here are all the important attributes of Field

@vindex Field.x
@vindex Field.y
@subsubsection x/y
These are the coordinates where the Field is.

@vindex Field.defstr
@anchor{Field.defstr}
@subsubsection defstr
This is the string that is used for the Field if it's empty.  You can
change it at runtime.

@ignore
@node Placeholders
@chapter Placeholders
This chapter is for all references which need to be done.
@anchor{Obj}
@anchor{InputHandler}
@anchor{Map}
@end ignore

@node Index
@unnumbered Indices
Here are the four indices.  The feature Index leads you to
descriptions of concepts ad features.  The Function Index lists
top-level functions and methods.  The variable index lists important
attributes of classes.  The class index lists all classes that are
part of cursgame.

@unnumberedsec Feature Index
@printindex cp

@unnumberedsec Function Index
@printindex fn

@unnumberedsec Variable Index
@printindex vr

@unnumberedsec Class Index
@printindex tp

@bye
