Creating Custom Fixtures - VR Stage Lighting

Overview

VRSL’s modular architecture allows you to create custom light fixtures using the existing shader and script framework. This guide covers creating fixtures from scratch or modifying existing ones.

Custom fixtures use the same VRSL shaders and scripts as built-in fixtures, ensuring consistent performance and compatibility.

Fixture Architecture

A VRSL fixture consists of:

Fixture Body: Physical housing mesh
Volumetric Mesh: Light beam/cone mesh
Projection Mesh: Gobos/patterns (optional)
VRSL Script: DMX or AudioLink control component
Materials: Using VRSL shaders

Fixture Types

Static Fixtures:

PAR cans, wash lights, blinders
No movement capability
Simpler setup

Moving Head Fixtures:

Spotlights, wash movers
Pan/tilt movement
Requires head/base separation

Special Fixtures:

Disco balls, lasers, light bars
Unique behaviors
Custom shader features

Prerequisites

Knowledge Requirements

Basic Unity editor skills
Understanding of Unity materials and shaders
3D modeling (if creating custom models)
Basic understanding of DMX channels (for DMX fixtures)

Tools

Unity 2019.4 or newer
VRSL package installed
3D modeling software (Blender, Maya, etc.) - optional
Texture editing software (Photoshop, Substance) - optional

Creating a Static Fixture

Let’s create a simple static PAR light from scratch:

Create Base GameObject

In Unity Hierarchy, create empty GameObject

Name it “MyCustomPAR-DMX”

Position at origin (0, 0, 0)

This is your fixture root

Add Fixture Body Mesh

Create child GameObject: “Body”

Add Mesh Filter component

Add Mesh Renderer component

Assign your fixture body mesh (or use Unity primitive)

Create/assign material using VRSL-StandardSurface shader

Example Body Setup:

MyCustomPAR-DMX
└── Body (MeshRenderer)
    └── Material: Using VRSL-StandardSurface-Opaque

For initial testing, use a Unity Cylinder primitive. Replace with custom model later.

Add Volumetric Light Cone

Create child GameObject: “Volumetric”

Add Mesh Filter component

Assign cone mesh (use VRSL spotlight cone or create custom)

Add Mesh Renderer component

Create material using VRSL volumetric shader:

DMX: VRSL-StaticLight-VolumetricMesh
AudioLink: VRSL-AudioLink-StaticLight-VolumetricMesh

Set material Rendering Mode:

Render Queue: 3002 (Transparent)
Blend Mode: Transparent

Volumetric Setup:

MyCustomPAR-DMX
├── Body
└── Volumetric (MeshRenderer)
    └── Material: Using VRSL-StaticLight-VolumetricMesh

Add Projection Mesh (Optional)

Create child GameObject: “Projection”

Add Mesh Filter with flat cone/disc mesh

Add Mesh Renderer

Create material using projection shader:

DMX: VRSL-StaticLight-ProjectionMesh
AudioLink: VRSL-AudioLink-StaticLight-ProjectionMesh

Assign gobo texture atlas in material

Full Hierarchy:

MyCustomPAR-DMX
├── Body
├── Volumetric  
└── Projection

Add VRSL Control Script

Select root GameObject “MyCustomPAR-DMX”

Add Component:

DMX: VRStageLighting_DMX_Static
AudioLink: VRStageLighting_AudioLink_Static

Configure script:

Drag meshes into Obj Renderers array:
- [0] Body
- [1] Volumetric
- [2] Projection (if using)

Configure default values:

Global Intensity: 1.0
Light Color Tint: White
Cone Width: 1.5
Cone Length: 5.0

Configure Materials

Select each material

Set required properties:

Volumetric Material:

Enable “Use Depth Light” (if using depth light)

Set “Potato Mode” based on 3D noise preference

Configure cone properties

Set render queue to 3002

Projection Material:

Assign gobo texture atlas

Set projection selection

Configure intensity

Set render queue to 3001

Test Your Fixture

Enter Play Mode

Adjust properties in VRSL script inspector

Verify all meshes respond to changes

Test intensity, color, cone width/length

For DMX: Assign DMX channel and test with grid

Creating a Moving Head Fixture

Moving heads require additional structure for pan/tilt:

Create Fixture Hierarchy

MyCustomMover-DMX
├── Base (Static)
├── Yoke (Rotates on Y - Pan)
│   └── Head (Rotates on X - Tilt)  
│       ├── Body
│       ├── Volumetric
│       └── Projection
└── Target (Empty Transform for constraints)

Set Up Pan Rotation

Select “Yoke” GameObject

This object will rotate on Y axis for pan

Reset rotation to (0, 0, 0)

Rotation will be controlled by VRSL script or constraints

Set Up Tilt Rotation

Select “Head” GameObject (child of Yoke)

This object will rotate on X axis for tilt

Reset rotation to (0, 0, 0)

Position pivot point at yoke connection

Add Constraint System

Select “Head” GameObject

Add Aim Constraint component

This allows target following (optional)

Configure in VRSL script for automated targeting

Configure DMX Movement

Select root “MyCustomMover-DMX”

In VRStageLighting_DMX_Static component:

Max/Min Pan: Set rotation limits (e.g., -180 to 180)
Max/Min Tilt: Set rotation limits (e.g., -90 to 90)
Invert Pan/Tilt: Adjust if rotation direction is wrong
Is Upside Down: Check if fixture is ceiling-mounted

Assign DMX channels for pan/tilt (typically channels 2-5)

Ensure Head transform’s forward axis (blue arrow) points in the direction the light should project. Adjust mesh rotation in modeling software if needed.

Custom Volumetric Meshes

Creating Volumetric Mesh

Options for volumetric meshes: 1. Use Existing VRSL Meshes:

Located in VRSL package
Pre-optimized for performance
Various cone shapes available

2. Create in Blender:

Create cone mesh
UV unwrap (cylindrical projection)
Ensure origin is at cone tip
Export as FBX
Import to Unity

3. Create in Unity:

Use ProBuilder to create cone
Adjust vertices for desired shape
UV unwrap appropriately

Volumetric Mesh Requirements

Topology:

Origin at emission point (tip of cone)
Forward direction matches light direction
Reasonable polygon count (50-200 tris)
Clean geometry (no overlapping faces)

UVs:

Cylindrical unwrap from tip to base
U: Around circumference (0-1)
V: From tip to base (0-1)
Used by shader for gradient effects

LOD Versions:

Create High (200 tris), Med (100 tris), Low (50 tris)
Swap via VRSL Control Panel
Significant performance improvement

Start with VRSL’s existing volumetric meshes and modify their scale/proportions rather than creating from scratch.

Custom Gobo Textures

Creating Gobo Atlas

VRSL uses texture atlases for gobo patterns: Atlas Layout:

[1] [2] [3] [4]
[5] [6] [7] [8]

Specifications:

Resolution: 2048x2048 (or 1024x1024 for optimization)
Format: PNG with alpha channel
Each gobo: 512x512 pixels
Layout: 4x2 grid (8 gobos)
Background: Transparent (alpha = 0)
Pattern: White (for tinting) or colored

Creating Individual Gobos

In Photoshop/GIMP:

Create 512x512 document
Transparent background
Draw/import your pattern in white
Use alpha channel for shape:
- Black = Blocked (opaque)
- White = Light passes (transparent)
- Gray = Partial transparency
Save as PNG

Tips:

Keep designs high-contrast
Avoid very fine details (will blur at distance)
Test how it looks with different colors
Consider rotation when designing

Assembling the Atlas

Create 2048x2048 document
Arrange 8 gobos in 4x2 grid
Ensure exact spacing (no gaps or overlaps)
Each gobo occupies 512x512 square
Export as PNG with alpha
Import to Unity

Import Settings:

Texture Type: Default
Alpha Source: Input Texture Alpha
Alpha Is Transparency: Yes  
Wrap Mode: Clamp
Filter Mode: Bilinear
Max Size: 2048
Compression: High Quality

Assigning to Material

Create/select projection material
Find “Gobo Texture” property
Assign your atlas texture
Material will automatically index into correct gobo
Use “Projection Selection” (1-8) to choose gobo

Fixture Definitions (VRSL 2.6.0+)

Fixture Definition files describe your fixture’s DMX profile:

Creating Fixture Definition

Right-click in Project: Create > VRSL > Fixture Definition
Name it “MyCustomFixture-Definition”
Configure properties:

Basic Info:

Fixture Name: Display name
Manufacturer: Your name or studio
Channel Count: Total DMX channels used

Channel Definitions: For each channel, specify:

Channel number
Function (Intensity, Red, Green, Blue, Pan, Tilt, etc.)
Value range (0-255)
Description

Example 8-Channel PAR:

 Channel 1: Intensity (0-255)
 Channel 2: Red (0-255)
 Channel 3: Green (0-255)
 Channel 4: Blue (0-255)
 Channel 5: White (0-255)
 Channel 6: Strobe (0-255: 0=off, 1-255=speed)
 Channel 7: Dimmer Curve (0-255: Linear/Square/Inverse)
 Channel 8: Macro (Special effects)

Applying Definition to Fixture

Select your fixture GameObject
In DMX Static component, find “Fixture Definition”
Assign your Fixture Definition asset
Used for patch export and documentation

Exporting Patch Data

VRSL Control Panel > Utilities
“Export DMX Patch Data”
Choose format:
- JSON: Machine-readable
- MVR: My Virtual Rig (industry standard)
- PDF: Human-readable patch list
Includes all fixtures with definitions
Import into lighting software

Fixture Definitions are optional but highly recommended for documentation and collaboration.

Advanced Customization

Custom Shader Properties

Add custom properties while maintaining VRSL compatibility:

Duplicate VRSL shader
Add your properties:

_MyCustomColor ("My Custom Color", Color) = (1,1,1,1)
_MyCustomFloat ("My Custom Float", Range(0,1)) = 0.5

Integrate with VRSL’s existing calculations
Test thoroughly with DMX/AudioLink

Modifying VRSL shaders can break compatibility with updates. Document all changes and test extensively.

Custom Scripts

Extend VRSL scripts with custom behavior: Option 1: Inherit from VRSL Script

public class MyCustomFixture : VRStageLighting_DMX_Static
{
    public float customProperty;
    
    void Start()
    {
        base.Start();
        // Your custom initialization
    }
}

Option 2: Separate Control Script

public class CustomFixtureController : MonoBehaviour  
{
    public VRStageLighting_DMX_Static vrslComponent;
    
    void Update()
    {
        // Control vrslComponent from your logic
        vrslComponent.GlobalIntensity = yourCustomValue;
    }
}

Multi-Instance Fixtures

Create fixtures with multiple light sources: Light Bar Example:

MyLightBar-DMX
├── Cell-1 (Complete fixture)
│   ├── Body
│   ├── Volumetric
│   └── VRSL DMX Script (Channel 1)
├── Cell-2
│   ├── Body  
│   ├── Volumetric
│   └── VRSL DMX Script (Channel 5)
├── Cell-3
│   └── ... (Channel 9)
└── Cell-4
    └── ... (Channel 13)

Each cell is a complete fixture with its own DMX channel assignment.

Laser Fixtures

Lasers use a different shader:

Use VRSL-BasicLaser-DMX or VRSL-AudioLink-BasicLaser shader
Apply to line mesh or textured quad
Configure in VRStageLighting_AudioLink_Laser component:
- Laser Count: Number of beams
- Cone Width/Length: Beam properties
- Laser Thickness: Individual beam width
- Cone X/Y/Z Rotation: Beam pattern rotation
- Laser Scroll: Animated movement

Testing Custom Fixtures

Editor Testing

Enter Play Mode

Select fixture

Adjust inspector properties:

Global Intensity
Light Color Tint
Cone Width/Length
Projection Selection (if applicable)

Verify all meshes respond correctly

Check materials are using correct shaders

DMX Testing

Set up DMX grid node (or use test video)

Assign DMX channel to fixture

Send test DMX values from console

Verify:

Intensity responds (Channel 1)
Color responds (Channels 2-4)
Movement responds if moving head
Strobe responds
Gobo selection works

AudioLink Testing

Set up AudioLink in scene

Play test audio

Adjust Band and Multiplier

Verify fixture reacts to audio

Test different frequency bands

Test Color Chord if enabled

Performance Testing

Duplicate fixture 10-50 times

Check FPS in editor

Verify GPU instancing is working:

Check draw calls in Stats panel
Should be 1 batch per unique material

Test different quality settings

Profile in Unity Profiler

Creating Prefabs

Making Your Fixture Reusable

Set up fixture completely in scene

Configure all default values

Test thoroughly

Drag from Hierarchy to Project folder

Creates prefab asset

Name following VRSL convention:

“MyFixture-DMX-Horizontal”
“MyFixture-AudioLink”

Prefab Variants

Create variants for different modes:

Base Prefab:

Complete fixture setup

Default materials

Horizontal DMX Variant:

Inherits from base

DMX script configured for horizontal mode

Appropriate materials

Vertical DMX Variant:

Inherits from base

DMX script configured for vertical mode

Appropriate materials

AudioLink Variant:

Inherits from base

AudioLink script instead of DMX

AudioLink-compatible materials

Distribution

Packaging for Others

If sharing custom fixtures:

Organize Assets:
- Create folder: “Assets/MyFixtures/”
- Include:
  - Prefabs
  - Models (FBX/mesh files)
  - Materials
  - Textures
  - Fixture Definitions
