4.2. Visual aids — tutorial-mode overlays, mouse trail, narration, key HUD

Tutorial-mode overlays — highlight rectangles, mouse-cursor sprite + trail, narration text, key HUD, click flash — painted over the live ImGui surface to guide the viewer through scripted recordings. Every overlay is opt-in and keyed off the boost registry’s widget path, so highlighting MAIN_WIN/SETTINGS_TAB/RPS resolves to the exact rect the renderer drew. Painters are registered as end-of-frame hooks so the host’s render loop is unchanged.

Auto-highlight (imgui_auto_highlight_on_command) makes every accepted imgui_* command auto-flash its target — useful when recording with imgui_playwright so each programmatic action is visually narrated without explicit imgui_highlight calls.

4.2.1. Constants

g_keycap_trace_max = 6

g_keycap_trace_max:int const

g_keycap_trace_fallback_lifetime_s = 1f

g_keycap_trace_fallback_lifetime_s:float const

4.2.2. Structures

HighlightArgs

struct HighlightArgs

MouseTrailArgs

struct MouseTrailArgs

NarrateArgs

struct NarrateArgs

AutoHighlightArgs

struct AutoHighlightArgs

CursorSpriteArgs

struct CursorSpriteArgs

KeyHudArgs

struct KeyHudArgs

FocusRectArgs

struct FocusRectArgs

4.2.3. Highlight overlay

highlight(target: string; frames: int = highlight_default_frames; color: uint = highlight_color )

Flash a colored rect around the named widget’s bbox for frames ticks. target is a registry path or "0x<hex_id>".

Arguments:

  • target : string

  • frames : int

  • color : uint

imgui_highlight(input: JsonValue? ): JsonValue?

[live_command] wrapper around highlight. Args: target, frames, color.

Arguments:

4.2.4. Mouse trail

imgui_mouse_trail(input: JsonValue? ): JsonValue?

[live_command] wrapper around mouse_trail. Args: enabled, fade, color.

Arguments:
mouse_trail(enabled: bool; fade: float = -1f; color: uint = 0x0 )

Toggle the fading mouse-trail overlay; non-default fade / color override the module globals. Disabling clears the trail buffer.

Arguments:

  • enabled : bool

  • fade : float

  • color : uint

4.2.5. Narration

narrate(text: string; target: string = ""; frames: int = narrate_default_frames )

Pop a callout box with text for frames ticks. If target resolves to a widget bbox the box anchors next to it with a connector line; otherwise it floats top-left.

Arguments:

  • text : string

  • target : string

  • frames : int

4.2.6. Uncategorized

rgba(r: int; g: int; b: int; a: int ): uint

Pack R/G/B/A bytes into ImGui’s IM_COL32 word order. Useful when configuring the tunable color globals by channel rather than hex literal.

Arguments:

  • r : int

  • g : int

  • b : int

  • a : int

cursor_sprite(enabled: bool )

Toggle the in-frame cursor sprite. Drawn on the ForegroundDrawList so APNG recordings show a visible pointer even when the OS hardware cursor isn’t captured.

Arguments:

  • enabled : bool

apply_synth_io_override()

Per-frame synth IO entry point — call between the backend’s NewFrame and ImGui’s NewFrame. Drives imgui_synth_tick.

compute_narrate_anchor(has_target: bool; widget_bbox: float4; box_size: float2; viewport: float2; edge_margin: float; gap: float; shadow: float2; hud_zone_h: float; other_bboxes: array<float4> ): float2

Pick a post-it anchor (top-left corner) that fits the viewport without overlapping the target widget OR any other registered widget. Tries right → left → below → above of the target; falls back to a viewport-clamped right placement if nothing fits cleanly (e.g. text wider than the viewport, or every neighbor blocks).

Arguments:

  • has_target : bool

  • widget_bbox : float4

  • box_size : float2

  • viewport : float2

  • edge_margin : float

  • gap : float

  • shadow : float2

  • hud_zone_h : float

  • other_bboxes : array<float4>

compute_connector_start(anchor: float2; box_size: float2; widget_center: float2 ): float2

Midpoint of the post-it edge closest to the widget center. Used to anchor the connector line from the right edge when the post-it sits to the left of the widget, etc.

Arguments:

  • anchor : float2

  • box_size : float2

  • widget_center : float2

visual_aids_init()

[init] — registers the foreground-drawlist paint hook and the post-command auto-highlight hook. Runs once at module load.

imgui_narrate(input: JsonValue? ): JsonValue?

[live_command] wrapper around narrate. Args: text, target, frames.

Arguments:
imgui_auto_highlight(input: JsonValue? ): JsonValue?

[live_command] toggle for the imgui_auto_highlight_on_command flag. Arg: enabled.

Arguments:
imgui_cursor_sprite(input: JsonValue? ): JsonValue?

[live_command] wrapper around cursor_sprite. Arg: enabled.

Arguments:
imgui_key_hud(input: JsonValue? ): JsonValue?

[live_command] toggle for the bottom-center keycap HUD + Ctrl/Shift/Alt/Cmd modifier strip. Args: enabled, show_modifiers.

Arguments:
imgui_focus_rect(input: JsonValue? ): JsonValue?

[live_command] toggle for the focus rectangle around io.active_widget — shows where typing lands. Arg: enabled.

Arguments: