[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 1.00.

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

# 1. Running Enigma

After a hopefully succesfull installation and some first levels you may be interested in some information how Enigma is configured, how you can optimize Enigma to your demands and what some options and attributes within Enigma are for.

This first chapter should give you some valuable information to these questions and provides some basic knowledge you will need to know to manage level packs, levels or write own levels as described in the following chapters.

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

## 1.1 Locating Resources

For reasons of backup, system changes, special configurations, level additions and hopefully own new levels you may need to know where Enigma stores the resources and how you can control them.

Enigma maintains several paths for control of load and storage of files. You can list these paths either by pressing `F2` within the main menu or by starting Enigma with the switch ``--log'` (see section Startup Switches) and looking at the console output.

Preferences Path

  This is the path to the file that stores your preferences concerning application options. This file is usually located at your `HOME` directory. For `HOME`-less Windows users it is stored in the ``Application Data\Enigma'` directory. As it is the third version in the history of Enigma the file is named ``.enigmarc.xml'` by default.

  It is recommended to backup this file, even though it contains only few data that can be quickly reconfigured.

  As these preferences are quite specific for the operating system and configuration you will use a different version on each Enigma installation you have.

  Mainly for Enigma developers exists a switch ``--pref'` (see section Startup Switches) to rename this preferences file. By starting Enigma with a renamed preferences file a developer can temporarily use a complete seperated configuration for testing purposes without the danger of destroying his main configuration. The developer may use it to start Enigma with a plain standard configuration for testing purposes, too.

  In all cases the preferences filename will be hidden by a leading ``.'` in the filename.

User Path

  This is the main path to the users Enigma data. All updates, user installed levels and user written levels, the users scores, history and usually the users screenshots and level previews are stored at this path.

  A backup of this directory is mandatory!

  The standard location is the directory ``.enigma'` at your `HOME` directory. For `HOME`-less Windows users it is the ``Application Data\Enigma'` directory.

  You can define an own path within the User Options. By this means you can store your Enigma user data on a memory stick or you can store them on a shared partition and use them alternatively from two Enigma installations.

User Image Path

  This is a second path to the users Enigma data that is used to access images like screenshots and thumbnails of levels. Usually this path is identical to the main ``User Path'`.

  Just in case you make many screenshots and have limited resources on the main ``User Path'` you may want to store the images on another path. You can define an own path within the User Options.

System Path

  This path gives you the location of all system resources that are distributed with Enigma. Here you will find the levels, libraries, etc. A first class address to look for examples if you start writing own levels.

Resource Paths

  This is a list of paths. Every version independent resource is looked up on all paths in this list and loaded from the first occurence.

  User data preceed system data. This way updates on your user data path will win. Have a look at this list if you are observe difference between a source and the runtime behaviour. You may have looked at a file that was hidden by another on a preceeding path in this list.

l10n Path

  This path shows the directory that contains the localization data.

Please note that some resources like levels may be zipped. In this case a resource that you expect at ``dirname/filename'` may be stored in a zipfile named ``dirname.zip'`. The path of the file within the zip can be either ``dirname/filename'` or ``./filename'`. In case a resource is provided in zipped and unzipped the plain file stored in a directory wins, as it is assumed to be an update to the zip.

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

## 1.2 Startup Switches

Besides starting Enigma by clicking on a installation provided icon or start menu entry you can start enigma from a shell or commandline. With release 1.00 the Windows version supports this feature without restrictions. Even though it is not necessary using this feature to play the distributed levels you may take advantage of this feature in special or advanced usage.

The following list explains the supported user options. If an option is listed with a long name preceeded by two minus signs and with a one character abbreviation preceeded by one minus sign use one of both notations not both together, f.e. ``--data path'` or ``-d path'`.

--assert

  A switch for Enigma developers that forces all debugging assertions, even expensive ones, to be evaluated. The additionally evaluated checks look like ``ASSERT(noAssert || long_lasting_check(), XLevelRuntime, "remark");'`.

--data -d path

  A switch for Enigma developers that allows to add an additional path to the resource paths that preceeds the system path (see section Startup Switches). A developer can test an Enigma compilation without installation by calling it from the shell with the current working directory on the main directory via ``src/Enigma -d ./data'`.

--help -h

  Just list the available startup switches to the output and terminate.

--lang -l lang

  A switch that allows to override any other language preference. The language is given in the common 2 character sequence as ``fr'` for French or ``ru'` for Russian.

--log

  This switch turns on logging of internal information to the standard output. Windows users will find an file called ``stdout.txt'` in the current working directory. The output will f.e. list the paths described in Locating Resources.

--nograb

  A switch for Enigma developers that causes Enigma not to grab the mouse. Levels can hardly be played in this mode, but it makes it possible to debug the application in its core parts.

--nomusic

  Start Enigma without playing backgroud music.

--nosound

  Start Enigma with sounds being switched off.

--pref -p filename

  The name of an alternative preferences file without the leading dot for hidden filenames. This switch is a pure Enigma developer support feature as described in Locating Resources.

--pref -p dirpath

  The path of an alternative directory that contains the standard named preference file ``.enigmarc.xml'`. If no preference file exists or the directory does not yet exist they are created. On creation of the preference file the user data path is set to the given dirpath per default. This allows to store all Enigma user data in a single directory that can be stored anywhere, e.g. on a USB stick. You always need to call Enigma with the above switch to use this new set up. Remember that a path with spaces needs to be quoted.

--version

  Just print the version number to the output and terminate.

--window -w

  Start Enigma in window mode instead of screen mode.

All further arguments supplied on the commandline are taken as level file addresses. You can use absolut or relative addresses to level files stored on your computer. It is also possible to add url's to levels stored in the internet.

A Unix user may start Enigma with the following command:

`enigma --log ~/mylevel.xml http://somewhere.com/netlevel.xml`

A Windows user may start Enimga from the command line (please adjust the Enigma installation path):

`C:\programs\Enigma-1.00\enigma.exe demo_simple.xml`

You will find the levels in a levelpack called ``Startup Levels'` that is by default only visible if you supplied levels on the commandline.

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

## 1.3 User Options

Ratings update

  Please keep this option on the value ``Never'` until release of Enigma 1.00.

User name

  Enter your user name that will be attached to the scores. Please have a look at the Enigma home page for user names already in use and choose a new unique name. It is possible to change the user name at any point of time without loosing any scores.

User path

  This textfield allows you to define an arbitrary directory for your Enigma user data as described in Locating Resources.

  Deletion of the string resets the path to the default.

  The new path is activated on leaving the options menu. Even though all files are stored directly to the new path and files will still be found on the old path you may want to quit Enigma immediatly and first copy/merge the old directory to the new location. This copy of your old data is necessary as with the next start Enigma will locate user data at the new location exclusively.

User image path

  This textfield allows you to define an arbitrary directory for your Enigma user image data as described in Locating Resources.

  Deletion of the string resets the path to the default.

  The new path is activated on leaving the options menu. Even though all files are stored directly to the new path and files will still be found on the old path you may want to quit Enigma immediatly and first copy/merge the old directory to the new location. This copy of your old data is necessary as with the next start Enigma will locate user data at the new location exclusively.

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

## 1.4 Level Info

For every level Enigma manages more data than can be displayed in the level menu. You can view them all with the levelinspector. This special menu can be called from within the level menu by right or control clicking on the level icon.

Besides title and author information is provided concerning a public rating of the level, different score values of interest, details on the level version, the level file location and more. Additionally the levelinspector allows you to enter personal annotations for a level. Any screenshots you made for this level can be directly reviewed from the levelinspector, too.

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

### 1.4.1 Public Ratings

Most levels are rated within five different categories:

- int = Intelligence
- dex = Dexterity
- pat = Patience
- kno = Knowledge of Enigma
- spe = Speed and Speed control

To distinguish the ratings from their everyday-meanings, we use the abbreviations for the ratings. Each of these categories takes values between 1 (easy) and 5 (difficult), except for kno, which can also be 6 (unique mechanism).

Please bear in mind that it's not very simple to hold on to the following definitions in each single of nearly 750 cases, so there might be (will be) derivations from them in single levels.

Intelligence (int)

This is intended to measure the creativity, planning and analytic requirements needed to solve the level. Intelligence is a very difficult notion in itself, and thus at first not easy to rate nor to grasp. Consequently, a fixed definition of the five rating-degrees does not only help in the rating process, but is essential. So, assume you know everything about the single elements of a level. Then ask yourself these questions:

- Can I see the solution at once? Yes -> int 1
- Do I only have to orient myself, like testing the exits of wormholes or see the function of a switch? -> int 2
- Is there a standard algorithm to solve the problem, like in a maze, or searching for a hidden item? -> int 3
- Neither trial-and-error nor standard algorithms work; is it a simple kind of code or advanced planning? -> int 4
- A difficult code, pattern or causal chain? -> int 5

High values for intelligence are typically puzzles. int-ratings do not accumulate; the most difficult puzzle alone already determines the rating.

Dexterity (dex)

There are lots of levels, which can be solved either by accuracy or by patience. In our context, dexterity is not meant in the sense of accuracy to avoid patience, but accuracy to avoid death. So it focuses on the lethal positions in a level, not only death-stones and abysses, but also casualties like pushing a stone accidentally into an unreachable corner.

- It doesn't matter what I touch, this level is damn-proof. -> dex 1
- Well, there are lethal positions I shouldn't move the level into, but they are not difficult to overcome. -> dex 2
- Comparable with a single row with abyss left and right. -> dex 3
- Comparable with pushing a stone to the right while there is abyss on the left, or a single row with death-stones left and right. -> dex 4
- Needs lots of attempts to succeed. -> dex 5

In contrast to the int-rating, dex might accumulate: Many situations, each of dex 3 can add up to dex 4 or even 5. This way dex 5 can be achieved. Rotors in a level contribute as well to dex as to the speed-rating spe. Thus, levels with a high dex-spe-combination are mostly action-driven, whereas a high dex-pat-combination typically is a dangerous maze.

Patience (pat)

Patience is a relatively subjective rating, and refers much to "feeled time". So two levels with same mechanics can have different pat-values, e.g. if one level has a nicer design or shows the progress of the level in some way, like the number of opened oxyds. It explicitly includes having to start the level over and over again; not the time in the lower left corner or the score is crucial, but the complete feeled time needed to solve the level, starting from the first look at it.

- I solved the level right after understanding it. -> pat 1
- I needed some time but is wasn't boring. -> pat 2
- Okay, some minutes. But the landscape is nice .... -> pat 3
- I know what to do, but it doesn't seem to end. -> pat 4
- This level really needs discipline. -> pat 5

A high number of oxyds can as well heighten the pat-value as lower it: If the player has to traverse the level several times to open matching pairs of oxyds, it is definitely pat-heightening. However, if they are arranged to mark the progress of the player, and deal as a kind of small rewards within the level, they can lower the pat-value. The same with a high number of doors: The arrangement is the critical factor.

High pat-values are typically mazes. In combination with int 3, a high pat-value can indicate a hidden item or a hollow stone. pat-values involve the whole level, so they can't accumulate.

Knowledge of Enigma (kno)

The kno-rating mostly takes on the function and interactions of single objects in the game, like stones, floors, items, and actors. However, in some cases it also deals with special techniques. The guide line is the "Advanced Tutorial", which defines kno 3. kno 4 corresponds to standard objects that aren't shown in the tutorial, kno 5 requires a deeper knowledge of the game internals. Finally, kno 6 indicates special mechanisms, that are seldom or unique. The overall kno-rating of a level equals that of the most difficult object or technique (and thus is non-accumulative):

1. Moving a single marble on normal floors, normal walls, oxyds, stones that look like oxyds, death-stones, water, abyss, documents, using the inventory, static gravity, visible gradients.
2. Pushing stones, simple Sokoban-tricks, bridge-building in water and abyss, connected puzzle-stones, moving more than one marble, meditations, grates, rotors and tops, hidden gradients, triggers and switches, doors, holes (not by dynamite), swamp, floppys and st-floppy, keys and locks, coins and slots, cracks, timer-stones.
3. Different floors can have different fraction and mouseforce, space, ice, inverted floor, some stones sink while others swim, black grates that hold rotors and tops away, dynamite, dynamite-breakable stones, spade, bolders, magic-wand to change bolder-direction, bolders sink into abyss, sheafs of glass, spoon, actors and items may hide under movable stones, small not-killer whiteballs, coloured one-way-streets, actorimpulse-stones ("bumpers"), rotors can fly over abyss, fart-stones, swords and knights, lasers, static and movable mirrors, item- and coin-transformations by pushing stones over them and by lasers, umbrellas protect of abyss, hammer and breakable stones (although not in tutorial).
4. Bridge-building in swamps, rubber-bands, rubber-band-stones, scissor-stones, unconnected puzzle-stones, exploding puzzle-stones, turning puzzle-stones (with and without a magic wand), springs (both types, on the floor and hole-kind springs like in "Upstream Journey"), thiefs, three-parted shogun-stones, invisible stones, hollow stones, chameleon-stones, items hidden under chameleon stones, stones that aren't what they seem (e.g. fake-death-stones), wormholes, magnets, using F3 for a restart to solve a level, yin-yangs, one-colour-, yin-yang- and inverted yin-yang-stones, stones breakable by only one colour, killer-balls, swap-stones, brush and paintable stones, changing one-way-streets with a magic wand, making stones to glass with a magic wand, impulse-stones (movable, static and hollow), black and white bombs, bomb-stones, fire, extinguishers, rotator-stones, yellow anti-swapping stones, mines, flags, seeds, weights, putting objects under one-way-streets and other hollow stones, electric stones, turnstiles, mailing and pipes, rings (single and multiplayer), volcanos, bags, randomizers (as possible effect of a switch), horses and horse-passing stones, pins, bananas, cherries make invisible, surprise-item.
5. Cracks, floor-springs, wormholes etc. are all items, seeds can grow inside stones, laser is blocked by all items, killer-balls don't sink in water, "Space Meditation"-kind collisions, holding down the mouse-button, invisibility lets you go through glass, jumping over lasers ....
6. Spitter-stones, surprise-stones, levels like "Enigris" or "Flood Gates" ....

kno 6 does not neccessarily mean that this level is difficult to understand; the unique mechanism or object might as well be very intuitive, like in "Flood Gates".

Speed and speed control (spe)

The spe-value not only corresponds to the maximum speed a level requires (like it's needed to run away from a rotor), but also the degree of control a player has over his mouse while moving it, excellent examples for this are "Mourning Palace" and the middle part of "Sacrifice". This involves moving the mouse with a constant velocity for a long time, as well as correctly estimating the speed that's needed in a certain task, like shattering a sheaf of glass.

1. No time limit.
2. You shouldn't stop for too long. For example, something slow might be chasing you.
3. There is an appropiate time limit or speed control task. This can be a single, not too fast rotor in an open area.
4. Don't stop! Examples are difficult timing-tasks as well as a single fast rotor or several slower ones.
5. Hurry Up! Whereas spe 4 is meant to be difficult, but obviously solvable in not too many attempts, spe 5 is everything above this.

The spe-rating again is cumulative, as many slow rotors can add up to spe 3 or 4 or a combination of many slow time-switches to be pressed in a certain order can make up a horrible task. In contrast to the other categories, for which the average is near 3 (or between 3 and 4 for kno), an overwhelming fraction of all levels are definitely spe 1. So, the spe-rating is more a kind of supplement to the three core-ratings int, dex and pat.

Combinations of ratings

In some cases it can be of interest to have a single value to measure the difficulty of a level. A simple possibility to calculate such a universal rating is to choose a linear combination of the 5 single ratings, weighted with appropriate weights. These weights should correspond to the difficulty a single category adds to the universal difficulty, but these weights also should be carefully chosen to avoid number-theoretic obstructions (e.g. when all weights are even except for the spe-rating, then there will be a visible difference in the distribution of even and odd univeral ratings, which can be very misleading). A working and very interesting linear combination is the following, which has been applied in the reordering process:

    universal difficulty  =  7*int + 6*dex + 4*pat + 3*kno + 4*spe - 23

This has the special property that it takes relatively broadly and continuously distributed values between 1 (all ratings 1) and 100 (all ratings 5, kno 6) and emphasizes the most difficult categories intelligence and dexterity. However, some very small or very high values cannot appear in this combination, like 2 or 99. Other combinations lead to full, but narrow, or to broad but uncontinuous spectra.

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

### 1.4.2 Scores

The score columns show your and some comparison values for the difficult and for the easy mode if the levels supports it.

The world record is the best score that was retransmitted to the enigma team. The holders of the world record are listed below.

The PAR value is the "professional average rating" of the level. It is the harmonic average of all scores that have been retransmitted. But we take only into account scores from players that have solved a certain number of levels. Opposed to the world record that will be very difficult to gain the PAR value is a much more realistic aim for an ambitioned player. Within the level menu levels are marked with a speeding blackball if you are equal or better than PAR.

The authors value is another reference score. Most authors are not keen on holding the world record of their own levels. But they will likley know the fastest way to solve the level. If your score is much higher than the authors score a simpler solution to solve the level may exist.

The solved number is the number of players who solved this level in the given score version.

The solved percentage is the relation of player who solved this level to the number of players who retransmitted scores. Actually we take only those players in account that could have solved the level. F.e. players that did retransmit scores before the level was written without updating afterwards are not taken into account. A low percentage is a hint for a level that is not easy to solve.

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

### 1.4.3 Versions

The version column shows detail information about the level. Read chapter Level Basics node see section <version> and see section <modes> for explanation of the values.

For you as a player the ``Score'` version number can be of some interest. If solve a level with a certain score it may happen that in a updated Enigma release the level appears with a red triangle in the level menu. Even though the level menu displays the medals showing that you solved the level the score values will not be displayed any more. This is due to a incompatible level update that requires a new solution with different incomparable score values. The author will increase the score version number in such a case.

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

### 1.4.4 Privat Annotations and Ratings

The textfield allows you to enter an annotation for a level that you can review on later replays. Note that the current textfield may not allow you to enter all characters and needs the mouse cursor to remain within its boundaries. But it should work for entering short annotations that may be very useful lateron.

Annotations are stored in your private applications ``state.xml'` file. There is one annotation per level independent of the level version.

You may rate the levels, too. Just click on the ratings button. Values go from 0 to 10 with an additional ``-'` for abstention. 0 stands for a poor level that you think is not worth playing, 5 for an average level and 10 for the ultimate best levels. Try to use all values in your ratings.

The ratings are stored together with the scores and will be evaluated annonymously. The resulting average rating of all users is displayed for your information. Note that different ratings are possible for different score versions of the same level. This makes sense as levels may improve on suggestions of users. As long as you do not rerate a new version of a level your rating from a previous version in inherited.

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

### 1.4.5 Screenshots

While playing a level you can make screenshots by pressing `F10`. You can make several screenshots in sequence for documentation purposes. Each will be stored with a unique image filename. With help of the level inspector you can view the screenshots directly from within Enigma. Just click on the screenshot button to view the first image.

As any buttons would disturb the view of a screenshot all functions are keyboard commands. Press `F1` to get a help. `ESC` returns to the level inspector. `Page Up` and `Page Down` will show the previous and next screenshot. If you scroll down behind the last screenshot the "missing" screenshot file is named. This may be a useful hint were to search the other screenshot files on your ``user image path'` (see section Locating Resources).

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

## 1.5 Handicap and PAR

As PAR (see section Scores) describes the difficulty of a level the handicap ``hcp'` describes your ability to solve levels in PAR. The handicap is always related to a levelpack or group of levelpacks. For each levelpack you can see your handicap in the level menu if you select the PAR mode by clicking on the lower left button until the speeding black marble appears. The value is displayed in the upper right corner together with the number of levels you solved in PAR.

The handicap is similar to the golfers handicap. A low value is better than a high value. If you solve all levels exactly in PAR your handicap will be 0. If you are even better than PAR your handicap will be negativ. Players can use this value to compare their overall abilities.

Just for those of you that want to know the details of this score rating system of PAR and handicap some additional information that others may well skip to the next chapter Levelpack Basics.

We request all users to send their scores. All scores are evaluated for world records and counts of level solvage rates and numbers.

But for the PAR calculation we take only scores from users into account that have solved more than a certain rate of levels (currently about 10% of the levels). For every level we calculate the harmonic average of the scores of these ``professionals'`. Professionals that did not solve a level are taken into account with the 10 fold world record score. The harmonic average calculates as

harm.avg. = N / (sum_[j=1..N] 1/score_j) )

It weights small times with a greater weight than large solvage times.

The handicap is a sum of values that describe your scores in relationship to the PAR value of a level. As it has to take into account that you have no score at all or that no PAR value exists some exception rules have to be applied to the addends:

• | + 1.0 | for each unsolved level
• | + log10(score/par) | for each solved level with existing par if score >= par
• | + 0.7 | as upper limit for each solved level with existing par if score >= par
• | + log2(score/par) | for each solved level with existing par if score < par
• | - 3.0 | as lower limit and as value for levels without par

Note that each score that is better than PAR results in a negative addend and thus reduces your handicap. For a levelpack with 100 levels the handicap will be in the range of +100 to -300. For levelpacks with more or less levels the sum will be scaled by a factor 100/size to result in comparable handicap values. Handicaps are stated with one digit behind the decimal point.

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

# 2. Levelpack Basics

Knowing the basics of running Enigma you may wonder how levels are organized in levelpacks and how you can add levels or complete levelpacks to Enigma.

Levelpacks are sorted collections of levels that consist of an index and optional attached level sources. Not all level sources of a levelpack have to be included within the levelpack itself. A levelpack can crossreference levels stored in other levelpacks. If a levelpack has no own level sources and consists only of crossreferences we speak of a crossindex as the levelpack is just represented by a single index file.

These definitions suite well to all versions of Enigma. But up to Enigma 0.92 levelpacks needed to be manually edited and the registration of levelpacks was a little bit cryptic. Thus we decided to rewrite the complete levelpack system for Enigma 1.0 and tried to make it versatile and easy to use. We did set us the following aims:

- an ``Auto'` levelpack that allows level addition by drag and drop of the level source
- levelpack addition by just copying the files to the userpath
- autodetection of all levelpacks without editing any registration files
- commandline supplied levels as a standard levelpack
- a ``History'` levelpack with crossreferences of last played levels
- level search results as a levelpack of crossreferences
- zipped levelpacks that are just archives of levelpack directories and their files
- grouping of levelpacks in the menu
- integrated composer to create and modify new levelpacks
- updates of levelpacks without updating Enigma itself
- automatic convertion of Enigma 0.92 levelpacks

Some of these features work seamlessy. You can use them immediately from the levelpack menu. For others you may need to know where to place files. We will explain these details in the following sections:

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

## 2.1 Getting Started with Levelpacks

One of the outstanding features of Enigma is its extendibility by new levels. And the community of users usually provides us every week several new great levels.

Adding a new level that you receive as an XML file is very simple. Locate the subdirectory ``levels/auto'` on your ``user path'` (see section Locating Resources). Just copy the level file to this folder and restart Enigma. The new level will be part of the ``Auto'` levelpack and can be played like any other level.

Please note that errornous or incompatible levels are displayed with an error icon in the level menu. Of course an attempt to run such a level will result in an error message. Have a look at the level metadata with the levelinspector (see section Level Info) to identify the required compatibility version and contact the author via the address in case of level code errors.

A second way to run new levels is to add the address of the level files to the commandline (see section Startup Switches). This way you can play levels that are stored anywhere. Even Url addresses of levels stored in the internet may be used. Levels added to the commandline are accessable via the ``Startup Levels'` levelpack.

If you want to run an old fashioned Lua level that was written for Enigma 0.92 or earlier you may try to start it via the commandline. These old levels miss necessary metadata for auto detection. But commandline supplied levels are treated as temporary levels that are available just for a single run of Enigma. The missing data is substituted by reasonable defaults. You will have good chances that the level will run, but scoring and copy, past and linking of such levels is not possible.

Besides single new levels the community may provide you with complete levelpacks, too. These levelpacks may occur as directories with levels, zip archives or single XML files. All of them can be installed by simple copying the files. But we have to distinguish the three formats.

Levelpacks that are distributed as directories with level files and an index file in it have just to be copied to the subdirectory ``levels'` on your ``user path'` (see section Locating Resources).

Levelpacks that are distributed as zip archives have to be copied to the subdirectory ``levels'` on your ``user path'`. There is no need to unpack the zip even though it is possible as described in the section Zip Levelpacks.

Levelpacks that are distributed as a single XML index file have to copied to the subdirectory ``levels/cross'` on your ``user path'`.

After restarting Enigma all new levelpacks should be accessable via the levelpack menu.

That is all you need to know to be able to add new levels and levelpacks for testing and playing. If your main interest lies in writing own levels you may want to preceed directly to chapter Level Basics. The rest of this chapter explains how to arrange and sort existing levels in own levelpacks.

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

## 2.2 Converting 0.92 Levelpacks

With the changes of the levelpack index format it is necessary to convert old levelpacks. Even though the main work is done automatically just by starting Enigma a few special cases remain that need manual preparations. Furtheron some cleanup after the autoconvertion may be useful.

If you used to maintain your levelpacks within the Enigma system levels directory you should now copy your own levelpacks from the old Enigma version to the ``user path'` subdir ``levels'` (see section Locating Resources). The ``user path'` exists on all systems and as Enigma 1.00 will never write to the system levels directory updates and convertions will only be performed on the ``user path'`. If you registered your levelpacks on the system levels directory within the ``index.lua'` file you need to copy these registration lines to a file names ``index_user.lua'` which you shoud store on your ``user path'`.

If you maintained several own levelpacks Enigma 0.92 allowed you to keep them in several subdirectories of the ``levels'` directory. But you were also allowed to keep all level files and different indices in the ``levels'` directroy itself. In this last case you will run into trouble with the auto convertion as Enigma 1.00 allows only one levelpack with attached level files per directory. In this case we recommend a step by step convertion: in every step provide only one old index for convertion. Enigma will convert this index to an new ``index.xml'`. Move this new index together with all levels to a subdirectory and convert the next levelpack.

A last special case occurs if you had an old index stored in ``levels'` that referenced level files in different subdirectories of ``levels'`. As Enigma 0.92 did not had a concept of cross references and Enigma 1.00 requires all level files attached to a levelpack to be stored in a single subdirectory the convertion algorithm needs to guess the correct subdirectory. It just takes the subdirectory of the first level. If this does not fit you may need to clean up your 0.92 levelpack prior to convertion.

All other standard levelpacks should be converted without problems. The convertion is just performed once. As soon as the new ``index.xml'` exists only this index is used. Thus after a careful check you may remove the old ``index.txt'`. We recommend to keep a backup of the old index until you completly switched to Enigma 1.00.

In the case that you used an own levelpack in the zip format you will find a subdirectory named with the base name of the zip archive in your user ``levels'` directory. Within this directory the converted ``index.xml'` is stored. You may want to exchange the old ``index.txt'` in the zip with the new index. Afterwards you can delete the subdirectory as the index will be loaded directly from the zip archive.

After converting your levelpacks we strongly recommend that you update your own levels to the new XML format as described in Level Basics.

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

## 2.3 Zip Levelpacks

Besides the classical levelpack format of a subdirectory of ``levels'` with an ``index.xml'` and several level files Enigma 1.00 provides a compatible zip archive format. This zip allows you to reduce resources and to ease distribution of levelpacks.

The compatibility is 100%. If you have a classical subdirectory levelpack you can simply zip the complete subdirectory and name the zip with the name of the subdirectory plus standard ``.zip'` suffix. Now you can completly remove the subdirectory and the levelpack is autodetected and fully playable. Even cross references into this levelpacks will not be broken!

On the other hand you are allowed to expand every zip levelpack to a subdirectory with index and level files. Again everything runs and no crossreferences are broken.

If you keep both, files contained in the subdirectory preceed files in the zip archive. Thus updates of single files are stored in subdirectories in parallel to existing zip archives.

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

## 2.4 Grouping and Sorting Levelpacks

As the number of levelpacks increased it got necessary to sort and group the levelpacks in the menu. We tried to provide a useful set of default groups and default assignment of the distributed levelpacks to these groups:

- Enigma - levels that are written just for Enigma
- Déjà-vu - levels that you may have seen before
- Sokoban
- Facets - special sortings and views of the levels above
- User - personal levels and levelpacks like History, Autofolder generated by the system for the user.
- Development - templates and unfinished levels from the Enigma Team
- All Packs

But this is just a proposal. You are free to rename the groups, add new groups and change the assignments of the levelpacks. As in other parts of Enigma you can right or control click on the group and levelpack buttons.

The group configuration menu allows you to rename and reposition a group. You can choose any name that is not a duplicate, that is not enclosed in square brackets and differs from ``Every Group'`. Note that you may not be able to enter all characters that you are used too. Sorry for this inconvenience.

The levelpack configuration menu allows you to assign a pack to a group. The group list contains two special entries: ``[Every Group]'` and another name enclosed in square brackets. A selection of the first pseudogroup shows up the levelpack in every group. The ``Startup Levels'` group has this assignment by default. The second square bracket enclosed name is the default group of the levelpack itself. It is a hint for you and allows you to reassign a levelpack to the default group even if you meanwhile have deleted the group.

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

## 2.5 Creating New Levelpacks

To create a new levelpack you simply select the group to which you want to add the new pack. This is most likly the ``User'` group. Right or ctrl click on the group and simply click on the ``New Levelpack'` button. The levelpack configuration menu will be called that allows you to enter all important data for the creation of a levelpack.

First you should enter a name for the levelpack. You are limited to characters that can be used for filenames, too. Alphanumerical characters A-Za-z0-9 and space, underscore and hyphen are usable. Note that you may rename the pack lateron for a better suitable display name (see section Modifying and Deleting Levelpacks).

Furtheron you should decide whether you want a levelpack that can contain level sources or just a crossreference levelpack. The first one is useful for storing own self written levels or levels that you download yourself from the internet. The crossreference levelpacks are for your favorite collections where you just reference existing levels of other levelpacks with your own personal sorting. You set the selected type with the ``Level types'` button which uses symbols for references and carbon copies.

The ``Default Location'` is a number that determines the sorting location within levelpack groups as long as the levelpack has not been resorted manually (see section Grouping and Sorting Levelpacks). This default value is only relevant if you distribute your levelpack and want to ensure that the users will find your levelpack at a proper location. The value given after creating a new levelpack should work fine in most circumstances.

You may declare yourself as owner or creator of the levelpack. This just a string for identification purposes.

Finally when you completed the configuration you can create the levelpack by clickling ``OK'`. The levelpack will be created on your ``userpath'` (see section Locating Resources).

If you decide not to create a new levelpack just click ``Undo'`. Nothing will be created or changed in this case.

If you want to set up immediatly the new levelpack you can click directly on ``Compose Pack'`. The levelpack will be created and you can use the composer to fill it with levels.

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

## 2.6 Modifying and Deleting Levelpacks

To modify a levelpack right or ctrl click on its button in the levelpack menu. You will see the metadata for all levelpacks. But only for your own levelpacks that are stored on your ``userpath'` a button ``Edit Metadata'` will show up. Clicking on it allows you to edit the metadata.

It is possible to rename the levelpack, but the filenames will not be changed any more. The new name will be used as the logical levelpack name that shows up in Enigma.

Other attributes that can be modified are the ``Default Location'` and the ``Owner'`.

Note that it is not possible to change the levelpack type lateron. You have to create a new levelpack of proper type and copy the levels by Composing Levelpacks.

We do not provide a levelpack deletion function to avoid uninteded loss of levelsources. But the deletion of a levelpack is as simple as deleting the complete levelpack directory on your ``userpath'`. For crossreference levelpacks you have to delete just the index XML file on the ``levels/cross'` subdirectory of your ``userpath'`.

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

## 2.7 Composing Levelpacks

You can change the levels of a levelpack by the levelpack composer. You call it by right or ctrl clicking on the levelpack button in the levelpack menu and clicking on the ``Compose Pack'` button in the levelpack configuration menu.

The composer looks quite similar to the levelmenu but it provides other functionallity. All commands are listed in the F1 help menu. First you may note that the levels are bordered red if you compose your own levelpacks. This is a warning as you can modify these levelpacks. System levelpacks as the distributed Enigma levelpacks will border the levels in gray as you can use the composer only for copying levels to the clipboard.

The clipboard allows you to select levels in one or several levelpacks and to insert these levels as reference or as copy to your own levelpacks. First clear the clipboard by ``Shift delete'`. Then select within the composer levels from any levelpack you want. Add them by ``Shift click'`. They will show up in the upper text lines in the composer. Return to the levelpack where you want to add the levels. Select the level behind which you want to add the levels. Use ``F8'` to insert the levels of the clipboard as references. If you edit a levelpack that can take level copies you may use ``F9'` to insert the levels of the clipboard as file copies.

As soon as you modify the levelpack a small red triangle in the upper left corner signals the modification. Leaving the composer via button ``OK'` finalizes all changes. Leaving the composer via button ``Undo'` reverts all changes.

Besides addition of levels you can delete levels by usage of the ``delete'` button. Note that the level files itself will be deleted if you delete a level that is not just a reference. Be careful with all levels that have the document icon on its preview. Deletions can be reverted by the ``Undo'` button.

All levels can be resorted by ``alt left arrow'` and ``alt right arrow'`. The new sorting is shown up directly and saved by the ``OK'` button.

The ``F5'` button updates the index from the levels. This is very useful if you edit levels yourself. Changes in title, revision, easy mode support etc. will be noticed by the levelpack. All levels of the levelpack are updated at once.

By usage of the Auto levelpack and the composer you can setup levelpacks of your own levels as follows. Create a new levelpack, add the level files to the ``auto'` folder, restart Enigma, add the levels from the ``auto'` folder to the clipboard, insert the levelpack by the composer to your levelpack as copies, delete the unused level file copies from the ``auto'` folder.

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

# 3. Level Basics

As you have played some levels of Enigma you may have noticed that Enigma is a quite dynamic game with versatile levels. Thus it is not astonishing that it is not possible to describe such levels with a static approach of a simple object map like Sokoban. Some levels like mazes, generate their layout and look different each time they are played. Other levels provide a dynamic behaviour during the play. F.e. switches may open doors only on certain circumstances. To comply these demands the powerful light-weight C extension language Lua has been integrated into Enigma.

Up to Enigma 0.92 two different level formats did exist. One was a XML like format that was primarily designed for external level editor programs. As its static object map description part was inconvenient for manual edition it was never used by many authors. The second format was plain Lua code that used an interface of Enigma Lua functions to add objects and callback functions. This second format was used by nearly all authors. But it had a small drawback - metadata for the level like the author name, license info and last but not least the level name itself could only be stored as unformatted Lua comments and had to be reinserted manually into the level-package indices.

With the post 0.92 XMLification of Enigma we achieved full XML support by integration of Apache Xerces and were wondering how to get rid of the old level format drawbacks and how to add some compelling new features:

- a single format with optional parts - use only those parts you have need of
- no major changes or any limitations for Lua level authors
- keep all author supplied metadata in the level
- enable plug & play for users - copy the level from the author and play it without manual index edition
- support of various encodings like US-ASCII, UTF-8, UTF-16, windows-1252
- internationalization of levels - allow authors to add strings in their native language and supply translators with all translatable level strings and comments from the authors how to translate.
- add a release and dependecy management for levels and libraries
- add level update and upgrade support for levels and libraries
- substitute the old XML format by a versatile editor interface
- keep the format open to future extensions

Let us have a first view on complete simple ``Hello World'` level in the new format:

    <?xml version="1.0" encoding="UTF-8" standalone="no" ?>
    <el:level xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://enigma-game.org/schema/level/1 level.xsd" xmlns:el="http://enigma-game.org/schema/level/1">
      <el:protected >
        <el:info el:type="level">
          <el:identity el:title="Demo Simple" el:id="20060210ral001"/>
          <el:version el:score="1" el:release="1" el:revision="0" el:status="stable"/>
          <el:author  el:name="Ronald Lamprecht"/>
          <el:copyright>Copyright © 2006 Ronald Lamprecht</el:copyright>
          <el:license el:type="GPL v2.0 or above" el:open="true"/>
          <el:compatibility el:enigma="0.92"/>
          <el:modes el:easy="false" el:single="true" el:network="false"/>
          <el:score el:easy="-" el:difficult="-"/>
        </el:info>
        <el:luamain><![CDATA[
    levelw = 20
    levelh = 13

    create_world( levelw, levelh)
    draw_border("st-wood")
    fill_floor("fl-leavesb", 0,0,levelw,levelh)

    oxyd( 4,4)
    oxyd( 14,4)

    set_actor("ac-blackball", 4, 11)
        ]]></el:luamain>
        <el:i18n/>
      </el:protected>
    </el:level>

You may notice that the XML part contains all the metadata that the level author is used to supply with a level. The XML part is like a formular that can be copied from a template and be filled out.

The Lua code is embedded in the XML. The only limitation to the Lua part is that ``]]>'` is reserved for the end mark and would have to be substituted by ``]] >'`. No further restrictions.

As the example above includes all mandatory XML parts our aim to avoid major changes for Lua level authors should be achieved.

You find the example above in the ``Exp'` levelpack grouped in ``Development'`. The source code is located on the system path subdirectory ``levels/enigma_experimental'` (see section Locating Resources).

If you make your first coding experiments on a copy of this level either add your copy to the auto folder (see section Getting Started with Levelpacks) or use it as an argument on the command line (see section Startup Switches).

Of course we have to look at the details of the format and explain the optional parts:

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

## 3.1 Getting Started with Levels

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] | [ ? ]

## 3.2 XML Level structure

Let us start with a complete overview of all existing top XML element nodes. The following level skeleton contains optional elements that are beyond level basics. These elements are just included for completeness:

    <?xml version="1.0" encoding="UTF-8" standalone="no" ?>
    <el:level xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://enigma-game.org/schema/level/1 level.xsd http://enigma-game.org/schema/editor editor.xsd" xmlns:el="http://enigma-game.org/schema/level/1" xmlns:ee="http://enigma-game.org/schema/editor">
      <el:protected>
        <el:info el:type="level">
          <!-- required elements omited -->
        </el:info>
        <el:elements/>
        <el:luamain><![CDATA[
        ]]></el:luamain>
        <ee:editor/>
        <el:i18n/>
      </el:protected>
      <el:public>
        <el:i18n/>
        <el:upgrade/>
      </el:public>
    </el:level>

The first line is the XML declaration. It is fixed besides the encoding specification. Enigma supports on all platforms at least ``US-ASCII'`, ``UTF-8'`, ``UTF-16'`, ``ISO-8859-1'`, ``windows-1252'`. Enter your encoding and ensure that your editor saves the level in this encoding. On some editors you can start in ASCII mode, copy the level skeleton with a different encoding declaration like UTF-8, save the level still in ASCII mode and reopen the file - the editor may detect the XML declaration and switch automatically to the given encoding. Note that as long as you do not enter international strings in the level you do not have to bother with the encoding at all. You can choose UTF-8 in this case.

