Introduction

Welcome to the reference documentation for Visionaire. This is a documentation for programmers discussing lua features and keeping track of advanced functions. If you're not to savy on programming you can still use the finished scripts.

getVolume(type)

-- is music volume over 50%?ifgetVolume(eMusicVolume)>50then-- do some actionend-- is speech volume more than or equal to 80%?ifgetVolume(eSpeechVolume)>=80then-- do some actionend-- is global (master) volume not equal to 50%?ifgetVolume(eGlobalVolume)~=50then-- do some actionend

Returns the general volume for background music, sound or speech output.

getCursorPos()

-- let's store the current position into a variablelocalcurPos=getCursorPos()-- let's check if the stored cursor position equals another x,y valueifcurPos.x==200andcurPos.y==400then-- do some actionelse-- do some other actionend

Returns the current absolute cursor position.

Return Type

Description

point

position Table with x and y values containing cursor position.

setCursorPos(pos)

setCursorPos({x=240,y=480})localcPos={x=240,y=480}setCursorPos(cPos)

Parameter

Type

Description

pos

point

{x=int,y=int} - The position where the cursor will be set to.

createScreenshot(saveTo, flags)

-- save to "screenshots" folder as "filename.png"createScreenshot("screenshots/filename.png")-- add this as an execute script action inside of a key input; change filename to whatever you like-- save to "screenshots" folder as "filename_(date)_(time).pnglocaltime=os.date("%Y-%m-%d_%Hh-%Mm-%Ss")createScreenshot("screenshots/filename_"..time..".png")createScreenshot("",{flags=1,clear=true})

Creates a new screenshot which is either used for a savegame or stored to a file.

Parameter

Type

Description

saveTo

string

If specified the screenshot will be saved to the given path. Otherwise the screenshot will be used for the next savegame(s), as long as a new screenshot is created or the current screenshot is cleared. If a screenshot for a savegame was created before it will be overwritten by the new screenshot.

flags

table

If true the screenshot will be cleared. Default value is false. If the screenshot is cleared it will be generated automatically by the engine again, everytime the scene is changed from a playable scene to a menu.

registerEventHandler(eventtype, handler, flags)

functiononMainLoop()-- do somethingendregisterEventHandler("mainLoop","onMainLoop")-- mouse eventfunctiononMouseEvent(eventType,mousePosition)ifeventType==eEvtMouseWheelUporeventType==eEvtMouseWheelDownthen-- mouse wheel was activated, do somethingendendregisterEventHandler("mouseEvent","onMouseEvent",{eEvtMouseMove,eEvtMouseLeftButtonDoubleClick,eEvtMouseLeftButtonDown,eEvtMouseLeftButtonUp,eEvtMouseLeftButtonHold,eEvtMouseLeftButtonHolding,eEvtMouseRightButtonDoubleClick,eEvtMouseRightButtonDown,eEvtMouseRightButtonUp,eEvtMouseMiddleButtonDown,eEvtMouseMiddleButtonUp,eEvtMouseWheelUp,eEvtMouseWheelDown})-- key eventfunctionkeyboardHandler(eventType,character,keycode,modifiers)ifeventType==eEvtKeyUpthenprint('key up: '..keycode)-- test for '0' with character parameterifcharacter=='0'thenprint('0 released')end-- another option to test '0' keyifkeycode==48thenprint('0 released')endelseifeventType==eEvtKeyDownthenprint('key down: '..keycode)elseifeventType==eEvtKeyTextInputthen-- this will also show more 'complex' unicode characters when multiple keys are used to generate a single character (e.g. Chinese characters)print('input: '..character)endifkeycode==eKeyEscapethen-- event will not be handled by engine. this means that also cutscenes can't be skipped with Escape keyreturntrueendreturnfalse-- key event will also be handled by engineendregisterEventHandler("keyEvent","keyboardHandler")

Registers an event handler function for a specific event.

The function for the events "animationStarted", "animationStopped", "textStarted" and "textStopped" should take exactly one argument which is the affected visionaire object.
There are no arguments for the "mainLoop" event handler.
The function for "mouseEvent" takes two arguments, the first one is the mouse event (see "eventFlags" parameter) and the second argument is the current mouse position (a table containing x- and y-position).
The function for "keyEvent" takes four arguments: eventType, character, keycode and modifiers. Return value must be true or false. If the function returns true, the key event will not be handled by the engine.
eventType: eEvtKeyDown (key pressed, can be fired multiple times for pressed key), eEvtKeyTextInput (text input, can be fired multiple times for pressed key) and eEvtKeyUp (key released, only fired once).
character: current text input of pressed key(s). This parameter only contains printable characters.
keycode: virtual keycode, only valid for eEvtKeyDown and eEvtKeyUp events. Can be used to query special keys like Esc or Shift.
modifiers: currently active key modifiers (e.g. Ctrl, Shift).

{int,...} - Can only be specified for "mouseEvent": a list of mouse events where the event handler is called. Currently the following mouse events are supported: eEvtMouseMove, eEvtMouseLeftButtonDoubleClick, eEvtMouseLeftButtonDown, eEvtMouseLeftButtonUp, eEvtMouseLeftButtonHold, eEvtMouseLeftButtonHolding, eEvtMouseRightButtonDoubleClick, eEvtMouseRightButtonDown, eEvtMouseRightButtonUp, eEvtMouseMiddleButtonDown, eEvtMouseMiddleButtonUp, eEvtMouseWheelUp and eEvtMouseWheelDown. If no mouse event is specified then the event handler is registered for all mouse events.

unregisterEventHandler(event, handler)

functiononMainLoop()-- do somethingendregisterEventHandler("mainLoop","onMainLoop")-- ... later on, when the main loop event handler is not needed anymore:unregisterEventHandler("mainLoop","onMainLoop")

Unregisters an event handler function for a specific event.

Parameter

Type

Description

event

string

The event which triggers the event handler to be called. Currently supported events: "mainLoop", "mouseEvent".

handler

string

The name of the lua function which is called when the event occurs.

registerHookFunction(hook, hookFunction)

functionadaptedTextPosition(text)-- show texts of character Hero 10 pixel below character positionlocalowner=text:getLink(VTextOwner)ifowner:getId().tableId==eCharactersandowner:getName()=='Hero'thenlocalpos=owner:getPoint(VCharacterPosition)pos.y=pos.y+10text:setValue(VTextPosition,pos)returntrueendreturnfalseendregisterHookFunction("setTextPosition","adaptedTextPosition")functionmyActionText(mousePos)-- individual action text: object name (in current language) of object below cursor, if there is no object then '<empty>' is shown as action textlocalobj=game:getLink(VGameCurrentObject)ifobj:getId().tableId==eObjectsthenreturn'current object: '..obj:getTextStr(VObjectName)endreturn'<empty>'endregisterHookFunction("getActionText","myActionText")

Registers a hook function for a specific operation.

"setTextPosition": The function should take exactly one argument which is the affected visionaire object. The function must return a boolean value: true if the operation was handled in the hook function, false if the operation was not handled and should be handled by the engine (as if there were no hook).
"getActionText": The function should take exactly one argument which is the current mouse position (a table containing x- and y-position). The function must return a string value which will be used as the current action text.
"getCharacterAnimationIndex": The function takes exactly 3 arguments: the character (visionaire object), animation type () and new direction (degrees). The function must return an integer value which specifies the walk animation to use for the new direction (0-based index).
If -1 is returned the index is handled by the engine (as if there were no hook).

Parameter

Type

Description

hook

string

The operation for which the hook function should be called. Currently supported hooks: "setTextPosition" (the hook is called everytime the position of a displayed text is set), "getActionText" (the hook is called everytime to get the currently displayed action text), "getWalkAnimationIndex" (the hook is called everytime a character changes its direction during walking).

hookFunction

string

The name of the lua function which is called when the hook is executed.

initGameClient(clientID, clientSecret)

Init the gog galaxy client with the given values. Note: this command only works for the gog galaxy client!

Parameter

Type

Description

clientID

string

gog galaxy clientID.

clientSecret

string

gog galaxy clientSecret.

Return Type

Description

boolean

success

getGameClientStat(apiName)

Returns the requested game client stat. Note: this command only works if the steam_api/gog galaxy library was loaded and if a steam / gog galaxy account for your game exists.

Parameter

Type

Description

apiName

string

The name of the requested stat. This is the API name specified in the steam account.

Return Type

Description

stat

The integer value of the stat or -1 if the stat could not be retrieved.

setGameClientStat(apiName, value)

Sets the specified steam/gog galaxy stat to the given value. Note: this command only works if the steam_api/gog galaxy library was loaded and if a steam / gog galaxy account for your game exists.

