Introduction

CLEO Redux is an embeddable and extensible runtime capable of running user-made scripts in games and desktop applications. It supports JavaScript and TypeScript languages. Inspired by CLEO Library and partially compatible with its scripts and plugins, CLEO Redux, however, aims to provide better experience for developers and users and support games beyond just GTA 3D series.

Follow the first steps tutorial to learn how to write and run your first script. Also check our YouTube playlist for video guides. Or jump straight away to example scripts.

Supported Releases

Grand Theft Auto series:

GTA III 1.0
GTA Vice City 1.0
GTA San Andreas 1.0 (only with CLEO 4.4)
GTA IV The Complete Edition (1.2.0.43, 1.2.0.59)

Grand Theft Auto: The Trilogy - The Definitive Edition:

Title Update 1.03 and Title Update 1.04 (see details)

Other games and applications:

Bully: Scholarship Edition 1.200
re3 & reVC (see details)
unknown host (see details)

For the complete reference on supported features refer to this page. Also there are known limitations listed here.

License

CLEO Redux is available under the end-user license agreement

Relation to CLEO Library

CLEO is a common name for the custom libraries designed and created for GTA III, Vice City or San Andreas. Each version can be found and downloaded here. CLEO Redux is another CLEO implementation made from scratch with a few distinctive features, such as shared code base between all games and JavaScript support.

At the moment CLEO Redux can not be considered as a complete replacement for CLEO Library due to the lack of support for many widely used CLEO commands. To solve this issue and get the best out of the two libraries, CLEO Redux supports two different usage strategies.

CLEO Redux can run as a standalone software, or as an addon to CLEO Library.

Running CLEO Redux as a standalone software

As a standalone software CLEO Redux runs compiled scripts and JavaScript and provides access to all native script commands. It also provides a limited set of custom commands backward-compatible to CLEO Library. Existing CLEO scripts may not work if they use custom commands (for example from a third-party plugin) not supported by CLEO Redux.

In the standalone mode your game directory contains cleo_redux.asi (or cleo_redux64.asi) file and there is no cleo.asi (or III.CLEO.asi or VC.CLEO.asi) file from CLEO Library. This mode does not work in the classic GTA San Andreas.

Running CLEO Redux as an addon to CLEO library

As an addon CLEO Redux runs alongside CLEO Library delegating it all the care for custom scripts. It means all custom scripts and plugins made for CLEO Library will continue working exactly the same. CLEO Redux only manages JS scripts. All custom commands become available to JavaScript runtime, which means you can use commands currently not implemented natively in CLEO Redux, for example for files.

In the delegate mode your game directory contains both cleo.asi (or III.CLEO.asi or VC.CLEO.asi) from CLEO Library and cleo_redux.asi (or cleo_redux64.asi). This mode works in classic GTA III, GTA Vice City and GTA San Andreas where CLEO Library exists.

Installation

CLEO Redux comes with a hassle-free installer that identifies the selected game and downloads all the dependencies. Just run cleo_redux_setup.exe and follow its steps.

Both CLEO Redux and its installer recognize the target game purely by the executable name in the selected/working directory.

GTA III - gta3.exe

GTA VC - gta-vc.exe

GTA SA - gta_sa.exe, gta-sa.exe, or gta_sa_compact.exe

GTA IV - GTAIV.exe

re3 - re3.exe

reVC - reVC.exe

GTA III: DE - libertycity.exe

GTA VC: DE - vicecity.exe

GTA SA: DE - sanandreas.exe

Bully: SE - bully.exe

Names matching is case-insensitive. If the exe file does not contain a version information CLEO Redux always assumes the version is correct (see supported versions).

Once the installation is complete, CLEO Redux is ready to use. You can now install scripts and extra plugins not included in the installer, and change the default configuration if needed.

CLEO Directory

CLEO directory is the primary location where you install CLEO scripts, CLEO plugins and custom texts. CLEO Redux automatically creates this folder during installation and any time the game starts.

