Finished automatically generated docs

Time to correct it by itself
2026-05-20 22:49:46 +02:00
parent df6cf2f3d3
commit 198d9cf477
35 changed files with 6120 additions and 73 deletions
--- a/docs/pl/reference/MATRIX.md
+++ b/docs/pl/reference/MATRIX.md
@@ -0,0 +1,438 @@
+# 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)).