Keymap
Hyprune owns ~/.config/hyprune/input.json. Edit it directly or use the Director’s Settings tab. Core validates and live-reloads it independently of Hyprland. Each action accepts up to three bindings. [L] means hold for 1000 ms by default.
Movement keys are listed HJKL first, then WASD and arrows. E uses a window or workspace wall in place. F zooms into that window or workspace. From world control, Super+Tab or Back enters a real free cursor (an active carry finishes first). The camera freezes; layers and other outputs receive ordinary input. From use/focus, Back or Super+Tab returns directly to the world. From the world it enters free cursor; another press returns to the world. A colliding Hyprland shortcut is stolen only in the mode that defines it, while the world is active.
Q holds scope zoom; the wheel changes its magnification. Shift sprints and Ctrl crouches (descends in flight). Shift also snaps position-tool movement to 0.1 m, rotation to 15°, and scale factors to 0.1. Ctrl+R records (below): Ctrl crouches at once, and a Ctrl chord ends the crouch or descent and puts the height back, so Ctrl+R never leaves the camera lower. Keys 1–4 select tools; 5 selects the Placement tool; 9 selects the debug tool. Wheel selects an unplaced window; LMB places ahead and RMB places on a surface. MMB pockets the aimed window for travel. A nonempty queue preselects tool 5 on first entry. HUD concepts (Adventure, Instrument and Minimal) are selected in Settings → HUD & reticle, with Adventure as default. The window tool cycles place/lock; the path tool cycles line/curve/arc and Alternate toggles open/closed; the position tool cycles move/rotate/scale.
Super+LMB on a window’s edge (about 10 cm) resizes it from the nearest corner; anywhere else it carries. The Super window gestures (carry, resize, push/pull, rotate, content scale) also work while using a window (E). A window brought into the world (opened there, moved or dragged in from another output, pulled, recalled, placed or carried off its wall) becomes a floating window at its own size (very large ones are scaled down); back on its home wall it is tiled again.
Carrying: r toggles FACING YOU / KEEP ANGLE. Super+Ctrl+Wheel rotates; Super+Shift+Wheel changes content scale. Super+Shift+MMB resets the window. The shell reports content scale and client pixel dimensions.
Tool input slots
Section titled “Tool input slots”Primary, Secondary, Alternate and Cycle use the same globally rebindable primary, secondary, alternate, cycle actions in every tool. Their defaults are LMB, RMB, MMB and Wheel. Unassigned slots do nothing. Super modifier gestures always override tool slots, including during a carry.
| Tool | Primary | Secondary | Alternate | Cycle |
|---|---|---|---|---|
| Normal | Click / interact | Right-click | Middle-click | Scroll window |
| Window | Tag/mount or lock (sub-mode) | Lock/unlock | Unassigned | Place/lock sub-mode |
| Path | Add point; drag a point; click a segment to insert | Remove the aimed point (else the last) | Open/close path | Line/curve/arc |
| Position | Select / drag gizmo | World/local axes | Toggle snapping | Move/rotate/scale |
| Placement | Place ahead | Mount on surface | Pocket aimed window | Select pocketed window |
| Debug (9) | Inspect the aimed item | Close the info card | Unassigned | Next/previous debug layer |
Paths show only in the path tool, with their points and curve handles; the point under the reticle highlights. Press on a point and drag to move it (Ctrl snaps to 0.1 m), release to commit; Escape cancels the drag. Ctrl+Z and Ctrl+Shift+Z (or Ctrl+Y) undo and redo path edits as they do position edits. Period (.) in the path tool keeps all paths shown in the other tools; the debug view (F3) shows them too.
Debug tool
Section titled “Debug tool”Key 9 selects the debug tool. It shows one debug layer at a time; the wheel (Cycle) steps through them and a banner at the top names the layer with a one-line legend of its colours. The layers are: window boxes and mounts (window volumes, workspace wall, tool mount and data object frames); window zones (where windows are placed freely and objects are refused); collision (floors, walls, invisible walls or backstops, object proxies) near you; playable volumes and the fly ceiling; paths with their points and stops, and the walking graph; keepClear volumes, screen approach zones and spawn or climb clearances; seats with their approach; visibility regions (where you are, what is drawn from there); character steering (body, predicted positions, offset from the route, detours, who holds whom up); and every volume the placement rules refuse, by rule.
Primary on something in the current layer opens an info card: its id, type, owner and area, and whether it blocks placement and why (for example Inside a window zone). In the placement layer, Primary on open ground says whether a 0.5 m box would be allowed there. Secondary closes the card. The tool draws thick lines (3 px at 1080p, scaled with the output) and light fills, dimmed and dashed behind walls; the F3 debug view keeps its thin lines. A still view renders no frames while the tool is out.
Tool hints come from core declarations over IPC. Pocketed windows remain alive but invisible; newest pocketed comes first. There is no return-to-last-spot command. windows.carry_face_player defaults to true in Lua config; content scale changes client logical resolution while keeping the world rectangle fixed. Reset returns content resolution, facing and distance to defaults, subject to collision recovery.
In-world
Section titled “In-world”| Action | Default bindings |
|---|---|
| look | MouseMove |
| forward | k, w, Up |
| back | j, s, Down |
| left | h, a, Left |
| right | l, d, Right |
| menu | Tab[L] |
| markers.reveal | Tab |
| sprint | Shift_L |
| up | space |
| down | Control_L |
| use | e |
| focus | f |
| noclip | v |
| scope | q |
| debug | F3, y |
| capture | u |
| record.toggle | Ctrl+r |
| carry | Super+LMB |
| resize | Super+RMB |
| distance | Super+Wheel |
| rotate | Super+Ctrl+Wheel |
| carry.facing | r |
| content.scale | Super+Shift+Wheel |
| window.reset | Super+Shift+MMB |
| tool1 | 1 |
| tool2 | 2 |
| tool3 | 3 |
| tool4 | 4 |
| tool5 | 5 |
| tool9 | 9 |
| hud.cycle | Unbound |
| transport | z |
| autopilot | x |
| primary | LMB |
| secondary | RMB |
| alternate | MMB |
| cycle | Wheel |
| fly | F4 |
| exit | Super+Tab, Back |
Interactive / use in place
Section titled “Interactive / use in place”| Action | Default bindings |
|---|---|
| debug | F3 |
| capture | Super+u |
| record.toggle | Unbound |
| exit | Super+Tab, Back |
Focus / fullscreen
Section titled “Focus / fullscreen”| Action | Default bindings |
|---|---|
| debug | F3 |
| capture | Super+u |
| record.toggle | Unbound |
| exit | Super+Tab, Back |
| Action | Default bindings |
|---|---|
| debug | F3 |
| capture | Super+u |
| record.toggle | Unbound |
| exit | Escape |
A short Tab tap is markers.reveal: markers for the tracked quest step, the waypoint, area homes and places nearby fade in for about 4 s (Settings → Guidance & focus). Holding Tab is menu: the hold ring appears after a short delay and the Director opens; a tap never opens it. A plain and a [L] binding of the same key in one mode for different actions form such a tap/hold pair; any other duplicate is a conflict.
Ctrl+R (record.toggle, world mode only: in apps Ctrl+R stays theirs) starts and stops a private debug recording of input, camera and frame timing for measuring motion feel. A red REC dot and the elapsed time show while it runs; on stop the HUD asks for an optional label (Esc skips). Recording does not change how motion runs. Application keystrokes are masked unless explicitly enabled through the recording API.
File options
Section titled “File options”| Option | Default | Valid range / meaning |
|---|---|---|
| version | 3 | Exactly 3. A version 2 file is upgraded once: record.toggle gets Ctrl+r where it is unbound and free. A keymap still at the swapped pair of IPC 0.29 (sprint Control_L, down Shift_L) gets Shift sprint and Ctrl down back once |
| longHoldMs | 1000 | 100–5000 ms |
| scopeVignette | true | Scope ring and shaded edges |
| invert_y | false | Reverse vertical mouse look; false means mouse up looks up |
| show_area_markers | false | Optional core-rendered area/place labels; active waypoint/route remain visible |
| useDistance | 6 | 0.2–30 m; E maximum distance |
| useTolerance | 0.12 | 0–0.5 m margin around an aimed surface |
| captureInputLimit | 256 | 16–1024 recent input events in captures |
| modes | tables above | All listed actions; 0–3 bindings each |
Binding names use XKB keysyms, Super+Shift+Ctrl+Alt+key, LMB, RMB, MMB, Back, Forward, ButtonN, Wheel, WheelUp, WheelDown, or MouseMove. Keys use the active keyboard layout’s base-level symbol, with letters canonicalized to lowercase; Shift/Ctrl/Alt/Super are separate modifiers. Press identity is retained through release even if modifiers or layout change. Modifier order is canonicalized. F12 remains the emergency exit outside free-cursor mode. In free-cursor mode Back and Super+Tab return to world control; Escape does too when no app has keyboard focus. Other keys go to native focus. Internal conflicts reject a save; Hyprland collisions are reported and accepted. Invalid edits retain the last valid configuration.
U in world, or Super+U in interactive/focus/menu, writes a private timestamped JSON/PNG capture pair under $XDG_STATE_HOME/hyprune/captures/ (default ~/.local/state/hyprune/captures/) and shows the path in a notice. The JSON records the completed world frame camera, age and timings, plus mode, tools, surfaces, placements, recent IPC/events and the bounded input history.
Compositor graphics, sensitivity and inertia remain in hl.plugin.hyprune.config({...}); input bindings belong in the independent JSON file. Walking and running speed, view bob, the reticle and reach limits are player settings.
Tools save paths, window locks and object transforms in $XDG_STATE_HOME/hyprune/editor.json, scoped by world and area. Authored world packages stay read-only.
Player settings
Section titled “Player settings”Movement speed, view bob, the reticle and how far your hands reach are player settings. Change them in the Director’s Settings tab (Movement & camera, HUD & reticle, World & characters) or with player.set (IPC 0.19) or settings.set (IPC 0.30); changes apply immediately. Only changed keys (your overrides) are saved, to $HYPRUNE_PLAYER_FILE, else $XDG_CONFIG_HOME/hyprune/player.json (default ~/.config/hyprune/player.json). hl.plugin.hyprune.config({player = {...}}) accepts the same keys; saved values win. The old player.run_multiplier still works in Lua and sets run speed to walk speed × multiplier.
| Setting | Default | Valid range / meaning |
|---|---|---|
| walk_speed | 4.0 | 0.5–20 m/s; walking and the flight base speed |
| run_speed | 10.0 | 0.5–30 m/s while sprint (Shift) is held; flight scales by run/walk |
| view_bob | subtle | off, subtle or normal walking view bob |
| reticle_style | cross_dot | cross_dot, t_dot, circle_dot, dot, cross or chevron |
| reticle_size | 18 | 6–64 px, full extent |
| reticle_thickness | 2 | 1–6 px |
| reticle_gap | 4 | 0–20 px from the centre to the arms |
| reticle_opacity | 0.9 | 0.2–1 |
| reticle_outline | true | Dark 1 px outline for contrast |
| reticle_colour | theme | theme (the HUD theme) or an RGB colour |
| reticle_dynamic | true | The reticle opens up while you move or turn |
| reach_grab | 15 | 1–100 m; Super+button window gestures (carry, resize) |
| reach_mount | 8 | 1–100 m; snapping into tool-mount frames (tools 2 and 5, releasing a carry) |
| reach_placement | 12 | 1–100 m; placing on a surface and pocketing (tool 5), mounting on a wall (tool 2), path points (tool 3) |
| look_inertia | 0.03 | 0–0.1 s (IPC 0.29); mouse look smoothing, 0 = raw input (lowest latency) |
| move_inertia | 0.05 | 0–0.3 s (IPC 0.29); how quickly walking speeds up and slows down |
| view_bob_roll | 0.4 | 0–2° (IPC 0.29); head tilt per stride on top of the view bob |
| carry_turn | 0.11 | 0–0.4 s (IPC 0.29); how long a carried window takes to turn to face you, 0 = rigid |
| carry_follow | 0.04 | 0–0.3 s (IPC 0.29); how far a carried window trails behind its grab point when you turn, 0 = rigid |
The graphics reduced_motion setting turns off the view bob, its head tilt, the carry easing and the dynamic reticle whatever these settings say. Every settings preset uses these defaults today; a saved value is an override that stays when you change the preset. The graphics frame_pacing setting (IPC 0.29, even or max_rate, from the preset) chooses how a rate-capped offload renderer spaces its frames. Clicking into a window with the normal tool has no reach limit; beyond the other limits the action is refused and a notice says how far away the target is.
The reticle shows what the current tool or held Super gesture would do: a valid target gets corner brackets in the valid colour, a target out of reach turns the reticle to the warning colour with a hollow centre and a Too far: N m label (a refused action also flashes it), a target that can’t take the action turns the reticle into an x in the warning colour, and carrying a window shows brackets in the reticle colour. Shape changes go with every colour change, so no state relies on colour alone. The reticle is hidden in the free cursor and follows the pointer while typing.
Workspaces
Section titled “Workspaces”Entering the world switches the output to the free room, native workspace 20 (windows.world_workspace). Each area of the loaded world has a default home at windows.workspace_base (20) + its slot: slot 01 is workspace 21, slot 02 is 22, and so on. Any Hyprland workspace bind or the Director switching to a home travels to that area, and windows on it appear on the area’s main wall. Your own Lua config values and explicit workspace.bind homes win over these defaults.