update to 1.0.0-dev

.gitignore

@@ -6,5 +6,6 @@ target
 *.asi
 *.pdb
 Release
+Debug
 x64
 *.exe

SDK/cleo_redux_sdk.h

@@ -29,9 +29,12 @@ enum class HostId
 };
 
 typedef void* Context;
+typedef intptr_t isize;
+
 typedef HandlerResult (*CommandHandler)(Context);
 typedef void* (*CustomLoader)(const char*);
-typedef intptr_t isize;
+typedef void (*OnTickCallback)(unsigned int current_time, int time_step);
+typedef void (*OnRuntimeInitCallback)();
 
 extern "C" {
 	// since v1
@@ -97,5 +100,14 @@ extern "C" {
 	// since v3
 	// Frees up the memory chunk allocated with AllocMem
 	void FreeMem(void *ptr);
-
+	// since v4
+	// Registers a new callback invoked on each main loop iteration (before scripts are executed)
+	void OnBeforeScripts(OnTickCallback callback);
+	// since v4
+	// Registers a new callback invoked on each main loop iteration (after scripts are executed)
+	void OnAfterScripts(OnTickCallback callback);
+	// since v4
+	// Registers a new callback invoked on each runtime init event (new game, saved game load, or SDK's RuntimeInit)
+    void OnRuntimeInit(OnRuntimeInitCallback callback);
 }
+

SDK/cleo_redux_sdk.rs

@@ -35,6 +35,8 @@ pub type c_void = std::ffi::c_void;
 pub type Context = *const c_void;
 pub type CustomCommand = extern "C" fn(Context) -> HandlerResult;
 pub type CustomLoader = extern "C" fn(*const c_char) -> *mut c_void;
+pub type OnTickCallback = extern "C" fn(current_time: u32, time_step: i32);
+pub type OnRuntimeInitCallback = extern "C" fn();
 
 #[cfg_attr(target_arch = "x86", link(name = "cleo_redux"))]
 #[cfg_attr(target_arch = "x86_64", link(name = "cleo_redux64"))]
@@ -128,6 +130,18 @@ extern "C" {
     ///
     /// since v3
     fn FreeMem(ptr: *mut c_void);
+    /// Registers a new callback invoked on each main loop iteration (before scripts are executed)
+    ///
+    /// since v4
+    fn OnBeforeScripts(cb: OnTickCallback);
+    /// Registers a new callback invoked on each main loop iteration (after scripts are executed)
+    ///
+    /// since v4
+    fn OnAfterScripts(cb: OnTickCallback);
+    /// Registers a new callback invoked on each runtime init event (new game, saved game load, or SDK's RuntimeInit)
+    ///
+    /// since v4
+    fn OnRuntimeInit(cb: OnRuntimeInitCallback);
 }
 
 macro_rules! sz {
@@ -317,3 +331,33 @@ pub fn alloc_mem(size: usize) -> *mut c_void {
 pub fn free_mem(ptr: *mut c_void) {
     unsafe { FreeMem(ptr) }
 }
+
+/// Registers a new callback invoked on each main loop iteration (before scripts are executed)
+///
+/// since v4
+#[allow(dead_code)]
+pub fn on_before_scripts(cb: OnTickCallback) {
+    unsafe {
+        OnBeforeScripts(cb);
+    }
+}
+
+/// Registers a new callback invoked on each main loop iteration (after scripts are executed)
+///
+/// since v4
+#[allow(dead_code)]
+pub fn on_after_scripts(cb: OnTickCallback) {
+    unsafe {
+        OnAfterScripts(cb);
+    }
+}
+
+/// Registers a new callback invoked on each runtime init event (new game, saved game load, or SDK's RuntimeInit)
+///
+/// since v4
+#[allow(dead_code)]
+pub fn on_runtime_init(cb: OnRuntimeInitCallback) {
+    unsafe {
+        OnRuntimeInit(cb);
+    }
+}

docs/en/SUMMARY.md

@@ -6,12 +6,8 @@
 
 - [Installation](./installation.md)
 
-  - [Classic GTA III, GTA VC, GTA SA](./installation-classic-games.md)
-  - [re3 or reVC](./installation-re3-revc.md)
-  - [The Definitive Edition](./installation-definitive-edition.md)
-  - [CLEO Directory](./cleo-directory.md)
-    - [Plugins](./installation-plugins.md)
-    - [Scripts](./installation-scripts.md)
+  - [Plugins](./installation-plugins.md)
+  - [Scripts](./installation-scripts.md)
 
 - [Configuration](./config.md)
 

docs/en/first-run-notes.md

@@ -1,5 +1,5 @@
-There could be a noticeable lag during the first game run as CLEO Redux downloads the files necessary for [JavaScript support](./prerequisites.md). It won't happen on subsequent runs.
+During the first game run CLEO Redux downloads extra files necessary for [JavaScript support](./prerequisites.md). It doesn't happen on subsequent runs.
 
-A new folder named `CLEO` should appear in the game directory. This is the primary location for all CLEO scripts, plugins and configs.
+After that a new folder named `CLEO` should appear in the game directory. This is the primary location for all CLEO scripts, plugins and configs.
 
 {{#include ./cleo-directory-note.md}}

docs/en/imports.md

@@ -63,7 +63,7 @@ log(lines.join("")); // prints the entire file
 - Extensions: `.ide`
 - Plugin name: `IdeLoader.cleo`
 
-The IDE loader transforms an item definition file (`*.ide`) that is widely used in GTA 3D series games. The file is imported as an object where each key corresponds to a section in the file and the value is an array of array of strings:
+The IDE loader transforms an item definition file (`*.ide`) that is widely used in GTA series games. The file is imported as an object where each key corresponds to a section in the file and the value is an array of array of strings:
 
 ```ts
 interface Ide {

docs/en/installation-plugins.md

@@ -8,6 +8,7 @@ Plugins should be copied to the `CLEO\CLEO_PLUGINS` directory.
 
 | Name       | Description                               | Link |
 | ---------- | ----------------------------------------- | ---- |
-| IniFiles   | Reading from and writing to INI files     | [src](https://github.com/cleolibrary/CLEO-Redux/tree/master/plugins/IniFiles) - [download](https://github.com/cleolibrary/CLEO-Redux/releases/download/0.9.2/CLEO_Redux-0.9.2+IniFiles+Dylib.zip)    |
-| Dylib      | Loading DLL files and importing functions | [src](https://github.com/cleolibrary/CLEO-Redux/tree/master/plugins/Dylib) - [download](https://github.com/cleolibrary/CLEO-Redux/releases/download/0.9.2/CLEO_Redux-0.9.2+IniFiles+Dylib.zip)     |
-| ImGuiRedux | Dear ImGui bindings                       | [https://github.com/user-grinch/ImGuiRedux](https://github.com/user-grinch/ImGuiRedux)     |
+| [IniFiles](https://library.sannybuilder.com/#/unknown_x86/ini)   | Reading from and writing to INI files     | [src](https://github.com/cleolibrary/CLEO-Redux/tree/master/plugins/IniFiles) - [download](https://github.com/cleolibrary/CLEO-Redux/releases/download/0.9.2/CLEO_Redux-0.9.2+IniFiles+Dylib.zip)    |
+| [Dylib](https://library.sannybuilder.com/#/unknown_x86/dylib)      | Loading DLL files and importing functions | [src](https://github.com/cleolibrary/CLEO-Redux/tree/master/plugins/Dylib) - [download](https://github.com/cleolibrary/CLEO-Redux/releases/download/0.9.2/CLEO_Redux-0.9.2+IniFiles+Dylib.zip)     |
+| [ImGuiRedux](https://library.sannybuilder.com/#/unknown_x86/imgui) | Dear ImGui bindings                       | [GitHub repo](https://github.com/user-grinch/ImGuiRedux)     |
+| [MemoryOperations](https://library.sannybuilder.com/#/unknown_x86/memops) | Low-level memory operations                      | [GitHub repo](https://github.com/cleolibrary/CLEO-REDUX-PLUGINS)     |

docs/en/installation.md

@@ -1,23 +1,39 @@
 # Installation
 
-Depending on the game CLEO Redux installation may require a few extra steps. Check the relevant guides below:
+CLEO Redux comes with a hassle-free installer that identifies the selected game and downloads all the dependencies. Just run `cleo_redux_setup.exe` and follow its steps.
 
-- [Installation for Classic GTA III, GTA VC, GTA SA](./installation-classic-games.md)
-- [Installation for re3 or reVC](./installation-re3-revc.md)
-- [Installation for The Trilogy: The Definitive Edition](./installation-definitive-edition.md)
-
-> Note that CLEO Redux recognizes the target game purely by the executable name it is running from. 
+> CLEO Redux and its installer recognize the target game purely by the executable name in the selected/working directory. 
 >
 > * GTA III - `gta3.exe`
 > * GTA VC - `gta-vc.exe`
 > * GTA SA - `gta_sa.exe`, `gta-sa.exe`, or `gta_sa_compact.exe`
+> * GTA IV - `GTAIV.exe`
 > * re3 - `re3.exe`
 > * reVC - `reVC.exe`
 > * GTA III: DE - `libertycity.exe`
 > * GTA VC: DE - `vicecity.exe`
 > * GTA SA: DE - `sanandreas.exe`
 >
-> Names matching is case-insensitive. For classic games CLEO Redux always assumes version 1.0. 
+> Names matching is case-insensitive. If the exe file does not contain a version information CLEO Redux always assumes version 1.0. 
+
+
+Once the installation is complete, run the game once. During the first run CLEO Redux downloads and generates extra files necessary for [JavaScript support](./prerequisites.md).
+
+## CLEO Directory
+
+CLEO directory is the primary location where you install [CLEO scripts](./installation-scripts.md), [CLEO plugins](./installation-plugins.md) and [custom texts](./using-fxt.md). CLEO Redux automatically creates this folder when the game starts. 
+
+In most cases this directory can be found in the game folder. If, however, CLEO lacks write permissions there and fails to create new files, it uses an alternate path at `C:\Users\<your_username>\AppData\Roaming\CLEO Redux`. `cleo_redux.log` and the `CLEO` directory can be found there.
+
+## Dependency on ASI Loader
+
+CLEO Redux is distributed as a dynamic-load library with an `.asi` extension. Historically ASI files have been used in GTA 3 and Vice City as addons to the Miles Sound System library (Mss32) which loads them into the game process. More recent titles didn't use MSS, so the modding community developed custom loaders commonly named "ASI Loader" to continue using ASI for any custom code to be injected into the game. 
+
+[Ultimate ASI Loader](https://github.com/ThirteenAG/Ultimate-ASI-Loader/releases) by ThirteenAG can be used to load CLEO Redux in all games except GTA3/VC/re3/reVC. It gets downloaded during CLEO Redux setup. You may opt out of installing Ultimate ASI Loader if you have other means of injecting ASI files into the game (i.e. an alternative loader).
+
+## Note on re3 or reVC
+
+{{#include ./re3-reVC-notes.md}}
 
 ## Uninstallation
 

docs/en/introduction.md

@@ -1,8 +1,6 @@
 # Introduction
-
-CLEO Redux is a scripting runtime for the GTA 3D era games. It is a proud member of the CLEO family and provides familiar experience to anyone who used original CLEO Library for the classic 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 about it.
+CLEO Redux is an [embeddable](https://re.cleo.li/docs/en/embedding.html) and [extensible](https://re.cleo.li/docs/en/using-sdk.html) JavaScript runtime capable of running user-made scripts in games and desktop applications. It is inspired by [CLEO Library](https://cleo.li/) and is [partially compatible](https://re.cleo.li/docs/en/relation-to-cleo-library.html) with its scripts and plugins. CLEO Redux, however, aims to provide a better developer and user experience and support games beyond just GTA 3D series.
 
 ## Supported Releases
 
@@ -11,6 +9,7 @@ Classic:
 - GTA III 1.0
 - GTA Vice City 1.0
 - GTA San Andreas 1.0 (only with [CLEO 4.4](https://github.com/cleolibrary/CLEO4))
+- GTA IV 1.2.0.43 (The Complete Edition, Steam)
 
 Remasters (The Trilogy):
 
@@ -22,8 +21,6 @@ Other:
 - reVC (see [details](./troubleshooting.md#cleo-does-not-work-with-re3-or-revc))
 - unknown host (see [details](./embedding.md))
 
-CLEO Redux only supports the PC version of each game.
-
 For the complete reference on supported features [refer to this page](https://github.com/cleolibrary/CLEO-Redux/wiki/Feature-Support-Matrix). Also there are known limitations [listed here](unsupported.md).
 
 ## License

docs/en/prerequisites.md

@@ -8,9 +8,10 @@ On the first run CLEO tries to download a definition file (see the table below)
 | ----------------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------ |
 | GTA III, re3                        | [gta3.json](https://github.com/sannybuilder/library/blob/master/gta3/gta3.json)                      | `0.218`                  |
 | GTA VC, reVC                        | [vc.json](https://github.com/sannybuilder/library/blob/master/vc/vc.json)                            | `0.220`                  |
-| GTA San Andreas (Classic) 1.0       | [sa.json](https://github.com/sannybuilder/library/blob/master/sa/sa.json)                            | `0.236`                  |
+| GTA San Andreas (Classic) 1.0       | [sa.json](https://github.com/sannybuilder/library/blob/master/sa/sa.json)                            | `0.245`                  |
+| GTA IV                              | [gta_iv.json](https://github.com/sannybuilder/library/blob/master/gta_iv/gta_iv.json)                | `0.34`                   |
 | GTA III: The Definitive Edition     | [gta3_unreal.json](https://github.com/sannybuilder/library/blob/master/gta3_unreal/gta3_unreal.json) | `0.213`                  |
 | Vice City: The Definitive Edition   | [vc_unreal.json](https://github.com/sannybuilder/library/blob/master/vc_unreal/vc_unreal.json)       | `0.215`                  |
 | San Andreas: The Definitive Edition | [sa_unreal.json](https://github.com/sannybuilder/library/blob/master/sa_unreal/sa_unreal.json)       | `0.220`                  |
-| Unknown (32-bit)                    | [unknown_x86.json](https://github.com/sannybuilder/library/blob/master/unknown_x86/unknown_x86.json) | `0.1`                    |
-| Unknown (64-bit)                    | [unknown_x64.json](https://github.com/sannybuilder/library/blob/master/unknown_x64/unknown_x64.json) | `0.1`                    |
+| Unknown (32-bit)                    | [unknown_x86.json](https://github.com/sannybuilder/library/blob/master/unknown_x86/unknown_x86.json) | `0.203`                  |
+| Unknown (64-bit)                    | [unknown_x64.json](https://github.com/sannybuilder/library/blob/master/unknown_x64/unknown_x64.json) | `0.207`                  |

docs/en/relation-to-cleo-library.md

@@ -1,6 +1,6 @@
 # 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 and JavaScript support.
+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 shared code base between all games and JavaScript support.
 
 At the moment CLEO Redux can not be considered as a complete 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.
 

docs/en/using-fxt.md

@@ -31,6 +31,9 @@ Text.PrintHelp('KEY1') // displays <TEXT1>
 
 You can find the commands available in each game in the Sanny Builder Library, e.g. [for San Andreas: DE](https://library.sannybuilder.com/#/sa_unreal/classes/Text).
 
+
+> CLEO Redux only supports texts encoded in UTF-8. It means that any non-standard encoding (e.g. for Russian localization by 1C) most likely will not work.
+
 ## FxtStore
 
 <iframe width="560" height="315" src="https://www.youtube.com/embed/FLyYyrGz1Xg" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
@@ -53,7 +56,7 @@ declare interface FxtStore {
 }
 ```
 
-Using `FxtStore` you can create unique keys and values in the script and put it in local FXT storage. Each script owns a private storage and keys from one script will not conflict with other scripts. Also keys defined in the FxtStore will shadow the same keys defined in static FXT files. Consider the example:
+Using `FxtStore` you can create unique keys and values in the script and put it in local FXT storage. Each script owns a private storage and keys from one script will not conflict with other scripts. Also keys defined in the FxtStore shadow the same keys defined in static FXT files. Consider the example:
 
 custom.fxt: