Scripted camera - Revision history

QCherry: Update 0.1.3 camera world placement, streaming safety and far camera test

2026-09-09T00:07:56Z

Update 0.1.3 camera world placement, streaming safety and far camera test

← Older revision		Revision as of 00:07, 9 September 2026
Line 37:		Line 37:
	</syntaxhighlight>		</syntaxhighlight>

	Server-side <code>true</code> does not confirm the target client's camera is ready, accepts ownership, ~~satisfies the distance limit~~ or displays the requested view. There are no server camera getters or server camera-acknowledgement events. Use client scripting for sequences that must wait for execution results. Do not mix client and server ownership within one sequence.		Server-side <code>true</code> does not confirm the target client's camera is ready, accepts ownership, has finished world streaming or displays the requested view. There are no server camera getters or server camera-acknowledgement events. Use client scripting for sequences that must wait for execution results. Do not mix client and server ownership within one sequence.

	== Units, poses and limits ==		== Units, poses and limits ==
Line 46:		Line 46:
	\| Position \|\| World-space metres; finite coordinates between -1,000,000 and 1,000,000		\| Position \|\| World-space metres; finite coordinates between -1,000,000 and 1,000,000
	\|-		\|-
	\| Distance from player \|\| ~~Camera must remain within 100 m of~~ the local character, ~~including during movement~~		\| Distance from player \|\| No distance limit relative to the local character; positions, paths and orbits may target distant locations in the current world, subject to the coordinate limits
	\|-		\|-
	\| Rotation \|\| Pitch, yaw and roll in degrees; finite absolute values at most 360,000; shortest-angle interpolation		\| Rotation \|\| Pitch, yaw and roll in degrees; finite absolute values at most 360,000; shortest-angle interpolation
Line 71:		Line 71:
	<code>orbitCamera(center, options)</code> takes a fixed <code>{x,y,z}</code> centre, not a player ID. Defaults are radius 5 m, height 2 m, startAngle 0 degrees, sweepAngle 360 degrees, loop false and easing smooth. Radius must be 0.1 to 50 m, height -50 to 50 m, startAngle within +/-360,000 degrees and sweepAngle within +/-3600 degrees. A negative sweep reverses direction. The current FOV is preserved.		<code>orbitCamera(center, options)</code> takes a fixed <code>{x,y,z}</code> centre, not a player ID. Defaults are radius 5 m, height 2 m, startAngle 0 degrees, sweepAngle 360 degrees, loop false and easing smooth. Radius must be 0.1 to 50 m, height -50 to 50 m, startAngle within +/-360,000 degrees and sweepAngle within +/-3600 degrees. A negative sweep reverses direction. The current FOV is preserved.

	Client-side options must explicitly provide <code>durationMs</code> from 100 to 600,000. On the server, the options table is required but a missing durationMs defaults to 10,000. The centre does not follow a moving player. The complete orbit must fit the ~~player's 100 m camera bound; the~~ conservative check ~~includes centre~~ distance ~~plus~~ the ~~radius/height extent~~.		Client-side options must explicitly provide <code>durationMs</code> from 100 to 600,000. On the server, the options table is required but a missing durationMs defaults to 10,000. The centre does not follow a moving player. The centre and complete orbit extent must fit the finite coordinate range: <code>center.x +/- radius</code>, <code>center.y +/- radius</code> and <code>center.z + height</code> must each remain between -1,000,000 and 1,000,000 metres. This conservative check applies even to a partial sweep; it is not a distance limit from the character.

	== Acknowledgements and cached getters ==		== Acknowledgements and cached getters ==
