[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Adonthell-commits] CVS: doc/scripting_guide .cvsignore,NONE,1.1 Makefi
From: |
Kai Sterker <address@hidden> |
Subject: |
[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 |
Date: |
Sat, 22 Feb 2003 06:27:08 -0500 |
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}
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [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> <=
- Prev by Date:
[Adonthell-commits] CVS: doc/architecture abstract.tex,1.2,NONE
- Next by Date:
[Adonthell-commits] CVS: doc/plot_guideline intro.tex,NONE,1.1 Makefile,1.1,1.2 documentation.tex,1.1,1.2 dot.tex,1.1,1.2 main_plot.tex,1.1,1.2 npc.tex,1.1,1.2 plot_guideline.tex,1.1,1.2 side_quest.tex,1.1,1.2 abstract.tex,1.1,NONE
- Previous by thread:
[Adonthell-commits] CVS: doc/architecture abstract.tex,1.2,NONE
- Next by thread:
[Adonthell-commits] CVS: doc/plot_guideline intro.tex,NONE,1.1 Makefile,1.1,1.2 documentation.tex,1.1,1.2 dot.tex,1.1,1.2 main_plot.tex,1.1,1.2 npc.tex,1.1,1.2 plot_guideline.tex,1.1,1.2 side_quest.tex,1.1,1.2 abstract.tex,1.1,NONE
- Index(es):