Difference between revisions of "Scripting"
m |
|||
Line 1: | Line 1: | ||
− | Visionaire Studio comes with its own | + | Visionaire Studio comes with its own scripting language, which consists of: a combination of Lua script (http://www.lua.org) and a Visionaire Object Model. The object model is used to access the Visionaire [[Data_Structure|data structure]] in a convenient way. Almost every instance in Visionaire is represented as an object (e.g. scene, character, interface, ...), all of which can be manipulated through the scripting language. |
---- | ---- | ||
− | Online documentation about scripting Language: | + | Online documentation about the Lua scripting Language: |
* Programming in Lua: http://www.lua.org/pil/index.html | * Programming in Lua: http://www.lua.org/pil/index.html | ||
* Reference Manual: http://www.lua.org/manual/5.1 | * Reference Manual: http://www.lua.org/manual/5.1 |
Revision as of 17:50, 20 January 2015
Visionaire Studio comes with its own scripting language, which consists of: a combination of Lua script (http://www.lua.org) and a Visionaire Object Model. The object model is used to access the Visionaire data structure in a convenient way. Almost every instance in Visionaire is represented as an object (e.g. scene, character, interface, ...), all of which can be manipulated through the scripting language.
Online documentation about the Lua scripting Language:
- Programming in Lua: http://www.lua.org/pil/index.html
- Reference Manual: http://www.lua.org/manual/5.1
- AFRLme's Guide to Lua Script: Basic Lua
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 the data structure page.
The field types of the data structure are mapped to Lua types in the following way:
Field Type | Description |
---|---|
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) entries, each entry referencing one Visionaire Object. |
t_int | number (integer) |
t_float | number (decimal) |
t_bool | boolean (true or false) |
t_point | table (with entries "x" and "y") |
t_rect | table (with entries "x", "y", "width" and "height") |
t_string | "string" |
t_text | table with entries "text", "sound" (relative path to sound file for speech output) and "language" (language id). |
t_path | "string" |
t_sprite | table with entries "path" (relative path to image file), "position" (t_point for sprite offset in case sprite is used in an animation), "transparency", "transpcolor" (transparent color) and "pause" (pause value in msec in case sprite is used in an animation). |
t_vint | table with number (integer) entries |
t_vfloat | table with number (float) entries |
t_vpoint | table with t_point entries |
t_vrect | table with t_rect entries |
t_vstring | table with string entries |
t_vtext | table with t_text entries |
t_vpath | table with t_path entries |
t_vsprite | table with t_sprite entries |
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.
- emptyObject: an empty visionaire object.
- game: the game object. This is the same as calling getObject("Game") but faster and easier to use.
Exported constants
The following constants are exported to the Lua scripting environment:
- all fields which are used to reference attributes of visionaire objects. The fields are all listed in the Visionaire Data Structure documentation. To reference a field use a V and the field name. E.g. VDialogPartAvailable to reference the field DialogPartAvailable.
- all visionaire tables. These constants start with an e and then the plural table name. E.g. for the table Action the constant is eActions.
- DIVIDING_POINT: a table with entries x and y which specifies a point which is used to separate multiple polygons. Usually a point list (t_vpoint field) can contain multiple polygons (e.g. ObjectPolygon which is used for the object boundaries). In this point list a point which is equal to DIVIDING_POINT marks the end of the current polygon.
- localAppDir: directory where the save games (in the sub directory save games), the messages.log file and possible dumps are written to. This directory is also used for the config.ini in case the project file is given as command line parameter for the player.
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 attributes of all objects.
The following methods are supported on a VisionaireObject (in alphabetical order):
clearLink
Removes a link from the visionaire object. A more convenient alternative to the emptyObject method (see examples below).
clearLink(number)
Arguments
number | The field which specifies a link to be cleared. The field type must be t_link. |
Example(s)
game:clearLink(VGameSpeechLanguage)
versus...
game:setValue(VGameSpeechLanguage, emptyObject)
getBool
Returns a boolean value of true or false.
getBool(number)
Arguments
number | The field which specifies a boolean value. The field type must be t_bool. |
Return Values
boolean | Current value of the specified field. Will return true or false. |
Example(s)
local allowSkipText = game:getBool(VGameAlwaysAllowSkipText)
getFloat
Returns a float (decimal) value.
getFloat(number)
Arguments
number | The field which specifies a number value. The field type must be t_float. |
Return Values
float | A decimal value. For example: 3.141 |
Example(s)
getObject("Game.GameCurrentCharacter"):getFloat(VCharacterSize)
getFloats
Returns a table containing multiple float (decimal) values. Iteration is required.
getFloats(number)
Arguments
number | The field which specifies a number list. The field type must be t_vfloat. |
Return Values
table | A table containing multiple float (decimal) values. |
getId
Returns the ID of the specified table or object.
getId()
Return Values
table | A table with the fields tableId and id returning the table id and object id of the VisionaireObject. |
Example(s)
function checkAnimOwner(n)
n = getObject("Animations[" .. n .. "]")
-- + --
if n:getParent():getId().tableId == eOutfits then
print( n:getName() .. " is a character animation" )
else
print( n:getName() .. " is not a character animation" )
end
end
checkAnimOwner("pick_up") -- check if "pick_up" animation belongs to a character or not.
getInt
Returns an integer (number) value.
getInt(number)
Arguments
number | The field which specifies a number value. The field type must be t_int. |
Return Values
integer | An integer (number) value. |
Example(s)
local direction = getObject("Characters[Tom]"):getInt(VCharacterDirection)
getInts
Returns a table containing multiple integer (number) values. Iteration is required.
getInts(number)
Arguments | Description |
---|---|
number | The field which specifies a number list. The field type must be t_vint. |
Return Values | Description |
table | A table containing multiple integer (number) values. |
getLink
Returns a VisionaireObject.
getLink(number)
Arguments | Description |
---|---|
number | The field which specifies a link. The field type must be t_link. |
Return Values | Description |
userdata (VisionaireObject) | The linked object; or an empty object if no object is linked for this field. |
Example:
game:getLink(VGameCurrentCharacter)
getLinks
Returns a table containing multiple VisionaireObjects.
getLinks(number)
Arguments | Description |
---|---|
number | The field which specifies a link list. The field type must be t_links. |
Return Values | Description |
table | Table containing multiple VisionaireObjects (links). |
Example:
local c_act = getObject("Characters[Tom]"):getLinks(VCharacterActions) -- store all actions associated with Tom into a variable
-- iterate the list by printing each link to the log.
for i = 1, #c_act do -- for i = 1 to list total do...
print( c_act[i]:getName() ) -- print the name of each action to the log based on current index value (i).
end
-- it's also possible to access a specific tables data value by including an index value.
print( c_act[1] ) -- print link inside of table index 1.
getName
Returns the name of a VisionaireObject. This should not be confused with the names included in the properties tab of an object.
getName()
Return Values | Description |
---|---|
"string" | The internal name of the visionaire object (editor). This is the name which is used to access the object. |
Example:
game:getLink(VGameCurrentScene):getName() -- this would return the "string" name of the current scene.
getObject
This is the most common method for accessing all the various fields & tables of the visionaire data structure.
getObject("string")
Arguments | Description |
---|---|
"string" | 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 | Description |
userdata (VisionaireObject) | A VisionaireObject; or an empty object if the return value is nil. |
Example:
local scene = getObject("Scenes[Bedroom]")
local deskCond = scene:getObject(".SceneObjects[Desk].ObjectCondition")
getParent
Returns the parent object of the specified VisionaireObject.
getParent()
Return Values | Description |
---|---|
VisionaireObject | The parent object for this object. An object has always a parent which contains it; only the game objects have no parent. |
Example:
print( getObject("Actions[test]"):getParent() ) -- print the parent object that the "test" action belongs to.
getPath
Returns the path to the media file. This could be an image, an animation, an audio file, or a video file, etc...
getPath(number)
Arguments | Description |
---|---|
number | The field which specifies a path value. The field type must be t_path. |
Return Values | Description |
"string" | The path will be returned in unix format ('/' for directories) and relative to the .ved file. |
getPaths
Returns a table containing multiple paths to media files. These could be images, animations, audio files, or video files, etc...
getPaths(number)
Arguments | Description |
---|---|
number | The field which specifies a path list. The field type must be t_vpath. |
Return Values | Description |
table | A table containing multiple paths. The paths will be returned in unix format ('/' for directories) and relative to the .ved file. |
getPoint
Returns a table containing x & y coordinate values.
getPoint(number)
Arguments | Description |
---|---|
number | The field which specifies a point value. The field type must be t_point. |
Return Values | Description |
table | A table containing x & y coordinate values. |
Example:
animPos = getObject("ActiveAnimations[test]"):getPoint(VAnimationCurrentPosition) -- store current coordinate values into a variable
print(animPos.x, animPos.y) -- print the x & y values to the log.
getPoints
Lua Syntax:
getPoints(number)
- Arguments
- number
The field which specifies a point list. The field type must be t_vpoint.
- Return Values
- table
Table with t_point entries representing the specified field.
getPosition
Lua Syntax:
getPosition()
- Arguments
- none
The field which specifies a sprites position (x & y). The field type must be t_sprite.
- Return Values
- table
Table with t_sprite entries representing the specified field.
local obj = Objects["bottle"].ObjectSprite.SpriteSprite:getPosition()
print(obj.x, obj.y)
getRect
Lua Syntax:
getRect(number)
- Arguments
- number
The field which specifies a rectangle value. The field type must be t_rect.
- Return Values
- table
A table representing the value of the specified field. The table contains the entries x, y, width and height.
getRects
Lua Syntax:
getRects(number)
- Arguments
- number
The field which specifies a rectangle list. The field type must be t_vrect.
- Return Values
- table (list of table with x, y, width and height entries)
Table with t_rect entries representing the specified field.
getSize
Lua Syntax:
getSize()
- Arguments
- none
The field which specifies a sprites size (width & height). The field type must be t_sprite.
- Return Values
- table
Table with t_sprite entries representing the specified field.
local obj = Objects["bottle"].ObjectSprite.SpriteSprite:getSize()
print(obj.x, obj.y)
getSprite
Lua Syntax:
getSprite(number)
- Arguments
- number
The field which specifies a sprite value. The field type must be t_sprite.
- Return Values
- table
See t_sprite field type.
getSprites
Lua Syntax:
getSprites(number)
- Arguments
- number
The field which specifies a sprite list. The field type must be t_vsprite.
- Return Values
- table
Table with t_sprite entries representing the specified field.
getStr
Lua Syntax:
getStr(number)
- Arguments
- number
The field which specifies a string value. The field type must be t_string.
- Return Values
- string
Current value of specified field.
Example:
local str = getObject("Values[test]"):getStr(VValueString)
print(str)
getTexts
Lua Syntax:
getTexts(number)
- Arguments
- number
The field which specifies a text languages value. The field type must be t_vtext.
- Return Values
- table
Table with t_text entries representing the specified field.
getTextStr
Lua Syntax:
getTextStr(number, <languageId>)
- Arguments
- number
The field which specifies a text languages value. The field type must be t_link to Text.
- languageId (optional)
The text will be returned for the language with this id. If parameter is missing then the text will be returned in the currently active language.
- Return Values
- string
Text string in given language.
- Example:
local button = getObject("Buttons[Talk]")
local langEn = getObject("Languages[English]")
local langDe = getObject("Languages[German]")
-- print name of talk command in current language
print(button:getTextStr(VButtonName))
-- print English name of talk command
print(button:getTextStr(VButtonName, langEn:getId().id))
-- print German name of talk command
print(button:getTextStr(VButtonName, langDe:getId().id))
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.
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.
setName
Sets the internal name of the visionaire object.
Lua Syntax:
setName(string)
- Arguments
- string
The new internal name.
setValue
Sets a field of the visionaire object. Note that only fields which are marked as 'Scriptable' in the Visionaire Data Structure documentation should be modified. If the field is not marked as scriptable then changes to this field are often not recognized (or sometimes not immediately). Further changes to these fields will usually not be stored in savegames for performance reasons.
Lua Syntax:
setValue(number, VARIANT, {flags=1, index = number})
- Arguments
- number
Data field which will be set.
- VARIANT
Value to set. The type of the value must match the type of the field. E.g. if the field type is t_int then the value type must be a number (int). If the field type is t_rect then the value type must be a table with the entries "x", "y", "width" and "height".
- Flags
- index
If specified then an existing list element at the given index will be modified. In this case the field type must be of a list-type (t_vint, t_links, ...).
Examples:
-- set character "Tom" to position x(100), y(300)
local tom = getObject("Characters[Tom]")
tom:setValue(VCharacterPosition, {x=100,y=300})
-- set condition "TV is on" to true
local cond = getObject("Conditions[TV is on]")
cond:setValue(VConditionValue, true)
-- let the "dog" follow the current character
local dog = getObject("Characters[dog]")
local currentCharacter = getObject("Game.GameCurrentCharacter")
dog:setValue(VCharacterFollowCharacter, currentCharacter)
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).
Editor Functions / Commands
Player Functions / Commands
Contents
- 1 Visionaire Object Model
- 2 Exported objects
- 3 Exported constants
- 4 VisionaireObject
- 4.1 clearLink
- 4.2 getBool
- 4.3 getFloat
- 4.4 getFloats
- 4.5 getId
- 4.6 getInt
- 4.7 getInts
- 4.8 getLink
- 4.9 getLinks
- 4.10 getName
- 4.11 getObject
- 4.12 getParent
- 4.13 getPath
- 4.14 getPaths
- 4.15 getPoint
- 4.16 getPoints
- 4.17 getPosition
- 4.18 getRect
- 4.19 getRects
- 4.20 getSize
- 4.21 getSprite
- 4.22 getSprites
- 4.23 getStr
- 4.24 getTexts
- 4.25 getTextStr
- 4.26 isAnyObject
- 4.27 isEmpty
- 4.28 setName
- 4.29 setValue
- 5 Accessing an object
- 6 Editor Functions / Commands
- 7 Player Functions / Commands