Skip to content
San Andreas Online Docs

requestFileCutscene

Client-side
SA:O APINative file cutscenes

Load one of GTA:SA's original mission cutscenes by name. The returned handle lets Lua start it, detect completion, skip it, and restore gameplay afterward.

Syntax

int|false requestFileCutscene(string name [, int visibleArea])

Arguments

namestring

Stock cutscene name from GTA's audio-track table, from one through seven characters.

visibleAreaintoptional

Optional SCM-style visible world area from 0 through 255. It does not change the player's interior.

Returns

A non-zero generation token, or false when the name or visible area is invalid, another camera lease is active, or GTA already has a file cutscene active.

Ownership and lifecycle

File cutscenes share GTA's exclusive camera lease. Release, resource shutdown, disconnect, or a camera takeover deletes the native cutscene before restoring gameplay state.

Important behavior
  • Loading is asynchronous. Wait for isFileCutsceneLoaded before starting playback.
  • When visibleArea is supplied, the lease captures GTA's current visible area before loading and restores it on explicit release, camera takeover, resource stop, or failed cleanup.
  • Managed loading repairs area 13 only on the current native cutscene-manager objects. Ordinary MTA objects keep their existing area behavior.

Example

local token = assert(requestFileCutscene("SWEET3A", 1))
-- Poll isFileCutsceneLoaded(token), then start after the server readiness barrier.

Where this comes from

SOURCECLuaCameraDefs.cppClient/mods/deathmatch/logic/luadefs/CLuaCameraDefs.cpp INTRODUCED / EXTENDEDe6e485ba2Read the commit and why the change was made TEST RESOURCE nines-and-aks test-resources/nines-and-aks
RELATED SA:O APIS

Continue exploring

Read the system guide →
isFileCutsceneLeaseActive Reports whether the calling resource still owns this file-cutscene generation. isFileCutsceneLoaded Reports whether GTA has finished loading the owned DAT/CUT/IFP cutscene data. startFileCutscene Starts an owned, fully loaded native file cutscene exactly once.

← Back to the SA:O Lua API · How Native file cutscenes works →