script-runtimes

title: Script runtimes weight: 20 description: > Describes support for the fxOM script runtimes.

CitizenFX supports pluggable scripting runtimes. These runtimes are implemented as CitizenFX components (code/components/) implementing fxOM (CitizenFX Object Model) interfaces defined in fxScripting.idl.

The specific interfaces used at the time of this writing are:

In addition, there is a host interface: IScriptHost, which will be passed to IScriptRuntime::Create.

Interface reference > IScriptRuntime > Create

void Create(in IScriptHost scriptHost);

This method is called by the host when the script runtime is created. The script host passed should probably be saved.

Interface reference > IScriptRuntime > Destroy

void Destroy();

This method is called by the host when the script runtime is about to be destroyed.

Interface reference > IScriptRuntime > GetParentObject

void* GetParentObject(); // direct return value, not result_t

This should return the object set by SetParentObject.

Interface reference > IScriptRuntime > SetParentObject

void SetParentObject(void* object); // direct return value, not result_t

This sets the parent object. This is typically a native fx::Resource*, which may be relevant to runtimes implemented in C++.

Interface reference > IScriptRuntime > GetInstanceId

int GetInstanceId(); // direct return value, not result_t

This should return a random instance ID created by the runtime upon initialization.

Interface reference > IScriptTickRuntime > Tick

void Tick();

This is called by the host every frame.

Interface reference > IScriptEventRuntime > TriggerEvent

void TriggerEvent(in char* eventName, in char* argsSerialized, in uint32_t serializedSize, in char* sourceId);

TriggerEvent is called by the host whenever an event has been triggered. eventName contains the name of the executed event, argsSerialized and serializedSize indicate the argument array (serialized using the common serialization convention, see the 'conventions' section), and sourceId contains a string identifying the source of the event.

Interface reference > IScriptRefRuntime

A 'ref' is a function reference, which is used to allow other resources (or the host) to invoke delegates/closures in the script runtime. Each ref is identified by an integer on resource level, in the host it is qualified with the resource name, instance ID and the ref index. Refs should not be reference counted by index, each creation should be paired with a single deletion.

Interface reference > IScriptRefRuntime > CallRef

void CallRef(in int32_t refIdx, in char* argsSerialized, in uint32_t argsSize, out char* retvalSerialized, out uint32_t retvalSize);

CallRef is called by the host when a reference should be invoked. refIdx contains the ref to call, argsSerialized/argsSize contain the argument array, and retvalSerialized and retvalSize should contain the return value array upon completion.

Interface reference > IScriptRefRuntime > DuplicateRef

void DuplicateRef(in int32_t refIdx, out int32_t newRefIdx);

DuplicateRef should return a new reference index referencing the same internal function object as refIdx into newRefIdx.

Interface reference > IScriptRefRuntime > RemoveRef

void RemoveRef(in int32_t refIdx);

RemoveRef should delete the reference identified by refIdx.

Interface reference > IScriptFileHandlingRuntime > HandlesFile

int32_t HandlesFile(in char* scriptFile);

Should return whether or not the specified file should be handled by this runtime.

Interface reference > IScriptFileHandlingRuntime > LoadFile

void LoadFile(in char* scriptFile);

This function should load the file in the runtime.

Interface reference > IScriptHost > InvokeNative

void InvokeNative(inout NativeCtx context);

Invokes a native function. nativeIdentifier should contain the native function identifier, numArguments the amount of arguments, and arguments the specific function arguments following the RAGE native ABI.

Any result, for natives that return any, will be returned in the first argument fields in the context.

Interface reference > IScriptHost > OpenSystemFile

Returns a stream referencing the specified file name in the system VFS.

Interface reference > IScriptHost > OpenHostFile

Returns a stream referencing the specified file name, relative to the host path (resources:/resourceName/).

Interface reference > IScriptHostWithResourceData

This can be obtained using QueryInterface on the IScriptHost.

Interface reference > IScriptHostWithResourceData > GetResourceName

Returns the name of the parent resource.

Interface reference > IScriptHostWithResourceData > GetNumResourceMetaData

This function should not be used, instead the native {{% native_link "GET_NUM_RESOURCE_METADATA" %}} should be used.

Interface reference > IScriptHostWithResourceData > GetResourceMetaData

This function should not be used, instead the native {{% native_link "GET_RESOURCE_METADATA" %}} should be used.

Interface reference > IScriptHostWithManifest

This can be obtained using QueryInterface on the IScriptHost.

Interface reference > IScriptHostWithManifest > IsManifestVersionBetween

bool IsManifestVersionBetween(guid_t* lowerBound, guid_t* upperBound);

Returns whether or not the host resource's manifest version is within a specific range of GUIDs (lowerBound <= guid < upperBound).

If one of the GUIDs is the null GUID, only tests if the version is greater/less then the other GUID.

Conventions > Serialization

Serialization occurs using MessagePack, with a specific extension ID for delegates/function refs.

title: Script runtimes weight: 20 description: > Describes support for the fxOM script runtimes.

CitizenFX supports pluggable scripting runtimes. These runtimes are implemented as CitizenFX components (code/components/) implementing fxOM (CitizenFX Object Model) interfaces defined in fxScripting.idl.

The specific interfaces used at the time of this writing are:

In addition, there is a host interface: IScriptHost, which will be passed to IScriptRuntime::Create.