Enigma Reference Manual

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

1. Running Enigma

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

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

1.1 Locating Resources

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

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

Preferences Path

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

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

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

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

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

User Path

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

A backup of this directory is mandatory!

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

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

User Image Path

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

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

System Path

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

Resource Paths

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

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

l10n Path

This path shows the directory that contains the localization data.

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

1.2 Startup Switches

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

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

--assert

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

--data -d path

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

--help -h

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

--lang -l lang

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

--log

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

--nograb

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

--nomusic

Start Enigma without playing backgroud music.

--nosound

Start Enigma with sounds being switched off.

--pref -p filename

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

--version

Just print the version number to the output and terminate.

--window -w

Start Enigma in window mode instead of screen mode.

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

A Unix user may start Enigma with the following command:

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

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

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

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

1.3 User Options

Ratings update

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

User name

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

User path

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

Deletion of the string resets the path to the default.

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

User image path

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

Deletion of the string resets the path to the default.

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

1.4 Level Info

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

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

1.4.1 Public Ratings

Most levels are rated within five different categories:

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

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

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

Intelligence (int)

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

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

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

Dexterity (dex)

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

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

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

Patience (pat)

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

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

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

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

Knowledge of Enigma (kno)

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

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

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

Speed and speed control (spe)

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

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

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

Combinations of ratings

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

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

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

1.4.2 Scores

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

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

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

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

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

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

1.4.3 Versions

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

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

1.4.4 Privat Annotations and Ratings

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

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

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

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

1.4.5 Screenshots

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

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

1.5 Handicap and PAR

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

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

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

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

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

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

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

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

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

2. Levelpack Basics

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

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

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

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

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

2.1 Getting Started with Levelpacks

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

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

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

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

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

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

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

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

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

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

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

2.2 Converting 0.92 Levelpacks

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

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

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

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

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

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

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

2.3 Zip Levelpacks

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

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

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

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

2.4 Grouping and Sorting Levelpacks

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

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

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

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

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

2.5 Creating New Levelpacks

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

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

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

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

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

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

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

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

2.6 Modifying and Deleting Levelpacks

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

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

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

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

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

2.7 Composing Levelpacks

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

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

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

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

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

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

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

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

3. Level Basics

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

3.1 Getting Started with Levels

A Simple Level

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

 1   CreateWorld(20, 13)
 2   draw_border("st-brownie")
 3   fill_floor("fl-hay", 0,0, level_width,level_height)
 4
 5   set_stone("st-fart", level_width-1,0, {name="fart"})
 6   set_stone("st-timer", 0,0, {action="trigger", target="fart",
 7             interval=10})
 8
 9   oxyd(3,3)
10   oxyd(level_width-4,level_height-4)
11   oxyd(level_width-4, 3)
12   oxyd(3,level_height-4)
13   oxyd_shuffle()
14
15   set_actor("ac-blackball", 10,6.5)

The resulting level looks like this inside the game:

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

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

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

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

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

 5   set_stone("st-fart", level_width-1,0, {name="fart"})
 6   set_stone("st-timer", 0,0, {action="trigger", target="fart",
 7             interval=10})

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

Attributes are the key to customizing the behaviour of objects in a landscape. Here, we first give a name to the first stone we create. It's a fart stone that has the unpleasant habit of "blowing off" when triggered. Triggering this fart stone is done by the timer stone we create in line 6-7. This stone performs a predefined action at regular intervals. In this case we want to send a "trigger" message every ten seconds to the object named "fart".

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

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

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

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

3.2 XML Level structure

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

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

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

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

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

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

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

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

Elements:

/level, required, single occurence

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

Attributes:

xmlns:xsi, required, contents fixed

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

xsi:schemaLocation, required, contents fixed

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

xmlns:el, required, contents fixed

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

xmlns:ee, optional

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

/level/protected, required, single occurence

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

/level/protected/info, required, single occurence

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

/level/protected/elements, optional, single occurence

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

/level/protected/luamain, optional, single occurence

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

/level/protected/editor, optional, single occurence

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

/level/protected/i18n, required, single occurence

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

/level/public, optional, single occurence

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

/level/public/i18n, optional, single occurence

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

/level/public/upgrade, optional, single occurence

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

3.3 Info metadata

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

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

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

Attributes:

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

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

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

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

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

quantity, optional

The number of levels contained in a multilevel file.

Contents - Elements:

identity, required

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

version, required

All aspects of the level <version>.

author, required

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

