439 lines
11 KiB
Markdown
439 lines
11 KiB
Markdown
# MATRIX
|
||
|
||
Plansza złożona z prostokątnej siatki pól z prostym systemem fizyki kamieni i prymitywnym wyznaczaniem ruchu przeciwników. Zaprojektowany pod jeden, konkretny przypadek użycia — minigrę z podkopem (sekcje Kretesa w *Reksio i Ufo*: mur na Indorze oraz podkop do więzienia na Kuranie).
|
||
|
||
Dane planszy są przechowywane jako jednowymiarowa tablica liczb całkowitych — adres pola wyznacza się ze wzoru `index = y * width + x`. Stąd obecność metod konwertujących indeks na pozycję 2D i odwrotnie.
|
||
|
||
## Kody pól {#kody-pol}
|
||
|
||
Wartości używane przez metody [`GET`](#get), [`GETCELLSNO`](#getcellsno), [`SET`](#set), [`SETROW`](#setrow) i wewnętrzny system fizyki:
|
||
|
||
| Kod | Znaczenie |
|
||
| --- | --- |
|
||
| `0` | puste pole |
|
||
| `1` | grunt |
|
||
| `2` | kamień |
|
||
| `3` | laska dynamitu |
|
||
| `4` | wyburzalna ściana |
|
||
| `5` | przeciwnik |
|
||
| `6` | nierozbijalna ściana |
|
||
| `7` | odpalona laska dynamitu |
|
||
| `8` | pole w zasięgu eksplozji |
|
||
| `9` | wyjście |
|
||
| `99` | pozycja Kretesa |
|
||
|
||
## Kody kierunku ruchu {#kody-kierunku-ruchu}
|
||
|
||
Wartości używane przez [`TICK`](#tick), [`NEXT`](#next) i [`CALCENEMYMOVEDIR`](#calcenemymovedir):
|
||
|
||
| Kod | Kierunek |
|
||
| --- | --- |
|
||
| `0` | w lewo |
|
||
| `1` | w górę |
|
||
| `2` | w prawo |
|
||
| `3` | w dół |
|
||
|
||
Wewnętrzny system fizyki używa dodatkowych kodów zwracanych przez [`TICK`](#tick) i odczytywanych przez [`NEXT`](#next):
|
||
|
||
| Kod | Operacja |
|
||
| --- | --- |
|
||
| `1` | kamień spada w dół |
|
||
| `2` | kamień spada w lewo po skosie |
|
||
| `3` | kamień spada w prawo po skosie |
|
||
| `4` | kamień z przeciwnikiem eksplodują |
|
||
|
||
## Pola
|
||
|
||
### BASEPOS
|
||
|
||
```
|
||
INTEGER, INTEGER BASEPOS
|
||
```
|
||
|
||
Pozycja lewego górnego rogu planszy na ekranie w pikselach (`X,Y`).
|
||
|
||
### CELLHEIGHT
|
||
|
||
```
|
||
INTEGER CELLHEIGHT
|
||
```
|
||
|
||
Wysokość pojedynczego pola w pikselach.
|
||
|
||
### CELLWIDTH
|
||
|
||
```
|
||
INTEGER CELLWIDTH
|
||
```
|
||
|
||
Szerokość pojedynczego pola w pikselach.
|
||
|
||
### SIZE
|
||
|
||
```
|
||
INTEGER, INTEGER SIZE
|
||
```
|
||
|
||
Wymiary planszy w polach (`szerokość,wysokość`). Wartość wyznacza również rozmiar wewnętrznej tablicy z kodami pól.
|
||
|
||
## Metody
|
||
|
||
### CALCENEMYMOVEDEST
|
||
|
||
```
|
||
INTEGER CALCENEMYMOVEDEST(INTEGER oldCell, INTEGER direction)
|
||
```
|
||
|
||
Wylicza indeks pola, na które przeciwnik przejdzie z pola `oldCell` przy ruchu w kierunku `direction`. Jeśli pole docelowe znajduje się poza planszą lub nie jest puste, zwracany jest niezmieniony `oldCell`.
|
||
|
||
**Parametry**
|
||
|
||
- `oldCell` — bieżąca pozycja przeciwnika (indeks pola).
|
||
- `direction` — kierunek ruchu (`0`–`3`, zobacz [Kody kierunku ruchu](#kody-kierunku-ruchu)).
|
||
|
||
**Zwraca**: [`INTEGER`](INTEGER.md) — indeks pola docelowego.
|
||
|
||
**Przykłady**
|
||
|
||
```
|
||
MAT^CALCENEMYMOVEDEST(IENOLDCELL,IENNEWDIR);
|
||
```
|
||
|
||
### CALCENEMYMOVEDIR
|
||
|
||
```
|
||
INTEGER CALCENEMYMOVEDIR(INTEGER oldCell, INTEGER oldDir)
|
||
```
|
||
|
||
Wylicza kierunek ruchu przeciwnika. Algorytm preferuje skręt w lewo: w pierwszej kolejności sprawdzany jest kierunek `(oldDir+3) MOD 4`, następnie `oldDir`, dalej w prawo i wreszcie do tyłu. Zwracany jest pierwszy kierunek, dla którego pole docelowe jest puste; jeżeli żaden nie jest dostępny — preferowany skręt w lewo.
|
||
|
||
**Parametry**
|
||
|
||
- `oldCell` — bieżąca pozycja przeciwnika.
|
||
- `oldDir` — kierunek ruchu z poprzedniego kroku.
|
||
|
||
**Zwraca**: [`INTEGER`](INTEGER.md) — nowy kierunek ruchu.
|
||
|
||
**Przykłady**
|
||
|
||
```
|
||
MAT^CALCENEMYMOVEDIR(IENOLDCELL,IENOLDDIR);
|
||
```
|
||
|
||
### CANHEROGOTO
|
||
|
||
```
|
||
BOOL CANHEROGOTO(INTEGER cellNo)
|
||
```
|
||
|
||
Sprawdza, czy główny bohater może wejść na podane pole. Pole jest przejezdne, jeżeli nie zawiera słabej ściany, mocnej ściany, przeciwnika ani kamienia, a także nie należy do obszaru bramy ustawionej metodą [`SETGATE`](#setgate).
|
||
|
||
**Parametry**
|
||
|
||
- `cellNo` — indeks sprawdzanego pola.
|
||
|
||
**Zwraca**: [`BOOL`](BOOL.md) — `TRUE`, jeżeli pole jest przejezdne.
|
||
|
||
**Przykłady**
|
||
|
||
```
|
||
MAT^CANHEROGOTO(I_0);
|
||
```
|
||
|
||
### GET
|
||
|
||
```
|
||
INTEGER GET(INTEGER cellNo)
|
||
```
|
||
|
||
Zwraca kod pola o podanym indeksie. Dla indeksów spoza zakresu zwraca `0`.
|
||
|
||
**Parametry**
|
||
|
||
- `cellNo` — indeks pola.
|
||
|
||
**Zwraca**: [`INTEGER`](INTEGER.md) — kod pola (zobacz [Kody pól](#kody-pol)).
|
||
|
||
**Przykłady**
|
||
|
||
```
|
||
MAT^GET(I_ITERATOR);
|
||
MAT^GET(I_MOLE_FIELD_CURR);
|
||
```
|
||
|
||
### GETCELLOFFSET
|
||
|
||
```
|
||
INTEGER GETCELLOFFSET(INTEGER x, INTEGER y)
|
||
```
|
||
|
||
Zwraca indeks pola na podstawie współrzędnych `(x, y)`. Dla współrzędnych spoza planszy zwracane jest `-1`.
|
||
|
||
**Parametry**
|
||
|
||
- `x`, `y` — koordynaty pola.
|
||
|
||
**Zwraca**: [`INTEGER`](INTEGER.md) — indeks pola lub `-1`.
|
||
|
||
**Przykłady**
|
||
|
||
```
|
||
MAT^GETCELLOFFSET(ISSRCX,ISSRCY);
|
||
MAT^GETCELLOFFSET(ISTRGX,ISTRGY);
|
||
```
|
||
|
||
### GETCELLPOSX
|
||
|
||
```
|
||
INTEGER GETCELLPOSX(INTEGER cellNo)
|
||
```
|
||
|
||
Zwraca pozycję X pola w pikselach (`BASEPOS.X + col * CELLWIDTH`).
|
||
|
||
**Parametry**
|
||
|
||
- `cellNo` — indeks pola.
|
||
|
||
**Zwraca**: [`INTEGER`](INTEGER.md) — koordynata X w pikselach.
|
||
|
||
### GETCELLPOSY
|
||
|
||
```
|
||
INTEGER GETCELLPOSY(INTEGER cellNo)
|
||
```
|
||
|
||
Zwraca pozycję Y pola w pikselach (`BASEPOS.Y + row * CELLHEIGHT`).
|
||
|
||
**Parametry**
|
||
|
||
- `cellNo` — indeks pola.
|
||
|
||
**Zwraca**: [`INTEGER`](INTEGER.md) — koordynata Y w pikselach.
|
||
|
||
### GETCELLSNO
|
||
|
||
```
|
||
INTEGER GETCELLSNO(INTEGER cellCode)
|
||
```
|
||
|
||
Zwraca liczbę pól z podanym kodem.
|
||
|
||
**Parametry**
|
||
|
||
- `cellCode` — kod pola, którego wystąpienia mają zostać policzone.
|
||
|
||
**Zwraca**: [`INTEGER`](INTEGER.md) — liczba pól o podanym kodzie.
|
||
|
||
**Przykłady**
|
||
|
||
```
|
||
MAT^GETCELLSNO(IC_FIELD_CODE_EXIT);
|
||
MAT^GETCELLSNO(IC_FIELD_CODE_ENEMY);
|
||
```
|
||
|
||
### GETFIELDPOSX
|
||
|
||
```
|
||
INTEGER GETFIELDPOSX(INTEGER cellNo)
|
||
```
|
||
|
||
Alias [`GETCELLPOSX`](#getcellposx) używany w *Reksio i Ufo* z silnikiem Piklib 7.1. W Piklib 8 metoda nie jest już udostępniana — próba jej wywołania w nowszej wersji powoduje awarię silnika.
|
||
|
||
**Parametry**
|
||
|
||
- `cellNo` — indeks pola.
|
||
|
||
**Zwraca**: [`INTEGER`](INTEGER.md) — koordynata X w pikselach.
|
||
|
||
### GETFIELDPOSY
|
||
|
||
```
|
||
INTEGER GETFIELDPOSY(INTEGER cellNo)
|
||
```
|
||
|
||
Alias [`GETCELLPOSY`](#getcellposy) używany w *Reksio i Ufo* z silnikiem Piklib 7.1. W Piklib 8 metoda nie jest już udostępniana — próba jej wywołania w nowszej wersji powoduje awarię silnika.
|
||
|
||
**Parametry**
|
||
|
||
- `cellNo` — indeks pola.
|
||
|
||
**Zwraca**: [`INTEGER`](INTEGER.md) — koordynata Y w pikselach.
|
||
|
||
### GETOFFSET
|
||
|
||
```
|
||
INTEGER GETOFFSET(INTEGER x, INTEGER y)
|
||
```
|
||
|
||
Alias [`GETCELLOFFSET`](#getcelloffset) używany w *Reksio i Ufo* z silnikiem Piklib 7.1. W Piklib 8 metoda została zastąpiona przez `GETCELLOFFSET`.
|
||
|
||
**Parametry**
|
||
|
||
- `x`, `y` — koordynaty pola.
|
||
|
||
**Zwraca**: [`INTEGER`](INTEGER.md) — indeks pola lub `-1`.
|
||
|
||
### ISGATEEMPTY
|
||
|
||
```
|
||
BOOL ISGATEEMPTY()
|
||
```
|
||
|
||
Sprawdza, czy wszystkie pola w obszarze bramy ustawionej metodą [`SETGATE`](#setgate) mają kod `0` (puste). Jeśli brama nie została ustawiona, zwracane jest `FALSE`.
|
||
|
||
**Zwraca**: [`BOOL`](BOOL.md) — `TRUE`, jeżeli wszystkie pola bramy są puste.
|
||
|
||
**Przykłady**
|
||
|
||
```
|
||
MAT^ISGATEEMPTY();
|
||
```
|
||
|
||
### ISINGATE
|
||
|
||
```
|
||
BOOL ISINGATE(INTEGER cellNo)
|
||
```
|
||
|
||
Sprawdza, czy pole o podanym indeksie należy do obszaru bramy ustawionej metodą [`SETGATE`](#setgate).
|
||
|
||
**Parametry**
|
||
|
||
- `cellNo` — indeks pola.
|
||
|
||
**Zwraca**: [`BOOL`](BOOL.md) — `TRUE`, jeżeli pole znajduje się w obszarze bramy.
|
||
|
||
### MOVE
|
||
|
||
```
|
||
void MOVE(INTEGER oldCell, INTEGER newCell)
|
||
```
|
||
|
||
Przesuwa zawartość pola źródłowego na pole docelowe; pole źródłowe pozostaje puste (kod `0`).
|
||
|
||
**Parametry**
|
||
|
||
- `oldCell` — indeks pola źródłowego.
|
||
- `newCell` — indeks pola docelowego.
|
||
|
||
**Przykłady**
|
||
|
||
```
|
||
MAT^MOVE(I_0,I_1);
|
||
```
|
||
|
||
### NEXT
|
||
|
||
```
|
||
INTEGER NEXT()
|
||
```
|
||
|
||
Wykonuje kolejny zaplanowany ruch z kolejki wygenerowanej przez [`TICK`](#tick). Pole źródłowe jest czyszczone, a pole docelowe otrzymuje kod kamienia. Po wykonaniu ruchu emitowany jest sygnał [`ONNEXT`](#onnext) (dla wszystkich ruchów oprócz ostatniego) lub [`ONLATEST`](#onlatest) (dla ostatniego ruchu z kolejki).
|
||
|
||
**Zwraca**: [`INTEGER`](INTEGER.md) — `0`, jeżeli kolejka jest pusta; `1` przy zwykłym ruchu kamienia; `2`, jeśli kamień wylądował dwa pola nad Kretesem (kolizja).
|
||
|
||
**Przykłady**
|
||
|
||
```
|
||
MAT^NEXT();
|
||
```
|
||
|
||
### SET
|
||
|
||
```
|
||
void SET(INTEGER cellNo, INTEGER cellCode)
|
||
void SET(INTEGER x, INTEGER y, INTEGER cellCode)
|
||
```
|
||
|
||
Ustawia kod pola. Metoda ma dwie formy: pierwsza przyjmuje gotowy indeks pola, druga — współrzędne `(x, y)`.
|
||
|
||
**Parametry**
|
||
|
||
- `cellNo` — indeks pola **(forma 1)**.
|
||
- `x`, `y` — koordynaty pola **(forma 2)**.
|
||
- `cellCode` — nowa wartość pola (zobacz [Kody pól](#kody-pol)).
|
||
|
||
**Przykłady**
|
||
|
||
```
|
||
MAT^SET(I_MOLE_FIELD_CURR,IC_FIELD_CODE_EMPTY);
|
||
MAT^SET([I_FIELD_INDEX%I_LEVEL_WIDTH],[I_FIELD_INDEX@I_LEVEL_WIDTH],IC_FIELD_CODE_EMPTY);
|
||
```
|
||
|
||
### SETGATE
|
||
|
||
```
|
||
void SETGATE(INTEGER startX, INTEGER startY, INTEGER endX, INTEGER endY)
|
||
```
|
||
|
||
Wyznacza prostokątny obszar bramy określony przez współrzędne początkowego i końcowego pola (włącznie). Brama wpływa na działanie metod [`CANHEROGOTO`](#canherogoto), [`ISGATEEMPTY`](#isgateempty) oraz [`ISINGATE`](#isingate).
|
||
|
||
**Parametry**
|
||
|
||
- `startX`, `startY` — koordynaty lewego górnego rogu obszaru bramy.
|
||
- `endX`, `endY` — koordynaty prawego dolnego rogu obszaru bramy.
|
||
|
||
**Przykłady**
|
||
|
||
```
|
||
MAT^SETGATE(3,1,16,4);
|
||
```
|
||
|
||
### SETROW
|
||
|
||
```
|
||
void SETROW(INTEGER row, INTEGER cellCode1, [INTEGER cellCode2, ...])
|
||
```
|
||
|
||
Ustawia kody pól w podanym wierszu. Kolejne argumenty są wpisywane do pól od kolumny `0` w prawo; nadmiarowe argumenty (więcej niż szerokość planszy) są ignorowane.
|
||
|
||
**Parametry**
|
||
|
||
- `row` — indeks wiersza.
|
||
- `cellCode1`, `cellCode2`, … — kolejne kody pól w wierszu.
|
||
|
||
**Przykłady**
|
||
|
||
```
|
||
MAT^SETROW(0,6,6,6,6,6,6,6,6,6,6,6,6,6,6,6,6,6,6,6,6);
|
||
MAT^SETROW(1,6,6,6,2,2,2,2,2,2,2,2,2,2,2,2,2,2,6,6,6);
|
||
```
|
||
|
||
### TICK
|
||
|
||
```
|
||
void TICK()
|
||
```
|
||
|
||
Wykonuje jedno tyknięcie wewnętrznego systemu fizyki. Plansza jest skanowana od dołu do góry, od lewej do prawej. Dla każdego kamienia sprawdzane są kolejno:
|
||
|
||
1. Czy pod kamieniem jest puste pole — zaplanowanie ruchu w dół.
|
||
2. Czy pod kamieniem znajduje się przeciwnik — zaplanowanie eksplozji.
|
||
3. Czy obok kamienia leży inny kamień, a pola na ukos w lewo lub w prawo są puste — zaplanowanie zsuwu po skosie.
|
||
|
||
Ruchy są zapisywane do wewnętrznej kolejki i wykonywane kolejno przez wywołania [`NEXT`](#next). Każdy wpis zawiera koordynatę X i Y pola źródłowego oraz kod operacji.
|
||
|
||
**Przykłady**
|
||
|
||
```
|
||
MAT^TICK();
|
||
```
|
||
|
||
## Sygnały
|
||
|
||
### ONINIT
|
||
|
||
Wywoływany w momencie inicjalizacji obiektu.
|
||
|
||
### ONNEXT
|
||
|
||
Wywoływany przez [`NEXT`](#next) po wykonaniu ruchu, który nie był ostatnim w bieżącej kolejce. Argumentami sygnału są: koordynata X (`$1`), koordynata Y (`$2`) i kod operacji (`$3`) pola źródłowego.
|
||
|
||
### ONLATEST
|
||
|
||
Wywoływany przez [`NEXT`](#next) po wykonaniu ostatniego ruchu z bieżącej kolejki. Argumenty sygnału są identyczne jak w [`ONNEXT`](#onnext).
|
||
|
||
### ONSIGNAL
|
||
|
||
Wywoływany po otrzymaniu sygnału (zobacz [Zdarzenia i sygnały](../engine/events.md#onsignal)).
|