[Adonthell-commits] CVS: doc/scripting_guide .cvsignore,NONE,1.1 Makefile,NONE,1.1 intro.tex,NONE,1.1 items.tex,NONE,1.1 scripting_guide.tex,NONE,1.1

[Kai Sterker <address@hidden>]

Update of /cvsroot/adonthell/doc/scripting_guide
In directory subversions:/tmp/cvs-serv8372/scripting_guide

Added Files:
        .cvsignore Makefile intro.tex items.tex scripting_guide.tex 
Log Message:
ADDED beginning of Adonthell Scripting Guide
ADDED distributing and obtaining information


--- NEW FILE ---
*.aux
*.log
*.toc
*.pdf
*.tgz
*.out
*.ind
*.idx
*.ilg
*.zip
*.eps

--- NEW FILE ---
IMAGES = 
        
all: pdf

pdf: ${IMAGES} *.tex
        pdflatex scripting_guide.tex

%.pdf: %.eps
        epstopdf $<

%.eps: %.ps
        ps2eps -f $<

%.eps: %.fig
        fig2dev -Leps $< $*.eps
        
%.ps: %.dot
        dot -Tps2 -o $*.ps $<

clean:
        rm -rf *.ps *.eps *.pdf

--- NEW FILE ---
\section{Introduction}
\thispagestyle{empty}

\subsection{About the Scripting Guide}

One of Adonthell's fundamental design principles is to keep engine and game 
strictly seperate. Therefore, a lot of game specific functionality is not 
included in the engine, but needs to be written anew for each game. This makes 
the engine very flexible and allows to create very different kinds of RPGs. 
However, it also requires plenty of Python scripting. To ease this task, this 
guide has been compiled. It will explain the structure of each script and also 
give some example code. However, it is not supposed to replace the Adonthell 
API documentation, which explains the available classes and methods in much 
greater detail.\\

