Skip to content

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.

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.

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.

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
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 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.

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.

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.

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.