copyright, required

The <copyright> message for the level.

license, required

Information about the <license> conditions.

compatibility, required

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

modes, required

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

comments, optional

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

update, optional

Update and Upgrade

upgrade, optional

Update and Upgrade

score, required

The authors own <score> of this level.

3.3.1 <identity>

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

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

Attributes:

title, required

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

subtitle, optional

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

id, required

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

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

YYYYMMDDuserNNN

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

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

Contents:

The element itself is empty - no content is allowed.

3.3.2 <version>

This element provides the versioning information for the system.

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

Attributes:

score, required

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

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

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

release, required

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

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

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

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

revision, required

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

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

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

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

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

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

Contents:

The element itself is empty - no content is allowed.

3.3.3 <author>

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

The author element node may look like:

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

Attributes:

name, optional, default = "anonymous"

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

email, optional

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

homepage, optional

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

Contents:

The element itself is empty - no content is allowed.

3.3.4 <copyright>

The standardized location for a copyright message of the author:

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

Attributes:

none

Contents:

The copyright notice of the author.

3.3.5 <license>

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

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

Attributes:

type, required

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

open, required

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

Contents:

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

3.3.6 <compatibility>

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

Attributes:

enigma, required

The minimal Enigma release number required for compatibility.

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

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

Contents - Elements:

The comments element itself contains only subelements as content.

dependency, optional, mutiple occurence

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

Attributes:

path, required

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

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

id, required

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

release, required

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

preload, required

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

url, optional

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

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

Contents:

none.

externaldata, optional, multiple occurence

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

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

Attributes:

path, optional

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

url, optional

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

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

Contents:

none.

editor, optional, single occurence

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

Attributes:

name, required

The name of the level editor.

version, required

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

Contents:

none

Contents:

none

3.3.7 <modes>

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

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

Attributes:

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

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

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

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

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

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

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

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

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

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

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

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

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

Contents:

none

3.3.8 <comments>

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

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

Attributes: none

Contents - Elements:

The comments element itself contains only subelements as content.

credits, optional, single occurence

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

Attributes:

showinfo, optional, default = "false"

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

showstart, optional, default = "false"

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

Contents:

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

dedication, optional, single occurence

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

Attributes:

showinfo, optional, default = "false"

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

showstart, optional, default = "false"

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

Contents:

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

code, optional, single occurence

Attributes:

none.

Contents:

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

3.3.9 <score>

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

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

Attributes:

easy, required

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

difficult, required

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

Contents:

3.4 LUA code

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

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

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

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

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

Attributes:

none

Contents:

This element takes the main Lua code as its contents.

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

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

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

3.5 Internationalization (i18n)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

3.6 Usage

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

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

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

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

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

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

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

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

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

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

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

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

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

3.7 Update and Upgrade

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

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

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

Attributes:

url, required

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

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

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

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

Attributes:

url, required

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

release, required

The release version of the upgrade.

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

3.8 Libraries

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

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

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

3.8.1 Writing a Library

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

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

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

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

3.8.2 Maintaining a Library

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

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

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

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

4. Objects

4.1 Floors

4.1.1 Common Floor Attributes

Standard attributes:

friction

Overrides the default friction for this floor tile.

mousefactor

Overrides the default mousefactor.

force_x, force_y

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

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

burnable

Sets if the floor may burn.

ignitable

Sets if the floor gets ignited by explosions.

secure

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

eternal

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

noash

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

fastfire

Sets if the fire spreads fast.

initfire

Sets if the floor starts burning on initialisation.

4.1.2 Special floor tiles

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

4.1.3 Regular floor tiles

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

4.1.4 fl-abyss

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

4.1.5 fl-ac[black/white]

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

4.1.6 fl-bridge

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

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

Attributes

type

a, x or y

Messages

open, close, openclose

as they say

signal

change state, like openclose

Variants

fl-bridge

open by default

fl-bridge-open

fl-bridge-close

4.1.7 fl-dummy

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

4.1.8 fl-gradient

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

Attributes

force

overrides enigma.SlopeForce

type

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

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

Variants

fl-gradient

type 1 by default

fl-gradient1 .. fl-gradient12

type is 1..12

fl-gradient13 .. fl-gradient16

types are 22, 21, 24 and 23

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

4.1.9 fl-ice

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

Variants

fl-ice

4.1.10 fl-inverse

Inverses the mouse movements (negative mouseforce).

Variants

fl-inverse

fl-inverse2

