0.5.0 release

CHANGELOG.md

@@ -1,3 +1,13 @@
+### 0.5.0 - September 25, 2021
+
+- add support for GTA III 1.0 and GTA VC 1.0
+- add support for auto-incrementing variables `TIMERA` and `TIMERB`
+- add permission levels for unsafe opcodes
+- add two unsafe opcodes: 0A8C WRITE_MEMORY and 0A8D READ_MEMORY
+- fix: custom opcodes did not work in main.scm
+- fix: gosub did not work in CS scripts
+- fix: race condition caused false-positive timeouts for JS scripts
+
 ### 0.4.0 - September 02, 2021
 
 - add bindings for all opcodes in JS scripts
@@ -14,7 +24,7 @@
 
 ### 0.3.0 - August 17, 2021
 
-- add experimental VM executing ES5 code (JavaScript)
+- add experimental VM executing ECMAScript 5 (JavaScript)
 
 ### 0.2.1 - August 14, 2021
 

README.md

@@ -1,51 +1,134 @@
 # CLEO Redux
 
-This is the official port of CLEO Library for re3 and reVC.
+## Getting Started
 
-At the moment it's very barebone and has a limited number of features (see below).
+### What is CLEO Redux?
+
+CLEO Redux is a scripting runtime for GTA III and GTA Vice City in a form of an ASI library that the game can natively load. It's a member of the CLEO family and provides familiar experience to anyone who used CLEO Library for GTA San Andreas or its re-implementations for other games. The main goal of CLEO is to provide a way to easily customize the game with countless user-made scripts.
+
+If you're new to CLEO visit the [official website](https://cleo.li/) to find more information on it.
+
+### Supported Releases
+
+- GTA III v1.0
+- GTA Vice City v1.0
+- re3
+- reVC
 
 ## Installation
 
