How to associate prefabs and Vortex documents in a Unity project

To complement the scene creation workflow in Unity, a simple tool was put in place. It allows to easily and quickly set up a Unity scene associated to a Vortex scene. It also eases the addition of mechanisms, from Unity, in an existing scene.

Overview

This tool is simply a list of prefabs that is defined in an asset file from the project. When any of these prefabs contain either a VortexMechanism, VortexAssembly or VortexGraphicsGallery component with a valid path to the corresponding Vortex document (.vxmechanism, .vxassembly or .vxgraphicgallery, respectively), the Vortex integration will try to instantiate them when possible, depending on if the associated Vortex documents are getting loaded for the first time.

Specifically, this happens in two cases:

1. When associating a Vortex Scene to a Vortex-Unity scene (see this page for more information on this topic: Associate a Unity Scene and a Vortex Scene)

   1. If a mechanism, assembly or graphics gallery is in the Vortex scene, their Vortex document file path will be used to find a prefab with the matching path in the list. If found, the prefab is instantiated. If not, simple empty Game Objects are created, only containing its respective Vortex component (VortexMechanism or VortexGraphicsGallery).
      
      

2. When adding a Vortex Mechanism or Assembly to a Vortex-Unity scene (see this page for more information on this topic: Add Vortex Mechanism or Assembly to a Unity scene)

   1. When a mechanism is added from the Vortex menu, if the mechanism file is found to be on any prefab in the list, it will be instantiated in the scene.

   2. When a mechanism or assembly is added from the Vortex menu, if it contains a graphics gallery and if this graphics gallery is found to be on any prefab in the list, it will be instantiated in the scene.

Open

Here, an instance of the Excavator prefab was added to the scene automatically when it was associated to its Vortex scene, because its prefab was added to the project’s list.

Generating or accessing the list of Vortex prefabs

The prefab list is saved in an asset that is generated automatically when using the menu button. This button can be found in the Editor, in the Vortex menu, under Vortex>Edit Vortex Prefab List…

Open

When clicked for the first time, it creates the VortexPrefabList.asset file under the Asset/Vortex folder of the project. On subsequent clicks, this file will be selected to be edited and saved.

Here is an example of the prefab list asset:

Prefabs corresponding to Vortex objects should be added in this list. For instance, prefabs for mechanisms or graphics galleries that are re-used in different scenes.

Creating Vortex prefabs

Unity prefabs are a type of asset that allows to save a specific game object as a template, along with its own children objects, and re-use it easily in a project. With the Vortex integration, we use this principle for re-usability across different Vortex-Unity scenes by associating prefabs to specific Vortex documents. Essentially, when associating or loading a Vortex scene or when adding a mechanism or assembly from the Vortex menu, the project’s list of Vortex prefabs is queried to find a prefab matching a specific Vortex document (meaning with the proper component), such as a Vortex Mechanism, Vortex Assembly, or Vortex Graphics Gallery.

Making a prefab for a Graphics Gallery

To create a prefab from a graphics gallery, you need to:

1. If your graphics gallery contains 3D graphics, import its 3D model in the project, such as a FBX file.

2. Add this model to any Unity scene.

3. If needed, adjust the object hierarchy to make it match the gallery’s hierarchy (including object names). Especially for the root object and children object corresponding to Graphics Nodes, if any.

4. On the root object, corresponding to the graphics gallery, add the Vortex Graphics Gallery component.

5. In this component, set the path to the corresponding Graphics Gallery document.

6. Drag and drop the root object into the Unity Editor’s Project panel, in any folder under the Assets folder, to save it as a prefab.

7. Add the prefab to the list of Vortex prefabs of your project, for later re-use.

Making a prefab for a Mechanism or Assembly

To create a prefab from a mechanism or assembly, you need to:

1. Associate a Vortex scene (containing a mechanism or assembly) to a Unity scene.

2. Prepare your mechanism’s or assembly’s graphics gallery prefab, if needed.

3. Add a Mechanism or Assembly to the scene using the Vortex menu.

4. Customize the object (or its children) as needed, while keeping the same object hierarchy as the corresponding Vortex document.

5. In the scene, find the objects corresponding to the mechanism or assembly that you want to re-use as a prefab.

6. Select the root object (containing either the Vortex Mechanism or Vortex Assembly components, which are added automatically), and drag and drop it into the Unity Editor’s Project panel, in any folder under the Assets folder, to save it as a prefab.

7. Add the prefab to the list of Vortex prefabs of your project, for later re-use.

Re-using assets from the prefab list

With these prefabs added to the list, this means that we can now easily reuse these assets in different scenes. For instance, let’s say we create a copy of the Excavator Scene (Excavator.vxscene) from the demo scenes. To create a new Vortex-Unity scene from this copy, we can simply create a new Unity scene and associate it to the Vortex scene’s copy from the menu button.

Then, after the scene is initialized based on the Vortex scene’s hierarchy and prefab list from the project, we can see that these objects were added automatically: