# Predefined LUA functions

There is a number of functions that you can use in the level script. In this section, we'll look closer on them, to see which one does what job.

## init.lua functions

### Contents

AddRubberBand
CreateWorld
draw_checkerboard_floor
draw_border
draw_floor
draw_items
draw_stones
fill_floor
fill_items
fill_stones
GetAttrib
MakeObject
SetAttrib
set_attribs
SetDefaultAttribs
set_floor
set_item
set_stone
set_stones

### AddRubberBand

Syntax:
`AddRubberBand(actor, object, strength, length)`

Description: Rubber band connects an actor with some other actor or with a stone. It drags the two connected objects together with given strength, if their distance is greater than length. In case of two actors, each of them is dragged to the other one. If an actor is bound with stone, only actor is dragged towards the stone.

Actor: First argument always has to be a variable holding an actor object, you cannot bind two stones together. Typically the variable holds a return value of set_actor function.

Object: Second argument may be variable holding an actor or a stone. Typically return value of set_actor or set_stone function.

Strength: A force that drags the two objects to one another, if their distance is greater than length. If their distance is not as big, the strength is zero.

Example:

    local ac=set_actor("ac-blackball", 1.5,7.5, {player=0})
    local st=set_stone("st-brownie", 10,6)
    AddRubberBand(ac, st, 50, 10)

### CreateWorld

Syntax:
`CreateWorld(width, height)`

Description: Creates a new level. This should always be first thing to do before adding any stones, items, floors or actors. This function also initializes some internal variables and sets other variables to their default values.

Notes: Please note, that level fields are indexed from zero, so that level 20x13 has in fact fields (0..19)x(0..12).
Also note, that the screens in enigma overlap at one line or column. That means, that one screen level has size of 20x13, but two screens are 39x13 or 20x25, three screens 58x13 or 20x37.

Example:

    create_world(20, 25)

### draw_checkerboard_floor

Syntax:
`draw_checkerboard_floor(floorname1, floorname2, x, y, w, h, attribs)`

Description: This function draws checkerboard composed of two selected floor types.

Floorname1, Floorname2: Names of floor objects. See set_floor for further details.

x,y: Location of left top corner of checkerboard area. Note that upper left map corner is [0,0].

w,h: Size of generated checkerboard.

Attribs: Table of attribute names and corresponding values: `{attrib1=value1, attrib2=value2, ...}`. These attributes, together with default attributes, are passed to each filed of generated checkerboard.

Example:

    draw_checkerboard_floor("fl-abyss", "fl-rough", 2, 2, 23, 11)
    draw_checkerboard_floor("fl-normal", "fl-inverse", 0, 0, levelw, levelh) -- racetrack

### draw_border

Syntax:
`draw_border(stonename)`
`draw_border(stonename, x, y, w, h)`

Description: This function adds a border to your level - the row of stones, by default located at first and last row and column of the map.

Stonename: Name of stone that should make up the border. See set_stone for further details. If this is the only argument passed to the function (i.e., the first syntax is used), the border will bound whole map.

x, y: Location of upper left corner of bordered area. If you omit these arguments, zeroes are passed instead.

w, h: The width and height of bordered area. If you omit one of those parametters, level width and height are passed instead.

Example:

    draw_border("st-marble")
    draw_border("st-greenbrown", 0,5,3,3)

### draw_floor

Syntax:
`draw_floor(floorname, location, increment, count, attribs)`

Description: Use this function to add several floor objects to your level in periodical distances. How does it work? At first it places the floor to location. Then it moves by increment, and again places given floor. And again and again - so many times as defined by count.

Floorname: Name of floor object. See set_floor for further details.

Location: This is Lua table with two elements: `{x,y}`. They represent the location of first floor object you want to add to map.

Increment: Another Lua table with two elements: `{dx,dy}`. dx is the increment per step in x-axis, dy is increment per step in y-axis. Often this function is used to add a row of floors in one direction, and then Increment looks like this: `{1,0}` or `{0,1}`.

