/[enigma]/enigma/doc/refman/refman.texi
ViewVC logotype

Diff of /enigma/doc/refman/refman.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.5 by dheck, Fri Sep 12 21:37:24 2003 UTC revision 1.6 by dheck, Sun Sep 14 19:32:35 2003 UTC
# Line 109  The resulting level looks like this insi Line 109  The resulting level looks like this insi
109    
110  Let's now turn to a line-by-line analysis of this program:  Let's now turn to a line-by-line analysis of this program:
111    
   
   
112  @example  @example
113   1   CreateWorld(20, 13)   1   CreateWorld(20, 13)
114   2   draw_border("st-brownie")   2   draw_border("st-brownie")
# Line 124  The upper left corner has coordinates (0 Line 122  The upper left corner has coordinates (0
122  coordinates (19,12).  Every block contains a floor tile, an (optional)  coordinates (19,12).  Every block contains a floor tile, an (optional)
123  item, and an (optional) stone.  item, and an (optional) stone.
124    
125  @ignore  A frame of stones is drawn around the newly created landscape with the
126        <para>A frame of stones is drawn around the newly created  @code{draw_border} command.  Its argument, @code{"st-brownie"}, is the
127        landscape with the <function>draw_border</function> command.  name of a stone.  By convention, all stones have @code{"st-"} prefixed
128        Its argument, <literal>"st-brownie"</literal>, is the name of a  to their name, similarly all item names begin with @code{"it-"} and
129        stone.  By convention, all stones have <literal>"st-"</literal>  all floor names with @code{"fl-"}.
130        prefixed to their name, similarly all item names begin with  
131        <literal>"it-"</literal> and all floor names with  The @code{fill_floor} command in line 3 fills the complete floor with
132        <literal>"fl-"</literal>.</para>  tiles of type @code{"fl-hay"}.  The other arguments are the upper left
133    corner and the width and height of the rectangle to be filled.
134        <para>The <function>fill_floor</function> command in line 3  
135        fills the complete floor with tiles of type  @example
136        <literal>"fl-hay"</literal>.  The other arguments are the upper   5   set_stone("st-fart", level_width-1,0, @{name="fart"@})
137        left corner and the width and height of the rectangle to be   6   set_stone("st-timer", 0,0, @{action="trigger", target="fart",
138        filled.</para>   7             interval=10@})
139    @end example
 <programlisting>  
  5   set_stone("st-fart", level_width-1,0, {name="fart"})  
  6   set_stone("st-timer", 0,0, {action="trigger", target="fart",  
  7             interval=10})  
 </programlisting>  
   
       <para>Lines 5 to 7 demonstrate how to create individual stones.  
       The <function>set_stone</function> command takes a stone name,  
       the desired coordinates, and an (optional) list of  
       <emphasis>attributes</emphasis> as arguments.  Note the use of  
       curly braces &quot;{&quot;, &quot;}&quot; to enclose the  
       attribute list.</para>  
   
       <para>Attributes are the key to customizing the behaviour of  
       objects in a landscape.  Here, we first give a name to the first  
       stone we create.  It's a fart stone that has the unpleasant  
       habit of &quot;blowing off&quot; when triggered.  Triggering  
       this fart stone is done by the timer stone we create in line  
       6-7.  This stone performs a predefined action at regular  
       intervals.  In this case we want to send a &quot;trigger&quot;  
       message every ten seconds to the object named  
       &quot;fart&quot;.</para>  
140    
141  <programlisting>  Lines 5 to 7 demonstrate how to create individual stones.  The
142    @code{set_stone} command takes a stone name, the desired
143    coordinates, and an (optional) list of @emph{attributes}
144    as arguments.  Note the use of curly braces @code{@{},
145    @code{@}} to enclose the attribute list.
146    
147    Attributes are the key to customizing the behaviour of objects in a
148    landscape.  Here, we first give a name to the first stone we create.
149    It's a fart stone that has the unpleasant habit of ``blowing off''
150    when triggered.  Triggering this fart stone is done by the timer stone
151    we create in line 6--7.  This stone performs a predefined action at
152    regular intervals.  In this case we want to send a ``trigger'' message
153    every ten seconds to the object named ``fart''.
154    
155    @example
156   9   oxyd(3,3)   9   oxyd(3,3)
157  10   oxyd(level_width-4,level_height-4)  10   oxyd(level_width-4,level_height-4)
158  11   oxyd(level_width-4, 3)  11   oxyd(level_width-4, 3)
159  12   oxyd(3,level_height-4)  12   oxyd(3,level_height-4)
160  13   oxyd_shuffle()  13   oxyd_shuffle()
161  </programlisting>  @end example
162    
163        <para>These commands place a couple of oxyd stones in the level.  These commands place a couple of oxyd stones in the level.  The
164        The <function>oxyd</function> command internally uses  @code{oxyd} command internally uses @code{set_stone("st-oxyd", x,y,
165        <function>set_stone</function><literal>("st-oxyd", x,y, ...)</literal>  ...)}  to create the stones, but it additionally assigns sensible
166        to create the stones, but it additionally assigns sensible  values to some of the oxyd stones' attributes (most notably the
167        values to some of the oxyd stones' attributes (most notably the  color).  The command on line 14 permutes the colors on the oxyd stones
168        color).  The command on line 14 permutes the colors on the oxyd  currently in the landscape.
       stones currently in the landscape.</para>  
   
 <programlisting>  
 15   set_actor("ac-blackball", 10,6.5, {player=0})  
 </programlisting>  
   
       <para>This final line creates the black marble controlled by the  
       player.  Objects that can move around freely are called  
       <emphasis>actors</emphasis> in Enigma.  Unlike stones and items,  
       actors are not restricted to integer coordinates, as you can see  
       in this example.  The last parameter is, as usual, a list of  
       attributes.  In single-player levels this is always  
       <literal>{player=0}</literal> for the black  
       marble, in two-player levels you can use this attribute to  
       assign actors to either player one or two.  </para>  
     </sect1>  
   
 <!-- ------------------------------------------------------------ -->  
     <sect1><title>Functions from <filename>init.lua</filename></title>  
         
       <refentry id="AddRubberBand">  
         <refmeta>  
           <refentrytitle>AddRubberBand</refentrytitle>  
         </refmeta>  
         <refnamediv><refname>AddRubberBand</refname>  
           <refpurpose>Create a new rubber band</refpurpose>  
         </refnamediv>  
             
         <refsynopsisdiv>  
           <programlisting>  
 AddRubberBand(actor, object, strength, length)  
           </programlisting>  
         </refsynopsisdiv>  
         <refsect1><title>Description</title>  
169    
170            <para>This function connects two objects with a rubber band:  @example
171            The first object is always an actor, the second object can  15   set_actor("ac-blackball", 10,6.5, @{player=0@})
172            be either another actor or a stone.</para>  @end example
173                
174            <para>The first argument <parameter>actor</parameter> is  
175            always a reference to an actor created earlier with the  This final line creates the black marble controlled by the player.
176            <function>set_actor</function> function.  The second  Objects that can move around freely are called ``actors'' in Enigma.
177            parameter <parameter>object</parameter> may be either an  Unlike stones and items, actors are not restricted to integer
178            actor or a stone created earlier.  The last two parameters  coordinates, as you can see in this example.  The last parameter is,
179            define the properties of the rubber band:  as usual, a list of attributes.  In single-player levels this is
180            <parameter>strength</parameter> denotes the force factor of  always @code{@{player=0@}} for the black marble, in two-player levels
181            the elastic and <parameter>length</parameter> its natural  you can use this attribute to assign actors to either player one or
182            length.  No force is exerted on the actor if the rubber band  two.
183              is shorter than its natural length.</para>  
184          </refsect1>  
185          <refsect1><title>Example</title>  @node Objects, Variables, Introduction, Top
186            <programlisting>  @chapter Objects
187  local ac=set_actor("ac-blackball", 1.5,7.5, {player=0})  
188    @menu
189    * Stones::                      
190    * Actors::                      
191    @end menu
192    
193    @node Stones, Actors, Objects, Objects
194    @section Stones
195    
196    @menu
197    * st-chameleon::                
198    * st-death::                    
199    * st-death_invisible::          
200    * st-disco::                    
201    * st-easymode::                
202    * st-fart::                    
203    * st-floppy::                  
204    * st-grate::                    
205    * st-knight::                  
206    * st-rubberband::              
207    * st-oneway::                  
208    * st-scissors::                
209    * st-stone_break::              
210    * st-swap::                    
211    * st-thief::                    
212    * st-timer::                    
213    * st-window::                  
214    * st-wood::                    
215    @end menu
216    
217    @node st-chameleon, st-death, Stones, Stones
218    @subsection st-chameleon: Chameleon Stone
219    
220    This stone takes on the look of the floor beneath it.  Actors can
221    move through it, so these stones are perfect for hiding stuff under
222    them...
223    
224    @node st-death, st-death_invisible, st-chameleon, Stones
225    @subsection st-death: Skull Stone
226    
227    Simply kills all marbles that touch it (except when protected by an
228    umbrella).  @ref{st-death_invisible}.
229    
230    @node st-death_invisible, st-disco, st-death, Stones
231    @subsection st-death_invisible: Invivible Skull Stone
232    
233    Simply kills all marbles that touch it (except when protected by an
234    umbrella).  This variant is invisible.  @ref{st-death}.
235    
236    @node st-disco, st-easymode, st-death_invisible, Stones
237    @subsection st-disco: Disco Stones
238    
239    Darkens everything that is underneath the stone (much like tinted
240    glass).  Can be switched on and off (hence the name).
241    
242    @subsubsection Messages
243    
244    @table @code
245    @item signal
246    With parameter 1, lighten the stone and (recursively) all neighboring
247    disco stones; with parameter smaller than 1, darken them.
248    @item lighten
249    @item darken
250    @end table
251    
252    @subsubsection Variants
253    
254    @table @code
255    @item st-disco-light
256    @item st-disco-medium
257    @item st-disco-dark
258    @end table
259    
260    @node st-easymode, st-fart, st-disco, Stones
261    @subsection st-easymode: Easy Mode Stone
262    
263    In easy game mode this stone converts the floor at its position to
264    @code{fl-normal}.  In normal game mode the stone removes any item at
265    its position.  The stone itself never appears in either game mode; it
266    removes itself immediately after performing its job.
267    
268    This stone is commonly used to hide danger areas (water holes, abyss)
269    or to insert helper items (umbrellas, seeds, etc.) that make the level
270    easier in easy game mode.
271    
272    @node st-fart, st-floppy, st-easymode, Stones
273    @subsection st-fart: Fart Stone
274    
275    The fart stone has the unpleasant habit of ``blowing off'' when
276    triggered (by actor hit or signal) and will close all Oxyd stones.
277    
278    @subsubsection Messages
279    
280    @table @code
281    @item trigger
282    blow off
283    @end table
284    
285    
286    
287    @node st-floppy, st-grate, st-fart, Stones
288    @subsection st-floppy: Floppy Switch
289    
290    A switch that is activated by inserting a floppy disk.
291    
292    @subsubsection Attributes
293    
294    @table @code
295    @item on
296    1 or 0
297    @item target
298    @item action
299    @end table
300    
301    @node st-grate, st-knight, st-floppy, Stones
302    @subsection st-grate: Grates
303    
304    Floating grates, mainly decorative.  Flying objects (jumping marbles,
305    rotors, etc.) cannot pass, objects moving on the floor can.
306    
307    @subsubsection Variants
308    
309    @table @code
310    @item st-grate1
311    @item st-grate2
312    @item st-grate3
313    @end table
314    
315    @node st-knight, st-rubberband, st-grate, Stones
316    @subsection st-knight: Knight Stone
317    
318    See user manual for a description.
319    
320    @node st-rubberband, st-oneway, st-knight, Stones
321    @subsection st-rubberband: Rubberband stone
322    
323    If hit by a marble, this stone first removes existing connections with
324    other rubberband stones and then attaches a new elastic between the
325    marble and itself.  Nothing happens if the marble was already attached
326    to this particular stone.
327    
328    This stone can be moved if hit with a magic wand.
329    
330    @subsubsection Attributes
331    
332    @table @code
333    @item length  
334    The natural length of the rubberband (default: 1)
335    @item strength
336    The strength of the rubberband (default: 10)
337    @end table
338    
339    
340    @node st-oneway, st-scissors, st-rubberband, Stones
341    @subsection st-oneway: One-way Stones
342    
343    This stone can be passed by the marble in only one direction. (Or, to
344    be more exact, the arrow on the stone points to the one side of the
345    stone through which it @emph{can't} be entered.  Hard to explain, try
346    it yourself :-)
347    
348    There are three different variants of the one-way stone: the standard
349    one, @code{st-oneway}, which both the black and the white marble can
350    pass, and two colored ones, @code{st-oneway_black} and
351    @code{st-oneway_white}, which completely block marbles of the other
352    color.
353    
354    @subsubsection Variants
355    
356    @table @code
357    @item st-oneway
358    @item st-oneway-[nesw]
359    @item st-oneway_black
360    @item st-oneway_black-[nesw]
361    @item st-oneway_white
362    @item st-oneway_white-[nesw]
363    @end table
364    
365    @subsubsection Attributes
366    
367    
368    @table @code
369    @item orientation
370    One of @code{NORTH}, @code{EAST}, @code{SOUTH}, or @code{WEST}.  This
371    determines the orientation of the stone when the level is loaded.  You
372    need to use the @code{direction} message for changing the orientation
373    during the game.  Note that it is usually easier to use one of the
374    alternative names, like @code{st-oneway-north} instead of explicitly
375    setting this attribute.
376    @end table
377    
378    @subsubsection Messages
379    
380    @table @code
381    @item direction
382    Set the direction of the arrow during the game.  Simply setting the
383    attribute @code{orientation} is not enough, since this does not update
384    the stone's model on the screen.
385    @item signal
386    @item flip
387    Both these messages flip the direction of the arrow.
388    @end table
389    
390    
391    @node st-scissors, st-stone_break, st-oneway, Stones
392    @subsection st-scissors: Scissors Stone
393    
394    This stone cuts all rubber bands attached to an actor that touches it.
395    
396    
397    @node st-stone_break, st-swap, st-scissors, Stones
398    @subsection st-stone_break: Breakable Stone
399    
400    This stone can be destroyed by an actor having a hammer and by laser,
401    dynamite, bombs and bombstones.
402    
403    @node st-swap, st-thief, st-stone_break, Stones
404    @subsection st-swap: Swap Stone
405    
406    This stone can exchange its position with other neighboring stones
407    if it is hit hard enough.  In a way, this makes swap stones a kind
408    of "movable stone", except that they can be only exchanged with
409    other stones and may not be moved on empty fields.
410    
411    
412    @node st-thief, st-timer, st-swap, Stones
413    @subsection st-thief: Thief Stone
414    
415    Takes one item from inventory after when hit by the player's marble.
416    Umbrellas protect against thievery.
417    
418    
419    
420    
421    @node st-timer, st-window, st-thief, Stones
422    @subsection st-timer: Timer Stone
423    
424    This stone can be used to trigger periodic events or to trigger one
425    single event after a certain amount of time.
426    
427    @subsubsection Attributes
428    
429    @table @code
430    @item on
431    1 if the timer is running
432    @item interval
433    number of seconds before @code{action} is performed
434    @item loop
435    if 1, restart the timer after performing @code{action}
436    @item action
437    as usual
438    @item target
439    as usual
440    @item invisible
441    if 1, stone is invisible
442    @end table
443    
444    @subsubsection Messages
445    @table @code
446    @item on
447    @item off
448    @item onoff
449    @end table
450    
451    
452    @subsubsection Example
453    
454    @example
455    -- activate a laser after 5 seconds
456    set_stone("st-laser", 10,11, @{name="laser"@})
457    set_stone("st-timer", 10,10,
458              @{loop=0, action="onoff", target="laser", interval=5@})
459    @end example
460    
461    
462    
463    @node st-window, st-wood, st-timer, Stones
464    @subsection st-window: Breakable Stone
465    
466    Hit this window heavily with your marble to blast it into smithereens.
467    
468    @node st-wood,  , st-window, Stones
469    @subsection st-wood: Wooden Stone
470    
471    This stone is movable.  If moved into abyss, water or swamp it builds
472    a wooden plank.
473    
474    Note: There are two flavors of @code{st-wood} which may be specified
475    by using @code{st-wood1} or @code{st-wood2}.
476    
477    @node Actors,  , Stones, Objects
478    @section Actors
479    
480    Movable objects are called ``actors'' in Enigma.  The commonest actor
481    is, of course, the black marble, but there are a others, including the
482    white marble, the killerball and a few more.
483    
484    @menu
485    * Actor Attributes::            
486    @end menu
487    
488    @node Actor Attributes,  , Actors, Actors
489    @subsection Actor Attributes
490    
491    All actors share a set of common attributes that determine their
492    general behaviour:
493    
494    @table @code
495    @item player
496    The player ``owning'' this actor.  This is either 0 or 1 for the first
497    or second player respectively.  Actors attached to a player can pick
498    up items and can be respawned when they are killed.
499    @item mouseforce
500    A factor that determines how much the actor accelerates when the mouse
501    is moved.  Default is 1, use higher values for fast moving actors.  If
502    set to 0, the actor cannot be moved with the mouse (but external
503    forces can still exert a force on it).
504    @item controllers
505    Determines which players may move this actor: 1=Player 1, 2=Player 2,
506    3=both. By default, @code{ac-blackball}, @code{ac-whiteball} and
507    @code{ac-whiteball-small} have their @code{controllers} attribute set
508    to 1,2, and 3 respectively.
509    @item whiteball, blackball
510    Used by color-sensitive stones (black/white switches for example) to
511    determine whether the actor is the black or the white marble.  These
512    attributes may disappear in future versions, please avoid using them
513    if possible.
514    @end table
515    
516    
517    
518    @node Variables, Functions, Objects, Top
519    @chapter Variables
520    
521    This chapter describes the Lua variables that can be accessed from
522    level descriptions
523    
524    @defvar enigma.AllowTogglePlayer
525    @code{TRUE} or @code{FALSE}
526    @end defvar
527    
528    @defvar enigma.Brittleness
529    A value between 0 and 1, denoting the probability that a brittle floor
530    plate desintegrates further when an actor enters or leaves it.  1
531    means that the floor will always crack, 0 that it is indestructible.
532    @end defvar
533    
534    @defvar enigma.ConserveLevel
535    @code{TRUE} or @code{FALSE}.  If @code{FALSE}, reload the level
536    whenever the an actor that is controlled by a player (i.e., one that
537    has the @code{player} attribute set) dies.  Often used in meditation
538    landscapes or landscapes that are intended to be solved in one go.
539    @end defvar
540    
541    @defvar enigma.ElectricForce
542    @end defvar
543    
544    @defvar enigma.FrictionFactor
545    @end defvar
546    
547    @defvar enigma.ShowMoves
548    TRUE or FALSE.  This is only used in the Sokoban level pack.
549    @end defvar
550    
551    @defvar enigma.SlopeForce
552    @end defvar
553    
554    @defvar enigma.SlopeForce2
555    @end defvar
556    
557    
558    @node Functions, Object Index, Variables, Top
559    @chapter Functions
560    
561    @menu
562    * AddRubberBand::              
563    * CreateWorld::                
564    @end menu
565    
566    @node AddRubberBand, CreateWorld, Functions, Functions
567    @section AddRubberBand
568    
569    @defun AddRubberBand (actor, object, strength, length)
570    
571    This function connects two objects with a rubber band: The first
572    object is always an actor, the second object can be either another
573    actor or a stone.
574    
575    The first argument @var{actor} is always a reference to an actor
576    created earlier with the @code{set_actor} function.  The second
577    parameter @var{object} may be either an actor or a stone created
578    earlier.  The last two parameters define the properties of the rubber
579    band: @var{strength} denotes the force factor of the elastic and
580    @var{length} its natural length.  No force is exerted on the actor if
581    the rubber band is shorter than its natural length.
582    
583    @end defun
584    
585    @subsection Example
586    
587    @example
588    local ac=set_actor("ac-blackball", 1.5,7.5, @{player=0@})
589  local st=set_stone("st-brownie", 10,6)  local st=set_stone("st-brownie", 10,6)
590  AddRubberBand(ac, st, 50, 10)  AddRubberBand(ac, st, 50, 10)
591            </programlisting>  @end example
         </refsect1>  
       </refentry>  
           
       <refentry id="CreateWorld">  
         <refmeta>  
           <refentrytitle>CreateWorld</refentrytitle>  
         </refmeta>  
         <refnamediv><refname>CreateWorld</refname>  
           <refpurpose>Initialize the level</refpurpose>  
         </refnamediv>  
           
         <refsynopsisdiv>  
           <programlisting>  
 CreateWorld(width, heigth)  
           </programlisting>  
         </refsynopsisdiv>  
592    
593            <refsect1><title>Description</title>  @node CreateWorld,  , AddRubberBand, Functions
594    @section CreateWorld
595    
596              <para>This function creates a new level. Because objects  @defun CreateWorld (width, heigth)
597              can only be added to the level after  
598              <function>CreateWorld</function> has been called, you  This function creates a new level. Because objects can only be added
599              should usually do so near the beginning of your level  to the level after @code{CreateWorld} has been called,
600              description. </para>  you should usually do so near the beginning of your level
601    description.
602              <para>The <parameter>width</parameter> and  
603              <parameter>height</parameter> denote the size of the size  The @var{width} and @var{height} denote the size of the size of the
604              of the new level.  All levels with only one screen have  new level.  All levels with only one screen have the minimum size of
605              the minimum size of 20x13 blocks.  Larger levels  20x13 blocks.
606    
607              <para>Note that level fields are indexed from zero, i.e,  Note that level fields are indexed from zero, i.e, the field indices
608              the field indices for a 20x13 level are in the range  for a 20x13 level are in the range (0..19)x(0..12). Also note that the
609              (0..19)x(0..12). Also note that the screens in Enigma  screens in Enigma overlap by one line or column: A level that fits on
610              overlap by one line or column: A level that fits on a  a single screen has size of 20x13, but two a level that is two screens
611              single screen has size of 20x13, but two a level that is  wide 39x13 or 20x25, three screens 58x13 or 20x37.
612              two screens wide 39x13 or 20x25, three screens 58x13 or  @end defun
613              20x37. </para>  
614            </refsect1>  @ignore
         </refentry>  
615    
 <!--  
       <refentry>  
         <refmeta>  
           <refentrytitle></refentrytitle>  
         </refmeta>  
         <refnamediv><refname></refname>  
           <refpurpose></refpurpose>  
         </refnamediv>  
         <refsect1><title>Description</title>  
           <para></para>  
         </refsect1>  
       </refentry>  
 -->  
616    
617        <refentry>        <refentry>
618          <refmeta>          <refmeta>
# Line 861  set_stone("st-invisible", 7, 9)     -- d Line 1189  set_stone("st-invisible", 7, 9)     -- d
1189    
1190  <h2>Functions and variables internal to Enigma</h2>  <h2>Functions and variables internal to Enigma</h2>
1191      display.SetFollowMode(display.FOLLOW_SCREEN)      display.SetFollowMode(display.FOLLOW_SCREEN)
     enigma.ConserveLevel = TRUE  
1192    
1193  @end ignore  @end ignore
1194    
1195    
 @node Objects, Variables, Introduction, Top  
 @chapter Objects  
   
 @menu  
 * Stones::                        
 * Actors::                        
 @end menu  
   
 @node Stones, Actors, Objects, Objects  
 @section Stones  
   
 @menu  
 * st-chameleon::                  
 * st-death::                      
 * st-death_invisible::            
 * st-disco::                      
 * st-easymode::                  
 * st-fart::                      
 * st-floppy::                    
 * st-grate::                      
 * st-knight::                    
 * st-rubberband::                
 * st-oneway::                    
 * st-scissors::                  
 * st-stone_break::                
 * st-swap::                      
 * st-thief::                      
 * st-timer::                      
 * st-window::                    
 * st-wood::                      
 @end menu  
   
 @node st-chameleon, st-death, Stones, Stones  
 @subsection st-chameleon: Chameleon Stone  
   
 This stone takes on the look of the floor beneath it.  Actors can  
 move through it, so these stones are perfect for hiding stuff under  
 them...  
   
 @node st-death, st-death_invisible, st-chameleon, Stones  
 @subsection st-death: Skull Stone  
   
 Simply kills all marbles that touch it (except when protected by an  
 umbrella).  @ref{st-death_invisible}.  
   
 @node st-death_invisible, st-disco, st-death, Stones  
 @subsection st-death_invisible: Invivible Skull Stone  
   
 Simply kills all marbles that touch it (except when protected by an  
 umbrella).  This variant is invisible.  @ref{st-death}.  
   
 @node st-disco, st-easymode, st-death_invisible, Stones  
 @subsection st-disco: Disco Stones  
   
 Darkens everything that is underneath the stone (much like tinted  
 glass).  Can be switched on and off (hence the name).  
   
 @subsubsection Messages  
   
 @table @code  
 @item signal  
 With parameter 1, lighten the stone and (recursively) all neighboring  
 disco stones; with parameter smaller than 1, darken them.  
 @item lighten  
 @item darken  
 @end table  
   
 @subsubsection Variants  
   
 @table @code  
 @item st-disco-light  
 @item st-disco-medium  
 @item st-disco-dark  
 @end table  
   
 @node st-easymode, st-fart, st-disco, Stones  
 @subsection st-easymode: Easy Mode Stone  
   
 In easy game mode this stone converts the floor at its position to  
 @code{fl-normal}.  In normal game mode the stone removes any item at  
 its position.  The stone itself never appears in either game mode; it  
 removes itself immediately after performing its job.  
   
 This stone is commonly used to hide danger areas (water holes, abyss)  
 or to insert helper items (umbrellas, seeds, etc.) that make the level  
 easier in easy game mode.  
   
 @node st-fart, st-floppy, st-easymode, Stones  
 @subsection st-fart: Fart Stone  
   
 The fart stone has the unpleasant habit of ``blowing off'' when  
 triggered (by actor hit or signal) and will close all Oxyd stones.  
   
 @subsubsection Messages  
   
 @table @code  
 @item trigger  
 blow off  
 @end table  
   
   
   
 @node st-floppy, st-grate, st-fart, Stones  
 @subsection st-floppy: Floppy Switch  
   
 A switch that is activated by inserting a floppy disk.  
   
 @subsubsection Attributes  
   
 @table @code  
 @item on  
 1 or 0  
 @item target  
 @item action  
 @end table  
   
 @node st-grate, st-knight, st-floppy, Stones  
 @subsection st-grate: Grates  
   
 Floating grates, mainly decorative.  Flying objects (jumping marbles,  
 rotors, etc.) cannot pass, objects moving on the floor can.  
   
 @subsubsection Variants  
   
 @table @code  
 @item st-grate1  
 @item st-grate2  
 @item st-grate3  
 @end table  
   
 @node st-knight, st-rubberband, st-grate, Stones  
 @subsection st-knight: Knight Stone  
   
 See user manual for a description.  
   
 @node st-rubberband, st-oneway, st-knight, Stones  
 @subsection st-rubberband: Rubberband stone  
   
 If hit by a marble, this stone first removes existing connections with  
 other rubberband stones and then attaches a new elastic between the  
 marble and itself.  Nothing happens if the marble was already attached  
 to this particular stone.  
   
 This stone can be moved if hit with a magic wand.  
   
 @subsubsection Attributes  
   
 @table @code  
 @item length    
 The natural length of the rubberband (default: 1)  
 @item strength  
 The strength of the rubberband (default: 10)  
 @end table  
   
   
 @node st-oneway, st-scissors, st-rubberband, Stones  
 @subsection st-oneway: One-way Stones  
   
 This stone can be passed by the marble in only one direction. (Or, to  
 be more exact, the arrow on the stone points to the one side of the  
 stone through which it @emph{can't} be entered.  Hard to explain, try  
 it yourself :-)  
   
 There are three different variants of the one-way stone: the standard  
 one, @code{st-oneway}, which both the black and the white marble can  
 pass, and two colored ones, @code{st-oneway_black} and  
 @code{st-oneway_white}, which completely block marbles of the other  
 color.  
   
 @subsubsection Variants  
   
 @table @code  
 @item st-oneway  
 @item st-oneway-[nesw]  
 @item st-oneway_black  
 @item st-oneway_black-[nesw]  
 @item st-oneway_white  
 @item st-oneway_white-[nesw]  
 @end table  
   
 @subsubsection Attributes  
   
   
 @table @code  
 @item orientation  
 One of @code{NORTH}, @code{EAST}, @code{SOUTH}, or @code{WEST}.  This  
 determines the orientation of the stone when the level is loaded.  You  
 need to use the @code{direction} message for changing the orientation  
 during the game.  Note that it is usually easier to use one of the  
 alternative names, like @code{st-oneway-north} instead of explicitly  
 setting this attribute.  
 @end table  
   
 @subsubsection Messages  
   
 @table @code  
 @item direction  
 Set the direction of the arrow during the game.  Simply setting the  
 attribute @code{orientation} is not enough, since this does not update  
 the stone's model on the screen.  
 @item signal  
 @item flip  
 Both these messages flip the direction of the arrow.  
 @end table  
   
   
 @node st-scissors, st-stone_break, st-oneway, Stones  
 @subsection st-scissors: Scissors Stone  
   
 This stone cuts all rubber bands attached to an actor that touches it.  
   
   
 @node st-stone_break, st-swap, st-scissors, Stones  
 @subsection st-stone_break: Breakable Stone  
   
 This stone can be destroyed by an actor having a hammer and by laser,  
 dynamite, bombs and bombstones.  
   
 @node st-swap, st-thief, st-stone_break, Stones  
 @subsection st-swap: Swap Stone  
   
 This stone can exchange its position with other neighboring stones  
 if it is hit hard enough.  In a way, this makes swap stones a kind  
 of "movable stone", except that they can be only exchanged with  
 other stones and may not be moved on empty fields.  
   
   
 @node st-thief, st-timer, st-swap, Stones  
 @subsection st-thief: Thief Stone  
   
 Takes one item from inventory after when hit by the player's marble.  
 Umbrellas protect against thievery.  
   
   
   
   
 @node st-timer, st-window, st-thief, Stones  
 @subsection st-timer: Timer Stone  
   
 This stone can be used to trigger periodic events or to trigger one  
 single event after a certain amount of time.  
   
 @subsubsection Attributes  
   
 @table @code  
 @item on  
 1 if the timer is running  
 @item interval  
 number of seconds before @code{action} is performed  
 @item loop  
 if 1, restart the timer after performing @code{action}  
 @item action  
 as usual  
 @item target  
 as usual  
 @item invisible  
 if 1, stone is invisible  
 @end table  
   
 @subsubsection Messages  
 @table @code  
 @item on  
 @item off  
 @item onoff  
 @end table  
   
   
 @subsubsection Example  
   
 @example  
 -- activate a laser after 5 seconds  
 set_stone("st-laser", 10,11, @{name="laser"@})  
 set_stone("st-timer", 10,10,  
           @{loop=0, action="onoff", target="laser", interval=5@})  
 @end example  
   
   
   
 @node st-window, st-wood, st-timer, Stones  
 @subsection st-window: Breakable Stone  
   
 Hit this window heavily with your marble to blast it into smithereens.  
   
 @node st-wood,  , st-window, Stones  
 @subsection st-wood: Wooden Stone  
   
 This stone is movable.  If moved into abyss, water or swamp it builds  
 a wooden plank.  
   
 Note: There are two flavors of @code{st-wood} which may be specified  
 by using @code{st-wood1} or @code{st-wood2}.  
   
 @node Actors,  , Stones, Objects  
 @section Actors  
   
 Movable objects are called ``actors'' in Enigma.  The commonest actor  
 is, of course, the black marble, but there are a others, including the  
 white marble, the killerball and a few more.  
   
 @node Actor Attributes,,,  
 @subsection Actor Attributes  
   
 All actors share a set of common attributes that determine their  
 general behaviour:  
   
 @table @code  
 @item player  
 The player ``owning'' this actor.  This is either 0 or 1 for the first  
 or second player respectively.  Actors attached to a player can pick  
 up items and can be respawned when they are killed.  
 @item mouseforce  
 A factor that determines how much the actor accelerates when the mouse  
 is moved.  Default is 1, use higher values for fast moving actors.  If  
 set to 0, the actor cannot be moved with the mouse (but external  
 forces can still exert a force on it).  
 @item controllers  
 Determines which players may move this actor: 1=Player 1, 2=Player 2,  
 3=both. By default, @code{ac-blackball}, @code{ac-whiteball} and  
 @code{ac-whiteball-small} have their @code{controllers} attribute set  
 to 1,2, and 3 respectively.  
 @item whiteball, blackball  
 Used by color-sensitive stones (black/white switches for example) to  
 determine whether the actor is the black or the white marble.  These  
 attributes may disappear in future versions, please avoid using them  
 if possible.  
 @end table  
   
   
   
 @node Variables, Functions, Objects, Top  
 @chapter Variables  
   
 @node Functions, Object Index, Variables, Top  
 @chapter Functions  
   
1196  @node Object Index, Variables Index, Functions, Top  @node Object Index, Variables Index, Functions, Top
1197  @unnumbered Object Index  @unnumbered Object Index
1198    

Legend:
Removed from v.1.5  
changed lines
  Added in v.1.6

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26