In most cases this directory can be found in the game folder. If, however, CLEO lacks write permissions there and fails to create new files, it uses an alternate path at C:\Users\<your_username>\AppData\Roaming\CLEO Redux. cleo_redux.log and the CLEO directory can be found there.

Dependency on ASI Loader

CLEO Redux is distributed as a dynamic-load library with an .asi extension. Historically ASI files have been used in GTA III and Vice City as addons to the Miles Sound System library (Mss32) which loads them into the game process. More recent titles didn't use MSS, so the modding community developed custom loaders commonly named "ASI Loader" to continue using ASI for any custom code to be injected into the game.

Ultimate ASI Loader by ThirteenAG can be used to load CLEO Redux in any game. It gets downloaded during CLEO Redux setup. You may opt out of installing Ultimate ASI Loader if you have other means of injecting ASI files into the game (i.e. an alternative loader) or the game already supports ASI, e.g. by using MSS lib.

Note that the Ultimate ASI Loader dll file can be renamed, e.g. to dinput8.dll or d3d9.dll depending on the game. By default CLEO Redux installs it as vorbisFile.dll in 32-bit games and version.dll in 64-bit games. There are some exceptions:

it is d3d9.dll in re3 and reVC (x64)
it is dinput8.dll in GTA IV

If the default name does not work with the given game, try renaming the dll file into another compatible name. Visit Ultimate ASI loader repo for more information.

Note on re3 or reVC

CLEO Redux supports "Windows D3D9" version of re3 or reVC (both 32-bit and 64-bit).

During installation you must select the correct version of re3 or reVC: either 32-bit or 64-bit.

When running on re3 and reVC make sure the game directory contains the file re3.pdb (for re3) or reVC.pdb (for reVC). Due to the dynamic nature of memory addresses in those implementations CLEO Redux relies on debug information stored in the PDB file to correctly locate itself.

Uninstallation

To uninstall CLEO Redux perform the following steps:

Delete cleo_redux.asi (or cleo_redux64.asi).
Delete the CLEO folder (optional).
Delete the cleo_redux.log (optional)

Plugins

Plugins are optional programs adding extra scripting commands with the help of CLEO Redux SDK. A plugin file has a .cleo extension and should be copied to the CLEO\CLEO_PLUGINS directory.

List of plugins

Name	Description	Link
IniFiles	Reading from and writing to INI files	src
Dylib	Loading DLL files and importing functions	src
Input	Checking for keyboard and mouse input, emulating key presses	src
ImGuiRedux	Dear ImGui bindings	GitHub repo
MemoryOperations	Low-level memory operations	GitHub repo
Frontend	Checking for updates on GitHub and displaying information in the main menu
Events	Emitting custom events	src

Plugins are included in the CLEO Redux installer. You can opt out of some of them by unchecking the corresponding checkbox in the installer.

Scripts

Adding a new script

Generally a script file (.cs, .js) should just be copied to the CLEO directory. Some scripts may require extra steps for installation. In case of any issues check the script documentation or ask its author.

Complex JS scripts with dependencies may be distributed as folders with index.js and other files in it. Copy such folders to the CLEO directory.

Removing the script

Delete the script file from CLEO directory. Some scripts may require extra steps for undoing the installation. In case of any issues check the script documentation or ask its author.

First steps

Introduction

Since available commands vary from game to game for the purpose of this tutorial we will be using CLEO's built-in commands such as log command that is available everywhere.

Once you have CLEO Redux installed run the game once to make sure CLEO is loading. You can verify it by having cleo_redux.log created in the game root folder. If there are no errors in the log you can start adding new scripts.

Go to the CLEO directory and create a new file named intro.js. This will be a text file and you can edit it in any text editor. We recommend using VS Code as the most advanced choice available today, but other editors, even Notepad, would work too. Open intro.js and add two lines:

// intro script, revision 1
log("Hello world");

Lines starting with // are comments and ignored by the game. The only meaningful line is the second that instructs the JavaScript runtime to print a message in the log file.

Now save the file and run the game. Start a new game or load a save file, play a few seconds and then go to cleo_redux.log (do not exit the game yet). You should now see a new line like:

10:12:19 [INFO] ["intro"] "Hello world"

If you can't find this line, try to read through other messages, they might point you out the issue.

If you see the message, open intro.js again and change "Hello world" to another text. Save the file and go back to game. Play, then switch back to cleo_redux.log. Notice how the log now contains the new message. The script was reloaded on the fly as you saved it and the game now runs an updated version of it. This is called hot reloading.

Concurrency

There is so little fun in a single script, so let's explore another important aspect. CLEO Redux can load and run many scripts concurrently. But they do not run in parallel, or at the same time. Instead there is a queue of scripts to execute them sequentually on each game loop iteration. It reduces a number of possible issues caused due to the use of shared resources from multiple parallel scripts. The game's main loop is also locked while CLEO scripts get processed.

When the script is ready to return control to the main script or another script in the queue, it must call the wait(n) command where n is a number greater than or equal to zero. This command pauses the current script for at least n milliseconds:

wait(250); // pause current script and wake up after 250 milliseconds

Low values (such as 0 or generally anything lower than 16) essentially make the script run on each tick of the game's main loop.

Let's create another JS file in the CLEO directory and call it second.js. Add the following lines:

wait(1000);
log("This is the second script");

Save the file and re-run the game. You should now see two lines in the cleo_redux.log:

10:12:19 [INFO] ["intro"] "Hello world"
10:12:20 [INFO] ["second"] "This is the second script"

Notice that there is a difference in one second between two messages. Try different combinations of log and wait commands in both scripts and see the results. Do they match your expectations?

Variables

Variables keep your script's state and intermediate results. Each variable has a unique name and a type and can be either mutable or immutable. Mutable variables are created with var or let keywords. Immutable variables (or constants) are created with a const keyword.

let x = 5;
let name = "CJ";
const z = -100;

Constants can not be reassigned to another value. The following code will throw an error:

const z = -100;
z = -200;

On the other side var or let variables can get new values. Those values can be of a different type, e.g. you can reuse same variable for different types of data:

let temp;

temp = 1; // number
temp = "str"; // string
temp = {}; // object
temp = []; // array

Use operator typeof to find the type of the variable at any given moment:

let temp;

temp = 1;
log(typeof temp); // prints "number" in cleo_redux.log
temp = "str";
log(typeof temp); // prints "string" in cleo_redux.log
temp = {};
log(typeof temp); // prints "object" in cleo_redux.log
temp = [];
log(typeof temp); // prints "object" in cleo_redux.log*

*typeof returns "object" for an array ([]). This is a very well known quirk in the language. You can read more about it here and find other means of differenting between arrays and plain objects.

Control Flow

Conditions

So far we have been running commands in the script in a sequence from top to bottom. The runtime executed the first line, then proceed to the second line if there was one, then to the third line, etc. But what if we want to execute a command only when some condition is met, lets say a button is pressed? We can use conditions.

In JavaScript an if statement allows to conditionally execute a branch of code if the condition is met. For example, when you write:

if (true) {
  log("this is always printed");
}

You always get the log line printed since the condition in if always evaluates to true. Likewise

if (false) {
  log("this will never be printed");
}

when the condition evaluates to false inside the if block does not run so you won't see the log messages.

You can have any expression in the if statement. JavaScript runtime will try its best to convert it to a boolean (simply saying, convert to true or false). Here are some examples of expressions that get evaluated to true (they are called truthy):

if (1) {...}
if ("string") {...}
if (5 > 4) {...}
if ([]) {...}
if ({}) {...}

Note that 0 and an empty string always get evaluated to false (they are "falsy" values):

if (0) {...}
if ("") {...}

