This page describes the workflow to create, maintain and use Unity assets in a distributed Vortex Studio simulation. 

Installing the Vortex Integration Package in a Unity Project

First of all, the Vortex Integration Package needs to be installed in a Unity project. It contains all necessary tools to prepare, test and use Vortex objects using Unity graphics. In particular, it provides:

• Running a Vortex Simulation directly in the Unity Editor via the Vortex Player. From the Player, you can load and unload documents, as well as start and stop a Vortex simulation. 
• Some Vortex-specific components, such as the Vortex Spline and Spline Renderer components.
• A straightforward Editor-based packaging tool to package Asset Bundles, which can be loaded by any Unity application that includes the Vortex Studio Integration package.

For detailed installation steps, please refer to: Installing the Vortex Studio Package in a Unity Project.

Preparing Unity Prefabs and Asset Bundles

When using the Vortex Graphics Integration with Unity, Vortex objects must be associated to prefabs in Unity. Each Vortex object has a name and is part of the simulation's object hierarchy. Since graphics are handled by Unity, a mapping must be made between Vortex objects and Unity Game Objects. A Game Object hierarchy saved as an asset is called a prefab. Those prefabs must be exported into Asset Bundles, which are containers of Unity assets to be loaded at runtime. For any supported Vortex graphics gallery loaded in a simulation, the Graphics Integration in Unity will look for a corresponding asset bundle containing a corresponding prefab. This prefab will then be instanced and updated every frame according to the Vortex simulation, depending on what type of extension it is. Generally, any change in the extension's inputs will be reflected in the instanced Unity GameObject corresponding to it.

Associating a Prefab to a Vortex object

In general, mapping of a prefab to a Vortex object is done via the object's name, since names of Vortex objects in a hierarchy are unique. This means a prefab and any of its Game Objects must have the same exact name as their Vortex object to be associated and instantiated in Unity. 

Here is an example with a simple Graphics Gallery.

Notice how the gallery and node in Vortex have equivalent objects in Unity.

Furthermore, the Asset Bundle containing this prefab must be placed next to the Vortex document's file that defines it.

Here is how this applies in practice for some object types:

• The Vortex Graphics Gallery must have a corresponding GameObject as the prefab's root.
• To maintain a vortex Graphics Gallery's node hierarchy, GameObjects corresponding to Vortex Graphics Nodes should have the same name as the node's.
• A bundle containing a prefab for a Vortex Graphics Gallery must be placed next to its vxgraphicgallery document file.
• A bundle containing a prefab for a Vortex Graphics Spline must be placed next to its containing vxscene, vxmechanism or vxassembly document file.

Supported Vortex Extensions

So far, here is the list of Vortex graphics extensions that are supported and handled by the Graphics Integration in Unity:

• Graphics Galleries.
  For the complete process on creating graphics in Unity for Vortex Graphics Galleries, refer to: How to Display a Vortex Graphics Gallery in Unity.
  For generating many Galleries at once with a tool, see: How to Automatically Convert many Vortex Graphics Galleries for use in Unity.
  Graphics Galleries are composed of Graphics Nodes, which are associated to GameObjects under the prefab root GameObject in Unity.
  
  
• Graphics Cables : Splines
  For the complete process on creating Graphics Splines in Unity for Vortex cables, refer to: How to Display Vortex Cables in Unity
  
• HUD Text and HUD Image.
  For more information on the HUD creating process in Unity, refer to: How to Display HUD Extensions in Unity
  
• Vortex Lights : How to Control Unity Lights from Vortex
  The Unity component will be connected to a Vortex Light extension. Changes to the on/off state and the the position and orientation of the Vortex light will be applied to the Unity light.
  
• Display Loading Images

For the complete process on creating Loading Images in Unity, refer to: How to set Loading Images in Unity

For each of these extensions, the graphics content must be made in Unity and added to a prefab, and packaged into an Asset Bundle that corresponds to a Vortex document.

Exporting into an Asset Bundle

When you are satisfied with a prefab, you can package it into an asset bundle, along with its related assets (these are the assets referenced by its different Components). A contextual action has been added to do exactly this.

A Unity Asset Bundle is a file that contains Unity assets to be loaded at runtime only (it cannot be edited). They can be loaded by any Unity application, which is a concept similar to how Vortex Studio asset files can be used in any Vortex Studio simulation.

Here is how to use it:

1. First, find the desired assets in your Unity project, via the Unity Project window. This action is only available when selecting a prefab asset or a folder that contains prefabs.
   Note: this function also supports multi-selection, so many asset bundles can be created at once.
   In this example, we have cone assets (FBX file, textures, and a prefab) inside a "Cone" folder.
   
2. Right-click the prefab. In the contextual menu, select Vortex > Export Asset Bundle...
   
   
3. Choose a destination folder.
4. The prefab and its related assets will be packaged into an asset bundle file, with extension .unity3d. Its name will be based on the selected prefab (or folder).
5. Make sure to place this file in the same folder as its corresponding Vortex asset file, with the same name too.
6. At this point, your asset bundle should be ready to be tested or used in a simulation.

Loading Vortex documents in a Vortex simulation with Unity

Once you have mapped Vortex objects with Unity graphics and would like to use them in a Vortex simulation, there are a number of ways to go about it. Here they are:

In Unity Editor

1. Make sure your project has the Vortex Integration package.
   See Installing the Vortex Studio Package in a Unity Project.
   An example project can be found in the Vortex Studio bin folder: VortexUnityTools.
2. Enter Play mode in Unity by pressing the Play button in the Unity Editor.
   
3. This will launch a Vortex window. From it, you can load Vortex documents directly in the Unity Editor and Start/Stop the simulation.
   You can do these operations as long as you are in Play mode.
   If the Vortex documents you load have asset bundles associated to them, they will be loaded directly in the current open scene.
   
4. You can quit using Unity's Play button again, or with the Vortex window's X button.

In Unity Player (VortexUnityApp)

1. Find the VortexUnityApp executable from Vortex Studio's bin folder.
2. Start VortexUnityApp.
   It will open up a Unity graphics window, and a Vortex interface from which you can load any Vortex document.
   
3. From this Vortex interface, you can load Vortex documents in Unity and Start/Stop the simulation.

In Unity Player (custom Unity application integrating Vortex)

1. It is also possible to generate your own Unity application from your project, using the Unity Build Settings from the File menu of the Unity Editor.
   This application fills the same role as VortexUnityApp, so it can be used either directly or as a graphics node in a Vortex distributed simulator.
2. Please note that a Unity application needs a default scene, set in the Build Settings window.
   Unity always loads the first scene in the list by default.
   
3. To build your application, press the Build button:
   
4. Run your application from the generated executable.
   It will launch a Vortex window and the Unity application.
   
5. The Vortex window can now be used to load Vortex documents in Unity and Start/Stop the simulation.

This built application can also be used in a distributed simulator, as described in section 4).

In Unity Player with Vortex Director (distributed simulation)

Note that these past methods are not for distributed simulators. For a distributed simulator, the Vortex Director must be used with a compatible setup file (vxc).

See this section of this page for details on adapting a distributed Vortex simulator with Unity graphics.

How-tos