Cameras and transitions
Client scripts control cameras through GTA natives. Each camera has a native handle that you keep until the scene closes. Camera changes affect the local view and leave the player’s position and dimension unchanged.
Create a preview camera
Section titled “Create a preview camera”This example places a camera at position and points it toward a world-space
target, such as the centre of a vehicle. Use it in an already loaded scene.
It returns a function that restores the gameplay camera and destroys the preview:
// @ts-check/// <reference types="@revomp/types-client" />/// <reference types="@revomp/types-natives" />import * as natives from 'natives';
/** * Shows a static preview in an already loaded scene. * @param {import('revo-client').IVector3} position * @param {import('revo-client').IVector3} target */export function showPreviewCamera(position, target) { const camera = natives.createCamWithParams( 'DEFAULT_SCRIPTED_CAMERA', position.x, position.y, position.z, 0, 0, 0, 50, true, 2, ); if (!natives.doesCamExist(camera)) throw new Error('Could not create preview camera');
natives.pointCamAtCoord(camera, target.x, target.y, target.z); natives.renderScriptCams(true, false, 0, true, false, 0);
let closed = false; return () => { if (closed) return; closed = true;
natives.renderScriptCams(false, false, 0, true, false, 0); natives.destroyCam(camera, false); };}Creating an active camera and enabling scripted camera rendering are separate
steps. renderScriptCams(true, ...) displays the active scripted camera.
renderScriptCams(false, ...) returns to the gameplay camera.
The field of view in this example is 50 degrees. Camera rotations also use
degrees. When using setCamRot() and getCamRot(), keep the same rotation order
for both calls. When using entity rot values, convert radians to degrees and
account for the entity’s rotation order. See the native references for
camera rotation
and field of view.
pointCamAtCoord() keeps looking at a fixed world position. For a moving subject,
use pointCamAtEntity() with a ready entity and stop
using that target if it streams out.
Smooth camera changes
Section titled “Smooth camera changes”To blend from gameplay into a scripted camera, use
natives.renderScriptCams(true, true, 750, true, false, 0). The duration is in
milliseconds. Set the first argument to false to blend back to gameplay.
Keep the camera alive until the blend finishes, then destroy it.
RenderScriptCams reference.
Between two scripted cameras, use
natives.setCamActiveWithInterp(nextCamera, currentCamera, 750, 1, 1).
Create and configure the destination camera before starting the transition.
Keep both cameras alive while isCamInterpolating(nextCamera) is true.
The last two arguments are numeric easing parameters.
SetCamActiveWithInterp reference.
Fade through black
Section titled “Fade through black”doScreenFadeOut(duration) starts a fade to black. Wait for isScreenFadedOut()
before changing the view, then use doScreenFadeIn(duration) to reveal it.
Both durations are in milliseconds.
This helper switches between prepared views and waits for both fades. Its
finally block starts the fade-in even if the first wait or callback throws.
The caller can handle the rejected promise:
// @ts-check/// <reference types="@revomp/types-client" />/// <reference types="@revomp/types-natives" />import * as revo from 'revo-client';import * as natives from 'natives';
/** @param {() => void} changeView Switches between prepared camera views. */export async function switchUnderFade(changeView) { try { natives.doScreenFadeOut(250); await revo.waitFor(() => natives.isScreenFadedOut(), 2000); changeView(); } finally { natives.doScreenFadeIn(250); await revo.waitFor(() => natives.isScreenFadedIn(), 2000); }}The callback is synchronous. Prepare any required models or scene data before calling it. Run one transition at a time so overlapping fades cannot reveal the scene while another transition is still preparing it.
GTA fades affect the game image. Manage WebView visibility or CSS transitions separately. Camera changes and fades also leave player controls enabled. Use cursor and UI focus for menus, or control natives for a scene that needs to restrict gameplay input.
Distant scenes and loading
Section titled “Distant scenes and loading”For a camera far from the player, call
natives.setFocusPosAndVel(x, y, z, 0, 0, 0) at the scene location to direct GTA
map streaming there. Update the focus as the camera travels to a different area.
Call natives.clearFocus() when returning to the player.
Streaming focus and collision requests start loading work. Check the parts of the scene you need before revealing it:
| Requirement | Check |
|---|---|
| A script entity is available in GTA | Its ready property. |
| Collision around a loaded ped or vehicle | natives.hasCollisionLoadedAroundEntity(entity), after requesting collision at its location with requestCollisionAtCoord(). |
| A requested interior is ready | natives.isInteriorReady(interiorId) with the interior’s valid ID. |
These checks cover their respective assets. Entity readiness alone does not confirm that the surrounding map and textures have finished loading. Use bounded waits and keep a fallback view available if preparation fails. For an initial login scene, prepare it under the loading screen.
Network entities are streamed around the player’s position and dimension. Changing GTA’s streaming focus leaves that network selection unchanged. For a distant character-selection scene, place the player in the scene’s area and appropriate dimension through the server, then wait for the required entities.
Restore the previous view
Section titled “Restore the previous view”Keep camera rendering and streaming focus under one scene controller. The preview example assumes it owns the scripted view and returns to gameplay on close. If another scripted scene should resume, restore that scene’s camera instead.
Call the preview’s returned function when the interface closes or is cancelled.
Also clear any streaming-focus override and restore input settings changed for
the scene. Destroy individual camera handles you created, since
destroyAllCams() can remove cameras used by other scripts.