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

2026-09-09T00:07:53Z

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

← Older revision		Revision as of 00:07, 9 September 2026
Line 54:		Line 54:
	* Available in client-side and server-side resource scripts. Equivalent PascalCase spelling: <code>OrbitCamera</code>.		* Available in client-side and server-side resource scripts. Equivalent PascalCase spelling: <code>OrbitCamera</code>.
	* Client-side options must specify durationMs from 100 to 600,000 whole milliseconds. Server-side durationMs defaults to 10,000 when omitted.		* Client-side options must specify durationMs from 100 to 600,000 whole milliseconds. Server-side durationMs defaults to 10,000 when omitted.
	* startAngle is finite with an absolute maximum of 360,000 degrees. A negative sweepAngle reverses direction. The complete orbit extent must remain within ~~100~~ metres of the ~~local~~ player.		* startAngle is finite with an absolute maximum of 360,000 degrees. A negative sweepAngle reverses direction. The centre and complete orbit extent must remain within the finite world-coordinate range: centre.x +/- radius, centre.y +/- radius and centre.z + height must each stay between -1,000,000 and 1,000,000 metres, even for a partial sweep. This is not a distance limit from the player.
	* The current FOV is preserved. For login backgrounds, set FOV separately; use [[Scripted camera]] for a lifecycle-safe example.		* The current FOV is preserved. For login backgrounds, set FOV separately; use [[Scripted camera]] for a lifecycle-safe example.
	* Client success: <code>applied</code>, then <code>completed</code> only for a non-looping orbit. A looping orbit runs until stopped, reset, interrupted or invalidated.		* Client success: <code>applied</code>, then <code>completed</code> only for a non-looping orbit. A looping orbit runs until stopped, reset, interrupted or invalidated.
	* 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.		* 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 and ~~complete paths/~~orbits must ~~stay~~ within ~~100~~ metres of the ~~local character~~. Camera control does not move the character, change replication distance, freeze input, or enable remote-player spectating.		* 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]].		* 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 ~~that the resulting view has rendered~~. For a fresh read-back, request state after another frame or a short timer. See [[Scripted camera]] for lifecycle, acknowledgement and state-cache details.		* 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.

	[[Category:Lua Functions]]		[[Category:Lua Functions]]
	[[Category:Shared Functions]]		[[Category:Shared Functions]]
	[[Category:Camera Functions]]		[[Category:Camera Functions]]

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

2026-09-08T23:50:58Z

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

New page

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

Moves the scripted camera around a fixed world-space centre while looking at that centre.

== Syntax ==
<syntaxhighlight lang="lua">
-- Client-side
number|false orbitCamera(table center, table options)
-- Server-side
bool orbitCamera(int playerId, table center, table options)
</syntaxhighlight>

== Parameters ==
{| class="wikitable"
! Name !! Type !! Required !! Description
|-
| <code>playerId</code> || <code>int</code> || yes || Server-side only: the connected player whose local camera receives the command.
|-
| <code>center</code> || <code>table</code> || yes || Required numeric x/y/z centre coordinates in metres. The centre is captured at submission and does not automatically follow a moving player.
|-
| <code>options</code> || <code>table</code> || yes || radius=5 (0.1..50 m), height=2 (-50..50 m), startAngle=0 degrees, sweepAngle=360 (-3600..3600 degrees), durationMs, loop=false, easing="smooth".
|}

== Returns ==
'''Client-side:''' a positive <code>requestId</code>, or <code>false</code> when validation or queuing fails. Wait for [[onClientCameraCommandResult]] to learn the execution result. '''Server-side:''' <code>true</code> only means validated and queued for the connected player; <code>false</code> 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.
<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
orbitCamera({x=state.playerX, y=state.playerY, z=state.playerZ + 1.2},
{radius=5, height=2, durationMs=8000, loop=true, easing="linear"})
end)
query = requestCameraState()
if not query then outputDebugString("Camera query was not queued", 2) end
</syntaxhighlight>

== Notes ==
* Available in client-side and server-side resource scripts. Equivalent PascalCase spelling: <code>OrbitCamera</code>.
* Client-side options must specify durationMs from 100 to 600,000 whole milliseconds. Server-side durationMs defaults to 10,000 when omitted.
* startAngle is finite with an absolute maximum of 360,000 degrees. A negative sweepAngle reverses direction. The complete orbit extent must remain within 100 metres of the local player.
* The current FOV is preserved. For login backgrounds, set FOV separately; use [[Scripted camera]] for a lifecycle-safe example.
* Client success: <code>applied</code>, then <code>completed</code> only for a non-looping orbit. A looping orbit runs until stopped, reset, interrupted or invalidated.
* 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 and complete paths/orbits must stay within 100 metres of the local character. 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 that the resulting view has rendered. For a fresh read-back, request state after another frame or a short timer. See [[Scripted camera]] for lifecycle, acknowledgement and state-cache details.

[[Category:Lua Functions]]
[[Category:Shared Functions]]
[[Category:Camera Functions]]

OrbitCamera - Revision history

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

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