Line 129:		Line 129:
	Resource stop/start failure automatically cleans up camera ownership; do not depend on a camera-reset callback while the resource is closing. Use the normal resource-stop lifecycle to cancel your own timers. For a still-running resource, [[onClientCameraReset]] reports forced native lifecycle cleanup or IPC invalidation. Native forced cleanup targets the camera owner; IPC disconnect also notifies affected query-only resources with cached state or pending requests. The cache, pending requests and ownership bookkeeping are cleared before the callback. On IPC disconnect, stateJson can be empty; this notification alone does not prove a newly restored view has rendered. Wait for world/spawn readiness before starting again. Old request IDs and connection generations must not be replayed.		Resource stop/start failure automatically cleans up camera ownership; do not depend on a camera-reset callback while the resource is closing. Use the normal resource-stop lifecycle to cancel your own timers. For a still-running resource, [[onClientCameraReset]] reports forced native lifecycle cleanup or IPC invalidation. Native forced cleanup targets the camera owner; IPC disconnect also notifies affected query-only resources with cached state or pending requests. The cache, pending requests and ownership bookkeeping are cleared before the callback. On IPC disconnect, stateJson can be empty; this notification alone does not prove a newly restored view has rendered. Wait for world/spawn readiness before starting again. Old request IDs and connection generations must not be replayed.

	Camera movement does not change the server's area of interest: distant players/NPCs/monsters are still replicated relative to the character. This API is not long-range spectator support. The older experimental <code>setCameraTarget</code>/<code>resetCamera</code> entry points are separate APIs, not aliases of these functions; remote-player target following is not implemented by this scripted-camera feature.		== Distant views and world streaming ==

			Camera positions, paths and orbits are not restricted by distance from the local character. They address locations in the current world; they do not switch maps or make coordinates outside the game's actual terrain meaningful.

			Unreal's standard local PlayerController streaming source follows its active <code>ViewTarget</code>, which this API changes to the scripted camera.

			Before taking that view, the native module adds its own <code>WorldPartitionStreamingSourceComponent</code> to the validated local pawn. The engine follows the component owner's position, preserving a streaming source around the character without teleporting it or freezing input. It uses the world's default grid loading range without changing global streaming settings or existing sources. If this safeguard cannot be prepared, camera takeover is rejected with <code>camera-pawn-streaming-source-unavailable</code>.

			The pawn's source remains active throughout a reset blend until the return is confirmed. Deferred cleanup or a foreign cutscene keeps it until a safe return to the pawn or pawn/world teardown. <code>stopCameraMovement</code> and natural <code>completed</code> do not release it because scripted camera ownership remains active. Keeping both areas loaded can increase memory and streaming costs and affect frame rate.

			World streaming is asynchronous: a large camera jump can initially show missing terrain, low-detail scenery or assets still loading. An <code>applied</code>, <code>completed</code> or <code>state</code> acknowledgement does not confirm streaming completion, and <code>ready</code> describes camera/world context rather than readiness of every visible asset. A fresh pose read-back checks where the camera is, not whether the remote scenery has finished loading. Allow time for streaming and manually check the distant scene and the return to the character; camera commands do not provide an all-visible-assets-loaded event.

			Camera movement does not change the server's area of interest: distant players/NPCs/monsters are still replicated relative to the character. Streaming scenery around the camera does not request those remote multiplayer entities. This API is not long-range multiplayer spectator support. The older experimental <code>setCameraTarget</code>/<code>resetCamera</code> entry points are separate APIs, not aliases of these functions; remote-player target following is not implemented by this scripted-camera feature.

	== Example: a moving login background ==		== Example: a moving login background ==
Line 207:		Line 219:
	== Manual test in the bundled GothicRP resource ==		== Manual test in the bundled GothicRP resource ==

	After login and confirmed character spawn, run <code>/cameratest</code> in a safe place. ~~It exercises~~ position, rotation including roll, LookAt, FOV, cached getters, full poses, smooth and linear motion, paths/holds/loops, orbits, stop, movement replacement and reset. <code>/cameratest stop</code> cancels the ~~sequence~~ and requests a reset. Chat messages are in English.		After login and confirmed character spawn, run <code>/cameratest</code> in a safe place. Its original 19 stages remain local to the character and exercise position, rotation including roll, LookAt, FOV, cached getters, full poses, smooth and linear motion, paths/holds/loops, orbits, stop, movement replacement and reset.

			The optional <code>/cameratest far</code> runs a separate 14-stage sequence around a fixed scene approximately 300 m from the starting character position. It tests a distant position and LookAt, smooth movement, a three-point path, a full orbit, a reverse looping orbit, stop and return to the player camera. Five fresh state queries, issued at least 350 ms after the corresponding acknowledgement, verify that the camera is more than 200 m from the starting character position, is stopped where expected, and reaches the requested endpoints within 1 m. The final reset is acknowledged and followed by a fresh inactive/not-moving check. The far test reports an error on the old distance-limited client or when an acknowledgement arrives without the expected position change.

			<code>/cameratest stop</code> cancels either sequence and requests a reset. A missing native acknowledgement fails the current step after 20 seconds and requests a reset. Restarting a test retires the previous run's timers and pending request; delayed results from that run do not advance the new sequence. Chat messages are in English.

	~~This is a~~ GothicRP resource ~~command~~, not a built-in camera ~~API~~ available in every gamemode. ~~It does~~ not teleport the character or modify progression. ~~The sequence waits for native acknowledgements, but a~~ success report ~~still requires~~ a human ~~to judge visual~~ movement and ~~the~~ final return to the player camera.		These are GothicRP resource commands, not built-in camera APIs available in every gamemode. They do not teleport the character, freeze input or modify progression. A success report confirms the tested commands/read-backs, not terrain loading or rendered image quality: a human must inspect the distant scenery, camera movement and final return to the player camera.

	[[Category:Lua API]]		[[Category:Lua API]]
	[[Category:Lua Examples]]		[[Category:Lua Examples]]

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

2026-09-08T23:51:05Z

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

New page

__NOTOC__
= Scripted camera =

<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;">The scripted-camera functions and client events described here are available in G1R:MP 0.1.3 and later.</div>
</div>

Use a scripted camera for a login background, character presentation, a fixed shot, a travelling shot or an orbit. It controls the local view without teleporting the character or possessing a spectator pawn. Camera control does not freeze player input, make the character invulnerable, or change server gameplay rules.

== Function reference ==

All functions support the documented lowerCamelCase name and an equivalent PascalCase name: for example, <code>setCameraPos</code> and <code>SetCameraPos</code>.

{| class="wikitable"
! Purpose !! Functions !! Execution side
|-
| Position, rotation and view || [[setCameraPos]], [[setCameraRot]], [[setCameraLookAt]], [[setCameraFOV]], [[setCameraPose]] || Client and server
|-
| Movement || [[moveCameraTo]], [[playCameraPath]], [[orbitCamera]], [[stopCameraMovement]] || Client and server
|-
| Restore gameplay view || [[resetCameraPos]] || Client and server
|-
| Cached read-back || [[getCameraPos]], [[getCameraRot]], [[getCameraFOV]], [[getCameraState]] || Client only
|-
| Refresh cached state || [[requestCameraState]] || Client only
|}

Client mutators return a positive request ID, or <code>false</code> when validation or queuing fails. The ID is not an execution acknowledgement. Server mutators prepend <code>playerId</code> and return a queued boolean instead:

<syntaxhighlight lang="lua">
-- Client-side, current resource and local player:
local requestId = setCameraFOV(70)

-- Server-side, a connected player:
local queued = setCameraFOV(playerId, 70)
</syntaxhighlight>

Server-side <code>true</code> does not confirm the target client's camera is ready, accepts ownership, satisfies the distance limit or displays the requested view. There are no server camera getters or server camera-acknowledgement events. Use client scripting for sequences that must wait for execution results. Do not mix client and server ownership within one sequence.

== Units, poses and limits ==

{| class="wikitable"
! Value !! Contract
|-
| Position || World-space metres; finite coordinates between -1,000,000 and 1,000,000
|-
| Distance from player || Camera must remain within 100 m of the local character, including during movement
|-
| Rotation || Pitch, yaw and roll in degrees; finite absolute values at most 360,000; shortest-angle interpolation
|-
| FOV || 15 to 150 degrees inclusive
|-
| Timings || Whole milliseconds; general movement duration 0 to 600,000; reset blend 0 to 10,000
|-
| Easing || Case-sensitive <code>linear</code>, <code>smooth</code>, <code>in</code>, <code>out</code>; default <code>smooth</code>
|}

A complete pose has <code>x, y, z, pitch, yaw, roll, fov</code>. Client-side <code>setCameraPose</code>, <code>moveCameraTo</code> and the first path point can inherit missing fields from the current resource's ready acknowledged cache. Without that cache, supply all seven fields. Later client path points inherit missing pose fields from the previous point.

On the server, <code>setCameraPose</code>, <code>moveCameraTo</code> and '''every''' path point independently require <code>x,y,z</code>. Missing angles default to 0 and FOV to 90. There is no server-side pose inheritance.

Position-only, rotation-only and FOV-only setters preserve the remaining current camera fields. Omitting <code>roll</code> in <code>setCameraRot</code> sets roll to 0. <code>setCameraLookAt</code> rotates towards a fixed world point, sets roll to 0, and fails if the target coincides with the camera position. It is not a persistent follow attachment.

=== Paths ===