Parameter

Type

Description

apiName

string

The name of the stat to set. This is the API name specified in the steam/gog galaxy account.

value

int

Stat will be set to this value.

Return Type

Description

boolean

success True if the value was set successfully, false if the operation failed.

resetGameClientStats(resetAchievements)

Resets all game clients stats. Note: this command only works if the steam_api/gog galaxy library was loaded and if a steam / gog galaxy account for your game exists.

Parameter

Type

Description

resetAchievements

boolean

If true all achievements will be cleared, otherwise only all stats will be reset. Default value is false

Return Type

Description

boolean

True if the stats were cleared successfully, false if the operation failed.

getGameClientAchievement(apiName)

Gets current state of an achievement.
Note: this command only works if the steam_api/gog galaxy library was loaded and if a steam / gog galaxy account for your game exists.

Parameter

Type

Description

apiName

string

The name of the requested achievement. This is the API name specified in the steam / gog galaxy account.

Return Type

Description

bool

result True/false depending if the achievement is set or not, false if the operation failed.

setGameClientAchievement(apiName, flags)

Sets an achievement to done.
Note: this command only works if the steam_api/gog galaxy library was loaded and if a steam / gog galaxy account for your game exists.

Parameter

Type

Description

apiName

string

The name of the achievement to set. This is the API name specified in the steam / gog galaxy account.

flags

table

If clear flag is true the achievement will be cleared. Default value is false.

startDefaultBrowser(url)

-- launch default browser & open included link, if browser is already running then open link in a new tabstartDefaultBrowser("http://visionaire-studio.net")-- returns true if customURL exists, false otherwise:localcustomURL=startDefaultBrowser("customURL://",true)

Open an url in user's default browser or in the steam overlay (if active).

Parameter

Type

Description

url

string

Return Type

Description

bool

status True if browser was successfully launched, false otherwise.

getProperty(name)

-- if platform equals windows then do some action else if mac do some other actionifgetProperty("platform")=="win"thengetObject("Conditions[win?]"):setValue(VConditionValue,true)elseifgetProperty("platform")=="mac"thengetObject("Conditions[mac?]"):setValue(VConditionValue,true)end-- let's check if steam has initialized & set a value based on return valuelocalsteamLoaded=getProperty("steam_initialized")ifsteamLoadedthengetObject("Conditions[steamLoaded?]"):setValue(VConditionValue,true)elsegetObject("Conditions[steamLoaded?]"):setValue(VConditionValue,false)end-- let's check if gog galaxy has initialized & set a value based on return valuelocalgalaxyLoaded=getProperty("galaxy_initialized")ifgalaxyLoadedthengetObject("Conditions[galaxyLoaded?]"):setValue(VConditionValue,true)elsegetObject("Conditions[galaxyLoaded?]"):setValue(VConditionValue,false)end-- set game language to users operating system languagelocalsysLang=getProperty("system_language")ifsysLang=="English"thengame:setValue(VGameStandardLanguage,getObject("Languages[English]"))elseifsysLang=="German"thengame:setValue(VGameStandardLanguage,getObject("Languages[Deutsch]"))end

"string" - The requested property to retrieve.
Currently supported properties:
"platform" (win,mac,ios,android,linux,ps4,xbox1,html5)
"steam_initialized" (true/false depending if the steam_api was loaded and client is connected, false if the operation failed)
"galaxy_initialized" (true/false depending if the gog galaxy_api was loaded and client is connected, false if the operation failed)
"galaxy_ready" (true if the galaxy_api is ready)
"system_language" Returns English name of system language or "unknown" if language could not be retrieved.
"display_resolution" Returns the rect that is drawn in, subtracting the black borders

Parameter

Type

Description

name

string

Return Type

Description

variant

result

startSound(sounditem, values)

--play audio file, store sound id (for later use) and update sound balance of currently started soundlocalsoundId=startSound('vispath:sounds/example.ogg')setSoundProperty(soundId,{flags=1,balance=40})-- play audio file and set volume, balance and offsetstartSound('vispath:sounds/example.ogg',{flags=1,volume=70,balance=-10,offset=1000})

getSoundProperty(soundID, property)