Count: Number of steps to proceed.

Attribs: Table of attribute names and corresponding values: `{attrib1=value1, attrib2=value2, ...}`. It represents the attributes to be passed to each created floor. You can omit this argument.

Example:

    draw_floor("fl-abyss", {3,0}, {0,1}, level_height)
    draw_floor("fl-gradient", {15, 5}, {1,0}, 4, {type=1})
    draw_floor("fl-water", {level_width-4,3}, {0,1}, level_height-6)

### draw_items

Syntax:
`draw_items(itemname, location, increment, count, attribs)`

Description: This function adds to your level several item objects in periodical distances. It works much like draw_floor except that it adds items instead of floors.

Itemname: Name of item object. See set_item for further details.

Location: This is Lua table with two elements: `{x,y}`. They represent the location of first item that you want to add to map.

Increment: Another Lua table with two elements: `{dx,dy}`. dx is the increment per step in x-axis, dy is increment per step in y-axis.

Count: Number of steps to proceed.

Attribs: Table of attribute names and corresponding values: `{attrib1=value1, attrib2=value2, ...}`. It represents the attributes to be passed to each created item. You may omit this argument.

Example:

    draw_items("it-trigger", {3,3}, {2,0}, 8)
    draw_items("it-tinyhill", {5,3}, {2,0}, 7)

### draw_stones

Syntax:
`draw_stones(stonename, location, increment, count, attribs)`

Description: This function adds to your level several stones in periodical distances. It works much like draw_floor except that it adds stones instead of floors.

Stonename: Name of stone object. See set_stone for further details.

Location: This is Lua table with two elements: `{x,y}`. They represent the location of first stone to be placed to map.

Increment: Another Lua table with two elements: `{dx,dy}`. dx is the increment per step in x-axis, dy is increment per step in y-axis.

Count: Total number of stones to add.

Attribs: Table of attribute names and corresponding values: `{attrib1=value1, attrib2=value2, ...}`. It represents the attributes to be passed to each created stone. You may omit this argument.

Example:

    draw_stones("st-grate1", {9,1},{0,1}, 5)
    draw_stones("st-stone_break", {21,1}, {1,0}, 10)

    function draw_border(stonename, x0, y0, w, h)
        draw_stones(stonename, {x0,y0}, {1,0}, w)
        draw_stones(stonename, {x0,y0+h-1},{1,0}, w)
        draw_stones(stonename, {x0,y0}, {0,1}, h)
        draw_stones(stonename, {x0+w-1,y0},{0,1}, h)
    end

### fill_floor

Syntax:
`fill_floor(floorname)`
`fill_floor(floorname, x, y, w, h)`

Description: This function fills an area of map with selected floor type.

Floorname: Name of floor object. See set_floor for further details. If this is the only argument to the function, whole map area is filled with this kind of floor.

x, y: Coordinates of upper left corner of filled area. Note that upper left square of map is at coordinates [0,0]. If those arguments are omitted, zero is passed instead.

w, h: Size of filled area. If any of these arguments is omitted, level width or height respectively is passed by default.

Example:

    fill_floor("fl-space", 0,0, level_width,level_height)  -- these two lines
    fill_floor("fl-space")                                 -- do the same
    fill_floor("fl-gray", 1, 1, level_width-2, level_height-2)
    fill_floor("fl-water", 24,47, 11,1)

### fill_items

Syntax:
`fill_items(itemname, x, y, w, h)`

Description: This function fills an area of map with items of selected kind.

Itemname: Name of item object. See set_item for further details.

x, y: Coordinates of upper left corner of filled area. Note that upper left square of map is at coordinates [0,0].

w, h: Size of filled area - w is width and h is height.

Note: Please note thatin contrast to function fill_floor, this function doesn't have any default attributes and no parametter may be omitted.

