Enigma Reference Manual

This manual describes the internals of Enigma version 1.30, in particular how to build new levels using Lua and how to interact with the game engine.

1. Running Enigma

Hopefully, after successfully installing and playing some first levels, you may be interested in some information about how we have configured Enigma, how you can optimize Enigma to your needs, and the purpose of some options and attributes within Enigma.

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

1.1 Locating Resources

For reasons of backup, system changes, special configurations, level additions and hopefully your 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 in the help submenu paths, 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. Since it is the third version in the history of Enigma, the file is named ‘.enigmarc.xml’ by default.

We recommend that you backup this file, although it contains only a few data that you can quickly reconfigure.

Since 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, a switch exists ‘--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 separate 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, a leading ‘.’ will hide the preferences filename.

User Path

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

A backup of this directory is mandatory!

The standard location is the directory ‘.enigma’ in your HOME directory. For HOME-less Windows users, it is the folder ‘%APPDATA%\Enigma’, what resolves to the subfolder ‘Application Data\Enigma’ on XP/2000 or ‘AppData\Roaming\Enigma’ on Vista/Windows 7 located within your user data folder.

This standard location of the user path is the location of logging and error output files, too.

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

User Image Path

This is a second path to the user’s Enigma data, which you can use to access images such as 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 your 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. This is a first class address to look for examples if you start writing your own levels.

Resource Paths

This is a list of paths. The program looks up each version-independent resource on all paths in this list, and loads from the first occurrence.

User data precedes system data; this way, updates on your user data path will win. Have a look at this list if you are observing a difference between a source and the runtime behavior. You may have looked at a file that another file had hidden on a preceding 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 to find 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 form, the plain file stored in a directory wins, since Enigma assumes it to be an update to the zip.

1.2 Startup Switches

Besides starting Enigma by clicking on an installation-provided icon or start menu entry, you can start Enigma from a shell or commandline. This allows you to add a selection of startup switches that are valid for just a single run.

For repeated usage of constant startup switches you can create a desktop icon or start menu entry and append the startup switch to the target string of the Enigma application executable.

The following list explains the supported user options. If an option is listed with a long name preceded by two minus signs, and with a one-character abbreviation preceded by one minus sign, use one of the notations, not both together; for example, ‘--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 you to add an additional path to the resource paths that precedes 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 lists the available startup switches to the output and terminate.

--lang -l lang

A switch that allows you 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 a file called ‘Output.log’ in the standard ‘User Path’ folder. An additional file ‘Error.log’ lists severe error messages.

The output will, for example, list the paths described in Locating Resources.

--nograb

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

--nomusic

Start Enigma without playing background music.

--nosound

Start Enigma with sound 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.

--redirect

Redirect the ‘stdout’ and ‘stderr’ to files named ‘Output.log’ and ‘Error.log’ on the standard user path (see section Locating Resources). For Windows this option is always true, but the usage of this option is useful on any operating system if Enigma is started via a desktop icon or a menu button.

--robinson

Disable all connections to the internet. No automatic updates will take place and all user initiated requests that would require an internet connection will fail with an error message.

--showfps

Show the framerate (FPS) during the game.

--version

Just print the version number to the output and terminate.

--window -w

Start Enigma in window mode instead of screen mode.

Enigma interprets all further arguments supplied on the commandline as level file addresses. You can use absolute or relative addresses to level files stored on your computer. Adding url’s to levels stored in the Internet is also possible.

A Unix user may start Enigma with the following command:

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

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

C:\Programs\Enigma\enigma.exe --log demo_simple.xml

You will find these levels in the levelpack called ‘Startup Levels’, which is only visible by default if you supplied levels on the commandline.

1.3 User Options

Ratings update

Please retain this option on the value ‘Never’ until release of Enigma 1.00.

User name

Enter your user name, which Enigma will attach to your scores. Please look at the Enigma home page for user names already in use and choose a new, unique name. You can change your user name at anytime without losing any of your 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.

Enigma activates the new path when you leave the options menu. Though it stores all files directly to the new path, and will still find files on the old path, you may want to quit Enigma immediately and first copy/merge the old directory to the new location. This copy of your old data is necessary, since 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.

Enigma activates the new path when you leave the options menu. Though it has stored all files directly to the new path and files will still be found on the old path, you may want to quit Enigma immediately and first copy/merge the old directory to the new location. This copy of your old data is necessary, since with the next start, Enigma will locate user data at the new location exclusively.

1.4 Inventory Console

The lower right window area that usually shows the inventory items and scrolls the texts of activated document items allows the user to reread previous document texts, to enter textual commands and to reissue previous commands.

You can issue a command by usage of the keyboard. Just enter the command string and activate the command by a finishing <return> stroke. The following commands are supported:

help

List all public available commands.

abort

Abort level and return to level selection menu. Same as <Alt X>

April 1st

Just a joke.

cheats

List level developer cheat commands for fast testing.

collision

Developer cheat that disables collisions between stones and marbles or pearls. Once used no score will be recorded if the level is successfully finished.

easy

Restart level in easy difficulty mode.

find search_string

Searches levels in all levelpacks that contain matching string in either the level’s title, author’s name or the file name.

god

Developer cheat that protects the actors assigned to the current player like the activation of an it_umbrella does. Once used no score will be recorded if the level is successfully finished.

hunt

Switch to world record hunting mode. Same as toggling the left most button in the level selection menu to the world icon.

info

Show info about level like the levelpack, position within levelpack, the file location, the title, author, version and the level internal id.

jumpto levelpack,position

Directly start the given level. The levelpack is identified by its title. The position is the number within the levelpack. E.g. jumpto Enigma IV,33.

nohunt

Switch off the world record hunting mode. Same as toggling the left most button in the level selection menu to the marble icon.

regular

Restart level in regular difficulty mode

restart

Restart level in currently selected difficulty mode.

suicide

Kill actors, but continue level if possible. Same as <F3>.

Both, the commands and the displayed document text have a history. You recall the history by usage of the up and down arrows.

• inventory –> jump to start
• command #10, oldest command in history
• command #9
• …
• command #2
• command #1, last executed command
• command under edition, just if the last edited command has not been executed
• inventory <– start
• document #1, last viewed document
• document #2, previous viewed document
• …
• document #n, first viewed document
• level title, subtitle, author, as shown on level start
• inventory –> jump to start

Starting with the inventory item display the up arrow shows the previously submitted commands. Just by another <return> you can reissue a command. The history will be resorted with the last command at the position direktly above the inventory. You can edit history commands anytime like you can insert a new command. If you do not finish a command by a <return> the string will still be recorded and presented as the first command above the inventory. The command history is persistent.

The document history can be recalled by usage of the down arrow. All level documents previously displayed can be redisplayed. Additionally the initial level info displayed on the level start can be read again.

Both histories revolve to the item inventory when the up or down keys are used beyond the oldest command or message.

1.5 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. You can call this special menu from within the level menu by right or control clicking on the level icon.

Besides title and author, Enigma provides information 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. You can review any screenshots you made for this level directly from the levelinspector, too.

1.5.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 following abbreviations for the ratings. Each of these categories takes values between 1 (easy) and 5 (difficult), except kno, which can also be 6 (unique mechanism).

Please bear in mind that it’s not simple to retain the following definitions in each of nearly 750 cases, so there might be (will be) deviations from them in single levels.

Intelligence (int)

This rating is intended to measure the creativity, planning and analytic requirements needed to solve the level. Intelligence is a very difficult concept in itself, and thus at first not easy to rate or to grasp. Consequently, a fixed definition of the five rating-degrees not only helps, but is essential in the rating process. 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, for example, testing the exits of wormholes or to 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 does it require advance planning? -> int 4
• Is it 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 itself already determines the rating.

Dexterity (dex)

You can solve many levels either by accuracy or by patience. In our context, we do not mean dexterity in the sense of accuracy to avoid impatience, 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 to a single row with an abyss left and right. -> dex 3
• Comparable to pushing a stone to the right with an 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: A level with many situations, each of dex 3, can add up to dex 4 or even 5. This way, you can achieve dex 5. Rotors in a level also contribute to dex and 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 mostly to “felt time”, how long it felt to complete the level. 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 restart the level repeatedly; not the time in the lower left corner or the score is crucial, but the complete “felt 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 it wasn’t boring. -> pat 2
• Okay, it took 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 requires discipline. -> pat 5

A high number of oxyds can heighten the pat-value and also 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 oxyds are arranged to mark the progress of the player, and act as a kind of small reward within the level, they can lower the pat-value. It’s 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 guideline 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 encountered 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, an abyss, documents, using the inventory, static gravity, visible gradients.
2. Pushing stones, simple Sokoban-tricks, bridge-building in water and an abyss, connected puzzle-stones, moving more than one marble, meditations, grates, rotors and tops, hidden gradients, triggers and switches, doors, holes (not made by dynamite), swamp, floppies and st-floppy, keys and locks, coins and slots, cracks, timer-stones.
3. Different floors can have different friction 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, boulders, magic-wand to change boulder-direction, boulders sink into an abyss, sheets 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 an abyss, quake-stones, swords and knights, lasers, static and movable mirrors, item- and coin-transformations by pushing stones over them and by using lasers, umbrellas protect in an abyss, hammer and breakable stones (although not in the 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”), thieves, three-part 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-color-, yin-yang- and inverted yin-yang-stones, stones breakable by only one color, killer-balls, swap-stones, brush and paintable stones, changing one-way-streets with a magic wand, changing 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 (the actors) and horse-passing stones, pins, bananas, cherries can make you invisible, surprise-item.
5. Cracks, floor-springs, wormholes, etc., are all items, seeds can grow inside stones, the 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 necessarily mean that this level is difficult to understand; the unique mechanism or object might also be very intuitive, like in “Flood Gates”.

Speed and speed control (spe)