Of course you can have complex experession like functions or methods calls inside the if condition:

if ("string".length > 0) {...}
if ([1,2,3].includes(3)) {...}
if ( ({ status: 'open'}).status === 'open' ) {...}

CLEO API has many conditional commands for different types of checks. For example, the Input plugin provides commands to check the user input (i.g. a check that the button is pressed). Go to intro.js and change its content to:

// intro script, revision 2
wait(2000);
if (native("IS_KEY_PRESSED", 115)) {
  log("F4 button is pressed");
}

Run the game. In cleo_redux.log you should not see the line "F4 button is pressed". Now try running it while holding the F4 button. A new log entry should appear.

You can combine multiple conditions in the same if statement using && (AND) or || (or) operators :

if (native("IS_KEY_PRESSED", 115) || native("IS_KEY_PRESSED", 116)) {
  log("Either F4 or F5 button is pressed");
}

if (native("IS_KEY_PRESSED", 115) && native("IS_KEY_PRESSED", 116)) {
  log("Both F4 and F5 button are pressed");
}

You can execute commands in else block if the condition is not met:

if (native("IS_KEY_PRESSED", 115)) {
  log("F4 button is pressed");
} else {
  log("F4 button is not pressed");
}

Loops

TBD

Functions

TBD

Configuration

CLEO Redux exposes some of the configurable settings in the file CLEO\.config\cleo.ini.

General

AllowCs - when set to 1 CLEO loads and executes *.cs files located in the CLEO directory. Enabled by default.
AllowJs - when set to 1 CLEO loads and executes *.js files located in the CLEO directory. Enabled by default.
AllowFxt - when set to 1 CLEO loads and uses *.fxt files located in the CLEO\CLEO_TEXT directory. Enabled by default.
LogOpcodes - when set to 1 CLEO logs all executed opcodes in custom scripts.
PermissionLevel - sets the permission level for unsafe operations (see below). Default is Lax.
CheckUpdates - (deprecated in favor of Frontend plugin)
DisplayMenuInfo - (deprecated in favor of Frontend plugin)

Host

EnableSelfHost - when set to 1 CLEO runs in the self-host mode. Only applicable on an Unknown host. See the Emdedding guide for more information.
SelfHostFps - the amount of iterations per second the CLEO's main loop will do. Only applicable when EnableSelfHost is 1. Default is 30.

Permissions

This section lists permission tokens and sets whether they are allowed or not in the Strict mode.

Permissions

CLEO Redux acknowledges some custom commands (opcodes) as unsafe and requires the user to decide whether to run them or not. Raw access to the process memory, loading external libraries or making network requests can be harmful and produce undesired side-effects. Hence CLEO introduces permission levels for running the unsafe code.

There are four available levels:

All

Any unsafe operation is allowed. Use this only when you trust the scripts you run.

Lax

This is the default permission level.

No unsafe operation is allowed unless the script explicitly requests it. Currently to request a permission, the name of the script file must include the permissions tokens wrapped in square brackets.

For example, if the script wants to access the memory via 0A8D READ_MEMORY the file name must contain [mem], e.g. cool-spawner[mem].cs. If the file is named differently CLEO rejects 0A8D and the script crashes.

Strict

No unsafe operation is allowed unless the script explicitly requests it (see "Lax") and the CLEO config file permits this type of operation under the Permissions section.

Permissions section in cleo.ini allows to enable or disable groups of unsafe operations by using the permission tokens. For example,

mem=0

disables all memory-related opcodes even if the script has the [mem] token in the file name.

Permissions section in the cleo.ini only takes effect when PermissionLevel is Strict.

None

No unsafe operation is allowed.

Known Permission Tokens

mem - reading from and writing to the process memory, calling foreign functions
dll - loading dynamic libraries and finding exported functions
fs - creating, reading and deleting files from the local file system

Scripts

CLEO Redux provides a runtime capable of executing compiled binary scripts (*.cs) in the native SCM format and plain text scripts (*.js) written in JavaScript.