Example:

    -- (strange, no one ever used this function in their map...)
    fill_items("it-wormhole", 1, 1, 3, 3) -- field of 3x3 wormholes

### fill_stones

Syntax:
`fill_stones(stonename, x, y, w, h)`

Description: This function fills an area of map with stones of selected kind.

Stonename: Name of stone object. See set_stone for further details.

x, y: Coordinates of upper left corner of filled area. Note that upper left square of map is at coordinates [0,0].

w, h: Size of filled area - w is width and h is height.

Note: Please note thatin contrast to function fill_floor, this function doesn't have any default attributes and no parametter may be omitted.

Example:

    fill_stones("st-chameleon", 1, 1, 18, 11)
    fill_stones("st-grate1", 1, 5, 5, 7)
    fill_stones("st-death", 9, 5, 2, 2)

### GetAttrib

Syntax:
`GetAttrib(object, attribname)`

Description: The function is similar to SetAttrib, except that it doesn't set the attribute, but return current attribute value. Function arguments have the same meaning like in SetAttrib, see its description.

Example:

    local bolder_dir = GetAttrib(bolder1, "direction")

### MakeObject

Syntax:
`MakeObject(objname, attribs)`

Description: The function MakeObject is used internally by other functions, like set_floor, set_item or set_stone. It takes care of creating the object and sets up all desired attributes, including default ones.

Objname: Name of internal enigma object. It can be name of any floor, stone or item.

Attribs: Table of attribute names and corresponding values: `{attrib1=value1, attrib2=value2, ...}`

Example: To my best knowledge, no one uses this function in their levels. You should rather use set_floor/stone/item functions for creating particular enigma objects. If you need this function, you are probably guru and you don't need this manual either.

### SetAttrib

Syntax:
`SetAttrib(object, attribname, value)`

Description: The function sets the given attribute of a given object to given value. If you try to pass unknown attribute to an object, enigma will ignore it (i.e. nothing happens).

Object: The variable that holds the object. Every function that creates an object returns the variable representing freshly added object. That's right what should be passed to SetAttrib. (See example).

Attribname: Name of the attribute. See the description of objects to learn which object knows what attributes.

Value: New value of attribute.

Example:

    local ls = set_stone("st-laser", 1, 4, {on=FALSE, dir=NORTH})
    set_attrib(ls, "name", "laser")

(also "on" and "dir" are attributes in this example)

### set_attribs

Syntax:
`set_attribs(object, attribs)`

Description: This function sets several attributes at a time. The only thing it does is call SetAttrib as many times as needed to set values of all desired attributes.

Object: Value that holds the object, whose attributes are about to change.

Attribs: Table of attribute names and corresponding values: `{attrib1=value1, attrib2=value2, ...}`

Example:

    local ls = set_stone("st-laser", 1, 4, {on=FALSE, dir=NORTH})
    ... (some lua code) ...
    set_attribs(ls, {on=TRUE, dir=WEST})

### SetDefaultAttribs

Syntax:
`CreateWorld(objname, attribs)`

Description: Use this function if there are several objects of same kind, that have attributes (all or just some) with same value. For example if there are twenty wormholes with strength of 10, you can set the strength of 10 as a default value for all wormholes.

Objname may be name of any enigma stone, floor or item. In most cases this is wormhole, because it's usual to have several wormholes with same strength and range, while it's not very common to have for example all doors vertical or all bolders facing west.

Attribs: Table of keys and corresponding values: `{attrib1=value1, attrib2=value2, ...}`

Notes: Default attributes can be overriden or several extra attributes can be assigned to object. The attributes specified at creation time (using set_floor, set_item, set_stone functions) override default attributes specified by SetDefaultAttribs.

Example:

    SetDefaultAttribs("it-wormhole", {range=1.0, strength=10})
    set_item("it-wormhole", 11, 6, {targetx="48.5",targety="56.5"})

### set_floor

Syntax:
`set_floor(floorname, x, y, attribs)`

Description: As you would expect, this function creates a floor at given [x,y] position in enigma level, and passes all necessary default attributes and attributes passed in attribs argument.

Floorname: Enigma internal object name. The name should be the name of floor (they typically start with "fl-" prefix). In fact, it is possible to add a stone object as a floor, but strange things happen. Generally nothing you would like to use in your levels.

x, y Location where you want the floor to be placed. Note that level coordinates begin with zero (see CreateWorld).

Attribs: Table of attribute names and corresponding values: `{attrib1=value1, attrib2=value2, ...}`

Example:

    function setup_gradient_rose(x,y)
       set_floor("fl-gradient", x, y+1, {type=1})
       set_floor("fl-gradient", x, y-1, {type=2})
       set_floor("fl-gradient", x+1, y, {type=3})
       set_floor("fl-gradient", x-1, y, {type=4})
    end

### set_item

Syntax:
`set_item(itemname, x, y, attribs)`

Description: This function is very similar to the one named set_floor, describer earlier. It creates an item at given position. Items in enigma are all those magic wands, brushes, coins, triggers, bombs and also for example the laser ray or crackles. There can be only one single item on each position.

Itemname: Enigma internal object name. The name has to be the name of item (they typically start with "it-" prefix). Enigma won't let you create an item from other object that just item.

x, y Location where you want the item to be placed. Note that level coordinates begin with zero (see CreateWorld).

Attribs: Table of attribute names and corresponding values: `{attrib1=value1, attrib2=value2, ...}`

Note: The rule of single item per field also means, that laser cannot "overshoot" magic wand or trigger, that you cannot drop item to cracked floor etc. It may look like disadvantage, but on the other hand, it can be used as an advantage (see for example the level named "Follow the Light" in "Oxyd Clones" package).

Example:

    set_item("it-trigger", 34, 3, {action="openclose", target="bridge1"})

### set_stone

Syntax:
`set_stone(stonename, x, y, attribs)`

Description: This function is very similar to the one named set_floor, describer earlier. It places the stone to desired location. Stones in enigma are all walls, glass blocks, death's heads, and also doors, switches, lasers, bolders and lots of other special enigma objects.

Stonename: Enigma internal stone name. The name has to be the name of stone (they typically start with "st-" prefix). Enigma won't let you create the stone from other object that just stone.

x, y Location where you want the stone to be placed. Note that level coordinates begin with zero (see CreateWorld).

Attribs: Table of attribute names and corresponding values: `{attrib1=value1, attrib2=value2, ...}`

Example:

    set_stone("st-door", 18,  6, {name="door01", type="h"})
    set_stone("st-bolder", 2, 11, {name="bolder01", direction=NORTH})

### set_stones

Syntax:
`set_stones(stonename, positions, attribs)`

Description: This function is somehow similar to draw_stones. It can place several stones to locations all over the map. The locations to which the stones will be placed are listed in argument positions.

Stonename: Enigma internal stone name. See set_stone for further details.

Positions Table of stone locations. Its format is like this: `{loc1, loc2, ...}`, where each location is `{x,y}`. Together it looks like this: `{{x1,y1}, {x2,y2}, ...}`.

Attribs: Table of attribute names and corresponding values: `{attrib1=value1, attrib2=value2, ...}`. Those attributes will be passed to created stones together with default attributes. You may omit this attribute.

Example:

    set_stones("st-glass", {{1,6},{1,12},{34,1},{34,2},{35,2},{36,1},{36,2}})
    set_stones(bordertile, {{34, 1}, {34, 5}, {34, 7}, {34, 11}})
    set_stones("st-invisible", {{7,9}}) -- these two lines
    set_stone("st-invisible", 7, 9)     -- do the same

## Functions and variables internal to enigma

display.SetFollowMode(display.FOLLOW_SCREEN)
enigma.ConserveLevel = TRUE

## ?? natmaze.lua package

## ?? ant.lua package

Last modified: Tue Sep 24 15:46:25 CEST 2002