476 lines
11 KiB
Markdown
476 lines
11 KiB
Markdown
# ARRAY
|
|
|
|
Tablica indeksowana od `0`, przechowująca wartości dowolnego typu. Pełna obsługa zapisu i operacji arytmetycznych dotyczy czterech typów prymitywnych: [`INTEGER`](INTEGER.md), [`DOUBLE`](DOUBLE.md), [`STRING`](STRING.md) i [`BOOL`](BOOL.md). Mieszane typy w pojedynczej tablicy są dozwolone, ale niektóre metody mogą interpretować elementy niezgodnie z intuicją (patrz uwagi przy [`FIND`](#find), [`CONTAINS`](#contains) i [`GETSUMVALUE`](#getsumvalue)).
|
|
|
|
## Pola
|
|
|
|
### TOINI
|
|
|
|
```
|
|
BOOL TOINI
|
|
```
|
|
|
|
Określa, czy zawartość tablicy jest serializowana do pliku INI i przywracana po ponownym uruchomieniu.
|
|
|
|
## Metody
|
|
|
|
### ADD
|
|
|
|
```
|
|
void ADD(mixed value1, [mixed value2, ..., mixed valueN])
|
|
```
|
|
|
|
Dodaje przekazane wartości na koniec tablicy. Typy argumentów nie muszą być jednakowe.
|
|
|
|
**Parametry**
|
|
|
|
- `value1, …, valueN` — wartości do dodania.
|
|
|
|
**Przykłady**
|
|
|
|
```
|
|
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)
|
|
```
|
|
|
|
Dodaje argument do elementu na pozycji `index`. Operacja konwertuje element i argument do `DOUBLE`, dodaje, i zapisuje wynik jako [`DOUBLE`](DOUBLE.md) — typ elementu na tej pozycji po wywołaniu zawsze jest `DOUBLE`. Wywołanie z `index` poza zakresem nie zmienia tablicy.
|
|
|
|
**Parametry**
|
|
|
|
- `index` — pozycja elementu (numerowana od `0`).
|
|
- `value` — wartość do dodania.
|
|
|
|
**Przykłady**
|
|
|
|
```
|
|
ARRIDLETIME^ADDAT(0, 1);
|
|
ARRENEMYY^ADDAT(VARITMPINDEX, VARITMP1);
|
|
ARRSPEED^ADDAT(0, 2.0);
|
|
```
|
|
|
|
### CHANGEAT
|
|
|
|
```
|
|
void CHANGEAT(INTEGER index, mixed value)
|
|
```
|
|
|
|
Zastępuje element na pozycji `index` przekazaną wartością. Typ nowego elementu jest zachowywany dokładnie taki, jaki został przekazany. Wywołanie z `index` poza zakresem nie zmienia tablicy.
|
|
|
|
**Parametry**
|
|
|
|
- `index` — pozycja elementu (numerowana od `0`).
|
|
- `value` — nowa wartość.
|
|
|
|
**Przykłady**
|
|
|
|
```
|
|
ARRIDLETIME^CHANGEAT(0, 0);
|
|
G_ARRREXSPELLS^CHANGEAT(VARIREPEATSPELL, 1);
|
|
ARRAYPLAYERSSTATE^CHANGEAT([VARCLONE-1], "NULL");
|
|
```
|
|
|
|
### CLAMPAT
|
|
|
|
```
|
|
void CLAMPAT(INTEGER index, mixed rangeMin, mixed rangeMax)
|
|
```
|
|
|
|
Sprowadza wartość na pozycji `index` do przedziału `[rangeMin, rangeMax]`. Typ elementu jest zachowywany — wartości `INTEGER` pozostają `INTEGER`, wartości `DOUBLE` pozostają `DOUBLE`. Dla elementów innych typów (oraz dla `index` poza zakresem) wywołanie nie zmienia tablicy.
|
|
|
|
**Parametry**
|
|
|
|
- `index` — pozycja elementu (numerowana od `0`).
|
|
- `rangeMin` — dolna granica (włącznie).
|
|
- `rangeMax` — górna granica (włącznie).
|
|
|
|
**Przykłady**
|
|
|
|
```
|
|
ARRSPEED^CLAMPAT(VARPLAYER, 0.0, 100.0);
|
|
ARRSPEED^CLAMPAT(0, 0.0, 17.0);
|
|
```
|
|
|
|
### CONTAINS
|
|
|
|
```
|
|
BOOL CONTAINS(mixed needle)
|
|
```
|
|
|
|
Sprawdza, czy tablica zawiera element o podanej wartości. Porównanie wykonywane jest na poziomie tekstowej reprezentacji elementów — wartość `needle` jest rzutowana do [`STRING`](STRING.md) i porównywana z wynikiem `toDisplayString` każdego elementu. To różni się od `FIND`, które porównuje wartości zgodnie z [regułami arytmetyki silnika](../engine/arithmetic.md#regula-typowania).
|
|
|
|
**Parametry**
|
|
|
|
- `needle` — szukana wartość.
|
|
|
|
**Zwraca**: [`BOOL`](BOOL.md) — `TRUE`, jeżeli element został znaleziony.
|
|
|
|
**Przykłady**
|
|
|
|
```
|
|
ART0^CONTAINS(ICIK);
|
|
ARRAYWARSZTATPRZEDMIOTY^CONTAINS(ARRAYTEMP^GET($1));
|
|
```
|
|
|
|
### COPYTO
|
|
|
|
```
|
|
void COPYTO(STRING arrayVarName)
|
|
```
|
|
|
|
Dokleja zawartość bieżącej tablicy na koniec tablicy o nazwie podanej w argumencie. Tablica docelowa musi już istnieć i być typu `ARRAY`. Tablica docelowa **nie** jest czyszczona przed kopiowaniem.
|
|
|
|
**Parametry**
|
|
|
|
- `arrayVarName` — nazwa docelowej zmiennej tablicowej.
|
|
|
|
**Przykłady**
|
|
|
|
```
|
|
ARAG^COPYTO("ARTMP");
|
|
```
|
|
|
|
### FIND
|
|
|
|
```
|
|
INTEGER FIND(mixed needle)
|
|
```
|
|
|
|
Wyszukuje w tablicy pierwszy element równy podanej wartości. Porównanie wykonywane jest zgodnie z [regułami arytmetyki silnika](../engine/arithmetic.md#regula-typowania) — typ elementu w tablicy wyznacza, do jakiego typu rzutowana jest wartość `needle` w danej iteracji. Skutkuje to nieintuicyjnymi wynikami w tablicach mieszanych typów, np. wyszukiwanie `240` w tablicy zawierającej `TRUE` zwróci indeks elementu `TRUE`, ponieważ `240` zostaje rzutowane do `BOOL` (wartość różna od zera, czyli `TRUE`).
|
|
|
|
**Parametry**
|
|
|
|
- `needle` — szukana wartość.
|
|
|
|
**Zwraca**: indeks pierwszego dopasowanego elementu, lub `-1`, jeżeli element nie został znaleziony.
|
|
|
|
**Przykłady**
|
|
|
|
```
|
|
G_ARRCUTSCENES^FIND(G_SCUTSCENE);
|
|
ARRSTARTNAME0^FIND("NULL");
|
|
ARRCLONES^FIND(-1);
|
|
```
|
|
|
|
### GET
|
|
|
|
```
|
|
mixed GET(INTEGER index)
|
|
```
|
|
|
|
Zwraca element na pozycji `index`. Dla `index` poza zakresem zwracana jest wartość `NULL`.
|
|
|
|
**Parametry**
|
|
|
|
- `index` — pozycja elementu (numerowana od `0`).
|
|
|
|
**Zwraca**: wartość elementu lub `NULL`.
|
|
|
|
**Przykłady**
|
|
|
|
```
|
|
ARRIDLETIME^GET(0);
|
|
ARRACTIVESPELLS^GET(_I_);
|
|
ARRAYPLAYERSSTATE^GET([VARCLONE-1]);
|
|
```
|
|
|
|
### GETSIZE
|
|
|
|
```
|
|
INTEGER GETSIZE()
|
|
```
|
|
|
|
Zwraca liczbę elementów w tablicy.
|
|
|
|
**Zwraca**: rozmiar tablicy.
|
|
|
|
**Przykłady**
|
|
|
|
```
|
|
G_ARRSETTINGS^GETSIZE();
|
|
ARRENEMYROUTEX^GETSIZE();
|
|
```
|
|
|
|
### GETSUMVALUE
|
|
|
|
```
|
|
DOUBLE GETSUMVALUE()
|
|
```
|
|
|
|
Zwraca sumę wartości wszystkich elementów tablicy. Każdy element jest rzutowany do `DOUBLE` zgodnie z [regułami konwersji](../engine/arithmetic.md#konwersje-typow); elementy nienumeryczne mogą wnosić niespodziewane wartości (`BOOL` → `1.0` lub `0.0`, [`STRING`](STRING.md) nie będący liczbą → `0.0`).
|
|
|
|
**Zwraca**: suma wartości jako [`DOUBLE`](DOUBLE.md).
|
|
|
|
**Przykłady**
|
|
|
|
```
|
|
ARCONTAINER^GETSUMVALUE();
|
|
```
|
|
|
|
### INSERTAT
|
|
|
|
```
|
|
void INSERTAT(INTEGER index, mixed value)
|
|
```
|
|
|
|
Wstawia wartość na pozycji `index`, przesuwając istniejące elementy w prawo. Dopuszczalne wartości `index` to `[0, rozmiar]` — wstawienie na pozycji równej rozmiarowi tablicy dokleja element na koniec. Wywołanie z `index` poza tym zakresem nie zmienia tablicy.
|
|
|
|
**Parametry**
|
|
|
|
- `index` — pozycja wstawienia.
|
|
- `value` — wstawiana wartość.
|
|
|
|
**Przykłady**
|
|
|
|
```
|
|
ARRTURNIEJ^INSERTAT(I3, I1);
|
|
ARRTURNIEJ^INSERTAT(4, I1);
|
|
```
|
|
|
|
### LOAD
|
|
|
|
```
|
|
void LOAD(STRING path)
|
|
```
|
|
|
|
Zastępuje zawartość tablicy danymi wczytanymi z binarnego pliku `.ARR`. Plik zapisany jest w little-endian: 4-bajtowa liczba elementów, a następnie dla każdego elementu 4-bajtowy znacznik typu (`1`=`INTEGER`, `2`=`STRING`, `3`=`BOOL`, `4`=`DOUBLE`) i odpowiadająca mu reprezentacja wartości.
|
|
|
|
**Parametry**
|
|
|
|
- `path` — ścieżka pliku `.ARR` w VFS gry.
|
|
|
|
**Przykłady**
|
|
|
|
```
|
|
G_ARRSETTINGS^LOAD("$COMMON\SETTINGS.ARR");
|
|
ARRPATH^LOAD(["MAPA"+ILEVEL+".ARR"]);
|
|
```
|
|
|
|
### LOADINI
|
|
|
|
```
|
|
void LOADINI()
|
|
```
|
|
|
|
Zastępuje zawartość tablicy danymi zserializowanymi w pliku INI gry pod kluczem o nazwie tej zmiennej. Format zapisu w INI to lista wartości oddzielonych przecinkami:
|
|
|
|
```
|
|
NAZWA_TABLICY=wartość1,wartość2,wartość3,...
|
|
```
|
|
|
|
Każdy element jest interpretowany kolejno jako [`INTEGER`](INTEGER.md), [`DOUBLE`](DOUBLE.md), [`BOOL`](BOOL.md) lub [`STRING`](STRING.md) — pierwszy pasujący typ zostaje przyjęty.
|
|
|
|
**Przykłady**
|
|
|
|
```
|
|
ARRAYWARSZTATMENUPRZEDMIOTY^LOADINI();
|
|
```
|
|
|
|
### MODAT
|
|
|
|
```
|
|
void MODAT(INTEGER index, mixed divisor)
|
|
```
|
|
|
|
Zapisuje resztę z dzielenia elementu na pozycji `index` przez argument. Operacja konwertuje element i argument do `DOUBLE`, wykonuje modulo, i zapisuje wynik jako [`DOUBLE`](DOUBLE.md). Dzielenie przez zero oraz wywołanie z `index` poza zakresem nie zmieniają tablicy.
|
|
|
|
**Parametry**
|
|
|
|
- `index` — pozycja elementu.
|
|
- `divisor` — dzielnik.
|
|
|
|
**Przykłady**
|
|
|
|
```
|
|
ARRANGLE^MODAT(VARPLAYER, 360);
|
|
```
|
|
|
|
### MULAT
|
|
|
|
```
|
|
void MULAT(INTEGER index, mixed multiplier)
|
|
```
|
|
|
|
Mnoży element na pozycji `index` przez argument. Operacja konwertuje element i argument do `DOUBLE`, mnoży, i zapisuje wynik jako [`DOUBLE`](DOUBLE.md). Wywołanie z `index` poza zakresem nie zmienia tablicy.
|
|
|
|
**Parametry**
|
|
|
|
- `index` — pozycja elementu.
|
|
- `multiplier` — mnożnik.
|
|
|
|
**Przykłady**
|
|
|
|
```
|
|
ARRDIRY^MULAT(VARPLAYER, -1.0);
|
|
ARRDIRX^MULAT(VARPLAYER, -1);
|
|
```
|
|
|
|
### REMOVEALL
|
|
|
|
```
|
|
void REMOVEALL()
|
|
```
|
|
|
|
Usuwa wszystkie elementy z tablicy.
|
|
|
|
**Przykłady**
|
|
|
|
```
|
|
G_ARRSETTINGS^REMOVEALL();
|
|
ARRTEMP^REMOVEALL();
|
|
```
|
|
|
|
### REMOVEAT
|
|
|
|
```
|
|
void REMOVEAT(INTEGER index)
|
|
```
|
|
|
|
Usuwa element na pozycji `index`, przesuwając pozostałe w lewo. Wywołanie z `index` poza zakresem nie zmienia tablicy.
|
|
|
|
**Parametry**
|
|
|
|
- `index` — pozycja usuwanego elementu.
|
|
|
|
**Przykłady**
|
|
|
|
```
|
|
ARRTEMP^REMOVEAT(VARITEMP2);
|
|
ARRENEMYROUTEX^REMOVEAT(0);
|
|
```
|
|
|
|
### REVERSEFIND
|
|
|
|
```
|
|
INTEGER REVERSEFIND(mixed needle)
|
|
```
|
|
|
|
Działa jak [`FIND`](#find), ale przeszukuje tablicę od końca. Stosują się te same reguły porównań zależnych od typu elementu.
|
|
|
|
**Parametry**
|
|
|
|
- `needle` — szukana wartość.
|
|
|
|
**Zwraca**: indeks ostatniego dopasowanego elementu, lub `-1`, jeżeli element nie został znaleziony.
|
|
|
|
**Przykłady**
|
|
|
|
```
|
|
ARRAYKURNIKFREESLOTS^REVERSEFIND(0);
|
|
```
|
|
|
|
### SAVE
|
|
|
|
```
|
|
void SAVE(STRING path)
|
|
```
|
|
|
|
Zapisuje zawartość tablicy do binarnego pliku `.ARR` w formacie opisanym przy [`LOAD`](#load).
|
|
|
|
**Parametry**
|
|
|
|
- `path` — ścieżka docelowego pliku `.ARR` w VFS gry.
|
|
|
|
**Przykłady**
|
|
|
|
```
|
|
G_ARRSETTINGS^SAVE("$COMMON\SETTINGS.ARR");
|
|
ARRPATH^SAVE(["MAPA"+ILEVEL+".ARR"]);
|
|
```
|
|
|
|
### SAVEINI
|
|
|
|
```
|
|
void SAVEINI()
|
|
```
|
|
|
|
Serializuje zawartość tablicy do pliku INI gry pod kluczem o nazwie tej zmiennej, w formacie listy wartości rozdzielonych przecinkami (opisany przy [`LOADINI`](#loadini)).
|
|
|
|
**Przykłady**
|
|
|
|
```
|
|
ARRAYPLATFORMOWKAPRZEDMIOTY^SAVEINI();
|
|
```
|
|
|
|
### SUB
|
|
|
|
```
|
|
void SUB(mixed value)
|
|
```
|
|
|
|
Odejmuje argument od każdego elementu tablicy. Operacja konwertuje każdy element do `DOUBLE` przed odjęciem; wszystkie elementy po wywołaniu mają typ `DOUBLE`.
|
|
|
|
**Parametry**
|
|
|
|
- `value` — wartość odejmowana.
|
|
|
|
**Przykłady**
|
|
|
|
```
|
|
ARRAYBKGA^SUB([0-VARINT2]);
|
|
```
|
|
|
|
### SUBAT
|
|
|
|
```
|
|
void SUBAT(INTEGER index, mixed value)
|
|
```
|
|
|
|
Odejmuje argument od elementu na pozycji `index`. Operacja konwertuje element i argument do `DOUBLE`, odejmuje, i zapisuje wynik jako [`DOUBLE`](DOUBLE.md). Wywołanie z `index` poza zakresem nie zmienia tablicy.
|
|
|
|
**Parametry**
|
|
|
|
- `index` — pozycja elementu.
|
|
- `value` — wartość odejmowana.
|
|
|
|
**Przykłady**
|
|
|
|
```
|
|
ARRBUTTONPRESSED^SUBAT(IBUTTONNR, 1);
|
|
ARRSPEED^SUBAT(VARPLAYER, 0.15);
|
|
```
|
|
|
|
### SUM
|
|
|
|
```
|
|
void SUM(mixed value)
|
|
```
|
|
|
|
Dodaje argument do każdego elementu tablicy. Operacja konwertuje każdy element do `DOUBLE` przed dodaniem; wszystkie elementy po wywołaniu mają typ `DOUBLE`.
|
|
|
|
**Parametry**
|
|
|
|
- `value` — wartość dodawana.
|
|
|
|
**Przykłady**
|
|
|
|
```
|
|
ARRCHICKENX^SUM(-60);
|
|
ARRCHICKENY^SUM(-110);
|
|
```
|
|
|
|
## Sygnały
|
|
|
|
### ONCHANGE
|
|
|
|
Wywoływany po dokonaniu zmiany w tablicy.
|
|
|
|
### ONINIT
|
|
|
|
Wywoływany w momencie inicjalizacji zmiennej.
|
|
|
|
### ONDONE
|
|
|
|
Wywoływany w momencie wychodzenia ze sceny, do której należy zmienna.
|
|
|
|
### ONSIGNAL
|
|
|
|
Wywoływany po otrzymaniu sygnału (przez wywołanie metody `SEND` — zobacz [Zdarzenia i sygnały](../engine/events.md#onsignal)).
|