Visionary Render API

2025.1

Released 2025-03-07

Changed

vrSetting functions will continue to work when the setting they reference is moved
vrSettingWrite throws a warning instead of an error when attempting to write to a setting that no longer exists

Fixed

Make vrExtractBinaryAssets accept unversioned metanode names and deduce the metanode type automatically from the provided node if no explicit type is defined

2024.3

Released 2024-10-25

Added

vrHasLicenceFeature to check whether a licence feature is available

2024.2

Released 2024-07-08

Added

vrDisableNetwork to permit networking to be disabled, in contrast to vrEnableNetwork

Removed

relTo parameter from vrScriptEditorSetInsertPos and vrScriptEditorSetMarkPos

Fixed

Prevent vrSettingCreate functions from being able to create unnamed settings

2024.1

Released 2024-02-29

Added

vrSplitVirtalisHubURL to identify Virtalis Hub URLs and extract their server name, artifact ID and artifact name

Fixed

vrDot to work with vrVec4 values

2023.2

Released 2023-09-26

Added

vrGenerateQRCodeFile to permit QR codes to be generated and saved to a file (which is used by the HoloLens 2 to view scenes in Augmented Reality)

2022.2

Released 2022-07-08

Fixed

Incorrect return values from vrNodeIsInGroup

2022.1

Released 2022-01-24

Changed

Improve logging so that failures in the plugin sandbox can be understood

2021.3.1

Released 2021-11-29

Fixed

Occasional crash after certain combinations of Lua script errors

2021.3

Released 2021-10-07

Changed

vrNodeFindChild to return nil instead of the node to search from when passed an empty search path

2021.2

Released 2021-07-12

Added

2 functions to the Lua API for observing events:

Function	Description
`vrAddEventObserver`	Adds an observer and callback function to execute for events
`vrAddGlobalEventObserver`	Adds an observer and callback function to execute for global events

32 functions to the C API for observing events:

Function	Description
`VRAddCallbackActivate`	Add callback for Activate event of a node and the other node deactivated
`VRRemoveCallbackActivate`	Remove callback for Activate event of a node and the other node deactivated
`VRAddCallbackTouch`	Add Touch callback (assembly has collided)
`VRRemoveCallbackTouch`	Remove Touch callback (assembly has collided)
`VRAddCallbackBreak`	Add Break callback (assembly has ceased colliding)
`VRRemoveCallbackBreak`	Remove Break callback (assembly has ceased colliding)
`VRAddCallbackKeyPress`	Add Key press callback (key was pressed)
`VRRemoveCallbackKeyPress`	Remove Key press callback (key was pressed)
`VRAddCallbackKeyRelease`	Add Key release callback (key was released)
`VRRemoveCallbackKeyRelease`	Remove Key release callback (key was released)
`VRAddCallbackPoseEntered`	Add Pose entered callback (a hand switched to a pose)
`VRRemoveCallbackPoseEntered`	Remove Pose entered callback (a hand switched to a pose)
`VRAddCallbackPoseLeft`	Add Pose left callback (a hand left a pose)
`VRRemoveCallbackPoseLeft`	Remove Pose left callback (a hand left a pose)
`VRAddCallbackGesture`	Add Gesture callback (a hand activated a gesture)
`VRRemoveCallbackGesture`	Remove Gesture callback (a hand activated a gesture)
`VRAddCallbackClick`	Add Click callback (button or similar node clicked)
`VRRemoveCallbackClick`	Remove Click callback (button or similar node clicked)
`VRAddCallbackDoubleClick`	Add Double click callback (button or similar node double-clicked)
`VRRemoveCallbackDoubleClick`	Remove Double click callback (button or similar node double-clicked)
`VRAddCallbackEnter`	Add Enter callback (a generic state was entered)
`VRRemoveCallbackEnter`	Remove Enter callback (a generic state was entered)
`VRAddCallbackLeave`	Add Leave callback (a generic state was left)
`VRRemoveCallbackLeave`	Remove Leave callback (a generic state was left)
`VRAddCallbackMove`	Add Move callback. The Move event applies to sliders, scrollbars and markers in the GUI system in addition to assemblies.
`VRRemoveCallbackMove`	Remove Move callback (the transform property has changed)
`VRAddCallbackPress`	Add Press callback (button or similar node pressed)
`VRRemoveCallbackPress`	Remove Press callback (button or similar node pressed)
`VRAddCallbackRelease`	Add Release callback (button or similar node released)
`VRRemoveCallbackRelease`	Remove Release callback (button or similar node released)
`VRAddCallbackToggle`	Add Toggle callback (button or similar node toggled)
`VRRemoveCallbackToggle`	Remove Toggle callback (button or similar node toggled)

14 functions to the Lua API for creating and editing user settings:

