method
Input.cursor_mode
Input.cursor_mode(mode)
Sets how a windowed game captures the OS mouse cursor:
- 0 normal (default) — the cursor is visible and free.
- 1 hidden — the cursor is hidden while the window is focused, so a game can draw its own reticle.
- 2 locked — hidden and dissociated from the mouse; the mouse feeds relative motion through Input.mouse_dx / mouse_dy, and Input.mouse_x / mouse_y is a clamped virtual cursor — the FPS / twin-stick aim mode.
- 3 confined — dissociated but visible; the mouse cannot leave the window.
The platform **auto-releases** (shows the cursor and reconnects it) while the window is not the key window (Cmd-Tab), and restores it on window close, so the cursor is never left captured. On a headless / non-windowed build it is a no-op.
Example
program Aim {
property Tag { n: int = 0 }
model P { Tag }
@OnStart handler Boot { Input.cursor_mode(2) } # lock + hide for aiming
handler Draw phase Render {
Screen.clear(0x101018)
Screen.fill_rectangle(Input.mouse_x() - 2, Input.mouse_y() - 2, 4, 4, 0xffcc00)
Screen.show()
}
}