What are CLEO scripts?

A CLEO script is a custom script written for the Grand Theft Auto games series by Rockstar Games. While these games already provide a very rich gameplay experience, they can be easily expanded by adding new features or tweaking existing ones. These scripts can be compiled with a compiler such as Sanny Builder into a single binary file with the extension .cs (Custom Script). Anyone can learn to write their own scripts and share them freely with other CLEO users!

CLEO provides a huge range of features for scripts to add anything from brand new game features and missions to game engine enhancements or even entire in-game applications (such as DYOM) to allow users to modify their own game, all within scripts which are tiny in size and easy to download and install. Features such as brand new opcode libraries, easy game integration, a sound system, mission loader, game saving abilities and plugin support allow for an endless set of possibilities to add something new to your Grand Theft Auto game.

Where to download CLEO scripts?

There are the links to the sites hosting a big enough collection of CLEO scripts. Note that the CLEO library developers do not maintain those sites and are in no way responsible for its content.

How to install CLEO scripts?

The CLEO Library allows adding new scripts without needing to start a new game. You can add a new script at any stage of the game or delete an existing one.

To install a CLEO script you need to copy the file with the extension .cs to the CLEO folder. The file name does not matter, but CLEO uses its first 7 letters to name the script. For example, a CLEO script located in the file showsavescreen.cs would have the name SHOWSAV.

To remove the script, just delete the appropriate file from the CLEO directory.

How do I write my own CLEO script?

Writing a CLEO script is very easy (if you know how to make scripts for GTA at all). With Sanny Builder you can simply use the directive {$CLEO} at the beginning of your script and compile. The resulting file will be copied to the CLEO directory and will be given the extension specified by the directive (.cs by default).

The process for a CLEO mission is similar, except the compiled script must have the .cm extension which can be specified using {$CLEO .cm}. The mission can then be started by a CLEO script using opcode 0A94.

There are a few basic rules to follow when writing custom CLEO scripts as they differ from SCM scripts:

1) One file - one script. CLEO only supports one script per file. If you need to launch additional scripts, use opcode 0A92 with the path to another .cs file.

2) Never use opcode 004E in the CLEO scripts. They work separately from those in the SCM, so use of this opcode is unsupported. Use opcode 0A93, if you need to stop a CLEO script. Conversely, never use opcode 0A93 in the CLEO missions, but instead use 004E to end a custom mission.

Each CLEO script may be saved and loaded along with those found in the SCM. They are not saved by default, but saving can be enabled per-script using opcode 0A95. The saves themselves are located in the folder 'CLEO\cleo_saves'. There is an individual file for each save slot. The save file stores not only the active scripts, but also those which have ended (using opcode 0A93), to prevent them from being re-run.

If at the game loading one of saved script is not found, there is no error. If you add a new script that is not present in the current save file, it will be loaded along with the others and begin to work from the very beginning.

CLEO scripts work in a very similar way to regular SCM scripts on the whole. They have 32 local variables and 2 timers incrementing constantly. You can pass up to 34 parameters to a launched script on creation of any script or mission (similarly to opcode 004F).

Another important thing of concern is data communication between a CLEO script and the main.scm. While CLEO scripts are able interact with SCM variables and labels, it is recommended to keep reliance on SCM data to a minimum to reduce damage if any change to the SCM is made. The best practise is to reduce all dependencies in a CLEO script by allowing it to only use variables and labels defined by it and eleminate any possible conflicts with the SCM. There are however some common variables which may need to be used and can be done so in most cases such as $PLAYER_CHAR, $PLAYER_ACTOR and $ONMISSION.

Also, for data communication between the main.scm and CLEO, or between the CLEO scripts you may use CLEO variables (see opcodes 0AB3, 0AB4).

The CLEO complete set includes examples of simple scripts with sources.