Content Packaging

Owned by Marc Lievin
Mar 14, 2024
3 min read

Content Packaging Overview

A content package contains all the assets and information necessary to run all exercises for an Equipment category, in the form of a folder structure.

A vxpackage file is a special archive that contains a content package folder structure, and designed to work with VortexSetup.

VortexSetup installs the content of .vxpackage files on the target computer(s) for installed packages and register them to be used by Vortex applications. (such as setting the Windows registry accordingly).

When Vortex Launcher starts, the Windows registry information to locate all installed Equipment packages is looked up.

After an Equipment is chosen by the user, Vortex Launcher starts a simulator that can run the exercises associated with this Equipment.

VortexEditor provides an easy way to create a package folder structure, by using the "Add Project..." button in the Asset Browser. See Asset Browser for more information.

Package structure

The following describes the standard vxpackage structure.

where :

  • assets : contains all the Vortex scenes, mechanisms, assembly, python scripts, etc. that are used at runtime

  • assets/Scenario : contains the Equipment (*.vxequipment) and Exercise (*.vxexercise) files

  • bin : if available, it contains the Unity executable (*.exe) built from the Unity project

    • The .exe file must have the exact same name as the .vxequipment file found in assets/Scenario

  • localization: all files needed for the package translation

  • plugins : if available, it contains additional plugins (.dll) that will be used by the this Equipment

  • resources/config : contains the Setup files (*.vxc)

  • resources/simulators : contains the Topology files (*.vxsimulator)

  • a manifest file at the root (*.vxmanifest)

  • optional: package.info

Vortex manifest file

.vxpackage archives always contain a .vxmanifest file at the root.

The manifest file contains all the information necessary to install the package content.

Note that the manifest file name must match the package filename.

Manifest elements:

  • "formatVersion": version of the format of the current file

  • "displayName": name of the equipment followed by a version number (Major.Minor)

  • "packageName": name of the equipment

  • "installationSubDirectory": name of the folder where the package should be installed, under the folder set by VortexSetup

  • "packageVersion": full version of the equipment (Major.Minor.Revision.Build)

  • "vortexStudioVersion": full version of the Vortex Studio installation needed to run the equipment (Major.Minor.Revision.Build)

  • "description": short description of the equipment

  • "category": category of this installation, will most probably be "Simulation"

  • "createdBy": name of the company

  • "targetPlatform": "Windows"

  • "dependencies": list of dependencies needed by the current equipment

    • "packageName": name of the Vortex package needed to run the equipment

    • "category": category of that package

Package info

A package may be tagged to be ignored by Vortex Launcher.

A JSON file named package.info needs to be placed in the package’s installation folder (alongside the .vxmanifest file), with the ”useInLauncher” field set to false:

Package creation

To generate a package:

  • Prepare the folder structure as shown above.

  • Add a manifest file in the root (and a package.info file if needed)

  • Use 7zip to create the archive

    • Add all files and folders contained in the root of the working package folder to the archive

      • assets

        • Scenario

      • bin

      • plugins

      • resources

      • EquipmentA_2023.7.0.1234.vxmanifest

      • package.info

    • Save the archive as

      • EquipmentA_2023.7.0.1234.vxpackage (same name as the manifest inside of it)

Package installation

VortexSetup

It is mandatory to use VortexSetup to install an Equipment from a .vxpackage.

To install a custom .vxpackage file:

  • Download or locate VortexSetup.exe.

  • Move or copy VortexSetup to an empty folder.

  • Move or copy your custom .vxpackage file in the same folder as VortexSetup.exe

  • Start VortexSetup from that location (by double clicking or starting in cmd)

  • Choose “Install on Desktop” or “Install on Simulator”

  • Your package should appear in the list of available products in the “Install Stage”.

  • Make sure the package is already selected.

  • In the Component Stage, locate the Vortex Studio version needed by the currently installed package

    • It should be greyed out, and automatically selected if it is not already installed.

  • Follow the remaining steps in VortexSetup.

Content Package Registry keys

In order to be visible by the Vortex Launcher, a content package must have a set of standard registry keys.

These keys are written by VortexSetup when installing packages.

VortexLauncher will look at the registry entries under HKEY_CURRENT_USER\SOFTWARE\CM Labs\[PackageName]

The following keys are mandatory

  • InstallLocation : the root path of the package installation

  • ProductVersion : the version of the package

  • VortexVersion : the Vortex toolkit version to use to use the content package

  • ManifestFile : the name of the manifest file (just the file name, not the path)

When using .vxpackage containing a valid .vxmanifest file, all of this is handled automatically.