4.1.11 fl-nomouse

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

4.1.12 fl-space

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

4.1.13 fl-space-force

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

4.1.14 fl-swamp

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

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

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

4.1.15 fl-thief

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

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

4.1.16 fl-water

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

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

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

4.2 Items

4.2.1 Item List

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

4.2.2 System and Debug Items

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

it-1pkillstone, it-2pkillstone

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

it-bridge-oxyd, it-bridge-oxyd_active

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

it-debris

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

it-dummy

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

it-easykillstone

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

it-easykeepstone

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

it-explosion[1,2,3]

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

it-oxyd5f

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

it-signalfilter[0/1]

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

4.2.3 Hills and Hollows

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

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

Messages

trigger

Converts a hill to a hollow and vice versa.

shovel

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

signal

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

Attributes

essential

only it-tinyhollow and it-hollow, see below

In Meditation Levels

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

Use the essential-attribute if there are more holes than small whiteballs in a level and you want to determine which of the holes are needed to finish the level (1 means this hollow must be filled with a whiteball to end the level).

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

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

4.2.4 Fire and Extinguisher

Compare The 1.0-Fire System.

There are six items special to the fire system:

• Use it-burnable to allow a floor tile to catch fire, and it ignites from explosions like from it-dynamite, it-blackbomb and it-whitebomb.
• it-burnable_oil is the visible variant of the invisible it-burnable.
• it-burnable_ignited carries the starting-animation of fire. Use the setfire-message to a floor instead.
• it-burnable_burning carries the animation of burning fire. Use setfire instead.
• it-burnable_ash is the unburnable remnant of a fire.
• it-burnable_fireproof saves a floor from fire.

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

4.2.5 it-abyss

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

4.2.6 it-bag

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

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

4.2.7 it-banana

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

4.2.8 it-blackbomb

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

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

Messages

ignite, expl

ignite, then explode

explode

explode instantly

Variants

it-blackbomb

it-blackbomb_burning

4.2.9 it-blocker

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

Messages

trigger, openclose

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

open, close

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

signal

1: open, 0: close

Variants

it-blocker

it-blocker-new

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

4.2.10 it-booze

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

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

4.2.11 it-booze-broken

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

4.2.12 it-brake

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

4.2.13 it-brush

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

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

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

4.2.14 it-changefloor

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

4.2.15 it-cherry

