[Top] | [Contents] | [Index] | [ ? ] |
This manual describes the internals of Enigma, in particular how to build new levels using Lua and how to interact with the game engine. It describes Enigma version 0.90.
1. Introduction | General remarks on creating new levels | |
2. XML levels | The new XML-based level descriptions | |
3. Objects | Description of all objects in Enigma | |
4. Variables | Lua variables that influence the game | |
5. Functions | Predefined functions | |
Index |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This chapter explains how Enigma works internally and how you can create your own levels. This manual is not for users of graphical level editors, but rather for programmers of graphical level editors or users who want to use the full power of the Enigma "engine" by using the built-in scripting language.
There are two kinds of file formats you can use to build levels for Enigma. The traditional solution was to write small programs in a programming language called Lua. Although this is still possible, the preferred way is now to prepare files in a data-centric format called XML; this will be discussed in detail in chapter
Enigma's level format is extremely flexible and allows you to create very dynamic and interactive levels. Here are a few examples of levels that make heavy use of Lua, both when preparing the level and during the game:
Our focus is on using Lua to access Enigma's game engine, so you won't
learn much about Lua as a language in this chapter. Many simple things,
like function calls or if
statements, will appear familiar to
anyone having a little programming experience: In many ways Lua is
similar to programming languages like Basic or Pascal. But for most of
Lua's finer points you will have to reach for the official Lua
documentation, which you can download from
lua.org.
1.1 Creating New Levels | ||
1.2 A Simple Level | ||
1.3 Registering Levels | ||
1.4 Where to go from here |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Creating a new level basically consists of the following steps
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Here is a very simple level description that can also serve as a starting-point for new landscapes. (In fact, this is the first level in Enigma, so you can try it out right away.)
1 CreateWorld(20, 13) 2 draw_border("st-brownie") 3 fill_floor("fl-hay", 0,0, level_width,level_height) 4 5 set_stone("st-fart", level_width-1,0, {name="fart"}) 6 set_stone("st-timer", 0,0, {action="trigger", target="fart", 7 interval=10}) 8 9 oxyd(3,3) 10 oxyd(level_width-4,level_height-4) 11 oxyd(level_width-4, 3) 12 oxyd(3,level_height-4) 13 oxyd_shuffle() 14 15 set_actor("ac-blackball", 10,6.5) |
The resulting level looks like this inside the game:
Let's now turn to a line-by-line analysis of this program:
1 CreateWorld(20, 13) 2 draw_border("st-brownie") 3 fill_floor("fl-hay", 0,0, level_width,level_height) |
The level begins with a call to CreateWorld
, which creates a
new world that is 20 blocks wide and 13 blocks high. Every
block in the world can be accessed with a pair of coordinates:
The upper left corner has coordinates (0,0), the lower right one has
coordinates (19,12). Every block contains a floor tile, an (optional)
item, and an (optional) stone.
A frame of stones is drawn around the newly created landscape with the
draw_border
command. Its argument, "st-brownie"
, is the
name of a stone. By convention, all stones have "st-"
prefixed
to their name, similarly all item names begin with "it-"
and
all floor names with "fl-"
.
The fill_floor
command in line 3 fills the complete floor with
tiles of type "fl-hay"
. The other arguments are the upper left
corner and the width and height of the rectangle to be filled.
5 set_stone("st-fart", level_width-1,0, {name="fart"}) 6 set_stone("st-timer", 0,0, {action="trigger", target="fart", 7 interval=10}) |
Lines 5 to 7 demonstrate how to create individual stones. The
set_stone
command takes a stone name, the desired
coordinates, and an (optional) list of attributes
as arguments. Note the use of curly braces {
,
}
to enclose the attribute list.
Attributes are the key to customizing the behaviour of objects in a landscape. Here, we first give a name to the first stone we create. It's a fart stone that has the unpleasant habit of "blowing off" when triggered. Triggering this fart stone is done by the timer stone we create in line 6--7. This stone performs a predefined action at regular intervals. In this case we want to send a "trigger" message every ten seconds to the object named "fart".
9 oxyd(3,3) 10 oxyd(level_width-4,level_height-4) 11 oxyd(level_width-4, 3) 12 oxyd(3,level_height-4) 13 oxyd_shuffle() |
These commands place a couple of oxyd stones in the level. The
oxyd
command internally uses set_stone("st-oxyd", x,y,
...)
to create the stones, but it additionally assigns sensible
values to some of the oxyd stones' attributes (most notably the
color). The command on line 14 permutes the colors on the oxyd stones
currently in the landscape.
15 set_actor("ac-blackball", 10,6.5) |
This final line creates the black marble controlled by the player. Objects that can move around freely are called "actors" in Enigma. Unlike stones and items, actors are not restricted to integer coordinates, as you can see in this example.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
After writing the level description you have to tell Enigma where to find your brand new landscape. That's really two separate steps:
The `.lua'-Files and the corresponding level index usually reside in the same directory. For the levels that come with Enigma, for example, this is the `levels' directory inside. For your own levels you can either use the same directory (currently your only choice if you use the Windows version of Enigma) or the `.enigma/levels' directory in your home folder (only if you use the Unix version).
A level index is a file that contains the list of landscapes that comprise a level pack in Enigma. Here is an excerpt from `index_enigma.txt', which defines the "Enigma" level pack:
{file=welcome name="Welcome" author="Daniel Heck" } {file=martin06 name="Is It Easy?" author="Martin Hawlisch" } {file=lasers101 name="Lasers 101" author="Daniel Heck" } {file=level3a name="Feel Your Way" author="Siegfried Fennig" } {file=martin04 name="Sokoban Revival" author="Martin Hawlisch" } |
Every line in this file describes one landscape in the level pack. The general format of these lines is
{ tag1=content1 tag2=content2 ... } |
One line normally contains many different tag=content
pairs.
If your content contains spaces, surround the content with quotes
(e.g. name="Is It Easy?"
). If you want the string to contain quotes,
escape them with \
(e.g. author = "Petr \"ant\" Machata"
).
Here's a description of all supported tags:
file
name
author
revision
If you do changes to the level that affect the way the level is solved, you should increase the revision number. If you only did cosmetic changes, you should NOT increase the revision.
You should never decrease the revision number!
easymode
par_time
par_time=sec,name
sec
is the par time for the level in seconds.
name
is the player who did the par.
If easymode is 1 then par_time_easy
and/or par_time_normal
have to be used instead of par_time
.
When Enigma starts up it automatically tries to load an index file called `index_user.txt', where you can store all your personal levels. This file is not included in Enigma distributions, you have to create it yourself. The levels listed in this file will show up in a new level pack called "User Levels".
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The example level from the first section of this chapter was hopefully enough to give you an impression how level descriptions look like in Enigma. Of course, that level was extremely simple, and most interesting levels will be more complicated. The rest of this reference manual tries to document the available game objects and how to interact with the Enigma game engine, both when preparing the level (before the game starts) and during the game.
This manual only describes the low-level interface to Enigma's game
engine, which is as flexible as it is inconvenient to use by hand.
Petr Machata has written a comprehensive set of helper routines that
greatly simplify the creation of new levels. You can use the package
by including the line Require("levels/ant.lua")
in your level
descriptions. There is extensive documentation for `ant.lua' in
file `ant_lua.txt' in the documentation directory.
Before you read on, please be aware that this manual is far from complete. We are working on it and it will be ready for the (glorious) 1.0 release. For the moment, the available level descriptions are the best "documentation" available.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Enigma is slowly moving towards a more data-centric level description format. Although the current use of small Lua scripts for this purpose makes it possible to create levels with sophisticated dynamic behavior, it is difficult to create large, complex levels by hand and even more difficult to write graphical tools that help level designers with this task. The purpose of the XML-based levle format for Enigma is to provide an extensible basis for automated processing of Enigma levels, while retaining the full expressive power of the Lua scripting language where necessary or desirable.
The general outline of an XML-style Enigma level looks like this:
<level width="20" height="13"> <info> <!-- level information --> </info> <option ... /> <actors> <!-- actor definitions --> </actors> <floors> <!-- floor definition --> </floors> <items> <!-- item definition --> </items> <stones> <!-- stone definition --> </stones> <rubberbands> <!-- rubberband definition --> </rubberbands> <signals> <!-- signal definition --> </signals> <lua> <!-- optional Lua code --> </lua> </level> |
If you are unfamiliar with XML, here are a few general notes:
<level>
and closing tags </level>
.
level
tag.
Arguments have the form name="value"
; note that the value must
be enclosed in quotation marks.
<option ... />
is an abbreviation for
<option ...></option>
.
<!-- blabla -->
.
An Enigma level must begin with <level width="xx" height="yy">
,
where xx
and yy
are width and height of the level, and ends
with </level>
The following sections of this manual describe the
structure of the remaining parts of a level description, in the order
indicated in the above example.
2.1 Meta information | ||
2.2 Level options | ||
2.3 Actors | ||
2.4 Objects | ||
2.5 Signals | ||
2.6 Rubberbands | ||
2.7 Embedded Lua code |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Every level should begin with a short block containing general information about the level. This can include the level name, its author and license restrictions. If you intend your level(s) to be distributed with Enigma, the following four fields are mandatory:
<info> <name>LEVEL NAME</name> <author>AUTHOR NAME</author> <copyright>COPYRIGHT NOTICE</copyright> <license>LICENSE TERMS</license> </info> |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Certain aspects of the game can be customized by changing the values of the options to be described in this section. Some of these options control general aspects, like constant force fields or whether the level automatically restarts when the marble gets destroyed, while other options provide default values for objects in the level, like the strength of magnetic fields or the look of Oxyd stones.
The following example shows the general syntax for options. Note the use of empty tags: the salient information is already contained in the attributes name and value. Boolean options are always encoded as "YES" or "NO".
<option name="shuffle" value="NO" /> |
Here is the table of all options available so far:
shuffle
oxydflavor
reset
scrolling
In addition, there are a few numeric options that determine the behavior of certain comon objects. These correspond to the variables desribed later in the document, see 4. Variables for details.
brittleness
slopeforce
flatforce
frictionfactor
electricforce
bumperforce
magnetforce
magnetrange
wormholeforce
wormholerange
holeforce
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Syntax:
<actors> <actor kind=@"ac-blackball@" x=@"10.5@" y=@"5.5@" /> </actors> <actors difficulty=@"hard@"> <actor kind=@"ac-killerball" x=@"3@" y=@"4@" attribs=@"controllers=3@" /> </actors> <actors difficulty=@"easy@"> <actor kind=@"ac-killerball" x=@"3@" y=@"4@" attribs=@"controllers=0@" /> </actors> |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The description of floor tiles, items, and stones in the XML level file is very similar, so we treat them here in one section. The general syntax looks like this:
<floors> <row y=@"yy@"> ... </row> <floor kind=@"name@" x=@"xx@" y=@"yy@" attribs=@"attriblist@" /> </floor> |
For items and stones, the XML tags are called <items>
and
<stones>
respectively. As for the actor sections, you can
optionally include a difficulty=
option to place certain objects
only in the specified difficulty level.
The <row>
tag can be used to draw complete rows of objects to the
screen. An example looks like this:
<floors> <row y=@"10@">abyss 10 water # abyss 10 </row> </floors> |
This must be read as follows: In the tenth row, put one fl-abyss
(not that the prefix is not included in the level file!), repeat it ten
more times (so it's elevel abyss tiles), put one water tile, repeat it
once, and then finish with another eleven abysses.
Here's another, more advanced, example for a row of items:
<items> <row y=@"10@">-10 hammer - - blackbomb - # -5 3</row> </items> |
-2
instead), put one black bomb, skip one
field, put another black bomb, skip five fields, and finish with three
more black bombs.
In general there can be five different kinds of entries in such a row description, all of them separated by spaces:
#
-
You cannot specify object attributes using <row>
tags, to do this
you must place objects individually, using either <floor ... />
,
<item ... />
, or <stone ... />
, for example
<stones> ... <stone kind=@"st-switch@" x=@"2@" y=@"2@" attribs=@"action='openclose', target='door1'@" /> ... </stones> |
{}
that must be omitted in the XML level
format. Please note that you must in this case use single quotes
'
to enclose string attributes, double quotes would terminate the
XML argument. Enigma's current XML parser unfortunately does not yet
understand character entities like "
, this will hopefully be
fixed in future versions.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
[To be written]
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Syntax:
<rubberbands> <rubberband from=@"objname@" to=@"objname@" strength=@"12@" length=@"5@" minlen=@"0@" /> </rubberbands> |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
To make XML levels every bit as expressive as the former level format,
a special <lua>
tag is available to carry arbitrary Lua code.
Only one such tag per level is allowed, and the code it contains
is executed after all other tags have been processed, immediately
before handing the level over to the game engine.
Lua code blocks can be used for everything that can not be realized with the data-centric XML format, like specially crafted signal handlers, randomly generated levels or puzzles, or to access features of Enigma's game engine that are not otherwise available.
Graphical level editors are expected not to tamper with the contents of Lua code blocks when they read or write Enigma levels, i.e., neither to modify them nor to delete them without notice.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
3.1 Floors | ||
3.2 Items | ||
3.3 Stones | ||
3.4 Actors | ||
3.5 General object attributes |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
fl-abyss fl-acblack fl-acwhite fl-bridge( type ) fl-bridge-closed( type ) fl-bridge-open( type ) fl-gradient( type ) fl-gradient{1..16} fl-springboard fl-swamp fl-water |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
fl-abyss_fake fl-black fl-bluegray fl-bluegreen fl-bluegreenx fl-brick fl-bumps fl-concrete fl-darkgray fl-dummy fl-dunes fl-floor_001 fl-gravel fl-gray fl-hay fl-himalaya fl-ice fl-ice_001 fl-inverse fl-inverse2 fl-leaves fl-leavesb fl-leavesc{1..4} fl-leavesd{1..4} fl-leavese{1..4} fl-light fl-lightgray fl-marble fl-metal fl-metal{1..6} fl-mortar fl-normal fl-normal_x fl-plank fl-red fl-rock fl-rough fl-rough-blue fl-rough-red fl-rough_medium fl-rough_slow fl-sahara fl-samba fl-samba1 fl-samba2 fl-sand fl-space fl-space-force fl-stone fl-stwood fl-stwood1 fl-stwood2 fl-tigris fl-trigger fl-white fl-wood fl-woven |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
3.2.1 Item List | A complete list of all items | |
3.2.2 it-document: Scrolls of Paper | Scrolls of Paper | |
3.2.3 it-floppy: Floppy Disk | Floppy Disk | |
3.2.4 it-hollow: Hollows in the floor | Pits in the floor | |
3.2.5 it-ring: Ring | Ring | |
3.2.6 it-vortex: Vortex | Vortices for Teleporting |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
it-1pkillstone it-2pkillstone it-abyss it-bag it-banana it-blackbomb it-blackbomb_burning it-blocker it-blocker-new it-booze it-brake it-bridge-oxyd it-bridge-oxyd_active it-brush it-burnable it-burnable_ash it-burnable_burning it-burnable_fireproof it-burnable_ignited it-changefloor it-cherry it-coffee it-coin1( value ) it-coin2( value ) it-coin4( value ) it-crack{0..3} ( type fixed brittleness ) it-cross it-debris it-document( text ) it-drop it-dummy it-dynamite it-easykeepstone it-easykillstone it-explosion1 it-explosion2 it-explosion3 it-extinguisher( load ) it-extinguisher_empty( load ) it-extinguisher_medium( load ) it-extralife it-flagblack it-flagwhite it-floppy it-glasses it-glasses-broken it-hammer it-hill it-hollow it-hstrip it-inversesensor it-key( keycode ) it-key_a it-key_b it-key_c it-landmine it-magicwand it-magnet( on strength range ) it-magnet-off( on strength range ) it-magnet-on( on strength range ) it-odometer it-oxyd5f it-pencil it-pin it-pipe-e it-pipe-es it-pipe-h it-pipe-n it-pipe-ne it-pipe-s it-pipe-sw it-pipe-v it-pipe-w it-pipe-wn it-puller-e it-puller-n it-puller-s it-puller-w it-ring it-rubberband( object1 object2 length strength ) it-seed it-seed_nowood it-seed_volcano it-sensor it-shogun-l it-shogun-m it-shogun-s it-signalfilter0 it-signalfilter1 it-spade it-spoon it-spring1 it-spring2 it-springboard it-squashed it-surprise it-sword it-tinyhill it-tinyhollow it-trigger( invisible ) it-umbrella it-vortex-closed( autoclose targetx targety ) it-vortex-open( autoclose targetx targety ) it-vstrip it-weight it-whitebomb it-wormhole( on targetx targety strength range ) it-wormhole-off( on targetx targety strength range ) it-wrench it-yinyang |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This item looks like a piece of paper and contains text messages that can be displayed by activating the item.
Attributes
text
Example
set_item("it-document", 1,1, {text="Hello World!"}) Document(1,1, "Hello World") |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The floppy disk is needed to activate the Floppy switch (see 3.3.9 st-floppy: Floppy Switch).
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This item creates a hollow in the floor. If all existing @xref{ac-whiteball-small} are inside hollows the level succeeds.
Attributes
essential
Use this attribute if there are more holes than small whiteballs in a level and you want to determine which of the holes are needed to finish the level.
For example: If you have many holes and 3 whiteballs, then set
essential=1
in 3 holes. The game will end when the 3
whiteballs are inside the 3 marked holes.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
When a player drops this item, the marble is teleported. The destination depends on the game mode:
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Vortices, like wormholes, can be used to teleport marbles. In the simplest case, every vortex is connected to exactly one other vortex. If there are multiple target vortices, the marble will be teleported to the first unblocked target site. Many levels in the original Oxyd games required the player to selectively block vortices to gain access to new parts of the level.
Example
This example creates three vortices. If the second vortex is blocked, a marble falling into the first one is transported to (20,1).
set_item ("it-vortex", 1, 1) set_item ("it-vortex", 10,1) set_item ("it-vortex", 20,1) Signal ("it(1 1)", "it(10 1)") Signal ("it(1 1)", "it(20 1)") Signal ("it(10 1)", "it(1 1)") Signal ("it(20 1)", "it(1 1)") |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Simple stones
The following stone types are commonly used for "decoration". They
generally do not have special properties or abilities. Three types of
abbreviations are used in the tables: [abc]
stands for any of the
characters in square brackets, <abc>
stands for any subsequence
of the characters between the angle brackets (in this case abc, ab, bc,
a, b, c), and {1..9}
indicates a sequence of numbers.
st-beads st-bigbrick-<nesw> st-blue-sand st-bluegray st-bluegray_hole st-brick st-brownie st-bumps st-dummy st-fakeoxyd( blinking ) st-fakeoxyda st-glass st-glass[123] st-glass[12]_hole st-glass1_move st-glass_move st-grate{1..3} st-greenbrown st-greenbrown_hole st-greenbrown_move st-likeoxyd[abcd] st-likeoxyd[abcd]-open st-marble st-marble_hole st-marble_move st-metal st-plain st-plain_hole st-plain_move st-rock{1..8} st-rock[123]_hole st-rock[13]_move st-stone[12] st-wood[12] st-wood_001 st-woven st-yellow |
Special stones
The following stones types are special in the sense that they perform some action, either when hit by an actor, or all by themselves.
st-3mirror( transparent movable orientation ) st-actorimpulse st-actorimpulse_invisible st-black{1..4} st-blackballs st-block st-blocker st-blocker-growing st-bolder-[ensw] st-bombs st-brake st-break_acblack st-break_acwhite st-break_bolder st-break_gray st-break_invisible st-breaking st-brick_magic st-bug st-chameleon st-chargeminus( charge ) st-chargeplus( charge ) st-chargezero( charge ) st-coffee st-coinslot( on ) st-death st-death_invisible st-disco-dark st-disco-light st-disco-medium st-door( type ) st-door-h( type ) st-door-h-open( type ) st-door-v( type ) st-door-v-open( type ) st-door_[abc] st-easymode st-explosion st-fart st-flash st-floppy( on ) st-fourswitch( on ) st-greenbrown-growing st-invisible st-invisible_magic st-key( on keycode ) st-key_[abc] ( on keycode ) st-knight st-laser-[ensw]( on ) st-laserbreak st-laserswitch st-lasertimeswitch( delay ) st-magic st-mail-[ensw] st-mirror-3< st-mirror-3<m st-mirror-3<t st-mirror-3<tm st-mirror-3> st-mirror-3>m st-mirror-3>t st-mirror-3>tm st-mirror-3^ st-mirror-3^m st-mirror-3^t st-mirror-3^tm st-mirror-3v st-mirror-3vm st-mirror-3vt st-mirror-3vtm st-mirror-p- st-mirror-p-m st-mirror-p-t st-mirror-p-tm st-mirror-p/ st-mirror-p/m st-mirror-p/t st-mirror-p/tm st-mirror-p\ st-mirror-p\m st-mirror-p\t st-mirror-p\tm st-mirror-p| st-mirror-p|m st-mirror-p|t st-mirror-p|tm st-oneway-[nesw] st-oneway_black-[nesw] st-oneway_white-[nesw] st-oxyd( flavor color ) st-oxyd-0x18 st-peroxyd-0xb8 st-peroxyd-0xb9 st-plain_break st-plain_breaking st-plain_cracked st-plain_falling st-pmirror( transparent movable orientation ) st-pull st-puzzle-hollow( oxyd ) st-puzzle-<nesw>( oxyd ) st-puzzle2-hollow( oxyd ) st-puzzle2-<nesw>( oxyd ) st-rock3_break st-rock3_movebreak st-rotator-left st-rotator-right st-rotator_move-left st-rotator_move-right st-rubberband( length strength ) st-scissors st-shogun-<sml> st-spitter st-stone_break st-stonebrush st-stoneimpulse st-stoneimpulse-hollow st-stoneimpulse_movable st-surprise st-swap st-switch( on ) st-switch_black( on ) st-switch_white( on ) st-thief st-timer( on interval loop invisible ) st-timeswitch( delay ) st-turnstile st-turnstile-green st-turnstile-[ensw] st-volcano st-volcano-growing st-volcano_active st-volcano_inactive st-white{1..4} st-whiteballs st-window st-wood st-wood-growing st-yinyang{1..3} |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
These stones apply an impulse to actors that touch them. The amount
of force applied can be controlled by setting
@xref{enigma.BumperForce} accordingly (the default is 800).
Alternatively, the force
attribute can be used to set this
factor for individual bumper stones.
The invisible variant, @xref{st-actorimpulse_invisible} can "painted" with a @xref{it-brush}.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This stone takes on the look of the floor beneath it. Actors can move through it, so these stones are perfect for hiding stuff under them...
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
A switch that can be activated with coins. The more coins you put in, the longer the switch will stay activated.
Attributes
target, action
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Simply kills all marbles that touch it (except when protected by an umbrella).
Variants
st-death
st-death_invisible
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Darkens everything that is underneath the stone (much like tinted glass). Can be switched on and off (hence the name).
Messages
signal
lighten
darken
Variants
st-disco-light
st-disco-medium
st-disco-dark
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
In easy game mode this stone converts the floor at its position to
fl-normal
. In normal game mode the stone removes any item at
its position. The stone itself never appears in either game mode; it
removes itself immediately after performing its job.
This stone is commonly used to hide danger areas (water holes, abyss) or to insert helper items (umbrellas, seeds, etc.) that make the level easier in easy game mode.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The fart stone has the unpleasant habit of "blowing off" when triggered (by actor hit or signal) and will close all Oxyd stones.
Messages
trigger
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
A switch that is activated by inserting a floppy disk (see 3.2.3 it-floppy: Floppy Disk).
Attributes
on
target
action
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Floating grates, mainly decorative. Flying objects (jumping marbles, rotors, etc.) cannot pass, objects moving on the floor can.
Variants
st-grate1
st-grate2
st-grate3
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This switch is on
while hit by a laserbeam
and off
when not hit by a laserbeam.
See also 3.3.12 st-lasertimeswitch: Laser Time Switch.
Attributes
inverse=1
on
at startup and switch off
with laserbeam)
target,action
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This switch is a mix between 3.3.11 st-laserswitch: Laser Switch and 3.3.22 st-timeswitch: Time Switch.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This stone can be passed by the marble in only one direction. (Or, to be more exact, the arrow on the stone points to the one side of the stone through which it can't be entered. Hard to explain, try it yourself :-)
There are three different variants of the one-way stone: the standard
one, st-oneway
, which both the black and the white marble can
pass, and two colored ones, st-oneway_black
and
st-oneway_white
, which completely block marbles of the other
color.
Variants
st-oneway
st-oneway-[nesw]
st-oneway_black
st-oneway_black-[nesw]
st-oneway_white
st-oneway_white-[nesw]
Attributes
orientation
NORTH
, EAST
, SOUTH
, or WEST
. This
determines the orientation of the stone when the level is loaded. You
need to use the direction
message for changing the orientation
during the game. Note that it is usually easier to use one of the
alternative names, like st-oneway-north
instead of explicitly
setting this attribute.
Messages
direction
orientation
is not enough, since this does not update
the stone's model on the screen.
signal
flip
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Oxyd stones are characterized by two attributes: Their flavor and
their color. The flavor
only affects the visual representation
of the stone; it can be either `a' (opening like a flower), `b'
(displaying a fade-in animation), `c', or `d'. The color
attribute determines the color on the oxyd stone.
Note: You should rarely need to create Oxyd stones manually
with set_stone()
. Use the predefined oxyd()
function
instead. It will automatically take care of creating two Oxyd stones
of every color.
Attributes
flavor
color
Messages
closeall
shuffle
oxyd_shuffle()
function.
trigger
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
If hit by a marble, this stone first removes existing connections with other rubberband stones and then attaches a new elastic between the marble and itself. Nothing happens if the marble was already attached to this particular stone.
This stone can be moved if hit with a magic wand.
Attributes
length
strength
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This stone cuts all rubber bands attached to an actor that touches it.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This stone can be destroyed by an actor having a hammer and by laser, dynamite, bombs and bombstones.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This stone can exchange its position with other neighboring stones if it is hit hard enough. In a way, this makes swap stones a kind of "movable stone", except that they can be only exchanged with other stones and may not be moved on empty fields.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
A simple switch.
Variants
st-switch
st-switch_black
st-switch_white
Attributes
on
target, action
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Takes one item from inventory after when hit by the player's marble. Umbrellas protect against thievery.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This stone can be used to trigger periodic events or to trigger one single event after a certain amount of time.
Attributes
on
interval
action
is performed
loop
action
action
target
invisible
Messages
on
off
onoff
Example
-- activate a laser after 5 seconds set_stone("st-laser", 10,11, {name="laser"}) set_stone("st-timer", 10,10, {loop=0, action="onoff", target="laser", interval=5}) |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
When this switch is touched by an actor, it switches on
for 1.8 seconds and then switches off
again.
See also 3.3.12 st-lasertimeswitch: Laser Time Switch.
Attributes
delay
off
.
inverse=1
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Hit this window heavily with your marble to blast it into smithereens.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This stone is movable. If moved into abyss, water or swamp it builds a wooden plank.
Note: There are two flavors of st-wood
which may be specified
by using st-wood1
or st-wood2
.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Yin-Yang stones change into @xref{st-white} or @xref{st-black} if you touch them.
There are several flavors of this stone:
st-yinyang1
st-yinyang2
st-yinyang3
Actors get stuck inside the Yin-Yang Stone if they are starting there or when they warp there. They can be freed by changing the color of the Yin-Yang Stone to their color.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Movable objects are called "actors" in Enigma. The commonest actor is, of course, the black marble, but there are others, including the white marble, the killerball and a few more:
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
mouseforce (default 1.0) color (default 0.0) blackball (default 1) player (default 0) controllers (default 1)
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
mouseforce (default 1.0) color (default 1.0) whiteball (default 1) player (default 1) controllers (default 2)
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
mouseforce (default 1.0) color (default 1.0) whiteball (default 1) controllers (default 3)
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
mouseforce (default 2.0) color (default 1.0) whiteball (default 1) controllers (default 3)
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
range (default 5.0) force (default 10.0) gohome (default 1)
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
range (default 5.0) force (default 10.0) gohome (default 1)
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
force (default 10.0) target1 target2 target3 target4
3.4.9 Actor Attributes |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
All actors share a set of common attributes that determine their general behaviour:
player
mouseforce
controllers
ac-blackball
, ac-whiteball
and
ac-whiteball-small
have their controllers
attribute set
to 1,2, and 3 respectively.
essential
essential=1
, the game restarts if 1
of all essential
actors can't resurrect (analog for higher values). If you set the
attribute for several actors, you should use the same value for
all of them!
whiteball, blackball
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
name
name
attribute. Such named objects can
be searched using 5.4 enigma.GetNamedObject.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This chapter describes the a few variables that can be changed from level descriptions to alter the behavior of the game engine or set default attributes for some particular objects. In the latter case, the same effect can usually be achieved by setting the corresponding object attributes directly, but being able to specify a global default value it is often more convenient. You can always override these default attribute values for specific objects by setting the appropriate object attributes.
TRUE
or FALSE
. If FALSE
, reload the level
whenever the an actor that is controlled by a player (i.e., one that
has the player
attribute set) dies. Often used in meditation
landscapes or landscapes that are intended to be solved in one go.
Default: TRUE
.
TRUE
or FALSE
. This is only used in the Sokoban level
pack to display a move counter in the inventory.
Default: FALSE
.
st-actorimpulse
stone. 3.3.2 st-actorimpulse: Bumper Stones.
Default: 200.0.
fl-space
. Default: 0.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
5.1 AddRubberBand | Creating rubber bands | |
5.2 CreateWorld | ||
5.3 enigma.AddConstantForce | ||
5.4 enigma.GetNamedObject | ||
5.5 SendMessage | Sending messages to objects | |
5.6 draw_checkerboard_floor | ||
5.7 draw_border | Drawing a border of stones |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This function connects two objects with a rubber band: The first object is always an actor, the second object can be either another actor or a stone.
The first argument actor is always a reference to an actor
created earlier with the set_actor
function. The second
parameter object may be either an actor or a stone created
earlier. The last two parameters define the properties of the rubber
band: strength denotes the force factor of the elastic and
length its natural length. No force is exerted on the actor if
the rubber band is shorter than its natural length.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
local ac=set_actor("ac-blackball", 1.5,7.5) local st=set_stone("st-brownie", 10,6) AddRubberBand(ac, st, 50, 10) |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This function creates a new level. Because objects can only be added
to the level after CreateWorld
has been called,
you should usually do so near the beginning of your level
description.
The width and height denote the size of the new level. All levels with only one screen have the minimum size of 20x13 blocks.
Note that level fields are indexed from zero, i.e, the field indices for a 20x13 level are in the range (0..19)x(0..12). Also note that the screens in Enigma overlap by one line or column: A level that fits on a single screen has size of 20x13, but two a level that is two screens wide 39x13 or 20x25, three screens 58x13 or 20x37.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Adds global gravity to the current level.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This function searches for an object that has a name
attribute
with value objname. It returns a reference to the object or
nil
if none could be found.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
set_stone("st-wood", 7, 11, {name="woodie"}) ... local Woodie = enigma.GetNamedObject("woodie") |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This function sends a message to an object.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
set_stone("st-laser-s", 2, 2, {name="laser3", on=FALSE}) ... SendMessage("laser3", "onoff") |
set_stone("st-bolder", 7, 11, {name="bolder1", direction=SOUTH}) ... SendMessage("bolder1", "direction", WEST) |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This function draws checkerboard composed of two selected floor types. name1 and name2 are names of floor objects. See @xref{set_floor} for further details.
{attrib1=value1, attrib2=value2, ...}
. These attributes,
together with default attributes, are passed to each tile of the
generated checkerboard.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
draw_checkerboard_floor("fl-abyss", "fl-rough", 2, 2, 23, 11) draw_checkerboard_floor("fl-normal", "fl-inverse", 0, 0, levelw, levelh) -- racetrack |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This function adds a border of stones to your level. If invoked with only one argument, this border encloses the whole level.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
draw_border("st-marble") draw_border("st-greenbrown", 0,5,3,3) |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Jump to: | A C D E S |
---|
Jump to: | A C D E S |
---|
[Top] | [Contents] | [Index] | [ ? ] |
1. Introduction
1.1 Creating New Levels2. XML levels
1.2 A Simple Level
1.3 Registering Levels
1.4 Where to go from here
2.1 Meta information3. Objects
2.2 Level options
2.3 Actors
2.4 Objects
2.5 Signals
2.6 Rubberbands
2.7 Embedded Lua code
3.1 Floors4. Variables
3.1.1 Special floor tiles3.2 Items
3.1.2 Regular floor tiles
3.2.1 Item List3.3 Stones
3.2.2 it-document: Scrolls of Paper
3.2.3 it-floppy: Floppy Disk
3.2.4 it-hollow: Hollows in the floor
3.2.5 it-ring: Ring
3.2.6 it-vortex: Vortex
3.3.1 Stone List3.4 Actors
3.3.2 st-actorimpulse: Bumper Stones
3.3.3 st-chameleon: Chameleon Stone
3.3.4 st-coinslot
3.3.5 st-death: Skull Stones
3.3.6 st-disco: Disco Stones
3.3.7 st-easymode: Easy Mode Stone
3.3.8 st-fart: Fart Stone
3.3.9 st-floppy: Floppy Switch
3.3.10 st-grate: Grates
3.3.11 st-laserswitch: Laser Switch
3.3.12 st-lasertimeswitch: Laser Time Switch
3.3.13 st-oneway: One-way Stones
3.3.14 st-oxyd: Oxyd Stones
3.3.15 st-rubberband: Rubberband Stone
3.3.16 st-scissors: Scissors Stone
3.3.17 st-stone_break: Breakable Stone
3.3.18 st-swap: Swap Stone
3.3.19 st-switch: Switches
3.3.20 st-thief: Thief Stone
3.3.21 st-timer: Timer Stone
3.3.22 st-timeswitch: Time Switch
3.3.23 st-window: Breakable Stone
3.3.24 st-wood: Wooden Stone
3.3.25 st-yinyang: Yin-Yang Stones
3.4.1 ac-blackball3.5 General object attributes
3.4.2 ac-whiteball
3.4.3 ac-whiteball_small
3.4.4 ac-killerball
3.4.5 ac-rotor
3.4.6 ac-top
3.4.7 ac-bug
3.4.8 ac-horse
3.4.9 Actor Attributes
5. Functions
5.1 AddRubberBandIndex
5.1.1 Example5.2 CreateWorld
5.3 enigma.AddConstantForce
5.4 enigma.GetNamedObject
5.4.1 Example5.5 SendMessage
5.5.1 Examples5.6 draw_checkerboard_floor
5.6.1 Example5.7 draw_border
5.7.1 Example
[Top] | [Contents] | [Index] | [ ? ] |
1. Introduction
2. XML levels
3. Objects
4. Variables
5. Functions
Index
[Top] | [Contents] | [Index] | [ ? ] |
Button | Name | Go to | From 1.2.3 go to |
---|---|---|---|
[ < ] | Back | previous section in reading order | 1.2.2 |
[ > ] | Forward | next section in reading order | 1.2.4 |
[ << ] | FastBack | previous or up-and-previous section | 1.1 |
[ Up ] | Up | up section | 1.2 |
[ >> ] | FastForward | next or up-and-next section | 1.3 |
[Top] | Top | cover (top) of document | |
[Contents] | Contents | table of contents | |
[Index] | Index | concept index | |
[ ? ] | About | this page |
where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure: