Skip to content

Recording, editing, and running macros

What a Controll3r macro is

A macro is a structured set of keyboard, pointer, wait, decision, and repeat blocks stored in a .c3rm file. It can use fixed screen coordinates or Visual Anchors captured from the target image.

Visual Anchors are useful when an element may move but still looks the same. Fixed coordinates are useful when the target layout is guaranteed not to move.

A macro sends real input to a real machine — it can change firmware settings or delete data exactly as a person at the keyboard could. Test macros on non-production systems, use timeouts and Wait For Operator around risky steps, and review a macro before running it unattended.

Before recording

  1. establish a stable live video signal
  2. verify that keyboard and pointer input reach the target
  3. use the target resolution and capture format that playback will use
  4. open the Macros card or macro picker
  5. choose Record new macro

Automation pointer actions require the Controll3r Interface absolute pointer device. If it is disabled, Controll3r asks before enabling it, applying a live trial, verifying the change, and committing it.

Guided recording

During recording, every target click asks how it should be grounded:

  • Fixed position records the exact image coordinate.
  • Visual Anchor captures an image around the clicked control and stores the click offset inside that image.

You only have to answer once if you want: check Do this for all remaining clicks (stop asking) in the grounding prompt and the same choice applies to every later click in the recording.

For a Visual Anchor:

  1. choose Visual Anchor in the grounding prompt
  2. adjust the suggested box or drag a new box
  3. keep the box tight enough to be distinctive
  4. accept the box
  5. continue recording

Controll3r parks the target pointer before capturing the template so the cursor itself is not part of the anchor.

Consecutive keyboard events are grouped into an editable key-sequence block. Time spent in Controll3r's grounding and capture dialogs is not added to the recorded delay between target actions.

Use Pause Recording when you need to prepare the target without recording new steps. Use Stop Recording or the configured stop key, initially Esc, to finish.

Review and edit

After recording, the flowchart editor opens.

  • The left palette adds blocks.
  • The center flow shows execution order and nesting.
  • The right inspector edits the selected block.

You can:

  • rename the macro
  • change labels and timing
  • edit key sequences and text
  • reorder blocks by drag, keyboard, or move controls
  • multi-select adjacent blocks
  • wrap selected blocks in If or Repeat
  • convert a recorded Delay into an Await Anchor in one step
  • capture or recapture Visual Anchors
  • configure timeout recovery blocks
  • save or cancel with unsaved-change protection

Block behavior

Click

  • Fixed click acts at one recorded coordinate.
  • Visual Anchor click finds the saved image and applies the recorded click offset.

Keyboard and text

  • Key sequence stores physical key down/up snapshots and their timing.
  • Type text uses the same reliable translation and untypable-character handling as Paste.

Timing and operator control

  • Delay waits for a fixed duration. A recorded delay usually stands in for "wait until the target is ready" — use Convert to Await Anchor on the block to replace the guess with a wait that actually watches the screen.
  • Wait For Operator pauses, gives input to the operator, and resumes only when the operator confirms.
  • Stop ends the macro intentionally.

Wait For Operator is not available in headless playback.

Visual waits

  • Await Anchor continues when an image appears.
  • Wait Until Clear continues when the saved image is no longer present.

Timeout is entered in seconds. 0 means no timeout. A wait may contain recovery blocks that run when a positive timeout expires.

Decisions

An If block evaluates whether an anchor is present or absent and runs its Then or Else body. Visual conditions use multiple frames to avoid making a decision from a single contradictory frame.

Repetition

Repeat blocks can:

  • run a fixed number of times
  • continue until an anchor appears
  • continue until an anchor disappears

Safety limits protect unattended runs from accidental infinite repetition. Break exits the nearest repeat block. Continue starts its next iteration.

Choosing a good Visual Anchor

Prefer an anchor that:

  • includes a distinctive icon, label, border, or color combination
  • is stable while the macro runs
  • is not covered by the target pointer
  • does not include a blinking caret, clock, animation, or changing counter
  • is large enough to distinguish from similar controls
  • is small enough to exclude unrelated changing content

Color is part of the match. A differently colored lookalike with the same brightness should not be accepted as the same anchor.

Exact playback context

Version 1 Visual Anchors are exact-resolution and exact-format. Playback must use the capture dimensions and pixel format stored with the macro. If the context differs, Controll3r reports the recorded and current values rather than silently searching in the wrong coordinate system.

If a target changes resolution:

  1. restore the recorded resolution and capture format, or
  2. re-record or recapture the affected anchors in the new context

Run a macro

  1. select a macro from the card or searchable picker
  2. choose Play
  3. watch the running banner for the active block
  4. use the banner's stop action or configured stop key to cancel

While playback owns the target, live input is paused so operator movement cannot corrupt automation. A Wait For Operator block temporarily returns control in a deliberate state.

Failure recovery

If a Visual Anchor cannot be found, the failure view can include:

  • the expected anchor image
  • the current target image
  • the best observed match
  • timeout and confidence information

Use Recapture Anchor when the target's appearance changed. Use Open in editor when the workflow or threshold needs broader correction.

Macro Repeat

Macro Repeat runs the selected macro repeatedly with a randomized delay between the configured minimum and maximum. It uses the same playback ownership and safety behavior as one normal run.

Share and back up macros

Each macro is one .c3rm bundle containing:

  • one macro.json entry
  • the macro's blocks and recording context
  • the Visual Anchor images, embedded in the same file

Use the macro library's Open folder action for backup and file transfer, or use the REST API to upload and download bundles. A .c3rm may contain recognizable target-screen pixels, so treat it as potentially sensitive.

The default library is:

%LocalAppData%\Controll3r\macros\

Old text scripts are not a supported macro format.