Function	Description
`vrSettingCreateArrayDouble`	Creates a new double array user setting
`vrSettingCreateArrayFloat`	Creates a new float array user setting
`vrSettingCreateArrayInt`	Creates a new integer array user setting
`vrSettingCreateBool`	Creates a new boolean user setting
`vrSettingCreateDouble`	Creates a new double user setting
`vrSettingCreateFloat`	Creates a new float user setting
`vrSettingCreateInt`	Creates a new integer user setting
`vrSettingCreateLink`	Creates a new link user setting
`vrSettingCreateString`	Creates a new string user setting
`vrSettingGetRoot`	Gets the node associated with the root of the settings hierarchy
`vrSettingSetCaption`	Assigns a custom caption to a setting, allowing the text displayed in user interface to be different from the setting name
`vrSettingSetFilter`	Assigns a filter to a setting. The meaning of the filter depends on the setting type
`vrSettingSetStep`	Assigns a step size to a numerical setting
`vrSettingSetType`	Assigns a type to a setting, which determines how the setting is presented in the user interface

Changed

Improve vrNodeHasTrait(node:hasTrait()) to support checking for traits without version numbers and without the Trait_ prefix. For example, n:hasTrait("AttributeTable") as a shortcut for n:hasTrait("Trait_AttributeTable.1")

Deprecated

__registerCallback no longer accepts non-function objects as callbacks

Fixed

Crash when a vector or matrix is passed to a Lua function that expects a node
Various instances where infinite progress displays could be spawned from Lua scripts
Inability to register Lua functions in the Lua state provided by vrtree.dll
Scripts in the StandardActions library can execute multiple times in a collaboration

2021.1.1

Released 2021-04-19

Changed

vrAddPropertyObserver can observe multiple properties of a metanode

2021.1

Released 2021-04-01

Added

40 functions to the Lua API for for creating your own metanode types:

Function	Description
`vrCreateMetaNode`	Creates a new metanode
`vrFinishMetaNode`	Finishes a metanode (call this after creating it and adding properties, etc.)
`vrAddPropertyBool`	Adds a new boolean property to an unfinished metanode
`vrAddPropertyChar`	Adds a new character property to an unfinished metanode
`vrAddPropertyInt`	Adds a new integer property to an unfinished metanode
`vrAddPropertyFloat`	Adds a new float property to an unfinished metanode
`vrAddPropertyDouble`	Adds a new double property to an unfinished metanode
`vrAddPropertyWorldFloat`	Adds a new world float property to an unfinished metanode
`vrAddPropertyLink`	Adds a new link property to an unfinished metanode
`vrAddPropertyString`	Adds a new string property to an unfinished metanode
`vrAddPropertyVec2i`	Adds a new vec2i property to an unfinished metanode
`vrAddPropertyVec2f`	Adds a new vec2f property to an unfinished metanode
`vrAddPropertyVec2d`	Adds a new vec2d property to an unfinished metanode
`vrAddPropertyVec2w`	Adds a new vec2w property to an unfinished metanode
`vrAddPropertyVec3i`	Adds a new vec3i property to an unfinished metanode
`vrAddPropertyVec3f`	Adds a new vec3f property to an unfinished metanode
`vrAddPropertyVec3d`	Adds a new vec3d property to an unfinished metanode
`vrAddPropertyVec3w`	Adds a new vec3w property to an unfinished metanode
`vrAddPropertyVec4i`	Adds a new vec4i property to an unfinished metanode
`vrAddPropertyVec4f`	Adds a new vec4f property to an unfinished metanode
`vrAddPropertyVec4d`	Adds a new vec4d property to an unfinished metanode
`vrAddPropertyVec4w`	Adds a new vec4w property to an unfinished metanode
`vrAddPropertyMat3f`	Adds a new mat3f property to an unfinished metanode
`vrAddPropertyMat3d`	Adds a new mat3d property to an unfinished metanode
`vrAddPropertyMat3w`	Adds a new mat3w property to an unfinished metanode
`vrAddPropertyMat4f`	Adds a new mat4f property to an unfinished metanode
`vrAddPropertyMat4d`	Adds a new mat4d property to an unfinished metanode
`vrAddPropertyMat4w`	Adds a new mat4w property to an unfinished metanode
`vrAddPropertyArrayBool`	Adds a new boolean array property to an unfinished metanode
`vrAddPropertyArrayChar`	Adds a new character array property to an unfinished metanode
`vrAddPropertyArrayInt`	Adds a new integer array property to an unfinished metanode
`vrAddPropertyArrayFloat`	Adds a new float array property to an unfinished metanode
`vrAddPropertyArrayDouble`	Adds a new double array property to an unfinished metanode
`vrAddPropertyArrayWorldFloat`	Adds a new world float array property to an unfinished metanode
`vrAddPropertyVectorBool`	Adds a new boolean vector property to an unfinished metanode
`vrAddPropertyVectorChar`	Adds a new character vector property to an unfinished metanode
`vrAddPropertyVectorInt`	Adds a new integer vector property to an unfinished metanode
`vrAddPropertyVectorFloat`	Adds a new float vector property to an unfinished metanode
`vrAddPropertyVectorDouble`	Adds a new double vector property to an unfinished metanode
`vrAddPropertyVectorWorldFloat`	Adds a new world float vector property to an unfinished metanode
`vrAddPropertyVectorString`	Adds a new string vector property to an unfinished metanode

