patryk025/Rex-EMoolator-docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
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
Download Patch File Download Diff File Expand all files Collapse all files

180
docs/pl/engine/arithmetic.md Normal file
View File

@@ -0,0 +1,180 @@
# Arytmetyka
Silnik Piklib/BlooMoo wykonuje obliczenia wyłącznie wewnątrz **wyrażeń arytmetycznych** zamkniętych w nawiasach kwadratowych. Nawiasy okrągłe są zarezerwowane dla list argumentów wywołań metod i nie pełnią roli grupującej w wyrażeniach. Sekcja poniżej opisuje obsługiwane operatory, reguły typowania oraz konwersje pomiędzy typami prymitywnymi.
## Składnia {#skladnia}
Wyrażenie arytmetyczne zapisuje się w nawiasach kwadratowych. Może być użyte wszędzie, gdzie spodziewana jest wartość — w tym jako argument metody lub jako wartość przypisywana do pola:
```
NAZWA_ZMIENNEJ^SET([VAL1+VAL2]);
*["ANIMO_"+_I_]^PLAY();
```
Zagnieżdżanie wyrażeń odbywa się przez kolejne pary nawiasów kwadratowych:
```
[[VAL1+VAL2]*VAL3]
```
## Reguła typowania {#regula-typowania}
Wszystkie operacje binarne w wyrażeniach kierują się jedną zasadą:
> **Typ wyniku oraz typ prawego operandu są wyznaczone przez typ lewego operandu.**
Prawy operand jest rzutowany na typ lewego przed wykonaniem operacji, a wynik również ma ten typ. Przykłady:
```
"Wartosc" + 2.5 → "Wartosc2.50000" # DOUBLE rzutowany do STRING
2 + "3" → 5 # STRING rzutowany do INTEGER
```
Konsekwencja: kolejność operandów ma znaczenie nie tylko dla operatorów nieprzemiennych, ale również dla samego typu wyniku.
## Konwersje typów
W ramach reguły typowania prawy operand jest rzutowany według poniższych zasad.
### Z `STRING`
| Cel | Reguła |
|---|---|
| [`INTEGER`](../reference/INTEGER.md) | Z początkowej części tekstu wyciągana jest liczba całkowita (analogicznie do `parseInt`). Jeżeli tekst nie zaczyna się od liczby, wynikiem jest `0`. |
| [`DOUBLE`](../reference/DOUBLE.md) | Analogicznie do `INTEGER`, ale z zachowaniem części ułamkowej. Separatorem dziesiętnym jest kropka. |
| [`BOOL`](../reference/BOOL.md) | Tekst odpowiadający wartości prawdziwej (`TRUE` lub niezerowa liczba) zwraca `TRUE`; w pozostałych przypadkach `FALSE`. |
```
"5" → 5
"Test" → 0
```
### Z `INTEGER`
| Cel | Reguła |
|---|---|
| [`STRING`](../reference/STRING.md) | Zapis dziesiętny liczby. |
| [`DOUBLE`](../reference/DOUBLE.md) | Liczba z zerową częścią ułamkową (pięć zer po przecinku). |
| [`BOOL`](../reference/BOOL.md) | Wartość różna od `0` daje `TRUE`, równa `0` — `FALSE`. |
```
5 → "5"
3 → 3.00000
-2 → TRUE
0 → FALSE
```
### Z `DOUBLE`
| Cel | Reguła |
|---|---|
| [`STRING`](../reference/STRING.md) | Zapis dziesiętny z kropką i pięcioma miejscami po przecinku. Dla wartości równych `0.0` część po przecinku jest pomijana. |
| [`INTEGER`](../reference/INTEGER.md) | Zaokrąglenie do najbliższej liczby całkowitej; przy `.5` w górę dla liczb dodatnich i w dół dla ujemnych. |
| [`BOOL`](../reference/BOOL.md) | Pośrednie: najpierw rzutowanie do `INTEGER` (z powyższym zaokrągleniem), potem do `BOOL`. Wartości z przedziału `(-0.5, 0.5)` dają `FALSE`, pozostałe `TRUE`. |
```
3.5 → "3.50000", 4, TRUE
0.0 → "0", 0, FALSE
0.45362 → "0.45362", 0, FALSE
1.00001 → "1.00001", 1, TRUE
-0.5 → "-0.50000", -1, TRUE
```
### Z `BOOL`
| Cel | Reguła |
|---|---|
| [`STRING`](../reference/STRING.md) | `TRUE` → `"TRUE"`, `FALSE` → `"FALSE"`. |
| [`INTEGER`](../reference/INTEGER.md) | `TRUE` → `1`, `FALSE` → `0`. |
| [`DOUBLE`](../reference/DOUBLE.md) | `TRUE` → `1.00000`, `FALSE` → `0.00000`. |
## Operatory arytmetyczne
W wyrażeniach dostępne są następujące operatory binarne:
| Operator | Znaczenie |
|---|---|
| `+` | dodawanie / konkatenacja |
| `-` | odejmowanie |
| `*` | mnożenie |
| `@` | dzielenie |
| `%` | reszta z dzielenia |
### Dodawanie (`+`)
| Typ lewego operandu | Zachowanie |
|---|---|
| [`STRING`](../reference/STRING.md) | Konkatenacja prawego operandu (po rzutowaniu) do lewego. |
| [`INTEGER`](../reference/INTEGER.md) | Suma liczbowa. |
| [`DOUBLE`](../reference/DOUBLE.md) | Suma liczbowa. |
| [`BOOL`](../reference/BOOL.md) | Koniunkcja logiczna (`AND`). `TRUE + FALSE` daje `FALSE`. |
### Odejmowanie (`-`)
| Typ lewego operandu | Zachowanie |
|---|---|
| [`STRING`](../reference/STRING.md) | Brak efektu; wynikiem jest lewy operand. |
| [`INTEGER`](../reference/INTEGER.md) | Różnica liczbowa. |
| [`DOUBLE`](../reference/DOUBLE.md) | Różnica liczbowa. |
| [`BOOL`](../reference/BOOL.md) | Brak efektu; wynikiem jest lewy operand. |
### Mnożenie (`*`)
| Typ lewego operandu | Zachowanie |
|---|---|
| [`STRING`](../reference/STRING.md) | Brak efektu; wynikiem jest lewy operand. |
| [`INTEGER`](../reference/INTEGER.md) | Iloczyn liczbowy. |
| [`DOUBLE`](../reference/DOUBLE.md) | Iloczyn liczbowy. |
| [`BOOL`](../reference/BOOL.md) | Alternatywa logiczna (`OR`). `FALSE * TRUE` daje `TRUE`. |
### Dzielenie (`@`)
| Typ lewego operandu | Zachowanie |
|---|---|
| [`STRING`](../reference/STRING.md) | Brak efektu; wynikiem jest lewy operand. |
| [`INTEGER`](../reference/INTEGER.md) | Iloraz całkowity. |
| [`DOUBLE`](../reference/DOUBLE.md) | Iloraz zmiennoprzecinkowy. |
| [`BOOL`](../reference/BOOL.md) | Brak efektu; wynikiem jest lewy operand. |
Dzielenie przez `0` w typach liczbowych powoduje błąd silnika.
### Reszta z dzielenia (`%`)
| Typ lewego operandu | Zachowanie |
|---|---|
| [`STRING`](../reference/STRING.md) | Brak efektu; wynikiem jest lewy operand. |
| [`INTEGER`](../reference/INTEGER.md) | Reszta z dzielenia. |
| [`DOUBLE`](../reference/DOUBLE.md) | Reszta z dzielenia obcięta do liczby całkowitej, a następnie rzutowana z powrotem do `DOUBLE`. Skutkuje to utratą części ułamkowej, np. `1.5 % 2` daje `1.00000`, nie `1.50000`. |
| [`BOOL`](../reference/BOOL.md) | Brak efektu; wynikiem jest lewy operand. |
Modulo z drugim operandem równym `0` powoduje błąd silnika.
## Operatory porównań
W wyrażeniach dostępne są standardowe operatory porównań: `==`, `!=`, `<`, `<=`, `>`, `>=`. Prawy operand jest najpierw rzutowany na typ lewego (zgodnie z [regułą typowania](#regula-typowania)), a następnie porównywany.
### Równość i nierówność
`==` zwraca `TRUE`, jeżeli oba operandy (po rzutowaniu) są równe; `!=` zwraca przeciwieństwo. Dla typu [`STRING`](../reference/STRING.md) porównanie odbywa się znak po znaku, dla typów liczbowych — wartościami.
### Porównania mniejsze / większe
| Typ lewego operandu | `<` zwraca `TRUE`, jeżeli |
|---|---|
| [`STRING`](../reference/STRING.md) | Leksykograficznie lewy operand poprzedza prawy (porównanie znak po znaku w kodowaniu CP1250). |
| [`INTEGER`](../reference/INTEGER.md) | Wartość liczbowa lewego operandu jest mniejsza. |
| [`DOUBLE`](../reference/DOUBLE.md) | Wartość liczbowa lewego operandu jest mniejsza. |
| [`BOOL`](../reference/BOOL.md) | Lewy operand to `FALSE`, a prawy `TRUE` (`FALSE < TRUE`). |
`>` zwraca `TRUE` w sytuacjach przeciwnych. Operatory `<=` oraz `>=` są równoważne odpowiednio `<` lub `==` oraz `>` lub `==`.
## Operatory logiczne
Operatory `&&` (koniunkcja) i `||` (alternatywa) przyjmują wyłącznie operandy typu [`BOOL`](../reference/BOOL.md). Podanie operandu innego typu (nawet jeżeli mógłby zostać rzutowany) powoduje błąd silnika.
| Operator | Wynik |
|---|---|
| `&&` | `TRUE` tylko jeżeli oba operandy są `TRUE`. |
| `||` | `TRUE` jeżeli przynajmniej jeden z operandów jest `TRUE`. |
W [warunku złożonym instrukcji `@IF`](scripts.md#warunek-zlozony) operatory `&&` i `||` zachowują się tak samo, ale zapisywane są jako część ciągu warunku, nie jako operatory wyrażenia arytmetycznego.

90
docs/pl/engine/events.md Normal file
View File

@@ -0,0 +1,90 @@
# Zdarzenia i sygnały
Silnik Piklib/BlooMoo udostępnia reaktywny model sterowania logiką gry oparty o sygnały. Każdy obiekt może emitować nazwane sygnały, do których w skryptach można podłączyć procedury lub bloki kodu. Niniejszy rozdział opisuje, jak działa ten mechanizm i jakie typowe sygnały są dostępne.
## Podłączanie obsługi sygnału
Sygnał obsługiwany jest analogicznie do dowolnej innej właściwości obiektu — w miejscu wartości podaje się nazwę procedury albo blok kodu:
```
NAZWA_OBIEKTU:ONCHANGED=NAZWA_PROCEDURY
NAZWA_OBIEKTU:ONCHANGED={NAZWA_INNEGO_OBIEKTU^PLAY("TADA");}
```
W ramach jednego obiektu można podłączyć po jednej obsłudze do każdej nazwy sygnału.
## Sygnały parametryzowane {#sygnaly-parametryzowane}
Niektóre sygnały, w szczególności [`ONCHANGED`](#onchanged) oraz [`ONBRUTALCHANGED`](#onbrutalchanged), są emitowane razem z wartością. Wartość ta może być wykorzystana do filtrowania — silnik najpierw szuka obsługi dopasowanej do pary `sygnał + wartość`, a dopiero w przypadku jej braku trafia do uniwersalnej obsługi dla samej nazwy sygnału.
Dyskryminator zapisuje się po nazwie sygnału, oddzielony znakiem daszka `^`:
```
NAZWA_OBIEKTU:ONBRUTALCHANGED^3=OBSLUGA_DLA_TROJKI
NAZWA_OBIEKTU:ONBRUTALCHANGED=OBSLUGA_OGOLNA
```
Dla powyższego: wywołanie `OBIEKT^SET(3)` uruchomi `OBSLUGA_DLA_TROJKI`; dla każdej innej wartości — `OBSLUGA_OGOLNA`.
## Wykonywanie obsługi
System sygnałów jest synchroniczny i jednowątkowy. Emisja sygnału natychmiast przekazuje sterowanie do obsługi: bieżąca procedura jest wstrzymywana, wykonywana jest obsługa sygnału, a po jej zakończeniu sterowanie wraca do miejsca, z którego sygnał został wyemitowany. Sygnały nie są kolejkowane.
Sekwencja zagnieżdżonych wywołań sygnał–procedura–sygnał–procedura tworzy drzewo wywołań. Operatory skoku oddziałują na to drzewo w następujący sposób:
- [`@ONEBREAK`](scripts.md#operatory-skoku) — przerywa wyłącznie bieżącą procedurę i wraca do wywołującego.
- [`@BREAK`](scripts.md#operatory-skoku) — przerywa całe drzewo wywołań rozpoczęte przez pierwotną emisję sygnału.
## Argumenty sygnału
Niektóre sygnały emitowane są z dodatkowymi argumentami. Wewnątrz obsługi sygnału argumenty te są dostępne tak samo jak w procedurze — przez `$1`, `$2`, … (numeracja od `1`). Pozwala to obsłudze reagować na konkretną wartość, która wywołała sygnał.
## Sygnały uniwersalne
### ONINIT
Emitowany podczas inicjalizacji zmiennej w trakcie wczytywania jej pliku. Kolejność emisji nie jest przypadkowa — zmienne są inicjalizowane w stałej kolejności typów; szczegóły opisano w sekcji [Inicjalizacja zmiennych](scripts.md#inicjalizacja-zmiennych).
Typowe zastosowania: inicjalizacja [tablic](../reference/index.md), ustawienie początkowego stanu animacji, wczytanie danych z plików zewnętrznych.
### ONSIGNAL
Sygnał ogólnego przeznaczenia, emitowany przez wywołanie globalnej metody `SEND` na rzecz obiektu:
```
NAZWA_OBIEKTU^SEND("MOJ_SYGNAL");
```
Przesłany ciąg znaków jest dostępny w obsłudze sygnału jako pierwszy argument (`$1`). Mechanizm pozwala definiować własne zdarzenia bez konieczności reagowania na zmiany wartości lub zdarzenia animacji.
## Sygnały zmiany wartości
Emitowane są przez typy [prymitywne](../reference/index.md) (oraz inne typy z polem `VALUE`) przy każdej modyfikacji wartości.
### ONCHANGED
Emitowany wyłącznie wtedy, gdy nowa wartość różni się od poprzedniej. Argumentem (`$1`) jest nowa wartość.
### ONBRUTALCHANGED
Emitowany przy każdej modyfikacji wartości, nawet jeżeli nowa wartość jest taka sama jak poprzednia. Argumentem (`$1`) jest nowa wartość.
W praktyce `ONBRUTALCHANGED` przydaje się do wykrywania samego faktu wywołania metody zmieniającej wartość (`SET`, `INC`, `SWITCH`, …), niezależnie od tego, czy wartość faktycznie się zmieniła.
## Sygnały obiektów graficznych i sekwencji
### ONSTARTED
Emitowany po rozpoczęciu odtwarzania animacji lub sekwencji.
- Dla **sekwencji** — emitowany raz, z nazwą bieżącego eventu z pliku `.SEQ` jako argumentem.
- Dla **animacji** — emitowany z nazwą eventu z pliku `.ANN`. Jeżeli animacja sterowana jest przez sekwencję, sygnał może być emitowany wielokrotnie ze względu na zapętlanie.
### ONFINISHED
Emitowany po zakończeniu odtwarzania:
- dla **animacji** — po wyświetleniu ostatniej klatki i zatrzymaniu odtwarzania,
- dla **sekwencji** — po zakończeniu ostatniego eventu (lub dla każdego eventu odtwarzanego po kolei, w zależności od konfiguracji).
W obu przypadkach sygnał jest również emitowany w odpowiedzi na ręczne wywołanie metody `STOP` (bez argumentu lub z `TRUE`).

70
docs/pl/engine/globals.md Normal file
View File

@@ -0,0 +1,70 @@
# Zmienne globalne i wbudowane
Silnik udostępnia kilka kategorii zmiennych i nazw, do których można odwoływać się z dowolnego miejsca w skryptach, niezależnie od ich poziomu w hierarchii kontekstów. Niniejszy rozdział opisuje wbudowane obiekty, zmienne niejawne, specjalne procedury oraz hierarchię widoczności.
## Hierarchia kontekstów
Każdy wczytywany skrypt tworzy kontekst zmiennych. Konteksty są zagnieżdżone: kontekst sceny dziedziczy po kontekście epizodu, ten po kontekście aplikacji, a ten po kontekście globalnym silnika. Wyszukiwanie zmiennej odbywa się od najniższego kontekstu w górę — zmienne z niższych poziomów przesłaniają zmienne o tej samej nazwie z poziomów wyższych, ale zmienne wyższych poziomów są widoczne z poziomów niższych.
## Obiekty wbudowane
Następujące obiekty są tworzone leniwie przez silnik przy pierwszym odwołaniu i są dostępne z dowolnego kontekstu pod stałymi nazwami:
| Nazwa | Typ | Opis |
|---|---|---|
| `MOUSE` | [`MOUSE`](../reference/index.md) | Stan myszy (pozycja, kliknięcia). |
| `KEYBOARD` | [`KEYBOARD`](../reference/index.md) | Stan klawiatury. |
| `RAND` | [`RAND`](../reference/index.md) | Generator liczb pseudolosowych. Dostępny również pod aliasem `RANDOM`. |
| `SYSTEM` | [`SYSTEM`](../reference/index.md) | Interfejs do funkcji systemowych (czas, środowisko). |
Wszystkie cztery obiekty są singletonami w kontekście globalnym — odwołanie do nich z dowolnego skryptu trafia do tej samej instancji.
## Obiekty z `Application.def`
Obiekty zdefiniowane w pliku `Application.def` — typu [`APPLICATION`](../reference/index.md), [`EPISODE`](../reference/index.md) oraz [`SCENE`](../reference/index.md) — są ładowane do kontekstu globalnego silnika i widoczne ze wszystkich skryptów gry. Pozostałe typy w tym pliku są ignorowane (zobacz [Punkt startowy](scripts.md#punkt-startowy)).
## Zmienne niejawne
Silnik wstrzykuje do skryptów kilka zmiennych nie deklarowanych jawnie.
### `_I_`
Licznik pętli ustawiany przez instrukcję [`@LOOP`](scripts.md#loop). Jest zmienną typu [`INTEGER`](../reference/INTEGER.md) tworzoną lokalnie w kontekście bieżącej iteracji. Wartość zmienia się automatycznie wraz z postępem pętli.
Wewnątrz pętli `@LOOP` `_I_` może być odczytywana w wyrażeniach arytmetycznych i jako argument metod:
```
@LOOP({*["ANIMO_"+_I_]^PLAY();}, 0, 10, 1);
```
Pętla [`@FOR`](scripts.md#for-bloomoo) pozwala podać własną nazwę licznika; w takim przypadku `_I_` nie jest ustawiana.
### `THIS`
Referencja do obiektu, który wyemitował aktualnie obsługiwany sygnał. Dostępna wyłącznie w bloku obsługi sygnału i procedurach z niego wywołanych. Szczegóły jej zachowania opisano w sekcji [Zmienna THIS](scripts.md#zmienna-this).
### `$1`, `$2`, … `$N`
Argumenty procedury lub obsługi sygnału (numeracja od `1`). Dostępne tylko w ciele procedury lub bloku obsługującego sygnał:
```
PROCEDURA:CODE={NAZWA_ZMIENNEJ^SET($1);}
```
Powyższa składnia jest opisana również w sekcji [Argumenty procedur](scripts.md#argumenty-procedur).
## Specjalne procedury
Niektóre nazwy procedur mają znaczenie konwencjonalne — silnik wywołuje je automatycznie w określonych momentach cyklu życia.
### `__ONINIT__`
Procedura wywoływana po zakończeniu inicjalizacji wszystkich zmiennych w wczytanym pliku. Zobacz [Inicjalizacja zmiennych](scripts.md#inicjalizacja-zmiennych). Typowe zastosowanie: ustawienie stanu początkowego sceny po tym, jak wszystkie obiekty są już dostępne.
### `__INIT__`
Procedura wywoływana po załadowaniu sceny i wykonaniu inicjalizacji zmiennych — bezpośrednio przed przekazaniem sterowania do logiki gry. Wykorzystywana do ustawiania stanu sceny zależnego od bieżącego epizodu lub aplikacji.
## Konwencja nazewnictwa
Nazwy poprzedzone i zakończone dwoma podkreślnikami (`__NAZWA__`) są zarezerwowane dla silnika oraz dla konwencjonalnych nazw rozpoznawanych globalnie (np. `__KEYB__`, `__INIT__`, `__ONINIT__`). W praktyce skrypty AidemMedia używają tego formatu również dla własnych zmiennych globalnych, których nie chcą przypadkowo przesłonić w kontekstach lokalnych.

38
docs/pl/engine/index.md Normal file
View File

@@ -0,0 +1,38 @@
# Silnik
**Piklib** (później **BlooMoo**) to 32-bitowy silnik graficzny stworzony przez firmę Aidem Media na potrzeby polskich gier przygodowych z lat 2000. Niniejsza dokumentacja opisuje wewnętrzną logikę silnika i sposób, w jaki wykonuje on skrypty gry.
## Czego dotyczy ta dokumentacja
Dokumentacja koncentruje się na **języku skryptowym** silnika i **modelu wykonania** widzianym z poziomu skryptów — czyli na tym, co programista treści gry musi wiedzieć, żeby zrozumieć działanie istniejących skryptów lub pisać własne.
Nie jest to dokumentacja kodu źródłowego silnika ani pełna specyfikacja wszystkich struktur danych; są to obszary, które będą uzupełniane stopniowo.
## Struktura
Dokumentacja silnika podzielona jest na pięć rozdziałów:
- [Skrypty](scripts.md) — składnia skryptów, parser, kolejność wczytywania i inicjalizacji obiektów.
- [Arytmetyka](arithmetic.md) — wyrażenia obliczeniowe, operatory i reguły konwersji między typami prymitywnymi.
- [Zdarzenia i sygnały](events.md) — model reaktywny silnika, podłączanie obsługi, propagacja przez drzewo wywołań.
- [Zmienne globalne](globals.md) — wbudowane obiekty (`MOUSE`, `KEYBOARD`, `RAND`, `SYSTEM`), zmienne niejawne (`_I_`, `THIS`, `$N`) i specjalne procedury.
- [Dziwactwa silnika](quirks.md) — niestandardowe zachowania, które łatwo przeoczyć.
Pełną listę dostępnych typów danych zawiera [Referencja typów](../reference/index.md).
## Gry wykorzystujące silnik
Lista jest niekompletna i będzie uzupełniana w miarę identyfikowania kolejnych tytułów.
| Gra | Wersja silnika |
|---|---|
| Reksio i Skarb Piratów | Piklib 8 |
| Reksio i Ufo | Piklib 7.1, Piklib 8 |
| Reksio i Czarodzieje | Piklib 8 |
| Reksio i Wehikuł Czasu | Piklib 8 |
| Reksio i Kapitan Nemo | BlooMoo |
| Reksio i Kretes w Akcji | BlooMoo |
| Poznaj Mity: Wyprawa po Złote Runo | Piklib 7.1 |
| Poznaj Mity: Wojna Trojańska | Piklib 7.2 |
| Poznaj Mity: Przygody Odyseusza | Piklib 8 |
| Poznaj Mity: Herkules | Piklib 8 |

118
docs/pl/engine/quirks.md Normal file
View File

@@ -0,0 +1,118 @@
# Dziwactwa silnika
Silnik Piklib/BlooMoo zawiera szereg niestandardowych zachowań, które mogą zaskoczyć programistę przyzwyczajonego do popularnych języków skryptowych. Niniejszy rozdział zbiera najczęstsze z nich w jednym miejscu.
## Wyrażenia i operatory
### Tylko nawiasy kwadratowe grupują obliczenia
W wyrażeniach arytmetycznych grupowanie wykonuje się wyłącznie za pomocą `[ ]`. Nawiasy okrągłe `( )` są zarezerwowane dla list argumentów wywołań metod i nie pełnią funkcji grupującej (zobacz [Arytmetyka](arithmetic.md#skladnia)).
### `@` zamiast `/` dla dzielenia
Operator dzielenia to znak małpki `@`, nie `/`. Próba użycia `/` w wyrażeniu nie zostanie zinterpretowana jako dzielenie.
### Typ wyniku zależy od typu lewego operandu
Wszystkie operacje binarne rzutują prawy operand na typ lewego. Wynik również ma typ lewego operandu. Skutki kolejności są nietrywialne (zobacz [Reguła typowania](arithmetic.md#regula-typowania)):
```
"Wartosc" + 2.5 → "Wartosc2.50000"
2 + "3" → 5
```
### Operatory na `BOOL` mają odwróconą logikę
Operator `+` na [`BOOL`](../reference/BOOL.md) działa jak koniunkcja logiczna (`AND`), a `*` jak alternatywa (`OR`). Operatory `-`, `@` i `%` na `BOOL` nie mają efektu (zobacz [Operatory arytmetyczne](arithmetic.md#operatory-arytmetyczne)).
### `%` na `DOUBLE` traci część ułamkową
Reszta z dzielenia w typie [`DOUBLE`](../reference/DOUBLE.md) jest najpierw obliczana, a następnie obcinana do liczby całkowitej i ponownie rzutowana na `DOUBLE`. W efekcie `1.5 % 2` daje `1.00000`, a nie `1.50000`.
### `&&` i `||` przyjmują wyłącznie `BOOL`
Operatory logiczne nie wykonują niejawnego rzutowania nawet wtedy, gdy operand byłby konwertowalny do `BOOL`. Próba użycia wartości innego typu jako operandu kończy się błędem silnika.
### Dzielenie przez `0` w wyrażeniach kończy się błędem
W odróżnieniu od metod typów liczbowych (gdzie `DIV` i `MOD` zwracają wartość bez zmian), dzielenie operatorem `@` lub `%` przez `0` w wyrażeniu arytmetycznym powoduje wyjście do pulpitu.
## Składnia skryptów
### Bloki kodu muszą być w jednej linii
Cały blok kodu pomiędzy `{` a `}` musi się zmieścić w jednej linii pliku skryptu. Wieloliniowe bloki nie są obsługiwane.
### Każda instrukcja musi kończyć się średnikiem
Również ostatnia instrukcja w bloku kodu. Pominięcie końcowego średnika może spowodować, że instrukcja nie zostanie wykonana.
### Komentarze: `#` dla linii, `!` dla instrukcji
Linia rozpoczynająca się od `#` jest pomijana w całości. Pojedyncza instrukcja poprzedzona znakiem `!` jest wykomentowana aż do najbliższego średnika.
### Komparator równości zmienia się w warunkach złożonych
W [warunku prostym `@IF`](scripts.md#warunek-prosty) równość zapisuje się jako `_`. W [warunku złożonym `@IF`](scripts.md#warunek-zlozony) ten sam komparator zapisuje się jako apostrof `'`. Pozostałe komparatory (`<`, `>`, `<_`/`<'`, `>_`/`>'`) zachowują się analogicznie.
### Tekst bez cudzysłowów jest najpierw szukany jako zmienna
Wartość zapisana bez cudzysłowów najpierw jest interpretowana jako nazwa zmiennej. Jeśli zmienna o takiej nazwie istnieje, użyta zostanie jej wartość; w przeciwnym razie tekst zostanie potraktowany jako literał typu [`STRING`](../reference/STRING.md). Może to prowadzić do trudnych do wykrycia kolizji, gdy literał przypadkowo zbieżny jest z nazwą zmiennej.
### Wielokrotna deklaracja obiektu scala właściwości
Powtórzenie linii `OBJECT=NAZWA` w tym samym pliku nie nadpisuje wcześniejszej definicji — silnik dołącza nowe właściwości do istniejącej i nadpisuje wpisy o tych samych kluczach.
### `Application.def` powinien kończyć się pustą linią
Brak pustej linii na końcu pliku `Application.def` może spowodować, że ostatnia scena nie zostanie poprawnie zinterpretowana, co objawia się czarnym ekranem.
## Liczby
### `DOUBLE` akceptuje literę `d` jako znak wykładnika
W notacji wykładniczej zarówno `e`, jak i `d` są rozpoznawane jako separator wykładnika: `1.23e4` i `1.23d4` są równoważne.
### `DOUBLE → INTEGER` zaokrągla, a nie obcina
Przy rzutowaniu [`DOUBLE`](../reference/DOUBLE.md) na [`INTEGER`](../reference/INTEGER.md) liczba jest zaokrąglana do najbliższej liczby całkowitej, a nie obcinana. Dla wartości dodatnich `.5` zaokrąglane jest w górę, dla ujemnych — w dół, więc `-0.5 → -1`, a `0.5 → 1`.
### `STRING → INTEGER` zwraca `0` zamiast błędu
Konwersja tekstu nie będącego liczbą do [`INTEGER`](../reference/INTEGER.md) (lub [`DOUBLE`](../reference/DOUBLE.md)) zwraca `0` (`0.00000`), a nie generuje błędu. Może to maskować błędy w wyrażeniach łączących literały tekstowe z liczbowymi.
## Metody typów
### `DOUBLE.MOD` obcina część ułamkową
Analogicznie do operatora `%`, metoda [`MOD`](../reference/DOUBLE.md#mod) typu `DOUBLE` zwraca część całkowitą reszty z dzielenia.
### `DOUBLE.SGN` zwraca `INTEGER`, nie `DOUBLE`
Metoda [`SGN`](../reference/DOUBLE.md#sgn) jest jedyną metodą typu `DOUBLE`, która nie zmienia wartości zmiennej i jako wartość zwraca [`INTEGER`](../reference/INTEGER.md).
### `INTEGER.RANDOM(min, max)` jest obustronnie włączne
Wariant dwuargumentowy metody [`RANDOM`](../reference/INTEGER.md#random) zwraca wartość z przedziału `[min, max]`, włącznie z oboma końcami. Wariant jednoargumentowy zwraca `[0, bound)`.
### `INTEGER.DIV` i `INTEGER.MOD` z `0` nie modyfikują zmiennej
W odróżnieniu od dzielenia operatorem `@`/`%` w wyrażeniu, metody [`DIV`](../reference/INTEGER.md#div) i [`MOD`](../reference/INTEGER.md#mod) na typie `INTEGER` z dzielnikiem `0` zwracają niezmienioną wartość bieżącą zamiast generować błąd. Analogicznie zachowują się metody na typie `DOUBLE`.
### `STRING.COPYFILE` ignoruje obiekt-odbiorcę
Metoda [`COPYFILE`](../reference/STRING.md#copyfile) na typie [`STRING`](../reference/STRING.md) nie korzysta z wartości zmiennej, na której została wywołana — operuje wyłącznie na dwóch argumentach reprezentujących ścieżki źródłową i docelową.
### `STRING.CHANGEAT` zastępuje dokładnie jeden znak
Niezależnie od długości ciągu w drugim argumencie, [`CHANGEAT`](../reference/STRING.md#changeat) usuwa jeden znak z bieżącej wartości na podanej pozycji i wstawia w jego miejsce cały ciąg argumentu. Długość ciągu po operacji może być inna niż przed.
## `THIS` w obsłudze sygnałów
### `THIS` zwraca `"temp"` dla `GETNAME`
Mimo że `THIS` jest referencją do obiektu, który wyemitował sygnał, próba pobrania jego nazwy metodą `GETNAME` zwraca ciąg `"temp"`, co wskazuje na wewnętrzną reprezentację jako obiekt tymczasowy.
### Nie wszystkie metody typu działają na `THIS`
Bezpiecznie działają `GET`/`SET` (dla typów prymitywnych) oraz `SHOW`/`HIDE`/`PLAY`/`PAUSE`/`STOP`/`RESUME` (dla obiektów graficznych). Wywołanie metod specyficznych dla typu obiektu (np. [`GETCFRAMEINEVENT`](../reference/index.md) na `ANIMO`) zazwyczaj kończy się błędem silnika. Szczegóły opisano w sekcji [Zmienna THIS](scripts.md#zmienna-this).

280
docs/pl/engine/scripts.md Normal file
View File

@@ -0,0 +1,280 @@
# Skrypty
Silnik Piklib/BlooMoo wykonuje logikę gry interpretując skrypty tekstowe. W tym rozdziale opisana jest składnia tych skryptów, sposób w jaki silnik je wczytuje oraz kolejność inicjalizacji obiektów.
## Format plików
Skrypty zapisywane są w plikach o rozszerzeniach `.CNV`, `.DEF`, `.CLASS` oraz `.SEQ`. Wszystkie mają tę samą podstawową strukturę tekstową — różnią się jedynie kontekstem użycia.
Silnik traktuje cały kod jak wielkie litery i nie rozróżnia ich wielkości. Konwencjonalnie skrypty zapisuje się wielkimi literami.
### Szyfrowanie
Pliki dystrybuowane z grą są domyślnie zaszyfrowane szyfrem przestawieniowym o zmiennym przesunięciu. Plik zaszyfrowany rozpoczyna się nagłówkiem postaci:
```
{<X:N>}
```
gdzie `X` to litera określająca kierunek przesunięcia (`D` oznacza przesunięcie ujemne), a `N` to wartość przesunięcia. Silnik wykrywa ten nagłówek automatycznie i odszyfrowuje resztę pliku przed parsowaniem. Pliki nieszyfrowane (bez tego nagłówka) są wczytywane bezpośrednio.
## Deklaracja obiektów
Obiekt zaczyna się od linii ze słowem kluczowym `OBJECT`:
```
OBJECT=NAZWA_OBIEKTU
```
Linie pomiędzy kolejnymi `OBJECT=` definiują właściwości aktualnego obiektu. Definicja obiektu trwa do końca pliku lub do napotkania kolejnej linii `OBJECT=`.
Jeżeli ten sam obiekt zostanie zadeklarowany ponownie w tym samym pliku, jego właściwości zostaną scalone — nowsze wpisy nadpisują wcześniejsze.
## Właściwości obiektów
Właściwości zapisuje się po nazwie obiektu i znaku dwukropka:
```
NAZWA_OBIEKTU:WLASCIWOSC=WARTOSC
```
Sygnały mogą przyjmować dodatkowy parametr po znaku daszka `^`:
```
NAZWA_OBIEKTU:ONBRUTALCHANGED^3=NAZWA_PROCEDURY
```
W obu przypadkach silnik akceptuje wokół znaku `=` zarówno brak spacji (`KLUCZ=WARTOSC`), jak i spacje po obu stronach (`KLUCZ = WARTOSC`).
## Typ zmiennej
Typ jest kluczowy — bez niego silnik nie wie, jak obsłużyć obiekt, i najczęściej kończy się to wyjściem do pulpitu. Typ deklaruje się właściwością `TYPE`:
```
NAZWA_OBIEKTU:TYPE=STRING
```
Pełna lista dostępnych typów znajduje się w [Referencji typów](../reference/index.md).
## Literały i ciągi znaków
Sposób interpretacji literału zależy od kontekstu:
- Tekst w cudzysłowach (`"..."`) traktowany jest zawsze jako wartość typu [`STRING`](../reference/STRING.md).
- Tekst bez cudzysłowów najpierw jest sprawdzany jako nazwa istniejącej zmiennej — jeżeli zmienna istnieje, używana jest jej wartość. W przeciwnym razie tekst przyjmowany jest dosłownie.
Liczby zmiennoprzecinkowe akceptują notację standardową (`1.234`) oraz wykładniczą z literą `e` lub `d` (`1.23e4`, `1.23d4`).
## Bloki kodu
Bloki kodu — używane jako wartość sygnału lub jako ciało procedury — zapisuje się w nawiasach klamrowych. Instrukcje rozdzielone są średnikami; ostatnia instrukcja również musi kończyć się średnikiem, w przeciwnym razie może nie zostać wykonana.
```
NAZWA_OBIEKTU:ONCHANGED={ZMIENNA2^PLAY("TADA");}
```
Cały blok kodu musi być zapisany w jednej linii — silnik nie obsługuje wieloliniowych bloków bezpośrednio w pliku skryptu.
## Komentarze
Silnik rozpoznaje dwie formy komentarzy:
- **Komentarz liniowy** — linia zaczynająca się od znaku `#` jest pomijana w całości.
- **Komentarz blokowy** — pojedyncza instrukcja poprzedzona znakiem `!` jest traktowana jako wykomentowana; obowiązuje do najbliższego średnika.
## Wywoływanie metod
Metody wywołuje się przy pomocy znaku `^`:
```
NAZWA_OBIEKTU^METODA(arg1, arg2);
```
## Wyrażenia arytmetyczne
Wyrażenia obliczeniowe zapisuje się w nawiasach kwadratowych:
```
NAZWA_ZMIENNEJ^SET([NAZWA_ZMIENNEJ^GET()+"2"]);
```
Szczegóły operatorów i typowania znajdują się w rozdziale [Arytmetyka](arithmetic.md).
## Wskaźniki tekstowe
Znak `*` przed nazwą zmiennej lub wyrażeniem oznacza, że wartość ma zostać użyta jako nazwa innej zmiennej. Pozwala to dynamicznie odwoływać się do zmiennych skonstruowanych z tekstu:
```
*NAZWA_ZMIENNEJ^PLAY();
*["ANIMO_"+_I_]^PLAY();
```
W pierwszym przypadku `NAZWA_ZMIENNEJ` powinna być typu [`STRING`](../reference/STRING.md) i zawierać nazwę faktycznego obiektu. W drugim — nazwa obiektu konstruowana jest z wyrażenia arytmetycznego.
## Argumenty procedur
Wewnątrz ciała procedury argumenty dostępne są przez znak dolara z numerem (numeracja od `1`):
```
PROCEDURA:CODE={NAZWA_ZMIENNEJ^SET($1);}
```
## Zmienna THIS
W bloku obsługującym sygnał dostępna jest niejawna zmienna `THIS`, ustawiona na referencję do obiektu, który sygnał wywołał. Zmienna jest dostępna również w procedurach zagnieżdżonych wewnątrz takiego bloku.
`THIS` zachowuje się nietypowo: na żądanie nazwy (`GETNAME`) zwraca ciąg `"temp"`, co sugeruje, że pod spodem jest to obiekt tymczasowy. Bezpiecznie działają na niej:
- metody `GET` i `SET` dla typów prymitywnych,
- metody `SHOW`, `HIDE`, `PLAY`, `PAUSE`, `STOP` i `RESUME` dla obiektów graficznych ([`ANIMO`](../reference/index.md)).
Wywołanie innej metody specyficznej dla typu obiektu (np. `GETCFRAMEINEVENT` na [`ANIMO`](../reference/index.md)) zazwyczaj kończy się błędem silnika. Aby tego uniknąć, w skryptach AidemMedia stosowane było obejście: nazwa obiektu była najpierw zapisywana do zmiennej typu [`STRING`](../reference/STRING.md), a następnie wywoływana była `^RUN(nazwa_zmiennej, nazwa_metody)`, która wewnętrznie rozwiązuje wskaźnik tekstowy do faktycznego obiektu.
## Pętle
### @LOOP
```
@LOOP(BEHAVIOUR code, INTEGER start, INTEGER delta, INTEGER increment)
```
Wykonuje `code` dla wartości licznika `_I_` z przedziału `[start, start + delta)` z krokiem `increment`. W pseudokodzie:
```
for (int _I_ = start; _I_ < start + delta; _I_ += increment) {
code;
}
```
### @FOR (BlooMoo)
```
@FOR(INTEGER counter, BEHAVIOUR code, INTEGER start, INTEGER delta, INTEGER increment)
```
Identyczna do `@LOOP`, z tą różnicą, że pierwszy argument wskazuje zmienną pełniącą rolę licznika zamiast domyślnej `_I_`.
### @WHILE
```
@WHILE(mixed value1, STRING comparator, mixed value2, BEHAVIOUR code)
```
Wykonuje `code` tak długo, jak prawdziwy jest warunek `value1 comparator value2`. Listę komparatorów opisano poniżej w [Instrukcji warunkowej](#instrukcja-warunkowa).
## Instrukcja warunkowa
Silnik udostępnia dwa warianty instrukcji `@IF`.
### Warunek prosty
```
@IF(mixed value1, STRING comparator, mixed value2, BEHAVIOUR codeTrue, BEHAVIOUR codeFalse)
```
Dostępne komparatory:
| Komparator | Znaczenie |
|---|---|
| `_` | równa się |
| `!_` | różne niż |
| `<` | mniejsze niż |
| `<_` | mniejsze lub równe |
| `>` | większe niż |
| `>_` | większe lub równe |
### Warunek złożony {#warunek-zlozony}
```
@IF(STRING condition, BEHAVIOUR codeTrue, BEHAVIOUR codeFalse)
```
W warunku złożonym dostępne są operatory logiczne:
- `&&` — koniunkcja (i)
- `||` — alternatywa (lub)
W warunku złożonym znak równości jest zapisywany jako apostrof (`'`) zamiast podkreślnika (`_`):
| Komparator | Znaczenie |
|---|---|
| `'` | równa się |
| `!'` | różne niż |
| `<` | mniejsze niż |
| `<'` | mniejsze lub równe |
| `>` | większe niż |
| `>'` | większe lub równe |
## Dynamiczne tworzenie zmiennych
Wewnątrz bloku kodu można utworzyć zmienną na bieżąco:
```
@INT(STRING name, INTEGER value)
@DOUBLE(STRING name, DOUBLE value)
@STRING(STRING name, STRING value)
@BOOL(STRING name, BOOL value)
```
Każda z instrukcji tworzy zmienną odpowiedniego typu o podanej nazwie i wartości początkowej.
## Operatory skoku
Wewnątrz pętli oraz procedur można sterować przepływem instrukcjami:
- `@CONTINUE()` — pomija pozostałe instrukcje w bieżącej iteracji pętli i przechodzi do następnej.
- `@BREAK()` — przerywa całe drzewo wywołań rozpoczęte przez bieżący sygnał lub wywołanie.
- `@ONEBREAK()` — przerywa wyłącznie bieżącą procedurę.
- `@RETURN(mixed value)` — ustawia wartość zwracaną przez procedurę, ale nie przerywa jej wykonywania.
## Kolejność wczytywania skryptów
Skrypty silnika są zorganizowane hierarchicznie: skrypty z niższych poziomów hierarchii widzą zmienne swoje i wszystkich przodków, ale nie odwrotnie.
### Punkt startowy
Silnik rozpoczyna od pliku `Application.def` w podkatalogu `dane`. Plik ten zawiera definicje obiektów typu [`APPLICATION`](../reference/index.md), [`EPISODE`](../reference/index.md) oraz [`SCENE`](../reference/index.md) — pozostałe typy w tym pliku są ignorowane.
Przykładowa zawartość:
```
OBJECT=GAME
GAME:TYPE=APPLICATION
GAME:PATH=GAME
GAME:EPISODES=PRZYGODA
GAME:STARTWITH=PRZYGODA
OBJECT=PRZYGODA
PRZYGODA:TYPE=EPISODE
PRZYGODA:PATH=GAME\PRZYGODA
PRZYGODA:SCENES=START,CREDITS,LEBIODKA
PRZYGODA:STARTWITH=START
OBJECT=START
START:TYPE=SCENE
START:PATH=GAME\PRZYGODA\START
```
### Ładowanie kolejnych plików {#ladowanie-kolejnych-plikow}
Po wczytaniu `Application.def` silnik ładuje plik `.CNV` dla każdego zdefiniowanego obiektu. Ścieżkę pliku konstruuje z atrybutu `PATH` obiektu (relatywnie do katalogu `dane`), nazwy obiektu i rozszerzenia `.CNV`. Jeśli plik nie istnieje, jego ładowanie jest pomijane bez błędu.
Kolejność ładowania:
1. Plik powiązany z obiektem `APPLICATION`.
2. Plik pierwszego epizodu (atrybut `STARTWITH` w `APPLICATION`).
3. Plik pierwszej sceny tego epizodu (atrybut `STARTWITH` w `EPISODE`).
Przy lokalizowaniu plików silnik dodatkowo uwzględnia aktualnie ustawiony język (zobacz [`APPLICATION.SETLANGUAGE`](../reference/APPLICATION.md#setlanguage)) — wybrany identyfikator języka wskazuje podkatalog z lokalizowanymi zasobami, konsultowany podczas wczytywania plików gry.
### Inicjalizacja zmiennych
W ramach każdego pliku zmienne są tworzone i inicjalizowane w stałej kolejności typów:
1. Procedury.
2. Typy prymitywne ([`STRING`](../reference/STRING.md), [`DOUBLE`](../reference/DOUBLE.md), [`INTEGER`](../reference/INTEGER.md), [`BOOL`](../reference/BOOL.md)).
3. Tablice oraz warunki.
4. Animacje, obrazy, dźwięki i fonty.
5. Przyciski, pola tekstowe, sekwencje, mysz, klawiatura, obserwator kanwy.
Dla każdej zmiennej w tej fazie wywoływany jest sygnał `ONINIT`. Na koniec, po zakończeniu inicjalizacji wszystkich zmiennych, wywoływana jest procedura `__ONINIT__`, jeśli została zdefiniowana.

19
docs/pl/index.md Normal file
View File

@@ -0,0 +1,19 @@
# Rex-EMoolator
Nieoficjalna dokumentacja silników skryptowych **Piklib** oraz **BlooMoo**, używanych w serii gier *Przygody Reksia*, oraz emulatora **Rex-EMoolator**.
## Czego można się tu dowiedzieć
- jak zbudowany jest język skryptowy silnika,
- jakie typy danych i obiekty są dostępne w skryptach,
- jakie metody, pola i sygnały udostępnia każdy typ,
- jak silnik interpretuje pliki, kolejność ładowania i format danych.
## Nawigacja
- [Silnik](engine/index.md) — opis języka skryptowego, modelu wykonania, zdarzeń, globali i niestandardowych zachowań.
- [Referencja typów](reference/index.md) — alfabetyczny spis typów dostępnych w skryptach.
## Status
Dokumentacja jest cały czas uzupełniana. Część informacji powstaje na podstawie analizy oryginalnych skryptów oraz reverse-engineeringu silnika; tam, gdzie zachowanie nie zostało jeszcze potwierdzone, znajdują się odpowiednie adnotacje.

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 `0–255` (`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.

154
docs/pl/reference/APPLICATION.md Normal file
View File

@@ -0,0 +1,154 @@
# APPLICATION
Obiekt aplikacji — najwyższy poziom hierarchii skryptów gry. Deklarowany w pliku [`Application.def`](../engine/scripts.md#punkt-startowy) jako pierwszy obiekt; zawiera listę epizodów i wskazuje, który z nich uruchomić jako pierwszy.
## Pola
### EPISODES
```
STRING EPISODES
```
Lista nazw epizodów ([`EPISODE`](EPISODE.md)) tworzących aplikację, oddzielonych przecinkami. W analizowanych grach z reguły zawiera jedną pozycję.
### PATH
```
STRING PATH
```
Ścieżka relatywna do katalogu `dane`, w którym znajdują się pliki aplikacji. Używana przez silnik przy lokalizowaniu pliku `.CNV` powiązanego z aplikacją (zobacz [Ładowanie kolejnych plików](../engine/scripts.md#ladowanie-kolejnych-plikow)).
### STARTWITH
```
STRING STARTWITH
```
Nazwa epizodu, od którego silnik rozpocznie grę.
### Metadane
Następujące pola są zapisywane w pliku skryptu jako metadane i nie wpływają bezpośrednio na działanie silnika:
- `AUTHOR` — autor pliku.
- `BLOOMOO_VERSION` — wersja silnika BlooMoo.
- `CREATIONTIME` — data utworzenia pliku.
- `DESCRIPTION` — opis aplikacji.
- `LASTMODIFYTIME` — data ostatniej modyfikacji pliku.
- `VERSION` — wersja aplikacji.
## Metody
### EXIT
```
void EXIT()
```
Kończy działanie aplikacji.
**Przykłady**
```
GAME^EXIT();
```
### GETLANGUAGE
```
STRING GETLANGUAGE()
```
Zwraca aktualnie ustawiony język aplikacji. Wartością domyślną jest `"POL"`.
**Zwraca**: kod języka.
**Przykłady**
```
UFO^GETLANGUAGE();
```
### RUN
```
mixed RUN(STRING varName, STRING methodName, [mixed param1, ..., mixed paramN])
```
Wywołuje metodę `methodName` na zmiennej `varName`, przekazując pozostałe argumenty jako jej parametry. Wartość zwracana to wynik wywołanej metody. Mechanizm pełni rolę dynamicznego wywołania — pozwala wybrać zarówno docelową zmienną, jak i metodę w runtime.
**Parametry**
- `varName` — nazwa docelowej zmiennej.
- `methodName` — nazwa wywoływanej metody.
- `param1, …, paramN` — (opcjonalnie) argumenty przekazywane do wywołania.
**Zwraca**: wartość zwróconą przez wywołaną metodę.
**Przykłady**
```
UFO^RUN(VARSTRINGTEMP, "SETASBUTTON", FALSE, FALSE);
UFO^RUN(VARSTRINGTEMP, "HIDE");
UFO^RUN(["ANIMO"+$1], "HIDE");
UFO^RUN($1, "PLAY", $2);
UFO^RUN(ARRCARS^GET(VARPLAYER), "SETPRIORITY", ARRPRIORITY^GET(VARPLAYER));
```
### RUNENV
```
mixed RUNENV(STRING sceneName, STRING behaviourName)
```
Wywołuje procedurę `behaviourName`, ale tylko wtedy, gdy aktualnie aktywna scena ma nazwę `sceneName`. W przeciwnym razie metoda nie ma efektu. Mechanizm służy do warunkowego uruchamiania procedur, które mają sens wyłącznie w konkretnym kontekście sceny.
**Parametry**
- `sceneName` — nazwa sceny, w której procedura ma być wykonana.
- `behaviourName` — nazwa wywoływanej procedury.
**Zwraca**: wartość zwróconą przez procedurę lub `NULL`, jeżeli warunek sceny nie został spełniony.
**Przykłady**
```
GAME^RUNENV(SCENENAME, "__HELPSTART__");
GAME^RUNENV(SCENENAME, "B_PAUSE_START");
GAME^RUNENV(SCENENAME, "__CUTINIT__");
```
### SETLANGUAGE
```
void SETLANGUAGE(STRING languageCode)
```
Ustawia kod języka aplikacji. Silnik mapuje przekazany kod LCID Windows na wewnętrzny identyfikator języka według poniższej tabeli:
| Kod LCID | Język | Wewnętrzny ID | Podkatalog |
|---|---|---|---|
| `0415` | polski | `1` | `POL` |
| `0405` | czeski | `2` | `CZE` |
| `0402` | bułgarski | `3` | `BUL` |
| `0418` | rumuński | `4` | `ROM` |
| `0419` | rosyjski | `5` | `RUS` |
| `040E` | węgierski | `6` | `HUN` |
| `041B` | słowacki | `7` | `SLO` |
| `0422` | ukraiński | `8` | `UKR` |
Wybrany identyfikator decyduje o podkatalogu z lokalizowanymi zasobami, z którego silnik wczytuje pliki gry (zobacz [Ładowanie kolejnych plików](../engine/scripts.md#ladowanie-kolejnych-plikow)). Identyfikatory `9`, `10` i `11` (ustawiane inną drogą niż `SETLANGUAGE`) odpowiadają podkatalogowi `NIEM` — wersji niemieckojęzycznej. Identyfikator spoza powyższego zakresu skutkuje pustym podkatalogiem. Po ustawieniu języka silnik ponownie inicjalizuje również układ klawiatury.
**Parametry**
- `languageCode` — kod LCID w postaci czterocyfrowej liczby szesnastkowej.
**Przykłady**
```
UFO^SETLANGUAGE("0415");
UFO^SETLANGUAGE("040E");
UFO^SETLANGUAGE("0419");
```

475
docs/pl/reference/ARRAY.md Normal file
View File

@@ -0,0 +1,475 @@
# 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)).

122
docs/pl/reference/BEHAVIOUR.md Normal file
View File

@@ -0,0 +1,122 @@
# BEHAVIOUR
Procedura. Wykonuje kod zapisany w polu `CODE`, opcjonalnie obwarowany warunkiem wskazanym w polu `CONDITION`. Argumenty wywołania dostępne są wewnątrz kodu jako `$1`, `$2`, …, opisane szerzej w [Argumenty procedur](../engine/scripts.md#argumenty-procedur).
## Pola
### CODE
```
STRING CODE
```
Treść procedury — blok kodu w nawiasach klamrowych, zgodny ze składnią opisaną w rozdziale [Skrypty](../engine/scripts.md#bloki-kodu).
Przykład:
```
BEHGOTOTITLE:CODE={BEHSETSCENE^RUN();G_SARCADESCENE^SET("EGIPTLEJ");BEHCSSTART^RUN();}
```
### CONDITION
```
STRING CONDITION
```
Nazwa zmiennej typu [`CONDITION`](CONDITION.md) lub [`COMPLEXCONDITION`](COMPLEXCONDITION.md), używana przez metodę [`RUNC`](#runc) oraz przez [`RUNLOOPED`](#runlooped) jako warunek przerwania pętli. Jeżeli pole nie jest ustawione, metody działają bezwarunkowo.
## Metody
### RUN
```
mixed RUN([mixed param1, ..., mixed paramN])
```
Wykonuje kod procedury. Przekazane argumenty są dostępne w kodzie jako `$1`, `$2`, …. Wartość zwracana to wynik wyrażenia [`@RETURN`](../engine/scripts.md#operatory-skoku) w ciele procedury, lub `NULL`, jeżeli `@RETURN` nie został wywołany.
**Parametry**
- `param1, …, paramN` — argumenty procedury (opcjonalne, dowolnego typu).
**Zwraca**: wartość zwrócona przez procedurę lub `NULL`.
**Przykłady**
```
__LOAD_SETTINGS__^RUN();
BEHSELECTOBJ^RUN(VARITER);
BEHADDITEM^RUN(SOBJECT|SPARAM0, VARITER);
BEHENTERRABBIT^RUN("ANNHILL0", -1);
```
### RUNC
```
mixed RUNC([mixed param1, ..., mixed paramN])
```
Wywołuje procedurę pod warunkiem, że warunek wskazany w polu `CONDITION` jest spełniony. Jeżeli `CONDITION` nie jest ustawione, zachowuje się jak [`RUN`](#run). Argumenty i wartość zwracana — jak w `RUN`.
**Parametry**
- `param1, …, paramN` — argumenty procedury.
**Zwraca**: wartość zwróconą przez procedurę lub `NULL` (również, gdy warunek nie był spełniony).
**Przykłady**
```
BEHREMOVEMENUITEM^RUNC("CHOMIK");
BEHREMOVEMENUITEM^RUNC(VARSTRINGTEMP);
BEH_HERO_FINISHED_0^RUNC();
```
### RUNLOOPED
```
void RUNLOOPED(INTEGER start, INTEGER length)
void RUNLOOPED(INTEGER start, INTEGER length, INTEGER step, [mixed extraArg1, ..., mixed extraArgN])
```
Wywołuje procedurę w pętli `for` z licznikiem przekazywanym jako `$1`. Dodatkowe argumenty (od czwartego włącznie) trafiają do procedury jako `$2`, `$3`, … . Jeżeli pole `CONDITION` jest ustawione, jego warunek jest sprawdzany przed każdą iteracją — jeżeli warunek nie jest spełniony, pętla się kończy.
Pętla jest równoważna następującemu pseudokodowi:
```
for (int i = start; i < start + length; i += step) {
// wywołanie procedury z $1 = i, $2..$N = extraArgs
}
```
Jeżeli `step` jest pomijany lub przekazany jako `0`, używana jest wartość `1`. Operator [`@BREAK`](../engine/scripts.md#operatory-skoku) w ciele procedury kończy pętlę `RUNLOOPED` (ale nie procedurę wywołującą).
**Parametry**
- `start` — wartość początkowa licznika.
- `length` — liczba iteracji do wykonania (`startVal < endVal` to `startVal + length`).
- `step` — (opcjonalnie) krok licznika. Domyślnie `1`.
- `extraArg1, …, extraArgN` — (opcjonalnie) dodatkowe argumenty przekazywane do procedury.
**Przykłady**
```
BEHSHOWMENU^RUNLOOPED(0, ARRAYWARSZTATMENUPRZEDMIOTY^GETSIZE());
BEHSHOWPIONEK^RUNLOOPED(1, 9);
BEHINITZASLONAX^RUNLOOPED(0, 7, 1, "[80*$1]");
```
## Sygnały
### ONINIT
Wywoływany w momencie inicjalizacji procedury.
### ONDONE
Wywoływany po zakończeniu wywołania procedury.
### ONSIGNAL
Wywoływany po otrzymaniu sygnału (zobacz [Zdarzenia i sygnały](../engine/events.md#onsignal)).

92
docs/pl/reference/BOOL.md Normal file
View File

@@ -0,0 +1,92 @@
# BOOL
Typ logiczny. Przechowuje jedną z dwóch wartości: `TRUE` lub `FALSE`.
## Pola
### TOINI
```
BOOL TOINI
```
Określa, czy wartość pola jest zapisywana do pliku INI i przywracana po ponownym uruchomieniu.
### VALUE
```
BOOL VALUE
```
Aktualna wartość zmiennej.
## Metody
### GET
```
BOOL GET()
```
Zwraca aktualną wartość zmiennej.
**Zwraca**
- `BOOL` — bieżąca wartość pola `VALUE`.
### RESETINI
```
void RESETINI()
```
Przywraca wartość zmiennej do wartości resetu zdefiniowanej w atrybutach obiektu w skrypcie. Silnik szuka wartości w kolejności: `DEFAULT` → `INIT_VALUE` → `VALUE`; używana jest pierwsza znaleziona.
### SET
```
void SET(BOOL value)
```
Ustawia wartość zmiennej.
**Parametry**
- `value` — nowa wartość typu `BOOL`.
**Przykłady**
```
VARBLOCKSCENE^SET(FALSE);
__KEYB__^SET(KEYBOARD^ISENABLED());
VARBTEMP1^SET($2);
```
### SWITCH
```
void SWITCH(BOOL value1, BOOL value2)
```
Przełącza wartość zmiennej między wartościami podanymi w argumentach. Metoda przyjmuje dwa parametry ze względu na zgodność sygnatury z metodą `SWITCH` typów [`INTEGER`](INTEGER.md) oraz [`DOUBLE`](DOUBLE.md), choć w przypadku typu `BOOL` pełna informacja zawarta byłaby już w jednym argumencie.
**Parametry**
- `value1` — pierwsza wartość.
- `value2` — druga wartość.
**Przykłady**
```
B_0^SWITCH(TRUE, FALSE);
```
## Sygnały
### ONCHANGED
Wywoływany, gdy wartość zmiennej zostaje zmieniona na inną niż dotychczasowa.
### ONBRUTALCHANGED
Wywoływany przy każdym wywołaniu metody zmieniającej wartość, niezależnie od tego, czy nowa wartość różni się od poprzedniej.

70
docs/pl/reference/CLASS.md Normal file
View File

@@ -0,0 +1,70 @@
# CLASS
Definicja klasy obiektów. Plik definicji ma rozszerzenie `.class` i wewnętrznie składnię analogiczną do plików `.CNV`. Z definicji klasy tworzone są instancje (`INSTANCE`) metodą [`NEW`](#new); usuwane są metodą [`DELETE`](#delete).
## Pola
### DEF
```
STRING DEF
```
Ścieżka do pliku z definicją klasy. Jeżeli ścieżka nie zaczyna się od `$`, jest poprzedzana prefiksem `$COMMON/classes/`.
### BASE
```
STRING BASE
```
Klasa bazowa do dziedziczenia. W aktualnej implementacji emulatora pole jest odczytywane, ale nie używane.
## Metody
### NEW
```
mixed NEW(STRING varName, [mixed param1, ..., mixed paramN])
```
Tworzy nową instancję klasy o nazwie `varName`. Nowa zmienna jest rejestrowana w kontekście, w którym zadeklarowana jest klasa (a nie w kontekście wywołującym) — instancja przeżywa zatem zmianę sceny, jeżeli klasa jest zadeklarowana na poziomie aplikacji.
Po utworzeniu instancji, jeżeli plik definicji klasy zawiera procedurę o nazwie `CONSTRUCTOR`, jest ona wywoływana z argumentami przekazanymi do `NEW` (włącznie z `varName` jako `$1`).
**Parametry**
- `varName` — nazwa nowej zmiennej-instancji.
- `param1, …, paramN` — (opcjonalnie) argumenty przekazywane do procedury `CONSTRUCTOR`.
**Zwraca**: wartość zwróconą przez procedurę `CONSTRUCTOR` lub `NULL`.
**Przykłady**
```
MM^NEW("G_MENU");
CLSLOGOBJ^NEW("LOG", FALSE);
CLSEIFELENEMYOBJ^NEW("ENEMY0", "1_ENEMY0.ANN", 2, 5, 16, 4, 0, 2, 18);
CLSBDENEMYOBJ^NEW(["BDENEMY"+I2], _I_, I1, I2, IBDKRAINA);
```
### DELETE
```
mixed DELETE(STRING varName, [mixed param1, ..., mixed paramN])
```
Usuwa instancję klasy o nazwie `varName`. Jeżeli definicja klasy zawiera procedurę o nazwie `DESTRUCTOR`, jest ona wywoływana z argumentami przekazanymi do `DELETE` (włącznie z `varName` jako `$1`) zanim zmienna zostanie wyrejestrowana z kontekstu.
**Parametry**
- `varName` — nazwa usuwanej zmiennej-instancji.
- `param1, …, paramN` — (opcjonalnie) argumenty przekazywane do procedury `DESTRUCTOR`.
**Zwraca**: wartość zwróconą przez procedurę `DESTRUCTOR` lub `NULL`.
## Sygnały
### ONINIT
Wywoływany w momencie inicjalizacji zmiennej klasy.

104
docs/pl/reference/COMPLEXCONDITION.md Normal file
View File

@@ -0,0 +1,104 @@
# COMPLEXCONDITION
Obiekt łączący dwa warunki ([`CONDITION`](CONDITION.md) lub zagnieżdżone `COMPLEXCONDITION`) operatorem logicznym `AND` lub `OR`. Konfigurowany trzema polami w skrypcie i wywoływany analogicznie jak `CONDITION`.
## Pola
### CONDITION1
```
STRING CONDITION1
```
Nazwa zmiennej z lewym warunkiem składowym. Wartością powinna być zmienna typu [`CONDITION`](CONDITION.md) albo `COMPLEXCONDITION` — w obu przypadkach warunek zostanie zewaluowany rekurencyjnie.
### CONDITION2
```
STRING CONDITION2
```
Nazwa zmiennej z prawym warunkiem składowym; reguły identyczne jak dla `CONDITION1`.
### OPERATOR
```
STRING OPERATOR
```
Operator logiczny łączący warunki. Domyślnie `AND`. Dopuszczalne wartości:
| Wartość | Znaczenie |
|---|---|
| `AND` | koniunkcja — całość prawdziwa, gdy oba warunki są prawdziwe |
| `OR` | alternatywa — całość prawdziwa, gdy przynajmniej jeden warunek jest prawdziwy |
## Metody
### BREAK
```
void BREAK([BOOL emitSignals])
```
Ewaluuje warunek złożony. Jeżeli wynik jest `TRUE`, przerywa całe bieżące drzewo wywołań (efekt analogiczny do [`@BREAK`](../engine/scripts.md#operatory-skoku)).
**Parametry**
- `emitSignals` — (opcjonalnie) jeżeli `TRUE`, sygnały [`ONRUNTIMESUCCESS`](#onruntimesuccess)/[`ONRUNTIMEFAILED`](#onruntimefailed) są emitowane zarówno przez ten obiekt, jak i przez każdy warunek składowy. Domyślnie `FALSE`.
**Przykłady**
```
COC_END^BREAK(TRUE);
CCONDISATPOS^BREAK(TRUE);
```
### CHECK
```
BOOL CHECK([BOOL emitSignals])
```
Ewaluuje warunek złożony i zwraca wynik.
**Parametry**
- `emitSignals` — (opcjonalnie) jak w [`BREAK`](#break).
**Zwraca**: [`BOOL`](BOOL.md) — wynik kombinacji warunków.
**Przykłady**
```
CCONDTESTEND^CHECK(TRUE);
```
### ONE_BREAK
```
void ONE_BREAK([BOOL emitSignals])
```
Ewaluuje warunek złożony. Jeżeli wynik jest `TRUE`, przerywa wyłącznie bieżącą procedurę (efekt analogiczny do [`@ONEBREAK`](../engine/scripts.md#operatory-skoku)).
**Parametry**
- `emitSignals` — (opcjonalnie) jak w [`BREAK`](#break).
**Przykłady**
```
COC_END^ONE_BREAK(TRUE);
CCONDISATPOS^ONE_BREAK(TRUE);
```
## Sygnały
### ONRUNTIMESUCCESS
Wywoływany, gdy warunek złożony zwrócił `TRUE` i `emitSignals` było ustawione na `TRUE`.
### ONRUNTIMEFAILED
Wywoływany, gdy warunek złożony zwrócił `FALSE` i `emitSignals` było ustawione na `TRUE`.

115
docs/pl/reference/CONDITION.md Normal file
View File

@@ -0,0 +1,115 @@
# CONDITION
Obiekt opisujący warunek porównania dwóch operandów. Konfigurowany trzema polami w skrypcie i wywoływany metodą [`CHECK`](#check) lub jedną z metod sterujących przepływem ([`BREAK`](#break), [`ONE_BREAK`](#one_break)).
## Pola
### OPERAND1
```
STRING OPERAND1
```
Lewy operand porównania. Pole zawiera tekstowy zapis operandu, który zostanie zinterpretowany przy każdej ewaluacji warunku. Dopuszczalne formy:
- literał tekstowy w cudzysłowach (`"..."` lub `'...'`),
- literał logiczny (`TRUE`, `FALSE`),
- literał liczbowy (`5`, `-3.14`),
- nazwa zmiennej (zostanie pobrana jej wartość; jeżeli zmienna jest typu [`EXPRESSION`](index.md), `CONDITION` lub [`COMPLEXCONDITION`](COMPLEXCONDITION.md), zostanie ewaluowana),
- wyrażenie skryptowe — fragment kodu rozpoczynający się od `[`, `*` lub zawierający operatory `^` albo `|`.
### OPERAND2
```
STRING OPERAND2
```
Prawy operand porównania. Reguły interpretacji są identyczne jak dla `OPERAND1`.
### OPERATOR
```
STRING OPERATOR
```
Operator porównania. Domyślnie `EQUAL`. Dopuszczalne wartości:
| Wartość | Znaczenie |
|---|---|
| `EQUAL` | równa się |
| `NOTEQUAL` | różne niż |
| `LESS` | mniejsze niż |
| `GREATER` | większe niż |
| `LESSEQUAL` | mniejsze lub równe |
| `GREATEREQUAL` | większe lub równe |
## Metody
### BREAK
```
void BREAK([BOOL emitSignals])
```
Ewaluuje warunek. Jeżeli wynik jest `TRUE`, przerywa całe bieżące drzewo wywołań (efekt analogiczny do [`@BREAK`](../engine/scripts.md#operatory-skoku)). Jeżeli wynik jest `FALSE`, metoda nie ma efektu.
**Parametry**
- `emitSignals` — (opcjonalnie) jeżeli `TRUE`, dodatkowo emitowany jest sygnał [`ONRUNTIMESUCCESS`](#onruntimesuccess) lub [`ONRUNTIMEFAILED`](#onruntimefailed) w zależności od wyniku. Domyślnie `FALSE`.
**Przykłady**
```
COND1^BREAK(TRUE);
CONDKONTROLA^BREAK(TRUE);
```
### CHECK
```
BOOL CHECK([BOOL emitSignals])
```
Ewaluuje warunek i zwraca wynik porównania.
**Parametry**
- `emitSignals` — (opcjonalnie) jeżeli `TRUE`, dodatkowo emitowany jest sygnał [`ONRUNTIMESUCCESS`](#onruntimesuccess) lub [`ONRUNTIMEFAILED`](#onruntimefailed) w zależności od wyniku. Domyślnie `FALSE`.
**Zwraca**: [`BOOL`](BOOL.md) — wynik porównania.
**Przykłady**
```
CONPR1^CHECK(TRUE);
CONPR2^CHECK(TRUE);
```
### ONE_BREAK
```
void ONE_BREAK([BOOL emitSignals])
```
Ewaluuje warunek. Jeżeli wynik jest `TRUE`, przerywa wyłącznie bieżącą procedurę (efekt analogiczny do [`@ONEBREAK`](../engine/scripts.md#operatory-skoku)). Jeżeli wynik jest `FALSE`, metoda nie ma efektu.
**Parametry**
- `emitSignals` — (opcjonalnie) jak w [`BREAK`](#break).
**Przykłady**
```
COND1^ONE_BREAK(TRUE);
CONDREMOVEMENUITEM^ONE_BREAK(TRUE);
```
## Sygnały
### ONRUNTIMESUCCESS
Wywoływany, gdy ewaluacja warunku zwróciła `TRUE` i `emitSignals` było ustawione na `TRUE`.
### ONRUNTIMEFAILED
Wywoływany, gdy ewaluacja warunku zwróciła `FALSE` i `emitSignals` było ustawione na `TRUE`.

458
docs/pl/reference/DOUBLE.md Normal file
View File

@@ -0,0 +1,458 @@
# DOUBLE
Liczba zmiennoprzecinkowa o podwójnej precyzji.
## Pola
### TOINI
```
BOOL TOINI
```
Określa, czy wartość pola jest zapisywana do pliku INI i przywracana po ponownym uruchomieniu.
### VALUE
```
DOUBLE VALUE
```
Aktualna wartość zmiennej. Akceptowane są zapisy w notacji standardowej (np. `1.234`) oraz w notacji wykładniczej z literą `e` lub `d` (np. `1.23e4`, `1.23d4`).
## Metody
### ABS
```
DOUBLE ABS(DOUBLE value)
```
Zapisuje w zmiennej wartość bezwzględną przekazanego argumentu i zwraca ją.
**Parametry**
- `value` — liczba, której wartość bezwzględna zostanie zapisana.
**Zwraca**: nową wartość zmiennej.
**Przykłady**
```
VARDTMP2^ABS(VARDTMP2);
DKIERUNEKY^ABS(DKIERUNEKY);
```
### ADD
```
DOUBLE ADD(DOUBLE addend)
```
Dodaje argument do bieżącej wartości zmiennej, zapisuje wynik i zwraca go.
**Parametry**
- `addend` — wartość dodawana.
**Zwraca**: nową wartość zmiennej.
**Przykłady**
```
VARDMENUOPACITY^ADD([42.5*VARIMENUVISIBLE]);
VARDTIME^ADD(1.0);
STREX|DPOSX^ADD(STREX|FORCEX);
```
### ARCTAN
```
DOUBLE ARCTAN(DOUBLE value)
```
Zapisuje w zmiennej arcus tangens argumentu wyrażony w stopniach i zwraca tę wartość. Argument traktowany jest jako liczba (tangens kąta), a nie jako kąt.
**Parametry**
- `value` — liczba, dla której wyznaczany jest arcus tangens.
**Zwraca**: nową wartość zmiennej (w stopniach).
**Przykłady**
```
VARDTMP1^ARCTAN(VARDTMP1);
```
### ARCTANEX
```
DOUBLE ARCTANEX(DOUBLE y, DOUBLE x)
```
Zapisuje w zmiennej wartość funkcji `atan2(y, x)` wyrażoną w stopniach i zwraca tę wartość. Jest to kąt wektora `(x, y)` względem dodatniej osi `OX`.
**Parametry**
- `y` — pierwsza składowa wektora.
- `x` — druga składowa wektora.
**Zwraca**: nową wartość zmiennej (w stopniach).
**Przykłady**
```
VARDTEMP1^ARCTANEX(VARIDIRY, VARIDIRX);
VARDTEMP2^ARCTANEX(VREFLECT^GET(1), VREFLECT^GET(0));
```
### CLAMP
```
DOUBLE CLAMP(DOUBLE rangeMin, DOUBLE rangeMax)
```
Sprowadza bieżącą wartość zmiennej do przedziału `[rangeMin, rangeMax]`. Wartości spoza przedziału są przycinane do jego granic.
**Parametry**
- `rangeMin` — dolna granica przedziału (włącznie).
- `rangeMax` — górna granica przedziału (włącznie).
**Zwraca**: nową wartość zmiennej.
**Przykłady**
```
D3^CLAMP(0.5, 2.5);
VARDTMP1^CLAMP(-15.0, 15.0);
DKONSPEED^CLAMP(0.0, DKONSPEEDMAX);
```
### CLEAR
```
DOUBLE CLEAR()
```
Ustawia wartość zmiennej na `0.0` i zwraca tę wartość.
**Zwraca**: `0.0`.
### COSINUS
```
DOUBLE COSINUS(DOUBLE angle)
```
Zapisuje w zmiennej cosinus podanego kąta i zwraca tę wartość. Kąt podawany jest w stopniach.
**Parametry**
- `angle` — kąt w stopniach.
**Zwraca**: nową wartość zmiennej.
**Przykłady**
```
VARDTEMP0^COSINUS(VARDANGLE);
VARDTEMP1^COSINUS(ARRANGLE^GET(VARPLAYER));
```
### DEC
```
DOUBLE DEC()
```
Zmniejsza wartość zmiennej o `1.0`.
**Zwraca**: nową wartość zmiennej.
### DIV
```
DOUBLE DIV(DOUBLE divisor)
```
Dzieli bieżącą wartość zmiennej przez argument, zapisuje wynik i zwraca go. Dzielenie przez zero nie zmienia wartości zmiennej.
**Parametry**
- `divisor` — dzielnik.
**Zwraca**: nową wartość zmiennej (lub niezmienioną wartość, jeśli `divisor` był równy `0.0`).
**Przykłady**
```
VARDTEMP0^DIV(ARRSPEEDFACTOR^GET(0));
DKONSPEED^DIV(6.0);
VARDTMP2^DIV(15);
```
### GET
```
DOUBLE GET()
```
Zwraca aktualną wartość zmiennej.
**Zwraca**: bieżąca wartość pola `VALUE`.
### INC
```
DOUBLE INC()
```
Zwiększa wartość zmiennej o `1.0`.
**Zwraca**: nową wartość zmiennej.
### LENGTH
```
DOUBLE LENGTH(DOUBLE x, DOUBLE y)
```
Wyznacza długość wektora `(x, y)` jako `sqrt(x² + y²)`, zapisuje wynik i zwraca go.
**Parametry**
- `x` — pierwsza składowa wektora.
- `y` — druga składowa wektora.
**Zwraca**: długość wektora.
**Przykłady**
```
VARDTEMP0^LENGTH(VARIDIRX, VARIDIRY);
```
### LOG
```
DOUBLE LOG(DOUBLE value)
```
Zapisuje w zmiennej logarytm naturalny argumentu i zwraca tę wartość.
**Parametry**
- `value` — liczba, której logarytm jest wyznaczany.
**Zwraca**: nową wartość zmiennej.
### MAXA
```
DOUBLE MAXA(DOUBLE value1, [DOUBLE value2, ..., DOUBLE valueN])
```
Wyznacza maksimum spośród podanych argumentów, zapisuje wynik i zwraca go. Wymaga co najmniej jednego argumentu.
**Parametry**
- `value1, …, valueN` — wartości, spośród których wybierane jest maksimum.
**Zwraca**: największą z podanych wartości.
**Przykłady**
```
VARDPOWER^MAXA(0.0, VARDPOWER);
```
### MINA
```
DOUBLE MINA(DOUBLE value1, [DOUBLE value2, ..., DOUBLE valueN])
```
Wyznacza minimum spośród podanych argumentów, zapisuje wynik i zwraca go. Wymaga co najmniej jednego argumentu.
**Parametry**
- `value1, …, valueN` — wartości, spośród których wybierane jest minimum.
**Zwraca**: najmniejszą z podanych wartości.
**Przykłady**
```
VARDPOWER^MINA(VARDPOWER, 9.0);
```
### MOD
```
DOUBLE MOD(DOUBLE divisor)
```
Wyznacza resztę z dzielenia bieżącej wartości zmiennej przez argument, obcina część ułamkową wyniku do liczby całkowitej, zapisuje i zwraca. Dzielenie przez zero nie zmienia wartości zmiennej.
**Parametry**
- `divisor` — dzielnik.
**Zwraca**: nową wartość zmiennej (lub niezmienioną wartość, jeśli `divisor` był równy `0.0`).
### MUL
```
DOUBLE MUL(DOUBLE multiplier)
```
Mnoży bieżącą wartość zmiennej przez argument, zapisuje wynik i zwraca go.
**Parametry**
- `multiplier` — mnożnik.
**Zwraca**: nową wartość zmiennej.
**Przykłady**
```
STPLAYER|FORCEX^MUL(0.75);
VARCATFORCEX^MUL(1000000);
STREX|FORCEX^MUL(STREX|DEFIANCE);
```
### RESETINI
```
DOUBLE RESETINI()
```
Przywraca wartość zmiennej do wartości resetu zdefiniowanej w atrybutach obiektu w skrypcie. Silnik szuka wartości w kolejności: `DEFAULT` → `INIT_VALUE` → `VALUE`; używana jest pierwsza znaleziona. Jeśli żadna z nich nie jest ustawiona, wartość ustawiana jest na `0.0`.
**Zwraca**: nową wartość zmiennej.
### SET
```
DOUBLE SET(DOUBLE value)
```
Ustawia wartość zmiennej.
**Parametry**
- `value` — nowa wartość.
**Zwraca**: nową wartość zmiennej.
**Przykłady**
```
VARDMAXVEL^SET(300.0);
VARDMAXVELKRET^SET([0.6*VARDMAXVEL]);
VARD_KRETSPEED^SET($1);
```
### SGN
```
INTEGER SGN()
```
Zwraca znak bieżącej wartości zmiennej: `-1` dla wartości ujemnych, `1` dla dodatnich, `0` dla zera. Metoda nie modyfikuje wartości zmiennej i jako jedyna w tym typie zwraca [`INTEGER`](INTEGER.md), nie `DOUBLE`.
**Zwraca**: znak wartości zmiennej (`-1`, `0` lub `1`).
### SINUS
```
DOUBLE SINUS(DOUBLE angle)
```
Zapisuje w zmiennej sinus podanego kąta i zwraca tę wartość. Kąt podawany jest w stopniach.
**Parametry**
- `angle` — kąt w stopniach.
**Zwraca**: nową wartość zmiennej.
**Przykłady**
```
VARDTEMP1^SINUS(VARDANGLE);
VARDTEMP2^SINUS(ARRANGLE^GET(VARPLAYER));
```
### SQRT
```
DOUBLE SQRT()
DOUBLE SQRT(DOUBLE value)
```
Zapisuje w zmiennej pierwiastek kwadratowy i zwraca tę wartość.
- W wariancie bez argumentu pierwiastkowana jest bieżąca wartość zmiennej.
- W wariancie z argumentem pierwiastkowany jest argument.
**Parametry**
- `value` — (opcjonalnie) liczba, której pierwiastek jest wyznaczany.
**Zwraca**: nową wartość zmiennej.
**Przykłady**
```
VARDODLEGLOSC^SQRT(VARDODLEGLOSC);
```
### SUB
```
DOUBLE SUB(DOUBLE subtrahend)
```
Odejmuje argument od bieżącej wartości zmiennej, zapisuje wynik i zwraca go.
**Parametry**
- `subtrahend` — wartość odejmowana.
**Zwraca**: nową wartość zmiennej.
**Przykłady**
```
VARDANGLE^SUB(VARDTEMP2);
DKONSPEED^SUB([DKONACCELERATION*D3]);
```
### SWITCH
```
DOUBLE SWITCH(DOUBLE valueA, DOUBLE valueB)
```
Jeżeli bieżąca wartość zmiennej jest równa `valueA`, zmiennej zostaje przypisana `valueB`; w przeciwnym razie — `valueA`. Pozwala to naprzemiennie przełączać między dwiema wartościami.
**Parametry**
- `valueA` — pierwsza wartość.
- `valueB` — druga wartość.
**Zwraca**: nową wartość zmiennej.
## Sygnały
### ONCHANGED
Wywoływany, gdy wartość zmiennej zostaje zmieniona na inną niż dotychczasowa.
### ONBRUTALCHANGED
Wywoływany przy każdym wywołaniu metody zmieniającej wartość, niezależnie od tego, czy nowa wartość różni się od poprzedniej.

102
docs/pl/reference/EPISODE.md Normal file
View File

@@ -0,0 +1,102 @@
# EPISODE
Logiczny segment gry — kontener scen ([`SCENE`](SCENE.md)) wewnątrz [`APPLICATION`](APPLICATION.md). W praktyce gry AidemMedia używały jednego epizodu na całą grę.
## Pola
### SCENES
```
STRING SCENES
```
Lista nazw scen tworzących epizod, oddzielonych przecinkami.
### PATH
```
STRING PATH
```
Ścieżka relatywna do katalogu `dane` zawierająca pliki epizodu. Używana przez silnik przy lokalizowaniu plików `.CNV` scen.
### STARTWITH
```
STRING STARTWITH
```
Nazwa sceny, od której rozpoczyna się epizod.
### Metadane
Następujące pola są zapisywane jako metadane i nie wpływają bezpośrednio na działanie silnika:
- `AUTHOR` — autor pliku.
- `CREATIONTIME` — data utworzenia pliku.
- `DESCRIPTION` — opis epizodu.
- `LASTMODIFYTIME` — data ostatniej modyfikacji pliku.
- `VERSION` — wersja epizodu.
## Metody
### BACK
```
void BACK()
```
Wraca do sceny odtwarzanej bezpośrednio przed bieżącą.
**Przykłady**
```
PRZYGODA^BACK();
```
### GETCURRENTSCENE
```
STRING GETCURRENTSCENE()
```
Zwraca nazwę aktualnie aktywnej sceny.
**Zwraca**: nazwa sceny.
**Przykłady**
```
PRZYGODA^GETCURRENTSCENE();
```
### GETLATESTSCENE
```
STRING GETLATESTSCENE()
```
Zwraca nazwę sceny odtwarzanej przed bieżącą — tej, do której wróciłoby wywołanie [`BACK`](#back).
**Zwraca**: nazwa poprzedniej sceny.
### GOTO
```
void GOTO(STRING sceneName)
```
Przełącza grę do podanej sceny.
**Parametry**
- `sceneName` — nazwa sceny docelowej.
**Przykłady**
```
PRZYGODA^GOTO("CREDITS");
PRZYGODA^GOTO("MAGIC");
PRZYGODA^GOTO(G_SARCADEOBJECTS);
PRZYGODA^GOTO(UFO^RUN(["VARLEVEL"+VARNR], "GET"));
```

25
docs/pl/reference/FONT.md Normal file
View File

@@ -0,0 +1,25 @@
# FONT
Definicja czcionki bitmapowej. Obiekt nie udostępnia metod skryptowych ani sygnałów — jest używany przez typ [`TEXT`](TEXT.md) jako źródło tekstur znaków.
## Pola
### DEF
```
STRING DEF_<nazwa>_<styl>_<rozmiar>
```
Pole definiujące plik czcionki w formacie `.FNT`. Nazwa pola koduje metadane konkretnego wariantu czcionki: jej nazwę, styl i rozmiar.
Format zapisu w skrypcie:
```
FONT:DEF_<nazwa>_<styl>_<rozmiar>=<plik>.FNT
```
**Przykład**
```
FONT:DEF_ARIAL_STANDARD_14=ARIAL14.FNT
```

409
docs/pl/reference/IMAGE.md Normal file
View File

@@ -0,0 +1,409 @@
# IMAGE
Statyczny obraz wyświetlany na scenie. Obsługuje pozycję, przezroczystość, przycinanie obszaru rysowania, dynamiczne ładowanie pliku oraz monitorowanie kolizji z innymi obiektami.
## Pola
### FILENAME
```
STRING FILENAME
```
Nazwa pliku `.IMG` z obrazem. Pole odczytywane przy inicjalizacji zmiennej; może być również nadpisane przez metodę [`LOAD`](#load).
### MONITORCOLLISION
```
BOOL MONITORCOLLISION
```
Określa, czy obraz uczestniczy w detekcji kolizji z innymi obiektami. Modyfikowane przez metody [`MONITORCOLLISION`](#monitorcollision-1) i [`REMOVEMONITORCOLLISION`](#removemonitorcollision).
### MONITORCOLLISIONALPHA
```
BOOL MONITORCOLLISIONALPHA
```
Określa, czy w detekcji kolizji uwzględniany jest kanał przezroczystości obrazu — kolizja nie zachodzi w pikselach całkowicie przezroczystych.
### PRIORITY
```
INTEGER PRIORITY
```
Priorytet renderowania (`Z`) względem innych obiektów na scenie.
### VISIBLE
```
BOOL VISIBLE
```
Widoczność obrazu. Modyfikowana metodami [`SHOW`](#show) i [`HIDE`](#hide).
## Metody
### GETALPHA
```
INTEGER GETALPHA(INTEGER posX, INTEGER posY)
```
Zwraca wartość kanału alfa piksela o podanych współrzędnych (w skali `0–255`, gdzie `255` to pełna nieprzezroczystość).
**Parametry**
- `posX` — współrzędna X piksela.
- `posY` — współrzędna Y piksela.
**Zwraca**: wartość alfa piksela.
**Przykłady**
```
IMGLEVEL^GETALPHA(VARX, VARY);
IMGALPHA^GETALPHA(EXPMASKX, EXPMASKY);
```
### GETCENTERX
```
INTEGER GETCENTERX()
```
Zwraca współrzędną X środka prostokąta zajmowanego przez obraz.
**Zwraca**: środek X.
### GETCENTERY
```
INTEGER GETCENTERY()
```
Zwraca współrzędną Y środka prostokąta zajmowanego przez obraz.
**Zwraca**: środek Y.
### GETHEIGHT
```
INTEGER GETHEIGHT()
```
Zwraca wysokość obrazu w pikselach.
**Zwraca**: wysokość obrazu.
**Przykłady**
```
IMGLINA^GETHEIGHT();
```
### GETPIXEL
```
INTEGER GETPIXEL(INTEGER posX, INTEGER posY)
```
Zwraca wartość piksela na podanych współrzędnych jako liczbę całkowitą zakodowaną zgodnie z głębią koloru obrazu: dla 16-bitowych obrazów — RGB565, dla 15-bitowych — RGB555.
**Parametry**
- `posX` — współrzędna X piksela.
- `posY` — współrzędna Y piksela.
**Zwraca**: zakodowana wartość koloru piksela.
**Przykłady**
```
IMGMASK^GETPIXEL(IKONNEWX, IKONNEWY);
```
### GETPOSITIONX
```
INTEGER GETPOSITIONX()
```
Zwraca współrzędną X lewego górnego rogu obrazu.
**Zwraca**: pozycja X.
### GETPOSITIONY
```
INTEGER GETPOSITIONY()
```
Zwraca współrzędną Y lewego górnego rogu obrazu.
**Zwraca**: pozycja Y.
### GETWIDTH
```
INTEGER GETWIDTH()
```
Zwraca szerokość obrazu w pikselach.
**Zwraca**: szerokość obrazu.
**Przykłady**
```
IMGPASEK^GETWIDTH();
```
### HIDE
```
void HIDE()
```
Ukrywa obraz (ustawia [`VISIBLE`](#visible) na `FALSE`).
**Przykłady**
```
G_IMGPAGE^HIDE();
```
### INVALIDATE
```
void INVALIDATE()
```
Stosuje oczekującą wartość przezroczystości ustawioną metodą [`SETOPACITY`](#setopacity). Bez wywołania `INVALIDATE` zmiana przezroczystości nie staje się widoczna.
**Przykłady**
```
G_IMGPAGE^INVALIDATE();
```
### ISAT
```
BOOL ISAT(INTEGER posX, INTEGER posY)
```
Sprawdza, czy punkt o podanych współrzędnych znajduje się wewnątrz prostokąta zajmowanego przez obraz.
**Parametry**
- `posX` — współrzędna X punktu.
- `posY` — współrzędna Y punktu.
**Zwraca**: [`BOOL`](BOOL.md) — `TRUE`, jeżeli punkt jest wewnątrz prostokąta obrazu.
### LOAD
```
void LOAD(STRING path)
```
Wczytuje obraz z pliku, zastępując dotychczasową zawartość. Obraz po wczytaniu jest automatycznie pokazywany ([`VISIBLE`](#visible) ustawiane na `TRUE`).
**Parametry**
- `path` — ścieżka pliku `.IMG` w VFS gry.
**Przykłady**
```
G_IMGPAGE^LOAD("$COMMON\PAGE.IMG");
IMGTLO^LOAD(VARSTEMP0);
IMGSCR^LOAD(["$COMMON\SAVE_BD\BD_SCR"+VARIACTIVESLOT+".IMG"]);
```
### MERGEALPHA
```
void MERGEALPHA(INTEGER posX, INTEGER posY, STRING maskName)
```
Wiąże z obrazem maskę alfa pochodzącą z innego obrazu. Maska jest pozycjonowana w punkcie `(posX, posY)` i modyfikuje wynikową przezroczystość bieżącego obrazu w obszarze pokrycia.
**Parametry**
- `posX` — współrzędna X pozycji maski.
- `posY` — współrzędna Y pozycji maski.
- `maskName` — nazwa zmiennej typu `IMAGE`, której kanał alfa zostanie użyty jako maska.
**Przykłady**
```
IMGDARK^MERGEALPHA([ANNPLAYER0^GETCENTERX()-75], [ANNPLAYER0^GETCENTERY()-75], "IMGKOLKO");
IMG_WODA^MERGEALPHA(800, VARI_Y, "IMG_LIGHT");
```
### MONITORCOLLISION {#monitorcollision-1}
```
void MONITORCOLLISION()
```
Włącza monitorowanie kolizji obrazu z innymi obiektami. Po wywołaniu pole [`MONITORCOLLISION`](#monitorcollision) ma wartość `TRUE`, a obraz jest rejestrowany w mechanizmie detekcji kolizji.
### MONITORCOLLISIONALPHA {#monitorcollisionalpha-1}
```
void MONITORCOLLISIONALPHA()
```
Włącza uwzględnianie kanału alfa przy detekcji kolizji. Po wywołaniu pole [`MONITORCOLLISIONALPHA`](#monitorcollisionalpha) ma wartość `TRUE`.
### MOVE
```
void MOVE(INTEGER offsetX, INTEGER offsetY)
```
Przesuwa obraz o zadane wartości względem aktualnej pozycji.
**Parametry**
- `offsetX` — przesunięcie w osi X.
- `offsetY` — przesunięcie w osi Y.
**Przykłady**
```
IMGBKGA^MOVE(0, 800);
IMGLINA^MOVE(0, IMOVDY);
IMRECT^MOVE(IGSX, 0);
```
### 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).
### SETCLIPPING
```
void SETCLIPPING(INTEGER xLeft, INTEGER yBottom, INTEGER xRight, INTEGER yTop)
```
Ogranicza obszar rysowania obrazu do prostokąta o podanych krawędziach. Piksele poza prostokątem nie są rysowane.
**Parametry**
- `xLeft, yBottom, xRight, yTop` — współrzędne prostokąta przycinania.
**Przykłady**
```
G_IMGPAGE^SETCLIPPING(0, 0, G_IPAGE, 600);
```
### SETOPACITY
```
void SETOPACITY(INTEGER opacity)
```
Ustawia oczekującą wartość przezroczystości obrazu w skali `0–255` (`0` — pełna przezroczystość, `255` — pełna nieprzezroczystość). Wartości spoza zakresu są przycinane do jego granic. **Zmiana nie staje się widoczna, dopóki nie zostanie wywołana metoda [`INVALIDATE`](#invalidate).**
**Parametry**
- `opacity` — wartość kanału alfa (`0–255`).
**Przykłady**
```
AIDEMMEDIA^SETOPACITY(VARNR);
IMGBRIDGE^SETOPACITY(200);
```
### SETPOSITION
```
void SETPOSITION(INTEGER posX, INTEGER posY)
```
Ustawia bezwzględną pozycję lewego górnego rogu obrazu.
**Parametry**
- `posX` — współrzędna X.
- `posY` — współrzędna Y.
**Przykłady**
```
IMGENERGIA^SETPOSITION([795-VARENERGIA], 78);
IMGKOLKO^SETPOSITION(-500, -500);
IMGNAKLADKA^SETPOSITION(VARIPOSX, 0);
```
### SETPRIORITY
```
void SETPRIORITY(INTEGER priority)
```
Ustawia priorytet renderowania obrazu.
**Parametry**
- `priority` — nowa wartość pola [`PRIORITY`](#priority).
**Przykłady**
```
G_IMGPAGE^SETPRIORITY(3000);
AIDEMMEDIA^SETPRIORITY(3);
```
### SHOW
```
void SHOW()
```
Pokazuje obraz (ustawia [`VISIBLE`](#visible) na `TRUE`).
**Przykłady**
```
G_IMGPAGE^SHOW();
REX^SHOW();
```
## Sygnały
### ONCLICK
Wywoływany po kliknięciu w obraz.
### ONFOCUSON
Wywoływany po najechaniu kursorem na obraz.
### ONFOCUSOFF
Wywoływany po zjechaniu kursorem z obrazu.
### ONINIT
Wywoływany w momencie inicjalizacji obiektu.

413
docs/pl/reference/INTEGER.md Normal file
View File

@@ -0,0 +1,413 @@
# INTEGER
Liczba całkowita ze znakiem.
## Pola
### TOINI
```
BOOL TOINI
```
Określa, czy wartość pola jest zapisywana do pliku INI i przywracana po ponownym uruchomieniu.
### VALUE
```
INTEGER VALUE
```
Aktualna wartość zmiennej.
## Metody
### ABS
```
INTEGER ABS(INTEGER value)
```
Zapisuje w zmiennej wartość bezwzględną przekazanego argumentu i zwraca ją.
**Parametry**
- `value` — liczba, której wartość bezwzględna zostanie zapisana.
**Zwraca**: nową wartość zmiennej.
**Przykłady**
```
VARINT0^ABS(VARINT0);
I_7^ABS(ARRFLDCLONES^GET(I_FIELD_INDEX));
```
### ADD
```
INTEGER ADD(INTEGER addend)
```
Dodaje argument do bieżącej wartości zmiennej, zapisuje wynik i zwraca go.
**Parametry**
- `addend` — wartość dodawana.
**Zwraca**: nową wartość zmiennej.
**Przykłady**
```
VARIRADIUS^ADD([VARIMENUVISIBLE*16]);
VARIKRETSTARTX^ADD(50);
VARITEMP0^ADD(VARIRADIUS);
```
### AND
```
INTEGER AND(INTEGER value)
```
Wykonuje bitową koniunkcję bieżącej wartości zmiennej z argumentem, zapisuje wynik i zwraca go.
**Parametry**
- `value` — wartość, z którą wykonywana jest operacja.
**Zwraca**: nową wartość zmiennej.
**Przykłady**
```
VARITEMP2^AND(1);
VARITEMP1^AND(ARRMASK^GET(ARRENEMYMASK^GET(VARENEMY)));
```
### CLAMP
```
INTEGER CLAMP(INTEGER rangeMin, INTEGER rangeMax)
```
Sprowadza bieżącą wartość zmiennej do przedziału `[rangeMin, rangeMax]`. Wartości spoza przedziału są przycinane do jego granic.
**Parametry**
- `rangeMin` — dolna granica przedziału (włącznie).
- `rangeMax` — górna granica przedziału (włącznie).
**Zwraca**: nową wartość zmiennej.
**Przykłady**
```
VARIMENUX^CLAMP(92, 708);
I1^CLAMP(0, IMIECZMAX);
IFRAMER^CLAMP(IFRAMECENTER, IFRAMEMAX);
```
### CLEAR
```
INTEGER CLEAR()
```
Ustawia wartość zmiennej na `0` i zwraca tę wartość.
**Zwraca**: `0`.
### DEC
```
INTEGER DEC()
```
Zmniejsza wartość zmiennej o `1`.
**Zwraca**: nową wartość zmiennej.
**Przykłady**
```
VARITIMETOEXIT^DEC();
VARIWAIT^DEC();
```
### DIV
```
INTEGER DIV(INTEGER divisor)
```
Dzieli bieżącą wartość zmiennej (dzielenie całkowite) przez argument, zapisuje wynik i zwraca go. Dzielenie przez zero nie zmienia wartości zmiennej.
**Parametry**
- `divisor` — dzielnik.
**Zwraca**: nową wartość zmiennej (lub niezmienioną wartość, jeśli `divisor` był `0`).
**Przykłady**
```
VARITEMP0^DIV(2);
VARMOUSEDX^DIV(VARMOUSESPEED);
```
### GET
```
INTEGER GET()
```
Zwraca aktualną wartość zmiennej.
**Zwraca**: bieżąca wartość pola `VALUE`.
### INC
```
INTEGER INC()
```
Zwiększa wartość zmiennej o `1`.
**Zwraca**: nową wartość zmiennej.
**Przykłady**
```
VARINUMITEMS^INC();
VARITUTCOUNT^INC();
```
### LENGTH
```
INTEGER LENGTH(INTEGER x, INTEGER y)
```
Wyznacza długość wektora `(x, y)` jako `sqrt(x² + y²)`, obcina wynik do liczby całkowitej, zapisuje i zwraca.
**Parametry**
- `x` — pierwsza składowa wektora.
- `y` — druga składowa wektora.
**Zwraca**: długość wektora obciętą do liczby całkowitej.
**Przykłady**
```
VARI_TMP1^LENGTH([VARI_TMPX-VARI_CARX], [VARI_TMPY-VARI_CARY]);
I3^LENGTH(I3, 600);
```
### MOD
```
INTEGER MOD(INTEGER divisor)
```
Zapisuje w zmiennej resztę z dzielenia jej bieżącej wartości przez argument. Dzielenie przez zero nie zmienia wartości zmiennej.
**Parametry**
- `divisor` — dzielnik.
**Zwraca**: nową wartość zmiennej (lub niezmienioną wartość, jeśli `divisor` był `0`).
**Przykłady**
```
VARITEMP4^MOD(8);
IGC^MOD(ARLEVG^GETSIZE());
```
### MUL
```
INTEGER MUL(INTEGER multiplier)
```
Mnoży bieżącą wartość zmiennej przez argument, zapisuje wynik i zwraca go.
**Parametry**
- `multiplier` — mnożnik.
**Zwraca**: nową wartość zmiennej.
**Przykłady**
```
VARITEMP0^MUL(34);
I1^MUL(IGRID);
```
### NOT
```
INTEGER NOT()
```
Wykonuje bitową negację (dopełnienie) bieżącej wartości zmiennej, zapisuje wynik i zwraca go.
**Zwraca**: nową wartość zmiennej.
### OR
```
INTEGER OR(INTEGER value)
```
Wykonuje bitową alternatywę bieżącej wartości zmiennej z argumentem, zapisuje wynik i zwraca go.
**Parametry**
- `value` — wartość, z którą wykonywana jest operacja.
**Zwraca**: nową wartość zmiennej.
### POWER
```
INTEGER POWER(INTEGER exponent)
```
Podnosi bieżącą wartość zmiennej do podanej potęgi, zaokrągla wynik do liczby całkowitej, zapisuje i zwraca.
**Parametry**
- `exponent` — wykładnik potęgi.
**Zwraca**: nową wartość zmiennej.
### RANDOM
```
INTEGER RANDOM(INTEGER bound)
INTEGER RANDOM(INTEGER min, INTEGER max)
```
Zapisuje w zmiennej liczbę pseudolosową i zwraca ją.
- W wariancie z jednym argumentem zwracana jest liczba z przedziału `[0, bound)`.
- W wariancie z dwoma argumentami zwracana jest liczba z przedziału `[min, max]` (oba końce włącznie).
**Parametry**
- `bound` — wartość graniczna (wyłącznie).
- `min`, `max` — granice przedziału (włącznie).
**Zwraca**: wylosowaną wartość.
**Przykłady**
```
VARITEMP0^RANDOM(0, 100);
VARI_TMP3^RANDOM(VARI_TMP3);
```
### RESETINI
```
INTEGER RESETINI()
```
Przywraca wartość zmiennej do wartości resetu zdefiniowanej w atrybutach obiektu w skrypcie. Silnik szuka wartości w kolejności: `DEFAULT` → `INIT_VALUE` → `VALUE`; używana jest pierwsza znaleziona. Jeśli żadna z nich nie jest ustawiona, wartość ustawiana jest na `0`.
**Zwraca**: nową wartość zmiennej.
### SET
```
INTEGER SET(INTEGER value)
```
Ustawia wartość zmiennej.
**Parametry**
- `value` — nowa wartość.
**Zwraca**: nową wartość zmiennej.
**Przykłady**
```
G_IPAGE^SET(800);
VARITEMP1^SET($2);
ITEMP^SET(STCBAZA|SRODEK);
```
### SUB
```
INTEGER SUB(INTEGER subtrahend)
```
Odejmuje argument od bieżącej wartości zmiennej, zapisuje wynik i zwraca go.
**Parametry**
- `subtrahend` — wartość odejmowana.
**Zwraca**: nową wartość zmiennej.
**Przykłady**
```
G_IPAGE^SUB(100);
VARIPRIORITY^SUB(VARIBKGOFFSETY);
```
### SWITCH
```
INTEGER SWITCH(INTEGER valueA, INTEGER valueB)
```
Jeżeli bieżąca wartość zmiennej jest równa `valueA`, zmiennej zostaje przypisana `valueB`; w przeciwnym razie — `valueA`. Pozwala to naprzemiennie przełączać między dwiema wartościami.
**Parametry**
- `valueA` — pierwsza wartość.
- `valueB` — druga wartość.
**Zwraca**: nową wartość zmiennej.
### XOR
```
INTEGER XOR(INTEGER value)
```
Wykonuje bitową różnicę symetryczną bieżącej wartości zmiennej z argumentem, zapisuje wynik i zwraca go.
**Parametry**
- `value` — wartość, z którą wykonywana jest operacja.
**Zwraca**: nową wartość zmiennej.
## Sygnały
### ONCHANGED
Wywoływany, gdy wartość zmiennej zostaje zmieniona na inną niż dotychczasowa.
### ONBRUTALCHANGED
Wywoływany przy każdym wywołaniu metody zmieniającej wartość, niezależnie od tego, czy nowa wartość różni się od poprzedniej.
### ONINIT
Wywoływany w momencie inicjalizacji zmiennej.
### ONSIGNAL
Wywoływany po otrzymaniu sygnału.

137
docs/pl/reference/KEYBOARD.md Normal file
View File

@@ -0,0 +1,137 @@
# KEYBOARD
Wbudowany obiekt reprezentujący stan klawiatury. Dostępny pod globalną nazwą `KEYBOARD` z dowolnego kontekstu (zobacz [Obiekty wbudowane](../engine/globals.md#obiekty-wbudowane)). Obsługuje zdarzenia naciśnięcia oraz zwolnienia klawiszy, w tym tryb autorepeat.
## Metody
### DISABLE
```
void DISABLE()
```
Wyłącza obsługę zdarzeń klawiatury — sygnały klawiszy przestają być emitowane.
**Przykłady**
```
KEYBOARD^DISABLE();
```
### ENABLE
```
void ENABLE()
```
Włącza obsługę zdarzeń klawiatury.
**Przykłady**
```
KEYBOARD^ENABLE();
```
### GETLATESTKEY
```
STRING GETLATESTKEY()
```
Zwraca nazwę ostatnio wciśniętego klawisza.
**Zwraca**: nazwa klawisza w postaci akceptowanej przez [`ISKEYDOWN`](#iskeydown) (zobacz [Obsługiwane klawisze](#obslugiwane-klawisze)).
**Przykłady**
```
KEYBOARD^GETLATESTKEY();
```
### ISENABLED
```
BOOL ISENABLED()
```
Sprawdza, czy obsługa klawiatury jest włączona.
**Zwraca**: [`BOOL`](BOOL.md) — `TRUE`, jeżeli klawiatura reaguje na zdarzenia.
**Przykłady**
```
KEYBOARD^ISENABLED();
```
### ISKEYDOWN
```
BOOL ISKEYDOWN(STRING keyName)
```
Sprawdza, czy podany klawisz jest aktualnie wciśnięty.
**Parametry**
- `keyName` — nazwa klawisza (zobacz [Obsługiwane klawisze](#obslugiwane-klawisze)).
**Zwraca**: [`BOOL`](BOOL.md) — `TRUE`, jeżeli klawisz jest wciśnięty. Dla nieznanej nazwy zwracane jest `FALSE`.
**Przykłady**
```
KEYBOARD^ISKEYDOWN("UP");
KEYBOARD^ISKEYDOWN("LEFT");
KEYBOARD^ISKEYDOWN(ARRAYKEYBOARD^GET(0));
```
### SETAUTOREPEAT
```
void SETAUTOREPEAT(BOOL autorepeat)
```
Ustawia, czy sygnał [`ONKEYDOWN`](#onkeydown) ma być emitowany cyklicznie tak długo, jak klawisz pozostaje wciśnięty. Domyślnie wyłączone.
**Parametry**
- `autorepeat` — `TRUE`, aby włączyć powtarzanie.
**Przykłady**
```
KEYBOARD^SETAUTOREPEAT(FALSE);
```
## Sygnały
### ONKEYDOWN
Wywoływany po naciśnięciu klawisza. Sygnał jest [parametryzowany](../engine/events.md#sygnaly-parametryzowane) nazwą klawisza — pozwala podpiąć osobną obsługę pod każdy z nich:
```
KEYBOARD:ONKEYDOWN^UP=BEHGOUP
KEYBOARD:ONKEYDOWN^DOWN=BEHGODOWN
```
Przy włączonym autorepeacie ([`SETAUTOREPEAT(TRUE)`](#setautorepeat)) sygnał jest emitowany w każdej klatce, w której klawisz pozostaje wciśnięty.
### ONKEYUP
Wywoływany po zwolnieniu klawisza. Sygnał jest parametryzowany nazwą klawisza, analogicznie do [`ONKEYDOWN`](#onkeydown).
### ONCHAR
Wywoływany po naciśnięciu klawisza dla każdego wygenerowanego znaku. Sygnał jest parametryzowany nazwą klawisza.
## Obsługiwane klawisze {#obslugiwane-klawisze}
Klawiatura silnika rozpoznaje następujące nazwy klawiszy:
- **Funkcyjne**: `F1`, `F2`, `F3`, `F4`, `F5`, `F6`, `F7`, `F8`, `F9`, `F10`, `F11`, `F12`
- **Strzałki**: `UP`, `DOWN`, `LEFT`, `RIGHT`
- **Modyfikatory**: `LSHIFT`, `RSHIFT`, `LCTRL`, `RCTRL`, `LALT`, `RALT`, `CAPSLOCK`
- **Specjalne**: `ESC`, `ENTER`, `SPACE`, `TAB`, `INSERT`, `PGUP`, `PGDN`, `HOME`
- **Litery**: `Q`, `W`, `E`, `R`, `T`, `U`, `I`, `O`, `P`, `A`, `S`, `D`, `F`, `G`, `H`, `J`, `K`, `L`, `C`, `V`, `B`, `N`, `M`
- **Cyfry**: `0`, `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9`

208
docs/pl/reference/MOUSE.md Normal file
View File

@@ -0,0 +1,208 @@
# MOUSE
Wbudowany obiekt reprezentujący stan myszy. Dostępny pod globalną nazwą `MOUSE` z dowolnego kontekstu (zobacz [Obiekty wbudowane](../engine/globals.md#obiekty-wbudowane)). Obsługuje pozycję kursora, stan przycisków oraz reaktywne zdarzenia kliknięcia, ruchu i podwójnego kliknięcia.
## Pola
### RAW
```
BOOL RAW
```
Określa, czy obiekt odczytuje surowe dane myszy (z pominięciem przyspieszenia i kalibracji systemowej).
## Metody
### DISABLE
```
void DISABLE()
```
Wyłącza odbieranie zdarzeń myszy — kursor przestaje aktualizować pozycję, a sygnały nie są emitowane.
**Przykłady**
```
MOUSE^DISABLE();
```
### DISABLESIGNAL
```
void DISABLESIGNAL()
```
Wyłącza emisję sygnałów myszy. W przeciwieństwie do [`DISABLE`](#disable) pozycja kursora nadal jest śledzona, ale obsługa sygnałów ([`ONMOVE`](#onmove), [`ONCLICK`](#onclick) itd.) nie jest wywoływana.
**Przykłady**
```
MOUSE^DISABLESIGNAL();
```
### ENABLE
```
void ENABLE()
```
Włącza odbieranie zdarzeń myszy.
**Przykłady**
```
MOUSE^ENABLE();
```
### ENABLESIGNAL
```
void ENABLESIGNAL()
```
Włącza emisję sygnałów myszy.
**Przykłady**
```
MOUSE^ENABLESIGNAL();
```
### GETPOSX
```
INTEGER GETPOSX()
```
Zwraca aktualną pozycję kursora w osi X.
**Zwraca**: współrzędna X kursora.
**Przykłady**
```
MOUSE^GETPOSX();
```
### GETPOSY
```
INTEGER GETPOSY()
```
Zwraca aktualną pozycję kursora w osi Y.
**Zwraca**: współrzędna Y kursora.
**Przykłady**
```
MOUSE^GETPOSY();
```
### HIDE
```
void HIDE()
```
Ukrywa kursor myszy.
**Przykłady**
```
MOUSE^HIDE();
```
### ISLBUTTONDOWN
```
BOOL ISLBUTTONDOWN()
```
Sprawdza, czy lewy przycisk myszy jest aktualnie wciśnięty.
**Zwraca**: [`BOOL`](BOOL.md) — `TRUE`, jeżeli przycisk jest wciśnięty.
**Przykłady**
```
MOUSE^ISLBUTTONDOWN();
```
### SET
```
void SET(STRING cursorStyle)
```
Ustawia styl kursora.
**Parametry**
- `cursorStyle` — nazwa stylu kursora (np. `"ACTIVE"`, `"ARROW"`).
**Przykłady**
```
MOUSE^SET("ACTIVE");
MOUSE^SET("ARROW");
```
### SETPOSITION
```
void SETPOSITION(INTEGER posX, INTEGER posY)
```
Ustawia pozycję kursora myszy na ekranie. Jeżeli pozycja faktycznie się zmieniła, dodatkowo emitowany jest sygnał [`ONMOVE`](#onmove).
**Parametry**
- `posX` — nowa współrzędna X kursora.
- `posY` — nowa współrzędna Y kursora.
**Przykłady**
```
MOUSE^SETPOSITION(400, 300);
MOUSE^SETPOSITION(MOUSE^GETPOSX(), VARINT0);
MOUSE^SETPOSITION(ANNMUCHA0^GETCENTERX(), ANNMUCHA0^GETCENTERY());
```
### SHOW
```
void SHOW()
```
Wyświetla kursor myszy.
## Sygnały
### ONCLICK
Wywoływany po kliknięciu przycisku myszy. Sygnał jest [parametryzowany](../engine/events.md#sygnaly-parametryzowane) nazwą wciśniętego przycisku (`LEFT`, `RIGHT`), co pozwala podpiąć osobną obsługę dla każdego z nich:
```
NAZWA_OBIEKTU:ONCLICK^LEFT=BEHLEFTCLICK
NAZWA_OBIEKTU:ONCLICK^RIGHT=BEHRIGHTCLICK
```
### ONDBLCLICK
Wywoływany po dwukrotnym kliknięciu przycisku myszy.
### ONINIT
Wywoływany w momencie inicjalizacji obiektu.
### ONMOVE
Wywoływany po wykryciu ruchu myszy (zmiany pozycji kursora).
### ONRELEASE
Wywoływany po zwolnieniu przycisku myszy.

107
docs/pl/reference/MULTIARRAY.md Normal file
View File

@@ -0,0 +1,107 @@
# MULTIARRAY
Tablica wielowymiarowa, indeksowana od `0`. Domyślnie tworzona jako tablica dwuwymiarowa o wymiarach `16 × 16`; liczba wymiarów może być zmieniona w skrypcie polem `DIMENSIONS`. Każdy wymiar rozszerza się automatycznie (podwajając rozmiar) przy próbie zapisu do pozycji wykraczającej poza bieżący zakres.
## Pola
### DIMENSIONS
```
INTEGER DIMENSIONS
```
Liczba wymiarów tablicy. Pole odczytywane podczas inicjalizacji zmiennej; domyślnie `2`. Każdy wymiar jest tworzony z początkowym rozmiarem `16`.
## Metody
### GET
```
mixed GET(INTEGER index1, [INTEGER index2, ..., INTEGER indexN])
```
Zwraca wartość z komórki o podanych współrzędnych. Liczba argumentów musi być równa liczbie wymiarów zadeklarowanej polem `DIMENSIONS`. Dla komórki, do której nie zapisano wartości, lub gdy współrzędne są poza zakresem, zwracany jest `NULL`.
**Parametry**
- `index1, …, indexN` — współrzędne komórki (numerowane od `0`), po jednej na każdy wymiar.
**Zwraca**: wartość komórki lub `NULL`.
**Przykłady**
```
ARRMAPA^GET(IKRETMOVEONMAPAX, IKRETPOSMAPAY);
ARRMAPA^GET([IPLAYERPOSX-1], IPLAYERPOSY);
ARRMAPA^GET(_I_, I1);
```
### SET
```
void SET(INTEGER index1, [INTEGER index2, ..., INTEGER indexN], mixed value)
```
Zapisuje wartość w komórce o podanych współrzędnych. Liczba argumentów musi być równa liczbie wymiarów + 1; ostatni argument to zapisywana wartość. Jeżeli którakolwiek współrzędna wykracza poza bieżący zakres wymiaru, tablica jest automatycznie powiększana (rozmiar wymiaru jest podwajany aż do objęcia współrzędnej).
**Parametry**
- `index1, …, indexN` — współrzędne komórki.
- `value` — zapisywana wartość.
**Przykłady**
```
ARRMAPA^SET(ITMPX, ITMPY, 0);
ARRMAPA^SET(IX, IY, SPOLE);
ARRMAPA^SET(IPLAYERGOONX, IPLAYERGOONY, "PLAYER");
ARRMAPA^SET([IPLAYERPOSX+ILASTDIRX], [IPLAYERPOSY+ILASTDIRY], IPLAYER);
```
### GETSIZE
```
INTEGER GETSIZE(INTEGER dimension)
```
Zwraca rozmiar podanego wymiaru tablicy.
**Parametry**
- `dimension` — indeks wymiaru (numerowany od `0`).
**Zwraca**: rozmiar wymiaru lub `0` dla nieprawidłowego indeksu.
### LOAD
```
void LOAD(STRING path)
```
Zastępuje zawartość tablicy danymi wczytanymi z pliku binarnego. Format obejmuje wymiary tablicy oraz wartości komórek.
**Parametry**
- `path` — ścieżka pliku w VFS gry.
### SAVE
```
void SAVE(STRING path)
```
Zapisuje zawartość tablicy do pliku binarnego.
**Parametry**
- `path` — ścieżka docelowego pliku w VFS gry.
## Sygnały
### ONINIT
Wywoływany w momencie inicjalizacji zmiennej; w tym momencie odczytywana jest wartość pola `DIMENSIONS` i alokowane są wymiary tablicy.
### ONSIGNAL
Wywoływany po otrzymaniu sygnału (zobacz [Zdarzenia i sygnały](../engine/events.md#onsignal)).

52
docs/pl/reference/RAND.md Normal file
View File

@@ -0,0 +1,52 @@
# RAND
Wbudowany generator liczb pseudolosowych. Dostępny pod globalną nazwą `RAND` z dowolnego kontekstu, również pod aliasem `RANDOM` (zobacz [Obiekty wbudowane](../engine/globals.md#obiekty-wbudowane)).
## Metody
### GET
```
INTEGER GET(INTEGER range)
INTEGER GET(INTEGER offset, INTEGER range)
```
Zwraca liczbę pseudolosową.
- Wariant z jednym argumentem zwraca liczbę z przedziału `[0, range)`.
- Wariant z dwoma argumentami zwraca liczbę z przedziału `[offset, offset + range)`.
Jeżeli `range` jest mniejsze lub równe `0`, zwracany jest `offset` (lub `0` w wariancie jednoargumentowym).
**Parametry**
- `offset` — początek przedziału (włącznie), domyślnie `0`.
- `range` — rozmiar przedziału (wartość górna jest wyłączona).
**Zwraca**: wylosowaną liczbę.
**Przykłady**
```
RANDOM^GET(100);
RANDOM^GET(VARI_TMP3);
RANDOM^GET(0, 3);
```
### GETPLENTY
```
void GETPLENTY(STRING arrayName, INTEGER count, INTEGER offset, INTEGER range, BOOL onlyUnique)
```
Generuje `count` liczb pseudolosowych z przedziału `[offset, offset + range)` i dołącza je do tablicy o nazwie `arrayName`. Tablica nie jest czyszczona przed dodaniem.
Jeżeli `onlyUnique` jest `TRUE`, kolejne wylosowane wartości muszą być różne od siebie; jeżeli wymagana liczba unikalnych wartości przekracza rozmiar przedziału (`count > range`), metoda nie modyfikuje tablicy. Dla `count` mniejszego od `1` metoda również nie ma efektu.
**Parametry**
- `arrayName` — nazwa docelowej zmiennej typu [`ARRAY`](ARRAY.md).
- `count` — liczba elementów do wygenerowania.
- `offset` — początek przedziału (włącznie).
- `range` — rozmiar przedziału (wartość górna jest wyłączona).
- `onlyUnique` — `TRUE`, aby wymusić unikalność wygenerowanych wartości.

282
docs/pl/reference/SCENE.md Normal file
View File

@@ -0,0 +1,282 @@
# SCENE
Pojedyncza scena — jedna plansza, ekran lub minigra. Należy do [`EPISODE`](EPISODE.md). Definiuje tło, muzykę, zakres priorytetów hotspotów oraz udostępnia metody sterowania zawartością sceny.
## Pola
### BACKGROUND
```
STRING BACKGROUND
```
Ścieżka do pliku `.IMG` z obrazem tła sceny.
### DLLS
```
STRING DLLS
```
Lista bibliotek DLL podpinanych do sceny (rozszerzeń biblioteki BlooMoo, np. `INERTIA`).
### MUSIC
```
STRING MUSIC
```
Ścieżka do pliku z muzyką tła sceny.
### MUSICVOLUME
```
INTEGER MUSICVOLUME
```
Głośność muzyki sceny. Wartość `1000` odpowiada 100%. Modyfikowane metodą [`SETMUSICVOLUME`](#setmusicvolume).
### MINHSPRIORITY
```
INTEGER MINHSPRIORITY
```
Minimalny priorytet (`Z`) hotspotów aktywnych na scenie. Modyfikowane metodą [`SETMINHSPRIORITY`](#setminhspriority).
### MAXHSPRIORITY
```
INTEGER MAXHSPRIORITY
```
Maksymalny priorytet (`Z`) hotspotów aktywnych na scenie. Modyfikowane metodą [`SETMAXHSPRIORITY`](#setmaxhspriority).
### PATH
```
STRING PATH
```
Ścieżka relatywna do katalogu `dane` zawierająca pliki sceny.
### Metadane
Następujące pola są zapisywane jako metadane i nie wpływają bezpośrednio na działanie silnika:
- `AUTHOR` — autor pliku.
- `CREATIONTIME` — data utworzenia pliku.
- `LASTMODIFYTIME` — data ostatniej modyfikacji pliku.
- `VERSION` — wersja sceny.
## Metody
### GETMAXHSPRIORITY
```
INTEGER GETMAXHSPRIORITY()
```
Zwraca maksymalny priorytet hotspotów aktywnych na scenie.
**Zwraca**: bieżąca wartość pola [`MAXHSPRIORITY`](#maxhspriority).
### GETMINHSPRIORITY
```
INTEGER GETMINHSPRIORITY()
```
Zwraca minimalny priorytet hotspotów aktywnych na scenie.
**Zwraca**: bieżąca wartość pola [`MINHSPRIORITY`](#minhspriority).
### GETPLAYINGANIMO
```
void GETPLAYINGANIMO(STRING groupName)
```
Wypełnia zmienną typu [`GROUP`](index.md) o podanej nazwie listą nazw wszystkich obiektów [`ANIMO`](index.md) aktualnie odtwarzanych na scenie. Istniejąca zawartość grupy jest nadpisywana.
**Parametry**
- `groupName` — nazwa zmiennej `GROUP`, która ma zostać wypełniona.
### PAUSE
```
void PAUSE()
```
Pauzuje muzykę sceny oraz wszystkie odtwarzane animacje [`ANIMO`](index.md).
**Przykłady**
```
BARANDALF^PAUSE();
```
### REMOVECLONES
```
void REMOVECLONES(STRING varName, INTEGER firstId, INTEGER lastId)
```
Usuwa klony zmiennej `varName` o numerach z zakresu `[firstId, lastId]`. Wartość `-1` w `lastId` oznacza „do ostatniego klonu". Klony są nazwane wg wzorca `varName_N`, gdzie `N` rośnie od `1`.
**Parametry**
- `varName` — nazwa bazowa klonowanej zmiennej.
- `firstId` — numer pierwszego klonu do usunięcia (najmniej `1`).
- `lastId` — numer ostatniego klonu do usunięcia, lub `-1` dla wszystkich klonów do końca.
**Przykłady**
```
ARCADE^REMOVECLONES(VARSCURRENTITEMOBJECT, -1, -1);
CUTSCENKI^REMOVECLONES(SANN, -1, -1);
```
### RESUME
```
void RESUME()
```
Wznawia muzykę sceny (z głośnością z pola [`MUSICVOLUME`](#musicvolume)) oraz wszystkie wstrzymane animacje [`ANIMO`](index.md).
**Przykłady**
```
BARANDALF^RESUME();
```
### RESUMEONLY
```
void RESUMEONLY(STRING groupName)
```
Wznawia tylko te wstrzymane animacje, których nazwy znajdują się w zmiennej typu [`GROUP`](index.md) o podanej nazwie.
**Parametry**
- `groupName` — nazwa zmiennej `GROUP` z listą animacji do wznowienia.
### RUN
```
mixed RUN(STRING varName, STRING methodName, [mixed param1, ..., mixed paramN])
```
Dynamicznie wywołuje metodę `methodName` na zmiennej `varName`. Zachowanie identyczne jak [`APPLICATION.RUN`](APPLICATION.md#run); wariant na poziomie sceny istnieje dla skryptów, które mają referencję do sceny zamiast do aplikacji.
**Parametry**
- `varName` — nazwa docelowej zmiennej.
- `methodName` — nazwa wywoływanej metody.
- `param1, …, paramN` — (opcjonalnie) argumenty.
**Zwraca**: wartość zwróconą przez wywołaną metodę.
**Przykłady**
```
S16_SPACEINVADERS^RUN(VARNAME, "SETPOSITION", 0, 0);
S16_SPACEINVADERS^RUN(VARNAME, "PLAY", VARTEMPSTRING);
S16_SPACEINVADERS^RUN(VARUFOHIT, "PLAY", ["TRAFIONY"+RANDOM^GET(0,2)]);
```
### RUNCLONES
```
void RUNCLONES(STRING varName, INTEGER firstId, INTEGER lastId, STRING behaviourName)
```
Wywołuje procedurę `behaviourName` dla każdego klonu zmiennej `varName` w zakresie `[firstId, lastId]`. Wartość `-1` w `lastId` oznacza „do ostatniego klonu". Procedura otrzymuje jako pierwszy argument (`$1`) nazwę klonu.
**Parametry**
- `varName` — nazwa bazowa klonowanej zmiennej.
- `firstId` — numer pierwszego klonu (najmniej `1`).
- `lastId` — numer ostatniego klonu lub `-1`.
- `behaviourName` — nazwa wywoływanej procedury.
**Przykłady**
```
S16_SPACEINVADERS^RUNCLONES("ANIMOUFO", -1, -1, "BEHINITUFO");
S71_DROGA^RUNCLONES("ANNKURA", -1, -1, "BEHINITCLONES");
```
### SETMAXHSPRIORITY
```
void SETMAXHSPRIORITY(INTEGER maxHSPriority)
```
Ustawia maksymalny priorytet hotspotów aktywnych na scenie.
**Parametry**
- `maxHSPriority` — nowa wartość maksymalnego priorytetu.
### SETMINHSPRIORITY
```
void SETMINHSPRIORITY(INTEGER minHSPriority)
```
Ustawia minimalny priorytet hotspotów aktywnych na scenie.
**Parametry**
- `minHSPriority` — nowa wartość minimalnego priorytetu.
**Przykłady**
```
MENUGLOWNE^SETMINHSPRIORITY(999);
MENUGLOWNE^SETMINHSPRIORITY(0);
```
### SETMUSICVOLUME
```
void SETMUSICVOLUME(INTEGER volume)
```
Ustawia głośność muzyki sceny. Wartość `1000` odpowiada 100%. Zmiana jest stosowana natychmiast, jeżeli muzyka jest aktualnie odtwarzana.
**Parametry**
- `volume` — nowa głośność.
**Przykłady**
```
ARCADE^SETMUSICVOLUME(G_ARRSETTINGS^GET(1));
INTRO_2^SETMUSICVOLUME(500);
DIALOGS^SETMUSICVOLUME([0.8*G_ARRSETTINGS^GET(1)]);
```
### STARTMUSIC
```
void STARTMUSIC(STRING filename)
```
Zapisuje w polu [`MUSIC`](#music) ścieżkę do pliku muzycznego, który będzie odtwarzany jako muzyka tła sceny.
**Parametry**
- `filename` — ścieżka do pliku muzycznego.
**Przykłady**
```
ARCADE^STARTMUSIC(VARSMUSIC);
MAGIC^STARTMUSIC("POJEDYNEK.WAV");
DIALOGS^STARTMUSIC("GABINETY.WAV");
```

208
docs/pl/reference/SEQUENCE.md Normal file
View File

@@ -0,0 +1,208 @@
# SEQUENCE
Sekwencja animacji. Plik `.SEQ` zawiera **zdarzenia sekwencji** — opisy ciągów animacji ([`ANIMO`](ANIMO.md)) odtwarzanych jednocześnie z towarzyszącymi im efektami dźwiękowymi ([`SOUND`](SOUND.md)). Pozwala synchronizować ze sobą obraz i dźwięk w jednej, sterowanej skryptowo jednostce.
## Pola
### FILENAME
```
STRING FILENAME
```
Ścieżka do pliku `.SEQ` z definicją sekwencji.
## Metody
### GETEVENTNAME
```
STRING GETEVENTNAME()
```
Zwraca nazwę aktualnie odtwarzanego zdarzenia sekwencji.
**Zwraca**: nazwa zdarzenia.
**Przykłady**
```
SEQSFX^GETEVENTNAME();
```
### GETPLAYING
```
STRING GETPLAYING()
```
Zwraca nazwę zmiennej typu [`ANIMO`](ANIMO.md) odtwarzanej w ramach aktualnie aktywnego zdarzenia. Jeżeli żadne zdarzenie nie jest aktywne, zwracany jest pusty ciąg.
**Zwraca**: nazwa animacji lub `""`.
### HIDE
```
void HIDE()
```
Ukrywa wszystkie animacje, które należą do sekwencji.
**Przykłady**
```
SEQJEAN^HIDE();
SEQKRET^HIDE();
```
### ISPLAYING
```
BOOL ISPLAYING()
```
Sprawdza, czy sekwencja jest aktualnie odtwarzana.
**Zwraca**: [`BOOL`](BOOL.md) — `TRUE`, jeżeli sekwencja jest w trakcie odtwarzania.
**Przykłady**
```
SEQBLANK^ISPLAYING();
SEQMANDOLINA^ISPLAYING();
```
### PAUSE
```
void PAUSE()
```
Wstrzymuje odtwarzanie sekwencji.
**Przykłady**
```
SEQCS^PAUSE();
```
### PLAY
```
void PLAY(STRING eventName)
```
Rozpoczyna odtwarzanie zdarzenia sekwencji o podanej nazwie. Po starcie emitowany jest sygnał [`ONSTARTED`](#onstarted) z nazwą zdarzenia.
**Parametry**
- `eventName` — nazwa zdarzenia z pliku `.SEQ`.
**Przykłady**
```
GADAJA2^PLAY("KOGF2");
SEQNARRATOR^PLAY(VARSTRING0);
SEQLAB^PLAY(["PLAYER"+VARINT0]);
SEQREKSIO^PLAY($1);
```
### RESUME
```
void RESUME()
```
Wznawia sekwencję wstrzymaną przez [`PAUSE`](#pause).
**Przykłady**
```
SEQCS^RESUME();
```
### SETFREQ
```
void SETFREQ(INTEGER sampleRate)
```
Ustawia próbkowanie odtwarzania dźwięku przypisanego do aktualnie aktywnego zdarzenia sekwencji. Działanie równoważne wywołaniu [`SETFREQ`](SOUND.md#setfreq) na obiekcie [`SOUND`](SOUND.md) tego zdarzenia.
**Parametry**
- `sampleRate` — docelowe próbkowanie w Hz.
### SETPAN
```
void SETPAN(INTEGER pan)
```
Ustawia panoramę stereo (rozkład lewy–prawy) dźwięku aktywnego zdarzenia. Wartość `400` odpowiada panoramie wycentrowanej, `0` — pełnemu kanałowi lewemu, `800` — pełnemu kanałowi prawemu.
**Parametry**
- `pan` — wartość panoramy w zakresie `0–800`.
### SETVOLUME
```
void SETVOLUME(INTEGER volume)
```
Ustawia głośność dźwięku aktywnego zdarzenia. Wartość `1600` odpowiada maksymalnej głośności, `0` — wyciszeniu.
**Parametry**
- `volume` — wartość głośności w zakresie `0–1600`.
### SHOW
```
void SHOW()
```
Pokazuje wszystkie animacje należące do sekwencji.
### STOP
```
void STOP([BOOL emitSignal])
```
Zatrzymuje odtwarzanie sekwencji.
**Parametry**
- `emitSignal` — (opcjonalnie) jeżeli `FALSE`, sygnał [`ONFINISHED`](#onfinished) nie zostanie wyemitowany. Domyślnie sygnał jest emitowany.
**Przykłady**
```
SEQBLANK^STOP(FALSE);
SEQMENU^STOP(TRUE);
SEQZMIANAWAGIREX^STOP();
```
## Sygnały
### ONINIT
Wywoływany w momencie inicjalizacji obiektu.
### ONSTARTED
Wywoływany po rozpoczęciu odtwarzania zdarzenia sekwencji. Argumentem (`$1`) jest nazwa rozpoczętego zdarzenia.
### ONFINISHED
Wywoływany po zakończeniu odtwarzania zdarzenia sekwencji (naturalnym lub przez metodę [`STOP`](#stop) bez argumentu `FALSE`). Argumentem (`$1`) jest nazwa zakończonego zdarzenia. Sygnał jest [parametryzowany](../engine/events.md#sygnaly-parametryzowane) tą nazwą, więc można podpiąć obsługę pod konkretne zdarzenie:
```
SEKWENCJA:ONFINISHED^IDLE=BEHAFTERIDLE
```
### ONSIGNAL
Wywoływany po otrzymaniu sygnału (zobacz [Zdarzenia i sygnały](../engine/events.md#onsignal)).

150
docs/pl/reference/SOUND.md Normal file
View File

@@ -0,0 +1,150 @@
# SOUND
Krótki efekt dźwiękowy wczytywany z pliku `.WAV`. Obsługuje sterowanie odtwarzaniem oraz zmianę próbkowania, co pozwala dynamicznie zmieniać wysokość i prędkość odtwarzanego dźwięku.
## Pola
### FILENAME
```
STRING FILENAME
```
Nazwa pliku `.WAV` z dźwiękiem. Jeżeli ścieżka nie zaczyna się od `$`, silnik dokleja prefiks `$WAVS\`. Pole odczytywane podczas inicjalizacji zmiennej; może być również ustawione w trakcie działania metodą [`LOAD`](#load).
### PRELOAD
```
BOOL PRELOAD
```
Określa, czy dane dźwięku mają być załadowane od razu przy inicjalizacji, czy dopiero przed pierwszym odtworzeniem.
## Metody
### ISPLAYING
```
BOOL ISPLAYING()
```
Sprawdza, czy dźwięk jest aktualnie odtwarzany.
**Zwraca**: [`BOOL`](BOOL.md) — `TRUE`, jeżeli dźwięk jest odtwarzany.
**Przykłady**
```
SNDATGOAL^ISPLAYING();
SNDREX0^ISPLAYING();
```
### LOAD
```
void LOAD(STRING path)
```
Wczytuje plik dźwiękowy do zmiennej, zastępując dotychczas załadowany dźwięk. Bieżące odtwarzanie zostaje zatrzymane. Jeżeli ścieżka nie zaczyna się od `$`, dodawany jest prefiks `$WAVS\`.
**Parametry**
- `path` — ścieżka pliku `.WAV` w VFS gry.
**Przykłady**
```
SNDATGOAL^LOAD(VARSTEMP0);
SNDWAV^LOAD("$WAVS\NAR_I000.WAV");
SNDANSWER^LOAD(ARRSEQ^GET(0));
```
### PAUSE
```
void PAUSE()
```
Pauzuje odtwarzanie dźwięku.
**Przykłady**
```
SND_SHIP_GAZ2^PAUSE();
```
### PLAY
```
void PLAY()
```
Rozpoczyna odtwarzanie dźwięku. Po starcie emitowany jest sygnał [`ONSTARTED`](#onstarted); po zakończeniu odtwarzania — [`ONFINISHED`](#onfinished). Jeżeli dźwięk już gra, jest najpierw zatrzymywany i odtwarzany od początku.
**Przykłady**
```
SNDTAKE^PLAY();
SNDATGOAL^PLAY();
```
### RESUME
```
void RESUME()
```
Wznawia odtwarzanie zatrzymane wcześniej przez [`PAUSE`](#pause).
**Przykłady**
```
SND_SHIP_GAZ2^RESUME();
```
### SETFREQ
```
void SETFREQ(INTEGER sampleRate)
```
Ustawia bieżące próbkowanie odtwarzanego dźwięku (w hercach). Wartość różna od próbkowania oryginalnego pliku zmienia wysokość i prędkość odtwarzania proporcjonalnie do stosunku obu wartości. Próbkowanie pliku oryginalnego silnik traktuje domyślnie jako `22050` Hz.
**Parametry**
- `sampleRate` — docelowe próbkowanie w Hz.
**Przykłady**
```
SNDENGINE0^SETFREQ(10025);
```
### STOP
```
void STOP([BOOL emitSignal])
```
Zatrzymuje odtwarzanie dźwięku.
**Parametry**
- `emitSignal` — (opcjonalnie) jeżeli `FALSE`, sygnał [`ONFINISHED`](#onfinished) nie zostanie wyemitowany. Domyślnie sygnał jest emitowany.
**Przykłady**
```
SNDATGOAL^STOP(FALSE);
SNDIDLEREX^STOP();
```
## Sygnały
### ONSTARTED
Wywoływany po rozpoczęciu odtwarzania dźwięku przez metodę [`PLAY`](#play).
### ONFINISHED
Wywoływany po zakończeniu odtwarzania (naturalnym lub przez metodę [`STOP`](#stop) bez argumentu `FALSE`).

297
docs/pl/reference/STRING.md Normal file
View File

@@ -0,0 +1,297 @@
# STRING
Ciąg znaków.
## Pola
### TOINI
```
BOOL TOINI
```
Określa, czy wartość pola jest zapisywana do pliku INI i przywracana po ponownym uruchomieniu.
### VALUE
```
STRING VALUE
```
Aktualna wartość zmiennej.
## Metody
### ADD
```
STRING ADD(STRING text)
```
Dokleja argument do bieżącej wartości zmiennej (konkatenacja), zapisuje wynik i zwraca go.
**Parametry**
- `text` — tekst do dołączenia.
**Zwraca**: nową wartość zmiennej.
**Przykłady**
```
G_SLASTOBJECTS^ADD(VARSTEMP0);
VARSMUSIC^ADD(".WAV");
S_0^ADD($1);
```
### CHANGEAT
```
STRING CHANGEAT(INTEGER index, STRING replacement)
```
Zastępuje pojedynczy znak na pozycji `index` ciągiem `replacement`. Jeżeli `replacement` ma długość różną od `1`, długość ciągu po operacji zmienia się odpowiednio. Wywołanie z `index` poza zakresem nie zmienia wartości zmiennej.
**Parametry**
- `index` — pozycja znaku do zastąpienia (numerowana od `0`).
- `replacement` — ciąg, którym zostanie zastąpiony znak.
**Zwraca**: nową wartość zmiennej (lub niezmienioną wartość, jeśli `index` był poza zakresem).
**Przykłady**
```
*VARARRAYNAME^CHANGEAT([VARCLONE-1], "NULL");
*VARENEMYSTATE^CHANGEAT([VARINT1-1], VARSTRING1);
```
### COPYFILE
```
BOOL COPYFILE(STRING source, STRING destination)
```
Kopiuje plik w wirtualnym systemie plików gry (VFS) z lokalizacji `source` do `destination`. Metoda nie korzysta z wartości zmiennej, na której jest wywoływana — operuje wyłącznie na argumentach.
**Parametry**
- `source` — ścieżka pliku źródłowego w VFS.
- `destination` — ścieżka pliku docelowego w VFS.
**Zwraca**: [`BOOL`](BOOL.md) — `TRUE`, jeżeli kopiowanie się powiodło; `FALSE` w przeciwnym razie (np. gdy plik źródłowy nie istnieje lub wystąpił błąd I/O).
**Przykłady**
```
VARSTEMP0^COPYFILE("$COMMON\ITEMS_DEF.DTA", "$COMMON\ITEMS0.DTA");
S1^COPYFILE(S1, S2);
```
### CUT
```
STRING CUT(INTEGER index, INTEGER length)
```
Zastępuje wartość zmiennej fragmentem bieżącego ciągu, zaczynającym się od pozycji `index` i o długości `length`. Jeżeli długość przekracza dostępną liczbę znaków, fragment kończy się na końcu ciągu. Jeżeli `index` jest poza zakresem, zmienna przyjmuje wartość pustego ciągu.
**Parametry**
- `index` — początkowa pozycja fragmentu (numerowana od `0`).
- `length` — długość fragmentu.
**Zwraca**: nową wartość zmiennej.
**Przykłady**
```
VARSTRING0^CUT(0, VARSTRING0^FIND("_"));
```
### FIND
```
INTEGER FIND(STRING needle)
INTEGER FIND(STRING needle, INTEGER offset)
```
Wyszukuje w bieżącej wartości zmiennej pozycję pierwszego wystąpienia podanego ciągu. Metoda nie modyfikuje wartości zmiennej.
**Parametry**
- `needle` — szukany ciąg.
- `offset` — (opcjonalnie) pozycja, od której rozpoczyna się wyszukiwanie. Domyślnie `0`.
**Zwraca**: pozycję pierwszego wystąpienia (numerowaną od `0`) lub `-1`, jeżeli ciąg nie został znaleziony.
**Przykłady**
```
VARSTEMP0^FIND("IDLE");
SWYRAZ^FIND(S1);
```
### GET
```
STRING GET()
STRING GET(INTEGER index)
STRING GET(INTEGER index, INTEGER length)
```
Zwraca fragment bieżącej wartości zmiennej. Metoda nie modyfikuje wartości zmiennej.
- W wariancie bez argumentów zwracana jest cała wartość pola `VALUE`.
- W wariantach z argumentami zwracany jest fragment zaczynający się od pozycji `index` i o długości `length` (domyślnie `1`).
Jeżeli `index` jest poza zakresem, zwracany jest pusty ciąg. Jeżeli długość przekracza liczbę dostępnych znaków, fragment kończy się na końcu ciągu.
**Parametry**
- `index` — początkowa pozycja fragmentu (numerowana od `0`).
- `length` — (opcjonalnie) długość fragmentu. Domyślnie `1`.
**Zwraca**: wycięty fragment ciągu (lub całą wartość w wariancie bezargumentowym).
**Przykłady**
```
VARSTEMP3^GET(7);
VARENEMYNAME^GET(0, VARENEMYNAME^FIND("_"));
SOBJNAME^GET(0, 1);
```
### LENGTH
```
INTEGER LENGTH()
```
Zwraca długość bieżącej wartości zmiennej. Metoda nie modyfikuje wartości zmiennej.
**Zwraca**: [`INTEGER`](INTEGER.md) — liczbę znaków w ciągu.
**Przykłady**
```
VARSTEMP0^LENGTH();
```
### LOWER
```
STRING LOWER()
```
Zamienia wszystkie litery w bieżącej wartości zmiennej na małe.
**Zwraca**: nową wartość zmiennej.
### REPLACEAT
```
STRING REPLACEAT(INTEGER index, INTEGER length, STRING replacement)
```
Zastępuje fragment bieżącego ciągu o długości `length`, zaczynający się od pozycji `index`, ciągiem `replacement`. Jeżeli długość fragmentu przekracza dostępne znaki, podmieniana jest reszta ciągu. Wywołanie z `index` poza zakresem nie zmienia wartości zmiennej.
**Parametry**
- `index` — początkowa pozycja podmienianego fragmentu (numerowana od `0`).
- `length` — długość podmienianego fragmentu.
- `replacement` — ciąg, który zostanie wstawiony w miejsce fragmentu.
**Zwraca**: nową wartość zmiennej (lub niezmienioną wartość, jeśli `index` był poza zakresem).
**Przykłady**
```
S3^REPLACEAT(0, 1, S1);
VARSTMP2^REPLACEAT(8, 2, ["00"+VARIKRAINANO]);
```
### RESETINI
```
STRING RESETINI()
```
Przywraca wartość zmiennej do wartości resetu zdefiniowanej w atrybutach obiektu w skrypcie. Silnik szuka wartości w kolejności: `DEFAULT` → `INIT_VALUE` → `VALUE`; używana jest pierwsza znaleziona. Jeśli żadna z nich nie jest ustawiona, wartość ustawiana jest na pusty ciąg.
**Zwraca**: nową wartość zmiennej.
### SET
```
STRING SET(STRING value)
```
Ustawia wartość zmiennej.
**Parametry**
- `value` — nowa wartość.
**Zwraca**: nową wartość zmiennej.
**Przykłady**
```
SCENENAME^SET(PRZYGODA^GETCURRENTSCENE());
VARSTEMP0^SET(["BEHCLICK_"+SOBJECT|IDNAME]);
VARSTEMP0^SET($1);
```
### SUB
```
STRING SUB(INTEGER index, INTEGER length)
```
Usuwa z bieżącej wartości zmiennej fragment o długości `length`, zaczynający się od pozycji `index`. Pozostałe fragmenty (przed i za usuwanym) są scalane. Wywołanie z `index` poza zakresem nie zmienia wartości zmiennej.
**Parametry**
- `index` — początkowa pozycja usuwanego fragmentu (numerowana od `0`).
- `length` — długość usuwanego fragmentu.
**Zwraca**: nową wartość zmiennej (lub niezmienioną wartość, jeśli `index` był poza zakresem).
**Przykłady**
```
VARSTEMP0^SUB(0, 5);
VARSTEMP0^SUB(VARITEMP0, [VARSTEMP0^LENGTH()-VARITEMP0]);
```
### UPPER
```
STRING UPPER()
```
Zamienia wszystkie litery w bieżącej wartości zmiennej na wielkie.
**Zwraca**: nową wartość zmiennej.
**Przykłady**
```
SDIALOGWAVENAME^UPPER();
SDIALOGPERSON^UPPER();
```
## Sygnały
### ONCHANGED
Wywoływany, gdy wartość zmiennej zostaje zmieniona na inną niż dotychczasowa.
### ONBRUTALCHANGED
Wywoływany przy każdym wywołaniu metody zmieniającej wartość, niezależnie od tego, czy nowa wartość różni się od poprzedniej.
### ONINIT
Wywoływany w momencie inicjalizacji zmiennej.

35
docs/pl/reference/SYSTEM.md Normal file
View File

@@ -0,0 +1,35 @@
# SYSTEM
Wbudowany obiekt udostępniający informacje o systemie operacyjnym. Dostępny pod globalną nazwą `SYSTEM` z dowolnego kontekstu (zobacz [Obiekty wbudowane](../engine/globals.md#obiekty-wbudowane)).
## Metody
### GETDATE
```
INTEGER GETDATE()
```
Zwraca bieżącą datę zakodowaną jako liczba całkowita w formacie `(rok-2000)*10000 + miesiąc*100 + dzień`. Na przykład `26 marca 2026` to `260326`.
**Zwraca**: zakodowaną datę.
### GETMHZ
```
INTEGER GETMHZ()
```
Zwraca taktowanie procesora w megahercach.
**Zwraca**: częstotliwość CPU w MHz.
### GETSYSTEMTIME
```
INTEGER GETSYSTEMTIME()
```
Zwraca czas pracy systemu operacyjnego w milisekundach.
**Zwraca**: uptime w milisekundach.

138
docs/pl/reference/TEXT.md Normal file
View File

@@ -0,0 +1,138 @@
# TEXT
Tekst wyświetlany na ekranie. Korzysta z czcionki ([`FONT`](FONT.md)) wskazanej w polu [`FONT`](#font), a treść, pozycja i sposób wyrównania są konfigurowane przez pozostałe pola.
## Pola
### FONT
```
STRING FONT
```
Nazwa zmiennej typu [`FONT`](FONT.md), z której pobierane są tekstury znaków.
### HJUSTIFY
```
STRING HJUSTIFY
```
Wyrównanie w poziomie wewnątrz prostokąta `RECT`. Dopuszczalne wartości: `LEFT`, `RIGHT`, `CENTER`.
### PRIORITY
```
INTEGER PRIORITY
```
Priorytet renderowania (`Z`) tekstu względem innych obiektów na scenie.
### RECT
```
INTEGER,INTEGER,INTEGER,INTEGER RECT
```
Prostokąt, w którym tekst jest rysowany — cztery liczby oddzielone przecinkami: `xLeft, yBottom, xRight, yTop`. W skrypcie pole może też wskazywać na nazwę zmiennej typu [`ANIMO`](index.md) lub [`IMAGE`](IMAGE.md), z której przejmowane są wymiary.
### TEXT
```
STRING TEXT
```
Wyświetlany tekst. Modyfikowany metodą [`SETTEXT`](#settext).
### TOCANVAS
```
BOOL TOCANVAS
```
Określa, czy tekst jest renderowany na głównej kanwie sceny. Jeżeli pole jest `FALSE`, tekst nie jest widoczny niezależnie od stanu pola `VISIBLE`.
### VISIBLE
```
BOOL VISIBLE
```
Widoczność tekstu. Modyfikowana metodami [`SHOW`](#show) i [`HIDE`](#hide).
### VJUSTIFY
```
STRING VJUSTIFY
```
Wyrównanie w pionie wewnątrz prostokąta `RECT`. Dopuszczalne wartości: `TOP`, `BOTTOM`, `CENTER`.
## Metody
### HIDE
```
void HIDE()
```
Ukrywa tekst (ustawia [`VISIBLE`](#visible) na `FALSE`).
### SETJUSTIFY
```
void SETJUSTIFY(INTEGER xLeft, INTEGER yBottom, INTEGER xRight, INTEGER yTop, STRING hJustify, STRING vJustify)
```
Ustawia w jednym wywołaniu prostokąt rysowania ([`RECT`](#rect)) oraz wyrównanie poziome ([`HJUSTIFY`](#hjustify)) i pionowe ([`VJUSTIFY`](#vjustify)).
**Parametry**
- `xLeft, yBottom, xRight, yTop` — współrzędne prostokąta.
- `hJustify` — wyrównanie poziome (`LEFT`, `RIGHT`, `CENTER`).
- `vJustify` — wyrównanie pionowe (`TOP`, `BOTTOM`, `CENTER`).
### SETPRIORITY
```
void SETPRIORITY(INTEGER priority)
```
Ustawia priorytet renderowania tekstu.
**Parametry**
- `priority` — nowa wartość pola [`PRIORITY`](#priority).
### SETTEXT
```
void SETTEXT(STRING text)
```
Zmienia wyświetlany tekst.
**Parametry**
- `text` — nowa zawartość pola [`TEXT`](#text).
**Przykłady**
```
TXTDEBUG^SETTEXT(ARRPX^GETSIZE());
TXTDEBUG^SETTEXT("SAVED");
```
### SHOW
```
void SHOW()
```
Pokazuje tekst (ustawia [`VISIBLE`](#visible) na `TRUE`).
## Sygnały
### ONINIT
Wywoływany w momencie inicjalizacji obiektu.

55
docs/pl/reference/index.md Normal file
View File

@@ -0,0 +1,55 @@
# Referencja typów
Spis typów danych dostępnych w skryptach silnika Piklib/BlooMoo. Lista będzie uzupełniana w miarę opracowywania kolejnych stron.
## Typy używane w skryptach
### Prymitywne
- [BOOL](BOOL.md) — wartość logiczna.
- [DOUBLE](DOUBLE.md) — liczba zmiennoprzecinkowa o podwójnej precyzji.
- [INTEGER](INTEGER.md) — liczba całkowita ze znakiem.
- [STRING](STRING.md) — ciąg znaków.
### Kolekcje
- [ARRAY](ARRAY.md) — tablica jednowymiarowa.
- [MULTIARRAY](MULTIARRAY.md) — tablica wielowymiarowa z automatycznym rozszerzaniem.
### Warunki logiczne
- [CONDITION](CONDITION.md) — porównanie dwóch operandów.
- [COMPLEXCONDITION](COMPLEXCONDITION.md) — kombinacja dwóch warunków operatorem `AND`/`OR`.
### Struktura kodu
- [BEHAVIOUR](BEHAVIOUR.md) — procedura.
- [CLASS](CLASS.md) — definicja klasy obiektów.
### Sceniczne
- [APPLICATION](APPLICATION.md) — najwyższy poziom hierarchii skryptów.
- [EPISODE](EPISODE.md) — logiczny segment gry.
- [SCENE](SCENE.md) — pojedyncza scena.
### Wbudowane obiekty I/O
- [KEYBOARD](KEYBOARD.md) — stan klawiatury.
- [MOUSE](MOUSE.md) — stan myszy.
- [RAND](RAND.md) — generator liczb pseudolosowych.
- [SYSTEM](SYSTEM.md) — informacje systemowe.
### Media
- [ANIMO](ANIMO.md) — animacja z pliku `.ANN`.
- [FONT](FONT.md) — definicja czcionki bitmapowej.
- [IMAGE](IMAGE.md) — statyczny obraz.
- [SEQUENCE](SEQUENCE.md) — sekwencja animacji z synchronizowanym dźwiękiem.
- [SOUND](SOUND.md) — krótki efekt dźwiękowy.
- [TEXT](TEXT.md) — tekst wyświetlany na ekranie.
## Pozostałe typy
Strony dla poniższych typów zostaną dodane w następnej kolejności:
BUTTON, CANVAS_OBSERVER, CNVLOADER, DATABASE, EXPRESSION, GROUP, INERTIA, MATRIX, PATTERN, STATICFILTER, STRUCT, TIMER, VECTOR, VIRTUALGRAPHICSOBJECT, WORLD.