%% LyX 1.5.1 created this file.  For more info, see http://www.lyx.org/.
%% Do not edit unless you really know what you are doing.
\documentclass[english]{article}
\usepackage[T1]{fontenc}
\usepackage[latin1]{inputenc}
\IfFileExists{url.sty}{\usepackage{url}}
                      {\newcommand{\url}{\texttt}}

\makeatletter
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Textclass specific LaTeX commands.
\newenvironment{lyxlist}[1]
{\begin{list}{}
{\settowidth{\labelwidth}{#1}
 \setlength{\leftmargin}{\labelwidth}
 \addtolength{\leftmargin}{\labelsep}
 \renewcommand{\makelabel}[1]{##1\hfil}}}
{\end{list}}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% User specified LaTeX commands.

%   Copyright (c) 2007,2008 Gustavo Henrique Milaré
%
%   This file is part of The Feebs War.
%
%   The Feebs War 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.
%
%   The Feebs War 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 The Feebs War.  If not, see <http://www.gnu.org/licenses/>.




\IfFileExists{url.sty}{\usepackage{url}
}
                      {\newcommand{\url}{\texttt}}

\makeatletter
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Textclass specific LaTeX commands.



\IfFileExists{url.sty}{\usepackage{url}

}
                      {\newcommand{\url}{\texttt}}

\makeatletter




\makeatother


\makeatother

\usepackage{babel}
\makeatother

\begin{document}

\title{\textbf{\huge The Feebs War}}


\author{Gustavo Henrique Milaré}

\maketitle
\begin{abstract}
\textit{The Feebs War} is a modified version of Planet of The Feebs \url{http://www.cliki.net/Planet\%20of\%20the\%20Feebs},
a game made for people learn and improve their lisp and code manipulation
techniques. The graphics are now displayed using Lispbuilder \url{http://lispbuilder.sourceforge.net}'s
libraries, so the problems with portability from CMUCL and X Window
System do not exist anymore. Also the code is cleaner and more extensible. 
\end{abstract}
\tableofcontents{}


\section{Introduction}

The Feebs are intelligent and hostile creatures that live inside maze
tunnels. They also have no mercy with each other, so they frequently
throw a lethal flame from through their mouth, getting rid of their
opponent and eating the carcass left. But throwing flames have an
energy cost, so they must keep tracking for food.

This game is intended to help lisp newbies (or maybe a little more
advanced lispers) to learn lisp. A player must create a function that
receives what his/her feeb is seeing and feeling, and returns what
it will do next. To create the better feeb, one can create variables
to store data from previous moves (or not), and can also use all the
power of lisp to improve his/her creature. But the most important
is to make good choices and be aware of danger!


\subsection{Changes from \emph{Planet of the Feebs}}

Many changes were made from the original game, but, if you have any
feeb definition and you want to use it, it should be easy to adapt
the brain function to the new rules.

The main reason of this project is that \textit{Planet of the Feebs}
is really interesting for (not just) newbies to learn lisp, but the
difficulties to install, unportability and the absence of competitors
make it difficult to someone to be interested in making a feeb. So,
I hope that making these adjustments and maybe creating some contests
over the web make people be more interested in learning lisp.

So, these are (some of) the changes:

\begin{itemize}
\item The graphics are not based on X Window System anymore, but on \textit{Lispbuilder},
and there are no CMUCL's event handler. This way, the code is more
portable and graphics can be improved. Just creating some image files
of a feeb and your feeb is much more personalized! 
\item Every element of the map (including walls) is a list, so the brain
of a feeb doesn't need to test all the time if the element is an atom
or a list (which, in my opinion, is really boring, unlispy and unnecessary
in this case). That was only a reason to duplicate code and work,
adding no results at all... 
\item Many functions and variables are changed and others were added 
\item Documentation is more objective than the one provided with \textit{Planet
of the Feebs}, and is fully compatible with the code. This way it
is easier to understand the game. 
\item Security is improved. Now it the behavior functions are allowed to
store and change structures and vectors passed to it. The parameters
can't be change by those functions while inside the game. 
\item It is possible now to extend the rules: the code is object oriented
and new rules, special moves, change the behavior of flames, etc,
can be done by adding new classes and/or methods. This manual is just
the beginning! end{itemize}


\section{The Game}


\subsection{Overview}

Your feeb's objective is to survive and kill other feebs. It is inside
a maze of tunnels. Every turn, all feebs lose one unit of energy,
and maybe starves. Your feeb is able to move forward, turn left, right
or around, flame, peek around a corner, eat something or just wait.
After all feebs move, the flames thrown before also move (or dissipate),
carcasses may rot and mushrooms may grow, accordingly to some rules.

The game rules are defined by parameters. These parameters can be
read by the command \textsf{\textbf{(get-feeb-parm~}}\textsf{'parameter}\textsf{\textbf{)}}
To see all parameters, values and also all the documentation, one
can use \textsf{\textbf{(list-parameter-settings)}}. Using \textsf{\textbf{(change-feeb-parm}}\textsf{'parameter~value}\textsf{\textbf{)}}
gives the possibility to change them (but not during the game) and
\textsf{\textbf{(documentation~}}\textsf{'parameter~'feeb-parm}\textsf{\textbf{)}}
can be used to know them. Just remember that every probability must
be a rational number (like 1/2).

But don't panic! These parameters are just for one to know how the
game is going to be, but in the beginning there is no need to explicitly
use them when creating the brain of a feeb. The best way to create
a feeb is watching a game (among system feebs), improving it (it is
defined in file brains.lisp) a little more, testing the changes...

These are some global parameters:

\begin{lyxlist}{00.00.0000}
\item [{{\textsf{\textbf{'game-length}}}}] Number of turns the game will
last. 
\item [{{\textsf{\textbf{'points-for-killing}}}}] How many points some
feeb earn for killing someone. 
\item [{{\textsf{\textbf{'points-for-dying}}}}] How many points some
feeb earn for dying (usually negative). 
\item [{{\textsf{\textbf{'maze-x-size}}}}] Horizontal size of the maze. 
\item [{{\textsf{\textbf{'maze-y-size}}}}] Vertical size of the maze. 
\end{lyxlist}

\subsection{Throwing flame}

If a feeb decides to throw a flame, if it is prepared to and has enough
energy, the next turn there will be a flame in the square in front
of the feeb, and it will see it, so the feeb shouldn't move forward.
For a few turns, the feeb will not be able to throw flames. Each turn,
the flame moves forward destroing mushrooms and killing feebs it encounters,
transforming them into carcasses. If there is a wall, the flame can
reflect, and, if so, it will turn 180 degrees.

Once a feeb is killed (or starves), in it's place in the maze there
will appear a carcass. The feeb goes to the end of the dead feebs
line. When the carcass rots, the first feeb in line reincarnates.
So, dying is not so terrible.

These are the parameters related to flames:

\begin{lyxlist}{00.00.0000}
\item [{{\textsf{\textbf{'flame-energy}}}}] Amount of energy lost after
throwing a flame. 
\item [{{\textsf{\textbf{'fireball-guaranteed-lifetime}}}}] Number of
turns that a fireball is guaranteed not to dissipate, unless it encounters
a wall. 
\item [{{\textsf{\textbf{'fireball-dissipation-probability}}}}] Probability
of the flame to dissipate each turn after the appropriate time. 
\item [{{\textsf{\textbf{'fireball-reflection-probability}}}}] Probability
of the flame to reflect when encountering a wall. 
\item [{{\textsf{\textbf{'flame-no-recovery-time}}}}] Number of turns
that a feeb cannot fire. 
\item [{{\textsf{\textbf{'flame-recovery-probability}}}}] Probability
of the feeb to recover the ability to throw a flame, after the appropriate
time. 
\end{lyxlist}

\subsection{Eating food}

There are two kinds of food, carcasses and mushrooms. Carcasses usually
give less energy than mushrooms, and may rot, but, while it does not
rot, a feeb can feed as long as it wishes. Mushrooms disappear after
being eaten. By eating food, the feeb will be able to recover energy,
which is important because, if a feeb stays with 0 or less units of
energy, it starves.

These are the quantities:

\begin{lyxlist}{00.00.0000}
\item [{{\textsf{\textbf{'mushroom-energy}}}}] Amount of energy recovered
when the feeb eats a mushroom. 
\item [{{\textsf{\textbf{'carcass-energy}}}}] Amount of energy recovered
each turn that the feeb eats a carcass. 
\item [{{\textsf{\textbf{'carcass-guaranteed-lifetime}}}}] Number of
turns that a carcass will surely not rot. After these turns, it can
rot, depending on probabilities. 
\item [{{\textsf{\textbf{'carcass-rot-probability}}}}] Probability of
the carcass to rot, after the appropriate time. 
\item [{{\textsf{\textbf{'maximum-energy}}}}] Maximum amount of energy
that a feeb can have eating. 
\item [{{\textsf{\textbf{'starting-energy}}}}] Amount of energy a feeb
has when it reincarnates. 
\item [{{\textsf{\textbf{'number-of-mushrooms}}}}] Quantity of mushrooms
that exist in the maze. 
\end{lyxlist}

\section{The Feeb}

A feeb needs four things: a name, a brain and a set of graphics (optional).

\begin{itemize}
\item The name, a string. 
\item The brain is a function that decides what the feeb will do next, based
on what it is seeing and feeling. 
\item The set of graphics is an image file (of format BMP, JPEG, PNG, and
any others that supported by SDL\_image). 
\end{itemize}
One can create a feeb calling \textsf{\textbf{(define-feeb}}\textsf{~name~brain~}\textsf{\textbf{:graphics}}\textsf{~graphics}\textsf{\textbf{)}}.
If name is already used, a warning will be signaled, and the old feeb
will be substituted. Calling \textsf{\textbf{(list-of-feebs)}} will
return the list of the feebs (names only) that will be defined when
the game begins. \textsf{\textbf{(delete-feeb}}\textsf{~name}\textsf{\textbf{)}}
will delete the feeb with this name from this list, and \textsf{\textbf{(delete-all-feebs)}}
will clear it.


\subsection{Possible decisions}

After processing the information available, the brain will take a
decision. If this decision is not one of the decisions listed down,
a warning will be signaled, and the result will be like \textsf{\textbf{:wait}}.
Then, if someone is testing a brain function, he or she will be able
to know if something goes wrong.

The possible values that the brain function can return are these:

\begin{lyxlist}{00.00.0000}
\item [{{\textsf{\textbf{:move-forward}}}}] Move one square forward,
unless there is a wall in front of the feeb. 
\item [{{\textsf{\textbf{:turn-left}}}}] Turn 90 degrees to the left. 
\item [{{\textsf{\textbf{:turn-right}}}}] Turn 90 degrees to the right. 
\item [{{\textsf{\textbf{:turn-around}}}}] Turn 180 degrees. 
\item [{{\textsf{\textbf{:flame}}}}] Throw a flame. The flame will be
created next turn in the front square of the feeb. 
\item [{{\textsf{\textbf{:wait}}}}] Do nothing in this turn. 
\item [{{\textsf{\textbf{:peek-left}}}}] Peek to the left around a corner.
The creature does note actually move, but, in the next turn, the creature
will have the same vision that it would have if he had moved one step
forward and turned left (and one step back because the feeb needs to
see what is actually in front of it). Peeking used so a feeb can analyze
a corridor before trespassing it. 
\item [{{\textsf{\textbf{:peek-right}}}}] Peek to the right around a
corner, analogous to \textsf{\textbf{:peek-left}}. 
\item [{{\textsf{\textbf{:eat-carcass}}}}] Eat a carcass if there is
any available in the feeb's square. The amount of the parameter \textsf{\textbf{'carcass-energy}}
is restored to the feeb's energy. 
\item [{{\textsf{\textbf{:eat-mushroom}}}}] Eat a mushroom if there is
any available in the feeb's square. The amount of the parameter \textsf{\textbf{'mushroom-energy}}
is restored to the feeb's energy. 
\end{lyxlist}

\subsection{Information available}

The brain of a feeb must take five arguments; I'll call them \textsf{\emph{status}},
\textsf{\emph{proximity}}, \textsf{\emph{vision}}, \textsf{\emph{vision-left}}
and \textsf{\emph{vision-right}}.


\subsubsection{Status}

Every time the brain is called, it receives some useful information
through \textsf{\textbf{status}}.

The structure \textsf{\textbf{status}} keeps information about the
feeb itself. Also it has information of the previous movement of the
feeb. To access them, one must call:

\begin{lyxlist}{00.00.0000}
\item [{{\textsf{\textbf{(name}}\textsf{\emph{~status}}\textsf{\textbf{)}}}}]~


\begin{flushleft}
The name of the feeb. 
\par\end{flushleft}

\item [{{\textsf{\textbf{(facing}}\textsf{\emph{~status}}\textsf{\textbf{)}}}}]~


\begin{flushleft}
Where the feeb is facing to, one of the constants provided: \textsf{\textbf{north}},
\textsf{\textbf{east}}, \textsf{\textbf{south}} or \textsf{\textbf{west}},
which are 0, 1, 2 and 3 respectively. 
\par\end{flushleft}

\item [{{\textsf{\textbf{(x-position}}\textsf{\emph{~status}}\textsf{\textbf{)}}}}]~


\begin{flushleft}
The horizontal position of the feeb, starting with 0 and increasing
to east. If \textsf{\textbf{'sense-location-p}} is nil, it returns
nil instead. 
\par\end{flushleft}

\item [{{\textsf{\textbf{(y-position}}\textsf{\emph{~status}}\textsf{\textbf{)}}}}]~


\begin{flushleft}
The vertical position of the feeb, starting with 0 and increasing
to south. If \textsf{\textbf{'sense-location-p}} is nil, it returns
nil instead. 
\par\end{flushleft}

\item [{{\textsf{\textbf{(peeking}}\textsf{\emph{~status}}\textsf{\textbf{)}}}}]~


\begin{flushleft}
If it is \textsf{\textbf{:peek-left}} or \textsf{\textbf{:peek-right}},
it means that the current \textsf{\emph{vision}} provided is result
of a previous \textsf{\textbf{:peek-left}} or \textsf{\textbf{:peek-right}}
command of the same feeb. Otherwise, it is \textsf{\textbf{nil}}.
Note that \textsf{\emph{proximity}} is \emph{not} affected. 
\par\end{flushleft}

\item [{{\textsf{\textbf{(line-of-sight}}\textsf{\emph{~status}}\textsf{\textbf{)}}}}]~


\begin{flushleft}
Indicates the amount of valid entries in \textsf{\emph{vision}}. It
actually means that \textsf{\textbf{(aref}}\textsf{\emph{~vision~}}\textsf{\textbf{(line-of-sight}}\textsf{\emph{~status}}\textsf{\textbf{))}}
will return \textsf{\textbf{'(:rock)}}. 
\par\end{flushleft}

\item [{{\textsf{\textbf{(ready-to-fire}}\textsf{\emph{~status}}\textsf{\textbf{)}}}}]~


\begin{flushleft}
If \textsf{\textbf{T}} indicates that the feeb is ready to fire. If
\textsf{\textbf{Nil}} indicates it is not. 
\par\end{flushleft}

\item [{{\textsf{\textbf{(aborted}}\textsf{\emph{~status}}\textsf{\textbf{)}}}}]~


\begin{flushleft}
Related to timing. Returns \textsf{\textbf{T}} if the last move
of feeb was aborted because of timing issues. 
\par\end{flushleft}

\item [{{\textsf{\textbf{(last-move}}\textsf{\emph{~status}}\textsf{\textbf{)}}}}]~


\begin{flushleft}
The feeb's previous move, or \textsf{\textbf{:dead}} if it has just
reincarnated. 
\par\end{flushleft}

\end{lyxlist}

\subsubsection{Proximity and vision}

The brain receives also information about what is near the feeb and
what the feeb sees. We note that, contrary to \emph{Planet of the
Feebs}, it is safe to change anything inside these structures, so
you are allowed to keep them stored and to modify them as you wish.

The structure \textsf{\emph{proximity}} has the contents of the squares
near the feeb (not affected by peeking) with these fields:

\begin{lyxlist}{00.00.0000}
\item [{{\textsf{\textbf{(my-square}}\textsf{\emph{~proximity}}\textsf{\textbf{)}}}}]~


\begin{flushleft}
Contents of the feeb's current square. 
\par\end{flushleft}

\item [{{\textsf{\textbf{(left-square}}\textsf{\emph{~proximity}}\textsf{\textbf{)}}}}]~


\begin{flushleft}
Contents of the right square of the feeb. 
\par\end{flushleft}

\item [{{\textsf{\textbf{(right-square}}\textsf{\emph{~proximity}}\textsf{\textbf{)}}}}]~


\begin{flushleft}
Contents of the left square of the feeb. 
\par\end{flushleft}

\item [{{\textsf{\textbf{(rear-square}}\textsf{\emph{~proximity}}\textsf{\textbf{)}}}}]~


\begin{flushleft}
Contents of the square behind the feeb. 
\par\end{flushleft}

The vector \textsf{\emph{vision}} has the contents of the
squares that are in front of the feeb. For example, \textsf{\textbf{(aref}}\textsf{\emph{~vision~}}\textsf{0}\textsf{\textbf{)}}
will return the contents of the square in front of the feeb, \textsf{\textbf{(aref}}\textsf{\emph{~vision~}}\textsf{1}\textsf{\textbf{)}}
will return the contents of the next square, and so on. As said before,
\textsf{\textbf{(aref}}\textsf{\emph{~vision~}}\textsf{\textbf{(line-of-sight}}\textsf{\emph{~status}}\textsf{\textbf{))}}
will be the first \textsf{\textbf{'(:rock)}} encountered. All subsequents
square, like \textsf{\textbf{(aref}}\textsf{\emph{~vision~}}\textsf{\textbf{(+}}\textsf{~1~}\textsf{\textbf{(line-of-sight}}\textsf{\emph{~status}}\textsf{\textbf{)))}},
will be garbage and should not be used. 
\end{lyxlist}
The contents of one square returned by any of these calls is either
a list of elements, a wall \textsf{\textbf{'(:rock)}} (i.e. a list
with one element, a \textsf{\textbf{:rock}}) or \textsf{\textbf{()}}
if the square is empty. Each element of the square is one of these:

\begin{itemize}
\item \textbf{Feeb image.} One can call \textsf{\textbf{(feeb-image-p}}\textsf{~element}\textsf{\textbf{)}}
to see if element is a feeb image. 
\item \textbf{Fireball image.} One can call \textsf{\textbf{(fireball-image-p}}\textsf{~element}\textsf{\textbf{)}}
to check if element is a fireball image. 
\item \textsf{\textbf{:carcass}}. If there is a \textsf{\textbf{:carcass}}
in the square of the feeb (i.e. in \textsf{\textbf{(my-square}}\textsf{\emph{~proximity}}\textsf{\textbf{)}}),
the call \textsf{\textbf{:eat-carcass}} will make the feeb eat it. 
\item \textsf{\textbf{:mushroom}}. Analogous to \textsf{\textbf{:carcass}}.
A mushroom appears randomly in places previously marked in the map. 
\end{itemize}

\subsubsection{Feebs and fireballs images}

Both fireballs and feebs that are given to the brain function are
not the real ones, but just images with contents that the brain function
can access. It is allowed to keep and change its contents because
they won't be used internally.

These are the accessors available (they read and change the flies):

\begin{lyxlist}{00.00.0000}
\item [{{\textsf{\textbf{(feeb-image-name}}\textsf{~feeb-image}\textsf{\textbf{)}}}}]~


\begin{flushleft}
The name of the feeb. (Maybe you know it's weak points?) 
\par\end{flushleft}

\item [{{\textsf{\textbf{(feeb-image-facing}}\textsf{~feeb-image}\textsf{\textbf{)}}}}]~


\begin{flushleft}
The facing of the feeb. This way the brain function can see if the
feeb-image either sees the feeb which is playing or not. 
\par\end{flushleft}

\item [{{\textsf{\textbf{(feeb-image-peeking}}\textsf{~feeb-image}\textsf{\textbf{)}}}}]~


\begin{flushleft}
Returns \textsf{\textbf{:peek-left}} or \textsf{\textbf{:peek-right}}
if the feeb is peeking to (its) left or right, or \textsf{\textbf{nil}}
if not. 
\par\end{flushleft}

\item [{{\textsf{\textbf{(fireball-image-direction}}\textsf{~fireball-image}\textsf{\textbf{)}}}}]~


\begin{flushleft}
The direction where the fireball image is going to. 
\par\end{flushleft}

\end{lyxlist}

\subsubsection{Vision-left and vision-right}

\textsf{\emph{vision-left}} and \textsf{\emph{vision-right}} are vectors
similar to vision, but they are less precise in the contents. Also
their valid contents are limited by \textsf{\textbf{(line-of-sight}}\textsf{~}\textsf{\emph{status}}\textsf{\textbf{)}},
so \textsf{\textbf{(aref}}\textsf{~}\textsf{\emph{vision-left}}\textsf{~}\textsf{\textbf{(line-of-sight}}\textsf{~}\textsf{\emph{status}}\textsf{\textbf{))}},
for example, will return \textsf{\textbf{:unknown}}.

Note that feebs that are not peeking, mushrooms and carcasses are
\emph{not} be detected by these vectors. Also, if there is a feeb
peeking to the opposite side, it won't be detected either. The elements
in \textsf{\textbf{vision-left}} and \textsf{\textbf{vision-right}}
are lists containing these elements:

\begin{lyxlist}{00.00.0000}
\item [{{\textsf{\textbf{:peek-letf}}}}] This means that in that square
there is a feeb peeking to (its) left. 
\item [{{\textsf{\textbf{:peek-right}}}}] This means that in that square
there is a feeb peeking to (its) right. 
\item [{{\textsf{\textbf{:rock}}}}] This square is just a wall. In this
case, this is the only element in the square. 
\end{lyxlist}

\subsection{Extra functions provided}

Before making the brain of your feeb, you might want to take a look
at the Extra functions that are available in the file \emph{definitions/extra.lisp}.
The only thing you need so you can use them is to see their code and
know what they do.


\subsection{Changing the map layout}

It is possible to change the layout of the map by calling \textsf{\textbf{(change-layout}}\textsf{~new-layout}\textsf{\textbf{)}}.
There are a few predefined mazes that are in variables \textsf{\textbf{{*}maze-0{*}}}
(which is set by default) throw \textsf{\textbf{{*}maze-5{*}}}. In
a layout, `X' represents a wall, `e' represents a feeb entry point
(there will be as many entry points as feebs in the maze at the same
time), `m' represents a mushroom site and ` ' is a blank space.

If you want to create a new map, you can start by an empty template
of any size that is provided by \textsf{\textbf{(make-template}}\textsf{~x-size~y-size}\textsf{\textbf{)}},
or you can get a random map calling \textsf{\textbf{(generate-maze}}\textsf{~x-size~y-size~}\textsf{\textbf{:density}}\textsf{~density}\textsf{\textbf{)}}
The density is a number, recommended to be between 0.25 and 0.45, which
tells the portion of the maze should be blank spaces. The function
quits after a while if it doesn't meet this portion. See its documentation
for more details and options.


\subsection{Graphics}

With this version of the game, it's possible to choose the graphics
of a feeb when creating it, so your feeb will be more personalized.

The graphic of a feeb is defined by an image file, which should have
three columns by eight lines of pictures of the same size. The four
first lines must be the animations of the feeb walking up, left, down
and right, respectively. The next four lines must be the pictures
of the feeb flaming up, left, down and right, respectively. To see
an example, see {}``default-feeb.png''.

After creating the image file, you must call \textsf{\textbf{(create-graphics}}\textsf{~path-to-image-file}\textsf{\textbf{)}}.
If you now how to work with sdl surfaces in lispbuilder, you may use
the function with a surface instead of a image file; or you can call
\textsf{\textbf{(create-graphics}}\textsf{~path-to-image-file~nil}\textsf{\textbf{)}}
if the surface should not be freed after the call. The result must
be the third argument given to define-feeb.


\subsection{Starting the game}

The game loop is started by calling \textsf{\textbf{(simple-play)}}.


\section{Contests}

I suggest that you read this chapter only after you have created at
least a basic brain feeb, which is better than the (simple) provided
brain, or if you want to participate of a contest or a game with your
friends.


\subsection{\label{sub:Map}Map}

It is possible to get the maze map during the game, but with only
the corridors. Note that the function that gets the map is purposely
a little slow, so, invoking it too many times in a contest that uses
timing attributes is not a good idea; anyway, it is possible to invoke
this function before defining the feeb, and store its value somewhere.
Also note that the map returned does not have any information about
what is really in the maze, but only the possible ways.

To get the map, one can call \textsf{\textbf{(get-maze-map)}}. This
function will return \textsf{\textbf{nil}} if parameter \textsf{\textbf{'may-get-maze-map-p}}
is also \textsf{\textbf{nil}}. Otherwise, the map returned is an array,
so that calling \textsf{\textbf{(aref}}\textsf{~map~x~y}\textsf{\textbf{)}}
will get the contents in the position (x,y) (like euclidean but inverting
the y axis). The contents of a cell could be one of these:

\begin{lyxlist}{00.00.0000}
\item [{{\textsf{\textbf{:mushroom-place}}}}] A mushroom patch, i.e.
when a mushroom is reincarnate, it could reincarnate here. 
\item [{{\textsf{\textbf{:feeb-entry-place}}}}] A feeb entry, i.e. if
a carcass rots a feeb can appear here. 
\item [{{\textsf{\textbf{:rock}}}}] A wall. Feebs cannot come to this
place. 
\item [{{\textsf{\textbf{nil}}}}] An {}``empty'' place, i.e. neither
of the previous. 
\end{lyxlist}
This map can safely be used since \textsf{\textbf{(get-maze-map)}}
makes a new copy every time it is called.


\subsection{Timing}

There are also some timing attributes that can be given to the game.
The more time the feeb takes make a decision, greater is the probability
of its command to be aborted.

To make this available, someone must set these parameters:

\begin{lyxlist}{00.00.0000}
\item [{{\textsf{\textbf{'slow-feeb-noop-switch}}}}] If is non-nil, there
is a possibility that the move of a feeb is aborted according to its
function time. 
\item [{{\textsf{\textbf{'slow-feeb-noop-factor}}}}] The probability
of the feeb to abort will be this factor times the amount of time
the feeb takes to have a decision, divided by the total time taken
by all the feebs in the current turn or divided by a reference time. 
\item [{{\textsf{\textbf{'reference-time}}}}] Time taken by reference
if non-nil. 
\item [{{\textsf{\textbf{'points-for-slow-down}}}}] Points earned when
a feeb's move is aborted due to slowness. 
\end{lyxlist}

\subsection{Sense of location}

Some accessors related to position and orientation of the feeb can
be turned off.

These are the parameters:

\begin{lyxlist}{00.00.0000}
\item [{{\textsf{\textbf{'sense-location-p}}}}] If nil, \textsf{\textbf{x-position}}
and \textsf{\textbf{y-position}} will return nil when someone tries
to invoke it. Otherwise return the position. 
\end{lyxlist}

\subsection{Changing the rules}

To change the rules of the contest, they must be changed before the
feebs are defined, because in a feeb definition it could use the values
of the variables to make a global strategy.

All the parameters, values and documentation that can be listed using
\textsf{\textbf{(list-parameter-settings)}} can be changed using \textsf{\textbf{(change-feeb-parm
name value)}}, which is deactivated during the game. Also, they all
have documentation about themselves, so feel free to use \textsf{\textbf{(documentation~}}\textsf{'parameter~'feeb-parm}\textsf{\textbf{)}}
and see what each parameter does. Documentation is available to external
functions as well.


\section{Reference}

\begin{quote}
Fahlman, S. E. \textbf{\emph{Planet of the Feebs -}} \emph{A Somewhat
Educational Game.} \url{ftp://ftp.csl.sri.com/pub/users/gilham/feebs/feebs.tex}. 
\end{quote}
\end{itemize}

\end{document}
