Game code for STEAD is written in lua (5.1), therefore it is useful to know the language, though not necessary. The engine code in lua is about ~2000 lines long. And it is the best documentation.
The main game window contains information about static and dynamic parts of the scene, active events and the scene picture with possible passages to other scenes (in the graphic interpreter).
The dynamic part of a scene is composed of descriptions of the scene objects. It is always shown.
Static part of the scene is shown only once, when the player enters the scene. Also it is shown when the “look” command is repeated (click on the scene name in the graphic interpreter).
Inventory contains objects, that the player can access in every scene. The player can interact with the inventory objects or use inventory objects on other objects in the scene or inventory.
One should note that the “inventory” is defined rather vaguely. For example it may contain such objects as “open”, “examine”, “use”, etc.
Each game is a directory with a “main.lua” script. Other game resources (lua scripts, images, music) should be in this directory. All references to the resources are given relative to this game directory.
At the beginning of “main.lua” file a header may be defined. It consists of tags. Each tag should start with '--' symbols — lua comments. Right now only one tag exists: “$Name:”. It should contain the name of the game in UTF-8 encoding. For example:
The graphic interpreter searches for available games in the “games” directory. Unix version also checks “~/.instead/games”. Windows version (>=0.8.7) checks “Documents and Settings/USER/Local Settings/Application Data/instead/games”.
A scene is a game unit. Within it a player can examine all the scene objects and interact with them. A game should contain at least one scene with the name “main”.
The record means creation of an object “main” of a type “room”. Every object has attributes and handlers. For example the attribute “nam” (name) is obligatory for every object.
The “nam” attribute for a scene will be the scene name when it is played. The name of a scene is also used to identify it when passing between scenes.
The “dsc” attribute is a description of a static part of the scene. It is shown once when entering the scene or after the explicit “look” command.
Attention!!! If your creative design requires the static part description to be shown every time, you may define the “forcedsc” parameter for your game (at the start).
Object name “nam” is used when the object gets into the inventory or to address the object in a text interpreter.
“dsc” is an object descriptor. It will be shown in the dynamic part of the scene. Curly brackets indicate the text fragment which will be a link anchor in the graphic interpreter.
“act” is a handler, called when the player uses a scene object. It has to return a text line, which will become a part of the scene events, or a boolean value (see chapter 5)
WARNING: in the lua namespace some objects (tables) already exist. For example “table”, “io”, “string”... Be careful when creating objects. In the example above “tabl” is used instead of “table”. (But in fact, in modern versions of INSTEAD this problem is almost solved).
If the attribute or handler is laid out as a function, then the first argument of the function (s) is the object itself. In the example scene the dynamic part will have the text: 'There is something on the table.' When you try to use this “something”, '_seen' variable of the object “aple” will be set to “true” and we will see it was an apple.
`s._seen` means that the `_seen` variable is placed in the “s” object (in our case “aple”). Underscore means that this variable is saved in a savegame file.
Warning! Variable will be saved to savegame file if it was defined in: room, game, obj, player, global space and it's name begins from _ symbol or if it was defined using var/global.
In this case ''act'' handler is used to change room description but it is not supposed to add any description of its own. To achieve this we need to return true from the handler. It means the action is done successfully but does not require to diplay any additional description.
If you need to show some action is impossible, just don't return anything from handler. In this case default description will be shown for this action. Default actions can be set via ''game.act'' handler and are generally used for description of impossible actions.
Please note the new variable ''_dynamic_dsc'' is used to make a dynamic description in the above example. This is done to ensure new description is saved during the game save. Since the name 'dsc' does not start with underscore or capital letter it will not be saved by default.
This way when the player uses the “apple” object the apple is removed from the scene and added to the inventory. When the player uses the inventory “inv” handler is called.
In the present example when the player uses the apple in the inventory, the apple is eaten.
This way you can pass between ”main” and “room2” scenes. As you remember, “nam” may be a function, and you can generate scene names on the fly. For example if you don't want the player to know the name of the scene until he gets there.
When switching between scenes the engine calls the “exit” handler from the current scene and the “enter” from the destination scene. For example:
“exit” and “enter” may be functions. Then the first parameter is the object itself (as usual) and the second parameter is the room where the player is heading (for “exit”) or which he is leaving (for “enter”). For example:
As we see, the handlers can return two values: the string and the status. In our example the “exit” function returns “false” if the player tries to go to the “main” room from the hall. “false” means that the player will not pass. Same logic works for “enter” and “tak”.
Keep in mind that the current scene may not be changed by the moment of an enter action handler invocation. Since the version 1.2.0 available two new action handlers: 'left' and 'entered'. They are invoked immediately after the transition and recommended to use in case when transition prohibition is not required.
The player may use an inventory object on other objects. In this case “use” handler is invoked for the object in the inventory and “used” for the other one.
If the player takes the knife and uses it on the table, he gets the text of “use” and “used” hanlers. “use” and “used” may be functions. Then the first parameter is the object itself. The second parameter for “use” is the object being subjected to the action and fot “used” is the object performing the action.
If “use” returns “false” status, then “used” is not invoked (if there is one). The status of “used” is ignored.
As we can see, the object keeps the reference to the current player ('pl') and some parameters. For example at the start of your game you can set the encoding the following way:
The support of arbitrary encodings is present in every UNIX version of the interpreter and in windows versions from 0.7.7.
Also the object “game” may contain the default handlers: “act”, “inv”, “use”. They will be invoked if no other handlers are found after the user's actions. For example you can write at the game start:
Attribute lists (such as “way” or “obj”) allow to work with themselves thus allowing to implement dynamically defined passages between scenes, live objects, etc.
“add” adds to the list, “del” removes from the list, “purge” removes even disabled object, “srch” performs a search. “replace” replaces object. Note that “del”, “purge”, “replace” and “srch” may use as a parameter not only the object itself or its identifier, but also the object name.
Starting from version 0.8 the object itself may be a parameter of “add”. Also from this version an optional second parameter is added — position in list. From 0.8 you also can modify the list by the index with the “set” method. For example:
Apart from adding and deleting objects from lists you may switch them on and off with “enable()” and “disable()” methods. E.g. “knife:disable()”. This way the object “knife” will disappear from the scene description, but may be switched on later with “knife:enable()”.
From version 0.9.1 methods “zap” and “cat” can be used. zap() -- delete all elements. cat(b, [pos]) -- add all elements of list b to current list at position [pos].
Attention!!! Currently, it is recommended to use higher lever functions like: put/get/take/drop/remove/seen/have and so on, to work with objects and inventory.
* objs() returns the list of objects of the current scene; (from 0.8.5 it has an optional paremeter — the scene for which to return objects;
* ways() returns the list of passages from the current scene; (from 0.8.5 has an optional paremeter — the scene for which to return the list);
* me() returns the player object;
* here() returns the current scene; (from 0.8.5 another function where(obj) returns the scene where is object placed. Works only if it was placed with put/drop/move).
* from() returns an object from a previous scene;
* seen(obj, [scene]) returns an object, if it exists in scene and not disabled;
* have(obj, [scene]) returns an object, if it exists in the inventory;
* exist(obj, [scene]) returns an object, if it is exists in scene;
* live(obj) returns an object, if it is exists in lifes;
* path(obj,[where]) – lookup in way, even for disabled items;
If you want to move an object from an arbitrary scene, you'll have to delete it from the original scene with the “del” method. To create objects, that move in complex ways, you'll have to write a method that would save the object's position in the object itself and delete it from the original scene. You can set the initial position (room) as the third parameter of “move”.
From 0.8 there's a function “dropf” similar to “drop”, but adding the object to the list start. From 0.8.5 there's an optional second parameter — a room where to place the object. Also from >=0.8.5 there's a “put” function that does not remove the object from the inventory.
From version 0.8.9 there's a function remove(o, [from]), which deletes an object from the current scene or from the “from” scene.
change_pl(p) — switch to another player (with one's own inventory and position). The function returns the scene description of the new player and the returned value has to be transferred from the handler (see “goto()”).
“phr” creates a phrase. A phrase contains a question, an answer and a reaction (the example has no reaction). When the player picks one of the phrases, it is disabled. When all phrases are disabled, the dialog is over. Reaction is a line of lua code, which is executed when the phrase is disabled. E.g.:
In the example the player chooses his dinner. After getting the food (recording the choice in the “food._num” variable) he returns back to the scene from where he got in the dialog.
The reaction may have any lua code, but STEAD has some frequently used functions predefined:
pon(n..) — enable the phrases with numbers n... (in the example it allows to take the same food again).
poff(n...) — disable the phrases with numbers n...
prem(n...) — remove (block) phrases with numbers n... (blocked phrases won't be re-enabled with subsequent “pon”).
'“I do not know who you are,” he smiles, “but I have orders to let in only decent people.”',
[[pon(2);]]),
[2] = _phr('“I\'ve got an invitation!”',
'“And I don\'t care! Look at yourself in a mirror!!! You\'ve come to listen to Belin himself — the right hand of...” he made a respectful pause. “So get lost...”', [[pon(3,4)]]),
[3] = _phr(' “I\'m gonna kick your ass!”', '“I\'ve had enough...” Strong arms push me out to the corridor...',
`_phr` — creates a disabled phrase, which can be enabled. The example also shows the use of “pon”, “poff”, “prem” methods for a dialog (see “exit”).
You can enable/disable phrases not only of the current put of any arbitrary dialog with the “pon”/“poff” methods of a dialog object. For example: shopman:pon(5);
Sometimes a scene has to be filled with decorations with a limited functionality to add variety to the game. For that lightweight objects can be used. For example:
As you see, “vobj” allows to create a lightweight version of a static object, with which it will still be possible to interact (defining an “act” handler in the scene an analyzing the object name). “vobj” also calls the “used” method with the third parameter being the object which acts on the virtual object.
Any object or scene may have their “life” handler, which is called every time the game time advances, if the object or the scene have been added to the list of living objects with “lifeon”. Don't forget to remofe living objects from the list with “lifeoff”, when you no longer need them. You can do this, for example, in the “exit” handler or some other way.
From version 0.7.7 the set_music() function can get an additional parameter — the number of playbacks. You can get the current counter with “get_music_loop”. -1 means that the playback of the current track is over.
If version is >= 1.2.0 then the following modules are used automatically: vars, object, goto.
“prefs” object (included into “prefs” module) can store game preferences, e.g. player progress or attempt count…
<code>
require "prefs"
...
prefs.counter = 0
...
exit = function(s)
prefs.counter = prefs.counter + 1
prefs:store()
end
...
enter = function(s)
return 'You passed the game '..prefs.counter..' times';
end
...
act = function(s)
prefs:purge()
return "Preferences has been cleared"
end
</code>
“xact” module allows to make references to objects from other objects, reactions and life methods. These references have the form {object:string}, e.g.:
<code>
...
act = [[ I noticed a {myknife:knife} under the table.]]
...
</code>
"object" part of the reference can be object variable or object name.
This module also defines “xact” and “xdsc” objects.
“xact” is the simple reaction object. For example:
<code>
main = room {
forcedsc = true;
dsc = [[Author's comment: I was writing this game for a very {note1:long} time.]];
obj = {
xact('note1', [[More than 10 years.]]);
}
}
</code>
A reaction can contain a code:
<code>
xact('note1', code [[p "More than 10 years."]]);
</code>
“xdsc” allows to insert multiple description to the object list:
<code>
main = room {
forcedsc = true;
dsc = [[ I'm in the room. ]];
xdsc = [[ I see an {anapple:apple} and a {aknife:knife}. ]];
other = [[ There are also {achain:chain} and {atool:handsaw} here.]];
You can do menus in the inventory area, using menu constructor. Menu handler will be called after single mouse click. If handler have no return string the state of game will no change. For example, here is pocket realisation:
If you use “goto” from the “exit” handler, you get stack overflow, because goto would call “exit” again and again. You can prevent it by aadding a check that breaks the recursioon. For example:
It's convenient to create dynamic references either in the “enter” handler, or in the arbitrary place in the game code, where they are required. If the reference is created in the current scene, the example can be simplified:
If you want hide a game source code, you can encode it with command: “sdl-instead -encode <lua file> [encoded file]” and load encode file from lua with “doencfile”. It's neccessary to keep main.lua as plain text file. So, the recommended scheme is (game is a encoded game.lua ):
You can create a game with several characters and switch between them from time to time (see “switch_pl”). But you can also use the same trick to switch between different types of inventory.
Since version 1.1.5 ''instead'' supports mouse click handling (works with SDL version only). This can be done using ''input'' object.
input.click(s, pressed, mb, x, y, px, py) -- mouse click handler; pressed -- press or release event. mb -- mouse button index (1 is left button), x and y -- mouse cursor coordinates relative to upper left corner of the window. px and py parameters exist if a picture have been clicked, they contain mouse cursor coordinates relative to upper left corner of this picture.
Handler can return a ''stead'' interface command. In this case the interpreter doesn't handle a key.
For example:
<code>
input.click = function(s, press, mb, x, y, px, py)
if press and px then
click.x = px;
click.y = py;
click:enable();
return "look"
end
end
click = obj {
nam = 'click',
x = 0,
y = 0,
dsc = function(s)
return "You clicked a picture at "..s.x..','..s.y..'.';
end
}:disable();
main = room {
nam = 'test',
pic ='picture.png',
dsc = 'Example.',
obj = { 'click' },
};
</code>
Here is an example of a code layer that implements calling ''click'' method in the current room once the picture is clicked:
<code>
input.click = function(s, press, mb, x, y, px, py)
''new'' treats its string argument as an object constructor. The constructor must return an object. Thus, the string argument usually contains a constructor function call. For example:
Sometimes the we need to form event handler output from several parts depending on some conditions. In this case ''p()'' and ''pn()'' functions can be useful. These functions add text to the internal buffer of the handler. The content of this buffer is returned from the handler.
''pn()'' function adds line feed to the text and outputs the result to the buffer. ''p()'' does almost the same thing but adds a space instead of line feed.
Graphic interpreter supports theme mechanism. A theme is a directory with the “theme.ini” file inside.
The theme reqiured at the least is “default”. This theme is always the first to load. All other themes inherit from it and can partially or completely override its parameters. Themes are chosen by the user through the settings menu, but a game may contain its own theme. In the latter case the game directory contains its “theme.ini” file. However, the user may override custom game theme. If he does, the interpreter warns him that it disagrees with the game author's creative design.
“theme.ini” has a very simple syntax:
<parameter> = <value>
or
; comment
Pussible types of values are: string, color, number.
Colors are set in the #rgb form, where r g and b are color components in hexadecimal. Some colours are recognized by their names, e.g.: yellow, green, violet.
Possible parameters are:
scr.w = game area width in pixels (number)
scr.h = game area height in pixels (number)
scr.col.bg = background color
scr.gfx.bg = path to the background image (string)
scr.gfx.cursor.x = x coordinate of the cursor center (number) (version >= 0.8.9)
scr.gfx.cursor.y = y coordinate of the cursor center (number) (version >= 0.8.9)
scr.gfx.cursor.normal = path to the cursor picture file (string) (version >= 0.8.9)
scr.gfx.cursor.use = path to the cursor picture of the “use” indicator (string) (version >= 0.8.9)
scr.gfx.use = path to the cursor picture of the “use” indicator (string) (version < 0.8.9)
scr.gfx.pad = padding for scrollbars and menu edges (number)
scr.gfx.x, scr.gfx.y, scr.gfx.w, scr.gfx.h = coordinates, width and height of the picture window — the area to display the scene picture. Interpreted depending on the layout mode (numbers)
win.gfx.h - synonymous to scr.gfx.h (for compatibility)
scr.gfx.mode = layout mode (string “fixed”, “embedded” or “float”). Sets the mode for the picture. If “embedded”, the picture is part of the main window, scr.gfx.x, scr.gfx.y and scr.gfx.w are ignored. If “float”, the picture is placed in the coordinates (scr.gfx.x, scr.gfx.y) and downscaled to scr.gfx.w by scr.gfx.h if larger. If “fixed”, the picture is part of the main window as in “embedded”, but stays above the text and is not scrolled with it.
win.x, win.y, win.w, win.h = coordinates, width and height of the main wiindow. — the area with the scene description (numbers)
win.fnt.name = path to the font file (string)
win.fnt.size = font size for the main window (number)
win.gfx.up, win.gfx.down = paths to the pictures of up/down scrollers for the main window (string)
win.col.fg = font color for the main window (color)
win.col.link = link color for the main window (color)
win.col.alink = active link color for the main window (color)
inv.x, inv.y, inv.w, inv.h = coordinates, width and height of the inventory window (numbers)
inv.mode = inventory mode string (“horizontal” or “vertical”). In the horizontal mode several objects may fit in the same line, in the vertical — only 1 per line. (string)
inv.col.fg = inventory text color (color)
inv.col.link = inventory link color (color)
inv.col.alink = inventory active link color (color)
inv.fnt.name = path to the inventory font file (string)
inv.fnt.size = inventory font size (number)
inv.gfx.up, inv.gfx.down = paths to the pictures of inventory up/down scrollers (string)
menu.col.bg = menu background (color)
menu.col.fg = menu text color (color)
menu.col.link = menu link color (color)
menu.col.alink = menu active link color (color)
menu.col.alpha = menu transparency 0-255 (number)
menu.col.border = menu border color (color)
menu.bw = menu border width (number)
menu.fnt.name = paths to menu font file (string)
menu.fnt.size = menu font size (number)
menu.gfx.button = path to the menu icon (string)
menu.button.x, menu.button.y = menu button coordinates (number)
snd.click = path to the click sound file (string)
include = theme name (the last component in the directory path) (string)
The theme header may include comments with tags. Right now there is only one tag: “$Name:”, it contains an UTF-8 line with the theme name. E.g.:
The interpreter searches for themes in the “themes” directory. Unix version also checks ~/.instead/themes/ directory. Windows version (>=0.8.7) checks "Documents and Settings/USER/Local Settings/Application Data/instead/themes"