10 KiB
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, DOUBLE, STRING, and BOOL. Mixed-type arrays are allowed, but some methods interpret elements in non-obvious ways (see the notes on FIND, CONTAINS, and 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 — 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 and compared with the toDisplayString result of each element. This differs from FIND, which compares values according to the engine's typing rules.
Parameters
needle— the value to search for.
Returns: BOOL — 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 — 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; non-numeric elements can contribute unexpected values (BOOL → 1.0 or 0.0, a non-numeric STRING → 0.0).
Returns: the sum as a DOUBLE.
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.ARRfile 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, DOUBLE, BOOL, or STRING — 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. 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. 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, 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.
Parameters
path— the destination.ARRfile 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).
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. 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).