ludic/docs/language/input/input-cursor_mode.md

id	name	category	kind	tokens	sig	tip	order	ns	member
input-cursor_mode	Input.cursor_mode	input	namespace-method	Input.cursor_mode	Input.cursor_mode(mode)	Hide / lock / confine the OS mouse cursor to the window (windowed).	36	Input	cursor_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.

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()
  }
}