Added part of docs

docs/en/reference/ANIMO.md

@@ -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.

docs/en/reference/APPLICATION.md

@@ -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");
+```

docs/en/reference/ARRAY.md

@@ -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)).

docs/en/reference/BEHAVIOUR.md

@@ -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)).

docs/en/reference/BOOL.md

@@ -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.

docs/en/reference/CLASS.md

@@ -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.

docs/en/reference/COMPLEXCONDITION.md

@@ -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`.

docs/en/reference/CONDITION.md

@@ -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`.

docs/en/reference/DOUBLE.md

@@ -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.

docs/en/reference/EPISODE.md

@@ -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"));
+```

docs/en/reference/FONT.md

@@ -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
+```

docs/en/reference/IMAGE.md

@@ -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.

docs/en/reference/INTEGER.md

@@ -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.

docs/en/reference/KEYBOARD.md

@@ -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`

docs/en/reference/MOUSE.md

@@ -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.

docs/en/reference/MULTIARRAY.md

@@ -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)).

docs/en/reference/RAND.md

@@ -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.

docs/en/reference/SCENE.md

@@ -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");
+```

docs/en/reference/SEQUENCE.md

@@ -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)).

docs/en/reference/SOUND.md

@@ -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).

docs/en/reference/STRING.md

@@ -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.

docs/en/reference/SYSTEM.md

@@ -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.

docs/en/reference/TEXT.md

@@ -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.

docs/en/reference/index.md

@@ -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.