update to 1.0.6-dev

cleolibrary · Dec 26, 2022 · 939ab88 · 939ab88
1 parent ed72d9d
commit 939ab88
Show file tree

Hide file tree

Showing 11 changed files with 323 additions and 61 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,3 +1,19 @@
+### 1.0.6
+
+- new built-in function `addEventListener` to react on [game events](https://re.cleo.li/docs/en/events.html)
+- fix a rare deadlock causing scripts to stop on timeout
+
+**SDK AND PLUGINS**
+
+- new SDK method `TriggerEvent` to trigger custom events with some payload. SDK version is now 7.
+- new Events plugin that brings in a few events to react on in JS/TS code: `OnVehicleCreate`, `OnPedCreate`, `OnObjectCreate`, `OnVehicleDelete`, `OnPedDelete`, `OnObjectDelete`
+- IdeLoader 1.3: generate `ide_loader.d.ts` for better intellisense in TS scripts
+- TxtLoader 1.1: generate `txt_loader.d.ts` for better intellisense in TS scripts
+
+**BREAKING CHANGES**
+
+- bumped minimum required versions of [command definitions](https://re.cleo.li/docs/en/definitions.html)
+
 ### 1.0.5 - December 15, 2022
 
 - add [TypeScript support](https://re.cleo.li/docs/en/typescript.html)
@@ -8,6 +24,7 @@
 - `is_variadic` attribute is no longer used in JIT compilation of commands with the `arguments` type
 
 **SDK AND PLUGINS**
+
 - IdeLoader 1.2: fixed a parser bug that prevented `.ide` files with a `2dfx` section to be loaded
 - Frontend 1.1: reduced a timeout during a check for updates to 10 seconds
 - ImGuiRedux: [more commands](https://library.sannybuilder.com/#/unknown_x86/classes/ImGui)

diff --git a/SDK/cleo_redux.lib b/SDK/cleo_redux.lib
diff --git a/SDK/cleo_redux64.lib b/SDK/cleo_redux64.lib
diff --git a/SDK/cleo_redux_sdk.h b/SDK/cleo_redux_sdk.h
@@ -151,5 +151,8 @@ extern "C" {
 	/// since v6
 	/// Is end of arguments reached
 	bool IsEndOfArguments(Context ctx);
+	/// since v7
+	/// Triggers an event with the given name and data
+	void TriggerEvent(const char* name, const char* data);
 }
 
diff --git a/SDK/cleo_redux_sdk.rs b/SDK/cleo_redux_sdk.rs
@@ -195,6 +195,10 @@ extern "C" {
     ///
     /// since v6
     fn IsEndOfArguments(ctx: Context) -> bool;
+    /// Trigger an event with the given name and data
+    ///
+    /// since v7
+    fn TriggerEvent(event: *const c_char, data: *const c_char);
 }
 
 macro_rules! sz {
@@ -478,3 +482,11 @@ pub fn get_number_of_active_js_scripts() -> usize {
 pub fn is_end_of_arguments(ctx: Context) -> bool {
     unsafe { IsEndOfArguments(ctx) }
 }
+
+/// Triggers an event with the given name and data
+///
+/// since v7
+#[allow(dead_code)]
+pub fn trigger_event(name: &str, data: &str) {
+    unsafe { TriggerEvent(sz!(name), sz!(data)) }
+}
diff --git a/docs/en/SUMMARY.md b/docs/en/SUMMARY.md
@@ -24,6 +24,7 @@
     - [Script Lifecycle](./script-lifecycle.md)
     - [Imports](./imports.md)
     - [Asynchronous Programming](./async.md)
+    - [Events](./events.md)
     - [API](./api.md)
       - [Fluent Interface](./fluent-interface.md)
       - [Enums](./enums.md)

diff --git a/docs/en/api.md b/docs/en/api.md
@@ -1,5 +1,30 @@
 # JavaScript API
 
+- [Native functions](#native-functions)
+- [CLEO Redux Bindings](#cleo-redux-bindings)
+  - [Variables](#variables)
+    - [HOST](#host)
+    - [ONMISSION](#onmission)
+    - [TIMERA, TIMERB](#timera-timerb)
+    - [\_\_dirname](#__dirname)
+    - [\_\_filename](#__filename)
+  - [Functions](#functions)
+    - [log](#log)
+    - [wait](#wait)
+    - [showTextBox](#showtextbox)
+    - [exit](#exit)
+    - [native](#native)
+  - [Static Objects](#static-objects)
+    - [Memory](#memory)
+    - [Math](#math)
+    - [FxtStore](#fxtstore)
+    - [CLEO](#cleo)
+      - [CLEO.debug](#cleodebug)
+      - [CLEO.version](#cleoversion)
+      - [CLEO.apiVersion](#cleoapiversion)
+      - [CLEO.runScript](#cleorunscript)
+      - [CLEO.getLastEvent](#cleogetlastevent)
+
 ## Native functions
 
 CLEO Redux supports all commands native to the current game. In the classic GTA 3D series they are also known as _opcodes_. In GTA IV they are known as _native functions_. You can find them in [Sanny Builder Library](https://library.sannybuilder.com/).
@@ -194,71 +219,82 @@ if (native("HAS_MODEL_LOADED", 101)) {
   log(CLEO.apiVersion.build); // undefined
   ```
 
-##### CLEO.runScript
+  ##### CLEO.runScript
 
-- `CLEO.runScript(fileName, args?)` - method that spawns a new instance of the script. `fileName` is the path to the script to launch. `args` is an optional parameter to pass arguments to the script.
+  - `CLEO.runScript(fileName, args?)` - method that spawns a new instance of the script. `fileName` is the path to the script to launch. `args` is an optional parameter to pass arguments to the script.
 
-  > Don't overuse this feature as spawning a new script is a costly operation. Avoid spawning too many scripts in a loop.
+    > Don't overuse this feature as spawning a new script is a costly operation. Avoid spawning too many scripts in a loop.
 
-  `runScript` has the following limitations:
+    `runScript` has the following limitations:
 
-  - JS scripts must have an extension `.mjs`, CS scripts must have an extension `.s`. This is necessary to avoid automatic script loading.
-  - spawning CS scripts is not supported in the [delegate mode](./relation-to-cleo-library.md#running-cleo-redux-as-an-addon-to-cleo-library) (i.e. won't work in GTA San Andreas with CLEO 4 installed.)
+    - JS scripts must have an extension `.mjs`, CS scripts must have an extension `.s`. This is necessary to avoid automatic script loading.
+    - spawning CS scripts is not supported in the [delegate mode](./relation-to-cleo-library.md#running-cleo-redux-as-an-addon-to-cleo-library) (i.e. won't work in GTA San Andreas with CLEO 4 installed.)
 
-  When running a new script you can also provide arguments to it. `args` is a JavaScript object which keys correspond to variable names in the script. Key names for a CS script are numeric and correspond to local variables (0@, 1@, 2@, etc). JS scripts can receive both numbers and strings as arguments, whereas CS scripts can only receive numbers.
+    When running a new script you can also provide arguments to it. `args` is a JavaScript object which keys correspond to variable names in the script. Key names for a CS script are numeric and correspond to local variables (0@, 1@, 2@, etc). JS scripts can receive both numbers and strings as arguments, whereas CS scripts can only receive numbers.
 
-  You can spawn multiple instances of the same script with different arguments.
+    You can spawn multiple instances of the same script with different arguments.
 
-  ###### Launching a new JS script
+    ###### Launching a new JS script
 
-  Imagine that you have two files `main.js` and `child.mjs` in the CLEO directory:
+    Imagine that you have two files `main.js` and `child.mjs` in the CLEO directory:
 
-  main.js:
+    main.js:
 
-  ```js
-  CLEO.runScript("./child.mjs", { a: 1, b: "str", c: 10.5 });
-  ```
+    ```js
+    CLEO.runScript("./child.mjs", { a: 1, b: "str", c: 10.5 });
+    ```
 
-  child.mjs:
+    child.mjs:
 
-  ```js
-  showTextBox("child.mjs was launched with: " + a + " " + b + " " + c);
-  ```
+    ```js
+    showTextBox("child.mjs was launched with: " + a + " " + b + " " + c);
+    ```
 
-  Now if you run the game you should see the following message: `child.mjs was launched with: 1 str 10.5`.
+    Now if you run the game you should see the following message: `child.mjs was launched with: 1 str 10.5`.
 
-  ###### Launching a new CS script
+    ###### Launching a new CS script
 
-  main.js:
+    main.js:
 
-  ```js
-  CLEO.runScript("./child.cs", { 1: 500 });
-  ```
+    ```js
+    CLEO.runScript("./child.cs", { 1: 500 });
+    ```
 
-  child.cs:
+    child.cs:
 
-  ```
-  0109: player $PLAYER_CHAR money += 1@
-  0A93: terminate_this_custom_script
-  ```
+    ```
+    0109: player $PLAYER_CHAR money += 1@ // gives the player $500
+    0A93: terminate_this_custom_script
+    ```
 
-  The player will get 500 dollars.
+    To pass floating-point numbers to a CS script use `Memory.FromFloat` function:
 
-  To pass floating-point numbers to a CS script use `Memory.FromFloat` function:
+    main.js:
 
-  main.js:
+    ```js
+    CLEO.runScript("./child.cs", {
+      0: Memory.FromFloat(-921.25),
+      1: Memory.FromFloat(662.125),
+      2: Memory.FromFloat(-100.0),
+    });
+    ```
 
-  ```js
-  CLEO.runScript("./child.cs", {
-    0: Memory.FromFloat(-921.25),
-    1: Memory.FromFloat(662.125),
-    2: Memory.FromFloat(-100.0),
-  });
-  ```
+    child.cs:
 
-  child.cs:
+    ```
+    00A1: set_char_coordinates $PLAYER_ACTOR x 0@ y 1@ z 2@ // teleports the player at -921.25 662.125 -100.0
+    0A93: terminate_this_custom_script
+    ```
 
-  ```
-  00A1: set_char_coordinates $PLAYER_ACTOR x 0@ y 1@ z 2@
-  0A93: terminate_this_custom_script
-  ```
+  ##### CLEO.getLastEvent
+
+  - `CLEO.getLastEvent(): object | undefined` - method that returns the last event object. The event object is a JavaScript object with the following fields:
+
+    - `name` - the name of the event
+    - `data` - any payload [associated with the event](./events.md#list-of-events)
+
+    The method returns `undefined` if there was no event in this frame.
+
+    ```js
+    log(CLEO.getLastEvent()); // { name: "OnVehicleCreate", data: { address: 0x12345678 } }
+    ```
diff --git a/docs/en/definitions.md b/docs/en/definitions.md
@@ -6,15 +6,15 @@ At start CLEO validates that a definition file is present and correct and if not
 
 | Game                                | File                                                                                                 | Minimum Required Version |
 | ----------------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------ |
-| GTA III, re3                        | [gta3.json](https://github.com/sannybuilder/library/blob/master/gta3/gta3.json)                      | `0.251`                  |
-| GTA VC, reVC                        | [vc.json](https://github.com/sannybuilder/library/blob/master/vc/vc.json)                            | `0.257`                  |
-| GTA San Andreas (Classic) 1.0       | [sa.json](https://github.com/sannybuilder/library/blob/master/sa/sa.json)                            | `0.294`                  |
+| GTA III, re3                        | [gta3.json](https://github.com/sannybuilder/library/blob/master/gta3/gta3.json)                      | `0.252`                  |
+| GTA VC, reVC                        | [vc.json](https://github.com/sannybuilder/library/blob/master/vc/vc.json)                            | `0.258`                  |
+| GTA San Andreas (Classic) 1.0       | [sa.json](https://github.com/sannybuilder/library/blob/master/sa/sa.json)                            | `0.298`                  |
 | GTA III: The Definitive Edition     | [gta3_unreal.json](https://github.com/sannybuilder/library/blob/master/gta3_unreal/gta3_unreal.json) | `0.222`                  |
 | Vice City: The Definitive Edition   | [vc_unreal.json](https://github.com/sannybuilder/library/blob/master/vc_unreal/vc_unreal.json)       | `0.228`                  |
-| San Andreas: The Definitive Edition | [sa_unreal.json](https://github.com/sannybuilder/library/blob/master/sa_unreal/sa_unreal.json)       | `0.250`                  |
+| San Andreas: The Definitive Edition | [sa_unreal.json](https://github.com/sannybuilder/library/blob/master/sa_unreal/sa_unreal.json)       | `0.251`                  |
 | GTA IV                              | [gta_iv.json](https://github.com/sannybuilder/library/blob/master/gta_iv/gta_iv.json)                | `0.46`                   |
 | Unknown (32-bit)                    | [unknown_x86.json](https://github.com/sannybuilder/library/blob/master/unknown_x86/unknown_x86.json) | `0.222`                  |
 | Unknown (64-bit)                    | [unknown_x64.json](https://github.com/sannybuilder/library/blob/master/unknown_x64/unknown_x64.json) | `0.225`                  |
-| Bully: Scholarship Edition          | [bully.json](https://github.com/sannybuilder/library/blob/master/bully/bully.json)                   | `0.35`                   |
+| Bully: Scholarship Edition          | [bully.json](https://github.com/sannybuilder/library/blob/master/bully/bully.json)                   | `0.39`                   |
 
 CLEO Redux uses compound definitions (a combination of the primary JSON file for the current game and a JSON file for the Unknown host). It lets SDK commands to work in JS scripts regardless of them being defined or not in the primary JSON file. You should notice that during updates CLEO downloads both `<game>.json` and `unknown.json` as well as the accompanying `enums.js` files. It should not affect any existing scripts.