To find the information on how to install scripts see this page.

Compiled Scripts

Older games in Grand Theft Auto 3D series (GTA III, Vice City, San Andreas) use a custom binary format to store compiled scripts. This format is known as SCM. CLEO Library and CLEO Redux uses the same format for custom scripts. They usually have a .cs extension.

CS scripts run alongside the original SCM scripts and are subject to the same limitations.

Check the FAQ for the information on CS support in the remastered games.

Writing a Compiled Script

For a detailed step-by-step tutorial visit this page. It's applicable to CLEO Redux.

To create a new script use Sanny Builder 3 in GTA III, GTA VC or GTA SA edit modes respectively. Add a directive {$CLEO .cs} at the top of your script, write the code and run "Compile and Copy". Sanny Builder will create a new CS file in the CLEO directory.

At the moment CLEO Redux only provides a few custom commands. Most of the commands implemented in CLEO Library or its plugins are not available yet.

There are a few basic rules to follow when writing compiled scripts:

One file - one script. CLEO only supports one script per file.
Never use opcode 004E to terminate a script. This opcode is only supported in the main.scm. Use 0A93 instead.
Minimize the usage of global variables as they might conflict with other scripts. Some well-known variables such $PLAYER_CHAR, $PLAYER_ACTOR and $ONMISSION can be used.

CLEO Redux does not support saving the script status (a feature of CLEO Library) and there are no plans on adding this feature.

Custom Commands

The following commands are for classic GTA games only. For GTA The Trilogy check this information.

CLEO Redux supports all original opcodes available in the given game. On top of those it adds a few new commands listed below. Note that they strictly match the opcodes of CLEO Library.

0A8C WRITE_MEMORY (UNSAFE - requires mem permission)
0A8D READ_MEMORY (UNSAFE - requires mem permission)
0A8E INT_ADD
0A8F INT_SUB
0A90 INT_MUL
0A91 INT_DIV
0A93 TERMINATE_THIS_CUSTOM_SCRIPT
0AA5 CALL_FUNCTION (UNSAFE - requires mem permission)
0AA6 CALL_FUNCTION_RETURN (UNSAFE - requires mem permission)
0AA7 CALL_METHOD (UNSAFE - requires mem permission)
0AA8 CALL_METHOD_RETURN (UNSAFE - requires mem permission)
0AB0 IS_KEY_PRESSED

This list might not be complete as there are custom plugins with extra commands. Refer to Sanny Builder Library for the complete list of available commands for each game.

JavaScript

CLEO Redux targets JavaScript as the primary language for custom scripts. JavaScript is a popular programming language with rich ecosystem and plenty of available information. It's free from SCM language limits and pitfalls such as lack of support for functions, arrays, or the low number of variables.

To make a JS script use VS Code (recommended) or any editor of your choice. Create a new file with .js extension and put it in the CLEO folder. See Script lifecycle for extra information.

The runtime supports ECMAScript 2020 standard. It means you are able to use the most recent JavaScript features out of the box, such as imports, classes, arrow functions, etc.

CLEO Redux is not Node.js. Don't expect sockets, file system operations or other Node.js features to be available here.

Definitions

Due to the dynamic nature of JavaScript CLEO Redux needs to know an interface of each native command, i.e. a number of input arguments and returned values and their types. Sanny Builder Library serves as the source of command definitions for CLEO Redux.

At start CLEO validates that a definition file is present and correct and if not tries to download it from GitHub (see the table below) into your local CLEO/.config directory. If that did not happen, or you don't want to let CLEO make network calls, manually download the required file and place it in the CLEO/.config directory.

