[Enigma-cvs] enigma/doc/refman enigma-ref.texi,1.3,1.4

[Ralf Westram <address@hidden>]

Update of /cvsroot/enigma/enigma/doc/refman
In directory subversions:/tmp/cvs-serv7424/doc/refman

Modified Files:
        enigma-ref.texi 
Log Message:
- added enigma.SendMessage, enigma.GetNamedObject
- started section 'General object attributes'
- added description for it-hollow
- added some @ref's (some not available yet)




Index: enigma-ref.texi
===================================================================
RCS file: /cvsroot/enigma/enigma/doc/refman/enigma-ref.texi,v
retrieving revision 1.3
retrieving revision 1.4
diff -C2 -d -r1.3 -r1.4
*** enigma-ref.texi     22 Oct 2003 21:50:34 -0000      1.3
--- enigma-ref.texi     23 Oct 2003 18:41:02 -0000      1.4
***************
*** 15,19 ****
  @top
  
! This manual describes the internals of Enigma, in particular how to
  build new levels using Lua and how to interact with the game engine.
  It describes Enigma version 0.81.
--- 15,19 ----
  @top
  
! This manual describes the internals of 
@uref{http://www.nongnu.org/enigma/,Enigma}, in particular how to
  build new levels using Lua and how to interact with the game engine.
  It describes Enigma version 0.81.
***************
*** 276,279 ****
--- 276,280 ----
  * Stones::
  * Actors::
+ * General object attributes::
  @end menu
  
***************
*** 283,289 ****
  @menu
  * it-documents::                Scrolls of Paper
  @end menu
  
! @node it-documents,  , Items, Items
  @subsection it-document: Scrolls of Paper
  
--- 284,291 ----
  @menu
  * it-documents::                Scrolls of Paper
+ * it-hollow::                   Hollows in the floor
  @end menu
  
! @node it-documents, it-hollow , Items, Items
  @subsection it-document: Scrolls of Paper
  
***************
*** 305,308 ****
--- 307,332 ----
  @end example
  
+ @node it-hollow,   , Items, Items
+ @subsection it-hollow: Hollows in the floor
+ 
+ This item creates a hollow in the floor.
+ If all existing @ref{ac-whiteball-small} are inside hollows the level 
succeeds.
+ 
+ Hollows have the following attributes:
+ 
+ @table @code
+ @item essential
+ Whether the hollow must be filled with a whiteball to end the level (1 means 
'yes').
+ 
+ Use this attribute if there are more hollows than small whiteballs in a
+ level and you want to determine which of the hollows are needed to
+ finish the level.
+ 
+ For example: If you have many hollows and 3 whiteballs, then
+ set @code{essential=1} in 3 hollows. The game will end when the
+ 3 whiteballs are inside the 3 marked hollows.
+ 
+ @end table
+ 
  
  @node Stones, Actors, Items, Objects
***************
*** 337,346 ****
  These stones apply an impulse to actors that touch them.  The amount
  of force applied can be controlled by setting
! @code{enigma.BumperForce} accordingly (the default is 800).
  Alternatively, the @code{force} attribute can be used to set this
  factor for @emph{individual} bumper stones.
  
! The invisible variant, @code{st-actorimpulse_invisible} can
! ``painted'' with a brush.
  
  @node st-chameleon, st-coinslot, st-actorimpulse, Stones
--- 361,370 ----
  These stones apply an impulse to actors that touch them.  The amount
  of force applied can be controlled by setting
! @ref{enigma.BumperForce} accordingly (the default is 800).
  Alternatively, the @code{force} attribute can be used to set this
  factor for @emph{individual} bumper stones.
  
! The invisible variant, @ref{st-actorimpulse_invisible} can
! ``painted'' with a @ref{it-brush}.
  
  @node st-chameleon, st-coinslot, st-actorimpulse, Stones
***************
*** 651,655 ****
  by using @code{st-wood1} or @code{st-wood2}.
  
! @node Actors,  , Stones, Objects
  @section Actors
  
--- 675,679 ----
  by using @code{st-wood1} or @code{st-wood2}.
  
! @node Actors, General object attributes , Stones, Objects
  @section Actors
  
***************
*** 696,700 ****
--- 720,731 ----
  @end table
  
+ @node General object attributes, , Actors, Objects
+ @section General object attributes
  
+ @table @code
+ @item name
+ All objects may be given a @code{name} attribute. Such @emph{named objects} 
can
+ be searched using @ref{enigma.GetNamedObject}.
+ @end table
  
  @node Variables, Functions, Objects, Top
***************
*** 749,752 ****
--- 780,785 ----
  * AddRubberBand::
  * CreateWorld::
+ * enigma.GetNamedObject::
+ * enigma.SendMessage::
  @end menu
  
***************
*** 778,782 ****
  @end example
  
! @node CreateWorld,  , AddRubberBand, Functions
  @section CreateWorld
  
--- 811,815 ----
  @end example
  
! @node CreateWorld, enigma.GetNamedObject , AddRubberBand, Functions
  @section CreateWorld
  
***************
*** 798,801 ****
--- 831,887 ----
  wide 39x13 or 20x25, three screens 58x13 or 20x37.
  @end defun
+ 
+ 
+ @node enigma.GetNamedObject, enigma.SendMessage, CreateWorld, Functions
+ @section enigma.GetNamedObject
+ 
+ @defun enigma.GetNamedObject (objname)
+ 
+ This function searches for an object which has a @code{name} attribute
+ with value @var{objname}.
+ 
+ This is often used in conjunction with @ref{enigma.SendMessage}.
+ 
+ @end defun
+ 
+ @subsection Example
+ 
+ @example
+ set_stone("st-wood", 7, 11, {name="woodie"})
+ ...
+ local Woodie = enigma.GetNamedObject("woodie")
+ @end example
+ 
+ 
+ @node enigma.SendMessage,  , enigma.GetNamedObject, Functions
+ @section enigma.SendMessage
+ 
+ @defun enigma.SendMessage (object, message, data)
+ 
+ This function sends a @var{message} to an @var{object}.
+ If the @var{object} is aware of the sent @var{message} it will react properly
+ (e.g. toggle its state or change its direction).
+ If the @var{message} is unknown to the @var{object} nothing will happen.
+ 
+ @var{data} either contains a value expected by a specific message or 
@code{nil}.
+ 
+ Documentation about the messages known by a specific object can be found
+ in the description of the @ref{Objects}.
+ 
+ @end defun
+ 
+ @subsection Examples
+ 
+ @example
+ set_stone("st-laser", 2, 2, {name="laser3", dir=SOUTH, on=FALSE})
+ ...
+ enigma.SendMessage(enigma.GetNamedObject("laser3"), "signal", nil)
+ @end example
+ 
+ @example
+ set_stone("st-bolder", 7, 11, {name="bolder1", direction=SOUTH})
+ ...
+ enigma.SendMessage(enigma.GetNamedObject("bolder1"), "direction", WEST)
+ @end example
  
  @ignore