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/en/engine/arithmetic.md Normal file
View File

@@ -0,0 +1,180 @@
# Arithmetic
The Piklib/BlooMoo engine performs computations exclusively inside **arithmetic expressions** enclosed in square brackets. Round parentheses are reserved for method-call argument lists and do not act as grouping inside expressions. This chapter describes the available operators, the typing rules, and the conversions between primitive types.
## Syntax
An arithmetic expression is written between square brackets. It may appear anywhere a value is expected — including as a method argument or as the value assigned to a field:
```
VARIABLE_NAME^SET([VAL1+VAL2]);
*["ANIMO_"+_I_]^PLAY();
```
Expressions can be nested using additional pairs of square brackets:
```
[[VAL1+VAL2]*VAL3]
```
## Typing rule
All binary operations in expressions follow a single rule:
> **The result's type and the right operand's type are both determined by the type of the left operand.**
The right operand is cast to the left operand's type before the operation is performed, and the result also has that type. Examples:
```
"Value" + 2.5 → "Value2.50000" # DOUBLE cast to STRING
2 + "3" → 5 # STRING cast to INTEGER
```
A consequence: operand order matters not only for non-commutative operators, but also for the type of the result.
## Type conversions
Within the typing rule, the right operand is cast according to the rules below.
### From `STRING`
| Target | Rule |
|---|---|
| [`INTEGER`](../reference/INTEGER.md) | An integer is extracted from the start of the text (similar to `parseInt`). If the text does not start with a number, the result is `0`. |
| [`DOUBLE`](../reference/DOUBLE.md) | Same as `INTEGER`, but the fractional part is preserved. The decimal separator is a dot. |
| [`BOOL`](../reference/BOOL.md) | Text matching a truthful value (`TRUE` or a non-zero number) yields `TRUE`; otherwise `FALSE`. |
```
"5" → 5
"Test" → 0
```
### From `INTEGER`
| Target | Rule |
|---|---|
| [`STRING`](../reference/STRING.md) | The decimal representation of the number. |
| [`DOUBLE`](../reference/DOUBLE.md) | The number with a zero fractional part (five zeros after the dot). |
| [`BOOL`](../reference/BOOL.md) | A non-zero value yields `TRUE`; `0` yields `FALSE`. |
```
5 → "5"
3 → 3.00000
-2 → TRUE
0 → FALSE
```
### From `DOUBLE`
| Target | Rule |
|---|---|
| [`STRING`](../reference/STRING.md) | Decimal representation with a dot and five fractional digits. For `0.0` the fractional part is omitted. |
| [`INTEGER`](../reference/INTEGER.md) | Rounded to the nearest integer; ties round up for positive values and down for negative values. |
| [`BOOL`](../reference/BOOL.md) | Indirect: first cast to `INTEGER` (with the rounding above), then to `BOOL`. Values in the open interval `(-0.5, 0.5)` give `FALSE`, all others `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
```
### From `BOOL`
| Target | Rule |
|---|---|
| [`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`. |
## Arithmetic operators
Expressions support the following binary operators:
| Operator | Meaning |
|---|---|
| `+` | addition / concatenation |
| `-` | subtraction |
| `*` | multiplication |
| `@` | division |
| `%` | remainder |
### Addition (`+`)
| Left operand type | Behaviour |
|---|---|
| [`STRING`](../reference/STRING.md) | Concatenation of the right operand (after casting) onto the left. |
| [`INTEGER`](../reference/INTEGER.md) | Numeric sum. |
| [`DOUBLE`](../reference/DOUBLE.md) | Numeric sum. |
| [`BOOL`](../reference/BOOL.md) | Logical conjunction (`AND`). `TRUE + FALSE` yields `FALSE`. |
### Subtraction (`-`)
| Left operand type | Behaviour |
|---|---|
| [`STRING`](../reference/STRING.md) | No effect; the result is the left operand. |
| [`INTEGER`](../reference/INTEGER.md) | Numeric difference. |
| [`DOUBLE`](../reference/DOUBLE.md) | Numeric difference. |
| [`BOOL`](../reference/BOOL.md) | No effect; the result is the left operand. |
### Multiplication (`*`)
| Left operand type | Behaviour |
|---|---|
| [`STRING`](../reference/STRING.md) | No effect; the result is the left operand. |
| [`INTEGER`](../reference/INTEGER.md) | Numeric product. |
| [`DOUBLE`](../reference/DOUBLE.md) | Numeric product. |
| [`BOOL`](../reference/BOOL.md) | Logical disjunction (`OR`). `FALSE * TRUE` yields `TRUE`. |
### Division (`@`)
| Left operand type | Behaviour |
|---|---|
| [`STRING`](../reference/STRING.md) | No effect; the result is the left operand. |
| [`INTEGER`](../reference/INTEGER.md) | Integer quotient. |
| [`DOUBLE`](../reference/DOUBLE.md) | Floating-point quotient. |
| [`BOOL`](../reference/BOOL.md) | No effect; the result is the left operand. |
Dividing a numeric type by `0` crashes the engine.
### Remainder (`%`)
| Left operand type | Behaviour |
|---|---|
| [`STRING`](../reference/STRING.md) | No effect; the result is the left operand. |
| [`INTEGER`](../reference/INTEGER.md) | Remainder. |
| [`DOUBLE`](../reference/DOUBLE.md) | Remainder truncated to an integer and then cast back to `DOUBLE`. The fractional part is lost — for example, `1.5 % 2` yields `1.00000`, not `1.50000`. |
| [`BOOL`](../reference/BOOL.md) | No effect; the result is the left operand. |
Taking a remainder with `0` as the right operand crashes the engine.
## Comparison operators
Expressions support the standard comparisons: `==`, `!=`, `<`, `<=`, `>`, `>=`. The right operand is first cast to the left operand's type (per the [typing rule](#typing-rule)), and the comparison is then performed.
### Equality and inequality
`==` returns `TRUE` if both operands (after casting) are equal; `!=` returns the opposite. For [`STRING`](../reference/STRING.md) the comparison is character-by-character; for numeric types, it is value-based.
### Less / greater
| Left operand type | `<` returns `TRUE` if |
|---|---|
| [`STRING`](../reference/STRING.md) | The left operand is lexicographically smaller than the right (character-by-character in CP1250 encoding). |
| [`INTEGER`](../reference/INTEGER.md) | The left operand's value is smaller. |
| [`DOUBLE`](../reference/DOUBLE.md) | The left operand's value is smaller. |
| [`BOOL`](../reference/BOOL.md) | The left operand is `FALSE` and the right is `TRUE` (`FALSE < TRUE`). |
`>` returns `TRUE` in the symmetric cases. `<=` and `>=` are equivalent to `<` or `==`, and `>` or `==`, respectively.
## Logical operators
`&&` (conjunction) and `||` (disjunction) accept only [`BOOL`](../reference/BOOL.md) operands. Passing an operand of another type (even one that could be cast) crashes the engine.
| Operator | Result |
|---|---|
| `&&` | `TRUE` only if both operands are `TRUE`. |
| `||` | `TRUE` if at least one operand is `TRUE`. |
Inside the [compound `@IF` condition](scripts.md#compound-condition), `&&` and `||` behave the same way, but they are part of the condition string rather than operators of an arithmetic expression.

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

@@ -0,0 +1,90 @@
# Events and signals
The Piklib/BlooMoo engine drives game logic with a reactive, signal-based model. Every object can emit named signals, and scripts can attach procedures or code blocks to react to them. This chapter describes how the mechanism works and lists the most common signals.
## Attaching a signal handler
A signal is attached like any other property of an object — the value is either a procedure name or a code block:
```
OBJECT_NAME:ONCHANGED=PROCEDURE_NAME
OBJECT_NAME:ONCHANGED={OTHER_OBJECT^PLAY("TADA");}
```
Each signal name can have at most one handler attached to it on a given object.
## Parameterised signals
Some signals — notably [`ONCHANGED`](#onchanged) and [`ONBRUTALCHANGED`](#onbrutalchanged) — are emitted together with a value. That value can be used to filter the handler: the engine first looks up a handler matching the pair `signal + value`, and only falls back to a generic handler for the signal name if no specific one is registered.
The discriminator follows the signal name after a caret `^`:
```
OBJECT_NAME:ONBRUTALCHANGED^3=HANDLER_FOR_THREE
OBJECT_NAME:ONBRUTALCHANGED=GENERIC_HANDLER
```
In the example above, `OBJECT^SET(3)` runs `HANDLER_FOR_THREE`; any other value runs `GENERIC_HANDLER`.
## Handler execution
The signal system is synchronous and single-threaded. Emitting a signal immediately transfers control to its handler: the currently executing procedure is paused, the handler runs, and once it returns, control resumes where the signal was emitted. Signals are not queued.
A chain of nested signal–procedure–signal–procedure invocations forms a call tree. The jump operators affect that tree as follows:
- [`@ONEBREAK`](scripts.md#jump-operators) — aborts only the current procedure and returns to its caller.
- [`@BREAK`](scripts.md#jump-operators) — aborts the entire call tree started by the original signal emission.
## Signal arguments
Some signals are emitted with extra arguments. Inside a handler, those arguments are available exactly like procedure arguments — through `$1`, `$2`, … (numbered from `1`). This lets a handler react to the specific value that triggered the signal.
## Universal signals
### ONINIT
Fired during the variable's initialisation as its file is loaded. The order in which `ONINIT` is fired across the variables of a single file is fixed and goes by type; the details are in [Variable initialisation](scripts.md#variable-initialisation).
Typical uses: filling in [arrays](../reference/index.md), setting up the initial state of animations, loading data from external files.
### ONSIGNAL
A general-purpose signal, emitted by calling the global `SEND` method on an object:
```
OBJECT_NAME^SEND("MY_SIGNAL");
```
The string passed in is available inside the handler as the first argument (`$1`). This mechanism allows custom events to be defined without relying on value changes or animation events.
## Value-change signals
Fired by [primitive types](../reference/index.md) (and any other type with a `VALUE` field) whenever the value is modified.
### ONCHANGED
Fired only when the new value differs from the previous one. The argument (`$1`) is the new value.
### ONBRUTALCHANGED
Fired on every modification, even if the new value is identical to the previous one. The argument (`$1`) is the new value.
In practice, `ONBRUTALCHANGED` is useful for detecting that a value-setting method (`SET`, `INC`, `SWITCH`, …) was called at all, regardless of whether it actually changed the value.
## Signals from graphical objects and sequences
### ONSTARTED
Fired when an animation or sequence starts playing.
- For a **sequence** — fired once, with the current event name from the `.SEQ` file as its argument.
- For an **animation** — fired with the event name from the `.ANN` file. If the animation is driven by a sequence, this signal can fire multiple times as the animation loops.
### ONFINISHED
Fired when playback finishes:
- for an **animation** — after the last frame is displayed and playback stops,
- for a **sequence** — after the last event finishes (or for each individual event played in turn, depending on configuration).
In both cases the signal is also fired in response to a manual `STOP` call (with no argument or with `TRUE`).

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

@@ -0,0 +1,70 @@
# Global and built-in variables
The engine exposes a handful of variables and names that can be referenced from anywhere in the scripts, regardless of context depth. This chapter covers the built-in objects, the implicit variables, the special procedures, and the variable-lookup hierarchy.
## Context hierarchy
Each loaded script creates its own variable context. Contexts are nested: a scene's context inherits from its episode's context, which inherits from the application's context, which in turn inherits from the engine's global context. Variable lookup walks from the lowest context upwards — a variable in a lower context shadows one with the same name in a higher context, but higher-context variables remain visible from lower ones.
## Built-in objects
The following objects are created lazily by the engine on first access and are available from any context under fixed names:
| Name | Type | Description |
|---|---|---|
| `MOUSE` | [`MOUSE`](../reference/index.md) | Mouse state (position, buttons). |
| `KEYBOARD` | [`KEYBOARD`](../reference/index.md) | Keyboard state. |
| `RAND` | [`RAND`](../reference/index.md) | Pseudo-random number generator. Also available under the alias `RANDOM`. |
| `SYSTEM` | [`SYSTEM`](../reference/index.md) | Interface to system functions (time, environment). |
All four objects are singletons in the engine's global context — every script reference resolves to the same instance.
## Objects from `Application.def`
Objects defined in `Application.def` — of type [`APPLICATION`](../reference/index.md), [`EPISODE`](../reference/index.md), and [`SCENE`](../reference/index.md) — are loaded into the engine's global context and remain visible to every script in the game. Other types in that file are ignored (see [Entry point](scripts.md#entry-point)).
## Implicit variables
The engine injects a few variables that are not declared explicitly in scripts.
### `_I_`
The loop counter set up by the [`@LOOP`](scripts.md#loop) statement. It is an [`INTEGER`](../reference/INTEGER.md) variable created locally in the current iteration's context. Its value updates automatically as the loop progresses.
Inside a `@LOOP`, `_I_` can be read in arithmetic expressions and passed as a method argument:
```
@LOOP({*["ANIMO_"+_I_]^PLAY();}, 0, 10, 1);
```
The [`@FOR`](scripts.md#for-bloomoo) loop allows a custom counter name to be supplied; in that case `_I_` is not set.
### `THIS`
A reference to the object that emitted the signal currently being handled. Only available inside a signal-handling block and procedures called from it. Its behaviour is detailed in [The THIS variable](scripts.md#the-this-variable).
### `$1`, `$2`, … `$N`
The arguments of a procedure or signal handler (numbered from `1`). Available only inside the body of a procedure or handler block:
```
PROCEDURE:CODE={VARIABLE_NAME^SET($1);}
```
This syntax is also covered in [Procedure arguments](scripts.md#procedure-arguments).
## Special procedures
Certain procedure names have conventional meaning — the engine invokes them automatically at fixed points in the lifecycle.
### `__ONINIT__`
Called once the initialisation of every variable in a loaded file has finished. See [Variable initialisation](scripts.md#variable-initialisation). A common use is to set the scene's initial state once all of its objects are available.
### `__INIT__`
Called after the scene has been loaded and variable initialisation has completed — just before control is handed off to the game's logic. Used to set scene-specific state that depends on the current episode or application.
## Naming convention
Names surrounded by double underscores (`__NAME__`) are reserved for the engine and for global conventional names (e.g. `__KEYB__`, `__INIT__`, `__ONINIT__`). AidemMedia scripts also use this format for their own globally significant variables to avoid being shadowed in local contexts.

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

@@ -0,0 +1,38 @@
# Engine
**Piklib** (later **BlooMoo**) is a 32-bit graphical engine created by Aidem Media for a series of Polish adventure games released in the 2000s. This documentation describes the engine's internal logic and how it executes the games' scripts.
## Scope
This documentation focuses on the engine's **scripting language** and the **execution model** as seen from script-level code — that is, what a content programmer needs in order to read existing scripts or write new ones.
It is not a documentation of the engine's source code, nor a complete specification of every internal data structure; those areas are being filled in gradually.
## Structure
The engine documentation is divided into five chapters:
- [Scripts](scripts.md) — script syntax, the parser, loading order, and object initialisation.
- [Arithmetic](arithmetic.md) — computational expressions, operators, and conversion rules between primitive types.
- [Events and signals](events.md) — the engine's reactive model, attaching handlers, propagation through the call tree.
- [Global variables](globals.md) — built-in objects (`MOUSE`, `KEYBOARD`, `RAND`, `SYSTEM`), implicit variables (`_I_`, `THIS`, `$N`), and special procedures.
- [Engine quirks](quirks.md) — non-standard behaviours that are easy to miss.
The full list of available data types is in the [Type reference](../reference/index.md).
## Games using the engine
The list is incomplete and will be extended as more titles are identified.
| Game | Engine version |
|---|---|
| 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/en/engine/quirks.md Normal file
View File

@@ -0,0 +1,118 @@
# Engine quirks
The Piklib/BlooMoo engine has a number of non-standard behaviours that often surprise programmers used to mainstream scripting languages. This chapter collects the most common ones in a single place.
## Expressions and operators
### Only square brackets group computations
Inside arithmetic expressions, grouping is done exclusively with `[ ]`. Round parentheses `( )` are reserved for method-call argument lists and have no grouping role (see [Arithmetic](arithmetic.md#syntax)).
### `@` instead of `/` for division
The division operator is the at-sign `@`, not `/`. Using `/` in an expression is not interpreted as division.
### The result type follows the left operand
All binary operations cast the right operand to the type of the left. The result also takes the left operand's type. The order of operands has non-trivial consequences (see [Typing rule](arithmetic.md#typing-rule)):
```
"Value" + 2.5 → "Value2.50000"
2 + "3" → 5
```
### Operators on `BOOL` have inverted logic
The `+` operator on [`BOOL`](../reference/BOOL.md) behaves as a logical conjunction (`AND`), and `*` as a disjunction (`OR`). The operators `-`, `@`, and `%` on `BOOL` have no effect (see [Arithmetic operators](arithmetic.md#arithmetic-operators)).
### `%` on `DOUBLE` loses the fractional part
The remainder operator on [`DOUBLE`](../reference/DOUBLE.md) first computes the result and then truncates it to an integer before casting it back to `DOUBLE`. As a result, `1.5 % 2` yields `1.00000`, not `1.50000`.
### `&&` and `||` accept only `BOOL`
The logical operators perform no implicit casting, even when the operand could be converted to `BOOL`. Passing an operand of any other type crashes the engine.
### Division by `0` in expressions crashes
Unlike the numeric-type methods (where `DIV` and `MOD` leave the value unchanged), the `@` and `%` operators in an arithmetic expression crash the engine when the right operand is `0`.
## Script syntax
### Code blocks must fit on one line
The entire block between `{` and `}` must fit on a single line of the script file. Multi-line blocks are not supported.
### Every statement must end with a semicolon
Including the last statement in a code block. Omitting the final semicolon can cause that statement to be skipped.
### Comments: `#` for lines, `!` for statements
A line starting with `#` is skipped entirely. A single statement preceded by `!` is commented out up to the next semicolon.
### The equality comparator changes in compound conditions
In a [simple `@IF` condition](scripts.md#simple-condition), equality is written as `_`. In a [compound `@IF` condition](scripts.md#compound-condition), the same comparator is written as an apostrophe `'`. The remaining comparators (`<`, `>`, `<_`/`<'`, `>_`/`>'`) follow the same pattern.
### Unquoted text is first looked up as a variable name
A value written without quotes is first interpreted as a variable name. If a variable with that name exists, its value is used; otherwise the text is treated as a [`STRING`](../reference/STRING.md) literal. This can lead to hard-to-spot collisions when a literal accidentally matches a variable name.
### Repeated object declarations merge properties
A repeated `OBJECT=NAME` line in the same file does not overwrite the previous definition — the engine merges the new properties into the existing object and overrides entries with the same keys.
### `Application.def` should end with an empty line
Missing a trailing empty line in `Application.def` can leave the last scene incorrectly parsed, which manifests as a black screen at startup.
## Numbers
### `DOUBLE` accepts `d` as the exponent marker
In scientific notation, both `e` and `d` are recognised as exponent separators: `1.23e4` and `1.23d4` are equivalent.
### `DOUBLE → INTEGER` rounds, it does not truncate
When casting [`DOUBLE`](../reference/DOUBLE.md) to [`INTEGER`](../reference/INTEGER.md), the value is rounded to the nearest integer rather than truncated. For positive values, `.5` rounds up; for negative values, it rounds down — so `-0.5 → -1` and `0.5 → 1`.
### `STRING → INTEGER` returns `0` instead of erroring
Casting a non-numeric string to [`INTEGER`](../reference/INTEGER.md) (or [`DOUBLE`](../reference/DOUBLE.md)) returns `0` (`0.00000`) silently. This can mask bugs in expressions mixing textual literals with numeric ones.
## Type methods
### `DOUBLE.MOD` drops the fractional part
Like the `%` operator, [`MOD`](../reference/DOUBLE.md#mod) on `DOUBLE` returns the integer part of the remainder.
### `DOUBLE.SGN` returns `INTEGER`, not `DOUBLE`
The [`SGN`](../reference/DOUBLE.md#sgn) method is the only `DOUBLE` method that does not modify the variable, and its return value is an [`INTEGER`](../reference/INTEGER.md).
### `INTEGER.RANDOM(min, max)` is inclusive on both ends
The two-argument form of [`RANDOM`](../reference/INTEGER.md#random) returns a value from `[min, max]`, including both endpoints. The one-argument form returns `[0, bound)`.
### `INTEGER.DIV` and `INTEGER.MOD` with `0` leave the value unchanged
Unlike division with the `@`/`%` operators in an expression, the [`DIV`](../reference/INTEGER.md#div) and [`MOD`](../reference/INTEGER.md#mod) methods on `INTEGER` return the unchanged current value when given a `0` divisor instead of crashing. The same applies to the `DOUBLE` variants.
### `STRING.COPYFILE` ignores its receiver
The [`COPYFILE`](../reference/STRING.md#copyfile) method on [`STRING`](../reference/STRING.md) does not use the value of the variable on which it is called — it operates purely on its two path arguments.
### `STRING.CHANGEAT` always replaces exactly one character
Regardless of the length of the replacement string, [`CHANGEAT`](../reference/STRING.md#changeat) removes a single character from the current value at the given position and inserts the entire replacement string in its place. The string length after the operation may differ from before.
## `THIS` in signal handlers
### `THIS.GETNAME` returns `"temp"`
Even though `THIS` references the object that emitted the signal, retrieving its name with `GETNAME` returns the string `"temp"`, hinting at an internal temporary-wrapper representation.
### Not every type-specific method works on `THIS`
Calling `GET`/`SET` (for primitive types) or `SHOW`/`HIDE`/`PLAY`/`PAUSE`/`STOP`/`RESUME` (for graphical objects) works reliably. Calling a type-specific method such as [`GETCFRAMEINEVENT`](../reference/index.md) on `ANIMO` typically crashes the engine. See [The THIS variable](scripts.md#the-this-variable) for details.

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

@@ -0,0 +1,280 @@
# Scripts
The Piklib/BlooMoo engine drives game logic by interpreting text-based scripts. This chapter describes the syntax of those scripts, how the engine loads them, and the order in which objects are initialised.
## File formats
Scripts are stored in files with the `.CNV`, `.DEF`, `.CLASS`, and `.SEQ` extensions. They all share the same basic textual structure and differ only in their intended use.
The engine treats all script content as uppercase and is case-insensitive. By convention, scripts are written in uppercase.
### Encryption
Files shipped with the game are encrypted by default using a transposition cipher with a variable offset. An encrypted file begins with a header of the form:
```
{<X:N>}
```
where `X` is a letter indicating the direction of the offset (`D` means a negative offset) and `N` is the offset value. The engine detects this header automatically and decrypts the rest of the file before parsing. Files without this header are read as plain text.
## Object declaration
An object begins with a line containing the `OBJECT` keyword:
```
OBJECT=OBJECT_NAME
```
Lines between consecutive `OBJECT=` lines define properties of the current object. The definition lasts until the end of the file or the next `OBJECT=` line.
If the same object is declared more than once in a single file, its properties are merged — later entries override earlier ones.
## Object properties
Properties are written as `objectName:property=value`:
```
OBJECT_NAME:PROPERTY=VALUE
```
Signals can take an additional parameter after a caret (`^`):
```
OBJECT_NAME:ONBRUTALCHANGED^3=PROCEDURE_NAME
```
In both cases, the engine accepts both `KEY=VALUE` and `KEY = VALUE` (with spaces around the equals sign).
## Variable type
The type is essential — without it, the engine does not know how to handle the object, and the result is usually a hard crash. The type is declared with the `TYPE` property:
```
OBJECT_NAME:TYPE=STRING
```
The full list of available types is in the [Type reference](../reference/index.md).
## Literals and strings
How a literal is interpreted depends on its context:
- Text in double quotes (`"..."`) is always treated as a [`STRING`](../reference/STRING.md).
- Unquoted text is first checked against the names of existing variables — if a variable with that name exists, its value is used. Otherwise the text is taken literally.
Floating-point numbers accept both standard notation (`1.234`) and scientific notation with the letter `e` or `d` (`1.23e4`, `1.23d4`).
## Code blocks
Code blocks — used as the value of a signal or as the body of a procedure — are written inside curly braces. Statements are separated by semicolons; the final statement must also end with a semicolon, otherwise it may not be executed.
```
OBJECT_NAME:ONCHANGED={VARIABLE2^PLAY("TADA");}
```
The entire code block must fit on a single line — the engine does not support multi-line blocks directly inside a script file.
## Comments
The engine recognises two forms of comments:
- **Line comment** — a line starting with `#` is skipped entirely.
- **Statement comment** — a single statement preceded by `!` is treated as commented out, up to the next semicolon.
## Method calls
Methods are called using the caret (`^`):
```
OBJECT_NAME^METHOD(arg1, arg2);
```
## Arithmetic expressions
Computational expressions are written inside square brackets:
```
VARIABLE_NAME^SET([VARIABLE_NAME^GET()+"2"]);
```
Operators and typing rules are described in the [Arithmetic](arithmetic.md) chapter.
## String pointers
A `*` before a variable name or an expression means that the value is to be used as the name of another variable. This allows dynamic references built from text:
```
*VARIABLE_NAME^PLAY();
*["ANIMO_"+_I_]^PLAY();
```
In the first form, `VARIABLE_NAME` should be a [`STRING`](../reference/STRING.md) containing the actual object's name. In the second, the object name is constructed from an arithmetic expression.
## Procedure arguments
Inside the body of a procedure, arguments are accessed with a dollar sign followed by a number (numbered from `1`):
```
PROCEDURE:CODE={VARIABLE_NAME^SET($1);}
```
## The THIS variable
Inside a block that handles a signal, an implicit `THIS` variable is available, set to a reference to the object that fired the signal. `THIS` is also accessible from procedures called from within such a block.
`THIS` behaves unusually: calling `GETNAME` on it returns the string `"temp"`, suggesting that under the hood it is a temporary wrapper. The following work reliably on `THIS`:
- `GET` and `SET` for primitive types,
- `SHOW`, `HIDE`, `PLAY`, `PAUSE`, `STOP`, and `RESUME` for graphical objects ([`ANIMO`](../reference/index.md)).
Calling another type-specific method (e.g. `GETCFRAMEINEVENT` on [`ANIMO`](../reference/index.md)) usually crashes the engine. To work around this, AidemMedia scripts use the following pattern: store the object's name in a [`STRING`](../reference/STRING.md) variable first, then call `^RUN(string_variable, method_name)`, which internally resolves the string pointer to the actual object.
## Loops
### @LOOP
```
@LOOP(BEHAVIOUR code, INTEGER start, INTEGER delta, INTEGER increment)
```
Executes `code` for counter values `_I_` in the range `[start, start + delta)` with step `increment`. In pseudocode:
```
for (int _I_ = start; _I_ < start + delta; _I_ += increment) {
code;
}
```
### @FOR (BlooMoo)
```
@FOR(INTEGER counter, BEHAVIOUR code, INTEGER start, INTEGER delta, INTEGER increment)
```
Identical to `@LOOP`, except that the first argument selects a custom variable to act as the counter instead of the default `_I_`.
### @WHILE
```
@WHILE(mixed value1, STRING comparator, mixed value2, BEHAVIOUR code)
```
Executes `code` as long as the condition `value1 comparator value2` holds. The list of comparators is described below in [Conditional](#conditional).
## Conditional
The engine provides two forms of `@IF`.
### Simple condition
```
@IF(mixed value1, STRING comparator, mixed value2, BEHAVIOUR codeTrue, BEHAVIOUR codeFalse)
```
Available comparators:
| Comparator | Meaning |
|---|---|
| `_` | equal to |
| `!_` | not equal to |
| `<` | less than |
| `<_` | less than or equal |
| `>` | greater than |
| `>_` | greater than or equal |
### Compound condition
```
@IF(STRING condition, BEHAVIOUR codeTrue, BEHAVIOUR codeFalse)
```
Compound conditions add logical operators:
- `&&` — conjunction (and)
- `||` — disjunction (or)
In a compound condition, the equals sign is written as an apostrophe (`'`) rather than an underscore (`_`):
| Comparator | Meaning |
|---|---|
| `'` | equal to |
| `!'` | not equal to |
| `<` | less than |
| `<'` | less than or equal |
| `>` | greater than |
| `>'` | greater than or equal |
## Dynamic variable creation
Variables can be created on the fly inside a code block:
```
@INT(STRING name, INTEGER value)
@DOUBLE(STRING name, DOUBLE value)
@STRING(STRING name, STRING value)
@BOOL(STRING name, BOOL value)
```
Each statement creates a variable of the matching type with the given name and initial value.
## Jump operators
Inside loops and procedures, control flow can be redirected with:
- `@CONTINUE()` — skips the remaining statements in the current loop iteration and moves to the next one.
- `@BREAK()` — aborts the entire call tree started by the current signal or invocation.
- `@ONEBREAK()` — aborts the current procedure only.
- `@RETURN(mixed value)` — sets the value returned by the procedure but does not stop it from executing.
## Script loading order
Scripts in the engine are organised hierarchically: scripts at lower levels can see variables from their own scope and from all ancestors, but not the other way around.
### Entry point
The engine starts from `Application.def` in the `dane` subdirectory. This file defines objects of types [`APPLICATION`](../reference/index.md), [`EPISODE`](../reference/index.md), and [`SCENE`](../reference/index.md) — other types in this file are ignored.
Example contents:
```
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
```
### Loading subsequent files
After `Application.def` is read, the engine loads a `.CNV` file for each defined object. The file path is built from the object's `PATH` attribute (relative to the `dane` directory), the object's name, and the `.CNV` extension. If the file does not exist, loading is silently skipped.
The loading order is:
1. The file bound to the `APPLICATION` object.
2. The file of the first episode (`STARTWITH` attribute of `APPLICATION`).
3. The file of the first scene of that episode (`STARTWITH` attribute of `EPISODE`).
When locating files, the engine also takes the currently selected language into account (see [`APPLICATION.SETLANGUAGE`](../reference/APPLICATION.md#setlanguage)) — the chosen language identifier points to a subfolder of localised assets that is consulted while loading game files.
### Variable initialisation
Within each file, variables are created and initialised in a fixed order by type:
1. Procedures.
2. Primitive types ([`STRING`](../reference/STRING.md), [`DOUBLE`](../reference/DOUBLE.md), [`INTEGER`](../reference/INTEGER.md), [`BOOL`](../reference/BOOL.md)).
3. Arrays and conditions.
4. Animations, images, sounds, and fonts.
5. Buttons, text fields, sequences, mouse, keyboard, canvas observer.
For each variable in this phase the `ONINIT` signal is fired. Once all variables are initialised, the engine calls the `__ONINIT__` procedure if one is defined.

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

@@ -0,0 +1,19 @@
# Rex-EMoolator
Unofficial documentation of the **Piklib** and **BlooMoo** scripting engines used by the *Reksio's Adventures* game series, and of the **Rex-EMoolator** emulator.
## What you'll find here
- the structure of the engine's scripting language,
- the data types and objects available to scripts,
- the methods, fields, and signals exposed by each type,
- how the engine interprets files, the loading order, and the data formats.
## Navigation
- [Engine](engine/index.md) — the scripting language, execution model, events, globals, and non-standard behaviours.
- [Type reference](reference/index.md) — alphabetical list of types available in scripts.
## Status
This documentation is a work in progress. Much of it is derived from analysis of the original scripts and engine reverse-engineering; behaviour that has not yet been confirmed is annotated accordingly.

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

@@ -0,0 +1,875 @@
# ANIMO
An animation loaded from an `.ANN` file. The most complex visual type in the engine — supports multiple events (frame sequences), variable FPS, an anchor point, opacity, collision monitoring, and a button mode.
An animation is made up of **events**, each of which is a sequence of **frames**. The frame index inside an event starts at `0`, and the global frame index across the whole animation is also tracked separately from `0`.
## Fields
### ASBUTTON
```
BOOL ASBUTTON
```
Treats the animation as a clickable button. Modified through [`SETASBUTTON`](#setasbutton).
### FILENAME
```
STRING FILENAME
```
Name of the `.ANN` file with the animation. Read at variable initialisation; can be overwritten via [`LOAD`](#load).
### FPS
```
INTEGER FPS
```
Number of animation frames per second. Modified through [`SETFPS`](#setfps).
### MONITORCOLLISION
```
BOOL MONITORCOLLISION
```
Whether the animation participates in collision detection. Modified through [`MONITORCOLLISION`](#monitorcollision-1) and [`REMOVEMONITORCOLLISION`](#removemonitorcollision).
### MONITORCOLLISIONALPHA
```
BOOL MONITORCOLLISIONALPHA
```
Whether collision detection takes the alpha channel into account.
### PRELOAD
```
BOOL PRELOAD
```
Whether the animation data is loaded eagerly at initialisation.
### PRIORITY
```
INTEGER PRIORITY
```
Rendering priority (`Z`) relative to other scene objects.
### TOCANVAS
```
BOOL TOCANVAS
```
Whether the animation is drawn on the scene's main canvas. Setting this to `FALSE` hides the animation visually, but the engine keeps playing it and firing the associated events.
### VISIBLE
```
BOOL VISIBLE
```
Animation visibility. Modified through [`SHOW`](#show) and [`HIDE`](#hide).
## Methods
### GETANCHOR
```
STRING GETANCHOR()
```
Returns the currently configured anchor, in the form passed to [`SETANCHOR`](#setanchor).
**Returns**: the anchor name or its coordinates.
### GETCENTERX
```
INTEGER GETCENTERX()
```
Returns the X coordinate of the centre of the current frame's bounding box.
**Returns**: centre X.
**Examples**
```
ANNREX^GETCENTERX();
```
### GETCENTERY
```
INTEGER GETCENTERY()
```
Returns the Y coordinate of the centre of the current frame's bounding box.
**Returns**: centre Y.
### GETCFRAMEINEVENT
```
INTEGER GETCFRAMEINEVENT()
```
Returns the index of the current frame inside the currently playing event (counted from `0`).
**Returns**: the frame's index in the event.
**Examples**
```
ANNREX^GETCFRAMEINEVENT();
```
### GETCURRFRAMEPOSX
```
INTEGER GETCURRFRAMEPOSX()
```
Returns the X offset of the currently displayed frame image (per-frame, defined in the animation file).
**Returns**: frame X offset.
### GETCURRFRAMEPOSY
```
INTEGER GETCURRFRAMEPOSY()
```
Returns the Y offset of the currently displayed frame image.
**Returns**: frame Y offset.
### GETENDX
```
INTEGER GETENDX()
```
Returns the right edge of the current frame's bounding box.
**Returns**: right edge X.
### GETENDY
```
INTEGER GETENDY()
```
Returns the bottom edge of the current frame's bounding box.
**Returns**: bottom edge Y.
### GETEVENTNAME
```
STRING GETEVENTNAME()
```
Returns the name of the currently playing event.
**Returns**: event name.
**Examples**
```
ANNREX^GETEVENTNAME();
```
### GETFRAME
```
INTEGER GETFRAME()
```
Returns the global index of the currently displayed frame (independent of the event subdivision).
**Returns**: the global frame index.
### GETFRAMENAME
```
STRING GETFRAMENAME()
```
Returns the name of the currently displayed frame (the frame image file name).
**Returns**: the frame name.
### GETHEIGHT
```
INTEGER GETHEIGHT()
```
Returns the height of the current animation frame.
**Returns**: height in pixels.
### GETMAXHEIGHT
```
INTEGER GETMAXHEIGHT()
```
Returns the maximum height across all of the animation's frames.
**Returns**: the largest height in pixels.
### GETMAXWIDTH
```
INTEGER GETMAXWIDTH()
```
Returns the maximum width across all of the animation's frames.
**Returns**: the largest width in pixels.
**Examples**
```
ANN_STATEK^GETMAXWIDTH();
```
### GETNAME
```
STRING GETNAME()
```
Returns the animation variable's name.
**Returns**: the variable's name.
### GETNOE
```
INTEGER GETNOE()
```
Returns the number of events in the animation (short for *Number Of Events*).
**Returns**: event count.
**Examples**
```
ANNLISCIESLOTY^GETNOE();
ANNBTN^GETNOE();
```
### GETNOF
```
INTEGER GETNOF()
```
Returns the total number of frames in the animation (short for *Number Of Frames*).
**Returns**: frame count.
### GETNOFINEVENT
```
INTEGER GETNOFINEVENT(INTEGER eventId)
INTEGER GETNOFINEVENT(STRING eventName)
```
Returns the number of frames in the given event. The event can be identified by its number (from `0`) or by its name (case-insensitive). For a non-existent event, `0` is returned.
**Parameters**
- `eventId` / `eventName` — event identifier.
**Returns**: frame count in the event.
**Examples**
```
ANNREX^GETNOFINEVENT(VARSTEMP0);
ANNUKLAD^GETNOFINEVENT(0);
ANNPLANNAK^GETNOFINEVENT("IDLE");
```
### GETPOSITIONX
```
INTEGER GETPOSITIONX([BOOL absolute])
```
Returns the X coordinate of the current frame's top-left corner on the canvas. The variant with a `BOOL` argument returns the absolute position, ignoring per-frame offsets defined in the animation file.
**Parameters**
- `absolute` — (optional) `TRUE` to skip per-frame offsets.
**Returns**: position X.
### GETPOSITIONY
```
INTEGER GETPOSITIONY([BOOL absolute])
```
Returns the Y coordinate of the current frame's top-left corner on the canvas. The variant with a `BOOL` argument returns the absolute position.
**Parameters**
- `absolute` — (optional) `TRUE` to skip per-frame offsets.
**Returns**: position Y.
### GETPRIORITY
```
INTEGER GETPRIORITY()
```
Returns the animation's rendering priority (`Z`).
**Returns**: the value of the [`PRIORITY`](#priority) field.
### GETWIDTH
```
INTEGER GETWIDTH()
```
Returns the width of the current animation frame.
**Returns**: width in pixels.
### HIDE
```
void HIDE()
```
Hides the animation visually without stopping its playback. Calling [`PLAY`](#play) automatically restores visibility.
### ISAT
```
BOOL ISAT(INTEGER posX, INTEGER posY)
```
Checks whether the point at the given coordinates lies inside the current frame's bounding box.
**Parameters**
- `posX` — point X coordinate.
- `posY` — point Y coordinate.
**Returns**: [`BOOL`](BOOL.md) — `TRUE` if the point is inside the bounding box.
### ISNEAR
```
BOOL ISNEAR(STRING animoName, INTEGER iouThresholdPercent)
```
Checks whether this animation is close to another animation. Internally, the Jaccard index (*Intersection over Union*, IoU) of the two animations' bounding boxes is computed; if the IoU exceeds the given threshold (in percent), `TRUE` is returned.
**Parameters**
- `animoName` — name of the other animation.
- `iouThresholdPercent` — IoU threshold in percent.
**Returns**: [`BOOL`](BOOL.md) — `TRUE` if the IoU exceeds the threshold.
**Examples**
```
ENEMY^ISNEAR("HERO", 1);
ANNORKA^ISNEAR("ANNLODKA", 12);
```
### ISPLAYING
```
BOOL ISPLAYING()
BOOL ISPLAYING(STRING eventName)
```
Checks whether the animation is currently playing. The no-argument variant returns whether any event is currently playing; with a name, the check is limited to that specific event.
**Parameters**
- `eventName` — (optional) name of the event to check.
**Returns**: [`BOOL`](BOOL.md) — `TRUE` if the animation (or the specific event) is playing.
**Examples**
```
ANNREX^ISPLAYING();
ANNREXGLOWA^ISPLAYING("SPI");
```
### ISVISIBLE
```
BOOL ISVISIBLE()
```
Checks whether the animation is visible ([`VISIBLE`](#visible) = `TRUE` and [`TOCANVAS`](#tocanvas) = `TRUE`).
**Returns**: [`BOOL`](BOOL.md) — `TRUE` if the animation is visible.
### LOAD
```
void LOAD(STRING path)
```
Loads an animation from an `.ANN` file, replacing the previous contents.
**Parameters**
- `path` — `.ANN` file path in the game's VFS.
**Examples**
```
ANNBKG^LOAD(SOBJECT|NAME);
ANNCHARACTER^LOAD("PIXEL.ANN");
ANNMINIMAPA^LOAD([""+ILEVEL+"_MINIMAPA.ANN"]);
```
### MONITORCOLLISION {#monitorcollision-1}
```
void MONITORCOLLISION()
```
Enables collision monitoring between this animation and other objects.
### MONITORCOLLISIONALPHA {#monitorcollisionalpha-1}
```
void MONITORCOLLISIONALPHA()
```
Enables alpha-channel awareness in collision detection.
### MOVE
```
void MOVE(INTEGER offsetX, INTEGER offsetY)
```
Moves the animation by the given offsets relative to its current position.
**Parameters**
- `offsetX` — X offset.
- `offsetY` — Y offset.
**Examples**
```
ANNELEMENT^MOVE(-200, 0);
ANNPLAYER^MOVE(VARDX, VARDY);
ANNITEMDRAGGING^MOVE([IMOUSEX-IMOUSELASTX], [IMOUSEY-IMOUSELASTY]);
```
### NEXTFRAME
```
void NEXTFRAME()
```
Advances the animation to the next frame of the current event.
### NPLAY
```
void NPLAY(INTEGER eventId)
```
Starts playing the event with the given index (counted from `0`).
**Parameters**
- `eventId` — event index.
**Examples**
```
ANNDARK0^NPLAY(VARITEMP2);
CZAS^NPLAY(0);
```
### PAUSE
```
void PAUSE()
```
Pauses the animation on the current frame.
### PLAY
```
void PLAY([STRING eventName])
```
Starts playing an event. The no-argument variant restarts the previously played event from the beginning.
**Parameters**
- `eventName` — (optional) name of the event to play (case-insensitive).
**Examples**
```
G_STLPAGE^PLAY("ELAPSE");
ANNREX^PLAY(VARITEMP0);
ANNKRET^PLAY(["IDLE_"+ANNKRET^GETEVENTNAME()]);
ANIMOREKSIO^PLAY($1);
```
### PREVFRAME
```
void PREVFRAME()
```
Moves the animation to the previous frame of the current event.
### REMOVEMONITORCOLLISION
```
void REMOVEMONITORCOLLISION()
```
Disables collision monitoring previously enabled by [`MONITORCOLLISION`](#monitorcollision-1).
### REMOVEMONITORCOLLISIONALPHA
```
void REMOVEMONITORCOLLISIONALPHA()
```
Disables alpha-channel awareness in collision detection, previously enabled by [`MONITORCOLLISIONALPHA`](#monitorcollisionalpha-1).
### RESUME
```
void RESUME()
```
Resumes playback paused with [`PAUSE`](#pause).
### SETANCHOR
```
void SETANCHOR(STRING anchor)
void SETANCHOR(INTEGER offsetX, INTEGER offsetY)
```
Sets the animation's anchor — the offset that is subtracted from coordinates passed to [`SETPOSITION`](#setposition).
The `STRING` variant accepts a named position derived from the bounding box: `CENTER`, `LEFTUPPER`, `RIGHTUPPER`, `LEFTLOWER`, `RIGHTLOWER`, `LEFT`, `RIGHT`, `TOP`, `BOTTOM`.
The two-`INTEGER` variant accepts the anchor coordinates directly.
**Parameters**
- `anchor` — bounding-box position name.
- `offsetX, offsetY` — anchor coordinates.
**Examples**
```
ANNSELECT^SETANCHOR("CENTER");
ANNREX^SETANCHOR("LEFTLOWER");
ANNREX^SETANCHOR(0, -100);
```
### SETASBUTTON
```
void SETASBUTTON(BOOL enabled, BOOL changeCursor)
```
Configures the animation as a clickable button. Regardless of the argument values, the call makes the animation visible.
**Parameters**
- `enabled` — `TRUE` to activate click handling.
- `changeCursor` — `TRUE` for the cursor to change on hover.
**Examples**
```
ANNEXIT^SETASBUTTON(TRUE, TRUE);
ANIMOPOWROT^SETASBUTTON(FALSE, FALSE);
```
### SETBACKWARD
```
void SETBACKWARD()
```
Sets the playback direction to backwards.
### SETFORWARD
```
void SETFORWARD()
```
Sets the playback direction to forward (the natural direction).
### SETFPS
```
void SETFPS(INTEGER fps)
```
Changes the animation's playback speed.
**Parameters**
- `fps` — frames per second.
**Examples**
```
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)
```
Sets the animation to a specific frame. The one-argument variant selects a frame by its global index. The two-argument variant selects an event and then a position in it (by frame number or frame name).
**Parameters**
- `eventName` — event name.
- `frameNumber` — frame index within an event (from `0`) or a global frame index.
- `frameName` — specific frame name within the event.
**Examples**
```
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)
```
Changes the name of a specific frame inside the given event.
**Parameters**
- `eventId` — event index (from `0`).
- `frameNumber` — frame index within the event (from `0`).
- `name` — the new frame name.
**Examples**
```
ANNKALAREPA^SETFRAMENAME(0, 0, "200");
ANNKALAREPA^SETFRAMENAME(1, 0, "300");
```
### SETOPACITY
```
void SETOPACITY(INTEGER opacity)
```
Sets the animation's opacity in the `0–255` scale (`0` — fully transparent, `255` — fully opaque).
**Parameters**
- `opacity` — alpha-channel value.
**Examples**
```
ANNPLAYER0^SETOPACITY(255);
ANNPLAYER^SETOPACITY(100);
```
### SETPOSITION
```
void SETPOSITION(INTEGER posX, INTEGER posY)
```
Sets the animation's absolute position. If an anchor has been set via [`SETANCHOR`](#setanchor), its coordinates are subtracted from the arguments.
**Parameters**
- `posX` — X coordinate.
- `posY` — Y coordinate.
**Examples**
```
ANNREX^SETPOSITION(400, 300);
ANNEXIT^SETPOSITION(-700, -450);
ANNBKG^SETPOSITION([VARIBKGOFFSETX-VARDTEMP0], [VARIBKGOFFSETY-VARDTEMP1]);
```
### SETPRIORITY
```
void SETPRIORITY(INTEGER priority)
```
Sets the rendering priority.
**Parameters**
- `priority` — the new value of the [`PRIORITY`](#priority) field.
**Examples**
```
ANNREX^SETPRIORITY(VARIPRIORITY);
ANNHEAD1^SETPRIORITY(15);
```
### SHOW
```
void SHOW()
```
Shows the animation (sets [`VISIBLE`](#visible) to `TRUE`).
### STOP
```
void STOP([BOOL emitSignal])
```
Stops the animation's playback.
**Parameters**
- `emitSignal` — (optional) if `FALSE`, the [`ONFINISHED`](#onfinished) signal is suppressed. By default, the signal is fired.
**Examples**
```
G_STLPAGE^STOP(FALSE);
ANNREX^STOP(FALSE);
ANNBLANK^STOP();
```
### TOP
```
void TOP([BOOL flag])
```
Modifies how the animation is rendered relative to the scene's top layer. The exact behaviour depends on the current scene composition.
**Parameters**
- `flag` — (optional) a flag changing the rendering mode.
**Examples**
```
ANNWAND0^TOP(FALSE);
ANNHEAD0^TOP(FALSE);
```
## Signals
### ONCLICK
Fired when the animation is clicked, provided it is configured as a button via [`SETASBUTTON`](#setasbutton).
### ONCOLLISION
Fired when a collision is detected.
### ONCOLLISIONFINISHED
Fired when an ongoing collision ends.
### ONDONE
Fired after all of the animation's events have finished.
### ONFINISHED
Fired when an event finishes playing. The signal is [parameterised](../engine/events.md#parameterised-signals) by the event name, so a handler can target a specific event:
```
ANIMATION:ONFINISHED^IDLE=BEHAFTERIDLE
```
### ONFIRSTFRAME
Fired when the event's first frame is displayed.
### ONFOCUSON
Fired when the cursor moves onto the animation, provided it is configured as a button.
### ONFOCUSOFF
Fired when the cursor moves off the animation, provided it is configured as a button.
### ONFRAMECHANGED
Fired when the animation's frame changes.
### ONINIT
Fired when the object is initialised.
### ONPAUSED
Fired when the animation is paused via [`PAUSE`](#pause).
### ONRELEASE
Fired when a mouse button is released over an animation configured as a button.
### ONRESUMED
Fired when the animation is resumed via [`RESUME`](#resume).
### ONSIGNAL
Fired when a signal arrives (see [Events and signals](../engine/events.md#onsignal)).
### ONSTARTED
Fired when an event starts playing. Note: this signal arrives after [`ONFRAMECHANGED`](#onframechanged) for the event's first frame.

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

@@ -0,0 +1,154 @@
# APPLICATION
The application object — the top of the script hierarchy. Declared in [`Application.def`](../engine/scripts.md#entry-point) as the first object; lists the episodes and points to the one to start with.
## Fields
### EPISODES
```
STRING EPISODES
```
The list of episode names ([`EPISODE`](EPISODE.md)) that make up the application, separated by commas. The analysed games typically contain a single entry.
### PATH
```
STRING PATH
```
Path relative to the `dane` directory where the application's files live. Used by the engine when locating the `.CNV` file bound to the application (see [Loading subsequent files](../engine/scripts.md#loading-subsequent-files)).
### STARTWITH
```
STRING STARTWITH
```
Name of the episode the engine will start the game with.
### Metadata
The following fields are stored in the script as metadata and do not directly affect engine behaviour:
- `AUTHOR` — file author.
- `BLOOMOO_VERSION` — BlooMoo engine version.
- `CREATIONTIME` — file creation date.
- `DESCRIPTION` — application description.
- `LASTMODIFYTIME` — file last-modification date.
- `VERSION` — application version.
## Methods
### EXIT
```
void EXIT()
```
Terminates the application.
**Examples**
```
GAME^EXIT();
```
### GETLANGUAGE
```
STRING GETLANGUAGE()
```
Returns the application's currently selected language. Defaults to `"POL"`.
**Returns**: the language code.
**Examples**
```
UFO^GETLANGUAGE();
```
### RUN
```
mixed RUN(STRING varName, STRING methodName, [mixed param1, ..., mixed paramN])
```
Invokes the method `methodName` on the variable `varName`, forwarding the remaining arguments. The return value is whatever the called method returns. This is the engine's dynamic-dispatch mechanism — both the target variable and the method can be selected at runtime.
**Parameters**
- `varName` — name of the target variable.
- `methodName` — name of the method to invoke.
- `param1, …, paramN` — (optional) arguments forwarded to the call.
**Returns**: the value returned by the invoked method.
**Examples**
```
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)
```
Calls the procedure `behaviourName`, but only when the currently active scene has the name `sceneName`. Otherwise the method has no effect. Useful for procedures that only make sense in a particular scene context.
**Parameters**
- `sceneName` — name of the scene in which the procedure must run.
- `behaviourName` — name of the procedure to call.
**Returns**: the value returned by the procedure, or `NULL` if the scene guard was not satisfied.
**Examples**
```
GAME^RUNENV(SCENENAME, "__HELPSTART__");
GAME^RUNENV(SCENENAME, "B_PAUSE_START");
GAME^RUNENV(SCENENAME, "__CUTINIT__");
```
### SETLANGUAGE
```
void SETLANGUAGE(STRING languageCode)
```
Sets the application's language code. The engine maps the passed Windows LCID code to an internal language identifier per the table below:
| LCID | Language | Internal ID | Subfolder |
|---|---|---|---|
| `0415` | Polish | `1` | `POL` |
| `0405` | Czech | `2` | `CZE` |
| `0402` | Bulgarian | `3` | `BUL` |
| `0418` | Romanian | `4` | `ROM` |
| `0419` | Russian | `5` | `RUS` |
| `040E` | Hungarian | `6` | `HUN` |
| `041B` | Slovak | `7` | `SLO` |
| `0422` | Ukrainian | `8` | `UKR` |
The selected identifier determines the localised-assets subfolder the engine consults when loading game files (see [Loading subsequent files](../engine/scripts.md#loading-subsequent-files)). Identifiers `9`, `10`, and `11` (set through paths other than `SETLANGUAGE`) all map to the `NIEM` subfolder — the German-language build. Any identifier outside the listed range yields an empty subfolder. Setting the language also re-initialises the keyboard layout.
**Parameters**
- `languageCode` — the LCID as a four-digit hexadecimal number.
**Examples**
```
UFO^SETLANGUAGE("0415");
UFO^SETLANGUAGE("040E");
UFO^SETLANGUAGE("0419");
```

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

@@ -0,0 +1,475 @@
# ARRAY
Zero-indexed array that stores values of any type. Full support for serialisation and arithmetic operations is provided for the four primitive types: [`INTEGER`](INTEGER.md), [`DOUBLE`](DOUBLE.md), [`STRING`](STRING.md), and [`BOOL`](BOOL.md). Mixed-type arrays are allowed, but some methods interpret elements in non-obvious ways (see the notes on [`FIND`](#find), [`CONTAINS`](#contains), and [`GETSUMVALUE`](#getsumvalue)).
## Fields
### TOINI
```
BOOL TOINI
```
Controls whether the array's contents are serialised to an INI file and restored on the next run.
## Methods
### ADD
```
void ADD(mixed value1, [mixed value2, ..., mixed valueN])
```
Appends the given values to the end of the array. The argument types do not have to match.
**Parameters**
- `value1, …, valueN` — values to append.
**Examples**
```
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)
```
Adds the argument to the element at position `index`. Internally, the element and the argument are converted to `DOUBLE`, summed, and stored as [`DOUBLE`](DOUBLE.md) — after this call the element at that position is always of type `DOUBLE`. Calling with `index` out of range leaves the array unchanged.
**Parameters**
- `index` — element position (`0`-based).
- `value` — value to add.
**Examples**
```
ARRIDLETIME^ADDAT(0, 1);
ARRENEMYY^ADDAT(VARITMPINDEX, VARITMP1);
ARRSPEED^ADDAT(0, 2.0);
```
### CHANGEAT
```
void CHANGEAT(INTEGER index, mixed value)
```
Replaces the element at position `index` with the given value. The type of the new element is preserved exactly as passed. Calling with `index` out of range leaves the array unchanged.
**Parameters**
- `index` — element position (`0`-based).
- `value` — the new value.
**Examples**
```
ARRIDLETIME^CHANGEAT(0, 0);
G_ARRREXSPELLS^CHANGEAT(VARIREPEATSPELL, 1);
ARRAYPLAYERSSTATE^CHANGEAT([VARCLONE-1], "NULL");
```
### CLAMPAT
```
void CLAMPAT(INTEGER index, mixed rangeMin, mixed rangeMax)
```
Clamps the value at position `index` to the inclusive range `[rangeMin, rangeMax]`. The element's type is preserved — `INTEGER` stays `INTEGER`, `DOUBLE` stays `DOUBLE`. For elements of any other type (and for `index` out of range) the call leaves the array unchanged.
**Parameters**
- `index` — element position (`0`-based).
- `rangeMin` — lower bound (inclusive).
- `rangeMax` — upper bound (inclusive).
**Examples**
```
ARRSPEED^CLAMPAT(VARPLAYER, 0.0, 100.0);
ARRSPEED^CLAMPAT(0, 0.0, 17.0);
```
### CONTAINS
```
BOOL CONTAINS(mixed needle)
```
Checks whether the array contains an element matching the given value. The comparison is done on the textual representation — `needle` is cast to [`STRING`](STRING.md) and compared with the `toDisplayString` result of each element. This differs from `FIND`, which compares values according to the [engine's typing rules](../engine/arithmetic.md#typing-rule).
**Parameters**
- `needle` — the value to search for.
**Returns**: [`BOOL`](BOOL.md) — `TRUE` if a matching element was found.
**Examples**
```
ART0^CONTAINS(ICIK);
ARRAYWARSZTATPRZEDMIOTY^CONTAINS(ARRAYTEMP^GET($1));
```
### COPYTO
```
void COPYTO(STRING arrayVarName)
```
Appends the contents of this array to the end of the array named in the argument. The target array must already exist and be of type `ARRAY`. The target array is **not** cleared before copying.
**Parameters**
- `arrayVarName` — the name of the destination array variable.
**Examples**
```
ARAG^COPYTO("ARTMP");
```
### FIND
```
INTEGER FIND(mixed needle)
```
Searches the array for the first element equal to the given value. The comparison follows the [engine's typing rules](../engine/arithmetic.md#typing-rule) — the type of the array element in each iteration determines what type `needle` is cast to. This yields counterintuitive results in mixed-type arrays: for example, searching for `240` in an array containing `TRUE` will return the index of `TRUE`, because `240` is cast to `BOOL` (a non-zero value, which becomes `TRUE`).
**Parameters**
- `needle` — the value to search for.
**Returns**: the index of the first matching element, or `-1` if no match was found.
**Examples**
```
G_ARRCUTSCENES^FIND(G_SCUTSCENE);
ARRSTARTNAME0^FIND("NULL");
ARRCLONES^FIND(-1);
```
### GET
```
mixed GET(INTEGER index)
```
Returns the element at position `index`. For `index` out of range, returns `NULL`.
**Parameters**
- `index` — element position (`0`-based).
**Returns**: the element's value or `NULL`.
**Examples**
```
ARRIDLETIME^GET(0);
ARRACTIVESPELLS^GET(_I_);
ARRAYPLAYERSSTATE^GET([VARCLONE-1]);
```
### GETSIZE
```
INTEGER GETSIZE()
```
Returns the number of elements in the array.
**Returns**: the array's size.
**Examples**
```
G_ARRSETTINGS^GETSIZE();
ARRENEMYROUTEX^GETSIZE();
```
### GETSUMVALUE
```
DOUBLE GETSUMVALUE()
```
Returns the sum of all element values. Each element is cast to `DOUBLE` per the [conversion rules](../engine/arithmetic.md#type-conversions); non-numeric elements can contribute unexpected values (`BOOL` → `1.0` or `0.0`, a non-numeric [`STRING`](STRING.md) → `0.0`).
**Returns**: the sum as a [`DOUBLE`](DOUBLE.md).
**Examples**
```
ARCONTAINER^GETSUMVALUE();
```
### INSERTAT
```
void INSERTAT(INTEGER index, mixed value)
```
Inserts the value at position `index`, shifting existing elements to the right. Valid values of `index` are in `[0, size]` — inserting at the array's size appends the element at the end. Calling outside this range leaves the array unchanged.
**Parameters**
- `index` — insertion position.
- `value` — the value to insert.
**Examples**
```
ARRTURNIEJ^INSERTAT(I3, I1);
ARRTURNIEJ^INSERTAT(4, I1);
```
### LOAD
```
void LOAD(STRING path)
```
Replaces the array's contents with data read from a binary `.ARR` file. The file is little-endian: a 4-byte element count, followed by, for each element, a 4-byte type tag (`1`=`INTEGER`, `2`=`STRING`, `3`=`BOOL`, `4`=`DOUBLE`) and the corresponding value representation.
**Parameters**
- `path` — the `.ARR` file path in the game's VFS.
**Examples**
```
G_ARRSETTINGS^LOAD("$COMMON\SETTINGS.ARR");
ARRPATH^LOAD(["MAPA"+ILEVEL+".ARR"]);
```
### LOADINI
```
void LOADINI()
```
Replaces the array's contents with data deserialised from the game's INI file under the key matching this variable's name. The INI format is a comma-separated list of values:
```
ARRAY_NAME=value1,value2,value3,...
```
Each element is interpreted in order as [`INTEGER`](INTEGER.md), [`DOUBLE`](DOUBLE.md), [`BOOL`](BOOL.md), or [`STRING`](STRING.md) — the first matching type is used.
**Examples**
```
ARRAYWARSZTATMENUPRZEDMIOTY^LOADINI();
```
### MODAT
```
void MODAT(INTEGER index, mixed divisor)
```
Stores the remainder of dividing the element at position `index` by the argument. Internally, the element and the argument are converted to `DOUBLE`, modulo is computed, and the result is stored as [`DOUBLE`](DOUBLE.md). Division by zero, or calling with `index` out of range, leaves the array unchanged.
**Parameters**
- `index` — element position.
- `divisor` — the divisor.
**Examples**
```
ARRANGLE^MODAT(VARPLAYER, 360);
```
### MULAT
```
void MULAT(INTEGER index, mixed multiplier)
```
Multiplies the element at position `index` by the argument. Internally, the element and the argument are converted to `DOUBLE`, multiplied, and the result is stored as [`DOUBLE`](DOUBLE.md). Calling with `index` out of range leaves the array unchanged.
**Parameters**
- `index` — element position.
- `multiplier` — the multiplier.
**Examples**
```
ARRDIRY^MULAT(VARPLAYER, -1.0);
ARRDIRX^MULAT(VARPLAYER, -1);
```
### REMOVEALL
```
void REMOVEALL()
```
Removes all elements from the array.
**Examples**
```
G_ARRSETTINGS^REMOVEALL();
ARRTEMP^REMOVEALL();
```
### REMOVEAT
```
void REMOVEAT(INTEGER index)
```
Removes the element at position `index`, shifting the remaining elements to the left. Calling with `index` out of range leaves the array unchanged.
**Parameters**
- `index` — position of the element to remove.
**Examples**
```
ARRTEMP^REMOVEAT(VARITEMP2);
ARRENEMYROUTEX^REMOVEAT(0);
```
### REVERSEFIND
```
INTEGER REVERSEFIND(mixed needle)
```
Works like [`FIND`](#find), but scans the array from the end. The same type-dependent comparison rules apply.
**Parameters**
- `needle` — the value to search for.
**Returns**: the index of the last matching element, or `-1` if no match was found.
**Examples**
```
ARRAYKURNIKFREESLOTS^REVERSEFIND(0);
```
### SAVE
```
void SAVE(STRING path)
```
Writes the array's contents to a binary `.ARR` file in the format described in [`LOAD`](#load).
**Parameters**
- `path` — the destination `.ARR` file path in the game's VFS.
**Examples**
```
G_ARRSETTINGS^SAVE("$COMMON\SETTINGS.ARR");
ARRPATH^SAVE(["MAPA"+ILEVEL+".ARR"]);
```
### SAVEINI
```
void SAVEINI()
```
Serialises the array's contents to the game's INI file under the key matching this variable's name, as a comma-separated list of values (the format described in [`LOADINI`](#loadini)).
**Examples**
```
ARRAYPLATFORMOWKAPRZEDMIOTY^SAVEINI();
```
### SUB
```
void SUB(mixed value)
```
Subtracts the argument from every element of the array. Each element is converted to `DOUBLE` before the subtraction; all elements after the call are of type `DOUBLE`.
**Parameters**
- `value` — the value to subtract.
**Examples**
```
ARRAYBKGA^SUB([0-VARINT2]);
```
### SUBAT
```
void SUBAT(INTEGER index, mixed value)
```
Subtracts the argument from the element at position `index`. Internally, the element and the argument are converted to `DOUBLE`, subtracted, and the result is stored as [`DOUBLE`](DOUBLE.md). Calling with `index` out of range leaves the array unchanged.
**Parameters**
- `index` — element position.
- `value` — the value to subtract.
**Examples**
```
ARRBUTTONPRESSED^SUBAT(IBUTTONNR, 1);
ARRSPEED^SUBAT(VARPLAYER, 0.15);
```
### SUM
```
void SUM(mixed value)
```
Adds the argument to every element of the array. Each element is converted to `DOUBLE` before the addition; all elements after the call are of type `DOUBLE`.
**Parameters**
- `value` — the value to add.
**Examples**
```
ARRCHICKENX^SUM(-60);
ARRCHICKENY^SUM(-110);
```
## Signals
### ONCHANGE
Fired after a modification has been made to the array.
### ONINIT
Fired when the variable is initialised.
### ONDONE
Fired when leaving the scene that owns the variable.
### ONSIGNAL
Fired when a signal arrives (sent via the `SEND` method — see [Events and signals](../engine/events.md#onsignal)).

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

@@ -0,0 +1,122 @@
# BEHAVIOUR
A procedure. Executes the code stored in the `CODE` field, optionally guarded by the condition named in the `CONDITION` field. Call-site arguments are available inside the code as `$1`, `$2`, …; see [Procedure arguments](../engine/scripts.md#procedure-arguments) for details.
## Fields
### CODE
```
STRING CODE
```
The body of the procedure — a code block in curly braces following the syntax described in [Scripts](../engine/scripts.md#code-blocks).
Example:
```
BEHGOTOTITLE:CODE={BEHSETSCENE^RUN();G_SARCADESCENE^SET("EGIPTLEJ");BEHCSSTART^RUN();}
```
### CONDITION
```
STRING CONDITION
```
The name of a [`CONDITION`](CONDITION.md) or [`COMPLEXCONDITION`](COMPLEXCONDITION.md) variable, used by [`RUNC`](#runc) as a gate and by [`RUNLOOPED`](#runlooped) as a per-iteration loop guard. If the field is not set, the methods run unconditionally.
## Methods
### RUN
```
mixed RUN([mixed param1, ..., mixed paramN])
```
Executes the procedure's code. The arguments are exposed inside the body as `$1`, `$2`, …. The return value is whatever [`@RETURN`](../engine/scripts.md#jump-operators) sets in the body, or `NULL` if `@RETURN` is not invoked.
**Parameters**
- `param1, …, paramN` — procedure arguments (optional, of any type).
**Returns**: the value returned by the procedure or `NULL`.
**Examples**
```
__LOAD_SETTINGS__^RUN();
BEHSELECTOBJ^RUN(VARITER);
BEHADDITEM^RUN(SOBJECT|SPARAM0, VARITER);
BEHENTERRABBIT^RUN("ANNHILL0", -1);
```
### RUNC
```
mixed RUNC([mixed param1, ..., mixed paramN])
```
Calls the procedure only when the condition named in `CONDITION` is satisfied. If `CONDITION` is not set, behaves like [`RUN`](#run). Arguments and return value are the same as in `RUN`.
**Parameters**
- `param1, …, paramN` — procedure arguments.
**Returns**: the value returned by the procedure, or `NULL` (including the case when the condition was not satisfied).
**Examples**
```
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])
```
Runs the procedure in a `for` loop with the counter passed as `$1`. Extra arguments (from the fourth argument onwards) are forwarded to the procedure as `$2`, `$3`, … . If the `CONDITION` field is set, its condition is checked before every iteration — when it is not satisfied, the loop ends.
The loop is equivalent to the following pseudocode:
```
for (int i = start; i < start + length; i += step) {
// call procedure with $1 = i, $2..$N = extraArgs
}
```
If `step` is omitted or passed as `0`, the value `1` is used. The [`@BREAK`](../engine/scripts.md#jump-operators) operator inside the procedure terminates the `RUNLOOPED` loop (but not the calling procedure).
**Parameters**
- `start` — initial counter value.
- `length` — number of iterations (`startVal < endVal` equals `startVal + length`).
- `step` — (optional) counter step. Defaults to `1`.
- `extraArg1, …, extraArgN` — (optional) extra arguments forwarded to the procedure.
**Examples**
```
BEHSHOWMENU^RUNLOOPED(0, ARRAYWARSZTATMENUPRZEDMIOTY^GETSIZE());
BEHSHOWPIONEK^RUNLOOPED(1, 9);
BEHINITZASLONAX^RUNLOOPED(0, 7, 1, "[80*$1]");
```
## Signals
### ONINIT
Fired when the procedure is initialised.
### ONDONE
Fired after a procedure invocation completes.
### ONSIGNAL
Fired when a signal arrives (see [Events and signals](../engine/events.md#onsignal)).

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

@@ -0,0 +1,92 @@
# BOOL
Boolean type. Stores one of two values: `TRUE` or `FALSE`.
## Fields
### TOINI
```
BOOL TOINI
```
Controls whether the field's value is persisted to an INI file and restored on the next run.
### VALUE
```
BOOL VALUE
```
The current value of the variable.
## Methods
### GET
```
BOOL GET()
```
Returns the current value of the variable.
**Returns**
- `BOOL` — the current value of the `VALUE` field.
### RESETINI
```
void RESETINI()
```
Resets the variable's value to the reset value defined in the object's script attributes. The engine looks up the value in the following order: `DEFAULT` → `INIT_VALUE` → `VALUE`; the first one found is used.
### SET
```
void SET(BOOL value)
```
Sets the variable's value.
**Parameters**
- `value` — the new `BOOL` value.
**Examples**
```
VARBLOCKSCENE^SET(FALSE);
__KEYB__^SET(KEYBOARD^ISENABLED());
VARBTEMP1^SET($2);
```
### SWITCH
```
void SWITCH(BOOL value1, BOOL value2)
```
Toggles the variable's value between the two values passed as arguments. The method accepts two parameters in order to keep its signature consistent with `SWITCH` on the [`INTEGER`](INTEGER.md) and [`DOUBLE`](DOUBLE.md) types, even though for `BOOL` the full information could be expressed with a single argument.
**Parameters**
- `value1` — the first value.
- `value2` — the second value.
**Examples**
```
B_0^SWITCH(TRUE, FALSE);
```
## Signals
### ONCHANGED
Fired when the variable's value is changed to one different from the previous one.
### ONBRUTALCHANGED
Fired on every call that sets the value, regardless of whether the new value differs from the previous one.

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

@@ -0,0 +1,70 @@
# CLASS
A class definition. The definition file has the `.class` extension and uses syntax similar to `.CNV` files. Instances (`INSTANCE`) are created from a class definition with [`NEW`](#new) and removed with [`DELETE`](#delete).
## Fields
### DEF
```
STRING DEF
```
Path to the class definition file. If the path does not start with `$`, it is prefixed with `$COMMON/classes/`.
### BASE
```
STRING BASE
```
The base class for inheritance. In the current emulator implementation the field is read but not used.
## Methods
### NEW
```
mixed NEW(STRING varName, [mixed param1, ..., mixed paramN])
```
Creates a new instance of the class with the name `varName`. The new variable is registered in the context where the class is declared (not in the caller's context) — the instance therefore survives scene changes when the class is declared at the application level.
After the instance is created, if the class definition file contains a procedure called `CONSTRUCTOR`, it is invoked with the arguments passed to `NEW` (with `varName` as `$1`).
**Parameters**
- `varName` — name of the new instance variable.
- `param1, …, paramN` — (optional) arguments forwarded to the `CONSTRUCTOR` procedure.
**Returns**: the value returned by `CONSTRUCTOR` or `NULL`.
**Examples**
```
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])
```
Deletes the instance named `varName`. If the class definition contains a procedure called `DESTRUCTOR`, it is invoked with the arguments passed to `DELETE` (with `varName` as `$1`) before the variable is removed from its context.
**Parameters**
- `varName` — name of the instance to delete.
- `param1, …, paramN` — (optional) arguments forwarded to the `DESTRUCTOR` procedure.
**Returns**: the value returned by `DESTRUCTOR` or `NULL`.
## Signals
### ONINIT
Fired when the class variable is initialised.

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

@@ -0,0 +1,104 @@
# COMPLEXCONDITION
An object that combines two conditions ([`CONDITION`](CONDITION.md) or nested `COMPLEXCONDITION`) with a logical `AND` or `OR` operator. Configured by three fields in the script and invoked similarly to a `CONDITION`.
## Fields
### CONDITION1
```
STRING CONDITION1
```
The name of the variable holding the left-hand sub-condition. The referenced variable should be of type [`CONDITION`](CONDITION.md) or `COMPLEXCONDITION` — in either case it is evaluated recursively.
### CONDITION2
```
STRING CONDITION2
```
The name of the variable holding the right-hand sub-condition; the rules are identical to those of `CONDITION1`.
### OPERATOR
```
STRING OPERATOR
```
The logical operator joining the two sub-conditions. Defaults to `AND`. Accepted values:
| Value | Meaning |
|---|---|
| `AND` | conjunction — the whole is true when both sub-conditions are true |
| `OR` | disjunction — the whole is true when at least one sub-condition is true |
## Methods
### BREAK
```
void BREAK([BOOL emitSignals])
```
Evaluates the compound condition. If the result is `TRUE`, aborts the entire current call tree (the same effect as [`@BREAK`](../engine/scripts.md#jump-operators)).
**Parameters**
- `emitSignals` — (optional) if `TRUE`, [`ONRUNTIMESUCCESS`](#onruntimesuccess)/[`ONRUNTIMEFAILED`](#onruntimefailed) signals are fired by both this object and each sub-condition. Defaults to `FALSE`.
**Examples**
```
COC_END^BREAK(TRUE);
CCONDISATPOS^BREAK(TRUE);
```
### CHECK
```
BOOL CHECK([BOOL emitSignals])
```
Evaluates the compound condition and returns the result.
**Parameters**
- `emitSignals` — (optional) same as for [`BREAK`](#break).
**Returns**: [`BOOL`](BOOL.md) — the combined result.
**Examples**
```
CCONDTESTEND^CHECK(TRUE);
```
### ONE_BREAK
```
void ONE_BREAK([BOOL emitSignals])
```
Evaluates the compound condition. If the result is `TRUE`, aborts only the current procedure (the same effect as [`@ONEBREAK`](../engine/scripts.md#jump-operators)).
**Parameters**
- `emitSignals` — (optional) same as for [`BREAK`](#break).
**Examples**
```
COC_END^ONE_BREAK(TRUE);
CCONDISATPOS^ONE_BREAK(TRUE);
```
## Signals
### ONRUNTIMESUCCESS
Fired when the compound condition evaluated to `TRUE` and `emitSignals` was `TRUE`.
### ONRUNTIMEFAILED
Fired when the compound condition evaluated to `FALSE` and `emitSignals` was `TRUE`.

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

@@ -0,0 +1,115 @@
# CONDITION
An object that describes a comparison of two operands. Configured by three fields in the script and invoked through [`CHECK`](#check) or one of the control-flow methods ([`BREAK`](#break), [`ONE_BREAK`](#one_break)).
## Fields
### OPERAND1
```
STRING OPERAND1
```
The left-hand operand of the comparison. The field holds the operand's textual form, which is parsed on every evaluation. Accepted forms:
- a quoted string literal (`"..."` or `'...'`),
- a boolean literal (`TRUE`, `FALSE`),
- a numeric literal (`5`, `-3.14`),
- a variable name (its value is fetched; for variables of type [`EXPRESSION`](index.md), `CONDITION`, or [`COMPLEXCONDITION`](COMPLEXCONDITION.md), the variable is recursively evaluated),
- a script fragment — text starting with `[`, `*`, or containing the `^` or `|` operators.
### OPERAND2
```
STRING OPERAND2
```
The right-hand operand of the comparison. The interpretation rules are identical to those of `OPERAND1`.
### OPERATOR
```
STRING OPERATOR
```
The comparison operator. Defaults to `EQUAL`. Accepted values:
| Value | Meaning |
|---|---|
| `EQUAL` | equal to |
| `NOTEQUAL` | not equal to |
| `LESS` | less than |
| `GREATER` | greater than |
| `LESSEQUAL` | less than or equal |
| `GREATEREQUAL` | greater than or equal |
## Methods
### BREAK
```
void BREAK([BOOL emitSignals])
```
Evaluates the condition. If the result is `TRUE`, aborts the entire current call tree (the same effect as [`@BREAK`](../engine/scripts.md#jump-operators)). If the result is `FALSE`, the method has no effect.
**Parameters**
- `emitSignals` — (optional) if `TRUE`, also fires [`ONRUNTIMESUCCESS`](#onruntimesuccess) or [`ONRUNTIMEFAILED`](#onruntimefailed) depending on the result. Defaults to `FALSE`.
**Examples**
```
COND1^BREAK(TRUE);
CONDKONTROLA^BREAK(TRUE);
```
### CHECK
```
BOOL CHECK([BOOL emitSignals])
```
Evaluates the condition and returns the comparison result.
**Parameters**
- `emitSignals` — (optional) if `TRUE`, also fires [`ONRUNTIMESUCCESS`](#onruntimesuccess) or [`ONRUNTIMEFAILED`](#onruntimefailed) depending on the result. Defaults to `FALSE`.
**Returns**: [`BOOL`](BOOL.md) — the comparison result.
**Examples**
```
CONPR1^CHECK(TRUE);
CONPR2^CHECK(TRUE);
```
### ONE_BREAK
```
void ONE_BREAK([BOOL emitSignals])
```
Evaluates the condition. If the result is `TRUE`, aborts only the current procedure (the same effect as [`@ONEBREAK`](../engine/scripts.md#jump-operators)). If the result is `FALSE`, the method has no effect.
**Parameters**
- `emitSignals` — (optional) same as for [`BREAK`](#break).
**Examples**
```
COND1^ONE_BREAK(TRUE);
CONDREMOVEMENUITEM^ONE_BREAK(TRUE);
```
## Signals
### ONRUNTIMESUCCESS
Fired when the condition evaluated to `TRUE` and `emitSignals` was `TRUE`.
### ONRUNTIMEFAILED
Fired when the condition evaluated to `FALSE` and `emitSignals` was `TRUE`.

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

@@ -0,0 +1,458 @@
# DOUBLE
Double-precision floating-point number.
## Fields
### TOINI
```
BOOL TOINI
```
Controls whether the field's value is persisted to an INI file and restored on the next run.
### VALUE
```
DOUBLE VALUE
```
The current value of the variable. Accepted notations include standard decimal (e.g. `1.234`) and scientific with the letter `e` or `d` (e.g. `1.23e4`, `1.23d4`).
## Methods
### ABS
```
DOUBLE ABS(DOUBLE value)
```
Stores the absolute value of the argument in the variable and returns it.
**Parameters**
- `value` — the number whose absolute value will be stored.
**Returns**: the new value of the variable.
**Examples**
```
VARDTMP2^ABS(VARDTMP2);
DKIERUNEKY^ABS(DKIERUNEKY);
```
### ADD
```
DOUBLE ADD(DOUBLE addend)
```
Adds the argument to the variable's current value, stores the result, and returns it.
**Parameters**
- `addend` — the value to add.
**Returns**: the new value of the variable.
**Examples**
```
VARDMENUOPACITY^ADD([42.5*VARIMENUVISIBLE]);
VARDTIME^ADD(1.0);
STREX|DPOSX^ADD(STREX|FORCEX);
```
### ARCTAN
```
DOUBLE ARCTAN(DOUBLE value)
```
Stores the arctangent of the argument, expressed in degrees, in the variable and returns it. The argument is treated as a number (a tangent value), not as an angle.
**Parameters**
- `value` — the number whose arctangent is computed.
**Returns**: the new value of the variable (in degrees).
**Examples**
```
VARDTMP1^ARCTAN(VARDTMP1);
```
### ARCTANEX
```
DOUBLE ARCTANEX(DOUBLE y, DOUBLE x)
```
Stores the value of `atan2(y, x)` expressed in degrees in the variable and returns it. This is the angle of the vector `(x, y)` measured from the positive `OX` axis.
**Parameters**
- `y` — the first vector component.
- `x` — the second vector component.
**Returns**: the new value of the variable (in degrees).
**Examples**
```
VARDTEMP1^ARCTANEX(VARIDIRY, VARIDIRX);
VARDTEMP2^ARCTANEX(VREFLECT^GET(1), VREFLECT^GET(0));
```
### CLAMP
```
DOUBLE CLAMP(DOUBLE rangeMin, DOUBLE rangeMax)
```
Clamps the variable's current value to the inclusive range `[rangeMin, rangeMax]`. Values outside the range are pinned to its bounds.
**Parameters**
- `rangeMin` — lower bound of the range (inclusive).
- `rangeMax` — upper bound of the range (inclusive).
**Returns**: the new value of the variable.
**Examples**
```
D3^CLAMP(0.5, 2.5);
VARDTMP1^CLAMP(-15.0, 15.0);
DKONSPEED^CLAMP(0.0, DKONSPEEDMAX);
```
### CLEAR
```
DOUBLE CLEAR()
```
Sets the variable's value to `0.0` and returns it.
**Returns**: `0.0`.
### COSINUS
```
DOUBLE COSINUS(DOUBLE angle)
```
Stores the cosine of the given angle in the variable and returns it. The angle is given in degrees.
**Parameters**
- `angle` — the angle in degrees.
**Returns**: the new value of the variable.
**Examples**
```
VARDTEMP0^COSINUS(VARDANGLE);
VARDTEMP1^COSINUS(ARRANGLE^GET(VARPLAYER));
```
### DEC
```
DOUBLE DEC()
```
Decrements the variable's value by `1.0`.
**Returns**: the new value of the variable.
### DIV
```
DOUBLE DIV(DOUBLE divisor)
```
Divides the variable's current value by the argument, stores the result, and returns it. Division by zero leaves the variable unchanged.
**Parameters**
- `divisor` — the divisor.
**Returns**: the new value of the variable (or the unchanged value if `divisor` was `0.0`).
**Examples**
```
VARDTEMP0^DIV(ARRSPEEDFACTOR^GET(0));
DKONSPEED^DIV(6.0);
VARDTMP2^DIV(15);
```
### GET
```
DOUBLE GET()
```
Returns the current value of the variable.
**Returns**: the current value of the `VALUE` field.
### INC
```
DOUBLE INC()
```
Increments the variable's value by `1.0`.
**Returns**: the new value of the variable.
### LENGTH
```
DOUBLE LENGTH(DOUBLE x, DOUBLE y)
```
Computes the length of the vector `(x, y)` as `sqrt(x² + y²)`, stores it, and returns it.
**Parameters**
- `x` — the first vector component.
- `y` — the second vector component.
**Returns**: the vector length.
**Examples**
```
VARDTEMP0^LENGTH(VARIDIRX, VARIDIRY);
```
### LOG
```
DOUBLE LOG(DOUBLE value)
```
Stores the natural logarithm of the argument in the variable and returns it.
**Parameters**
- `value` — the number whose logarithm is computed.
**Returns**: the new value of the variable.
### MAXA
```
DOUBLE MAXA(DOUBLE value1, [DOUBLE value2, ..., DOUBLE valueN])
```
Picks the maximum of the given arguments, stores it, and returns it. Requires at least one argument.
**Parameters**
- `value1, …, valueN` — the values to choose from.
**Returns**: the largest of the given values.
**Examples**
```
VARDPOWER^MAXA(0.0, VARDPOWER);
```
### MINA
```
DOUBLE MINA(DOUBLE value1, [DOUBLE value2, ..., DOUBLE valueN])
```
Picks the minimum of the given arguments, stores it, and returns it. Requires at least one argument.
**Parameters**
- `value1, …, valueN` — the values to choose from.
**Returns**: the smallest of the given values.
**Examples**
```
VARDPOWER^MINA(VARDPOWER, 9.0);
```
### MOD
```
DOUBLE MOD(DOUBLE divisor)
```
Computes the remainder of dividing the variable's current value by the argument, truncates the fractional part to an integer, stores it, and returns it. Division by zero leaves the variable unchanged.
**Parameters**
- `divisor` — the divisor.
**Returns**: the new value of the variable (or the unchanged value if `divisor` was `0.0`).
### MUL
```
DOUBLE MUL(DOUBLE multiplier)
```
Multiplies the variable's current value by the argument, stores the result, and returns it.
**Parameters**
- `multiplier` — the multiplier.
**Returns**: the new value of the variable.
**Examples**
```
STPLAYER|FORCEX^MUL(0.75);
VARCATFORCEX^MUL(1000000);
STREX|FORCEX^MUL(STREX|DEFIANCE);
```
### RESETINI
```
DOUBLE RESETINI()
```
Resets the variable's value to the reset value defined in the object's script attributes. The engine looks up the value in the following order: `DEFAULT` → `INIT_VALUE` → `VALUE`; the first one found is used. If none of them is set, the value is reset to `0.0`.
**Returns**: the new value of the variable.
### SET
```
DOUBLE SET(DOUBLE value)
```
Sets the variable's value.
**Parameters**
- `value` — the new value.
**Returns**: the new value of the variable.
**Examples**
```
VARDMAXVEL^SET(300.0);
VARDMAXVELKRET^SET([0.6*VARDMAXVEL]);
VARD_KRETSPEED^SET($1);
```
### SGN
```
INTEGER SGN()
```
Returns the sign of the variable's current value: `-1` for negative values, `1` for positive, `0` for zero. This method does not modify the variable, and is the only method on this type that returns an [`INTEGER`](INTEGER.md) rather than a `DOUBLE`.
**Returns**: the sign of the variable's value (`-1`, `0`, or `1`).
### SINUS
```
DOUBLE SINUS(DOUBLE angle)
```
Stores the sine of the given angle in the variable and returns it. The angle is given in degrees.
**Parameters**
- `angle` — the angle in degrees.
**Returns**: the new value of the variable.
**Examples**
```
VARDTEMP1^SINUS(VARDANGLE);
VARDTEMP2^SINUS(ARRANGLE^GET(VARPLAYER));
```
### SQRT
```
DOUBLE SQRT()
DOUBLE SQRT(DOUBLE value)
```
Stores the square root in the variable and returns it.
- Without an argument, the square root of the variable's current value is taken.
- With an argument, the square root of the argument is taken.
**Parameters**
- `value` — (optional) the number whose square root is computed.
**Returns**: the new value of the variable.
**Examples**
```
VARDODLEGLOSC^SQRT(VARDODLEGLOSC);
```
### SUB
```
DOUBLE SUB(DOUBLE subtrahend)
```
Subtracts the argument from the variable's current value, stores the result, and returns it.
**Parameters**
- `subtrahend` — the value to subtract.
**Returns**: the new value of the variable.
**Examples**
```
VARDANGLE^SUB(VARDTEMP2);
DKONSPEED^SUB([DKONACCELERATION*D3]);
```
### SWITCH
```
DOUBLE SWITCH(DOUBLE valueA, DOUBLE valueB)
```
If the variable's current value equals `valueA`, assigns `valueB` to it; otherwise assigns `valueA`. Useful for alternating between two values.
**Parameters**
- `valueA` — the first value.
- `valueB` — the second value.
**Returns**: the new value of the variable.
## Signals
### ONCHANGED
Fired when the variable's value is changed to one different from the previous one.
### ONBRUTALCHANGED
Fired on every call that sets the value, regardless of whether the new value differs from the previous one.

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

@@ -0,0 +1,102 @@
# EPISODE
A logical segment of the game — a container of scenes ([`SCENE`](SCENE.md)) inside an [`APPLICATION`](APPLICATION.md). In practice, AidemMedia games used a single episode for the whole game.
## Fields
### SCENES
```
STRING SCENES
```
The list of scene names that make up the episode, separated by commas.
### PATH
```
STRING PATH
```
Path relative to the `dane` directory containing the episode's files. Used by the engine when locating the scenes' `.CNV` files.
### STARTWITH
```
STRING STARTWITH
```
The name of the scene that starts the episode.
### Metadata
The following fields are stored as metadata and do not directly affect engine behaviour:
- `AUTHOR` — file author.
- `CREATIONTIME` — file creation date.
- `DESCRIPTION` — episode description.
- `LASTMODIFYTIME` — file last-modification date.
- `VERSION` — episode version.
## Methods
### BACK
```
void BACK()
```
Returns to the scene that was active immediately before the current one.
**Examples**
```
PRZYGODA^BACK();
```
### GETCURRENTSCENE
```
STRING GETCURRENTSCENE()
```
Returns the name of the currently active scene.
**Returns**: the scene name.
**Examples**
```
PRZYGODA^GETCURRENTSCENE();
```
### GETLATESTSCENE
```
STRING GETLATESTSCENE()
```
Returns the name of the scene that was active immediately before the current one — the scene that [`BACK`](#back) would return to.
**Returns**: the previous scene's name.
### GOTO
```
void GOTO(STRING sceneName)
```
Switches the game to the given scene.
**Parameters**
- `sceneName` — target scene name.
**Examples**
```
PRZYGODA^GOTO("CREDITS");
PRZYGODA^GOTO("MAGIC");
PRZYGODA^GOTO(G_SARCADEOBJECTS);
PRZYGODA^GOTO(UFO^RUN(["VARLEVEL"+VARNR], "GET"));
```

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

@@ -0,0 +1,25 @@
# FONT
A bitmap font definition. The object exposes no script-callable methods or signals — it is used by the [`TEXT`](TEXT.md) type as a source of character textures.
## Fields
### DEF
```
STRING DEF_<name>_<style>_<size>
```
A field that declares a `.FNT` font file. The field's name encodes the font variant's metadata: its name, style, and size.
Script syntax:
```
FONT:DEF_<name>_<style>_<size>=<file>.FNT
```
**Example**
```
FONT:DEF_ARIAL_STANDARD_14=ARIAL14.FNT
```

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

@@ -0,0 +1,409 @@
# IMAGE
A static image rendered on a scene. Supports positioning, opacity, clipping, runtime file loading, and collision monitoring against other objects.
## Fields
### FILENAME
```
STRING FILENAME
```
Name of the `.IMG` file with the image. Read at variable initialisation; can also be overwritten at runtime via [`LOAD`](#load).
### MONITORCOLLISION
```
BOOL MONITORCOLLISION
```
Whether the image participates in collision detection with other objects. Modified through [`MONITORCOLLISION`](#monitorcollision-1) and [`REMOVEMONITORCOLLISION`](#removemonitorcollision).
### MONITORCOLLISIONALPHA
```
BOOL MONITORCOLLISIONALPHA
```
Whether collision detection takes the image's alpha channel into account — collisions do not occur on fully transparent pixels.
### PRIORITY
```
INTEGER PRIORITY
```
Rendering priority (`Z`) relative to other scene objects.
### VISIBLE
```
BOOL VISIBLE
```
Image visibility. Modified through [`SHOW`](#show) and [`HIDE`](#hide).
## Methods
### GETALPHA
```
INTEGER GETALPHA(INTEGER posX, INTEGER posY)
```
Returns the alpha-channel value of the pixel at the given coordinates (in the `0–255` scale, where `255` is fully opaque).
**Parameters**
- `posX` — pixel X coordinate.
- `posY` — pixel Y coordinate.
**Returns**: the pixel's alpha value.
**Examples**
```
IMGLEVEL^GETALPHA(VARX, VARY);
IMGALPHA^GETALPHA(EXPMASKX, EXPMASKY);
```
### GETCENTERX
```
INTEGER GETCENTERX()
```
Returns the X coordinate of the centre of the image's bounding rectangle.
**Returns**: centre X.
### GETCENTERY
```
INTEGER GETCENTERY()
```
Returns the Y coordinate of the centre of the image's bounding rectangle.
**Returns**: centre Y.
### GETHEIGHT
```
INTEGER GETHEIGHT()
```
Returns the image's height in pixels.
**Returns**: image height.
**Examples**
```
IMGLINA^GETHEIGHT();
```
### GETPIXEL
```
INTEGER GETPIXEL(INTEGER posX, INTEGER posY)
```
Returns the pixel value at the given coordinates as an integer encoded per the image's colour depth: RGB565 for 16-bit images, RGB555 for 15-bit images.
**Parameters**
- `posX` — pixel X coordinate.
- `posY` — pixel Y coordinate.
**Returns**: the encoded pixel colour value.
**Examples**
```
IMGMASK^GETPIXEL(IKONNEWX, IKONNEWY);
```
### GETPOSITIONX
```
INTEGER GETPOSITIONX()
```
Returns the X coordinate of the image's top-left corner.
**Returns**: position X.
### GETPOSITIONY
```
INTEGER GETPOSITIONY()
```
Returns the Y coordinate of the image's top-left corner.
**Returns**: position Y.
### GETWIDTH
```
INTEGER GETWIDTH()
```
Returns the image's width in pixels.
**Returns**: image width.
**Examples**
```
IMGPASEK^GETWIDTH();
```
### HIDE
```
void HIDE()
```
Hides the image (sets [`VISIBLE`](#visible) to `FALSE`).
**Examples**
```
G_IMGPAGE^HIDE();
```
### INVALIDATE
```
void INVALIDATE()
```
Applies the pending opacity value previously set with [`SETOPACITY`](#setopacity). Without `INVALIDATE`, the opacity change does not become visible.
**Examples**
```
G_IMGPAGE^INVALIDATE();
```
### ISAT
```
BOOL ISAT(INTEGER posX, INTEGER posY)
```
Checks whether the point at the given coordinates lies inside the image's bounding rectangle.
**Parameters**
- `posX` — point X coordinate.
- `posY` — point Y coordinate.
**Returns**: [`BOOL`](BOOL.md) — `TRUE` if the point is inside the image's rectangle.
### LOAD
```
void LOAD(STRING path)
```
Loads an image from a file, replacing the previous contents. After loading, the image is automatically shown ([`VISIBLE`](#visible) is set to `TRUE`).
**Parameters**
- `path` — `.IMG` file path in the game's VFS.
**Examples**
```
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)
```
Binds an alpha mask sourced from another image to this image. The mask is positioned at `(posX, posY)` and modifies the resulting transparency of the current image in the overlapping area.
**Parameters**
- `posX` — mask X position.
- `posY` — mask Y position.
- `maskName` — name of the `IMAGE` variable whose alpha channel will be used as the mask.
**Examples**
```
IMGDARK^MERGEALPHA([ANNPLAYER0^GETCENTERX()-75], [ANNPLAYER0^GETCENTERY()-75], "IMGKOLKO");
IMG_WODA^MERGEALPHA(800, VARI_Y, "IMG_LIGHT");
```
### MONITORCOLLISION {#monitorcollision-1}
```
void MONITORCOLLISION()
```
Enables collision monitoring between this image and other objects. After the call, the [`MONITORCOLLISION`](#monitorcollision) field is `TRUE` and the image is registered with the collision-detection mechanism.
### MONITORCOLLISIONALPHA {#monitorcollisionalpha-1}
```
void MONITORCOLLISIONALPHA()
```
Enables alpha-channel awareness in collision detection. After the call, the [`MONITORCOLLISIONALPHA`](#monitorcollisionalpha) field is `TRUE`.
### MOVE
```
void MOVE(INTEGER offsetX, INTEGER offsetY)
```
Moves the image by the given offsets relative to its current position.
**Parameters**
- `offsetX` — X offset.
- `offsetY` — Y offset.
**Examples**
```
IMGBKGA^MOVE(0, 800);
IMGLINA^MOVE(0, IMOVDY);
IMRECT^MOVE(IGSX, 0);
```
### REMOVEMONITORCOLLISION
```
void REMOVEMONITORCOLLISION()
```
Disables collision monitoring previously enabled by [`MONITORCOLLISION`](#monitorcollision-1).
### REMOVEMONITORCOLLISIONALPHA
```
void REMOVEMONITORCOLLISIONALPHA()
```
Disables alpha-channel awareness in collision detection, previously enabled by [`MONITORCOLLISIONALPHA`](#monitorcollisionalpha-1).
### SETCLIPPING
```
void SETCLIPPING(INTEGER xLeft, INTEGER yBottom, INTEGER xRight, INTEGER yTop)
```
Restricts the image's drawing area to the rectangle defined by the given edges. Pixels outside the rectangle are not drawn.
**Parameters**
- `xLeft, yBottom, xRight, yTop` — coordinates of the clipping rectangle.
**Examples**
```
G_IMGPAGE^SETCLIPPING(0, 0, G_IPAGE, 600);
```
### SETOPACITY
```
void SETOPACITY(INTEGER opacity)
```
Sets the pending opacity value in the `0–255` scale (`0` — fully transparent, `255` — fully opaque). Out-of-range values are clamped. **The change does not become visible until [`INVALIDATE`](#invalidate) is called.**
**Parameters**
- `opacity` — alpha-channel value (`0–255`).
**Examples**
```
AIDEMMEDIA^SETOPACITY(VARNR);
IMGBRIDGE^SETOPACITY(200);
```
### SETPOSITION
```
void SETPOSITION(INTEGER posX, INTEGER posY)
```
Sets the absolute position of the image's top-left corner.
**Parameters**
- `posX` — X coordinate.
- `posY` — Y coordinate.
**Examples**
```
IMGENERGIA^SETPOSITION([795-VARENERGIA], 78);
IMGKOLKO^SETPOSITION(-500, -500);
IMGNAKLADKA^SETPOSITION(VARIPOSX, 0);
```
### SETPRIORITY
```
void SETPRIORITY(INTEGER priority)
```
Sets the image's rendering priority.
**Parameters**
- `priority` — the new value of the [`PRIORITY`](#priority) field.
**Examples**
```
G_IMGPAGE^SETPRIORITY(3000);
AIDEMMEDIA^SETPRIORITY(3);
```
### SHOW
```
void SHOW()
```
Shows the image (sets [`VISIBLE`](#visible) to `TRUE`).
**Examples**
```
G_IMGPAGE^SHOW();
REX^SHOW();
```
## Signals
### ONCLICK
Fired when the image is clicked.
### ONFOCUSON
Fired when the cursor moves onto the image.
### ONFOCUSOFF
Fired when the cursor moves off the image.
### ONINIT
Fired when the object is initialised.

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

@@ -0,0 +1,413 @@
# INTEGER
Signed integer number.
## Fields
### TOINI
```
BOOL TOINI
```
Controls whether the field's value is persisted to an INI file and restored on the next run.
### VALUE
```
INTEGER VALUE
```
The current value of the variable.
## Methods
### ABS
```
INTEGER ABS(INTEGER value)
```
Stores the absolute value of the argument in the variable and returns it.
**Parameters**
- `value` — the number whose absolute value will be stored.
**Returns**: the new value of the variable.
**Examples**
```
VARINT0^ABS(VARINT0);
I_7^ABS(ARRFLDCLONES^GET(I_FIELD_INDEX));
```
### ADD
```
INTEGER ADD(INTEGER addend)
```
Adds the argument to the variable's current value, stores the result, and returns it.
**Parameters**
- `addend` — the value to add.
**Returns**: the new value of the variable.
**Examples**
```
VARIRADIUS^ADD([VARIMENUVISIBLE*16]);
VARIKRETSTARTX^ADD(50);
VARITEMP0^ADD(VARIRADIUS);
```
### AND
```
INTEGER AND(INTEGER value)
```
Performs a bitwise AND between the variable's current value and the argument, stores the result, and returns it.
**Parameters**
- `value` — the value to combine with.
**Returns**: the new value of the variable.
**Examples**
```
VARITEMP2^AND(1);
VARITEMP1^AND(ARRMASK^GET(ARRENEMYMASK^GET(VARENEMY)));
```
### CLAMP
```
INTEGER CLAMP(INTEGER rangeMin, INTEGER rangeMax)
```
Clamps the variable's current value to the inclusive range `[rangeMin, rangeMax]`. Values outside the range are pinned to its bounds.
**Parameters**
- `rangeMin` — lower bound of the range (inclusive).
- `rangeMax` — upper bound of the range (inclusive).
**Returns**: the new value of the variable.
**Examples**
```
VARIMENUX^CLAMP(92, 708);
I1^CLAMP(0, IMIECZMAX);
IFRAMER^CLAMP(IFRAMECENTER, IFRAMEMAX);
```
### CLEAR
```
INTEGER CLEAR()
```
Sets the variable's value to `0` and returns it.
**Returns**: `0`.
### DEC
```
INTEGER DEC()
```
Decrements the variable's value by `1`.
**Returns**: the new value of the variable.
**Examples**
```
VARITIMETOEXIT^DEC();
VARIWAIT^DEC();
```
### DIV
```
INTEGER DIV(INTEGER divisor)
```
Divides the variable's current value (integer division) by the argument, stores the result, and returns it. Division by zero leaves the variable unchanged.
**Parameters**
- `divisor` — the divisor.
**Returns**: the new value of the variable (or the unchanged value if `divisor` was `0`).
**Examples**
```
VARITEMP0^DIV(2);
VARMOUSEDX^DIV(VARMOUSESPEED);
```
### GET
```
INTEGER GET()
```
Returns the current value of the variable.
**Returns**: the current value of the `VALUE` field.
### INC
```
INTEGER INC()
```
Increments the variable's value by `1`.
**Returns**: the new value of the variable.
**Examples**
```
VARINUMITEMS^INC();
VARITUTCOUNT^INC();
```
### LENGTH
```
INTEGER LENGTH(INTEGER x, INTEGER y)
```
Computes the Euclidean length of the vector `(x, y)` as `sqrt(x² + y²)`, truncates the result to an integer, stores it, and returns it.
**Parameters**
- `x` — the first vector component.
- `y` — the second vector component.
**Returns**: the vector length truncated to an integer.
**Examples**
```
VARI_TMP1^LENGTH([VARI_TMPX-VARI_CARX], [VARI_TMPY-VARI_CARY]);
I3^LENGTH(I3, 600);
```
### MOD
```
INTEGER MOD(INTEGER divisor)
```
Stores in the variable the remainder of dividing its current value by the argument. Division by zero leaves the variable unchanged.
**Parameters**
- `divisor` — the divisor.
**Returns**: the new value of the variable (or the unchanged value if `divisor` was `0`).
**Examples**
```
VARITEMP4^MOD(8);
IGC^MOD(ARLEVG^GETSIZE());
```
### MUL
```
INTEGER MUL(INTEGER multiplier)
```
Multiplies the variable's current value by the argument, stores the result, and returns it.
**Parameters**
- `multiplier` — the multiplier.
**Returns**: the new value of the variable.
**Examples**
```
VARITEMP0^MUL(34);
I1^MUL(IGRID);
```
### NOT
```
INTEGER NOT()
```
Performs a bitwise NOT (complement) on the variable's current value, stores the result, and returns it.
**Returns**: the new value of the variable.
### OR
```
INTEGER OR(INTEGER value)
```
Performs a bitwise OR between the variable's current value and the argument, stores the result, and returns it.
**Parameters**
- `value` — the value to combine with.
**Returns**: the new value of the variable.
### POWER
```
INTEGER POWER(INTEGER exponent)
```
Raises the variable's current value to the given power, rounds the result to an integer, stores it, and returns it.
**Parameters**
- `exponent` — the exponent.
**Returns**: the new value of the variable.
### RANDOM
```
INTEGER RANDOM(INTEGER bound)
INTEGER RANDOM(INTEGER min, INTEGER max)
```
Stores a pseudo-random number in the variable and returns it.
- The one-argument form returns a value from `[0, bound)`.
- The two-argument form returns a value from `[min, max]` (both ends inclusive).
**Parameters**
- `bound` — upper bound (exclusive).
- `min`, `max` — range bounds (inclusive).
**Returns**: the generated random value.
**Examples**
```
VARITEMP0^RANDOM(0, 100);
VARI_TMP3^RANDOM(VARI_TMP3);
```
### RESETINI
```
INTEGER RESETINI()
```
Resets the variable's value to the reset value defined in the object's script attributes. The engine looks up the value in the following order: `DEFAULT` → `INIT_VALUE` → `VALUE`; the first one found is used. If none of them is set, the value is reset to `0`.
**Returns**: the new value of the variable.
### SET
```
INTEGER SET(INTEGER value)
```
Sets the variable's value.
**Parameters**
- `value` — the new value.
**Returns**: the new value of the variable.
**Examples**
```
G_IPAGE^SET(800);
VARITEMP1^SET($2);
ITEMP^SET(STCBAZA|SRODEK);
```
### SUB
```
INTEGER SUB(INTEGER subtrahend)
```
Subtracts the argument from the variable's current value, stores the result, and returns it.
**Parameters**
- `subtrahend` — the value to subtract.
**Returns**: the new value of the variable.
**Examples**
```
G_IPAGE^SUB(100);
VARIPRIORITY^SUB(VARIBKGOFFSETY);
```
### SWITCH
```
INTEGER SWITCH(INTEGER valueA, INTEGER valueB)
```
If the variable's current value equals `valueA`, assigns `valueB` to it; otherwise assigns `valueA`. Useful for alternating between two values.
**Parameters**
- `valueA` — the first value.
- `valueB` — the second value.
**Returns**: the new value of the variable.
### XOR
```
INTEGER XOR(INTEGER value)
```
Performs a bitwise XOR between the variable's current value and the argument, stores the result, and returns it.
**Parameters**
- `value` — the value to combine with.
**Returns**: the new value of the variable.
## Signals
### ONCHANGED
Fired when the variable's value is changed to one different from the previous one.
### ONBRUTALCHANGED
Fired on every call that sets the value, regardless of whether the new value differs from the previous one.
### ONINIT
Fired when the variable is initialised.
### ONSIGNAL
Fired upon receiving a signal.

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

@@ -0,0 +1,137 @@
# KEYBOARD
The built-in object representing keyboard state. Available under the global name `KEYBOARD` from any context (see [Built-in objects](../engine/globals.md#built-in-objects)). Handles key-down and key-up events, including auto-repeat mode.
## Methods
### DISABLE
```
void DISABLE()
```
Disables keyboard event handling — key signals stop being fired.
**Examples**
```
KEYBOARD^DISABLE();
```
### ENABLE
```
void ENABLE()
```
Enables keyboard event handling.
**Examples**
```
KEYBOARD^ENABLE();
```
### GETLATESTKEY
```
STRING GETLATESTKEY()
```
Returns the name of the most recently pressed key.
**Returns**: the key name in the format accepted by [`ISKEYDOWN`](#iskeydown) (see [Supported keys](#supported-keys)).
**Examples**
```
KEYBOARD^GETLATESTKEY();
```
### ISENABLED
```
BOOL ISENABLED()
```
Checks whether keyboard handling is enabled.
**Returns**: [`BOOL`](BOOL.md) — `TRUE` if the keyboard is responding to events.
**Examples**
```
KEYBOARD^ISENABLED();
```
### ISKEYDOWN
```
BOOL ISKEYDOWN(STRING keyName)
```
Checks whether the given key is currently held down.
**Parameters**
- `keyName` — the key name (see [Supported keys](#supported-keys)).
**Returns**: [`BOOL`](BOOL.md) — `TRUE` if the key is held down. For an unknown key name, `FALSE` is returned.
**Examples**
```
KEYBOARD^ISKEYDOWN("UP");
KEYBOARD^ISKEYDOWN("LEFT");
KEYBOARD^ISKEYDOWN(ARRAYKEYBOARD^GET(0));
```
### SETAUTOREPEAT
```
void SETAUTOREPEAT(BOOL autorepeat)
```
Sets whether the [`ONKEYDOWN`](#onkeydown) signal is fired repeatedly as long as the key remains held down. Disabled by default.
**Parameters**
- `autorepeat` — `TRUE` to enable repeat firing.
**Examples**
```
KEYBOARD^SETAUTOREPEAT(FALSE);
```
## Signals
### ONKEYDOWN
Fired when a key is pressed. The signal is [parameterised](../engine/events.md#parameterised-signals) by the key name — separate handlers can be attached for each:
```
KEYBOARD:ONKEYDOWN^UP=BEHGOUP
KEYBOARD:ONKEYDOWN^DOWN=BEHGODOWN
```
When auto-repeat is enabled ([`SETAUTOREPEAT(TRUE)`](#setautorepeat)), the signal is fired on every frame in which the key remains held down.
### ONKEYUP
Fired when a key is released. The signal is parameterised by the key name, analogously to [`ONKEYDOWN`](#onkeydown).
### ONCHAR
Fired for every character produced by a keypress. The signal is parameterised by the key name.
## Supported keys
The engine's keyboard recognises the following key names:
- **Function keys**: `F1`, `F2`, `F3`, `F4`, `F5`, `F6`, `F7`, `F8`, `F9`, `F10`, `F11`, `F12`
- **Arrows**: `UP`, `DOWN`, `LEFT`, `RIGHT`
- **Modifiers**: `LSHIFT`, `RSHIFT`, `LCTRL`, `RCTRL`, `LALT`, `RALT`, `CAPSLOCK`
- **Special**: `ESC`, `ENTER`, `SPACE`, `TAB`, `INSERT`, `PGUP`, `PGDN`, `HOME`
- **Letters**: `Q`, `W`, `E`, `R`, `T`, `U`, `I`, `O`, `P`, `A`, `S`, `D`, `F`, `G`, `H`, `J`, `K`, `L`, `C`, `V`, `B`, `N`, `M`
- **Digits**: `0`, `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9`

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

@@ -0,0 +1,208 @@
# MOUSE
The built-in object representing mouse state. Available under the global name `MOUSE` from any context (see [Built-in objects](../engine/globals.md#built-in-objects)). Exposes the cursor position, button state, and reactive click, move, and double-click events.
## Fields
### RAW
```
BOOL RAW
```
Controls whether the object reads raw mouse data (bypassing system acceleration and calibration).
## Methods
### DISABLE
```
void DISABLE()
```
Disables mouse input — the cursor stops updating its position, and no signals are emitted.
**Examples**
```
MOUSE^DISABLE();
```
### DISABLESIGNAL
```
void DISABLESIGNAL()
```
Disables mouse signal emission. Unlike [`DISABLE`](#disable), the cursor's position is still tracked, but signal handlers ([`ONMOVE`](#onmove), [`ONCLICK`](#onclick), …) are not invoked.
**Examples**
```
MOUSE^DISABLESIGNAL();
```
### ENABLE
```
void ENABLE()
```
Enables mouse input.
**Examples**
```
MOUSE^ENABLE();
```
### ENABLESIGNAL
```
void ENABLESIGNAL()
```
Enables mouse signal emission.
**Examples**
```
MOUSE^ENABLESIGNAL();
```
### GETPOSX
```
INTEGER GETPOSX()
```
Returns the current X coordinate of the cursor.
**Returns**: the cursor's X coordinate.
**Examples**
```
MOUSE^GETPOSX();
```
### GETPOSY
```
INTEGER GETPOSY()
```
Returns the current Y coordinate of the cursor.
**Returns**: the cursor's Y coordinate.
**Examples**
```
MOUSE^GETPOSY();
```
### HIDE
```
void HIDE()
```
Hides the mouse cursor.
**Examples**
```
MOUSE^HIDE();
```
### ISLBUTTONDOWN
```
BOOL ISLBUTTONDOWN()
```
Checks whether the left mouse button is currently pressed.
**Returns**: [`BOOL`](BOOL.md) — `TRUE` if the button is held down.
**Examples**
```
MOUSE^ISLBUTTONDOWN();
```
### SET
```
void SET(STRING cursorStyle)
```
Sets the cursor's style.
**Parameters**
- `cursorStyle` — the name of the cursor style (e.g. `"ACTIVE"`, `"ARROW"`).
**Examples**
```
MOUSE^SET("ACTIVE");
MOUSE^SET("ARROW");
```
### SETPOSITION
```
void SETPOSITION(INTEGER posX, INTEGER posY)
```
Sets the cursor's position on the screen. If the position actually changes, the [`ONMOVE`](#onmove) signal is also fired.
**Parameters**
- `posX` — the new X coordinate of the cursor.
- `posY` — the new Y coordinate of the cursor.
**Examples**
```
MOUSE^SETPOSITION(400, 300);
MOUSE^SETPOSITION(MOUSE^GETPOSX(), VARINT0);
MOUSE^SETPOSITION(ANNMUCHA0^GETCENTERX(), ANNMUCHA0^GETCENTERY());
```
### SHOW
```
void SHOW()
```
Shows the mouse cursor.
## Signals
### ONCLICK
Fired when a mouse button is clicked. The signal is [parameterised](../engine/events.md#parameterised-signals) by the button name (`LEFT`, `RIGHT`), so separate handlers can be attached for each:
```
OBJECT_NAME:ONCLICK^LEFT=BEHLEFTCLICK
OBJECT_NAME:ONCLICK^RIGHT=BEHRIGHTCLICK
```
### ONDBLCLICK
Fired when a mouse button is double-clicked.
### ONINIT
Fired when the object is initialised.
### ONMOVE
Fired when the cursor's position changes.
### ONRELEASE
Fired when a mouse button is released.

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

@@ -0,0 +1,107 @@
# MULTIARRAY
A zero-indexed multi-dimensional array. Created by default as a two-dimensional `16 × 16` array; the number of dimensions can be changed in the script through the `DIMENSIONS` field. Each dimension grows automatically (doubling its size) whenever a write targets a position outside its current range.
## Fields
### DIMENSIONS
```
INTEGER DIMENSIONS
```
The number of dimensions of the array. The field is read during variable initialisation; the default is `2`. Each dimension starts with size `16`.
## Methods
### GET
```
mixed GET(INTEGER index1, [INTEGER index2, ..., INTEGER indexN])
```
Returns the value at the cell with the given coordinates. The number of arguments must equal the dimension count declared by `DIMENSIONS`. For a cell that has not been written, or with coordinates out of range, `NULL` is returned.
**Parameters**
- `index1, …, indexN` — cell coordinates (`0`-based), one per dimension.
**Returns**: the cell's value or `NULL`.
**Examples**
```
ARRMAPA^GET(IKRETMOVEONMAPAX, IKRETPOSMAPAY);
ARRMAPA^GET([IPLAYERPOSX-1], IPLAYERPOSY);
ARRMAPA^GET(_I_, I1);
```
### SET
```
void SET(INTEGER index1, [INTEGER index2, ..., INTEGER indexN], mixed value)
```
Stores a value at the cell with the given coordinates. The number of arguments must equal the dimension count + 1; the last argument is the value to store. If any coordinate exceeds the current size of its dimension, the array is grown automatically (the dimension's size is doubled until it covers the coordinate).
**Parameters**
- `index1, …, indexN` — cell coordinates.
- `value` — the value to store.
**Examples**
```
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)
```
Returns the size of the given dimension of the array.
**Parameters**
- `dimension` — dimension index (`0`-based).
**Returns**: the dimension's size, or `0` for an invalid index.
### LOAD
```
void LOAD(STRING path)
```
Replaces the array's contents with data read from a binary file. The format includes the array's dimensions and cell values.
**Parameters**
- `path` — file path in the game's VFS.
### SAVE
```
void SAVE(STRING path)
```
Writes the array's contents to a binary file.
**Parameters**
- `path` — destination file path in the game's VFS.
## Signals
### ONINIT
Fired when the variable is initialised; the `DIMENSIONS` field is read at this moment and the array's dimensions are allocated.
### ONSIGNAL
Fired when a signal arrives (see [Events and signals](../engine/events.md#onsignal)).

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

@@ -0,0 +1,52 @@
# RAND
The built-in pseudo-random number generator. Available under the global name `RAND` from any context, and also under the alias `RANDOM` (see [Built-in objects](../engine/globals.md#built-in-objects)).
## Methods
### GET
```
INTEGER GET(INTEGER range)
INTEGER GET(INTEGER offset, INTEGER range)
```
Returns a pseudo-random number.
- The one-argument form returns a value from `[0, range)`.
- The two-argument form returns a value from `[offset, offset + range)`.
If `range` is less than or equal to `0`, `offset` is returned (or `0` in the one-argument form).
**Parameters**
- `offset` — start of the range (inclusive), default `0`.
- `range` — size of the range (the upper bound is exclusive).
**Returns**: the generated random value.
**Examples**
```
RANDOM^GET(100);
RANDOM^GET(VARI_TMP3);
RANDOM^GET(0, 3);
```
### GETPLENTY
```
void GETPLENTY(STRING arrayName, INTEGER count, INTEGER offset, INTEGER range, BOOL onlyUnique)
```
Generates `count` pseudo-random integers from the range `[offset, offset + range)` and appends them to the array named `arrayName`. The array is not cleared before appending.
If `onlyUnique` is `TRUE`, every generated value must be different from the previously generated ones; if the requested number of unique values exceeds the range size (`count > range`), the method leaves the array unchanged. For `count` less than `1`, the method also has no effect.
**Parameters**
- `arrayName` — name of the target [`ARRAY`](ARRAY.md) variable.
- `count` — number of elements to generate.
- `offset` — start of the range (inclusive).
- `range` — size of the range (the upper bound is exclusive).
- `onlyUnique` — `TRUE` to enforce uniqueness among the generated values.

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

@@ -0,0 +1,282 @@
# SCENE
A single scene — one board, screen, or minigame. Belongs to an [`EPISODE`](EPISODE.md). Defines the background, music, and hotspot priority range, and exposes methods that control the scene's contents.
## Fields
### BACKGROUND
```
STRING BACKGROUND
```
Path to the `.IMG` file with the scene's background image.
### DLLS
```
STRING DLLS
```
List of DLL libraries attached to the scene (extensions of the BlooMoo library, e.g. `INERTIA`).
### MUSIC
```
STRING MUSIC
```
Path to the file holding the scene's background music.
### MUSICVOLUME
```
INTEGER MUSICVOLUME
```
The scene music's volume. A value of `1000` corresponds to 100%. Modified by [`SETMUSICVOLUME`](#setmusicvolume).
### MINHSPRIORITY
```
INTEGER MINHSPRIORITY
```
Minimum priority (`Z`) of the hotspots active in the scene. Modified by [`SETMINHSPRIORITY`](#setminhspriority).
### MAXHSPRIORITY
```
INTEGER MAXHSPRIORITY
```
Maximum priority (`Z`) of the hotspots active in the scene. Modified by [`SETMAXHSPRIORITY`](#setmaxhspriority).
### PATH
```
STRING PATH
```
Path relative to the `dane` directory containing the scene's files.
### Metadata
The following fields are stored as metadata and do not directly affect engine behaviour:
- `AUTHOR` — file author.
- `CREATIONTIME` — file creation date.
- `LASTMODIFYTIME` — file last-modification date.
- `VERSION` — scene version.
## Methods
### GETMAXHSPRIORITY
```
INTEGER GETMAXHSPRIORITY()
```
Returns the maximum priority of the scene's active hotspots.
**Returns**: the current value of the [`MAXHSPRIORITY`](#maxhspriority) field.
### GETMINHSPRIORITY
```
INTEGER GETMINHSPRIORITY()
```
Returns the minimum priority of the scene's active hotspots.
**Returns**: the current value of the [`MINHSPRIORITY`](#minhspriority) field.
### GETPLAYINGANIMO
```
void GETPLAYINGANIMO(STRING groupName)
```
Fills the [`GROUP`](index.md) variable named `groupName` with the names of every [`ANIMO`](index.md) currently playing in the scene. Existing contents of the group are overwritten.
**Parameters**
- `groupName` — name of the `GROUP` variable to populate.
### PAUSE
```
void PAUSE()
```
Pauses the scene's music and every playing [`ANIMO`](index.md).
**Examples**
```
BARANDALF^PAUSE();
```
### REMOVECLONES
```
void REMOVECLONES(STRING varName, INTEGER firstId, INTEGER lastId)
```
Removes clones of the variable `varName` with numbers in the range `[firstId, lastId]`. A value of `-1` in `lastId` means "up to the last clone". Clones are named according to the pattern `varName_N`, with `N` starting at `1`.
**Parameters**
- `varName` — base name of the cloned variable.
- `firstId` — number of the first clone to remove (minimum `1`).
- `lastId` — number of the last clone to remove, or `-1` for all clones to the end.
**Examples**
```
ARCADE^REMOVECLONES(VARSCURRENTITEMOBJECT, -1, -1);
CUTSCENKI^REMOVECLONES(SANN, -1, -1);
```
### RESUME
```
void RESUME()
```
Resumes the scene's music (with the volume from the [`MUSICVOLUME`](#musicvolume) field) and every paused [`ANIMO`](index.md).
**Examples**
```
BARANDALF^RESUME();
```
### RESUMEONLY
```
void RESUMEONLY(STRING groupName)
```
Resumes only those paused animations whose names appear in the [`GROUP`](index.md) variable `groupName`.
**Parameters**
- `groupName` — name of the `GROUP` variable holding the animations to resume.
### RUN
```
mixed RUN(STRING varName, STRING methodName, [mixed param1, ..., mixed paramN])
```
Dynamically invokes the method `methodName` on the variable `varName`. Behaves the same as [`APPLICATION.RUN`](APPLICATION.md#run); the scene-level variant exists for scripts that hold a reference to the scene rather than the application.
**Parameters**
- `varName` — name of the target variable.
- `methodName` — name of the method to invoke.
- `param1, …, paramN` — (optional) arguments.
**Returns**: the value returned by the invoked method.
**Examples**
```
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)
```
Invokes the procedure `behaviourName` for each clone of the variable `varName` in the range `[firstId, lastId]`. A value of `-1` in `lastId` means "up to the last clone". The procedure receives the clone's name as its first argument (`$1`).
**Parameters**
- `varName` — base name of the cloned variable.
- `firstId` — number of the first clone (minimum `1`).
- `lastId` — number of the last clone, or `-1`.
- `behaviourName` — name of the procedure to invoke.
**Examples**
```
S16_SPACEINVADERS^RUNCLONES("ANIMOUFO", -1, -1, "BEHINITUFO");
S71_DROGA^RUNCLONES("ANNKURA", -1, -1, "BEHINITCLONES");
```
### SETMAXHSPRIORITY
```
void SETMAXHSPRIORITY(INTEGER maxHSPriority)
```
Sets the maximum priority of the scene's active hotspots.
**Parameters**
- `maxHSPriority` — the new maximum priority.
### SETMINHSPRIORITY
```
void SETMINHSPRIORITY(INTEGER minHSPriority)
```
Sets the minimum priority of the scene's active hotspots.
**Parameters**
- `minHSPriority` — the new minimum priority.
**Examples**
```
MENUGLOWNE^SETMINHSPRIORITY(999);
MENUGLOWNE^SETMINHSPRIORITY(0);
```
### SETMUSICVOLUME
```
void SETMUSICVOLUME(INTEGER volume)
```
Sets the scene music's volume. A value of `1000` corresponds to 100%. The change is applied immediately if the music is currently playing.
**Parameters**
- `volume` — the new volume.
**Examples**
```
ARCADE^SETMUSICVOLUME(G_ARRSETTINGS^GET(1));
INTRO_2^SETMUSICVOLUME(500);
DIALOGS^SETMUSICVOLUME([0.8*G_ARRSETTINGS^GET(1)]);
```
### STARTMUSIC
```
void STARTMUSIC(STRING filename)
```
Stores the path of the music file in the [`MUSIC`](#music) field; the engine plays it as the scene's background music.
**Parameters**
- `filename` — path to the music file.
**Examples**
```
ARCADE^STARTMUSIC(VARSMUSIC);
MAGIC^STARTMUSIC("POJEDYNEK.WAV");
DIALOGS^STARTMUSIC("GABINETY.WAV");
```

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

@@ -0,0 +1,208 @@
# SEQUENCE
An animation sequence. The `.SEQ` file contains **sequence events** — descriptions of [`ANIMO`](ANIMO.md) animation runs played in sync with accompanying [`SOUND`](SOUND.md) effects. Sequences let you treat picture and audio as a single, script-controlled unit.
## Fields
### FILENAME
```
STRING FILENAME
```
Path to the `.SEQ` file holding the sequence definition.
## Methods
### GETEVENTNAME
```
STRING GETEVENTNAME()
```
Returns the name of the sequence event currently being played.
**Returns**: event name.
**Examples**
```
SEQSFX^GETEVENTNAME();
```
### GETPLAYING
```
STRING GETPLAYING()
```
Returns the name of the [`ANIMO`](ANIMO.md) variable being played as part of the currently active event. If no event is active, an empty string is returned.
**Returns**: the animation name or `""`.
### HIDE
```
void HIDE()
```
Hides every animation belonging to the sequence.
**Examples**
```
SEQJEAN^HIDE();
SEQKRET^HIDE();
```
### ISPLAYING
```
BOOL ISPLAYING()
```
Checks whether the sequence is currently playing.
**Returns**: [`BOOL`](BOOL.md) — `TRUE` if the sequence is in playback.
**Examples**
```
SEQBLANK^ISPLAYING();
SEQMANDOLINA^ISPLAYING();
```
### PAUSE
```
void PAUSE()
```
Pauses the sequence's playback.
**Examples**
```
SEQCS^PAUSE();
```
### PLAY
```
void PLAY(STRING eventName)
```
Starts playing the sequence event with the given name. On start, the [`ONSTARTED`](#onstarted) signal is fired with the event name as its argument.
**Parameters**
- `eventName` — name of the event from the `.SEQ` file.
**Examples**
```
GADAJA2^PLAY("KOGF2");
SEQNARRATOR^PLAY(VARSTRING0);
SEQLAB^PLAY(["PLAYER"+VARINT0]);
SEQREKSIO^PLAY($1);
```
### RESUME
```
void RESUME()
```
Resumes a sequence paused with [`PAUSE`](#pause).
**Examples**
```
SEQCS^RESUME();
```
### SETFREQ
```
void SETFREQ(INTEGER sampleRate)
```
Sets the sample rate used by the sound attached to the currently active sequence event. Equivalent to calling [`SETFREQ`](SOUND.md#setfreq) on the [`SOUND`](SOUND.md) object of that event.
**Parameters**
- `sampleRate` — the target sample rate in Hz.
### SETPAN
```
void SETPAN(INTEGER pan)
```
Sets the stereo panning (left/right balance) of the active event's sound. A value of `400` corresponds to a centred mix, `0` to fully left, and `800` to fully right.
**Parameters**
- `pan` — panning value in the `0–800` range.
### SETVOLUME
```
void SETVOLUME(INTEGER volume)
```
Sets the active event sound's volume. A value of `1600` corresponds to maximum volume; `0` mutes the sound.
**Parameters**
- `volume` — volume value in the `0–1600` range.
### SHOW
```
void SHOW()
```
Shows every animation belonging to the sequence.
### STOP
```
void STOP([BOOL emitSignal])
```
Stops the sequence's playback.
**Parameters**
- `emitSignal` — (optional) if `FALSE`, the [`ONFINISHED`](#onfinished) signal is suppressed. By default, the signal is fired.
**Examples**
```
SEQBLANK^STOP(FALSE);
SEQMENU^STOP(TRUE);
SEQZMIANAWAGIREX^STOP();
```
## Signals
### ONINIT
Fired when the object is initialised.
### ONSTARTED
Fired when a sequence event starts playing. The argument (`$1`) is the name of the started event.
### ONFINISHED
Fired when a sequence event finishes (naturally or via a [`STOP`](#stop) call that does not suppress the signal). The argument (`$1`) is the name of the finished event. The signal is [parameterised](../engine/events.md#parameterised-signals) by that name, so a handler can target a specific event:
```
SEQUENCE:ONFINISHED^IDLE=BEHAFTERIDLE
```
### ONSIGNAL
Fired when a signal arrives (see [Events and signals](../engine/events.md#onsignal)).

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

@@ -0,0 +1,150 @@
# SOUND
A short sound effect loaded from a `.WAV` file. Supports playback control and sample-rate change, which can be used to dynamically alter the pitch and speed of the played sound.
## Fields
### FILENAME
```
STRING FILENAME
```
Name of the `.WAV` file with the sound. If the path does not start with `$`, the engine prepends `$WAVS\`. The field is read at variable initialisation; it can also be changed at runtime via [`LOAD`](#load).
### PRELOAD
```
BOOL PRELOAD
```
Whether the sound data is loaded eagerly at initialisation or lazily before the first playback.
## Methods
### ISPLAYING
```
BOOL ISPLAYING()
```
Checks whether the sound is currently being played.
**Returns**: [`BOOL`](BOOL.md) — `TRUE` if the sound is playing.
**Examples**
```
SNDATGOAL^ISPLAYING();
SNDREX0^ISPLAYING();
```
### LOAD
```
void LOAD(STRING path)
```
Loads a sound file into the variable, replacing any previously loaded sound. Any ongoing playback is stopped. If the path does not start with `$`, the prefix `$WAVS\` is added.
**Parameters**
- `path` — path to the `.WAV` file in the game's VFS.
**Examples**
```
SNDATGOAL^LOAD(VARSTEMP0);
SNDWAV^LOAD("$WAVS\NAR_I000.WAV");
SNDANSWER^LOAD(ARRSEQ^GET(0));
```
### PAUSE
```
void PAUSE()
```
Pauses the sound's playback.
**Examples**
```
SND_SHIP_GAZ2^PAUSE();
```
### PLAY
```
void PLAY()
```
Starts playing the sound. The [`ONSTARTED`](#onstarted) signal is fired on start, and [`ONFINISHED`](#onfinished) on completion. If the sound is already playing, it is stopped and restarted from the beginning.
**Examples**
```
SNDTAKE^PLAY();
SNDATGOAL^PLAY();
```
### RESUME
```
void RESUME()
```
Resumes playback paused earlier with [`PAUSE`](#pause).
**Examples**
```
SND_SHIP_GAZ2^RESUME();
```
### SETFREQ
```
void SETFREQ(INTEGER sampleRate)
```
Sets the current playback sample rate (in hertz). A value different from the source file's sample rate scales the playback pitch and speed proportionally to the ratio of the two. The engine assumes a default source sample rate of `22050` Hz.
**Parameters**
- `sampleRate` — the target sample rate in Hz.
**Examples**
```
SNDENGINE0^SETFREQ(10025);
```
### STOP
```
void STOP([BOOL emitSignal])
```
Stops the sound's playback.
**Parameters**
- `emitSignal` — (optional) if `FALSE`, the [`ONFINISHED`](#onfinished) signal is suppressed. By default, the signal is fired.
**Examples**
```
SNDATGOAL^STOP(FALSE);
SNDIDLEREX^STOP();
```
## Signals
### ONSTARTED
Fired when playback starts via [`PLAY`](#play).
### ONFINISHED
Fired when playback finishes (naturally or through a [`STOP`](#stop) call that does not suppress the signal).

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

@@ -0,0 +1,297 @@
# STRING
Character string.
## Fields
### TOINI
```
BOOL TOINI
```
Controls whether the field's value is persisted to an INI file and restored on the next run.
### VALUE
```
STRING VALUE
```
The current value of the variable.
## Methods
### ADD
```
STRING ADD(STRING text)
```
Appends the argument to the variable's current value (string concatenation), stores the result, and returns it.
**Parameters**
- `text` — the text to append.
**Returns**: the new value of the variable.
**Examples**
```
G_SLASTOBJECTS^ADD(VARSTEMP0);
VARSMUSIC^ADD(".WAV");
S_0^ADD($1);
```
### CHANGEAT
```
STRING CHANGEAT(INTEGER index, STRING replacement)
```
Replaces the single character at position `index` with the `replacement` string. If `replacement` is not exactly one character long, the resulting string length changes accordingly. Calling with an `index` outside the string's range leaves the variable unchanged.
**Parameters**
- `index` — position of the character to replace (`0`-based).
- `replacement` — the string to insert in place of the character.
**Returns**: the new value of the variable (or the unchanged value if `index` was out of range).
**Examples**
```
*VARARRAYNAME^CHANGEAT([VARCLONE-1], "NULL");
*VARENEMYSTATE^CHANGEAT([VARINT1-1], VARSTRING1);
```
### COPYFILE
```
BOOL COPYFILE(STRING source, STRING destination)
```
Copies a file inside the game's virtual file system (VFS) from `source` to `destination`. The method does not use the receiver variable's value — only the arguments matter.
**Parameters**
- `source` — path of the source file in the VFS.
- `destination` — path of the destination file in the VFS.
**Returns**: [`BOOL`](BOOL.md) — `TRUE` if the copy succeeded; `FALSE` otherwise (e.g. the source file does not exist or an I/O error occurred).
**Examples**
```
VARSTEMP0^COPYFILE("$COMMON\ITEMS_DEF.DTA", "$COMMON\ITEMS0.DTA");
S1^COPYFILE(S1, S2);
```
### CUT
```
STRING CUT(INTEGER index, INTEGER length)
```
Replaces the variable's value with a substring of the current value, starting at position `index` and of `length` characters. If the requested length exceeds the available characters, the substring stops at the end of the string. If `index` is out of range, the variable becomes an empty string.
**Parameters**
- `index` — starting position of the substring (`0`-based).
- `length` — length of the substring.
**Returns**: the new value of the variable.
**Examples**
```
VARSTRING0^CUT(0, VARSTRING0^FIND("_"));
```
### FIND
```
INTEGER FIND(STRING needle)
INTEGER FIND(STRING needle, INTEGER offset)
```
Searches the variable's current value for the first occurrence of the given string. This method does not modify the variable.
**Parameters**
- `needle` — the string to search for.
- `offset` — (optional) position from which the search starts. Defaults to `0`.
**Returns**: the position of the first occurrence (`0`-based), or `-1` if the string was not found.
**Examples**
```
VARSTEMP0^FIND("IDLE");
SWYRAZ^FIND(S1);
```
### GET
```
STRING GET()
STRING GET(INTEGER index)
STRING GET(INTEGER index, INTEGER length)
```
Returns a fragment of the variable's current value. This method does not modify the variable.
- Without arguments, returns the full value of the `VALUE` field.
- With arguments, returns a substring starting at `index` and of `length` characters (default `1`).
If `index` is out of range, an empty string is returned. If the requested length exceeds the available characters, the substring stops at the end of the string.
**Parameters**
- `index` — starting position of the substring (`0`-based).
- `length` — (optional) length of the substring. Defaults to `1`.
**Returns**: the extracted substring (or the full value in the no-argument form).
**Examples**
```
VARSTEMP3^GET(7);
VARENEMYNAME^GET(0, VARENEMYNAME^FIND("_"));
SOBJNAME^GET(0, 1);
```
### LENGTH
```
INTEGER LENGTH()
```
Returns the length of the variable's current value. This method does not modify the variable.
**Returns**: [`INTEGER`](INTEGER.md) — the number of characters in the string.
**Examples**
```
VARSTEMP0^LENGTH();
```
### LOWER
```
STRING LOWER()
```
Converts all letters in the variable's current value to lowercase.
**Returns**: the new value of the variable.
### REPLACEAT
```
STRING REPLACEAT(INTEGER index, INTEGER length, STRING replacement)
```
Replaces a fragment of the current string of `length` characters, starting at position `index`, with the `replacement` string. If the requested length exceeds the available characters, the rest of the string is replaced. Calling with an `index` outside the string's range leaves the variable unchanged.
**Parameters**
- `index` — starting position of the replaced fragment (`0`-based).
- `length` — length of the replaced fragment.
- `replacement` — the string that will replace the fragment.
**Returns**: the new value of the variable (or the unchanged value if `index` was out of range).
**Examples**
```
S3^REPLACEAT(0, 1, S1);
VARSTMP2^REPLACEAT(8, 2, ["00"+VARIKRAINANO]);
```
### RESETINI
```
STRING RESETINI()
```
Resets the variable's value to the reset value defined in the object's script attributes. The engine looks up the value in the following order: `DEFAULT` → `INIT_VALUE` → `VALUE`; the first one found is used. If none of them is set, the value is reset to an empty string.
**Returns**: the new value of the variable.
### SET
```
STRING SET(STRING value)
```
Sets the variable's value.
**Parameters**
- `value` — the new value.
**Returns**: the new value of the variable.
**Examples**
```
SCENENAME^SET(PRZYGODA^GETCURRENTSCENE());
VARSTEMP0^SET(["BEHCLICK_"+SOBJECT|IDNAME]);
VARSTEMP0^SET($1);
```
### SUB
```
STRING SUB(INTEGER index, INTEGER length)
```
Removes from the variable's current value a fragment of `length` characters, starting at position `index`. The remaining parts (before and after the removed fragment) are concatenated. Calling with an `index` outside the string's range leaves the variable unchanged.
**Parameters**
- `index` — starting position of the removed fragment (`0`-based).
- `length` — length of the removed fragment.
**Returns**: the new value of the variable (or the unchanged value if `index` was out of range).
**Examples**
```
VARSTEMP0^SUB(0, 5);
VARSTEMP0^SUB(VARITEMP0, [VARSTEMP0^LENGTH()-VARITEMP0]);
```
### UPPER
```
STRING UPPER()
```
Converts all letters in the variable's current value to uppercase.
**Returns**: the new value of the variable.
**Examples**
```
SDIALOGWAVENAME^UPPER();
SDIALOGPERSON^UPPER();
```
## Signals
### ONCHANGED
Fired when the variable's value is changed to one different from the previous one.
### ONBRUTALCHANGED
Fired on every call that sets the value, regardless of whether the new value differs from the previous one.
### ONINIT
Fired when the variable is initialised.

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

@@ -0,0 +1,35 @@
# SYSTEM
The built-in object exposing operating-system information. Available under the global name `SYSTEM` from any context (see [Built-in objects](../engine/globals.md#built-in-objects)).
## Methods
### GETDATE
```
INTEGER GETDATE()
```
Returns the current date encoded as an integer in the format `(year-2000)*10000 + month*100 + day`. For example, `26 March 2026` becomes `260326`.
**Returns**: the encoded date.
### GETMHZ
```
INTEGER GETMHZ()
```
Returns the processor's clock frequency in megahertz.
**Returns**: the CPU frequency in MHz.
### GETSYSTEMTIME
```
INTEGER GETSYSTEMTIME()
```
Returns the operating system's uptime in milliseconds.
**Returns**: the uptime in milliseconds.

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

@@ -0,0 +1,138 @@
# TEXT
A text element rendered on screen. Uses a font ([`FONT`](FONT.md)) referenced through the [`FONT`](#font) field; content, position, and alignment are configured by the remaining fields.
## Fields
### FONT
```
STRING FONT
```
Name of the [`FONT`](FONT.md) variable from which character textures are taken.
### HJUSTIFY
```
STRING HJUSTIFY
```
Horizontal alignment inside the `RECT` rectangle. Accepted values: `LEFT`, `RIGHT`, `CENTER`.
### PRIORITY
```
INTEGER PRIORITY
```
The text's rendering priority (`Z`) relative to other scene objects.
### RECT
```
INTEGER,INTEGER,INTEGER,INTEGER RECT
```
The rectangle in which the text is drawn — four comma-separated integers: `xLeft, yBottom, xRight, yTop`. In a script, the field can also reference a variable of type [`ANIMO`](index.md) or [`IMAGE`](IMAGE.md), in which case its bounds are taken from that object.
### TEXT
```
STRING TEXT
```
The displayed text. Modified through [`SETTEXT`](#settext).
### TOCANVAS
```
BOOL TOCANVAS
```
Whether the text is rendered on the scene's main canvas. If `FALSE`, the text is not visible regardless of `VISIBLE`.
### VISIBLE
```
BOOL VISIBLE
```
The text's visibility. Modified through [`SHOW`](#show) and [`HIDE`](#hide).
### VJUSTIFY
```
STRING VJUSTIFY
```
Vertical alignment inside the `RECT` rectangle. Accepted values: `TOP`, `BOTTOM`, `CENTER`.
## Methods
### HIDE
```
void HIDE()
```
Hides the text (sets [`VISIBLE`](#visible) to `FALSE`).
### SETJUSTIFY
```
void SETJUSTIFY(INTEGER xLeft, INTEGER yBottom, INTEGER xRight, INTEGER yTop, STRING hJustify, STRING vJustify)
```
Sets the drawing rectangle ([`RECT`](#rect)) and the horizontal ([`HJUSTIFY`](#hjustify)) and vertical ([`VJUSTIFY`](#vjustify)) alignment in a single call.
**Parameters**
- `xLeft, yBottom, xRight, yTop` — rectangle coordinates.
- `hJustify` — horizontal alignment (`LEFT`, `RIGHT`, `CENTER`).
- `vJustify` — vertical alignment (`TOP`, `BOTTOM`, `CENTER`).
### SETPRIORITY
```
void SETPRIORITY(INTEGER priority)
```
Sets the text's rendering priority.
**Parameters**
- `priority` — the new value of the [`PRIORITY`](#priority) field.
### SETTEXT
```
void SETTEXT(STRING text)
```
Changes the displayed text.
**Parameters**
- `text` — the new value of the [`TEXT`](#text) field.
**Examples**
```
TXTDEBUG^SETTEXT(ARRPX^GETSIZE());
TXTDEBUG^SETTEXT("SAVED");
```
### SHOW
```
void SHOW()
```
Shows the text (sets [`VISIBLE`](#visible) to `TRUE`).
## Signals
### ONINIT
Fired when the object is initialised.

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

@@ -0,0 +1,55 @@
# Type reference
List of data types available in scripts for the Piklib/BlooMoo engine. The list will be filled in as individual pages are written.
## Types used in scripts
### Primitives
- [BOOL](BOOL.md) — boolean value.
- [DOUBLE](DOUBLE.md) — double-precision floating-point number.
- [INTEGER](INTEGER.md) — signed integer number.
- [STRING](STRING.md) — character string.
### Collections
- [ARRAY](ARRAY.md) — one-dimensional array.
- [MULTIARRAY](MULTIARRAY.md) — multi-dimensional array with automatic resizing.
### Logical conditions
- [CONDITION](CONDITION.md) — comparison of two operands.
- [COMPLEXCONDITION](COMPLEXCONDITION.md) — combination of two conditions with `AND`/`OR`.
### Code structure
- [BEHAVIOUR](BEHAVIOUR.md) — procedure.
- [CLASS](CLASS.md) — class definition.
### Scene hierarchy
- [APPLICATION](APPLICATION.md) — top of the script hierarchy.
- [EPISODE](EPISODE.md) — logical segment of the game.
- [SCENE](SCENE.md) — a single scene.
### Built-in I/O objects
- [KEYBOARD](KEYBOARD.md) — keyboard state.
- [MOUSE](MOUSE.md) — mouse state.
- [RAND](RAND.md) — pseudo-random number generator.
- [SYSTEM](SYSTEM.md) — system information.
### Media
- [ANIMO](ANIMO.md) — animation from an `.ANN` file.
- [FONT](FONT.md) — bitmap font definition.
- [IMAGE](IMAGE.md) — static image.
- [SEQUENCE](SEQUENCE.md) — animation sequence with synchronised audio.
- [SOUND](SOUND.md) — short sound effect.
- [TEXT](TEXT.md) — on-screen text element.
## Remaining types
Pages for the following types will be added next:
BUTTON, CANVAS_OBSERVER, CNVLOADER, DATABASE, EXPRESSION, GROUP, INERTIA, MATRIX, PATTERN, STATICFILTER, STRUCT, TIMER, VECTOR, VIRTUALGRAPHICSOBJECT, WORLD.

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.

2
docs/requirements.txt Normal file
View File

@@ -0,0 +1,2 @@
mkdocs-material==9.5.44
mkdocs-static-i18n==1.2.3