Some addiontal remarks for XML newbies. The XML markup tags are quite similar to HTML. But XML requires for each start tag ``<element>'` a corresponding end tag ``</element>'`. For elements that have only attributes and no content you can and should use the alternativ empty element notation ``<element/>'`. Note that when we define an element as empty or state that no content is allowed not a single whitespace, even no linebreak is allowed between start and end tag - use the empty element notation to avoid mistakes.

We use a pretty printing format with an indention of 2. Each element starts on a separate line. Elements with text content have the end tag on the same line. Only elements with subelements have the end tag on a separate line with the same indention.

This format is not mandatory. You can even insert linebreaks in text contents and within the marks and even within attribute values. But note that the basic rule is that each linebreak will be substituted by a space during the XML parsing. Take this space into account to avoid mistakes, or simply live with the long lines.

All tag names and attribute names are prefixed with a namespace identifier. We use ``el'` as an abreviation for enigma level. All tag names that may be manually edited use this prefix.

And finally a short comment to the XML reserved characters ``&'` and ``<'`. These two characters are reserved as tag and entity starting characters. If you have need for them in text contents or in attribute values you have to substitute them by the entity sequences ``&amp;'` and ``&lt;'`. Additionally attribute values have to be enclosed either by ``"'` or ``''`. Of course the used enclosing character has to substituted in attribute values, too. Use ``&quot'` and ``&apos'`.

Elements:

/level, required, single occurence

  This is the root node. There is only one instance of this node per file. Like the first XML declaration line this second line is quite fixed. There are two versions. The simple 3 attribute version as used in the first example and the 4 attribute version as above that is only used by level editor programs. For manual level edition just copy the simple version as the second line to your level file.

  Attributes:

  xmlns:xsi, required, contents fixed

    Namespace definition for the schema. The contents is fixed to "http://www.w3.org/2001/XMLSchema-instance". The attribute tag ``xsi'` must match the prefix of the next attribute tag and is standard.

  xsi:schemaLocation, required, contents fixed

    Location of the used schemas. The contents is the fixed enigma level namespace followed by the schema location URL. Level editor programs will add their namespace and their schema location URL as in the second example above.

  xmlns:el, required, contents fixed

    Namespace definition for enigma level. We use ``el'` as namespace prefix for all level element and attribut tags as standard. The used prefix can be arbitrary but must match this attibutes tag. The contents of the attribute is fixed to the enigma level namespace.

  xmlns:ee, optional

    This last namespace definition is used by level editor programs only. As an example we declared ``ee'` as namespace prefix for all editor element and attribute tags. The used prefix can be arbitrary but must match this attibutes tag. The contents of the attribute is the editors namespace.

/level/protected, required, single occurence

  The protected node section contains all level data that derive from the author and should not be modified by anyone else.

/level/protected/info, required, single occurence

  The info node section contains all level metadata. It is mandatory and described in detail at section Info metadata.

/level/protected/elements, optional, single occurence

  The elements node section is optional. It contains level description parts that are given in a data driven manner. Even though the driving force is the support for level editor programs a level author may use any parts of this section he likes.

/level/protected/luamain, optional, single occurence

  The luamain node section is the part to insert manually Lua level descriptions. It is described in detail at section LUA code.

/level/protected/editor, optional, single occurence

  The editor node section is an open extension area for level editor programs. They can add any additional information in this section that they have need of. This node section is simply ignored by Enigma.

/level/protected/i18n, required, single occurence

  The i18n node section contains English strings, native translations and comments supplied from the author for the translators. This node section is mandatory and described in detail at section Internationalization (i18n).

/level/public, optional, single occurence

  This public node section is an optional extension to the proteced part. It contains information that is not validated by the author and may even be added after the last authors review.

/level/public/i18n, optional, single occurence

  This public i18n section contains further level supplied translations. They may derive from the author or other sources. These translations will be validated by the translators and are used as long as the translators do not supply corrected versions. See Internationalization (i18n).

/level/public/upgrade, optional, single occurence

  This upgrade node is part of the Update and Upgrade system.

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

## 3.3 Info metadata

The Info node contains all author supplied metadata of the level. This is the source of these data. All other parts of Enigma like level indices just contain copies that will be automatically updated to the levels original data.

Let us have a look on all supported subnodes of info with typically used attributes:

    <el:info el:type="level">
      <el:identity el:title="Demo I18N" el:subtitle="Translate or let it be translated" el:id="20060211ral002"/>
      <el:version el:score="1" el:release="1" el:revision="0" el:status="experimental"/>
      <el:author  el:name="Ronald Lamprecht" el:email="ral@users.berlios.de"/>
      <el:copyright>Copyright © 2006 Ronald Lamprecht</el:copyright>
      <el:license el:type="GPL v2.0 or above" el:open="true"/>
      <el:compatibility el:enigma="0.92"/>
      <el:modes el:easy="false" el:single="true" el:network="false"/>
      <el:comments/>
      <el:update el:url="http://…"/>
      <el:upgrade el:url="http://…" el:release="2"/>
      <el:score el:easy="-" el:difficult="-"/>
    </el:info>

Attributes:

type, required, values = "level", "library", "multilevel"

  The schema may be used for single enigma levels, libraries that contain level description parts for reusage as well as descriptions for multiple levels at once.

  ``level'` are all single level descriptions. It does not matter if they are edited manually or by a level editor program and which description elements are used

  ``library'` are level description parts that may be included into levels. The library may consist just of Lua code in the luamain node or addtional object descriptions in the elements node. Libraries may make use of nearly all nodes besides the ``/level/protected/info/score'` and ``/level/*/i18n'` which both have to be provided but will not be evaluated. Libraries are included into levels via the dependency node-element. See <compatibility>.

  ``multilevel'` are descriptions for multiple levels at once. The main purpose is to support foreign game level formats like the Sokoban level format which describes usually a whole set of level maps in a single file.

quantity, optional

  The number of levels contained in a multilevel file.

Contents - Elements:

identity, required

  The title, subtitle and the main level identification string. See <identity>.

version, required

  All aspects of the level <version>.

