0.7.0 release

CHANGELOG.md

@@ -1,9 +1,21 @@
+### 0.7.0 - Oct 30, 2021
+
+- CLEO Redux can now work as an extension to CLEO Library (see [Relation to CLEO Library](README.md#relation-to-cleo-library))
+- CLEO Redux now runs JavaScript in GTA San Andreas with CLEO 4.4 installed 
+- new config parameter `AllowCs` to control `*.cs` scripts 
+- fix: ini config was ignored if there were missing parameters in the `cleo.ini`
+
+#### BREAKING CHANGE
+
+CLEO Redux' primary distribution file has been renamed to `cleo_redux.asi`. To avoid conflicts with previously installed versions of CLEO Redux manually delete old `cleo.asi` file from the game directory.
+
 ### 0.6.2 - Oct 11, 2021
 - add [CALL_FUNCTION](https://library.sannybuilder.com/#/gta3/CLEO/0AA5), [CALL_FUNCTION_RETURN](https://library.sannybuilder.com/#/gta3/CLEO/0AA7), [CALL_METHOD](https://library.sannybuilder.com/#/gta3/CLEO/0AA6), [CALL_METHOD_RETURN](https://library.sannybuilder.com/#/gta3/CLEO/0AA8). See [Using Memory](using-memory.md#calling-foreign-functions) for more information.
 - update typings to include links to relevant documentation
 
 ### 0.6.1 - Oct 08, 2021
 - fix crash in `Memory` class methods
+
 ### 0.6.0 - Oct 08, 2021
 
 - add [INT_ADD](https://library.sannybuilder.com/#/gta3/CLEO/0A8E), [INT_SUB](https://library.sannybuilder.com/#/gta3/CLEO/0A8F), [INT_MUL](https://library.sannybuilder.com/#/gta3/CLEO/0A90), [INT_DIV](https://library.sannybuilder.com/#/gta3/CLEO/0A91) commands

README.md

@@ -8,21 +8,50 @@ CLEO Redux is a scripting runtime for classic versions of GTA III and GTA Vice C
 
 If you're new to CLEO visit the [official website](https://cleo.li/) to find more information about it.
 
+### Supported Languages
+
+CLEO Redux supports compiled binary scripts (`*.cs`) in the native SCM format and plain text scripts (`*.js`) written in 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.
+
+JavaScript is enabled by default. To disable it open up `CLEO\.config\cleo.ini` and change `AllowJs` to `0`.
+
 ### Supported Releases
 
 - GTA III v1.0
 - GTA Vice City v1.0
+- GTA San Andreas v1.0 (only with CLEO 4.4)
 - re3
 - reVC
 
+### 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](https://cleo.li/download.html). CLEO Redux is *another* CLEO implementation made from scratch with a few distinctive features, such as single code base for all games, or support for JavaScript code. 
+
+At the moment CLEO Redux can not be considered as a 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.
+
+#### Running CLEO Redux as a standalone software
+
+CLEO Redux can run as a standalone software, or as an addon to CLEO Library. In the first case your game directory would only contain `cleo_redux.asi` file. In the second case, your game directory would have both `cleo.asi` (or `III.CLEO.asi` or `VC.CLEO.asi`) and `cleo_redux.asi`. 
+
+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](#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.
+
+This mode does not work in 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 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](https://library.sannybuilder.com/#/gta3/classes/File) or [dynamic libraries](https://library.sannybuilder.com/#/gta3/classes/DynamicLibrary).
+
+This mode works in GTA III, GTA Vice City and GTA San Andreas.
+
 ## Installation
 
-- Copy `cleo.asi` to the game directory.
+- Copy `cleo_redux.asi` to the game directory.
 - Run the game
 
 Note: CLEO Redux does not alter any game files. It exploits the fact that the game natively loads `.asi` files as addons to the Miles Sound System library. No extra software is required.
 
-You should see the words "CLEO Redux" and the current version in the bottom-left corner of the game menu.
+You should see the words "CLEO Redux" and the current version in the bottom-right corner of the game menu.
 
 ### First time setup
 
@@ -38,19 +67,20 @@ When running on `re3` and `reVC` make sure the game directory contains the file
 
 ### Uninstallation
 
-- Delete `cleo.asi`.
+- Delete `cleo_redux.asi`.
 - Delete the `CLEO` folder (optional).
-- Delete the `cleo.log` (optional)
+- Delete the `cleo_redux.log` (optional)
 
 ## Configuration
 
 CLEO Redux exposes some of the configurable settings in the file `CLEO\.config\cleo.ini`.
 
 ### General Configuration
 
+- `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.
 - `CheckUpdates` - when set to `1` CLEO check if there is a new update available for download during the game startup. Enabled by default.
-- `LogOpcodes` - when set to `1` CLEO logs all executed opcodes in custom scripts. This log is part of the `cleo.log` file that can be found in the game directory.
+- `LogOpcodes` - when set to `1` CLEO logs all executed opcodes in custom scripts. This log is part of the `cleo_redux.log` file that can be found in the game directory.
 - `PermissionLevel` - sets the permission level for unsafe operations (see below). Default is `Lax`.
 
 ### Permissions
@@ -91,7 +121,7 @@ No unsafe operation is allowed.
 
 ## Log
 
-CLEO logs important events and errors in the `cleo.log` file located in the game directory. This file gets overwritten on each game run. If you experience any issue when using CLEO Redux, start investigating the root cause from this file.
+CLEO logs important events and errors in the `cleo_redux.log` file located in the game directory. This file gets overwritten on each game run. If you experience any issue when using CLEO Redux, start investigating the root cause from this file.
 
 ## Custom Scripts
 
@@ -103,14 +133,6 @@ Generally a script file should just be copied to the `CLEO` directory. Some scri
 
 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.
 
-### Supported Languages
-
-CLEO Redux supports compiled binary scripts (`*.cs`) in the native SCM format and plain text scripts (`*.js`) written in 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.
-
-JavaScript is enabled by default. To disable it open up `CLEO\.config\cleo.ini` and change `AllowJs` to `0`.
-
 ### Custom Commands
 
 - 0A8C [WRITE_MEMORY](https://library.sannybuilder.com/#/gta3/CLEO/0A8C) (**UNSAFE** - requires `mem` permission)
@@ -154,15 +176,24 @@ For `GTA VC` or `reVC`
 /// <reference path=".config/vc.d.ts" />
 ```
 
+For `GTA SA`
+
+```
+/// <reference path=".config/sa.d.ts" />
+```
+
 This line instructs VS Code where to look for the commands definitions for the autocomplete feature. The `path` can be relative to the script file or be absolute. [Find out more information](https://www.typescriptlang.org/docs/handbook/triple-slash-directives.html#-reference-path-) on the official TypeScript portal.
 
 ## JavaScript Support
 
 ### Prerequisites
 
-When JavaScript is enabled CLEO Redux needs commands definitions from https://library.sannybuilder.com/. On the first run CLEO would try to download the necessary files and put them into your local `CLEO/.config` directory. If that did not happen, or you don't want to let CLEO make network calls, manually download [gta3.json](https://github.com/sannybuilder/library/blob/master/gta3/gta3.json) or [vc.json](https://github.com/sannybuilder/library/blob/master/vc/vc.json) and place them in the `CLEO/.config` directory.
+When JavaScript is enabled CLEO Redux needs commands definitions from https://library.sannybuilder.com/. On the first run CLEO would try to download the necessary files and put them into your local `CLEO/.config` directory. If that did not happen, or you don't want to let CLEO make network calls, manually download [gta3.json](https://github.com/sannybuilder/library/blob/master/gta3/gta3.json), [vc.json](https://github.com/sannybuilder/library/blob/master/vc/vc.json), or [sa.json](https://github.com/sannybuilder/library/blob/master/sa/sa.json) and place them in the `CLEO/.config` directory.
 
-Minimum required version of the commands definitions is `0.92` for `gta3.json` and `0.136` for `vc.json`.
+Minimum required version of the commands definitions: 
+ * `gta3.json`: `0.99`
+ * `vc.json`: `0.143`
+ * `sa.json`: `0.164`
 
 ### Script Lifecycle
 
@@ -188,7 +219,7 @@ while (true) {
 
 ### Native Commands
 
-CLEO Redux supports all in-game commands (opcodes) in the class form as defined in Sanny Builder Library. Keywords and custom extensions are not supported.
+CLEO Redux supports all in-game commands (opcodes) in the class form as defined in Sanny Builder Library.
 
 #### Class ScriptObject vs Object
 
@@ -259,7 +290,7 @@ This would be the equivalent to the opcode `020B: explode_car $infernus` or `EXP
 
 ### Custom Bindings
 
-- `GAME` - current game id. Possible values: `gta3`, `vc`, `re3`, `reVC`
+- `GAME` - current game id. Possible values: `gta3`, `vc`, `re3`, `reVC`, `sa`
 
 ```js
 if (GAME === "gta3") {
@@ -268,9 +299,12 @@ if (GAME === "gta3") {
 if (GAME === "vc") {
   showTextBox("This is Vice City");
 }
+if (GAME === "sa") {
+  showTextBox("This is San Andreas");
+}
 ```
 
-- `log(...values)` - prints comma-separated `{values}` to the cleo.log
+- `log(...values)` - prints comma-separated `{values}` to the cleo_redux.log
 
 ```js
 var x = 1;
@@ -326,7 +360,7 @@ if (op(0x0248, 101)) {
 
 ### SCM Log
 
-CLEO Redux has built-in support for tracking SCM instructions. To enable trace for executed commands open up cleo.ini and change `LogOpcodes` to 1.
+CLEO Redux has built-in support for tracking SCM instructions. To enable trace for executed commands open up `cleo.ini` and change `LogOpcodes` to 1. Note that it can greatly impact game performance due to frequent microdelays during writes to the log file. Use this option only for debugging purposes.
 
 ### Hot Reload
 

examples/gang_weapon_randomizer.js

@@ -0,0 +1,25 @@
+// Script by Vital (Vitaly Pavlovich Ulyanov)
+/// <reference path=".config/vc.d.ts"/>
+
+if (GAME === "vc") {
+  var gangs = [0, 1, 2, 3, 4, 5, 6],
+    primary_weapons = [19, 21, 22, 23, 24, 25, 26, 27],
+    secondary_weapons = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 17, 18];
+  var gn_len = gangs.length,
+    pr_weap_len = primary_weapons.length,
+    sc_weap_len = secondary_weapons.length;
+
+  while (true) {
+    wait(3000);
+
+    for (var i = 0; i < gn_len; i++) {
+      Gang.SetWeapons(
+        gangs[i],
+        primary_weapons[Math.RandomIntInRange(0, pr_weap_len)],
+        secondary_weapons[Math.RandomIntInRange(0, sc_weap_len)]
+      );
+    }
+  }
+} else {
+  log("Sorry, this script is for GTA VC only")
+}

examples/saveanywhere.js → examples/save_anywhere.js

@@ -1,6 +1,7 @@
 // uncomment one of these to enable autocomplete in VS Code
 // /// <reference path=".config/gta3.d.ts" />
 // /// <reference path=".config/vc.d.ts" />
+// /// <reference path=".config/sa.d.ts" />
 
 var VK_F4 = 115;
 while (true) {

examples/slow_time.js

@@ -2,11 +2,12 @@
 
 var VK_R = 82;
 var game_speed = 1.0;
+var player = new Player(0);
 
 while (true) {
   wait(0);
 
-  if (op(0x0256, 0) && Pad.IsKeyPressed(VK_R)) {
+  if (player.isPlaying() && Pad.IsKeyPressed(VK_R)) {
     // Wait for button release (ON)
     while (Pad.IsKeyPressed(VK_R)) {
       wait(0);
@@ -45,10 +46,10 @@ while (true) {
 }
 
 function playSound(soundId) {
-  op(0x018c, 0, 0, 0, soundId);
+  Sound.AddOneOffSound(0, 0, 0, soundId)
 }
 
 function setGameSpeed(speed) {
   game_speed = speed;
-  op(0x015d, speed);
+  Clock.SetTimeScale(speed)
 }

examples/spawn_infernus.js

@@ -6,15 +6,15 @@
  * when the F5 button is pressed
  */
 var VK_F5 = 116;
-var MI_INFERNUS = GAME === "re3" || GAME === "gta3" ? 101 : 141;
+var MI_INFERNUS = getInfernusMI();
 var player = new Player(0);
 
 while (true) {
   wait(250);
   if (Pad.IsKeyPressed(VK_F5) && player.isPlaying()) {
     loadModel(MI_INFERNUS);
 
-    var pos = addVec(player.getCoordinates(), { x: 2.0, y: -2.0, z: 0 });
+    var pos = addVec(player.getChar().getCoordinates(), { x: 2.0, y: -2.0, z: 0 });
     var infernus = Car.Create(MI_INFERNUS, pos.x, pos.y, pos.z);
     var blip = Blip.AddForCar(infernus);
 
@@ -37,3 +37,16 @@ function loadModel(mi) {
 function addVec(v1, v2) {
   return { x: v1.x + v2.x, y: v1.y + v2.y, z: v1.z + v2.z };
 }
+
+function getInfernusMI() {
+  switch (GAME) {
+    case "re3":
+    case "gta3":
+      return 101;
+    case "reVC":
+    case "vc":
+      return 141;
+    case "sa":
+      return 411;
+  }
+}

website/index.html

@@ -6,7 +6,7 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <meta
       name="description"
-      content="CLEO Redux: a new scripting runtime for GTA 3D games"
+      content="CLEO Redux is an experimental JavaScript runtime for classic GTA 3D games"
     />
     <meta name="author" content="Seemann" />
     <title>CLEO Redux</title>
@@ -72,8 +72,7 @@ <h1 class="font-weight-bold d-flex justify-content-center">
           <hr class="divider" />
           <div class="mb-5 text-white-75">
             <p>
-              CLEO Redux is a new experimental scripting runtime for GTA III and
-              GTA Vice City with JavaScript support.
+              CLEO Redux is an experimental JavaScript runtime for classic GTA 3D games.
             </p>
             <p>
               It brings a joy of enhancing the gameplay with countless
@@ -98,7 +97,7 @@ <h1 class="font-weight-bold d-flex justify-content-center">
                 href="https://github.com/cleolibrary/CLEO-Redux/releases/latest"
                 >Download</a
               >
-              <small class="pt-1 text-muted">v0.6.2 | Oct 11, 2021</small>
+              <small class="pt-1 text-muted">v0.7.0 | Oct 30, 2021</small>
             </div>
           </div>
         </div>
@@ -114,8 +113,8 @@ <h1 class="font-weight-bold d-flex justify-content-center">
           <a href="LICENSE.txt">end-user license agreement</a>.
         </p>
         <p class="m-0">
-          Grand Theft Auto III, Grand Theft Auto: Vice City © Rockstar Games,
-          Inc. Photo by
+          Grand Theft Auto III, Grand Theft Auto: Vice City, Grand Theft Auto:
+          San Andreas © Rockstar Games, Inc. Photo by
           <a href="https://www.pexels.com/@kubiceknov" target="_blank"
             >Jakub Novacek</a
           >