Game	File	Minimum Required Version
GTA III, re3	gta3.json	`0.267`
GTA VC, reVC	vc.json	`0.273`
GTA San Andreas (Classic) 1.0	sa.json	`0.319`
GTA III: The Definitive Edition	gta3_unreal.json	`0.228`
Vice City: The Definitive Edition	vc_unreal.json	`0.234`
San Andreas: The Definitive Edition	sa_unreal.json	`0.263`
GTA IV	gta_iv.json	`0.78`
Unknown (32-bit)	unknown_x86.json	`0.225`
Unknown (64-bit)	unknown_x64.json	`0.228`
Bully: Scholarship Edition	bully.json	`0.41`

CLEO Redux uses compound definitions (a combination of the primary JSON file for the current game and a JSON file for the Unknown host). It lets SDK commands to work in JS scripts regardless of them being defined or not in the primary JSON file. You should notice that during updates CLEO downloads both <game>.json and unknown.json as well as the accompanying enums.js files. It should not affect any existing scripts.

Script Lifecycle

A file with the JavaScript code should have a .js extension and contain valid instructions.

Valid instructions include a code conforming to the ECMAScript 2020 standard and custom bindings available in the CLEO Redux runtime. If the runtime encounters an unknown or illegal instruction the execution halts and a new error is logged in cleo_redux.log. The script may have no instructions (the empty script).

CLEO script runs as soon as the new game starts or a save file is loaded. If you change the file while the game is running, CLEO reloads the script and it restarts.

The script terminates automatically when the last instruction has been executed. The runtime also terminates stuck scripts to prevent the game from freezing. The stuck script is the one that took more than 2 seconds to run since the last wait command. If that happened, check out your loops, some of the are missing the wait command.

while (true) {
  // meaningless infinite loop normally freezing the game
  // will be terminated after two seconds
}

The runtime will terminate this script. To avoid that, add the wait command

while (true) {
  wait(250);
  // still meaningless, but does not freeze the game
}

Organizing Scripts

A single self-contained script file can be placed directly in the CLEO directory.

Complex JS scripts having a lot of dependencies (imported files, FXT dictionaries) can be organized in folders. CLEO Redux scans the subdirectories of the CLEO directory and checks if there is a file named index.js. If index.js is found, CLEO Redux runs it. It also loads all FXT files from the same directory.

Let's have a look at the example structure:

CLEO/
├─ CLEO_TEXT/
│  ├─ main.fxt
├─ folderA/
│  ├─ text.fxt
│  ├─ index.js
├─ folderB/
│  ├─ test.fxt
│  ├─ test.js
├─ script1.js
├─ script2.cs

By default CLEO Redux loads all CS and JS files from the root of the CLEO directory and FXT files from the CLEO_TEXT folder. So it loads script1.js, script2.cs, and main.fxt.

After scanning subdirectories, CLEO loads index.js and text.fxt located in the folderA and skips folderB as there is no index.js file.

CLEO_TEXT, CLEO_PLUGINS, and .config are not considered as script directories.

Imports

You can import other scripts and some custom file formats in your code to make the code modular and share the common logic. This page describes static import statements (unconditional importing). Their format matches the ES6 import syntax. CLEO Redux also supports dynamic imports (importing on-demand).

Importing scripts

Extensions: .js, .mjs, .ts

./ in a path resolves to the current file's directory. If a script is located at C:\Game\CLEO\mod1\extra\addon.js and it contains import { foo } from './bar.js', the runtime will try to load C:\Game\CLEO\mod1\extra\bar.js.

../ resolves to the parent directory. If a script is located at C:\Game\CLEO\mod1\extra\addon.js and it contains import { foo } from '../bar.js', the runtime will try to load C:\Game\CLEO\mod1\bar.js. You can combine ../ to traverse multiple levels up.

To avoid running imported .js files as standalone scripts, either put them into a separate folder outside of the main CLEO directory (e.g. CLEO/includes/) or use the extension .mjs.

// imports default export from other.js or other.mjs located in the same directory
import func from "./other";

// imports named export PedType from types.js or types.mjs located in the CLEO/includes directory
import { PedType } from "./includes/types";