Document:
- Create README.txt
- Include:
  - Installation instructions
  - DMX channel layout
  - Usage notes
  - Version compatibility
Export UnityPackage:
- Right-click folder
- Export Package
- Include dependencies
- Test import in fresh project
Share:
- Upload to Gumroad, GitHub, etc.
- Include preview images
- Specify VRSL version compatibility
- Provide support contact

Licensing Considerations

VRSL shaders are MIT licensed (permissive)
Your models/textures can use any license
Credit VRSL if redistributing with shaders
Consider open-source for community benefit

Common Issues

Fixture Doesn’t Respond

Check:

VRSL script component is attached
Obj Renderers array includes all meshes
Materials use VRSL shaders
DMX channel is assigned (for DMX fixtures)
Control Panel is in scene

Materials Look Wrong

Verify:

Using correct VRSL shader (DMX vs AudioLink)
Render queue is correct (3002 for volumetric)
Blend mode is set properly
Material properties match expectations
No conflicting materials or shaders

Movement Not Working

For Moving Heads:

Check Yoke and Head hierarchy
Verify forward direction is correct
Check pan/tilt limits are set
Ensure DMX channels are assigned correctly
Test with known working DMX data

Performance Issues

Optimize:

Use lower-poly volumetric mesh
Reduce projection texture resolution
Ensure GPU instancing is working
Check for duplicate materials
Use appropriate render queues

Best Practices

Design Guidelines:

Start with existing VRSL fixtures as templates
Keep volumetric meshes under 200 triangles
Use power-of-2 texture dimensions
Test with both DMX and AudioLink
Create multiple LOD versions
Document your DMX channel layout
Follow VRSL naming conventions

Workflow:

Model in your 3D software
Import to Unity early and test often
Use VRSL’s existing shaders when possible
Create prefab variants for different modes
Test performance with many instances
Get feedback from community

Compatibility:

Test with latest VRSL version
Document version requirements
Don’t modify core VRSL shaders if possible
Use Material Property Blocks for per-instance properties
Maintain GPU instancing compatibility

Next Steps

Learn DMX Setup to control your fixtures
Integrate AudioLink for audio reactivity
Optimize with Performance Guide
Set up Video Streaming for live control

Resources

VRSL Discord - Share and get feedback on custom fixtures
VRSL GitHub - Example fixtures
Unity Shader Documentation
Blender Documentation - For 3D modeling

Get Started

Core Concepts

Fixtures

Components

Guides

​Overview

​Fixture Architecture

​Fixture Types

​Prerequisites

​Knowledge Requirements

​Tools

​Creating a Static Fixture

​Creating a Moving Head Fixture

​Custom Volumetric Meshes

​Creating Volumetric Mesh

​Volumetric Mesh Requirements

​Custom Gobo Textures

​Creating Gobo Atlas

​Creating Individual Gobos

​Assembling the Atlas

​Assigning to Material

​Fixture Definitions (VRSL 2.6.0+)

​Creating Fixture Definition

​Applying Definition to Fixture

​Exporting Patch Data

​Advanced Customization

​Custom Shader Properties

​Custom Scripts

​Multi-Instance Fixtures

​Laser Fixtures

​Testing Custom Fixtures

​Creating Prefabs

​Making Your Fixture Reusable

​Distribution

​Packaging for Others

​Licensing Considerations

​Common Issues

​Fixture Doesn’t Respond

​Materials Look Wrong

​Movement Not Working

​Performance Issues

​Best Practices

​Next Steps

​Resources

Build docs developers (and LLMs) love

Overview

Fixture Architecture

Fixture Types

Prerequisites

Knowledge Requirements

Tools

Creating a Static Fixture

Creating a Moving Head Fixture

Custom Volumetric Meshes

Creating Volumetric Mesh

Volumetric Mesh Requirements

Custom Gobo Textures

Creating Gobo Atlas

Creating Individual Gobos

Assembling the Atlas

Assigning to Material

Fixture Definitions (VRSL 2.6.0+)

Creating Fixture Definition

Applying Definition to Fixture

Exporting Patch Data

Advanced Customization

Custom Shader Properties

Custom Scripts

Multi-Instance Fixtures

Laser Fixtures

Testing Custom Fixtures

Creating Prefabs

Making Your Fixture Reusable

Distribution

Packaging for Others

Licensing Considerations

Common Issues

Fixture Doesn’t Respond

Materials Look Wrong

Movement Not Working

Performance Issues

Best Practices

Next Steps

Resources