Scripting: Difference between revisions

From VisionaireWiki
Jump to navigation Jump to search
No edit summary
 
(20 intermediate revisions by the same user not shown)
Line 1: Line 1:
== General ==
== 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.<br>
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 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 scripting Language:
Online documentation about scripting Language:
Line 27: Line 27:
t_links
t_links
| valign="top" |
| valign="top" |
table (array) with Visionaire Objects (userdata or string, see t_link above) elements, each entry referencing one Visionaire Object.
table (array) with Visionaire Objects (userdata or string, see t_link above) entries, each entry referencing one Visionaire Object.
|-
|-
| valign="top" |
| valign="top" |
Line 42: Line 42:
t_bool
t_bool
| valign="top" |
| valign="top" |
number (boolean)
boolean
|-
|-
| valign="top" |
| valign="top" |
t_point
t_point
| valign="top" |
| valign="top" |
table (with elements "x" and "y")
table (with entries "x" and "y")
|-
|-
| valign="top" |
| valign="top" |
t_rect
t_rect
| valign="top" |
| valign="top" |
table (with elements "x", "y", "width" and "height")
table (with entries "x", "y", "width" and "height")
|-
|-
| valign="top" |
| valign="top" |
Line 67: Line 67:
t_sprite
t_sprite
| valign="top" |
| valign="top" |
table (with element "path" and optional elements "x", "y", "cutting" (t_rect) and "transparent" (t_point))
table (with entry "path" and optional entries "x", "y", "cutting" (t_rect) and "transparent" (t_point))
|-
|-
| valign="top" |
| valign="top" |
t_vint
t_vint
| valign="top" |
| valign="top" |
table with number (integer) elements
table with number (integer) entries
|-
|-
| valign="top" |
| valign="top" |
t_vfloat
t_vfloat
| valign="top" |
| valign="top" |
table with number (float) elements
table with number (float) entries
|-
|-
| valign="top" |
| valign="top" |
t_vpoint
t_vpoint
| valign="top" |
| valign="top" |
table with t_point elements
table with t_point entries
|-
|-
| valign="top" |
| valign="top" |
t_vrect
t_vrect
| valign="top" |
| valign="top" |
table with t_rect elements
table with t_rect entries
|-
|-
| valign="top" |
| valign="top" |
t_vstring
t_vstring
| valign="top" |
| valign="top" |
table with string elements
table with string entries
|-
|-
| valign="top" |
| valign="top" |
t_vpath
t_vpath
| valign="top" |
| valign="top" |
table with t_path elements
table with t_path entries
|-
|-
| valign="top" |
| valign="top" |
t_vsprite
t_vsprite
| valign="top" |
| valign="top" |
table with t_sprite elements
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 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 3.x|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 ==
Line 113: Line 128:
=== clearLink ===
=== clearLink ===


Removes a link from the visionaire object. This is only a convenient method and has the same effect as calling setValue with the field and emptyObject.
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:
Lua Syntax:
Line 131: Line 146:
;boolean
;boolean
Current value of specified field.
Current value of specified field.
Example:
local allowSkipText = game:getBool(VGameAlwaysAllowSkipText)


=== getFloat ===
=== getFloat ===
Line 161: Line 179:
;table
;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:
-- writes to the log file if the animation with the name 'animname' (must be set before)
-- is a character animation
local anim = getObject("Animations[" .. animname .. "]")
if anim:getParent():getId().tableId == eOutfits then
  print("character animation")
else
  print("no character animation")
end


=== getInt ===
=== getInt ===
Line 337: Line 365:
;string
;string
Current value of specified field.
Current value of specified field.
=== getTexts ===
Lua Syntax:
<pre>getTexts(number)</pre>
*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:
<pre>getTextStr(number, <languageId>)</pre>
*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 ===
=== isAnyObject ===
Line 366: Line 428:
=== setValue ===
=== 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.
Sets a field of the visionaire object. Note that only fields which are marked as 'Scriptable' in the [[Data Structure 3.x|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:
Lua Syntax:
Line 389: Line 451:
  -- let the "dog" follow the current character
  -- let the "dog" follow the current character
  local dog = getObject("Characters[dog]")
  local dog = getObject("Characters[dog]")
  local currentCharacter = getObject("Game.CurrentCharacter")
  local currentCharacter = getObject("Game.GameCurrentCharacter")
  dog:setValue(VCharacterFollowCharacter, currentCharacter)
  dog:setValue(VCharacterFollowCharacter, currentCharacter)
== 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.
== Exported constants ==
The following contants are exported to the Lua scripting environment:


== Accessing an object ==
== Accessing an object ==

Latest revision as of 19:41, 14 March 2014

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 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.

Online documentation about 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 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) entries, each entry referencing one Visionaire Object.

t_int

number (integer)

t_float

number

t_bool

boolean

t_point

table (with entries "x" and "y")

t_rect

table (with entries "x", "y", "width" and "height")

t_string

string

t_path

string

t_sprite

table (with entry "path" and optional entries "x", "y", "cutting" (t_rect) and "transparent" (t_point))

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_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 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 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

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. This is only a convenient method and has the same effect as calling setValue with emptyObject as value.

Lua Syntax:

clearLink(number)
  • Arguments
number

The field which specifies a link to be cleared. The field type must be t_link.

getBool

Lua Syntax:

getBool(number)
  • Arguments
number

The field which specifies a boolean value. The field type must be t_bool.

  • Return Values
boolean

Current value of specified field.

Example:

local allowSkipText = game:getBool(VGameAlwaysAllowSkipText)

getFloat

Lua Syntax:

getFloat(number)
  • Arguments
number

The field which specifies a number value. The field type must be t_float.

  • Return Values
number

Current value of specified field.

getFloats

Lua Syntax:

getFloats(number)
  • Arguments
number

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

  • Return Values
table

Table with t_float entries representing the specified field.

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.

Example:

-- writes to the log file if the animation with the name 'animname' (must be set before)
-- is a character animation
local anim = getObject("Animations[" .. animname .. "]")
if anim:getParent():getId().tableId == eOutfits then
  print("character animation")
else
  print("no character animation")
end

getInt

Lua Syntax:

getInt(number)
  • Arguments
number

The field which specifies a number value. The field type must be t_int.

  • Return Values
number

Current value of specified field.

Example

local direction = getObject("Characters[Mother]"):getInt(VCharacterDirection)

getInts

Lua Syntax:

getInts(number)
  • Arguments
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.

getLink

Lua Syntax:

getLink(number)
  • 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

Lua Syntax:

getLinks(number)
  • 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

Lua Syntax:

getName()
  • 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

Lua Syntax:

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 (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")

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.

getPath

Lua Syntax:

getPath(number)
  • Arguments
number

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

  • Return Values
string

Current value of specified field. The path will be returned in unix format ('/' for directories) and relative to the .ved file.

getPaths

Lua Syntax:

getPaths(number)
  • Arguments
number

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

  • Return Values
table

Table with t_path entries representing the specified field.

getPoint

Lua Syntax:

getPoint(number)
  • 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.

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.

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.

getSprite

Lua Syntax:

getStr(number)
  • Arguments
number

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

  • Return Values
table

A table representing the value of the specified field. The table contains the entries path, x, y, cutting (t_rect) and transparency.

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.

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
local tom = getObject("Characters[Tom]")
-- set character "tom" to position 100,300
tom:setValue(VCharacterPosition, {x=100,y=300})
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).

Commands

Commands for Visionaire Player only