Using the VortexRuntime API in Unity Scripts
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 Method | Description |
|---|---|
| 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 VortexApplicationCreated | Checks 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.
| Method | Description |
|---|---|
| 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.