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.
Possible actions of the player are:
* looking at the scene;
* using a scene object;
* using an inventory object;
* using an inventory object on a scene object;
* using an inventory object on an inventory object;
* passing to another scene;
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”.
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.
And then always use “sw” or some other auxiliary function.
`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. Starting from version 0.7.7 variables starting with a capital letter also get saved.
Warning!!! The variables outside any of the following object types: room, object, game, player — never get saved.
From version 0.8.9 you can define a function “isForSave(k)”, which is called to determine whether to save a variable to a savegame file. By default it is defined this way:
here()._dsc = [[The room transformed after I pressed the button. The book-case disappeared along with the table and the chest, and a strange looking device took its place.]];
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, you can return false or nil from its `act` 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.
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 a reference to 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”.
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.
List methods are: “add”, “del”, “look”, “srch”. The most used are “add” and “del”.
“add” adds to the list, “del” removes from the list, “srch” performs a search. Note that “del” 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].
* 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).
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.
From 0.8.5 has optional second parameter — a room where to take the object from.
taken(o) — returns true if the object has already been taken (with “tak” or “take()”);
rnd(m) — random number from 1 to m.
goto(w) — go to scene w, the handler has to return the “goto” return value, since “goto” returns the description of the new scene or message that the passage is impossible. E.g.:
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 key). “vobj” also calls the “used” method with the third parameter being the object which acts on the virtual object.
“vobj” syntax: vobj(key, name, descriptor); where key is a number to be transferred to the “act”/“used” handlers of the scene as a second parameter.
There is a modification of “vobj” object — “vway”. It creates a reference.
“vway” syntax: vway(name, descriptor, destination scene); for example:
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.
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:
The engine code is in the stead.lua file. In your game you can redefine any lua function or object, getting whatever your creative concept needs. It is useful to know the peculiarities of the engine work. For example below is an implementation of player status as a text in the inventory, which cannot be picked.
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:
<code>
function myconstructor()
local v = {}
v.nam = 'test object',
v.act = 'test feedback',
return obj(v);
end
</code>
The object created will be saved every time the game is saved. ''new()'' returns a real object; to get its name you can use ''deref'' function:
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"