author, required

  All information provided about the author him- or herself. See <author>.

copyright, required

  The <copyright> message for the level.

license, required

  Information about the <license> conditions.

compatibility, required

  All information about <compatibility> to Enigma releases, dependencies from libraries, external data and the editor program that generated the level.

modes, required

  The <modes> that the level supports, as difficulty, network and control.

comments, optional

  Optional comments like credits, dedication and code comments. See <comments>.

update, optional

  Update and Upgrade

upgrade, optional

  Update and Upgrade

score, required

  The authors own <score> of this level.

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

### 3.3.1 <identity>

The ``identity'` element is required, as it provides the information for human and system identification of the level.

    <el:identity el:title="Demo I18N" el:subtitle="Translate or let it be translated" el:id="20060211ral002"/>

Attributes:

title, required

  The English title of the level. Make sure that the title is not too long as it will be used on the level selection menu. Translations of the title can be provided in the Internationalization (i18n) sections.

subtitle, optional

  An optional english subtitle. Used for title parts that are too long for the main title, or for a short first hint. The subtitle is displayed on the level info page and on the start of the level. Translations of the subtitle can be provided in the Internationalization (i18n) sections.

id, required

  This is the central system identification string of the level that remains valid for all time independent of upcomming release updates. Enigma's single demand on the id is that it is unique. Unique among all levels created by all authors around the world.

  As levels can be edited with any text editor or different special Enigma level editors there is no control about the uniqueness. Thus we have to provide a simple convention to avoid any possible id clashes:

  YYYYMMDDuserNNN

  Where ``YYYY'`,``MM'`,``DD'` is the date of the creation of the first experimental version, ``user'` stand for a user specific name and ``NNN'` for a random number. F.e. my level called ``Houdini'` has the id ``20060816ral719'`. Of course all level created on the same day have to differ in the random number part. The id is a Enigma level system id and is never exposed to users.

  For backward compatibility legacy levels keep their former filename as the new level id and do not fit in the name schema given above. But that does not harm as the only requirement is the uniqueness.

Contents:

The element itself is empty - no content is allowed.

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

### 3.3.2 <version>

This element provides the versioning information for the system.

    <el:version el:score="1" el:release="1" el:revision="0" el:status="experimental"/>

Attributes:

score, required

  The score version is given as a positiv integer number. New levels start with score verison "1". New level versions need to increase the score version number if the level modifications cause different solutions with uncomparable score values. Of course level authors should be very restrictive with such modifications.

  During the development of a level the attribute ``status'` should be used to mark a level as not released. Not later than the author changes the ``status'` to ``released'` he has to check scoring compatibility and increase the score version if necessary.

  This attribute is the logical equivalence to the Enigma 0.92 ``index.txt'` attribute ``revision'`.

release, required

  The technical release version is given as a positiv integer number. New levels start with release version "1". New level versions need to increase the release version number if the level modifications either cause technical incompatibilities with previous Enigma releases or the scoring version has been increased.

  The primary cause for technical incompatibilities should be the compensation of Enigma engine changes. As such compensations will not run on the old Enigma version the level versions have to be distinguished by a different release number.

  In both cases, technical and scoring incompatibilities, the level file name has to be changed, too. This is necessary as on some systems different Enigma versions may be installed at the same time. They have the need for both level versions at the same time. Internet servers providing Enigma levels need to offer different level release at the same time, too.

  To enable humans to assign different level release files to a level itself we strongly recommend the name convention for levels AuthoridentifierLevelnumber_Releasenumber.Suffix. Where the levelnumber is at least 2 digits. For example ``ral01_2.xml'`

revision, required

  The revision number is a simple ever increasing version number. Every published version of the level should have a new revision number. The revision number is independent from the scoring and release version number.

  If Enigma finds two levelfiles in its data serach paths with identical filenames, id, score and release version it will load the one with the higher revision number. This feature guarantees, that a new revision of a level distributed with a new Enigma release can not be shadowed by an older level revision stored on the users home level directory. Online updates will check the level revision numbers, too.

  Even though the revision evaluates to a number the attribute can take a second string format as the literal keyword ``$Revision$'`. This Subversion format allows level authors to let the level revision number be automatically inserted by their Subversion repository. They just have to set ``svn propset svn:keywords "Revision" level.xml'` at their repository for every level file. As the Subversion revision number is ever increasing it fulfills our criteria. Note that there is no need for revision numbers to be consecutive.

status, required, values = "released", "stable", "test", "experimental"

  This attributes describes the quality of the level during development. Enigma uses the status to protect the score database to be spoiled by unplanned solution scores. Only for levels marked as ``released'` scores will be recorded.

  A level author who starts a change on a released level should first change the status back to ``experimental'`. Then he should make his changes and test the level. When he is definitivly sure that he did not introduce any spoilers he can release the level again with a new revision and may be release or score version number.

Contents:

The element itself is empty - no content is allowed.

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

### 3.3.3 <author>

The information about the author him/herself. The element itself is required. But all attributes are optional to allow an author to be anonymous. Please remember, that level adminstrators and translators may have a need to contact you as an author. So please give a way to drop a note for you.

The author element node may look like:

    <el:author  el:name="Ronald Lamprecht" el:email="ral@users.berlios.de" el:homepage="http://myhomepage.domain"/>

Attributes:

name, optional, default = "anonymous"

  The authors name as it will be displayed on the level info page and on the start of the level. The name defaults to ``anonymous'`.

email, optional

  The authors email address or a newsgroup or forum he listens to. In general a hint how to drop a note for him. The value will just be displayed as a string on the level info page.

homepage, optional

  An address about the author or where the author publishes further Enigma levels. The value will just be displayed as a string on the level info page.

Contents:

The element itself is empty - no content is allowed.

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

### 3.3.4 <copyright>

The standardized location for a copyright message of the author:

    <el:copyright>Copyright © 2006 Ronald Lamprecht</el:copyright>

Attributes:

none

Contents:

The copyright notice of the author.

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

### 3.3.5 <license>

Of course every author is free to choose the license conditions for his levels. But the author has to state the conditions. Thus this node element and its attributes are required:

    <el:license el:type="GPL v2.0 or above" el:open="true"/>

Attributes:

type, required

  A short license identifier of the license type with an optional link address to the license text or the string ``special'` if the author supplies an own license as the content of this element.

open, required

  A boolean statement if the choosen license fulfills the criteria of the Open Source Initiative (OSI). Please note that a value of ``false'` may keep your level of being distributed together with Enigma.

Contents:

A complete license text may be added as the contens of this element. Please make use of identification of the level via the type attribute.

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

### 3.3.6 <compatibility>

    <el:compatibility el:enigma="0.92" el:engine="enigma">
      <el:dependency el:path="lib/natmaze" el:id="lib/natmaze" el:release="1" el:preload="true" el:url="http://anywhere.xxx/mypage/natmaze.xml"/>
      <el:externaldata el:path="./extfile" el:url="http://anywhere.xxx/mypage/extdata.xml"/>
      <el:editor el:name="none" el:version=""/>
    </el:compatibility>

Attributes:

enigma, required

  The minimal Enigma release number required for compatibility.

engine, optional, values = "enigma", "oxyd1", "per.oxyd", "oxyd.extra", "oxyd.magnum"; default = "enigma"

  The required engine compatibility mode that influences the behaviour of various objects. This attribute is only evaluated for levels. Libraries ignore this attribute.

Contents - Elements:

The comments element itself contains only subelements as content.

dependency, optional, mutiple occurence

  With the use of this element you can specify any Enigma-Lua library this levels depends on. You can specify several libraries by multiple occurence of this element. If you configure a library to be preloaded it will be loaded by the engine before any level Lua code is loaded and executed. The load sequence of several libraries conforms strictly to the sequence of their dependencies elements.

  Attributes:

  path, required

    The resource path of the library without it's suffix and any release extension. As most libraries are stored in the ``lib'` subdirectory of Enigma's ``levels'` directory the resource path will be in most cases like the one in the example above: ``lib/ant'`. This is the valid path for the library file that may be either ``levels/lib/ant.xml'` or ``levels/lib/ant.lua'` or ``levels/lib/ant_1.xml'`.

    But libraries can also be totally level pack specific. In this case you may use a relative resource path like ``./mylib'` and store the library in the level pack directory itself.

  id, required

    The version independent id of the library as specified in the library metadata. It will be checked on load of the library to avoid problems and may be used together with the release number to detect relocated libraries.

  release, required

    Even though different release versions of libraries have to have different filenames we require to specify the library version. It will be checked on load of the library to avoid problems and may be used together with the id to detect relocated libraries.

  preload, required

    A boolean statement that specifies whether the library should be preloaded. If the library is not preloaded you can still load it via Lua code statements. But even those libraries have to be declared as they will be checked on conformance. You should always preload your libraries if you make use of the ``elements'` section.

  url, optional

    This optional attribute allows to specifiy a backup address for the library. This will be usefull for the usage of new libraries that are not yet distributed with the system.

    For the development and test phase of new libraries themself a developer can hand out test levels with an empty ``library'` resource path attribute. The test levels will load the newest library version as published at the given url.

  Contents:

  none.

externaldata, optional, multiple occurence

  This element can be used to specify any external data file this levels depends on. You can specify several files by multiple occurence of this element. Files declared can be read via the Lua interface.

  This feature should support levels that simulate foreign games like Sokoban within Enigma. Due to copyrights and license conditions it may not be possible to include some data within a level. But it may be legal to distribute the data in the original unmodified format.

  Attributes:

  path, optional

    The resource path of the external data file with it's suffix. As the data are usually level specific they should be stored aside of the level in the same levelpacl directory. Thus a relative resource path like ``./datafile.ext'` should be preferable.

  url, optional

    This optional attribute allows to specifiy an online address for the external data file. Only wellformed xml data files can be accessd by this method.

    The online access method should only be used as a backup address or due to very restrictive license conditions that make it impossible to distribute the data file together with Enigma.

  Contents:

  none.

editor, optional, single occurence

  This element can be used by special level editor programs to store information about themselves.

  Attributes:

  name, required

    The name of the level editor.

  version, required

    A version number of the editor given as a string. .

  Contents:

  none

Contents:

none

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

### 3.3.7 <modes>

The modes element allows the author to declare the supported and the default modes of his level. Enigma's engine checks that the level is used in supported modes.

    <el:modes el:easy="false" el:single="true" el:network="false" el:control="force" el:scoreunit="duration" el:scoretarget="time"/>

Attributes:

easy, required, values = "true", "false"

  If a level provides a second easy-difficulty mode set this attribute to ``true'`. If only a one difficulty mode is supported set this attribute to ``false'`.

single, required, values = "true", "false"

  If a level provides a single player game as it is standard set this attribute to ``true'`. Only if the level is a 2-player-network game only set this attribute to ``false'`.

network, required, values = "true", "false"

  If a level provides a 2-player-network game set this attribute to ``true'`. If not set this attribute to ``false'`.

control, optional, values = "force", "balance", "key", "other"; default = "force"

  This attribute defines the standard control mode of the level. A level can be played by using the mouse to generate forces on the marbles as it is the standard and only way up to Enigma 0.92. Or a level can be played using the mouse, or other input devices to balance the level-world with the marbles. Or the keyboard may be used with its cursor keys to move the actor like in classical Sokoban games.

  Even though the user has always the last choice to define the input method he currently wants to use the author has to define the standard control-mode that is used by the scoring system. Only scores achieved in the defined control mode will be saved and evaluated for high score lists.

scoreunit, optional, values = "duration", "number"; default = "duration"

  This attribute defines the evaluation and display mode of score values. By the default ``duration'` the score is intepreted as level solution time and displayed in a MM:SS format. In the ``number'` mode scores are displayed as plain numbers and lower numbers be evaluated as better scores. This mode is appropriate for counting of pushes and moves.

scoretarget, optional, values = "time", "pushes", "moves", *; default = "time"

  The score target triggers the measuring of score values. ``time'` will take the solution time, ``pushes'` counts the pushes of stones, ``moves'` counts the moves of the actor. Any other value will call a Lua function for score values. The target is used as a short title for the score in user interface displays.

Contents:

none

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

### 3.3.8 <comments>

The optional comments node allows the author to add a few comments and to determine how they should be processed. Please note that comments will not be translated by the internationalization support.

    <el:comments>
        <el:credits el:showinfo="true" el:showstart="false">Thanks to the author of my favorite libs</el:credits>
        <el:dedication el:showinfo="true" el:showstart="false">To a honorable or a beloved person</el:dedication>
        <el:code>some important general notes</el:code>
    </el:comments>

Attributes: none

Contents - Elements:

The comments element itself contains only subelements as content.

credits, optional, single occurence

  The place to honor people who did make your level running.

  Attributes:

  showinfo, optional, default = "false"

    A value of ``true'` will make the message being displayed on the level info page

  showstart, optional, default = "false"

    A value of ``true'` will make the message being displayed on startup of the level. Please use this feature only in rare cases.

  Contents:

  The credits message itself. It may be broken over several lines. Whitespaces will be collapsed before display.

dedication, optional, single occurence

  The place to dedicate the level to a honorable of a beloved person. Please use this place instead of adding document-items within the level.

  Attributes:

  showinfo, optional, default = "false"

    A value of ``true'` will make the message being displayed on the level info page

  showstart, optional, default = "false"

    A value of ``true'` will make the message being displayed on startup of the level. Please use this feature only in rare cases.

  Contents:

  The dedication message itself. It may be broken over several lines. Whitespaces will be collapsed before display.

code, optional, single occurence

  Attributes:

  none.

  Contents:

  The main code comment that may be an explanation of the <version> status or a todo list. It may be broken over several lines. This comment will not be processed.

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

### 3.3.9 <score>

In this node the author should provide his own scoring values as hints and challenge for other players. All values are related to the control mode defined in <modes>.

    <el:score el:easy="01:07" el:difficult="-"/>

Attributes:

easy, required

  The solvage time for the easy mode. The format is either MM:SS where MM stands for the minutes, and SS for the seconds, or - if the author did not yet solve the level himself. For levels with a score unit mode ``number'` the value would be the number of marble moves or pushes.

difficult, required

  The solvage time for the difficult mode. The format is either MM:SS where MM stands for the minutes, and SS for the seconds, or - if the author did not yet solve the level himself. For levels with a score unit mode ``number'` the value would be the number of marble moves or pushes.

Contents:

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

## 3.4 LUA code

This elements takes any Lua code as a single chunk with nearly no limitations:

        <el:luamain><![CDATA[
    levelw = 20
    levelh = 13

    create_world( levelw, levelh)
    draw_border("st-wood")
    fill_floor("fl-leavesb", 0,0,levelw,levelh)

    oxyd( 4,4)
    oxyd( 14,4)

    document(5,10,"hint1")
    document(10,10,"hint2")
    document(10,5,"Heureka!")
    set_actor("ac-blackball", 4, 11)
        ]]></el:luamain>

Attributes:

none

Contents:

This element takes the main Lua code as its contents.

All other possible libraries that are declared as dependencies and Lua chunks supplied by XML elements are preloaded as described in <compatibility>. Generally there is no more need to use Lua functions like ``Require'` to load libraries. Just in case you need to control the point of execution were the library has to be loaded you can declare the library with the attribute ``el:preload="false"'`. You should use the new function enigma.LoadLib to load the library.

The Lua code itself that is enclosed in a XML CDATA section. This limitates the Lua code to not use the reserved end marker ``]]>'`. Any occurence has to be substituted by ``]] >'`.

On the other hand the XML format extends the Lua capatibilities to the usage of encodings. You may use Lua strings and comments with Umlauts. But Lua identifiers are still limited to pure US-ASCII. The benefit is that you can use Umlauts and other non ASCII characters within it-document hints.

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

## 3.5 Internationalization (i18n)

The internationalization of levels is one of the driving forces behind the level format changes. As you may have noticed there are two ``i18n'` elements, one in the authors protected section and one in the public. Let us look how to use them for internationalization of the three documents of our ``demo_i18n.xml'` level:

      <el:protected >
        <!-- elements ommited -->
        <el:i18n>
          <el:string el:key="title">
            <el:english el:translate="false"/>
          </el:string>
          <el:string el:key="subtitle">
            <el:english el:translate="true"/>
            <el:translation el:lang="de">Übersetzten oder übersetzten lassen</el:translation>
          </el:string>
          <el:string el:key="hint1">
            <el:english el:comment="Let 'right' be ambiguous: correct and opposite of left - if not possible choose correct">Read the right document</el:english>
            <el:translation el:lang="de">Lies das rechte Dokument</el:translation>
          </el:string>
          <el:string el:key="hint2">
            <el:english el:comment="the correct one and not the right positioned one">The right one, not the right one!</el:english>
            <el:translation el:lang="de">Das rechte, nicht das rechte</el:translation>
          </el:string>
          <el:string el:key="Heureka!">
            <el:english el:translate="false">Heureka!</el:english>
          </el:string>
        </el:i18n>
      </el:protected>
      <el:public>
        <el:i18n>
          <el:string el:key="hint1">
            <el:translation el:lang="fr">Lisez la document de droite</el:translation>
          </el:string>
        </el:i18n>
      </el:public>

Two of the documents use key words to reference a string. The last one uses the English string itself as the key. There are two additional reserved keys ``title'` and ``subtitle'`.

For each string we like to translate or have translated we define a ``string'` subelement of the protected section and add a ``english'` subelement to the ``string'` element itself. The ``string'` element just takes a single mandatory attribute - the key of the string. The ``english'` element has a one mandatory attribute ``translate'` that defaults to ``true'` stating the author decision whether the string should be translated. In case the author does not want a string to be translated he can, and will, just add no ``string'` element for this string at all. Thus the elements for the strings with the keys ``title'` and ``Heureka!'` are optional and quite unusual.

``title'` and ``subtitle'` have the English text given in the <identity> element. All other strings referenced by keys need to add the English text as the content of the ``english'` element. ``hint1'` and ``hint2'` are examples.

As we did choose quite ambiguous English texts it is very likly that translators who do not play the game and just get the text to translate may deliver a wrong translation. To avoid mistakes a level author may add a ``comment'` attribute to the ``english'` element. The translator receives this comment together with the English string as we will see lateron.

If the author is not native English speaking he should add himself ``translation'` subelement to the ``sting'` element. The ``translation'` element has a single mandatory attribute ``lang'` that takes the 2-character language abbreviation. The contents of the element is the translation itself.

All translations added in the protected section take preceedance over any translators translation and will work directly after addition without waiting for a translators translation.

Last but not least we have a ``i18n'` element in the public section. This element takes translation suggestions. They may be added by the author himself for further languages he is aware of. They may be added by other people on the way to the user or even the user himself.

Translations in this section will again work directly after addition without waiting for a translators tranlation. But they will be preceeded by available translations provided by translators.

The format is identical to the protected section, with the exception that no ``english'` element may be provided. The ``key'` attribute in the ``string'` element must match exactly the ``key'` attribute in the corresponding ``string'` element in the protected section. There is one subtle difference due to technical and practical reasons. ``key'` attributes in the public section need to be XML identifiers - thus you can not provide public translations for strings that use the english phrase as the key. Choose a keyword and provide the english string in the public ``i18n'` section to avoid these troubles.

The ``string'` element in protected section as well as in the public section must be unique concerning the attribute ``key'` within the section. This means you should add translations for all known languages for a string in ``string'` element in the proteced and one in the public section. The sequence does not matter.

Let us have a look what the translator gets presented for each string. Let us start with ``hint2'` for the German translator:

    #  level: "Demo Internationalization"
    #  author: "Ronald Lamprecht" email "ral@users.berlios.de"
    #  comment: "the correct one and not the right positioned one"
    #  use: "Das rechte, nicht das rechte"
    #: po/level_i18n.cc:17
    msgid "The right one, not the right one!"
    msgstr ""

``msgid'` is the English string. ``msgstr'` takes the German translation. But the translator does not need to translate as the German tranlation was given by the author in the ``# use:'` line

And as another example ``hint1'` for the French translator:

    #  level: "Demo Internationalization"
    #  author: "Ronald Lamprecht" email "ral@users.berlios.de"
    #  comment: "Let 'right' be ambiguous: correct and opposite of left - if not possible choose correct"
    #  check: "Lisez la document de droite"
    #: po/level_i18n.cc:14
    msgid "Read the right document"
    msgstr "Lisez le document de droite"

Here the public translation is given in the ``# check:'` line. As it contains at least one mistake the translator will correct it as shown in the ``msgstr'` string.

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

## 3.6 Usage

After all the theory lets have a look how to deal with the XML levelformat in practice. Of course you will not assemble all XML metadata from scratch for every new level you write. You should use templates. You can start with any existing level, f.e. the ``demo_i18n.xml'` that is supplied with this documentation. Add your personal data to your template and store it as basis for all new levels you write.

Some level authors are very used to the Lua file format as their favorite editor supports Lua files with syntax coloring. The XML file name and the XML elements will cause their editor to use XML syntax coloring. As these authors are nevertheless used to supply metadata in the header of their Lua levels as non standardized Lua comments we decided to support a similar Lua compatible XML format. We call it "Lua commented XML" as it simply comments out all XML lines with the Lua comment ``--xml-- '`. For example

    --xml-- <?xml version="1.0" encoding="UTF-8" standalone="no" ?>
    --xml-- <el:level xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://enigma-game.org/schema/level/1 level.xsd" xmlns:el="http://enigma-game.org/schema/level/1">
    --xml--   <el:protected >
    --xml--     <el:info el:type="level">
    --xml--       <el:identity el:title="Demo Simple" el:id="20060210ral001"/>
    --xml--       <el:version el:score="1" el:release="1" el:revision="0" el:status="stable"/>
    --xml--       <el:author  el:name="Ronald Lamprecht"/>
    --xml--       <el:copyright>Copyright © 2006 Ronald Lamprecht</el:copyright>
    --xml--       <el:license el:type="GPL2" el:open="true">GPL v2.0 or above</el:license>
    --xml--       <el:compatibility el:enigma="0.92"/>
    --xml--       <el:modes el:easy="false" el:single="true" el:network="false"/>
    --xml--       <el:score el:easy="-" el:difficult="-"/>
    --xml--     </el:info>
    --xml--     <el:luamain><![CDATA[
    levelw = 20
    levelh = 13

    create_world( levelw, levelh)
    draw_border("st-wood")
    fill_floor("fl-leavesb", 0,0,levelw,levelh)

    oxyd( 4,4)
    oxyd( 14,4)

    set_actor("ac-blackball", 4, 11)
    --xml--     ]]></el:luamain>
    --xml--     <el:i18n/>
    --xml--   </el:protected>
    --xml-- </el:level>

Please note that each XML metadata line has to start exactly with ``--xml-- '`, 8 charcters including the space at the end! An additional limitation of the Lua commented XML format arises from Lua's capability of handling character encodings. You need to limit yourself to ``UTF-8'` or of cause ``US-ASCII'` to successfully use the Lua commented XML format. Please remember, that even though the XML part is Lua commented, it will still be evaluated and has thus to valid.

Every level stored in this Lua commented XML format as a file with extension ``.lua'` can be used locally for command line usage as well as in any level package that is stored on the Enigma's users home directory. But Lua commented XML levels can not be stored on Internet servers and cannot be online updated. Thus this format is good for level development, but the levels should be converted to the pure XML format for distribution. Please note that Enigma looks for XML levels first, and uses Lua levels only if no XML level could be found.

Another usage of Lua commented XML levels is the format backward compatibility to Enigma 0.92. As long as levels do not use new Enigma features you can include your levels in Enigma 0.92 level packages in this format.

As you may need to convert levels several times between the XML and the Lua format we do provide tools for conversion: ``xml2lua'` and ``lua2xml'`. Both are very simple Lua 5 scripts that you can execute as ``lua xml2lua demo_simple.xml > demo_simple.lua'` with a proper installed Lua 5 version. On Unix systems you can mark the scripts as executables and simply call ``xml2lua demo_simple.xml > demo_simple.lua'`.

Of course you can add the convertion algorithm as simple macros for your favorite editor. Please publish any editor macros you write.

As you fiddle with the XML metadata you may of course produce syntactical errors. You can validate your level by trying to start it with Enigma. XML errors are output as Lua errors are. In case the error messages are too long to read you may want to start Enigma from the command line with option ``--log'` and read the messages printed to the command line or written to the file ``stdout.txt'` on the current working directory for Windows systems.

Of course you can use any external XML validation tool, too. You just need to copy the schema file ``level.xsd'` on the same directory as the level itself. Possible validation tools are the Xerces-C sample application ``DOMPrint.exe -n -s -f -v=always level.xml'` or validating editors like Exchanger XML Lite. Such editors will provide you with selections of all possible elements and attributes at each position.

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

## 3.7 Update and Upgrade

Enigma is capable to load new level versions as we provide all necessary attributes in the <version> element.

If Enigma loads a new level version that differs just in the ``revision'` we speak of an ``update'`. Updates can be performed quite automatically and old versions can be replaced by the updates as they are guaranteed by the author to be compatible in scoring and dependencies. In the protected info element the author should provide a download address for automatic updates:

    <el:update el:url="http://myLevelServer.org/path/level_1.xml"/>

Attributes:

url, required

  A longtime valid complete address for update downloads of this level in the same score and release version.

If the author of a level introduces incompatibilities into the level he increases the release version of the level and stores it with a new filename. The download of such a new level version we call ``upgrade'`.

To publish the availability of a upgrade release the author should update the previous release with a final revision that just adds an upgrade element that announces the new release:

    <el:upgrade el:url="http://myLevelServer.org/path/level_2.xml" el:release="2"/>

Attributes:

url, required

  A longtime valid complete address for upgrade downloads of this level. A path to the new file.

release, required

  The release version of the upgrade.

As the author cannot update all distributed levels himself to announce the availability of the new release we added another upgrade element in the public section. Level administrators can use this element for the same purpose with the same syntax without modifying the authors protected section.

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

## 3.8 Libraries

Libraries are collections of Lua functions for reusage in many levels. To make use of a libray you have to declare it as an dependency as described in <compatibility>. If you preload the library that is all you have to do to use the library. Otherwise you can use the function enigma.LoadLib to load the library at a certain point of execution.

Enigma provides several very usefull libraries. You fill find them on the system path in the subdirectory ``levels/lib'`. Most of them are document in line. For ``ant'` you will find a seperate documentation file ``doc/ant_lua.txt'`.

In this section we will concentrate on the aspects of writing and maintaing libraries:

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

### 3.8.1 Writing a Library

Library files are nearly identical to level files. The main difference is the attribute ``el:type'` in the ``info'` element which should be set to ``library'`. All other elements and attributes have to be provided as they have to be for levels. Of course all scoring related attributes will never be evaluated and should be set to defaults.

Libraries may depend on others, they have to provide an id and a release number. Several releases of a library can coexist and they can be updated and upgraded if the necessary information is given. Of course libraries may contain document strings that can be localized if the ``i18n'` elements are provided.

The ``el:luamain'` element takes the complete Lua code as it does for levels. Lets have a look at the essential XML parts of a library:

    <?xml version="1.0" encoding="UTF-8" standalone="no" ?>
    <el:level xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://enigma-game.org/schema/level/1 level.xsd" xmlns:el="http://enigma-game.org/schema/level/1">
      <el:protected >
        <el:info el:type="library">
          <el:identity el:title="" el:id="lib/ant"/>
          <el:version el:score="1" el:release="1" el:revision="0" el:status="released"/>
          <el:author  el:name="Petr Machata"/>
          <el:copyright>Copyright © 2002-2003 Petr Machata</el:copyright>
          <el:license el:type="GPL v2.0 or above" el:open="true"/>
          <el:compatibility el:enigma="0.92">
            <el:dependency el:path="lib/natmaze" el:id="lib/natmaze" el:release="1" el:preload="false">
          </el:compatibility>
          <el:modes el:easy="false" el:single="false" el:network="false"/>
          <el:score el:easy="-" el:difficult="-"/>
        </el:info>
        <el:luamain><![CDATA[
        …
        ]]></el:luamain>
        <el:i18n/>
      </el:protected>
    </el:level>

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

### 3.8.2 Maintaining a Library

Libraries may exist in different releases and revisions. Library versions that just differ in the revision denote compatible versions. Library versions that introduce incompatibilities have to differ in the release number. But as existing leves may depend on the legacy behaviour of the older release both library release versions have to be maintained and distributed with Enigma at the same time.

To coexist these different library releases have to follow a strict naming scheme. Every library has a base name. In the example above it is ``lib/ant'`. The filename of a given release is the basename with addition of an underscore and the release number plus suffix xml. Thus release 2 of ``lib/ant'` has to be stored as ``lib/ant_2.xml'`.

If you look at the lib directory you may wonder that most library files are stored without release number addition to the basename. This is due to 0.92 Lua level format compatibility support. One, and of course only one, release of each library can be stored without release number addition to the basename. This version will be loaded from pure Lua levels that do not provide any information of the required library release.

In case a library file with complete filename is not present the default library file without release number addition will be loaded for XML load requests, too. But the future belongs to the new naming scheme and every new library should follow it from the beginning.

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

# 4. Objects

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

## 4.1 Floors

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

### 4.1.1 Common Floor Attributes

Standard attributes:

`friction`

  Overrides the default friction for this floor tile.

`mousefactor`

  Overrides the default mousefactor.

`force_x, force_y`

  Define horizontal and vertical flat forces on the floor. On fl-gradient, `force_x` and `force_y` are additive to the gradient's standard force.

Attributes connected to The 1.0-Fire System (all boolean):

`burnable`

  Sets if the floor may burn.

`ignitable`

  Sets if the floor gets ignited by explosions.

`secure`

  Sets if the floor gets securely ignited and/or heated by neighbors.

`eternal`

  Sets if the floor doesn't stop burning after awhile.

`noash`

  Sets if the floor doesn't leave `it-burnable_ash` behind.

`fastfire`

  Sets if the fire spreads fast.

`initfire`

  Sets if the floor starts burning on initialisation.

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

### 4.1.2 Special floor tiles

    fl-abyss
    fl-acblack
    fl-acwhite
    fl-bridge( type )
    fl-bridge-closed( type )
    fl-bridge-open( type )
    fl-dummy
    fl-gradient( type force )
    fl-gradient{1..16}( force )
    fl-ice
    fl-inverse
    fl-inverse2
    fl-nomouse
    fl-swamp
    fl-thief
    fl-water

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

### 4.1.3 Regular floor tiles

    fl-abyss_fake
    fl-black
    fl-bluegray
    fl-bluegreen
    fl-bluegreenx
    fl-brick
    fl-bumps
    fl-concrete
    fl-darkgray
    fl-dunes
    fl-floor_001
    fl-gravel
    fl-gray
    fl-hay
    fl-himalaya
    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-springboard
    fl-stone
    fl-stwood
    fl-stwood1
    fl-stwood2
    fl-tigris
    fl-trigger
    fl-white
    fl-wood
    fl-woven

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

### 4.1.4 fl-abyss

Kills marbles that roll onto it, unless they're protected by it-umbrella. st-wood: Wooden Stone transforms this floor into `fl-stwood`. Marbles may jump over fl-abyss with an it-spring[1/2/board]. Compare with it-abyss, fl-water and fl-swamp.

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

### 4.1.5 fl-ac[black/white]

Marbles on this floor are controlled by player 0 only (who has ac-blackball by default) respectively player 1 only (ac-whiteball by default). See it-changefloor for an item interacting with these floors.

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

### 4.1.6 fl-bridge

`fl-bridge` can be open (marbles fall into it) or closed (marbles may pass). The state can be changed via messages.

`fl-bridge` closes and re-opens automatically when a stone is pushed onto it. Thus st-wood: Wooden Stone and other stones don't fall into it, as they do on fl-abyss.

Attributes

`type`

  `a`, `x` or `y`

Messages

`open, close, openclose`

  as they say

`signal`

  change state, like `openclose`

Variants

`fl-bridge`

  open by default

`fl-bridge-open`
`fl-bridge-closed`

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

### 4.1.7 fl-dummy

Prints its Oxyd code when entered. Used for maintaining purposes. Compare with `st-dummy` (Oxyd Compatibility Stones) and `it-dummy` (System and Debug Items).

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

### 4.1.8 fl-gradient

Adds a horizontal, vertical or diagonal force to actors on it. The strength of the force is determined by `enigma.SlopeForce` (see Variables) or the attribute `force`. It is additive to the force determined by the `force_[x/y]`-attributes (see Common Floor Attributes).

Attributes

`force`

  overrides `enigma.SlopeForce`

`type`

  between 1 and 24, determines the direction of the gradient and its design

Direction of the forces to certain types: 1 and 21: south, 2 and 22: north, 3 and 23: east, 4 and 24: west, 5 and 9: south-east, 6 and 11: south-west, 7 and 10: north-east, 8 and 12: north-west.

Variants

`fl-gradient`

  type 1 by default

`fl-gradient1 .. fl-gradient12`

  type is 1..12

`fl-gradient13 .. fl-gradient16`

  types are 22, 21, 24 and 23

The latter four gradients don't show an outline like the first twelve: They all look identical, and similar to `fl-gray`. The remaining types show outlines that don't correspond to their forces (use them for tubes etc.).

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

### 4.1.9 fl-ice

Ice has very low friction and mousefactor, such that it's difficult to move on it. You can use it-pin and `enigma.IceFriction` (see Variables) to ease the friction.

Variants

`fl-ice`

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

### 4.1.10 fl-inverse

Inverses the mouse movements (negative `mouseforce`).

Variants

`fl-inverse`
`fl-inverse2`

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

### 4.1.11 fl-nomouse

This floor prevents a player from controlling the marble (`mouseforce = 0`).

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

### 4.1.12 fl-space

This floor prevents a player from controlling the marble (`mouseforce = 0`), but in contrast to fl-nomouse there also is no friction, such that marbles seldom get stuck on space.

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

### 4.1.13 fl-space-force

This floor has (like fl-space) no friction and no mouseforce, but adds a vertical force of the amount given in `enigma.FlatForce`. This is obsolete since you can use `fl-space` with `force_y`-attribute (see Common Floor Attributes). Note however, that the `force_y`-attribute of `fl-space-force` is overriden by `enigma.FlatForce`.

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

### 4.1.14 fl-swamp

Kills marbles that roll onto it, unless they're protected by it-umbrella. st-wood: Wooden Stone transforms this floor into `fl-stwood`.

Once in the swamp, marbles constantly sink with the speed given by `enigma.SwampSinkSpeed` (see Variables) and may raise again when moving fast enough (compare with fl-water and fl-abyss).

Marbles may jump over fl-swamp with an it-spring[1/2/board].

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

### 4.1.15 fl-thief

This floor steals one item from the players inventory. It looks like the simple floor `fl-bluegray`. Compare with st-thief: Thief Stone for details.

Like `st-thief`, `fl-thief` can be deactivated with st-chess_[black/white]: Chess (Knight) Stone, leaving an it-bag behind filled with the items the thief stole from the actors (plus possibly the item that already lay on the floor if it could be picked up; if it is a static item, no `it-bag` is produced).

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

### 4.1.16 fl-water

Kills marbles that roll onto it, unless they're protected by it-umbrella. st-wood: Wooden Stone transforms this floor into `fl-stwood`.

Once in the water, marbles constantly sink with the speed given by `enigma.WaterSinkSpeed` (see Variables). In constrast to fl-swamp they can't raise again, as long as they're in the water. Also compare with fl-abyss.

Marbles may jump over fl-water with an it-spring[1/2/board].

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

## 4.2 Items

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

### 4.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-booze-broken
    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( action target )
    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( essential )
    it-hstrip
    it-inversesensor( action target )
    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( action target )
    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( target length strength minlength scissor)
    it-seed
    it-seed_nowood
    it-seed_volcano
    it-sensor( action target )
    it-shogun-l( action target )
    it-shogun-m( action target )
    it-shogun-s( action target )
    it-signalfilter0( action target )
    it-signalfilter1( action target )
    it-spade
    it-spoon
    it-spring1
    it-spring2
    it-springboard
    it-squashed
    it-surprise
    it-sword
    it-tinyhill
    it-tinyhollow( essential )
    it-trigger( action target 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 interval )
    it-wormhole-off( on targetx targety strength range interval )
    it-wrench
    it-yinyang

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

### 4.2.2 System and Debug Items

There are several items that are not meant as items in the usual way:

`it-1pkillstone, it-2pkillstone`

  Kills the stone on the same tile in single-player mode (resp. multi-player mode). Unused due to missing networking capability of Enigma.

`it-bridge-oxyd, it-bridge-oxyd_active`

  Used for Oxyd compatibility to animate bridges. Use fl-bridge instead.

`it-debris`

  Animation of a breaking floor. Creates fl-abyss, then kills itself.

`it-dummy`

  Prints its own oxyd code when picked up or used. Compare fl-dummy and `st-dummy` (Oxyd Compatibility Stones).

`it-easykillstone`

  Kills the stone on the same tile in easy mode; if it is one of st-death: Skull Stones, st-flash: Flash Stone or st-thief: Thief Stone, it is transformed to st-plain: Plain Stones instead.

`it-easykeepstone`

  Kills the stone on the same tile in normal mode; no exceptions.

`it-explosion[1,2,3]`

  Sets a visual explosion effect of strength 1 (no remainder), 2 (`it-hollow` remains, see Hills and Hollows) or 3 (`it-debris` remains, shattering the floor).

`it-oxyd5f`

  When a message is sent to this item, it performs its `action/target`-pair. Used for Oxyd compatibility only.

`it-signalfilter[0/1]`

  Transforms signal 1 to signal 0 or 1, forgets signal 0. Used for Oxyd Compatibility only.

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

### 4.2.3 Hills and Hollows

`it-hill` and `it-hollow` create small hills and hollows in the floor, `it-tinyhill` and `it-tinyhollow` are smaller versions. The strength of the slope is given by `enigma.HoleForce` (see Variables).

When a stone is pushed over them or an it-spade is used on them, they decrease their size: `it-hill` and `it-hollow` become `it-tinyhill` and `it-tinyhollow`, the latter two disappear completely.

Messages

`trigger`

  Converts a hill to a hollow and vice versa.

`shovel`

  Hills and hollows are replaced by their tiny versions; tiny ones are removed.

`signal`

  0: become `it-hollow` or `it-tinyhollow`, 1: become `it-hill` or `it-tinyhill`

Attributes

`essential`

  only `it-tinyhollow` and `it-hollow`, see below

In Meditation Levels

If all existing ac-whiteball-small are inside hollows (`it-hollow` or `it-tinyhollow`), the level succeeds.

