diff --git a/CHANGELOG.md b/CHANGELOG.md index 0ece210..c894813 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,10 @@ +### 0.8.5 - Jan 1, 2022 +- add support for [static FXT files](using-fxt.md#static-fxt-files) in `CLEO_TEXT` folder +- add support for [private FXT storage](using-fxt.md#fxtstore) in each JS script +- fixed an issue when [scripts permissions](README.md#permissions) were not validated for CLEO scripts +- fixed an issue when the game may crash on the script reload +- [custom CLEO opcodes](README.md#compatibility-with-the-trilogy-the-definitive-edition) (`0C00`-`0C07`) can now be used in the main.scm in San Andreas: DE + ### 0.8.4 - Dec 17, 2021 - for San Andreas: The Definitive Edition: diff --git a/README.md b/README.md index 847c0ca..0b8dd0b 100644 --- a/README.md +++ b/README.md @@ -37,6 +37,8 @@ Other: 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 + ### 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, or support for JavaScript code. @@ -121,7 +123,7 @@ At the moment CLEO Redux only supports San Andreas: The Definitive Edition `1.0. Use SA Mobile mode to compile CLEO scripts for San Andreas: The Definitive Edition. -For many people running their game with CLEO Redux installed results in the immediate crash. It happens if there is no write permissions in the current directory (`Win64`). To remediate this issue CLEO will fallback to using alternate path at `C:\Users\\AppData\Roaming\CLEO Redux`. `cleo_redux.log`and the `CLEO` directory can be found there. +For many people running their game with CLEO Redux installed results in the immediate crash. It happens if there is no write permissions in the current directory (`Win64`). To remediate this issue CLEO will fallback to using alternate path at `C:\Users\\AppData\Roaming\CLEO Redux`. `cleo_redux.log` and the `CLEO` directory can be found there. See also the [troubleshooting guide](TROUBLESHOOTING.md). ### Uninstallation diff --git a/using-fxt.md b/using-fxt.md new file mode 100644 index 0000000..777fea6 --- /dev/null +++ b/using-fxt.md @@ -0,0 +1,79 @@ +## Using FXT + +### Static FXT files + +CLEO Redux can load and serve static text content. Create a new file with the `.fxt` extension and put it in the `CLEO\CLEO_TEXT` folder. The file name can be any valid name. + +Each FXT file contains a list of the key-value entries in the following format: + +``` + + +... + +``` + +There should be a single space character between a key and a value. The key's maximum length is 7 characters. Try using unique keys that are unlikely to clash with other entries. The text length is unlimited, however each game may impose its own limitations. + +CLEO loads FXT files on startup and merges their content in a single dictionary. It also monitors the files and reloads them if any change is made. + +You can also find an editor for FXT files on the cleo.li website: https://cleo.li/download.html + +To display the custom content in game, use the `Text` class. The key defined in the FXT file is usually the first argument to Text commands, e.g. + +``` +Text.PrintHelp('KEY1') // will display +``` + +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 + + +### FxtStore + +CLEO Redux provides an interface for manipulating custom text directly in JavaScript code. There is a static variable, named `FxtStore` with the following interface: + +```ts +declare interface FxtStore { + /** + * Inserts new text content in the script's fxt storage overwriting the previous content and shadowing static fxt with the same key + * @param key GXT key that can be used in text commands (7 characters max) + * @param value text content + */ + insert(key: string, value: string): void; + /** + * Removes the text content associated with the key in the local fxt storage + * @param key GXT key + */ + delete(key: string): void; +} +``` + +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: + +custom.fxt: +``` +MY_KEY Text from FXT file +``` + +custom.js: + +```js +Text.PrintHelp('MY_KEY') // this displays "Text from FXT file" +FxtStore.insert('MY_KEY', 'Text from script'); +Text.PrintHelp('MY_KEY') // this displays "Text from script" +FxtStore.delete('MY_KEY') +Text.PrintHelp('MY_KEY') // this displays "Text from FXT file" again +``` + +A private FXT storage is not supported in San Andreas: The Definitive Edition. Each script modifies one single shared FXT storage (which is different from the FXT files anyway, so temporary shadowing of the static content is still possible). + +Custom text can be constructed dynamically, e.g.: + +```js +while(true) { + wait(0); + FxtStore.insert('TIME', 'Timestamp: ' + Date.now()); + Text.PrintHelp('TIME') // this displays "Timestamp: " and the updated timestamp value +} +``` + diff --git a/website/index.html b/website/index.html index 2cfcb45..18a5b0c 100644 --- a/website/index.html +++ b/website/index.html @@ -128,7 +128,7 @@

href="https://github.com/cleolibrary/CLEO-Redux/releases/latest" >Download - v0.8.4 | Dec 17, 2021 + v0.8.5 | Jan 01, 2022