CLEO/Tutorial - Revision history

Spaceeinstein at 04:08, 8 August 2017

2017-08-08T04:08:24Z

Show changes

Spaceeinstein: update

2017-07-18T23:08:40Z

update

Seemann: /* Details of Hello.fxt */

2016-11-22T08:29:07Z

‎Details of Hello.fxt

Spaceeinstein at 07:45, 22 November 2016

2016-11-22T07:45:26Z

Spaceeinstein: Created page with "== 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: Extr..."

2016-10-16T19:33:21Z

Created page with "== 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: Extr..."

New page

== 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.
<syntaxhighlight lang="scm">
{$CLEO .cs}
wait 1000 ms
00BC: text_highpriority 'HELLO' time 5000 flag 1
0A93: terminate_this_custom_script
</syntaxhighlight>

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.
<syntaxhighlight lang="text">
HELLO Hello World!
</syntaxhighlight>

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: <code>{$CLEO .cs}</code>
Directives are a feature of Sanny Builder that tells the compiler to function in different ways.
<code>{$CLEO .cs}</code> is a directive telling the compiler to compile a CLEO script with a .cs extension.

* Line 2: <code>wait 1000 ms</code>
This [[0001|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: <code>00BC: text_highpriority 'HELLO' time 5000 flag 1</code>
This shows the bulk of the complexity of scripting in the game. [[00BC]] is an [[opcode]], an instruction represented by a [[wikipedia:Hexadecimal|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. <code>text_highpriority</code> is a human-readable description of the command. This text is unimportant when the program compiles your code. <code>time</code> and <code>flag</code> 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 <code>00BC: 'HELLO' 5000 1</code>. 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: <code>0A93: terminate_this_custom_script</code>
[[0A93]] is another opcode that is exclusive to CLEO. This opcode ends the CLEO script. This opcode requires no inputs. Again, <code>terminate_this_custom_script</code> is a human-readable description of the command, so the bare minimum to get this to compile is <code>0A93:</code>.

=== 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.

[[Category:Tutorials]]

@@ Line 1: / Line 1: @@
 == 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.
+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/source/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.
+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/source/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.
+The following outlines the basic steps on how to write a simple CLEO script and run it 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.
-<pre<includeonly></includeonly> class="sb-code"><span class="no">{$CLEO .cs}</span>
+{{Pre|class=sb-code|1=
 <span class="k">wait</span> <span class="m">1000</span> ms
-BC: text_highpriority <span class="s1">'HELLO'</span> time <span class="m">5000</span> flag <span class="m">1</span>
+ACD: show_text_highpriority <span class="s2">"Hello World!"</span> time <span class="m">5000</span>
 A93: terminate_this_custom_script
-</pre>
+}}
-Run the game to see your simple CLEO code display text for five seconds in the game.
+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. Run the game to see your simple CLEO code display the text "Hello World!" for five seconds in the game.
 === Details of Hello.cs ===
@@ Line 31: / Line 29: @@
 This [[0001|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: <code class="sb-code">00BC: text_highpriority <span class="s1">'HELLO'</span> time <span class="m">5000</span> flag <span class="m">1</span></code>
+* Line 3: <code class="sb-code">0ACD: show_text_highpriority <span class="s2">"Hello World!"</span> time <span class="m">5000</span></code>
-This shows the bulk of the complexity of scripting in the game. [[00BC]] is an [[opcode]], an instruction represented by a [[wikipedia:Hexadecimal|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. <code>text_highpriority</code> is a human-readable description of the command. This text is unimportant when the program compiles your code. <code>time</code> and <code>flag</code> 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 <code>00BC: 'HELLO' 5000 1</code>. 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.
+This shows the bulk of the complexity of scripting in the game. [[0ACD]] is an [[opcode]], an instruction represented by a [[wikipedia:Hexadecimal|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. <code>show_text_highpriority</code> is a human-readable description of the command. This text is unimportant when the program compiles your code. <code>time</code> is 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 <code class="sb-code">0ACD: <span class="s2">"Hello World!"</span> <span class="m">5000</span></code>. Move your text cursor to this line and on the bottom left corner of the window you can see the message "0ACD: expecting 2 params." Opcode 0ACD requires two inputs, which in the example are <code class="sb-code"><span class="s2">"Hello World!"</span></code> and <code class="sb-code"><span class="m">5000</span></code>. 0ACD is exclusive to CLEO and does not work without CLEO installed.
 * Line 4: <code>0A93: terminate_this_custom_script</code>
 [[0A93]] is another opcode that is exclusive to CLEO. This opcode ends the CLEO script. This opcode requires no inputs. Again, <code>terminate_this_custom_script</code> is a human-readable description of the command, so the bare minimum to get this to compile is <code>0A93:</code>.
 == 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:
-<pre<includeonly></includeonly> class="sb-code"><span class="no">{$CLEO .cs}</span>
+{{Pre|class=sb-code|1=
 :
 <span class="k">while</span> <span class="k">true</span>
-     <span class="k">wait</span> <span class="m">0</span>
+     <span class="k">wait</span> <span class="m">0</span> ms
-BC: text_highpriority <span class="s1">'HELLO'</span> time <span class="m">5000</span> flag <span class="m">1</span>
+ACD: show_text_highpriority <span class="s2">"Hello World!"</span> time <span class="m">5000</span>
 <span class="k">end</span>
 A93: terminate_this_custom_script
-</pre>
+}}
 Compile your code. Run the game to see your simple CLEO code display text indefinitely.
 * Line 2: <code>0000:</code>
-[[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.
+This opcode is a [[0000|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: <code class="sb-code"><span class="k">while</span> <span class="k">true</span></code>
@@ Line 61: / Line 57: @@
 * Line 4: <code class="sb-code"><span class="k">wait</span> <span class="m">0</span> ms</code>
-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.
+Any loops that do not terminate as soon as reasonably possible require a wait, as in this case. Without a wait, the game locks itself into processing the script and cannot process the rest of the game. 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: <code>0A93: terminate_this_custom_script</code>
 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.
 [[Category:Tutorials]]

@@ Line 38: / Line 38: @@
 === 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.
+The [[FXT#CLEO|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 ==

@@ Line 8: / Line 8: @@
 == 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.
-<syntaxhighlight lang="scm">
+<pre<includeonly></includeonly> class="sb-code"><span class="no">{$CLEO .cs}</span>
-{$CLEO .cs}
+<span class="k">wait</span> <span class="m">1000</span> ms
-wait 1000 ms
+BC: text_highpriority <span class="s1">'HELLO'</span> time <span class="m">5000</span> flag <span class="m">1</span>
 A93: terminate_this_custom_script
-</syntaxhighlight>
+</pre>
 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.
@@ Line 25: / Line 24: @@
 This section explains in detail the simple Hello World! code.
-* Line 1: <code>{$CLEO .cs}</code>
+* Line 1: <code class="sb-code"><span class="no">{$CLEO .cs}</span></code>
 Directives are a feature of Sanny Builder that tells the compiler to function in different ways.
 <code>{$CLEO .cs}</code> is a directive telling the compiler to compile a CLEO script with a .cs extension.
-* Line 2: <code>wait 1000 ms</code>
+* Line 2: <code class="sb-code"><span class="k">wait</span> <span class="m">1000</span> ms</code>
 This [[0001|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: <code>00BC: text_highpriority 'HELLO' time 5000 flag 1</code>
+* Line 3: <code class="sb-code">00BC: text_highpriority <span class="s1">'HELLO'</span> time <span class="m">5000</span> flag <span class="m">1</span></code>
 This shows the bulk of the complexity of scripting in the game. [[00BC]] is an [[opcode]], an instruction represented by a [[wikipedia:Hexadecimal|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. <code>text_highpriority</code> is a human-readable description of the command. This text is unimportant when the program compiles your code. <code>time</code> and <code>flag</code> 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 <code>00BC: 'HELLO' 5000 1</code>. 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 40: / Line 39: @@
 === 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.
 [[Category:Tutorials]]