Currently supported properties:
"volume" (0 mute ... 100 full volume, -1 if volume could not be retrieved),
"balance" (-100 ... left, 0 ... center, +100 ... right, 0 if balance could not be retrieved),
"offset" (current position from beginning of the sound in milliseconds, -1 if offset could not be retrieved),
"duration" (total duration of sound in milliseconds, -1 if duration could not be retrieved),
"loop" (true if sound is looped, false it is only played once, false if loop property could not be retrieved),
"playing" (true if sound is currently playing, false otherwise).
"paused" (true if sound is currently paused, false if sound is playing or not active at all).

toggleSoundPause(soundID)

setWindowTitle(WindowTitle)

-- basic set window title commandsetWindowTitle("my new game title")-- set window title based on current users system languagesysLang=getProperty("system_language")ifsysLang=="English"thensetWindowTitle("my demogame")elseifsysLang=="German"thensetWindowTitle("mein Demospiel")end"));

Sets the window title.

Parameter

Type

Description

WindowTitle

string

getWindowBrightness()

Returns the brightness (gamma) for the window.
Note: 0 is completely dark and 100 is normal brightness.

Return Type

Description

int

Brightness

setWindowBrightness(Brightness)

setWindowBrightness(100)

Sets the brightness (gamma) for the window.

Parameter

Type

Description

Brightness

int

The brightness (gamma) value. 0 is completely dark and 100 is normal brightness. Returns false if not supported otherwise true.

isPointInsidePolygon(point, polygon)

-- Test if the current position of an active 'cloud' animation is inside the polygon of a 'window' object on the current scene -- and store the result in a global variablelocalanim=ActiveAnimations['Cloud']localpolygon=game.GameCurrentScene.SceneObjects['Window'].ObjectPolygoncloudVisible=isPointInsidePolygon(anim.AnimationCurrentPosition,polygon)

Tests if a point is inside polygon.

Parameter

Type

Description

point

point

polygon

pointlist

A single polygon. Bear in mind that a field containing multiple polygons (e.g. a way border or object polygon) must first be split into single polygons and tested separately.

toggleWindowMode()

toggleWindowMode()

Toggle the window mode to fullscreen or windowed.

getWindowMode()

Returns the window mode (fullscreen or not).
Note: true is fullscreen and false is windowed.

getTime(reset)

localtime=getTime()functioncheckTime()ifgetTime()>3000then-- if time elapsed is more than 3 seconds then ...-- do some actiongetTime({flags=1,reset=true})-- let's reset timer back to zeroendend-- the checkTime() function would be most effective if included in a mainLoop event handler

Returns the number of milli seconds since the command was called the first time (or the timer was reset).
Use this command for relative time measurements. E.g. call this command twice
at different locations and calculate the time differential to see the time passed.

Parameter

Type

Description

reset

table

getObject(path, logWarning)

localobj=getObject("\\eScenes\\")print(obj.name)-- Access object by scanning whole object table (object name must be unique for whole table)getObject(\"Conditions[door_open?]\")-- get condition with name 'door open?'-- Specific object accessgetObject(\"Scenes[office].SceneConditions[door_open?]\")-- get condition 'door open?' linked to scene 'office'

The path has to start with a table name, then follows
the object name in brackets ('[',']') - only the game table
does not have an object name. Optionally a field name
(field type must either be t_link or t_links) can follow after
a dot '.'. For t_links fields you must specify an object name in
brackets ('[',']'). For t_link fields there are no brackets.
Alternatively you can also pass in a tuple with the table id and
the object id, e.g. "(0,3)".

->Object Paths

Parameter

Type

Description

path

string

logWarning

bool

If true (default) a warning will be printed to the log file if the object could not be found.

Fields

assert(condition/nil, error)

localfile=assert(io.open("fake_file.lua","rb"))assert(false,"error: false unexpected")assert(a==0,"a should be 0")localarg=assert(file)

Parameter

Type

Description

condition/nil

variant

error

string

message

Return Type

Description

variant

passthrough all variables

collectgarbage(what)

"collect": performs a full garbage-collection cycle. This is the default option."stop": stops the garbage collector."restart": restarts the garbage collector."count": returns the total memory in use by Lua (in Kbytes)."step": performs a garbage-collection step. The step "size" is controlled by arg (larger values mean more steps) in a non-specified way. If you want to control the step size you must experimentally tune the value of arg. Returns true if the step finished a collection cycle."setpause": sets arg as the new value for the pause of the collector. Returns the previous value for pause."setstepmul": sets arg as the new value for the step multiplier of the collector. Returns the previous value for step.