The spe-value corresponds not only to the maximum speed a level requires (like you need 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 at a constant velocity for a long time, as well as correctly estimating the speed that’s needed in a certain task, like shattering a sheet 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 appropriate time limit or speed control task. This can be a single, not-too-fast rotor in an open area.
4. Don’t stop! Examples include 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 beyond this.

The spe-rating again is cumulative, since 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 create a horrible task. In contrast to the other categories, for which the average is near 3 (or between 3 and 4 for kno), most levels are definitely spe 1. So, the spe-rating is more a supplement to the three core-ratings int, dex and pat.

Combinations of ratings

Sometimes, it can be interesting to have a single value to measure the difficulty of a level. To calculate such a universal rating, a simple possibility is choosing 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. Yet you should also choose these weights carefully 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 universal 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 a special property, in that it takes relatively broad 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 low or very high values cannot appear in this combination, such as 2 or 99. Other combinations lead to full but narrow, or to broad but noncontinuous spectra.

1.5.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 world record holders are listed below.

The PAR value is the “professional average rating” of the level. It is the harmonic average of all scores that Enigma players have retransmitted. However, we take into account only scores from players who have solved a certain number of levels. Opposed to the world record, which will be very difficult to gain, the PAR value is a much more realistic aim for an ambitious player. If you are equal or better than PAR, the levels are marked with a speeding blackball within the level menu.

The author’s value is another reference score. Most authors are not keen on holding the world record of their own levels. However, they will likely know the fastest way to solve the level. If your score is much higher than the author’s 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 the number of players who solved this level to the number of players who retransmitted scores. Actually, we take into account only those players who could have solved the level. For example, players who did retransmit scores before the level was written, without updating afterwards, are not taken into account. A low percentage is a hint that a level is not easy to solve.

1.5.3 Versions

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

For you as a player, the ‘Score’ version number can be interesting. A level you had solved with a certain score may appear with a red triangle in the level menu in an updated Enigma release of the level. Although the level menu displays the medals showing that you solved the level, it will not display the score values anymore. This is due to an 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.

1.5.4 Private Annotations and Ratings

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

Enigma stores annotations in your private applications ‘state.xml’ file. It permits 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.

Enigma stores the ratings with the scores and evaluates them anonymously. Enigma displays the resulting average rating of all users, for your information. Note that different ratings are possible for different score versions of the same level, because levels may improve as a result of suggestions by users. If you do not re-rate a new version of a level, Enigma inherits your rating from a previous version.

1.5.5 Screenshots

While playing a level, you can make screenshots by pressing <F10>. You can make several screenshots in sequence for documentation purposes. Enigma will store each with a unique image filename. Using the level inspector, you can view the screenshots directly from within Enigma. Just click on the screenshot button to view the first image.

Because any buttons would disturb the view of a screenshot, all functions are keyboard commands. Press <F1> to get a help screen. <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 as to where to search the other screenshot files on your ‘user image path’ (see section Locating Resources).

1.6 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. You can see your handicap for each levelpack 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, with the number of levels you solved in PAR.

The handicap is similar to the golfer’s 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 negative. 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, here is some additional information, which others may skip and continue with the next chapter Levelpack Basics.

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

However, for the PAR calculation, we take into account only scores from users who have solved more than a certain percentage of levels (currently about 10% of the levels). For every level, we calculate the harmonic average of the scores of these ‘professionals’. We take professionals who did not solve a level 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 (short) times with a greater weight than large (long) solution times.

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

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 fewer levels, Enigma will scale the sum by a factor 100/size to result in comparable handicap values. Handicaps are stated with one digit behind the decimal point.

1.7 User Sound Sets

(The following information accounts only for Enigma 1.01 and above.) Sound effects are triggered by so-called ‘sound events’. These sound events usually have a name (like ‘dooropen’) and an associated location (the coordinates of the door) which affects the way a sound effect is played. The collection of all sound files, their assignment to sound events, and some additional information how to play them is called a ‘sound set’.

You can use own sound files to create own sound sets for Enigma, and choose among them in the options menu (entry ‘Sound set’). You can distribute these sound sets under your own choice of license and install sound sets from other users. There is no internal limit for the number of installed sound sets.

The sound event is converted into a real sound effect using tables, you can find such tables in the ‘data/sound-defaults.lua’ file and in the empty sample file at ‘reference/soundset.lua’. Each entry in these tables is either a string like ‘enigma/st-coinslot’, which is interpreted as the file ‘soundsets/enigma/st-coinslot.wav’ with some default properties, or a list of sound attributes enclosed in curly braces. Sound events triggered by a sound message are converted the same way. Here is an example of such an entry:

dooropen = { file="my_soundset/open-door", volume=0.9, priority=4 },

The meaning of these attributes is as follows:

• ‘file’ Path and name of the sound file for this event, without the ‘.wav’ extension.
• ‘volume’ The sound volume: 1.0 is default, 0.0 is silent.
• ‘priority’ If many effects are active at the same time, high-priority effects can replace lower-priority effects. Use an integer between 1 and 10 (default 1). This property does not yet work with Enigma 1.01.
• ‘global’ Either ‘true’ or ‘false’. If true, no stereo effects are applied and there is no attenuation. Used for menu sound, level end sounds, etc. Default is ‘false’.
• ‘loop’ ‘true’ or ‘false’. If true, the sound repeats infinitely until canceled. Default is ‘false’.
• ‘damp_max’, ‘damp_inc’, ‘damp_mult’, ‘damp_min’, ‘damp_tick’ Parameters for sound damping. Sounds from noisy objects like light passengers are damped to reduce the noise. For this, the sound event’s frequency is estimated. ‘damp_max’ calibrates the maximal damping factor (high means quiet), ‘damp_inc’ how fast the damping accumulates, ‘damp_mult’ is an overall factor, ‘damp_min’ defines a lower bound for the damping entries (beyond which they are removed from memory) and ‘damp_tick’ the factor that’s applied all 0.1 seconds. See ‘sound.hh’ for details. Defaults: 10.0, 1.0, 1.0, 0.5, 0.9.

To design a new sound set, proceed as follows:

1. Create a new folder containing a copy of the sample file ‘soundset.lua’ and the wav files you want to use.
2. Move this new folder into Enigma’s "soundsets" folder in your user path. (Possibly you have to create it.) The directory structure should look something like this:

   (user path)/soundsets/my_sounds/ /soundset.lua /high_pitch.wav /soundfile_13.wav ...

3. Run Enigma and choose ‘My Soundset’ in the options menu. Since this file’s sound set does not map any sound effect to a wav file, you should hear nothing.
4. Edit the contents of ‘soundset.lua’ to your liking. You can access the default sound files, e.g.:

   ... coinsloton = { file="enigma/st-coinslot" }, ...

   When using own sound files, remember to add the subfolder, like in

   ... coinsloton = { file="my_sounds/soundfile_13" }, ...

   No extension ".wav"! It’s added automatically. Make sure that the extension is in lower case letters.

5. Replace ‘MY_SOUNDSET’ by a suitable variable name, and ‘My Soundset’ by the name you want to see in the sound options menu. Remember to make it short enough to fit on the button. The three identifiers variable, button name, directory name need not have the same names, but it eases the life of other developers to give them similar names that uniquely determine the sound set.

Remember to choose the sound set in the options menu anew each time you change its name. And always shut down Enigma before changing sound sets, new sounds are not recognized during runtime.

Feel free to zip and distribute the whole directory containing your sounds and the ‘soundset.lua’ file. You can install a downloaded zipped sound set simply by unpacking it and placing it into the ‘soundsets’-subdirectory of your user path. Make sure that the ‘soundset.lua’ is always exactly one subdirectory below ‘soundsets’. Deinstall a user sound set simply by deleting its directory. Renaming the directory does not suffice – you have to rename the ‘soundset.lua’ if you want to hide a sound set from Enigma. This can be advantageous if you use interdependent sound sets (sound sets that share sound files) and want to deactivate just one of them.

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 level sources of its own and consists only of crossreferences, we speak of a crossindex, since just a single index file represents the levelpack.

These definitions suit all versions of Enigma well. However, 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 up the following aims:

• an ‘Auto’ levelpack that allows level addition by drag and drop of the level source
• levelpack addition simply by 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 conversion of Enigma 0.92 levelpacks

Some of these features work seamlessly. 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:

2.1 Getting Started with Levelpacks

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

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 you can play it like any other level.

Please note that Enigma displays erroneous or incompatible levels with an error icon in the level menu. Of course an attempt to run such a level will result in an error message. 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, and you may even use url addresses of levels stored on the internet. Levels added to the commandline are accessible via the ‘Startup Levels’ levelpack.

If you want to run an old-fashioned Lua level that someone wrote for Enigma 0.92 or earlier, you may try to start it via the commandline. These old levels miss necessary metadata for auto detection. However, commandline-supplied levels are treated as temporary levels available just for a single run of Enigma; reasonable defaults substitute the missing data. The level will probably run, but scoring and copy, paste 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. You can install all of them simply by copying the files, but we have to distinguish the three formats.

You must copy levelpacks distributed as directories, with level files and an index file in them, to the subdirectory ‘levels’ on your ‘user path’ (see section Locating Resources).

You must copy levelpacks distributed as zip archives to the subdirectory ‘levels’ on your ‘user path’. You do not need to unpack the zip, although it is possible, as described in the section Zip Levelpacks.

You must copy levelpacks that are distributed as a single XML index file to the subdirectory ‘levels/cross’ on your ‘user path’.

All new levelpacks should be accessible via the levelpack menu after restarting Enigma.

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 your own levels, you may want to proceed directly to chapter Level Basics. The rest of this chapter explains how to arrange and sort existing levels in your own levelpacks.

2.2 Converting 0.92 Levelpacks

With the changes of the levelpack index format, converting old levelpacks is necessary. Although the main work is done automatically just by starting Enigma, a few special cases remain that need manual preparation. Further on, after the autoconversion, some cleanup may be useful.

If you formerly maintained 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 since Enigma 1.00 will never write to the system levels directory, it will perform updates and conversions only 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 the ‘index_user.lua’ file, which you should store on your ‘user path’.

If you maintained several of your own levelpacks, Enigma 0.92 allowed you to keep them in several subdirectories of the ‘levels’ directory. However, since it also allowed you to keep all level files and different indices in the ‘levels’ directory itself, you will run into trouble with the auto conversion, because Enigma 1.00 allows only one levelpack with attached level files per directory. In this case, we recommend a step-by-step conversion: in every step, provide only one old index for conversion. Enigma will convert this index to a 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’. Since Enigma 0.92 did not have a concept of cross-references, and Enigma 1.00 requires that you store all level files attached to a levelpack in a single subdirectory, the conversion algorithm needs to guess the correct subdirectory. It simply takes the subdirectory of the first level. If this does not fit, you may need to clean up your 0.92 levelpack prior to conversion.

Enigma should convert all other standard levelpacks without problems. It only performs the conversion 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 keeping a backup of the old index until you have completely switched to Enigma 1.00.

If you used a levelpack of your own in the zip format, you will find a subdirectory named with the base name of the zip archive in your user ‘levels’ directory. Enigma stores the converted ‘index.xml’ within this directory. You may want to exchange the old ‘index.txt’ in the zip with the new index. Afterwards you can delete the subdirectory, since Enigma will load the index 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.

2.3 Zip Levelpacks

Besides the classic 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 classic subdirectory levelpack, you can simply zip the complete subdirectory and name the zip with the name of the subdirectory, plus the standard ‘.zip’ suffix. Now you can completely remove the subdirectory; Enigma autodetects the levelpack and it is fully playable. Even cross-references into this levelpack will not be broken!

On the other hand, Enigma allows you to expand every zip levelpack to a subdirectory with index and level files. Again, everything runs and no cross-references are broken.

If you keep both, the files contained in the subdirectory precede files in the zip archive. Thus, Enigma stores updates of single files in subdirectories in parallel to existing zip archives.

2.4 Grouping and Sorting Levelpacks

As the number of levelpacks increased, it became 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

Still, 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 as many characters as you are used to. 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. Selecting the first pseudogroup displays the levelpack in every group. This is the default assignment of the ‘Startup Levels’ group. 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 meanwhile you have deleted the group.

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 likely the ‘User’ group. Right or ctrl click on the group and simply click on the ‘New Levelpack’ button. Enigma will call the levelpack configuration menu, which allows you to enter all the 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. You may use alphanumerical characters A-Z, a-z, 0-9 and space, underscore and hyphen. Note that you may rename the pack later for a better or more suitable display name (see section Modifying and Deleting Levelpacks).

Later, 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 your own self-written levels or levels that you download from the internet. You may use the crossreference levelpacks for your favorite collections, where you simply 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, if you have not resorted the levelpack manually (see section Grouping and Sorting Levelpacks). This default value is relevant only 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 well in most circumstances.

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

Finally, when you have completed the configuration, you can create the levelpack by clicking ‘OK’. Enigma will create the levelpack on your ‘userpath’ (see section Locating Resources).

If you decide not to create a new levelpack, just click ‘Undo’. Enigma will not create or change anything in this case.

If you want to set up the new levelpack immediately, you can click directly on ‘Compose Pack’. Enigma will create the levelpack, and you can use the composer to fill it with levels.

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. However, an ‘Edit Metadata’ button will appear only for your own levelpacks, which Enigma stores on your ‘userpath’. Clicking on it allows you to edit the metadata.

Renaming the levelpack is possible, but Enigma will not change the filenames anymore. It will use the new name as the logical levelpack name that shows up in Enigma.

Other attributes that you can modify include the ‘Default Location’ and the ‘Owner’.

Note that changing the levelpack type later is not possible. You must create a new levelpack of the proper type and copy the levels by using Composing Levelpacks.

We do not provide a levelpack deletion function to avoid unintended loss of levelsources. Still, the deletion of a levelpack is as simple as deleting the complete levelpack directory on your ‘userpath’. For crossreference levelpacks, you simply need to delete the index XML file on the ‘levels/cross’ subdirectory of your ‘userpath’.

2.7 Composing Levelpacks

You can change the levels of a levelpack by using the levelpack composer. You call it by right or ctrl clicking on the levelpack button in the levelpack menu, then clicking on the ‘Compose Pack’ button in the levelpack configuration menu.

The composer looks similar to the levelmenu, but it provides other functionality. Enigma lists all commands in the F1 help menu. First, if you compose your own levelpacks, you may note that the levels are bordered red. This is a warning, since you can modify these levelpacks. System levelpacks (the distributed Enigma levelpacks) will border the levels in gray, since 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 any levels you want from within the composer levels, and add them by ‘Shift click’; or use ‘F6’ to add all levels from the current levelpack to the clipboard. They will appear 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 the ‘OK’ button finalizes all changes. Leaving the composer via the‘Undo’ button reverts all changes.

Besides adding levels, you can delete levels by using the ‘delete’ button. Note that Enigma will delete the level files themselves if you delete a level that is not just a reference. Be careful with all levels that have the document icon on their preview. You can revert deletions with the ‘Undo’ button.

You can resort all levels with the ‘alt left arrow’ and ‘alt right arrow’. The new sorting appears immediately, and you can save it by using the ‘OK’ button.

You can use the ‘F5’ button to update the index from the levels. This is very useful if you edit levels yourself. The levelpack will notice changes in title, revision, easy mode support etc. Enigma updates all levels of the levelpack at once.

By using the Auto levelpack and the composer, you can set up 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, use the composer to insert the levelpack to your levelpack as a copy, and delete the unused level file copies from the ‘auto’ folder.

Outside the composer, you can use ‘F6’ in a normal level menu as well. This way you can swiftly create level packs from search results: Make sure the clipboard is empty, enter your search criteria in the search menu, start the search, press ‘F6’, create a new level pack, go to its composer, and press ‘F8’.

3. Level Basics

Now that you have played some levels of Enigma, you may have noticed that Enigma is quite a dynamic game with versatile levels. Thus, it is not astonishing that it is impossible 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 you play them. Other levels provide a dynamic behavior during the play; i.e., switches may open doors only in certain circumstances. To comply with these demands, we have integrated the powerful lightweight C extension language Lua as of version 5.1.4 into Enigma.

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

With the post-0.92 XMLification of Enigma, we achieved full XML support by integrating 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 need
• 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, such as 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 dependency management for levels and libraries
• add level update and upgrade support for levels and libraries
• substitute the old XML format with 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="2" el:status="stable"/>
      <el:author  el:name="Ronald Lamprecht"/>
      <el:copyright>Copyright © 2006,2009 Ronald Lamprecht</el:copyright>
      <el:license el:type="GPL v2.0 or above" el:open="true"/>
      <el:compatibility el:enigma="1.10"/>
      <el:modes el:easy="false" el:single="true" el:network="false"/>
      <el:score el:easy="-" el:difficult="-"/>
    </el:info>
    <el:luamain><![CDATA[
ti[" "] = {"fl_lawn_b"}
ti["#"] = {"st_box"}
ti["o"] = {"st_oxyd"}
ti["@"] = {"#ac_marble"}

wo(ti, " ", {
    "####################",
    "#                  #",
    "#  o      @     o  #",
    "#                  #",
    "####################",
})
    ]]></el:luamain>
    <el:i18n/>
  </el:protected>
</el:level>

You may notice that the XML portion contains all the metadata that the level author is accustomed to supplying with a level. The XML part is like a formula that you can copy from a template and fill out.

The Lua code is embedded in the XML. The only limitation to the Lua portion is that it reserves ‘]]>’ for the end mark, and you would have to substitute it with ‘]] >’. No further restrictions.

Since the example above includes all mandatory XML parts, we should achieve our aim to avoid major changes for Lua level authors.

You can 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 must look at the details of the format and explain the optional parts:

3.1 Getting Started with Levels

Most likely you are keen on understanding the basic principles of placing objects in a 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 welcome level in levelpack Enigma I, so you can try it out right away.)

 1    ti[" "] = {"fl_gravel"}
 2    ti["#"] = {"st_box"}
 3    ti["O"] = {"st_oxyd"}
 4    if wo["IsDifficult"] then
 5        ti["Q"] = {"st_quake", name="quake"}
 6        ti["T"] = {"st_timer", interval=10.0, target="quake"}
 7    else
 8        ti["Q"] = ti[" "]
 9        ti["T"] = ti[" "]
10    end
11    ti["@"] = {"ac_marble_black", 0.0, 0.5}
11
12    wo(ti, " ", {
13	"####################",
14	"#                  #",
15	"#                  #",
16	"#  O            O  #",
17	"#         @        #",
18	"#                  #",
19	"#        QT        #",
20	"#                  #",
21	"#                  #",
22	"#  O            O  #",
23	"#                  #",
24	"#                  #",
25	"####################"})

The resulting level looks like this inside the game:

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

 1    ti[" "] = {"fl_gravel"}
 2    ti["#"] = {"st_box"}
 3    ti["O"] = {"st_oxyd"}

First we declare some keys for objects we like to use in our level map. We just add each key to our ti tiles repository and assign an object tile description that consists of the object kind name in these simple cases. The two character prefix of the kind name shows us the basic object type like floor, item, stone, actor, etc.

 4    if wo["IsDifficult"] then
 5        ti["Q"] = {"st_quake", name="quake"}
 6        ti["T"] = {"st_timer", interval=10.0, target="quake"}
 7    else
 8        ti["Q"] = ti[" "]
 9        ti["T"] = ti[" "]
10    end

The welcome level provides two modes, the regular difficult one and an easy one. As the regular difficult one differs just in two additional stones we add two mode specific tile declarations.

In the difficult mode we assign two stone definitions. Each provides the stone kind and additional attributes. The ‘st_quake’ is the stone that closes oxyd stones when being hit or toggled. We just name it, to be able to reference it later on. The second stone is a timer that should get active every 10 seconds and should send a toggle message to its target, our oxyd closing ‘st_quake’. As we did name this stone we can reference it here as target by its name.

11    ti["@"] = {"ac_marble_black", 0.0, 0.5}

Now we just need to declare our actor. It is a black marble that should not be placed at the left upper corner of a grid but in the mid of the left border of a tile grid. Actually we just want to center it within the level. As a one screen sized level has the extension of 20 x 13 we need the offsets given above.

12    wo(ti, " ", {
13        "####################",
14        "#                  #",
15        "#                  #",
16        "#  O            O  #",
17        "#         @        #",
18        "#                  #",
19        "#        QT        #",
20        "#                  #",
21        "#                  #",
22        "#  O            O  #",
23        "#                  #",
24        "#                  #",
25        "####################"})

Now we can create the world simply by providing a map. We just need to call ‘wo’, our world handle, provide it our tile resolver, the key of the default floor and a map of tile keys.

You will find all conceptional background information in chapter Enigma Paradigm and more examples and syntax information in chapter Lua API. But first you should take the time to get aware of the XML based level metadata.

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. We include these elements 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 omitted -->
    </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 make sure 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 then detect the XML declaration and switch automatically to the given encoding. Note that unless you 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 additional remarks for XML newbies: The XML markup tags are quite similar to HTML. But XML requires a corresponding end tag ‘</element>’ for each start tag ‘<element>’. For elements that have only attributes and no content, you can and should use the alternative empty element notation ‘<element/>’. Note that when we define an element as empty or state that no content is allowed, not a single whitespace, not even a linebreak is allowed between start and end tag. Use the empty element notation to avoid mistakes.

