diff --git a/docs/zengin/music.pl.md b/docs/zengin/music.pl.md index 95e4c6fde0..f5feb18ae8 100644 --- a/docs/zengin/music.pl.md +++ b/docs/zengin/music.pl.md @@ -3,9 +3,9 @@ title: Muzyka --- # Muzyka -Zengin używa [DirectMusic](https://en.m.wikipedia.org/wiki/DirectMusic) do odtwarzania ścieżki dźwiękowej w grze. Aby edytować pliki muzyczne Gothica, potrzebujesz [Direct Music Producer](https://en.m.wikipedia.org/wiki/DirectMusic), programu wydanego przez Microsoft i dołączanego do starszych zestawów SDK DirectX. +Zengin używa [DirectMusic](https://en.m.wikipedia.org/wiki/DirectMusic) do odtwarzania ścieżki dźwiękowej w grze. Aby edytować pliki muzyczne Gothica, potrzebujesz programu [Direct Music Producer](https://en.m.wikipedia.org/wiki/DirectMusic), który został wydany przez Microsoft i był dostarczany do starszych zestawów SDK DirectX. -!!! Warning +!!! Warning "Ostrzeżenie" Pliki muzyczne nie mogą być spakowane do archiwów `.vdf` lub `.mod`, wszystkie takie pliki muszą znajdować się w katalogu `/_work/Data/Music`. ## Formaty plików @@ -14,7 +14,7 @@ Katalog `Music` zawiera następujące typy plików: - `.dls` - Plik formatu [Downloadable Sound](https://en.wikipedia.org/wiki/DLS_format). Jest bazą dla wszystkich innych plików. Zawiera: - Kolekcje wirtualnych instrumentów muzycznych. - - Pliki `.wav` urzywane przez instrumenty. + - Pliki `.wav` używane przez instrumenty. - `.sty` - Plik stylu. Zawiera: - Zespoły (Bands) - ustawienia instrumentów wirtualnych z `.dls`. diff --git a/docs/zengin/scripts/extenders/ikarus/floats.md b/docs/zengin/scripts/extenders/ikarus/floats.md new file mode 100644 index 0000000000..343a5dc451 --- /dev/null +++ b/docs/zengin/scripts/extenders/ikarus/floats.md @@ -0,0 +1,360 @@ +# Floats +This part of ikarus implements support for 32 bit IEEE 754 floats in Daedalus. The script was originally created to edit `zFLOAT` and `zREAL` variables, but can also be used to arthmetic operations on real float values (not to be confused with Daedalus floats). + +## Initialization +The best way to initialize all Ikarus functions is to call `MEM_InitAll()` in the `Init_Global()` initialization function. +!!! warning + If you want to use Ikarus in Gothic 1, it is best to define your own `Init_Global()` function and call it from every world initialization function. + +```dae +MEM_InitAll(); +``` + +## Implementation +[:material-github: float.d on GitHub](https://github.com/Lehona/Ikarus/blob/master/float.d) + +## Functions +!!! Danger + Ikarus floats are saved as int but it doesn't mean that you can use arthmetic operators on them. All operations on floats must be done with functions listed below. + +### `mkf` +(make float) Converts the input integer x to a float value. +```dae +func int mkf(var int x) +``` +**Parameters** + +- `#!dae var int x` + The input integer + +**Return value** + +The function returns the float representation of the input integer x. + +### `truncf` +(truncate float) Truncates the decimal part of the input float x. +```dae +func int truncf(var int x) +``` +**Parameters** + +- `#!dae var int x` + The input float + +**Return value** + +The function returns the integer part of the input float x by discarding the decimal part. + +### `roundf` +(round float) Rounds the input float x to the nearest integer value. +```dae +func int roundf(var int x) +``` +**Parameters** + +- `#!dae var int x` + The input float + +**Return value** + +The function returns the nearest integer value to the input float x. If the decimal part is exactly halfway between two integers, the function rounds to the nearest even integer. + +### `addf` +(add floats) Adds two ikarus floats together. +```dae +func int addf(var int x, var int y) +``` +**Parameters** + +- `#!dae var int x` + The first float +- `#!dae var int y` + The second float + +**Return value** + +The function returns the sum of the input floats `x` and `y`. (x + y) + +### `subf` +(subtract floats) Subtracts the second float from the first float. +```dae +func int subf(var int x, var int y) +``` +**Parameters** + +- `#!dae var int x` + The first float +- `#!dae var int y` + The second float + +**Return value** + +The function returns the difference between the first float `x` and the second float `y`. (x - y) + +### `negf` +(negate float) Negates the input float. +```dae +func int negf(var int x) +``` +**Parameters** + +- `#!dae var int x` + The input float + +**Return value** + +The function returns the negation of the input float `x`. + +### `mulf` +(multiply floats) Multiplies two ikarus floats. +```dae +func int mulf(var int x, var int y) +``` +**Parameters** + +- `#!dae var int x` + The first float +- `#!dae var int y` + The second float + +**Return value** + +The function returns the product of multiplying the input floats x and y. (x * y) + +### `divf` +(divide floats) Divides two ikarus floats. +```dae +func int divf(var int x, var int y) +``` +**Parameters** + +- `#!dae var int x` + The dividend float +- `#!dae var int y` + The divisor float + +**Return value** + +The function returns the quotient of dividing the input float x by y. (x / y) + +### `invf` +(inverse float) Computes the inverse of the input float. +```dae +func int invf(var int x) +``` +**Parameters** + +- `#!dae var int x` + The input float + +**Return value** + +The function returns the inverse of the `x`, calculated as `1/x`. + +### `gf` +(greater) Checks if the first float is greater than the second float. +```dae +func int gf(var int x, var int y) +``` +**Parameters** + +- `#!dae var int x` + The first float +- `#!dae var int y` + The second float + + + +**Return value** + +The function returns `TRUE` if `x` is greater than `y`, `FALSE` is returned otherwise. + +### `gef` +(greater or equal) Checks if the first float is greater than or equal to the second float. +```dae +func int gef(var int x, var int y) +``` +**Parameters** + +- `#!dae var int x` + The first float +- `#!dae var int y` + The second float + +**Return value** + +The function returns `TRUE` if `x` is greater than or equal to `y`, `FALSE` is returned otherwise. + +### `lf` +(lower) Checks if the first float is less than the second float. +```dae +func int lf(var int x, var int y) +``` +**Parameters** + +- `#!dae var int x` + The first float +- `#!dae var int y` + The second float + +**Return value** + +The function returns `TRUE` if `x` is less than `y`, `FALSE` is returned otherwise. + +### `lef` +(lower or equal) Checks if the first float is less than or equal to the second float. +```dae +func int lef(var int x, var int y) +``` +**Parameters** + +- `#!dae var int x` + The first float +- `#!dae var int y` + The second float + +**Return value** + +The function returns `TRUE` if `x` is less than or equal to `y`, `FALSE` is returned otherwise. + +### `sqrf` +(square float) Calculates the square of the float. +```dae +func int sqrf(var int x) +``` +**Parameters** + +- `#!dae var int x` + The input float + +**Return value** + +The function returns the square of the input float `x`, computed as `x * x`. + +### `sqrtf` +(square root float) Calculates the square root of the float. +```dae +func int sqrtf(var int x) +``` +**Parameters** + +- `#!dae var int x` + The input float + +**Return value** + +The function returns the square root of the input float `x`. + +### `sqrtf_approx` +Calculates the approximate square root of a float. +```dae +func int sqrtf_approx(var int f) +``` +**Parameters** + +- `#!dae var int f` + The input float + +**Return value** + +The function returns the approximate square root of the input float as an ikarus float. + +### `absf` +(absolute value) Computes the absolute value of a float. +```dae +func int absf(var int x) +``` +**Parameters** + +- `#!dae var int x` + The input float + +**Return value** + +The function returns the absolute value of the input float `x`, which is the value without the negative sign (if present). + +### `fracf` +(fraction) Computes the fraction of two integers p and q. +```dae +func int fracf(var int p, var int q) +``` +**Parameters** + +- `#!dae var int p` + Numerator +- `#!dae var int q` + Denominator + +**Return value** + +The function returns the fraction of `p` divided by `q` as an ikarus float. + +### `castFromIntf` +Converts an ikarus float to a Daedalus float. +```dae +func float castFromIntf(var int f) +``` +**Parameters** + +- `#!dae var int f` + Ikarus float + +**Return Value** + +The function returns the value `f` as a Daedalus float. + +### `castToIntf` +Converts a Daedalus float to an ikarus float. +```dae +func int castToIntf(var float f) +``` +**Parameters** + +- `#!dae var float f` + Daedalus float + +**Return Value** + +The function returns the value `f` as an ikarus float. + +### `toStringf` +Converts a float value to its string representation. +```dae +func string toStringf(var int x) +``` +**Parameters** + +- `#!dae var int x` + Input float value + +**Return value** + +The function returns a string representation of the input float value. + +### `printf` +(print float) Prints the float on screen using `Print()`. +```dae +func void printf(var int x) +``` +**Parameters** + +- `#!dae var int x` + The printed float + +## Examples + +### Simple operations +```dae +var int float1 = mkf(5); // Create an Ikarus float with value 5 +var int float2 = mkf(2); // Create an Ikarus float with value 2 + +var int addResult = addf(float1, float2); // Add float1 and float2 +var int subResult = subf(float1, float2); // Subtract float2 from float1 +var int mulResult = mulf(float1, float2); // Multiply float1 by float2 +var int divResult = divf(float1, float2); // Divide float1 by float2 + +printf(addResult); // Output: 7 +printf(subResult); // Output: 3 +printf(mulResult); // Output: 10 +printf(divResult); // Output: 2.5 +``` \ No newline at end of file diff --git a/docs/zengin/scripts/extenders/ikarus/functions/ini_access.pl.md b/docs/zengin/scripts/extenders/ikarus/functions/ini_access.pl.md index c3ec2b5138..6adf7957c1 100644 --- a/docs/zengin/scripts/extenders/ikarus/functions/ini_access.pl.md +++ b/docs/zengin/scripts/extenders/ikarus/functions/ini_access.pl.md @@ -29,7 +29,7 @@ func string MEM_GetGothOpt(var string sectionname, var string optionname) **Zwracana wartość** -Funkcja zwraca wartość opcji w postaci łańcucha znaków, albo pustą zmienną, gdy opcja nie istnieje w danej sekcji. +Funkcja zwraca wartość opcji w postaci ciągu znaków, albo pustą zmienną, gdy opcja nie istnieje w danej sekcji. ### `MEM_GetModOpt` Przeszukuje ini załadowanej modyfikacji w poszukiwaniu opcji. @@ -45,7 +45,7 @@ func void MEM_GetModOpt(var string sectionname, var string optionname) **Zwracana wartość** -Funkcja zwraca wartość opcji w postaci łańcucha znaków, albo pustą zmienną, gdy opcja nie istnieje w danej sekcji. +Funkcja zwraca wartość opcji w postaci ciągu znaków, albo pustą zmienną, gdy opcja nie istnieje w danej sekcji. ### `MEM_GothOptSectionExists` Sprawdza, czy dana sekcja istnieje w `Gothic.ini` diff --git a/docs/zengin/scripts/extenders/ikarus/functions/mem_access.md b/docs/zengin/scripts/extenders/ikarus/functions/mem_access.md index 07e248c476..81f4e34065 100644 --- a/docs/zengin/scripts/extenders/ikarus/functions/mem_access.md +++ b/docs/zengin/scripts/extenders/ikarus/functions/mem_access.md @@ -82,7 +82,7 @@ The function returns integer value from the array if the address is correct. ### `MEM_ReadStringArray` !!! Info - `MEM_ReadStringArray` has been already moved to the LeGo PermMem package. + `MEM_ReadStringArray` has been already moved to the LeGo [PermMem](../../lego/tools/permmem.md#mem_readstringarray) package. ### `MEM_ReadByteArray` Reads byte from the array at the `arrayAddress`. diff --git a/docs/zengin/scripts/extenders/ikarus/functions/preamble.md b/docs/zengin/scripts/extenders/ikarus/functions/preamble.md new file mode 100644 index 0000000000..12ace22c36 --- /dev/null +++ b/docs/zengin/scripts/extenders/ikarus/functions/preamble.md @@ -0,0 +1,128 @@ +# Preamble +The preamble is a bunch of functions related with debug and some stuff, that doesn't fit to other sections. + +## Initialization +The best way to initialize all Ikarus functions is to call `MEM_InitAll()` in the `Init_Global()` initialization function. +!!! warning + If you want to use Ikarus in Gothic 1, it is best to define your own `Init_Global()` function and call it from every world initialization function. + +```dae +MEM_InitAll(); +``` + +## Implementation +[:material-github: Ikarus.d on GitHub](https://github.com/Lehona/Ikarus/blob/master/Ikarus.d#L137) + +## Functions + +### `MEM_CheckVersion` +Checks if the version of Ikarus is the specified version or newer. +```dae +func int MEM_CheckVersion(var int base, var int major, var int minor) +``` +**Parameters**: + +- `#!dae var int base` + Base version number +- `#!dae var int major` + Major revision number +- `#!dae var int minor` + Minor revision number + +**Return value** + +The function returns `TRUE` if the version of Ikarus is the specified version or newer, `FALSE` is returned otherwise. + +### `MEM_SendToSpy` +Sends a message to the debugging console. +```dae +func void MEM_SendToSpy(var int errorType, var string text) +``` +**Parameters** + +- `#!dae var int errorType` + Type of error (e.g., `zERR_TYPE_FAULT`, `zERR_TYPE_WARN`, `zERR_TYPE_INFO`) +- `#!dae var string text` + The message to be sent. + +### `MEM_ErrorBox` +Displays an error message in a message box. +```dae +func void MEM_ErrorBox(var string text) +``` +**Parameters** + +- `#!dae var string text` + The error message to be displayed. + +### `MEM_PrintStackTrace` +Prints the stack trace. +```dae +func void MEM_PrintStackTrace() +``` + +### `MEM_Error` +Handles a fatal error, displaying the error message and printing the stack trace. +```dae +func void MEM_Error(var string error) +``` +**Parameters** + +- `#!dae var string error` + The error message. + +### `MEM_Warn` +Handles a warning, displaying the warning message and printing the stack trace. +```dae +func void MEM_Warn(var string warn) +``` +**Parameters** + +- `#!dae var string warn` + The warning message. + +### `MEM_Info` +Handles an information message, printing it if enabled in the settings. +```dae +func void MEM_Info(var string info) +``` +**Parameters** + +- `#!dae var string info` + The information message. + +### `MEM_AssertFail` +Handles an assertion failure, reporting the error message as a fatal error. +```dae +func void MEM_AssertFail(var string assertFailText) +``` +**Parameters** + +- `#!dae var string assertFailText` + The assertion failure message. + +### `MEM_Debug` +Sends a debug message to the zSpy or on screen or displays an error box basing on `zERR_DEBUG_TOSPY`, `zERR_DEBUG_TOSCREEN` and `zERR_DEBUG_ERRORBOX` constants (`TRUE` - display). +```dae +func void MEM_Debug(var string message) +``` +**Parameters** + +- `#!dae var string message` + The debug message. + +### `MEMINT_SwitchG1G2` +Switches between values based on the game version. Used mainly to change addresses in multi-platform hooks or function calls. +```dae +func int MEMINT_SwitchG1G2(var int g1Val, var int g2Val) +``` +**Parameters** + +- `#!dae var int g1Val` + The value to return if the game version is Gothic 1. +- `#!dae var int g2Val` + The value to return if the game version is Gothic 2. + +**Return value** + +The function returns an appropriate value based on the game version. \ No newline at end of file diff --git a/docs/zengin/scripts/extenders/ikarus/functions/string.md b/docs/zengin/scripts/extenders/ikarus/functions/string.md new file mode 100644 index 0000000000..9cfb647bfb --- /dev/null +++ b/docs/zengin/scripts/extenders/ikarus/functions/string.md @@ -0,0 +1,291 @@ +# String operations +Collection of Ikarus functions to manipulate and format strings. + +## Initialization +The best way to initialize all Ikarus functions is to call `MEM_InitAll()` in the `Init_Global()` initialization function. +!!! warning + If you want to use Ikarus in Gothic 1, it is best to define your own `Init_Global()` function and call it from every world initialization function. + +```dae +MEM_InitAll(); +``` + +## Implementation +[:material-github: Ikarus.d on GitHub](https://github.com/Lehona/Ikarus/blob/master/Ikarus.d#L2341) + +## Functions + +### `STR_GetCharAt` +Returns the ASCII value of a character at a specific position in a string. +```dae +func int STR_GetCharAt (var string str, var int pos) +``` +**Parameters**: + +- `#!dae var string str` + The input string +- `#!dae var int pos` + The position of the character + +**Return value** + +The function returns the ASCII value of the character at the specified position. + +### `STR_Len` +Returns the length of a string. +```dae +func int STR_Len (var string str) +``` +**Parameters**: + +- `#!dae var string str` + The input string + +**Return value** + +The function returns the length of the string in characters. + +### `STR_toChar` +Converts a string to a pointer to its character array. +```dae +func int STR_toChar (var string str) +``` +**Parameters**: + +- `#!dae var string str` + The input string + +**Return value** + +The function returns a pointer to the character array representing the input string `str` + +### `STR_FromChar` +Converts a character array to a string. +```dae +func string STR_FromChar(var int char) +``` +**Parameters**: + +- `#!dae var int char` + Pointer to the character array + +**Return value** + +The function returns a string representation of the character array. + +### `STR_SubStr` +Extracts a substring from a given string. +```dae +func string STR_SubStr (var string str, var int start, var int count) +``` +**Parameters**: + +- `#!dae var string str` + The input string +- `#!dae var int start` + The starting position of the substring +- `#!dae var int count` + The length of the substring + +**Return value** + +The function returns a substring, if the starting position is invalid an empty string is returned. + + +### `STR_Prefix` +Extracts a prefix of a given string, similar to [`STR_SubStr`](#str_substr), but with the starting position set to the first character of the string. +```dae +func string STR_Prefix (var string str, var int len) +``` +**Parameters**: + +- `#!dae var string str` + The input string +- `#!dae var int count` + The length of the prefix + +**Return value** + +The function returns a prefix of the input string with the specified length. + +### `STR_Compare` +Compares two strings lexicographically and returns a result indicating their relative order. +```dae +func int STR_Compare(var string str1, var string str2) +``` +**Parameters** + +- `#!dae var string str1` + The first string to compare +- `#!dae var string str2` + The second string to compare + +**Return Value** + +The function returns an integer value representing the result of the comparison: + +- `STR_GREATER` (1): If `str1` comes lexicographically after `str2`. +- `STR_EQUAL` (0): If `str1` is lexicographically equal to `str2`. +- `STR_SMALLER` (-1): If `str1` comes lexicographically before `str2`. + +??? abstract "Examples" + The comparison is based on lexicographic order, which is the order of characters as they appear in the ASCII table. Uppercase letters come before lowercase letters. + + ```dae + int result1 = STR_Compare("A", "B"); + // The 'result1' variable now contains STR_SMALLER + + int result2 = STR_Compare("ABC", "ABC"); + // The 'result2' variable now contains STR_EQUAL + + int result3 = STR_Compare("AA", "A"); + // The 'result3' variable now contains STR_GREATER + + int result4 = STR_Compare("BA", "BB"); + // The 'result4' variable now contains STR_SMALLER + + int result5 = STR_Compare("B", "a"); + // The 'result5' variable now contains STR_SMALLER + + int result6 = STR_Compare("A", ""); + // The 'result6' variable now contains STR_GREATER + ``` + +### `STR_ToInt` +Converts a string to an integer. +```dae +func int STR_ToInt (var string str) +``` +**Parameters**: + +- `#!dae var string str` + The input string + +**Return Value** + +The function returns an integer value of the string, if a string is invalid (doesn't contain an integer) zero is returned. + +### `STR_IndexOf` +Searches for a substring `tok` within a given string and returns the index of the first occurrence of `tok`, taking into account upper and lower case letters. +```dae +func int STR_IndexOf(var string str, var string tok) +``` +**Parameters** + +- `#!dae var string str` + The string in which to search for `tok`. +- `#!dae var string tok` + The substring to search for within `str`. + +**Return Value** + +The function returns the index at which the first occurrence of `tok` begins within `str`. If `tok` is not found in `str`, the function returns -1. + +??? abstract "Examples" + + ```dae + int index1 = STR_IndexOf("Hello World!", "Hell"); + // The 'index1' variable now contains 0 + + int index2 = STR_IndexOf("Hello World!", "World"); + // The 'index2' variable now contains 6 + + int index3 = STR_IndexOf("Hello World!", "Cake"); + // The 'index3' variable now contains -1 + + int index4 = STR_IndexOf("Hello World!", ""); + // The 'index4' variable now contains 0 + + int index5 = STR_IndexOf("Hello", "Hello World!"); + // The 'index5' variable now contains -1 + + int index6 = STR_IndexOf("hello Hell!", "Hell"); + // The 'index6' variable now contains 6 + + int index7 = STR_IndexOf("", ""); + // The 'index7' variable now contains 0 + ``` + +### `STR_SplitCount` +Counts the number of parts a string splits into when using a specified separator. +```dae +func int STR_SplitCount(var string str, var string seperator) +``` +**Parameters** + +- `#!dae var string str` + The input string to be split. +- `#!dae var string separator` + The separator character or string used to split the input string. + +**Return Value** + +The function returns a number of parts the input string splits into when using the specified separator. + +??? abstract "Example" + + ```dae + string inputStr = "This is a sentence."; + int count = STR_SplitCount(inputStr, " "); + // The 'count' variable now contains 4 + ``` + +### `STR_Split` +Splits a string into multiple substrings based on a specified separator and returns the substring at a specified offset. +```dae +func string STR_Split(var string str, var string separator, var int offset) +``` + +**Parameters** + +- `#!dae var string str ` + The input string to be split. +- `#!dae var string separator` + The separator character or string used to split the input string. +- `#!dae var int offset` + The index of the substring to be returned after splitting. The index is zero-based. + +**Return Value** + +The function returns a substring at the specified offset after splitting the input string. If the offset is greater than or equal to the number of parts generated by splitting, an empty string is returned. + +??? abstract "Example" + + ```dae + func void foo() { + string inputStr = "This is a sentence."; + string tok1 = STR_Split(inputStr, " ", 0); // This + string tok2 = STR_Split(inputStr, " ", 1); // is + string tok3 = STR_Split(inputStr, " ", 2); // a + string tok4 = STR_Split(inputStr, " ", 3); // sentence + }; + ``` + At the end of the function, `tok1` contains "This", `tok2` contains "is", `tok3` contains "a", and `tok4` contains "sentence.". + +### `STR_Upper` +Converts a string to uppercase. +```dae +func string STR_Upper(var string str) +``` +**Parameters**: + +- `#!dae var string str` + The input string + +**Return Value** + +The function returns a copy of `str` with all uppercase letters converted to their corresponding uppercase letters. + +### `STR_Lower` +Converts a string to lowercase. +```dae +func string STR_Lower(var string str) +``` +**Parameters**: + +- `#!dae var string str` + The input string + +**Return Value** + +The function returns a copy of `str` with all lowercase letters converted to their corresponding uppercase letters. diff --git a/docs/zengin/scripts/extenders/lego/applications/bars.md b/docs/zengin/scripts/extenders/lego/applications/bars.md index 950b7499a1..40c4e74095 100644 --- a/docs/zengin/scripts/extenders/lego/applications/bars.md +++ b/docs/zengin/scripts/extenders/lego/applications/bars.md @@ -3,7 +3,7 @@ This package makes it very easy to add new bars, for e.g. stamina. ## Dependencies -- PermMem +- [PermMem](../tools/permmem.md) - View ## Initialization diff --git a/docs/zengin/scripts/extenders/lego/applications/bars.pl.md b/docs/zengin/scripts/extenders/lego/applications/bars.pl.md index d8bd8df4ef..a281909300 100644 --- a/docs/zengin/scripts/extenders/lego/applications/bars.pl.md +++ b/docs/zengin/scripts/extenders/lego/applications/bars.pl.md @@ -6,7 +6,7 @@ Ten pakiet bardzo ułatwia dodawanie nowych pasków, dla wyświetlania np. wytrz ## Zależności -- PermMem +- [PermMem](../tools/permmem.md) - View ## Inicjalizacja diff --git a/docs/zengin/scripts/extenders/lego/applications/buffs.md b/docs/zengin/scripts/extenders/lego/applications/buffs.md index ff46616b77..70acef0c05 100644 --- a/docs/zengin/scripts/extenders/lego/applications/buffs.md +++ b/docs/zengin/scripts/extenders/lego/applications/buffs.md @@ -4,7 +4,7 @@ Status effects on the hero are displayed graphically in a bar. ## Dependencies -- PermMem +- [PermMem](../tools/permmem.md) - [FrameFunctions](../tools/frame_functions.md) ## Initialization diff --git a/docs/zengin/scripts/extenders/lego/applications/buttons.md b/docs/zengin/scripts/extenders/lego/applications/buttons.md index 78893bea70..5fe44ea615 100644 --- a/docs/zengin/scripts/extenders/lego/applications/buttons.md +++ b/docs/zengin/scripts/extenders/lego/applications/buttons.md @@ -3,7 +3,7 @@ This package extends the handling of the mouse and allows creating rectangular b ## Dependencies -- PermMem +- [PermMem](../tools/permmem.md) - View ## Initialization diff --git a/docs/zengin/scripts/extenders/lego/applications/console_commands.md b/docs/zengin/scripts/extenders/lego/applications/console_commands.md index a1c590d60b..40e8fd8dc2 100644 --- a/docs/zengin/scripts/extenders/lego/applications/console_commands.md +++ b/docs/zengin/scripts/extenders/lego/applications/console_commands.md @@ -3,7 +3,7 @@ This package allows you to create new console commands. ## Dependencies -- PermMem +- [PermMem](../tools/permmem.md) - [HookEngine](../tools/hook_engine.md) ## Initialization diff --git a/docs/zengin/scripts/extenders/lego/applications/console_commands.pl.md b/docs/zengin/scripts/extenders/lego/applications/console_commands.pl.md index 520c77d50a..56db711d51 100644 --- a/docs/zengin/scripts/extenders/lego/applications/console_commands.pl.md +++ b/docs/zengin/scripts/extenders/lego/applications/console_commands.pl.md @@ -6,7 +6,7 @@ Ten Pakiet pozwala na tworzenie nowych poleceń konsoli dostępnej po naciśnię ## Zależności -- PermMem +- [PermMem](../tools/permmem.md) - [HookEngine](../tools/hook_engine.md) ## Inicjalizacja diff --git a/docs/zengin/scripts/extenders/lego/applications/gamestate.md b/docs/zengin/scripts/extenders/lego/applications/gamestate.md index 8875b5bc5d..9b7fc50053 100644 --- a/docs/zengin/scripts/extenders/lego/applications/gamestate.md +++ b/docs/zengin/scripts/extenders/lego/applications/gamestate.md @@ -65,8 +65,6 @@ func void Init_Global() }; ``` -This might be useful when working with PermMem, where PermMem objects do not need to be recreated after the game loads. - It can also be done like that: ```dae func void Init_Global() diff --git a/docs/zengin/scripts/extenders/lego/applications/render.md b/docs/zengin/scripts/extenders/lego/applications/render.md index c0b8eba391..728930519a 100644 --- a/docs/zengin/scripts/extenders/lego/applications/render.md +++ b/docs/zengin/scripts/extenders/lego/applications/render.md @@ -4,7 +4,7 @@ With this package items can be rendered on the screen. Since items are rendered - List - View -- PermMem +- [PermMem](../tools/permmem.md) ## Initialization Initialize with `LeGo_Render` flag. diff --git a/docs/zengin/scripts/extenders/lego/applications/saves.md b/docs/zengin/scripts/extenders/lego/applications/saves.md index 2c3e245fe4..26f220aa45 100644 --- a/docs/zengin/scripts/extenders/lego/applications/saves.md +++ b/docs/zengin/scripts/extenders/lego/applications/saves.md @@ -1,5 +1,5 @@ # Saves -Offers an open file stream that can read/write variables on save/load. It is used by PermMem, so you don't need to address it manually anymore. +Offers an open file stream that can read/write variables on save/load. It is used by [PermMem](../tools/permmem.md), so you don't need to address it manually anymore. ## Dependencies diff --git a/docs/zengin/scripts/extenders/lego/applications/trialoge.pl.md b/docs/zengin/scripts/extenders/lego/applications/trialoge.pl.md index 1d2f4f56fe..d93b1ff5a3 100644 --- a/docs/zengin/scripts/extenders/lego/applications/trialoge.pl.md +++ b/docs/zengin/scripts/extenders/lego/applications/trialoge.pl.md @@ -118,7 +118,7 @@ func void TRIA_Cam(var string evt) **Parametry** - `#!dae var string evt` - Nazwa ruchu kamery w Spacerze. Jeśli zostanie przekazany pusty łańcuch znaków, nastąpi przerwanie ruchu kamery. + Nazwa ruchu kamery w Spacerze. Jeśli zostanie przekazany pusty ciąg znaków, nastąpi przerwanie ruchu kamery. ### `TRIA_Finish` Kończy trwający trialog. Musi być zawsze wywoływana na końcu, w przeciwnym razie dalsze trialogi nie będą mogły zostać rozpoczęte. diff --git a/docs/zengin/scripts/extenders/lego/tools/ai_function.md b/docs/zengin/scripts/extenders/lego/tools/ai_function.md index 5a4e3c8940..f0554acd8b 100644 --- a/docs/zengin/scripts/extenders/lego/tools/ai_function.md +++ b/docs/zengin/scripts/extenders/lego/tools/ai_function.md @@ -1,8 +1,8 @@ --- title: AI_Function --- -# AI Function -This package allows time-delayed functions to be called by enqueuing the functions in the AI queue of the NPC in question. This can be very useful e.g. cutscenes. +# AI_Function +This package allows time-delayed functions to be called by enqueuing the functions in the AI queue of the NPC in question. This can be very useful in writing cutscenes on engine or implementing new routines. ## Dependencies diff --git a/docs/zengin/scripts/extenders/lego/tools/ai_function.pl.md b/docs/zengin/scripts/extenders/lego/tools/ai_function.pl.md index 03be61ea1f..54bbfbd88b 100644 --- a/docs/zengin/scripts/extenders/lego/tools/ai_function.pl.md +++ b/docs/zengin/scripts/extenders/lego/tools/ai_function.pl.md @@ -1,8 +1,8 @@ --- title: Funkcje AI --- -# AI Function - Funkcje AI -Ten pakiet umożliwia wywoływanie funkcji opóźnionych w czasie poprzez kolejkowanie ich w kolejce AI danego NPC. Może to być bardzo przydatne np. do cutscenek. +# AI_Function - Funkcje AI +Ten pakiet umożliwia wywoływanie funkcji opóźnionych w czasie poprzez kolejkowanie ich w kolejce AI danego NPC. Może to być bardzo przydatne przy pisaniu przerywników filmowych na silniku lub implementacji nowych rutyn. ## Zależności diff --git a/docs/zengin/scripts/extenders/lego/tools/binary_machines.md b/docs/zengin/scripts/extenders/lego/tools/binary_machines.md index e438c1332d..c3d18d421a 100644 --- a/docs/zengin/scripts/extenders/lego/tools/binary_machines.md +++ b/docs/zengin/scripts/extenders/lego/tools/binary_machines.md @@ -22,6 +22,10 @@ func int BW_NewFile(var string file) - `#!dae var string file` Name of created file +**Return value** + +The function returns `TRUE` if the file is successfully created and initialized, `FALSE`is returned otherwise. + ### `BW_Close` Closes the current write stream. ```dae @@ -48,7 +52,7 @@ func void BW_Int(var int data) **Parameters** - `#!dae var int data` - Int value to wirte + Integer value to write ### `BW_Char` Writes the first character from the `data` to the stream. Same as `BW(Str_GetCharAt(data, 0), 1)`. @@ -120,6 +124,11 @@ func int BR_OpenFile(var string file) - `#!dae var string file` File to be opened +**Return value** + +The function returns `TRUE` if the file is successfully opened and initialized, `FALSE`is returned otherwise. + + ### `BR_Close` Closes the current read stream. ```dae @@ -156,7 +165,7 @@ func string BR_Char() ``` **Return value** -The function returns the read character. +The function returns the read character as a `string`. ### `BR_String` Reads a string terminated by `\0` from the stream. @@ -213,6 +222,89 @@ func string BR_Text(var int length) The function returns the read string. +### `BR_NextLine` +Changes the read position to the next paragraph, created with [`BW_NextLine`](#bw_nextline) +```dae +func void BR_NextLine() +``` + +## Enginecalls + +### `WIN_GetLastError` +Call of a Win32 API [`GetLastError` function](https://learn.microsoft.com/en-us/windows/win32/api/errhandlingapi/nf-errhandlingapi-getlasterror) +```dae +func int WIN_GetLastError() +``` +**Return value** + +The function returns calling thread's last-error code. + +### `WIN_CreateFile` +Call of a Win32 API [`CreateFileA` function](https://learn.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-createfilea) +```dae +func int WIN_CreateFile(var string lpFileName,var int dwDesiredAccess,var int dwShareMode,var int lpSecurityAttributes,var int dwCreationDisposition,var int dwFlagsAndAttributes,var int hTemplateFile) +``` +**Parameters** + +Full description of parameters can be found [here](https://learn.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-createfilea#parameters) + +**Return value** + +Information about return value can be found [here](https://learn.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-createfilea#return-value) + +### `WIN_WriteFile` +Call of a Win32 API [`WriteFile` function](https://learn.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-writefile) +```dae +func void WIN_WriteFile(var int hFile,var int lpBuffer,var int nNumberOfBytesToWrite,var int lpNumberOfBytesWritten,var int lpOverlapped) +``` +**Parameters** + +Full description of parameters can be found [here](https://learn.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-writefile#parameters) + +### `WIN_ReadFile` +Call of a Win32 API [`ReadFile` function](https://learn.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-readfile) +```dae +func void WIN_ReadFile(var int hFile,var int lpBuffer,var int nNumberOfBytesToRead,var int lpNumberOfBytesRead,var int lpOverlapped) +``` +**Parameters** + +Full description of parameters can be found [here](https://learn.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-readfile#parameters) + +### `WIN_CloseHandle` +Call of a Win32 API [`CloseHandle` function](https://learn.microsoft.com/en-us/windows/win32/api/handleapi/nf-handleapi-closehandle) +```dae +func void WIN_CloseHandle(var int hObject) +``` +**Parameters** + +Full description of parameters can be found [here](https://learn.microsoft.com/en-us/windows/win32/api/handleapi/nf-handleapi-closehandle#parameters) + +### `WIN_GetFileSize` +Call of a Win32 API [`GetFileSize` function](https://learn.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-getfilesize) +```dae +func int WIN_GetFileSize(var int hFile,var int lpFileSizeHigh) +``` +**Parameters** + +Full description of parameters can be found [here](https://learn.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-getfilesize#parameters) + +**Return value** + +Information about return value can be found [here](https://learn.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-getfilesize#return-value) + +### Constants +In addition there are some constants defined for use with the specific engine calls. +```dae +const int CREATE_ALWAYS = 2; +const int OPEN_EXISTING = 3; +const int GENERIC_ALL = 1073741824; +const int GENERIC_READ = -2147483648; +const int FILE_SHARE_READ = 1; +const int FILE_SHARE_WRITE = 2; +const int FILE_SHARE_DELETE = 4; +const int FILE_ATTRIBUTE_NORMAL = 128; +``` + ## Examples ### Save and load variables diff --git a/docs/zengin/scripts/extenders/lego/tools/binary_machines.pl.md b/docs/zengin/scripts/extenders/lego/tools/binary_machines.pl.md new file mode 100644 index 0000000000..c8d9529b53 --- /dev/null +++ b/docs/zengin/scripts/extenders/lego/tools/binary_machines.pl.md @@ -0,0 +1,406 @@ +# BinaryMachines +Ten pakiet pozwala tworzyć i zapisywać własne pliki w dowolnym miejscu w systemie plików. + +## Zależności +Brak + +## Inicjalizacja +Brak + +## Implementacja +[:material-github: BinaryMachines.d na GitHub](https://github.com/Lehona/LeGo/blob/dev/BinaryMachines.d) + +## BinaryWriter + +### `BW_NewFile` +Tworzy plik o nazwie `file` i otwiera strumień. Nie działa, jeśli strumień jest już otwarty. +```dae +func int BW_NewFile(var string file) +``` +**Parametry** + +- `#!dae var string file` + Nazwa tworzonego pliku + +**Zwracana wartość** + +Funkcja zwraca `TRUE` jeśli plik został pomyślnie utworzony i zainicjalizowany, w przeciwnym razie zwracane jest `FALSE`. + +### `BW_Close` +Zamyka aktualny strumień zapisu. +```dae +func void BW_Close() +``` + +### `BW` +Zapisuje `length` bajtów z `data` do strumienia, maksymalnie 4 bajty. +```dae +func void BW(var int data, var int length) +``` +**Parametry** + +- `#!dae var int data` + Wartość bajtów +- `#!dae var int length` + Liczba bajtów + +### `BW_Int` +Zapisuje 4 bajty z `data` do strumienia. To samo co `BW(data, 4)`. +```dae +func void BW_Int(var int data) +``` +**Parametry** + +- `#!dae var int data` + Wartość całkowita do zapisania + +### `BW_Char` +Zapisuje pierwszy znak z `data` do strumienia. To samo co `BW(Str_GetCharAt(data, 0), 1)`. +```dae +func void BW_Char(var string data) +``` +**Parametry** + +- `#!dae var string data` + Znak do zapisania + +### `BW_String` +Zapisuje `data` zakończone znakiem `\0` do strumienia. +```dae +func void BW_String(var string data) +``` +**Parametry** + +- `#!dae var string data` + Ciąg znaków do zapisania + +### `BW_Byte` +Zapisuje bajt z `data` do strumienia. To samo co `BW(data, 1)`. +```dae +func void BW_Byte(var int data) +``` +**Parametry** + +- `#!dae var int data` + Wartość bajtowa do zapisania + +### `BW_Bytes` +Zapisuje `length` bajtów ze wskaźnika `dataPtr` do strumienia. +```dae +func void BW_Bytes(var int dataPtr, var int length) +``` +**Parametry** + +- `#!dae var int dataPtr` + Wskaźnik danych do zapisania +- `#!dae var int length` + Liczba bajtów + +### `BW_Text` +Zapisuje ciąg znaków do strumienia bez jego zakończenia. Nie można go już odczytać. +```dae +func void BW_Text(var string data) +``` +**Parametry** + +- `#!dae var string data` + Tekst do zapisania + +### `BW_NextLine` +Zapisuje akapit do strumienia. +```dae +func void BW_NextLine() +``` + +## BinaryReader + +### `BR_OpenFile` +Otwiera plik o nazwie `file` i otwiera strumień. Nie działa, jeśli strumień jest już otwarty. +```dae +func int BR_OpenFile(var string file) +``` +**Parametry** + +- `#!dae var string file` + Plik, który ma być otwarty + +**Zwracana wartość** + +Funkcja zwraca `TRUE` jeśli plik został pomyślnie otworzony i zainicjalizowany, w przeciwnym razie zwracane jest `FALSE`. + + +### `BR_Close` +Zamyka aktualny strumień odczytu. +```dae +func void BR_Close() +``` + +### `BR` +Odczytuje bajty ze strumienia. +```dae +func int BR(var int length) +``` +**Parametry** + +- `#!dae var int length` + Liczba bajtów do odczytania (maksymalnie 4) + +**Zwracana wartość** + +Funkcja zwraca odczytaną wartość bajtów. + +### `BR_Int` +Odczytuje 4 bajty ze strumienia. To samo co `BR(4)`. +```dae +func int BR_Int() +``` +**Zwracana wartość** + +Funkcja zwraca odczytaną liczbę całkowitą. + +### `BR_Char` +Odczytuje znak ze strumienia. To samo co `BR(1)`. +```dae +func string BR_Char() +``` +**Zwracana wartość** + +Funkcja zwraca odczytany znak jako `string`. + +### `BR_String` +Odczytuje ciąg znaków zakończony znakiem `\0` ze strumienia. +```dae +func string BR_String() +``` +**Zwracana wartość** + +Funkcja zwraca odczytany ciąg znaków. + +### `BR_Byte` +Odczytuje bajt ze strumienia. +```dae +func int BR_Byte() +``` +**Zwracana wartość** + +Funkcja zwraca odczytany bajt. + +### `BR_Bytes` +Odczytuje bajty ze strumienia. +```dae +func int BR_Bytes(var int length) +``` +**Parametry** + +- `#!dae var int length` + Liczba bajtów do odczytania + +**Zwracana wartość** + +Funkcja zwraca wskaźnik do odczytanych bajtów. + +### `BR_TextLine` +Odczytuje linię ze strumienia. +```dae +func string BR_TextLine() +``` +**Zwracana wartość** + +Funkcja zwraca odczytaną linię. + +### `BR_Text` +Odczytuje ciąg znaków o podanej długości ze strumienia. +```dae +func string BR_Text(var int length) +``` +**Parametry** + +- `#!dae var int length` + Liczba znaków do odczytania + +**Zwracana wartość** + +Funkcja zwraca odczytany ciąg znaków. + +### `BR_NextLine` +Zmienia pozycję odczytu na następny akapit, utworzony za pomocą [`BW_NextLine`](#bw_nextline). +```dae +func void BR_NextLine() +``` + +## Wywołania funkcji silnika + +### `WIN_GetLastError` +Wywołanie [funkcji `GetLastError`](https://learn.microsoft.com/en-us/windows/win32/api/errhandlingapi/nf-errhandlingapi-getlasterror) z Win32 API. +```dae +func int WIN_GetLastError() +``` +**Zwracana wartość** + +Funkcja zwraca kod ostatniego błędu wątku wywołującego. + +### `WIN_CreateFile` +Wywołanie [funkcji `CreateFileA`](https://learn.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-createfilea) z Win32 API. +```dae +func int WIN_CreateFile(var string lpFileName,var int dwDesiredAccess,var int dwShareMode,var int lpSecurityAttributes,var int dwCreationDisposition,var int dwFlagsAndAttributes,var int hTemplateFile) +``` +**Parametry** + +Pełny opis parametrów można znaleźć [tutaj](https://learn.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-createfilea#parameters) + +**Zwracana wartość** + +Informacje o zwracanej wartości znajdziesz [tutaj](https://learn.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-createfilea#return-value) + +### `WIN_WriteFile` +Wywołanie [funkcji `WriteFile`](https://learn.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-writefile) z Win32 API. +```dae +func void WIN_WriteFile(var int hFile,var int lpBuffer,var int nNumberOfBytesToWrite,var int lpNumberOfBytesWritten,var int lpOverlapped) +``` +**Parametry** + +Pełny opis parametrów można znaleźć [tutaj](https://learn.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-writefile#parameters) + +### `WIN_ReadFile` +Wywołanie [funkcji `ReadFile`](https://learn.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-readfile) z Win32 API. +```dae +func void WIN_ReadFile(var int hFile,var int lpBuffer,var int nNumberOfBytesToRead,var int lpNumberOfBytesRead,var int lpOverlapped) +``` +**Parametry** + +Pełny opis parametrów można znaleźć [tutaj](https://learn.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-readfile#parameters) + +### `WIN_CloseHandle` +Wywołanie [funkcji `CloseHandle`](https://learn.microsoft.com/en-us/windows/win32/api/handleapi/nf-handleapi-closehandle) z Win32 API. +```dae +func void WIN_CloseHandle(var int hObject) +``` +**Parametry** + +Pełny opis parametrów można znaleźć [tutaj](https://learn.microsoft.com/en-us/windows/win32/api/handleapi/nf-handleapi-closehandle#parameters) + +### `WIN_GetFileSize` +Wywołanie [funkcji `GetFileSize`](https://learn.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-getfilesize) z Win32 API. +```dae +func int WIN_GetFileSize(var int hFile,var int lpFileSizeHigh) +``` +**Parametry** + +Pełny opis parametrów można znaleźć [tutaj](https://learn.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-getfilesize#parameters) + +**Zwracana wartość** + +Informacje o zwracanej wartości znajdziesz [tutaj](https://learn.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-getfilesize#return-value) + +### Constants +Dodatkowo istnieją pewne stałe zdefiniowane do użycia z określonymi wywołaniami funkcji silnika. +```dae +const int CREATE_ALWAYS = 2; +const int OPEN_EXISTING = 3; +const int GENERIC_ALL = 1073741824; +const int GENERIC_READ = -2147483648; +const int FILE_SHARE_READ = 1; +const int FILE_SHARE_WRITE = 2; +const int FILE_SHARE_DELETE = 4; +const int FILE_ATTRIBUTE_NORMAL = 128; +``` + +## Przykłady + +### Zapisywanie i wczytywanie zmiennych +```dae +const string filename = "System\MySave.sav"; + +var string s0; // ciąg znaków +var int i1; // liczba całkowita +var int b2; // bajt +var string c3; // znak + +func void SaveMyData() + + +{ + if(BW_NewFile(filename)) // Utwórz nowy plik: + { + BW_String(s0); + BW_Int(i1); + BW_Byte(b2); + BW_Char(c3); // Zapisz dane... + BW_Close(); // ...i zamknij. + }; +}; + +func void LoadMyData() { + if(BR_OpenFile(filename)) // Spróbuj otworzyć plik: + { + s0 = BR_String(); + i1 = BR_Int(); + b2 = BR_Byte(); + c3 = BR_Char(); // Odczytaj wartości... + BR_Close(); // ...i zamknij. + } + else + { + SaveMyData(); // W przeciwnym razie utwórz plik z zapisem. + }; +}; +``` + +### Gratulacje dla gracza +```dae +func void Certificate(var string Username, var int Score) +{ + var string filename; filename = ConcatStrings(Username, "'s Certificate.txt"); + BW_NewFile(filename); // Nazwa użytkownika + "s Certificate.txt". Plik jest w katalogu Gothic. + BW_Text("Gratulacje "); BW_Text(Username); + BW_TextLine("!"); + + BW_Text("Zdobyłeś "); + BW_Text(IntToString(Score)); // Nie BW_Int! + BW_TextLine(" punktów w tej grze."); + + BW_NextLine(); + + BW_Text("Z wyrazami szacunku, Autor"); + BW_Close(); + + /* + Przy wywołaniu: Certificate("Player", 1000); + zostanie utworzony plik o nazwie 'Player's Certificate.txt', który zawierać będzie: + + Gratulacje NazwaGracza! + Zdobyłeś 1000 punktów w tej grze. + + Z wyrazami szacunku, Autor + */ +}; +``` + +### Położenie postaci NPC +```dae +func void BW_NpcPosition(var C_NPC slf) +{ + var int ptr; ptr = MEM_Alloc(60); // 16 * 4 + MEM_CopyBytes(MEM_InstToPtr(slf) + 60, ptr, 60); // Skopiuj slf.trafoObjToWorld + BW_Bytes(ptr, 60); // Zapisz skopiowane 60 bajtów + MEM_Free(ptr); // I posprzątaj... +}; + +func void BR_NpcPosition(var C_NPC slf) +{ + var int ptr; ptr = BR_Bytes(60); // Odczytaj 60 bajtów + MEM_CopyBytes(ptr, MEM_InstToPtr(slf) + 60, 60); // Wklej z powrotem do slf + MEM_Free(ptr); // I posprzątaj ponownie... +}; + +/* + Użycie standardowe: + BW_NewFile(file); + BW_NpcPosition(hero); + BW_Close(); +*/ +``` + +!!! Uwaga + Przykłady zostały pierwotnie napisane przez Gottfrieda i [opublikowane](https://forum.worldofplayers.de/forum/threads/969446-Skriptpaket-Ikarus-3/page3?p=16198713#post16198713) na forum World of Gothic. +` \ No newline at end of file diff --git a/docs/zengin/scripts/extenders/lego/tools/event_handler.md b/docs/zengin/scripts/extenders/lego/tools/event_handler.md index 00e60506ef..35ee4221be 100644 --- a/docs/zengin/scripts/extenders/lego/tools/event_handler.md +++ b/docs/zengin/scripts/extenders/lego/tools/event_handler.md @@ -6,7 +6,7 @@ This package allows to create new events and trigger them at desired times. The ## Dependencies -- PermMem +- [PermMem](permmem.md) ## Initialization Initialize with `LeGo_EventHandler` flag. diff --git a/docs/zengin/scripts/extenders/lego/tools/frame_functions.md b/docs/zengin/scripts/extenders/lego/tools/frame_functions.md index 57e633c34e..4b5648b8b0 100644 --- a/docs/zengin/scripts/extenders/lego/tools/frame_functions.md +++ b/docs/zengin/scripts/extenders/lego/tools/frame_functions.md @@ -4,7 +4,7 @@ The FrameFunctions package allows to call any number of functions called on ever ## Dependencies - Floats -- PermMem +- [PermMem](permmem.md) - [HookEngine](../tools/hook_engine.md) - [Timer](timer.md) diff --git a/docs/zengin/scripts/extenders/lego/tools/hashtables.md b/docs/zengin/scripts/extenders/lego/tools/hashtables.md index d07f4c4c3e..2a79cae442 100644 --- a/docs/zengin/scripts/extenders/lego/tools/hashtables.md +++ b/docs/zengin/scripts/extenders/lego/tools/hashtables.md @@ -4,7 +4,7 @@ Hashtables package is an implementation of hashtables in Gothic. Currently (vers ## Dependencies -- PermMem +- [PermMem](permmem.md) ## Initialization Initialize with `LeGo_PermMem` flag. diff --git a/docs/zengin/scripts/extenders/lego/tools/interface.md b/docs/zengin/scripts/extenders/lego/tools/interface.md index c9b4912dd6..192243f4bb 100644 --- a/docs/zengin/scripts/extenders/lego/tools/interface.md +++ b/docs/zengin/scripts/extenders/lego/tools/interface.md @@ -6,7 +6,7 @@ This package offers a lot of useful functions to work with the 2D interface. - [AI_Function](ai_function.md) - [Anim8](../applications/anim8.md) - [HookEngine](hook_engine.md) -- PermMem +- [PermMem](permmem.md) ## Initialization diff --git a/docs/zengin/scripts/extenders/lego/tools/list.md b/docs/zengin/scripts/extenders/lego/tools/list.md new file mode 100644 index 0000000000..9f46e904b3 --- /dev/null +++ b/docs/zengin/scripts/extenders/lego/tools/list.md @@ -0,0 +1,363 @@ +# List +The List package is a collection of functions designed to simplify the handling of `zCList` and `zCListSort` lists in daedalus. It offers a range of functions for creating, manipulating, and querying lists. + +## Dependencies +N/A + +## Initialization +N/A + +## Implementation +[:material-github: List.d on GitHub](https://github.com/Lehona/LeGo/blob/dev/List.d) + +## Functions +!!! Note + All functions come with an additional "S" at the end for objects of type `zCListSort`. (Example: List_Node S .) Unlike most LeGo packages, pointers are used here, not handles! + +### `List_Create` +Creates a list with an initial value. +```dae +func int List_Create(var int data) +``` +**Parameters** + +- `#!dae var int data` + The value of the first list element. + +**Return value** + +The function returns a pointer to the created list. + +### `List_Add` +Appends a value to the end of the list. +```dae +func void List_Add(var int list, var int data) +``` +**Parameters** + +- `#!dae var int list` + The list to be used. +- `#!dae var int data` + The value to be appended. + +### `List_AddFront` +Adds a value before the first element of the list. +```dae +func void List_AddFront(var int list, var int data) +``` +**Parameters** + +- `#!dae var int list` + The list to be used. +- `#!dae var int data` + The value to be appended. + +### `List_AddOffset` +Inserts a value between two list elements. +```dae +func void List_AddOffset(var int list, var int offset, var int data) +``` +**Parameters** + +- `#!dae var int list` + The list to be used. +- `#!dae var int offset` + The number of the list element after which the value is inserted. +- `#!dae var int data` + The value to be appended. + +### `List_Set` +Sets a list element to a specific value. +```dae +func void List_Set(var int node, var int data) +``` +**Parameters** + +- `#!dae var int node` + Pointer to a list element. +- `#!dae var int data` + The value to be written into the list element. + +### `List_Get` +Retrieves the value of a list element. +```dae +func int List_Get(var int list, var int nr) +``` +**Parameters** + +- `#!dae var int list` + The list to be used. +- `#!dae var int nr` + The number of the list element. + +**Return value** + +The function returns the value of the specified list element. + +### `List_Node` +Returns a pointer to a list element. +```dae +func int List_Node(var int list, var int nr) +``` +**Parameters** + +- `#!dae var int list` + The list to be used. +- `#!dae var int nr` + The number of a list element. + +**Return value** + +The function returns a pointer to the specified list element. + +### `List_Length` +Returns the length of the list (number of all elements). +```dae +func int List_Length(var int list) +``` +**Parameters** + +- `#!dae var int list` + The list to be used. + +**Return value** + +The function returns the number of elements in the list. + +### `List_HasLength` +Checks if the list has the specified length. +```dae +func int List_HasLength(var int list, var int length) +``` +**Parameters** + +- `#!dae var int list` + The list to be used. +- `#!dae var int length` + The desired length. + +**Return value** + +The function returns a boolean value indicating whether the list has the specified length or not. + +### `List_End` +Returns the last list element of the list. +```dae +func int List_End(var int list) +``` +**Parameters** + +- `#!dae var int list` + The list to be used. + +**Return value** + +The function returns a pointer to the last list element. + +### `List_Concat` +Concatenates two lists. +```dae +func void List_Concat(var int list, var int list2) +``` +**Parameters** + +- `#!dae var int list` + The first list. +- `#!dae var int list2` + The second list. Its beginning is appended to the end of the first list. + +### `List_Contains` +Returns the last list element with a specific value. +```dae +func int List_Contains(var int list, var int data) +``` +**Parameters** + +- `#!dae var int list` + The list to be used. +- `#!dae var int data` + The value to search for. + +**Return value** + +The function returns the number of the last list element with the value `data`. + +### `List_For` +Calls a function for each list element, passing a pointer to the list element as a parameter. +```dae +func void List_For(var int list, var string function) +``` +**Parameters** + +- `#!dae var int list` + The list to be used. +- `#!dae var string function` + Name of a function to be called for each list element (`void handler(var int node)`). + +### `List_ForF` +Similar to `List_For`, but with a function parameter instead of a string. +```dae +func void ListForF(var int list, var func function) +``` +**Parameters** + +- `#!dae var int list` + The list to be used. +- `#!dae var func function` + The function to be called for each list element (`void handler(var int node)`). + +### `List_ForI` +Similar to `List_For`, but with a function parameter instead of a string. +```dae +func void List_ForI(var int list, var int funcID) +``` +**Parameters** + +- `#!dae var int list` + The list to be used. +- `#!dae var int funcID` + ID of a function to be called for each list element (`void handler(var int node)`). + +### `List_Delete` +Deletes a list element. All subsequent elements shift position. +```dae +func void List_Delete(var int list, var int nr) +``` +**Parameters** + +- `#!dae var int list` + The list to be used. +- `#!dae var int nr` + The number of the list element to be deleted. + + +### `List_Destroy` +Destroys the entire list. +```dae +func void List_Destroy(var int list) +``` +**Parameters** + +- `#!dae var int list` + The list to be destroyed. + +### `List_ToArray` +Returns a pointer to a memory area containing all values of the list. +```dae +func int List_ToArray(var int list) +``` +**Parameters** + +- `#!dae var int list` + The list to be used. + +**Return value** + +The function returns a memory area containing all the values of the list. + +### `List_MoveDown` +Moves the specified list node down by one position in the list. +```dae +func void List_MoveDown(var int list, var int node) +``` +**Parameters** + +- `#!dae var int list` + The list in which the node is located. +- `#!dae var int node` + The node to be moved down. + +### `List_MoveUp` +Moves the specified list node up by one position in the list. +```dae +func void List_MoveUp(var int list, var int node) +``` +**Parameters** + +- `#!dae var int list` + The list in which the node is located. +- `#!dae var int node` + The node to be moved up. + +### `List_InsertSorted` +Inserts a value into a sorted list while preserving the sort order. + +```dae +func void List_InsertSorted(var int list, var int data, var func compare) +``` +**Parameters:** + +- `#!dae var int list` + The list to insert the value into. +- `#!dae var int data` + The value to be inserted. +- `#!dae var func compare` + A comparison function used to determine the sort order. + +## Comparison Functions + +The following comparison functions can be used as the `compare` parameter in the `List_InsertSorted` function: + +#### `List_CmpAscending` +Compares two integer values in ascending order. +```dae +func int List_CmpAscending(var int data1, var int data2) +``` +**Parameters:** + +- `#!dae var int data1` + The first integer value. +- `#!dae var int data2` + The second integer value. + +**Return Value:** + +The function returns `TRUE` if `data1` is greater than `data2`, `FALSE` is returned otherwise. + +#### `List_CmpDescending` +Compares two integer values in descending order. +```dae +func int List_CmpDescending(var int data1, var int data2) +``` +**Parameters:** + +- `#!dae var int data1` + The first integer value. +- `#!dae var int data2` + The second integer value. + +**Return Value:** + +The function returns `TRUE` if `data1` is less than `data2`, `FALSE` is returned otherwise. + +#### `List_CmpAscendingUnsigned` +Compares two unsigned integer values in ascending order. +```dae +func int List_CmpAscendingUnsigned(var int data1, var int data2) +``` +**Parameters:** + +- `#!dae var int data1` + The first unsigned integer value. +- `#!dae var int data2` + The second unsigned integer value. + +**Return Value:** + +The function returns `TRUE` if `data1` is greater than `data2`, `FALSE` is returned otherwise. + +#### `List_CmpDescendingUnsigned` +Compares two unsigned integer values in descending order. +```dae +func int List_CmpDescendingUnsigned(var int data1, var int data2) +``` +**Parameters:** + +- `#!dae var int data1` + The first unsigned integer value. +- `#!dae var int data2` + The second unsigned integer value. + +**Return Value:** + +The function returns `TRUE` if `data1` is less than `data2`, `FALSE` is returned otherwise. \ No newline at end of file diff --git a/docs/zengin/scripts/extenders/lego/tools/locals.md b/docs/zengin/scripts/extenders/lego/tools/locals.md index d5b73767a9..7831ab4b1a 100644 --- a/docs/zengin/scripts/extenders/lego/tools/locals.md +++ b/docs/zengin/scripts/extenders/lego/tools/locals.md @@ -5,7 +5,7 @@ There is also the `final` function, which can be used to emulate something simil ## Dependencies -- StringBuilder +- [StringBuilder](string_builder.md) ## Initialization N/A diff --git a/docs/zengin/scripts/extenders/lego/tools/permmem.md b/docs/zengin/scripts/extenders/lego/tools/permmem.md new file mode 100644 index 0000000000..191d81ccd8 --- /dev/null +++ b/docs/zengin/scripts/extenders/lego/tools/permmem.md @@ -0,0 +1,506 @@ +# PermMem +PermMem is a powerful package that allows classes (or instances) to be used permanently even after loading or restarting by saving them to the ASCII `.ZEN` archive in the savegame directory. PermMem manages handles that are used to access instances, and provides various functions to manipulate these handles and instances. + +## Dependencies + +- [Saves](../applications/saves.md) +- [Locals](locals.md) + +## Initialization +Initialize with `LeGo_PermMem` flag. +```dae +LeGo_Init(LeGo_PermMem); +``` + +## Implementation +[:material-github: PermMem.d on GitHub](https://github.com/Lehona/LeGo/blob/dev/PermMem.d) + +## Functions + +### `new` +Creates a handle to a new instance of `inst`. +```dae +func int new(var int inst) +``` +**Parameters** + +- `#!dae var int inst` + A valid instance. Used as "constructor" + +**Return value** + +The function returns a new, valid PermMem handle. + +### `create` +Similar to `new`, but here a pointer is returned directly and not a handle. Caution! Not managed by PermMem! +```dae +func int create(var int inst) +``` +**Parameters** + +- `#!dae var int inst` + A valid instance. Used as "constructor" + +**Return value** + +The function returns a pointer to the new instance. + +### `wrap` +"Wraps" a handle "around" a pointer so that the pointer can be used with any function that expects handles. +Only conditionally managed by PermMem. +```dae +func int wrap(var int inst, var int ptr) +``` +**Parameters** + +- `#!dae var int inst` + A valid instance. Determines the type of the handle +- `#!dae var int ptr` + Pointer to wrap + +**Return value** + +The function returns a handle with `ptr` as content. + +### `clear` +Cleans the handle. After that it is invalid. +```dae +func void clear(var int hndl) +``` +**Parameters** + +- `#!dae var int hndl` + Valid PermMem handle + +### `release` +Frees the handle. The reserved memory is not deleted, the handle becomes invalid. +```dae +func void release(var int hndl) +``` +**Parameters** + +- `#!dae var int hndl` + Valid PermMem handle + +### `delete` +Cleans the handle just like `clear`, only the destructor is also called. +```dae +func void delete(var int hndl) +``` +**Parameters** + +- `#!dae var int hndl` + Valid PermMem handle + +### `free` +Similar to `delete`, only here a pointer is destroyed and not a handle. Caution! Not managed by PermMem! +```dae +func void free(var int ptr, var int inst) +``` +**Parameters** + +- `#!dae var int ptr` + The pointer to be cleaned +- `#!dae var int inst` + Instance used in [`create`](#create) function. + +### `get` +Returns the instance of the handle. +```dae +func instance get(var int hndl) +``` +**Parameters** + +- `#!dae var int hndl` + Valid PermMem handle + +### `getPtr` +Returns a pointer to instance of handle. +```dae +func int getPtr(var int hndl) +``` +**Parameters** + +- `#!dae var int hndl` + Valid PermMem handle + +### `setPtr` +Sets the pointer of a handle. +```dae +func void setPtr(var int hndl, var int ptr) +``` +**Parameters** + +- `#!dae var int hndl` + Valid PermMem handle +- `#!dae var int ptr` + New pointer for handle + +### `getInst` +Returns the instance used to create the given handle in [`new`](#new) function. +```dae +func int getInst(var int hndl) +``` +**Parameters** + +- `#!dae var int hndl` + Valid PermMem handle + +### `numHandles` +Returns the number of handles managed by PermMem. +```dae +func int numHandles() +``` + +### `sizeof` +Returns Size of the instance's class in bytes +```dae +func int sizeof(var int inst) +``` +**Parameters** + +- `#!dae var int inst` + Any instance + +### `Hlp_IsValidHandle` +Indicates whether the handle exists and is managed by PermMem. +```dae +func int Hlp_IsValidHandle(var int hndl) +``` +**Parameters** + +- `#!dae var int hndl` + PermMem's handle + +**Return value** + +The function returns `TRUE` if the handle is valid (managed by PermMem), `FALSE` is returned otherwise. + +??? abstract "Example" + The example function that use `Hlp_IsValidHandle` is [`Bar_SetMax`](../applications/bars.md#bar_setmax) form LeGo [Bars](../applications/bars.md) package. The function first checks if the handle is valid, then gets the instance and changes its parameters. + + ```dae + func void Bar_SetMax(var int bar, var int max) + { + if(!Hlp_IsValidHandle(bar)) { return; }; + var _bar b; b = get(bar); + b.valMax = max; + }; + ``` + +### `foreachHndl` +Executes a function for each handle of an instance. +```dae +func void foreachHndl(var int inst, var func fnc) +``` +**Parameters** + +- `#!dae var int inst` + The function is called for this instance +- `#!dae var int inst` + This function is called. The signature is `function(int handle)` + +### `hasHndl` +Checks if PermMem has a handle of this instance. +```dae +func int hasHndl(var int inst) +``` +**Parameters** + +- `#!dae var int inst` + Instance to be checked + +**Return value** + +The function returns `TRUE` if the PermMem has a handle of this instance, `FALSE` is returned otherwise. + +### `MEM_ReadStringArray` +Function moved to PermMem form [Ikarus](../../ikarus/functions/mem_access.md#mem_readstringarray). Reads string from the array at the `arrayAddress`. +```dae +func string MEM_ReadStringArray(var int arrayAddress, var int index) +``` +**Parameters** + +- `#!dae var int arrayAddress` + Memory address of array +- `#!dae var int offset` + Array offset (array index) + +**Return value** + +The function returns string from the array if the address is correct. + + +### `PM_Exists` +Checks if the specified field already exists in the archive. (used with archiver/unarchiver) +```dae +func int PM_Exists(var string name) +``` +**Parameters** + +- `#!dae var string name` + Name of the field + +**Return value** +The function returns `TRUE` if the field exists in the archive, `FALSE` is returned otherwise. + +## Archiver + +### `PM_SaveInt` +Saves an integer to the archive. +```dae +func void PM_SaveInt (var string name, var int val) +``` +**Parameters** + +- `#!dae var string name` + Name of the field in saved archive +- `#!dae var int val` + Value of the saved integer + +### `PM_SaveFloat` +Saves a daedalus float to the archive. +```dae +func void PM_SaveFloat (var string name, var int flt) +``` +**Parameters** + +- `#!dae var string name` + Name of the field in saved archive +- `#!dae var int flt` + Value of the saved float + +### `PM_SaveString` +Saves a string to the archive. +```dae +func void PM_SaveString (var string name, var string val) +``` +**Parameters** + +- `#!dae var string name` + Name of the field in saved archive +- `#!dae var string val` + Saved string + +### `PM_SaveFuncID` +Saves a function ID to the archive. +```dae +func void PM_SaveFuncID(var string name, var int fnc) +``` +**Parameters** + +- `#!dae var string name` + Name of the field in saved archive +- `#!dae var int fnc` + Saved function ID + +### `PM_SaveFuncOffset` +Saves a function offset to the archive. +```dae +func void PM_SaveFuncOffset(var string name, var int fnc) +``` +**Parameters** + +- `#!dae var string name` + Name of the field in saved archive +- `#!dae var int fnc` + Saved function offset + +### `PM_SaveFuncPtr` +Saves a function pointer to the archive. +```dae +func void PM_SaveFuncPtr(var string name, var int fnc) +``` +**Parameters** + +- `#!dae var string name` + Name of the field in saved archive +- `#!dae var int fnc` + Saved function pointer + +### `PM_SaveClassPtr` +Saves a pointer of a class to the archive. +```dae +func void PM_SaveClassPtr(var string name, var int ptr, var string className) +``` +**Parameters** + +- `#!dae var string name` + Name of the field in saved archive +- `#!dae var int ptr` + Saved pointer +- `#!dae var string className` + Name of the class of stored pointer + +### `PM_SaveClass` +Saves a class like `PM_SaveClassPtr`. +```dae +func void PM_SaveClass(var string name, var int ptr, var string className) +``` +**Parameters** + +- `#!dae var string name` + Name of the field in saved archive +- `#!dae var int ptr` + Saved class pointer +- `#!dae var string className` + Name of the class of stored pointer + +### `PM_SaveIntArray` +Saves an array of integers. +```dae +func void PM_SaveIntArray(var string name, var int ptr, var int elements) +``` +**Parameters** + +- `#!dae var string name` + Name of the field in saved archive +- `#!dae var int ptr` + Pointer to the array +- `#!dae var int elements` + Number of elements in array + +### `PM_SaveStringArray` +Saves an array of integers. +```dae +func void PM_SaveStringArray(var string name, var int ptr, var int elements) +``` +**Parameters** + +- `#!dae var string name` + Name of the field in saved archive +- `#!dae var int ptr` + Pointer to the array +- `#!dae var int elements` + Number of elements in array + +## Unarchiver + +### `PM_Load` +Universal function to load integers, floats, class pointers and int arrays. +```dae +func int PM_Load(var string name) +``` +**Parameters** + +- `#!dae var string name` + Name of the loaded field + +**Return value** +The function returns the data existing in the archive at the given field. + +### `PM_LoadInt` +Returns an integer stored in the archive. +```dae +func int PM_LoadInt(var string name) +``` +**Parameters** + +- `#!dae var string name` + Name of the loaded field + +### `PM_LoadFloat` +Returns a daedalus float stored in the archive. +```dae +func int PM_LoadFloat(var string name) +``` +**Parameters** + +- `#!dae var string name` + Name of the loaded field + +### `PM_LoadString` +Returns a string stored in the archive. +```dae +func string PM_LoadString(var string name) +``` +**Parameters** + +- `#!dae var string name` + Name of the loaded field + +### `PM_LoadFuncID` +Returns a function ID stored in the archive. +```dae +func int PM_LoadFuncID(var string name) +``` +**Parameters** + +- `#!dae var string name` + Name of the loaded field + +### `PM_LoadFuncOffset` +Returns a function offset stored in the archive. +```dae +func int PM_LoadFuncOffset(var string name) +``` +**Parameters** + +- `#!dae var string name` + Name of the loaded field + +### `PM_LoadFuncPtr` +Returns a function pointer stored in the archive. +```dae +func int PM_LoadFuncPtr(var string name) +``` +**Parameters** + +- `#!dae var string name` + Name of the loaded field + +### `PM_LoadClassPtr` +Returns a class pointer stored in the archive. +```dae +func int PM_LoadClassPtr(var string name) +``` +**Parameters** + +- `#!dae var string name` + Name of the loaded field + +### `PM_LoadClass` +Loads a pointer to the class from the archive to `destPtr`. +```dae +func void PM_LoadClass(var string name, var int destPtr) +``` +**Parameters** + +- `#!dae var string name` + Name of the loaded field +- `#!dae var int destPtr` + Destination pointer, the address to where it will deserialize the saved data + +### `PM_LoadArray` +Returns a pointer to array stored in the archive. +```dae +func int PM_LoadArray(var string name) +``` +**Parameters** + +- `#!dae var string name` + Name of the loaded field + +### `PM_LoadArrayToPtr` +Loads a pointer to array from the archive to `destPtr`. +```dae +func void PM_LoadArrayToPtr(var string name, var int destPtr) +``` +**Parameters** + +- `#!dae var string name` + Name of the loaded field +- `#!dae var int destPtr` + Destination pointer, the address to where it will deserialize the saved data + +### `PM_LoadToPtr` +Universal function to load array or class pointer from the archive to `destPtr`. +```dae +func void PM_LoadToPtr(var string name, var int destPtr) +``` +**Parameters** + +- `#!dae var string name` + Name of the loaded field +- `#!dae var int destPtr` + Destination pointer, the address to where it will deserialize the saved data \ No newline at end of file diff --git a/docs/zengin/scripts/extenders/lego/tools/queue.md b/docs/zengin/scripts/extenders/lego/tools/queue.md index f60f6c6dec..fb110aca03 100644 --- a/docs/zengin/scripts/extenders/lego/tools/queue.md +++ b/docs/zengin/scripts/extenders/lego/tools/queue.md @@ -3,7 +3,7 @@ This package is an implementation of the Queue data structure and a queue for fu ## Dependencies -- PermMem +- [PermMem](permmem.md) ## Initialization N/A diff --git a/docs/zengin/scripts/extenders/lego/tools/string_builder.md b/docs/zengin/scripts/extenders/lego/tools/string_builder.md new file mode 100644 index 0000000000..d9f8117be5 --- /dev/null +++ b/docs/zengin/scripts/extenders/lego/tools/string_builder.md @@ -0,0 +1,325 @@ +# StringBuilder +The StringBuilder is a package, designed to easily concatenate multiple elements into a string (without `ConcatStrings` and `IntToString`). + +All created StringBuilders are transient. All functions starting from `SB_InitBuffer`, including it, use the active StringBuilder set with `SB_New` or `SB_Use`, so there is no `#!dae var int stringBuilder` parameter in functions. A look at the example explains what I mean. + +!!! Warning + The StringBuilder works with pointers, not handles like many other LeGo packages. + +## Dependencies +N/A + +## Initialization +N/A + +## Implementation +[:material-github: StringBuilder.d on GitHub](https://github.com/Lehona/LeGo/blob/dev/StringBuilder.d) + +## Functions + +### `SB_New` +Creates and returns a new `StringBuilder`. At the same time, this new `StringBuilder` is set as active. (See `SB_Use`.) +```dae +func int SB_New() +``` +**Return value** + +The function returns a pointer to a new `StringBuilder`. + +### `SB_Use` +Marks this `StringBuilder` as active. It can now be used with the functions. +```dae +func void SB_Use(var int sb) +``` +**Parameters** + +- `#!dae var int sb` + Pointer to a `StringBuilder`, returned from `SB_New` + +### `SB_Get` +Returns the active `StringBuilder`. +```dae +func int SB_Get() +``` +**Return value** + +The function returns the active `StringBuilder` object - last set with `SB_Use` or just created with `SB_New`. + +### `SB_InitBuffer` +If the size of the resulting string is already known, the buffer can be set manually. This is usually not necessary. +```dae +func void SB_InitBuffer(var int size) +``` +**Parameters** + +- `#!dae var int size` + Size in bytes. **Warning!** Only works if the `StringBuilder` has been newly created! + +### `SB_Clear` +Empties the current `StringBuilder`. It is not destroyed in the process, so it can be used again. If the object has a buffer allocated, the buffer is freed. +```dae +func void SB_Clear() +``` + +### `SB_Release` +Releases the current stream of the `StringBuilder`. The `StringBuilder` is destroyed, and the stream can be obtained via `SB_GetStream`. +```dae +func void SB_Release() +``` + +### `SB_Destroy` +Completely destroys the `StringBuilder`. +```dae +func void SB_Destroy() +``` + +### `SB_ToString` +Returns a copy of the stream as a string. +```dae +func string SB_ToString() +``` +**Return value** + +The function returns the copy of the active `StringBuilder` as a string. If the `StringBuilder` object doesn't have a buffer allocated, an empty string is returned. + +### `SB_ToStream` +Returns a copy of the stream in raw format. +```dae +func int SB_ToStream() +``` +**Return value** + +The function returns a copy of the stream in raw format (`char[]`) + +### `SB_GetStream` +Doesn't copy the stream, but returns it as it is. +```dae +func int SB_GetStream() +``` +**Return value** + +The function returns the stream as it is. `SB_Destroy` or `SB_Clear` destroy the returned pointer. + +### `SB_Length` +Returns the current length of the stream. Similar to `STR_Len` from [Ikarus](../../ikarus/index.md) . +```dae +func int SB_Length() +``` +**Return value** + +The function returns the current length of the active `StringBuilder`. + +### `SB_SetLength` +Sets the length of the stream. When increasing, zero bytes are appended. +```dae +func void SB_SetLength(var int length) +``` + +## Stream operations + + +### `SB` +Appends a string, to the active `StringBuilder`. +```dae +func void SB(var string s) +``` +**Parameters** + +- `#!dae var string s` + The appended string + +### `SBi` +Appends an integer in text form, to the active `StringBuilder`. +```dae +func void SBi(var int i) +``` +**Parameters** + +- `#!dae var int i` + The appended integer + +### `SBc` +Appends a byte, to the active `StringBuilder`. (e.g. 82 for 'R' - An ASCII table can be quickly found) +```dae +func void SBc(var int c) +``` +**Parameters** + +- `#!dae var int c` + The appended byte (ASCII table character) + +### `SBraw` +Appends a raw bytes array, to the active `StringBuilder`. +```dae +func void SBraw(var int ptr, var int len) +``` +**Parameters** + +- `#!dae var int ptr` + Pointer to the appended array +- `#!dae var int len` + Length of an array + +### `SBflt` +Appends a Daedalus float in text form, to the active `StringBuilder`. +```dae +func void SBflt(var float x) +``` +**Parameters** + +- `#!dae var float x` + The appended Daedalus float value + +### `SBf` +Appends an Ikarus float in text form, to the active `StringBuilder`. +```dae +func void SBf(var int x) +``` +**Parameters** + +- `#!dae var float x` + The appended Ikarus float value + +### `SBw` +Appends a 4-byte raw data (interpreted as an integer `x`), to the active `StringBuilder`. +```dae +func void SBw(var int x) +``` +**Parameters** + +- `#!dae var int i` + The appended value + +## Independent Functions + +### `STR_Escape` +Makes escape sequences out of non-writable characters. For example, newline character `\n` becomes `\\n`, tab character `\t` becomes `\\t`, etc. +```dae +func string STR_Escape(var string s0) +``` +**Parameters** + +- `#!dae var string s0` + The string to be added escape sequences + +**Return value** + +The function returns a new string with escape sequences added for special characters. + + +### `STR_Unescape` +Counterpart to `STR_Escape`. Escape sequences like `\n`, `\r` or `\t` are converted back. +```dae +func string STR_Unescape(var string s0) +``` +**Parameters** + +- `#!dae var string s0` + The string to be removed escape sequences + +**Return value** + +The function returns a new string with escape sequences replaced by their corresponding characters. + +### `STR_StartsWith` +Checks if the input string `s` starts with the specified prefix string. +```dae +func int STR_StartsWith(var string str, var string start) +``` +**Parameters** + +- `#!dae var string str` + The string to be checked +- `#!dae var string start` + The searched prefix + +**Return value** + +The function returns `TRUE` if the string starts with the prefix, `FALSE` is returned otherwise. + +## Additional Functions + +### `BuildStringSymbolsArray` +Creates an array of all string symbols found in the parser's string table. +```dae +func int BuildStringSymbolsArray() +``` +**Return value** + +The function returns created array. + +### `GetStringSymbolByAddr` +Retrieves the symbol at the specified address from the string table. +```dae +func int BuildStringSymbolsArray() +``` +**Return value** + +The function returns a parser symbol at the given address. + +## Examples + +### Basic functionality +This is how function that builds a string looks without `StringBuilder`: +```dae +func void PrintMyNumbers(var int x0, var int x1, var int x2) { + var string res; + res = ConcatStrings(IntToString(x0), ", "); + res = ConcatStrings(res, IntToString(x1)); + res = ConcatStrings(res, ", "); + res = ConcatStrings(res, IntToString(x2)); + PrintS(res); +}; +``` +And now the function that uses `StringBulider`: +```dae +func void PrintMyNumbers(var int x0, var int x1, var int x2) { + var int s; s = SB_New(); // Create StringBuilder + SBi(x0); // Append Int + SB (", "); // Append string + SBi(x1); // Append Int + SB (", "); // Append string + SBi(x2); // Append Int + PrintS(SB_ToString()); // Get output as a string + SB_Destroy(); // Destroy StringBuilder +}; +``` +Looks much more pleasant, right? But why do we create a StringBuilder and then not use it? +The idea is the following: A StringBuilder is created with `SB_New()` and set as the active StringBuilder in the background. The package only supports one StringBuilder at a time, which will keep the pointer in case we want to use another StringBuilder in between. + +### Multiple StringBuilders +Simple example. We want to fill two StringBuilders at the same time and then return them combined: +```dae +func string Example2() { + // Create two StringBuilders: + var int s0; s0 = SB_New(); + var int s1; s1 = SB_New(); + + // Set the first StringBuilder as active and fill it. + SB_Use(s0); + SB("Hello "); + SB("World!"); + + // Set the second StringBuilder as active and fill it. + SB_Use(s1); + SB("This is "); + SB("the hero speaking!"); + + // Now we want to combine the two StringBuilders. + // The system doesn't actually provide for such an operation, but it can still be done using a helper string + var string str; str = SB_ToString(); // This string now says “This is the hero speaking!” + + SB_Use(s0); + SB(" "); + SB(str); + + str = SB_ToString(); // Now "Hello world! This is the hero speaking!" are in the string. + + // The rest is already known, we destroy StringBuilders + SB_Destroy(); + SB_Use(s1); + SB_Destroy(); + + return str; +}; +``` \ No newline at end of file diff --git a/docs/zengin/scripts/extenders/lego/tools/talents.md b/docs/zengin/scripts/extenders/lego/tools/talents.md index 9f7921d68c..b9ae1b043d 100644 --- a/docs/zengin/scripts/extenders/lego/tools/talents.md +++ b/docs/zengin/scripts/extenders/lego/tools/talents.md @@ -8,7 +8,7 @@ Talents package uses one free AIVar variables, the default is AIVar with the ind ## Dependencies -- PermMem +- [PermMem](permmem.md) ## Initialization Initialize with `LeGo_PermMem` flag. diff --git a/docs/zengin/scripts/extenders/lego/tools/talents.pl.md b/docs/zengin/scripts/extenders/lego/tools/talents.pl.md index 50f5ae20a3..8c2709d027 100644 --- a/docs/zengin/scripts/extenders/lego/tools/talents.pl.md +++ b/docs/zengin/scripts/extenders/lego/tools/talents.pl.md @@ -11,7 +11,7 @@ Pakiet `Talents` używa jednego wolnego AIVara, domyślnie jest to AIVar z numer ## Zależności -- PermMem +- [PermMem](permmem.md) ## Inicjalizacja Zainicjuj za pomocą flagi `LeGo_PermMem`.