Finished automatically generated docs

Time to correct it by itself
2026-05-20 22:49:46 +02:00
parent df6cf2f3d3
commit 198d9cf477
35 changed files with 6120 additions and 73 deletions
--- a/docs/en/reference/BUTTON.md
+++ b/docs/en/reference/BUTTON.md
@@ -0,0 +1,249 @@
+# BUTTON
+
+An interactive button with three visual states (normal, hovered, pressed) and separate graphics and sounds for each. A button can also be disabled — either completely (`DISABLE`) or while remaining visible (`DISABLEBUTVISIBLE`).
+
+Internally the button is a small state machine. Every state transition automatically shows or hides the appropriate graphics, plays the linked sound, and may emit a signal.
+
+## Button states
+
+| State | Meaning |
+| --- | --- |
+| `STANDARD` | at rest — the `GFXSTANDARD` graphic is shown. |
+| `HOVERED` | the cursor is over the button — the `GFXONMOVE` graphic is shown (or `GFXSTANDARD` if unset). |
+| `PRESSED` | the button is being pressed — the `GFXONCLICK` graphic is shown (or `GFXSTANDARD` if unset). |
+| `DISABLED` | the button is disabled and hidden. |
+| `DISABLED_BUT_VISIBLE` | the button is disabled but the `GFXSTANDARD` graphic is shown. |
+
+## Fields
+
+### DRAGGABLE
+
+```
+BOOL DRAGGABLE
+```
+
+Whether the button can be dragged.
+
+### ENABLE
+
+```
+BOOL ENABLE
+```
+
+Whether the button is enabled after initialisation. A value of `FALSE` puts the button into the [`DISABLED`](#button-states) state.
+
+### GFXONCLICK
+
+```
+STRING GFXONCLICK
+```
+
+Name of the [`ANIMO`](ANIMO.md) or [`IMAGE`](IMAGE.md) variable shown in the [`PRESSED`](#button-states) state. Optional — if unset, `GFXSTANDARD` keeps being shown while pressed.
+
+### GFXONMOVE
+
+```
+STRING GFXONMOVE
+```
+
+Name of the [`ANIMO`](ANIMO.md) or [`IMAGE`](IMAGE.md) variable shown in the [`HOVERED`](#button-states) state. Optional.
+
+### GFXSTANDARD
+
+```
+STRING GFXSTANDARD
+```
+
+Name of the [`ANIMO`](ANIMO.md) or [`IMAGE`](IMAGE.md) variable shown at rest. If [`ENABLE`](#enable) is `FALSE`, the graphic is hidden after initialisation — with one exception: if the linked animation is already playing, it stays visible (example: the torch in `16BLAWA` from *Reksio i Skarb Piratów*). In that case the linked graphic's [`TOCANVAS`](ANIMO.md#tocanvas) setting is ignored.
+
+### RECT
+
+```
+INTEGER, INTEGER, INTEGER, INTEGER RECT
+STRING RECT
+```
+
+The cursor hit area. Two forms are accepted:
+
+- Four integers `xLeft,yBottom,xRight,yTop` defining a rectangle on screen.
+- The name of an [`ANIMO`](ANIMO.md) or [`IMAGE`](IMAGE.md) variable whose current graphic rectangle will be used.
+
+If unset, the rectangle of the [`GFXSTANDARD`](#gfxstandard) variable is used.
+
+### SNDONCLICK
+
+```
+STRING SNDONCLICK
+```
+
+Name of the [`SOUND`](SOUND.md) variable played on entering the [`PRESSED`](#button-states) state.
+
+### SNDONMOVE
+
+```
+STRING SNDONMOVE
+```
+
+Name of the [`SOUND`](SOUND.md) variable played on entering the [`HOVERED`](#button-states) state.
+
+### SNDSTANDARD
+
+```
+STRING SNDSTANDARD
+```
+
+Name of the [`SOUND`](SOUND.md) variable played on returning to the [`STANDARD`](#button-states) state.
+
+### VISIBLE
+
+```
+BOOL VISIBLE
+```
+
+Persisted in script data but not observed by the engine — testing shows this field has no effect on button behaviour.
+
+## Methods
+
+### DISABLE
+
+```
+void DISABLE()
+```
+
+Disables the button and hides all linked graphics ([`GFXSTANDARD`](#gfxstandard), [`GFXONMOVE`](#gfxonmove), [`GFXONCLICK`](#gfxonclick)). Graphics linked via [`RECT`](#rect) are unaffected.
+
+**Examples**
+
+```
+B_GLOBAL_PAUSE^DISABLE();
+```
+
+### DISABLEBUTVISIBLE
+
+```
+void DISABLEBUTVISIBLE()
+```
+
+Disables the button but keeps the [`GFXSTANDARD`](#gfxstandard) graphic visible (like `DISABLE`, but the final state is [`DISABLED_BUT_VISIBLE`](#button-states)).
+
+**Examples**
+
+```
+BTNBONE^DISABLEBUTVISIBLE();
+BTNFORGOT^DISABLEBUTVISIBLE();
+```
+
+### ENABLE
+
+```
+void ENABLE()
+```
+
+Enables the button and restores visibility of the [`GFXSTANDARD`](#gfxstandard) graphic. Calling this on an already-enabled button has no effect.
+
+**Examples**
+
+```
+B_GLOBAL_PAUSE^ENABLE();
+BTNEXIT^ENABLE();
+```
+
+### SETPRIORITY
+
+```
+void SETPRIORITY(INTEGER posZ)
+```
+
+Sets the rendering priority (Z position) of all three linked graphics ([`GFXSTANDARD`](#gfxstandard), [`GFXONMOVE`](#gfxonmove), [`GFXONCLICK`](#gfxonclick)). Higher values are drawn on top.
+
+**Parameters**
+
+- `posZ` — new priority value.
+
+**Examples**
+
+```
+B_GLOBAL_PAUSE^SETPRIORITY(5001);
+BTNNULLFADE^SETPRIORITY(40000);
+```
+
+### SETRECT
+
+```
+void SETRECT(STRING varName)
+void SETRECT(INTEGER xLeft, INTEGER yBottom, INTEGER xRight, INTEGER yTop)
+```
+
+Sets the cursor hit area. The first form copies the rectangle from a graphics variable; the second specifies it directly.
+
+**Parameters**
+
+- `varName` — name of the graphics variable **(form 1)**.
+- `xLeft`, `yBottom`, `xRight`, `yTop` — rectangle coordinates **(form 2)**.
+
+**Examples**
+
+```
+EXITPROGAM^SETRECT("ANNEXIT");
+*STMP0^SETRECT([ITMPX+[ITMPDX*_I_]],[ITMPY+[ITMPDY*_I_]],[ITMPX+15+[ITMPDX*_I_]],[ITMPY+15+[ITMPDY*_I_]]);
+```
+
+### SETSTD
+
+```
+void SETSTD(STRING varName)
+void SETSTD(STRING varName, BOOL flag)
+```
+
+Sets the button's standard graphic ([`GFXSTANDARD`](#gfxstandard)) and zeroes its priority. Shipping scripts also use a two-argument form whose boolean flag is always `FALSE`; its meaning has not been established.
+
+**Parameters**
+
+- `varName` — name of the new standard graphic variable (an empty string `""` clears the link).
+- `flag` — configuration flag **(form 2, meaning unknown)**.
+
+**Examples**
+
+```
+BTNEXIT^SETSTD("ANNOBJECT2");
+B_GLOBAL_PAUSE^SETSTD("",FALSE);
+BTNBAD^SETSTD("ZLY",FALSE);
+```
+
+## Signals
+
+### ONINIT
+
+Fired when the object is initialised.
+
+### ONFOCUSON
+
+Fired on the transition from [`STANDARD`](#button-states) to [`HOVERED`](#button-states) — i.e. when the cursor enters the button area.
+
+### ONFOCUSOFF
+
+Fired on the transition from [`HOVERED`](#button-states) to [`STANDARD`](#button-states) — when the cursor leaves the button.
+
+### ONCLICKED
+
+Fired on the transition into [`PRESSED`](#button-states) (the mouse button has been pressed).
+
+### ONRELEASED
+
+Fired on the transition from [`PRESSED`](#button-states) to [`HOVERED`](#button-states) — when the mouse button is released over the button area.
+
+### ONACTION
+
+Fired together with [`ONRELEASED`](#onreleased) — confirms that a full click (press and release on the button area) has happened.
+
+### ONSTARTDRAGGING
+
+Fired when dragging begins (only for buttons with [`DRAGGABLE`](#draggable) set to `TRUE`).
+
+### ONENDDRAGGING
+
+Fired when dragging ends.
+
+### ONSIGNAL
+
+Fired when a signal arrives (see [Events and signals](../engine/events.md#onsignal)).
--- a/docs/en/reference/CANVAS_OBSERVER.md
+++ b/docs/en/reference/CANVAS_OBSERVER.md
@@ -0,0 +1,243 @@
+# CANVAS_OBSERVER
+
+Entry point for canvas operations — the shared rendering area where the engine draws every visible graphic. Provides methods for adding and removing graphics from the screen, looking up the object under a point, setting the background, taking screenshots, and emitting signals on game-window focus changes.
+
+A scene typically has a single `CANVAS_OBSERVER` instance that scripts treat as a global object.
+
+## Methods
+
+### ADD
+
+```
+void ADD(STRING varName)
+void ADD(STRING varName, INTEGER priority)
+```
+
+Adds an [`ANIMO`](ANIMO.md) or [`IMAGE`](IMAGE.md) variable to the canvas — makes it visible and optionally assigns a render priority (default `1000`).
+
+**Parameters**
+
+- `varName` — name of the graphics variable.
+- `priority` — (optional) render priority (Z position).
+
+**Examples**
+
+```
+CANVASOBSERVER^ADD("ANNMKORBA2");
+CANVASOBSERVER^ADD("ANNMPRZEGRYZA");
+```
+
+### ENABLENOTIFY
+
+```
+void ENABLENOTIFY(BOOL enable)
+```
+
+Enables or disables emission of game-window focus signals ([`ONWINDOWFOCUSON`](#onwindowfocuson), [`ONWINDOWFOCUSOFF`](#onwindowfocusoff)).
+
+**Parameters**
+
+- `enable` — `TRUE` enables notifications, `FALSE` disables them.
+
+**Examples**
+
+```
+CANVASOBSERVER^ENABLENOTIFY(TRUE);
+```
+
+### GETBPP
+
+```
+INTEGER GETBPP()
+```
+
+Returns the canvas colour depth in bits per pixel. The original BlooMoo engine runs in 16 bpp (RGB565) — this method always returns `16`.
+
+**Returns**: [`INTEGER`](INTEGER.md) — colour depth in bits (`16`).
+
+### GETGRAPHICSAT
+
+```
+STRING GETGRAPHICSAT(INTEGER posX, INTEGER posY, BOOL onlyVisible, INTEGER minZ, INTEGER maxZ)
+STRING GETGRAPHICSAT(INTEGER posX, INTEGER posY, BOOL onlyVisible, INTEGER minZ, INTEGER maxZ, BOOL ignoreAlpha)
+```
+
+Returns the name of the graphics variable at the point `(posX, posY)`. Only the current scene is searched. The lookup starts from the highest-priority graphic and walks down. Returns `"NULL"` if no graphic matches.
+
+**Parameters**
+
+- `posX`, `posY` — query point coordinates.
+- `onlyVisible` — if `TRUE`, only currently visible graphics are considered.
+- `minZ`, `maxZ` — priority (Z) range restricting the search.
+- `ignoreAlpha` — (optional) if `TRUE`, only the graphic's rectangle is tested; if `FALSE` (or omitted), the pixel's alpha channel is checked too.
+
+**Returns**: [`STRING`](STRING.md) — the matched object's name or `"NULL"`.
+
+**Examples**
+
+```
+CANVASOBSERVER^GETGRAPHICSAT(MOUSE^GETPOSX(),MOUSE^GETPOSY(),TRUE,2998,2998,FALSE);
+CANVASOBSERVER^GETGRAPHICSAT(VARICURSORX,VARICURSORY,TRUE,40,40,TRUE);
+```
+
+### GETGRAPHICSAT2
+
+```
+STRING GETGRAPHICSAT2(INTEGER posX, INTEGER posY, BOOL onlyVisible, INTEGER minZ, INTEGER maxZ)
+STRING GETGRAPHICSAT2(INTEGER posX, INTEGER posY, BOOL onlyVisible, INTEGER minZ, INTEGER maxZ, BOOL ignoreAlpha)
+```
+
+Variant of [`GETGRAPHICSAT`](#getgraphicsat) that walks up the container hierarchy (scene → episode → root) instead of searching only the current scene.
+
+### MOVEBKG
+
+```
+void MOVEBKG(INTEGER deltaX, INTEGER deltaY)
+```
+
+Moves the background by the given X/Y deltas (relative to its current position).
+
+**Parameters**
+
+- `deltaX`, `deltaY` — translation vector in pixels.
+
+**Examples**
+
+```
+CANVASOBSERVER^MOVEBKG(0,ARRAYDY^GET(0));
+CANVASOBSERVER^MOVEBKG(ISCROLLMOVEX,ISCROLLMOVEY);
+```
+
+### PASTE
+
+```
+void PASTE(STRING varName, INTEGER posX, INTEGER posY)
+```
+
+Pastes a snapshot of the current contents of an [`ANIMO`](ANIMO.md) or [`IMAGE`](IMAGE.md) graphic onto the canvas as a static, non-modifiable texture at `(posX, posY)`. The source variable itself is not modified.
+
+**Parameters**
+
+- `varName` — name of the graphics variable.
+- `posX`, `posY` — paste position.
+
+**Examples**
+
+```
+CANVASOBSERVER^PASTE("ANNBUM",[I1-IPLANPOSX],[I2-IPLANPOSY]);
+CANVASOBSERVER^PASTE("IMG1",0,0);
+```
+
+### REDRAW
+
+```
+void REDRAW()
+```
+
+In the original engine this marks the canvas as needing repaint. In practice the engine already redraws the whole canvas every frame, so this method behaves as a no-op.
+
+### REFRESH
+
+```
+void REFRESH()
+```
+
+Forces a redraw of every [`IMAGE`](IMAGE.md) in the current scene — internally calls [`INVALIDATE`](IMAGE.md#invalidate) on each.
+
+### REMOVE
+
+```
+void REMOVE(STRING varName1, [STRING varName2, ...])
+```
+
+Hides the listed graphics on the canvas (sets their visibility to `FALSE`). Accepts any number of arguments.
+
+**Parameters**
+
+- `varName1, varName2, …` — successive graphics-variable names to hide.
+
+**Examples**
+
+```
+CANVASOBSERVER^REMOVE("ZLY");
+CANVASOBSERVER^REMOVE("ANNAUTOR","ANNAUTOL","ANNAUTORMASK","ANNAUTOLMASK");
+```
+
+### SAVE
+
+```
+void SAVE(STRING imgFileName, DOUBLE xScaleFactor, DOUBLE yScaleFactor)
+void SAVE(STRING imgFileName, DOUBLE xScaleFactor, DOUBLE yScaleFactor, INTEGER xLeft, INTEGER yTop, INTEGER xRight, INTEGER yBottom)
+```
+
+Saves the current canvas view to an `.IMG` file. The seven-argument form crops a rectangle from the canvas before scaling.
+
+**Parameters**
+
+- `imgFileName` — destination `.IMG` path.
+- `xScaleFactor`, `yScaleFactor` — X/Y scaling factors.
+- `xLeft`, `yTop`, `xRight`, `yBottom` — (optional) rectangle to crop before scaling.
+
+**Examples**
+
+```
+CANVASOBSERVER^SAVE("$COMMON\PAGE.IMG",1,1);
+CANVASOBSERVER^SAVE("$COMMON\ZOOM.IMG",2,2,$1,$2,$3,$4);
+CANVASOBSERVER^SAVE(["$COMMON\SAVE_BD\BD_SCR"+VARISLOTNO+".IMG"],0.5,0.5);
+```
+
+### SETBACKGROUND
+
+```
+void SETBACKGROUND(STRING imageName)
+```
+
+Sets the canvas background. The argument may name an existing [`IMAGE`](IMAGE.md) variable or a path to an `.IMG` file — in the latter case the engine creates a hidden [`IMAGE`](IMAGE.md) variable backing that file.
+
+**Parameters**
+
+- `imageName` — [`IMAGE`](IMAGE.md) variable name or `.IMG` file path.
+
+**Examples**
+
+```
+CANVASOBSERVER^SETBACKGROUND(SOBJECT|NAME);
+CANVASOBSERVER^SETBACKGROUND("LOGO.IMG");
+```
+
+### SETBKGPOS
+
+```
+void SETBKGPOS(INTEGER posX, INTEGER posY)
+```
+
+Sets the absolute X/Y position of the background.
+
+**Parameters**
+
+- `posX`, `posY` — new background position.
+
+**Examples**
+
+```
+CANVASOBSERVER^SETBKGPOS([VARI_BKGX-VARI_BKGXOFFSET],[VARI_BKGY-VARI_BKGYOFFSET]);
+CANVASOBSERVER^SETBKGPOS(VARI_TMPX,0);
+```
+
+## Signals
+
+### ONINIT
+
+Fired when the object is initialised.
+
+### ONWINDOWFOCUSON
+
+Fired when the game window gains focus (e.g. after un-minimising). Emission requires notifications enabled via [`ENABLENOTIFY`](#enablenotify).
+
+### ONWINDOWFOCUSOFF
+
+Fired when the game window loses focus (e.g. when switched to another application). Emission requires notifications enabled.
+
+### ONSIGNAL
+
+Fired when a signal arrives (see [Events and signals](../engine/events.md#onsignal)).
--- a/docs/en/reference/CNVLOADER.md
+++ b/docs/en/reference/CNVLOADER.md
@@ -0,0 +1,55 @@
+# CNVLOADER
+
+Dynamic loader for `.CNV` files at runtime. Unlike [`CLASS`](CLASS.md), which defines an isolated per-instance context, `CNVLOADER` merges variables from the loaded file directly into the current context — they behave as if they had been defined there from the start.
+
+A single `CNVLOADER` can hold several `.CNV` files loaded at once. Each [`RELEASE`](#release) call frees one specific file.
+
+## Methods
+
+### LOAD
+
+```
+void LOAD(STRING cnvFile)
+```
+
+Loads the given `.CNV` file. Variables defined in the file are added to the current context. Re-loading an already-loaded file is a no-op.
+
+**Parameters**
+
+- `cnvFile` — path to the `.CNV` file (resolved through the engine VFS).
+
+**Examples**
+
+```
+CNVLOADER^LOAD(VARSTEMP0);
+CNVLOADER^LOAD([G_SCUTSCENE+".CNV"]);
+```
+
+### RELEASE
+
+```
+void RELEASE(STRING cnvFile)
+```
+
+Unloads a previously loaded file — removes from the current context every variable that came from it. Calling this on a file that has not been loaded is a no-op.
+
+**Parameters**
+
+- `cnvFile` — path to a previously loaded file.
+
+**Examples**
+
+```
+CNVLOADER^RELEASE([G_SCUTSCENE+".CNV"]);
+CNVLOADER^RELEASE("WYNURZENIE.CNV");
+```
+
+## Signals
+
+### ONINIT
+
+Fired when the object is initialised.
+
+### ONSIGNAL
+
+Fired when a signal arrives (see [Events and signals](../engine/events.md#onsignal)).
--- a/docs/en/reference/DATABASE.md
+++ b/docs/en/reference/DATABASE.md
@@ -0,0 +1,152 @@
+# DATABASE
+
+A tabular database — a collection of rows sharing a single schema. The schema is defined by a paired [`STRUCT`](STRUCT.md) variable: its [`FIELDS`](STRUCT.md#fields) entry specifies the table's columns and per-column data types.
+
+Rows are accessed sequentially via a cursor. The cursor position is updated by [`SELECT`](#select) (move to a specific index), [`NEXT`](#next) (advance one row), and [`FIND`](#find) (move to the first row matching a column value). Data is persisted in `.DTA` files using a `|`-separated text format — loadable via [`LOAD`](#load) and writable via [`SAVE`](#save).
+
+## Fields
+
+### MODEL
+
+```
+STRING MODEL
+```
+
+Name of the [`STRUCT`](STRUCT.md) variable that defines the database's schema. Required — [`LOAD`](#load) refuses to run if the schema has not been synchronised with the [`STRUCT`](STRUCT.md) beforehand.
+
+## Methods
+
+### FIND
+
+```
+INTEGER FIND(STRING columnName, mixed columnValue, INTEGER defaultIndex)
+```
+
+Returns the index of the first row whose `columnName` column equals `columnValue`. Falls back to `defaultIndex` if no row matches.
+
+**Parameters**
+
+- `columnName` — name of the column to search.
+- `columnValue` — value to match.
+- `defaultIndex` — index returned on no match.
+
+**Returns**: [`INTEGER`](INTEGER.md) — matching row index or `defaultIndex`.
+
+**Examples**
+
+```
+DBOBJECTS^FIND("IDNAME",VARSTAKENAME,0);
+DBOBJECTS^FIND("TYPE",102,0);
+DBDIALOGI^FIND("ID",SDIALOGNAME,IDIALOGINDEKS);
+```
+
+### GETROWSNO
+
+```
+INTEGER GETROWSNO()
+```
+
+Returns the number of rows in the database.
+
+**Returns**: [`INTEGER`](INTEGER.md) — the row count.
+
+**Examples**
+
+```
+DBOBJECTS^GETROWSNO();
+```
+
+### LOAD
+
+```
+void LOAD(STRING dtaName)
+```
+
+Loads database contents from a `.DTA` file. Each line is one row; columns within a row are separated by `|`. The call aborts with an error if the schema ([`MODEL`](#model)) has not been set.
+
+**Parameters**
+
+- `dtaName` — path to the `.DTA` file.
+
+**Examples**
+
+```
+DBOBJECTS^LOAD(VARSCURRARCADE);
+DBITEMS^LOAD("$COMMON\ITEMS0.DTA");
+```
+
+### NEXT
+
+```
+void NEXT()
+```
+
+Advances the cursor to the next row.
+
+**Examples**
+
+```
+DBSCENE^NEXT();
+```
+
+### REMOVEALL
+
+```
+void REMOVEALL()
+```
+
+Drops every row from the database. The schema ([`MODEL`](#model)) is preserved.
+
+**Examples**
+
+```
+DBITEMS^REMOVEALL();
+```
+
+### SAVE
+
+```
+void SAVE(STRING dtaName)
+```
+
+Writes the current contents to a `.DTA` file using the same format that [`LOAD`](#load) accepts (rows separated by newlines, columns by `|`).
+
+**Parameters**
+
+- `dtaName` — destination `.DTA` path.
+
+**Examples**
+
+```
+DBOBJECTS^SAVE(VARSCURRARCADE);
+DBLEVEL^SAVE(["$COMMON\SAVE_BD\BD_CLEV"+VARIACTIVESLOT+".FLD"]);
+```
+
+### SELECT
+
+```
+void SELECT(INTEGER rowIndex)
+```
+
+Moves the cursor to the row at the given (zero-based) index.
+
+**Parameters**
+
+- `rowIndex` — target row index.
+
+**Examples**
+
+```
+DBOBJECTS^SELECT(0);
+DBOBJECTS^SELECT(VARITER);
+```
+
+## Signals
+
+### ONINIT
+
+Fired when the object is initialised.
+
+### ONSIGNAL
+
+Fired when a signal arrives (see [Events and signals](../engine/events.md#onsignal)).
--- a/docs/en/reference/EXPRESSION.md
+++ b/docs/en/reference/EXPRESSION.md
@@ -0,0 +1,51 @@
+# EXPRESSION
+
+A named two-operand arithmetic expression. Reading the variable's value recomputes `OPERAND1 OPERATOR OPERAND2` in the current context every time, so the result tracks live changes to the input variables.
+
+Operands may be numeric literals, variable names, or bracketed sub-expressions (see [Arithmetic](../engine/arithmetic.md)). `EXPRESSION` exposes no script methods.
+
+## Fields
+
+### OPERAND1
+
+```
+STRING OPERAND1
+```
+
+Left-hand operand of the expression.
+
+### OPERAND2
+
+```
+STRING OPERAND2
+```
+
+Right-hand operand of the expression.
+
+### OPERATOR
+
+```
+STRING OPERATOR
+```
+
+Binary operator applied to the operands. Accepted values:
+
+| Value | Operation |
+| --- | --- |
+| `ADD` | addition |
+| `SUB` | subtraction |
+| `MUL` | multiplication |
+| `DIV` | division |
+| `MOD` | modulo |
+
+The result-type rules (integer vs floating-point) mirror those of ordinary script arithmetic — see [Arithmetic — typing rule](../engine/arithmetic.md#typing-rule).
+
+## Signals
+
+### ONINIT
+
+Fired when the object is initialised.
+
+### ONSIGNAL
+
+Fired when a signal arrives (see [Events and signals](../engine/events.md#onsignal)).
--- a/docs/en/reference/GROUP.md
+++ b/docs/en/reference/GROUP.md
@@ -0,0 +1,166 @@
+# GROUP
+
+A group of variables that can receive batched method calls. Any method invoked on a `GROUP` instance that is not part of the group's own API is delegated to each member in turn. Members that do not implement the called method are skipped silently (without error).
+
+The group keeps an internal **marker** pointing at one of its elements. The marker is updated by [`NEXT`](#next), [`PREV`](#prev), and [`RESETMARKER`](#resetmarker). It can be used to iterate over the group sequentially.
+
+The variable's value is the number of elements in the group.
+
+## Methods
+
+### \[method name\]
+
+```
+void <methodName>(mixed param1, ..., mixed paramN)
+```
+
+Any method outside the group's own API is forwarded to every member with the same arguments. Members that do not implement the method are skipped.
+
+**Examples**
+
+```
+GRPHIDE^HIDE();
+GRPMOVE^SETPOSITION(VARX,VARY);
+```
+
+### ADD
+
+```
+void ADD(STRING varName1, [STRING varName2, ...])
+```
+
+Adds one or more elements to the group by variable name. Re-adding an element that is already in the group is a no-op.
+
+**Parameters**
+
+- `varName1, varName2, …` — successive variable names to add.
+
+**Examples**
+
+```
+GRPHIDE^ADD("ANNREX");
+GRPMOVE^ADD("ANNBODY1","ANNWAND1","ANNHEAD1");
+GALL^ADD(["ANNPOLA_"+ICLONENO]);
+```
+
+### ADDCLONES
+
+```
+void ADDCLONES(STRING varName, INTEGER firstCloneIndex, INTEGER lastCloneIndex)
+```
+
+Adds an inclusive range of variable clones — from `firstCloneIndex` up to `lastCloneIndex`. Clones are referenced by name using the engine's clone-naming pattern (index suffix).
+
+**Parameters**
+
+- `varName` — base variable name.
+- `firstCloneIndex` — first clone index.
+- `lastCloneIndex` — last clone index.
+
+**Examples**
+
+```
+GBKG^ADDCLONES("ANNPLANNAK",0,[I1-1]);
+GTRASA^ADDCLONES("ANNSKRZYNIA",1,ITMPCLONENO);
+GRPLANS^ADDCLONES("IMGPLAN1",1,10);
+```
+
+### GETSIZE
+
+```
+INTEGER GETSIZE()
+```
+
+Returns the number of elements in the group.
+
+**Returns**: [`INTEGER`](INTEGER.md) — the group size.
+
+**Examples**
+
+```
+GRPHIDE^GETSIZE();
+```
+
+### NEXT
+
+```
+mixed NEXT()
+```
+
+Advances the marker by one (clamped at the last element) and returns a reference to the element under the new marker.
+
+**Returns**: reference to the element under the new marker.
+
+**Examples**
+
+```
+GENEMIES^NEXT();
+GBAZUK^NEXT();
+```
+
+### PREV
+
+```
+mixed PREV()
+```
+
+Moves the marker back by one (clamped at zero) and returns a reference to the element under the new marker.
+
+**Returns**: reference to the element under the new marker.
+
+### REMOVE
+
+```
+void REMOVE(STRING varName)
+```
+
+Removes the named element from the group. If the marker was pointing past the new last index, it is moved back to the last available element (or to `-1` if the group becomes empty).
+
+**Parameters**
+
+- `varName` — variable name to remove.
+
+**Examples**
+
+```
+GOBJ^REMOVE(S1);
+GOBJ^REMOVE("ANNTNTR");
+```
+
+### REMOVEALL
+
+```
+void REMOVEALL()
+```
+
+Drops every element from the group and resets the marker.
+
+**Examples**
+
+```
+GRPHIDE^REMOVEALL();
+```
+
+### RESETMARKER
+
+```
+void RESETMARKER()
+```
+
+Moves the marker to the first element (index `0`). For an empty group the marker becomes `-1`.
+
+**Examples**
+
+```
+GENEMIES^RESETMARKER();
+```
+
+## Signals
+
+### ONINIT
+
+Fired when the object is initialised.
+
+### ONSIGNAL
+
+Fired when a signal arrives (see [Events and signals](../engine/events.md#onsignal)).
--- a/docs/en/reference/INERTIA.md
+++ b/docs/en/reference/INERTIA.md
@@ -0,0 +1,300 @@
+# INERTIA
+
+Interface to the built-in 2D physics engine of the same name (Inertia). Manages rigid bodies: creating objects, linking them to animations, gravity, velocities, damping, and applying forces. Used in *Reksio i Kretes w Akcji*.
+
+Every physics body has an `objectId` — an integer used by most methods to identify the body. The world is loaded from an `.INE` file (see [Engine overview](../engine/index.md)) via [`LOAD`](#load).
+
+## Methods
+
+### ADDFORCE
+
+```
+void ADDFORCE(INTEGER objectId, INTEGER forceX, INTEGER forceY)
+```
+
+Applies a force to the object along the X and Y axes.
+
+**Parameters**
+
+- `objectId` — object identifier.
+- `forceX`, `forceY` — force components.
+
+**Examples**
+
+```
+EXTWORLD^ADDFORCE(1,-500,0);
+EXTWORLD^ADDFORCE(1,0,-50);
+```
+
+### CREATESPHERE
+
+```
+void CREATESPHERE(INTEGER objectId, INTEGER posX, INTEGER posY, INTEGER radius)
+```
+
+Creates a sphere of the given centre position and radius in the physics world, assigning the given identifier.
+
+**Parameters**
+
+- `objectId` — identifier for the new body.
+- `posX`, `posY` — sphere centre position.
+- `radius` — sphere radius.
+
+**Examples**
+
+```
+EXTWORLD^CREATESPHERE(5,10,10,10);
+```
+
+### DELETEBODY
+
+```
+void DELETEBODY(INTEGER objectId)
+```
+
+Removes a body from the physics engine.
+
+**Parameters**
+
+- `objectId` — identifier of the body to remove.
+
+**Examples**
+
+```
+EXTWORLD^DELETEBODY(IHANDLEDEL);
+EXTWORLD^DELETEBODY(IRAKIETAOBJ);
+```
+
+### GETPOSITIONX
+
+```
+INTEGER GETPOSITIONX(INTEGER objectId)
+```
+
+Returns the body's current X position.
+
+**Parameters**
+
+- `objectId` — body identifier.
+
+**Returns**: [`INTEGER`](INTEGER.md) — X coordinate.
+
+### GETPOSITIONY
+
+```
+INTEGER GETPOSITIONY(INTEGER objectId)
+```
+
+Returns the body's current Y position.
+
+**Parameters**
+
+- `objectId` — body identifier.
+
+**Returns**: [`INTEGER`](INTEGER.md) — Y coordinate.
+
+### GETSPEED
+
+```
+DOUBLE GETSPEED(INTEGER objectId)
+```
+
+Returns the body's speed (linear velocity magnitude).
+
+**Parameters**
+
+- `objectId` — body identifier.
+
+**Returns**: [`DOUBLE`](DOUBLE.md) — speed value.
+
+### LINK
+
+```
+void LINK(INTEGER objectId, STRING animoName, BOOL flag1, BOOL flag2)
+```
+
+Binds a physics body to an [`ANIMO`](ANIMO.md) animation — the animation's position is updated from the physics simulation. The meaning of the two boolean flags has not been established (shipping games always pass `TRUE` for both).
+
+**Parameters**
+
+- `objectId` — physics body identifier.
+- `animoName` — name of the [`ANIMO`](ANIMO.md) variable.
+- `flag1`, `flag2` — configuration flags (purpose not established).
+
+**Examples**
+
+```
+EXTWORLD^LINK(1,"ANNSZCZUREK",TRUE,TRUE);
+EXTWORLD^LINK(IOBIEKT,["ANNSTRZAL_"+ISTRZAL],TRUE,TRUE);
+```
+
+### LOAD
+
+```
+void LOAD(STRING path)
+```
+
+Loads a physics-world definition from an `.INE` file.
+
+**Parameters**
+
+- `path` — path to the `.INE` file.
+
+**Examples**
+
+```
+EXTWORLD^LOAD("WORLD.INE");
+```
+
+### RESETTIMER
+
+```
+void RESETTIMER()
+```
+
+Resets the simulation's internal timer.
+
+**Examples**
+
+```
+EXTWORLD^RESETTIMER();
+```
+
+### SETGRAVITY
+
+```
+void SETGRAVITY(DOUBLE gravityX, DOUBLE gravityY)
+```
+
+Sets the global gravity vector. A value of `(0, 0)` disables gravity.
+
+**Parameters**
+
+- `gravityX`, `gravityY` — gravity components.
+
+**Examples**
+
+```
+EXTWORLD^SETGRAVITY(0,0);
+```
+
+### SETLINEARDAMPING
+
+```
+void SETLINEARDAMPING(INTEGER objectId, INTEGER linearDamping)
+```
+
+Sets linear damping (gradual reduction of linear velocity) for a body.
+
+**Parameters**
+
+- `objectId` — body identifier.
+- `linearDamping` — damping value.
+
+**Examples**
+
+```
+EXTWORLD^SETLINEARDAMPING(1,300);
+```
+
+### SETMATERIAL
+
+```
+void SETMATERIAL(INTEGER objectId, STRING material)
+```
+
+Sets the body's material. Materials control how bodies respond to contact (rigidity, elasticity, friction). One name encountered in shipping scripts is `"TRIGGER"`, for which the engine fires the `ONSIGNAL^TRIGGER` signal on the linked animation.
+
+**Parameters**
+
+- `objectId` — body identifier.
+- `material` — material name.
+
+**Examples**
+
+```
+EXTWORLD^SETMATERIAL(IOBIEKT,"TRIGGER");
+```
+
+### SETPOSITION
+
+```
+void SETPOSITION(INTEGER objectId, INTEGER posX, INTEGER posY)
+```
+
+Sets the body's absolute position in the physics world.
+
+**Parameters**
+
+- `objectId` — body identifier.
+- `posX`, `posY` — new position.
+
+**Examples**
+
+```
+EXTWORLD^SETPOSITION(IOBIEKT,[ANNSZCZUREK^GETCENTERX()+70],[ANNSZCZUREK^GETCENTERY()-1]);
+EXTWORLD^SETPOSITION(IRAKIETAOBJ,ANNDODATKI_7^GETPOSITIONX(),ANNDODATKI_7^GETPOSITIONY());
+```
+
+### SETVELOCITY
+
+```
+void SETVELOCITY(INTEGER objectId, INTEGER speedX, INTEGER speedY)
+```
+
+Sets a body's velocity along the X and Y axes.
+
+**Parameters**
+
+- `objectId` — body identifier.
+- `speedX`, `speedY` — velocity components.
+
+**Examples**
+
+```
+EXTWORLD^SETVELOCITY(1,0,0);
+EXTWORLD^SETVELOCITY(IOBIEKT,8,0);
+```
+
+### TICK
+
+```
+void TICK()
+```
+
+Advances the simulation by one step. Without `TICK` the physics world stays frozen — typically called from a [`TIMER`](TIMER.md)'s [`ONTICK`](TIMER.md#ontick) signal.
+
+**Examples**
+
+```
+EXTWORLD^TICK();
+```
+
+### UNLINK
+
+```
+void UNLINK(INTEGER objectId)
+```
+
+Breaks an animation binding established with [`LINK`](#link).
+
+**Parameters**
+
+- `objectId` — body identifier.
+
+**Examples**
+
+```
+EXTWORLD^UNLINK(IID);
+EXTWORLD^UNLINK(1);
+```
+
+## Signals
+
+### ONINIT
+
+Fired when the object is initialised.
+
+### ONSIGNAL
+
+Fired when a signal arrives (see [Events and signals](../engine/events.md#onsignal)).
--- a/docs/en/reference/MATRIX.md
+++ b/docs/en/reference/MATRIX.md
@@ -0,0 +1,438 @@
+# MATRIX
+
+A rectangular grid of cells with a small built-in stone-falling physics system and primitive enemy pathfinding. Designed around a single use case — the digging minigame (Kretes sections in *Reksio i Ufo*: the wall on Indor and the prison-tunnel on Kuran).
+
+Grid data lives in a one-dimensional array of integers — a cell's address is computed as `index = y * width + x`. Hence the family of methods that converts between linear index and 2D position.
+
+## Field codes
+
+Values used by [`GET`](#get), [`GETCELLSNO`](#getcellsno), [`SET`](#set), [`SETROW`](#setrow) and the internal physics system:
+
+| Code | Meaning |
+| --- | --- |
+| `0` | empty cell |
+| `1` | ground |
+| `2` | stone |
+| `3` | dynamite stick |
+| `4` | weak (destructible) wall |
+| `5` | enemy |
+| `6` | strong (indestructible) wall |
+| `7` | lit dynamite stick |
+| `8` | cell within blast radius |
+| `9` | exit |
+| `99` | Kretes' position |
+
+## Movement direction codes
+
+Values used by [`TICK`](#tick), [`NEXT`](#next), and [`CALCENEMYMOVEDIR`](#calcenemymovedir):
+
+| Code | Direction |
+| --- | --- |
+| `0` | left |
+| `1` | up |
+| `2` | right |
+| `3` | down |
+
+The physics system uses additional codes returned by [`TICK`](#tick) and consumed by [`NEXT`](#next):
+
+| Code | Operation |
+| --- | --- |
+| `1` | stone falls down |
+| `2` | stone slides diagonally to the left |
+| `3` | stone slides diagonally to the right |
+| `4` | stone collides with an enemy and explodes |
+
+## Fields
+
+### BASEPOS
+
+```
+INTEGER, INTEGER BASEPOS
+```
+
+Pixel position of the grid's top-left corner on screen (`X,Y`).
+
+### CELLHEIGHT
+
+```
+INTEGER CELLHEIGHT
+```
+
+Height of a single cell in pixels.
+
+### CELLWIDTH
+
+```
+INTEGER CELLWIDTH
+```
+
+Width of a single cell in pixels.
+
+### SIZE
+
+```
+INTEGER, INTEGER SIZE
+```
+
+Grid dimensions in cells (`width,height`). The value also dictates the size of the internal field-code array.
+
+## Methods
+
+### CALCENEMYMOVEDEST
+
+```
+INTEGER CALCENEMYMOVEDEST(INTEGER oldCell, INTEGER direction)
+```
+
+Computes the destination cell for an enemy moving from `oldCell` in the given `direction`. If the target cell is out of bounds or not empty, `oldCell` is returned unchanged.
+
+**Parameters**
+
+- `oldCell` — the enemy's current cell index.
+- `direction` — movement direction (`0`–`3`, see [Movement direction codes](#movement-direction-codes)).
+
+**Returns**: [`INTEGER`](INTEGER.md) — destination cell index.
+
+**Examples**
+
+```
+MAT^CALCENEMYMOVEDEST(IENOLDCELL,IENNEWDIR);
+```
+
+### CALCENEMYMOVEDIR
+
+```
+INTEGER CALCENEMYMOVEDIR(INTEGER oldCell, INTEGER oldDir)
+```
+
+Computes the next movement direction for an enemy. The algorithm prefers turning left: it first checks `(oldDir+3) MOD 4`, then `oldDir`, then right, and finally backwards. The first direction whose target cell is empty is returned; if none is available, the leftward direction is returned anyway.
+
+**Parameters**
+
+- `oldCell` — the enemy's current cell index.
+- `oldDir` — the previous-step movement direction.
+
+**Returns**: [`INTEGER`](INTEGER.md) — the new movement direction.
+
+**Examples**
+
+```
+MAT^CALCENEMYMOVEDIR(IENOLDCELL,IENOLDDIR);
+```
+
+### CANHEROGOTO
+
+```
+BOOL CANHEROGOTO(INTEGER cellNo)
+```
+
+Checks whether the protagonist can step onto the given cell. A cell is walkable if it does not contain a weak wall, strong wall, enemy or stone, and is not part of a gate area set with [`SETGATE`](#setgate).
+
+**Parameters**
+
+- `cellNo` — index of the cell to check.
+
+**Returns**: [`BOOL`](BOOL.md) — `TRUE` if the cell is walkable.
+
+**Examples**
+
+```
+MAT^CANHEROGOTO(I_0);
+```
+
+### GET
+
+```
+INTEGER GET(INTEGER cellNo)
+```
+
+Returns the field code of the cell at the given index. For out-of-range indices returns `0`.
+
+**Parameters**
+
+- `cellNo` — cell index.
+
+**Returns**: [`INTEGER`](INTEGER.md) — field code (see [Field codes](#field-codes)).
+
+**Examples**
+
+```
+MAT^GET(I_ITERATOR);
+MAT^GET(I_MOLE_FIELD_CURR);
+```
+
+### GETCELLOFFSET
+
+```
+INTEGER GETCELLOFFSET(INTEGER x, INTEGER y)
+```
+
+Returns the cell index for the given `(x, y)` grid coordinates. Returns `-1` if the coordinates fall outside the grid.
+
+**Parameters**
+
+- `x`, `y` — grid coordinates.
+
+**Returns**: [`INTEGER`](INTEGER.md) — the cell index or `-1`.
+
+**Examples**
+
+```
+MAT^GETCELLOFFSET(ISSRCX,ISSRCY);
+MAT^GETCELLOFFSET(ISTRGX,ISTRGY);
+```
+
+### GETCELLPOSX
+
+```
+INTEGER GETCELLPOSX(INTEGER cellNo)
+```
+
+Returns the cell's X position in pixels (`BASEPOS.X + col * CELLWIDTH`).
+
+**Parameters**
+
+- `cellNo` — cell index.
+
+**Returns**: [`INTEGER`](INTEGER.md) — X coordinate in pixels.
+
+### GETCELLPOSY
+
+```
+INTEGER GETCELLPOSY(INTEGER cellNo)
+```
+
+Returns the cell's Y position in pixels (`BASEPOS.Y + row * CELLHEIGHT`).
+
+**Parameters**
+
+- `cellNo` — cell index.
+
+**Returns**: [`INTEGER`](INTEGER.md) — Y coordinate in pixels.
+
+### GETCELLSNO
+
+```
+INTEGER GETCELLSNO(INTEGER cellCode)
+```
+
+Returns the number of cells with the given field code.
+
+**Parameters**
+
+- `cellCode` — the field code to count.
+
+**Returns**: [`INTEGER`](INTEGER.md) — number of matching cells.
+
+**Examples**
+
+```
+MAT^GETCELLSNO(IC_FIELD_CODE_EXIT);
+MAT^GETCELLSNO(IC_FIELD_CODE_ENEMY);
+```
+
+### GETFIELDPOSX
+
+```
+INTEGER GETFIELDPOSX(INTEGER cellNo)
+```
+
+Alias of [`GETCELLPOSX`](#getcellposx), used in *Reksio i Ufo* with the Piklib 7.1 engine. Piklib 8 no longer ships this method — calling it crashes the engine.
+
+**Parameters**
+
+- `cellNo` — cell index.
+
+**Returns**: [`INTEGER`](INTEGER.md) — X coordinate in pixels.
+
+### GETFIELDPOSY
+
+```
+INTEGER GETFIELDPOSY(INTEGER cellNo)
+```
+
+Alias of [`GETCELLPOSY`](#getcellposy), used in *Reksio i Ufo* with the Piklib 7.1 engine. Piklib 8 no longer ships this method — calling it crashes the engine.
+
+**Parameters**
+
+- `cellNo` — cell index.
+
+**Returns**: [`INTEGER`](INTEGER.md) — Y coordinate in pixels.
+
+### GETOFFSET
+
+```
+INTEGER GETOFFSET(INTEGER x, INTEGER y)
+```
+
+Alias of [`GETCELLOFFSET`](#getcelloffset), used in *Reksio i Ufo* with the Piklib 7.1 engine. Piklib 8 replaces it with `GETCELLOFFSET`.
+
+**Parameters**
+
+- `x`, `y` — grid coordinates.
+
+**Returns**: [`INTEGER`](INTEGER.md) — cell index or `-1`.
+
+### ISGATEEMPTY
+
+```
+BOOL ISGATEEMPTY()
+```
+
+Checks whether all cells in the gate area set with [`SETGATE`](#setgate) have field code `0` (empty). Returns `FALSE` if no gate has been set.
+
+**Returns**: [`BOOL`](BOOL.md) — `TRUE` if all gate cells are empty.
+
+**Examples**
+
+```
+MAT^ISGATEEMPTY();
+```
+
+### ISINGATE
+
+```
+BOOL ISINGATE(INTEGER cellNo)
+```
+
+Checks whether the cell at the given index belongs to the gate area set with [`SETGATE`](#setgate).
+
+**Parameters**
+
+- `cellNo` — cell index.
+
+**Returns**: [`BOOL`](BOOL.md) — `TRUE` if the cell is inside the gate area.
+
+### MOVE
+
+```
+void MOVE(INTEGER oldCell, INTEGER newCell)
+```
+
+Moves the contents of the source cell to the destination cell; the source cell becomes empty (code `0`).
+
+**Parameters**
+
+- `oldCell` — source cell index.
+- `newCell` — destination cell index.
+
+**Examples**
+
+```
+MAT^MOVE(I_0,I_1);
+```
+
+### NEXT
+
+```
+INTEGER NEXT()
+```
+
+Executes the next queued move generated by [`TICK`](#tick). The source cell is cleared and the destination cell receives the stone code. After the move the [`ONNEXT`](#onnext) signal is emitted for every move except the last one in the queue, which fires [`ONLATEST`](#onlatest) instead.
+
+**Returns**: [`INTEGER`](INTEGER.md) — `0` if the queue is empty; `1` for an ordinary stone move; `2` if the stone has come to rest two cells above Kretes (collision).
+
+**Examples**
+
+```
+MAT^NEXT();
+```
+
+### SET
+
+```
+void SET(INTEGER cellNo, INTEGER cellCode)
+void SET(INTEGER x, INTEGER y, INTEGER cellCode)
+```
+
+Sets a cell's field code. Two forms are accepted: the first takes a precomputed cell index, the second takes `(x, y)` coordinates.
+
+**Parameters**
+
+- `cellNo` — cell index **(form 1)**.
+- `x`, `y` — cell coordinates **(form 2)**.
+- `cellCode` — new field code (see [Field codes](#field-codes)).
+
+**Examples**
+
+```
+MAT^SET(I_MOLE_FIELD_CURR,IC_FIELD_CODE_EMPTY);
+MAT^SET([I_FIELD_INDEX%I_LEVEL_WIDTH],[I_FIELD_INDEX@I_LEVEL_WIDTH],IC_FIELD_CODE_EMPTY);
+```
+
+### SETGATE
+
+```
+void SETGATE(INTEGER startX, INTEGER startY, INTEGER endX, INTEGER endY)
+```
+
+Defines a rectangular gate area, inclusive of both corners. The gate affects [`CANHEROGOTO`](#canherogoto), [`ISGATEEMPTY`](#isgateempty), and [`ISINGATE`](#isingate).
+
+**Parameters**
+
+- `startX`, `startY` — coordinates of the gate's top-left corner.
+- `endX`, `endY` — coordinates of the gate's bottom-right corner.
+
+**Examples**
+
+```
+MAT^SETGATE(3,1,16,4);
+```
+
+### SETROW
+
+```
+void SETROW(INTEGER row, INTEGER cellCode1, [INTEGER cellCode2, ...])
+```
+
+Sets field codes for all cells in the given row, starting from column `0`. Excess arguments (beyond the grid's width) are ignored.
+
+**Parameters**
+
+- `row` — row index.
+- `cellCode1`, `cellCode2`, … — field codes for successive cells in the row.
+
+**Examples**
+
+```
+MAT^SETROW(0,6,6,6,6,6,6,6,6,6,6,6,6,6,6,6,6,6,6,6,6);
+MAT^SETROW(1,6,6,6,2,2,2,2,2,2,2,2,2,2,2,2,2,2,6,6,6);
+```
+
+### TICK
+
+```
+void TICK()
+```
+
+Executes one physics tick. The grid is scanned bottom-to-top, left-to-right. For each stone the following cases are checked in order:
+
+1. Is the cell directly below empty — schedule a downward move.
+2. Is the cell below an enemy — schedule an explosion.
+3. Are the diagonally adjacent cells (and the lateral neighbour) empty — schedule a diagonal slide.
+
+Scheduled moves are appended to an internal queue and executed one-by-one by [`NEXT`](#next). Each entry records the source cell's X and Y, plus the operation code.
+
+**Examples**
+
+```
+MAT^TICK();
+```
+
+## Signals
+
+### ONINIT
+
+Fired when the object is initialised.
+
+### ONNEXT
+
+Fired by [`NEXT`](#next) after a move that was not the last in the current queue. Signal arguments are the source cell's X (`$1`), Y (`$2`) and operation code (`$3`).
+
+### ONLATEST
+
+Fired by [`NEXT`](#next) after the last queued move. Arguments are identical to [`ONNEXT`](#onnext).
+
+### ONSIGNAL
+
+Fired when a signal arrives (see [Events and signals](../engine/events.md#onsignal)).
--- a/docs/en/reference/PATTERN.md
+++ b/docs/en/reference/PATTERN.md
@@ -0,0 +1,147 @@
+# PATTERN
+
+A board built from a grid of fixed-size tiles arranged in multiple layers. Used in flying minigames such as the dragon-rider on Smokręt (*Reksio i Wehikuł Czasu*) and the broomstick (*Reksio i Czarodzieje*) — most likely to store the scrolling level map. Analysis of this type is still ongoing.
+
+## Fields
+
+### GRIDX
+
+```
+INTEGER GRIDX
+```
+
+Width of a single tile in pixels.
+
+### GRIDY
+
+```
+INTEGER GRIDY
+```
+
+Height of a single tile in pixels.
+
+### HEIGHT
+
+```
+INTEGER HEIGHT
+```
+
+Board height.
+
+### LAYERS
+
+```
+INTEGER LAYERS
+```
+
+Number of layers.
+
+### PRIORITY
+
+```
+INTEGER PRIORITY
+```
+
+Board render priority (Z position).
+
+### TOCANVAS
+
+```
+BOOL TOCANVAS
+```
+
+Whether the board is drawn on the canvas.
+
+### VISIBLE
+
+```
+BOOL VISIBLE
+```
+
+Whether the board is visible.
+
+### WIDTH
+
+```
+INTEGER WIDTH
+```
+
+Board width.
+
+## Methods
+
+### ADD
+
+```
+void ADD(STRING tileId, INTEGER posX, INTEGER posY, STRING animoName, [INTEGER layer])
+```
+
+Places a graphic onto the board.
+
+**Parameters**
+
+- `tileId` — tile identifier.
+- `posX`, `posY` — tile coordinates.
+- `animoName` — name of the [`ANIMO`](ANIMO.md) variable to display in the tile.
+- `layer` — (optional) layer number.
+
+**Examples**
+
+```
+PATBOARD^ADD(["E"+_I_],VARX,VARY,VARSTRING0,0);
+PATTERNFOREST^ADD([VARSTRING0+"_"+_I_],VARINT1,VARINT2,VARSTRING1,VARINT3);
+```
+
+### GETGRAPHICSAT
+
+```
+STRING GETGRAPHICSAT(INTEGER posX, INTEGER posY, BOOL onlyVisible, BOOL ignoreAlpha, INTEGER minZ, [INTEGER maxZ])
+```
+
+Returns the name of the tile at the given point. Behaves analogously to [`CANVAS_OBSERVER.GETGRAPHICSAT`](CANVAS_OBSERVER.md#getgraphicsat), but limited to this board's tiles.
+
+**Parameters**
+
+- `posX`, `posY` — query point coordinates.
+- `onlyVisible` — if `TRUE`, only visible tiles are considered.
+- `ignoreAlpha` — if `TRUE`, only the tile's rectangle is tested; if `FALSE`, the pixel's alpha channel is also checked.
+- `minZ` — minimum layer.
+- `maxZ` — (optional) maximum layer.
+
+**Returns**: [`STRING`](STRING.md) — tile name or `"NULL"`.
+
+**Examples**
+
+```
+PATTERNMASKKRET^GETGRAPHICSAT([ANNKRET^GETCENTERX()+20],ANNKRET^GETCENTERY(),TRUE,FALSE,0,1);
+PATTERNFIRE^GETGRAPHICSAT(ANNCOLLUP^GETCENTERX(),ANNCOLLUP^GETCENTERY(),FALSE,FALSE,0);
+```
+
+### MOVE
+
+```
+void MOVE(INTEGER offsetX, INTEGER offsetY)
+```
+
+Moves the board by the given X/Y offsets.
+
+**Parameters**
+
+- `offsetX`, `offsetY` — translation vector.
+
+**Examples**
+
+```
+PATBOARD^MOVE(0,-3000);
+PATTERNBKG^MOVE(VARINT0,0);
+```
+
+## Signals
+
+### ONINIT
+
+Fired when the object is initialised.
+
+### ONSIGNAL
+
+Fired when a signal arrives (see [Events and signals](../engine/events.md#onsignal)).
--- a/docs/en/reference/STATICFILTER.md
+++ b/docs/en/reference/STATICFILTER.md
@@ -0,0 +1,110 @@
+# STATICFILTER
+
+A graphical filter — an effect applied to [`ANIMO`](ANIMO.md) or [`IMAGE`](IMAGE.md) variables. Each filter instance has one effect kind ([`ACTION`](#action)) and a set of properties set via [`SETPROPERTY`](#setproperty). A filter is attached to a specific graphic with [`LINK`](#link) — from then on property changes take effect in real time.
+
+A single `STATICFILTER` can be attached to multiple graphics at once.
+
+## Fields
+
+### ACTION
+
+```
+STRING ACTION
+```
+
+Filter effect type. Accepted values (per `sub_100A4490` in the Piklib8 library):
+
+| Value | Effect |
+| --- | --- |
+| `COLORCHANNEL` | RGB channel manipulation |
+| `GRAYSCALE` | convert to grayscale |
+| `BLUR` | blur |
+| `ROTATE` | rotate |
+| `SCALE` | scale |
+| `NEGATIVE` | invert colours |
+| `RANDOMJITTER` | random per-pixel jitter |
+| `WAVES` | wave distortion |
+
+## Methods
+
+### LINK
+
+```
+void LINK(STRING objectName)
+```
+
+Attaches the filter to an [`ANIMO`](ANIMO.md) or [`IMAGE`](IMAGE.md) variable. The current property values are forwarded to the freshly created effect, which then takes effect immediately.
+
+**Parameters**
+
+- `objectName` — graphics variable name.
+
+**Examples**
+
+```
+FJITTER^LINK("IMGZOOM");
+FROTATE^LINK(ARRCARS^GET(0));
+```
+
+### SETPROPERTY
+
+```
+void SETPROPERTY(STRING propertyName, mixed value)
+```
+
+Sets a filter property. Accepted names depend on the chosen [`ACTION`](#action):
+
+| Property | Type | Filters |
+| --- | --- | --- |
+| `CANUNDO` | [`BOOL`](BOOL.md) | all |
+| `CURRENTFRAME` | [`BOOL`](BOOL.md) | all |
+| `CHANNELS` | [`STRING`](STRING.md) | `COLORCHANNEL` |
+| `MAXJITTER` | [`INTEGER`](INTEGER.md) | `RANDOMJITTER` |
+| `BLUR` | [`INTEGER`](INTEGER.md) | `BLUR` |
+| `ANGLE` | [`INTEGER`](INTEGER.md) | `ROTATE` |
+| `BYCENTER` | [`BOOL`](BOOL.md) | `ROTATE`, `SCALE` |
+| `FACTORX` | [`INTEGER`](INTEGER.md) | `SCALE` |
+| `FACTORY` | [`INTEGER`](INTEGER.md) | `SCALE` |
+
+**Parameters**
+
+- `propertyName` — name of the property to set.
+- `value` — new property value.
+
+**Examples**
+
+```
+FCOLOR^SETPROPERTY("CANUNDO","TRUE");
+FCOLOR^SETPROPERTY("CHANNELS","B");
+FJITTER^SETPROPERTY("MAXJITTER",7);
+FROTATE^SETPROPERTY("ANGLE",IKONANGLE);
+```
+
+### UNLINK
+
+```
+void UNLINK(STRING objectName)
+```
+
+Detaches the filter from a graphics variable — removes the effect.
+
+**Parameters**
+
+- `objectName` — graphics variable name.
+
+**Examples**
+
+```
+FROTATE^UNLINK("ANNKON");
+FROTATE^UNLINK(ARRCARS^GET(VARPLAYER));
+```
+
+## Signals
+
+### ONINIT
+
+Fired when the object is initialised.
+
+### ONSIGNAL
+
+Fired when a signal arrives (see [Events and signals](../engine/events.md#onsignal)).
--- a/docs/en/reference/STRUCT.md
+++ b/docs/en/reference/STRUCT.md
@@ -0,0 +1,63 @@
+# STRUCT
+
+A data structure with named, typed fields. In engine scripts it is used exclusively together with [`DATABASE`](DATABASE.md) — it describes a database row's schema and stores the values of the currently pointed-to record after a call to [`SET`](#set).
+
+## Fields
+
+### FIELDS
+
+```
+STRING FIELDS
+```
+
+The struct's schema, written as a comma-separated list. Each entry has the form `NAME<TYPE>`, where `NAME` is the field name and `TYPE` is the data type. Accepted types: `STRING`, `INTEGER`, `DOUBLE`, `BOOLEAN`. Type names are case-insensitive; any unrecognised name is treated as `STRING`.
+
+## Methods
+
+### GETFIELD
+
+```
+<type> GETFIELD(INTEGER fieldIndex)
+```
+
+Returns the value of the field at the given (zero-based) index. The return type follows the schema — `<INTEGER>` fields return [`INTEGER`](INTEGER.md), `<DOUBLE>` returns [`DOUBLE`](DOUBLE.md), `<BOOLEAN>` returns [`BOOL`](BOOL.md), and everything else returns [`STRING`](STRING.md). Out-of-range indices return an empty value. If the struct has not yet been synchronised with a [`DATABASE`](DATABASE.md), every field is empty.
+
+**Parameters**
+
+- `fieldIndex` — field index (zero-based).
+
+**Returns**: the field value, typed according to the schema.
+
+**Examples**
+
+```
+STLEVEL^GETFIELD(0);
+```
+
+### SET
+
+```
+void SET(STRING cursorName)
+```
+
+Synchronises the struct with the row currently pointed to by a [`DATABASE`](DATABASE.md) cursor. Raw cursor values are converted to the types declared in the [`FIELDS`](#fields) schema.
+
+**Parameters**
+
+- `cursorName` — name of the cursor variable associated with a database.
+
+**Examples**
+
+```
+SOBJECT^SET("DBOBJECTS_CURSOR");
+```
+
+## Signals
+
+### ONINIT
+
+Fired when the object is initialised.
+
+### ONSIGNAL
+
+Fired when a signal arrives (see [Events and signals](../engine/events.md#onsignal)).
--- a/docs/en/reference/TIMER.md
+++ b/docs/en/reference/TIMER.md
@@ -0,0 +1,138 @@
+# TIMER
+
+A cyclic time counter that emits the [`ONTICK`](#ontick) signal every `ELAPSE` milliseconds. Lets scripts run logic at regular intervals — nothing involving the passage of time (animated values, delays, regeneration) can be done in the engine without one.
+
+The variable's value is the number of ticks emitted so far.
+
+## Fields
+
+### ELAPSE
+
+```
+INTEGER ELAPSE
+```
+
+Tick interval in milliseconds. For values of `0` or less the timer does not tick even when enabled.
+
+### ENABLED
+
+```
+BOOL ENABLED
+```
+
+Whether the timer is active after initialisation. Defaults to `TRUE`.
+
+### TICKS
+
+```
+INTEGER TICKS
+```
+
+Tick limit — once that many ticks have been emitted, the timer disables itself (`ENABLED = FALSE`). A value of `0` removes the limit (the timer ticks indefinitely).
+
+## Methods
+
+### DISABLE
+
+```
+void DISABLE()
+```
+
+Disables the timer. [`ONTICK`](#ontick) is no longer emitted; the current tick count is preserved.
+
+**Examples**
+
+```
+TIMER1^DISABLE();
+```
+
+### ENABLE
+
+```
+void ENABLE()
+```
+
+Enables the timer and resets the reference time to *now*. The first tick after the call fires only after a full `ELAPSE` has passed, regardless of how long the timer was disabled.
+
+**Examples**
+
+```
+TIMCNV^ENABLE();
+TIMER2^ENABLE();
+```
+
+### GETTICKS
+
+```
+INTEGER GETTICKS()
+```
+
+Returns the number of ticks emitted so far (counted from the last [`RESET`](#reset) or initialisation).
+
+**Returns**: [`INTEGER`](INTEGER.md) — the tick count.
+
+**Examples**
+
+```
+TIMER1^GETTICKS();
+```
+
+### RESET
+
+```
+void RESET()
+```
+
+Zeros the tick count and resets the reference time to *now*.
+
+**Examples**
+
+```
+TIMER1^RESET();
+```
+
+### SET
+
+```
+void SET(INTEGER ticks)
+```
+
+Sets the [`TICKS`](#ticks) limit. A value of `0` removes the limit.
+
+**Parameters**
+
+- `ticks` — the new tick limit.
+
+### SETELAPSE
+
+```
+void SETELAPSE(INTEGER timeMs)
+```
+
+Sets the tick interval in milliseconds and resets the reference time to *now*.
+
+**Parameters**
+
+- `timeMs` — the new tick interval (in milliseconds).
+
+**Examples**
+
+```
+TIMERSEQ^SETELAPSE(RANDOM^GET(30000,10000));
+TIMERPIECHUR^SETELAPSE(ARRAYPIECHURZYPARAM^GET(0));
+TIMER1^SETELAPSE(VARTIMEUFO);
+```
+
+## Signals
+
+### ONINIT
+
+Fired when the object is initialised.
+
+### ONTICK
+
+Fired after each full [`ELAPSE`](#elapse) cycle, provided the timer is enabled. The argument (`$1`) is the current tick count (`currentTickCount`).
+
+### ONSIGNAL
+
+Fired when a signal arrives (see [Events and signals](../engine/events.md#onsignal)).
--- a/docs/en/reference/VECTOR.md
+++ b/docs/en/reference/VECTOR.md
@@ -0,0 +1,160 @@
+# VECTOR
+
+An N-dimensional vector of floating-point numbers. In practice, used for two- or three-dimensional coordinates — engine games use vectors mostly in physics-flavoured minigames (reflection, movement-direction normalisation).
+
+The variable's value is the vector's Euclidean length, i.e. `sqrt(x1² + x2² + … + xN²)`.
+
+## Fields
+
+### SIZE
+
+```
+INTEGER SIZE
+```
+
+The number of vector components. Typical values in shipping games are `2` or `3`.
+
+### VALUE
+
+```
+DOUBLE, DOUBLE, [DOUBLE...] VALUE
+```
+
+Initial values of each component. The number of entries should match [`SIZE`](#size).
+
+## Methods
+
+### ADD
+
+```
+void ADD(STRING|VECTOR vectorName)
+```
+
+Adds another vector to this one component-wise. The result is stored in the vector the method was called on.
+
+**Parameters**
+
+- `vectorName` — the vector to add; either a [`STRING`](STRING.md) (variable name) or a `VECTOR`.
+
+**Examples**
+
+```
+VTEMP2^ADD("VTOCENTER");
+VTEMP2^ADD(VTOCENTER);
+```
+
+### ASSIGN
+
+```
+void ASSIGN(DOUBLE x1, DOUBLE x2, [DOUBLE...])
+```
+
+Assigns new component values. The number of arguments dictates how many components are overwritten — any beyond that retain their previous values. If more arguments are supplied than the vector has components, the vector is extended.
+
+**Parameters**
+
+- `x1, x2, …` — the new component values.
+
+**Examples**
+
+```
+VTEMP1^ASSIGN(0.0,0.0);
+VTEMP1^ASSIGN(ARRDIRX^GET(VARPLAYER),ARRDIRY^GET(VARPLAYER));
+VNORMAL^ASSIGN([ARRPOSX^GET(VARPLAYER)+ARRHWIDTH^GET(VARPLAYER)],[ARRPOSY^GET(VARPLAYER)+ARRHHEIGHT^GET(VARPLAYER)]);
+```
+
+### GET
+
+```
+DOUBLE GET(INTEGER index)
+```
+
+Returns the value of the component at the given (zero-based) index. Returns `0.0` for out-of-range indices.
+
+**Parameters**
+
+- `index` — component index, zero-based.
+
+**Returns**: [`DOUBLE`](DOUBLE.md) — the component value or `0.0`.
+
+**Examples**
+
+```
+VTEMP1^GET(0);
+VTEMP1^GET(1);
+```
+
+### LEN
+
+```
+DOUBLE LEN()
+```
+
+Returns the vector's Euclidean length.
+
+**Returns**: [`DOUBLE`](DOUBLE.md) — the vector length.
+
+### MUL
+
+```
+void MUL(DOUBLE scalar)
+```
+
+Multiplies every component by the given scalar.
+
+**Parameters**
+
+- `scalar` — the multiplier.
+
+**Examples**
+
+```
+VTEMP1^MUL(10.0);
+VTEMP1^MUL(ARRSPEED^GET(VARPLAYER));
+VTEMP2^MUL(-1);
+```
+
+### NORMALIZE
+
+```
+void NORMALIZE()
+```
+
+Normalises the vector to length `1` (divides each component by the current length). Calling this on a zero-length vector leaves the vector unchanged.
+
+**Examples**
+
+```
+VNORMAL^NORMALIZE();
+VTEMP1^NORMALIZE();
+```
+
+### REFLECT
+
+```
+void REFLECT(STRING|VECTOR normalVector, STRING|VECTOR resultVector)
+```
+
+Reflects this vector about the given normal vector and writes the result into the result vector. The original vector is unchanged.
+
+**Parameters**
+
+- `normalVector` — normal vector of the surface to reflect against.
+- `resultVector` — vector that will receive the result.
+
+**Examples**
+
+```
+VINCIDENT^REFLECT("VNORMAL","VREFLECT");
+VINCIDENT^REFLECT(VNORMAL,VREFLECT);
+```
+
+## Signals
+
+### ONINIT
+
+Fired when the object is initialised.
+
+### ONSIGNAL
+
+Fired when a signal arrives (see [Events and signals](../engine/events.md#onsignal)).
--- a/docs/en/reference/VIRTUALGRAPHICSOBJECT.md
+++ b/docs/en/reference/VIRTUALGRAPHICSOBJECT.md
@@ -0,0 +1,213 @@
+# VIRTUALGRAPHICSOBJECT
+
+A virtual graphics object — acts as a proxy or composite over another graphic referenced by the [`SOURCE`](#source) field. Lets scripts treat an existing graphical element as a separate entity with its own position, priority, mask, and collision flags.
+
+This type appears only sporadically in shipping scripts — primarily in *Reksio i Czarodzieje* (`common\classes\SinglePuzzle.class`).
+
+## Fields
+
+### ASBUTTON
+
+```
+BOOL ASBUTTON
+```
+
+Whether the object behaves as a clickable button.
+
+### MASK
+
+```
+STRING MASK
+```
+
+Name of the graphics variable used as a clipping mask during rendering.
+
+### MONITORCOLLISION
+
+```
+BOOL MONITORCOLLISION
+```
+
+Enables collision monitoring against other graphical objects.
+
+### MONITORCOLLISIONALPHA
+
+```
+BOOL MONITORCOLLISIONALPHA
+```
+
+Enables collision monitoring with alpha-channel awareness — a collision is reported only when the overlapping pixels are opaque.
+
+### PRIORITY
+
+```
+INTEGER PRIORITY
+```
+
+Render priority (Z position).
+
+### SOURCE
+
+```
+STRING SOURCE
+```
+
+Name of the graphics variable whose contents are rendered through this virtual object.
+
+### TOCANVAS
+
+```
+BOOL TOCANVAS
+```
+
+Whether the object is drawn on the canvas.
+
+### VISIBLE
+
+```
+BOOL VISIBLE
+```
+
+Whether the object is visible.
+
+## Methods
+
+### GETHEIGHT
+
+```
+INTEGER GETHEIGHT()
+```
+
+Returns the object's height in pixels.
+
+**Returns**: [`INTEGER`](INTEGER.md) — height.
+
+### GETPOSITIONX
+
+```
+INTEGER GETPOSITIONX()
+```
+
+Returns the object's X position.
+
+**Returns**: [`INTEGER`](INTEGER.md) — X coordinate.
+
+### GETPOSITIONY
+
+```
+INTEGER GETPOSITIONY()
+```
+
+Returns the object's Y position.
+
+**Returns**: [`INTEGER`](INTEGER.md) — Y coordinate.
+
+### GETWIDTH
+
+```
+INTEGER GETWIDTH()
+```
+
+Returns the object's width in pixels.
+
+**Returns**: [`INTEGER`](INTEGER.md) — width.
+
+### MOVE
+
+```
+void MOVE(INTEGER offsetX, INTEGER offsetY)
+```
+
+Moves the object by the given offsets, relative to its current position.
+
+**Parameters**
+
+- `offsetX`, `offsetY` — translation vector.
+
+**Examples**
+
+```
+VGO^MOVE($1,$2);
+```
+
+### SETMASK
+
+```
+void SETMASK(STRING maskName)
+```
+
+Sets the clipping mask — equivalent to the [`MASK`](#mask) field.
+
+**Parameters**
+
+- `maskName` — name of the graphics variable used as the mask.
+
+**Examples**
+
+```
+VGO^SETMASK(MSK);
+```
+
+### SETPOSITION
+
+```
+void SETPOSITION(INTEGER posX, INTEGER posY)
+```
+
+Sets the object's absolute position.
+
+**Parameters**
+
+- `posX`, `posY` — new position.
+
+**Examples**
+
+```
+VGO^SETPOSITION($1,$2);
+```
+
+### SETPRIORITY
+
+```
+void SETPRIORITY(INTEGER priority)
+```
+
+Sets the render priority (Z position) — equivalent to the [`PRIORITY`](#priority) field.
+
+**Parameters**
+
+- `priority` — new priority value.
+
+**Examples**
+
+```
+VGO^SETPRIORITY(1000);
+```
+
+### SETSOURCE
+
+```
+void SETSOURCE(STRING sourceName)
+```
+
+Sets the graphics variable referenced by [`SOURCE`](#source).
+
+**Parameters**
+
+- `sourceName` — graphics variable name.
+
+**Examples**
+
+```
+VGO^SETSOURCE($2);
+```
+
+## Signals
+
+### ONINIT
+
+Fired when the object is initialised.
+
+### ONSIGNAL
+
+Fired when a signal arrives (see [Events and signals](../engine/events.md#onsignal)).
--- a/docs/en/reference/WORLD.md
+++ b/docs/en/reference/WORLD.md
@@ -0,0 +1,549 @@
+# WORLD
+
+Interface to the 3D physics engine built on the Sekai library — a thin wrapper around Open Dynamics Engine (ODE). The world manages rigid bodies, joints, and navigation paths, and applies forces, gravity, and damping. The 3D counterpart used in Piklib-era games. Conceptually equivalent to [`INERTIA`](INERTIA.md), but with access to the third axis and a substantially wider API.
+
+Each body in the world is identified by an integer (`objectId`). The world is loaded from a `.SEK` file holding the body definitions, physical parameters, collision meshes, the per-scene list of navigation points, and their connections.
+
+## Geometry types
+
+Values accepted by the `geomType` argument of [`ADDBODY`](#addbody):
+
+| Value | Geometry |
+| --- | --- |
+| `0` | box |
+| `1` | cylinder |
+| `2` | sphere |
+| `3` | trimesh (only used while loading from `.SEK`) |
+| `4` | car (four wheels + box) |
+
+## Fields
+
+### FILENAME
+
+```
+STRING FILENAME
+```
+
+Path to the `.SEK` file with the physics-world definition.
+
+## Methods
+
+### ADDBODY
+
+```
+void ADDBODY(INTEGER objectId, DOUBLE mass, DOUBLE mu, DOUBLE mu2,
+             DOUBLE bounce, DOUBLE bounceVelocity, DOUBLE maxVelocity,
+             INTEGER bodyType, INTEGER geomType,
+             DOUBLE dim1, DOUBLE dim2, DOUBLE dim3)
+```
+
+Creates a new physics body in the world. `mass`, `mu`, `mu2`, `bounce`, and `bounceVelocity` map directly onto their ODE counterparts: mass, friction, secondary-direction friction, bounciness, and minimum velocity required for a bounce. `maxVelocity` caps the body's speed.
+
+The dimensions `dim1`, `dim2`, `dim3` depend on `geomType`:
+
+- **box** — X, Y, Z lengths.
+- **cylinder** — `dim1` is the radius, `dim2` is the height; `dim3` is ignored.
+- **sphere** — `dim1` is the radius; `dim2` and `dim3` are ignored.
+
+**Parameters**
+
+- `objectId` — identifier of the new body.
+- `mass` — body mass.
+- `mu`, `mu2` — friction coefficients.
+- `bounce` — bounciness factor.
+- `bounceVelocity` — minimum velocity required for a bounce.
+- `maxVelocity` — speed cap.
+- `bodyType` — body type (ODE-reserved meaning).
+- `geomType` — geometry type (see [Geometry types](#geometry-types)).
+- `dim1`, `dim2`, `dim3` — dimensions interpreted per geometry.
+
+**Examples**
+
+```
+WORLD^ADDBODY(100,10,0.0,10000.0,0.0,0.0,40000,1,2,30,16,16);
+WORLD^ADDBODY(VARINT0,0.1,0.5,0.5,0.0,0.0,100000,1,2,16,16,16);
+```
+
+### ADDFORCE
+
+```
+void ADDFORCE(INTEGER objectId, DOUBLE forceX, DOUBLE forceY, [DOUBLE forceZ])
+```
+
+Applies a force to the body along three axes. Omitting `forceZ` is equivalent to passing `0.0`.
+
+**Parameters**
+
+- `objectId` — body identifier.
+- `forceX`, `forceY`, `forceZ` — force components.
+
+**Examples**
+
+```
+WORLD^ADDFORCE(100,VARFORCEX,VARFORCEY,0);
+WTEST^ADDFORCE(501,0,VARD_TMP1,0);
+```
+
+### ADDGRAVITYEX
+
+```
+void ADDGRAVITYEX(INTEGER objectId, INTEGER secondObjectId, BOOL gravityEx)
+```
+
+Adds an extended gravity interaction between two bodies. The exact behaviour has not been established.
+
+**Examples**
+
+```
+WTEST^ADDGRAVITYEX(VARI_ID,_I_,TRUE);
+```
+
+### FINDPATH
+
+```
+void FINDPATH(INTEGER objectId, INTEGER pointObjectId,
+              INTEGER targetX, INTEGER targetY, INTEGER targetZ,
+              BOOL saveIntermediates, [BOOL flag])
+```
+
+Computes a path for an object from its current position to a target point using the navigation graph loaded from the `.SEK` file. The result is cached by the physics engine and used by subsequent [`FOLLOWPATH`](#followpath) calls.
+
+**Parameters**
+
+- `objectId` — identifier of the body to navigate.
+- `pointObjectId` — identifier of the navigation anchor point.
+- `targetX`, `targetY`, `targetZ` — target coordinates.
+- `saveIntermediates` — if `TRUE`, intermediate path points are kept.
+- `flag` — (optional) configuration flag (meaning unknown).
+
+**Examples**
+
+```
+WPATH^FINDPATH(100,VARIPATHID,$3,$4,0,TRUE,FALSE);
+WPATH^FINDPATH(101,VARIPATHID,VARIKRETGOX,VARIKRETGOY,0,FALSE);
+```
+
+### FOLLOWPATH
+
+```
+DOUBLE FOLLOWPATH(INTEGER objectId, INTEGER arrivalRadius, DOUBLE turnClamp, DOUBLE speed)
+```
+
+Advances the body along the path previously computed by [`FINDPATH`](#findpath). Returns the remaining distance to the goal.
+
+**Parameters**
+
+- `objectId` — body identifier.
+- `arrivalRadius` — radius within which the body is considered to have arrived.
+- `turnClamp` — per-step turn limit.
+- `speed` — movement speed.
+
+**Returns**: [`DOUBLE`](DOUBLE.md) — remaining distance.
+
+**Examples**
+
+```
+WPATH^FOLLOWPATH(100,20,0.5,VARDMAXVEL);
+WPATH^FOLLOWPATH(101,20,0.5,VARD_KRETSPEED);
+```
+
+### GETANGLE
+
+```
+DOUBLE GETANGLE(INTEGER objectId)
+```
+
+Returns the angle derived from the body's velocity vector (in degrees).
+
+**Parameters**
+
+- `objectId` — body identifier.
+
+**Returns**: [`DOUBLE`](DOUBLE.md) — angle in degrees.
+
+### GETBKGPOSX
+
+```
+INTEGER GETBKGPOSX()
+```
+
+Returns the X position of the background associated with the physics world.
+
+### GETBKGPOSY
+
+```
+INTEGER GETBKGPOSY()
+```
+
+Returns the Y position of the background associated with the physics world.
+
+### GETMOVEDISTANCE
+
+```
+DOUBLE GETMOVEDISTANCE(INTEGER objectId)
+```
+
+Returns the distance the body has covered since the measurement was last reset.
+
+**Parameters**
+
+- `objectId` — body identifier.
+
+### GETPOSITIONX
+
+```
+INTEGER GETPOSITIONX(INTEGER objectId)
+```
+
+Returns the body's X position in screen-space (offset by `+400` from the physics origin).
+
+### GETPOSITIONY
+
+```
+INTEGER GETPOSITIONY(INTEGER objectId)
+```
+
+Returns the body's Y position in screen-space (axis flipped — `300 - Y`).
+
+### GETPOSITIONZ
+
+```
+INTEGER GETPOSITIONZ(INTEGER objectId)
+```
+
+Returns the body's Z position.
+
+### GETROTATIONZ
+
+```
+DOUBLE GETROTATIONZ(INTEGER objectId)
+```
+
+Returns the body's rotation around the Z axis (in degrees).
+
+### GETSPEED
+
+```
+DOUBLE GETSPEED(INTEGER objectId)
+```
+
+Returns the body's speed (linear velocity magnitude).
+
+### JOIN
+
+```
+void JOIN(INTEGER firstId, INTEGER secondId,
+          DOUBLE anchorX, DOUBLE anchorY, DOUBLE anchorZ,
+          DOUBLE limitMotor, DOUBLE lowStop, DOUBLE highStop,
+          [DOUBLE hingeAxisX, DOUBLE hingeAxisY, DOUBLE hingeAxisZ])
+```
+
+Creates a hinge joint between two bodies. The optional axis arguments specify the rotation axis — defaults to `(0, 0, 1)`.
+
+**Parameters**
+
+- `firstId`, `secondId` — body identifiers to join.
+- `anchorX`, `anchorY`, `anchorZ` — joint anchor point.
+- `limitMotor` — force required to break the joint.
+- `lowStop`, `highStop` — rotation limits.
+- `hingeAxisX`, `hingeAxisY`, `hingeAxisZ` — (optional) rotation axis.
+
+**Examples**
+
+```
+WORLD^JOIN(199,200,400,300,0,0,-180,180);
+WTEST^JOIN(VARI_ID,VARI_TMP1,VARI_X,VARI_TMP2,0,0,-180,180,0,1,0);
+```
+
+### LINK
+
+```
+void LINK(INTEGER objectId, STRING objectName)
+```
+
+Binds a physics body to an [`ANIMO`](ANIMO.md) or [`IMAGE`](IMAGE.md) variable — the graphic's position is updated from the body's physics state.
+
+**Parameters**
+
+- `objectId` — body identifier.
+- `objectName` — graphics variable name.
+
+**Examples**
+
+```
+WPATH^LINK(100,"ANNREX");
+WORLD^LINK(VARINT0,VARSTRING0);
+```
+
+### LOAD
+
+```
+void LOAD(STRING filename)
+```
+
+Resets the physics engine and loads the world from a `.SEK` file.
+
+**Parameters**
+
+- `filename` — path to the `.SEK` file.
+
+**Examples**
+
+```
+WPATH^LOAD(SOBJECT|NAME);
+```
+
+### MOVEOBJECTS
+
+```
+DOUBLE MOVEOBJECTS()
+```
+
+Steps the simulation forward by one frame and moves every body according to the physics. Returns the simulated time that elapsed during this step.
+
+**Returns**: [`DOUBLE`](DOUBLE.md) — simulation step duration.
+
+**Examples**
+
+```
+WORLD^MOVEOBJECTS();
+```
+
+### REMOVEOBJECT
+
+```
+void REMOVEOBJECT(INTEGER objectId)
+```
+
+Removes a body from the physics engine.
+
+**Examples**
+
+```
+WTEST^REMOVEOBJECT(60);
+```
+
+### SETACTIVE
+
+```
+void SETACTIVE(INTEGER objectId, BOOL active, BOOL collidable)
+```
+
+Sets a body's activity state.
+
+**Parameters**
+
+- `objectId` — body identifier.
+- `active` — whether the body participates in the simulation.
+- `collidable` — whether the body participates in collision detection.
+
+**Examples**
+
+```
+WPATH^SETACTIVE(VARI_3DPATHID,$1,$2);
+```
+
+### SETBKGSIZE
+
+```
+void SETBKGSIZE(INTEGER leftX, INTEGER rightX, INTEGER topY, INTEGER bottomY)
+```
+
+Sets the size of the background rectangle associated with the world.
+
+### SETG
+
+```
+void SETG(INTEGER objectId, DOUBLE g)
+```
+
+Sets a per-body gravitational constant (used to model magnets). Defaults to `0`, i.e. no attraction.
+
+**Parameters**
+
+- `objectId` — body identifier.
+- `g` — gravitational constant.
+
+**Examples**
+
+```
+WTEST^SETG(VARI_ID,VARD_MAGNESREACT);
+WTEST^SETG(501,-7000000);
+```
+
+### SETGRAVITY
+
+```
+void SETGRAVITY(DOUBLE gravityX, DOUBLE gravityY, DOUBLE gravityZ)
+```
+
+Sets the world's global gravity vector.
+
+**Parameters**
+
+- `gravityX`, `gravityY`, `gravityZ` — gravity components.
+
+**Examples**
+
+```
+WORLD^SETGRAVITY(0,0,-1000);
+WORLD^SETGRAVITY(0,-15,0);
+```
+
+### SETGRAVITYCENTER
+
+```
+void SETGRAVITYCENTER(INTEGER objectId, BOOL gravityCenter)
+```
+
+Toggles whether a body is treated as the source of a central gravitational field.
+
+**Parameters**
+
+- `objectId` — body identifier.
+- `gravityCenter` — toggle flag.
+
+### SETLIMIT
+
+```
+void SETLIMIT(INTEGER objectId, INTEGER minX, INTEGER minY, INTEGER minZ,
+              INTEGER maxX, INTEGER maxY, INTEGER maxZ)
+```
+
+Limits the body's position to a box-shaped region.
+
+**Parameters**
+
+- `objectId` — body identifier.
+- `minX`, `minY`, `minZ` — lower bounds.
+- `maxX`, `maxY`, `maxZ` — upper bounds.
+
+**Examples**
+
+```
+WORLD^SETLIMIT(100,0,0,0,800,600,999999);
+```
+
+### SETMAXSPEED
+
+```
+void SETMAXSPEED(INTEGER objectId, INTEGER maxSpeed)
+```
+
+Caps the body's speed.
+
+**Examples**
+
+```
+WORLD^SETMAXSPEED(100,200);
+```
+
+### SETMOVEFLAGS
+
+```
+void SETMOVEFLAGS(BOOL moveX, BOOL moveY)
+```
+
+Enables or disables movement along the X and Y axes. Full meaning and context of use have not been established.
+
+**Examples**
+
+```
+WPATH^SETMOVEFLAGS(VARITEMP0,VARITEMP1);
+```
+
+### SETPOSITION
+
+```
+void SETPOSITION(INTEGER objectId, DOUBLE x, DOUBLE y, DOUBLE z)
+```
+
+Sets the body's absolute position (screen-space coordinates — the engine converts them to physics space).
+
+**Examples**
+
+```
+WORLD^SETPOSITION(100,150,400,0);
+WTEST^SETPOSITION(VARI_ID,VARI_X,VARI_Y,0);
+```
+
+### SETREFOBJECT
+
+```
+void SETREFOBJECT(INTEGER objectId)
+```
+
+Marks a body as the reference object — used when computing positions relative to it.
+
+**Examples**
+
+```
+WPATH^SETREFOBJECT(100);
+```
+
+### SETVELOCITY
+
+```
+void SETVELOCITY(INTEGER objectId, DOUBLE speedX, DOUBLE speedY, DOUBLE speedZ)
+```
+
+Sets the body's velocity along three axes.
+
+**Examples**
+
+```
+WORLD^SETVELOCITY(207,5000000,0,0);
+WORLD^SETVELOCITY(VARPLAYERID,0,0,0);
+```
+
+### START
+
+```
+void START()
+```
+
+Starts the simulation (enables the physics engine's timer).
+
+**Examples**
+
+```
+WORLD^START();
+```
+
+### STOP
+
+```
+void STOP()
+```
+
+Stops the simulation (disables the physics engine's timer). Body state is preserved.
+
+**Examples**
+
+```
+WORLD^STOP();
+```
+
+### UNLINK
+
+```
+void UNLINK(INTEGER objectId)
+```
+
+Breaks the animation binding established by [`LINK`](#link).
+
+**Examples**
+
+```
+WTEST^UNLINK(VARI_TMP2);
+```
+
+## Signals
+
+### ONINIT
+
+Fired when the object is initialised.
+
+### ONSIGNAL
+
+Fired when a signal arrives (see [Events and signals](../engine/events.md#onsignal)).
--- a/docs/en/reference/index.md
+++ b/docs/en/reference/index.md
@@ -1,6 +1,6 @@
 # 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.
+List of data types available in scripts for the Piklib/BlooMoo engine, grouped by topic.

 ## Types used in scripts

@@ -32,6 +32,24 @@ List of data types available in scripts for the Piklib/BlooMoo engine. The list
 - [EPISODE](EPISODE.md) — logical segment of the game.
 - [SCENE](SCENE.md) — a single scene.

+### Interaction and composition
+
+- [BUTTON](BUTTON.md) — interactive button with three visual states.
+- [CANVAS_OBSERVER](CANVAS_OBSERVER.md) — canvas and background operations.
+- [CNVLOADER](CNVLOADER.md) — dynamic `.CNV` file loading.
+- [GROUP](GROUP.md) — variable group with delegated method calls.
+- [PATTERN](PATTERN.md) — multi-layer tile board.
+- [STATICFILTER](STATICFILTER.md) — graphical filter (rotate, scale, blur).
+- [VIRTUALGRAPHICSOBJECT](VIRTUALGRAPHICSOBJECT.md) — virtual graphics proxy object.
+
+### Data
+
+- [DATABASE](DATABASE.md) — tabular database with cursor.
+
+### 3D physics
+
+- [WORLD](WORLD.md) — interface to the ODE-based 3D physics engine.
+
 ### Built-in I/O objects

 - [KEYBOARD](KEYBOARD.md) — keyboard state.
@@ -48,8 +66,11 @@ List of data types available in scripts for the Piklib/BlooMoo engine. The list
 - [SOUND](SOUND.md) — short sound effect.
 - [TEXT](TEXT.md) — on-screen text element.

-## Remaining types
+### Math and utility

-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.
+- [EXPRESSION](EXPRESSION.md) — two-operand arithmetic expression.
+- [INERTIA](INERTIA.md) — interface to the built-in 2D physics engine.
+- [MATRIX](MATRIX.md) — grid of cells with a stone-falling physics system.
+- [STRUCT](STRUCT.md) — data structure with named fields.
+- [TIMER](TIMER.md) — cyclic time counter.
+- [VECTOR](VECTOR.md) — N-dimensional vector of floating-point numbers.