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.