CLEO Redux supports all commands native to the current game. In the classic GTA 3D series they are also known as opcodes. In GTA IV they are known as native functions. You can find them in Sanny Builder Library.
Each available command has a predefined name that the game associates with a particular set of instructions running as you execute that command with arguments. To call a command by name use a built-in function native. For example, to change the player's health run native("SET_PLAYER_HEALTH", 0, 100), where 0 is the player's id and 100 is the desired health.
For convenience, CLEO Redux also defines a wide set of abstractions on top of the native functions called classes. Each class represents a group of commands around some domain, e.g. commands related to the player, vehicles, or text display can be found in classes Player, Car, or Text respectively. You can browse available classes and their methods in Sanny Builder Library.
For example, to change the player's health using classes run p.setHealth(100), where p is an instance of the Player class created with new Player() or Player.Create functions.
In addition to native commands CLEO Redux adds extra variables and functions.
the host name (previously available as GAME variable). Possible values are gta3, vc, re3, reVC, sa, gta3_unreal, vc_unreal, sa_unreal, gta_iv, bully, unknown.
CLEO plugins can use SDK to customize the name for their needs.
if (HOST === "gta3") {
showTextBox("This is GTA III");
}
if (HOST === "sa") {
showTextBox("This is San Andreas");
}
if (HOST === "unknown") {
showTextBox("This host is not natively supported");
}the global flag controlling whether the player is on a mission now. Not available on an unknown host.
if (!ONMISSION) {
showTextBox("Not on a mission. Setting ONMISSION to true");
ONMISSION = true;
}Setting ONMISSION to true has a side effect of turning the current script into a mission script, e.g. you can use mission-only commands, such as STORE_CAR_CHAR_IS_IN or MISSION_HAS_FINISHED. Setting ONMISSION to false turns the current script into a normal script.
two auto-incrementing timers useful for measuring time intervals.
while (true) {
TIMERA = 0;
// wait 1000 ms
while (TIMERA < 1000) {
wait(0);
}
showTextBox("1 second passed");
}an absolute path to the directory with the current file
an absolute path to the current file
addEventListener(name, callback) calls the {callback} function every time an event with the specified {name} is triggered. The {callback} function accepts a single argument that contains event-specific data. addEventListener returns a function that can be used to remove the listener.
const cancel = addEventListener("OnVehicleCreate", (event) => {
log("A vehicle is created!");
});
// ...
cancel(); // the event callback won't be called anymoreawait asyncWait(timeInMs) pauses the script execution for at least {timeInMs} milliseconds. asyncWait can be used in async functions.
async function loop() {
while (true) {
await asyncWait(1000);
log("1 second passed");
}
}See setTimeout.
See setInterval.
dispatchEvent(name, data?) triggers a custom event with the specified {name} and {data}. The {data} argument is optional. The event can be caught by addEventListener function from any active script.
addEventListener("greeting", (event) => {
log(event.data); // prints "hello"
});
dispatchEvent("greeting", "hello");exit(reason?) terminates the script immediately. exit function accepts an optional string argument that will be added to the cleo_redux.log.
exit("Script ended");log(...values) prints comma-separated {values} to the cleo_redux.log
var x = 1;
log("value of x is ", x);native(command_name, ...input_args) is a low-level function to execute a command using its name {command_name}. The command name matches name property in a JSON file provided by Sanny Builder Library.
native("SET_TIME_OF_DAY", 12, 30); // sets the time of day to 12:30For the commands that return a single value, the result is this value.
const progress = native("GET_PROGRESS_PERCENTAGE");
showTextBox(`Progress is ${progress}`);For the commands that return multiple values, the result is an object where each key corresponds to a returned value. The key names match the output names given in the command definition
var pos = native("GET_CHAR_COORDINATES", char); // returns char's coordinates vector {x, y, z}
showTextBox(`Character pos: x ${pos.x} y ${pos.y} z ${pos.z}`);For the conditional commands the result is the boolean value true or false
if (native("HAS_MODEL_LOADED", 101)) {
// checks the condition
showTextBox("Model with id 101 has been loaded");
}setInterval(callback, timeInMs?) calls the {callback} function every {timeInMs} milliseconds (or 0 if the argument is not present).
setInterval returns an unique id that can be used to cancel the interval early using clearInterval.
let intervalId = setInterval(() => {
showTextBox("1 second passed");
}, 1000);
clearInterval(intervalId); // the callback won't be called anymoresetTimeout(callback, timeInMs?) calls the {callback} function after {timeInMs} milliseconds (or 0 if the argument is not present).
setTimeout returns an unique id that can be used to cancel the timeout early using clearTimeout.
let timeoutId = setTimeout(() => {
exit("Terminate script);
}, 1000);
clearTimeout(timeoutId); // the callback won't be calledshowTextBox(text) displays {text} in the black rectangular box. Not available on an unknown host.
showTextBox("Hello, world!");wait(timeInMs) pauses the script execution for at least {timeInMs} milliseconds
while (true) {
wait(1000);
log("1 second passed");
}Memoryobject allows to manipulate the process memory. See the Memory guide for more information.
Mathobject is a standard object available in the JS runtime that provides common mathematical operations. CLEO Redux extends it with some extra commands. See the Math object for more information.
FxtStoreallows to update the content of in-game texts. See the Custom Text guide for details.
-
CLEOobject provides access to the runtime information and utilities:CLEO.debug.trace(flag)toggles on and off command tracing in the current script. When {flag} is true all executed commands get added tocleo_redux.log:
CLEO.debug.trace(true); wait(50); const p = new Player(0); CLEO.debug.trace(false);
CLEO.version- a complex property providing information about current CLEO version
log(CLEO.version); // "0.9.4-dev.20220427" log(CLEO.version.major); // "0" log(CLEO.version.minor); // "9" log(CLEO.version.patch); // "4" log(CLEO.version.pre); // "dev" log(CLEO.version.build); // "20220427"
CLEO.apiVersion- a complex property providing information about current API (usingmeta.versionfield in the primary definition file). Scripts can use it to check if the user has a particular API version installed.
log(CLEO.apiVersion); // "0.219" log(CLEO.apiVersion.major); // "0" log(CLEO.apiVersion.minor); // "219" log(CLEO.apiVersion.patch); // undefined log(CLEO.apiVersion.pre); // undefined log(CLEO.apiVersion.build); // undefined
CLEO.hostVersion- a complex property providing information about the host version. Currently only available if the current exe file has version info (e.g. GTA IV or GTA Trilogy)
log(CLEO.hostVersion); // "1.2.0.43" log(CLEO.hostVersion.major); // "1" log(CLEO.hostVersion.minor); // "2" log(CLEO.hostVersion.patch); // "0" log(CLEO.hostVersion.pre); // undefined log(CLEO.hostVersion.build); // "43"
-
CLEO.runScript(fileName, args?)- method that spawns a new instance of the script.fileNameis the path to the script to launch.argsis an optional parameter to pass arguments to the script.Don't overuse this feature as spawning a new script is a costly operation. Avoid spawning too many scripts in a loop.
runScripthas the following limitations:- script files must have one of the following extensions:
.mjs,.js(JS scripts),.ts(TS scripts),.sor.cs(CS scripts). - spawning CS scripts is not supported in the delegate mode (i.e. won't work in GTA San Andreas with CLEO 4 installed.)
When running a new script you can also provide arguments to it.
argsis a JavaScript object which keys correspond to variable names in the script. Key names for a CS script are numeric and correspond to local variables (0@, 1@, 2@, etc). JS scripts can receive both numbers and strings as arguments, whereas CS scripts can only receive numbers.You can spawn multiple instances of the same script with different arguments.
Imagine that you have two files
main.jsandchild.mjsin the CLEO directory:main.js:
CLEO.runScript("./child.mjs", { a: 1, b: "str", c: 10.5 });
child.mjs:
showTextBox("child.mjs was launched with: " + a + " " + b + " " + c);
Now if you run the game you should see the following message:
child.mjs was launched with: 1 str 10.5.main.js:
CLEO.runScript("./child.cs", { 1: 500 });
child.cs:
0109: player $PLAYER_CHAR money += 1@ // gives the player $500 0A93: terminate_this_custom_scriptTo pass floating-point numbers to a CS script use
Memory.FromFloatfunction:main.js:
CLEO.runScript("./child.cs", { 0: Memory.FromFloat(-921.25), 1: Memory.FromFloat(662.125), 2: Memory.FromFloat(-100.0), });
child.cs:
00A1: set_char_coordinates $PLAYER_ACTOR x 0@ y 1@ z 2@ // teleports the player at -921.25 662.125 -100.0 0A93: terminate_this_custom_script - script files must have one of the following extensions: