Mouse capture

Captures the mouse for games that look around with it, hiding the pointer and sending its relative movement to the camera kits, and gives it back when nobody wants it, in pause or in menus.

Source: module-kits:kits/input_pointer_lock/usage/en.mdView Markdown source

Also read offline — CLI: grip-forge docs input-pointer-lockMCP tool: gripforge_docs { "topic": "input-pointer-lock" }

Mouse capture (input.pointer_lock) #

What it is for #

Captures the mouse for games that look around with it, hiding the pointer and sending its relative movement to the camera kits, and gives it back when nobody wants it, in pause or in menus.

It needs game.engine; installing it brings them in.

Turn it on #

Install the kit in a project, then change a setting (the values shown are its defaults):

gripforge_gamekit_install   { project_id: "gkp_…", id: "input.pointer_lock" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "input.pointer_lock",
                              config: { "capture": "click", "when": "auto" } }

First example #

This is the body of the passing test attaching_asks_the_host_to_lock_and_the_host_confirms; the helper functions it calls are defined at the top of the same test file.

#[test]
fn attaching_asks_the_host_to_lock_and_the_host_confirms() {
    let mut s = eager();
    assert_eq!(c(&mut s, "attach", json!([true])), json!(true));
    assert_eq!(calls(&mut s), json!(["lock"]));
    assert_eq!(c(&mut s, "hostChanged", json!([true])), json!(true));
    assert_eq!(c(&mut s, "isCaptured", json!([])), json!(true));
    assert_eq!(s.host.state.get("pointer.captured"), Some(&json!(true)));
    assert_eq!(topics(&mut s, "pointer.captured").len(), 1);
    // The same answer twice changes nothing.
    assert_eq!(c(&mut s, "hostChanged", json!([true])), json!(false));
    assert_eq!(topics(&mut s, "pointer.captured").len(), 1);
    assert_eq!(state(&mut s)["blocked"], Json::Null);
    // Detaching forgets the port: the calls list is empty again.
    assert_eq!(c(&mut s, "attach", json!([false])), json!(false));
    assert_eq!(calls(&mut s), json!([]));
}

Settings and defaults #

Descriptions come from the kit manifest and stay in English.

Setting	Type	Default	Range or values	Meaning
`capture`	string	`"click"`	`click`, `play`, `manual`	click: the first capture waits for a click in the game, then coming back to the game captures again; play: asked as soon as the…
`when`	string	`"auto"`	`auto`, `always`, `requests`	auto: while a kit asks, a look service is mounted (lookServices) or the control scheme of the game captures the pointer; always:…
`lookServices`	array	`["camera.look"]`		Capabilities that receive every movement at once through add(dx, dy) (pixels, right and down positive).
`cursorTopics`	array	`[{"open": "dialogue.started", "close": "dialo…`		Interfaces that need the cursor: the pointer is released from the event `open` to the event `close`.
`fullscreenGrace`	number	`0.5`	0–5	Seconds around an entry in fullscreen during which a capture the host took back is armed again (a browser may give the pointer…

Services, events, variables #

Service input.pointer_lock: capture(owner), release(owner), requesters(), showCursor(owner), hideCursor(owner), cursors(), isCaptured(), wanted(), available(), state(), movement(), consume(); host side: attach(port), hostChanged(locked), hostRefused(reason), hostMove(dx, dy, free), gesture(), hostCalls().
Events emitted:
- pointer.captured — The host really captured the pointer.
- pointer.released (reason) — The pointer is free again: nobody wants it (request), the game does not play (pause), a menu (menu), a kit needs the cursor (cursor), a touch screen…
- pointer.armed (reason) — The host took the pointer back while the display entered fullscreen: the kit is armed, the next gesture captures again.
- pointer.refused (reason, armed) — The host refused the capture: gesture (outside a player gesture: armed, asked again at the next click) or denied.
Events listened to: game.phase, menu.screen, input.device, fullscreen.changed
Variables:
- pointer.captured (boolean) — Pointer captured

Hooks and modding #

Moddable settings: capture, when, cursorTopics, fullscreenGrace

Engines #

Declared targets: web, godot, unity, unreal, rust. gripforge kit api input.pointer_lock lists the exact settings and services of your version.

Versions #

Kit version 1.1.0.