QCherry: Document scripted camera API and events available from G1R:MP 0.1.3

2026-09-08T23:50:53Z

Document scripted camera API and events available from G1R:MP 0.1.3

New page

= requestCameraState =
<div style="background:#fff5f5; border:1px solid #d13b3b; border-left:5px solid #d13b3b; color:#111111; padding:0.85rem 1rem; margin:0.75rem 0 1rem;">
<div style="color:#111111; font-weight:bold; letter-spacing:0.04em;">AVAILABLE FROM UPDATE 0.1.3</div>
<div style="color:#111111; margin-top:0.25rem;">This function is available in G1R:MP 0.1.3 and later. The contract below includes the compatibility guarantees introduced in that update.</div>
</div>

Requests an asynchronous read-back of the local camera and local player position without taking camera ownership.

== Syntax ==
<syntaxhighlight lang="lua">
number|false requestCameraState()
</syntaxhighlight>

== Parameters ==
This function does not accept parameters.

== Returns ==
A positive requestId if queued, or false if the request cannot be submitted. A matching [[onClientCameraCommandResult]] with <code>ok=true, phase="state"</code> carries the snapshot; execution failure reports an error.

== Examples ==
Read a snapshot once; do not issue another query unconditionally inside the result handler.
<syntaxhighlight lang="lua" line>
-- Client-side: run after the local world and player camera are ready.
local query
addEventHandler("onClientCameraCommandResult", resourceRoot,
function(requestId, ok, phase, errorText, stateJson)
if requestId ~= query then return end
query = nil
if not ok or phase ~= "state" then
outputDebugString("Camera query failed: " .. tostring(errorText), 2)
return
end
local state = getCameraState()
if not state or not state.ready then return end
outputDebugString(("Player position: %.2f %.2f %.2f"):format(state.playerX, state.playerY, state.playerZ))
end)
query = requestCameraState()
if not query then outputDebugString("Camera query was not queued", 2) end
</syntaxhighlight>

== Notes ==
* Client-side only. Equivalent spelling: <code>RequestCameraState</code>.
* A query can be submitted before the local world/camera is ready, provided the IPC connection can accept it. A successful state response may have ready=false; check that field before using pose values or starting camera control. A successful Lua return is only a request ID, not an acknowledgement.
* Queries do not acquire the camera and can be issued by another resource while the current owner controls it.
* The resource cache is updated before the result callback, making [[getCameraPos]], [[getCameraRot]], [[getCameraFOV]] and [[getCameraState]] available there.
* Use the requestId to match replies and handle [[onClientCameraReset]] by discarding pending work. See [[Scripted camera]].

[[Category:Lua Functions]]
[[Category:Client Functions]]
[[Category:Camera Functions]]

RequestCameraState - Revision history

QCherry: Document scripted camera API and events available from G1R:MP 0.1.3