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

[Kai Sterker <address@hidden>]

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

Modified Files:
        .cvsignore items.tex 
Added Files:
        Makefile.am 
Removed Files:
        Makefile 
Log Message:
ADDED configure stuff to detect required tools and ease building of docs


--- NEW FILE ---
# -- require automake 1.6
AUTOMAKE_OPTIONS = 1.6

# -- document sources
TEXFILES = \
        intro.tex \
        items.tex \
        scripting_guide.tex

# -- image files
IMAGES = 

# -- what should be distributed
EXTRA_DIST = ${TEXFILES}

# -- installation target
docdir = ${prefix}/doc/adonthell
doc_DATA = scripting_guide.pdf

# -- build the PDF file
scripting_guide.pdf: ${IMAGES} ${TEXFILES}
        @if test ! -e scripting_guide.toc ; then \
                ${PDFLATEX} scripting_guide.tex; \
        fi
        ${PDFLATEX} scripting_guide.tex 
        @if test `grep -c "Label(s) may have changed." scripting_guide.log` -gt 
0 ; then \
                ${PDFLATEX} scripting_guide.tex; \
        fi

# -- misc rules 
%.pdf: %.eps
        ${EPS2PDF} $<

%.eps: %.ps
        ${PS2EPS} -f $<

%.eps: %.fig
        ${FIG2DEV} -Leps $< $@
        
%.ps: %.dot
        ${DOT} -Tps2 -o $@ $<

# -- actual target
CLEANFILES = scripting_guide.pdf

# -- temporary stuff
MOSTLYCLEANFILES = $(IMAGES) *.ps *.eps *.aux *.log *.out *.toc

Index: .cvsignore
===================================================================
RCS file: /cvsroot/adonthell/doc/scripting_guide/.cvsignore,v
retrieving revision 1.1
retrieving revision 1.2
diff -C2 -r1.1 -r1.2
*** .cvsignore  22 Feb 2003 11:27:05 -0000      1.1
--- .cvsignore  30 Mar 2003 00:22:09 -0000      1.2
***************
*** 1,2 ****
--- 1,4 ----
+ Makefile
+ Makefile.in
  *.aux
  *.log

Index: items.tex
===================================================================
RCS file: /cvsroot/adonthell/doc/scripting_guide/items.tex,v
retrieving revision 1.1
retrieving revision 1.2
diff -C2 -r1.1 -r1.2
*** items.tex   22 Feb 2003 11:27:05 -0000      1.1
--- items.tex   30 Mar 2003 00:22:09 -0000      1.2
***************
*** 9,15 ****
  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.
  
  
--- 9,15 ----
  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!
  
! That may sound very restrictive, but it isn't. Immutable items can still be 
``transformed" into completely different items. See section 
\ref{AdvancedInterface} for more details.
  
  
***************
*** 30,34 ****
  
  \begin{Script}
! \caption{Item template}\label{ItemTemplate}
  {\footnotesize
  \begin{verbatim}
--- 30,34 ----
  
  \begin{Script}
! \caption{Item template (Basic Interface)}\label{ItemTemplate}
  {\footnotesize
  \begin{verbatim}
***************
*** 64,71 ****
  
  \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]
--- 64,75 ----
  
  \subsection{Advanced Interface}
+ \label{AdvancedInterface}
  
  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 equip} method} serves two purposes. For one, it is used 
to test whether an item is equippable (by a certain character). If the equip 
method of an item returns {\tt 1}, the item can be equipped. If it returns {\tt 
0}, or if the item has no equip method, the item cannot be equipped.
! Further, the equip method can also be used to apply any effects the item 
might have on the character.
! 
! \paragraph{The {\tt combine} method} is used to implement actions involving 
exactly two items: an {\it agent} that is ``applied" to a {\it target}. If the 
combination is possible, the target will be transformed, as the following 
examples demonstrate:
  
  \begin{table}[h]
***************
*** 83,85 ****
  \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.
--- 87,100 ----
  \end{table}
  
! If the combination is sucessful, the resulting item has to be returned. If 
the two items cannot be combined, the method should return {\tt None} instead. 
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.
! 
! 
! \subsection{Custom Interface}
! 
! Apart from the basic and advanced interfaces that are required and used by 
the engine, items may of course provide further methods that are accessible 
from other scripts. Weapons for example might provide a {\tt deal\_damage} 
method to calculate the damage a character takes when being hit by that weapon. 
! 
! Whether an item needs a custom interface depends mostly on other parts of a 
game, like rules or combat system. Some items won't need additional methods, 
others will. It's up to you to make the most out of this feature.
! 
! 
! \subsection{Creating Items at Runtime}
! 

--- Makefile DELETED ---