We use a pretty printing format with an indentation 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 indentation.

This format is not mandatory. You can even insert linebreaks in text contents, within the marks, and even within attribute values. But note: 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.

A namespace identifier prefixes all tag names and attribute names. We use ‘el’ as an abbreviation for Enigma levels. All tag names you can manually edit use this prefix.

Finally, a short comment on the XML reserved characters, ‘&’ and ‘<’. These two characters are reserved as tag and entity starting characters. If you need them in text contents or in attribute values, you must substitute them by the entity sequences ‘&amp;’ and ‘&lt;’. Additionally, you must enclose attribute values with either ‘"’ or ‘'’. Of course, you must substitute the enclosing character used in attribute values, too. Use ‘&quot’ and ‘&apos’.

Elements:

/level, required, single occurrence

This is the root node. Only one instance of this node occurs 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 only level editor programs use the 4-attribute version as above. For manual level editing, 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 are 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 schemas used. The contents are 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 the namespace prefix for all level element and attribute tags, as standard. The prefix used can be arbitrary, but must match this attributes tag. The contents of the attribute is fixed to the Enigma level namespace.

xmlns:ee, optional

Only level editor programs use this last namespace definition. For example, we declared ‘ee’ as the namespace prefix for all editor element and attribute tags. The prefix you use can be arbitrary, but must match this attributes tag. The contents of the attribute are the editor’s namespace.

/level/protected, required, single occurrence

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 occurrence

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

/level/protected/elements, optional, single occurrence

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

/level/protected/luamain, optional, single occurrence

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 occurrence

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

/level/protected/i18n, required, single occurrence

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

/level/public, optional, single occurrence

This public node section is an optional extension to the protected part. It contains information that the author has not validated and may even be added after the last author’s review.

/level/public/i18n, optional, single occurrence

This public i18n section contains further translations supplied for the level. They may derive from the author or other sources. The translators will validate these translations, and they continue in use if the translators do not supply corrected versions. See Internationalization (i18n).

/level/public/upgrade, optional, single occurrence

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

3.3 Info metadata

The Info node contains all author-supplied metadata for the level. This is the source of these data. All other parts of Enigma, such as level indices, simply contain copies that will be automatically updated to the level’s original data.

Let us look at 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"

You may use the schema for single Enigma levels, libraries that contain level description parts for reuse, and descriptions for multiple levels at once.

‘level’ are all single level descriptions. It does not matter if you edit them manually or with a level editor program, or which description elements you use.

