PlayCameraPath

playCameraPath

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.

Plays a sequence of camera poses with per-point travel times, optional holds and optional looping.

Syntax

-- Client-side
number|false playCameraPath(table points [, table options])
-- Server-side
bool playCameraPath(int playerId, table points [, table options])

Parameters

Name	Type	Required	Description
playerId	int	yes	Server-side only: the connected player whose local camera receives the command.
points	table	yes	Dense 1-based array of 1 to 32 pose tables. Each point has durationMs (default 2000, minimum 1) and holdMs (default 0).
options	table	no	Optional loop (boolean, default false) and easing (linear/smooth/in/out, default smooth).

Returns

Client-side: a positive requestId, or false when validation or queuing fails. Wait for onClientCameraCommandResult to learn the execution result. Server-side: true only means validated and queued for the connected player; false means rejected. A server return value is not a client acknowledgement.

Examples

Read the local camera/player state before issuing the command. The command's own result arrives separately in onClientCameraCommandResult.

-- 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
        playCameraPath({
            {x=state.playerX - 5, y=state.playerY, z=state.playerZ + 3,
                pitch=-15, yaw=0, roll=0, fov=75, durationMs=2000, holdMs=500},
            {x=state.playerX - 4, y=state.playerY + 3, z=state.playerZ + 3,
                pitch=-15, yaw=-35, roll=0, fov=70, durationMs=2500, holdMs=250}
        }, {loop=false, easing="smooth"})
    end)
query = requestCameraState()
if not query then outputDebugString("Camera query was not queued", 2) end

Notes

• Available in client-side and server-side resource scripts. Equivalent PascalCase spelling: PlayCameraPath.
• Client-side: the first point can inherit omitted pose fields from a ready acknowledged cache; without one it must contain all seven pose fields. Later points inherit missing pose fields from the previous point.
• Server-side: every point independently requires x/y/z. Missing angles default to 0 and FOV to 90; server points do not inherit the previous point's pose.
• The sum of all durationMs and holdMs values must not exceed 600,000 ms. Timings are non-negative integers; travel duration per point must be greater than 0. A looping path repeats this bounded sequence until stopped, reset or interrupted.
• Client success: applied, then completed for a non-looping path. Loops do not emit completed while running. Use stopCameraMovement to hold the current view or resetCameraPos to return to gameplay.
• Only the owning resource may change an already controlled camera. Server and client ownership are distinct, even when resource names match; use one side consistently for a camera sequence.
• Camera positions, paths and orbits have no distance limit relative to the local character. All world coordinates must remain finite and within -1,000,000 to 1,000,000 metres; the complete orbit extent is validated too. Camera control does not move the character, change replication distance, freeze input, or enable remote-player spectating.
• Use resetCameraPos to restore gameplay view. Resource stop, disconnect and world/character changes release camera ownership; see onClientCameraReset.
• An applied acknowledgement confirms command handling, not rendering or completion of world streaming. For a fresh read-back, request state after another frame or a short timer. See Scripted camera for distant scenes, lifecycle, acknowledgement and state-cache details.