<code>playCameraPath(points, options)</code> accepts a dense 1-based array of 1 to 32 poses. Each point's <code>durationMs</code> defaults to 2000 and must be at least 1; <code>holdMs</code> defaults to 0. The sum of all travel and hold times must not exceed 600,000 ms. Options are <code>loop=false</code> and <code>easing="smooth"</code> by default. A loop repeats the sequence until stopped, reset or interrupted; the 600,000 ms limit applies to one complete sequence, not the lifetime of a loop.

=== Orbits ===

<code>orbitCamera(center, options)</code> takes a fixed <code>{x,y,z}</code> centre, not a player ID. Defaults are radius 5 m, height 2 m, startAngle 0 degrees, sweepAngle 360 degrees, loop false and easing smooth. Radius must be 0.1 to 50 m, height -50 to 50 m, startAngle within +/-360,000 degrees and sweepAngle within +/-3600 degrees. A negative sweep reverses direction. The current FOV is preserved.

Client-side options must explicitly provide <code>durationMs</code> from 100 to 600,000. On the server, the options table is required but a missing durationMs defaults to 10,000. The centre does not follow a moving player. The complete orbit must fit the player's 100 m camera bound; the conservative check includes centre distance plus the radius/height extent.

== Acknowledgements and cached getters ==

The built-in local event [[onClientCameraCommandResult]] is attached to <code>resourceRoot</code>; no <code>addEvent</code> call is needed. Its callback is:

<syntaxhighlight lang="lua">
function(requestId, ok, phase, errorText, stateJson)
</syntaxhighlight>

{| class="wikitable"
! Command !! Successful phases
|-
| requestCameraState || <code>state</code>
|-
| Position/rotation/LookAt/FOV/pose setters; stopCameraMovement || <code>applied</code>
|-
| moveCameraTo; non-looping playCameraPath/orbitCamera || <code>applied</code>, then <code>completed</code> using the same requestId
|-
| Looping path/orbit || <code>applied</code>; no completed while looping
|-
| resetCameraPos || <code>reset</code> after the restore transition
|}

Execution rejection reports <code>ok=false, phase="error"</code>. Replacing, stopping or resetting an active movement can report <code>ok=false, phase="cancelled"</code> for the earlier movement request. Interrupted reset requests can report an error. Match request IDs: a cancellation for an older movement is not a failure of the new command.

A validated state snapshot is cached before the callback, including an available valid snapshot attached to a failed result. A query can be submitted before the local camera/world is ready if IPC is connected, and can successfully return <code>phase="state", ready=false</code>; always check ready before using the pose or starting control. <code>getCameraPos</code> returns <code>{x,y,z}</code>, <code>getCameraRot</code> returns <code>{pitch,yaw,roll}</code>, and <code>getCameraFOV</code> returns a number. These return false when no ready snapshot exists. <code>getCameraState</code> returns false with no cache, or a table which may have <code>ready=false</code>.

The state table contains:

{| class="wikitable"
! Fields !! Meaning
|-
| x, y, z; pitch, yaw, roll; fov || Last acknowledged engine camera pose, in metres/degrees
|-
| playerX, playerY, playerZ || Local character position in metres
|-
| ready || Whether valid local-world/camera context is available for the snapshot
|-
| active || Whether the scripted camera is active
|-
| moving || Whether a scripted movement is active
|-
| sampleTimeMs || Timestamp of the native sample; not a UTC wall-clock time
|}

The event's JSON additionally includes <code>version=1</code>; <code>getCameraState()</code> does not expose that version field. Failed results may have empty stateJson, so parse defensively.

'''Getters are not synchronous engine queries.''' An applied acknowledgement confirms command handling; completed confirms the interpolation reached its end. Neither proves the new camera view has rendered. An immediate acknowledgement snapshot can still contain the previous frame's pose. If you need post-change values, wait another frame or a short timer, call <code>requestCameraState</code>, and handle its <code>state</code> result. Do not issue a new query unconditionally for every result, which would create a feedback loop.

== Ownership, stopping and cleanup ==

Only one resource/origin can own scripted camera control at a time. A client resource and a server resource with the same name are still different origins. Another resource's mutating request is rejected while the owner is active. State queries do not take ownership and can be used by other client resources.

<code>stopCameraMovement</code> leaves the camera in place and keeps ownership. A non-looping movement reaching completed also leaves the scripted camera active. Use <code>resetCameraPos</code> to restore the player's gameplay camera and release your ownership. Reset is owner-scoped; it does not steal another resource's camera or forcefully replace a foreign cutscene.

