0.7.1 release

CHANGELOG.md

@@ -1,7 +1,12 @@
+### 0.7.1 - Nov 02, 2021
+
+- new static function `Memory.Translate` to get memory address of a function or variable by its name (see [documentation](using-memory.md#finding-memory-addresses-in-re3-and-revc))
+- new function `exit` to terminate the script early
+
 ### 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 
+- CLEO Redux is now able to execute 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`
 

README.md

@@ -328,6 +328,8 @@ showTextBox("Hello, world!");
 
 - family of static methods in the `Memory` class for manipulating different data types. See the [Memory guide](using-memory.md) for more information.
 
+- `exit(reason?)` - terminates the script immeditely. `exit` function accepts an optional string argument that will be added to the `cleo_redux.log`.
+
 ### Deprecated
 
 Note: usage of the following commands is not recommended.

examples/free_resprays[mem].js

@@ -0,0 +1,11 @@
+/// <reference path=".config/gta3.d.ts" />
+
+if (GAME !== "re3" && GAME !== "reVC") {
+  exit("Only for re3 or reVC");
+}
+
+wait(1000);
+var addr = Memory.Translate("CGarages::RespraysAreFree");
+Memory.WriteU8(addr, 1, 0);
+
+showTextBox("Resprays are free now!");

using-memory.md

@@ -30,6 +30,8 @@ interface Memory {
     ToI16(value: int): int;
     ToI32(value: int): int;
 
+    Translate(symbol: string): int;
+
     CallFunction(address: int, numParams: int, pop: int, ...funcParams: int[]): void;
     CallFunctionReturn(address: int, numParams: int, pop: int, ...funcParams: int[]): int;
     CallMethod(address: int, struct: int, numParams: int, pop: int, ...funcParams: int[]): void;
@@ -67,7 +69,7 @@ interface Memory {
 
 ### Reading and Writing Values
 
-First group of methods (`ReadXXX`/`WriteXXX`) can be used for changing values stored in the memory. Each method is designed for a particular data type. To change a floating-point value (which occupies 4 bytes in the original game) use `Memory.WriteFloat`, e.g.:
+Group of memory access methods (`ReadXXX`/`WriteXXX`) can be used for reading or modifying values stored in the memory. Each method is designed for a particular data type. To change a floating-point value (which occupies 4 bytes in the original game) use `Memory.WriteFloat`, e.g.:
 
 ```js
     Memory.WriteFloat(address, 1.0, false)
@@ -233,3 +235,19 @@ By default a returned result is considered a 32-bit signed integer value. If the
 ```
 
 This code invokes a `cdecl` function at `0x1234567` with no arguments and stores the result as a 8-bit unsigned integer value. 
+
+
+### Finding Memory Addresses in re3 and reVC
+
+Since `re3` and `reVC` use address space layout randomization (ASLR) feature, it can be difficult to locate needed addresses. CLEO Redux provides a helper function `Memory.Translate` that accepts a name of the function or variable and returns its current address. If the requested symbol is not found, the result is 0.
+
+```js
+    var addr = Memory.Translate("CTheScripts::MainScriptSize");
+
+    // check if address is not zero
+    if (addr) {
+        showTextBox("MainScriptSize = " + Memory.ReadI32(addr, 0))
+    }
+```
+
+At the moment `Memory.Translate` should only be used in `re3` and `reVC`. In other games you will be getting `0` as a result most of the time.