Runtime interfaces and source limitations
Writing a resource in Lua, JavaScript or C# is different from implementing a new scripting runtime. The official runtime implementation manual describes CitizenFX components under code/components/ implementing fxOM interfaces defined in fxScripting.idl. This page records that interface surface and the places where the source supplies no contract.
Runtime lifecycle, ticks and events
The following is an interface contract table, not standalone compilable C# or a stable ABI declaration for every release. Compile against the IDL and headers in the exact platform revision being modified.
| Interface and member | Documented responsibility |
|---|---|
IScriptRuntime.Create(in IScriptHost scriptHost) | Initialize the runtime using the host supplied by the platform; retain the host as needed for later calls. |
IScriptRuntime.Destroy() | Release runtime-owned resources when the platform destroys the instance. |
IScriptRuntime.GetParentObject() | Return the pointer previously assigned through SetParentObject. This is a direct pointer return, not result_t. |
IScriptRuntime.SetParentObject(void* object) | Record the native parent, typically an fx::Resource*. It is not ownership of an arbitrary script object. |
IScriptRuntime.GetInstanceId() | Return the random instance ID established at initialization; the documented return is direct int. |
IScriptTickRuntime.Tick() | Receive the host’s per-frame tick. Do not block it with unbounded work. |
IScriptEventRuntime.TriggerEvent(eventName, argsSerialized, serializedSize, sourceId) | Receive the event name, serialized argument-array bytes and length, and a source-identifying string. Validate lengths before decoding. |
Function references
A function reference allows another resource or the host to call a delegate in the runtime. The runtime uses an integer index; the host qualifies it with resource name, instance ID and reference index. A reference from an old runtime instance must not be mistaken for a function in a restarted resource.
IScriptRefRuntime member | Input/output contract |
|---|---|
CallRef(refIdx, argsSerialized, argsSize, out retvalSerialized, out retvalSize) | Invoke a reference with a serialized argument array and return a serialized result array plus its byte length. |
DuplicateRef(refIdx, out newRefIdx) | Allocate a new reference index pointing to the same internal function object. |
RemoveRef(refIdx) | Delete that reference. Pair each creation with one deletion rather than reference-counting only by an existing index. |
Serialization uses MessagePack, with a dedicated extension for delegates/function references. The manual does not state that extension’s numeric tag or enough ABI details to implement a compatible encoder from this page alone. Inspect the exact platform implementation, exercise duplicate/remove pairs and test callbacks after resource shutdown. A JSON encoder is not a replacement.
File handling and host interfaces
IScriptFileHandlingRuntime.HandlesFile(scriptFile) returns whether a runtime handles a file. LoadFile(scriptFile) loads it. Match the declared language/file type before loading; manifest metadata is not a reason to execute an arbitrary file.
IScriptHost.InvokeNative(inout NativeCtx context) invokes a native using its identifier, argument count and arguments in the RAGE native ABI. Results are written into the first argument fields of the context. This contract belongs to a native runtime implementation, not a portable Lua/JavaScript FFI recipe.
OpenSystemFile opens a stream in the system virtual filesystem. OpenHostFile opens a path relative to the host resource, described as resources:/resourceName/. The manual lists CanonicalizeRef and ScriptTrace headings without signatures or behavior; those omissions are not evidence that arbitrary parameter lists work. Resource-level access also remains subject to the sandbox.
Use QueryInterface on the host to obtain IScriptHostWithResourceData or IScriptHostWithManifest. The former exposes GetResourceName; its GetNumResourceMetaData and GetResourceMetaData methods should not be used according to the manual. Use the GET_NUM_RESOURCE_METADATA and GET_RESOURCE_METADATA natives instead.
IScriptHostWithManifest.IsManifestVersionBetween(lowerBound, upperBound) uses the interval lower bound inclusive, upper bound exclusive. A null GUID omits that bound. This is the historical GUID-based manifest interface, not a comparison of arbitrary strings such as cerulean.
Lua pages with no published function contract
At the pinned revision, the following individual function pages contain a title and a -- todo syntax block. Listing the symbol does not document parameter types, initialization, pointer lifetime or return coercion. Read their exact source files and implementation before using them.
| Family | Symbols whose individual pages are placeholders |
|---|---|
| References and immediate threading | Citizen.CanonicalizeRef, Citizen.CreateThreadNow, Citizen.GetFunctionReference, Citizen.InvokeFunctionReference |
| Pointer values | Citizen.PointerValueFloat, Citizen.PointerValueFloatInitialized, Citizen.PointerValueInt, Citizen.PointerValueIntInitialized, Citizen.PointerValueVector |
| Result coercion | Citizen.ResultAsFloat, Citizen.ResultAsInteger, Citizen.ResultAsLong, Citizen.ResultAsObject, Citizen.ResultAsString, Citizen.ResultAsVector, Citizen.ReturnResultAnyway |
| Runtime routines | Citizen.SetCallRefRoutine, Citizen.SetDeleteRefRoutine, Citizen.SetDuplicateRefRoutine, Citizen.SetEventRoutine, Citizen.SetTickRoutine |
The files for promise.all, promise.first, promise.map and promise.new are empty. Do not assume JavaScript Promise combinator semantics, ordering, cancellation or rejection behavior from their names. Citizen.Await has a documented call form but does not fill those missing combinator contracts. Use the Lua function reference for the supported source-backed surface.
JavaScript placeholders and generated catalogs
The JavaScript files RegisterNetEvent.md, addRawEventListener.md and removeEventListener.md are also empty in the source snapshot. Their presence in a tree is not complete API documentation. Use the explicitly documented on, onNet, emit, emitNet and exports forms instead of fabricating an alias or handler-token type.
The client/server function index pages for C#, Lua and JavaScript point partly to generated native catalogs. C# additionally directs readers to assembly IntelliSense and the class browser, with native wrappers under CitizenFX.Core.Native.API. Client functionality is related to ScriptHookV.NET but the reference does not promise exact API identity. The server catalog must be selected for server code.
Generated native signatures and payload catalogs are not all present in the fivem-docs Markdown repository. Follow native context and lookup, client event contracts and server event contracts. Documentation coverage of an index cannot certify an external native database or every compiled SDK version.
Platform build and contribution entry points
The developers/compiling-fivem.md and developers/coding-guidelines.md files are drafts containing TODO. The developer index instead links to building.md in the platform repository . Use the build instructions shipped with the same platform revision as the code you are changing; there is no complete platform-build procedure to mirror from either draft page.
For a normal resource, use the existing C# build/interoperability lab or JavaScript resource guide. For official documentation or native-description changes, read upstream contribution and Git workflow. This website does not redefine Cfx.re’s contributor policy.