CLEO/Tutorial

Installation

Install Sanny Builder into your computer. Go to http://cleo.li/ and choose the relevant link to download the latest version of CLEO.

• For GTA III:

Extract all the contents in the ZIP file, including III.CLEO.asi and the CLEO folder with everything inside, into GTA III's folder. Go to your Sanny Builder folder and open data\gta3\SCM.INI using any text editor. Go to https://raw.githubusercontent.com/cleolibrary/III.VC.CLEO/master/CLEO_SDK/scm.txt and copy the lines to the end of SCM.INI. Save SCM.INI.

• For Vice City:

Extract all the contents in the ZIP file, including VC.CLEO.asi and the CLEO folder with everything inside, into Vice City's folder. Go to your Sanny Builder folder and open data\vc\VCSCM.INI using any text editor. Go to https://raw.githubusercontent.com/cleolibrary/III.VC.CLEO/master/CLEO_SDK/scm.txt and copy the lines to the end of VCSCM.INI. Save VCSCM.INI.

Hello World!

The following outlines the basic steps on how to write a simple CLEO code and run the script in the game. Run Sanny Builder and choose the relevant game on the bottom right side of the window. Select File > New... to create a new empty document. Copy and paste the following code.

{$CLEO .cs}
wait 1000 ms
00BC: text_highpriority 'HELLO' time 5000 flag 1
0A93: terminate_this_custom_script

Save your code by selecting File > Save and save it as Hello.txt into the CLEO folder in the game's directory. Then select Run > Compile to compile your code. Hello.cs should appear in the same folder. Now go to CLEO_TEXT folder and create a new file named Hello.fxt which can be opened using any text editor. Inside that file, copy and paste the following line.

HELLO Hello World!

Run the game to see your simple CLEO code display text for five seconds in the game.

Details of Hello.cs

This section explains in detail the simple Hello World! code.

• Line 1: {$CLEO .cs}

Directives are a feature of Sanny Builder that tells the compiler to function in different ways. {$CLEO .cs} is a directive telling the compiler to compile a CLEO script with a .cs extension.

• Line 2: wait 1000 ms

This wait command stops the execution of the script for the specified time. It takes a while for the game to fade in so you might miss the upcoming Hello World! text. The wait causes the script stop for a second before proceeding onto the next command to display the text.

• Line 3: 00BC: text_highpriority 'HELLO' time 5000 flag 1

This shows the bulk of the complexity of scripting in the game. 00BC is an opcode, an instruction represented by a hexadecimal number. All commands in any scripts are represented by an opcode internally. The wait in the previous line uses a keyword "wait" that uses the opcode 0001 internally. Keywords are another feature of Sanny Builder that helps simplify certain aspects of coding. text_highpriority is a human-readable description of the command. This text is unimportant when the program compiles your code. time and flag are also unimportant when compiling and are there only for human readability. In essence, the bare minimum for getting this line to compile in the program is 00BC: 'HELLO' 5000 1. Move your text cursor to this line and on the bottom left corner of the window you can see the message "00BC: expecting 3 params." Opcode 00BC requires three inputs, which in the example are 'HELLO', 5000, and 1. 'HELLO' is the key to display your text. This is explained in the next section detailing Hello.fxt.

• Line 4: 0A93: terminate_this_custom_script

0A93 is another opcode that is exclusive to CLEO. This opcode ends the CLEO script. This opcode requires no inputs. Again, terminate_this_custom_script is a human-readable description of the command, so the bare minimum to get this to compile is 0A93:.

Details of Hello.fxt

The FXT file is a plain-text file for CLEO and the game to read custom text from. Each line in the file consists of the key and data. The key is a unique text that helps the game find and retrieve the actual data. Its length must be seven characters or less and must not contain a space, which is used to separate the key from the data. The data contains the full text that the game can display on the screen.

Flow of control

Loops

The above Hello World script only runs once. If you want to repeat the same commands, you can place your code in a continuous loop. Replace your Hello World code with the following code:

{$CLEO .cs}
0000:
while true
    wait 0
    00BC: text_highpriority 'HELLO' time 5000 flag 1
end
0A93: terminate_this_custom_script

Compile your code. Run the game to see your simple CLEO code display text indefinitely.

• Line 2: 0000:

This opcode is a no operation, meaning executing this command produce no effect. Because the first line that is not a no operation is the start of a loop, this line is needed to avoid a jump-at-zero-offset bug.

• Line 3: while true

This is the start of the while loop. The condition of the while is always true, so it will loop indefinitely. The while loop is closed off in line 6. The while construct is a feature of Sanny Builder. When compiled, internally opcode 0002 allows the code to jump back to the beginning of the loop.

• Line 4: wait 0 ms

Nearly all loops require a wait. Without one, the game can crash. Note that this line and line 5 are indented. Indentations are unimportant when the program compiles your code and are there only for human readability. It is good practice to indent your code within loops so that you can see where the loop affects your code.

• Line 7: 0A93: terminate_this_custom_script

The game will never reach this line because the script loops indefinitely. You can omit this line if you choose but this is placed here in case you modified the example code to exit out of the loop.