Added part of docs
Some checks failed
docs / deploy (push) Has been cancelled
docs / build (push) Has been cancelled

This commit is contained in:
Patryk Gensch
2026-05-19 20:51:59 +02:00
parent e91fd2e42a
commit df6cf2f3d3
66 changed files with 11821 additions and 0 deletions

875
docs/pl/reference/ANIMO.md Normal file
View File

@@ -0,0 +1,875 @@
# ANIMO
Animacja wczytywana z pliku `.ANN`. Najbardziej rozbudowany typ wizualny w silniku — obsługuje wiele zdarzeń (sekwencji klatek), zmianę FPS-u, kotwicę punktu zaczepienia, przezroczystość, monitorowanie kolizji oraz tryb przycisku.
Animacja składa się z **zdarzeń** (`event`), z których każde jest sekwencją **klatek** (`frame`). Numer klatki w zdarzeniu liczony jest od `0`, a indeks globalny klatki w całej animacji liczony jest od `0` osobno.
## Pola
### ASBUTTON
```
BOOL ASBUTTON
```
Traktuje animację jako klikalny przycisk. Modyfikowane przez metodę [`SETASBUTTON`](#setasbutton).
### FILENAME
```
STRING FILENAME
```
Nazwa pliku `.ANN` z animacją. Pole odczytywane podczas inicjalizacji zmiennej; może być nadpisane metodą [`LOAD`](#load).
### FPS
```
INTEGER FPS
```
Liczba klatek animacji na sekundę. Modyfikowane przez metodę [`SETFPS`](#setfps).
### MONITORCOLLISION
```
BOOL MONITORCOLLISION
```
Określa, czy animacja uczestniczy w detekcji kolizji. Modyfikowane przez metody [`MONITORCOLLISION`](#monitorcollision-1) i [`REMOVEMONITORCOLLISION`](#removemonitorcollision).
### MONITORCOLLISIONALPHA
```
BOOL MONITORCOLLISIONALPHA
```
Określa, czy w detekcji kolizji uwzględniany jest kanał przezroczystości.
### PRELOAD
```
BOOL PRELOAD
```
Określa, czy dane animacji mają być załadowane od razu przy inicjalizacji.
### PRIORITY
```
INTEGER PRIORITY
```
Priorytet renderowania (`Z`) względem innych obiektów na scenie.
### TOCANVAS
```
BOOL TOCANVAS
```
Określa, czy animacja jest rysowana na głównej kanwie sceny. Ustawienie `FALSE` ukrywa animację wizualnie, ale silnik nadal ją odtwarza i emituje powiązane zdarzenia.
### VISIBLE
```
BOOL VISIBLE
```
Widoczność animacji. Modyfikowana metodami [`SHOW`](#show) i [`HIDE`](#hide).
## Metody
### GETANCHOR
```
STRING GETANCHOR()
```
Zwraca aktualnie ustawioną kotwicę animacji w postaci, w jakiej została przekazana do [`SETANCHOR`](#setanchor).
**Zwraca**: nazwa kotwicy lub jej współrzędne.
### GETCENTERX
```
INTEGER GETCENTERX()
```
Zwraca współrzędną X środka bounding boxa aktualnej klatki animacji.
**Zwraca**: środek X.
**Przykłady**
```
ANNREX^GETCENTERX();
```
### GETCENTERY
```
INTEGER GETCENTERY()
```
Zwraca współrzędną Y środka bounding boxa aktualnej klatki animacji.
**Zwraca**: środek Y.
### GETCFRAMEINEVENT
```
INTEGER GETCFRAMEINEVENT()
```
Zwraca numer bieżącej klatki wewnątrz aktualnie odtwarzanego zdarzenia (licząc od `0`).
**Zwraca**: indeks klatki w zdarzeniu.
**Przykłady**
```
ANNREX^GETCFRAMEINEVENT();
```
### GETCURRFRAMEPOSX
```
INTEGER GETCURRFRAMEPOSX()
```
Zwraca przesunięcie w osi X dla aktualnie wyświetlanego obrazka (per-klatkowe, definiowane w pliku animacji).
**Zwraca**: przesunięcie X obrazka.
### GETCURRFRAMEPOSY
```
INTEGER GETCURRFRAMEPOSY()
```
Zwraca przesunięcie w osi Y dla aktualnie wyświetlanego obrazka.
**Zwraca**: przesunięcie Y obrazka.
### GETENDX
```
INTEGER GETENDX()
```
Zwraca prawą krawędź bounding boxa aktualnej klatki.
**Zwraca**: prawa krawędź X.
### GETENDY
```
INTEGER GETENDY()
```
Zwraca dolną krawędź bounding boxa aktualnej klatki.
**Zwraca**: dolna krawędź Y.
### GETEVENTNAME
```
STRING GETEVENTNAME()
```
Zwraca nazwę aktualnie odtwarzanego zdarzenia.
**Zwraca**: nazwa zdarzenia.
**Przykłady**
```
ANNREX^GETEVENTNAME();
```
### GETFRAME
```
INTEGER GETFRAME()
```
Zwraca globalny indeks aktualnie odtwarzanej klatki (niezależny od podziału na zdarzenia).
**Zwraca**: globalny indeks klatki.
### GETFRAMENAME
```
STRING GETFRAMENAME()
```
Zwraca nazwę aktualnie odtwarzanej klatki (nazwa pliku obrazka).
**Zwraca**: nazwa klatki.
### GETHEIGHT
```
INTEGER GETHEIGHT()
```
Zwraca wysokość aktualnej klatki animacji.
**Zwraca**: wysokość w pikselach.
### GETMAXHEIGHT
```
INTEGER GETMAXHEIGHT()
```
Zwraca maksymalną wysokość spośród wszystkich klatek animacji.
**Zwraca**: największa wysokość w pikselach.
### GETMAXWIDTH
```
INTEGER GETMAXWIDTH()
```
Zwraca maksymalną szerokość spośród wszystkich klatek animacji.
**Zwraca**: największa szerokość w pikselach.
**Przykłady**
```
ANN_STATEK^GETMAXWIDTH();
```
### GETNAME
```
STRING GETNAME()
```
Zwraca nazwę zmiennej animacji.
**Zwraca**: nazwa zmiennej.
### GETNOE
```
INTEGER GETNOE()
```
Zwraca liczbę zdarzeń w animacji (skrót od *Number Of Events*).
**Zwraca**: liczba zdarzeń.
**Przykłady**
```
ANNLISCIESLOTY^GETNOE();
ANNBTN^GETNOE();
```
### GETNOF
```
INTEGER GETNOF()
```
Zwraca łączną liczbę klatek w animacji (skrót od *Number Of Frames*).
**Zwraca**: liczba klatek.
### GETNOFINEVENT
```
INTEGER GETNOFINEVENT(INTEGER eventId)
INTEGER GETNOFINEVENT(STRING eventName)
```
Zwraca liczbę klatek w podanym zdarzeniu. Zdarzenie można wskazać numerem (od `0`) lub nazwą (wielkość liter bez znaczenia). Dla nieistniejącego zdarzenia zwracane jest `0`.
**Parametry**
- `eventId` / `eventName` — identyfikator zdarzenia.
**Zwraca**: liczba klatek w zdarzeniu.
**Przykłady**
```
ANNREX^GETNOFINEVENT(VARSTEMP0);
ANNUKLAD^GETNOFINEVENT(0);
ANNPLANNAK^GETNOFINEVENT("IDLE");
```
### GETPOSITIONX
```
INTEGER GETPOSITIONX([BOOL absolute])
```
Zwraca współrzędną X lewego górnego rogu aktualnej klatki na kanwie. Wariant z `BOOL` zwraca pozycję bezwzględną, bez uwzględniania per-klatkowych przesunięć z pliku animacji.
**Parametry**
- `absolute` — (opcjonalnie) `TRUE`, aby pominąć przesunięcia per-klatkowe.
**Zwraca**: pozycja X.
### GETPOSITIONY
```
INTEGER GETPOSITIONY([BOOL absolute])
```
Zwraca współrzędną Y lewego górnego rogu aktualnej klatki na kanwie. Wariant z `BOOL` zwraca pozycję bezwzględną.
**Parametry**
- `absolute` — (opcjonalnie) `TRUE`, aby pominąć przesunięcia per-klatkowe.
**Zwraca**: pozycja Y.
### GETPRIORITY
```
INTEGER GETPRIORITY()
```
Zwraca priorytet renderowania (`Z`) animacji.
**Zwraca**: wartość pola [`PRIORITY`](#priority).
### GETWIDTH
```
INTEGER GETWIDTH()
```
Zwraca szerokość aktualnej klatki animacji.
**Zwraca**: szerokość w pikselach.
### HIDE
```
void HIDE()
```
Ukrywa animację wizualnie, nie przerywając jej odtwarzania. Po wywołaniu [`PLAY`](#play) widoczność zostanie automatycznie przywrócona.
### ISAT
```
BOOL ISAT(INTEGER posX, INTEGER posY)
```
Sprawdza, czy punkt o podanych współrzędnych znajduje się wewnątrz bounding boxa aktualnej klatki.
**Parametry**
- `posX` — współrzędna X punktu.
- `posY` — współrzędna Y punktu.
**Zwraca**: [`BOOL`](BOOL.md) — `TRUE`, jeżeli punkt jest wewnątrz bounding boxa.
### ISNEAR
```
BOOL ISNEAR(STRING animoName, INTEGER iouThresholdPercent)
```
Sprawdza, czy bieżąca animacja jest w pobliżu drugiej animacji. Wewnętrznie wyznaczany jest indeks Jaccarda (*Intersection over Union*, IoU) bounding boxów dwóch animacji; jeżeli IoU przekracza podany próg (wyrażony w procentach), zwracane jest `TRUE`.
**Parametry**
- `animoName` — nazwa drugiej animacji.
- `iouThresholdPercent` — próg IoU w procentach.
**Zwraca**: [`BOOL`](BOOL.md) — `TRUE`, jeżeli IoU przekracza próg.
**Przykłady**
```
ENEMY^ISNEAR("HERO", 1);
ANNORKA^ISNEAR("ANNLODKA", 12);
```
### ISPLAYING
```
BOOL ISPLAYING()
BOOL ISPLAYING(STRING eventName)
```
Sprawdza, czy animacja jest odtwarzana. Wariant bez argumentu sprawdza, czy jakiekolwiek zdarzenie jest aktualnie odtwarzane; wariant z nazwą zdarzenia sprawdza, czy odtwarzane jest konkretnie to zdarzenie.
**Parametry**
- `eventName` — (opcjonalnie) nazwa zdarzenia do sprawdzenia.
**Zwraca**: [`BOOL`](BOOL.md) — `TRUE`, jeżeli animacja (lub konkretne zdarzenie) jest odtwarzana.
**Przykłady**
```
ANNREX^ISPLAYING();
ANNREXGLOWA^ISPLAYING("SPI");
```
### ISVISIBLE
```
BOOL ISVISIBLE()
```
Sprawdza, czy animacja jest widoczna ([`VISIBLE`](#visible) = `TRUE` i [`TOCANVAS`](#tocanvas) = `TRUE`).
**Zwraca**: [`BOOL`](BOOL.md) — `TRUE`, jeżeli animacja jest widoczna.
### LOAD
```
void LOAD(STRING path)
```
Wczytuje animację z pliku `.ANN`, zastępując dotychczasową zawartość.
**Parametry**
- `path` — ścieżka pliku `.ANN` w VFS gry.
**Przykłady**
```
ANNBKG^LOAD(SOBJECT|NAME);
ANNCHARACTER^LOAD("PIXEL.ANN");
ANNMINIMAPA^LOAD([""+ILEVEL+"_MINIMAPA.ANN"]);
```
### MONITORCOLLISION {#monitorcollision-1}
```
void MONITORCOLLISION()
```
Włącza monitorowanie kolizji animacji z innymi obiektami.
### MONITORCOLLISIONALPHA {#monitorcollisionalpha-1}
```
void MONITORCOLLISIONALPHA()
```
Włącza uwzględnianie kanału alfa przy detekcji kolizji.
### MOVE
```
void MOVE(INTEGER offsetX, INTEGER offsetY)
```
Przesuwa animację o zadane wartości względem aktualnej pozycji.
**Parametry**
- `offsetX` — przesunięcie w osi X.
- `offsetY` — przesunięcie w osi Y.
**Przykłady**
```
ANNELEMENT^MOVE(-200, 0);
ANNPLAYER^MOVE(VARDX, VARDY);
ANNITEMDRAGGING^MOVE([IMOUSEX-IMOUSELASTX], [IMOUSEY-IMOUSELASTY]);
```
### NEXTFRAME
```
void NEXTFRAME()
```
Przeskakuje do następnej klatki bieżącego zdarzenia.
### NPLAY
```
void NPLAY(INTEGER eventId)
```
Rozpoczyna odtwarzanie zdarzenia o podanym indeksie (numerowanym od `0`).
**Parametry**
- `eventId` — indeks zdarzenia.
**Przykłady**
```
ANNDARK0^NPLAY(VARITEMP2);
CZAS^NPLAY(0);
```
### PAUSE
```
void PAUSE()
```
Wstrzymuje odtwarzanie animacji w aktualnej klatce.
### PLAY
```
void PLAY([STRING eventName])
```
Rozpoczyna odtwarzanie zdarzenia. Wariant bez argumentu wznawia ostatnio odtwarzane zdarzenie od początku.
**Parametry**
- `eventName` — (opcjonalnie) nazwa zdarzenia do odtworzenia (wielkość liter bez znaczenia).
**Przykłady**
```
G_STLPAGE^PLAY("ELAPSE");
ANNREX^PLAY(VARITEMP0);
ANNKRET^PLAY(["IDLE_"+ANNKRET^GETEVENTNAME()]);
ANIMOREKSIO^PLAY($1);
```
### PREVFRAME
```
void PREVFRAME()
```
Przechodzi do poprzedniej klatki bieżącego zdarzenia.
### REMOVEMONITORCOLLISION
```
void REMOVEMONITORCOLLISION()
```
Wyłącza monitorowanie kolizji, włączone wcześniej przez [`MONITORCOLLISION`](#monitorcollision-1).
### REMOVEMONITORCOLLISIONALPHA
```
void REMOVEMONITORCOLLISIONALPHA()
```
Wyłącza uwzględnianie kanału alfa przy detekcji kolizji, włączone wcześniej przez [`MONITORCOLLISIONALPHA`](#monitorcollisionalpha-1).
### RESUME
```
void RESUME()
```
Wznawia odtwarzanie wstrzymane przez [`PAUSE`](#pause).
### SETANCHOR
```
void SETANCHOR(STRING anchor)
void SETANCHOR(INTEGER offsetX, INTEGER offsetY)
```
Ustawia kotwicę animacji — punkt zaczepienia, który jest odejmowany od współrzędnych przekazywanych do [`SETPOSITION`](#setposition).
Wariant z `STRING` przyjmuje nazwę pozycji wyliczonej z bounding boxa: `CENTER`, `LEFTUPPER`, `RIGHTUPPER`, `LEFTLOWER`, `RIGHTLOWER`, `LEFT`, `RIGHT`, `TOP`, `BOTTOM`.
Wariant z dwoma `INTEGER`-ami przyjmuje współrzędne kotwicy bezpośrednio.
**Parametry**
- `anchor` — nazwa pozycji w bounding boxie.
- `offsetX, offsetY` — współrzędne kotwicy.
**Przykłady**
```
ANNSELECT^SETANCHOR("CENTER");
ANNREX^SETANCHOR("LEFTLOWER");
ANNREX^SETANCHOR(0, -100);
```
### SETASBUTTON
```
void SETASBUTTON(BOOL enabled, BOOL changeCursor)
```
Ustawia animację jako klikalny przycisk. Niezależnie od wartości argumentów wywołanie sprawia, że animacja staje się widoczna.
**Parametry**
- `enabled``TRUE`, aby aktywować obsługę kliknięć.
- `changeCursor``TRUE`, aby kursor zmieniał wygląd po najechaniu na animację.
**Przykłady**
```
ANNEXIT^SETASBUTTON(TRUE, TRUE);
ANIMOPOWROT^SETASBUTTON(FALSE, FALSE);
```
### SETBACKWARD
```
void SETBACKWARD()
```
Ustawia kierunek odtwarzania animacji na wsteczny.
### SETFORWARD
```
void SETFORWARD()
```
Ustawia kierunek odtwarzania animacji na zgodny z naturalnym (do przodu).
### SETFPS
```
void SETFPS(INTEGER fps)
```
Zmienia tempo odtwarzania animacji.
**Parametry**
- `fps` — liczba klatek na sekundę.
**Przykłady**
```
STLMAGIC^SETFPS(5);
ANNMUCHA1^SETFPS(30);
ANNKON^SETFPS([IKONFPS*8]);
```
### SETFRAME
```
void SETFRAME(INTEGER frameNumber)
void SETFRAME(STRING eventName, INTEGER frameNumber)
void SETFRAME(STRING eventName, STRING frameName)
```
Ustawia animację na konkretną klatkę. Wariant z jednym argumentem ustawia klatkę po jej globalnym indeksie. Wariant dwuargumentowy wybiera zdarzenie, a następnie pozycję w nim (przez numer lub nazwę klatki).
**Parametry**
- `eventName` — nazwa zdarzenia.
- `frameNumber` — indeks klatki w zdarzeniu (od `0`) lub globalny indeks klatki.
- `frameName` — nazwa konkretnej klatki w zdarzeniu.
**Przykłady**
```
ANNREX^SETFRAME(VARSTEMP0, [VARITEMP2-1]);
ANNSCIAGA^SETFRAME("PLAY", VARIREPEATSPELL);
OFERTA^SETFRAME(3);
ANN_H_PIECYK^SETFRAME("ROT", "PIECYK4");
```
### SETFRAMENAME
```
void SETFRAMENAME(INTEGER eventId, INTEGER frameNumber, STRING name)
```
Zmienia nazwę konkretnej klatki w podanym zdarzeniu.
**Parametry**
- `eventId` — indeks zdarzenia (od `0`).
- `frameNumber` — indeks klatki w zdarzeniu (od `0`).
- `name` — nowa nazwa klatki.
**Przykłady**
```
ANNKALAREPA^SETFRAMENAME(0, 0, "200");
ANNKALAREPA^SETFRAMENAME(1, 0, "300");
```
### SETOPACITY
```
void SETOPACITY(INTEGER opacity)
```
Ustawia przezroczystość animacji w skali `0255` (`0` — pełna przezroczystość, `255` — pełna nieprzezroczystość).
**Parametry**
- `opacity` — wartość kanału alfa.
**Przykłady**
```
ANNPLAYER0^SETOPACITY(255);
ANNPLAYER^SETOPACITY(100);
```
### SETPOSITION
```
void SETPOSITION(INTEGER posX, INTEGER posY)
```
Ustawia bezwzględną pozycję animacji. Jeżeli wcześniej ustawiono kotwicę metodą [`SETANCHOR`](#setanchor), jej współrzędne są odejmowane od podanych argumentów.
**Parametry**
- `posX` — współrzędna X.
- `posY` — współrzędna Y.
**Przykłady**
```
ANNREX^SETPOSITION(400, 300);
ANNEXIT^SETPOSITION(-700, -450);
ANNBKG^SETPOSITION([VARIBKGOFFSETX-VARDTEMP0], [VARIBKGOFFSETY-VARDTEMP1]);
```
### SETPRIORITY
```
void SETPRIORITY(INTEGER priority)
```
Ustawia priorytet renderowania.
**Parametry**
- `priority` — nowa wartość pola [`PRIORITY`](#priority).
**Przykłady**
```
ANNREX^SETPRIORITY(VARIPRIORITY);
ANNHEAD1^SETPRIORITY(15);
```
### SHOW
```
void SHOW()
```
Pokazuje animację (ustawia [`VISIBLE`](#visible) na `TRUE`).
### STOP
```
void STOP([BOOL emitSignal])
```
Zatrzymuje odtwarzanie animacji.
**Parametry**
- `emitSignal` — (opcjonalnie) jeżeli `FALSE`, sygnał [`ONFINISHED`](#onfinished) nie zostanie wyemitowany. Domyślnie sygnał jest emitowany.
**Przykłady**
```
G_STLPAGE^STOP(FALSE);
ANNREX^STOP(FALSE);
ANNBLANK^STOP();
```
### TOP
```
void TOP([BOOL flag])
```
Modyfikuje sposób renderowania animacji względem warstwy „wierzchu" sceny. Dokładne zachowanie zależne od bieżącej kompozycji sceny.
**Parametry**
- `flag` — (opcjonalnie) flaga modyfikująca tryb działania.
**Przykłady**
```
ANNWAND0^TOP(FALSE);
ANNHEAD0^TOP(FALSE);
```
## Sygnały
### ONCLICK
Wywoływany po kliknięciu w animację, jeżeli jest ustawiona jako przycisk ([`SETASBUTTON`](#setasbutton)).
### ONCOLLISION
Wywoływany po wykryciu rozpoczęcia kolizji.
### ONCOLLISIONFINISHED
Wywoływany po zakończeniu kolizji.
### ONDONE
Wywoływany po zakończeniu wszystkich zdarzeń animacji.
### ONFINISHED
Wywoływany po zakończeniu odtwarzania zdarzenia. Sygnał jest [parametryzowany](../engine/events.md#sygnaly-parametryzowane) nazwą zdarzenia, więc można podpiąć handler dla konkretnego zdarzenia:
```
ANIMACJA:ONFINISHED^IDLE=BEHAFTERIDLE
```
### ONFIRSTFRAME
Wywoływany po odtworzeniu pierwszej klatki zdarzenia.
### ONFOCUSON
Wywoływany po najechaniu kursorem na animację, jeżeli jest ustawiona jako przycisk.
### ONFOCUSOFF
Wywoływany po zjechaniu kursorem z animacji, jeżeli jest ustawiona jako przycisk.
### ONFRAMECHANGED
Wywoływany po zmianie klatki animacji.
### ONINIT
Wywoływany w momencie inicjalizacji obiektu.
### ONPAUSED
Wywoływany po wstrzymaniu animacji metodą [`PAUSE`](#pause).
### ONRELEASE
Wywoływany po zwolnieniu przycisku myszy nad animacją ustawioną jako przycisk.
### ONRESUMED
Wywoływany po wznowieniu animacji metodą [`RESUME`](#resume).
### ONSIGNAL
Wywoływany po otrzymaniu sygnału (zobacz [Zdarzenia i sygnały](../engine/events.md#onsignal)).
### ONSTARTED
Wywoływany po rozpoczęciu odtwarzania zdarzenia. Sygnał emitowany jest po [`ONFRAMECHANGED`](#onframechanged) dla pierwszej klatki zdarzenia.