Stage Coding Guide

This file covers concepts related to the stage, including accessing its collections, positioning objects, and building complex stage setups like DMX lighting.

The Object Class

All 3D stage elements (such as screens, props, surfaces, and lights) inherit from the core Object class. This class provides common spatial properties and methods, including:

offset: The 3D position of the object on stage (as a Vec).
rotation: The orientation of the object (as a Vec or quaternion, depending on context).
scale: The scale of the object (multiplier for the mesh scale).
mesh: The mesh Resource used to represent the object in the stage - this mesh defines the overall size. Default is an internally generated mesh called Rectangle which has a 1m x 1m dimension, meaning the scale parameter can be used to define absolute sizes unless a custom mesh is used.
resolution: The pixel resolution for display objects.
Common Methods: Methods for manipulating position, parenting, and other spatial relationships.

When you interact with stage objects in Python, you are typically working with these properties and methods from the Object class.

Object hierarchy

There is a standard 3D scene node hierarchy to inherit parent Object transforms between Objects, but it is not mandatory. The correct method for adding and removing Objects from the stage is to add it to the correct typed list in the Stage object. Adding objects as parents and children of others is purely for inheriting transforms.

Object Collections

The stage contains several arrays of different object types. These arrays are the correct way to add, find and remove Objects from the Stage.

The lists within the reference are mostly self-explanatory, however there are some lists which behave differently to the others:

Displays

The stage.displays array contains all display surfaces on the stage, including screens and projectors. It duplicates the contents of all arrays which themselves contain Display subclasses. This is convenient for quickly accessing all display elements without needing to search through multiple arrays.

Pucks

Pucks are controlled by the stage.people property and accessible via the stage.pucks array. Each Puck is unnamed, and its description is always Puck. To identify Pucks, you should use their index in the stage.pucks array.

When asking for an overview of the stage, you can mention the number of Pucks, but unless explicitly asked for, the details of individual Pucks should be avoided as it can be overwhelming and is not usually relevant to the user’s needs.

Props

Props are held on the stage.venue, which can be None. If a Venue is present, it contains all the props visible in the Stage.

Some Props are used as a “null” object, in the 3D hierarchy, to provide transform information to groups of other Objects.

Stage & Object Access

Task	Python
Get the current stage object	`stage = state.stage`
Get an object collection from the stage (e.g., lights)	`stage.lights` or `stage.dmxLights`
Get the stage’s venue object (can be None)	`stage.venue`
Get all props from the venue (after checking if venue is not None)	`stage.venue.props`
Find a specific projection surface on stage by its name	`my_surface = next((s for s in stage.surfaces if s.description.lower() == "surface 1"), None)`
Add a surface to the stage to make it visible/active	`stage.surfaces.append(my_surface_object)`

Object Spatial Properties

Assumes my_obj is an object on the stage, inheriting from Object:

Task	Python
Get an object’s position/offset	`current_pos = my_obj.offset`
Set an object’s position/offset	`my_obj.offset = Vec(1.0, 2.0, 3.0)`
Set an object’s rotation	`my_obj.rotation = Vec(0.0, 90.0, 0.0)`
Set an object’s scale	`my_obj.scale = Vec(16.0, 9.0, 0.1)`
Set an object’s resolution	`my_obj.resolution = Int2(1920, 1080)`

DMX Screens

DMX Screens are contiguous arrays of pixels (like LED tape) that are simpler to set up than DMX Lights.

Task	Python
Create a new DMX screen	`dmx_screen = DmxScreen()`
Set fixture type (RGB, RrGgBbWw, etc.)	`dmx_screen.fixture_type = 0` # 0 = RGB
Configure array parameters	`dmx_screen.array = 1` `dmx_screen.origin = 0`
Set DMX universe and channel	`dmx_screen.universe = 1` `dmx_screen.channel = 101`
Set universe step for multiple universes	`dmx_screen.universe_step = 3`
Set scale and position	`dmx_screen.scale = Vec(5.0, 0.1, 0.1)` `dmx_screen.offset = Vec(0.0, 2.0, 0.0)`
Add to stage	`stage.dmxScreens.append(dmx_screen)`

Complete DMX Screen Setup Example

dmx_screen = DmxScreen()
dmx_screen.fixture_type = 0  # 0 = RGB
dmx_screen.array = 1
dmx_screen.origin = 0
dmx_screen.universe = 1
dmx_screen.channel = 101
dmx_screen.universe_step = 3
dmx_screen.scale = Vec(5.0, 0.1, 0.1)
dmx_screen.offset = Vec(0.0, 2.0, 0.0)
stage.dmxScreens.append(dmx_screen)

DMX Lights

DMX Lights are actually arrays of DMX lights, controlled as a screen by placing the individual light fixtures across the Object’s mesh.

Basic DMX Light Setup

Task	Python
Create a fixture resource	`fixture = Fixture()`
Set fixture channel count and size	`fixture.nChannels = 3` `fixture.size_ = Vec(0.1, 0.1, 0.1)`
Create a driver (DmxDriver, GenericLampDriver, or MovingHeadLedDriver)	`driver = DmxDriver()` `driver.mode = 0` # RGB mode
Assign driver to fixture	`fixture.driver = driver`
Create DMX assignment	`patch = DmxAssigner()`
Create DMX string configuration	`dmx_string = DmxString()`
Add to stage	`stage.dmxLights.append(fixture_group)`

Complete DMX Light Setup Example

# Create fixture
fixture = Fixture()
fixture.nChannels = 3
fixture.size_ = Vec(0.1, 0.1, 0.1)

# Create and configure driver
driver = DmxDriver()
driver.mode = 0  # RGB mode
fixture.driver = driver

# Create DMX assignment
patch = DmxAssigner()

# Configure DMX string
dmx_string = DmxString()
dmx_string.nUnits = 20
dmx_string.universe = 1
dmx_string.channel = 101
dmx_string.step = 3

# Add string to patch and apply
patch.strings.append(dmx_string)
patch.assign()

# Create fixture group and assign patch
fixture_group = DmxLight()
fixture_group.fixture = fixture
fixture_group.assignment = patch

# Add to stage
stage.dmxLights.append(fixture_group)

Advanced DMX Light Driver Types

Task	Python
Create GenericLampDriver for moving light	`driver = GenericLampDriver()`
Create MovingHeadLedDriver for LED moving head	`driver = MovingHeadLedDriver()` `driver.first_pixel_channel = 1`
Set fixture as aimable	`fixture.aimable = 1`
Set fixture resolution for LED arrays	`fixture.resolution = Vec2(8, 1)` # 8 LED pixels

Configure GenericLampDriver

driver = GenericLampDriver()

# Configure lamp controller (color channels)
driver.lamp.red_channel = 1
driver.lamp.green_channel = 2
driver.lamp.blue_channel = 3

# Configure pan/tilt controller
driver.pan_tilt.pan_channel = 5
driver.pan_tilt.tilt_channel = 6
driver.pan_tilt.pan_range = 540.0

Complex DMX Light Arrays

Task	Python
Clear all strings from patch	`patch.strings = []`

Multiple DMX Strings Example

# Create multiple DMX strings for different universes
string1 = DmxString()
string2 = DmxString()

# Configure string 1 (Universe 1)
string1.nUnits = 33
string1.universe = 1
string1.channel = 101
string1.step = 3

# Configure string 2 (Universe 2)
string2.nUnits = 33
string2.universe = 2
string2.channel = 1
string2.step = 3

# Add both strings to patch
patch.strings.append(string1)
patch.strings.append(string2)

Search

Designer Plugins