Scripting
General
Visionaire 3.0 comes with a Scripting language which is a combination of Lua (http://www.lua.org) and a Visionaire Object Model. The object model is used to access the Visionaire data structure in a convinient way. Almost every instance in Visionaire is represented as an object (e.g. scene, character, interface, ...) which can be manipulated through the scripting language.
Online documentation about scripting Language:
- Programming in Lua: http://www.lua.org/pil/index.html
- Reference Manual: http://www.lua.org/manual/5.1/
Visionaire Object Model
All objects can be accessed and manipulated through the scripting language. All objects of the same type (e.g. scene or button) are stored in one table. The properties of an object can be accessed by defined fields for the specific table. All objects and its fields are documented in Visionaire Data Structure.
The field types of the data structure are mapped to Lua types in the following way:
|
Field Type |
Lua Type |
|
t_link |
userdata (VisionaireObject) or string which describes the object path. See object access for description of the object path. |
|
t_links |
table (array) with Visionaire Objects (userdata or string, see t_link above) elements, each entry referencing one Visionaire Object. |
|
t_int |
number (integer) |
|
t_float |
number |
|
t_bool |
number (boolean) |
|
t_point |
table (with elements "x" and "y") |
|
t_rect |
table (with elements "x", "y", "width" and "height") |
|
t_string |
string |
|
t_path |
string |
|
t_sprite |
table (with element "path" and optional elements "x", "y", "cutting" (t_rect) and "transparent" (t_point)) |
|
t_vint |
table with number (integer) elements |
|
t_vfloat |
table with number (float) elements |
|
t_vpoint |
table with t_point elements |
|
t_vrect |
table with t_rect elements |
|
t_vstring |
table with string elements |
|
t_vpath |
table with t_path elements |
|
t_vsprite |
table with t_sprite elements |
VisionaireObject
Every instance of an object of the visionaire data structure is a VisionaireObject. With this object it is possible to read and manipulate the objects of the game.
The following methods are supported on a VisionaireObject:
isEmpty
Lua Syntax:
isEmpty()
- Return Values
- boolean
true if the object is empty, i.e. the VisionaireObject does not reference an object of the visionaire data structure.
isAnyObject
Lua Syntax:
isAnyObject()
- Return Values
- boolean
true if the object represents any object (isEmpty would return true because the object does not represent an object of the data structure). This is needed for actions where the user can set "[Any item]" for actions which should be executed in case an item was used.
getId
Lua Syntax:
getId()
- Return Values
- table
A table with the fields tableId and id returning the table id and object id of the VisionaireObject.
getParent
Lua Syntax:
getParent()
- Return Values
- VisionaireObject
The parent object for this object. An object has always a parent which contains it - only the game object has no parent.
getObject
Lua Syntax:
getObject(path)
- Arguments
- path
Path to a Visionaire Object. The path has to start with a dot '.' and then a field name (field type must either be t_link or t_links). For t_links fields you must specify an object name in brackets ('[',']'). For t_link fields there are no brackets. The path is relative to this object. See object access for description of the object path.
- Return Values
- VisionaireObject
- The found visionaire object or an empty object if no object was found.
- Example:
local scene = getObject("Scenes[Bedroom]")
local deskCond = scene:getObject(".SceneObjects[Desk].ObjectCondition")
Exported objects
The following objects are exported to the Lua scripting environment:
- currentAction: a visionaire object which represents the action where the current script was called from.
- emptyObj: an empty visionaire object.
Accessing an object
Use the getObject command to access a visionaire object. Pass an object path to the command to get the visionaire object.
Examples:
local mother = getObject("Characters[Mother]")
local cond = getObject("Scenes[Forest].SceneObjects[Tree].ObjectCondition")
Whenever an object path is needed you can specify it the following way:
1. start with a Table (as is shown in the table column of the Visionaire Data Structure).
2. if this table is not "Game" (this table has only one object) then you have to write the name of the object inside bracktes ('[' and ']').
3. either goto 7. or continue with 4.
4. write a dot '.' and then a fieldname of this object (the field type must either be t_link or t_links).
5. if the field type is t_links then goto 2., else goto 6.
6. either goto 7. or goto 4. (access another link)
7. done. A valid object is specified.
Examples:
Game.CharacterLinks[Tom]
Scenes[Room].SceneObjects[start].SceneConditions[game started?]
Characters[Tom].CharacterInterfaces[Tom-MI3]
Alternatively, you can also access an object by its table-id and object-id. It can be specified by a tuple:
(table-id,object-id)
Example:
(0,6)
Selects the object with id 6 from table 0 (characters).