Importing JSON files

Extensions: .json

// imports vehicles.json as a JavaScript value (an array, object).
import data from "./vehicles.json";

Importing other formats

CLEO Redux supports custom file loaders. The purpose of a loader is to load a provided file, parse it and serialize into a JSON string suitable for the use in JavaScript. Those loaders are implemented as CLEO plugins and use CLEO SDK to associate itself with particular file extensions.

Default CLEO installation includes loaders for .txt and .ide files.

TXT

Extensions: .txt, .text
Plugin name: TextLoader.cleo

The TXT loader transforms a text file into an array of strings where each element is a line in the text file. For an empty file an empty array is constructed. If the file can not be open for reading the import statement raises an exception.

import lines from "./some-file.txt";

for (const line of lines) {
  log(line); // prints a line
}

This script prints each line from the some-file.txt file into the log. If you need the content of the file as a single string use .join('') method to concatenate all array elements:

import lines from "./some-file.txt";

log(lines.join("")); // prints the entire file

IDE

Extensions: .ide
Plugin name: IdeLoader.cleo

The IDE loader transforms an item definition file (*.ide) that is widely used in GTA series games. The file is imported as an object where each key corresponds to a section in the file and the value is an array of array of strings:

interface Ide {
  [key: string]: Array<Array<string>>;
}

A first-level array represents a list of lines within this section in the file, and a second-level array represents a list of columns within that line. E.g. the following IDE file

peds
0, null, generic, PLAYER1, STAT_PLAYER, player, 7f
1, cop, cop, COP, STAT_COP, man, 7f
end

objs
170, grenade, generic, 1, 100, 0
end

would be transformed into:

{
  "peds": [
    ["0", "null", "generic", "PLAYER1", "STAT_PLAYER", "player", "7f"],
    ["1", "cop", "cop", "COP", "STAT_COP", "man", "7f"]
  ],
  "objs": ["170", "grenade", "generic", "1", "100", "0"]
}

Note that each data element becomes a string, even if it was a number in the original file. The loader does not make any assumption about specific sections, nor validate them. It follows a few simple rules where each section should start with an identifier ("peds", "objs") and end with the "end" string. It considers each line to be a comma- or space-separated set of columns that could be anything.

// read data/default.ide file in the game directory
import data from "data/default.ide";

// read "peds" section from the file
const peds = data.peds;

// find a line in the peds section where the second element (column) is "cop"
const cop = peds.find((line) => line[1] === "cop");

// if the line is found print the model id from the first column
if (cop) {
  log("Cop model ID is " + parseInt(cop[0]));
} else {
  log("Model with the name 'cop' not found");
}

This script shows how you can use .find and other common array methods to find a line in the imported IDE file and use it. It prints 1 when given a file with the content shown above.

Asynchronous Programming

CLEO Redux supports asynchronous code via Promises and async/await syntax. This enables lots of advanced code patterns.

Note that asynchoronous programming is a fairly complex topic and if you want to learn more about visit the following resources:

See an example of an async script for GTA III here.

Async API

CLEO Redux 1.0.4 has one native async command: asyncWait. This command pauses the script for a specified amount of time. It returns a Promise that resolves after the specified amount of time. asyncWait can only be used inside an async function.

async function delay(ms) {
  log("Waiting for " + ms + "ms");
  await asyncWait(ms);
  log("Done waiting");
}

delay(1000);

Difference between asyncWait and wait is that the former is not a blocking command. If you don't put the await keyword in front of it, the script execution continues.

async function delay(ms) {
  log("Waiting for " + ms + "ms");
  asyncWait(ms); // no await here, the script continues
  log("Executed immediately");
}

delay(1000);

Async Functions

CLEO Redux does not support a top-level await. This means that you cannot use the await keyword in the main body of the script.

// script begins
await asyncWait(1000); // won't work
showTextBox("Hello");

To bypass this limitation wrap your code in an anonymous async function.

