Added part of docs

2026-05-19 20:51:59 +02:00
parent e91fd2e42a
commit df6cf2f3d3
66 changed files with 11821 additions and 0 deletions
--- a/docs/en/reference/ARRAY.md
+++ b/docs/en/reference/ARRAY.md
@@ -0,0 +1,475 @@
+# ARRAY
+
+Zero-indexed array that stores values of any type. Full support for serialisation and arithmetic operations is provided for the four primitive types: [`INTEGER`](INTEGER.md), [`DOUBLE`](DOUBLE.md), [`STRING`](STRING.md), and [`BOOL`](BOOL.md). Mixed-type arrays are allowed, but some methods interpret elements in non-obvious ways (see the notes on [`FIND`](#find), [`CONTAINS`](#contains), and [`GETSUMVALUE`](#getsumvalue)).
+
+## Fields
+
+### TOINI
+
+```
+BOOL TOINI
+```
+
+Controls whether the array's contents are serialised to an INI file and restored on the next run.
+
+## Methods
+
+### ADD
+
+```
+void ADD(mixed value1, [mixed value2, ..., mixed valueN])
+```
+
+Appends the given values to the end of the array. The argument types do not have to match.
+
+**Parameters**
+
+- `value1, …, valueN` — values to append.
+
+**Examples**
+
+```
+G_ARRSETTINGS^ADD(0, 600);
+G_ARRDATAS^ADD("PODWIECZOREK1", "PODWIECZOREK2", "PODWIECZOREK3");
+ARRFLAMESDIR^ADD("R", "R", "R", "L", "L");
+ARR_JOINTS^ADD(FALSE, 6, "B", 10, "A", 4);
+```
+
+### ADDAT
+
+```
+void ADDAT(INTEGER index, mixed value)
+```
+
+Adds the argument to the element at position `index`. Internally, the element and the argument are converted to `DOUBLE`, summed, and stored as [`DOUBLE`](DOUBLE.md) — after this call the element at that position is always of type `DOUBLE`. Calling with `index` out of range leaves the array unchanged.
+
+**Parameters**
+
+- `index` — element position (`0`-based).
+- `value` — value to add.
+
+**Examples**
+
+```
+ARRIDLETIME^ADDAT(0, 1);
+ARRENEMYY^ADDAT(VARITMPINDEX, VARITMP1);
+ARRSPEED^ADDAT(0, 2.0);
+```
+
+### CHANGEAT
+
+```
+void CHANGEAT(INTEGER index, mixed value)
+```
+
+Replaces the element at position `index` with the given value. The type of the new element is preserved exactly as passed. Calling with `index` out of range leaves the array unchanged.
+
+**Parameters**
+
+- `index` — element position (`0`-based).
+- `value` — the new value.
+
+**Examples**
+
+```
+ARRIDLETIME^CHANGEAT(0, 0);
+G_ARRREXSPELLS^CHANGEAT(VARIREPEATSPELL, 1);
+ARRAYPLAYERSSTATE^CHANGEAT([VARCLONE-1], "NULL");
+```
+
+### CLAMPAT
+
+```
+void CLAMPAT(INTEGER index, mixed rangeMin, mixed rangeMax)
+```
+
+Clamps the value at position `index` to the inclusive range `[rangeMin, rangeMax]`. The element's type is preserved — `INTEGER` stays `INTEGER`, `DOUBLE` stays `DOUBLE`. For elements of any other type (and for `index` out of range) the call leaves the array unchanged.
+
+**Parameters**
+
+- `index` — element position (`0`-based).
+- `rangeMin` — lower bound (inclusive).
+- `rangeMax` — upper bound (inclusive).
+
+**Examples**
+
+```
+ARRSPEED^CLAMPAT(VARPLAYER, 0.0, 100.0);
+ARRSPEED^CLAMPAT(0, 0.0, 17.0);
+```
+
+### CONTAINS
+
+```
+BOOL CONTAINS(mixed needle)
+```
+
+Checks whether the array contains an element matching the given value. The comparison is done on the textual representation — `needle` is cast to [`STRING`](STRING.md) and compared with the `toDisplayString` result of each element. This differs from `FIND`, which compares values according to the [engine's typing rules](../engine/arithmetic.md#typing-rule).
+
+**Parameters**
+
+- `needle` — the value to search for.
+
+**Returns**: [`BOOL`](BOOL.md) — `TRUE` if a matching element was found.
+
+**Examples**
+
+```
+ART0^CONTAINS(ICIK);
+ARRAYWARSZTATPRZEDMIOTY^CONTAINS(ARRAYTEMP^GET($1));
+```
+
+### COPYTO
+
+```
+void COPYTO(STRING arrayVarName)
+```
+
+Appends the contents of this array to the end of the array named in the argument. The target array must already exist and be of type `ARRAY`. The target array is **not** cleared before copying.
+
+**Parameters**
+
+- `arrayVarName` — the name of the destination array variable.
+
+**Examples**
+
+```
+ARAG^COPYTO("ARTMP");
+```
+
+### FIND
+
+```
+INTEGER FIND(mixed needle)
+```
+
+Searches the array for the first element equal to the given value. The comparison follows the [engine's typing rules](../engine/arithmetic.md#typing-rule) — the type of the array element in each iteration determines what type `needle` is cast to. This yields counterintuitive results in mixed-type arrays: for example, searching for `240` in an array containing `TRUE` will return the index of `TRUE`, because `240` is cast to `BOOL` (a non-zero value, which becomes `TRUE`).
+
+**Parameters**
+
+- `needle` — the value to search for.
+
+**Returns**: the index of the first matching element, or `-1` if no match was found.
+
+**Examples**
+
+```
+G_ARRCUTSCENES^FIND(G_SCUTSCENE);
+ARRSTARTNAME0^FIND("NULL");
+ARRCLONES^FIND(-1);
+```
+
+### GET
+
+```
+mixed GET(INTEGER index)
+```
+
+Returns the element at position `index`. For `index` out of range, returns `NULL`.
+
+**Parameters**
+
+- `index` — element position (`0`-based).
+
+**Returns**: the element's value or `NULL`.
+
+**Examples**
+
+```
+ARRIDLETIME^GET(0);
+ARRACTIVESPELLS^GET(_I_);
+ARRAYPLAYERSSTATE^GET([VARCLONE-1]);
+```
+
+### GETSIZE
+
+```
+INTEGER GETSIZE()
+```
+
+Returns the number of elements in the array.
+
+**Returns**: the array's size.
+
+**Examples**
+
+```
+G_ARRSETTINGS^GETSIZE();
+ARRENEMYROUTEX^GETSIZE();
+```
+
+### GETSUMVALUE
+
+```
+DOUBLE GETSUMVALUE()
+```
+
+Returns the sum of all element values. Each element is cast to `DOUBLE` per the [conversion rules](../engine/arithmetic.md#type-conversions); non-numeric elements can contribute unexpected values (`BOOL` → `1.0` or `0.0`, a non-numeric [`STRING`](STRING.md) → `0.0`).
+
+**Returns**: the sum as a [`DOUBLE`](DOUBLE.md).
+
+**Examples**
+
+```
+ARCONTAINER^GETSUMVALUE();
+```
+
+### INSERTAT
+
+```
+void INSERTAT(INTEGER index, mixed value)
+```
+
+Inserts the value at position `index`, shifting existing elements to the right. Valid values of `index` are in `[0, size]` — inserting at the array's size appends the element at the end. Calling outside this range leaves the array unchanged.
+
+**Parameters**
+
+- `index` — insertion position.
+- `value` — the value to insert.
+
+**Examples**
+
+```
+ARRTURNIEJ^INSERTAT(I3, I1);
+ARRTURNIEJ^INSERTAT(4, I1);
+```
+
+### LOAD
+
+```
+void LOAD(STRING path)
+```
+
+Replaces the array's contents with data read from a binary `.ARR` file. The file is little-endian: a 4-byte element count, followed by, for each element, a 4-byte type tag (`1`=`INTEGER`, `2`=`STRING`, `3`=`BOOL`, `4`=`DOUBLE`) and the corresponding value representation.
+
+**Parameters**
+
+- `path` — the `.ARR` file path in the game's VFS.
+
+**Examples**
+
+```
+G_ARRSETTINGS^LOAD("$COMMON\SETTINGS.ARR");
+ARRPATH^LOAD(["MAPA"+ILEVEL+".ARR"]);
+```
+
+### LOADINI
+
+```
+void LOADINI()
+```
+
+Replaces the array's contents with data deserialised from the game's INI file under the key matching this variable's name. The INI format is a comma-separated list of values:
+
+```
+ARRAY_NAME=value1,value2,value3,...
+```
+
+Each element is interpreted in order as [`INTEGER`](INTEGER.md), [`DOUBLE`](DOUBLE.md), [`BOOL`](BOOL.md), or [`STRING`](STRING.md) — the first matching type is used.
+
+**Examples**
+
+```
+ARRAYWARSZTATMENUPRZEDMIOTY^LOADINI();
+```
+
+### MODAT
+
+```
+void MODAT(INTEGER index, mixed divisor)
+```
+
+Stores the remainder of dividing the element at position `index` by the argument. Internally, the element and the argument are converted to `DOUBLE`, modulo is computed, and the result is stored as [`DOUBLE`](DOUBLE.md). Division by zero, or calling with `index` out of range, leaves the array unchanged.
+
+**Parameters**
+
+- `index` — element position.
+- `divisor` — the divisor.
+
+**Examples**
+
+```
+ARRANGLE^MODAT(VARPLAYER, 360);
+```
+
+### MULAT
+
+```
+void MULAT(INTEGER index, mixed multiplier)
+```
+
+Multiplies the element at position `index` by the argument. Internally, the element and the argument are converted to `DOUBLE`, multiplied, and the result is stored as [`DOUBLE`](DOUBLE.md). Calling with `index` out of range leaves the array unchanged.
+
+**Parameters**
+
+- `index` — element position.
+- `multiplier` — the multiplier.
+
+**Examples**
+
+```
+ARRDIRY^MULAT(VARPLAYER, -1.0);
+ARRDIRX^MULAT(VARPLAYER, -1);
+```
+
+### REMOVEALL
+
+```
+void REMOVEALL()
+```
+
+Removes all elements from the array.
+
+**Examples**
+
+```
+G_ARRSETTINGS^REMOVEALL();
+ARRTEMP^REMOVEALL();
+```
+
+### REMOVEAT
+
+```
+void REMOVEAT(INTEGER index)
+```
+
+Removes the element at position `index`, shifting the remaining elements to the left. Calling with `index` out of range leaves the array unchanged.
+
+**Parameters**
+
+- `index` — position of the element to remove.
+
+**Examples**
+
+```
+ARRTEMP^REMOVEAT(VARITEMP2);
+ARRENEMYROUTEX^REMOVEAT(0);
+```
+
+### REVERSEFIND
+
+```
+INTEGER REVERSEFIND(mixed needle)
+```
+
+Works like [`FIND`](#find), but scans the array from the end. The same type-dependent comparison rules apply.
+
+**Parameters**
+
+- `needle` — the value to search for.
+
+**Returns**: the index of the last matching element, or `-1` if no match was found.
+
+**Examples**
+
+```
+ARRAYKURNIKFREESLOTS^REVERSEFIND(0);
+```
+
+### SAVE
+
+```
+void SAVE(STRING path)
+```
+
+Writes the array's contents to a binary `.ARR` file in the format described in [`LOAD`](#load).
+
+**Parameters**
+
+- `path` — the destination `.ARR` file path in the game's VFS.
+
+**Examples**
+
+```
+G_ARRSETTINGS^SAVE("$COMMON\SETTINGS.ARR");
+ARRPATH^SAVE(["MAPA"+ILEVEL+".ARR"]);
+```
+
+### SAVEINI
+
+```
+void SAVEINI()
+```
+
+Serialises the array's contents to the game's INI file under the key matching this variable's name, as a comma-separated list of values (the format described in [`LOADINI`](#loadini)).
+
+**Examples**
+
+```
+ARRAYPLATFORMOWKAPRZEDMIOTY^SAVEINI();
+```
+
+### SUB
+
+```
+void SUB(mixed value)
+```
+
+Subtracts the argument from every element of the array. Each element is converted to `DOUBLE` before the subtraction; all elements after the call are of type `DOUBLE`.
+
+**Parameters**
+
+- `value` — the value to subtract.
+
+**Examples**
+
+```
+ARRAYBKGA^SUB([0-VARINT2]);
+```
+
+### SUBAT
+
+```
+void SUBAT(INTEGER index, mixed value)
+```
+
+Subtracts the argument from the element at position `index`. Internally, the element and the argument are converted to `DOUBLE`, subtracted, and the result is stored as [`DOUBLE`](DOUBLE.md). Calling with `index` out of range leaves the array unchanged.
+
+**Parameters**
+
+- `index` — element position.
+- `value` — the value to subtract.
+
+**Examples**
+
+```
+ARRBUTTONPRESSED^SUBAT(IBUTTONNR, 1);
+ARRSPEED^SUBAT(VARPLAYER, 0.15);
+```
+
+### SUM
+
+```
+void SUM(mixed value)
+```
+
+Adds the argument to every element of the array. Each element is converted to `DOUBLE` before the addition; all elements after the call are of type `DOUBLE`.
+
+**Parameters**
+
+- `value` — the value to add.
+
+**Examples**
+
+```
+ARRCHICKENX^SUM(-60);
+ARRCHICKENY^SUM(-110);
+```
+
+## Signals
+
+### ONCHANGE
+
+Fired after a modification has been made to the array.
+
+### ONINIT
+
+Fired when the variable is initialised.
+
+### ONDONE
+
+Fired when leaving the scene that owns the variable.
+
+### ONSIGNAL
+
+Fired when a signal arrives (sent via the `SEND` method — see [Events and signals](../engine/events.md#onsignal)).