How to Automatically Convert many Vortex Graphics Galleries for use in Unity

When using Unity as a renderer with Vortex, each graphics node of a distributed simulator runs VortexUnityApp (or any Unity application with the Vortex Integration Package) which includes the Vortex Integration for Unity. VortexUnityApp acts the same manner as SimApp which is the Vortex Standard executable for simulations.

As of our current implementation, any Vortex graphics gallery must be associated to a Unity prefab contained within a Unity Asset Bundle. The Vortex integration relies on this association to display the correct 3D models and textures in a Vortex simulation.

More details on this page: How to associate Vortex Objects with Unity prefabs

Manually converting many graphics galleries takes a lot of time, so a tool was made to ease this process for larger amounts of assets. 

In short, it is a Python 3 script that exports Vortex graphics galleries into FBX files, which then runs the Unity Editor in batch mode to import those files into Unity. Prefabs are then generated from these models, and each one is packaged in an asset bundle that is finally put next to its respective graphics gallery. All assets from which the bundles are made are also added inside the Assets folder of the VortexUnityTools project, which comes installed with Vortex. They can be found under VortexUnityTools\Assets\Imported Vortex Assets\Graphics Galleries\<Gallery Name>. You can then modify those assets and re-export them into Asset Bundles as needed using the Vortex > Export As Asset Bundle... contextual action on a prefab or asset folder.

Vortex graphics galleries (SimApp) vs Unity asset bundles made with this tool (VortexUnityApp)

Required Setup

In addition to Vortex Studio and Unity, some initial setup is required:

• The script is for Python 3.8, so it needs to be installed.
• The script uses the Vortex Python 3 module. Using the script from C:\CM Labs\Vortex Studio 2021b\bin will find the module automatically without any setup.

How to Use

Now that everything is installed, the conversion tool can be used.

1. Open a command prompt and navigate to the Vortex Studio bin folder. To do this, open the Windows Start menu and type cmd. Navigate to the folder by entering cd C:\CM Labs\Vortex Studio 2021.2\bin and pressing Enter.
   Alternatively, you can open the folder from the Windows explorer and enter cmd directly from the directory path at the top.
2. To run the script with Python, type the path to python.exe followed by the script's file name and desired arguments. 

3. To show the script's different arguments and their descriptions, type the script's file name followed by -h or --help.
   Example: C:\Python38\python.exe VortexToUnityAssetConverter.py --help
   
   

   
   Here is some more information, with examples:

   Argument	Value	Description	Example	Required/Optional
   -h, --help	none	Will display the list of arguments with short descriptions.	C:\Python38\python.exe VortexToUnityAssetConverter.py -h	Optional (standalone)
   -r, --root	path to a directory	Path of the root directory containing Vortex graphics galleries (sub-directories are considered). Asset Bundles will be generated next to their galleries.	C:\Python38\python.exe VortexToUnityAssetConverter.py -r "D:\Assets\Graphics"	Required
   -e, --unity_editor	path to a file	Full path of Unity.exe file to be ran for asset processing. By default, Unity.exe is looked for in C:\ProgramFiles\Unity\2020.3.20f1\Editor\Unity.exe and C:\Program Files\Unity\Hub\Editor\2020.3.20f1\Editor\Unity.exe	C:\Python38\python.exe VortexToUnityAssetConverter.py -r "D:\Assets\Graphics" -e "C:\Program Files\Unity\2019.4.14f1\Editor\Unity.exe"	Optional
   -o, --overwrite	none	If specified, all asset bundles will be generated, and any existing one will be replaced. By default, they will be skipped if they already exist.	C:\Python38\python.exe VortexToUnityAssetConverter.py -r "D:\Assets\Graphics" -o	Optional
   -p, --project	path to a directory	Full path of the Unity project that will be used for extracting the content. All extracted content will be put in this project Asset directory. By default the project is VortexUnityTools.	C:\Python38\python.exe VortexToUnityAssetConverter.py -r "D:\Assets\Graphics" -p "E:\Unity\MyProject"	Optional

4. Enter your command line, then press Enter to execute it. Wait for it to end. If successful, a message is shown and asset bundles will have been generated. 
5. The amount of galleries found, exported and skipped is shown, as well as the amount of asset bundles that were generated.
   Here's a demo video for generating one asset bundle from a graphics gallery: 
   

Tool Overview

When the program starts, it will execute these following steps. The time it takes depends on the amount of graphics galleries to process.

1. It looks through the root directory and its sub-directories for any graphics galleries, and exports them as FBX files, along with textures.

2. After each export to FBX, it launches the Unity Editor from command line and calls an editor script with relevant arguments. 
3. It then imports the FBX file and its textures in Unity. This step can take a bit of time, depending on the complexity of the model and how many textures it has. A new folder is created to contain the assets respective to this gallery.
4. A prefab is made from each 3D model (FBX file).
5. The prefab is modified to support shadow volumes by searching for graphics nodes following a certain naming convention: "SV" or "shadows". These nodes will cast shadows. Otherwise, shadows will be disabled for all other nodes.
6. Each prefab is packaged into an asset bundle, which contains the 3D model and textures that the prefab references. This step also takes a bit of time.
7. Each generated asset bundle is added in the folder corresponding to its graphics gallery. 
8. Imported assets for this gallery remain inside the VortexUnityTools project (or other specified project), under VortexUnityTools\Assets\Imported Vortex Assets\Graphics Galleries\<Gallery Name>.
9. A message is shown to inform if the execution was successful or not.
10. If there are problems with the Unity steps, you can check the Editor's log file, which can be found in AppData\Local\Unity\Editor\Editor.log.

Limitations

Some asset bundles need manual correction after conversion. In this case, a new bundle must be generated from the imported assets in VortexUnityTools project. 

To generate an asset bundle manually, refer to this page: How to Display a Vortex Graphics Gallery in Unity

For instance, Materials with transparency or Dither effect need manual intervention.
Here are some examples with the Unity Rendering Mode equivalent.

To be able to change the material rendering mode, 
The materials need to be extracted before importing the fbx (Extract Materials is not available through Unity API, only in Editor).

As an example, here are the steps to fix the opaque windows of the excavator from the demo scenes:

1. Export the excavator graphics gallery to fbx and open it in the Unity EditorSelect the fbx and click Extract Materials... on the Materials tab of the Inspector.
   
   
   
2. Once the materials are extracted we can see they are not inside the fbx anymore, they are in the materials directory selected at extraction
   
   
   
3. Drag the excavator fbx to the scene
   
4. Fix the Shadow volume as explained 3486827721
   
5. Open the materials directory and select the material to edit (Excavator_Windows_Material)
   
   
   
6. Change the windows rendering mode to Transparent
   
   
   
7. Put back the original alpha channel value to the Aldebo color
   
   
   
8. Drag the excavator game object to the assets to create the original prefab so it can be exported to and asset bundle
   
   
   
9. You now have a prefab with transparent windows