Actions

An action is a named, reusable operation that bundles together a sequence of effects — fire a device control, set an output's dimmer, power an output on or off, change a TouchDesigner parameter, wait, repeat — and exposes the whole thing as one button (or one toggle). Actions are how you turn "open the venue" or "shutdown for the night" into a single thing operators, schedules, sensors, and external systems can fire.

Button vs toggle

Every action is one of two types, set when you create it. The choice is structural — you can't change it later without re-creating.

Button actions are fire-and-forget. You hit the button, the steps run, and that's it. Good for one-shot operations: Reset Projectors, Snap All Cameras, Reload Media.

Toggle actions have state — they're either ON or OFF, and they have two parallel step sequences. Activating runs the on-steps; deactivating runs the off-steps. Good for stateful workflows: Venue Open / Closed, Show Mode / Standby, Party Lights On / Off.

Toggle actions appear in the UI as a switch. Their state persists across reloads and is broadcast to every connected client, so the switch matches reality everywhere.

Action structure

Every action has:

Steps

A step is one effect. Steps run sequentially — each waits for the previous to complete before starting. Five types:

Control step

Fire a control on a device. Pick a device, pick one of its controls, optionally pass a value (for sliders and dropdowns).

Dimmer step

Set an output's brightness between 0 and 100%.

Power step

Enable or disable an output. This is the output's on/off state — different from dimming all the way to zero.

Config parameter step

Set a custom TouchDesigner parameter on an output, source, effect, or system plugin. This is how an action reconfigures the install — switch a projector's network target, change which monitor a screen output renders to, swap the LED pixel-mapping algorithm.

Delay step

Wait before running the next step. Useful for hardware that needs a beat between commands — e.g. power on a projector, wait 30 seconds for warmup, then change input.

Only fire on change

Every stateful step (control, dimmer, power, config parameter) has an Only fire on change option in the step editor. When enabled, the step checks the target's current value first and skips firing if it's already at the desired value. Useful for actions that run often (a mandatory calendar event firing every night, a content trigger firing on every activation) — avoids spamming devices with redundant commands.

---

Triggering actions

Actions can be fired from many places:

Each firing is logged with its source so you can trace what triggered what.

Content triggers

An action can listen for specific content activations. Add a content name to the action's content-triggers list and the action fires automatically when that content activates.

For buttons, the action runs its steps on activation.

For toggles, the trigger sets the toggle to a configured state (on or off) when the content activates. By default this only fires on activation; configure it to fire on deactivation too if you want the toggle to flip back when the content goes away.

Common patterns:

• Bind a "Projector on" toggle to a "Venue Open" scene → projector comes up automatically when the scene activates.
• Bind a "Show Live" toggle (a state-only action with no steps) to a "Performance" playlist → the toggle reflects whether a show is running, queryable from external systems.
• Bind a "Snap photos" button to a "Curtain Open" scene → camera fires at the start of every show.

Each action has a master switch to disable every one of its content triggers at once without removing them — useful for testing.

See Changing content → Action content triggers for the upstream view.

---

Toggle state — keeping it in sync

For toggle actions, "is this ON or OFF?" needs a source of truth. There are three behaviors:

1. Bookkeeping (default). State updates only when the action executes — Lightpath remembers whether the last execution was an ON or an OFF. Simple, but the state can drift if a user controls one of the target devices directly.

2. Single-control auto-sync. If an action has exactly one control step targeting a toggle-type device control, Lightpath automatically queries that device's live status to sync state. No configuration needed.

3. Explicit state source. In the action editor, pick a specific thing for the toggle to track — a device control, an output's dimmer, an output's power state, or a TouchDesigner config parameter. Lightpath polls it live every 5 seconds. The polled value gets compared against the action's matching on-step and off-step:

   • If it matches an on-step's value, state = ON.
   • If it matches an off-step's value, state = OFF.
   • If it matches neither cleanly, state stays unchanged.

Use an explicit state source when the action's target devices have status APIs (PJLink projectors, Shelly relays, etc.) and you want the toggle to track reality regardless of how it was changed.

Actions with no steps

A toggle action with no steps on either side is a state variable — it can be toggled and read by other parts of the system but doesn't do anything when fired.

This sounds weird but is genuinely useful:

• Calendar conditions: a "Party Mode" toggle other rules can check.
• Logic rule inputs: a toggle representing "is the venue open?" that multiple rules condition on.
• Content trigger destinations: have content set a flag that an external system polls via the API.

Stateless buttons with no steps are also valid — they fire purely as a notification signal: any content triggers or webhook subscribers see them, but Lightpath itself does nothing.

---

Where actions appear

• Actions page (Configure → Actions) — full list, search, group by output. Edit, duplicate, delete, run.
• Controller — actions associated with an output appear in that output's controls. System-level actions appear in the All Outputs view.
• Kiosk — admins can add specific actions to the Kiosk via the Kiosk Editor. Buttons render as buttons, toggles as switches.
• Calendar — calendar events can target an action in addition to or instead of content.
• Logic — rules can list actions in their then branch.

---

Gotchas

• Disabled actions still show up in the UI. They render greyed-out and don't run when triggered, but they aren't hidden. Use this for "disable temporarily, re-enable later" — to fully remove, delete the action.
• Orphaned content triggers don't error. If you add a content trigger for "Sunset" and later rename the look to "Sundown", the trigger silently stops firing. There's no save-time validation; fix by editing the action.
• Device offline → step fails, action stops. If a control step targets an offline device, the step records a failure and the action stops. Subsequent steps don't run. Enable Only fire on change on steps for devices that might already be at the desired state, so the action skips them gracefully.
• Step retries vs action retries. Individual device control calls retry up to 3× with exponential backoff (100ms → 200ms → 400ms) before the step gives up. The action itself does not retry — the calendar, logic rule, or external system that fired it is responsible for handling failure.
• State drift without a state source. A toggle whose target device also has another way to be controlled (a physical switch, a remote, another piece of software) will drift out of sync. Set the toggle's state source to the device control to fix this.