https://g1r-mp.com/wiki/index.php?action=history&feed=atom&title=Mouse_captureMouse capture - Revision history2026-09-19T15:45:40ZRevision history for this page on the wikiMediaWiki 1.46.0https://g1r-mp.com/wiki/index.php?title=Mouse_capture&diff=900&oldid=prevQCherry: Document upcoming 0.1.4 weapon confirmation and mouse camera APIs2026-09-19T13:53:43Z<p>Document upcoming 0.1.4 weapon confirmation and mouse camera APIs</p>
<p><b>New page</b></p><div>= Mouse capture =<br />
'''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.'''<br />
<br />
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: <code>true</code> from [[setMouseCapture]] means acceptance, not active input.<br />
<br />
== API ==<br />
* [[setMouseCapture]]: <code>boolean setMouseCapture(boolean enabled)</code>.<br />
* [[getMouseCaptureState]]: <code>string getMouseCaptureState()</code>, returning inactive, pending, active or suspended for the calling resource.<br />
* [[onClientMouseMove]]: <code>function(dx, dy, elapsedMs)</code>. 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.<br />
* [[onClientMouseCaptureChanged]]: <code>function(state, reason)</code>, delivered to the owning resource only.<br />
* [[UpdateCameraPose]] / <code>updateCameraPose</code>: coalesced updates for an already acquired scripted camera.<br />
<br />
== Ownership and safety ==<br />
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.<br />
<br />
Capture does not imply a camera lease. Acquire the camera with existing <code>RequestCameraState</code>, <code>SetCameraPose</code> and <code>onClientCameraCommandResult</code> before streaming poses. Release it separately with <code>ResetCameraPos</code>. GUI interaction pauses capture; simultaneous GUI dragging is not provided by this API.<br />
<br />
<syntaxhighlight lang="lua"><br />
-- Acquire your camera first and wait for its successful command result.<br />
local yaw, pitch = 0, -12<br />
addEventHandler("onClientMouseMove", resourceRoot, function(dx, dy, elapsedMs)<br />
yaw = (yaw + dx * 0.12) % 360<br />
pitch = math.max(-80, math.min(80, pitch - dy * 0.12))<br />
UpdateCameraPose({yaw = yaw, pitch = pitch})<br />
end)<br />
setMouseCapture(true)<br />
-- Later: setMouseCapture(false); ResetCameraPos(250)<br />
</syntaxhighlight><br />
<br />
== Development test ==<br />
The gothic_rp test commands require a spawned, authenticated character, enabled test tools and <code>admin.players</code> permission:<br />
* <code>/mousetest camera</code>, <code>/mousetest orbit</code>, <code>/mousetest observe</code>.<br />
* <code>/mousetest gui</code> checks suspension and return from GUI input.<br />
* F8 or <code>/mousetest stop</code> releases capture and restores the test camera. Automatic stop after 60 seconds.<br />
<br />
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.<br />
[[Category:Lua API]]</div>QCherry