Difference between revisions of "Scripting"

From The Official Visionaire Studio: Adventure Game Engine Wiki
m (getBool)
(36 intermediate revisions by the same user not shown)
Line 1: Line 1:
== General ==
+
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 accessed / manipulated through the scripting language.
Visionaire Studio 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|data structure]] in a convenient way. Almost every instance in Visionaire is represented as an object (e.g. scene, character, interface, ...) which can be manipulated through the scripting language.<br>
+
----
 
+
Online documentation about the Lua scripting Language:
Online documentation about 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
 
* AFRLme's Guide to Lua Script: [[Basic_lua:_Index|Basic Lua]]
 
* AFRLme's Guide to Lua Script: [[Basic_lua:_Index|Basic Lua]]
 +
* Simon's [http://www.visionaire-studio.com/luadocs/ Luadocs]
 +
  
 
== Visionaire Object Model ==
 
== 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|data structure]] page.
 
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|data structure]] page.
  
Line 15: Line 15:
 
{| class="ts"
 
{| class="ts"
 
|-
 
|-
! style="text-align:left" | Field Type  
+
! style="text-align:left" | Field Type !! style="text-align:left;width:80%" | Description
! style="text-align:left;width:80%" | Description
 
|-
 
 
|-
 
|-
| valign="top" |
+
| t_link  
t_link
+
| userdata ([[#VisionaireObject|VisionaireObject]]) or string which describes the object path. See [[#Accessing_an_object|object access]] for description of the object path.
| valign="top" |
 
userdata ([[#VisionaireObject|VisionaireObject]]) or string which describes the object path. See [[#Accessing_an_object|object access]] for description of the object path.
 
 
|-
 
|-
| valign="top" |
+
| t_links
t_links
+
| table (array) with Visionaire Objects (userdata or string, see t_link above) entries, each entry referencing one Visionaire Object.
| valign="top" |
 
table (array) with Visionaire Objects (userdata or string, see t_link above) entries, each entry referencing one Visionaire Object.
 
 
|-
 
|-
| valign="top" |
+
| t_int
t_int
+
| number (integer)
| valign="top" |
 
number (integer)
 
 
|-
 
|-
| valign="top" |
+
| t_float
t_float
+
| number (decimal)
| valign="top" |
 
number
 
 
|-
 
|-
| valign="top" |
+
| t_bool
t_bool
+
| boolean (<span class="green">true</span> ''or'' <span class="red">false</span>)
| valign="top" |
 
boolean
 
 
|-
 
|-
| valign="top" |
+
| t_point
t_point
+
| table (with entries "x" and "y")
| valign="top" |
 
table (with entries "x" and "y")
 
 
|-
 
|-
| valign="top" |
+
| t_rect
t_rect
+
| table (with entries "x", "y", "width" and "height")
| valign="top" |
 
table (with entries "x", "y", "width" and "height")
 
 
|-
 
|-
| valign="top" |
+
| t_string
t_string
+
| "string"
| valign="top" |
 
string
 
 
|-
 
|-
| valign="top" |
+
| t_text
t_text
+
| table with entries "text", "sound" (relative path to sound file for speech output) and "language" (language id).
| valign="top" |
 
table with entries "text", "sound" (relative path to sound file for speech output) and "language" (language id).
 
 
|-
 
|-
| valign="top" |
+
| t_path
t_path
+
| "string"
| valign="top" |
 
string
 
 
|-
 
|-
| valign="top" |
+
| t_sprite
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).
| valign="top" |
 
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).
 
 
|-
 
|-
| valign="top" |
+
| t_vint
t_vint
+
| table with number (integer) entries
| valign="top" |
 
table with number (integer) entries
 
 
|-
 
|-
| valign="top" |
+
| t_vfloat
t_vfloat
+
| table with number (float) entries
| valign="top" |
 
table with number (float) entries
 
 
|-
 
|-
| valign="top" |
+
| t_vpoint
t_vpoint
+
| table with t_point entries
| valign="top" |
 
table with t_point entries
 
 
|-
 
|-
| valign="top" |
+
| t_vrect
t_vrect
+
| table with t_rect entries
| valign="top" |
 
table with t_rect entries
 
 
|-
 
|-
| valign="top" |
+
| t_vstring
t_vstring
+
| table with string entries
| valign="top" |
 
table with string entries
 
 
|-
 
|-
| valign="top" |
+
| t_vtext
t_vtext
+
| table with t_text entries
| valign="top" |
 
table with t_text entries
 
 
|-
 
|-
| valign="top" |
+
| t_vpath
t_vpath
+
| table with t_path entries
| valign="top" |
 
table with t_path entries
 
 
|-
 
|-
| valign="top" |
+
| t_vsprite
t_vsprite
+
| table with t_sprite entries
| valign="top" |
 
table with t_sprite entries
 
 
|}
 
|}
  
 
== Exported objects ==
 
== Exported objects ==
 
 
The following objects are exported to the Lua scripting environment:
 
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.
 
* currentAction: a visionaire object which represents the action where the current script was called from.
 
* emptyObject: an empty visionaire object.
 
* emptyObject: an empty visionaire object.
 
* game: the game object. This is the same as calling getObject("Game") but faster and easier to use.
 
* game: the game object. This is the same as calling getObject("Game") but faster and easier to use.
 +
  
 
== Exported constants ==
 
== 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 [[Data_Structure|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.
  
The following contants 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 [[Data Structure|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 savegames (in the sub directory savegames), 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 ==
 
== VisionaireObject ==
 +
Every instance of an object of the visionaire [[Data_Structure|data structure]] is a VisionaireObject. With this object it is possible to read and manipulate the attributes of all objects.
  
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):
 
The following methods are supported on a VisionaireObject (in alphabetical order):
 +
  
 
=== clearLink ===
 
=== clearLink ===
 +
Removes a link from the visionaire object. A more convenient alternative to the emptyObject method (''see examples below'').
 +
<syntaxhighlight>clearLink(number)</syntaxhighlight>
  
Removes a link from the visionaire object. This is only a convenient method and has the same effect as calling setValue with emptyObject as value.
 
 
Lua Syntax:
 
<syntaxhighlight>clearLink(number)</syntaxhighlight>
 
*Arguments
 
;number
 
The field which specifies a link to be cleared. The field type must be t_link.
 
  
=== getBool ===
+
==== Arguments ====
 
{| class="ts"
 
{| class="ts"
 
|-
 
|-
! Syntax !! Description
+
| style="width: 10%;" | number || The field which specifies a link to be cleared. The field type must be t_link.
|-
 
| getBool(number) || Returns a boolean value of <span class="green">true</span> ''or'' <span class="red">false</span>.
 
 
|}
 
|}
 +
 +
==== Example(s) ====
 +
<syntaxhighlight>
 +
game:clearLink(VGameSpeechLanguage)
 +
</syntaxhighlight>
 +
''versus...''
 +
<syntaxhighlight>
 +
game:setValue(VGameSpeechLanguage, emptyObject)
 +
</syntaxhighlight>
  
  
 +
=== getBool ===
 +
Returns a boolean value of <span class="green">true</span> ''or'' <span class="red">false</span>.
 +
<syntaxhighlight>
 +
getBool(number)
 +
</syntaxhighlight>
 +
 +
 +
==== Arguments ====
 
{| class="ts"
 
{| class="ts"
 
|-
 
|-
! Arguments !! Description
+
| style="width: 10%;" | number || The field which specifies a boolean value. The field type must be t_bool.
|-
+
|}
| number || The field which specifies a boolean value. The field type must be t_bool.
+
==== Return Values ====
|-
+
{| class="ts"
! Return Values || Description
 
 
|-
 
|-
| boolean || Current value of the specified field. Will return <span class="green">true</span> ''or'' <span class="red">false</span>.
+
| style="width: 10%;" | boolean || Current value of the specified field. Will return <span class="green">true</span> ''or'' <span class="red">false</span>.
 
|}
 
|}
  
 +
==== Example(s) ====
 +
<syntaxhighlight>
 +
print( game:getBool(VGameAlwaysAllowSkipText) ) -- print current boolean value of VGameAlwaysAllowSkipText to the log
 +
game:setValue(VGameAlwaysAllowSkipText, true) -- set VGameAlwaysAllowSkipText to true
 +
</syntaxhighlight>
  
Example:
 
<syntaxhighlight>local allowSkipText = game:getBool(VGameAlwaysAllowSkipText)</syntaxhighlight>
 
  
 
=== getFloat ===
 
=== getFloat ===
 +
Returns a float (decimal) value.
 +
<syntaxhighlight>getFloat(number)</syntaxhighlight>
  
Lua Syntax:
 
<syntaxhighlight>getFloat(number)</syntaxhighlight>
 
*Arguments
 
;number
 
The field which specifies a number value. The field type must be t_float.
 
*Return Values
 
;number
 
Current value of specified field.
 
  
Example:
+
==== Arguments ====
 +
{| class="ts"
 +
|-
 +
| style="width: 10%;" | number || The field which specifies a number value. The field type must be t_float.
 +
|}
 +
==== Return Values ====
 +
{| class="ts"
 +
|-
 +
| style="width: 10%;" | float || A decimal value. For example: 3.141
 +
|}
 +
 
 +
==== Example(s) ====
 
<syntaxhighlight>
 
<syntaxhighlight>
 
getObject("Game.GameCurrentCharacter"):getFloat(VCharacterSize)
 
getObject("Game.GameCurrentCharacter"):getFloat(VCharacterSize)
 
</syntaxhighlight>
 
</syntaxhighlight>
 +
  
 
=== getFloats ===
 
=== getFloats ===
 +
Returns a table containing multiple float (decimal) values. ''Iteration is required.''
 +
<syntaxhighlight>getFloats(number)</syntaxhighlight>
 +
  
Lua Syntax:
+
==== Arguments ====
<syntaxhighlight>getFloats(number)</syntaxhighlight>
+
{| class="ts"
*Arguments
+
|-
;number
+
| style="width: 10%;" | number || The field which specifies a number list. The field type must be t_vfloat.
The field which specifies a number list. The field type must be t_vfloat.
+
|}
*Return Values
+
==== Return Values ====
;table
+
{| class="ts"
Table with t_float entries representing the specified field.
+
|-
 +
| style="width: 10%;" | table || A table containing multiple float (decimal) values.
 +
|}
  
 
=== getId ===
 
=== getId ===
 +
Returns the ID of the specified table or object.
 +
<syntaxhighlight>getId()</syntaxhighlight>
 +
  
Lua Syntax:
+
==== Return Values ====
<syntaxhighlight>getId()</syntaxhighlight>
+
{| class="ts"
* Return Values
+
|-
;table
+
| style="width: 10%;" | table || A table with the fields '''tableId''' and '''id''' returning the table id and object id of the VisionaireObject.
A table with the fields '''tableId''' and '''id''' returning the table id and object id of the VisionaireObject.
+
|}
  
Example:
+
==== Example(s) ====
 
<syntaxhighlight>
 
<syntaxhighlight>
 
function checkAnimOwner(n)
 
function checkAnimOwner(n)
Line 219: Line 206:
 
checkAnimOwner("pick_up") -- check if "pick_up" animation belongs to a character or not.
 
checkAnimOwner("pick_up") -- check if "pick_up" animation belongs to a character or not.
 
</syntaxhighlight>
 
</syntaxhighlight>
 +
  
 
=== getInt ===
 
=== getInt ===
 +
Returns an integer (number) value.
 +
<syntaxhighlight>getInt(number)</syntaxhighlight>
 +
 +
 +
==== Arguments ====
 +
{| class="ts"
 +
|-
 +
| style="width: 10%;" | number || The field which specifies a number value. The field type must be t_int.
 +
|}
 +
==== Return Values ====
 +
{| class="ts"
 +
|-
 +
| style="width: 10%;" | integer || An integer (number) value.
 +
|}
  
Lua Syntax:
+
==== Example(s) ====
<syntaxhighlight>getInt(number)</syntaxhighlight>
+
<syntaxhighlight>
*Arguments
+
local direction = getObject("Characters[Tom]"):getInt(VCharacterDirection)
;number
+
</syntaxhighlight>
The field which specifies a number value. The field type must be t_int.
 
*Return Values
 
;number
 
Current value of specified field.
 
  
Example:
 
<syntaxhighlight>local direction = getObject("Characters[Mother]"):getInt(VCharacterDirection)</syntaxhighlight>
 
  
 
=== getInts ===
 
=== getInts ===
 +
Returns a table containing multiple integer (number) values. ''Iteration is required.''
 +
<syntaxhighlight>getInts(number)</syntaxhighlight>
  
Lua Syntax:
+
 
<syntaxhighlight>getInts(number)</syntaxhighlight>
+
==== Arguments ====
*Arguments
+
{| class="ts"
;number
+
|-
The field which specifies a number list. The field type must be t_vint.
+
| style="width: 10%;" | number || The field which specifies a number list. The field type must be t_vint.
*Return Values
+
|}
;table
+
 
Table with t_int entries representing the specified field.
+
==== Return Values ====
 +
{| class="ts"
 +
|-
 +
| style="width: 10%;" | table || A table containing multiple integer (number) values.
 +
|}
  
 
=== getLink ===
 
=== getLink ===
 +
Returns a VisionaireObject.
 +
<syntaxhighlight>getLink(number)</syntaxhighlight>
 +
 +
 +
==== Arguments ====
 +
{| class="ts"
 +
|-
 +
| style="width: 10%;" | number || The field which specifies a link. The field type must be t_link.
 +
|}
 +
==== Return Values ====
 +
{| class="ts"
 +
|-
 +
| style="width: 10%;" | userdata || A VisionaireObject; ''or an empty object if no object is linked for this field.''
 +
|}
 +
 +
==== Example(s) ====
 +
<syntaxhighlight>
 +
game:getLink(VGameCurrentCharacter)
 +
</syntaxhighlight>
  
Lua Syntax:
 
<syntaxhighlight>getLink(number)</syntaxhighlight>
 
*Arguments
 
;number
 
The field which specifies a link. The field type must be t_link.
 
*Return Values
 
;userdata (VisionaireObject)
 
The linked object or an empty object if no object is linked for this field.
 
  
 
=== getLinks ===
 
=== getLinks ===
 +
Returns a table containing multiple VisionaireObjects.
 +
<syntaxhighlight>getLinks(number)</syntaxhighlight>
 +
 +
 +
==== Arguments ====
 +
{| class="ts"
 +
|-
 +
| style="width: 10%;" | number || The field which specifies a link list. The field type must be t_links.
 +
|}
 +
==== Return Values ====
 +
{| class="ts"
 +
|-
 +
| style="width: 10%;" | table || Table containing multiple VisionaireObjects (links).
 +
|}
 +
 +
==== Example(s) ====
 +
<syntaxhighlight>
 +
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.
 +
</syntaxhighlight>
  
Lua Syntax:
 
<syntaxhighlight>getLinks(number)</syntaxhighlight>
 
*Arguments
 
;number
 
The field which specifies a link list. The field type must be t_links.
 
*Return Values
 
;table (list of VisionaireObject)
 
Table containing all linked visionaire objects.
 
  
 
=== getName ===
 
=== getName ===
 +
Returns the name of a VisionaireObject. ''This should not be confused with the names included in the properties tab of an object.''
 +
<syntaxhighlight>getName()</syntaxhighlight>
 +
 +
 +
==== Return Values ====
 +
{| class="ts"
 +
|-
 +
| style="width: 10%;" | "string" || The internal name of the visionaire object (editor). This is the name which is used to access the object.
 +
|}
 +
 +
==== Example(s) ====
 +
<syntaxhighlight>
 +
game:getLink(VGameCurrentScene):getName() -- this would return the "string" name of the current scene.
 +
</syntaxhighlight>
  
Lua Syntax:
 
<syntaxhighlight>getName()</syntaxhighlight>
 
* Return Values
 
;string
 
The internal name of the visionaire object. This is the name which is used to access the object and also shown in the editor. This name is not shown to the user in the game - therefor always a language dependent text is used.
 
  
 
=== getObject ===
 
=== getObject ===
 +
This is the most common method for accessing all the various fields & tables of the visionaire [[Data_Structure|data structure]].
 +
<syntaxhighlight>getObject("string")</syntaxhighlight>
  
Lua Syntax:
+
 
<syntaxhighlight>getObject(string)</syntaxhighlight>
+
==== Arguments ====
* Arguments
+
{| class="ts"
;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 [[Scripting#Accessing_an_object|object access]] for description of the object path.
+
| style="width: 10%;" | "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 [[Scripting#Accessing_an_object|object access]] for description of the object path.
* Return Values
+
|}
;userdata (VisionaireObject)
+
==== Return Values ====
The found visionaire object or an empty object if no object was found.
+
{| class="ts"
Example:
+
|-
 +
| style="width: 10%;" | userdata || A VisionaireObject; ''or an empty object if the return value is nil.''
 +
|}
 +
 
 +
==== Example(s) ====
 
<syntaxhighlight>
 
<syntaxhighlight>
 
local scene = getObject("Scenes[Bedroom]")
 
local scene = getObject("Scenes[Bedroom]")
 
local deskCond = scene:getObject(".SceneObjects[Desk].ObjectCondition")
 
local deskCond = scene:getObject(".SceneObjects[Desk].ObjectCondition")
 
</syntaxhighlight>
 
</syntaxhighlight>
 +
  
 
=== getParent ===
 
=== getParent ===
 +
Returns the parent object of the specified VisionaireObject.
 +
<syntaxhighlight>getParent()</syntaxhighlight>
 +
 +
 +
==== Return Values ====
 +
{| class="ts"
 +
|-
 +
| style="width: 10%;" | userdata || The parent object for the specified VisionaireObject. An object has always a parent which contains it; ''only the '''game''' objects have no parent.''
 +
|}
 +
 +
==== Example(s) ====
 +
<syntaxhighlight>
 +
print( getObject("Actions[test]"):getParent() ) -- print the parent object that the "test" action belongs to.
 +
</syntaxhighlight>
  
Lua Syntax:
 
<syntaxhighlight>getParent()</syntaxhighlight>
 
* 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.
 
  
 
=== getPath ===
 
=== getPath ===
 +
Returns the path to the media file. This could be an image, an animation, an audio file, or a video file, etc...
 +
<syntaxhighlight>getPath(number)</syntaxhighlight>
 +
  
Lua Syntax:
+
==== Arguments ====
<syntaxhighlight>getPath(number)</syntaxhighlight>
+
{| class="ts"
*Arguments
+
|-
;number
+
| style="width: 10%;" | number || The field which specifies a path value. The field type must be t_path.
The field which specifies a path value. The field type must be t_path.
+
|}
*Return Values
+
==== Return Values ====
;string
+
{| class="ts"
Current value of specified field. The path will be returned in unix format ('/' for directories) and relative to the .ved file.
+
|-
 +
| style="width: 10%;" | "string" || The path will be returned in unix format ('/' for directories) and relative to the .ved file.
 +
|}
  
 
=== getPaths ===
 
=== getPaths ===
 +
Returns a table containing multiple paths to media files. These could be images, animations, audio files, or video files, etc...
 +
<syntaxhighlight>getPaths(number)</syntaxhighlight>
  
Lua Syntax:
+
 
<syntaxhighlight>getPaths(number)</syntaxhighlight>
+
==== Arguments ====
*Arguments
+
{| class="ts"
;number
+
|-
The field which specifies a path list. The field type must be t_vpath.
+
| style="width: 10%;" | number || The field which specifies a path list. The field type must be t_vpath.
*Return Values
+
|}
;table
+
==== Return Values ====
Table with t_path entries representing the specified field.
+
{| class="ts"
 +
|-
 +
| style="width: 10%;" | table || A table containing multiple paths. The paths will be returned in unix format ('/' for directories) and relative to the .ved file.
 +
|}
  
 
=== getPoint ===
 
=== getPoint ===
 +
Returns a table containing '''x''' & '''y''' coordinate values.
 +
<syntaxhighlight>getPoint(number)</syntaxhighlight>
  
Lua Syntax:
 
<syntaxhighlight>getPoint(number)</syntaxhighlight>
 
*Arguments
 
;number
 
The field which specifies a point value. The field type must be t_point.
 
*Return Values
 
;table
 
A table representing the value of the specified field. The table contains the entries '''x''' and '''y'''.
 
  
Example:
+
==== Arguments ====
 +
{| class="ts"
 +
|-
 +
| style="width: 10%;" | number || The field which specifies a point value. The field type must be t_point.
 +
|}
 +
==== Return Values ====
 +
{| class="ts"
 +
|-
 +
| style="width: 10%;" | table || A table containing '''x''' & '''y''' coordinate values.
 +
|}
 +
 
 +
==== Example(s) ====
 
<syntaxhighlight>
 
<syntaxhighlight>
-- let's get the x, y position of an animation ...
+
animPos = getObject("ActiveAnimations[test]"):getPoint(VAnimationCurrentPosition) -- store current coordinate values into a variable.
animPos = getObject("ActiveAnimations[anim_name]"):getPoint(VAnimationCurrentPosition)
+
print(animPos.x, animPos.y) -- print the x & y values to the log.
 +
</syntaxhighlight>
  
-- let's print it to the log file!
 
print("current position of x=" .. animPos.x)
 
print("current position of y=" .. animPos.y)
 
</syntaxhighlight>
 
  
 
=== getPoints ===
 
=== getPoints ===
 +
Returns multiple tables containing '''x''' & '''y''' coordinate values.
 +
<syntaxhighlight>getPoints(number)</syntaxhighlight>
 +
  
Lua Syntax:
+
==== Arguments ====
<syntaxhighlight>getPoints(number)</syntaxhighlight><br/>
+
{| class="ts"
*Arguments
+
|-
;number
+
| style="width: 10%;" | number || The field which specifies a point list. The field type must be t_vpoint.
The field which specifies a point list. The field type must be t_vpoint.
+
|}
*Return Values
+
==== Return Values ====
;table
+
{| class="ts"
Table with t_point entries representing the specified field.
+
|-
 +
| style="width: 10%;" | table || Multiple tables containing '''x''' & '''y''' coordinate values.
 +
|}
  
 
=== getPosition ===
 
=== getPosition ===
 +
Returns a table containing the current '''x''' & '''y''' coordinates of the specified sprite.
 +
<syntaxhighlight>getPosition()</syntaxhighlight>
  
Lua Syntax:
+
 
<syntaxhighlight>getPosition()</syntaxhighlight><br/>
+
==== Arguments ====
*Arguments
+
{| class="ts"
;none
+
|-
The field which specifies a sprites position (x & y). The field type must be t_sprite.
+
| style="width: 10%;" | number || The field which specifies a sprites position (x & y). The field type must be t_sprite.
*Return Values
+
|}
;table
+
==== Return Values ====
Table with t_sprite entries representing the specified field.
+
{| class="ts"
 +
|-
 +
| style="width: 10%;" | table || A table containing the current '''x''' & '''y''' coordinate values of the specified sprite.
 +
|}
  
 
<syntaxhighlight>
 
<syntaxhighlight>
local obj = Objects["bottle"].ObjectSprite.SpriteSprite:getPosition()
+
local obj = Objects["bottle"].ObjectSprite.SpriteSprite:getPosition() -- store position into a variable.
print(obj.x, obj.y)
+
print(obj.x, obj.y) -- print the x, y coordinates of said object sprite to the log.
 
</syntaxhighlight>
 
</syntaxhighlight>
 +
  
 
=== getRect ===
 
=== getRect ===
 +
Returns a table (rectangle) consisting of '''x''', '''y''', '''width''' & '''height'''. ''A rectangle is essentially a specified area in which something will be placed, such as: the dialog interface, or action text, etc.''
 +
<syntaxhighlight>getRect(number)</syntaxhighlight>
 +
 +
 +
==== Arguments ====
 +
{| class="ts"
 +
|-
 +
| style="width: 10%;" | number || The field which specifies a rectangle value. The field type must be t_rect.
 +
|}
 +
==== Return Values ====
 +
{| class="ts"
 +
|-
 +
| style="width: 10%;" | table || A table containing the entries '''x''', '''y''', '''width''' & '''height'''.
 +
|}
 +
 +
==== Example(s) ====
 +
<syntaxhighlight>
 +
-- let's say I have a scene that is 1280x720px & I want to limit the playable area to specific portion of the scene...
 +
getObject("Scenes[bedroom]"):setValue( VSceneScrollableArea, { x = 320, y = 180, width = 640, height = 360 } ) -- 50% of scene size from center of scene.
 +
 +
-- math: x = width ÷ 4, y = height ÷ 4, width = width ÷ 2, height = height ÷ 2
 +
</syntaxhighlight>
  
Lua Syntax:
 
<syntaxhighlight>getRect(number)</syntaxhighlight>
 
*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 ===
 
=== getRects ===
 +
Returns multiple tables (rectangles) containing '''x''', '''y''', '''width''' & '''height''' values. ''A rectangle is essentially a specified area in which something will be placed, such as: the dialog interface, or action text, etc.''
 +
<syntaxhighlight>getRects(number)</syntaxhighlight>
  
Lua Syntax:
+
 
<syntaxhighlight>getRects(number)</syntaxhighlight>
+
==== Arguments ====
*Arguments
+
{| class="ts"
;number
+
|-
The field which specifies a rectangle list. The field type must be t_vrect.
+
| style="width: 10%;" | 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)
+
==== Return Values ====
Table with t_rect entries representing the specified field.
+
{| class="ts"
 +
|-
 +
| style="width: 10%;" | table || Multiple tables containing '''x''', '''y''', '''width''' & '''height'''.
 +
|}
  
 
=== getSize ===
 
=== getSize ===
 +
Returns a table containing the width ('''x''') & height ('''y''') of the specified object sprite.
 +
<syntaxhighlight>getSize()</syntaxhighlight>
 +
  
Lua Syntax:
+
==== Arguments ====
<syntaxhighlight>getSize()</syntaxhighlight><br/>
+
{| class="ts"
*Arguments
+
|-
;none
+
| style="width: 10%;" | number || The field which specifies a sprites size (width & height). The field type must be t_sprite.
The field which specifies a sprites size (width & height). The field type must be t_sprite.
+
|}
*Return Values
+
==== Return Values ====
;table
+
{| class="ts"
Table with t_sprite entries representing the specified field.
+
|-
 +
| style="width: 10%;" | table || A table containing the width ('''x''') & height ('''y''') entries of the specified object sprite.
 +
|}
  
 
<syntaxhighlight>
 
<syntaxhighlight>
local obj = Objects["bottle"].ObjectSprite.SpriteSprite:getSize()
+
local obj = Objects["bottle"].ObjectSprite.SpriteSprite:getSize() -- store size of object sprite into a variable.
print(obj.x, obj.y)
+
print(obj.x, obj.y) -- print width & height of said object sprite to the log.
 
</syntaxhighlight>
 
</syntaxhighlight>
 +
  
 
=== getSprite ===
 
=== getSprite ===
 +
Returns a sprite. ''A sprite is an image; in other words this could consist of a static image or the current frame of an animation.''
 +
<syntaxhighlight>getSprite(number)</syntaxhighlight>
 +
 +
 +
==== Arguments ====
 +
{| class="ts"
 +
|-
 +
| style="width: 10%;" | number || The field which specifies a sprite value. The field type must be t_sprite.
 +
|}
 +
==== Return Values ====
 +
{| class="ts"
 +
|-
 +
| style="width: 10%;" | table || A table containing the 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 ms, in case sprite is used in an animation).
 +
|}
 +
 +
==== Example(s) ====
 +
<syntaxhighlight>
 +
getObject("Objects[bottle]"):getLink(VObjectSprite):getSprite(VSpriteSprite)
 +
</syntaxhighlight>
  
Lua Syntax:
 
<syntaxhighlight>getSprite(number)</syntaxhighlight>
 
*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 ===
 
=== getSprites ===
 +
Returns a table containing multiple sprites. ''A sprite is an image; in other words this could consist of a static image or the current frame of an animation.''
 +
<syntaxhighlight>getSprites(number)</syntaxhighlight>
  
Lua Syntax:
+
 
<syntaxhighlight>getSprites(number)</syntaxhighlight>
+
==== Arguments ====
*Arguments
+
{| class="ts"
;number
+
|-
The field which specifies a sprite list. The field type must be t_vsprite.
+
| style="width: 10%;" | number || The field which specifies a sprite list. The field type must be t_vsprite.
*Return Values
+
|}
;table
+
==== Return Values ====
Table with t_sprite entries representing the specified field.
+
{| class="ts"
 +
|-
 +
| style="width: 10%;" | table || Multiple tables containing the 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 ms, in case sprite is used in an animation).  
 +
|}
  
 
=== getStr ===
 
=== getStr ===
 +
Returns a "string" value. ''A "string" can consist of a mixture of plain text, numbers & symbols.''
 +
<syntaxhighlight>getStr(number)</syntaxhighlight>
 +
  
Lua Syntax:
+
==== Arguments ====
<syntaxhighlight>getStr(number)</syntaxhighlight>
+
{| class="ts"
*Arguments
+
|-
;number
+
| style="width: 10%;" | number || The field which specifies a string value. The field type must be t_string.
The field which specifies a string value. The field type must be t_string.
+
|}
*Return Values
+
==== Return Values ====
;string
+
{| class="ts"
Current value of specified field.
+
|-
 +
| style="width: 10%;" | "string" || A "string" value consisting of a mixture of text, numbers & symbols.
 +
|}
  
Example:
+
==== Example(s) ====
 
<syntaxhighlight>
 
<syntaxhighlight>
local str = getObject("Values[test]"):getStr(VValueString)
+
local str = getObject("Values[test]"):getStr(VValueString) -- store string value of "test" into a variable.
print(str)
+
print(str) -- print said "string" to the log file.
 
</syntaxhighlight>
 
</syntaxhighlight>
 +
  
 
=== getTexts ===
 
=== getTexts ===
 +
Returns a table containing multiple text (name) language values.
 +
<syntaxhighlight>getTexts(number)</syntaxhighlight>
 +
 +
 +
==== Arguments ====
 +
{| class="ts"
 +
|-
 +
| style="width: 10%;" | number || The field which specifies a text languages value. The field type must be t_vtext.
 +
|}
 +
==== Return Values ====
 +
{| class="ts"
 +
|-
 +
| style="width: 10%;" | table || A table containing multiple text (name) language entries for the specified VisionaireObject.
 +
|}
 +
 +
==== Example(s) ====
 +
''iterate through texts belonging to a specified object (shorthand).''
 +
<syntaxhighlight>
 +
local txt = Objects["test"].ObjectName.TextTextLanguages
 +
 +
for i = 1, #txt do
 +
if txt[i].language == Languages["English"]:getId().id then
 +
  print( txt[i].text )
 +
end
 +
end
 +
</syntaxhighlight>
 +
''same as above, but using the getObject method (longhand).''
 +
<syntaxhighlight>
 +
local txt = getObject("Objects[test].ObjectName"):getTexts(VTextTextLanguages)
 +
 +
for i = 1, #txt do
 +
if txt[i].language == getObject("Languages[English]"):getId().id then
 +
  print( txt[i].text )
 +
end
 +
end
 +
</syntaxhighlight>
  
Lua Syntax:
 
<syntaxhighlight>getTexts(number)</syntaxhighlight>
 
*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 ===
 
=== getTextStr ===
 +
Returns the text belonging to the specified object; ''based on specified language.''
 +
<syntaxhighlight>getTextStr(number, <languageId>)</syntaxhighlight>
 +
 +
 +
 +
==== Arguments ====
 +
{| class="ts"
 +
|-
 +
| style="width: 10%;" | number || The field which specifies a text languages value. The field type must be t_link to Text.
 +
|-
 +
| style="width: 10%;" | languageId || 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 ====
 +
{| class="ts"
 +
|-
 +
| style="width: 10%;" | "string" || The "string" value of the specified text of a VisionaireObject belonging to the given languageId.
 +
|}
  
Lua Syntax:
+
==== Example(s) ====
<syntaxhighlight>getTextStr(number, <languageId>)</syntaxhighlight>
+
''get the text belonging to the currently active language for the specified object.''
*Arguments
+
<syntaxhighlight>
;number
+
getObject("Buttons[talk]"):getTextStr(VButtonName)
The field which specifies a text languages value. The field type must be t_link to Text.
+
</syntaxhighlight>
;languageId (optional)
+
''get the text belong to the given language for the the specified object.''
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:
 
 
<syntaxhighlight>
 
<syntaxhighlight>
local button = getObject("Buttons[Talk]")
+
getObject("Buttons[talk]"):getTextStr( VButtonName, getObject("Languages[English]"):getId().id ) -- get text belong to "English" language.
local langEn = getObject("Languages[English]")
+
getObject("Buttons[talk]"):getTextStr( VButtonName, getObject("Languages[German]"):getId().id ) -- get text belong to "German" language.
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))
 
 
</syntaxhighlight>
 
</syntaxhighlight>
 +
  
 
=== isAnyObject ===
 
=== isAnyObject ===
 
+
Returns a boolean value of <span class="green">true</span> ''or'' <span class="red">false</span>,  depending on whether or not VisionaireObject is returned???? (not actually sure about this one - never used it before).
 
Lua Syntax:
 
Lua Syntax:
 
<syntaxhighlight>isAnyObject()</syntaxhighlight>
 
<syntaxhighlight>isAnyObject()</syntaxhighlight>
Line 489: Line 650:
 
;boolean
 
;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.
 
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 ===
 
=== isEmpty ===
Line 497: Line 659:
 
;boolean
 
;boolean
 
true if the object is empty, i.e. the VisionaireObject does not reference an object of the visionaire data structure.
 
true if the object is empty, i.e. the VisionaireObject does not reference an object of the visionaire data structure.
 +
  
 
=== setName ===
 
=== setName ===
Line 507: Line 670:
 
;string
 
;string
 
The new internal name.
 
The new internal name.
 +
  
 
=== setValue ===
 
=== setValue ===
Line 529: Line 693:
 
  tom:setValue(VCharacterPosition, {x=100,y=300})
 
  tom:setValue(VCharacterPosition, {x=100,y=300})
 
</syntaxhighlight>
 
</syntaxhighlight>
 
  
 
<syntaxhighlight>
 
<syntaxhighlight>
Line 536: Line 699:
 
  cond:setValue(VConditionValue, true)
 
  cond:setValue(VConditionValue, true)
 
</syntaxhighlight>
 
</syntaxhighlight>
 
  
 
<syntaxhighlight>
 
<syntaxhighlight>
Line 544: Line 706:
 
  dog:setValue(VCharacterFollowCharacter, currentCharacter)
 
  dog:setValue(VCharacterFollowCharacter, currentCharacter)
 
</syntaxhighlight>
 
</syntaxhighlight>
 +
  
 
== Accessing an object ==
 
== Accessing an object ==
Line 551: Line 714:
 
Examples:
 
Examples:
 
<syntaxhighlight>local mother = getObject("Characters[Mother]")</syntaxhighlight>
 
<syntaxhighlight>local mother = getObject("Characters[Mother]")</syntaxhighlight>
 
  
 
<syntaxhighlight>local cond = getObject("Scenes[Forest].SceneObjects[Tree].ObjectCondition")</syntaxhighlight>
 
<syntaxhighlight>local cond = getObject("Scenes[Forest].SceneObjects[Tree].ObjectCondition")</syntaxhighlight>
Line 566: Line 728:
 
Examples:
 
Examples:
 
<syntaxhighlight>Game.CharacterLinks[Tom]</syntaxhighlight>
 
<syntaxhighlight>Game.CharacterLinks[Tom]</syntaxhighlight>
 
  
 
<syntaxhighlight>Scenes[Room].SceneObjects[start].SceneConditions[game started?]</syntaxhighlight>
 
<syntaxhighlight>Scenes[Room].SceneObjects[start].SceneConditions[game started?]</syntaxhighlight>
 
  
 
<syntaxhighlight>Characters[Tom].CharacterInterfaces[Tom-MI3]</syntaxhighlight>
 
<syntaxhighlight>Characters[Tom].CharacterInterfaces[Tom-MI3]</syntaxhighlight>
Line 581: Line 741:
 
Selects the object with id 6 from table 0 (characters).
 
Selects the object with id 6 from table 0 (characters).
  
== Commands  ==
+
== Editor Functions / Commands  ==
  
* [[VisObjectCmds|Object access]]
+
* [[Common_Commands|Editor based functions]]
  
=== Commands for Visionaire Player only ===
+
== Player Functions / Commands ==
  
* [[Player_Commands|Player commands]]{{toc}}
+
* [[Player_Commands|Player based functions]]
 +
{{toc}}

Revision as of 23:58, 27 October 2018

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 accessed / manipulated through the scripting language.


Online documentation about the Lua scripting Language:


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)

print( game:getBool(VGameAlwaysAllowSkipText) ) -- print current boolean value of VGameAlwaysAllowSkipText to the log
game:setValue(VGameAlwaysAllowSkipText, true) -- set VGameAlwaysAllowSkipText to true


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

number The field which specifies a number list. The field type must be t_vint.

Return Values

table A table containing multiple integer (number) values.

getLink

Returns a VisionaireObject.

getLink(number)


Arguments

number The field which specifies a link. The field type must be t_link.

Return Values

userdata A VisionaireObject; or an empty object if no object is linked for this field.

Example(s)

game:getLink(VGameCurrentCharacter)


getLinks

Returns a table containing multiple VisionaireObjects.

getLinks(number)


Arguments

number The field which specifies a link list. The field type must be t_links.

Return Values

table Table containing multiple VisionaireObjects (links).

Example(s)

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

"string" The internal name of the visionaire object (editor). This is the name which is used to access the object.

Example(s)

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

"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

userdata A VisionaireObject; or an empty object if the return value is nil.

Example(s)

local scene = getObject("Scenes[Bedroom]")
local deskCond = scene:getObject(".SceneObjects[Desk].ObjectCondition")


getParent

Returns the parent object of the specified VisionaireObject.

getParent()


Return Values

userdata The parent object for the specified VisionaireObject. An object has always a parent which contains it; only the game objects have no parent.

Example(s)

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

number The field which specifies a path value. The field type must be t_path.

Return Values

"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

number The field which specifies a path list. The field type must be t_vpath.

Return Values

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

number The field which specifies a point value. The field type must be t_point.

Return Values

table A table containing x & y coordinate values.

Example(s)

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

Returns multiple tables containing x & y coordinate values.

getPoints(number)


Arguments

number The field which specifies a point list. The field type must be t_vpoint.

Return Values

table Multiple tables containing x & y coordinate values.

getPosition

Returns a table containing the current x & y coordinates of the specified sprite.

getPosition()


Arguments

number The field which specifies a sprites position (x & y). The field type must be t_sprite.

Return Values

table A table containing the current x & y coordinate values of the specified sprite.
local obj = Objects["bottle"].ObjectSprite.SpriteSprite:getPosition() -- store position into a variable.
print(obj.x, obj.y) -- print the x, y coordinates of said object sprite to the log.


getRect

Returns a table (rectangle) consisting of x, y, width & height. A rectangle is essentially a specified area in which something will be placed, such as: the dialog interface, or action text, etc.

getRect(number)


Arguments

number The field which specifies a rectangle value. The field type must be t_rect.

Return Values

table A table containing the entries x, y, width & height.

Example(s)

-- let's say I have a scene that is 1280x720px & I want to limit the playable area to specific portion of the scene...
getObject("Scenes[bedroom]"):setValue( VSceneScrollableArea, { x = 320, y = 180, width = 640, height = 360 } ) -- 50% of scene size from center of scene.

-- math: x = width ÷ 4, y = height ÷ 4, width = width ÷ 2, height = height ÷ 2


getRects

Returns multiple tables (rectangles) containing x, y, width & height values. A rectangle is essentially a specified area in which something will be placed, such as: the dialog interface, or action text, etc.

getRects(number)


Arguments

number The field which specifies a rectangle list. The field type must be t_vrect.

Return Values

table Multiple tables containing x, y, width & height.

getSize

Returns a table containing the width (x) & height (y) of the specified object sprite.

getSize()


Arguments

number The field which specifies a sprites size (width & height). The field type must be t_sprite.

Return Values

table A table containing the width (x) & height (y) entries of the specified object sprite.
local obj = Objects["bottle"].ObjectSprite.SpriteSprite:getSize() -- store size of object sprite into a variable.
print(obj.x, obj.y) -- print width & height of said object sprite to the log.


getSprite

Returns a sprite. A sprite is an image; in other words this could consist of a static image or the current frame of an animation.

getSprite(number)


Arguments

number The field which specifies a sprite value. The field type must be t_sprite.

Return Values

table A table containing the 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 ms, in case sprite is used in an animation).

Example(s)

getObject("Objects[bottle]"):getLink(VObjectSprite):getSprite(VSpriteSprite)


getSprites

Returns a table containing multiple sprites. A sprite is an image; in other words this could consist of a static image or the current frame of an animation.

getSprites(number)


Arguments

number The field which specifies a sprite list. The field type must be t_vsprite.

Return Values

table Multiple tables containing the 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 ms, in case sprite is used in an animation).

getStr

Returns a "string" value. A "string" can consist of a mixture of plain text, numbers & symbols.

getStr(number)


Arguments

number The field which specifies a string value. The field type must be t_string.

Return Values

"string" A "string" value consisting of a mixture of text, numbers & symbols.

Example(s)

local str = getObject("Values[test]"):getStr(VValueString) -- store string value of "test" into a variable.
print(str) -- print said "string" to the log file.


getTexts

Returns a table containing multiple text (name) language values.

getTexts(number)


Arguments

number The field which specifies a text languages value. The field type must be t_vtext.

Return Values

table A table containing multiple text (name) language entries for the specified VisionaireObject.

Example(s)

iterate through texts belonging to a specified object (shorthand).

local txt = Objects["test"].ObjectName.TextTextLanguages

for i = 1, #txt do
 if txt[i].language == Languages["English"]:getId().id then
  print( txt[i].text )
 end
end

same as above, but using the getObject method (longhand).

local txt = getObject("Objects[test].ObjectName"):getTexts(VTextTextLanguages)

for i = 1, #txt do
 if txt[i].language == getObject("Languages[English]"):getId().id then
  print( txt[i].text )
 end
end


getTextStr

Returns the text belonging to the specified object; based on specified language.

getTextStr(number, <languageId>)


Arguments

number The field which specifies a text languages value. The field type must be t_link to Text.
languageId 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" The "string" value of the specified text of a VisionaireObject belonging to the given languageId.

Example(s)

get the text belonging to the currently active language for the specified object.

getObject("Buttons[talk]"):getTextStr(VButtonName)

get the text belong to the given language for the the specified object.

getObject("Buttons[talk]"):getTextStr( VButtonName, getObject("Languages[English]"):getId().id ) -- get text belong to "English" language.
getObject("Buttons[talk]"):getTextStr( VButtonName, getObject("Languages[German]"):getId().id ) -- get text belong to "German" language.


isAnyObject

Returns a boolean value of true or false, depending on whether or not VisionaireObject is returned???? (not actually sure about this one - never used it before). 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