-CLEO Redux only supports "Windows D3D9 MSS 32bit" version of re3 and reVC.
+- Copy `cleo.asi` to the game directory.
+- Run the game
+
+Note: CLEO Redux does not alter any game files.
+
+### First time setup
+
+There could be a noticeable lag during the first game run as CLEO Redux downloads the files necessary for JavaScript support. It won't happen on subsequent runs.
+
+Also a new folder named `CLEO` should appear in the game directory. This is the primary location for all CLEO scripts, plugins and configs.
+
+### Compatibility with re3 and reVC
+
+When running on `re3` and `reVC` make sure the game directory contains the file `re3.pdb` (for **re3**) or `reVC.pdb` (for **reVC**). Due to the dynamic nature of memory addresses in those implementations CLEO Redux relies on debug information stored in the PDB file to correctly locate itself.
+
+### Uninstallation
+
+- Delete `cleo.asi`.
+- Delete the `CLEO` folder (optional).
+- Delete the `cleo.log` (optional)
+
+## Configuration
+
+CLEO Redux exposes some of the configurable settings in the file `CLEO\.config\cleo.ini`.
+
+### General Configuration
+
+- `AllowJS` - when set to `1` CLEO loads and executes `*.js` files located in the CLEO directory. 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.
+- `PermissionLevel` - sets the permission level for unsafe operations (see below). Default is `Lax`.
+
+### Permissions
+
+CLEO Redux acknowledges some [custom commands](#custom-commands) (opcodes) as unsafe and requires the user to decide whether to run them or not. Raw access to the process memory, loading external libraries or making network requests can be harmful and produce undesired side-effects. Hence CLEO introduces permission levels for running the unsafe code.
+
+There are four available levels:
+
+#### All
+
+Any unsafe operation is allowed. Use this only when you trust the scripts you run.
+
+#### Lax
+
+This is the default permission level.
+
+No unsafe operation is allowed unless the script explicitly requests it. Currently to request a permission, the name of the script file must include the permissions tokens wrapped in square brackets.
+
+For example, if the script wants to access the memory via `0A8D READ_MEMORY` the file name must contain `[mem]`, e.g. `cool-spawner[mem].cs`. If the file is named differently CLEO rejects `0A8D` and the script crashes.
+
+#### Strict
+
+No unsafe operation is allowed unless the script explicitly requests it (see `"Lax"`) and the CLEO config file permits this type of operation under the `Permissions` section.
 
-- Download and install [re3](https://github.com/GTAmodding/re3#installation) or [reVC](https://github.com/GTAmodding/re3/tree/miami#installation)
+Permissions section in `cleo.ini` allows to enable or disable groups of unsafe operations by using the permission tokens. For example,
 
-- Download `cleo.asi` from the [Releases page](https://github.com/cleolibrary/cleo-redux/releases).
+```ini
+mem=0
+```
+
+disables all memory-related opcodes even if the script has the `[mem]` token in the file name.
+
+Note: `Permissions` section in the `cleo.ini` only takes effect when `PermissionLevel` is `Strict`.
+
+#### None
+
+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 the file.
 
-Make sure `cleo.asi`, `re3.exe` (or `reVC.exe`) and `re3.pdb` (or `reVC.pdb`) are located in the same folder.
+## Custom Scripts
 
-- Create CLEO directory and [install CLEO scripts](https://cleo.li/scripts.html#how_to_install_CLEO_scripts). You can try a classic `showsavescreen.cs` from CLEO 3 (see example scripts). Press `F4` to display the save screen while on foot.
+### Adding a new script
 
-**NOTE: CLEO scripts written for GTA III/Vice City should work, but CLEO Redux does not support most of the common CLEO commands yet (see the list of supported commands below).**
+Generally a script file should just be copied to the `CLEO` directory. Some scripts may require extra steps for installation. In case of any issues check the script documentation or ask its author.
 
-If the script only uses vanilla commands, or commands listed below it should work.
+### Removing the script
 
-## Features
+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.
 
-- Loading and processing compiled scripts (`*.cs`) located in the CLEO directory
+### Supported Languages
 
-- Experimental support for JavaScript execution (see below).
+CLEO Redux supports compiled binary scripts (`*.cs`) in the native SCM format and plain text scripts (`*.js`) written in JavaScript.
 
-- Hot Reload
+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.
 
-  - CLEO monitors active scripts and reloads them in game as they change https://www.youtube.com/watch?v=WanLojClqFw.
-  - Adding a new CS file in CLEO directory or deleting an existing one while the game is running starts or stops the script automatically: https://www.youtube.com/watch?v=LAi2syrsxJg
+JavaScript is enabled by default. To disable it open up `CLEO\.config\cleo.ini` and change `AllowJS` to `0`.
 
-- Basic SCM log. To enable trace for executed commands open up `cleo.ini` and change `LogOpcodes` to `1`.
+### Custom Commands
 
-## Writing CLEO Scripts in JavaScript
+- 0A93
+  [TERMINATE_THIS_CUSTOM_SCRIPT](https://library.sannybuilder.com/#/sa/CLEO/0A93)
+- 0AB0 [IS_KEY_PRESSED](https://library.sannybuilder.com/#/sa/CLEO/0AB0)
+- 0A8D [READ_MEMORY](https://library.sannybuilder.com/#/gta3/CLEO/0A8D) (**UNSAFE** - requires `mem` permission)
+- 0A8C [WRITE_MEMORY](https://library.sannybuilder.com/#/gta3/CLEO/0A8C) (**UNSAFE** - requires `mem` permission)
 
-CLEO Redux can run scripts written in [ECMAScript 5.1](https://262.ecma-international.org/5.1/). This is the foundational standard for the modern JavaScript (although not the most recent version).
+### Writing CS scripts
 
-Each script should be made as a text file with the `.js` file extension. Find out available commands in this [reference page](https://re.cleo.li/reference.html) and [example scripts](https://github.com/cleolibrary/CLEO-Redux/tree/master/examples).
+Use [Sanny Builder 3.8.0](https://sannybuilder.com) in GTA III or GTA VC edit modes respectively. Check out [this page](https://cleo.li/scripts.html) for more information.
 
-JavaScript is enabled by default. To disable it open up `cleo.ini` and change `AllowJS` to `0`.
+### Writing JS scripts
 
-**Note: 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` or `vc.json` from the [library's repo](https://github.com/sannybuilder/library) and put them to `CLEO/.config` directory.**
+Use VS Code (recommended) or any editor of your choice. Create a new file with `.js` extension and put it in the CLEO folder.
+
+Note: The runtime supports scripts in [ECMAScript 5.1 standard](https://262.ecma-international.org/5.1). It means you won't be able to use the most recent JavaScript features out of the box, however you can use any traspiler, such as [Babel](https://babeljs.io/) or [TypeScript](https://www.typescriptlang.org/), to downlevel unsupported ES6+ code to ES5.
 
 ### Integration with Visual Studio Code
 
-CLEO 0.4.0 generates typings for all supported commands that you can use when writing JavaScript in VS Code. Add the two following lines in your `*.js` script to get the full autocomplete support:
+See demo: https://youtu.be/jqz8_lGnG4g
+
+CLEO Redux generates typings for all supported commands that you can use when writing JavaScript in VS Code. Add the two following lines in your `*.js` script to get the full autocomplete support:
 
 ```
 /// <reference no-default-lib="true"/>
@@ -56,19 +139,170 @@ The first line excludes standard JavaScript API from autocomplete as it's not su
 
 The second 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.
 
-See this demo video: https://youtu.be/jqz8_lGnG4g
+## JavaScript Support
 
-## Writing Compiled CLEO Scripts (.cs)
+### Prerequisites
 
-Use [Sanny Builder 3.8.0](https://sannybuilder.com) in GTA III or GTA VC edit modes respectively. Check out [this page](https://cleo.li/scripts.html) for more information.
+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` or `vc.json` from the [library's repo](https://github.com/sannybuilder/library) and put them to the `CLEO/.config` directory.
 
-## Custom Commands
+### Script Lifecycle
 
-- 0A93
-  [TERMINATE_THIS_CUSTOM_SCRIPT](https://library.sannybuilder.com/#/sa/CLEO/0A93)
-- 0AB0 [IS_KEY_PRESSED](https://library.sannybuilder.com/#/sa/CLEO/0AB0)
+A file with the JavaScript code should have the \*.js extension and contain known instructions as described below. The script may have no instructions (the empty script). It runs as soon as the the new game starts or a save file is loaded.
+
+The script terminates automatically when the last instruction has been executed. The runtime also terminates stuck scripts to prevent the game from freezing. The stuck script is the one that took more than 2 seconds to run since the last wait command. If that happened, check out your loops, some of the are missing the wait command.
+
+```js
+while (true) {
+  // meaningless infinite loop normally freezing the game
+  // will be terminated after two seconds
+}
+```
+
+The runtime will terminate this script. To avoid that, add the wait command
+
+```js
+while (true) {
+  wait(250);
+  // still meaningless, but does not freeze the game
+}
+```
+
+### 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.
+
+#### Examples
+
+If you were to change the time of day to 22:00, run the following command
+
+```js
+Clock.SetTimeOfDay(22, 0);
+```
+
+This would be the equivalent of the opcode `00C0: set_time_of_day 22 0` or `SET_TIME_OF_DAY 22 0` in SCM code.
+
+Change player's money
+
+```js
+var player = new Player(0);
+player.addScore(1000);
+```
+
+`new Player(0);` is the equivalent of getting the player's index using `$PLAYER_CHAR` global variable in Sanny Builder.
+
+Create a dynamic entity (e.g. a car)
+
+```js
+// request a model
+Streaming.RequestModel(101);
+
+// wait while the game loads the model
+while (!Streaming.HasModelLoaded(101)) {
+  wait(250);
+}
+
+// create a car at the coordinates and store the handle
+var infernus = Car.Create(101, 1234.0, 567.0, -100.0);
+```
+
+Variable `infernus` will contain a handle of the newly created car. It can be passed directly to any command receiving the `Car` handle
+
+```js
+// create a marker on the created car and store the marker handle
+var blip = Blip.AddForCar(infernus);
+```
+
+The same variable infernus can be used to call the `Car`'s methods, for example, to explode the car
+
+```js
+infernus.explode();
+```
+
+This would be the equivalent to the opcode `020B: explode_car $infernus` or `EXPLODE_CAR $infernus` in SCM scripts.
+
+### Custom Bindings
+
+- `GAME` - current game id. Possible values: `gta3`, `vc`, `re3`, `reVC`
+
+```js
+if (GAME === "gta3") {
+  showTextBox("This is GTA III");
+}
+if (GAME === "vc") {
+  showTextBox("This is Vice City");
+}
+```
+
+- `log(...values)` - prints `{values}` to the cleo.log
+
+```js
+var x = 1;
+log("value of x is ", x);
+```
+
+- `wait(timeInMs)` - pauses the script execution for at least `{timeInMs}` milliseconds
+
+```js
+while (true) {
+  wait(1000);
+  log("1 second passed");
+}
+```
+
+- `isKeyPressed(vk_id)` - returns `true` if the key with the code `{vk_id}` is pressed. [Virtual key-codes reference](https://docs.microsoft.com/en-us/windows/win32/inputdev/virtual-key-codes)
+
+```js
+if (isKeyPressed(0x74)) {
+  log("F5 is pressed");
+}
+```
+
+- `showTextBox(text)` - displays `{text}` in the black rectangular box
+
+```js
+showTextBox("Hello, world!");
+```
+
+### Deprecated
+
+Note: usage of the following commands is not recommended.
+
+- `op(opcode_id, ...input_args)` - a low-level function to execute any in-game command with opcode `{opcode_id}`.
+
+  For the commands that return a single value, the result is this value.
+
+  For the commands that return multiple values, the result is an object where each key corresponds to a returned value. The key names match the output names given in the command definition
+
+  For the conditional commands the result is the boolean value `true` or `false`
+
+```js
+op(0x00c0, 12, 30); // sets the time of day to 12:30
+```
+
+```js
+var pos = op(0x0054, 0); // returns player 0 coordinates vector {x, y, z}
+showTextBox("Player pos:", " x = ", pos.x, " y = ", pos.y, " z = ", pos.z);
+```
+
+```js
+if (op(0x0248, 101)) {
+  // checks the condition
+  showTextBox("Model with id 101 has been loaded");
+}
+```
+
+## Dev Features
+
+### 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.
+
+### Hot Reload
+
+CLEO monitors active scripts and reloads them in game as they change
+
+Demo: https://www.youtube.com/watch?v=WanLojClqFw.
 
-## Links
+Adding a new script file in CLEO directory or deleting one while the game is running starts or stops the script automatically
 
-- re3 project: https://github.com/GTAmodding/re3
-- CLEO Redux: https://re.cleo.li/
+Demo: https://www.youtube.com/watch?v=LAi2syrsxJg