CLEO 3 / Scripts

CLEO 3 allows adding new scripts needlessly to start a new game. Strictly speaking, the main.scm state does not matter for these scripts, as CLEO scripts are run and functioned separately from it.

What does it give? You can add new script at any stage of the game or delete an existing one. Even so, you do not need to edit the main.scm, so the need to start a new game, the saves incompatibility, some script limits – all these problems disappear right away.

The CLEO script is an ordinary script written using the opcodes in Sanny Builder. Each script should be made as a single file with an extension .cs (Custom Script). The major requirement in writing such scripts is that they must be compiled as the external scripts.

There are several ways of making of a CLEO script being able to work correctly in the game. First: you add a new external script in the main.scm, compile it, and then extract that script from the file script.img. The extracted file will have the extension .scm, so you only need to change it on the .cs and copy to the folder ‘game\CLEO’.

The second way is easier. Create a new file in Sanny Builder, write the directive $E at the beginning of it, and compile. The compiled file will be the same as that one extracted from the script.img. You only need to change its extension to the .cs and copy to the ‘game\CLEO’.

Finally, the easiest one. Create a new file in Sanny Builder, write the directive $CLEO at the beginning of the file, and compile. The compiled file will be copied into the ‘game\CLEO’ directory and will have a file extension specified by the directive (.cs by default).

The CLEO scripts could be used as missions. The compiling process is the same, but the output file must have the extension .cm (Custom Mission). To start this mission, use the opcode 0A94.

The rules you must follow writing custom CLEO scripts:

1. One file – one thread. Each CLEO script must be made as a single thread compiled in a single file. If you need more threads for your script, use the opcodes 004F or 0A92, depending on where that additional thread is located in - in the main.scm or separate .cs file.
2. Never use opcode 004E in the CLEO threads. They work separately from the common threads, so using this opcode will cause an error. Use the opcode 0A93, if you need to stop a CLEO script. Conversely, never use opcode 0A93 in the CLEO missions, but instead use 004E to cancel a mission.

To install the CLEO script you need to copy the file with an extension .cs to the folder ‘game\CLEO’. The file name does not matter, but it uses at the thread initialization to set the internal name_thread of it. For example, the CLEO thread located in the file showsavescreen.cs has the name SHOWSAV.

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

The CLEO thread status may be saved and loaded along with the common threads. It does not saved by default. The saves themselves are located in the folder CLEO\cleo_saves. There is an own save for each save slot. The save file stores only the data of the CLEO threads having the saving flag enabled (0A95 opcode). The save file stores not only the active threads, but also the ones being forced to end (0A93 opcode), to prevent their re-run at loading. If at the game loading one of saved threads 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.

The CLEO thread is an ordinary thread on the whole. It has 32 local variables and 2 timers incrementing constantly. You can pass in up to 34 parameters at creation of that thread or a CLEO mission (by analogy with the opcode 004F).

An important thing concerns with data communication between a CLEO script and the main.scm. To use the SCM code, its variables, threads you have to compile the CLEO script as an external one (the first way). But this method is not recommended, as such a script becomes very sensible to any main.scm change. Implicitly, a CLEO script should be sufficient for itself and use minimum of the SCM data. However, you can freely use global variables names from the CustomVaribles.ini (for example, $PLAYER_CHAR, $PLAYER_ACTOR, $ONMISSION, etc).
Also, for the data communicate between the main.scm and CLEO, or between the CLEO scripts you may use the CLEO variables (see opcodes 0AB3, 0AB4).

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