Resource stop/start failure automatically cleans up camera ownership; do not depend on a camera-reset callback while the resource is closing. Use the normal resource-stop lifecycle to cancel your own timers. For a still-running resource, [[onClientCameraReset]] reports forced native lifecycle cleanup or IPC invalidation. Native forced cleanup targets the camera owner; IPC disconnect also notifies affected query-only resources with cached state or pending requests. The cache, pending requests and ownership bookkeeping are cleared before the callback. On IPC disconnect, stateJson can be empty; this notification alone does not prove a newly restored view has rendered. Wait for world/spawn readiness before starting again. Old request IDs and connection generations must not be replayed.

Camera movement does not change the server's area of interest: distant players/NPCs/monsters are still replicated relative to the character. This API is not long-range spectator support. The older experimental <code>setCameraTarget</code>/<code>resetCamera</code> entry points are separate APIs, not aliases of these functions; remote-player target following is not implemented by this scripted-camera feature.

== Example: a moving login background ==

This client-side example demonstrates the public APIs. Call <code>beginLoginCamera()</code> from your UI flow only after the local game world/player camera is ready. Call <code>finishLoginCameraAfterSpawn()</code> only after your resource has confirmed the actual character spawn has completed. Authentication success alone is not that confirmation. These two helper functions are defined by the example; they are not built-in events or engine functions.

<syntaxhighlight lang="lua" line>
local showingLogin = false
local queryRequest, fovRequest, orbitRequest, resetRequest
local orbitCenter

function beginLoginCamera()
if showingLogin then return end
showingLogin = true
queryRequest = requestCameraState()
if not queryRequest then showingLogin = false end
end

local function releaseLoginCamera()
showingLogin = false
queryRequest, fovRequest, orbitRequest = nil, nil, nil
resetRequest = resetCameraPos(800)
if not resetRequest then
outputDebugString("Login camera reset was not queued", 2)
end
end

function finishLoginCameraAfterSpawn()
releaseLoginCamera()
end

addEventHandler("onClientCameraCommandResult", resourceRoot,
function(requestId, ok, phase, errorText)
if requestId == resetRequest then
if not ok or phase == "reset" then resetRequest = nil end
if not ok then outputDebugString("Camera reset: " .. tostring(errorText), 2) end
return
end
if not showingLogin then return end
if requestId ~= queryRequest and requestId ~= fovRequest
and requestId ~= orbitRequest then return end
if not ok then
outputDebugString("Login camera: " .. tostring(errorText), 2)
releaseLoginCamera() -- Abort this presentation and release our view.
return
end
if requestId == queryRequest and phase == "state" then
queryRequest = nil
local state = getCameraState()
if not state or not state.ready then
showingLogin = false
return
end
orbitCenter = {x=state.playerX, y=state.playerY, z=state.playerZ + 1.2}
fovRequest = setCameraFOV(70)
if not fovRequest then releaseLoginCamera() end
elseif requestId == fovRequest and phase == "applied" then
fovRequest = nil
orbitRequest = orbitCamera(orbitCenter,
{radius=5, height=2, durationMs=30000, loop=true, easing="linear"})
if not orbitRequest then releaseLoginCamera() end
elseif requestId == orbitRequest and phase == "applied" then
outputDebugString("Login camera orbit started")
end
end)

addEventHandler("onClientCameraReset", resourceRoot, function(reason)
showingLogin = false
queryRequest, fovRequest, orbitRequest, resetRequest = nil, nil, nil, nil
orbitCenter = nil
outputDebugString("Login camera invalidated: " .. tostring(reason))
end)
</syntaxhighlight>

For production UI, also bound the time spent waiting for acknowledgements and cancel your own timers when the resource stops or the camera is invalidated. Do not retry indefinitely or reacquire the camera on every frame. Freeze/unfreeze gameplay input separately only if your resource's login flow requires it; camera ownership itself does not manage input.

== Manual test in the bundled GothicRP resource ==

After login and confirmed character spawn, run <code>/cameratest</code> in a safe place. It exercises position, rotation including roll, LookAt, FOV, cached getters, full poses, smooth and linear motion, paths/holds/loops, orbits, stop, movement replacement and reset. <code>/cameratest stop</code> cancels the sequence and requests a reset. Chat messages are in English.

This is a GothicRP resource command, not a built-in camera API available in every gamemode. It does not teleport the character or modify progression. The sequence waits for native acknowledgements, but a success report still requires a human to judge visual movement and the final return to the player camera.

[[Category:Lua API]]
[[Category:Lua Examples]]