=======================
CREATING NEW LANDSCAPES
=======================

Enigma does not currently include a graphical level editor.  Instead,
landscapes are described by small programs that are loaded and
interpreted by the game engine.

To create new levels you have to know a few basics about Lua, the
programming language used internally by Enigma.  Fortunately, Lua is a
very simple language, and only a subset of it is required for all but
the most complicated levels.

The bulk of this chapter describes the available game objects, their
attributes, and the programming interface used to put these objects in
a landscape.  This manual will not teach you how to create *new* kinds
of objects or modify existing ones.  If that's what you're interested
in, your best bet is to (a) read the source code, and (b) join the
Enigma development mailing list.

This file is more of a reference manual than a tutorial.  If you are
new to creating Enigma levels, you may prefer to read the ``Overview''
in the next section, study some of the existing levels, and then come
back to this text for more information as needed.


1.0     Quick Overview 
----------------------

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 try it out right away.)

 1   create_world(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   enigma.AddConstantForce(0,6)
 9
10   oxyd(3,3)
11   oxyd(level_width-4,level_height-4) 
12   oxyd(level_width-4, 3) 
13   oxyd(3,level_height-4) 
14   oxyd_shuffle() 
15 
16   set_actor("ac-blackball", 10,6.5, {player=0})

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

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

The first line creates a new world that is 20 blocks wide and 13
blocks high.  Each ``block'' in the world can be accessed with using a
pair of coordinates: The upper left corner has coordinates (0,0), the
lower right one has coordinates (19,12).  Each block contains a floor
tile, an (optional) item, and an (optional) stone.

A frame of stones is drawn around the landscape just created with the
``draw_border'' command.  The 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 likewise fills the complete floor
with tiles of type "fl-hay".  As additional arguments, this function
takes 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--7 demonstrate how to place individual stones into the world.
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".

 8   enigma.AddConstantForce(0,6)

This command adds a constant force field to the landscape.  The
horizontal component of the force is 0, while the vertical is 6, so
all movable objects in the landscape (in this case we have only one
black marble) is pulled towards the bottom of the screen.

10   oxyd(3,3)
11   oxyd(level_width-4,level_height-4)
12   oxyd(level_width-4, 3)
13   oxyd(3,level_height-4)
14   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.

16   set_actor("ac-blackball", 10,6.5, {player=0})

This final line creates the black marble controlled by the player.
Objects that can move around freely are called ``actors'' in Enigma
(to be completely honest, there is currently only this single type of
actor in Enigma, but more of them will be added in future releases).
Unlike stones and items, actors are naturally *not* restricted to
integer coordinates, as can be seen in this example.  The final
argument is, as usual, a list of attributes.  For the time being, this
should always be "{player=0}".

[The "player" attribute will become more important in future releases
when one player can control multiple actors, or when there are two (or
even more) players.]


2.0     PREDEFINED FUNCTIONS
============================

2.1     Functions
-----------------

* create_world(width, height)
* make_object(name, attrs)
* set_attrib(object, key, value)
* set_attribs(object, attrs)

* set_stone(stname, x, y, attrs)
* set_floor(flname, x, y, attrs)
* set_item(itname, x, y, attrs)

* fill_floor(flname, x,y, width, height)
* draw_floor(flname, {x,y}, {xinc, yinc}, n, attrs)
* draw_items(itname, {x,y}, {xinc, yinc}, n, attrs)
* draw_stones(stname, {x,y}, {xinc, yinc}, n, attrs)
* draw_border(stname)
* set_stones(stname, poslist, attrs)
* set_actor(name, x,y, attrs)

* def_stone(stname, sound)
* def_floor(flname, friction, mousefactor)

2.2     Variables
-----------------

* level_width
* level_height
* oxyd_default_flavor
* EAST, WEST, SOUTH, NORTH
* TRUE, FALSE


3.0     AVAILABLE OBJECTS
=========================

3.1     Floors
--------------

Abyss ("fl-abyss")
Water ("fl-water")


3.2     Items
-------------

Document ("it-document")
Magic Wand ("it-magic")
Trigger ("it-trigger")
Shogun Dot ("it-shogundot")
Hollows ("it-hollow", "it-tinyhollow")
Hills ("it-hill", "it-tinyhill")


3.3     Stones
--------------

Bolder Stone ("st-bolder")
--------------------------

  Attributes

    "direction"   NORTH, EAST, SOUTH, WEST


Fart Stone ("st-fart")
----------------------

* Messages

  "trigger"	blow off


Timer Stone ("st-timer")
------------------------

    This stone can be used to trigger periodic events or to trigger
    one single event after a certain amount of time.

  Attributes

    "on" (1)        1 if the timer is running
    "interval" (1)  number of seconds before "action" is performed
    "loop" (1)      if 1, restart the timer after performing "action"
    "action", "target"

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


