Action Authoring Overview

Actions are deterministic, scripted sequences of control changes that Fusor Studio runs in three contexts: as a fusor's pre-run or post-run step (Pre-run Actions), as a pad-mode trigger (Pad Mode), or as a one-shot manual run from the Library. The runtime contract lives in the Action File Reference: file shape, step types, predicates, role addresses.

The editor runs inside the Library popover, parallels the fusor editor in shape, and is where you create, edit, duplicate, and delete .faction files.

Opening an action for editing

Open the Library from the menubar and switch to the Actions tab. The Actions sub-tab lists every .faction file in the library.

Edit an existing action. Click an action to open its detail view, or right-click → Details. The detail view is already editable.
Create a new action. Click + New Action (the blue + in the list header). An in-app prompt asks for a name; there's no file-explorer dialog. Fusor Studio writes the file into your library's actions/ folder for you.
Duplicate an existing action. Right-click an action and choose Duplicate. The prompt proposes "name copy"; confirm or type a different name. The copy carries the original's description, app tags, preflight note, and steps; the actionId is regenerated for the new file.
Delete. Right-click → Delete. Confirm the prompt and the .faction file is removed from disk.
Rescan the folder. The Scan Folder button (refresh icon in the list header) rescans actions/ for files added or changed outside the app.

Canceling either prompt writes nothing. If the name you typed is already taken, Fusor Studio still creates the action: the file on disk gets a number appended (crossfader-passthrough-2.faction, and so on) so nothing gets overwritten. The list still shows the display name you typed, duplicate or not.

There's no separate "enter authoring" step, no Save/Cancel bar on the main detail view, and no pencil button to flip into edit mode.

Autosave

Edits to the action's metadata commit as you make them. There's no Save button on the detail view.

Text fields (name, description) commit on blur: click out of the field, or press Tab.
Apps multi-select commits as soon as you change the selection.
Code tab (the raw DSL text) commits on blur of the text area.

Editing an action's metadata triggers a rescan so the list view picks up the new name or app tags without a Scan Folder click.

Action edits are not in the fusor editor's undo stack, which belongs to the loaded fusor. If you make a typo in an action's name or description, fix it the same way (blur to commit, edit again, blur again). For larger changes to the steps, work in the pop-out Step Editor, which carries its own explicit Save and an "unsaved" indicator.

The two tabs

The action detail view has two tabs along the top:

Tab	What it's for
Notes	Metadata: Name, Description, Pre-flight, Apps (a multi-select picker of DJ-app tags from the registry — Traktor, Mixxx, djay, Virtual DJ, rekordbox, Serato). App tags are informational; they don't gate execution.
Code	The action's steps as raw DSL text. Lives in a single text area with inline parse-error feedback. The pencil icon in the tab bar opens the structured pop-out Step Editor.

Pre-flight is the reminder text shown on the player's before you run this surface, and this field is the master copy every fusor draws from. When you add the action to a fusor's pre-run or post-run list, the fusor takes its own copy of this text at that moment. Editing Pre-flight here afterward changes what a fusor copies the next time the action is added. It doesn't reach fusors that already have it; each keeps the text it copied when it was added. To change the reminder on a fusor that already lists the action, edit its per-action override instead (see Pre-run Actions → per-action preflight editor).

This field edits the plain reminder only. A .faction file can also carry separate reminder text per DJ app; that stays a hand-edit in the file itself, and editing Pre-flight here leaves any per-app text already there untouched.

Both tabs read and write the same underlying .faction file. Edits in either tab show up in the other.

The Notes tab is the right surface for renaming, describing what the action does, and tagging which DJ apps it targets. The Code tab is where you author and tweak the steps themselves. For non-trivial edits, click the pencil to open the Step Editor instead of editing DSL by hand.

What an action is, structurally

Every .faction file is a JSON document with a small fixed shape:

Action (.faction)
├── format: "faction"
├── version: 1
├── meta
│   ├── name              (display label)
│   ├── shortId           (REQUIRED — up to 12 characters, for controller
│   │                      and pad labels; an action without one won't run)
│   ├── description       (free-form summary)
│   ├── apps              (["traktor", "mixxx", …])
│   ├── actionId          (UUID — auto, don't hand-edit)
│   ├── preflight         (optional reminder shown before a run; edit the
│   │                      plain text on the Notes tab — per-app entries
│   │                      stay a hand-edit)
│   └── anticipatedDurationMs   (optional override for the duration badge)
└── steps                 (ordered list — runs top-to-bottom)

shortId is not optional. An action missing a valid one fails validation and will not run. The Step Editor exposes it as the Short ID field; if you're writing the file by hand, don't leave it out.

Steps come in six types: SET, WAIT, WAIT_UNTIL, CAPTURE, RESTORE, IF. The full schema, predicate grammar, nesting rules, and worked examples live in the Action File Reference. The Step Editor walks through the same shapes from the UI side.

Where files live

Actions are JSON files with the .faction extension, stored under your library folder (Documents/Fusor/ by default) in actions/:

<library>/
  actions/
    deck-prep.faction
    crossfader-passthrough.faction
    fx-resets/
      reset-fx1.faction
      reset-fx2.faction

Subfolders are scanned, so an action filed into one still appears in the Actions list. They are a hand-filing convenience and nothing more. The runtime treats every .faction file the same regardless of which folder it sits in.

The file name follows the action's name. Rename an action and the next save moves the file to match, staying in whatever subfolder you filed it in. The status line confirms it: "File renamed to match: filename." So the file on disk is findable by the name you see in the list — which matters when you want to send someone a single action.

Nothing breaks when a file moves. Fusors reference an action by its id, not by where it sits, so you can rename it, file it into a subfolder, or point Fusor Studio at a different library folder, and every fusor using that action keeps working. The one thing that does break a reference is deleting the action.

Packs work the same way and always have. A pack is a separate .fpack file in the library's Packs/ folder, and it references actions by id too. Which folder an action lives in has no bearing on which packs it belongs to. See Pack Authoring for the 8-slot grid Pad Mode fires.

The authoring loop

The rhythm of building an action:

Create or open the action in the Library popover (right-click → Details, or + New Action).
Name and describe it on the Notes tab. Tag which DJ apps it targets so the list view filters correctly.
Author the steps. For quick changes, the Code tab is fine. For anything multi-step, click the pencil icon to open the Step Editor.
Wire it up. Add the action to a fusor's Pre-run or Post-run list, drop it into a pad slot (Pack Authoring), or run it standalone from the Library for a one-shot test.
Iterate. Edits land on disk immediately. Any fusor that already references the action picks up the new behaviour next time it runs, since there's one canonical file per action.

Nothing needs compiling and there's no separate test mode. What you save is what runs.

Editing while a fusor is running

The fusor detail view shows a save-lock banner while the loaded fusor is mid-transition (see Authoring Overview → Editing is paused mid-transition). Action authoring has no equivalent lock: the engine reads action files at queue-load time, not continuously during a transition, so editing a .faction while a different fusor runs is safe.

If you edit an action that's currently in the pre-run queue of the loaded fusor, the change takes effect the next time the queue is loaded (typically the next time the fusor arms). The currently-running queue holds the version that was loaded when it armed.

Where to next

Action Editor — The pop-out Step Editor: step list, per-type forms, address and value pickers.
Pack Authoring — Group actions into an 8-slot pad-mode pack.
Pre-run Actions — Wire actions into a fusor's pre-run and post-run lists.
Pad Mode — How packs and slots show up at performance time.
Action File Reference — The .faction JSON format, step types, predicates, validation rules.