Skip to main content

​
Overview

A Sequence is a specialized type of Chaser that is bound to a single Scene. Instead of playing different scenes in order, a Sequence animates the channel values of its bound scene across multiple steps, creating smooth transitions and animations.
Sequences inherit all functionality from Chasers but add scene-binding capabilities for streamlined animation workflows.

​
When to Use Sequences

Channel Animation

Animate dimmer, color, or position values smoothly over time

Movement Patterns

Create complex movement sequences for moving head fixtures

Color Fades

Smooth color transitions across multiple steps

Intensity Ramps

Build fade-up and fade-down effects for theatrical cues

​
How Sequences Differ from Chasers

FeatureChaserSequence
Member FunctionsMultiple different functionsSingle bound scene only
Value StorageReferences function IDsStores channel values per step
Use CasePlay different lighting statesAnimate channel values
FlexibilityAny function typeScene values only

​
Bound Scene Concept

Every Sequence is bound to exactly one Scene: 
class Sequence : public Chaser {
private:
    quint32 m_boundSceneID;  // The associated Scene ID
};
The bound scene defines:
  • Which fixtures are controlled
  • Which channels are animated
  • The base structure for all sequence steps

​
Creating a Sequence

1

Create Base Scene

Create a scene with all fixtures and channels you want to animate
2

Create Sequence

Create a new Sequence and bind it to your scene
3

Add Steps

Each step stores the channel values for that point in time
4

Configure Timing

Set fade times and hold durations for smooth transitions

​
Key Properties

​
Bound Scene ID

​
boundSceneID
quint32
The ID of the Scene this Sequence animates. Set with setBoundSceneID().

​
Step Values

Each ChaserStep in a Sequence contains: 
struct ChaserStep {
    quint32 fid;                  // Always equals boundSceneID
    QList<SceneValue> values;     // Channel values for this step
    uint fadeIn;                  // Fade in time
    uint hold;                    // Hold time
    uint fadeOut;                 // Fade out time
};

​
Class Methods

The Sequence class (sequence.h:31) extends Chaser:

​
Scene Binding

// Set the bound scene
void setBoundSceneID(quint32 sceneID);

// Get the bound scene ID
quint32 boundSceneID() const;

// Get component list (returns bound scene)
QList<quint32> components() const;

​
Inherited from Chaser

Sequences inherit all Chaser methods:
  • Step management (addStep(), removeStep(), etc.)
  • Speed mode control
  • Playback control
  • Tempo synchronization

​
Step Synchronization

Sequences maintain value consistency with the bound scene: 
private:
    bool m_needFixup;  // Flag for post-load synchronization
During postLoad(), the sequence verifies:
  • All steps have the same channels as the bound scene
  • Missing channels are added with zero values
  • Extra channels are preserved
If the bound scene is modified after creating the sequence (channels added/removed), the sequence may need to be regenerated or manually fixed.

​
XML Structure

Sequences save with scene binding information: 
<Function Type="Sequence" ID="3" Name="Color Fade" BoundScene="0">
  <Speed FadeIn="0" FadeOut="0" Duration="500"/>
  <Direction>Forward</Direction>
  <RunOrder>Loop</RunOrder>
  <SpeedModes FadeIn="PerStep" FadeOut="PerStep" Duration="Common"/>
  <Step Number="0" FadeIn="500" Hold="0" FadeOut="0">
    <Function>0</Function>
    <Value>0:255</Value>    <!-- Fixture 0, Red: 255 -->
    <Value>1:0</Value>      <!-- Fixture 0, Green: 0 -->
    <Value>2:0</Value>      <!-- Fixture 0, Blue: 0 -->
  </Step>
  <Step Number="1" FadeIn="500" Hold="0" FadeOut="0">
    <Function>0</Function>
    <Value>0:0</Value>
    <Value>1:255</Value>
    <Value>2:0</Value>
  </Step>
</Function>
The BoundScene attribute is required for Sequences. Without it, the sequence cannot be loaded.

​
Scene Value Fixup

The fixup mechanism (sequence.cpp:231) handles scene mismatches: 
void Sequence::postLoad() {
    if (m_needFixup == false)
        return;
        
    Scene *scene = doc()->function(boundSceneID());
    QList<SceneValue> sceneValues = scene->values();
    
    // Synchronize each step with scene structure
    for (ChaserStep &step : m_steps) {
        step.values = sceneValues;
        // Restore original values where they exist
    }
}
This ensures:
  1. All steps have consistent channel structure
  2. New scene channels appear in all steps (value = 0)
  3. Existing step values are preserved

​
Best Practices

1

Design Scene First

Fully configure the bound scene with all needed fixtures/channels before creating steps
2

Use PerStep Speed Mode

For smooth animations, use PerStep mode with appropriate fade times
3

Test Scene Changes

If you modify the bound scene, verify the sequence still works correctly
4

Organize Step Values

Keep channel values logically organized for easier editing

​
Common Use Cases

​
Dimmer Chase

<!-- Step 1: Full intensity -->
<Value>0:255</Value>
<!-- Step 2: 50% intensity -->
<Value>0:128</Value>
<!-- Step 3: Off -->
<Value>0:0</Value>

​
Color Wheel

<!-- Red -->
<Value>0:255</Value><Value>1:0</Value><Value>2:0</Value>
<!-- Yellow -->
<Value>0:255</Value><Value>1:255</Value><Value>2:0</Value>
<!-- Green -->
<Value>0:0</Value><Value>1:255</Value><Value>2:0</Value>

​
Position Sweep

<!-- Position 1 -->
<Value>0:0</Value>    <!-- Pan -->
<Value>1:128</Value>  <!-- Tilt -->
<!-- Position 2 -->
<Value>0:128</Value>
<Value>1:128</Value>
<!-- Position 3 -->
<Value>0:255</Value>
<Value>1:128</Value>

​
Performance Considerations

  • Sequences with many steps and channels use more memory
  • The fixup mechanism adds load time overhead
  • Hidden scenes (used only as sequence containers) don’t render in UI
Sequences require their bound scene to exist. Deleting the bound scene will break the sequence. Always delete sequences before deleting their bound scenes.

​
Limitations

  1. Single Scene Only: Cannot animate multiple scenes
  2. Channel Structure Fixed: Adding/removing scene channels requires fixup
  3. No Function Mixing: Cannot mix scenes with other function types
  4. Legacy Format: Old sequence format is no longer supported

​
See Also

  • Scenes - The base for all sequences
  • Chasers - Parent class with playback control
  • Shows - Timeline-based alternative for complex animations

Build docs developers (and LLMs) love

Get started for freeTalk to us