Use the `essential`-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 (1 means this hollow must be filled with a whiteball to end 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.

Note that hollows might appear or disappear during the game, they are handled the same way as descriped.

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

### 4.2.4 Fire and Extinguisher

Compare The 1.0-Fire System.

There are six items special to the fire system:

Use `it-extinguisher` to set `it-burnable_fireproof`. After using it once, it becomes `it-extinguisher_medium` which guards less floor, and itself becomes `it-extinguisher_empty`, which can be laid down again.

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

### 4.2.5 it-abyss

Use this to set an invisible alternative to fl-abyss. Note however, that st-wood: Wooden Stone doesn't fill `it-abyss` as it does with `fl-abyss`. Marbles may jump over `it-abyss` with an `it-spring[1/2/board]`, in contrast to it-death. Also compare to it-booze-broken.

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

### 4.2.6 it-bag

As long as `it-bag` is at the first place in the inventory, new items are put into the bag instead of the inventory, until the bag is full (13 items). `it-bag` can be dropped. When picked up again, items from the bag are put back into inventory (until it is full).

`it-bag` is created by st-thief: Thief Stone and fl-thief when they're captured by st-chess_[black/white]: Chess (Knight) Stone.

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

### 4.2.7 it-banana

`it-banana` transforms into it-cherry when hit by a laser beam, and into it-squashed when a stone is pushed over it.

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

### 4.2.8 it-blackbomb

This item can't be picked up, but received from st-bombs: Bombstones. It can be ignited by lasers, fire and other explosions (other `it-blackbomb`, it-whitebomb, it-dynamite, exploding `st-bombs` above them), messages "ignite", "expl" and "explosion" and by pushing stones over them (except for st-shogun-<sml>: Shogun Stones and, in Oxyd compatibility mode, st-wood: Wooden Stone).

When exploding, `it-blackbomb` ignites or destroys neighboring items and destroys its own floor tile by replacing it against `fl-abyss`. See also it-whitebomb for a stronger version.

Messages

`ignite, expl`

  ignite, then explode

`explode`

  explode instantly

Variants

`it-blackbomb`
`it-blackbomb_burning`

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

### 4.2.9 it-blocker

This item is the shrinked form of st-blocker: Shrinkable Blocker Stone. When it is hit by st-bolder: Bolder (or Arrow) Stone, it becomes `st-blocker` again. It can be destroyed with it-brake.

Messages

`trigger, openclose`

  If shrinked, grow. Otherwise: change internal state, only sensible while a stone is on top of `it-blocker`.

`open, close`

  These are complicated, but in most cases `close` makes the item grow. Consult the source code for details.

`signal`

  1: open, 0: close

Variants

`it-blocker`
`it-blocker-new`

  doesn't grow at once when `st-bolder` just arrives (acts as if recently shrinked)

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

### 4.2.10 it-booze

When used, the actor becomes slower for a short period of time. Note that `it-booze` is still under development, behaviour might be changed.

When hit by a stone, `it-booze` transforms into it-booze-broken.

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

### 4.2.11 it-booze-broken

The remnants of it-booze after pushing a stone over it. Kills a marble that touches it, but not when it is jumping with it-spring[1/2/board] or protected by it-umbrella, compare it-abyss and it-death. Can be removed with it-brush while jumping over it or otherwise protected.

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

### 4.2.12 it-brake

When used, this item creates an st-brake: Brake, which itself can be picked up as `it-brake` again. It can be used to destroy it-blocker.

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

### 4.2.13 it-brush

This item can be used to make some invisible stones visible (`st-actorimpulse_invisible` (see st-actorimpulse: Bumper Stones), `st-break_invisible` (see Breakable Stones), `st-stonebrush` (see st-invisible: Invisible Stones) and to remove debris from the level (it-cross, it-squashed, it-booze-broken, `it-glasses-broken` (see it-glasses), `it-burnable_ash`, `it-burnable_fireproof` (see Fire and Extinguisher)).

In addition, this item can be used to transform `st-firebreak` into `st-plain` and `st-firebreak_move` into `st-plain_move` (see st-firebreak[_move]: Firebreakable Stones and st-plain: Plain Stones).

The Per.Oxyd-compatibility stone `st-yinyang3` (see st-yinyang: Yin-Yang Stones) must be touched with an `it-brush` or it-magicwand in order to activate it.

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

### 4.2.14 it-changefloor

When in multi-player mode, this item exchanges `fl-acblack` and `fl-acwhite` below it after an actor has left it (see fl-ac[black/white]). This way the marble can't roll back as easily as before. Try the original Per.Oxyd Link Level 69 to see this scarcely used item in action.

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

### 4.2.15 it-cherry

When used, the marble becomes invisible for a short time. Some benefits of this are that rotors and tops can't find it and it can walk through glass. There are some different glassstones, and not all may be passed when invisible. For details, see Glassstones. When a stone is pushed over `it-cherry`, it becomes it-squashed.

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

### 4.2.16 it-coffee

`it-coffee` is supposed to pause the game. Not implemented yet.

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

### 4.2.17 it-coin

Activates st-coinslot.

When hit by a stone, `it-coin2` transforms into `it-coin4` and `it-coin1` into `it-coin2`. A laser beam transforms `it-coin1`, `it-coin2`, and `it-coin4` into it-umbrella, it-hammer, and it-extralife.

Attributes

`value`

  Determines how long st-coinslot keeps activated. Defaults: `it-coin1` 3.0, `it-coin2` 6.0, `it-coin4` 12.0.

Variants

`it-coin1`
`it-coin2`
`it-coin4`

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

### 4.2.18 it-crack

Represents cracks in the floor. `it-crack0` is invisible and grows to `it-crack1`, `it-crack2`, `it-crack3`, after which the floor desintegrates to fl-abyss.

The `brittleness`-attribute and `enigma.Brittleness`-variable determine the probability that a crack grows when an actor enters. When the crack grows, it spreads to neighboring unoccupied tiles. If you want to suppress this, set `enigma.Brittleness` to 0.0 and the `brittleness`-attribute of the cracks to 0.5 (or whatever you like, also see Variables).

Attributes

`type`

  0, 1, 2, or 3

`fixed`

  0: crack can grow, 1: crack doesn't grow

`brittleness`

  overrides `enigma.Brittleness`

Messages

`crack`

  grow by one step

Variants

`it-crack0`
`it-crack1`
`it-crack2`
`it-crack3`

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

### 4.2.19 it-cross

Marks an interesting spot, can be created with an it-pencil and removed with it-brush.

When a marble remains on the cross for at least 10 seconds, `it-cross` performs its `action/target` (only once, not every 10 seconds). Similar functions have it-trigger and it-sensor.

Attributes

`action, target`

  as usual

Messages

`brush`

  remove `it-cross`

`signal`

  performs `action/target` with inverted signal-data, works only in Per.Oxyd-compatibility mode

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

### 4.2.20 it-death

Kills a marble that touches it, even when it is jumping with it-spring[1/2/board], compare it-abyss and it-booze-broken. it-umbrella protects the marble.

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

### 4.2.21 it-document

This item looks like a piece of paper and contains text messages that can be displayed by activating the item. It is destroyed by explosions (like it-blackbomb, it-whitebomb, st-bombs: Bombstones and also it-dynamite).

Attributes

`text`

  The message to be displayed.

Messages

`expl, bombstone`

  destroy

`ignite`

  destroy if not in Oxyd compatibility mode

Example

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

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

### 4.2.22 it-drop

Transforms the marble into an ac-rotor for a short time. Can be used multiple times.

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

### 4.2.23 it-dynamite

`it-dynamite` can be ignited by dropping it, by lasers, fire, other explosions (it-blackbomb, it-whitebomb, other `it-dynamite` and st-bombs: Bombstones). While burning, it can't be picked up. During explosion, it ignites neighbouring items and leaves an `it-hollow` behind (see Hills and Hollows).

Messages

`ignite, expl, bombstone`

  ignite, then explode

`explode`

  explode instantly

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

### 4.2.24 it-extralife

Adds a life to the player's inventory.

A laser beam transforms this into it-glasses, and `it-extralife` itself results from `it-coin4` (see it-coin).

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

### 4.2.25 it-flag[black/white]

Marks the place, where ac-blackball respectively ac-whiteball respawn when killed. For this purpose, they have to be used at least once.

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

### 4.2.26 it-floppy

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

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

### 4.2.27 it-glasses

While `it-glasses` is in the inventory, hollow stones become invisible and `st-death_invisible` becomes visible (see st-death: Skull Stones).

`it-glasses` breaks when a stone is pushed over it, and becomes the inactive version `it-glasses-broken`. `it-glasses` is the result of the laser transformation of it-extralife.

Variants

`it-glasses`
`it-glasses-broken`

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

### 4.2.28 it-hammer

The hammer is used to destroy some stones, see Breakable Stones and st-lightpassenger: Light Passenger. It also transforms into it-sword when hit with a laser beam and is itself laser-transformation-result of it-sword and `it-coin2` (see it-coin).

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

### 4.2.29 it-[h/v]strip

These items cover a small strip of the ground below them and provide a narrow bridge for the marble to safely pass fl-abyss, fl-swamp, fl-water, or any other floor.

Variants

`it-hstrip`

  horizontal

`it-vstrip`

  vertical

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

### 4.2.30 it-key

Used to activate st-key: Key (or Lock) Stone.

Attributes

`keycode`

  see st-key: Key (or Lock) Stone

Variants

`it-key`

  `keycode` is 1

`it-key_a`

  `keycode` is 1

`it-key_b`

  `keycode` is 2

`it-key_c`

  `keycode` is 3

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

### 4.2.31 it-landmine

Explodes when hit by a marble or by a stone, shatters the marble, and leaves an `it-hollow` behind (see Hills and Hollows).

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

### 4.2.32 it-magicwand

- Changes direction of a oneway stone (st-oneway: One-way Stones).
- Changes direction of a bolder stone (st-bolder: Bolder (or Arrow) Stone).
- Scrambles blue puzzle stones instead of pushing, lets complete clusters explode (st-puzzle: Puzzle Stones).
- Makes `st-brick_magic` transparent (st-brick_magic: Magic Brick Stone).
- Makes `st-invisible_magic` visible and non-transparent (st-invisible: Invisible Stones).
- Makes rubberband stones movable (st-rubberband: Rubberband Stone).
- Changes colour of a chess stone (st-chess_[black/white]: Chess (Knight) Stone).
- Activates `st-yinyang3` (st-yinyang: Yin-Yang Stones).

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

### 4.2.33 it-magnet

Attracts actors in its `range` with a force proportional to `strength` and the inverse of the distance. The magnet can be on or off.

Attributes

`on`

  `TRUE` or `FALSE`, see variants below

`strength`

  default: 30

`range`

  default: 1000 (quasi infinite)

Messages

`on, off, onoff`

  as usual

`signal`

  0: off, 1: on

Variants

`it-magnet`

  by default off

`it-magnet-on`
`it-magnet-off`

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

### 4.2.34 it-odometer

Supposed to measure the route the marble has rolled since picking up `it-odometer`. Not implemented yet.

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

### 4.2.35 it-pencil

Try to scratch an it-cross into the floor, pencil is lost after this. Scratching onto ice results in a crack, scratching while flying or on certain floors results in dropping the pencil.

In addition, this item can be used to transform `st-plain` into `st-firebreak` and `st-plain_move` into `st-firebreak_move` (see st-plain: Plain Stones and st-firebreak[_move]: Firebreakable Stones).

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

### 4.2.36 it-pin

While in inventory, `it-pin` increases the friction of the floor. Used in conjunction with fl-ice.

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

### 4.2.37 it-pipe

Pipes are used by st-mail: Mail Stones to transport items over large distances or onto unreachable grounds. Pipes can be destroyed by explosions (like from it-blackbomb or it-whitebomb).

Variants

`it-pipe-e`
`it-pipe-w`
`it-pipe-s`
`it-pipe-n`
`it-pipe-es`
`it-pipe-ne`
`it-pipe-sw`
`it-pipe-wn`
`it-pipe-h`

  horizontal

`it-pipe-v`

  vertical

The first four variants depict endpoints of the pipe, they're of no use to st-mail: Mail Stones other than blocking the endpoint.

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

### 4.2.38 it-puller

When dropped, these items pull a stone from the direction they point to to their own position. They explode during this, shattering marbles near them.

Variants

`it-puller-e`
`it-puller-w`
`it-puller-s`
`it-puller-n`

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

### 4.2.39 it-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 it-flag[black/white].

Multi player levels:

  Both marbles exchange their positions. In contrast to it-yinyang, the positions are exchanged, not the players.

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

### 4.2.40 it-rubberband

Connects the actor using it with a target. This target can be an other actor or a stone. The target is determined by its name-attribute. If the target doesn't exist, the it-rubberband will be dropped.

Attributes

`target`

  The target to connect with. It has to be an the name of an other actor or a stone.

`length`

  The natural length of the rubberband (default: 1)

`strength`

  The strength of the rubberband (default: 10)

`minlength`

  The minimal length of the rubberband (default: 0)

`scissor`

  Boolean value defining if already existing rubberbands to the actor should be cut off. (Default: false)

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

### 4.2.41 Examples

    set_stones("st-glass", 5, 5, {name="MyRubberTarget1"})
    …
    -- When used, this it-rubberband will connect the actor with the glassstone.
    set_item("it-rubberband", 3, 5, {target="MyRubberTarget1"})

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

### 4.2.42 it-seed

There are three different seeds from which stones can grow: `it-seed` creates st-wood: Wooden Stone, `it-seed_nowood` creates `st-greenbrown-growing`, which results in the unmovable simple stone `st-greenbrown`, and `it-seed_volcano`, which creates an st-volcano: Volcano. The name of the seed is inherited to the new stone.

In Oxyd-Magnum-compatibility mode, `it-seed` under `st-grate1` (see st-grate: Grates) grows to the simple floor `fl-stwood` instead of destroying the grate. In all other cases, stones at the position of the seed are replaced by the new stone.

Seeds start growing on dropping them, on laser beams, stone hits and the `grow` and `signal`-messages.

Messages

`grow, signal`

  start growing

Variants

`it-seed`
`it-seed_nowood`
`it-seed_volcano`

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

### 4.2.43 it-sensor

This is an invisible, quiet and less extensive version of it-trigger. Whenever an actor enters it, it performs its `action/target`-pair, with second data `TRUE` for `it-sensor` and `FALSE` for `it-inversesensor`. Also compare it-cross.

Attributes

`action, target`

  as usual

Variants

`it-sensor`
`it-inversesensor`

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

### 4.2.44 it-shogun

Performs its `action/target`-pair when an st-shogun-<sml>: Shogun Stones of fitting size covers it.

Attributes

`target, action`

  as usual

Messages

`noshogun`

  deactivate

`shogun ....`

  used to activate or deactivate `it-shogun`

Variants

`it-shogun-s`
`it-shogun-m`
`it-shogun-l`

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

### 4.2.45 it-spade

Decreases the size of an `it-hill` or `it-hollow` and removes `it-tinyhill` and `it-tinyhollow`, see Hills and Hollows.

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

### 4.2.46 it-spoon

Shatters the marble. Note that in contrast to F3, `it-spoon` only shatters the marble using it, not all of them.

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

### 4.2.47 it-spring[1/2/board]

Springs let marbles jump, e.g. over fl-water, fl-swamp, fl-abyss, it-abyss, and laser beams. Note that you can't jump over stones or fire (Fire and Extinguisher), and cannot pass st-grate: Grates during the jump, even if you could on the ground.

You can pick up and use `it-spring1` and `it-spring2`. You keep the former in the inventory, but in general drop `it-spring2` when using. `it-springboard` is fixed to the ground, you can only use it where it is.

Variants

`it-spring1`
`it-spring2`
`it-springboard`

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

### 4.2.48 it-squashed

The remnants of it-cherry or it-banana after pushing a stone over them. Can be removed with it-brush.

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

### 4.2.49 it-sword

Used to neutralize st-knight: Knight Stone. Laser-transforms into it-hammer and vice versa.

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

### 4.2.50 it-trigger

When pushed down by an actor or a stone, this trigger performs its `action/target`-pair, and a second time when it is released again. As second data it uses `TRUE` when pressed, and `FALSE` if not.

Floating stones do not hold down a trigger, except of the tunnel puzzle-stone (see st-puzzle: Puzzle Stones).

`it-trigger` can be initialized as invisible with attribute `invisible = TRUE`. Note that it still produces its click-sounds. For a simpler version, see it-sensor. Also compare it-cross.

Attributes

`invisible`

  0.0 (visible) or 1.0 (invisible), by default 0.0

`action, target`

  as usual

Messages

`signal`

  perform `action/target` according to second data

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

### 4.2.51 it-umbrella

`it-umbrella` temporarily protects a marble from st-death: Skull Stones, st-knight: Knight Stone, st-thief: Thief Stone, fl-abyss, fl-water, fl-swamp, fl-thief, it-death, it-abyss, it-booze-broken, explosions, moving stones and the "shatter" and "fall"-messages - in other words: from all lethal situations and thiefs.

`it-umbrella` can be destroyed by laserlight and is the result of laser-transforming an `it-coin1` (see it-coin).

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

### 4.2.52 it-vortex

Vortices, like it-wormhole, 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.

In a further contrast to wormholes, vortices can be open or closed, and when marbles exit, they jump out of them. Furthermore, connecting vortices in a cycle works as expected and is standard (though not necessary), whereas connecting wormholes cyclic results in an error-message (as long as their `interval`-message isn't used).

Attributes

`targetx, targety`

  destination of teleport

`autoclose`

  not implemented yet, see variants below

Messages

`open, close, openclose`

  as they say

`trigger`

  identical to `openclose`

`signal`

  0: close, 1: open

`arrival`

  used by the teleport-system, don't use in levels

Variants

`it-vortex-open`

  This vortex starts open and doesn't close when an actor jumps out of it. Default teleportation target is the own position, thus an actor keeps jumping in and out of it until moved away.

`it-vortex-closed`

  This vortex starts closed and closes again when an actor jumps out of it. If you want to create an open vortex that closes after an actor, send a `trigger`-message to `it-vortex-closed` on initialization.

Note that `it-vortex-open` and `it-vortex-closed` do behave differently, in contrast to their names.

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-open", 1, 1)
    set_item ("it-vortex-open", 10,1)
    set_item ("it-vortex-open", 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] | [ ? ]

### 4.2.53 it-weight

Heightens the mass of the marble (making it more difficult to accelerate and guide) and can't be dropped. Note that it can still be stolen by st-thief: Thief Stone or fl-thief and mailed away with st-mail: Mail Stones.

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

### 4.2.54 it-whitebomb

This item is the stronger version of it-blackbomb, and can't be picked up also. It can be ignited by lasers, fire and other explosions (it-blackbomb, other `it-whitebomb`, it-dynamite), messages "ignite", "expl" and "explosion" and by pushing stones over them (except for st-shogun-<sml>: Shogun Stones and, in Oxyd compatibility mode, st-wood: Wooden Stone).

When exploding, `it-whitebomb` ignites or destroys neighbouring items and destroys all nine neighbouring floor tiles by replacing them with `fl-abyss`.

Messages

`ignite, expl`

  ignite, then explode

`explode`

  explode instantly

Note that, in contrast to it-blackbomb, white bombs are not removed from st-bombs: Bombstones-explosions.

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

### 4.2.55 it-wormhole

Teleports actors to the coordinates given by the `targetx`- and `targety`-attributes (compare it-vortex). In addition, wormholes have a variable force field, which can be switched on and off.

After teleporting an actor, the wormhole's teleporting ability is switched off for a time period given by the `interval`-attribute, which is by default 0.0.

Attributes

`targetx, targety`

  exit of the wormhole

`strength, range`

  strength and range of the force field

`on`

  whether force field is on

`interval`

  minimal delay between two teleports

Messages

`on, off, onoff`

  as usual

`signal`

  0: off, 1: on

Variants

`it-wormhole`
`it-wormhole-off`

  wormhole without force field

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

### 4.2.56 it-wrench

Changes direction of st-rotator: Rotator Stone.

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

### 4.2.57 it-yinyang

Toggles between players. Compare it-ring in multiplayer mode.

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

## 4.3 Stones

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

### 4.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-blue-sand
    st-bluegray
    st-bluegray_hole
    st-brick
    st-brownie
    st-bumps
    st-camouflage
    st-dummy
    st-fakeoxyd( blinking )
    st-glass
    st-glass_move
    st-glass[123]
    st-glass[12]_hole
    st-glass[12]_move
    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-redrock
    st-rock{1..10}
    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( force hit_factor hit_distortion_[xx/xy/yx/yy] )
    st-actorimpulse_invisible( force hit_factor hit_distortion_[xx/xy/yx/yy] )
    st-bigbluesand-<nesw>
    st-bigbrick-<nesw>
    st-black{1..4}
    st-blackballs
    st-block
    st-blocker
    st-blocker-growing
    st-bolder( direction )
    st-bolder-[ensw]( direction )
    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-chess_black( color direction1 direction2 )
    st-chess_white( color direction1 direction2 )
    st-coffee
    st-coinslot( on action target )
    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-fakeoxyda
    st-fart
    st-firebreak
    st-firebreak_move
    st-flash( hit_factor hit_distortion_[xx,xy,yx,yy] )
    st-flhay
    st-floppy( action target on )
    st-flrock
    st-fourswitch( action target on )
    st-grate[123]
    st-greenbrown-growing
    st-invisible
    st-invisible_magic
    st-key( action target on keycode )
    st-key_[abc]( action target on keycode )
    st-knight
    st-laser( dir on )
    st-laser-[ensw]( dir on )
    st-laserbreak
    st-laserswitch( action target inverse )
    st-lasertimeswitch( action target inverse delay )
    st-lightpassenger( interval friction_factor gradient_factor )
    st-magic
    st-mail-[ensw]
    st-mirror*( movable transparent orientation )
    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( orientation )
    st-oneway-[nesw]( orientation )
    st-oneway_black( orientation )
    st-oneway_black-[nesw]( orientation )
    st-oneway_white( orientation )
    st-oneway_white-[nesw]( orientation )
    st-oxyd( flavor color static )
    st-oxyd-0x18
    st-peroxyd-0xb8
    st-peroxyd-0xb9
    st-plain
    st-plain_break
    st-plain_breaking
    st-plain_cracked
    st-plain_falling
    st-plain_hole
    st-plain_move
    st-pmirror( transparent movable orientation )
    st-polarswitch( on )
    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 minlength scissor)
    st-scissors( action target )
    st-shogun-<sml>( holes )
    st-spitter( hit_factor hit_distortion_[xx/xy/yx/yy] )
    st-stone_break
    st-stonebrush
    st-stoneimpulse
    st-stoneimpulse-hollow
    st-stoneimpulse_movable
    st-surprise
    st-swap
    st-switch( action target on )
    st-switch_black( action target on )
    st-switch_white( action target on )
    st-thief
    st-timer( action target on interval loop invisible )
    st-timeswitch( action target delay inverse )
    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] | [ ? ]

### 4.3.2 Glassstones

There are a few kinds of glassstones, all similar, but with different details. Some of them may be passed after the use of an it-cherry, others will be just pushed. Some are transparent for lasers, but not all! This table shows their exact properties.

stone: | actor is visible: | actor is invisible: | lasertransparent:
--- | --- | --- | ---
st-glass | - | pass | yes
st-glass_move | push | pass | yes
st-glass1 | - | pass | yes
st-glass1_move | push | push | yes
st-glass1_hole | pass | pass | yes
st-glass2 | - | pass | no
st-glass2_move | push | push | no
st-glass2_hole | pass | pass | yes
st-glass3 | - | - | yes
st-polarswitch (on) | toggle | pass | yes
st-polarswitch (off) | toggle | pass | no
st-beads | - | pass | no

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

### 4.3.3 Breakable Stones

A list of all breakable stones and what may break them. Messages are given in quotation marks. "pyro" is short for dynamite, bombs, bombstones, "ignite", "expl" and "bombstone".

`st-stone_break, st-rock3_break, st-break_gray`

  hammer, laser, pyro

`st-break_acblack`

  ac-blackball with hammer, laser, pyro

`st-break_acwhite`

  ac-whiteball with hammer, laser, pyro

`st-break_bolder`

  hammer, laser, bolder, "trigger", (pyro?)

`st-break_invisible`

  hammer after using a brush

`st-laserbreak`

  laser, pyro

`st-rock3_movebreak`

  hammer, pyro; this stone is movable

`st-plain_break`

  hammer, laser, pyro; falls into fl-abyss

`st-plain_cracked`

  hammer, pyro

`st-plain_move`

  pyro; this stone is movable; falls into fl-abyss, fl-water and fl-swamp; see also st-plain: Plain Stones

`st-bug`

  ac-bug

`st-breaking, st-plain_breaking`

  breaks instantly, looks like `st-rock3`

`st-fart`

  hammer, laser; see also st-fart: Fart Stone

`st-bombs`

  bombs, bombstones, "expl", "bombstone"; see also st-bombs: Bombstones

`st-brake`

  laser, bombs, "expl"; see st-brake: Brake

`st-puzzle`

  see st-puzzle: Puzzle Stones

`st-volcano_active`

  hammer; see st-volcano: Volcano

`st-lightpassenger`

  hammer when active and trapped; see st-lightpassenger: Light Passenger

`st-firebreak`

  fire near the stone; see also st-firebreak[_move]: Firebreakable Stones

`st-firebreak_move`

  fire under the stone; movable; falls into fl-abyss, fl-water and fl-swamp; see also st-firebreak[_move]: Firebreakable Stones

For the mentioned objects see it-hammer, it-dynamite, it-blackbomb, st-bombs: Bombstones, st-bolder: Bolder (or Arrow) Stone, it-brush. Also compare st-plain: Plain Stones, as `st-plain_cracked` results from `st-plain` when hit by a laser beam, and `st-plain[_move]` can be transformed into and out of `st-firebreak[_move]`.

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

### 4.3.4 Oxyd Compatibility Stones

`st-magic` disappears when hit strong enough.

`st-dummy` prints its own Oxyd code when hit. Compare `it-dummy` (System and Debug Items) and fl-dummy.

`st-peroxyd-0xb8`, `st-peroxyd-0xb9` and `st-oxyd-0x18` just seem to destroy themselves on creation, the former two creating `fl-normal` beneath them. Their purpose in the original games is unknown.

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

### 4.3.5 st-actorimpulse: Bumper Stones

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

Attributes

`force`

  factor of the transmitted force (overrides `enigma.BumperForce`)

`hit_factor`

  factor of the transmitted force (overrides `enigma.BumperForce` and `force`)

`hit_distortion_xx, hit_distortion_xy, hit_distortion_yx, hit_distortion_yy`

  define a matrix to be applied to the force (default `((1,0),(0,1))`)

Variants

The invisible variant, `st-actorimpulse_invisible` can be "painted" with an it-brush.

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

### 4.3.6 st-big[brick/bluesand]: Big Stones

These stones are used to construct big clusters of stones that visually seem like one big stone. Though mainly decorative, they also have a small special ability, as they are the only stones that can't be swapped with st-swap: Swap Stone or st-pull: Pull Stone (besides st-oxyd: Oxyd Stones with true `static`-attribute).

Attributes

`connections`

  A number between 1 an 16. Each bit in (connections-1) corresponds to an open face of the stone. You will normally simply use one of the Lua constants `PUZ_0001` to `PUZ_1111`.

Variants

There are two families of big stones, that differ in design: `st-bigbrick-<nesw>` (similar to `st-brick`) and `st-bigbluesand-<nesw>` (similar to `st-blue-sand`).

The term `<nesw>` denotes all non-empty substrings of `nesw`, describing the directions to which the single parts are open. Examples: `st-bigbluesand-nw` is a blue stone with border on the south and east side, `st-bigbrick-esw` is a brick-type stone which connects to the east, south and west, and has a border on the north side.

`st-bigbrick` and `st-bigbluesand` without suffix are not defined. Use `st-brick` and `st-blue-sand` to set single stones of these designs. Note however, that these stones both are swappable and pullable like normal stones.

See st-puzzle: Puzzle Stones for another kind of cluster-building stones.

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

### 4.3.7 st-[black/white]: Black and white stones

These stones only let black respectively white marbles pass.

Variants

`st-black` and `st-white` come in four flavors each: `st-black1` and `st-white1` are not transparent at all, `…2` has a diagonal bar, `…3` a cross and `…4` only consists of a black or white frame.

See st-grate: Grates for further stones which only special actors may pass.

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

### 4.3.8 st-[black/white]balls: Blackballs and Whiteballs Stones

Mainly used decorative, this stone also has a special function: When it receives a message from a stone, which is just hit by a black (resp. white) marble, it sends signal 1 to the neighbouring stones west and east of it and 0 to north and south; or vice versa, depending on the position of the message-sending stone.

A typical construction for this is an `st-blackballs` surrounded by st-door: Doors and it-sensor, with `st-blackballs` as target of the action of `it-sensor`. When in this situation a black marble hits one of the closed doors, the door lets `it-sensor` perform its action, sending a message to `st-blackballs`. This then opens the knocked door and the door in the opposite direction, while closing the doors in the perpendicular directions. However, when `it-sensor` triggers because of the marble entering it, `st-blackballs` won't trigger as there is no collision causing this event.

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

### 4.3.9 st-block: Solid Block

This stone is movable and sinks on fl-abyss, fl-water and fl-swamp.

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

### 4.3.10 st-blocker: Shrinkable Blocker Stone

This stone shrinks to it-blocker when hit by an st-bolder: Bolder (or Arrow) Stone and vice versa.

Messages

`trigger, openclose, open, close`

  shrink (open) / grow (close)

`signal`

  1: shrink, 0: grow

Note that `st-blocker` becomes a new object when shrinking, such that the messages `close` and `signal (0)` only make sense during transformation.

Variants

`st-blocker`
`st-blocker-growing`

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

### 4.3.11 st-bolder: Bolder (or Arrow) Stone

This stone runs in the direction given by the arrow on its picture. When a stone blocks its way, it triggers it (e.g. st-oxyd: Oxyd Stones, st-stoneimpulse: Impulse Stones), marbles are shattered.

Bolder stones fall into fl-abyss, but cross fl-water unchanged. it-magicwand and lasers reverse its direction. st-rotator: Rotator Stone changes its direction according to the rotators direction.

Attributes

`direction`

  `EAST`, `NORTH`, `SOUTH` or `WEST`

Messages

`direction`

  Change direction to the direction in the second argument, e.g. `SendMessage(mystone, "direction", WEST)`.

Variants

`st-bolder`

  default direction is `NORTH`

`st-bolder-w`
`st-bolder-s`
`st-bolder-e`
`st-bolder-n`

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

### 4.3.12 st-bombs: Bombstones

When hit, `st-bombs` adds an it-blackbomb to the inventory. It can be destroyed with explosions from it-blackbomb, it-whitebomb and other bombstones (see Breakable Stones). When exploding, it ignites items below it. It also ignites it-dynamite beneath it, but not `it-blackbomb` or `it-whitebomb`.

Messages

`expl, bombstone`

  destroy stone

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

### 4.3.13 st-brake: Brake

This stone can be picked up as item it-brake. It can be used to block st-bolder: Bolder (or Arrow) Stone. It destroys it-blocker and can itself be destroyed by lasers and explosions from bombs (it-blackbomb, it-whitebomb).

Messages

`expl`

  destroy stone

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

### 4.3.14 st-brick_magic: Magic Brick Stone

At first sight identical with `st-brick`, this stone becomes transparent when hit with an it-magicwand.

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

### 4.3.15 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. For solid, yet invisible stone-types see st-invisible: Invisible Stones.

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

### 4.3.16 st-charge: Charge Stones

When hit, the marble is provided with a constant electrostatic charge, given by the `charge`-attribute of `st-charge`. The charge is confined to be between -1.0 and +1.0. Actors with charges are drawn together respectively pushed apart by a force given by multiplication of their charges and the factor `enigma.ElectricForce` (see Variables) and divided by their relative distance.

Attributes

`charge`

Variants

`st-chargeplus`

  charge +1.0

`st-chargeminus`

  charge -1.0

`st-chargezero`

  charge 0.0

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

### 4.3.17 st-chess_[black/white]: Chess (Knight) Stone

When hit, a chess stone makes a knight move: two steps in direction of the hit plus one step in direction of the vertical velocity component. `st-chess_black` can only be moved with the black marble, `st-chess_white` only with the white. When there is a chess stone of opposite color or a thief stone (st-thief: Thief Stone) at the target position of a knight move, this stone is destroyed.

When hit with a magic wand (it-magicwand), a chess stone changes color. Chess stones fall into fl-abyss and sink in fl-swamp, but cross fl-water undamaged. They inactivate fl-thief.

Chess stones can't jump over or into fire (see The 1.0-Fire System). At least, a chess knight is brave enough not to get in panic when fire starts to burn beneath. Note that fire can't ignite the floor below an `st-chess_[black/white]`, in this context it acts like an immovable stone. In the same sense, they don't act on impulses of st-stoneimpulse: Impulse Stones or similar stones.

Attributes

`color`

  0 for black, 1 for white

`direction1, direction2`

  Used by the `move`-message

Messages

`capture`

  Destroy stone with capture-animation.

`flip`

  Change color.

`move_[nne, nnw, wwn, wws, ssw, sse, ees, een]`

  Make a knight move.

`move`

  Make a knight move defined by the attributes `direction1` (two steps) and `direction2` (one step). You can use the `NORTH`, `SOUTH`, `EAST` and `WEST` constants for this.

Variants

`st-chess_black`
`st-chess_white`

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

### 4.3.18 st-coffee

This stone is non-transparent at first and becomes transparent and movable when hit (`st-glass_move`). See st-fakeoxyda: Movable Fake Oxyd Stone for a similar stone.

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

### 4.3.19 st-coinslot

A switch that can be activated with coins (see it-coin). The more coins you put in, the longer the switch will stay activated.

Attributes

`on`

  as usual

`target, action`

  As usual

Messages

`on, off, onoff`

  as usual

`signal`

  0: off, 1: on

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

### 4.3.20 st-death: Skull Stones

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

The invisible variant `st-death_invisible` becomes visible while using it-glasses.

Variants

`st-death`
`st-death_invisible`

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

### 4.3.21 st-disco: Disco Stones

A passable stone, which darkens everything that is underneath the stone (much like tinted glass). Can be switched on and off (hence the name).

When lightened or darkened, this stone also lightens and darkens neighboring `st-disco`, such that the light on a passage can be switched on and off just by sending one single message.

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] | [ ? ]

