Mouse capture

Mouse capture

Since 0.1.4 — in development. Not available in public 0.1.3. Matching client and server are required. Live game acceptance tests are still required.

Client Lua can acquire relative mouse motion for camera scripts without replacing GUI click handling. One resource owns capture; another resource cannot steal it. Acquisition is asynchronous: true from setMouseCapture means acceptance, not active input.

API

• setMouseCapture: boolean setMouseCapture(boolean enabled).
• getMouseCaptureState: string getMouseCaptureState(), returning inactive, pending, active or suspended for the calling resource.
• onClientMouseMove: function(dx, dy, elapsedMs). Relative raw counts, positive X right and positive Y down, not pixels or degrees. Apply sensitivity; do not multiply displacement by elapsed time. Only non-zero movement is delivered, at most approximately 60 events/second. Absolute tablet input is not included.
• onClientMouseCaptureChanged: function(state, reason), delivered to the owning resource only.
• UpdateCameraPose / updateCameraPose: coalesced updates for an already acquired scripted camera.

Ownership and safety

Capture suspends on loss of game focus, GUI or keyboard capture, detected native menu/input blocking, death or missing game state. It resumes after the blocker clears and native confirmation arrives. Resource stop and IPC loss release capture. A 750 ms native lease expires when heartbeats stop. Native look locking balances only this feature's own lock; it does not reset another subsystem's lock.

Capture does not imply a camera lease. Acquire the camera with existing RequestCameraState, SetCameraPose and onClientCameraCommandResult before streaming poses. Release it separately with ResetCameraPos. GUI interaction pauses capture; simultaneous GUI dragging is not provided by this API.

-- Acquire your camera first and wait for its successful command result.
local yaw, pitch = 0, -12
addEventHandler("onClientMouseMove", resourceRoot, function(dx, dy, elapsedMs)
    yaw = (yaw + dx * 0.12) % 360
    pitch = math.max(-80, math.min(80, pitch - dy * 0.12))
    UpdateCameraPose({yaw = yaw, pitch = pitch})
end)
setMouseCapture(true)
-- Later: setMouseCapture(false); ResetCameraPos(250)

Development test

The gothic_rp test commands require a spawned, authenticated character, enabled test tools and admin.players permission:

• /mousetest camera, /mousetest orbit, /mousetest observe.
• /mousetest gui checks suspension and return from GUI input.
• F8 or /mousetest stop releases capture and restores the test camera. Automatic stop after 60 seconds.

Verify Alt-Tab, native menus/inventory, chat, GUI clicks, resource restart and disconnect in the live game. Automated tests do not establish that every native G1R menu/custom input path respects the look gate.