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

2026-09-08T23:51:01Z

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

New page

= onClientCameraCommandResult =
<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 event is available in G1R:MP 0.1.3 and later. The contract below includes the compatibility guarantees introduced in that update.</div>
</div>

Reports execution progress or the outcome of a camera command submitted by the current client resource.

== Availability ==
This event is available in '''client-side''' scripts.

== Callback signature ==
<syntaxhighlight lang="lua">
onClientCameraCommandResult(number requestId, bool ok, string phase, string errorText, string stateJson)
</syntaxhighlight>

== Parameters ==
{| class="wikitable"
! Name !! Type !! Description
|-
| <code>requestId</code> || <code>number</code> || Identifier returned by the originating camera function. Match this before handling the result.
|-
| <code>ok</code> || <code>bool</code> || True for successful progress/results; false for execution errors or cancelled motion.
|-
| <code>phase</code> || <code>string</code> || state, applied, completed, reset, error or cancelled; see the operation-specific rules below.
|-
| <code>errorText</code> || <code>string</code> || Diagnostic reason; normally empty on success. Do not use this as a localized user-facing API contract.
|-
| <code>stateJson</code> || <code>string</code> || JSON camera-state snapshot when available; parse defensively with fromJSON. It can be empty if there is no valid snapshot.
|}

== Examples ==
Query once and correlate the response.
<syntaxhighlight lang="lua" line>
local pending
addEventHandler("onClientCameraCommandResult", resourceRoot,
function(requestId, ok, phase, errorText, stateJson)
if requestId ~= pending then return end
if not ok then
pending = nil
outputDebugString("Camera failed: " .. tostring(errorText), 2)
return
end
if phase == "state" then
pending = nil
local state = getCameraState()
if state and state.ready then
outputDebugString("FOV: " .. tostring(state.fov))
end
end
end)
-- Call when the local game world and camera are ready.
pending = requestCameraState()
</syntaxhighlight>

== Notes ==
* Built-in local event: attach to resourceRoot; do not call addEvent to declare it and do not send it across the network.
* requestCameraState succeeds with state, which may contain ready=false before the local camera is ready. Position/rotation/LookAt/FOV/pose setters and stopCameraMovement succeed with applied.
* moveCameraTo, playCameraPath and orbitCamera first acknowledge applied. Non-looping movement later emits completed; loops continue until stopped, replaced, reset or invalidated and do not emit completed while looping.
* resetCameraPos succeeds with reset after the return transition. A superseded movement can emit ok=false/cancelled for its old requestId. An interrupted reset can emit ok=false/error.
* A request rejected synchronously with false has no valid requestId to await. Server-side mutation calls return only a queued boolean and do not produce this event in server Lua.
* A valid snapshot is cached before the callback. Getters see that snapshot inside the handler; phase applied/completed does not certify that the new view has rendered. Request another snapshot after the next frame or a short timer if required.
* Stale generations, wrong-resource and unknown-request results are discarded. Use [[onClientCameraReset]] to discard pending client-side work after forced cleanup.
* Snapshot fields and owner rules are documented in [[Scripted camera]].

[[Category:Lua Events]]
[[Category:Client Events]]

OnClientCameraCommandResult - Revision history

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