‘library’ are level description parts that may be included in levels. Library Files consist simply of Lua code in the luamain node. Libraries may make use of nearly all nodes besides the ‘/level/protected/info/score’ and ‘/level/*/i18n’, which both must be provided, but will not be evaluated. Libraries are included in 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 usually describes a whole set of level maps in a single file (see section Multilevel Files).

quantity, optional

The number of levels contained in a multilevel file (see section Multilevel Files).

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, such as difficulty, network and control.

comments, optional

Optional comments, such as credits, dedication and code comments. See <comments>.

update, optional

Update and Upgrade

upgrade, optional

Update and Upgrade

score, required

The author’s own <score> of this level.

3.3.1 <identity>

The ‘identity’ element is required, since 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. The string can contain arbitrary characters that are displayable by Enigma’s font and XML conformant. Just in case of Multilevel Files a trailing hash sign has a special meaning. Anyway please make sure that the title is not too long, since Enigma will use it 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. Enigma displays the subtitle 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 upcoming release updates. The id string should not contain spaces, braces and wildcard characters, that means no character out of ‘*? ()[]{}’. Enigma’s main demand on the id is that it is unique among all levels created by all authors around the world and that it does not end on a closing square bracket.

Since you can edit levels 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’ stands for a user-specific name and ‘NNN’ for a random number. For example, my level called ‘Houdini’ has the id ‘20060816ral719’. Of course all levels created on the same day have to differ in the random number part. The id is an 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. Still, that does not harm since the only requirement is the uniqueness.

Contents:

The element itself is empty - no content is allowed.

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 positive integer number. New levels start with score version “1”. New level versions need to increase the score version number if the level modifications cause different solutions with incomparable score values. Of course, level authors should be very restrictive with such modifications.

During the development of a level, you should use the attribute ‘status’ to mark a level as not released. When 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 positive integer number. New levels start with release version “1”. You must increase the release version number if the level modifications cause either 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. Since such compensations will not run on the old Enigma version, the level versions must be distinguished by a different release number.

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

To enable people 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 search paths with identical filenames, id, score and release version, it will load the one with the higher revision number. This feature guarantees that an older level revision stored on the user’s home level directory cannot supersede a new revision of a level distributed with a new Enigma release. Online updates will check the level revision numbers, too.

Although the revision evaluates to a number, the attribute can take a second string format as the literal keyword ‘$Revision: 1.8 $’. This Subversion format allows level authors to let their Subversion repository automatically insert the level revision number. They must simply set ‘svn propset svn:keywords "Revision" level.xml’ at their repository for every level file. Since the Subversion revision number is ever-increasing, it fulfills our criteria. Note that Enigma does not require that revision numbers be consecutive.

status, required, values = “released”, “stable”, “test”, “experimental”

This attribute describes the quality of the level during development. Enigma uses the status to protect the score database from being spoiled by unplanned solution scores. It will record scores only for levels marked as ‘released’.

As a level author, if you start to change a released level, you should first change the status back to ‘experimental’. Then make your changes and test the level. When you are definitively sure that you did not introduce any spoilers, you can release the level again with a new revision and perhaps a new release or score version number.

Contents:

The element itself is empty - no content is allowed.

3.3.3 <author>

The information about the author him/herself. Enigma requires the author element itself, but all attributes are optional to allow an author to be anonymous. Please remember that level administrators and translators may need to contact you as the author. So please provide a way for them to contact 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 author’s 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 author’s email address or a newsgroup or forum he monitors. In general, this is a hint as to how to communicate with him or her. The value will simply be displayed as a string on the level info page.

homepage, optional

An address for the author or where the author publishes additional Enigma levels. The value will simply be displayed as a string on the level info page.

Contents:

The element itself is empty; no content is allowed.

3.3.4 <copyright>

The standardized location for the author’s copyright message:

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

Attributes:

none

Contents:

The author’s copyright notice.

3.3.5 <license>

Of course, every author is free to choose the license conditions for his/her levels. However, the author must 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 his/her own license as the content of this element.

open, required

A boolean statement, whether the chosen license fulfills the criteria of the Open Source Initiative (OSI). Please note that a value of ‘false’ may prevent your level from being distributed with Enigma.

Contents:

You may add a complete license text as the contents of this element. Please use the type attribute to identify the level.

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 behavior of various objects. This attribute is evaluated only for levels. Libraries ignore this attribute.

Contents - Elements:

The compatibility element itself contains only subelements as content.

dependency, optional, multiple occurrence

You can use this element to specify any Enigma-Lua library this level depends on. You can specify several libraries by multiple occurrence of this element. If you configure a library to be preloaded, the engine will load it before it loads or executes any level Lua code. 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 its suffix or any release extension. Enigma stores most libraries in the ‘lib’ subdirectory of its ‘levels’ directory, in most cases the resource path will be 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’.

However, libraries can also be totally level pack-specific. In this case, you may use a relative resource path, such as ‘./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. Enigma will check it on load of the library to avoid problems, and may use it with the release number to detect relocated libraries.

release, required

Although different release versions of libraries must have different filenames, we require to specify the library version. Enigma will check it on load of the library to avoid problems, and may use it with the release number 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. Yet even those libraries must be declared since Enigma will check them on conformance. You should always preload your libraries if you make use of the ‘elements’ section.

url, optional

This optional attribute allows you to specify a backup address for the library. This will be useful for using new libraries that are not yet distributed with the system.

For the development and test phase of new libraries themselves, 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 occurrence

You can use this element to specify any external text data file this level depends on. You can specify several files by multiple occurrences 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, the inclusion of such data within a level or even the distribution with Enigma may not be possible. However, distributing or downloading the data in the original unmodified format may be legal.

Attributes:

path, required

The resource path of the external data file without its suffix ‘.txt’. The path has to be either of the format "./name" for an external data file that is locally stored in the same folder as the level file, or will be saved at this position when it gets downloaded. Or the path can be of the format "externaldata/name" for shared external data files, that are referenced by multiple level files stored at different folders. The external data file will be locally stored or gets saved in the folder "levels/externaldata". In any case the local name of the external data file will have the suffix ‘.txt’ to mark it readable but not executable for the local operating system.

url, optional

This optional attribute allows you to specify an internet download address for the external data file. On first access a missing external data file will be downloaded and a copy will be stored locally for further access.

Contents:

none.

editor, optional, single occurrence

Special level editor programs use this element 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

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’. Set this attribute to ‘false’ only if the level is a 2-player-network game.

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. You can play a level by using the mouse to generate forces on the marbles, since it is the standard and was the only way up to Enigma 0.92. Or you can play a level using the mouse, or other input devices to balance the level-world with the marbles. Or you may use the keyboard with its cursor keys to move the actor like in classic Sokoban games.

Although the user has always the last choice to define the input method he/she currently wants to use, the author must define the standard control-mode that the scoring system uses. Enigma will save and evaluate only scores achieved in the defined control mode 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 interpreted as level solution time and displayed in a MM:SS format. The ‘number’ mode displays scores as plain numbers and lower numbers will be evaluated as better scores. This mode is appropriate for counting 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

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 internationalization support will not translate comments.

<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 occurrence

The place to honor people who helped to make your level run.

Attributes:

showinfo, optional, default = “false”

A value of ‘true’ will display the message on the level info page

showstart, optional, default = “false”

A value of ‘true’ will display the message on startup of the level. Please use this feature only in rare cases.

Contents:

The credits message itself. It may be broken into several lines. Whitespace will be collapsed before display.

dedication, optional, single occurrence

The place to dedicate the level to a honorable or 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 display the message on the level info page

showstart, optional, default = “false”

A value of ‘true’ will display the message on startup of the level. Please use this feature only in rare cases.

Contents:

The dedication message itself. It may be broken into several lines. Whitespace will be collapsed before display.

code, optional, single occurrence

Attributes:

none.

Contents:

The main code comment, which may be an explanation of the <version> status or a to-do list. It may be broken into several lines. This comment will not be processed.

3.3.9 <score>

In this node, the author should provide his own scoring values as hints and a 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 solution 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 him/herself. For levels with a score unit mode ‘number’, the value would be the number of marble moves or pushes.

difficult, required

The solution 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 him/herself. For levels with a score unit mode ‘number’, the value would be the number of marble moves or pushes.

Contents:

3.4 LUA code

This element 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 must be loaded, you can declare the library with the attribute ‘el:preload="false"’. You should use the new function @ref{enigma.LoadLib} to load the library.

The Lua code that is enclosed in a XML CDATA section. This limits the Lua code not to use the reserved end marker ‘]]>’. Any occurrence must be substituted by ‘]] >’.

On the other hand, the XML format extends the Lua capabilities to the use 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.

3.5 Internationalization (i18n)

The internationalization of levels is a driving force behind the level format changes. As you may have noticed, there are two ‘i18n’ elements, one in the author’s protected section and one in the public. Let us review how to use them for internationalization of the three documents of our ‘demo_i18n.xml’ level:

  <el:protected >
    <!-- elements omitted -->
    <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 single mandatory attribute ‘translate’ that defaults to ‘true’, stating the author’s decision whether the string should be translated. If the author does not want a string to be translated, he can and must simply 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’ display the English text 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.

Because we chose quite ambiguous English texts, it is very likely that translators who do not play the game but just translate the text, 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 with the English string as we will see later.

If the author is not native English-speaking, he should add his own ‘translation’ subelement to the ‘string’ 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 precedence over any translator’s translation and will work directly after addition without waiting for a translator’s translation.

Last but not least, we have an ‘i18n’ element in the public section. This element takes translation suggestions. The author may add them him/herself for other languages he/she knows. They may be added by others on the way to the user, or even by the user himself.

Translations in this section will work immediately after addition without waiting for a translator’s translation. However, available translations, provided by translators, will precede them.

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. One subtle difference exists, due to technical and practical reasons. ‘key’ attributes in the public section need to be XML identifiers; thus, you cannot 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 and 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 protected and in the public section. The sequence does not matter.

Let us review what the translator receives 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 since the author provided the German translation in the ‘# use:’ line

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 author gives the public translation in the ‘# check:’ line. Since it contains at least one mistake, the translator will correct it, as shown in the ‘msgstr’ string.

3.6 Usage

After all the theory, let’s look at 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, for example, the ‘demo_i18n.xml’ supplied with this documentation. Add your personal data to your template and store it as the basis for all new levels you write.

Some level authors are very familiar with the Lua file format since 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. Nevertheless, these authors are used to supplying 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” since 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 must start exactly with ‘--xml-- ’, 8 characters, 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 course ‘US-ASCII’ to successfully use the Lua-commented XML format. Please remember, that although the XML part is Lua-commented, it must still be evaluated and thus must be valid.

Every level stored in this Lua-commented XML format as a file with extension ‘.lua’ can be used locally for command line use as well as in any level package that is stored on the Enigma user’s home directory. However, Lua-commented XML levels cannot be stored on Internet servers or be updated online. Thus, this format is good for level development, but you should convert the levels to the pure XML format for distribution. Please note that Enigma looks for XML levels first, and uses Lua levels only if it can’t find an XML level.

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

Since 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 properly installed Lua 5 version. On Unix systems, you can mark the scripts as executable and simply call ‘xml2lua demo_simple.xml > demo_simple.lua’.

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

As you fiddle with the XML metadata, you may produce syntactical errors, of course. You can validate your level by trying to start it with Enigma. XML errors are output as Lua errors are. If the error messages are too long to read, you may want to start Enigma from the command line with the 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, such as Exchanger XML Lite. Such editors will provide you with selections of all possible elements and attributes at each position.

3.7 Update and Upgrade

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

If Enigma loads a new level version, which differs just in the ‘revision’, we speak of an ‘update’. You can perform updates automatically and replace old versions with the updates, since the author guarantees them to be compatible in scoring and dependencies. The author should provide a download address for automatic updates in the protected info element:

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

Attributes:

url, required

A long-term 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. We call the download of such a new level version an ‘upgrade’.

To publish the availability of an upgrade release, the author should update the previous release with a final revision that simply 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 long-term valid, complete address for upgrade downloads of this level. A path to the new file.

release, required

The release version of the upgrade.

Since 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 author’s protected section.

3.8 Library Files

Libraries are collections of Lua functions for reuse in many levels. To use a library, you must declare it as a dependency, as described in <compatibility>. Preloading the library is all you have to do to use the library. Otherwise, you can use the function @ref{enigma.LoadLib} to load the library at a certain point of execution.

Enigma provides several very useful Libraries. You will find them on the system path in the subdirectory ‘levels/lib’. Most of them are documented in-line. You will find a separate documentation file ‘doc/ant_lua.txt’ for ‘ant’.

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

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 you should set to ‘library’. You must provide all other elements and attributes as you must for levels. Of course no scoring related attributes will ever be evaluated and you should set them to default.

Libraries may depend on others, so you must provide an id and a release number. Several releases of a library can coexist and you can update and upgrade them if you provide the necessary information. Of course, libraries may contain document strings that can be localized if you provide the ‘i18n’ elements.

The ‘el:luamain’ element takes the complete Lua code as it does for levels. Let’s 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>

3.8.2 Maintaining a Library

Libraries may exist in different releases and revisions. Library versions that differ simply in the revision, denote compatible versions. Library versions that introduce incompatibilities must differ in the release number. However, since existing levels may depend on the legacy behavior of the older release, you must maintain both library release versions and distribute them with Enigma at the same time.

To coexist, these different library releases must 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 the addition of an underscore and the release number plus the suffix ‘xml’. Thus, you must store release ‘lib/ant’ as ‘lib/ant_2.xml’.

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

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

3.9 Multilevel Files

Another concept of code reusage besides Library Files are multilevel files. The code contained in a single file generates several levels, called sublevels, that appear as autonomous levels in a levelpack. Of course this concept is much less flexible than the library concept as other level files can not reuse the code. But you can write a multilevel if you wrote a lot of specific code for a complex level that provides more than just two variants, which would be otherwise presented as ‘difficult’ and ‘easy’ <modes>.

But the main reason for multilevel files is the support of foreign game level formats like Sokoban, which describe a whole set of levels in a single file. Enigma imports these original files with just a few lines of code. It would be inefficient, even though being possible, to write an Enigma level stub for every level imported from a single foreign file.

But multilevel files have some restrictions. They use a single set of XML level metadata. Thus these metadata must fit to all levels. The <version> will be identical as it reflects either the code version of the native level or the version of the imported foreign file. But the other data like <author>, <compatibility> and <modes> have to match, too. If they do not, you can not use a multilevel file.

Just the values for ‘title’ and ‘id’ will and have to differ for all levels described by a single multilevel file. There exists special support for multilevels to handle these attributes.

Let us look at all attributes and features of multilevels that differ from standard level files.

First you have to declare in the Info metadata element the type as "multilevel" and to provide the quantity of generated levels. The sublevels will be numbered from 1 to the given quantity.

In the element <identity> you have to provide just one unique level id value. Enigma will automatically append the string "[1]" for the first sublevel, "[2]" for the second and so on. Thus every sublevel has an unique id.

Additionally you should provide a base title for the levels in this metadata <identity> element. If your title ends with a hash ‘#’ sign Enigma will autogenerate titles for the sublevels by appending the sublevel number to the given common title string.

For individual sublevel titles the LUA code has to provide the titles. The title in the <identity> element may not end on a hash sign and will only be used as a default title base in case the LUA code fails to provide a sublevel title. Prior execution of the Lua code the global attribute SublevelNumber gets initialized. The Lua part has either way to load the appropriate sublevel based on this number. Now it has additionally the task to set the second special multilevel global attribute SublevelTitle.

<compatibility> externaldata

4. Enigma Paradigm

Now that you have learned about the formal declarative XML part of a level you should be eager to understand the basic principles of the participants of an Enigma level world. In this chapter we explain all the fundamental concepts and the terms used in the following chapters that describe the level author’s view of a level.

Please note that we describe the features of the new API of Enigma 1.10. The API of the earlier releases does not provide all the features and differs in several aspects.

4.1 The World’s Structure

We speak of a level as the opus as a whole that describes the initial composition of a gaming world and its dynamic behaviour during the game play. Let us look at the participating objects in details.

4.1.1 World’s Shape and Coordinates

Having played a few levels you will have noticed that every screen shows quadratic tiles, 20 ones in the horizontal and 13 ones in the vertical direction. Even if it is difficult for a player to map together all rooms and screens of a large level, every level world has the shape of a rectangle in whole. Nevertheless some parts may never be visible to the player due to walls of stones or oceans of water.

On the creation of a world the level author has to give its size in measure of tiles. The given width and height of the world are fixed and cannot be changed later on. A common size is 20x13 for a Onescreener. But there are no limits. You can even build levels smaller than a screen. Note that for larger levels you have to take into account that one tile row or column is usually shared between two screens on scrolling. Thus a level of 2x2 screens has a size of 39x25 tiles, a 3x4 screen level has 58x49 tiles,...

Looking at the edges of all the tiles we get a grid that spans our world. We define the upper left corner of our world as the position {0, 0}. The first coordinate is the horizontal offset to the right, the second coordinate the vertical offset to the bottom. For a Onescreener level the tile in the lower right corner is located at position {19, 12}, whereas the corner itself is at the position {20, 13} (Note that this point is actually not part of the level anymore).

A position of an actor like the black marble needs to be given by two floating numbers as coordinates like {1.5, 2.5} for an actor positioned in the center of the tile that is one column right and two rows down of the upper left corner tile.

But most objects like stones can only be placed on the fixed integral grid positions. Even if you try to put a stone on {1.5, 2.5} it will be put on the grid position {1, 2}. Thus we speak of a grid position if just the integral part is taken into account. You may note that a tile is positioned according to its upper left corner. Actually the upper and the left edge are part of a tile, whereas the right and lower edge belong to the neighbour tiles.

Finally let us look more precisely on the tile itself. On one grid position you may place a floor, an item, a stone and even several actors. The combination of all objects on one grid position is called a tile. It is a common technique to declare these object combinations once in so called tile definitions. As many grid positions share the same combination of objects these tiles can be reused very efficiently.

4.1.2 Object Layers

On every grid position you may set a floor, an item and a stone. But just one of each. If you set a second stone the first one will be replaced. Floor, item and stone have a unique physical arrangement with the floor always being below an item and a stone always being on top of the others. Thus we speak of three object layers - the floor layer, the item layer and the stone layer.

The floor layer has a unique prerequisite. Every grid position needs to be covered by a floor. You can define a default tile which contains a default floor that gets automatically set on every grid where you set no other floor. Even if you kill a floor, that means removing a floor without setting a replacement floor, a default floor will be set for you.

The floors provide two elementary features to the game: friction and adhesion. The friction slows down actors and the adhesion enables you to accelerate actors with your mouse. A floor may additionally cause a directed flat force that gives the user the feeling of a slope. And last but not least a floor may burn. A whole set of attributes let you control the details of the fire behaviour.

The item layer is shared between items that an actor can pick up and items that are static. The first category are items like keys, banana, etc. Static items are bombs, landmines, triggers, hollows and items that will only be set by the system itself like laserbeams, fire animations, ash, etc. As only one item can be positioned on every grid position a marble can not drop an item on such a static item. This is the technical reason that you can not intercept a laser beam by dropping an item. But as a level author you are free to add any item you like to the initial grid tile.

The stone layer is straight forward. The level author can choose a stone out of the repository per grid. Of course most grid positions should be kept free for the actors to move around. Even if most levels have a stone wall at the border of the world that visually limits the area this is not mandatory. Without a stone wall the marbles will be bounced at the physical boundary of the world.

The actors live in another layer that is not grid based. The actors can be placed at any position. Actors that pass a stone will be displayed below the stone.

4.1.3 World as an Object

Friction, Brittleness, Modes and Co., Scrollmodes

4.1.4 Unpositioned Objects

You should be missing at least one object, that can neither be assigned to a single position nor to one of the above layers: rubberbands! In fact there are many Other Objects besides floors, items, stones and actors that are unpositioned. Besides visible rubberbands and wires useful gadgets, that help in plug and play composition of levels, can be added to the world.

All these other objects are full objects concerning the following chapters. But you need to use the world’s add method to add them and you need to use Object Reference or Object Naming to access them later on, as no position driven access does exist.

4.1.5 Player and Inventory

Enigma is conceptionally a game for 2 players. But nevertheless it can be played by one user on a single computer by toggling the control between two virtual players. We do call these virtual player’s YIN and YANG, as the first player controls in most cases a black marble, whereas the second controls usually a white marble.

Each virtual player has its own inventory of up to 13 items. The leftmost item of the inventory is called ‘revealed’, as an item activation by a mouse click does activate this item and on actor hits this item may cause special actions.

The players inventories do exist outside of the rectangular world. Thus any item being part of a player’s inventory will report an invalid, out of world position, that evaluates on an ‘exists()’ request to ‘false’. You can add items directly to inventories by the advanced world method add.

Even though the actors are assigned to players they are quite independent objects that live in one of the Object Layers. Their relationship to players is as follows:

Each virtual player can own and control one or several actors of any kind. That means player YIN is not limited to a black ac_marble, but may as well control a white ac_pearl, an ac_horse or any other set of one or several arbitrary actors.

Ownership and control of actors are two distinct aspects. Ownership of an actor means that every item picked up by an actor ends up in the player’s inventory and items of the player’s inventory can act on all owned actors. The control of an actor by a player does just affect the movement of the actor by the users force input. An actor may be controlled by a player without parallel ownership. Another actor may be owned by a player without being controlled by it, thus being a passive actor that depends on being pushed by others. An actor may even be controlled by both players, but it can just be owned by one player or none.

The assignment of actors to players is solely configured by Actor Attributes.

When a single user plays Enigma he starts with the control over the player Yin. By usage of yinyang objects he can toggle the control to the player Yang and back again. Items it_yinyang are added automatically for network levels when played by a single user. They allow an arbitrary switch between the players. The stones st_yinyang do limit the user’s ability to switch between the player control.

4.1.6 Owned Objects

Besides objects owned by a player and being part of his inventory, objects can be temporary part of another object. The most obvious case is an item contained in an it_bag. Other samples are two st_shogun stones pushed onto the same grid position or for a short fraction of time a stone swapping the position with an st_swap or an st_pull.

In any case the owned object will report the same position as the owner itself. Even in case of some items contained in a bag that is itself part of another bag all items will report the same position as the outmost bag. If this bag is part of a player’s inventory all items report an invalid position.

You can not directly enforce ownership by setting two objects to the same position as this standard operation will kill and replace the old object by the new one. Where possible, like in the case of a bag, you can add objects to a container object by usage of the world advanced method add.

4.2 Object Description

Knowing where to place objects it is time to know how to select an object type, how to specify the details of the object and how to reference it later on.

4.2.1 Object Kind

Up to now we have spoken about object kinds of floor ‘fl’, item ‘it’, stone ‘st’ and actor ‘ac’. All these kinds are called abstract. You can check if a given object is of such a kind, but you can not instantiate an abstract kind.

To create an object you need to give a specific kind name like ‘st_switch’. You will find all object kinds described in the chapters starting with Floor Objects. All these kind names with at least one underscore can be instantiated.

Most kinds provide subkinds like ‘st_switch_black’ and ‘st_switch_white’. In case of the switches you get a color independent switch if you do not append a suffix. In other cases like ‘st_chess’ the super kind will result in a default ‘st_chess_black’ as no colorless chess stone exists.

If you request an object for its kind it will always return the most specific kind. This means that a fresh generated ‘st_chess’ returns the kind ‘st_chess_black’, whereas an ‘st_switch’ reports its name unchanged.

Objects can change their kind by level code statements or by user actions. You may set a color on a switch or a marble may cause a color change on a chess stone by hitting it with a revealed wand. The object will report the new kind on subsequent requests.

A few special object kinds do exist only for setting a new object. They are usually named with a suffix ‘_new’. These objects will never report their initial kind name but change to a standard kind immediately.

If you are not interested in the specific subkind you can check an object for conformity to any super kind. E.g. any switch stone of whatever color will return true if checked for ‘st_switch’.

4.2.2 Object Reference

Having set objects to the various layers a level author sometimes has the need of referencing them later on. On callbacks the engine provides references to sender objects. But the author can request any grid object anytime by its position.

With an object reference, that is of a special Lua type ‘object’, you can request the objects on its current state and attributes, modify the object, send messages or perform any supported methods of the object.

Objects can be grouped for efficient handling of common operations on all affected objects. E.g. if you can send a message to a group of objects all objects will receive the message in turn. The sequence of several objects in a group is constant and guaranteed to be observed in processing common operations.

As objects can seize to exist you have to be aware that the references are volatile, too. You can check every object reference for existence. But in many cases the validity of the reference is unimportant as Enigma 1.10 is very tolerant on invalid object references access. The operations will simply be ignored and requests will return default values.

As a general thumb rule you should request and keep object references just for the time of a local call. As long as your level code is processed in sequence without the running world simulation giving the player a chance to kill objects by marble actions, objects should seize to exist just due to your own direct statements.

To gain access to an object later on a subsequent call you can address it via two methods. First you can address it via its position. But as many objects are movable the position is not constant. Therefore you can address an object by name. See section Object Naming.

4.2.3 Object Naming

For addressing objects on a long term valid basis every object can individually be tagged by a name. Assigning a name to an object is as simple as setting the attribute ‘name’ with a unique string on this object. Of course you can request an objects name by reading the attribute ‘name’.

The name is a string that should be made up of characters ‘a..z’, ‘A..Z’, numbers ‘0..9’ and the underscore ‘_’. Other special characters are only allowed as far as they are explained in the following text.

It is up to you to ensure unique names. Reuse of an already assigned name will unname the prior object and assign the name to the new object. To simplify the naming of larger groups of similar objects you can add the hash sign ‘#’ as the last character to a name, e.g. ‘mydoor#’. This causes Enigma to add a unique random number to the given string. Thus an auto named object will never unname another prior auto named object. But if you delete an auto named object that has been named e.g. ‘mydoor#103284’ the number and the same name may be assigned to another that is created later on.

All named objects are registered by the named object repository. The API provides a variable ‘no’ that allows you to retrieve any named object, e.g. ‘no["mylaser_a"]’. You get an Object Reference or ‘nil’, if no object is registered by the given name.

As you can auto name groups of objects you are allowed to use the wildcard characters ‘?’ and ‘*’. The question mark replaces a single arbitrary character, the asterisk any number of arbitrary characters. E.g. ‘no["mydoor#*"]’ retrieves all auto named ‘mydoor’ objects in a single object group.

Many object attributes like ‘target’, ‘destination’ need object references to other objects. Besides a volatile Object Reference you always can provide a name string as a long term valid object reference. If the attribute allows several objects to be given you can either give a group of object references, a table of object names or an object name with wildcards. Thus the string ‘"mydoor#*"’ is a valid target.

Often switches are located near by their target object. As a major shortcut you can reference the nearest object out of a group by prefixing its name with an ‘@’ character.

ti["F"] = {"st_floppy", target="@door#*"}
ti["D"] = {"st_blocker", name="door#"}

With this tile declaration you can describe arbitrary number of floppy switches and nearby blocker doors in a world map all by the same two tile key characters. Every floppy switch will target the nearest blocker door. If two targets are given within the same distance the one located in the south will win. If the targets are additionally horizontally aligned the one located in east will win. In the rare case of objects located on the same position stones will precede items, floors and actors. The chosen target or destination depends just on the location of these objects and their type, but nothing else. Thus you can rely on a stable selection mechanism. Nearest Object Clustering may help you in case of unexpected selected equidistant targets.

Auto naming and nearest object features help you to reduce the number of needed tile declarations. Resolvers like res.autotile and res.composer are another feature for reducing the need of tile declarations.

Another unique feature of object names is their late on access evaluation. This allows you to reference an object prior to its existence. E.g. if you want to set two vortices each declaring the other one as its destination, object names are the favorite solution:

wo[{3,4}]  = {"it_vortex", name="vortex1", destination="vortex2"}
wo[{15,9}] = {"it_vortex", name="vortex2", destination="vortex1"}

In general you will need to use object name references within any tile declarations as none of the referenced objects will yet exist at the point of tile declarations.

Objects do change over time. Doors do open, a chess may be recolored, a blocker stone may shrink to a blocker item. This means that the kind of the objects will change. But in many cases this means that the volatile object reference will brake, too. For the sake of the level authors the identity of the object will be transferred even if the reference gets invalid. And like the user attributes the name is part of the object identity. Thus if you name an st_blocker and it shrinks to an it_blocker you will retrieve this item if you ask the name object repository for the named object.

When an object like a door is completely killed, e.g. by an it_seed, it can no longer be targeted by active objects like switches. A still existing reference to a no longer existing object does not cause problems on Messages. But what about the nearest object references? To avoid problems due to killed objects the standard nearest object reference with just one ‘@’ as prefix is finalized on Level Initialization. This means that they get substituted by the unique name of the nearest of all existing objects at a point of time when all objects have been created, but before the user takes action and can incidentally kill a candidate.

But sometimes you may like a dynamic nearest object target or destination. One that is evaluated when it gets accessed. By prefixing a name with ‘@@’ the reference will not get finalized on initialization but remains dynamic.

ti["c"] = {"it_coin_s", "magic#"}
ti["v"] = {"it_vortex", destination="@@magic#*"}

Setting three magic coins and one vortex in your map will teleport the marble to the grid of that coin that is nearest to the vortex at the moment of teleportation.

To avoid unexpected problems with invalid object references a few critical objects are internally autonamed if the level author does not provide a name. But these unique names should never interfere with the user assigned object names.

4.2.4 Object Attributes

One of the key concepts for the versatility of Enigma is possibility to fine tune objects by means of attributes. The level author is not limited to a fixed set of preconfigured objects as given by the object kind.

An attribute is a name, a string, with an assigned value. E.g. ‘obj["inverse"]=true’ sets a single object attribute to a boolean value and ‘{"it_magnet", range=6.5}’ describes a magnet item with an initial set floating point attribute.

The scope of values is manifold. Most Lua types and a bunch of Enigma specific types can be assigned:

• bool
• int
• double
• string
• nil, DEFAULT
• position
• object
• group
• tokens

If we speak of a bool value we do it in the sense of Lua 5, that means with the possible values ‘true’ and ‘false’.

Many enumerated values like orientations and colors are covered by the integer numbers.

Of special interest is the value ‘nil’. Just a few attributes make direct use of the value ‘nil’, e.g. "color" on some objects. If you set an attribute to value ‘nil’ you do actually reset its value to the default value. E.g. if you set the attribute "orientation" of st_boulder to ‘nil’ it will be set to its default, which is actually ‘NORTH’, an enumerated orientation value. A subsequent read of the attribute will return this value. Just those attributes that allow a nil value will ever return ‘nil’ on a read access. As a direct consequence these attributes always default to ‘nil’.

The authors of Lua did decide to prohibit the usage of ‘nil’ as a value in Lua tables. As we make heavy usage of anonymous tables as object declarations, you would not be able to set such attributes to ‘nil’. You would need to set such attributes explicitly. As a workaround we added a custom value ‘DEFAULT’ that can be used anywhere to set attributes - even within Lua tables.

mySwitch["color"] = nil
mySwitch["color"] = DEFAULT
wo[{3,6}] = {"ac_marble_black", player=DEFAULT}

Note that ‘DEFAULT’ is not equal to ‘nil’. They are different values concerning Lua. They just result both in attributes reset to their default. If you request a nil valued attribute you will always receive the Lua value ‘nil’. ‘DEFAULT’ will never be returned by the engine.

A group is an ordered set of Object References. As all contained objects must exist this value is seldom used for attributes in object declarations. But it is very useful for postprocessing of objects and for usage within Callback Functions.

The most complex attribute value type are the tokens. Their purpose is the specification of one or many objects. As Enigma provides several means to do that this value type combines and mix all possibilities. A token’s value may be a string, representing an object name, an object reference, a group or a table with any of these basic types in any sequence and number. E.g. the following right sides are all valid tokens for the attribute ‘target’:

obj1["target"] = "mydoor"
obj2["target"] = myobject
obj3["target"] = grp(ojb1, obj2, obj3)
obj4["target"] = {"mydoor", myobject}
obj5["target"] = {grp(ojb1, obj2, obj3), "mydoor", myobject, "anotherdoor"}

This versatility is useful to set tokens’ attributes independent of the given object reference types.

The chapter Common Attributes and Messages and its followers describe the existing object attributes in detail.

Besides these predefined attributes the level author can store own information on objects for later retrieval. Any name starting with an underscore ‘_’ can be used for level specific purposes. This prefix has been chosen as the resulting names are still valid Lua names. Common usage patterns are switches or triggers with callback functions. These functions provide the sender, the switch or trigger, as an argument. If you attach the same function to number of senders you can store the necessary context information within the sender.

The internal engine uses object attributes as well. Such inaccessible attributes are named with a leading dollar sign ‘$’. They may appear in the documentation for C++ developers information. Level authors should ignore these attributes.

In some cases you may observe a different behaviour on setting an attribute within the object definition and setting the same attribute while the object is already on the grid. E.g. a door ‘{"st_door_h", state = OPEN}’ is opened from the very beginning. Whereas ‘mydoor["state"] = OPEN’ on a closed door will start opening the door. This takes a short time until the door is really open. You find more details on these as aspects in the section The Lifecycle of a Level.

If you ever look into the C++ code you may wonder about the implementation of attributes. They are not all directly stored in a map. Some of them are held in object instance variables, other do not exist at all. Objects’ attributes are an abstract concept that unifies several internal features within a common simple API for level description code. Within the C++ engine subtle reasons like performance optimization forces a much more complex handling.

4.3 Methods of Interaction

Having looked at the description of the initial object composition of a level world we still need to understand how to configure the dynamic behaviour of a level.

4.3.1 Messages

You can generate an initially open door by setting its attributes. But how can a switch stone open a door when it is hit by a marble? It simply sends a message ‘open’ to the door. Another switch may send a message ‘on’ to a laser or ‘ignite’ to an it_dynamite. On explosion the dynamite will in turn send automatically ‘ignite’ messages to the neighbour grid positions.

Messages are a simple universal function or from the receiver object and the Lua level authors point of view a "method". It takes two arguments - the message name, a string, and an optional value. E.g.

mydoor:message("open")
myboulder:message("orientate", NORTH)

mydoor:open()
myboulder:orientate(NORTH)

The last two examples are a common abbreviation of the first two ones.

Messages may return a value. But most messages just return ‘nil’.

You can send any message to any object. Not supported messages are silently ignored. This is the reason that an exploding dynamite can send ‘ignite’ messages to its neighbours without knowing if the objects can be ignited at all. Further on the dynamite has not to bother with the recipients of the messages. Due to messages the sender and the receiver objects are totally decoupled concerning the code base. Thus the level author just needs one method that allows sending arbitrary messages to arbitrary objects.

You should not send a message during initialization of the level. You configure the switch to send an ‘open’ message to the door by Target - Action. Within a Lua Callback Function you may send messages during runtime to any object.

All messages are listed and described in Common Messages and the subsequent chapters.

4.3.2 Target - Action

The "target action paradigm" is a classical object oriented method that allows you to easily plug together objects. One object is triggered by a function call or by an event like an actor hitting a stone, crossing over or applying an item. You simply plug this object to another target object and tell it to send an action message. Every time the first object is triggered it will send the message to its target.

You configure such a target action by setting the attributes ‘target’ and ‘action’ on the first object. E.g. a for a switch stone that should open a door named ‘mydoor’ you can write:

{st_switch, target="mydoor", action="open"}

Objects like the switch can be triggered on and off. Each time they will perform the action. If you would like the door to open and close in turn to the switch you need another action than ‘open’. The universal message for changing targets in their alternate states is ‘toggle’.

{st_switch, target="mydoor", action="toggle"}
{st_switch, target="mydoor"}

Now the door will toggle in sync with the switch between its open and closed state. The message toggle can be used quite independent of the target object. In fact it is the default action message. As a default you may omit the action in this case as it is demonstrated by the second example.

But keep in mind that toggling just changes the state of the target. If you start with a switch in off state and an open door, the door will close when the switch in turned on. They will not sync. If you configure two switches both targeting the same door, you will have no clear relationship between the switch states and the door.

As you remember messages can take a value. Action messages are no exception. Every object sends its actions with a value, usually a bool value. A switch sends a value ‘true’ if it just switched on, and a value ‘false’ if it just switched off. The appropriate message for the door would be the universal message ‘signal’:

{st_switch, target="mydoor", action="signal"}

Now the door will open when the switch is turned on and close if the switch is turned off.

The message signal takes an integer value of ‘0’ or ‘1’. Indeed the action value does not match. But in this as in many other cases the messages and values are designed in a way that they are automatically converted to the appropriated type. This compatibility is the basis for a seamless plugging of objects.

In many cases authors face the task of triggering two or more objects by a single object. ‘target’ and ‘action’ are both able to take multiple values. ‘target’ is of type tokens, as described in Object Attributes, whereas ‘action’ can be a string or a table of strings.

{st_switch, target={grp(ojb1, obj2, obj3), "mydoor", myobject, "anotherdoor"},
            action={"toggle",              "open",   "turn",   "close"}}

All objects described by a token receive the related message in the action table. If not enough messages are listed the default action ‘toggle’ will be sent.

Usually actions are performed at once. That is very important as the sequence of actions if often essential. Consider an st_box being pushed from one it_trigger to a neighboring one, or just an ac_marble moving from the first trigger to the neighboring one. In both cases it is important that the first trigger is released prior the second one to be pressed. If this sequence gets mixed up both triggers could be pressed by a single object for a moment what could cause major shortcuts in a level. Thus all actions are performed in the logical sequence and in a stable, repeatable sequence without any random.

Action may be simple or sometimes be very complex world rearrangements. But in any case you should never ever ‘kill’ the sender object. Killing the sender can cause application crashes! Be aware that even chained actions are not allowed to kill any prior sender object. Thus an it_trigger that toggles an st_switch which in turn kills the first trigger is as critical as the trigger killing itself. We do generally discourage you to kill any object within its own action, as there is no dissolving animation and the WYSIWYG user paradigm is violated, too. But if there is urgent need for reasons of the level gaming logic you can perform the action in a secure, delayed mode. Just add the attribute safeaction with value ‘true’ to the self killing sender object. The action will no longer be performed at once, but with a minimum delay in a manner that will never cause crashes. But be aware that even a minimum delay, which is still within the same timeslice, may disturb the sequence of actions. This can cause unexpected logical results on the other hand.

4.3.3 Callback Function

The most powerful extension to the Target - Action paradigm that you can think of are callback functions. Instead of a target object as receiver of an action message you can supply an own Lua function that is called whenever the action is triggered.

{"st_switch", target="my_magic", action="callback"}
{"st_switch", target="my_magic"}

The ‘target’ is the name of the function as a string. You may set the ‘action’ to the string ‘"callback"’ for purpose of clarification, but it is not necessary as you see in the second example. The engine identifies the target to be of type of a Lua function and thus the action needs to be a callback. But you should note and remember that it is up to you to ensure that all object names and callback functions names are unique.

Let us look at the syntax of such a callback function

function my_magic(value, sender)
    if value == true then
        wo[sender + {1,0}] = {"it_coin_s"}
    end
end

The function is called with two arguments. The first one is a value. The type and contents depends on the issuing object, but in most cases it is a boolean value. You will find the value described in the objects description. The second argument is the reference of the calling object.

In the example we check if the st_switch did just toggle to ON. If this is given we take the switch, which is the sender, as a position and set a new it_coin to the grid east of it - a small bank automate that supplies money.

The Advanced Lua Examples will show examples of real powerful callback functions with a line by line comment.

Further usage and aspects of callbacks in the level’s lifecycle are given in the section Callbacks and Load Balancing.

4.3.4 Object State

A key concept for the ability to plug together objects like switches and doors are the very simple state machines of these objects. Most objects are described by simple machines with just 2 states like ‘ON’,‘OFF’ or ‘OPEN’, ‘CLOSED’. These objects can be plugged together by just few common messages. Further on these simple state machines are suited to the gamers who do not want to read manuals but want to explore the objects by playing with just a few tests.

Even though states are usually named by appropriate uppercase names like above, the states are integer numbers starting with ‘0’ usually related to the default state. But some objects use another mapping due to historic reasons. E.g. states that are orientation related use the state ‘3’ representing ‘NORTH’ usually as the default and number the orientations clockwise down to ‘0’ representing ‘WEST’.

In most cases it is sufficient to perform a state independent common action like toggle. Even two stated objects can be easily synchronized by the standard action signal. But sometimes you may want to perform very state specific actions. Let us look how this can be done.

E.g. let us take an st_fourswitch, that has four states, and two st_laser which should be switched on and off. Both lasers should emit their beams while the fourswitch is in 3 of its states. But one of them should be off just while the fourswitch is in the ‘EAST’ state and the other should be off just while the fourswitch is in the ‘WEST’ state. This can be done by usage of state dependent target and actions:

{st_fourswitch, target_3="laser#2", action_3="on",
                target_2="laser#1", action_2="off",
                target_1="laser#1", action_1="on",
                target_0="laser#2", action_0="off"}

Adding a number as suffix to ‘target_’ and ‘action_’ gives you special target and action attributes that will take precedence over the general ‘target’ and ‘action’ attributes if the state value equals the suffix number. An alternative declaration would be:

{st_fourswitch, target={"laser#1", "laser#2"},
              action_3={"nop",     "on"},
              action_2={"off",     "nop"},
              action_1={"on",      "nop"},
              action_0={"nop",     "off"}}

Here we do address both lasers in all states. But one of them receives a nop message that stands for "no operation". In fact this message will never be send. It is just a dummy message that we have need of for syntax reasons in the case above.

Another example are two it_trigger that switch a laser. An object pressing the first trigger should switch the laser on, an object pressing the second trigger should switch it off. But a trigger is two stated and performs one action on being pressed and another on being released. Thus we want to block the actions on trigger release events:

{it_trigger, name="on_trigger",  target="laser#1", action_1="on", action_0="nop"}
{it_trigger, name="off_trigger", target="laser#1", action_1="off", action_0="nop"}

The blocking of ‘action_0’ is essential and can not be omitted, as otherwise the default action would be performed. This would be a ‘toggle’ message that would switch the laser.

As this useful default mechanism can sometimes be annoying you can switch off the default message by setting the nopaction attribute to true.

{it_trigger, name="on_trigger",  target="laser#1", action_1="on", nopaction=true}
{it_trigger, name="off_trigger", target="laser#1", action_1="off", nopaction=true}

When an objects leaves a trigger the state ‘0’ action will be performed. As neither ‘action_0’ nor ‘action’ is specified the default action will be performed, which is now ‘nop’.

If you ever look into the C++ code you may note that many objects do have much more complex state machines than you expect from the level authors and gamers view. This is due to running animations, timers, etc.. The C++ objects map their complex internal state set to the much simpler external state set. This is the main reason that some features that level authors request can not be provided in the Lua API.

4.4 The Lifecycle of a Level

Snapshot Levelloading, Initialization, Runtime Callbacks, Ending Conditions - the mystery of Oxyds and Meditation

4.4.1 Library Preloading

4.4.2 Snapshot Principle

Most levels contain objects that take influence on each other. A switch might toggle a door by Target - Action, marbles may press a trigger, or a laser might activate a laserswitch or transform a hammer into a sword. Of course it is essential to know how to set up such objects to get the desired start configuration without the objects changing unexpected on level initialization.

The snapshot principle is a simple thumb rule that you can rely on in describing the level as a snapshot of object at a given point of time. Every object has just to be configured as it should be at the given time. All interactions that would take place in a running game do not take place while setting objects during initialization.

E.g. if a switch toggles a door and the switch should be initially on and the door should be initially open you describe the object with exactly these attributes:

{"st_switch", target="mydoor", state=ON}
{"st_door", name="mydoor", state=OPEN}

A laser that is initially on that illuminates a laserswitch needs an initially active laserswitch. But of course no attribute exists that would allow you to set a laserswitch active. The snapshot principle includes the rule that all internal states are updated without external actions. This means that the laserswitch will show up active without causing an action on its target.

{"st_laser", state=ON}
{"st_laserswitch", target="mydoor"}

What about objects that transform on laser light. The snapshot principle keeps the object from transforming during initialization. A hammer that is set in an initially existing laser beam will not transform to a sword. It remains as a hammer that will transform on any subsequent new laser light during the game.

Of course it cannot be allowed to describe impossible initial level states. Objects like dynamite do explode immediately on a laser beam hit. Thus a dynamite item in an initial laser beam is a fault that causes an exception. The snapshot principle forces you in this case to set an explosion item instead of the dynamite.

Some objects do process internal state transformations that cannot be configured by attributes. But some of these states may be of interest on describing a snapshot of a level. Where possible a special object subkind exists with a suffix of ‘_new’. These objects can be used in the initial level description to set objects in special initial states. E.g. it_blocker provides such a special subkind. Note that these objects will never report their initial subkind on a kind request as they come into existence as a standard object.

4.4.3 Level Initialization

Knowing what has been preloaded and knowing exactly which objects we have to set in which state, it is time to have a look on how your level code is processed. The main issue is to guarantee that all parts referenced have been set up properly in advance.

Prior execution of the first line of your code the world exists just as an abstract handle, but not as grid array able to accept objects. Thus the first lines of code should set up all Global Attributes deviating from their defaults. Even though many attributes can be set or changes later on and even on runtime, there are some attributes like ProvideExtralifes that take only effect if being set prior world creation, or others like MaxOxydColor that must be set prior their first usage. Our recommendation is to collect all global attribute settings at the very beginning of the level.

The second section of your level code should be the declaration of tiles. Being just declarations these code lines do not set objects to the world. They just depend on global attributes and may reference each other. Listing them all together in a code section makes it easy to maintain the overview and to avoid dependency conflicts.

If you use Resolvers you should put their declarations in the next code section as they may refer to tiles and global attributes and need to be set up prior the world creation.

The central statement of every level is the World Creation. It sets up the world to its size and sets initial objects according to the given tile declarations to the grid array. While you are free to add and change any of these objects later on the size of the world is fixed and can not be changed.

Thus subsequent code lines should add other objects, draw additional maps of objects and finalize some objects. The most common statement for such a finalization is the shuffleOxyd method. It needs to know all st_oxyd to be able to color and shuffle them. Another finalization may be a custom rendering of a maze, that extracts the maze shape out of the level map (see section res.maze).

This post world creation code may well have the need of loops or even some local used functions that need to be integrated to precede. Please keep such functions near by their usage and within the same code section.

Another set of functions that you may want to add are Callbacks and Load Balancing. We recommend to append these functions as the last section as they are not called within the level initialization itself.

But there is one very special exception. The postinit() callback is called after the level initialization code has been processed and all subsequent engine internal initialization has been finished. If this function is present in a level it gets executed directly before the first mouse movement event gets processed. Thus you can rely within this function that all objects are set up in their final state. If you have need of such a postinit callback you should put it after all the level intialization code and in front of other callback functions that will be executed on subsequent events.

4.4.4 Object Transformation

During runtime some Enigma objects do transform into other successor objects, like an st_blocker/it_blocker, an st_brake/it_brake, an it_rubberband/ot_rubberband, an it_hammer/it_sword,...

Even though the successor object may have other attributes, some attributes and especially any user attributes should be maintained. In fact the objects name, its target and action attributes and all attributes starting with an underscore ‘_’, the user attributes, are transferred to the successor object. Thus you can rely on the successor to message the same target and you can access it via its old name.

4.4.5 Named Positions

Many stones are movable and if the user can not push them, most may still be swapped. Items may be picked up by actors or be killed in a burning fire. Thus in most cases it is preferable to mark anchors or shapes in the floor. On every grid position a floor object is guaranteed and they are much more stable than other objects. But nevertheless a user may push an st_box, an st_puzzle or other floor building stone on an fl_water or fl_abyss. Furthermore a user may drop and ignite an it_bomb that destructs the floor leaving a new fl_abyss. In all these cases you may lose a named anchor or an essential part of a named grid area accessible as an object group.

Thus for every named floor that gets killed its position is stored in a repository under its name. You just need to retrieve the named positions instead of the named objects if you want to get all affected floor positions.

ti["~"] = {"fl_water", "water#"}
...
function sweet()
    wo[po["water#*"]] = {"it_cherry"}
end

Note that a request for a named position will include all positions of matching named objects as well as those named positions derived from killed floors.

4.4.6 Callbacks and Load Balancing

The most flexible feature for a level author to establish an unique behaviour of his level are Callback Functions.

Target - Action kill warning ot_timer

global and res.*.function

4.4.7 Level Restart

4.4.8 Ending Conditions

Two essential questions remain to be answered. When and under which conditions is a level successfully finished. How do I declare a level as being a meditation level in opposite to a standard oxyd pair opening level.

In fact there is no ’meditation’ flag, neither within the XML Level Info metadata nor as one of the Global Attributes. That means there is no formal distinction between both level ’types’. But there are two different types of ending conditions. Both are checked permanently and whichever is fulfilled first wins. Thus Enigma allows you to write true hybrid levels that provide st_oxyd as well as it_meditation allowing the user to solve the level by two totally different means.

The main way to end the game is to fulfill the oxyd pair opening condition:

The game is over when the user succeeds in opening all regular colored st_oxyds by pairs.

This implies that there is at least one pair of regular colored oxyd stones and that all oxyd colors appear in even number of instances. Whereas you will always add at least one pair of oxyds for a standard level, you may simply loose track of the number of instances. Therefore the engine will permanently check at runtime that every oxyd color appears in an even number of instances. Any violation causes an error. In case you will add or delete oxyd stones you need to disable this checking by setting the global attribute AllowSingleOxyds to true. Now it is your reponsibility as an author to ensure that the level remains solvable by adding or removing pairs only.

The second way to end the game is to fulfill the meditation condition:

All ac_pearls must reside for at least one second within the uneven area of an it_meditation, all it_meditation marked as essential must be occupied and the number of ac_pearls must be equal to the number of occupied it_meditations.

This implies again that there exists at least one ac_pearl and that no two pearls can reside within the same it_meditation. There must be at least the same number of it_meditation as of ac_pearl, but there may be more it_meditations as long as they are not marked as being essential. A surplus of it_meditation can easily occur due to explosions of it_dynamite.

A level that should be solved by fulfillment of the meditation condition can contain st_oxyd and by setting AllowSingleOxyds to true you can add odd numbers of oxyd stones of a color. On the other hand you can add ac_pearl to a level that should be solved by fulfillment of the oxyd pair condition. But you must carefully check that the user can not rest the pearls in given it_meditation or can create it_meditation by it_dynamite. Marking more it_meditation as essential than existing ac_pearls can avoid shortcuts.

A level that is set up to allow the user to fulfill both conditions is called a hybrid level. Of course it is a difficult task to provide equivalent solutions for both approaches.

Independent of the condition type all actors marked as essential need to be alive at the moment the condition is fulfilled. Mainly in existing legacy levels but also in some very carefully designed future levels the author may allow the user to sacrifice an actor to fulfill the condition by setting the global attribute SurviveFinish to false. In this case a marble may shatter while the condition is fulfilled. Of course the essential actor may not shatter in advance, because as soon as the shattering is over the essential actor will cause a level restart, if it can not be resurrected.

5. Lua API

Knowing the basic principles of an Enigma level’s world you now just need the language glue to write your first level. Enigma levels are written in the language Lua as of version 5.1.4. This powerful language gives you the ability to write most complex, dynamical levels, while being nearly transparent on writing basic standard levels. Indeed there is no reason to dig into this language at the very beginning.

With the second Lua API version, as of Enigma 1.10, we designed an optimized way of describing levels in a very short and readable manner. Thus we would like to introduce you to this API by giving several examples from a basic level to most thrilling dynamic real Enigma levels. You should be able to start your first experiments just after reading the first example with its explanations.

For your convenience we do color the Lua code part. Predefined Lua variables and functions are colored in green. Enigma internal string constants as object kinds, attribute or message names are colored in blue. Level specific variable names and value constants are colored in magenta.

After the examples and a short overview the details of the language specific API part are given, as you can expect it for a reference manual. Please note that additional Advanced Features are described in a separate chapter.

5.1 Basic Lua Examples

Let us look at two basic onescreener levels, that make use of all basic techniques. While the first level is a little bit artificial, as it is designed for demo purposes only, the second one is a quite dynamic real level out of the Enigma levelpacks.

5.1.1 Basic Example

Let us view the source code. We did add a line count in the first two columns for reference purpose within this section. These line count numbers are not part of the source code itself!

 1    <?xml version="1.0" encoding="UTF-8" standalone="no" ?>
 2    <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">
 3     <el:protected>
 4       <el:info el:type="level">
 5         <el:identity el:title="Basic Level" el:subtitle="" el:id="20080721ral513"/>
 6         <el:version el:score="1" el:release="1" el:revision="$Revision: 1.8 $" el:status="experimental"/>
 7         <el:author el:name="Ronald Lamprecht" el:email="ral@users.berlios.de"/>
 8         <el:copyright>Copyright © 2008 Ronald Lamprecht</el:copyright>
 9         <el:license el:type="GPL v2.0 or above" el:open="true"/>
10         <el:compatibility el:enigma="1.10"/>
11         <el:modes el:easy="true" el:single="true" el:network="false"/>
12         <el:score el:easy="-" el:difficult="-"/>
13       </el:info>
14       <el:luamain><![CDATA[
15
16    wo["ConserveLevel"] = true
17
18    ti[" "] = {"fl_samba"}
19    ti["."] = {"fl_abyss"}
20    ti["~"] = {"fl_water"}
21    ti["#"] = {"st_granite"}
22    ti["X"] = {"st_oxyd"}
23
24    ti["L"] = {"st_laser", orientation=EAST, state=ON}
25    ti["M"] = {"st_lightpassenger", interval=0.04}
26
27    ti["P"] = {"st_polarswitch", name="polar"}
28    ti["T"] = {"it_trigger", target="polar"}
29
30    ti["^"] = {"st_boulder", "boulder", orientation=NORTH}
31    ti["F"] = {"st_fourswitch", target="boulder", action="orientate"}
32
33    ti["D"] = {"st_door_d", "door", faces="ew"}
34    ti["B"] = {"it_blocker", "wall#"}
35    ti["S"] = {"st_switch", target={"door", "wall#*"}}
36
37    ti["v"] = {"it_vortex", "left", destination="right"}
38    ti["V"] = {"it_vortex", "right", destination="left"}
39
40    ti["O"] = {"st_turnstile", flavor="red"}
41    ti["E"] = {"st_turnstilearm", orientation=EAST}
42    ti["N"] = ti["."] .. {"st_turnstilearm_n"}
43
44    ti["+"] = {"fl_samba", checkerboard=0} .. ti({"fl_wood", checkerboard=1})
45
46    ti["1"] = {"#ac_marble"}
47
48    if wo["IsDifficult"] then
49        ti["="] = ti["~"]
50    else
51        ti["="] = ti["~"] .. {"it_strip_ew"}
52    end
53
54    w, h = wo(ti, " ", {
55        "####################",
56        "#      ....++++++~ #",
57        "L   PM ..N.++~~~~OE#",
58        "#######  T~++++++. #",
59        "#     ^   ~++++++# #",
60        "#         =++++++X X",
61        "#         ~++++++# #",
62        "#~~~~~~~~~~~~~+++X X",
63        "#    ~   B   ~+++###",
64        "F    ~   B   ~+++++#",
65        "# 1  ~   B   #+++++#",
66        "S   v~V  B   D+++++#",
67        "####################"
68    })
69
70    wo:shuffleOxyd()
71
72     ]]></el:luamain>
73        <el:i18n>
74          <el:string el:key="title">
75            <el:english el:translate="false"/>
76          </el:string>
77        </el:i18n>
78      </el:protected>
79    </el:level>

The resulting level looks like this in the game

Let us now analyse the code line by line.

Lines 1 to 14 are the XML metadata of the level as described in Level Basics. The only line worth mentioning is

10         <el:compatibility el:enigma="1.10"/>

You need to declare the level to be compatible to Enigma 1.10 or higher for the new API 2 as described in this reference manual. A value less than 1.10 indicates compatibility to a previous Enigma release that did use the old API 1, which should not be mixed up with the new API 2.

The Lua part starts with line 15:

16    wo["ConserveLevel"] = true

Like most levels it starts with setting Global Attributes. The handle of our world is ‘wo’. This object reference is preset (see section World as an Object). Concerning Lua it is an ‘userdata’, but most of its usage syntax is identical to that of Lua tables. Thus we access an attribute by providing the desired attribute name in square brackets. As we give a literal attribute name, we have to put it in double quotes ‘"’. In total this line requests the world to resurrect a killed actor as long as there are enough extra lifes to conserve the running level (see section ConserveLevel). In fact ‘true’ is the default value. So we could have left this line out. But remember it is a demo level.

The second part of a level are the tile definitions as explained in World’s Shape and Coordinates. Let us start with the most simple ones:

18    ti[" "] = {"fl_samba"}
19    ti["."] = {"fl_abyss"}
20    ti["~"] = {"fl_water"}
21    ti["#"] = {"st_granite"}
22    ti["X"] = {"st_oxyd"}

Again we use a handle ‘ti’ which is a preset object reference for the tile definition repository. Like the world it is a Lua ‘userdata’. And we can access it like the world by giving the desired index in square brackets. These indices are free to your choice. They have to be of a common character length if they are referenced in the world map below. For a small level one character keys are sufficient. You can use any ASCII character that Lua is aware of. That means upper and lower case characters ‘A-Z,a-z’, the numbers and special characters besides backslash ‘\’ and double quote ‘"’.

The assigned object definition are given as Lua anonymous tables, the curly braces, containing in the most simple case just the desired Object Kind. As it is again a literal string, it has to be quoted. Without any further specification the objects are taken in their default configuration as described in Floor Objects and following chapters.

24    ti["L"] = {"st_laser", orientation=EAST, state=ON}
25    ti["M"] = {"st_lightpassenger", interval=0.04}

These two lines define objects with custom configuration. The st_laser should send its beam to the east and should start being switched on. The st_lightpassenger should move a little bit faster than usually. Both times we just have to add comma separated additional attributes. The attribute names are not quoted as they are followed by an equal ‘=’ sign.

27    ti["P"] = {"st_polarswitch", name="polar"}
28    ti["T"] = {"it_trigger", target="polar"}

An st_polarswitch named for reference usage (see section Object Naming). The it_trigger sets up a Target - Action, the target being our polarswitch. The action attribute is omitted. It defaults to the message ‘toggle’. Thus any actor or stone on top of the trigger makes the polarswitch transparent, but switches it back to opacity when leaving the trigger.

30    ti["^"] = {"st_boulder", "boulder", orientation=NORTH}
31    ti["F"] = {"st_fourswitch", target="boulder", action="orientate"}

Another pair of objects that are coupled by Target - Action. The st_boulder starts trying to move to north. This time we name the object just by giving the name as the second comma separated string. We omitted the attribute identifier ‘name =’. This is a shortcut for this most common attribute which requires the name to be given as the second value directly after the object’s kind.

The st_fourswitch references the boulder as its target. We need to give the action as well, as we want to make use of a special action that directly steers the boulder according to the fourswitch orientation.

33    ti["D"] = {"st_door_d", "door", faces="ew"}
34    ti["B"] = {"it_blocker", "wall#"}
35    ti["S"] = {"st_switch", target={"door", "wall#*"}}

And another even more complex Target - Action. We want a single st_switch to toggle a st_door as well as set of it_blockers at the same time. The gaming idea is that neither with switch on nor with switch off the marble can pass both obstacles. The gamer needs to steer the boulder through the blocker wall to pass these obstacles.

The setup of the door is simple. We just need to name it to be able to reference it later on. We want to use several blocker objects and we need to name each for reference purposes. We do this by appending a hash sign ‘#’ to its name as described in Object Naming. Every blocker gets a unique name. The switch needs to list all these objects as its targets. This is done by an embedded anonymous table given by the curly braces and comma separated values. The first one is our door’s name, the second one is a wildcarded string that describes all our blocker objects. The asterisk stands for any suffix that may have been added behind the hash in the process of autonaming of our blockers.

37    ti["v"] = {"it_vortex", "left", destination="right"}
38    ti["V"] = {"it_vortex", "right", destination="left"}

We want to use two it_vortex that are connected to each other allowing the marble to warp into both directions. We set up both vortices with a unique name and add the attribute ‘destination’ referencing the other vortex’ name.

Note that it is no problem to reference the right vortex in line 37 while it is named later on in line 38. We are still just defining tiles and not creating any objects at all.

40    ti["O"] = {"st_turnstile", flavor="red"}
41    ti["E"] = {"st_turnstilearm", orientation=EAST}
42    ti["N"] = ti["."] .. {"st_turnstilearm_n"}

Another object group is an st_turnstile cluster with one arm disconnected. The first two definitions are straight forward. But in line 42 we precede the arm’s definition by another tile reference. It is the abyss tile defined in line 19. By concatenation, the two dots .., of a tile and an object definition we can define a new tile that is composed of both objects. In this case we define a turnstile arm on top of an abyss floor.

You may be wondering why we did not define floors for the other stone and item tiles. We make use of the tile definition in line 18 that we will declare later as the default floor for our level. Thus any tile declaration that does not provide its own floor will set this default floor.

44    ti["+"] = {"fl_samba", checkerboard=0} .. ti({"fl_wood", checkerboard=1})

Just for fun we want to provide a checkerboard floor on the right side of our level. This can be done by usage of the checkerboard attribute. Again we concatenate two object definitions for a single tile. Both are floors. That means for each grid position we try to set both floor types, but just one meets the checkerboard condition and will be set.

Please notice that we did convert one of the floor object definitions to a tile definition by the function call ‘ti()’. This is necessary as Lua does not know how to concatenate two anonymous tables. One argument of the concatenation has to be a tile.

46    ti["1"] = {"#ac_marble"}

Finally we do need our marble. Unlike other objects it can be positioned anywhere within a grid. The most common position is the center of the grid. This is simply done by preceding the actor’s kind by a hash sign ‘#’.

48    if wo["IsDifficult"] then
49        ti["="] = ti["~"]
50    else
51        ti["="] = ti["~"] .. {"it_strip_ew"}
52    end

We encourage every level author to provide an easy mode for the levels. This is an example how to define mode dependent tiles. Like in line 16 we access a world attribute. But this time it is a read access of IsDifficult. In easy mode we want an it_strip on top of the water floor that allows the marble to pass and press the trigger. In difficult mode there should be no passage. Thus the special tile is identical to the water tile defined in line 20.

54    w, h = wo(ti, " ", {
55        "####################",
56        "#      ....++++++~ #",
57        "L   PM ..N.++~~~~OE#",
58        "#######  T~++++++. #",
59        "#     ^   ~++++++# #",
60        "#         =++++++X X",
61        "#         ~++++++# #",
62        "#~~~~~~~~~~~~~+++X X",
63        "#    ~   B   ~+++###",
64        "F    ~   B   ~+++++#",
65        "# 1  ~   B   #+++++#",
66        "S   v~V  B   D+++++#",
67        "####################"
68    })

After all tiles have been defined we can create our world simply by a map that uses our tile keys. The first argument is our handle ‘ti’, that defines how the keys should be resolved. The second argument is the key of our default floor. The third argument is the map as a table of strings, one for every line.

The world initialization returns the width and height of our world which are calculated by the map’s size.

70    wo:shuffleOxyd()

After the world is created and all objects are set, we can do some final postprocessing before the level starts to run. The most common task is the shuffling of the oxyds, which is just a method call of shuffleOxyd to our mighty world object.

5.1.2 Colored Turnstiles

As this level is part of the Enigma levelpacks we recommend that you play the level first to get familiar with the used objects and their behaviour.

Now let us look at the essential Lua source code part of the level to understand how such an idea can be realized with the new API

ti[" "] = {"fl_sahara"}
ti["#"] = {"st_purplegray"}
ti["@"] = {"#ac_marble_black", "marble_black"}

ti["N"] = {"st_turnstilearm_n"}
ti["S"] = {"st_turnstilearm_s"}
ti["E"] = {"st_turnstilearm_e"}
ti["W"] = {"st_turnstilearm_w"}
ti["R"] = {"st_turnstile", action = {"open", "close"}, target = {"red#*", "green#*"}}
ti["G"] = {"st_turnstile", action = {"close", "open"}, target = {"red#*", "green#*"},
                           flavor = "green"}
ti["r"] = {"it_blocker", "red#"} .. ti({"fl_red"})
ti["g"] = {"it_blocker", "green#"} .. ti({"fl_lawn"})

ti["O"] = {"st_oxyd", flavor = "d", oxydcolor = OXYD_GREEN}
ti["o"] = {"st_oxyd", flavor = "d", oxydcolor = OXYD_RED}

w, h = wo(ti, " ", {
 -- 01234567890123456789
   "#O#####O############",
   "#   r N g N rO##O#O#",
   "#WRE#WGE# R ####g#r#",
   "#   r N r S  r N   #",
   "#g#g#WG #g##r# REr##",
   "# # N S r    g S  gO",
   "#@g RE#g#gWGE###g###",
   "# # S   g    r N  ro",
   "#r#r#WGE#r##g#WGEg##",
   "# N r S g N  r     #",
   "#WGE# RE# RE####r#g#",
   "#   g S r S go##o#o#",
   "#o#####o############"
})

wo:shuffleOxyd()

There are just four tile definitions that do all the dynamic actions. Let us look first at the blocker item definitions:

ti["r"] = {"it_blocker", "red#"} .. ti({"fl-red"})
ti["g"] = {"it_blocker", "green#"} .. ti({"fl-leaves"})

All blockers on red floors are autonamed with a name being composed of the prefix ‘red#’ and a unique random number being added by the engine as explained in Object Naming. This allows us to address all these blockers later on.

ti["R"] = {"st_turnstile", action = {"open", "close"}, target = {"red#*", "green#*"}}
ti["G"] = {"st_turnstile", action = {"close", "open"}, target = {"red#*", "green#*"},
                           flavor = "green"}

Whenever the marble hits and turns an st_turnstile it performs its actions on the targets. Here the author makes clever usage of multitargets and multiactions as described in Target - Action. On every turn of a red turnstile all objects named ‘red#*’, that are all our blockers on a red floor, will be sent a message ‘open’, whereas all blocks on a green floor, the second target group, receives the second action message ‘close’. It is essential to choose the ‘open’, ‘close’ messages instead of ‘toggle’, as more than one red turnstile may be turned in sequence, but just the first red turn should "toggle" all blockers. The next toggling should occur on the first green turn following thereafter.

Hope you got the basic idea of the new API. You may well start with you first level experiments. But you should return and read the following chapters with overview and advanced examples to write even more fancy levels.

5.2 API 2 Overview

Having analysed a first level it is time get an overview of the API 2 capabilities. Let us take a task driven approach by listing the different possibilities and use cases by example.

5.2.1 Types Overview

But first we need to introduce you to the special Enigma value types besides the standard Lua types ‘nil’, ‘boolean’, ‘string’, ‘function’ and ‘table’:

Types:

position:  See section Position

A position within the world that can be described by an x and y coordinate.

positions: preset variable: po;   See section Positions Repository

The singleton type of the repository of all named positions.

object:  See section Object

An Enigma object like a stone, item, floor, other. Any object is a position, too.

group:  See section Group

A list of objects.

namedobjects: preset variable: no;   See section NamedObjects

The singleton type of the repository of all named objects.

default: preset variable: DEFAULT;   See section Object Attributes

The singleton type of default values that can be used instead of Lua’s ‘nil’ in anonymous table tile definitions.

tile:  See section Tile and Object Declaration

A description of one or several objects for a common grid position (floor, item, stone, actor)

tiles: preset variable: ti;   See section Tiles Repository

The singleton type of the repository of all tile instances.

world: preset variable: wo;   See section World

The singleton type of the world that contains all objects.

position list:  See section Named Positions

A list of positions.

Please note the four handles ‘po’, ‘no’, ‘ti’ and ‘wo’. You have noticed two of them in the previous section Basic Lua Examples. These are four variables, that are preset prior the level code gets executed.

API 2 uses mainly two character names for frequently used variables and functions to shorten the level code and to make it better readable. Authors should try to use either single characters or names that are three characters or longer for private variable names.

For the rest of this section let us assume that ‘obj’ is an object reference of a stone, item or floor, which means that is of type ‘object’. And let ‘pos’ be a valid variable of type ‘position’.

5.2.2 Position Tasks

For reference details see section Position.

Creating Positions:

pos = po(7, 3) -- using function "po()" to generate a position object pos = po({7, 3}) -- using a table position constant as argument pos = obj -- every object is a valid position pos = po(12.3, 3.7) -- a position within a grid (for an actor)

Absolute positions are created by the function ‘po()’. But the most common way should be the reinterpretation of an object as a position. This lets you set other objects relatively to given ones.

Position Constants:

{7,3} -- a valid position for all arguments and operations (see Caveats)

Anonymous tables with just two number values can be used in many cases directly as a position constant. In case of errors, e.g. when operators are not well defined like addition of two constants, which results in an attempt of adding two Lua tables, use the function ‘po()’ to convert the constant.

Coordinate Access:

x, y = pos.x, pos.y x, y = pos["x"], pos["y"] x, y = pos:xy() x, y = obj.x, obj.y x, y = obj:xy()

The x and y coordinate of a position or object can be read accessed like any object attribute. A position or object method call by ‘xy()’ returns both coordinate values at once. You can not set a position value by coordinate write access. Objects need to be set to a new world position. New positions can be calculated by position arithmetic.

Position Calculation:

pos = obj + {2,7} dpos = obj1 - obj2 dpos2 = 2 * dpos dpos3 = dpos / 2

Positions can be added or subtracted to get distance vectors. You can multiply and divide them with any number.

Center positions for set actors

pos_centered1 = pos + {0.5, 0.5} pos_centered2 = #pos pos_centered3 = #obj

Especially for positioning of actors you sometimes need the position of the center of a grid. Of course you can get it by addition of a constant position. But the ‘#’ operator applied on a position or an actor does the same in a simpler way.

Round a position to a grid

grid_pos = pos:grid() grid_pos = ((pos1 - pos2)/2):grid()

A result of a position calculation needs sometimes to be rounded to integer grid coordinates. This is done by the ‘grid()’ method.

Position comparison

pos_centered1 == pos_centered2 pos_centered1 ~= pos_centered2 -- Lua's inequality operator

Position can be easily compared to equality.

Position existence

pos:exists()

‘true’ if a position is a valid position of the world. All positions outside of the world return ‘false’.

5.2.3 Attribute Tasks

For reference details see section Object.

Single Attribute Setting:

obj["destination"] = po(7,3) wo["Brittleness"] = 7

Object attributes as well as global world attributes can be set like Lua table values. They can take values of special Enigma types like position, object or group.

Multiple Attribute Setting:

obj:set({target=mydoor, action="open"})

You can set multiple attributes on any object at once with the object’s ‘set()’ method. The argument is an anonymous Lua table with the attribute names as keys and assigned values of your choice.

Requesting Attributes:

value = obj["attr_name"] value = wo["Brittleness"] if wo["IsDifficult"] then ... end

Attributes of objects and the world can be read like Lua table key values.

Reset Attributes:

obj["length"] = nil -- the default length, e.g. ‘1’ obj["color"] = nil -- delete color attribute - no color obj["length"] = DEFAULT -- the default length, e.g. ‘1’

Any object attribute can be reset to its default value, which is the attribute’s "delete" operation, by assigning it the Lua ‘nil’ or the Enigma ‘DEFAULT’ value.

5.2.4 Object Tasks

For reference details see section Object.

Creating Objects:

wo[pos] = {"st_chess", color=WHITE, name="Atrax"} -- on grid pos wo[#pos] = {"ac_bug"} -- actor centered on grid pos wo[pos] = {"#ac_bug"} -- actor centered on grid pos wo[pos] = {"ac_bug", 0.3, 0.7} -- actor with offsets to pos wo[my_floor] = {"it_magicwand"} -- set a wand on top of a given floor object wo[pos] = ti["x"] -- tile based object definition

Besides map based object creation, that you saw in the previous basic examples, you can create new objects on any world position directly. The world takes a position, that may well be an object, as key argument. The new object is described either by an anonymous Lua table, containing the kind string as first value and additional attributes as key value pairs appended, or by a tile object.

Object Naming:

no["Atrax"] = obj wo[pos] = {"st_chess", name="Atrax"} wo[pos] = {"st_chess", "Atrax", color=WHITE}

As explained in Object Naming, the names are the only longtime valid object references. You can explicitly name an object by assigning it at the named object repository ‘no’ to the name as the key. But most times you just supply the object’s name as an object attribute. If you supply the name attribute as the second value in the anonymous table you can omit the key ‘name =’ part as a common abbreviation.

Object Autonaming:

wo[pos] = {"st_chess", name="Atrax#"}

As explained in Object Naming you can append a hash sign ‘#’ to a name and use the resulting string for arbitrary number of similar objects. This is especially useful for building groups.

Requesting Objects:

obj = no["Atrax"] -- named object retrieval from repository obj = it(pos) obj = it(x,y) obj = st(pos) obj = wo:it(pos) my_item = it(my_floor) -- get the item that is on top of the given floor

The most common way is naming objects and the requesting the ‘no’ repository for the object reference. If you know the position of the desired object you can use one of the functions or world methods ‘fl’, ‘it’, ‘st’ that take a position, an object as position, or just the two coordinates as arguments. Especially requesting one type of objects that is positioned at the same grid as another object, the stone on top of a floor, etc. can be very useful.

Killing Objects:

wo[pos] = {"it_nil"} obj:kill()

You remove an object by setting another replacement object at the same position in the same layer. If you do not want to set a new object you can use the placebo objects ‘fl_nil’, ‘it_nil’, ‘st_nil’. Another way is to call the ‘kill()’ method of an object or send it a ‘kill’ message. You can only remove objects that are set on the grid. Neither actors nor owned objects like items in a players inventory can be killed - they will simply ignore the attempt.

Comparing Objects

obj1 == obj2 obj1 ~= obj2

Objects can be directly compared on equality or inequality. It is an identity comparison that acknowledges that you have two references of the same object.

Existence of an object

obj:exists() -obj -- unary minus operator on object if -obj then ...

Object references may get invalid due to objects being killed. In most cases this creates no problem as requests to invalid objects will simply be ignored. But if the level logic depends on the existence of an object you can call the ‘exists()’ method or simply precede the reference by the unary minus ‘-’ operator. Both ways return a simple bool value stating if the object reference is still valid.

Messages:

my_boulder:message("orientate", WEST) my_boulder:orientate(EAST) my_door:open()

Messages are a main feature of Enigma. You can send them directly to any object by the ‘message()’ method or by using any message directly as a method call itself.

Object Classification:

obj:is("st_chess") obj:is("st") obj:is("st_chess_black")

You create objects by giving an Object Kind. Later on you can check a given object for conformity to a given class or kind. Even though you can not create abstract kind objects like ‘st’, you can check this way if an object is a stone. Checking for special subkinds may even evaluate the current state or other attributes of an object to report its current classification.

5.2.5 Group Tasks

For reference details see section Group.

Creating Groups:

group = no["Atrax#*"] -- a group of all matching objects -- wildcards "*","?" allowed group = grp(obj1, obj2, obj3) group = grp({obj1, obj2, obj3}) -- a group of objects set up in a table

Requesting objects from the named object repository will result in a group of objects if you make proper usage of wildcards. Appending an asterisk ‘*’ to the autonaming hash will retrieve all objects that have been set with this name suffix. But you can create a group by the ‘grp’ function, too. Simply add the desired object reference as arguments, either single or as a table.

Group Usage:

floor_group["friction"] = 3.2 -- set attribute on all floors in the group door_group:message("open") door_group:open() stone_group:kill() wo[floor_group] = {"it_coin_m"} -- add some money on all floor positions wo[pos] = {"st_switch", target=door_group, action="open"} wo[pos] = {"st_switch", target="door#*", action="close"}

Many object operations can be applied to groups in the same manner. The operations will be applied to all members of the group. You set attributes, send messages or call any method.

The world object takes a group as key, too. You can set objects of a given definition to many positions at once.

Another usage of groups is the application as an attribute value. E.g. you can define multiple targets by supplying a group.

Group Operations:

doors_lasers = doorgrp + lasergrp -- join of two groups lasergrp = doors_lasers - doorgrp -- difference of two groups common_doors = doorgrp1 * doorgrp2 -- intersection of two groups

Groups offer some standard operations known from handling with sets.

Group Members:

count = #mygroup -- number of objects in the group obj = mygroup[5] -- 5th object of the group obj = mygroup[-1] -- last object of the group for i = 1, #mygroup do obj = mygroup[i] ... end for obj in mygroup do ... end

You can access the members of a group by numbered indices. The size of a group is reported by the standard Lua hash ‘#’ operator. If you need to iterate over the objects of a group you can write easily Lua for loops. You can either iterate with a counter or directly iterate the content objects.

Shuffled Group:

shuffled_group = sorted_group:shuffle() shuffled_group = no["Atrax#*"]:shuffle()

Every group returns a shuffled group with the same members when receiving the message "shuffle".

Sorted Group:

sorted_group = group:sort("linear", po(2, 1)) sorted_group = group:sort("linear") sorted_group = group:sort("circular") sorted_group = group:sort()

Sort group objects in linear order according to given direction vector, or direction determined by the first two objects. Or order objects circular around their center. If no argument is given order objects lexically.

Subset Group:

sub_group = group:sub(2) -- first two objects sub_group = group:sub(-2) -- last two objects sub_group = group:sub(2, 4) -- objects from 2 to 4 sub_group = group:sub(2, -2) -- two objects starting with 2

Build subgroup with given indices and numbers.

Nearest Object:

object = group:nearest(reference)

Search object in group that is nearest to the given reference object.

5.2.6 Tiles and World Tasks

For reference details see section Tile and Object Declaration, Tiles Repository and World.

Tiles:

ti["_"] = {"fl_sahara"} ti["__"] = {"fl_sahara"} ti[".."] = {"fl_sand"} ti["##"] = {"st_blocker"} ti["switch_template"] = {"st_switch"} ti[".."] = {"fl_abyss"} -- redefinition causes error to avoid common mistakes ti[".w"] = ti[".."] .. {"it_magicwand"} ti[" w"] = {"fl_abyss"} .. ti({"it_magicwand"})

The tiles repository ‘ti’ is like a table, but specialized on storage of tile definitions. You can use any string as key. You can store the same definition twice at different keys. But you are not allowed to redefine an already set key. This is pure protection of common error situations. A definition stored in the repository can be used in other definitions that follow. Referencing a tile’s repository entry at a given key like ‘ti[".."]’ results in a tile value. Such tile values can be concatenated by the ‘..’ operator with other tile values and anonymous tables containing object definitions. The last example is a concatenation of two prior not declared object definitions. You can not concatenate two anonymous tables. Lua forbids that. By converting any of the two tables by the ‘ti()’ to a tile value the concatenation gets valid.

World Initialization

width, height = wo(ti, "__", { -- second arg: default tile key that "##__......", -- defines the base, too - this example "##..__.w__", -- is 2 chars per tile/grid "##.. w__.." })

The world is initialized by the ‘wo()’ call that is explained in details at World Creation. In the simple form you supply the ‘ti’ handle as the first argument. The second argument is the key of the default tile definition that defines the default floor to be set if a tile does not contain another floor object. At the same time this key defines by its length the standard key length as used in the following map, too. The third argument is the map given as an anonymous table of strings. The world’s size is given by the maximum line length and the number of lines. These values are returned by the call.

5.2.7 Named Positions Tasks

For reference details see section PositionList.

Named Position Usage:

obj["name"] = "anchor1" obj:kill() pos = po["anchor1"] po["anchor2"] = pos

The position of any named object can be directly retrieved. The position is still accessible under the name, when the object gets killed. You can additionally name own positions. Note that the position of an existing object precedes a position stored under the same name.

Creating Position Lists:

polist = po["deepwater#*"] polist = po(grp)

Requesting positions will result in a list of positions if you make proper usage of wildcards. A given object group can be converted into a position list, too.

Position List Usage:

wo[polist] = ti["x"] grp = fl(polist)

You can use a list of positions to set tiles or to retrieve a group of floors, items, stones.

Position List Operations:

wo[polist .. po["beach#*"]] = {"it_banana"}

Two position lists can be appended. Single positions can be appended to a given position list, too.

Position List Members:

for i = 1, #polist do wo[polist[i]] = {"it_cherry"} end

Single positions within the list can be accessed by index. The whole list can be traversed by a simple for loop. The hash length operator reports the number of contained positions.

5.3 Advanced Lua Examples

Now it is time to reveal the real power of the new API. Let us look again at two real levels. Investigate the levels first by playing and then join in the line by line commentary of the source code to understand how to implement your own level ideas.

5.3.1 Color Maze

Let us view the Lua source code part. We did add a line count in the first two columns for reference purpose within this section. These line count numbers are not part of the source code itself!

01    wo["ConserveLevel"] = false
02    wo["FollowGrid"] = false
03    wo["FollowMethod"] = FOLLOW_SCROLL
04
05    ti[" "] = {"fl_fake_abyss"} .. ti({"st_lightglass"})
06
07    ti["!"] = {"fl_blueslab", "blue#", _color="blue"}
08    ti["@"] = {"fl_pinkbumps", "orange#", _color="orange"}
09    ti["#"] = {"fl_redslab", "red#", _color="red"}
10    ti["$"] = {"fl_lawn_b", "green#", _color="green"}
11
12    ti["b"] = ti["!"] .. {"st_door", flavor="d", faces="ns", state=OPEN}
13    ti["B"] = ti["!"] .. {"st_door", flavor="d", faces="ew", state=OPEN}
14    ti["o"] = ti["@"] .. {"st_door", flavor="d", faces="ns", state=OPEN}
15    ti["O"] = ti["@"] .. {"st_door", flavor="d", faces="ew", state=OPEN}
16    ti["r"] = ti["#"] .. {"st_door", flavor="d", faces="ns", state=OPEN}
17    ti["R"] = ti["#"] .. {"st_door", flavor="d", faces="ew", state=OPEN}
18    ti["g"] = ti["$"] .. {"st_door", flavor="d", faces="ns", state=OPEN}
19    ti["G"] = ti["$"] .. {"st_door", flavor="d", faces="ew", state=OPEN}
20
21    ti["d"] = {"it_document", text="text1"}
22    ti["5"] = ti["b"] .. ti["d"]
23    ti["6"] = ti["O"] .. ti["d"]
24    ti["7"] = ti["r"] .. ti["d"]
25    ti["8"] = ti["G"] .. ti["d"]
26
27    ti["x"] = {"it_sensor", invisible=true, target="gates"}
28    ti["*"] = ti["x"] .. {"#ac_marble_black", "me"}
29
30    ti["?"] = {"st_oxyd_a"}
31
32    wo(ti, " ", {
33    --      |         1    1   |2    2
34    --      |1   5    0    5   |0    5
35           "                           ",
36           " xO@OxR#RxO@OxB!BxR#RxB!Bx ", --01
37           " b   r   g   g   b   g   r ",
38           " !   #   $   $   !   $   # ",
39           " b   r   g   g   b   g   r ",
40           " xR#RxB!BxO@OxG$GxO@OxO@Ox ", --05
41           " g   g   r   g   g   b   b ",
42           " $   $   #   $   $   !   ! ",
43           " g   g   r   g   g   b   b ",
44           " xR#RxO@OxG$GxR#RxG$GxR#Rx ",
45           " g   b   b   o       b   r ", --10
46           " $   !   !   @       !   # ",
47           " g   b   5   o   ?   b   r ", --
48           " xO@OxO@6*8$Gx   xG$GxR#Rx ",
49           " r   b   7   b   ?   o   o ",
50           " #   !   #   !       @   @ ", --15
51           " r   b   r   b       o   o ",
52           " xG$GxB!BxR#RxO@OxR#RxG$Gx ",
53           " g   o   o   g   g   o   b ",
54           " $   @   @   $   $   @   ! ",
55           " g   o   o   g   g   o   b ", --20
56           " xB!BxO@OxR#RxR#RxO@OxB!Bx ",
57           " o   r   g   g   b   b   g ",
58           " @   #   $   $   !   !   $ ",
59           " o   r   g   g   b   b   g ", --
60           " xR#RxB!BxB!BxR#RxO@OxR#Rx ", --25
61           "                           "} --
62    --      |         1    1   |2    2
63    --      |1   5    0    5   |0    5
64    )
65
66    last = it(no["me"])   -- the last visited sensor
67    move = 0              -- the count of link moves
68    sequence = {}         -- the sequence of the 4 colors that the user did choose
69
70    function gates(value, sender)
71        if last ~= sender then
72            local middle = last + (sender - last)/2
73            local color = fl(middle)["_color"]
74            if color == nil then return end  -- someone cheated, avoid throwing an exception
75            st(no[color.."#*"]):close()
76            sequence[move%4] = color
77            if move >= 3 then
78                st(no[sequence[(move+1)%4].."#*"]):open()
79            end
80            move = move + 1
81            last = sender
82        end
83    end

Let us concentrate on new aspects not discussed in the previous Basic Lua Examples.

01    wo["ConserveLevel"] = false
02    wo["FollowGrid"] = false
03    wo["FollowMethod"] = FOLLOW_SCROLL

This level must forbid the user to resurrect a marble at the start position. At the same time the user should see the area around the marble as complete as possible. Thus the scroll mode needs to be set, too. All this is done by setting special Global Attributes.

05    ti[" "] = {"fl_fake_abyss"} .. ti({"st_lightglass"})
32    wo(ti, " ", {

The inaccessible areas are filled with a transparent glass on top of a black floor as defined in line 5. The world initialization uses this tile definition as the default tile. This is o.k. as it contains a floor definition. Additional objects like the glass stone will never be set on default usage.

07    ti["!"] = {"fl_blueslab", "blue#", _color="blue"}
08    ti["@"] = {"fl_pinkbumps", "orange#", _color="orange"}
09    ti["#"] = {"fl_redslab", "red#", _color="red"}
10    ti["$"] = {"fl_lawn_b", "green#", _color="green"}

Every floor object is autonamed for later group access purposes. Additionally every floor object sets a user attribute prefixed in its name by an underscore ‘_’. This attribute stores a string that we need later on in the callback function.

12    ti["b"] = ti["!"] .. {"st_door", flavor="d", faces="ns", state=OPEN}
13    ti["B"] = ti["!"] .. {"st_door", flavor="d", faces="ew", state=OPEN}

The doors are set without being named, as we will target them by their position.

27    ti["x"] = {"it_sensor", invisible=true, target="gates"}

The actors moves are detected by invisible it_sensors that are positioned on any intersection. The target is the Callback Function ‘gates’. The action can be omitted as the function name is a unique target.

66    last = it(no["me"])   -- the last visited sensor

A Lua variable that stores the last sensor visited by the marble. This is initially the sensor beneath the start position of the marble. We do get the marble by name, but do store the sensor item beneath it, that is an unnamed object.

67    move = 0              -- the count of link moves
68    sequence = {}         -- the sequence of the 4 colors that the user did choose

These are the essential variables for our algorithm. The user is free in selecting the sequence of the colored floors. We do initialize the sequence by an anonymous table that will be filled with the color names. An additional move counter will give us the current index into this table.

70    function gates(value, sender)
71        if last ~= sender then

The callback function provides the sender, the it_sensor, that caused the action. It is the current sensor. As the marble can return to the last sensor, we have to check that it is a new sensor before taking any actions. A simple object comparison suffices.

72            local middle = last + (sender - last)/2
73            local color = fl(middle)["_color"]

We need to know the color of the floor strip that the marble did pass. We do calculate the position of the middle of this floor strip by position calculation. We simply take the middle position between the last and the current intersection. Once we have the middle position we can get the floor object and retrieve the private user attribute with the color description.

74            if color == nil then return end  -- someone cheated, avoid throwing an exception

In regular play we are guaranteed to get a color value. But just in case a gamer cheats he may have moved irregular without visiting neighboring sensors. Just avoid errors. The gamer can not score anyway.

75            st(no[color.."#*"]):close()

Knowing the color we want to close all doors on same colored floor strips. We did autoname the floors by matching name prefixes. Thus we can retrieve all floors of a given color by concatenating the color string with the suffix ‘#*’ and requesting the named object repository. As we are interested in the doors we do request the stone above every floor. We provide a group of floors and get a group of stones. Not every floor has a door on top. That does not matter as only existing objects are added to the resulting stone group. Knowing the stones we just send them all a ‘close’ message.