-
-
Notifications
You must be signed in to change notification settings - Fork 19
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
5 changed files
with
186 additions
and
19 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,54 @@ | ||
| ## Using Math Object | ||
|
|
||
| JavaScript has a built-in `Math` object that provides common mathematical operations, such as `abs`, `sin`, `cos`, `random`, `pow`, `sqr`, etc. CLEO Redux extends this object to include extra operations supported by the game. The interface of `Math` looks as follows: | ||
|
|
||
| ```ts | ||
| declare class Math { | ||
| // native code | ||
| static readonly E: number; | ||
| static readonly LN10: number; | ||
| static readonly LN2: number; | ||
| static readonly LOG2E: number; | ||
| static readonly LOG10E: number; | ||
| static readonly PI: number; | ||
| static readonly SQRT1_2: number; | ||
| static readonly SQRT2: number; | ||
| static abs(x: number): number; | ||
| static acos(x: number): number; | ||
| static asin(x: number): number; | ||
| static atan(x: number): number; | ||
| static atan2(y: number, x: number): number; | ||
| static ceil(x: number): number; | ||
| static cos(x: number): number; | ||
| static exp(x: number): number; | ||
| static floor(x: number): number; | ||
| static log(x: number): number; | ||
| static max(...values: number[]): number; | ||
| static min(...values: number[]): number; | ||
| static pow(x: number, y: number): number; | ||
| static random(): number; | ||
| static round(x: number): number; | ||
| static sin(x: number): number; | ||
| static sqrt(x: number): number; | ||
| static tan(x: number): number; | ||
|
|
||
| // GTA III and GTA Vice City commands | ||
| static ConvertMetresToFeet(metres: int): int; | ||
| static RandomFloatInRange(min: float, max: float): float; | ||
| static RandomIntInRange(min: int, max: int): int; | ||
| // GTA Vice City-only commands | ||
| static GetDistanceBetweenCoords2D(fromX: float, fromY: float, toX: float, toZ: float): float; | ||
| static GetDistanceBetweenCoords3D(fromX: float, fromY: float, fromZ: float, toX: float, toY: float, toZ: float): float; | ||
| } | ||
| ``` | ||
|
|
||
| The first group includes the native constants and methods provided by the JavaScript runtime. They start with a lowercase letter, e.g. `Math.abs`. You can find the detailed documentation for these methods [here](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math). | ||
|
|
||
| The second group includes the game-specific methods (in this case those of GTA III). Following the naming convention, each method that is bound to a script opcode starts with a capital letter, e.g. `Math.RandomIntInRange` (opcode 0209). You can find the documentation in [Sanny Builder Library](https://library.sannybuilder.com/). | ||
|
|
||
|
|
||
| ```js | ||
| var x = Math.abs(-1); // x = 1 | ||
| var f = Math.ConvertMetresToFeet(10) // f = 32 | ||
| var pi = Math.floor(Math.PI) // pi = 3 | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,89 @@ | ||
| ## Using Memory class | ||
|
|
||
| Static class `Memory` provides methods for accessing and manipulating the data or code in the current process. It has the following interface: | ||
|
|
||
| ```ts | ||
| class Memory { | ||
| static ReadFloat(address: int, vp: boolean): float; | ||
| static WriteFloat(address: int, value: float, vp: boolean): void; | ||
| static ReadI8(address: int, vp: boolean): int; | ||
| static ReadI16(address: int, vp: boolean): int; | ||
| static ReadI32(address: int, vp: boolean): int; | ||
| static ReadU8(address: int, vp: boolean): int; | ||
| static ReadU16(address: int, vp: boolean): int; | ||
| static ReadU32(address: int, vp: boolean): int; | ||
| static WriteI8(address: int, value: int, vp: boolean): void; | ||
| static WriteI16(address: int, value: int, vp: boolean): void; | ||
| static WriteI32(address: int, value: int, vp: boolean): void; | ||
| static WriteU8(address: int, value: int, vp: boolean): void; | ||
| static WriteU16(address: int, value: int, vp: boolean): void; | ||
| static WriteU32(address: int, value: int, vp: boolean): void; | ||
| static Read(address: int, size: int, vp: boolean): int; | ||
| static Write(address: int, size: int, value: int, vp: boolean): void; | ||
|
|
||
| static ToFloat(value: int): float; | ||
| static FromFloat(value: float): int; | ||
| static ToU8(value: int): int; | ||
| static ToU16(value: int): int; | ||
| static ToU32(value: int): int; | ||
| static ToI8(value: int): int; | ||
| static ToI16(value: int): int; | ||
| static ToI32(value: int): int; | ||
| } | ||
| ``` | ||
|
|
||
| ### 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.: | ||
|
|
||
| ```js | ||
| Memory.WriteFloat(address, 1.0, false) | ||
| ``` | ||
|
|
||
| where `address` is a variable storing the memory location, `1.0` is the value to write and `false` means it's not necessary to change the memory protection with `VirtualProtect` (the address is already writable). | ||
|
|
||
| Similarly, to read a value from the memory, use one of the `ReadXXX` methods, depending on what data type the memory address contains. For example, to read a 8-bit signed integer (also known as a `char` or `uint8`) use `Memory.ReadI8`, e.g.: | ||
|
|
||
| ```js | ||
| var x = Memory.ReadI8(address, true) | ||
| ``` | ||
|
|
||
| variable `x` now holds a 8-bit integer value in the range (0..255). For the sake of showing possible options, this example uses `true` as the last argument, which means the default protection attribute for this address will be changed to `PAGE_EXECUTE_READWRITE` before the read. | ||
|
|
||
| ```js | ||
| var gravity = Memory.ReadFloat(gravityAddress, false); | ||
| gravity += 0.05; | ||
| Memory.WriteFloat(gravityAddress, gravity, false); | ||
| ``` | ||
|
|
||
| Finally, last two methods `Read` and `Write` is what other methods use under the hood. They have direct binding to opcodes [0A8D READ_MEMORY](https://library.sannybuilder.com/#/gta3/CLEO/0A8D) and [0A8C WRITE_MEMORY](https://library.sannybuilder.com/#/gta3/CLEO/0A8C) and produce the same result. | ||
|
|
||
| The `size` parameter in the `Read` method can only be `1`, `2` or `4`. CLEO treats the `value` as a signed integer stored in the little-endian format. | ||
|
|
||
| In the `Write` method any `size` larger than `0` is allowed. Sizes `3` and `5` onwards can only be used together with a single byte `value`. CLEO uses them to fill a continious block of memory starting at the `address` with the given `value` (think of it as `memset` in C++). | ||
|
|
||
| ```js | ||
| Memory.Write(addr, 0x90, 10, true) // "noping" 10 bytes of code starting from addr | ||
| ``` | ||
|
|
||
| **Note that usage of any of the read/write methods requires the `mem` [permission](README.md#Permissions)**. | ||
|
|
||
|
|
||
| ### Casting methods | ||
|
|
||
| By default `Read` and `Write` methods treat data as signed integer values. It can be inconvinient if the memory holds a floating-point value in IEEE 754 format or a large 32-bit signed integer (e.g. a pointer). In this case use casting methods `ToXXX`/`FromXXX`. They act similarly to [reinterpret_cast](https://docs.microsoft.com/en-us/cpp/cpp/reinterpret-cast-operator?view=msvc-160) operator in C++. | ||
|
|
||
| To get a quick idea what to expect from those methods see the following examples: | ||
|
|
||
| ```js | ||
| Memory.FromFloat(1.0) => 1065353216 | ||
| Memory.ToFloat(1065353216) => 1.0 | ||
| Memory.ToU8(-1) => 255 | ||
| Memory.ToU16(-1) => 65535 | ||
| Memory.ToU32(-1) => 4294967295 | ||
| Memory.ToI8(255) => -1 | ||
| Memory.ToI16(65535) => -1 | ||
| Memory.ToI32(4294967295) => -1 | ||
| ``` | ||
|
|
||
| Alternatively, use appropriate methods to read/write the value as a float (`ReadFloat`/`WriteFloat`) or as an unsigned integer (`ReadUXXX`/`WriteUXXX`). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters