[Top] | [Contents] | [Index] | [ ? ]

# Enigma Reference Manual

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.90.

1. Introduction |  | General remarks on creating new levels
2. XML levels |  | The new XML-based level descriptions
3. Objects |  | Description of all objects in Enigma
4. Variables |  | Lua variables that influence the game
5. Functions |  | Predefined functions
Index |  |

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

# 1. Introduction

This chapter explains how Enigma works internally and how you can create your own levels. This manual is not for users of graphical level editors, but rather for programmers of graphical level editors or users who want to use the full power of the Enigma "engine" by using the built-in scripting language.

There are two kinds of file formats you can use to build levels for Enigma. The traditional solution was to write small programs in a programming language called Lua. Although this is still possible, the preferred way is now to prepare files in a data-centric format called XML; this will be discussed in detail in chapter

Enigma's level format is extremely flexible and allows you to create very dynamic and interactive levels. Here are a few examples of levels that make heavy use of Lua, both when preparing the level and during the game:

- Flood Gates (``nat8.lua`') Was one of the first levels to use Lua for more than simply building the level and then handing it over to the game engine. The flowing water is controlled by a small function written in Lua--there is no built-in suppport for flowing water in the game engine.

- Enigris (``ralf04.lua`') lets you play Tetris inside Enigma.

- Mourning Palace (``ant08.lua`') moving platforms, also controlled by a Lua function.

- Finally, some of the maze levels and most of the levels in the Sokoban pack are dynamically generated: They look a little different every time you play them.

Our focus is on using Lua to access Enigma's game engine, so you won't learn much about Lua as a language in this chapter. Many simple things, like function calls or `if` statements, will appear familiar to anyone having a little programming experience: In many ways Lua is similar to programming languages like Basic or Pascal. But for most of Lua's finer points you will have to reach for the official Lua documentation, which you can download from lua.org.

1.1 Creating New Levels |  |
1.2 A Simple Level |  |
1.3 Registering Levels |  |
1.4 Where to go from here |  |

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 1.1 Creating New Levels

Creating a new level basically consists of the following steps

1. Writing the level description, for example a file named ``daniel01.lua`'.
2. Inserting the new level into a level pack of your choice
3. Creating a preview image for the level
4. Testing the level in Enigma

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 1.2 A Simple Level

Here is a very simple level description that can also serve as a starting-point for new landscapes. (In fact, this is the first level in Enigma, so you can try it out right away.)

     1   CreateWorld(20, 13)
     2   draw_border("st-brownie")
     3   fill_floor("fl-hay", 0,0, level_width,level_height)
     4
     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})
     8
     9   oxyd(3,3)
    10   oxyd(level_width-4,level_height-4)
    11   oxyd(level_width-4, 3)
    12   oxyd(3,level_height-4)
    13   oxyd_shuffle()
    14
    15   set_actor("ac-blackball", 10,6.5)

The resulting level looks like this inside the game:

Let's now turn to a line-by-line analysis of this program:

     1   CreateWorld(20, 13)
     2   draw_border("st-brownie")
     3   fill_floor("fl-hay", 0,0, level_width,level_height)

The level begins with a call to `CreateWorld`, which creates a new world that is 20 blocks wide and 13 blocks high. Every block in the world can be accessed with a pair of coordinates: The upper left corner has coordinates (0,0), the lower right one has coordinates (19,12). Every block contains a floor tile, an (optional) item, and an (optional) stone.

A frame of stones is drawn around the newly created landscape with the `draw_border` command. Its argument, `"st-brownie"`, is the name of a stone. By convention, all stones have `"st-"` prefixed to their name, similarly all item names begin with `"it-"` and all floor names with `"fl-"`.

The `fill_floor` command in line 3 fills the complete floor with tiles of type `"fl-hay"`. The other arguments are the upper left corner and the width and height of the rectangle to be filled.

     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})

Lines 5 to 7 demonstrate how to create individual stones. The `set_stone` command takes a stone name, the desired coordinates, and an (optional) list of attributes as arguments. Note the use of curly braces `{`, `}` to enclose the attribute list.

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 "blowing off" 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 "trigger" message every ten seconds to the object named "fart".

     9   oxyd(3,3)
    10   oxyd(level_width-4,level_height-4)
    11   oxyd(level_width-4, 3)
    12   oxyd(3,level_height-4)
    13   oxyd_shuffle()

These commands place a couple of oxyd stones in the level. The `oxyd` command internally uses `set_stone("st-oxyd", x,y, ...)` to create the stones, but it additionally assigns sensible values to some of the oxyd stones' attributes (most notably the color). The command on line 14 permutes the colors on the oxyd stones currently in the landscape.

    15   set_actor("ac-blackball", 10,6.5)

This final line creates the black marble controlled by the player. Objects that can move around freely are called "actors" in Enigma. Unlike stones and items, actors are not restricted to integer coordinates, as you can see in this example.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 1.3 Registering Levels

After writing the level description you have to tell Enigma where to find your brand new landscape. That's really two separate steps:

1. Move the ``.lua`'-File where Enigma can find it;
2. Insert a new entry into the appropriate level index.

The ``.lua`'-Files and the corresponding level index usually reside in the same directory. For the levels that come with Enigma, for example, this is the ``levels`' directory inside. For your own levels you can either use the same directory (currently your only choice if you use the Windows version of Enigma) or the ``.enigma/levels`' directory in your home folder (only if you use the Unix version).

A level index is a file that contains the list of landscapes that comprise a level pack in Enigma. Here is an excerpt from ``index_enigma.txt`', which defines the "Enigma" level pack:

    {file=welcome              name="Welcome"                        author="Daniel Heck"         }
    {file=martin06             name="Is It Easy?"                    author="Martin Hawlisch"     }
    {file=lasers101            name="Lasers 101"                     author="Daniel Heck"         }
    {file=level3a              name="Feel Your Way"                  author="Siegfried Fennig"    }
    {file=martin04             name="Sokoban Revival"                author="Martin Hawlisch"     }

Every line in this file describes one landscape in the level pack. The general format of these lines is

    { tag1=content1 tag2=content2 ... }

One line normally contains many different `tag=content` pairs.

If your content contains spaces, surround the content with quotes (e.g. `name="Is It Easy?"`). If you want the string to contain quotes, escape them with `\` (e.g. `author = "Petr \"ant\" Machata"`).

Here's a description of all supported tags:

`file`
  Defines the file name of the level (excluding the ``.lua`' extension). This entry is mandatory!

`name`
  Defines the full name of the level. This is the name the player will see in the level menu. You can leave this field empty if you prefer to leave your level unnamed.

`author`
  Defines the name of the autor. It will be displayed together with the full name at level startup.

`revision`
  Defines the revision number of the level (defaults to 1) When the revision number is increased, a small red ! appears in the level menu.

  If you do changes to the level that affect the way the level is solved, you should increase the revision number. If you only did cosmetic changes, you should NOT increase the revision.

  You should never decrease the revision number!

`easymode`
  Set this to 1 when the level supports different difficulties.

`par_time`
  Syntax: `par_time=sec,name`

  `sec` is the par time for the level in seconds.

  `name` is the player who did the par.

  If easymode is 1 then `par_time_easy` and/or `par_time_normal` have to be used instead of `par_time`.

When Enigma starts up it automatically tries to load an index file called ``index_user.txt`', where you can store all your personal levels. This file is not included in Enigma distributions, you have to create it yourself. The levels listed in this file will show up in a new level pack called "User Levels".

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 1.4 Where to go from here

The example level from the first section of this chapter was hopefully enough to give you an impression how level descriptions look like in Enigma. Of course, that level was extremely simple, and most interesting levels will be more complicated. The rest of this reference manual tries to document the available game objects and how to interact with the Enigma game engine, both when preparing the level (before the game starts) and during the game.

This manual only describes the low-level interface to Enigma's game engine, which is as flexible as it is inconvenient to use by hand. Petr Machata has written a comprehensive set of helper routines that greatly simplify the creation of new levels. You can use the package by including the line `Require("levels/ant.lua")` in your level descriptions. There is extensive documentation for ``ant.lua`' in file ``ant_lua.txt`' in the documentation directory.

Before you read on, please be aware that this manual is far from complete. We are working on it and it will be ready for the (glorious) 1.0 release. For the moment, the available level descriptions are the best "documentation" available.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

# 2. XML levels

Enigma is slowly moving towards a more data-centric level description format. Although the current use of small Lua scripts for this purpose makes it possible to create levels with sophisticated dynamic behavior, it is difficult to create large, complex levels by hand and even more difficult to write graphical tools that help level designers with this task. The purpose of the XML-based levle format for Enigma is to provide an extensible basis for automated processing of Enigma levels, while retaining the full expressive power of the Lua scripting language where necessary or desirable.

The general outline of an XML-style Enigma level looks like this:

    <level width="20" height="13">
      <info>
         <!-- level information -->
      </info>
      <option ... />
      <actors>
         <!-- actor definitions -->
      </actors>
      <floors>
         <!-- floor definition -->
      </floors>
      <items>
         <!-- item definition -->
      </items>
      <stones>
         <!-- stone definition -->
      </stones>
      <rubberbands>
         <!-- rubberband definition -->
      </rubberbands>
      <signals>
         <!-- signal definition -->
      </signals>
      <lua>
         <!-- optional Lua code -->
      </lua>
    </level>

If you are unfamiliar with XML, here are a few general notes:

- XML is a standard for representing hierarchical documents. An XML document consists of a number of arbitrarily nested segments delimited by opening tags like `<level>` and closing tags `</level>`.

- Tags can have arguments, as shown above for the `level` tag. Arguments have the form `name="value"`; note that the value must be enclosed in quotation marks.

- The empty tag `<option ... />` is an abbreviation for `<option ...></option>`.

- Comments can be written like this `<!-- blabla -->`.

An Enigma level must begin with `<level width="xx" height="yy">`, where `xx` and `yy` are width and height of the level, and ends with `</level>` The following sections of this manual describe the structure of the remaining parts of a level description, in the order indicated in the above example.

2.1 Meta information |  |
2.2 Level options |  |
2.3 Actors |  |
2.4 Objects |  |
2.5 Signals |  |
2.6 Rubberbands |  |
2.7 Embedded Lua code |  |

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 2.1 Meta information

Every level should begin with a short block containing general information about the level. This can include the level name, its author and license restrictions. If you intend your level(s) to be distributed with Enigma, the following four fields are mandatory:

    <info>
      <name>LEVEL NAME</name>
      <author>AUTHOR NAME</author>
      <copyright>COPYRIGHT NOTICE</copyright>
      <license>LICENSE TERMS</license>
    </info>

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 2.2 Level options

Certain aspects of the game can be customized by changing the values of the options to be described in this section. Some of these options control general aspects, like constant force fields or whether the level automatically restarts when the marble gets destroyed, while other options provide default values for objects in the level, like the strength of magnetic fields or the look of Oxyd stones.

The following example shows the general syntax for options. Note the use of empty tags: the salient information is already contained in the attributes name and value. Boolean options are always encoded as "YES" or "NO".

    <option name="shuffle" value="NO" />

Here is the table of all options available so far:

`shuffle`
  Shuffle the colors of the Oxyd stones after before starting the game? "YES"/"NO".

`oxydflavor`
  The look of Oxyd stones; "a"/"b"/"c"/"d". See 3.3.14 st-oxyd: Oxyd Stones for details.

`reset`
  Reset the level when the player dies? "YES"/"NO"

`scrolling`
  An integer between 1 and 4 (inclusive). Determines how the screen follows the currently active ball. 1: scroll the screen, 2: flip the screen, 3: scroll but align to screens, 4: keep marble at center.
``

In addition, there are a few numeric options that determine the behavior of certain comon objects. These correspond to the variables desribed later in the document, see 4. Variables for details.

`brittleness`
`slopeforce`
`flatforce`
`frictionfactor`
`electricforce`
`bumperforce`
`magnetforce`
`magnetrange`
`wormholeforce`
`wormholerange`
`holeforce`

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 2.3 Actors

Syntax:

    <actors>
      <actor kind=@"ac-blackball@" x=@"10.5@" y=@"5.5@" />
    </actors>

    <actors difficulty=@"hard@">
      <actor kind=@"ac-killerball" x=@"3@" y=@"4@" attribs=@"controllers=3@" />
    </actors>

    <actors difficulty=@"easy@">
      <actor kind=@"ac-killerball" x=@"3@" y=@"4@" attribs=@"controllers=0@" />
    </actors>

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 2.4 Objects

