Action System
DearScenario Player uses a unified Action system to route user input (keyboard shortcuts), UI interactions, and some network commands through a single dispatch pipeline. This ensures that pressing a key, clicking a button, or sending a remote command all trigger identical behavior.
Overview
Keyboard input ──┐
UI button click ─┤──→ ActionEvent ──→ ActionExecutor ──→ AppController
Network command ─┘ (action ID + params) (dispatches to player/UI)Every user-triggerable operation is identified by a string Action ID
(e.g. player.toggle_pause, ui.toggle_debug). The ActionExecutor maps
each Action ID to the corresponding IAppController method call, ensuring
consistent execution regardless of the input source.
Action IDs
Actions are organized by namespace:
UI actions
| Action ID | Description |
|---|---|
ui.toggle_debug | Toggle debug panel visibility. |
ui.close_debug | Close the debug panel. |
ui.show_exit_prompt | Show the Leave DearScenario Player prompt (Cancel / Minimize / Quit). |
ui.close_exit_prompt | Dismiss the Leave DearScenario Player prompt. |
ui.toggle_idle_info | Toggle idle screen info display. |
ui.open_calibration_tools | Open the calibration tools panel. |
ui.open_mask_editor | Open the mask editor. |
App actions
| Action ID | Description |
|---|---|
app.request_quit | Quit the player process. |
app.minimize_window | Minimize the window (keeps the player running). |
Player actions
| Action ID | Description |
|---|---|
player.toggle_pause | Toggle play/pause. |
player.play | Start or resume playback. |
player.pause | Pause playback. |
player.stop | Stop and unload media. |
player.cue | Return loaded media to its logical start and enter ready. |
player.seek | Seek to absolute position. |
player.seek_relative | Seek relative to current position. |
player.volume_step | Adjust volume by a delta. |
player.set_volume | Set absolute volume. |
player.set_mute | Set mute state. |
player.toggle_loop | Toggle loop state. |
player.set_loop | Set loop state. |
player.open_file_dialog | Open the file picker dialog (debug panel: Open media). |
player.load | Load media by source and leave it ready (debug panel: Reload media executes play_media). |
Calibration actions
| Action ID | Description |
|---|---|
calibration.close_pattern | Close the calibration pattern. |
calibration.set_pattern_type | Set the calibration pattern type. |
calibration.set_grid_density | Set grid line density. |
calibration.set_grayscale_steps | Set grayscale step count. |
calibration.set_border_width | Set border width. |
calibration.set_grid_color | Set grid color. |
Mask actions
| Action ID | Description |
|---|---|
mask.set_dirty | Mark mask state as modified. |
mask.exit_screen_edit | Exit fullscreen direct edit mode. |
Debug actions
| Action ID | Description |
|---|
Shortcut contexts
The ShortcutManager routes key presses based on the current UI context.
Contexts have a priority hierarchy — higher-priority contexts take precedence:
| Priority | Context | Active when |
|---|---|---|
| 1 (highest) | Calibration | A calibration pattern is displayed. |
| 2 | MaskEditor | Fullscreen mask direct-edit mode is active. |
| 3 | DebugUI | debug panel is visible. |
| 4 | ExitPrompt | The Leave DearScenario Player prompt is shown. |
| 5 | Playback | Debug UI is visible and media is loaded (playing/paused). |
| 6 | Idle | No media loaded. |
| 7 (lowest) | Global | Always active. |
When a key is pressed, the manager checks bindings from highest to lowest priority context. The first match wins. Playback shortcuts are intentionally limited to the Debug UI; Normal-mode exhibition playback is controlled through HTTP/OSC or the Web Console. If ImGui is capturing text input (e.g. a text field is focused), most keyboard shortcuts are suppressed.
Key chords
A KeyChord represents a key + modifier combination:
| Format | Example |
|---|---|
"F1" | Single key |
"space" | Named key |
"Ctrl+Shift+K" | Key with modifiers |
"Cmd+Shift+D" | macOS variant |
Modifiers: Ctrl, Shift, Alt, Cmd (macOS).
Trigger timing
| Trigger | When it fires |
|---|---|
Press | On key down. |
Release | On key up. |
Repeat | While held (OS key repeat). |
Synthetic input injection
The input_key command (maintenance-only) injects synthetic keyboard events through
the same shortcut pipeline as real key presses:
{
"cmd": "input_key",
"params": {
"chord": "F1",
"action": "tap",
"count": 1
}
}This is used for automated testing — injected events pass through context resolution, ImGui capture detection, and the temporary dev sequence logic, exactly as a real key press would.
See Keyboard Shortcuts for the default shortcut bindings.
Previous / Next
- Previous: Config Migration
- Next: Playback Basics