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