feat(input): #89 cursor capture — Input.cursor_mode (hide/lock/confine)
All checks were successful
bootstrap / cfree-fixpoint (push) Successful in 22s
ci / build-and-test (push) Successful in 2m24s
commit-lint / conventional-commits (push) Successful in 5s
docs / build-and-deploy (push) Successful in 29s

A windowed action game can hide the OS cursor and lock/confine the mouse to the
window. Input.cursor_mode(mode): 0 normal, 1 hidden (draw your own reticle),
2 locked (hidden + dissociated — the mouse feeds relative motion via
Input.mouse_dx/dy and Input.mouse_x/y is a clamped virtual cursor, FPS/twin-stick
aim), 3 confined (dissociated but visible; the mouse can't leave the window).
The platform auto-releases (shows + reconnects) while the window is not key
(Cmd-Tab) and on close, so the cursor is never left captured. Headless it is a
no-op (DCE'd).

Native macOS impl in cocoa.ll: [NSCursor hide]/[unhide] (ref-counted, toggled
only on change so the count stays balanced across focus changes),
CGAssociateMouseAndMouseCursorPosition, and CGGetLastMouseDelta for the relative
virtual cursor, behind a new win_cursor_mode intrinsic. Windowed-only behaviour
(not in the headless golden suite); example compiles headless and links
windowed. Full suite 115/0, fixpoint holds.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Orkun ÇAKILKAYA 2026-09-02 08:06:34 +03:00
parent f3f1336882
commit 3eb5447f74
11 changed files with 26543 additions and 26240 deletions

View file

@ -0,0 +1,34 @@
---
id: input-cursor_mode
name: Input.cursor_mode
category: input
kind: namespace-method
tokens: Input.cursor_mode
sig: Input.cursor_mode(mode)
tip: Hide / lock / confine the OS mouse cursor to the window (windowed).
order: 36
ns: Input
member: cursor_mode
---
Sets how a windowed game captures the OS mouse cursor:
- <code>0</code> normal (default) — the cursor is visible and free.
- <code>1</code> hidden — the cursor is hidden while the window is focused, so a game can draw its own reticle.
- <code>2</code> locked — hidden and dissociated from the mouse; the mouse feeds <em>relative</em> motion through <a href="input-mouse_dx.html"><code>Input.mouse_dx</code></a> / <code>mouse_dy</code>, and <a href="input-mouse_x.html"><code>Input.mouse_x</code></a> / <code>mouse_y</code> is a clamped virtual cursor — the FPS / twin-stick aim mode.
- <code>3</code> 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.
```ludic
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()
}
}
```