The description of floor tiles, items, and stones in the XML level file is very similar, so we treat them here in one section. The general syntax looks like this:

    <floors>
      <row y=@"yy@"> ... </row>
      <floor kind=@"name@" x=@"xx@" y=@"yy@" attribs=@"attriblist@" />
    </floor>

For items and stones, the XML tags are called `<items>` and `<stones>` respectively. As for the actor sections, you can optionally include a `difficulty=` option to place certain objects only in the specified difficulty level.

The `<row>` tag can be used to draw complete rows of objects to the screen. An example looks like this:

    <floors>
      <row y=@"10@">abyss 10 water # abyss 10 </row>
    </floors>

This must be read as follows: In the tenth row, put one `fl-abyss` (not that the prefix is not included in the level file!), repeat it ten more times (so it's elevel abyss tiles), put one water tile, repeat it once, and then finish with another eleven abysses.

Here's another, more advanced, example for a row of items:

    <items>
      <row y=@"10@">-10 hammer - - blackbomb - # -5 3</row>
    </items>

Read this as follows: skip 10 fields, put one hammer, skip two fields (you could also write `-2` instead), put one black bomb, skip one field, put another black bomb, skip five fields, and finish with three more black bombs.

In general there can be five different kinds of entries in such a row description, all of them separated by spaces:

name
  Put one object of the specified type at the current position, remember the object name;
`#`
  Repeat the last named object
positive number
  Repeat the last named object the specified number of times
`-`
  Skip one field
negative number
  Skip the specified number of fields

You cannot specify object attributes using `<row>` tags, to do this you must place objects individually, using either `<floor ... />`, `<item ... />`, or `<stone ... />`, for example

    <stones>
      ...
      <stone kind=@"st-switch@" x=@"2@" y=@"2@" attribs=@"action='openclose', target='door1'@" />
      ...
    </stones>

The attribute list looks like the one in Lua would, except for the enclosing braces `{}` that must be omitted in the XML level format. Please note that you must in this case use single quotes `'` to enclose string attributes, double quotes would terminate the XML argument. Enigma's current XML parser unfortunately does not yet understand character entities like `&quot;`, this will hopefully be fixed in future versions.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 2.5 Signals

[To be written]

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 2.6 Rubberbands

Syntax:

    <rubberbands>
      <rubberband from=@"objname@" to=@"objname@" strength=@"12@" length=@"5@" minlen=@"0@" />
    </rubberbands>

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 2.7 Embedded Lua code

To make XML levels every bit as expressive as the former level format, a special `<lua>` tag is available to carry arbitrary Lua code. Only one such tag per level is allowed, and the code it contains is executed after all other tags have been processed, immediately before handing the level over to the game engine.

Lua code blocks can be used for everything that can not be realized with the data-centric XML format, like specially crafted signal handlers, randomly generated levels or puzzles, or to access features of Enigma's game engine that are not otherwise available.

Graphical level editors are expected not to tamper with the contents of Lua code blocks when they read or write Enigma levels, i.e., neither to modify them nor to delete them without notice.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

# 3. Objects

3.1 Floors |  |
3.2 Items |  |
3.3 Stones |  |
3.4 Actors |  |
3.5 General object attributes |  |

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 3.1 Floors

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 3.1.1 Special floor tiles

    fl-abyss
    fl-acblack
    fl-acwhite
    fl-bridge( type )
    fl-bridge-closed( type )
    fl-bridge-open( type )
    fl-gradient( type )
    fl-gradient{1..16}
    fl-springboard
    fl-swamp
    fl-water

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 3.1.2 Regular floor tiles

    fl-abyss_fake
    fl-black
    fl-bluegray
    fl-bluegreen
    fl-bluegreenx
    fl-brick
    fl-bumps
    fl-concrete
    fl-darkgray
    fl-dummy
    fl-dunes
    fl-floor_001
    fl-gravel
    fl-gray
    fl-hay
    fl-himalaya
    fl-ice
    fl-ice_001
    fl-inverse
    fl-inverse2
    fl-leaves
    fl-leavesb
    fl-leavesc{1..4}
    fl-leavesd{1..4}
    fl-leavese{1..4}
    fl-light
    fl-lightgray
    fl-marble
    fl-metal
    fl-metal{1..6}
    fl-mortar
    fl-normal
    fl-normal_x
    fl-plank
    fl-red
    fl-rock
    fl-rough
    fl-rough-blue
    fl-rough-red
    fl-rough_medium
    fl-rough_slow
    fl-sahara
    fl-samba
    fl-samba1
    fl-samba2
    fl-sand
    fl-space
    fl-space-force
    fl-stone
    fl-stwood
    fl-stwood1
    fl-stwood2
    fl-tigris
    fl-trigger
    fl-white
    fl-wood
    fl-woven

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 3.2 Items

3.2.1 Item List |  | A complete list of all items
3.2.2 it-document: Scrolls of Paper |  | Scrolls of Paper
3.2.3 it-floppy: Floppy Disk |  | Floppy Disk
3.2.4 it-hollow: Hollows in the floor |  | Pits in the floor
3.2.5 it-ring: Ring |  | Ring
3.2.6 it-vortex: Vortex |  | Vortices for Teleporting

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 3.2.1 Item List

    it-1pkillstone
    it-2pkillstone
    it-abyss
    it-bag
    it-banana
    it-blackbomb
    it-blackbomb_burning
    it-blocker
    it-blocker-new
    it-booze
    it-brake
    it-bridge-oxyd
    it-bridge-oxyd_active
    it-brush
    it-burnable
    it-burnable_ash
    it-burnable_burning
    it-burnable_fireproof
    it-burnable_ignited
    it-changefloor
    it-cherry
    it-coffee
    it-coin1( value )
    it-coin2( value )
    it-coin4( value )
    it-crack{0..3} ( type fixed brittleness )
    it-cross
    it-debris
    it-document( text )
    it-drop
    it-dummy
    it-dynamite
    it-easykeepstone
    it-easykillstone
    it-explosion1
    it-explosion2
    it-explosion3
    it-extinguisher( load )
    it-extinguisher_empty( load )
    it-extinguisher_medium( load )
    it-extralife
    it-flagblack
    it-flagwhite
    it-floppy
    it-glasses
    it-glasses-broken
    it-hammer
    it-hill
    it-hollow
    it-hstrip
    it-inversesensor
    it-key( keycode )
    it-key_a
    it-key_b
    it-key_c
    it-landmine
    it-magicwand
    it-magnet( on strength range )
    it-magnet-off( on strength range )
    it-magnet-on( on strength range )
    it-odometer
    it-oxyd5f
    it-pencil
    it-pin
    it-pipe-e
    it-pipe-es
    it-pipe-h
    it-pipe-n
    it-pipe-ne
    it-pipe-s
    it-pipe-sw
    it-pipe-v
    it-pipe-w
    it-pipe-wn
    it-puller-e
    it-puller-n
    it-puller-s
    it-puller-w
    it-ring
    it-rubberband( object1 object2 length strength )
    it-seed
    it-seed_nowood
    it-seed_volcano
    it-sensor
    it-shogun-l
    it-shogun-m
    it-shogun-s
    it-signalfilter0
    it-signalfilter1
    it-spade
    it-spoon
    it-spring1
    it-spring2
    it-springboard
    it-squashed
    it-surprise
    it-sword
    it-tinyhill
    it-tinyhollow
    it-trigger( invisible )
    it-umbrella
    it-vortex-closed( autoclose targetx targety )
    it-vortex-open( autoclose targetx targety )
    it-vstrip
    it-weight
    it-whitebomb
    it-wormhole( on targetx targety strength range )
    it-wormhole-off( on targetx targety strength range )
    it-wrench
    it-yinyang

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 3.2.2 it-document: Scrolls of Paper

This item looks like a piece of paper and contains text messages that can be displayed by activating the item.

Attributes

`text`
  The message to be displayed.

Example

    set_item("it-document", 1,1, {text="Hello World!"})
    Document(1,1, "Hello World")

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 3.2.3 it-floppy: Floppy Disk

The floppy disk is needed to activate the Floppy switch (see 3.3.9 st-floppy: Floppy Switch).

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 3.2.4 it-hollow: Hollows in the floor

This item creates a hollow in the floor. If all existing @xref{ac-whiteball-small} are inside hollows the level succeeds.

Attributes

`essential`
  Whether the hollow must be filled with a whiteball to end the level (1 means 'yes').

  Use this attribute if there are more holes than small whiteballs in a level and you want to determine which of the holes are needed to finish the level.

  For example: If you have many holes and 3 whiteballs, then set `essential=1` in 3 holes. The game will end when the 3 whiteballs are inside the 3 marked holes.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 3.2.5 it-ring: Ring

When a player drops this item, the marble is teleported. The destination depends on the game mode:

Single player levels:
  The marble is transported to its starting position or to the position of the last dropped @xref{it-flag}.

Multi player levels:
  Both marbles exchange their positions.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 3.2.6 it-vortex: Vortex

Vortices, like wormholes, can be used to teleport marbles. In the simplest case, every vortex is connected to exactly one other vortex. If there are multiple target vortices, the marble will be teleported to the first unblocked target site. Many levels in the original Oxyd games required the player to selectively block vortices to gain access to new parts of the level.

Example

This example creates three vortices. If the second vortex is blocked, a marble falling into the first one is transported to (20,1).

    set_item ("it-vortex", 1, 1)
    set_item ("it-vortex", 10,1)
    set_item ("it-vortex", 20,1)
    Signal ("it(1 1)", "it(10 1)")
    Signal ("it(1 1)", "it(20 1)")
    Signal ("it(10 1)", "it(1 1)")
    Signal ("it(20 1)", "it(1 1)")

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 3.3 Stones

3.3.1 Stone List |  | A complete list of all stones
3.3.2 st-actorimpulse: Bumper Stones |  | Bumper Stones
3.3.3 st-chameleon: Chameleon Stone |  | Chameleon Stone
3.3.4 st-coinslot |  | Coin Slot Switch
3.3.5 st-death: Skull Stones |  | Skull Stones
3.3.6 st-disco: Disco Stones |  | Disco Stones
3.3.7 st-easymode: Easy Mode Stone |  | Easy Mode Stone
3.3.8 st-fart: Fart Stone |  | The Infamous Fart Stones
3.3.9 st-floppy: Floppy Switch |  | Floppy Switch
3.3.10 st-grate: Grates |  | Various Grates
3.3.11 st-laserswitch: Laser Switch |  | Laser Switch
3.3.12 st-lasertimeswitch: Laser Time Switch |  | Laser Time Switch
3.3.13 st-oneway: One-way Stones |  | One-way Stones
3.3.14 st-oxyd: Oxyd Stones |  | The Famous Oxyd Stones
3.3.15 st-rubberband: Rubberband Stone |  | Rubberband Stone
3.3.16 st-scissors: Scissors Stone |  | Scissors Stone
3.3.17 st-stone_break: Breakable Stone |  | Breakable Stone
3.3.18 st-swap: Swap Stone |  | Swap Stones
3.3.19 st-switch: Switches |  | Ordinary Switches
3.3.20 st-thief: Thief Stone |  | Thiefs
3.3.21 st-timer: Timer Stone |  | Timers
3.3.22 st-timeswitch: Time Switch |  | Time Switch
3.3.23 st-window: Breakable Stone |  | Breakable Window
3.3.24 st-wood: Wooden Stone |  | Wooden Stones
3.3.25 st-yinyang: Yin-Yang Stones |  | Yin-Yang Stones

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 3.3.1 Stone List

Simple stones

The following stone types are commonly used for "decoration". They generally do not have special properties or abilities. Three types of abbreviations are used in the tables: `[abc]` stands for any of the characters in square brackets, `<abc>` stands for any subsequence of the characters between the angle brackets (in this case abc, ab, bc, a, b, c), and `{1..9}` indicates a sequence of numbers.

    st-beads
    st-bigbrick-<nesw>
    st-blue-sand
    st-bluegray
    st-bluegray_hole
    st-brick
    st-brownie
    st-bumps
    st-dummy
    st-fakeoxyd( blinking )
    st-fakeoxyda
    st-glass
    st-glass[123]
    st-glass[12]_hole
    st-glass1_move
    st-glass_move
    st-grate{1..3}
    st-greenbrown
    st-greenbrown_hole
    st-greenbrown_move
    st-likeoxyd[abcd]
    st-likeoxyd[abcd]-open
    st-marble
    st-marble_hole
    st-marble_move
    st-metal
    st-plain
    st-plain_hole
    st-plain_move
    st-rock{1..8}
    st-rock[123]_hole
    st-rock[13]_move
    st-stone[12]
    st-wood[12]
    st-wood_001
    st-woven
    st-yellow

Special stones

The following stones types are special in the sense that they perform some action, either when hit by an actor, or all by themselves.

    st-3mirror( transparent movable orientation )
    st-actorimpulse
    st-actorimpulse_invisible
    st-black{1..4}
    st-blackballs
    st-block
    st-blocker
    st-blocker-growing
    st-bolder-[ensw]
    st-bombs
    st-brake
    st-break_acblack
    st-break_acwhite
    st-break_bolder
    st-break_gray
    st-break_invisible
    st-breaking
    st-brick_magic
    st-bug
    st-chameleon
    st-chargeminus( charge )
    st-chargeplus( charge )
    st-chargezero( charge )
    st-coffee
    st-coinslot( on )
    st-death
    st-death_invisible
    st-disco-dark
    st-disco-light
    st-disco-medium
    st-door( type )
    st-door-h( type )
    st-door-h-open( type )
    st-door-v( type )
    st-door-v-open( type )
    st-door_[abc]
    st-easymode
    st-explosion
    st-fart
    st-flash
    st-floppy( on )
    st-fourswitch( on )
    st-greenbrown-growing
    st-invisible
    st-invisible_magic
    st-key( on keycode )
    st-key_[abc] ( on keycode )
    st-knight
    st-laser-[ensw]( on )
    st-laserbreak
    st-laserswitch
    st-lasertimeswitch( delay )
    st-magic
    st-mail-[ensw]
    st-mirror-3<
    st-mirror-3<m
    st-mirror-3<t
    st-mirror-3<tm
    st-mirror-3>
    st-mirror-3>m
    st-mirror-3>t
    st-mirror-3>tm
    st-mirror-3^
    st-mirror-3^m
    st-mirror-3^t
    st-mirror-3^tm
    st-mirror-3v
    st-mirror-3vm
    st-mirror-3vt
    st-mirror-3vtm
    st-mirror-p-
    st-mirror-p-m
    st-mirror-p-t
    st-mirror-p-tm
    st-mirror-p/
    st-mirror-p/m
    st-mirror-p/t
    st-mirror-p/tm
    st-mirror-p\
    st-mirror-p\m
    st-mirror-p\t
    st-mirror-p\tm
    st-mirror-p|
    st-mirror-p|m
    st-mirror-p|t
    st-mirror-p|tm
    st-oneway-[nesw]
    st-oneway_black-[nesw]
    st-oneway_white-[nesw]
    st-oxyd( flavor color )
    st-oxyd-0x18
    st-peroxyd-0xb8
    st-peroxyd-0xb9
    st-plain_break
    st-plain_breaking
    st-plain_cracked
    st-plain_falling
    st-pmirror( transparent movable orientation )
    st-pull
    st-puzzle-hollow( oxyd )
    st-puzzle-<nesw>( oxyd )
    st-puzzle2-hollow( oxyd )
    st-puzzle2-<nesw>( oxyd )
    st-rock3_break
    st-rock3_movebreak
    st-rotator-left
    st-rotator-right
    st-rotator_move-left
    st-rotator_move-right
    st-rubberband( length strength )
    st-scissors
    st-shogun-<sml>
    st-spitter
    st-stone_break
    st-stonebrush
    st-stoneimpulse
    st-stoneimpulse-hollow
    st-stoneimpulse_movable
    st-surprise
    st-swap
    st-switch( on )
    st-switch_black( on )
    st-switch_white( on )
    st-thief
    st-timer( on interval loop invisible )
    st-timeswitch( delay )
    st-turnstile
    st-turnstile-green
    st-turnstile-[ensw]
    st-volcano
    st-volcano-growing
    st-volcano_active
    st-volcano_inactive
    st-white{1..4}
    st-whiteballs
    st-window
    st-wood
    st-wood-growing
    st-yinyang{1..3}

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 3.3.2 st-actorimpulse: Bumper Stones

These stones apply an impulse to actors that touch them. The amount of force applied can be controlled by setting @xref{enigma.BumperForce} accordingly (the default is 800). Alternatively, the `force` attribute can be used to set this factor for individual bumper stones.

The invisible variant, @xref{st-actorimpulse_invisible} can "painted" with a @xref{it-brush}.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 3.3.3 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...

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 3.3.4 st-coinslot

A switch that can be activated with coins. The more coins you put in, the longer the switch will stay activated.

Attributes

`target, action`
  As usual

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 3.3.5 st-death: Skull Stones

Simply kills all marbles that touch it (except when protected by an umbrella).

Variants

`st-death`
`st-death_invisible`

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 3.3.6 st-disco: Disco Stones

Darkens everything that is underneath the stone (much like tinted glass). Can be switched on and off (hence the name).

Messages

`signal`
  With parameter 1, lighten the stone and (recursively) all neighboring disco stones; with parameter smaller than 1, darken them.
`lighten`
`darken`

Variants

`st-disco-light`
`st-disco-medium`
`st-disco-dark`

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 3.3.7 st-easymode: Easy Mode Stone

In easy game mode this stone converts the floor at its position to `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.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 3.3.8 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.

Messages

`trigger`
  blow off

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 3.3.9 st-floppy: Floppy Switch

A switch that is activated by inserting a floppy disk (see 3.2.3 it-floppy: Floppy Disk).

Attributes

`on`
  1 or 0
`target`
`action`

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 3.3.10 st-grate: Grates

Floating grates, mainly decorative. Flying objects (jumping marbles, rotors, etc.) cannot pass, objects moving on the floor can.

Variants

`st-grate1`
`st-grate2`
`st-grate3`

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 3.3.11 st-laserswitch: Laser Switch

This switch is `on` while hit by a laserbeam and `off` when not hit by a laserbeam.

See also 3.3.12 st-lasertimeswitch: Laser Time Switch.

Attributes

`inverse=1`
  Inverts the on/off state of the switch (i.e `on` at startup and switch `off` with laserbeam)
`target,action`
  as usual

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 3.3.12 st-lasertimeswitch: Laser Time Switch

This switch is a mix between 3.3.11 st-laserswitch: Laser Switch and 3.3.22 st-timeswitch: Time Switch.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 3.3.13 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 can't be entered. Hard to explain, try it yourself :-)

There are three different variants of the one-way stone: the standard one, `st-oneway`, which both the black and the white marble can pass, and two colored ones, `st-oneway_black` and `st-oneway_white`, which completely block marbles of the other color.

Variants

`st-oneway`
`st-oneway-[nesw]`
`st-oneway_black`
`st-oneway_black-[nesw]`
`st-oneway_white`
`st-oneway_white-[nesw]`

Attributes

`orientation`
  One of `NORTH`, `EAST`, `SOUTH`, or `WEST`. This determines the orientation of the stone when the level is loaded. You need to use the `direction` message for changing the orientation during the game. Note that it is usually easier to use one of the alternative names, like `st-oneway-north` instead of explicitly setting this attribute.

Messages

`direction`
  Set the direction of the arrow during the game. Simply setting the attribute `orientation` is not enough, since this does not update the stone's model on the screen.
`signal`
`flip`
  Both these messages flip the direction of the arrow.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 3.3.14 st-oxyd: Oxyd Stones

Oxyd stones are characterized by two attributes: Their flavor and their color. The `flavor` only affects the visual representation of the stone; it can be either `a' (opening like a flower), `b' (displaying a fade-in animation), `c', or `d'. The `color` attribute determines the color on the oxyd stone.

Note: You should rarely need to create Oxyd stones manually with `set_stone()`. Use the predefined `oxyd()` function instead. It will automatically take care of creating two Oxyd stones of every color.

Attributes

`flavor`
  `a', `b', `c', or `d'
`color`
  a number between 0 and 7

Messages

`closeall`
  Close all oxyd stones
`shuffle`
  Interchange the colors of the oxyd stones in the current landscape. Use the `oxyd_shuffle()` function.
`trigger`
  Open the stone (useful for opening Oxyd stones using switches)

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 3.3.15 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.

Attributes

`length`
  The natural length of the rubberband (default: 1)
`strength`
  The strength of the rubberband (default: 10)

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 3.3.16 st-scissors: Scissors Stone

This stone cuts all rubber bands attached to an actor that touches it.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 3.3.17 st-stone_break: Breakable Stone

This stone can be destroyed by an actor having a hammer and by laser, dynamite, bombs and bombstones.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 3.3.18 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.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 3.3.19 st-switch: Switches

A simple switch.

Variants

`st-switch`
  All kinds of objects can activate this switch
`st-switch_black`
  Only black marbles can activate this switch
`st-switch_white`
  Only white marbles can activate this switch

Attributes

`on`
  1 (activate) or 0 (inactive)
`target, action`
  as usual

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 3.3.20 st-thief: Thief Stone

Takes one item from inventory after when hit by the player's marble. Umbrellas protect against thievery.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 3.3.21 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.

Attributes

`on`
  1 if the timer is running
`interval`
  number of seconds before `action` is performed
`loop`
  if 1, restart the timer after performing `action`
`action`
  as usual
`target`
  as usual
`invisible`
  if 1, stone is invisible

Messages

`on`
`off`
`onoff`

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})

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 3.3.22 st-timeswitch: Time Switch

When this switch is touched by an actor, it switches `on` for 1.8 seconds and then switches `off` again.

See also 3.3.12 st-lasertimeswitch: Laser Time Switch.

Attributes

`delay`
  The delay in seconds after which the switch goes `off`.
`inverse=1`
  Inverts the on/off state of the switch.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 3.3.23 st-window: Breakable Stone

Hit this window heavily with your marble to blast it into smithereens.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 3.3.24 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 `st-wood` which may be specified by using `st-wood1` or `st-wood2`.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 3.3.25 st-yinyang: Yin-Yang Stones

Yin-Yang stones change into @xref{st-white} or @xref{st-black} if you touch them.

There are several flavors of this stone:

`st-yinyang1`
  If touched it changes it's color to the opposite color of your marble.
`st-yinyang2`
  If touched it changes it's color to the same color as your marble.
`st-yinyang3`
  The Per.Oxyd compatible: You must hold @xref{it-magicwand} or @xref{it-brush} to change the color to the opposite color of your marble.

Actors get stuck inside the Yin-Yang Stone if they are starting there or when they warp there. They can be freed by changing the color of the Yin-Yang Stone to their color.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 3.4 Actors

Movable objects are called "actors" in Enigma. The commonest actor is, of course, the black marble, but there are others, including the white marble, the killerball and a few more:

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 3.4.1 ac-blackball

mouseforce (default 1.0) color (default 0.0) blackball (default 1) player (default 0) controllers (default 1)

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 3.4.2 ac-whiteball

mouseforce (default 1.0) color (default 1.0) whiteball (default 1) player (default 1) controllers (default 2)

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 3.4.3 ac-whiteball_small

mouseforce (default 1.0) color (default 1.0) whiteball (default 1) controllers (default 3)

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 3.4.4 ac-killerball

mouseforce (default 2.0) color (default 1.0) whiteball (default 1) controllers (default 3)

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 3.4.5 ac-rotor

range (default 5.0) force (default 10.0) gohome (default 1)

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 3.4.6 ac-top

range (default 5.0) force (default 10.0) gohome (default 1)

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 3.4.7 ac-bug

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 3.4.8 ac-horse

force (default 10.0) target1 target2 target3 target4

3.4.9 Actor Attributes |  |

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 3.4.9 Actor Attributes

All actors share a set of common attributes that determine their general behaviour:

`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.

`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).

`controllers`
  Determines which players may move this actor: 1=Player 1, 2=Player 2, 3=both. By default, `ac-blackball`, `ac-whiteball` and `ac-whiteball-small` have their `controllers` attribute set to 1,2, and 3 respectively.

`essential`
  A non-zero value marks this actor as essential. If `essential=1`, the game restarts if `1` of all essential actors can't resurrect (analog for higher values). If you set the attribute for several actors, you should use the same value for all of them!

`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 do not use them.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 3.5 General object attributes

`name`
  All objects may be given a `name` attribute. Such named objects can be searched using 5.4 enigma.GetNamedObject.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

# 4. Variables

This chapter describes the a few variables that can be changed from level descriptions to alter the behavior of the game engine or set default attributes for some particular objects. In the latter case, the same effect can usually be achieved by setting the corresponding object attributes directly, but being able to specify a global default value it is often more convenient. You can always override these default attribute values for specific objects by setting the appropriate object attributes.

Variable: enigma.ConserveLevel
  `TRUE` or `FALSE`. If `FALSE`, reload the level whenever the an actor that is controlled by a player (i.e., one that has the `player` attribute set) dies. Often used in meditation landscapes or landscapes that are intended to be solved in one go. Default: `TRUE`.

Variable: enigma.ShowMoves
  `TRUE` or `FALSE`. This is only used in the Sokoban level pack to display a move counter in the inventory. Default: `FALSE`.

Variable: enigma.Brittleness
  A value between 0 and 1, denoting the probability that a brittle floor plate desintegrates further when an actor enters or leaves it. 1 means that the floor will always crack, 0 that it is indestructible. Default: 0.5.

Variable: enigma.BumperForce
  The amount of force applied to an actor that hits an `st-actorimpulse` stone. 3.3.2 st-actorimpulse: Bumper Stones. Default: 200.0.

Variable: enigma.ElectricForce
  A force multiplier for all electric forces between actors. Default: 15.0.

Variable: enigma.FrictionFactor
  All friction forces are multiplied by this value. Default: 1.0.

Variable: enigma.FlatForce
  A global downward force. This is currently only applied on floors of type `fl-space`. Default: 0.

Variable: enigma.HoleForce
  A force factor that affects the steepness of hollows and hills. Default: 1.0.

Variable: enigma.MagnetForce
  A force multiplier for magnetic fields. Default: 30.0.

Variable: enigma.MagnetRange
  The range of magnetic fields. Default: 10.0.

Variable: enigma.SlopeForce
  A force multiplier for sloped floor tiles. Default: 25.0.

Variable: enigma.WaterSinkSpeed
  How quickly balls sink in water. Default: 1000.0.

Variable: enigma.SwampSinkSpeed
  How quickly balls sink in swamp. Default: 4.0.

Variable: enigma.WormholeForce
  A force multiplier for wormholes. Default: 30.0.

Variable: enigma.WormholeRange
  The range of worm holes. Default: 10.0.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

# 5. Functions

5.1 AddRubberBand |  | Creating rubber bands
5.2 CreateWorld |  |
5.3 enigma.AddConstantForce |  |
5.4 enigma.GetNamedObject |  |
5.5 SendMessage |  | Sending messages to objects
5.6 draw_checkerboard_floor |  |
5.7 draw_border |  | Drawing a border of stones

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 5.1 AddRubberBand

Function: AddRubberBand (actor, object, strength, length)

  This function connects two objects with a rubber band: The first object is always an actor, the second object can be either another actor or a stone.

  The first argument actor is always a reference to an actor created earlier with the `set_actor` function. The second parameter object may be either an actor or a stone created earlier. The last two parameters define the properties of the rubber band: strength denotes the force factor of the elastic and length its natural length. No force is exerted on the actor if the rubber band is shorter than its natural length.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 5.1.1 Example

    local ac=set_actor("ac-blackball", 1.5,7.5)
    local st=set_stone("st-brownie", 10,6)
    AddRubberBand(ac, st, 50, 10)

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 5.2 CreateWorld

Function: CreateWorld (width, heigth)

  This function creates a new level. Because objects can only be added to the level after `CreateWorld` has been called, you should usually do so near the beginning of your level description.

  The width and height denote the size of the new level. All levels with only one screen have the minimum size of 20x13 blocks.

  Note that level fields are indexed from zero, i.e, the field indices for a 20x13 level are in the range (0..19)x(0..12). Also note that the screens in Enigma overlap by one line or column: A level that fits on a single screen has size of 20x13, but two a level that is two screens wide 39x13 or 20x25, three screens 58x13 or 20x37.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 5.3 enigma.AddConstantForce

Function: enigma.AddConstantForce (gravity_x, gravity_y)

  Adds global gravity to the current level.

  gravity_x
    adds gravity in horizontal direction (positive means rightwards).
  gravity_y
    adds gravity in vertical direction (positive means downwards).

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 5.4 enigma.GetNamedObject

Function: enigma.GetNamedObject (objname)

  This function searches for an object that has a `name` attribute with value objname. It returns a reference to the object or `nil` if none could be found.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 5.4.1 Example

    set_stone("st-wood", 7, 11, {name="woodie"})
    ...
    local Woodie = enigma.GetNamedObject("woodie")

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 5.5 SendMessage

Function: SendMessage (object, message, data)

  This function sends a message to an object.

  object
    The recipient of the message. Can either be the name of an object or a reference as returned by 5.4 enigma.GetNamedObject.
  message
    The message itself (e.g. "signal") You can see which messages are understood in the documentation of the particular 3. Objects.
  data
    Some specific messages expect some additional data (e.g. message "direction" expects a direction like SOUTH or WEST).

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 5.5.1 Examples

    set_stone("st-laser-s", 2, 2, {name="laser3", on=FALSE})
    ...
    SendMessage("laser3", "onoff")

    set_stone("st-bolder", 7, 11, {name="bolder1", direction=SOUTH})
    ...
    SendMessage("bolder1", "direction", WEST)

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 5.6 draw_checkerboard_floor

Function: draw_checkerboard_floor (name1, name2, x, y, w, h, attribs)

  This function draws checkerboard composed of two selected floor types. name1 and name2 are names of floor objects. See @xref{set_floor} for further details.

  name1, name2
    Names of floor objects
  x, y
    Location of left top corner of checkerboard area. Note that upper left map corner is [0,0].
  w, h
    Size of generated checkerboard.
  attribs
    Table of attribute names and corresponding values: `{attrib1=value1, attrib2=value2, ...}`. These attributes, together with default attributes, are passed to each tile of the generated checkerboard.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 5.6.1 Example

    draw_checkerboard_floor("fl-abyss", "fl-rough", 2, 2, 23, 11)
    draw_checkerboard_floor("fl-normal", "fl-inverse", 0, 0, levelw, levelh) -- racetrack

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 5.7 draw_border

Function: draw_border (stonename, x,y, w,h)

  This function adds a border of stones to your level. If invoked with only one argument, this border encloses the whole level.

  stonename
    The name of the border stone.
  x,y
    (optional) Coordinates of upper-left corner. (0,0) if omitted.
  w,h
    (optional) Width and height of border.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 5.7.1 Example

    draw_border("st-marble")
    draw_border("st-greenbrown", 0,5,3,3)

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

# Index

Jump to: | A C D E S

| Index Entry | Section

A |  |
| `AddRubberBand` | 5.1 AddRubberBand

C |  |
| `CreateWorld` | 5.2 CreateWorld

D |  |
| `draw_border` | 5.7 draw_border
| `draw_checkerboard_floor` | 5.6 draw_checkerboard_floor

E |  |
| `enigma.AddConstantForce` | 5.3 enigma.AddConstantForce
| `enigma.Brittleness` | 4. Variables
| `enigma.BumperForce` | 4. Variables
| `enigma.ConserveLevel` | 4. Variables
| `enigma.ElectricForce` | 4. Variables
| `enigma.FlatForce` | 4. Variables
| `enigma.FrictionFactor` | 4. Variables
| `enigma.GetNamedObject` | 5.4 enigma.GetNamedObject
| `enigma.HoleForce` | 4. Variables
| `enigma.MagnetForce` | 4. Variables
| `enigma.MagnetRange` | 4. Variables
| `enigma.ShowMoves` | 4. Variables
| `enigma.SlopeForce` | 4. Variables
| `enigma.SwampSinkSpeed` | 4. Variables
| `enigma.WaterSinkSpeed` | 4. Variables
| `enigma.WormholeForce` | 4. Variables
| `enigma.WormholeRange` | 4. Variables

S |  |
| `SendMessage` | 5.5 SendMessage

Jump to: | A C D E S

[Top] | [Contents] | [Index] | [ ? ]

# Table of Contents

> 1. Introduction

> > 1.1 Creating New Levels
> > 1.2 A Simple Level
> > 1.3 Registering Levels
> > 1.4 Where to go from here

> 2. XML levels

> > 2.1 Meta information
> > 2.2 Level options
> > 2.3 Actors
> > 2.4 Objects
> > 2.5 Signals
> > 2.6 Rubberbands
> > 2.7 Embedded Lua code

> 3. Objects

> > 3.1 Floors

> > > 3.1.1 Special floor tiles
> > > 3.1.2 Regular floor tiles

> > 3.2 Items

> > > 3.2.1 Item List
> > > 3.2.2 it-document: Scrolls of Paper
> > > 3.2.3 it-floppy: Floppy Disk
> > > 3.2.4 it-hollow: Hollows in the floor
> > > 3.2.5 it-ring: Ring
> > > 3.2.6 it-vortex: Vortex

> > 3.3 Stones

> > > 3.3.1 Stone List
> > > 3.3.2 st-actorimpulse: Bumper Stones
> > > 3.3.3 st-chameleon: Chameleon Stone
> > > 3.3.4 st-coinslot
> > > 3.3.5 st-death: Skull Stones
> > > 3.3.6 st-disco: Disco Stones
> > > 3.3.7 st-easymode: Easy Mode Stone
> > > 3.3.8 st-fart: Fart Stone
> > > 3.3.9 st-floppy: Floppy Switch
> > > 3.3.10 st-grate: Grates
> > > 3.3.11 st-laserswitch: Laser Switch
> > > 3.3.12 st-lasertimeswitch: Laser Time Switch
> > > 3.3.13 st-oneway: One-way Stones
> > > 3.3.14 st-oxyd: Oxyd Stones
> > > 3.3.15 st-rubberband: Rubberband Stone
> > > 3.3.16 st-scissors: Scissors Stone
> > > 3.3.17 st-stone_break: Breakable Stone
> > > 3.3.18 st-swap: Swap Stone
> > > 3.3.19 st-switch: Switches
> > > 3.3.20 st-thief: Thief Stone
> > > 3.3.21 st-timer: Timer Stone
> > > 3.3.22 st-timeswitch: Time Switch
> > > 3.3.23 st-window: Breakable Stone
> > > 3.3.24 st-wood: Wooden Stone
> > > 3.3.25 st-yinyang: Yin-Yang Stones

> > 3.4 Actors

> > > 3.4.1 ac-blackball
> > > 3.4.2 ac-whiteball
> > > 3.4.3 ac-whiteball_small
> > > 3.4.4 ac-killerball
> > > 3.4.5 ac-rotor
> > > 3.4.6 ac-top
> > > 3.4.7 ac-bug
> > > 3.4.8 ac-horse
> > > 3.4.9 Actor Attributes

> > 3.5 General object attributes

> 4. Variables
> 5. Functions

> > 5.1 AddRubberBand

> > > 5.1.1 Example

> > 5.2 CreateWorld
> > 5.3 enigma.AddConstantForce
> > 5.4 enigma.GetNamedObject

> > > 5.4.1 Example

> > 5.5 SendMessage

> > > 5.5.1 Examples

> > 5.6 draw_checkerboard_floor

> > > 5.6.1 Example

> > 5.7 draw_border

> > > 5.7.1 Example

> Index

[Top] | [Contents] | [Index] | [ ? ]

# Short Table of Contents

> 1. Introduction
> 2. XML levels
> 3. Objects
> 4. Variables
> 5. Functions
> Index

[Top] | [Contents] | [Index] | [ ? ]

# About this document

This document was generated by using texi2html

The buttons in the navigation panels have the following meaning:

Button | Name | Go to | From 1.2.3 go to
--- | --- | --- | ---
[ < ] | Back | previous section in reading order | 1.2.2
[ > ] | Forward | next section in reading order | 1.2.4
[ << ] | FastBack | previous or up-and-previous section | 1.1
[ Up ] | Up | up section | 1.2
[ >> ] | FastForward | next or up-and-next section | 1.3
[Top] | Top | cover (top) of document |
[Contents] | Contents | table of contents |
[Index] | Index | concept index |
[ ? ] | About | this page |

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:

- 1. Section One
  - 1.1 Subsection One-One
    - ...
  - 1.2 Subsection One-Two
    - 1.2.1 Subsubsection One-Two-One
    - 1.2.2 Subsubsection One-Two-Two
    - 1.2.3 Subsubsection One-Two-Three <== Current Position
    - 1.2.4 Subsubsection One-Two-Four
  - 1.3 Subsection One-Three
    - ...
  - 1.4 Subsection One-Four

This document was generated by by Daniel Heck on , 15 2005 using texi2html