Author scenes

A scene names a coordinated multi-channel snapshot — "when I press this button, my robot should switch locomotion to walk-6 AND swing the arm to hold". The Agent's Runtime::applyScene activates all assignments atomically with claim-decreasing ordering, so channels giving up actuators always release before channels acquiring them.

This howto walks through authoring a scene in Studio's Scene Editor and applying it from the Remote's Scene Picker.

Pro Tip

Scenes are part of the channel model — they reference existing stanzas by id. You can't author a scene that points at a stanza that doesn't exist on the channel. Author your stanzas first, then compose scenes on top.

Before you start

You need:

• A preset with at least two channels and one non-idle stanza per channel.
• The preset deployed to an Agent (so the Remote-side picker can subscribe to its fixo-runtime section).

If you don't have a multi-channel preset yet, the hexapod template ships with locomotion + arm channels and is the canonical example.

Author a scene in Studio

1. Open the Studio's Preset Manager.
2. Open your preset. The preset editor opens with its tab strip — Actuators / Sensors / Lobes / Stanzas / Scenes. Click the Scenes tab.
3. Click Add. Enter a scene id (e.g. cruise). The id is the stable wire-format key; the display name is editable later via Rename.
4. The right column lists every channel in the preset. For each channel, pick a stanza from the dropdown:
   • The dropdown enumerates only the stanzas declared on that channel.
   • Selecting the empty entry means "use this channel's idle stanza" — explicit, visible, no hidden default.
5. The bottom-edge indicator turns red if the assignment is invalid:
   • Unknown channel — shouldn't happen unless you've manually edited the JSON.
   • Foreign stanza — the dropdown only offers in-channel stanzas, so this also shouldn't happen via the UI; only via raw JSON edit.
   • Claim conflict — two of your assignments fight for the same actuator. Resolve by picking a non-overlapping stanza on one of them, or move stanzas to different channels.
6. Edits autosave — every change flows through the preset editor's standard autosave path. Use the OS-level Back to return to the Preset Manager once you're done.

Repeat for as many scenes as you want; the editor list grows. Use Remove to drop a scene; the channel stanzas it referenced are unaffected.

Apply a scene from Remote

1. Open the Remote app.
2. From the controller menu pick Scenes. The picker mounts one button per scene declared by the active preset.
3. Click the scene you want. The button's applyTrigger counter increments, the Agent's RuntimeCourier picks up the change, and Runtime::applyScene runs.
4. The button stays highlighted while that scene is the last successfully applied scene. If you immediately click another, the highlight follows.

The picker tracks lastAppliedScene separately from the trigger counter — so a partial-failure apply (where one channel rejects) doesn't flash the highlight. The active-scene state on the Remote is always the Agent's authoritative view.

How conflict policy interacts with scene application

Runtime::applyScene defaults to ConflictPolicy::Force — the scene is the operator's explicit intent, so any leftover conflict from an unrelated active channel yields. If you have a concurrent autonomous service driving one of the channels in your scene (like a path-follower), pass Reject instead to fail atomically with a conflict list, or Negotiate to demote down the upgrade ladder.

The picker doesn't currently expose a policy chooser — the default Force covers the operator-initiated case. Future revisions may add policy selection per-scene as a manifest field.

Troubleshooting

• The scene button doesn't appear on Remote — verify the preset has at least one scene authored, and that the Remote is paired with the Agent. The picker rebuilds when sceneCount changes; check fixo-runtime/sceneCount in the Remote's section debug view.
• The scene applies but one channel didn't switch — that channel's activation hit a conflict that the Force policy couldn't resolve (typically an upstream service holding the channel). Check the Agent's logs for Runtime::activate outcomes per channel.
• Clicking the same scene button twice does nothing — by design. The applyTrigger is a monotonic counter; only an increment fires applyScene. If you want to re-apply, click a different scene first, then come back.

Related

• Channels reference — the underlying channel/stanza model.
• Configure Fixo Controller — sets up the preset that a scene composes against.
• Pilot CNC-shield personality — single-channel example without scenes; scenes shine when you have ≥2 channels.