(async function () {
  // script begins
  await asyncWait(1000); // works, because it's inside an async function
  showTextBox("Hello");
})();

Note that by design any exception thrown inside an async function is not caught automatically. This means that if you want to catch an exception you need to wrap your code in a try/catch block or add .catch handler to the promise.

(async function () {
  // script code goes here
  non_existing_function();
})().catch((e) => {
  log(e);
});

The log will contain the following message:

"ReferenceError: 'non_existing_function' is not defined"

Concurrent Async Functions

One of the advantages of async functions is that they could run concurrently. This means that you can run multiple async functions at the same time. Some languages call these coroutines.

import { KeyCode } from "./.config/enums";
let gVar = 0;

(async () => {
  await asyncWait(0);

  // running task1, task2, and task3 concurrently
  task1();
  task2();
  task3();
})();

// shakes the camera
async function task1() {
  while (true) {
    await asyncWait(0);
    Camera.Shake(30);
  }
}

// awards the player with $1000 every second and increments the global variable gVar
async function task2() {
  let p = new Player(0);
  while (true) {
    await asyncWait(1000);

    p.addScore(1);
    gVar++;
  }
}

// waits for the button J to be pressed and displays the value of gVar
async function task3() {
  while (true) {
    await asyncWait(0);
    if (Pad.IsKeyDown(KeyCode.J)) {
      showTextBox("gVar is " + gVar);
    }
  }
}

This is very similar to writing traditional while(true){} loops with a wait command in it, with the difference that the functions must have async keyword and use asyncWait instead of wait Each of the three tasks are executed independently from each other. Note that runtime guarantees that all async functions are executed in the same thread. They share global variables and can change them. Look at how gVar is being incremented in task2 and read in task3.

Dynamic Imports

CLEO Redux supports dynamic imports. It allows to load script files on-demand when they are needed. This is useful for large scripts that are not needed all the time.

(async () => {
  if (somethingIsTrue) {
    // import module for side effects
    await import("./my-module.mjs");
  }
})();

Imported modules can export functions and variables. They can be used in the same way as in regular scripts.

my-module.mjs:

export const myVar = 42;

main.js:

(async () => {
  const { myVar } = await import("./my-module.mjs");
  log(myVar); // prints 42
})();

When importing JSON files, its content is available via default property.

(async function () {
  const { default: data } = await import("./my.json");

  log(data); // prints the content of my.json
})();

setTimeout and setInterval

It is easy to implement setTimeout and setInterval using asyncWait and async functions. You can find an implementation example here.

Since 1.0.6 these functions are part of the standard library and are available in all scripts.

Events

CLEO Redux 1.0.6 adds initial support for event-driven scripting. This feature allows you to write scripts that react to events that happen in the game or another scripts.

Listening to events

A globally available addEventListener function creates a new event listener. It takes two arguments: an event name and a function that will be called when the event is triggered (a callback).

The event name argument corresponds to built-in or custom event names.

The callback receives a single argument. This argument is a JavaScript object with two fields: name (the event name) and data (custom data associated with this event).

Event listeners only work in async context. Scripts willing to react to game events must not use a blocking wait function. Use asyncWait instead.

addEventListener("OnVehicleCreate", (event) => {
  log("A vehicle is created!");
  log(event.name); // logs "OnVehicleCreate"
});

addEventListener returns a function that can be used to stop listening to the event. This is useful when you want to stop listening to the event after a certain condition is met.

const cancel = addEventListener("OnVehicleCreate", (event) => {
  log("A vehicle is created!");
});

// ...

cancel(); // the event callback won't be called anymore

List of events

The following documentation describes the Events.cleo plugin shipped with CLEO Redux 1.0.6+. Other plugins may add their own events. Events are game- and version- specific. Some of them might not be available on certain games or versions.

OnVehicleCreate

Triggered after the game creates a new vehicle of any type in the world. An event's data object contains the address of the vehicle structure.