retroarch_show_message
Show a temporary one-line message on the RetroArch display, ideal for debug output or progress updates during automation.
Instructions
PURPOSE: Display a single-line notification message overlaid on the RetroArch window (OSD). USAGE: For in-emulator debug output, progress markers during long scripts, or text to a human watching the RetroArch window. Purely cosmetic — no effect on game state. The ONLY way to push agent-generated text onto the RetroArch display; there is no read-the-screen counterpart. BEHAVIOR: Renders the message in RetroArch's notification area for ~3 seconds (RetroArch's default notification timeout, configurable via the input_overlay_show_inputs_port setting family). Messages are NOT queued — rapid calls replace the previous message before users can read it. FIRE-AND-FORGET: the NCI does NOT acknowledge this command — the call returns as soon as the UDP datagram is sent, with no confirmation that RetroArch received or applied it. To verify the effect, follow up with an observable tool (retroarch_get_status for run state, retroarch_read_memory / retroarch_read_ram for memory mutations, retroarch_screenshot for visual state). UDP packets to a not-listening RetroArch are silently dropped. Transport: RetroArch's Network Control Interface (NCI) over UDP (default 127.0.0.1:55355, requires network_cmd_enable = true in retroarch.cfg). RETURNS: 'Showed: MESSAGE' echoing what was sent (UDP-send confirmation only — does NOT verify the overlay rendered).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| message | Yes | UTF-8 message text. Spaces and most punctuation are preserved verbatim. NEWLINES (\n / \r) TRUNCATE the message — the NCI protocol is line-terminated, so anything after the first newline is silently dropped on the wire. Keep messages to ONE LINE; recommended ≤80 chars to fit RetroArch's notification overlay without horizontal clipping (the exact width depends on the user's video resolution and font size). Consecutive calls REPLACE rather than queue, so use one message per logical event rather than emitting a stream of status updates. Special characters: percent-signs are safe (RetroArch does NOT printf-interpret the string), quotes are safe (no shell interpolation), but ASCII control bytes other than space are likely rendered as boxes or stripped. |