Skip to main content

​
Overview

The DMX Patch Exporter provides tools for persisting and exporting DMX fixture patch data from your Unity scene. This system allows you to:
  • Save patch data to survive scene corruption or Unity crashes
  • Load previously saved patch configurations
  • Export patch data for use in external lighting software
  • Generate documentation for your lighting setup
The DMX Patch Exporter requires a VRSL_LocalUIControlPanel component in your scene. All operations work with the currently active scene.

​
Accessing Patch Exporter Functions

All patch exporter functions are accessible from the Unity menu bar: 
VRSL/
├── Save Patch Data
├── Load Patch Data
└── Export/
    ├── To JSON
    ├── To MVR
    └── To PDF (Windows)

​
Save Patch Data

​
Purpose

Saves the current DMX fixture configuration to a ScriptableObject asset for later restoration.

​
Workflow

1

Configure Your Fixtures

Set up all DMX fixtures in your scene with proper channel assignments, IDs, and properties using the VRSL Manager Window.
2

Save Patch Data

Navigate to VRSL > Save Patch Data in the Unity menu.
3

Asset Created

A VRSL_DMXPatchSettings asset is created in Assets/VRSL DMX Patch Folder/.The asset is automatically named: VRSL DMX Patch Data_[SceneName].asset
4

Verify Link

The VRSL_LocalUIControlPanel component is automatically linked to this asset via its fixtureSaveFile property.

​
Saved Data Includes

  • DMX universe assignments
  • DMX channel numbers
  • Fixture IDs
  • Fixture types (if defined)
  • Fixture names/GameObjects
  • All fixture-specific settings:
    • Intensity values
    • Color tints
    • Movement ranges (pan/tilt)
    • Inversions and offsets
    • Cone dimensions
    • Special feature toggles
Save patch data regularly when making significant changes to your lighting setup. This protects against scene corruption and makes it easy to revert changes.

​
First Save vs. Subsequent Saves

First Save:
  • Creates new VRSL_DMXPatchSettings asset
  • Creates VRSL DMX Patch Folder if it doesn’t exist
  • Links asset GUID to control panel
Subsequent Saves:
  • Overwrites existing linked asset
  • Preserves asset location and name
  • Updates all fixture data
If the linked patch data asset is deleted from the project, the next save will create a new asset. The link to the old asset will be automatically removed.

​
Load Patch Data

​
Purpose

Restores previously saved DMX fixture configuration to all fixtures in the current scene.

​
Workflow

1

Ensure Scene Match

Open the scene that corresponds to the saved patch data. Fixture GameObjects must exist in the scene with VRSL scripts attached.
2

Load Patch Data

Navigate to VRSL > Load Patch Data in the Unity menu.
3

Data Restored

All fixture properties are restored from the saved asset to matching fixtures in the scene.
4

Verify in Manager Window

Open the VRSL Manager Window to verify all settings were restored correctly.

​
How Fixtures Are Matched

The load operation matches saved data to scene fixtures using:
  1. GameObject name (primary identifier)
  2. GameObject hierarchy path (secondary verification)
  3. Component type (DMX vs. AudioLink)
Renamed or moved fixtures may not load correctly. Try to maintain consistent GameObject names and hierarchy structure.

​
Use Cases

  • Recovery: Restore patch after scene corruption
  • Iteration: Revert to known good configuration while experimenting
  • Collaboration: Share patch data between team members
  • Version Control: Maintain patch history alongside scene versions

​
Export Formats

​
Export to JSON

1

Access JSON Export

Navigate to VRSL > Export > To JSON
2

Choose Save Location

A file dialog opens. Select destination folder and filename.
3

JSON Created

A human-readable JSON file is created with complete patch data.

​
JSON Structure

{
  "sceneName": "MyLightingScene",
  "fixtures": [
    {
      "fixtureName": "Spotlight_001",
      "fixtureID": 100,
      "fixtureType": "Moving Head Spot",
      "dmxUniverse": 1,
      "dmxChannel": 1,
      "properties": {
        "globalIntensity": 1.0,
        "lightColorTint": "#FFFFFF",
        "maxMinPan": 180.0,
        "maxMinTilt": -180.0,
        "coneWidth": 15.0,
        "coneLength": 10.0,
        "invertPan": false,
        "invertTilt": false,
        "isUpsideDown": false
      }
    }
  ]
}

​
Use Cases

  • Version Control: Commit JSON to Git for tracking changes
  • Documentation: Human-readable patch reference
  • Integration: Import to web tools or custom scripts
  • Archival: Long-term storage format
JSON export is cross-platform and works on Windows, macOS, and Linux.

​
Export to MVR (My Virtual Rig)

1

Access MVR Export

Navigate to VRSL > Export > To MVR
2

Choose Save Location

A file dialog opens. Select destination and filename (.mvr extension).
3

MVR File Created

An MVR-compliant file is generated compatible with industry standard tools.

​
What is MVR?

My Virtual Rig (MVR) is an open standard file format for describing entertainment technology setups. It’s supported by:
  • MA Lighting grandMA2/grandMA3 - Import VRSL fixtures as console patch
  • Vectorworks Spotlight - Visualize VRSL rig in CAD environment
  • Vision/Capture/WYSIWYG - Previz software integration
  • GDTF Share - Fixture library compatibility

​
MVR Export Contents

  • Fixture positions (Unity world coordinates converted to MVR coordinate system)
  • DMX universe/address assignments
  • Fixture types (from Fixture Definitions)
  • Rotation/orientation data
  • Color and beam properties

​
Workflow Example: Unity to grandMA3

1

Export MVR from VRSL

Export your VRSL patch using VRSL > Export > To MVR
2

Import to grandMA3

In grandMA3 software:
  • Go to Patch menu
  • Import MVR file
  • Fixtures appear with matching addresses
3

Control VRSL from Console

Use grandMA3 with DMX output to control your VRSL fixtures in real-time
MVR export requires proper Fixture Definitions to be assigned to your fixtures for best results. Without definitions, fixtures export with generic types.

​
Export to PDF (Windows Only)

1

Access PDF Export

Navigate to VRSL > Export > To PDF (Windows)
2

PDF Generated

A formatted PDF patch sheet is automatically created and saved.
3

Open PDF

The system may automatically open the PDF in your default viewer.

​
PDF Patch Sheet Contents

  • Scene Name and export date
  • Fixture Table with columns:
    • Fixture ID
    • Fixture Name
    • Type (from Fixture Definition)
    • Universe
    • DMX Channel
    • Channel Count
    • Position (Unity coordinates)
    • Notes/Properties

​
Use Cases

  • Production Documentation: Print for venue reference
  • Load-In Sheets: Distribute to lighting crew
  • Client Deliverables: Professional documentation
  • Archival: Physical backup of patch
PDF export is currently Windows only due to platform-specific dependencies. Attempting to export on macOS or Linux will show an error dialog.

​
Workaround for macOS/Linux

  1. Export to JSON format
  2. Use online JSON-to-PDF converters
  3. Or write a custom Python/Node.js script to generate PDFs from JSON

​
Patch Data Asset Reference

​
VRSL_DMXPatchSettings

The ScriptableObject asset that stores patch data. Location: Assets/VRSL DMX Patch Folder/VRSL DMX Patch Data_[SceneName].asset Properties:
  • targetScene - Scene reference (for verification)
  • fixtureData - Serialized fixture array
  • exportDate - Last save/export timestamp
Methods:
  • SetDMXFixtureData() - Populates data from scene fixtures
  • LoadDMXFixtureData() - Applies data to scene fixtures
  • ToJsonFile(bool prettyPrint) - Exports to JSON
  • ToMVRFile() - Exports to MVR format
  • ToPDF() - Exports to PDF (Windows only)

​
Inspector View

Screenshot would show: The VRSL_DMXPatchSettings inspector with fixture data array, scene reference, and export timestamp.
When you select the patch data asset in the Project window:
  • View (but don’t edit) saved fixture data
  • See last save timestamp
  • Verify scene association
Do not manually edit patch data assets. Always use Save/Load functions to ensure data integrity.

​
Best Practices

​
Regular Saves

  • Save after initial fixture setup
  • Save before major restructuring
  • Save before Unity version upgrades
  • Save before VRChat world uploads

​
Version Control Integration

1

Include Patch Folder

Add Assets/VRSL DMX Patch Folder/ to your Git repository
2

Export JSON on Commits

Before major commits, export to JSON for readable diffs
3

Tag Important Versions

Use Git tags to mark stable patch configurations

​
Collaboration Workflow

  1. Lead Lighting Designer:
    • Configures patch in Unity
    • Saves patch data asset
    • Commits scene + patch asset to Git
  2. Team Members:
    • Pull latest scene + patch asset
    • Load patch data to restore exact configuration
    • Make local changes, save, commit
  3. External Lighting Programmers:
    • Receive MVR export
    • Import to console/previz software
    • Program show independent of Unity

​
Backup Strategy

  • Keep patch data assets in version control
  • Export JSON periodically to cloud storage
  • Export MVR before production/events
  • Generate PDF for physical archival

​
Troubleshooting

  • Verify VRSL_LocalUIControlPanel exists in scene
  • Check that scene is saved (not “Untitled”)
  • Ensure scene is not in play mode
  • Check Console for errors
  • Verify patch data asset still exists
  • Ensure fixture GameObjects have not been renamed
  • Confirm fixtures have VRSL component scripts attached
  • MVR uses different coordinate system than Unity
  • Verify fixture positions in external software
  • May need to adjust coordinate conversion in VRSL code
  • PDF export is Windows-only feature
  • Use JSON export as alternative
  • Consider cross-platform PDF library for future updates
  • Verify fixtures have Fixture Type assigned
  • Check that Fixture Definition file exists
  • See Fixture Definitions documentation

Build docs developers (and LLMs) love

Get started for freeTalk to us