### 4.3.22 st-door: Doors

Doors are designed to let actors pass or not, depended on their internal state, which can be changed by triggers and other objects in game. There is a family of "standard doors" (referred to as `st-door`-variants) as well as three single variants (`st-door_a`, `st-door_b`, `st-door_c`), which differ in design and behaviour.

`st-door`-variants let actors and laser beams pass in all directions when they are opened, and block those perpendicular to the doors when `st-door` is closed. The other three have no distinguished directions, they let actors and laser beams pass if and only if they're open.

When an `st-door`-variant is hit, the item at the doors position performs its `action/target`-pair (you can use all items for this). There is nothing similar for the other variants.

`st-door`-variants do not hold it-trigger down.

Attributes

`type`

  `h` (horizontal) or `v` (vertical): only `st-door`-variants.

Messages

`open, close, openclose`

  as they say

`signal`

  0: close, 1: open

Variants

`st-door`

  equals st-door-h

`st-door-h`
`st-door-v`
`st-door-h-open`
`st-door-v-open`
`st-door_a`
`st-door_b`
`st-door_c`

The first five all have the same design, the last three differ: `st-door_a` looks like st-oxyd: Oxyd Stones of flavor `a` when closed and like `st-grate` when open, `st-door_b` like `st-plain` and shrinks when opened, `st-door_c` also like `st-plain`, but `st-grate3` when opened. Note that this is just design, they don't behave the same way.

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

### 4.3.23 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] | [ ? ]

### 4.3.24 st-explosion: Explosion Stone

This stone mimics an explosion when set, and destroys itself afterwards. Actors in contact with it are shattered.

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

### 4.3.25 st-fakeoxyda: Movable Fake Oxyd Stone

This stone looks like an st-oxyd: Oxyd Stones of flavor `a`, yet it transforms into the movable and transparent `st-glass1_move` when hit. See st-coffee for a similar stone.

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

### 4.3.26 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. It can be destroyed with lasers and it-hammer, see also Breakable Stones.

Messages

`trigger`

  blow off

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

### 4.3.27 st-firebreak[_move]: Firebreakable Stones

`st-firebreak` gets destroyed when there is fire near it (see The 1.0-Fire System). `st-firebreak_move` is movable and gets destroyed when there is fire below it, just like st-wood: Wooden Stone. It falls into fl-water, fl-abyss and fl-swamp (if you need it not to fall, use fl-bridge instead).

`st-firebreak` and `st-firebreak_move` are the results of `st-plain` and `st-plain_move` when using it-pencil on them (see st-plain: Plain Stones), and can be reverted again by using it-brush.

Messages

`fire`

  `st-firebreak[_move]` breaks

`heat`

  `st-firebreak` breaks

Variants

`st-firebreak`
`st-firebreak_move`

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

### 4.3.28 st-flash: Flash Stone

When the flash stone is hit by the black marble, an impulse will be given to the white marble as if it had been hit itself - and vice versa, when the white marble hits the flash stone.

Attributes

`hit_factor`

  factor of the transmitted force (default 20)

`hit_distortion_xx, hit_distortion_xy, hit_distortion_yx, hit_distortion_yy`

  define a matrix to be applied to the force (default `((1,0),(0,1))`)

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

### 4.3.29 st-floppy: Floppy Switch

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

Attributes

`on`

  1 or 0

`target`
`action`

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

### 4.3.30 st-fourswitch: Fourswitch

When hit, this stone visually turns its pointer and performs the action given by the `action/target`-pair.

Attributes

`on`

  1: `EAST` or `WEST`, 0: `NORTH` or `SOUTH`

`action, target`

  as usual

Messages

`trigger, signal`

  turn as if hit with a marble

Note that no `direction`-attribute nor -message is implemented yet. When using the direction in a level, you have to count the hits yourself: The stone always starts with direction `NORTH`.

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

### 4.3.31 st-grate: Grates

Floating grates, mainly decorative. `st-grate1` and `st-grate2` block jumping marbles, all other actors may pass. In Oxyd compatibility mode, all actors may pass.

`st-grate3` lets only small marbles (ac-killerball and ac-whiteball-small) and ac-horse pass. See st-[black/white]: Black and white stones for further stones that let only some actors pass.

Variants

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

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

### 4.3.32 st-invisible: Invisible Stones

`st-invisible` is invisible and non-transparent for lasers, and in contrast to st-chameleon: Chameleon Stone, it is solid.

`st-stonebrush` initially equals `st-invisible`, but turns into `st-rock4` when hit with an it-brush, respectively into `st-likeoxydc-open` in Per.Oxyd compatibility mode.

`st-invisible_magic` is invisible and transparent for lasers, and turns into `st-greenbrown` when touched with it-magicwand.

Variants

`st-invisible`
`st-invisible_magic`
`st-stonebrush`

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

### 4.3.33 st-key: Key (or Lock) Stone

When the right it-key is used on this stone, it performs the action given by the `action/target`-pair. For this, the key has to have the same `keycode`-attribute as the stone.

In Enigma compatibility mode, the key remains in the stone and can't be used until removed from it. In all other modes, you keep the key.

Attributes

`keycode`

  a numerical code determining the correct key

`on`

  1: key used, 0: no key

`action, target`

  as usual

Variants

`st-key`

  `keycode` is 0

`st-key_a`

  `keycode` is 1

`st-key_b`

  `keycode` is 2

`st-key_c`

  `keycode` is 3

Note that `it-key` and `st-key` do not match by defaults, since the default keycodes are different. Use `st-key_a` instead.

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

### 4.3.34 st-knight: Knight Stone

Also called "black knight stone", this stone destroys all marbles that hit it, as long as they are not protected by it-umbrella or wield an it-sword. By hitting `st-knight` with an `it-sword` four times the knight stone spits out a cheeky remark and can be passed thereon, even without a sword.

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

### 4.3.35 st-laser: Laser Stone

`st-laser` emits a laser beam in a specified direction while activated. Note that a laser stone starts deactivated, but you can attach an `on=TRUE`-attribute to it to initialize it in an activated state.

Attributes

`on`
`dir`

  direction of the laser beam (use `SOUTH, EAST, NORTH, WEST`; read-only)

Messages

`on, off, onoff`

  as usual

Variants

`st-laser`

  standard direction is `EAST`

`st-laser-w`
`st-laser-s`
`st-laser-e`
`st-laser-n`

For redirecting and forking laser beams, see st-mirror: Mirror Stones.

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

### 4.3.36 st-laserswitch: Laser Switch

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

See also 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] | [ ? ]

### 4.3.37 st-lasertimeswitch: Laser Time Switch

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

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

### 4.3.38 st-lightpassenger: Light Passenger

The light passenger skates on a laser beam and may push up to one movable stone in front of it. Opposing laser beams are ignored. When the actual laser beam on which the passenger skates is crossed by another one, the passenger switches beams. If it is initially lighted by two rectangular beams, one of them will be chosen by random. The light passenger's skating ability can be turned off and on.

When a stone is in its way, the passenger sends an impulse to the blocking stone, which may move it, but may also have other effects. E.g. a turnstile turns around and an impulse-stone starts pulsing, but it does not open oxyds (this is intended).

The light passenger can't be pushed by actors, but e.g. by st-stoneimpulse: Impulse Stones.

The speed of the light passenger can be changed with the `interval`-attribute (default 50 ms, which is quite fast) and may include the floor friction and local gradient via `friction_factor` (ff) and `gradient_factor` (gf). The resulting interval results as

    interval  =  base * (1 + ff * friction) / (1 + gf * gradient)

with `base` the value of the `interval`-attribute, `friction` the friction of the floor below the light passenger, and `gradient` the parallel part of the force of the floor, i.e. the sum of gradient-force and `force_x/y`-attributes.

The light passenger can be switched on and off by messages (see below), and appears as `st-glass2` when inactive. The variant `st-lightpassenger_off` is deactivated from the beginning.

When an active `st-lightpassenger` is trapped between exactly two opposing light beams or light beams from all four directions, it starts blinking. In this state, it can be destroyed with it-hammer.

Attributes

`interval`

  overrides the standard speed of the light passenger

`friction_factor`

  involves friction into the speed of the light passenger (sensible: 1.0, default 0.0)

`gradient_factor`

  involves gradients into the speed of the light passenger (sensible: 0.02, default 0.0)

Messages

`onoff, on, off, trigger`

  trigger between activated and deactivated (= no skating)

`signal`

  with parameter 0: deactivating, else activating

Variants

`st-lightpassenger`
`st-lightpassenger_off`

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

### 4.3.39 st-mail: Mail Stones

When hit, these stones take the first item out of the players inventory and drop it at their exit or the exit of the appending it-pipe-structure. If this position is blocked (e.g. by another item), no item is taken from inventory.

Variants

`st-mail-w`
`st-mail-e`
`st-mail-s`
`st-mail-n`

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

### 4.3.40 st-mirror: Mirror Stones

These stones redirect and fork laser beams. They can be movable or non-movable, semi-transparent or non-transparent, plane or triangular and have one of four orientations. When hit, the mirror turns 90 degrees clockwise.

Attributes

`movable`
`transparent`
`orientation`

Messages

`trigger, turn`

  rotate clockwise

`signal`

  0: do nothing, else: rotate clockwise

`mirror-north, mirror-east, mirror-south, mirror-west`

  set orientation

Variants

There is a total of 32 mirrors, the names are constructed in the following way: Start with `st-mirror`. For a plane mirror, add `p` and one of the orientations `|,/,-,\\` (the last one is the backslash and has to be masked by doubling). For a triangular mirror, instead add `3` and one of `v,<,>,^`. For a semi-transparent mirror, add a `t`. Finally, for a movable version, add an `m`.

Or, use `st-pmirror` and `st-3mirror` and set the attributes accordingly, with defaults `/` or `v`, non-transparent and non-movable.

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

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

When hit with an it-magicwand, the standard `st-oneway` flips its direction, the variants `st-oneway_black` and `st-oneway_white` do not.

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.

Variants

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

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

### 4.3.42 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. The `static` attribute declares the oxyd stone to be unswappable/unpullable (see st-swap: Swap Stone and st-pull: Pull Stone).

Note: You should rarely need to create Oxyd stones manually with set_stone. Use the predefined @ref{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

`static`

  `true`, `false` (default) - static oxyds may not be swapped or pulled

Messages

`closeall`

  Close all oxyd stones.

`shuffle`

  Interchange the colors of the oxyd stones in the current landscape. Better use the @ref{oxyd_shuffle} function.

`trigger`

  Open the stone (useful for opening Oxyd stones using switches)

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

### 4.3.43 st-plain: Plain Stones

`st-plain` and `st-plain_hole` trigger between solid and hollow when they receive a `trigger`- or `signal`-message.

The solid version additionally becomes `st-plain_cracked` when hit by a laser beam and can then be destroyed with an it-hammer or explosions (see Breakable Stones). The hollow version is transparent for lasers. Note that `st-plain_cracked` doesn't become transparent nor hollow by messages.

`st-plain_move` is a movable and breakable stone (see Breakable Stones) that looks identical to `st-plain`. It falls into fl-abyss, fl-water and fl-swamp, but only when moved. `st-plain_move` and `st-plain` can be transformed into st-firebreak[_move]: Firebreakable Stones with it-pencil, and get reverted by it-brush.

As `st-plain` is a frequent design scheme, you might want to use a version that doesn't transform under laser light. For this purpose, use `st-rock3` or one of the closed doors `st-door_b` or `st-door_c` (see st-door: Doors). Further stones with the typical `st-plain`-design are st-chess_[black/white]: Chess (Knight) Stone and the already mentioned `st-firebreak[_move]`.

Messages

`trigger, signal`

  switch between solid and hollow

Variants

`st-plain`
`st-plain_hole`

Note that there are more stones starting with "st-plain", but none of them has the ability to trigger between solid and hollow: `st-plain_move`, `st-plain_breaking`, `st-plain_falling`, `st-plain_break` and `st-plain-cracked`. See Breakable Stones for them, and st-door: Doors for stones with similar functions like `st-plain`.

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

### 4.3.44 st-polarswitch: Light Switch

When hit, this stone changes transparency for laser beams. It uses the same graphics as `st-glass1` and `st-glass2`. By default, it is non-transparent.

Attributes and messages are equivalent to those of switches:

Attributes

`on`

  1 (transparent) or 0 (non-transparent)

Messages

`signal`

  1 (lighten) or 0 (darken)

`on, off, onoff`

  on = lighten, off = darken, onoff = toggle

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

### 4.3.45 st-pull: Pull Stone

When pushed, this stone acts like pulled, regardless of the source of the impulse. Actors on the destination field are pulled through it, such that they are not caged under them. Hollow stones on the position of the actor exchange their position with the pull-stone. Note however, that the special combination of st-brake: Brake and `st-pull` is lethal for the marble.

The only stones that cannot be pulled, are st-big[brick/bluesand]: Big Stones. Use them to make sure that an `st-pull` can't get out of a restricted area when you use e.g. st-rotator: Rotator Stone or other objects that `st-pull` reacts on. In addition, you can declare st-oxyd: Oxyd Stones to be unswappable by attribute `static`.

Note that, in non-Enigma-modes, `st-pull` may not get pulled into the border of the level. This behaviour might change in future versions.

For a stone with similar function and restrictions, see st-swap: Swap Stone.

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

### 4.3.46 st-puzzle: Puzzle Stones

Puzzle stones can construct large clusters of stones, that move together and can be destroyed together. There are two families, blue and yellow puzzle stones, that behave different (the yellow ones are compatible to the puzzle stones in the original Oxyd-Game). Each of these families again consists of several variants that differ in the location of soccets to which neighboring puzzle stones can be attached. A cluster is complete as soon as all soccets are connected to soccets of other puzzle stones of the same color.

Laser beams make all complete puzzle clusters explode. Besides this, yellow, non-complete puzzle cluster rotate on a laser beam (means: the lightened row or column rotates by one stone position). Non-complete blue clusters don't react on lasers.

If a complete cluster is moved fully onto a combination of fl-water and fl-abyss, it becomes a bridge of `fl-gray`, similar to st-wood: Wooden Stone. A non-complete cluster forms a bridge only on fl-water, and only if it the wielded item is not it-magicwand. Note that in contrast to `st-wood`, puzzle stones only become bridges after they are moved, they don't react on changing the floor.

There also is a single hollow variant for each of the two colors, `st-puzzle-hollow` and `st-puzzle2-hollow`. It acts as if it had soccets to all four directions, but is still hollow. However, these stones are the only hollow ones that press down it-trigger.

When an actor hits:

- a yellow complete cluster, it explodes;
- a single yellow puzzle stone, it moves;
- a yellow uncomplete cluster, it rotates;
- a blue complete cluster with `it-magicwand`, it explodes;
- a blue complete cluster without `it-magicwand`, it moves;
- a blue uncomplete cluster with `it-magicwand`, it rotates.

Note that an exploding cluster can shatter the marble.

In the current implementation, moving a puzzle stone over an item doesn't change it. This affects e.g. it-coin (that don't transform), Hills and Hollows (that don't diminish), it-blackbomb and it-whitebomb (that don't explode). Be aware when using these items together with `it-puzzle` that future implementations of Enigma might change this behaviour.

Messages

`scramble`

  internal message used to scramble a puzzle using secondary information; use @ref{AddScramble} and @ref{SetScrambleIntensity} to scramble a puzzle in a level instead or make use of one of the libraries (`ant` and `libpuzzle` both offer this possibility)

Attributes

`connections`

  A number between 1 an 16. Each bit in (connections-1) corresponds to a socket on one of the four faces. You will normally simply use one of the Lua constants `PUZ_0000` to `PUZ_1111`.

`oxyd`

  0, if the puzzle stone is blue; 1, if it is yellow (`st-puzzle2-*`)

Variants

`st-puzzle-hollow`

  blue hollow puzzle stone

`st-puzzle-<nesw>`

  blue solid puzzle stone

`st-puzzle2-hollow`

  yellow hollow puzzle stone

`st-puzzle2-<nesw>`

  yellow solid puzzle stone

The term `<nesw>` denotes all non-empty substrings of `nesw`, describing the directions to which there are soccets on the stone. Examples: `st-puzzle-nw` is a blue puzzle stone with connections going north and west, `st-puzzle2-esw` is a yellow puzzle stone with connections to the east, south and west.

See st-big[brick/bluesand]: Big Stones for other kinds of cluster-building stones.

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

### 4.3.47 st-rotator: Rotator Stone

Rotator stones come in four flavors: Clockwise or counterclockwise rotation and movable or not movable. They send impulses to neighboring stones, thus pushing them in the direction given by the rotation. st-bolder: Bolder (or Arrow) Stone additionally change their direction to the one they are pushed to. `st-rotator` changes direction when hit with an it-wrench or by a laser beam.

Variants

`st-rotator-right`
`st-rotator-left`
`st-rotator_move-right`
`st-rotator_move-left`

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

### 4.3.48 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)

`minlength`

  The minimal length of the rubberband (default: 0)

`scissor`

  Boolean value defining if already existing rubberbands to other Stones should be cut off. (Default: true)

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

### 4.3.49 st-scissors: Scissors Stone

This stone cuts all rubber bands attached to an actor that touches it. When at least one rubber band is cut, it performs the action given in the `action/target`-pair.

Attributes

`target, action`

  as usual

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

### 4.3.50 st-shogun-<sml>: Shogun Stones

These stones come in three basic variants: small (`s`), medium (`m`) and large (`l`). The smaller ones can be pushed into bigger ones, forming combined forms denoted by combinations of `s`, `m` and `l`. When hit, these combined stones split again into the smaller ones.

The shogun stones trigger shogun items (see it-shogun): A single `st-shogun-s` triggers `it-shogun-s`, a combined `st-shogun-sm` triggers `it-shogun-m`, and the ultimative `st-shogun-sml` triggers `it-shogun-l`.

Shogun stones don't ignite bombs when pushed over them.

Attributes

`holes`

  between 1 and 7 (the three lower bits), used internally, thus read-only

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

### 4.3.51 st-spitter: Spitter Stone

When hit, an it-extralife from the inventory of the hitting marble is transformed into a cannonball (ac-cannonball) which can open st-oxyd: Oxyd Stones, destroy items and floor tiles (replacing them by fl-abyss). The initial velocity of the cannonball can be varied by using the `hit_factor`- and `hit_distortion_*`-attributes.

Attributes

`hit_factor`

  factor of the transmitted force (default 1.0)

`hit_distortion_xx, hit_distortion_xy, hit_distortion_yx, hit_distortion_yy`

  define a matrix to be applied to the force (default `((1,0),(0,1))`)

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

### 4.3.52 st-stoneimpulse: Impulse Stones

These stones give impulses to their neighbors when they receive such themselves or when hit by a laser beam (only when laser beam is turned on or changed, not the whole time).

Messages

`trigger`

  Pulse as if pulse arrived from direction given in second argument to SendMessage (like in `SendMessage(mystone, "trigger", NORTH`). Use `NODIR` if no direction shall be assumed.

`signal`

  0: do nothing, else: start pulsing

Variants

`st-stoneimpulse`
`st-stoneimpulse-hollow`

  not activated by lasers; blocks laser and may shatter actors while pulsing

`st-stoneimpulse_movable`

  movable version; pulses after move

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

### 4.3.53 st-surprise: Surprise Stone

When hit, this stone randomly transforms into one of `st-grate1`, `st-death`, `st-glass1_hole`, `st-magic`, `st-knight`, `st-thief`, `st-plain_break`, `st-plain_breaking`, or another `st-surprise` (see st-grate: Grates, st-death: Skull Stones, Oxyd Compatibility Stones, st-knight: Knight Stone, st-thief: Thief Stone, and Breakable Stones)

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

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

The only stones that cannot be swapped, are st-big[brick/bluesand]: Big Stones. Use them to make sure that an `st-swap` can't get out of a restricted area. In addition, you can declare st-oxyd: Oxyd Stones to be unswappable by attribute `static`.

Note that, in non-Enigma-modes, `st-swap` may not swap into the border of the level. This behaviour might change in future versions.

For a stone with similar function and restrictions, see st-pull: Pull Stone.

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

### 4.3.55 st-switch: Switches

A simple switch.

Attributes

`on`

  1 (activate) or 0 (inactive)

`target, action`

  as usual

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.

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

### 4.3.56 st-thief: Thief Stone

Takes one item from inventory shortly after hit by a player's marble. it-umbrella protects against thievery.

Thief stones can be destroyed with chess stones (st-chess_[black/white]: Chess (Knight) Stone). They then leave an it-bag behind, filled with the stolen items. If the tile is already occupied by an item that could be picked up, it is added to the bag, if the item couldn't be picked up, no bag is produced (you can use this to suppress bag generation).

Compare with `fl-thief` (fl-thief).

Messages

`capture`

  Destroy thief stone with capture-animation (as if captured by a chess stone).

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

### 4.3.57 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. When triggering, it performs its `action/target`-pair, the second data is 1 for every odd activation, and 0 for every even one.

Attributes

`on`

  1 if the timer is running (default: 1)

`interval`

  number of seconds before `action` is performed (default: 1.0)

`loop`

  if 1, restart the timer after performing `action` (default: 1)

`action, target`

  as usual

`invisible`

  if 1, stone is invisible (default: 0)

Messages

`on, off, onoff`

  as usual

`signal`

  0: off, 1: on

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] | [ ? ]

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

`action, target`

  as usual

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

### 4.3.59 st-turnstile: Turnstiles

A turnstile consists of the pivot (`st-turnstile` or `st-turnstile-green`) and up to four arms (`st-turnstile-[w/e/s/n]`). When hit by an actor or by another impulse (e.g. st-lightpassenger: Light Passenger or st-stoneimpulse: Impulse Stones), the whole complex turns around by 90 degrees. The red standard version takes only the actor hitting the turnstile with it to the other side and shatters all others in its surrounding, while the green version takes all actors to the other side, regardless of who gave the impulse to it.

The turnstile may be blocked by other stones (even movable ones). Items are handled during rotation as if a stone is pushed over them.

Messages to the pivot

`signal`

  0: rotate clockwise, 1: rotate counterclockwise

Variants

`st-turnstile`
`st-turnstile-green`
`st-turnstile-e`
`st-turnstile-s`
`st-turnstile-n`
`st-turnstile-w`

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

### 4.3.60 st-volcano: Volcano

This stone duplicates itself and spreads out very fast. During one "life-cycle", it starts as `it-seed_volcano` (see it-seed), grows as `st-volcano-growing` (during which it shatters nearby marbles), becomes `st-volcano_active` when mature, spreads new `it-seed_volcano` on neighboring tiles and becomes inactive after some random time period.

Seeds are spread to randomly chosen neighboring tiles on which are no other stones. Other items are destroyed by this.

While active (not while growing and not while inactive), a volcano stone can be broken with it-hammer (see Breakable Stones).

Messages

`trigger`

  Makes an inactive stone active again.

Variants

`st-volcano`

  starts inactive

`st-volcano-growing`
`st-volcano_active`
`st-volcano_inactive`

See also it-seed.

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

### 4.3.61 st-window: Breakable Stone

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

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

### 4.3.62 st-wood: Wooden Stone

This stone is movable. If moved into fl-abyss, fl-water or fl-swamp it builds a wooden plank (`fl-stwood1` or `fl-stwood2`). In Oxyd 1 compatibility mode `st-wood` only checks for floor when it is moved or when it receives the message "fall".

Note: There are two flavors of `st-wood` which may be specified by using `st-wood1` or `st-wood2`.

`st-wood-growing` is a growing version of `st-wood`, it results from using a particular it-seed.

`st-flhay` and `st-flrock` are movable, too, and create `fl-hay` respectively `fl-rock` when moved into `fl-abyss`, `fl-water` or `fl-swamp`. The difference to `st-wood` is that `fl-hay` doesn't become `fl-abyss` when burning and `fl-rock` doesn't burn at all.

When there is fire under `st-wood` or `st-flhay`, they burn away. In contrast to this, `st-flrock` extinguishes fire, as it is pushed over it (see The 1.0-Fire System). This distinguishes it from all other movable stones. Fire that is extinguishes in this way might leave `it-burnable_ash` behind, but the floor does not fire-transform.

Variants

`st-wood`
`st-wood1`
`st-wood2`
`st-wood-growing`
`st-flrock`
`st-flhay`

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

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

Yin-Yang stones change into `st-white1` or `st-black1` if you touch them (see st-[black/white]: Black and white stones).

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.

Variants

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 it-magicwand or it-brush to change the color to the opposite color of your marble.

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

## 4.4 Actors

Movable objects are called "actors" in Enigma. The most common 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] | [ ? ]

### 4.4.1 Actor Attributes

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

`player values: 0, 1, nil; default: nil`

  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 (same player means same inventory). Note: The controllers of the marble are given by the `controllers`-attribute

`mouseforce values: float; default: 1.0`

  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 values: 0, 1, 2, 3`

  Determines which players may move this actor: 1=Player 0, 2=Player 1, 3=both, 0=none. By default, `ac-blackball`, `ac-whiteball` and `ac-whiteball-small` have their `controllers` attribute set to 1, 2, and 3 respectively. Use value 0 if you want a passive actor.

`essential values: 0, 1, -1`

  Describes the necessity of an actor to be alive in case of multiple actors being attached to a player. A value 0 marks an actor as not essential. The player may well continue to play with other actors that he controls which are still alive. A value of -1 marks an actor as totally necessary. If such an actor cannot be resurrected after a death the player is essentially dead. A value of 1 marks an actor as partially essental. Not the actor itself needs to survive but the number of actors of its kind controlled by the player need to be larger than the number of actors with value 1. F.e. marking 3 out of 5 small whiteballs with 1 means that the player is dead if no longer 3 small whiteballs are alive. See Variables ``enigma.ConserveLevel'` for more details about restart of levels.

`essential_id values: string; default: model name of actor`

  As a player may control actors of different kind at the same time the essentialness of actors is limited to its kind via this id. It is possible to group actors of different kind into an essential group via this id. The engine keeps this id even if actors are transformed into other kinds.

`whiteball, blackball depreceated`

  `TRUE` or `FALSE`. 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] | [ ? ]

### 4.4.2 ac-blackball

This is the most common actor.

Attributes

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

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

### 4.4.3 ac-bug

A small, passive marble. Can be used to break `st-bug` (see Breakable Stones), to pass `st-grate3` (see st-grate: Grates) to open oxyds etc. It can't shatter or die.

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

### 4.4.4 ac-cannonball

Used by st-spitter: Spitter Stone as a cannon ball. Don't use in levels.

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

### 4.4.5 ac-horse

A slightly larger actor which shuttles between the targets given in its `target1`- to `target4`- attributes with a given `force`. In future versions it's planned that marbles can ride `ac-horse` to surpass fl-abyss, fl-water etc. `ac-horse` can pass `st-grate3` (see st-grate: Grates), open oxyds and much more, without shattering or dying.

Attributes

`force (default 10.0)`
`target1`
`target2`
`target3`
`target4`

Example

The syntax of the `target`-attributes is a little bit uncommon. Here an example from the meditation `ral04_1`:

    set_actor("ac-horse",16.5, 6.5, {force=6, target1="16 3",
        target2="3 3", target3="3 9", target4="16 9" })

The attribute consists of a string, holding the x- and y-coordinates separated by a blank. The `ac-horse` in the example shuttles between the coordinates (16,3), (3,3), (3,9) and (16,9) on a rectangular route. Note that there are only four targets allowed at the moment.

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

### 4.4.6 ac-killerball

A small marble, mostly controlled by the player, which shatters other marbles.

Attributes

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

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

### 4.4.7 ac-rotor

An actor which is actively attracted by marbles and shatters them. Compare ac-top.

Attributes

`range (default 5.0)`
`force (default 10.0)`
`gohome (default 1)`
`attacknearest (default FALSE)`

  in case of multiple balls the default behaviour for rotors is to attac the center of all balls. If this flag is set to ``TRUE'` the nearest ball will be attacked.

`prefercurrent (default 0.0)`

  with values from 0.0 to 1.0 the likelyhood is expressed that the rotor hunts the current controlled ball instead of the otherwise attacked aim. You will usually use this attribute in combination with ``attacknearest=TRUE'`. The Level ``Toreador'` is an example of the behaviour of rotors.

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

### 4.4.8 ac-top

An actor which is actively attracted by marbles and shatters them. Compare ac-rotor.

Attributes

`range (default 5.0)`
`force (default 10.0)`
`gohome (default 1)`
`attacknearest (default FALSE)`

  in case of multiple balls the default behaviour for rotors is to attac the center of all balls. If this flag is set to ``TRUE'` the nearest ball will be attacked.

`prefercurrent (default 0.0)`

  with values from 0.0 to 1.0 the likelyhood is expressed that the rotor hunts the current controlled ball instead of the otherwise attacked aim. You will usually use this attribute in combination with ``attacknearest=TRUE'`. The Level ``Toreador'` is an example of the behaviour of rotors.

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

### 4.4.9 ac-whiteball

This marble is mostly played by another player or via it-yinyang.

Attributes

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

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

### 4.4.10 ac-whiteball-small

This is the meditation marble. In meditation levels, you have to place them in `it-hollow` or `it-tinyhollow` to succeed the level, see Hills and Hollows.

Attributes

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

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

## 4.5 General object attributes

`name`

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

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

## 4.6 The 1.0-Fire System

The 1.0-version of Enigma introduces a new fire system, making use of attributes and messages of the floor tiles. The default fire, once ignited, spreads over the landscape and destroys items, marbles and some stones. It spreads along those floor tiles that are marked "burnable" by default (like `fl-hay` or `fl-wood1`), by attribute (setting `enigma.SetAttrib(myfloor, "burnable", TRUE)`) or by one of two items that indicate burnability: the invisible `it-burnable` and the visible `it-burnable_oil`. On a burning floor, all items are destroyed. However, some items deny the floor to burn, like `it-hollow` (see Hills and Hollows) or it-dynamite (which is ignited instead).

Fire can be ignited in several standard ways:

- The `setfire`-message sets fire to a floor if it is burnable and the item on it allows it to burn (unburnable items like `it-dynamite` are not ignited by this!).
- The `heat`-message ignites burnable floors as does `setfire`, but also initiate a heat-transformation of the floor (see below) and ignite items on it.
- The `ignite` and `expl`-messages that are used by `it-dynamite`, it-blackbomb and it-whitebomb can initiate fire via `it-burnable[_oil]` or if the `ignitable`-attribute of the floor is set (off by default).
- The floor already starts burning on initialisation when the `initfire`-attribute is set (off by default).
- Fire in the neighborhood, see below.

If needed, the `forcefire`-message can be used to set fire to unburnable floors. Internally, it is equivalent to manually setting `it-burnable_ignited`, the last method (which was quite famous in 0.92) should be avoided in future, to allow a further development of the fire-system.

Fire does the following:

- It kills st-wood: Wooden Stone and st-firebreak[_move]: Firebreakable Stones above it (in case of `st-firebreak`: beneath it).
- It heats its neighboring tiles, which might result in a "heat-transform" of the floor (see below).
- It might ignite or destroy items on its neighbor, this concerns `it-dynamite`, `it-blackbomb`, `it-whitebomb` and it-crack.
- It might set fire to its neighbor.
- It shatters marbles that are not protected with it-umbrella. Note that in future versions, jumping over fire with it-spring[1/2/board] might get allowed.

Fire stops burning after a random amount of time, as long as the `eternal`-attribute of the floor is not set. When it stops burning, it might replace the floor by another kind ("fire-transform"), this is: Wooden floors are replaced by fl-abyss, leaves are replaced by `fl-dunes`. Finally, it puts `it-burnable_ash` on the floor, which prohibits a second fire and which can be removed with it-brush. However, ash is not set if the floor is `fl-abyss` or the `noash`-attribute is set.

As the spreading of fire is a random event, in 0.92 a level author couldn't be sure that a particular item was ignited or fire was set. In 1.0 these can be assured by setting the `secure`-attribute: When a burnable floor with `secure`-attribute is near fire, it will eventually catch fire, items on it are ignited etc.

In 0.92 there were two speeds of fire: When using `it-burnable`, fire spread much faster as without. This is still the same in 1.0. However, you can set the `fastfire`-attribute to fasten up the fire without setting the invisible `it-burnable`.

Fire that burns under a stone is not allowed to spread, only exception are non-floating stones (as st-grate: Grates), and those stones which are destroyed by fire anyway (see st-wood: Wooden Stone-variants and st-firebreak[_move]: Firebreakable Stones). In contrast to this, fire might also spread to under a movable stone, but not further.

You can stop fire with `it-extinguisher`, which creates the fireproof `it-burnable_fireproof`. Another way to stop fire is to push the totally inert `st-flrock` (see st-wood: Wooden Stone) over it: This is the only movable stone that doesn't allow fire under it. A final way to stop fire is to send the `stopfire`-message to a floor, which works the same way as `st-flrock`.

Compare with Fire and Extinguisher.

Heat-Transformations

When a fire starts to burn near fl-ice, this melts to fl-water. In the same sense, `fl-water` boils to fl-swamp, and this again to `fl-dunes`. In contrast to most other fire-related actions, this is not random, but always and only happens, when a nearby fire starts to burn.

Examples: Put an `st-flrock` on `fl-ice`. A fire will melt the ice, and `st-flrock` creates a fireproof and safe way to the other side. If you use st-wood: Wooden Stone instead, `fl-stwood` is created, which presumably catchs fire and leaves `fl-abyss` behind. A similar combination is `fl-water` with st-chess_[black/white]: Chess (Knight) Stone.

If you want to suppress this transformation, you can switch to a non-Enigma-compatibility-mode, see the following section.

Differences between 1.0 and 0.92

The old fire system of Enigma versions up to 0.92 differs from the 1.0 version mainly in the following points:

- no fire-transform except `fl-[st]wood` to `fl-abyss`
- no heat-transformations
- ash on fl-abyss
- no difference between different floors
- replication via same-floor-pattern instead of burnable-floor-pattern: 0.92 didn't distinguish between burnable and unburnable floors. Instead, fire was allowed to spread to floors of the same kind slowly.
- burnable items always catch fire: In 1.0 a burnable item (except for `it-burnable` and `it-burnable_oil` themselves) on an unburnable floor won't catch fire, in 0.92 it did.

A good model of the 0.92-system can be attained via the compatibility-modes: All non-Enigma-modes (see Differences between Compatibility Modes and <compatibility>) feature a version which only marginally differs from 0.92-fire, yet allowing some of the new achievements, like secure- or eternal-fire.

Note that in 0.92, fire-transformation happened at the beginning of the fire, which manifested in the so called "burning-abyss"-bug. Besides other details, this differs the original 0.92-system from the one in 1.0-non-Enigma-mode.

Burnable and Fireproof Floors

The following floors are fireproof (don't burn by default): `fl-abyss*, fl-ac*, fl-black, fl-brick, fl-bridge*, fl-bumps, fl-concrete, fl-dummy, fl-dunes, fl-gradient*, fl-gravel, fl-gray, fl-himalaya, fl-ice*, fl-inverse, fl-inverse2, fl-darkgray, fl-metal*, fl-mortar, fl-normal*, fl-rock, fl-sahara, fl-sand, fl-space*, fl-springboard, fl-stone, fl-swamp, fl-water, fl-white`

The following floors are burnable: `fl-bluegray, fl-bluegreen*, fl-hay, fl-light, fl-lightgray, fl-marble, fl-red, fl-rough*, fl-tigris, fl-woven*, fl-trigger`

The following floors are burnable and leave `fl-dunes` behind: `fl-leaves*`

The following floors are burnable and leave `fl-abyss` behind: `fl-floor_001, fl-plank, fl-samba*, fl-stwood*, fl-wood*`

Fireproof Items

Most items are passively burnable, this is: An item is destroyed by fire, if and only if the floor could burn all by itself. However, there are some items with individual reactions (`it-burnable, it-burnable_oil, it-dynamite, it-blackbomb, it-whitebomb, it-crack*`) and some items that are completely fireproof. These are: `it-hollow, it-tinyhollow, it-hill, it-tinyhill, it-vortex*, it-burnable_fireproof, it-burnable_ash, it-extinguisher, it-extinguisher_medium, it-abyss`, all items of section System and Debug Items (`it-[1/2]pkillstone, it-bridge-oxyd*, it-debris, it-dummy, it-easy[kill/keep]stone, it-explosion*, it-oxyd5f, it-signalfilter[0/1]`) and the fire animations themselves: `it-burnable_ignited` and `it-burnable_burning`.

Note that `it-extinguisher_empty, it-trigger` (visible and invisible), `it-landmine`, `it-changefloor` and `it-death` are passively burnable. In particular, `it-landmine` does not explode and does not create `it-hollow` when burning. The reaction of it-sensor and `it-inversesensor` towards fire might be changed in future versions.

If you need to save a passively burnable item from fire, simply set a fireproof floor like `fl-sand` or `fl-rock` below it. This normally is the case when using it-[h/v]strip and it-changefloor. However, you can use the `burnable`-attribute in these cases to force burnability of the floors.

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

## 4.7 Differences between Compatibility Modes

Although Enigma was inspired by the original Oxyd-series, there are some differences between the current Enigma engine and the Oxyds as well as between the Oxyds themselves. Using the compatibility-section of the xml-metadata (see <compatibility>) or the enigma.SetCompatibility-function, it's possible to activate some of these behaviours. Here's a list of the currently implemented differences, not all of them are mentioned at the corresponding sections above:

All non-Enigma modes `(oxyd1, per.oxyd, oxyd.magnum, oxyd.extra)`

- Keep it-key when using st-key: Key (or Lock) Stone.
- Oxyd-stones (st-oxyd: Oxyd Stones) must blink before they can be ultimately opened (pairs must be hit with some time delay).
- The non-Enigma modes feature a model of the 0.92-Fire System (see The 1.0-Fire System).
- it-squashed and it-cross can't be removed with it-brush.
- Only function of it-pencil is to turn `st-plain[_move]` into `st-firebreak[_move]`.
- it-booze doesn't break to it-booze-broken when a stone is pushed over it.
- st-swap: Swap Stone and st-pull: Pull Stone may not swap/pull into the level border.

`oxyd1`-compatibility

- it-seed grows to `fl-stwood` under `st-grate1` (st-grate: Grates), not to st-wood: Wooden Stone.
- Flying actors may pass `st-grate1` and `st-grate2` (see st-grate: Grates).
- st-wood: Wooden Stone only falls when moved.
- The `ignite`-message (e.g. by it-dynamite) doesn't kill it-document.
- Bombs (it-blackbomb, it-whitebomb) aren't ignited when st-wood: Wooden Stone is pushed over them (see `oxydmagnum`-compatibility).

`per.oxyd`-compatibility

- When painted with it-brush, `st-stonebrush` (see st-invisible: Invisible Stones) becomes `st-likeoxydc-open` instead of `st-rock4`.
- it-hammer doesn't laser-transform into it-sword.
- it-umbrella doesn't explode in laser-light.
- it-cross inverts signals it receives.

`oxyd.magnum`-compatibility

- it-seed grows to `fl-stwood` under `st-grate1` (st-grate: Grates), not to st-wood: Wooden Stone.
- Bombs (it-blackbomb, it-whitebomb) aren't ignited when st-wood: Wooden Stone is pushed over them (see `oxyd1`-compatibility).

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

# 5. Variables

This chapter describes 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, or that carry interesting information about the context of the level. In the second case, the same effect can usually be achieved by setting the corresponding object attributes directly, but being able to specify a global default value often is more convenient. You can always override these default attribute values for specific objects by setting the appropriate object attributes.

Variable: enigma.ConserveLevel values: `TRUE`, `FALSE`; default: `TRUE`

  The conserve mode determines if a dead actor will be resurrected in case of extralives in the gamers inventory.

  If `TRUE` dead actors attached to a player will be resurrected as long as extralives are available. If a player has no living actor to control or is missing the actors essential constraints (see section Actor Attributes) the player is dead. The level may still continue if a second player is alive. If the gamer has a yinyang in his inventory in single user mode the control switches to the second player. If all players are dead a new level game is started.

  If the conserve mode is `FALSE` no actors will be resurrected. As soon as the player is dead and the control cannot switch to another player all dead actors are resurrected by usage of extralives and the level is restartet without finishing the level game.

  Use `FALSE` if the level cannot be solved in case of resurrected actors. In all other cases mode `TRUE` with proper usage of actors essential constraints will be preferable (see section Actor Attributes).

Variable: enigma.CreatingPreview

  `TRUE` or `FALSE`, read-only. Use this to determine in a level whether it is just loaded to build a thumbnail. If so, you can e.g. change the start-position of ac-blackball to display another part of the level in the preview, or hide objects from it. When changing the initial position, it might be advantageous to also set the follow-mode to smooth (display.SetFollowMode):

      if enigma.CreatingPreview then
        display.SetFollowMode(display.FOLLOW_SMOOTH)
      else
        display.SetFollowMode(…)
      end

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 (see it-crack). Default: 0.5.

Variable: enigma.BumperForce

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

Variable: enigma.ElectricForce

  A force multiplier for all electric forces between actors, see st-charge: Charge Stones. 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-force and obsolete since introduction of the `force_[x/y]`-attributes. Default: 0.

Variable: enigma.IceFriction

  Friction of fl-ice is multiplied with this constant. Default: 1.0.

Variable: enigma.HoleForce

  A force factor that affects the steepness of hollows and hills (see Hills and Hollows). Default: 1.0.

Variable: enigma.MagnetForce

  A force multiplier for magnetic fields (see it-magnet). Default: 30.0.

Variable: enigma.MagnetRange

  The range of magnetic fields (see it-magnet). Default: 10.0.

Variable: enigma.ShowMoves

  `TRUE` or `FALSE`. This is preferably used in Sokoban levels to display a move counter in the inventory. Default: `FALSE`.

Variable: enigma.SlopeForce

  A force multiplier for sloped floor tiles (see fl-gradient). Default: 25.0.

Variable: enigma.WaterSinkSpeed

  How quickly balls sink in fl-water. Default: 1000.0.

Variable: enigma.SwampSinkSpeed

  How quickly balls sink in fl-swamp. Default: 4.0.

Variable: enigma.WormholeForce

  A force multiplier for it-wormhole. Default: 30.0.

Variable: enigma.WormholeRange

  The range of it-wormhole. Default: 10.0.

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

# 6. Functions

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

## 6.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] | [ ? ]

### 6.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] | [ ? ]

## 6.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] | [ ? ]

## 6.3 display.SetFollowMode

Function: display.SetFollowMode (mode)

  This function sets the followmode of a level. The followmode defines the behavior of the landscape if a level is bigger than one screen.

  Possible values are:

  display.FOLLOW_NONE

    Don't follow any sprite.

  display.FOLLOW_SCROLLING

    Scroll the screen.

  display.FOLLOW_SCREEN

    Flip the screen region.

  display.FOLLOW_SCREENSCROLLING

    Scroll to the next screen.

  display.FOLLOW_SMOOTH

    Follow pixel by pixel.

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

## 6.4 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] | [ ? ]

### 6.4.1 Example

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

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

## 6.5 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 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] | [ ? ]

### 6.5.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] | [ ? ]

## 6.6 draw_floor

Function: draw_floor (floorname, location, increment, count , attribs)

  Description: Use this function to add several floor objects to your level in periodical distances. How does it work? At first it places the floor to location. Then it moves by increment, and again places given floor. And again and again - so many times as defined by count.

  Floorname

    Name of floor object.

  Location

    This is Lua table with two elements: {x,y}. They represent the location of first floor object

  Increment: Another Lua table with two elements:

    {dx,dy}. dx is the increment per step in x-axis, dy is increment per step in y-axis. Often this function is used to add a row of floors in one direction, and then Increment looks like this: {1,0} or {0,1}.

  Count

    Number of steps to proceed.

  Attribs

    Table of attribute names and corresponding values: {attrib1=value1, attrib2=value2, …}. It represents the attributes to be passed to each created floor. You can omit this argument.

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

### 6.6.1 Example

    draw_floor("fl-abyss", {3,0}, {0,1}, level_height)
    draw_floor("fl-gradient", {15, 5}, {1,0}, 4, {type=1})
    draw_floor("fl-water", {level_width-4,3}, {0,1}, level_height-6)

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

## 6.7 draw_items

Function: draw_items (itemname, location, increment, count [, attribs])

  Description: This function adds to your level several item objects in periodical distances. It works much like draw_floor except that it adds items instead of floors.

  Itemname

    Name of item object.

  Location

    This is Lua table with two elements: {x,y}. They represent the location of first item that you want to add to map.

  Increment: Another Lua table with two elements:

    {dx,dy}. dx is the increment per step in x-axis, dy is increment per step in y-axis.

  Count

    Number of steps to proceed.

  Attribs

    Table of attribute names and corresponding values: {attrib1=value1, attrib2=value2, …}. It represents the attributes to be passed to each created item. You may omit this argument.

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

### 6.7.1 Example

    draw_items("it-trigger", {3,3}, {2,0}, 8)
    draw_items("it-tinyhill", {5,3}, {2,0}, 7)

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

## 6.8 draw_stones

Function: draw_stones (stonename, location, increment, count [, attribs])

  Description: This function adds to your level several stones in periodical distances. It works much like draw_floor except that it adds stones instead of floors.

  Stonename

    Name of stone object.

  Location

    This is Lua table with two elements: {x,y}. They represent the location of first stone to be placed to map.

  Increment

    Another Lua table with two elements: {dx,dy}. dx is the increment per step in x-axis, dy is increment per step in y-axis.

  Count

    Total number of stones to add.

  Attribs

    Table of attribute names and corresponding values: {attrib1=value1, attrib2=value2, …}. It represents the attributes to be passed to each created stone. You may omit this argument.

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

### 6.8.1 Example

    draw_stones("st-grate1", {9,1},{0,1}, 5)
    draw_stones("st-stone_break", {21,1}, {1,0}, 10)

    function draw_border(stonename, x0, y0, w, h)
        draw_stones(stonename, {x0,y0}, {1,0}, w)
        draw_stones(stonename, {x0,y0+h-1},{1,0}, w)
        draw_stones(stonename, {x0,y0}, {0,1}, h)
        draw_stones(stonename, {x0+w-1,y0},{0,1}, h)
    end

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

## 6.9 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] | [ ? ]

## 6.10 enigma.GetAttrib

Function: GetAttrib (object, attribname)

  Description: The function is similar to SetAttrib, except that it doesn't set the attribute, but return current attribute value. Function arguments have the same meaning like in SetAttrib, see its description. Also note GetKind.

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

### 6.10.1 Example

    local bolder_dir = GetAttrib(bolder1, "direction")

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

## 6.11 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] | [ ? ]

### 6.11.1 Example

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

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

## 6.12 enigma.GetKind

Function: enigma.GetKind(object)

  Description: This function returns the kind of an object.

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

### 6.12.1 Example

    set_stone("st-wood", 7, 11)
    …
    local mystone=enigma.GetStone(7,11)
    local mystonetype = enigma.GetKind(mystone)

    mystonekind will be "st-wood"

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

## 6.13 enigma.KillFloor

Function: enigma.KillFloor (x, y)

  Kills the floor tile at position (x,y).

  x, y

    Koordinates of the floortile to kill.

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

## 6.14 enigma.KillItem

Function: enigma.KillItem (x, y)

  Kills the item at position (x,y).

  x, y

    Koordinates of the item to kill.

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

## 6.15 enigma.KillStone

Function: enigma.KillStone (x, y)

  Kills the stone tile at position (x,y).

  x, y

    Koordinates of the stone to kill.

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

## 6.16 enigma.LoadLib

Function: enigma.LoadLib (libraryId)

  This function loads a Lua level library that has previously been declared in <compatibility> at a given point of code execution. If the library is declared with ``el:preload="true"'` no Lua function call is necessary. The libraryId is the same as in the declaration.

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

