/
Using the VortexRuntime API in Unity Scripts

Using the VortexRuntime API in Unity Scripts

Owned by Marc Lievin
Jan 11, 2023

To use Vortex in a Unity application, an API is provided with the Vortex Integration Package for Unity. To install it in a Unity project, read this guide: Installing the Vortex Studio Package in a Unity Project.

When the package is properly installed, the API is available as a C# class called VortexRuntime under the Vortex namespace. It grants access to Vortex functions from the standard Vortex Integration and provides some additional validation and utilities.


Tip: the ulong data type is used as a pointer (or handle) to Vortex objects that are loaded. For instance, you can use LoadMechanism to load a particular mechanism file and then use its handle to get or set data. Don't forget to unload it!

VortexRuntime Class

VortexRuntime MethodDescription
Simulation Helpers
bool CreateVortexApplication(VortexSettings settings = null)Creates the Vortex application. You can specify an optional VortexSettings argument, which is a simple class that defines some settings such as the Vortex Setup Document (vxc) that will be used during simulation.
bool UpdateVortexApplication()Updates the Vortex application.
void DestroyVortexApplication()Destroys the Vortex application.
void ResetSimulationTime()Resets the simulation time to 0.
bool SetApplicationMode(int mode, bool waitForModeToBeApplied)Changes the application mode (editing, simulating, playback).
bool StartSimulation()Starts the simulation.
void StepOnce()Steps the application only once and pauses.
bool StopSimulation()Stops the simulation.
bool Pause(bool pause)Pauses the simulation.
bool IsPaused()Returns if the simulation is currently paused.
uint GetFrame()Returns the current frame since the simulation started.
double GetSimulationFrameRate()Returns the simulation framerate.
double GetSimulationTime()Returns the current simulation time.
double GetSimulationTimeStep()Returns the time step between the each simulation frame.
Content Helpers
ulong LoadMechanism(string mechanismFile, double[] position, double[] orientation)Loads a Vortex mechanism from a file path at the specified position and orientation.
bool UnloadMechanism(ulong mechanismHandle)Unloads the specified mechanism.
ulong LoadScene(string sceneFile)Loads a Vortex scene from a file path.
bool UnloadScene(ulong sceneHandle)Unloads the specified scene.
ulong GetChildByName(ulong objectHandle, string childName)Looks for and returns the child object of another object, using its name.
void GetParentTransform(ulong objectHandle, double[] translation, double[] scale, double[] rotationQuaternion)From an object handle, returns the parent transform of this object as reference arguments.
Others
string GetCommandLineArguments()Returns the command line arguments set to the application.
bool IsVortexLicenseValid()Checks if the Vortex license is valid.
bool VortexApplicationCreatedChecks if the the Vortex application is created. Also initializes the Vortex Runtime if it was not already. (Note: this is not a method, but a property)

Furthermore, these next methods can be used to get or set data from and to Vortex, respectively.

MethodDescription
Accessing Data from Vortex to Unity
bool GetOutputBool(ulong objectHandle, string interfaceName, string outputName)Returns the boolean value of a particular VHL interface's output field from the specified Vortex object.
int GetOutputInt(ulong objectHandle, string interfaceName, string outputName)Returns the integer value of a particular VHL interface's output field from the specified Vortex object.
double GetOutputReal(ulong objectHandle, string interfaceName, string outputName)Returns the real value of a particular VHL interface's output field from the specified Vortex object.
string GetOutputString(ulong objectHandle, string interfaceName, string outputName)Returns the string value of a particular VHL interface's output field from the specified Vortex object.
Vector2 GetOutputVector2(ulong objectHandle, string interfaceName, string outputName)Returns the vector2 values of a particular VHL interface's output field from the specified Vortex object.
Vector3 GetOutputVector3(ulong objectHandle, string interfaceName, string outputName)Returns the vector3 values of a particular VHL interface's output field from the specified Vortex object.
Vector4 GetOutputVector4(ulong objectHandle, string interfaceName, string outputName)Returns the vector4 values of a particular VHL interface's output field from the specified Vortex object.
PositionRotation GetOutputMatrixAsPositionRotation(ulong objectHandle, string interfaceName, string outputName)Returns the position and rotation values of a particular VHL interface's output field from the specified Vortex object. PositionRotation is a simple class that regroups transform data (position, rotation, scale).
bool GetGraphicNodeData(ulong nodeHandle, ref GraphicNodeData graphicNodeData)(Advanced) For a specified Vortex graphics node object, returns its data in a struct. See GraphicNodeData from Vortex.Types namespace.
bool GetGraphicsNodeHandles(ulong objectHandle, ulong[] nodeHandleArray, ref uint nodeHandleCount)(Advanced) From a specified Vortex object, returns an array of handles to graphics nodes in this object.
Sending Data from Unity to Vortex
void SetInputBoolean(ulong objectHandle, string interfaceName, string inputName, bool value)Sets the boolean value of a particular VHL interface's input field from the specified Vortex object.
void SetInputInt(ulong objectHandle, string interfaceName, string inputName, int value)Sets the integer value of a particular VHL interface's input field from the specified Vortex object.
void SetInputReal(ulong objectHandle, string interfaceName, string inputName, double value)Sets the real value of a particular VHL interface's input field from the specified Vortex object.
void SetInputString(ulong objectHandle, string interfaceName, string inputName, string value)Sets the string value of a particular VHL interface's input field from the specified Vortex object.
void SetInputVector2(ulong objectHandle, string interfaceName, string inputName, Vector2 value)Sets the vector2 value of a particular VHL interface's input field from the specified Vortex object.
void SetInputVector3(ulong objectHandle, string interfaceName, string inputName, Vector3 value)Sets the vector3 value of a particular VHL interface's input field from the specified Vortex object.
void SetInputVector4(ulong objectHandle, string interfaceName, string inputName, Vector4 value)Sets the vector4 value of a particular VHL interface's input field from the specified Vortex object.
void SetInputMatrix(ulong objectHandle, string interfaceName, string inputName, Transform value)Sets the Matrix4x4 value of a particular VHL interface's input field from the specified Vortex object.
void SetInputExtensionPointer(ulong objectHandle, string interfaceName, string inputName, ulong value)Sets the extension pointer value of a particular VHL interface's input field from the specified Vortex object. The extensions pointer is also a handle of type ulong.

Vortex Unity Components

Some Unity components were made to work in tandem with VortexRuntime, and provide an easy way to load Vortex content in Unity. Here they are:

  • VortexMechanism: Can be used to load a Vortex mechanism (vxmechanism) by specifying the file path to the component. Its object handle can then be accessed from code any time.
  • VortexScene: Can be used to load a Vortex scene (vxscene) by specifying the file path to the component. Its object handle can then be accessed from code any time.

Related content