RequestCameraState

requestCameraState

AVAILABLE FROM UPDATE 0.1.3

This function is available in G1R:MP 0.1.3 and later. The contract below includes the compatibility guarantees introduced in that update.

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

Syntax

number|false requestCameraState()

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 ok=true, phase="state" carries the snapshot; execution failure reports an error.

Examples

Read a snapshot once; do not issue another query unconditionally inside the result handler.

-- 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

Notes

• Client-side only. Equivalent spelling: RequestCameraState.
• 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.