## 6.17 enigma.NameObject

Function: enigma.NameObject (object, value)

  Description: Gives the name value to object.

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

## 6.18 enigma.SetAttrib

Function: enigma.SetAttrib (object, attribname, value)

  Description: The function sets the given attribute of a given object to given value. If you try to pass unknown attribute to an object, enigma will ignore it (i.e. nothing happens).

  Object

    The variable that holds the object. Every function that creates an object returns the variable representing freshly added object. That's right what should be passed to SetAttrib. (See example).

  Attribname

    Name of the attribute. See the description of objects to learn which object knows what attributes.

  Value

    New value of attribute.

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

### 6.18.1 Examples

    local ls = set_stone("st-laser", 1, 4, {on=FALSE, dir=NORTH})
    set_attrib(ls, "name", "laser")

    -- (also "on" and "dir" are attributes in this example)

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

## 6.19 enigma.SetAttribs

Function: enigma.set_attribs (object, attribs)

  Description: This function sets several attributes at a time. The only thing it does is call SetAttrib as many times as needed to set values of all desired attributes.

  Object

    Value that holds the object, whose attributes are about to change.

  Attribs

    Table of attribute names and corresponding values: {attrib1=value1, attrib2=value2, …}

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

### 6.19.1 Examples

    local ls = set_stone("st-laser", 1, 4, {on=FALSE, dir=NORTH})
    … (some lua code) …
    set_attribs(ls, {on=TRUE, dir=WEST})

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

## 6.20 enigma.SetDefaultAttribs

Function: enigma.SetDefaultAttribs (objectname, attribs)

  Description: Use this function if there are several objects of same kind, that have attributes (all or just some) with same value. For example if there are twenty wormholes with strength of 10, you can set the strength of 10 as a default value for all wormholes.

  Notes: Default attributes can be overriden or several extra attributes can be assigned to object. The attributes specified at creation time (using set_floor, set_item, set_stone functions) override default attributes specified by SetDefaultAttribs.

  Objname may be name of any enigma stone, floor or

    item. In most cases this is wormhole, because it's usual to have several wormholes with same strength and range, while it's not very common to have for example all doors vertical or all bolders facing west.

  Attribs

    Table of keys and corresponding values: {attrib1=value1, attrib2=value2, …}

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

### 6.20.1 Examples

    SetDefaultAttribs("it-wormhole", {range=1.0, strength=10})
    set_item("it-wormhole", 11, 6, {targetx="48.5",targety="56.5"})

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

## 6.21 enigma.SetCompatibility

Function: enigma.SetCompatibility (compatibility)

  This function sets the compatibility of a level. Because in every of the original oxyd games certain objects may have a different behavior, there exists for each game a compatibility mode. Enigma itself has also a compatibilitiy mode, it's the default.

  Note: This function is depreceated. Set the compatibility information in the xml-node <compatibility> instead.

  Possible values for compatibility are:

  oxyd1

    Oxyd1-mode

  per.oxyd

    Per.Oxyd-mode

  oxyd.magnum

    OxydMagnum-mode

  oxyd.extra

    Oxydextra-mode

  enigma

    Enigma-mode

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

## 6.22 fill_floor

Function: fill_floor (floorname)

  fill_floor (floorname, x, y, w, h)

  Description: This function fills an area of map with selected floor type.

  Floorname

    Name of floor object. If this is the only argument to the function, whole map area is filled with this kind of floor.

  x, y

    Coordinates of upper left corner of filled area. Note that upper left square of map is at coordinates [0,0]. If those arguments are omitted, zero is passed instead.

  w, h

    Size of filled area. If any of these arguments is omitted, level width or height respectively is passed by default.

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

### 6.22.1 Examples

    fill_floor("fl-space", 0,0, level_width,level_height)  -- these two lines
    fill_floor("fl-space")                                 -- do the same
    fill_floor("fl-gray", 1, 1, level_width-2, level_height-2)
    fill_floor("fl-water", 24,47, 11,1)

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

## 6.23 fill_items

Function: fill_items (itemname, x, y, w, h)

  Description: This function fills an area of map with items of selected kind.

  Note: Please note that in contrast to function fill_floor, this function doesn't have any default attributes and no parametter may be omitted.

  (strange, no one ever used this function in their map ....)

  Itemname

    Name of item object.

  x, y

    Coordinates of upper left corner of filled area. Note that upper left square of map is at coordinates [0,0].

  w, h

    Size of filled area - w is width and h is height.

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

### 6.23.1 Examples

    fill_items("it-wormhole", 1, 1, 3, 3) -- field of 3x3 wormholes

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

## 6.24 fill_stones

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

  Description: This function fills an area of map with stones of selected kind.

  Note: Please note thatin contrast to function fill_floor, this function doesn't have any default attributes and no parametter may be omitted.

  Stonename

    Name of stone object.

  x, y

    Coordinates of upper left corner of filled area. Note that upper left square of map is at coordinates [0,0].

  w, h

    Size of filled area - w is width and h is height.

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

### 6.24.1 Examples

    fill_stones("st-chameleon", 1, 1, 18, 11)
    fill_stones("st-grate1", 1, 5, 5, 7)
    fill_stones("st-death", 9, 5, 2, 2)

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

## 6.25 MakeObject

Function: MakeObject (objname, attribs)

  Description: The function MakeObject is used internally by other functions, like set_floor, set_item or set_stone. It takes care of creating the object and sets up all desired attributes, including default ones

  Objname

    Name of internal enigma object. It can be name of any floor, stone or item.

  Attribs

    Table of attribute names and corresponding values: {attrib1=value1, attrib2=value2, …}

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

### 6.25.1 Example

    Example: To my best knowledge, no one uses this function in
    their levels. You should rather use set_floor/stone/item functions for
    creating particular enigma objects. If you need this function, you are
    probably guru and you don't need this manual either.

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

## 6.26 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 enigma.GetNamedObject.

  message

    The message itself (e.g. "signal") You can see which messages are understood in the documentation of the particular Objects.

  data

    Some specific messages expect some additional data (e.g. message "direction" expects a direction like SOUTH or WEST).

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

### 6.26.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] | [ ? ]

## 6.27 set_floor

Function: set_floor (floorname, x, y, attribs)

  Description: As you would expect, this function creates a floor at given [x,y] position in enigma level, and passes all necessary default attributes and attributes passed in attribs argument.

  Floorname

    Enigma internal object name. The name should be the name of floor (they typically start with "fl-" prefix). In fact, it is possible to add a stone object as a floor, but strange things happen. Generally nothing you would like to use in your levels.

  x, y

    Location where you want the floor to be placed. Note that level coordinates begin with zero (see CreateWorld).

  Attribs

    Table of attribute names and corresponding values: {attrib1=value1, attrib2=value2, …}

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

### 6.27.1 Examples

    function setup_gradient_rose(x,y)
       set_floor("fl-gradient", x, y+1, {type=1})
       set_floor("fl-gradient", x, y-1, {type=2})
       set_floor("fl-gradient", x+1, y, {type=3})
       set_floor("fl-gradient", x-1, y, {type=4})
    end

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

## 6.28 set_item

Function: set_item (itemname, x, y, attribs)

  Description: This function is very similar to the one named set_floor, describer earlier. It creates an item at given position. Items in enigma are all those magic wands, brushes, coins, triggers, bombs and also for example the laser ray or crackles. There can be only one single item on each position.

  Note: The rule of single item per field also means, that laser cannot "overshoot" magic wand or trigger, that you cannot drop item to cracked floor etc. It may look like disadvantage, but on the other hand, it can be used as an advantage (see for example the level named "Follow the Light" in "Oxyd Clones" package).

  Itemname

    Enigma internal object name. The name has to be the name of item (they typically start with "it-" prefix). Enigma won't let you create an item from other object that just item.

  x, y

    Location where you want the item to be placed. Note that level coordinates begin with zero (see CreateWorld).

  Attribs

    Table of attribute names and corresponding values: {attrib1=value1, attrib2=value2, …}

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

### 6.28.1 Examples

    set_item("it-trigger", 34, 3, {action="openclose", target="bridge1"})

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

## 6.29 set_stone

Function: set_stone (stonename, x, y, attribs)

  Description: This function is very similar to the one named set_floor, describer earlier. It places the stone to desired location. Stones in enigma are all walls, glass blocks, death's heads, and also doors, switches, lasers, bolders and lots of other special enigma objects.

  Stonename

    Enigma internal stone name. The name has to be the name of stone (they typically start with "st-" prefix). Enigma won't let you create the stone from other object that just stone.

  x, y

    Location where you want the stone to be placed. Note that level coordinates begin with zero (see CreateWorld).

  Attribs

    Table of attribute names and corresponding values: {attrib1=value1, attrib2=value2, …}

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

### 6.29.1 Examples

    set_stone("st-door", 18,  6, {name="door01", type="h"})
    set_stone("st-bolder", 2, 11, {name="bolder01", direction=NORTH})

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

## 6.30 set_stones

Function: set_stones (stonename, positions, attribs)

  Description: This function is somehow similar to draw_stones. It can place several stones to locations all over the map. The locations to which the stones will be placed are listed in argument positions.

  Stonename

    Enigma internal stone name.

  Positions

    Table of stone locations. Its format is like this: {loc1, loc2, …}, where each location is {x,y}. Together it looks like this: {{x1,y1}, {x2,y2}, …}.

  Attribs

    Table of attribute names and corresponding values: {attrib1=value1, attrib2=value2, …}. Those attributes will be passed to created stones together with default attributes. You may omit this attribute.

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

### 6.30.1 Examples

    set_stones("st-glass", {{1,6},{1,12},{34,1},{34,2},{35,2},{36,1},{36,2}})
    set_stones(bordertile, {{34, 1}, {34, 5}, {34, 7}, {34, 11}})
    …
    set_stones("st-invisible", {{7,9}}) -- these two lines
    set_stone("st-invisible", 7, 9)     -- do the same

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

# Function Index

Jump to: | A C D E F G M S

| Index Entry | Section
A |  |
| `AddRubberBand` | 6.1 AddRubberBand
C |  |
| `CreateWorld` | 6.2 CreateWorld
D |  |
| `display.SetFollowMode` | 6.3 display.SetFollowMode
| `draw_border` | 6.4 draw_border
| `draw_checkerboard_floor` | 6.5 draw_checkerboard_floor
| `draw_floor` | 6.6 draw_floor
| `draw_items` | 6.7 draw_items
| `draw_stones` | 6.8 draw_stones
E |  |
| `enigma.AddConstantForce` | 6.9 enigma.AddConstantForce
| `enigma.Brittleness` | 5. Variables
| `enigma.BumperForce` | 5. Variables
| `enigma.ConserveLevel` | 5. Variables
| `enigma.CreatingPreview` | 5. Variables
| `enigma.ElectricForce` | 5. Variables
| `enigma.FlatForce` | 5. Variables
| `enigma.FrictionFactor` | 5. Variables
| `enigma.GetKind(object)` | 6.12 enigma.GetKind
| `enigma.GetNamedObject` | 6.11 enigma.GetNamedObject
| `enigma.HoleForce` | 5. Variables
| `enigma.IceFriction` | 5. Variables
| `enigma.KillFloor` | 6.13 enigma.KillFloor
| `enigma.KillItem` | 6.14 enigma.KillItem
| `enigma.KillStone` | 6.15 enigma.KillStone
| `enigma.LoadLib` | 6.16 enigma.LoadLib
| `enigma.MagnetForce` | 5. Variables
| `enigma.MagnetRange` | 5. Variables
| `enigma.NameObject` | 6.17 enigma.NameObject
| `enigma.set_attribs` | 6.19 enigma.SetAttribs
| `enigma.SetAttrib` | 6.18 enigma.SetAttrib
| `enigma.SetCompatibility` | 6.21 enigma.SetCompatibility
| `enigma.SetDefaultAttribs` | 6.20 enigma.SetDefaultAttribs
| `enigma.ShowMoves` | 5. Variables
| `enigma.SlopeForce` | 5. Variables
| `enigma.SwampSinkSpeed` | 5. Variables
| `enigma.WaterSinkSpeed` | 5. Variables
| `enigma.WormholeForce` | 5. Variables
| `enigma.WormholeRange` | 5. Variables
F |  |
| `fill_floor` | 6.22 fill_floor
| `fill_items` | 6.23 fill_items
| `fill_stones` | 6.24 fill_stones
G |  |
| `GetAttrib` | 6.10 enigma.GetAttrib
M |  |
| `MakeObject` | 6.25 MakeObject
S |  |
| `SendMessage` | 6.26 SendMessage
| `set_floor` | 6.27 set_floor
| `set_item` | 6.28 set_item
| `set_stone` | 6.29 set_stone
| `set_stones` | 6.30 set_stones

Jump to: | A C D E F G M S

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

# Concept Index

Jump to: | C I L P R S U

| Index Entry | Section
C |  |
| crossindex | 2. Levelpack Basics
| crossreference | 2. Levelpack Basics
I |  |
| index | 2. Levelpack Basics
L |  |
| l10n path | 1.1 Locating Resources
| levelinspector | 1.4 Level Info
| levelpack | 2. Levelpack Basics
| localization path | 1.1 Locating Resources
P |  |
| preferences path | 1.1 Locating Resources
R |  |
| resource paths | 1.1 Locating Resources
S |  |
| system path | 1.1 Locating Resources
U |  |
| user image path | 1.1 Locating Resources
| user path | 1.1 Locating Resources

Jump to: | C I L P R S U

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

# Table of Contents

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

# About This Document

This document was generated on May, 5 2007 using texi2html 1.76.

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 | beginning of this chapter or previous chapter | 1
[ Up ] | Up | up section | 1.2
[ >> ] | FastForward | next chapter | 2
[Top] | Top | cover (top) of document |
[Contents] | Contents | table of contents |
[Index] | Index | index |
[ ? ] | About | about (help) |

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 on May, 5 2007 using texi2html 1.76.