It is assumed that the reader has at least a basic understanding of Python and 
object oriented programming (OOP). The Python tutorial\footnote{\sf 
\href{http://www.python.org/doc/current/tut/tut.html}{http://www.python.org/doc/current/tut/tut.html}}
 is a good source to refresh your memories on these topics, if necessary.

\subsection{Conventions}

Since Python is no strongly typed language, the type of parameters will often 
be not clear from the examples. Therefore it will be added in brackets, where 
useful. So a line like

{\footnotesize
\begin{verbatim}
def [item_base] combine (self, [item_base] item)
\end{verbatim}
}

indicates that the {\tt combine} method has both argument and return value of 
type {\tt item\_base}. This helps finding the respective class description in 
the API documention. 

\subsection{Obtaining and Distributing the Guide}

The Adonthell Scripting Guide can be redistributed freely. The most recent 
version can be obtained from the Adonthell website\footnote{\sf 
\href{http://adonthell.linuxgames.com/download/documentation.shtml}{http://adonthell.linuxgames.com/download/documentation.shtml}}.
 The \LaTeX{} sources are available via anonymous CVS. To retrieve them, issue 
the following commands:

{\footnotesize
\begin{verbatim}
cvs -d:pserver:address@hidden:/cvsroot/adonthell login
cvs -z3 -d:pserver:address@hidden:/cvsroot/adonthell co -P doc
\end{verbatim}
}

If prompted for a password, simply hit enter. To update your copy of the code, 
run

{\footnotesize
\begin{verbatim}
cvs -z3 -update -dP
\end{verbatim}
}

within the documentation directory from time to time.

--- NEW FILE ---
\section{Item Scripting}
\thispagestyle{plain}

Items are an area where lots of customization can be done, as they live mostly 
on Python side. However, this makes them a complex topic, where errors will 
often result in weird behaviour. Therefore, it is vital to get at least a basic 
understanding of the item implementation.


\subsection{Inside the Engine}

On the outside, all items are treated alike, but internally there is a huge 
difference between {\it mutable} and {\it immutable} items. Mutable items are 
all those items that can change their state throughout the game, like a torch 
that burns down, or a container that can be filled or emptied. Because of that, 
the engine has to keep track of each individual mutable item, which can become 
quite costly if there are a large number of them. \\

Immutable items on the other hand -- that is, items that don't change, like a 
coin or an arrow -- are not treated that way. Instead, exactly one copy of each 
immutable item type exists throughout the game. All instances of such an item 
are mere references to that single copy. This means, if an immutable item gets 
changed, all items of the same type will change as well! So be careful. \\

For more information about item internals, please refer to the item chapter of 
the Engine Architecture documentation.


\subsection{Basic Interface}

Above it says that items live mostly on Python side. That doesn't mean they are 
totally independent from the engine, though. Item management is part of the 
engine, and it relies upon a specific interface. Fortunately, the item base 
class, defined in {\tt item.py}, provides most of this interface already. As 
long as all items inherit (directly or indirectly) from the {\tt item} class, 
little further work needs to be done. Only three things have to be taken care 
of:

\begin{description}
\item[Constructor] If an item requires an {\tt \_\_init\_\_} method, it must 
not forget to call the constructor of its base class. Otherwise, some 
attributes of the item might remain unitialized, and errors will surely follow.

\item[Saving] Each item must be able to save its current state. For that 
purpose, it has to provide the {\tt put\_state} method. Apart from saving its 
own attributes, it must not forget to save its base class.

\item[Loading] Finally, an item must be able to restore its state. This is done
via the {\tt get\_state} method. Again, items must also take care of loading 
the state of their base class.
\end{description}

Script \ref{ItemTemplate} on the next page can serve as template for new items.

\begin{Script}
\caption{Item template}\label{ItemTemplate}
{\footnotesize
\begin{verbatim}

import base_class

#
# Item description goes here
#
class new_item (base_class.base_class):

    def __init__ (self):
        # -- init parent class
        base_class.base_class.__init__(self)
       
        # -- init attributes ...
        
    def [void] put_state (self, [ogzstream] file):
        # -- save state of parent class
        base_class.base_class.put_state (self, file)
        
        # -- save attributes ...
  
    def [void] get_state (self, [igzstream] file):
        # -- load state of parent class
        base_class.base_class.get_state (self, file)
        
        # -- load attributes ...
\end{verbatim}
}
\end{Script}


\subsection{Advanced Interface}

While the methods described above are essential for item management, they do 
little in terms of defining an item's properties and abilities. For that 
purpose, six more methods -- the so called {\it item actions} -- have been 
defined: {\tt pick\_up}, {\tt drop}, {\tt equip}, {\tt unequip}, {\tt combine} 
and {\tt use}. However, not every item needs to implement every action. Those 
that are not essential to an item's functionality can be omitted. Purpose and 
constraints of each action are described in detail below.

\paragraph{The {\tt combine} method} is used to implement actions involving 
exactly two items, a {\it target} and an {\it agent}. The target is transformed 
in the process, as some examples will show:

\begin{table}[h]
\center
\begin{tabular}{lllll}
\hline
{\bf target} & & {\bf agent} & & {\bf result} \\
\hline
lamp  & $+$ & lamp oil & $\rightarrow$ & lamp (refilled) \\
stick & $+$ & knife    & $\rightarrow$ & wooden arrow \\
arrow & $+$ & poison   & $\rightarrow$ & poisoned arrow \\
\hline
\end{tabular}
\caption{Item combination examples}
\end{table}

If the combination is sucessful, the result has to be returned. If the two 
items cannot be combined, the result is {\tt None}. If the target item was 
stackable, the result must be stackable as well, and its maximum stack size 
must be at least as large as that of the target.

--- NEW FILE ---
\documentclass[11pt, a4paper, twoside, pdftex]{article}
\usepackage[english]{babel}
\usepackage{a4}
\usepackage{a4wide}
\usepackage{pifont}
\usepackage{array}
\usepackage{calc}
\usepackage[pdftex]{graphicx}
\usepackage[pdftex,
            pagebackref=true,
            colorlinks=true,
            linkcolor=blue,
            urlcolor=blue,
            pdftitle={Adonthell Scripting Guide},
            pdfauthor={Kai Sterker},
            bookmarksopen=True,
            pdfsubject={Adonthell Designer's Reference}
           ]{hyperref}
\usepackage{fancyheadings}
\usepackage{float}
%\usepackage{makeidx}
%\makeindex

%------- Redefinitions ----------
\newcommand{\clearemptydoublepage}{\newpage{\pagestyle{empty}\cleardoublepage}}
%\newcommand{\Index}[1]{#1\index{#1}}

\floatstyle{ruled}
\newfloat{Script}{ths}{los}

\begin{document} 
 
%-------------- Title ----------------
\clearemptydoublepage         % Title
\pagestyle{empty}
\title{Adonthell \\ Scripting Guide}
\author{Kai Sterker}
\date{21.02.2003}
\maketitle
\thispagestyle{empty}

%------------------------------------------
\newpage                      % Copyright
\pagestyle{empty}

\begin{center}
{\sc Adonthell \\ Scripting Guide} \\
\vspace*{\stretch{2}}
This document is part of the Adonthell Designer's documentation\\
{\sf \href{http://adonthell.linuxgames.com}{http://adonthell.linuxgames.com}}\\
\vspace{1em}
\Pisymbol{psy}{211} 2003 Kai Sterker \& The Adonthell Team\\
{\sf address@hidden
\vspace{1em}
Created with \LaTeX{}2\raisebox{-0.4ex}{$\varepsilon$}
\end{center}
\clearemptydoublepage

%------------- Layout ---------------------
\pagestyle{fancyplain}
\addtolength{\headwidth}{\marginparsep}
\addtolength{\headwidth}{\marginparwidth}
\renewcommand{\sectionmark}[1]{\markboth{\thesection\ #1}{}}
\renewcommand{\subsectionmark}[1]{\markright{#1}}
\lhead[\fancyplain{}{\bfseries\thepage}]{\fancyplain{}{\bfseries\rightmark}}
\rhead[\fancyplain{}{\bfseries\leftmark}]{\fancyplain{}{\bfseries\thepage}}
\cfoot{}

%------------------------------------------
\tableofcontents             % Contents
\thispagestyle{empty}
%------------------------------------------
\pagenumbering{arabic}
\include{intro}             % Introduction
\include{items}             % Item scripting
\end{document}