When used, the marble becomes invisible for a short time (rotors and tops can't find it, marble can walk through glass). When a stone is pushed over it-cherry, it becomes it-squashed.

4.2.16 it-coffee

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

4.2.17 it-coin

Activates st-coinslot.

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

Attributes

value

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

Variants

it-coin1

it-coin2

it-coin4

4.2.18 it-crack

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

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

Attributes

type

0, 1, 2, or 3

fixed

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

brittleness

overrides enigma.Brittleness

Messages

crack

grow by one step

Variants

it-crack0

it-crack1

it-crack2

it-crack3

4.2.19 it-cross

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

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

Attributes

action, target

as usual

Messages

brush

remove it-cross

signal

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

4.2.20 it-death

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

4.2.21 it-document

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

Attributes

text

The message to be displayed.

Messages

expl, bombstone

destroy

ignite

destroy if not in Oxyd compatibility mode

Example

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

4.2.22 it-drop

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

4.2.23 it-dynamite

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

Messages

ignite, expl, bombstone

ignite, then explode

explode

explode instantly

4.2.24 it-extralife

Adds a life to the player's inventory.

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

4.2.25 it-flag[black/white]

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

4.2.26 it-floppy

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

4.2.27 it-glasses

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

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

Variants

it-glasses

it-glasses-broken

4.2.28 it-hammer

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

4.2.29 it-[h/v]strip

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

Variants

it-hstrip

horizontal

it-vstrip

vertical

4.2.30 it-key

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

Attributes

keycode

see st-key: Key (or Lock) Stone

Variants

it-key

keycode is 1

it-key_a

keycode is 1

it-key_b

keycode is 2

it-key_c

keycode is 3

4.2.31 it-landmine

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

4.2.32 it-magicwand

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

4.2.33 it-magnet

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

Attributes

on

TRUE or FALSE, see variants below

strength

default: 30

range

default: 1000 (quasi infinite)

Messages

on, off, onoff

as usual

signal

0: off, 1: on

Variants

it-magnet

by default off

it-magnet-on

it-magnet-off

4.2.34 it-odometer

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

4.2.35 it-pencil

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

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

4.2.36 it-pin

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

4.2.37 it-pipe

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

Variants

it-pipe-e

it-pipe-w

it-pipe-s

it-pipe-n

it-pipe-es

it-pipe-ne

it-pipe-sw

it-pipe-wn

it-pipe-h

horizontal

it-pipe-v

vertical

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

4.2.38 it-puller

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

Variants

it-puller-e

it-puller-w

it-puller-s

it-puller-n

4.2.39 it-ring

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

Single player levels:

The marble is transported to its starting position or to the position of the last dropped it-flag[black/white].

Multi player levels:

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

4.2.40 it-rubberband

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

Attributes

target

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

length

The natural length of the rubberband (default: 1)

strength

The strength of the rubberband (default: 10)

minlength

The minimal length of the rubberband (default: 0)

scissor

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

4.2.41 Examples

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

4.2.42 it-seed

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

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

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

Messages

grow, signal

start growing

Variants

it-seed

it-seed_nowood

it-seed_volcano

4.2.43 it-sensor

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

Attributes

action, target

as usual

Variants

it-sensor

it-inversesensor

4.2.44 it-shogun

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

Attributes

target, action

as usual

Messages

noshogun

deactivate

shogun ....

used to activate or deactivate it-shogun

Variants

it-shogun-s

it-shogun-m

it-shogun-l

4.2.45 it-spade

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

4.2.46 it-spoon

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

4.2.47 it-spring[1/2/board]

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

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

Variants

it-spring1

it-spring2

it-springboard

4.2.48 it-squashed

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

4.2.49 it-sword

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

4.2.50 it-trigger

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

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

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

Attributes

invisible

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

action, target

as usual

Messages

signal

perform action/target according to second data

4.2.51 it-umbrella

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

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

4.2.52 it-vortex

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

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

Attributes

targetx, targety

destination of teleport

autoclose

not implemented yet, see variants below

Messages

open, close, openclose

as they say

trigger

identical to openclose

signal

0: close, 1: open

arrival

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

Variants

it-vortex-open

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

it-vortex-closed

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

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

Example

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

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

4.2.53 it-weight

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

4.2.54 it-whitebomb

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

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

Messages

ignite, expl

ignite, then explode

explode

explode instantly

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

4.2.55 it-wormhole

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

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

Attributes

targetx, targety

exit of the wormhole

strength, range

strength and range of the force field

on

whether force field is on

interval

minimal delay between two teleports

Messages

on, off, onoff

as usual

signal

0: off, 1: on

Variants

it-wormhole

it-wormhole-off

wormhole without force field

4.2.56 it-wrench

Changes direction of st-rotator: Rotator Stone.

4.2.57 it-yinyang

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

4.3 Stones

4.3.1 Stone List

Simple stones

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

st-beads
st-blue-sand
st-bluegray
st-bluegray_hole
st-brick
st-brownie
st-bumps
st-camouflage
st-dummy
st-fakeoxyd( blinking )
st-glass
st-glass[123]
st-glass[12]_hole
st-glass1_move
st-glass_move
st-greenbrown
st-greenbrown_hole
st-greenbrown_move
st-likeoxyd[abcd]
st-likeoxyd[abcd]-open
st-marble
st-marble_hole
st-marble_move
st-metal
st-redrock
st-rock{1..10}
st-rock[123]_hole
st-rock[13]_move
st-stone[12]
st-wood[12]
st-wood_001
st-woven
st-yellow

Special stones

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

st-3mirror( transparent movable orientation )
st-actorimpulse( force hit_factor hit_distortion_[xx/xy/yx/yy] )
st-actorimpulse_invisible( force hit_factor hit_distortion_[xx/xy/yx/yy] )
st-bigbluesand-<nesw>
st-bigbrick-<nesw>
st-black{1..4}
st-blackballs
st-block
st-blocker
st-blocker-growing
st-bolder( direction )
st-bolder-[ensw]( direction )
st-bombs
st-brake
st-break_acblack
st-break_acwhite
st-break_bolder
st-break_gray
st-break_invisible
st-breaking
st-brick_magic
st-bug
st-chameleon
st-chargeminus( charge )
st-chargeplus( charge )
st-chargezero( charge )
st-chess_black( color direction1 direction2 )
st-chess_white( color direction1 direction2 )
st-coffee
st-coinslot( on action target )
st-death
st-death_invisible
st-disco-dark
st-disco-light
st-disco-medium
st-door( type )
st-door-h( type )
st-door-h-open( type )
st-door-v( type )
st-door-v-open( type )
st-door_[abc]
st-easymode
st-explosion
st-fakeoxyda
st-fart
st-firebreak
st-firebreak_move
st-flash( hit_factor hit_distortion_[xx,xy,yx,yy] )
st-flhay
st-floppy( action target on )
st-flrock
st-fourswitch( action target on )
st-grate[123]
st-greenbrown-growing
st-invisible
st-invisible_magic
st-key( action target on keycode )
st-key_[abc]( action target on keycode )
st-knight
st-laser( dir on )
st-laser-[ensw]( dir on )
st-laserbreak
st-laserswitch( action target inverse )
st-lasertimeswitch( action target inverse delay )
st-lightpassenger( interval friction_factor gradient_factor )
st-magic
st-mail-[ensw]
st-mirror*( movable transparent orientation )
st-mirror-3<
st-mirror-3<m
st-mirror-3<t
st-mirror-3<tm
st-mirror-3>
st-mirror-3>m
st-mirror-3>t
st-mirror-3>tm
st-mirror-3^
st-mirror-3^m
st-mirror-3^t
st-mirror-3^tm
st-mirror-3v
st-mirror-3vm
st-mirror-3vt
st-mirror-3vtm
st-mirror-p-
st-mirror-p-m
st-mirror-p-t
st-mirror-p-tm
st-mirror-p/
st-mirror-p/m
st-mirror-p/t
st-mirror-p/tm
st-mirror-p\
st-mirror-p\m
st-mirror-p\t
st-mirror-p\tm
st-mirror-p|
st-mirror-p|m
st-mirror-p|t
st-mirror-p|tm
st-oneway( orientation )
st-oneway-[nesw]( orientation )
st-oneway_black( orientation )
st-oneway_black-[nesw]( orientation )
st-oneway_white( orientation )
st-oneway_white-[nesw]( orientation )
st-oxyd( flavor color static )
st-oxyd-0x18
st-peroxyd-0xb8
st-peroxyd-0xb9
st-plain
st-plain_break
st-plain_breaking
st-plain_cracked
st-plain_falling
st-plain_hole
st-plain_move
st-pmirror( transparent movable orientation )
st-polarswitch( on )
st-pull
st-puzzle-hollow( oxyd )
st-puzzle-<nesw>( oxyd )
st-puzzle2-hollow( oxyd )
st-puzzle2-<nesw>( oxyd )
st-rock3_break
st-rock3_movebreak
st-rotator-left
st-rotator-right
st-rotator_move-left
st-rotator_move-right
st-rubberband( length strength minlength scissor)
st-scissors( action target )
st-shogun-<sml>( holes )
st-spitter( hit_factor hit_distortion_[xx/xy/yx/yy] )
st-stone_break
st-stonebrush
st-stoneimpulse
st-stoneimpulse-hollow
st-stoneimpulse_movable
st-surprise
st-swap
st-switch( action target on )
st-switch_black( action target on )
st-switch_white( action target on )
st-thief
st-timer( action target on interval loop invisible )
st-timeswitch( action target delay inverse )
st-turnstile
st-turnstile-green
st-turnstile-[ensw]
st-volcano
st-volcano-growing
st-volcano_active
st-volcano_inactive
st-white{1..4}
st-whiteballs
st-window
st-wood
st-wood-growing
st-yinyang{1..3}

4.3.2 Breakable Stones

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

st-stone_break, st-rock3_break, st-break_gray

hammer, laser, pyro

st-break_acblack

ac-blackball with hammer, laser, pyro

st-break_acwhite

ac-whiteball with hammer, laser, pyro

st-break_bolder

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

st-break_invisible

hammer after using a brush

st-laserbreak

laser, pyro

st-rock3_movebreak

hammer, pyro; this stone is movable

st-plain_break

hammer, laser, pyro; falls into fl-abyss

st-plain_cracked

hammer, pyro

st-plain_move

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

st-bug

ac-bug

st-breaking, st-plain_breaking

breaks instantly, looks like st-rock3

st-fart

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

st-bombs

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

st-brake

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

st-puzzle

see st-puzzle: Puzzle Stones

st-volcano_active

hammer; see st-volcano: Volcano

st-lightpassenger

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

st-firebreak

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

st-firebreak_move

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

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

4.3.3 Oxyd Compatibility Stones

st-magic disappears when hit strong enough.

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

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