40 functions to the C API for creating and observing settings:

Function	Description
`VRCreateSettingBool`	Creates a boolean setting if it doesn't already exist
`VRCreateSettingInt`	Creates an integer setting if it doesn't already exist
`VRCreateSettingArrayInt`	Creates an integer array setting if it doesn't already exist
`VRCreateSettingFloat`	Creates a float setting if it doesn't already exist
`VRCreateSettingArrayFloat`	Creates a float array setting if it doesn't already exist
`VRCreateSettingDouble`	Creates a double setting if it doesn't already exist
`VRCreateSettingArrayDouble`	Creates a double array setting if it doesn't already exist
`VRCreateSettingString`	Creates a string setting if it doesn't already exist
`VRCreateSettingLink`	Creates a link setting if it doesn't already exist
`VRSetSettingCaption`	Assigns a custom caption to a setting, allowing the text displayed to in user interface to be different from the setting name
`VRSetSettingRange`	Assigns a range to a numeric setting
`VRSetSettingStep`	Assigns a step size to a numeric setting
`VRSetSettingType`	Assigns a type to a setting, which determines how the setting is presented in the user interface
`VRSetSettingFilter`	Assigns a filter to a setting
`VRGetSettingSize`	Returns the number of bytes required to store a setting's value. For string settings, this includes the terminating null character
`VRReadSettingBool`	Reads a boolean setting
`VRReadSettingInt`	Reads an int setting
`VRReadSettingArrayInt`	Reads an int array setting
`VRReadSettingFloat`	Reads a float setting
`VRReadSettingArrayFloat`	Reads a float array setting
`VRReadSettingDouble`	Reads a double setting
`VRReadSettingArrayDouble`	Reads a double array setting
`VRReadSettingString`	Reads a string setting
`VRReadSettingLink`	Reads a link setting
`VRWriteSettingBool`	Sets the value of a boolean setting
`VRWriteSettingInt`	Sets the value of an int setting
`VRWriteSettingArrayInt`	Sets the value of an int array setting
`VRWriteSettingFloat`	Sets the value of a float setting
`VRWriteSettingArrayFloat`	Sets the value of a float array setting
`VRWriteSettingDouble`	Sets the value of a double setting
`VRWriteSettingArrayDouble`	Sets the value of a double array setting
`VRWriteSettingString`	Sets the value of a string setting
`VRWriteSettingLink`	Sets the value of a link setting
`VRGetSettingNode`	Gets the VRTree node associated with a setting. If the setting has a scene override, the override node is returned; otherwise, the user setting node is returned
`VRGetRootSettingNode`	Gets the VRTree node associated with the root of the settings hierarchy
`VRGetSceneRootSettingNode`	Gets the VRTree node associated with the root of the scene overrides, if present
`VRAddSettingToScene`	Adds a scene override of a setting (if it doesn't already exist) and copies the value from the user setting to the override
`VRRemoveSettingFromScene`	Removes a scene override of a setting
`VRAddCallbackSettingChanged`	Registers a function to be called when a setting value changes
`VRRemoveCallbackSettingChanged`	Removes a callback that was added with `VRAddCallbackSettingChanged()`

vrNodeArrayClear to clear the values held in an array property

Changed

Improves the performance of hooks in Lua scripts
Improves the performance of copying large strings in Lua scripts
vrNodeArraySet, vrNodeArrayPush and vrNodeArraySetElement so that they accept zero or more values, maths types (vrVec2/3/4, vrMat3/4, etc.), strings containing binary data, or nested tables containing any combination of these
Added an optional parameter to vrNodeArrayPop specifying how many items to pop (defaults to 1)
Made all the vrNodeArray* functions accept a single VectorPropUD userdata argument as an alternative to the node and property name

Fixed

vrSelectNodes({}) doesn't work

2020.2

Released 2020-07-08

Added

vrGetHoldingUser to determine which user has grabbed an object

Changed

The following functions can now be called for a specific user node:
- vrIsToolEnabled
- vrSetToolEnabled
- vrToggleToolEnabled
- vrSettingGetNode
- vrSettingGet
- vrSettingRead
- vrSettingWrite
Allows objects to be released from the TrackedManipulatorTool using vrReleaseObjectFromTrackedHand
Adds optional parameters to vrGrabObjectWithTrackedHand and vrReleaseObjectFromTrackedHand to specify the user and/or hand and object positioning

Fixed

Fixes issue with Lua functions such as vrSettingRead and vrSettingWrite being applied to the wrong user in a collaboration
Fixes problems with the vrBodyFly... Lua functions in collaboration sessions
Fixes incorrect results from vrBodyFlyToFit and vrBodyFlyToFitSphere when called from a script in a collaboration for a user other than the master
Fixes a bug where a call to vrBodyFlyTo from an activate event script would result in the event being triggered repeatedly

2020.1

Released 2020-03-18

Added

VRGetPrev - Get the previous sibling of a node
VRGetPrevOfType - Get the previous sibling of a specific type
VRSetParentEx - Set the parent of a node, specifying a sibling to insert after

Deprecated

vrSetTrackedHandNode and vrSetTrackedEyesNode

Fixed

Fixes issue with the plugins directory that Visionary Render installs not being checked for Lua scripts
Fixes crash when changing the current value of a custom drop-down setting created with vrSettingAddToScene

2019.5

Released 2019-12-06

Fixed

Fixes issue causing plugin installation via the settings window to silently fail under certain circumstances

2019.3

Released 2019-05-29

Added

VRGetPropertyEx() to extract the property index from a metanode name and property name
VRRemoveCallbackEx variants to remove callbacks specific to a piece of user data

typedef struct MyManager_
{
  uint32_t property;
  void (*translate)(HNode vrNode, const char* text);
} MyManager;

void onValuesChanged(HNode node, void* userData)
{
  MyManager- manager = (MyManager*)userData;
  size_t length = VRGetPropertyValueSizeEx(node, manager->property);
  auto text = (char*)malloc(length);
  VRGetPropertyStringEx(node, manager->property, text, length);
  if(manager->translate && length > 0)
    manager->translate(node, text);
  free(text);
}

void init(const char* metaName, MyManager* manager)
{
  VRAddCallbackNodeValuesChanged(metaName, &onValuesChanged, manager);
}

void release(const char* metaName, MyManager* manager)
{
  VRRemoveCallbackNodeValuesChangedEx(metaName, &onValuesChanged, manager);
}

using namespace vrtree;
using namespace vrtree_cpp;

struct MyManager2
  : public NodeManager
{
  MyManager2()
  {
    registerObserver(Meta_MetaDataString::Name());
    registerUpdateable();
  }

  ~MyManager2()
  {
    unRegisterObserver(Meta_MetaDataString::Name());
    unRegisterUpdateable();
  }

  void update(double deltaTime) override
  {
    // TODO: do stuff every step
  }

  void nodeValuesChanged(HNodeR& node) override
  {
    // TODO: respond to stuff
  }
  // More functions avaliable to override in NodeManager class...
}

Changed

Updated the scripting engine to LuaJIT-2.1.0-beta3, which allows 64-bit memory management
vrGeometryOp() now supports optimise, split, explode, prune, sieve, recentre, transform and merge operations

Fixed

Fixes crash that could occur when compressing DDS pixel data in the API
Fixes out-of-memory issues with scripting, most commonly affecting Windows 7

2019.2

Released 2019-03-27

Added

VRGetMetaNode to get the metanode handle from a given node handle
6 C API functions that work with properties containing vectors of strings:
- VRAddPropertyVectorString
- VRChangePropertyVectorString
- VRSetPropertyStringElement
- VRSetPropertyStringElementEx
- VRGetPropertyStringElement
- VRGetPropertyStringElementEx
6 C API functions to access fixed sized floating point value arrays such as those used for matrices:
- VRSetPropertyArrayFloat
- VRSetPropertyArrayFloatEx
- VRSetPropertyArrayDouble
- VRSetPropertyArrayDoubleEx
- VRSetPropertyArrayWorldFloat
- VRSetPropertyArrayWorldFloatEx

2019.1

Released 2019-01-24

Fixed

Fixes a crash that could occur when an unexpected uniform type is encountered in a surface shader

2.2

Released 2018-11-15

Changed

Nodes in the Toolbox no longer have an Enabled property; this is now controlled solely by the settings under Tools/State. Code that enables or disables tools can now do so via the settings, or preferably, with the Lua functions vrIsToolEnabled, vrSetToolEnabled and vrToggleToolEnabled. These take the name of a tool node, which also matches the metanode names if using the default Toolbox. In C/C++, these can be called using the Foreign Function Interface (FFI). For example:

if(HNode tool = VRFind(VRGetThisUser(), "ToolBox/MouseNavigatorTool")) {
  VRSetPropertyChar(tool, "Enabled", 0);
  VRCloseNodeHandle(tool);
}

if(HNodeR tool = VRFind(VRGetThisUser(), "ToolBox/MouseNavigatorTool")) {
  VRSetPropertyChar(tool, "Enabled", 0);
}

vrLocalUserNode():find("ToolBox/MouseNavigatorTool").Enabled = false

Should be changed to:

HFFIVar args[] = {
  VRFFIMakeString("MouseNavigatorTool"),
  VRFFIMakeBool(0)
};
HFFIVar ret = VRFFIInvoke("vrSetToolEnabled", args, 2);
VRFFIFree(ret);
VRFFIFree(args[1]);
VRFFIFree(args[0]);

HFFIVarR args[] = {
  VRFFIMakeString("MouseNavigatorTool"),
  VRFFIMakeBool(0)
};
HFFIVarR ret = VRFFIInvoke("vrSetToolEnabled", HFFIVarR::raw(args), 2);

vrSetToolEnabled("MouseNavigatorTool", false)

Removed

Removes Enabled property from all nodes under the toolbox. Any scripts that refer to the Enabled property of a tool node should be updated to refer to the relevant setting instead

Fixed

Fixes issue where Lua Observers were not receiving callbacks
Fixes issue where plugins would not display relevant progress messages
Fixes issues where matrix properties were not accessible via Lua

2.1

Released 2018-09-06

Added

Adds Lua function vrHideModalDialogues(true) for suppressing modal dialogues to enable unattended scripting
Adds VRGetNodeVersion which allows migration code to query the version of a node
Adds vrMetaNodeExists to check if the named metanode is present
Adds a progress display during shader cache priming

Changed

The internal Lua engine has changed from Lua 5.1 to LuaJIT 2.0.5. This is fully compatible with all existing Lua 5.1 code and plugins, and also supports some extensions from Lua 5.2. You can read more about LuaJIT and its extensions and performance benefits at http://luajit.org/luajit.html
Adds an improved API for node observer in Lua. Updates the function signatures of vrAddNodeObserver and vrAddMetaNodeObserver. The old versions have been deprecated. See Observers for more information
VR API development licenses are now less restricting, and one development license for a machine will allow development and debugging of any number of plugins

Fixed

Fixes a potential crash when calling certain Lua functions with too few arguments
Fixes issue with global Lua state not being reset when changing scenes
Fixes issue where the plugins list would be empty on cluster slaves
Fixes issue where some functions provided by Lua Plugins could be lost after starting a new scene
Fixes issue reading properties from node snapshots in Lua
Fixes corruption of metadata when editing a script

2.0

Released 2018-05-11

Added

Adds the VR Exchange API
Adds some utilities to assist working with reference types in Lua (vectors, matrices, etc)
- vrCopy
- vrGetOwnerNode
Adds vrSearchView which allows the tree view quick-search bar to be pre-populated with a search query string
Adds vrNodeGetTraits and vrNodeHasTrait to query the metanode traits of a node. If you know the name of the trait you are looking for, you should use vrNodeHasTrait, as getting all the traits is more expensive
Adds vrNodeIsInGroup to check whether a node is in the specified group, and vrGroupRemoveMember to remove a node from a group
Adds vrTreeViewSelectionSelectParent to select the parent nodes of the nodes in the specified view selection
Adds vrGetContactPoints which returns a list of contact points and normals between two nodes. This can be used, for example, from a Touch event by providing the __Self and __Other registers
Adds vrGetActivatorNode which can be used inside an activate event script to identify the node that activated it (in the case of it being activated by vrActivate)
Adds vrToggleProjection to toggle the current viewport between perspective and orthographic mode
Adds vrUsingHMD to identify whether the primary viewport is rendering into a head-mounted display
Adds the ability to author and load plugins exporting a C interface
Adds __Time register to scripts, containing the total time the application has been running
Adds optional fade effects to vrBodyFlyTo
Adds support for custom surface shaders

Changed

Most nodes in the User tree (and the Developer tree in general) are now hidden behind the User Interface / Advanced / Developer Admin Mode setting. If you are a plugin developer it is recommended to enable this setting
vrParseJSON now triggers a Lua error on parsing failure, instead of simply printing the error message and continuing
Fixes assignment to swizzled vector values (e.g. vrScenesNode().Cube.Transform.Rotation.zx = { 10, 20 }
New attribute table nodes are accessible from Lua using node property syntax for keys (e.g. local value = a.Metadata.KEY_NAME). The structure of attribute tables is such that keys and values are interleaved in regular properties, for example:
- 0 - Key 1
- 1 - Value 1
- 2 - Key 2
- 3 - Value 2
- etc... The vrNodeSetValueByIndex function allows access to key names as well as values using this convention
node.WorldEnabled provides access to the node's world enabled state
Lua plugins should no longer execute code outside of functions. Initialisation code should go in function init()
ApplicationMenuEntry nodes added to context menus now support all of the same types as the main application menu (e.g. app commands, lua blocks, property toggles, etc)
The tools window and associated UI nodes has been removed, replaced with the toolbar for common shortcuts, and the diagnostics frame for logs and stats. Plugins that were previously inserting frames into the tools window may now instead insert buttons into the toolbar, or add frames into the diagnostics window

Deprecated

The following Lua functions have been marked as Deprecated and may be removed in a future version. Most notably, all of the cluster specific Lua calls have been refactored into their non-cluster named equivalent. The cluster logic is now performed completely in C++.

Function	Replacement
`vrClusterResetWindows`	vrResetWindows
`vrShouldShowPropertyWindow`	None. This function has always returned true.
`vrPopupPropertyWindow`	vrShowPropertyWindow
`vrClusterPopupPropertyWindow`	vrShowPropertyWindow
`vrClusterShowPropertyWindow`	vrShowPropertyWindow
`vrShowNodeProperties`	vrShowPropertyWindow
`vrClusterShowNodeProperties`	vrShowPropertyWindow
`vrClusterTriggerRename`	vrTriggerRename
`vrPopupScriptWindow`	vrShowScriptWindow
`vrClusterPopupScriptWindow`	vrShowScriptWindow
`vrPopupScriptWindowAndShow`	vrShowScriptWindow
`vrClusterPopupScriptWindowAndShow`	vrShowScriptWindow
`vrClusterShowSequencer`	vrShowSequencer
`vrClusterPopupToolsWindow`	vrPopupToolsWindow
`vrClusterPopupFindWindow`	vrPopupFindWindow
`vrClusterShowSettingsWindow`	vrShowSettingsWindow
`vrShowInTree`	vrSelectNodes
`vrClusterShowInTree`	vrSelectNodes
`vrShowInTreeViewFrame`	vrSelectNodes
`vrClusterShowInTreeViewFrame`	vrSelectNodes
`vrSelectAndShowProperties`	vrSelectNodes
`vrClusterSelectAndShowProperties`	vrSelectNodes

Removed

vrNodeGetWorldMatrix and vrNodeSetWorldMatrix

Fixed

Fixes issues around manually creating pivots from Lua and reusing/re-parenting them
Fixes issues in some Lua vector and matrix math functions
Fixes issue where vrParseJSON would log an error but not actually fail when given invalid JSON

Lua Event Coroutines

Event handler scripts and the main Scripts console window now execute as coroutines

Introduction

A coroutine is a piece of code that may pause its execution and resume at some point in the future. In Visionary Render they can be used to control the flow of an event script, in most cases so that it can perform time-based operations sequentially.

Consider this basic example using vrYield:

for i = 1, 10 do
  print(i)
  vrYield(0.5)
end

This prints the numbers 1 through 10 to the application log (and Lua output window) over 5 seconds, printing one number and sleeping for half a second.

To do this without yielding, you would have to use a Timestep event and a piece of metadata or a global variable to track the value of i.

Gotchas

There are some issues yielding inside for loops, most obviously when using iterators such as pairs, but also in nested loops.

The following code may randomly fail with a nil access error on the next iteration:

local t = {1, 2, 3}
for i, v in ipairs(t) do
  print(i, v)
  vrYield(0.5) -- don't do this here...
end

Equally, this code will fail after a while because it thinks u is nil:

local t = 100
local u = 100
while t > 1 do
  while u > 1 do
    vrYield(0)
    u = u - 1
  end
  t = t - 1
end

The most stable way is to structure the code so that the yielding logic is in a function call, and that function does not contain loops. For example, this should be fine:

local function doU(u)
  --do stuff with u
  vrYield(0)
end

local t = 100
local u = 100
while t > 1 do
  while u > 1 do
    doU(u)
    u = u - 1
  end
  t = t - 1
end

Global Variables

When writing a script that makes use of vrYield, it is important to understand that global variables are shared between the main Lua state and any coroutines. This means that when your script yields, the values of any global variables are not guaranteed to be the same when the script resumes.

For example:

-- AssemblyA.EventCreate
print(__Self) -- prints AssemblyA
vrYield(0.1)
print(__Self) -- prints an undefined node (probably not AssemblyA)

If a script needs access to the global values it expects when the script it first executed, it should localise them somewhere in the script before the first call to vrYield.

-- AssemblyA.EventCreate
local me = __Self
print(me) -- prints AssemblyA
vrYield(0.1)
print(me) -- prints AssemblyA

Recompiling Coroutines

When editing scripts involving vrYield, compilation will automatically abort any previously running (and still sleeping) instances of the code. This is to avoid long running scripts becoming stuck, and waking up to perform out of date instructions which will most likely cause issues in the scripted simulations in the scene.

The exception to this is when executing code in the script console - no cleanup is done on the previously executing coroutine. This is intentional, because sometimes it is useful to write some test code that involves a long running script, and then also execute other code while that is running.

Managing Sleeping Coroutines

When a script calls vrYield, it goes to sleep for the specified (approximate) time. When this happens it is put into a list with all the other sleeping scripts, which is accessible from Lua itself using vrListSleepingScripts. This returns an array of sleeping coroutine names.

The name of a script can be set using vrSetScriptIdentifier, otherwise the name will just be a string representation of the coroutine memory address. This is not used for anything other than identification purposes and as the parameter to vrAbortScript, which can be used to abort a sleeping coroutine.

This can also be done using the Lua State tab in the Diagnostics window. The left panel displays the state of global variables, the right panel displays any sleeping scripts and provides an option to abort them.

Lua Observers

New Lua observers and additional callbacks for existing observers.

Transform Node Observer

There is a new type of observer that can be registered from Lua, which observes changes in internal scenegraph nodes dealing with world and local transforms, as well as world and local enabled states.

Difference from property observer

A transform observer differs from a normal property observer because it only observes the Enabled and Transform properties, and is also notified in response to changes of state on any ancestor of the node being observed.

When an assembly node is disabled, all of its descendants are also considered to be disabled in terms of application systems traversing the tree to process child nodes. However, a normal property observer on an Enabled property of one of these descendants would not be notified of this change because the property of that node hasn't actually changed.

Equally when an assembly node is moved, all of its descendants world transform change due to the nature of the transform hierarchy. A property observer on a Transform property of one of these descendants would not be notified of this change because the local transforms on these assemblies does not actually change when an ancestor transform changes.

This is the problem solved by the transform node observer.

Example

A transform observer is added using the vrAddTransformNodeObserver function.

Consider this hierarchy of assembly nodes in the Scenes tree:

Scenes
 - A
   - B
     - C

The following code snippet, executed in the console, will add a transform observer to the C assembly node, providing callback functions for transform and enabled state changes that print out a message that show the state notification was successful.

vrAddTransformNodeObserver("myObserver", 
  function(node, matrix) print("transform changed") end,
  function(node, enabled) print("enabled state changed") end,
  vrTreeRoot().Scenes.A.B.C
)

After running this example code, changing the transform or enabled property of any of A, B, or C will trigger the print messages.

The observer can also be removed using the vrRemoveObserver function, by providing the name (in this case "myObserver").

Changes to Node and MetaNode Observers

vrAddNodeObserver and vrAddMetaNodeObserver have been extended to support additional callbacks.

Node Observer

You can now specify a callback for when the observed node is destroyed.

vrAddNodeObserver("myObserver",
  function(node) print("node property changed") end,
  vrTreeRoot().Scenes.A,
  nil,
  function(node) print("node destroying") end
)

MetaNode Observer

You can now specify callbacks for parent change, renaming, and destroying.

vrAddMetaNodeObserver("myObserver",
  function(meta, node) print("node instance created") end,
  "Assembly",
  nil,
  function(meta, node, old, new) print("node parent changed from old to new") end,
  function(meta, node) print("node instance renamed") end,
  function(meta, node) print("node instance destroying") end
)

Pivot API

The internal implementation of pivots has been improved, and with this comes some new interfaces to simplify Lua interaction with Assemblies that are affected by a pivot point.

Creation

To add a pivot point to an Assembly, use

local target = vrTreeRoot():find("Scenes/My/Node")
context_create_pivot(target, 0)

This adds a child node called "Pivot" to the target assembly node. This assembly node now behaves as if its origin is located at the pivot location.

The second argument specifies whether to place the pivot at the existing origin (0), or at the centre of the assembly bounding box (1).

Transforms

To set the world or local transform of a node (pivot point as origin):

target.WorldTransform = myNewWorldMatrix --world
--or
target.Transform = myNewLocalMatrix --local

To set the world of local transform of a node, ignoring the pivot point:

target.UnpivotedWorldTransform = myNewWorldMatrix --world
--or
target.UnpivotedTransform = myNewLocalMatrix --local

To set the transform of the pivot itself (this will not change the final position of target):

target.Pivot.WorldTransform = myNewWorldMatrix --world
--or
target.Pivot.Transform = myNewLocalMatrix --local

To set the post-transform of the pivot (similar to target.UnpivotedTransform but leaves the pivot point in place)

target.Pivot.UnpivotedWorldTransform = myNewWorldMatrix --world
--or
target.Pivot.UnpivotedTransform = myNewLocalMatrix --local

Advanced Example

Moving an object around a pivot

-- Ensure a pre-defined fix position of the target assembly for comparing results 
target.UnpivotedWorldTransform = vrMat4()
target.UnpivotedWorldTransform.Position = {0,-2,0}
-- describe the pivot space ..
target.Pivot.WorldTransform.Position = {0,1,0}
target.Pivot.WorldTransform.Rotation = {0,0,0}
-- Rotate the target assembly around its pivot point
target.WorldTransform.Rotation = {0,0,20}
-- Rotate the target assembly around its world transform (Set on pivot node so the position of the pivot wont change)
target.Pivot.UnpivotedWorldTransform.Rotation = {0,0,0}

1.3.6

Released 2018-01-12

Fixed

Fixes a number of crashes caused by using Lua to set various setting values outside of the expected range
Fixes crash when providing invalid time format specifiers to os.date in a Lua script

1.3.3

Released 2017-08-09

Fixed

Fixes issue with vrPostCommand in a file being loaded causing an infinite loop

1.3.2

Released 2017-03-24

Fixed

Fixes issue where some functions on math objects exposed to Lua would conflict with other metatable entries (e.g. .Scale vs scale())
Fixes issue with view shader targets and colour space in de-ghost and red-cyan shaders

1.3.1

Released 2017-02-01

Fixed

Fixes issue where Lua functions vrNodeComposeLocalTransform and vrNodeDecomposeTransform would throw exceptions even if they were given perfectly valid matrices

1.3

Released 2016-11-10

Added

Adds vrBodyAddImpulse and vrBodyAddImpulseMouse to the Lua API
Adds vrGetCursorPosition and vrGetLastClickedCursorPosition to the Lua API
Adds Lua function vrNodeGetRelativePath and associated node:relpath(other) functions for getting the path of a node relative to another node
Adds Lua symbols for some property enum values which were previously missing, and unifies the naming convention of all symbols
Adds support for Lua coroutine yielding across the Lua/C boundary
Adds support for Lua function objects passed into VR functions that require a callback, instead of only relying on global functions passed by name

Changed

Renames some of the properties of StdMaterial (scripts referencing these properties will trigger a warning on scene load and Lua script errors)

Deprecated

Deprecates old Lua PRS methods for accessing transform properties and adds new methods to use and access transform properties on nodes with a more consistent interface

Fixed

Fixes issue where a Lua script call to find() could fail when searching for children of a node with the same name

1.2.1

Released 2016-06-09

Changed

Lua functions registered with vrAddNodeObserver and similar, now have valid __Script and __Self registers when called

1.1

Released 2014-10-24

Added

Adds Lua interface for creating toolbars on the Tools window
Adds Lua interface to our maths library, allowing scripts to work with vectors, matrices, quaternions, spheres, bounding boxes and rays

Changed

Lua plugins are now automatically loaded from the Documents directory as well as the install directory

2025.1​

Changed​

Fixed​

2024.3​

Added​

2024.2​

Added​

Removed​

Fixed​

2024.1​

Added​

Fixed​

2023.2​

Added​

2022.2​

Fixed​

2022.1​

Changed​

2021.3.1​

Fixed​

2021.3​

Changed​

2021.2​

Added​

Changed​

Deprecated​

Fixed​

2021.1.1​

Changed​

2021.1​

Added​

Changed​

Fixed​

2020.2​

Added​

Changed​

Fixed​

2020.1​

Added​

Deprecated​

Fixed​

2019.5​

Fixed​

2019.3​

Added​

Changed​

Fixed​

2019.2​

Added​

2019.1​

Fixed​

2.2​

Changed​

Removed​

Fixed​

2.1​

Added​

Changed​

Fixed​

2.0​

Added​

Changed​

Deprecated​

Removed​

Fixed​

Lua Event Coroutines​

Introduction​

Gotchas​

Global Variables​

Recompiling Coroutines​

Managing Sleeping Coroutines​

Lua Observers​

Transform Node Observer​

Difference from property observer​

Example​

Changes to Node and MetaNode Observers​

Node Observer​

MetaNode Observer​

Pivot API​

Creation​

2025.1

Changed

Fixed

2024.3

Added

2024.2

Added

Removed

Fixed

2024.1

Added

Fixed

2023.2

Added

2022.2

Fixed

2022.1

Changed

2021.3.1

Fixed

2021.3

Changed

2021.2

Added

Changed

Deprecated

Fixed

2021.1.1

Changed

2021.1

Added

Changed

Fixed

2020.2

Added

Changed

Fixed

2020.1

Added

Deprecated

Fixed

2019.5

Fixed

2019.3

Added

Changed

Fixed

2019.2

Added

2019.1

Fixed

2.2

Changed

Removed

Fixed

2.1

Added

Changed

Fixed

2.0

Added

Changed

Deprecated

Removed

Fixed

Lua Event Coroutines

Introduction

Gotchas

Global Variables

Recompiling Coroutines

Managing Sleeping Coroutines

Lua Observers

Transform Node Observer

Difference from property observer

Example

Changes to Node and MetaNode Observers

Node Observer

MetaNode Observer

Pivot API

Creation