How to Display Vortex Cables in Unity
- Marc Lievin
Cables, dynamically simulated in Vortex Studio, can be rendered in Unity during simulation. When a cable is loaded, a spline prefab is loaded from an asset bundle file located in the same directory as the Vortex file that contains the cables.
Manually creating prefabs and Asset Bundles
To manually create assets for the cables, a Unity project with the Vortex Integration Package is needed (such as VortexUnityTools or your own project), some spline prefabs must be added and the assets must be packaged in an asset bundle.
For an overview of the assets workflow, refer to How to associate Vortex Objects with Unity prefabs.
Spline Prefabs
At simulation time, when a spline instance is added, the Vortex Integration will look for a spline prefab with a specific name. The prefab name must contain the graphics cable hierarchy with the graphics cable name from the Vortex Editor explorer. The hierarchy levels are separated with period characters. Folders are omitted from the hierarchy. The name and hierarchy are case sensitive.
For example, if we open the excavator mechanism with the Vortex Editor, we can see that we have this tree:
The corresponding prefab name for the first cable would be "Hydraulic Turret Boom LB.Graphics". The "Hydraulic Cables" folder is omitted, Vortex Editor's folders have no impact on the hierarchy. The root instance name "Excavator" is omitted since it will change depending on the context.
Creating a Spline Prefab
The spline prefab must have a Vortex Spline component and a Vortex Spline Renderer component. To create a simple cylindric spline prefab in Unity:
- Create an empty GameObject
- Rename it with the proper name (see the Spline prefabs section introduction)
- Select the created GameObject and add the VortexSpline and VortexSplineGpuCylinderRenderer components in the inspector
- Create a new material based on the SplineGPUMeshDefaultShader and assign it to the VortexSplineCylinderRenderer material field
- Drag and drop the GameObject somewhere in an Assets folder in the project window to create a prefab. In this example, it is saved under the Excavator folder.
In the following section, we present in great detail the required components that compose a spline prefab.
The VortexSpline Component
The VortexSpline component is in charge of managing the control point arrays and to updating the renderers.
The Spline Renderer Components
We currently have these renderer components available
- VortexSplineCylinderRenderer
- VortexSplineGpuCylinderRenderer
- VortexSplineInstancedMeshRenderer
The VortexSplineCylinderRenderer Component
This component is used to render cylindrical meshes along the spline.
The mesh is generated in the renderer script every frame.
These public fields can be configured through the inspector:
| Field | Description |
|---|---|
| Material | The material that we want to assign to the generated mesh |
| Num Sides | The number of side composing the cylinder |
| Radius | The radius of the cylinder |
Note: Since the control points and the texture coordinates are generated on the Vortex side, the texture repeat period has to be edited from the Vortex Editor, not on the assigned Unity material.
The VortexSplineGpuCylinderRenderer Component
This component is also used to render cylindrical meshes along the spline, but the vertices are computed on the GPU. The VortexSplineCylinderRenderer can be too slow when too many cables must be rendered. The VortexSplineGpuCylinderRenderer component parallelize the work with compute shaders. The material applied to the GPU generated spline must be based on a custom shader.
These public fields can be configured through the inspector:
| Field | Description |
|---|---|
| Material | The material that we want to assign to the generated mesh. The material must be based on the SplineGPUMeshDefaultShader. |
| Num Sides | The number of side composing the cylinder |
| Radius | The radius of the cylinder |
| Material Compute Buffer | Name of the ComputeBuffer in the custom shader that contains the vertices data. |
The VortexSplineInstancedMeshRenderer Component
This component is used to render mesh instances along the spline.
A mesh can be assigned to the renderer with a local transform and a material.
These public fields can be configured through the inspector:
| Field | Description |
|---|---|
| Material | The material that we want to assign to mesh instances. Enable GPU Instancing must be activated on the material. |
| Mesh | The mesh that we want to instantiate along the spline |
| Mesh Position | A position offset for the mesh |
| Mesh Rotation | A rotation offset for the mesh |
| Mesh Scale | A XYZ scaling factors to apply to the mesh |
Since the control points are generated on the Vortex side, to get enough evenly distributed control points, the Graphics Cable parameters in Vortex must be tweaked. The Technique must be set to "Mesh". The distance between the control points will depend on the associated Graphics Geometry size and the "Mesh Overlap" parameter. To get mesh instances with alternate orientations, enable "Alternate Mesh Rotation".
The VortexSplineStrapRenderer Component
This component is used to render strap meshes computed on the GPU. The material applied to the GPU generated spline must be based on a custom shader.
These public fields can be configured through the inspector:
| Field | Description |
|---|---|
| Material | The material that we want to assign to the generated mesh. The material must be based on the SplineGPUMeshDefaultShader. |
| Radius | The width of the strap |
| Roundness | Thickness ratio to the strap width |
| Material Compute Buffer | Name of the ComputeBuffer in the custom shader that contains the vertices data. |
The SplineGPUMeshDefaultShader Shader
Materials based on the SplineGPUMeshDefaultShader shader exposes these parameters:
| Field | Description |
|---|---|
| Base Map | The albedo color texture |
| Base Color | Multiplication color for the albedo |
| Normal Map | The normal texture |
| Metallic | Determines how “metal-like” the surface is (between 0 and 1) |
| Smoothness | Determines how smooth the surface is (between 0 and 1). |
| Tiling And Offset | UV tiling (X, Y components) and UV offset (Z, W components) for the applied Base Map texture |
Creating an Asset Bundle
Once the spline prefabs are created, they can be packaged in an asset bundle so that they can be loaded by VortexUnityApp, or your own similar Unity application with Vortex Integration.
The process for generating an asset bundle is described in this section.
In order to get VortexUnityApp to load the asset bundle properly, the asset bundle file should be placed in the same folder where is stored the Vortex file that contains the cables.
For example, for the Excavator, we would have: