Finished automatically generated docs

Time to correct it by itself

.github/workflows/docs.yaml

@@ -1,63 +0,0 @@
-name: docs
-
-on:
-  push:
-    branches:
-      - main
-    paths:
-      - "docs/**"
-      - "mkdocs.yml"
-      - ".github/workflows/docs.yaml"
-  pull_request:
-    paths:
-      - "docs/**"
-      - "mkdocs.yml"
-      - ".github/workflows/docs.yaml"
-  workflow_dispatch:
-
-permissions:
-  contents: read
-  pages: write
-  id-token: write
-
-concurrency:
-  group: pages
-  cancel-in-progress: false
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - uses: actions/setup-python@v5
-        with:
-          python-version: "3.12"
-          cache: pip
-          cache-dependency-path: docs/requirements.txt
-
-      - name: Install MkDocs and plugins
-        run: pip install -r docs/requirements.txt
-
-      - name: Build site
-        run: mkdocs build
-
-      - name: Upload Pages artifact
-        if: github.event_name != 'pull_request'
-        uses: actions/upload-pages-artifact@v3
-        with:
-          path: site
-
-  deploy:
-    if: github.event_name != 'pull_request'
-    needs: build
-    runs-on: ubuntu-latest
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-    steps:
-      - name: Deploy to GitHub Pages
-        id: deployment
-        uses: actions/deploy-pages@v4

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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:
+- [EXPRESSION](EXPRESSION.md) — two-operand arithmetic expression.
-
+- [INERTIA](INERTIA.md) — interface to the built-in 2D physics engine.
-BUTTON, CANVAS_OBSERVER, CNVLOADER, DATABASE, EXPRESSION, GROUP, INERTIA, MATRIX, PATTERN, STATICFILTER, STRUCT, TIMER, VECTOR, VIRTUALGRAPHICSOBJECT, WORLD.
+- [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.

docs/pl/reference/BUTTON.md

@@ -0,0 +1,249 @@
+# BUTTON
+
+Interaktywny przycisk z trzema stanami wizualnymi (normalny, najechany, wciśnięty) oraz osobnymi grafikami i dźwiękami dla każdego z nich. Przycisk można dodatkowo wyłączyć — albo całkowicie (`DISABLE`), albo z zachowaniem widoczności (`DISABLEBUTVISIBLE`).
+
+Wewnętrznie przycisk jest maszyną stanów. Każde przejście stanu automatycznie pokazuje lub ukrywa odpowiednie grafiki, odtwarza powiązany dźwięk oraz może wyemitować sygnał.
+
+## Stany przycisku
+
+| Stan | Znaczenie |
+| --- | --- |
+| `STANDARD` | spoczynek — pokazywana jest grafika z `GFXSTANDARD`. |
+| `HOVERED` | kursor jest nad obszarem przycisku — pokazywana jest grafika z `GFXONMOVE` (jeśli ustawiona, w przeciwnym razie nadal `GFXSTANDARD`). |
+| `PRESSED` | przycisk jest aktualnie wciśnięty — pokazywana jest grafika z `GFXONCLICK` (jeśli ustawiona, w przeciwnym razie nadal `GFXSTANDARD`). |
+| `DISABLED` | przycisk wyłączony i ukryty. |
+| `DISABLED_BUT_VISIBLE` | przycisk wyłączony, ale pokazywana jest grafika z `GFXSTANDARD`. |
+
+## Pola
+
+### DRAGGABLE
+
+```
+BOOL DRAGGABLE
+```
+
+Określa, czy przycisk można przeciągać.
+
+### ENABLE
+
+```
+BOOL ENABLE
+```
+
+Określa, czy przycisk ma być włączony po inicjalizacji. Wartość `FALSE` umieszcza przycisk w stanie [`DISABLED`](#stany-przycisku).
+
+### GFXONCLICK
+
+```
+STRING GFXONCLICK
+```
+
+Nazwa zmiennej [`ANIMO`](ANIMO.md) lub [`IMAGE`](IMAGE.md) pokazywanej w stanie [`PRESSED`](#stany-przycisku). Pole opcjonalne — jeżeli nie zostanie ustawione, w stanie `PRESSED` nadal wyświetlana jest grafika z [`GFXSTANDARD`](#gfxstandard).
+
+### GFXONMOVE
+
+```
+STRING GFXONMOVE
+```
+
+Nazwa zmiennej [`ANIMO`](ANIMO.md) lub [`IMAGE`](IMAGE.md) pokazywanej w stanie [`HOVERED`](#stany-przycisku). Pole opcjonalne.
+
+### GFXSTANDARD
+
+```
+STRING GFXSTANDARD
+```
+
+Nazwa zmiennej [`ANIMO`](ANIMO.md) lub [`IMAGE`](IMAGE.md) wyświetlanej w stanie spoczynku. Jeżeli pole [`ENABLE`](#enable) zostało ustawione na `FALSE`, grafika jest automatycznie ukrywana po inicjalizacji — z jednym wyjątkiem: jeżeli powiązana animacja jest właśnie w trakcie odtwarzania, pozostaje widoczna (przykład: pochodnia w `16BLAWA` w *Reksio i Skarb Piratów*). W takim przypadku ustawienie [`TOCANVAS`](ANIMO.md#tocanvas) na powiązanej grafice nie ma znaczenia.
+
+### RECT
+
+```
+INTEGER, INTEGER, INTEGER, INTEGER RECT
+STRING RECT
+```
+
+Obszar reagujący na kursor. Pole może być podane na dwa sposoby:
+
+- Cztery liczby całkowite `xLeft,yBottom,xRight,yTop` definiujące prostokąt na ekranie.
+- Nazwa zmiennej typu [`ANIMO`](ANIMO.md) lub [`IMAGE`](IMAGE.md), z której pobierany jest bieżący prostokąt graficzny.
+
+Jeżeli pole nie zostanie ustawione, używany jest prostokąt zmiennej wskazanej przez [`GFXSTANDARD`](#gfxstandard).
+
+### SNDONCLICK
+
+```
+STRING SNDONCLICK
+```
+
+Nazwa zmiennej [`SOUND`](SOUND.md) odtwarzanej przy przejściu w stan [`PRESSED`](#stany-przycisku).
+
+### SNDONMOVE
+
+```
+STRING SNDONMOVE
+```
+
+Nazwa zmiennej [`SOUND`](SOUND.md) odtwarzanej przy przejściu w stan [`HOVERED`](#stany-przycisku).
+
+### SNDSTANDARD
+
+```
+STRING SNDSTANDARD
+```
+
+Nazwa zmiennej [`SOUND`](SOUND.md) odtwarzanej przy powrocie do stanu [`STANDARD`](#stany-przycisku).
+
+### VISIBLE
+
+```
+BOOL VISIBLE
+```
+
+Pole zapisywane w danych skryptowych, ale nieobserwowane przez silnik — z testów wynika, że jego wartość nie wpływa na żadne zachowanie przycisku.
+
+## Metody
+
+### DISABLE
+
+```
+void DISABLE()
+```
+
+Wyłącza przycisk i ukrywa powiązane z nim grafiki ustawione przez [`GFXSTANDARD`](#gfxstandard), [`GFXONMOVE`](#gfxonmove) i [`GFXONCLICK`](#gfxonclick). Grafiki podpięte przez [`RECT`](#rect) pozostają bez zmian.
+
+**Przykłady**
+
+```
+B_GLOBAL_PAUSE^DISABLE();
+```
+
+### DISABLEBUTVISIBLE
+
+```
+void DISABLEBUTVISIBLE()
+```
+
+Wyłącza przycisk, ale pozostawia widoczną grafikę z [`GFXSTANDARD`](#gfxstandard) (analogicznie do `DISABLE`, ale stan końcowy to [`DISABLED_BUT_VISIBLE`](#stany-przycisku)).
+
+**Przykłady**
+
+```
+BTNBONE^DISABLEBUTVISIBLE();
+BTNFORGOT^DISABLEBUTVISIBLE();
+```
+
+### ENABLE
+
+```
+void ENABLE()
+```
+
+Włącza przycisk i przywraca widoczność grafice z [`GFXSTANDARD`](#gfxstandard). Wywołanie na już włączonym przycisku nie ma efektu.
+
+**Przykłady**
+
+```
+B_GLOBAL_PAUSE^ENABLE();
+BTNEXIT^ENABLE();
+```
+
+### SETPRIORITY
+
+```
+void SETPRIORITY(INTEGER posZ)
+```
+
+Ustawia priorytet rysowania (pozycję w osi Z) dla wszystkich trzech grafik powiązanych z przyciskiem ([`GFXSTANDARD`](#gfxstandard), [`GFXONMOVE`](#gfxonmove), [`GFXONCLICK`](#gfxonclick)). Wyższa wartość oznacza rysowanie później (z wierzchu).
+
+**Parametry**
+
+- `posZ` — nowa wartość priorytetu.
+
+**Przykłady**
+
+```
+B_GLOBAL_PAUSE^SETPRIORITY(5001);
+BTNNULLFADE^SETPRIORITY(40000);
+```
+
+### SETRECT
+
+```
+void SETRECT(STRING varName)
+void SETRECT(INTEGER xLeft, INTEGER yBottom, INTEGER xRight, INTEGER yTop)
+```
+
+Ustawia obszar reagujący na kursor. Metoda ma dwie formy: pierwsza pobiera prostokąt z zadanej zmiennej [`ANIMO`](ANIMO.md) lub [`IMAGE`](IMAGE.md), druga definiuje go bezpośrednio przez koordynaty.
+
+**Parametry**
+
+- `varName` — nazwa zmiennej graficznej **(forma 1)**.
+- `xLeft`, `yBottom`, `xRight`, `yTop` — koordynaty prostokąta **(forma 2)**.
+
+**Przykłady**
+
+```
+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)
+```
+
+Ustawia grafikę standardową przycisku (pole [`GFXSTANDARD`](#gfxstandard)) i zeruje priorytet nowej grafiki. W skryptach gier występuje również forma dwuargumentowa z dodatkową flagą boolowską — zawsze wywoływana z wartością `FALSE`, znaczenie tego argumentu nie zostało ustalone.
+
+**Parametry**
+
+- `varName` — nazwa nowej zmiennej standardowej (pusty ciąg `""` czyści powiązanie).
+- `flag` — flaga konfiguracyjna **(forma 2, znaczenie nieustalone)**.
+
+**Przykłady**
+
+```
+BTNEXIT^SETSTD("ANNOBJECT2");
+B_GLOBAL_PAUSE^SETSTD("",FALSE);
+BTNBAD^SETSTD("ZLY",FALSE);
+```
+
+## Sygnały
+
+### ONINIT
+
+Wywoływany w momencie inicjalizacji obiektu.
+
+### ONFOCUSON
+
+Wywoływany przy przejściu ze stanu [`STANDARD`](#stany-przycisku) do [`HOVERED`](#stany-przycisku) — czyli gdy kursor wjedzie na przycisk.
+
+### ONFOCUSOFF
+
+Wywoływany przy przejściu z [`HOVERED`](#stany-przycisku) do [`STANDARD`](#stany-przycisku) — gdy kursor opuści przycisk.
+
+### ONCLICKED
+
+Wywoływany przy przejściu w stan [`PRESSED`](#stany-przycisku) (wciśnięcie przycisku myszy).
+
+### ONRELEASED
+
+Wywoływany przy przejściu z [`PRESSED`](#stany-przycisku) do [`HOVERED`](#stany-przycisku) — gdy przycisk myszy zostanie zwolniony nad obszarem przycisku.
+
+### ONACTION
+
+Wywoływany razem z [`ONRELEASED`](#onreleased) — sygnał potwierdzający, że nastąpiło kliknięcie (wciśnięcie i zwolnienie nad obszarem przycisku).
+
+### ONSTARTDRAGGING
+
+Wywoływany po rozpoczęciu przeciągania przycisku (dostępne tylko dla przycisków z polem [`DRAGGABLE`](#draggable) ustawionym na `TRUE`).
+
+### ONENDDRAGGING
+
+Wywoływany po zakończeniu przeciągania przycisku.
+
+### ONSIGNAL
+
+Wywoływany po otrzymaniu sygnału (zobacz [Zdarzenia i sygnały](../engine/events.md#onsignal)).

docs/pl/reference/CANVAS_OBSERVER.md

@@ -0,0 +1,243 @@
+# CANVAS_OBSERVER
+
+Punkt dostępu do operacji na kanwie — wspólnym obszarze rysowania, na którym silnik wyświetla wszystkie widoczne obiekty graficzne. Udostępnia metody do dodawania i usuwania grafik z ekranu, pobierania nazwy obiektu pod kursorem, ustawiania tła, robienia zrzutów ekranu oraz emitowania sygnałów przy zmianie fokusu okna gry.
+
+Zazwyczaj w scenie istnieje pojedyncza instancja typu `CANVAS_OBSERVER`, do której wszystkie skrypty odwołują się jak do obiektu globalnego.
+
+## Metody
+
+### ADD
+
+```
+void ADD(STRING varName)
+void ADD(STRING varName, INTEGER priority)
+```
+
+Dodaje na kanwę zmienną [`ANIMO`](ANIMO.md) lub [`IMAGE`](IMAGE.md) — ustawia jej widoczność na `TRUE` i opcjonalnie nadaje priorytet rysowania (domyślnie `1000`).
+
+**Parametry**
+
+- `varName` — nazwa zmiennej graficznej.
+- `priority` — (opcjonalnie) priorytet rysowania (pozycja w osi Z).
+
+**Przykłady**
+
+```
+CANVASOBSERVER^ADD("ANNMKORBA2");
+CANVASOBSERVER^ADD("ANNMPRZEGRYZA");
+```
+
+### ENABLENOTIFY
+
+```
+void ENABLENOTIFY(BOOL enable)
+```
+
+Włącza lub wyłącza emitowanie sygnałów o zmianie fokusu okna gry ([`ONWINDOWFOCUSON`](#onwindowfocuson), [`ONWINDOWFOCUSOFF`](#onwindowfocusoff)).
+
+**Parametry**
+
+- `enable` — `TRUE` włącza notyfikacje, `FALSE` je wyłącza.
+
+**Przykłady**
+
+```
+CANVASOBSERVER^ENABLENOTIFY(TRUE);
+```
+
+### GETBPP
+
+```
+INTEGER GETBPP()
+```
+
+Zwraca głębię koloru kanwy w bitach na piksel. Oryginalny silnik BlooMoo działa w trybie 16 bpp (RGB565) — metoda zawsze zwraca `16`.
+
+**Zwraca**: [`INTEGER`](INTEGER.md) — głębia koloru w bitach (`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)
+```
+
+Zwraca nazwę zmiennej graficznej znajdującej się pod punktem `(posX, posY)`. Przeszukuje wyłącznie bieżącą scenę. Wyszukiwanie zaczyna od grafik o najwyższym priorytecie. Jeśli żaden obiekt nie spełnia warunków, zwracane jest `"NULL"`.
+
+**Parametry**
+
+- `posX`, `posY` — koordynaty sprawdzanego punktu.
+- `onlyVisible` — gdy `TRUE`, brane są pod uwagę tylko widoczne grafiki.
+- `minZ`, `maxZ` — zakres priorytetu (osi Z) ograniczający wyszukiwanie.
+- `ignoreAlpha` — (opcjonalnie) gdy `TRUE`, sprawdzany jest tylko prostokąt grafiki; gdy `FALSE` (lub pominięte), test uwzględnia kanał alfa piksela.
+
+**Zwraca**: [`STRING`](STRING.md) — nazwa znalezionego obiektu lub `"NULL"`.
+
+**Przykłady**
+
+```
+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)
+```
+
+Wariant [`GETGRAPHICSAT`](#getgraphicsat) przeszukujący nie tylko bieżącą scenę, ale również nadrzędne kontenery (epizod, root).
+
+### MOVEBKG
+
+```
+void MOVEBKG(INTEGER deltaX, INTEGER deltaY)
+```
+
+Przesuwa tło o zadane wartości w osiach X i Y (względem aktualnej pozycji).
+
+**Parametry**
+
+- `deltaX`, `deltaY` — wektor przesunięcia w pikselach.
+
+**Przykłady**
+
+```
+CANVASOBSERVER^MOVEBKG(0,ARRAYDY^GET(0));
+CANVASOBSERVER^MOVEBKG(ISCROLLMOVEX,ISCROLLMOVEY);
+```
+
+### PASTE
+
+```
+void PASTE(STRING varName, INTEGER posX, INTEGER posY)
+```
+
+Wkleja na kanwę kopię bieżącej zawartości grafiki [`ANIMO`](ANIMO.md) lub [`IMAGE`](IMAGE.md) w postaci statycznej, niemodyfikowalnej tekstury w punkcie `(posX, posY)`. Operacja nie wpływa na samą zmienną źródłową.
+
+**Parametry**
+
+- `varName` — nazwa zmiennej graficznej.
+- `posX`, `posY` — pozycja wklejenia.
+
+**Przykłady**
+
+```
+CANVASOBSERVER^PASTE("ANNBUM",[I1-IPLANPOSX],[I2-IPLANPOSY]);
+CANVASOBSERVER^PASTE("IMG1",0,0);
+```
+
+### REDRAW
+
+```
+void REDRAW()
+```
+
+W oryginalnym silniku oznacza kanwę jako wymagającą ponownego rysowania. W praktyce silnik i tak rysuje całość każdą klatkę, więc metoda zachowuje się jak no-op.
+
+### REFRESH
+
+```
+void REFRESH()
+```
+
+Wymusza ponowne narysowanie wszystkich obiektów [`IMAGE`](IMAGE.md) w bieżącej scenie — wewnętrznie wywołuje na nich metodę [`INVALIDATE`](IMAGE.md#invalidate).
+
+### REMOVE
+
+```
+void REMOVE(STRING varName1, [STRING varName2, ...])
+```
+
+Ukrywa wymienione obiekty graficzne na kanwie (ustawia ich widoczność na `FALSE`). Metoda przyjmuje dowolną liczbę argumentów.
+
+**Parametry**
+
+- `varName1, varName2, …` — kolejne nazwy zmiennych graficznych do ukrycia.
+
+**Przykłady**
+
+```
+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)
+```
+
+Zapisuje aktualny widok kanwy do pliku `.IMG`. Forma siedmioargumentowa pozwala wyciąć prostokąt kanwy przed skalowaniem.
+
+**Parametry**
+
+- `imgFileName` — ścieżka docelowego pliku `.IMG`.
+- `xScaleFactor`, `yScaleFactor` — współczynniki skalowania w osiach X i Y.
+- `xLeft`, `yTop`, `xRight`, `yBottom` — (opcjonalnie) prostokąt do wycięcia przed skalowaniem.
+
+**Przykłady**
+
+```
+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)
+```
+
+Ustawia obraz tła kanwy. Argument może być nazwą istniejącej zmiennej [`IMAGE`](IMAGE.md) albo ścieżką do pliku `.IMG` — w drugim przypadku silnik utworzy ukryty obiekt [`IMAGE`](IMAGE.md) z plikiem.
+
+**Parametry**
+
+- `imageName` — nazwa zmiennej [`IMAGE`](IMAGE.md) lub ścieżka do pliku `.IMG`.
+
+**Przykłady**
+
+```
+CANVASOBSERVER^SETBACKGROUND(SOBJECT|NAME);
+CANVASOBSERVER^SETBACKGROUND("LOGO.IMG");
+```
+
+### SETBKGPOS
+
+```
+void SETBKGPOS(INTEGER posX, INTEGER posY)
+```
+
+Ustawia bezwzględną pozycję tła w osiach X i Y.
+
+**Parametry**
+
+- `posX`, `posY` — nowa pozycja tła.
+
+**Przykłady**
+
+```
+CANVASOBSERVER^SETBKGPOS([VARI_BKGX-VARI_BKGXOFFSET],[VARI_BKGY-VARI_BKGYOFFSET]);
+CANVASOBSERVER^SETBKGPOS(VARI_TMPX,0);
+```
+
+## Sygnały
+
+### ONINIT
+
+Wywoływany w momencie inicjalizacji obiektu.
+
+### ONWINDOWFOCUSON
+
+Wywoływany po uzyskaniu fokusu przez okno gry (np. powrót z minimalizacji). Emisja działa tylko, gdy notyfikacje są włączone metodą [`ENABLENOTIFY`](#enablenotify).
+
+### ONWINDOWFOCUSOFF
+
+Wywoływany po utracie fokusu przez okno gry (np. przełączenie na inną aplikację). Emisja działa tylko, gdy notyfikacje są włączone.
+
+### ONSIGNAL
+
+Wywoływany po otrzymaniu sygnału (zobacz [Zdarzenia i sygnały](../engine/events.md#onsignal)).

docs/pl/reference/CNVLOADER.md

@@ -0,0 +1,55 @@
+# CNVLOADER
+
+Dynamiczny ładowacz plików `.CNV` w trakcie działania silnika. W przeciwieństwie do [`CLASS`](CLASS.md), który definiuje izolowany kontekst per-instancja, `CNVLOADER` doładowuje zmienne ze wskazanego pliku bezpośrednio do bieżącego kontekstu — zachowują się tak, jakby były tam zdefiniowane od początku.
+
+Jeden obiekt `CNVLOADER` może mieć jednocześnie załadowanych wiele plików `.CNV`. Każde wywołanie [`RELEASE`](#release) zwalnia jeden konkretny plik.
+
+## Metody
+
+### LOAD
+
+```
+void LOAD(STRING cnvFile)
+```
+
+Ładuje wskazany plik `.CNV`. Zmienne zdefiniowane w pliku zostają dodane do bieżącego kontekstu. Próba ponownego załadowania pliku już raz załadowanego jest ignorowana.
+
+**Parametry**
+
+- `cnvFile` — ścieżka do pliku `.CNV` (rozwiązywana przez VFS silnika).
+
+**Przykłady**
+
+```
+CNVLOADER^LOAD(VARSTEMP0);
+CNVLOADER^LOAD([G_SCUTSCENE+".CNV"]);
+```
+
+### RELEASE
+
+```
+void RELEASE(STRING cnvFile)
+```
+
+Zwalnia wcześniej załadowany plik — usuwa z bieżącego kontekstu wszystkie zmienne, które do niego należały. Wywołanie z plikiem, który nie został wcześniej załadowany, nie ma efektu.
+
+**Parametry**
+
+- `cnvFile` — ścieżka do uprzednio załadowanego pliku.
+
+**Przykłady**
+
+```
+CNVLOADER^RELEASE([G_SCUTSCENE+".CNV"]);
+CNVLOADER^RELEASE("WYNURZENIE.CNV");
+```
+
+## Sygnały
+
+### ONINIT
+
+Wywoływany w momencie inicjalizacji obiektu.
+
+### ONSIGNAL
+
+Wywoływany po otrzymaniu sygnału (zobacz [Zdarzenia i sygnały](../engine/events.md#onsignal)).

docs/pl/reference/DATABASE.md

@@ -0,0 +1,152 @@
+# DATABASE
+
+Baza danych w postaci tabeli — zbiór wierszy o jednolitym schemacie. Schemat definiuje powiązana zmienna [`STRUCT`](STRUCT.md): jej pole [`FIELDS`](STRUCT.md#fields) wyznacza kolumny tabeli oraz typy danych w poszczególnych kolumnach.
+
+Dostęp do wierszy realizowany jest sekwencyjnie poprzez kursor. Bieżąca pozycja kursora jest zmieniana metodami [`SELECT`](#select) (bezpośrednio na indeks), [`NEXT`](#next) (kolejny wiersz) i [`FIND`](#find) (po wartości w kolumnie). Dane zapisywane są w plikach `.DTA` w formacie z separatorem `|` — można je ładować ([`LOAD`](#load)) i zapisywać ([`SAVE`](#save)).
+
+## Pola
+
+### MODEL
+
+```
+STRING MODEL
+```
+
+Nazwa zmiennej typu [`STRUCT`](STRUCT.md) definiującej schemat bazy. Pole obowiązkowe — metoda [`LOAD`](#load) wymaga, by schemat został wcześniej zsynchronizowany ze [`STRUCT`](STRUCT.md).
+
+## Metody
+
+### FIND
+
+```
+INTEGER FIND(STRING columnName, mixed columnValue, INTEGER defaultIndex)
+```
+
+Wyszukuje pierwszy wiersz, w którym kolumna o nazwie `columnName` ma wartość `columnValue`. Zwraca jego indeks lub `defaultIndex`, jeżeli żaden wiersz nie pasuje.
+
+**Parametry**
+
+- `columnName` — nazwa przeszukiwanej kolumny.
+- `columnValue` — szukana wartość.
+- `defaultIndex` — indeks zwracany, jeżeli nie znaleziono dopasowania.
+
+**Zwraca**: [`INTEGER`](INTEGER.md) — indeks znalezionego wiersza lub `defaultIndex`.
+
+**Przykłady**
+
+```
+DBOBJECTS^FIND("IDNAME",VARSTAKENAME,0);
+DBOBJECTS^FIND("TYPE",102,0);
+DBDIALOGI^FIND("ID",SDIALOGNAME,IDIALOGINDEKS);
+```
+
+### GETROWSNO
+
+```
+INTEGER GETROWSNO()
+```
+
+Zwraca liczbę wierszy w bazie.
+
+**Zwraca**: [`INTEGER`](INTEGER.md) — liczba wierszy.
+
+**Przykłady**
+
+```
+DBOBJECTS^GETROWSNO();
+```
+
+### LOAD
+
+```
+void LOAD(STRING dtaName)
+```
+
+Ładuje zawartość bazy z pliku `.DTA`. Każda linia pliku to jeden wiersz; kolumny w wierszu rozdzielone są znakiem `|`. Wywołanie metody bez wcześniej zdefiniowanego schematu ([`MODEL`](#model)) jest przerywane z komunikatem błędu.
+
+**Parametry**
+
+- `dtaName` — ścieżka do pliku `.DTA`.
+
+**Przykłady**
+
+```
+DBOBJECTS^LOAD(VARSCURRARCADE);
+DBITEMS^LOAD("$COMMON\ITEMS0.DTA");
+```
+
+### NEXT
+
+```
+void NEXT()
+```
+
+Przesuwa kursor do kolejnego wiersza.
+
+**Przykłady**
+
+```
+DBSCENE^NEXT();
+```
+
+### REMOVEALL
+
+```
+void REMOVEALL()
+```
+
+Usuwa wszystkie wiersze z bazy. Schemat ([`MODEL`](#model)) pozostaje bez zmian.
+
+**Przykłady**
+
+```
+DBITEMS^REMOVEALL();
+```
+
+### SAVE
+
+```
+void SAVE(STRING dtaName)
+```
+
+Zapisuje aktualną zawartość bazy do pliku `.DTA` w tym samym formacie, którego oczekuje [`LOAD`](#load) (wiersze rozdzielone znakiem nowej linii, kolumny — znakiem `|`).
+
+**Parametry**
+
+- `dtaName` — ścieżka docelowego pliku `.DTA`.
+
+**Przykłady**
+
+```
+DBOBJECTS^SAVE(VARSCURRARCADE);
+DBLEVEL^SAVE(["$COMMON\SAVE_BD\BD_CLEV"+VARIACTIVESLOT+".FLD"]);
+```
+
+### SELECT
+
+```
+void SELECT(INTEGER rowIndex)
+```
+
+Ustawia kursor na wiersz o podanym indeksie (liczonym od zera).
+
+**Parametry**
+
+- `rowIndex` — indeks docelowego wiersza.
+
+**Przykłady**
+
+```
+DBOBJECTS^SELECT(0);
+DBOBJECTS^SELECT(VARITER);
+```
+
+## Sygnały
+
+### ONINIT
+
+Wywoływany w momencie inicjalizacji obiektu.
+
+### ONSIGNAL
+
+Wywoływany po otrzymaniu sygnału (zobacz [Zdarzenia i sygnały](../engine/events.md#onsignal)).

docs/pl/reference/EXPRESSION.md

@@ -0,0 +1,51 @@
+# EXPRESSION
+
+Wyrażenie arytmetyczne dwuargumentowe. Zmienna pełni rolę nazwanej formuły — odczyt jej wartości każdorazowo oblicza `OPERAND1 OPERATOR OPERAND2` w bieżącym kontekście, więc wynik aktualizuje się automatycznie, gdy zmieniają się zmienne wejściowe.
+
+Operandy mogą być literałami liczbowymi, nazwami zmiennych lub wyrażeniami w nawiasach kwadratowych (zobacz [Arytmetyka](../engine/arithmetic.md)). Sam typ `EXPRESSION` nie udostępnia żadnych metod skryptowych.
+
+## Pola
+
+### OPERAND1
+
+```
+STRING OPERAND1
+```
+
+Lewy operand wyrażenia.
+
+### OPERAND2
+
+```
+STRING OPERAND2
+```
+
+Prawy operand wyrażenia.
+
+### OPERATOR
+
+```
+STRING OPERATOR
+```
+
+Operator binarny stosowany do operandów. Akceptowane wartości:
+
+| Wartość | Operacja |
+| --- | --- |
+| `ADD` | dodawanie |
+| `SUB` | odejmowanie |
+| `MUL` | mnożenie |
+| `DIV` | dzielenie |
+| `MOD` | reszta z dzielenia |
+
+Reguły typu wyniku (liczba całkowita vs zmiennoprzecinkowa) są takie same jak dla zwykłej arytmetyki w skryptach — zobacz [Arytmetyka — reguła typowania](../engine/arithmetic.md#regula-typowania).
+
+## Sygnały
+
+### ONINIT
+
+Wywoływany w momencie inicjalizacji obiektu.
+
+### ONSIGNAL
+
+Wywoływany po otrzymaniu sygnału (zobacz [Zdarzenia i sygnały](../engine/events.md#onsignal)).

docs/pl/reference/GROUP.md

@@ -0,0 +1,166 @@
+# GROUP
+
+Grupa zmiennych, do której można wysyłać zbiorowe wywołania metod. Każda metoda wywołana na obiekcie typu `GROUP` — która nie należy do własnego API grupy — jest delegowana do każdego elementu po kolei. Jeżeli dany element nie implementuje wywołanej metody, jest pomijany cicho (bez błędu).
+
+Grupa utrzymuje wewnętrzny **marker** wskazujący jeden z elementów. Pozycja markera jest modyfikowana metodami [`NEXT`](#next), [`PREV`](#prev) i [`RESETMARKER`](#resetmarker). Markerem można posłużyć się do sekwencyjnego przechodzenia po elementach grupy.
+
+Wartość zmiennej (`value`) typu `GROUP` to liczba elementów w grupie.
+
+## Metody
+
+### \[nazwa metody\]
+
+```
+void <methodName>(mixed param1, ..., mixed paramN)
+```
+
+Każda metoda spoza własnego API grupy jest delegowana do wszystkich elementów grupy z tymi samymi argumentami. Elementy, które nie implementują takiej metody, są pomijane.
+
+**Przykłady**
+
+```
+GRPHIDE^HIDE();
+GRPMOVE^SETPOSITION(VARX,VARY);
+```
+
+### ADD
+
+```
+void ADD(STRING varName1, [STRING varName2, ...])
+```
+
+Dodaje do grupy jeden lub więcej elementów po nazwie zmiennej. Próba ponownego dodania elementu już obecnego w grupie jest ignorowana.
+
+**Parametry**
+
+- `varName1, varName2, …` — kolejne nazwy zmiennych do dodania.
+
+**Przykłady**
+
+```
+GRPHIDE^ADD("ANNREX");
+GRPMOVE^ADD("ANNBODY1","ANNWAND1","ANNHEAD1");
+GALL^ADD(["ANNPOLA_"+ICLONENO]);
+```
+
+### ADDCLONES
+
+```
+void ADDCLONES(STRING varName, INTEGER firstCloneIndex, INTEGER lastCloneIndex)
+```
+
+Dodaje do grupy zakres klonów zmiennej — od `firstCloneIndex` do `lastCloneIndex` włącznie. Klony są referencjami po nazwie wygenerowanej według wzorca silnika (sufiks indeksu).
+
+**Parametry**
+
+- `varName` — nazwa zmiennej bazowej.
+- `firstCloneIndex` — indeks pierwszego klona.
+- `lastCloneIndex` — indeks ostatniego klona.
+
+**Przykłady**
+
+```
+GBKG^ADDCLONES("ANNPLANNAK",0,[I1-1]);
+GTRASA^ADDCLONES("ANNSKRZYNIA",1,ITMPCLONENO);
+GRPLANS^ADDCLONES("IMGPLAN1",1,10);
+```
+
+### GETSIZE
+
+```
+INTEGER GETSIZE()
+```
+
+Zwraca liczbę elementów w grupie.
+
+**Zwraca**: [`INTEGER`](INTEGER.md) — rozmiar grupy.
+
+**Przykłady**
+
+```
+GRPHIDE^GETSIZE();
+```
+
+### NEXT
+
+```
+mixed NEXT()
+```
+
+Przesuwa marker o jedno w prawo (do następnego elementu, ograniczony wartością ostatniego indeksu) i zwraca referencję do elementu wskazywanego po przesunięciu.
+
+**Zwraca**: referencja do elementu pod nowym markerem.
+
+**Przykłady**
+
+```
+GENEMIES^NEXT();
+GBAZUK^NEXT();
+```
+
+### PREV
+
+```
+mixed PREV()
+```
+
+Przesuwa marker o jedno w lewo (do poprzedniego elementu, ograniczony zerem) i zwraca referencję do elementu pod nowym markerem.
+
+**Zwraca**: referencja do elementu pod nowym markerem.
+
+### REMOVE
+
+```
+void REMOVE(STRING varName)
+```
+
+Usuwa z grupy element o podanej nazwie. Jeżeli marker wskazywał na element poza nowym zakresem, zostaje przesunięty na ostatni dostępny element (lub `-1`, jeśli grupa stała się pusta).
+
+**Parametry**
+
+- `varName` — nazwa zmiennej do usunięcia.
+
+**Przykłady**
+
+```
+GOBJ^REMOVE(S1);
+GOBJ^REMOVE("ANNTNTR");
+```
+
+### REMOVEALL
+
+```
+void REMOVEALL()
+```
+
+Czyści grupę z wszystkich elementów i resetuje marker.
+
+**Przykłady**
+
+```
+GRPHIDE^REMOVEALL();
+```
+
+### RESETMARKER
+
+```
+void RESETMARKER()
+```
+
+Ustawia marker na pierwszy element grupy (indeks `0`). Dla pustej grupy marker przyjmuje wartość `-1`.
+
+**Przykłady**
+
+```
+GENEMIES^RESETMARKER();
+```
+
+## Sygnały
+
+### ONINIT
+
+Wywoływany w momencie inicjalizacji obiektu.
+
+### ONSIGNAL
+
+Wywoływany po otrzymaniu sygnału (zobacz [Zdarzenia i sygnały](../engine/events.md#onsignal)).

docs/pl/reference/INERTIA.md

@@ -0,0 +1,300 @@
+# INERTIA
+
+Interfejs do wbudowanego silnika fizycznego 2D o tej samej nazwie (Inertia). Zarządza ciałami sztywnymi: tworzeniem obiektów, ich wiązaniem z animacjami, polem grawitacji, prędkościami, tłumieniem i przykładaniem sił. Wykorzystany w *Reksio i Kretes w Akcji*.
+
+Każdy obiekt fizyczny ma identyfikator (`objectId`) — wartość całkowitą używaną przez większość metod do wskazania ciała. Plik definiujący świat fizyczny ma rozszerzenie [`.INE`](../engine/index.md) i jest ładowany jednorazowo metodą [`LOAD`](#load).
+
+## Metody
+
+### ADDFORCE
+
+```
+void ADDFORCE(INTEGER objectId, INTEGER forceX, INTEGER forceY)
+```
+
+Przykłada siłę do obiektu w osiach X i Y.
+
+**Parametry**
+
+- `objectId` — identyfikator obiektu.
+- `forceX`, `forceY` — składowe siły.
+
+**Przykłady**
+
+```
+EXTWORLD^ADDFORCE(1,-500,0);
+EXTWORLD^ADDFORCE(1,0,-50);
+```
+
+### CREATESPHERE
+
+```
+void CREATESPHERE(INTEGER objectId, INTEGER posX, INTEGER posY, INTEGER radius)
+```
+
+Tworzy w silniku fizycznym sferę o podanej pozycji środka i promieniu, przypisując jej wskazany identyfikator.
+
+**Parametry**
+
+- `objectId` — identyfikator nowego obiektu.
+- `posX`, `posY` — pozycja środka sfery.
+- `radius` — promień sfery.
+
+**Przykłady**
+
+```
+EXTWORLD^CREATESPHERE(5,10,10,10);
+```
+
+### DELETEBODY
+
+```
+void DELETEBODY(INTEGER objectId)
+```
+
+Usuwa obiekt z silnika fizycznego.
+
+**Parametry**
+
+- `objectId` — identyfikator usuwanego obiektu.
+
+**Przykłady**
+
+```
+EXTWORLD^DELETEBODY(IHANDLEDEL);
+EXTWORLD^DELETEBODY(IRAKIETAOBJ);
+```
+
+### GETPOSITIONX
+
+```
+INTEGER GETPOSITIONX(INTEGER objectId)
+```
+
+Zwraca aktualną pozycję X obiektu o podanym identyfikatorze.
+
+**Parametry**
+
+- `objectId` — identyfikator obiektu.
+
+**Zwraca**: [`INTEGER`](INTEGER.md) — koordynata X.
+
+### GETPOSITIONY
+
+```
+INTEGER GETPOSITIONY(INTEGER objectId)
+```
+
+Zwraca aktualną pozycję Y obiektu o podanym identyfikatorze.
+
+**Parametry**
+
+- `objectId` — identyfikator obiektu.
+
+**Zwraca**: [`INTEGER`](INTEGER.md) — koordynata Y.
+
+### GETSPEED
+
+```
+DOUBLE GETSPEED(INTEGER objectId)
+```
+
+Zwraca prędkość obiektu o podanym identyfikatorze (długość wektora prędkości liniowej).
+
+**Parametry**
+
+- `objectId` — identyfikator obiektu.
+
+**Zwraca**: [`DOUBLE`](DOUBLE.md) — wartość prędkości.
+
+### LINK
+
+```
+void LINK(INTEGER objectId, STRING animoName, BOOL flag1, BOOL flag2)
+```
+
+Wiąże obiekt fizyczny z animacją [`ANIMO`](ANIMO.md) — pozycja animacji jest aktualizowana na podstawie symulacji fizyki. Znaczenie obu flag boolowskich nie zostało jeszcze ustalone (w grach zawsze podawane są jako `TRUE`).
+
+**Parametry**
+
+- `objectId` — identyfikator obiektu fizycznego.
+- `animoName` — nazwa zmiennej [`ANIMO`](ANIMO.md).
+- `flag1`, `flag2` — flagi konfiguracyjne (znaczenie nieustalone).
+
+**Przykłady**
+
+```
+EXTWORLD^LINK(1,"ANNSZCZUREK",TRUE,TRUE);
+EXTWORLD^LINK(IOBIEKT,["ANNSTRZAL_"+ISTRZAL],TRUE,TRUE);
+```
+
+### LOAD
+
+```
+void LOAD(STRING path)
+```
+
+Ładuje plik `.INE` z definicją świata fizycznego.
+
+**Parametry**
+
+- `path` — ścieżka do pliku `.INE`.
+
+**Przykłady**
+
+```
+EXTWORLD^LOAD("WORLD.INE");
+```
+
+### RESETTIMER
+
+```
+void RESETTIMER()
+```
+
+Resetuje wewnętrzny zegar symulacji.
+
+**Przykłady**
+
+```
+EXTWORLD^RESETTIMER();
+```
+
+### SETGRAVITY
+
+```
+void SETGRAVITY(DOUBLE gravityX, DOUBLE gravityY)
+```
+
+Ustawia globalny wektor grawitacji. Wartość `(0, 0)` wyłącza grawitację.
+
+**Parametry**
+
+- `gravityX`, `gravityY` — składowe grawitacji.
+
+**Przykłady**
+
+```
+EXTWORLD^SETGRAVITY(0,0);
+```
+
+### SETLINEARDAMPING
+
+```
+void SETLINEARDAMPING(INTEGER objectId, INTEGER linearDamping)
+```
+
+Ustawia tłumienie liniowe (stopniowe spowalnianie prędkości liniowej) dla obiektu.
+
+**Parametry**
+
+- `objectId` — identyfikator obiektu.
+- `linearDamping` — wartość tłumienia.
+
+**Przykłady**
+
+```
+EXTWORLD^SETLINEARDAMPING(1,300);
+```
+
+### SETMATERIAL
+
+```
+void SETMATERIAL(INTEGER objectId, STRING material)
+```
+
+Ustawia materiał obiektu. Materiały kontrolują, w jaki sposób obiekty reagują na kontakt (sztywność, sprężystość, tarcie). W skryptach gier spotykana jest m.in. nazwa `"TRIGGER"`, dla której silnik wywołuje na powiązanej animacji sygnał `ONSIGNAL^TRIGGER`.
+
+**Parametry**
+
+- `objectId` — identyfikator obiektu.
+- `material` — nazwa materiału.
+
+**Przykłady**
+
+```
+EXTWORLD^SETMATERIAL(IOBIEKT,"TRIGGER");
+```
+
+### SETPOSITION
+
+```
+void SETPOSITION(INTEGER objectId, INTEGER posX, INTEGER posY)
+```
+
+Ustawia bezwzględną pozycję obiektu w świecie fizycznym.
+
+**Parametry**
+
+- `objectId` — identyfikator obiektu.
+- `posX`, `posY` — nowa pozycja.
+
+**Przykłady**
+
+```
+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)
+```
+
+Ustawia prędkość obiektu w osiach X i Y.
+
+**Parametry**
+
+- `objectId` — identyfikator obiektu.
+- `speedX`, `speedY` — składowe prędkości.
+
+**Przykłady**
+
+```
+EXTWORLD^SETVELOCITY(1,0,0);
+EXTWORLD^SETVELOCITY(IOBIEKT,8,0);
+```
+
+### TICK
+
+```
+void TICK()
+```
+
+Wykonuje pojedynczy krok symulacji. Bez wywołania `TICK` świat fizyczny pozostaje zamrożony — typowo wywoływane z sygnału [`ONTICK`](TIMER.md#ontick) [`TIMER`](TIMER.md).
+
+**Przykłady**
+
+```
+EXTWORLD^TICK();
+```
+
+### UNLINK
+
+```
+void UNLINK(INTEGER objectId)
+```
+
+Zrywa powiązanie obiektu z animacją utworzone metodą [`LINK`](#link).
+
+**Parametry**
+
+- `objectId` — identyfikator obiektu.
+
+**Przykłady**
+
+```
+EXTWORLD^UNLINK(IID);
+EXTWORLD^UNLINK(1);
+```
+
+## Sygnały
+
+### ONINIT
+
+Wywoływany w momencie inicjalizacji obiektu.
+
+### ONSIGNAL
+
+Wywoływany po otrzymaniu sygnału (zobacz [Zdarzenia i sygnały](../engine/events.md#onsignal)).

docs/pl/reference/MATRIX.md

@@ -0,0 +1,438 @@
+# MATRIX
+
+Plansza złożona z prostokątnej siatki pól z prostym systemem fizyki kamieni i prymitywnym wyznaczaniem ruchu przeciwników. Zaprojektowany pod jeden, konkretny przypadek użycia — minigrę z podkopem (sekcje Kretesa w *Reksio i Ufo*: mur na Indorze oraz podkop do więzienia na Kuranie).
+
+Dane planszy są przechowywane jako jednowymiarowa tablica liczb całkowitych — adres pola wyznacza się ze wzoru `index = y * width + x`. Stąd obecność metod konwertujących indeks na pozycję 2D i odwrotnie.
+
+## Kody pól {#kody-pol}
+
+Wartości używane przez metody [`GET`](#get), [`GETCELLSNO`](#getcellsno), [`SET`](#set), [`SETROW`](#setrow) i wewnętrzny system fizyki:
+
+| Kod | Znaczenie |
+| --- | --- |
+| `0` | puste pole |
+| `1` | grunt |
+| `2` | kamień |
+| `3` | laska dynamitu |
+| `4` | wyburzalna ściana |
+| `5` | przeciwnik |
+| `6` | nierozbijalna ściana |
+| `7` | odpalona laska dynamitu |
+| `8` | pole w zasięgu eksplozji |
+| `9` | wyjście |
+| `99` | pozycja Kretesa |
+
+## Kody kierunku ruchu {#kody-kierunku-ruchu}
+
+Wartości używane przez [`TICK`](#tick), [`NEXT`](#next) i [`CALCENEMYMOVEDIR`](#calcenemymovedir):
+
+| Kod | Kierunek |
+| --- | --- |
+| `0` | w lewo |
+| `1` | w górę |
+| `2` | w prawo |
+| `3` | w dół |
+
+Wewnętrzny system fizyki używa dodatkowych kodów zwracanych przez [`TICK`](#tick) i odczytywanych przez [`NEXT`](#next):
+
+| Kod | Operacja |
+| --- | --- |
+| `1` | kamień spada w dół |
+| `2` | kamień spada w lewo po skosie |
+| `3` | kamień spada w prawo po skosie |
+| `4` | kamień z przeciwnikiem eksplodują |
+
+## Pola
+
+### BASEPOS
+
+```
+INTEGER, INTEGER BASEPOS
+```
+
+Pozycja lewego górnego rogu planszy na ekranie w pikselach (`X,Y`).
+
+### CELLHEIGHT
+
+```
+INTEGER CELLHEIGHT
+```
+
+Wysokość pojedynczego pola w pikselach.
+
+### CELLWIDTH
+
+```
+INTEGER CELLWIDTH
+```
+
+Szerokość pojedynczego pola w pikselach.
+
+### SIZE
+
+```
+INTEGER, INTEGER SIZE
+```
+
+Wymiary planszy w polach (`szerokość,wysokość`). Wartość wyznacza również rozmiar wewnętrznej tablicy z kodami pól.
+
+## Metody
+
+### CALCENEMYMOVEDEST
+
+```
+INTEGER CALCENEMYMOVEDEST(INTEGER oldCell, INTEGER direction)
+```
+
+Wylicza indeks pola, na które przeciwnik przejdzie z pola `oldCell` przy ruchu w kierunku `direction`. Jeśli pole docelowe znajduje się poza planszą lub nie jest puste, zwracany jest niezmieniony `oldCell`.
+
+**Parametry**
+
+- `oldCell` — bieżąca pozycja przeciwnika (indeks pola).
+- `direction` — kierunek ruchu (`0`–`3`, zobacz [Kody kierunku ruchu](#kody-kierunku-ruchu)).
+
+**Zwraca**: [`INTEGER`](INTEGER.md) — indeks pola docelowego.
+
+**Przykłady**
+
+```
+MAT^CALCENEMYMOVEDEST(IENOLDCELL,IENNEWDIR);
+```
+
+### CALCENEMYMOVEDIR
+
+```
+INTEGER CALCENEMYMOVEDIR(INTEGER oldCell, INTEGER oldDir)
+```
+
+Wylicza kierunek ruchu przeciwnika. Algorytm preferuje skręt w lewo: w pierwszej kolejności sprawdzany jest kierunek `(oldDir+3) MOD 4`, następnie `oldDir`, dalej w prawo i wreszcie do tyłu. Zwracany jest pierwszy kierunek, dla którego pole docelowe jest puste; jeżeli żaden nie jest dostępny — preferowany skręt w lewo.
+
+**Parametry**
+
+- `oldCell` — bieżąca pozycja przeciwnika.
+- `oldDir` — kierunek ruchu z poprzedniego kroku.
+
+**Zwraca**: [`INTEGER`](INTEGER.md) — nowy kierunek ruchu.
+
+**Przykłady**
+
+```
+MAT^CALCENEMYMOVEDIR(IENOLDCELL,IENOLDDIR);
+```
+
+### CANHEROGOTO
+
+```
+BOOL CANHEROGOTO(INTEGER cellNo)
+```
+
+Sprawdza, czy główny bohater może wejść na podane pole. Pole jest przejezdne, jeżeli nie zawiera słabej ściany, mocnej ściany, przeciwnika ani kamienia, a także nie należy do obszaru bramy ustawionej metodą [`SETGATE`](#setgate).
+
+**Parametry**
+
+- `cellNo` — indeks sprawdzanego pola.
+
+**Zwraca**: [`BOOL`](BOOL.md) — `TRUE`, jeżeli pole jest przejezdne.
+
+**Przykłady**
+
+```
+MAT^CANHEROGOTO(I_0);
+```
+
+### GET
+
+```
+INTEGER GET(INTEGER cellNo)
+```
+
+Zwraca kod pola o podanym indeksie. Dla indeksów spoza zakresu zwraca `0`.
+
+**Parametry**
+
+- `cellNo` — indeks pola.
+
+**Zwraca**: [`INTEGER`](INTEGER.md) — kod pola (zobacz [Kody pól](#kody-pol)).
+
+**Przykłady**
+
+```
+MAT^GET(I_ITERATOR);
+MAT^GET(I_MOLE_FIELD_CURR);
+```
+
+### GETCELLOFFSET
+
+```
+INTEGER GETCELLOFFSET(INTEGER x, INTEGER y)
+```
+
+Zwraca indeks pola na podstawie współrzędnych `(x, y)`. Dla współrzędnych spoza planszy zwracane jest `-1`.
+
+**Parametry**
+
+- `x`, `y` — koordynaty pola.
+
+**Zwraca**: [`INTEGER`](INTEGER.md) — indeks pola lub `-1`.
+
+**Przykłady**
+
+```
+MAT^GETCELLOFFSET(ISSRCX,ISSRCY);
+MAT^GETCELLOFFSET(ISTRGX,ISTRGY);
+```
+
+### GETCELLPOSX
+
+```
+INTEGER GETCELLPOSX(INTEGER cellNo)
+```
+
+Zwraca pozycję X pola w pikselach (`BASEPOS.X + col * CELLWIDTH`).
+
+**Parametry**
+
+- `cellNo` — indeks pola.
+
+**Zwraca**: [`INTEGER`](INTEGER.md) — koordynata X w pikselach.
+
+### GETCELLPOSY
+
+```
+INTEGER GETCELLPOSY(INTEGER cellNo)
+```
+
+Zwraca pozycję Y pola w pikselach (`BASEPOS.Y + row * CELLHEIGHT`).
+
+**Parametry**
+
+- `cellNo` — indeks pola.
+
+**Zwraca**: [`INTEGER`](INTEGER.md) — koordynata Y w pikselach.
+
+### GETCELLSNO
+
+```
+INTEGER GETCELLSNO(INTEGER cellCode)
+```
+
+Zwraca liczbę pól z podanym kodem.
+
+**Parametry**
+
+- `cellCode` — kod pola, którego wystąpienia mają zostać policzone.
+
+**Zwraca**: [`INTEGER`](INTEGER.md) — liczba pól o podanym kodzie.
+
+**Przykłady**
+
+```
+MAT^GETCELLSNO(IC_FIELD_CODE_EXIT);
+MAT^GETCELLSNO(IC_FIELD_CODE_ENEMY);
+```
+
+### GETFIELDPOSX
+
+```
+INTEGER GETFIELDPOSX(INTEGER cellNo)
+```
+
+Alias [`GETCELLPOSX`](#getcellposx) używany w *Reksio i Ufo* z silnikiem Piklib 7.1. W Piklib 8 metoda nie jest już udostępniana — próba jej wywołania w nowszej wersji powoduje awarię silnika.
+
+**Parametry**
+
+- `cellNo` — indeks pola.
+
+**Zwraca**: [`INTEGER`](INTEGER.md) — koordynata X w pikselach.
+
+### GETFIELDPOSY
+
+```
+INTEGER GETFIELDPOSY(INTEGER cellNo)
+```
+
+Alias [`GETCELLPOSY`](#getcellposy) używany w *Reksio i Ufo* z silnikiem Piklib 7.1. W Piklib 8 metoda nie jest już udostępniana — próba jej wywołania w nowszej wersji powoduje awarię silnika.
+
+**Parametry**
+
+- `cellNo` — indeks pola.
+
+**Zwraca**: [`INTEGER`](INTEGER.md) — koordynata Y w pikselach.
+
+### GETOFFSET
+
+```
+INTEGER GETOFFSET(INTEGER x, INTEGER y)
+```
+
+Alias [`GETCELLOFFSET`](#getcelloffset) używany w *Reksio i Ufo* z silnikiem Piklib 7.1. W Piklib 8 metoda została zastąpiona przez `GETCELLOFFSET`.
+
+**Parametry**
+
+- `x`, `y` — koordynaty pola.
+
+**Zwraca**: [`INTEGER`](INTEGER.md) — indeks pola lub `-1`.
+
+### ISGATEEMPTY
+
+```
+BOOL ISGATEEMPTY()
+```
+
+Sprawdza, czy wszystkie pola w obszarze bramy ustawionej metodą [`SETGATE`](#setgate) mają kod `0` (puste). Jeśli brama nie została ustawiona, zwracane jest `FALSE`.
+
+**Zwraca**: [`BOOL`](BOOL.md) — `TRUE`, jeżeli wszystkie pola bramy są puste.
+
+**Przykłady**
+
+```
+MAT^ISGATEEMPTY();
+```
+
+### ISINGATE
+
+```
+BOOL ISINGATE(INTEGER cellNo)
+```
+
+Sprawdza, czy pole o podanym indeksie należy do obszaru bramy ustawionej metodą [`SETGATE`](#setgate).
+
+**Parametry**
+
+- `cellNo` — indeks pola.
+
+**Zwraca**: [`BOOL`](BOOL.md) — `TRUE`, jeżeli pole znajduje się w obszarze bramy.
+
+### MOVE
+
+```
+void MOVE(INTEGER oldCell, INTEGER newCell)
+```
+
+Przesuwa zawartość pola źródłowego na pole docelowe; pole źródłowe pozostaje puste (kod `0`).
+
+**Parametry**
+
+- `oldCell` — indeks pola źródłowego.
+- `newCell` — indeks pola docelowego.
+
+**Przykłady**
+
+```
+MAT^MOVE(I_0,I_1);
+```
+
+### NEXT
+
+```
+INTEGER NEXT()
+```
+
+Wykonuje kolejny zaplanowany ruch z kolejki wygenerowanej przez [`TICK`](#tick). Pole źródłowe jest czyszczone, a pole docelowe otrzymuje kod kamienia. Po wykonaniu ruchu emitowany jest sygnał [`ONNEXT`](#onnext) (dla wszystkich ruchów oprócz ostatniego) lub [`ONLATEST`](#onlatest) (dla ostatniego ruchu z kolejki).
+
+**Zwraca**: [`INTEGER`](INTEGER.md) — `0`, jeżeli kolejka jest pusta; `1` przy zwykłym ruchu kamienia; `2`, jeśli kamień wylądował dwa pola nad Kretesem (kolizja).
+
+**Przykłady**
+
+```
+MAT^NEXT();
+```
+
+### SET
+
+```
+void SET(INTEGER cellNo, INTEGER cellCode)
+void SET(INTEGER x, INTEGER y, INTEGER cellCode)
+```
+
+Ustawia kod pola. Metoda ma dwie formy: pierwsza przyjmuje gotowy indeks pola, druga — współrzędne `(x, y)`.
+
+**Parametry**
+
+- `cellNo` — indeks pola **(forma 1)**.
+- `x`, `y` — koordynaty pola **(forma 2)**.
+- `cellCode` — nowa wartość pola (zobacz [Kody pól](#kody-pol)).
+
+**Przykłady**
+
+```
+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)
+```
+
+Wyznacza prostokątny obszar bramy określony przez współrzędne początkowego i końcowego pola (włącznie). Brama wpływa na działanie metod [`CANHEROGOTO`](#canherogoto), [`ISGATEEMPTY`](#isgateempty) oraz [`ISINGATE`](#isingate).
+
+**Parametry**
+
+- `startX`, `startY` — koordynaty lewego górnego rogu obszaru bramy.
+- `endX`, `endY` — koordynaty prawego dolnego rogu obszaru bramy.
+
+**Przykłady**
+
+```
+MAT^SETGATE(3,1,16,4);
+```
+
+### SETROW
+
+```
+void SETROW(INTEGER row, INTEGER cellCode1, [INTEGER cellCode2, ...])
+```
+
+Ustawia kody pól w podanym wierszu. Kolejne argumenty są wpisywane do pól od kolumny `0` w prawo; nadmiarowe argumenty (więcej niż szerokość planszy) są ignorowane.
+
+**Parametry**
+
+- `row` — indeks wiersza.
+- `cellCode1`, `cellCode2`, … — kolejne kody pól w wierszu.
+
+**Przykłady**
+
+```
+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()
+```
+
+Wykonuje jedno tyknięcie wewnętrznego systemu fizyki. Plansza jest skanowana od dołu do góry, od lewej do prawej. Dla każdego kamienia sprawdzane są kolejno:
+
+1. Czy pod kamieniem jest puste pole — zaplanowanie ruchu w dół.
+2. Czy pod kamieniem znajduje się przeciwnik — zaplanowanie eksplozji.
+3. Czy obok kamienia leży inny kamień, a pola na ukos w lewo lub w prawo są puste — zaplanowanie zsuwu po skosie.
+
+Ruchy są zapisywane do wewnętrznej kolejki i wykonywane kolejno przez wywołania [`NEXT`](#next). Każdy wpis zawiera koordynatę X i Y pola źródłowego oraz kod operacji.
+
+**Przykłady**
+
+```
+MAT^TICK();
+```
+
+## Sygnały
+
+### ONINIT
+
+Wywoływany w momencie inicjalizacji obiektu.
+
+### ONNEXT
+
+Wywoływany przez [`NEXT`](#next) po wykonaniu ruchu, który nie był ostatnim w bieżącej kolejce. Argumentami sygnału są: koordynata X (`$1`), koordynata Y (`$2`) i kod operacji (`$3`) pola źródłowego.
+
+### ONLATEST
+
+Wywoływany przez [`NEXT`](#next) po wykonaniu ostatniego ruchu z bieżącej kolejki. Argumenty sygnału są identyczne jak w [`ONNEXT`](#onnext).
+
+### ONSIGNAL
+
+Wywoływany po otrzymaniu sygnału (zobacz [Zdarzenia i sygnały](../engine/events.md#onsignal)).

docs/pl/reference/PATTERN.md

@@ -0,0 +1,147 @@
+# PATTERN
+
+Plansza złożona z siatki "kafelków" o określonych wymiarach i wielowarstwowej strukturze. Wykorzystywana m.in. w etapach z lataniem na Smokręcie (*Reksio i Wehikuł Czasu*) oraz na miotle (*Reksio i Czarodzieje*) — prawdopodobnie do zapisu mapy przewijającego się poziomu. Analiza tego typu jest w toku.
+
+## Pola
+
+### GRIDX
+
+```
+INTEGER GRIDX
+```
+
+Szerokość pojedynczego kafelka siatki w pikselach.
+
+### GRIDY
+
+```
+INTEGER GRIDY
+```
+
+Wysokość pojedynczego kafelka siatki w pikselach.
+
+### HEIGHT
+
+```
+INTEGER HEIGHT
+```
+
+Wysokość planszy.
+
+### LAYERS
+
+```
+INTEGER LAYERS
+```
+
+Liczba warstw planszy.
+
+### PRIORITY
+
+```
+INTEGER PRIORITY
+```
+
+Priorytet rysowania planszy (pozycja w osi Z).
+
+### TOCANVAS
+
+```
+BOOL TOCANVAS
+```
+
+Określa, czy plansza ma być rysowana na kanwie.
+
+### VISIBLE
+
+```
+BOOL VISIBLE
+```
+
+Określa, czy plansza jest widoczna.
+
+### WIDTH
+
+```
+INTEGER WIDTH
+```
+
+Szerokość planszy.
+
+## Metody
+
+### ADD
+
+```
+void ADD(STRING tileId, INTEGER posX, INTEGER posY, STRING animoName, [INTEGER layer])
+```
+
+Dodaje na planszę obiekt graficzny.
+
+**Parametry**
+
+- `tileId` — identyfikator kafelka.
+- `posX`, `posY` — koordynaty kafelka.
+- `animoName` — nazwa zmiennej [`ANIMO`](ANIMO.md) wyświetlanej na kafelku.
+- `layer` — (opcjonalnie) numer warstwy.
+
+**Przykłady**
+
+```
+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])
+```
+
+Zwraca nazwę kafelka pod punktem `(posX, posY)`. Zachowuje się analogicznie do [`CANVAS_OBSERVER.GETGRAPHICSAT`](CANVAS_OBSERVER.md#getgraphicsat), z tą różnicą, że przeszukuje wyłącznie kafelki tej planszy.
+
+**Parametry**
+
+- `posX`, `posY` — koordynaty sprawdzanego punktu.
+- `onlyVisible` — gdy `TRUE`, brane są pod uwagę tylko widoczne kafelki.
+- `ignoreAlpha` — gdy `TRUE`, sprawdzany jest tylko prostokąt; gdy `FALSE`, test uwzględnia kanał alfa piksela.
+- `minZ` — minimalna warstwa.
+- `maxZ` — (opcjonalnie) maksymalna warstwa.
+
+**Zwraca**: [`STRING`](STRING.md) — nazwa kafelka lub `"NULL"`.
+
+**Przykłady**
+
+```
+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)
+```
+
+Przesuwa planszę o zadane wartości w osiach X i Y.
+
+**Parametry**
+
+- `offsetX`, `offsetY` — wektor przesunięcia.
+
+**Przykłady**
+
+```
+PATBOARD^MOVE(0,-3000);
+PATTERNBKG^MOVE(VARINT0,0);
+```
+
+## Sygnały
+
+### ONINIT
+
+Wywoływany w momencie inicjalizacji obiektu.
+
+### ONSIGNAL
+
+Wywoływany po otrzymaniu sygnału (zobacz [Zdarzenia i sygnały](../engine/events.md#onsignal)).

docs/pl/reference/STATICFILTER.md

@@ -0,0 +1,110 @@
+# STATICFILTER
+
+Filtr graficzny — efekt nakładany na zmienne [`ANIMO`](ANIMO.md) lub [`IMAGE`](IMAGE.md). Każda instancja filtra ma jeden rodzaj efektu (pole [`ACTION`](#action)) i zbiór parametrów ustawianych metodą [`SETPROPERTY`](#setproperty). Filtr wiąże się z konkretną grafiką przez [`LINK`](#link) — od tego momentu wszystkie zmiany właściwości będą wpływały na widok grafiki w czasie rzeczywistym.
+
+Jeden obiekt `STATICFILTER` można powiązać równocześnie z wieloma grafikami.
+
+## Pola
+
+### ACTION
+
+```
+STRING ACTION
+```
+
+Rodzaj efektu filtra. Dostępne wartości (na podstawie `sub_100A4490` w bibliotece Piklib8):
+
+| Wartość | Efekt |
+| --- | --- |
+| `COLORCHANNEL` | manipulacja kanałami RGB |
+| `GRAYSCALE` | konwersja na odcienie szarości |
+| `BLUR` | rozmycie |
+| `ROTATE` | obrót |
+| `SCALE` | skalowanie |
+| `NEGATIVE` | negatyw |
+| `RANDOMJITTER` | losowe drgania pikseli |
+| `WAVES` | efekt fali |
+
+## Metody
+
+### LINK
+
+```
+void LINK(STRING objectName)
+```
+
+Wiąże filtr ze zmienną [`ANIMO`](ANIMO.md) lub [`IMAGE`](IMAGE.md). Bieżące ustawienia parametrów filtra zostają przekazane do nowo utworzonego efektu i zaczynają działać natychmiast.
+
+**Parametry**
+
+- `objectName` — nazwa zmiennej graficznej.
+
+**Przykłady**
+
+```
+FJITTER^LINK("IMGZOOM");
+FROTATE^LINK(ARRCARS^GET(0));
+```
+
+### SETPROPERTY
+
+```
+void SETPROPERTY(STRING propertyName, mixed value)
+```
+
+Ustawia parametr filtra. Akceptowane nazwy parametrów zależą od wybranej akcji ([`ACTION`](#action)):
+
+| Parametr | Typ | Filtry |
+| --- | --- | --- |
+| `CANUNDO` | [`BOOL`](BOOL.md) | wszystkie |
+| `CURRENTFRAME` | [`BOOL`](BOOL.md) | wszystkie |
+| `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` |
+
+**Parametry**
+
+- `propertyName` — nazwa ustawianego parametru.
+- `value` — nowa wartość parametru.
+
+**Przykłady**
+
+```
+FCOLOR^SETPROPERTY("CANUNDO","TRUE");
+FCOLOR^SETPROPERTY("CHANNELS","B");
+FJITTER^SETPROPERTY("MAXJITTER",7);
+FROTATE^SETPROPERTY("ANGLE",IKONANGLE);
+```
+
+### UNLINK
+
+```
+void UNLINK(STRING objectName)
+```
+
+Zrywa powiązanie filtra ze zmienną graficzną — usuwa efekt z grafiki.
+
+**Parametry**
+
+- `objectName` — nazwa zmiennej graficznej.
+
+**Przykłady**
+
+```
+FROTATE^UNLINK("ANNKON");
+FROTATE^UNLINK(ARRCARS^GET(VARPLAYER));
+```
+
+## Sygnały
+
+### ONINIT
+
+Wywoływany w momencie inicjalizacji obiektu.
+
+### ONSIGNAL
+
+Wywoływany po otrzymaniu sygnału (zobacz [Zdarzenia i sygnały](../engine/events.md#onsignal)).

docs/pl/reference/STRUCT.md

@@ -0,0 +1,63 @@
+# STRUCT
+
+Struktura danych z nazwanymi, typowanymi polami. W skryptach silnika wykorzystywana wyłącznie razem z [`DATABASE`](DATABASE.md) — opisuje schemat wiersza bazy danych i przechowuje wartości aktualnie wskazywanego rekordu po wywołaniu [`SET`](#set).
+
+## Pola
+
+### FIELDS
+
+```
+STRING FIELDS
+```
+
+Schemat struktury jako lista pól oddzielonych przecinkiem. Każde pole ma format `NAZWA<TYP>`, gdzie `NAZWA` to nazwa pola, a `TYP` to nazwa typu danych. Dopuszczalne typy: `STRING`, `INTEGER`, `DOUBLE`, `BOOLEAN`. Typy są rozpoznawane bez rozróżniania wielkości liter; nieznana nazwa typu jest traktowana jak `STRING`.
+
+## Metody
+
+### GETFIELD
+
+```
+<type> GETFIELD(INTEGER fieldIndex)
+```
+
+Zwraca wartość pola o podanym indeksie (liczonym od zera). Typ zwracanej wartości wynika ze schematu — pole zadeklarowane jako `<INTEGER>` zwraca [`INTEGER`](INTEGER.md), jako `<DOUBLE>` — [`DOUBLE`](DOUBLE.md), jako `<BOOLEAN>` — [`BOOL`](BOOL.md), w pozostałych przypadkach [`STRING`](STRING.md). Dla indeksu spoza zakresu zwracana jest wartość pusta. Jeśli struktura nie została wcześniej zsynchronizowana z [`DATABASE`](DATABASE.md), wszystkie pola mają wartość pustą.
+
+**Parametry**
+
+- `fieldIndex` — indeks pola (`0`-bazowany).
+
+**Zwraca**: wartość pola w typie zadeklarowanym w schemacie.
+
+**Przykłady**
+
+```
+STLEVEL^GETFIELD(0);
+```
+
+### SET
+
+```
+void SET(STRING cursorName)
+```
+
+Synchronizuje strukturę z bieżącym wierszem wskazywanym przez kursor [`DATABASE`](DATABASE.md). Surowe wartości z kursora są konwertowane do typów zadeklarowanych w schemacie pola [`FIELDS`](#fields).
+
+**Parametry**
+
+- `cursorName` — nazwa zmiennej kursora skojarzonego z bazą danych.
+
+**Przykłady**
+
+```
+SOBJECT^SET("DBOBJECTS_CURSOR");
+```
+
+## Sygnały
+
+### ONINIT
+
+Wywoływany w momencie inicjalizacji obiektu.
+
+### ONSIGNAL
+
+Wywoływany po otrzymaniu sygnału (zobacz [Zdarzenia i sygnały](../engine/events.md#onsignal)).

docs/pl/reference/TIMER.md

@@ -0,0 +1,138 @@
+# TIMER
+
+Cykliczny licznik czasu emitujący sygnał [`ONTICK`](#ontick) co `ELAPSE` milisekund. Pozwala uruchamiać kod skryptu w regularnych odstępach — bez timera nie da się w silniku zrealizować nic, co wymaga upływu czasu (animowanie wartości, opóźnienia, regeneracja).
+
+Wartość zmiennej (`value`) typu `TIMER` to liczba dotychczas wykonanych tyknięć.
+
+## Pola
+
+### ELAPSE
+
+```
+INTEGER ELAPSE
+```
+
+Długość cyklu timera w milisekundach. Dla wartości `0` lub mniejszej timer nie tyka, nawet jeżeli jest włączony.
+
+### ENABLED
+
+```
+BOOL ENABLED
+```
+
+Określa, czy timer ma działać po inicjalizacji. Domyślnie `TRUE`.
+
+### TICKS
+
+```
+INTEGER TICKS
+```
+
+Limit cykli — po wyemitowaniu tylu tyknięć timer wyłącza się automatycznie (`ENABLED = FALSE`). Wartość `0` oznacza brak limitu (timer tyka bez końca).
+
+## Metody
+
+### DISABLE
+
+```
+void DISABLE()
+```
+
+Wyłącza timer. Sygnał [`ONTICK`](#ontick) przestaje być emitowany; bieżąca liczba tyknięć nie zostaje wyzerowana.
+
+**Przykłady**
+
+```
+TIMER1^DISABLE();
+```
+
+### ENABLE
+
+```
+void ENABLE()
+```
+
+Włącza timer i ustawia punkt odniesienia odmierzania na *teraz*. Pierwszy tick po wywołaniu zostanie wyemitowany po upływie pełnego `ELAPSE`, niezależnie od tego, ile czasu minęło od ostatniego wyłączenia.
+
+**Przykłady**
+
+```
+TIMCNV^ENABLE();
+TIMER2^ENABLE();
+```
+
+### GETTICKS
+
+```
+INTEGER GETTICKS()
+```
+
+Zwraca liczbę dotychczas wykonanych tyknięć (zmierzoną od ostatniego wywołania [`RESET`](#reset) lub od inicjalizacji).
+
+**Zwraca**: [`INTEGER`](INTEGER.md) — liczba tyknięć.
+
+**Przykłady**
+
+```
+TIMER1^GETTICKS();
+```
+
+### RESET
+
+```
+void RESET()
+```
+
+Zeruje licznik tyknięć i ustawia punkt odniesienia odmierzania na *teraz*.
+
+**Przykłady**
+
+```
+TIMER1^RESET();
+```
+
+### SET
+
+```
+void SET(INTEGER ticks)
+```
+
+Ustawia limit tyknięć w polu [`TICKS`](#ticks). Wartość `0` znosi limit (timer tyka bez końca).
+
+**Parametry**
+
+- `ticks` — nowy limit cykli.
+
+### SETELAPSE
+
+```
+void SETELAPSE(INTEGER timeMs)
+```
+
+Ustawia długość cyklu timera w milisekundach i ustawia punkt odniesienia odmierzania na *teraz*.
+
+**Parametry**
+
+- `timeMs` — nowa długość cyklu (w milisekundach).
+
+**Przykłady**
+
+```
+TIMERSEQ^SETELAPSE(RANDOM^GET(30000,10000));
+TIMERPIECHUR^SETELAPSE(ARRAYPIECHURZYPARAM^GET(0));
+TIMER1^SETELAPSE(VARTIMEUFO);
+```
+
+## Sygnały
+
+### ONINIT
+
+Wywoływany w momencie inicjalizacji obiektu.
+
+### ONTICK
+
+Wywoływany po każdym pełnym cyklu o długości [`ELAPSE`](#elapse), o ile timer jest włączony. Argumentem (`$1`) jest aktualna liczba tyknięć (`currentTickCount`).
+
+### ONSIGNAL
+
+Wywoływany po otrzymaniu sygnału (zobacz [Zdarzenia i sygnały](../engine/events.md#onsignal)).

docs/pl/reference/VECTOR.md

@@ -0,0 +1,160 @@
+# VECTOR
+
+N-wymiarowy wektor liczb zmiennoprzecinkowych. W praktyce wykorzystywany do reprezentowania współrzędnych dwu- lub trójwymiarowych — w grach z silnika spotykany m.in. w minigrach z fizyką (odbicia, normalizacja kierunku ruchu).
+
+Wartość zmiennej (`value`) typu `VECTOR` to długość euklidesowa wektora, czyli `sqrt(x1² + x2² + … + xN²)`.
+
+## Pola
+
+### SIZE
+
+```
+INTEGER SIZE
+```
+
+Liczba współrzędnych wektora. Wartości w grach to zwykle `2` lub `3`.
+
+### VALUE
+
+```
+DOUBLE, DOUBLE, [DOUBLE...] VALUE
+```
+
+Lista wartości startowych poszczególnych współrzędnych. Liczba pozycji powinna odpowiadać polu [`SIZE`](#size).
+
+## Metody
+
+### ADD
+
+```
+void ADD(STRING|VECTOR vectorName)
+```
+
+Dodaje do bieżącego wektora wartości drugiego wektora pozycyjnie. Wynik jest zapisywany w wektorze, na którym wywołano metodę.
+
+**Parametry**
+
+- `vectorName` — wektor dodawany; przekazany jako [`STRING`](STRING.md) (nazwa) lub bezpośrednio jako `VECTOR`.
+
+**Przykłady**
+
+```
+VTEMP2^ADD("VTOCENTER");
+VTEMP2^ADD(VTOCENTER);
+```
+
+### ASSIGN
+
+```
+void ASSIGN(DOUBLE x1, DOUBLE x2, [DOUBLE...])
+```
+
+Przypisuje wektorowi nowe wartości współrzędnych. Liczba argumentów wyznacza, ile współrzędnych zostanie nadpisanych — pozostałe (jeśli wektor był większy) zachowują swoje wcześniejsze wartości. Jeśli liczba argumentów przekracza bieżącą długość wektora, wektor zostaje rozszerzony.
+
+**Parametry**
+
+- `x1, x2, …` — kolejne nowe wartości współrzędnych.
+
+**Przykłady**
+
+```
+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)
+```
+
+Zwraca wartość współrzędnej o podanym indeksie (liczonym od zera). Dla indeksów spoza zakresu zwracana jest wartość `0.0`.
+
+**Parametry**
+
+- `index` — indeks współrzędnej (`0`-bazowany).
+
+**Zwraca**: [`DOUBLE`](DOUBLE.md) — wartość współrzędnej lub `0.0`.
+
+**Przykłady**
+
+```
+VTEMP1^GET(0);
+VTEMP1^GET(1);
+```
+
+### LEN
+
+```
+DOUBLE LEN()
+```
+
+Zwraca długość euklidesową wektora.
+
+**Zwraca**: [`DOUBLE`](DOUBLE.md) — długość wektora.
+
+### MUL
+
+```
+void MUL(DOUBLE scalar)
+```
+
+Mnoży każdą współrzędną wektora przez skalar.
+
+**Parametry**
+
+- `scalar` — mnożnik.
+
+**Przykłady**
+
+```
+VTEMP1^MUL(10.0);
+VTEMP1^MUL(ARRSPEED^GET(VARPLAYER));
+VTEMP2^MUL(-1);
+```
+
+### NORMALIZE
+
+```
+void NORMALIZE()
+```
+
+Normalizuje wektor do długości `1` (dzieli każdą współrzędną przez aktualną długość). Wywołanie na wektorze zerowym nie zmienia jego wartości.
+
+**Przykłady**
+
+```
+VNORMAL^NORMALIZE();
+VTEMP1^NORMALIZE();
+```
+
+### REFLECT
+
+```
+void REFLECT(STRING|VECTOR normalVector, STRING|VECTOR resultVector)
+```
+
+Oblicza odbicie bieżącego wektora względem wektora normalnego i zapisuje wynik do wektora docelowego. Bieżący wektor pozostaje niezmieniony.
+
+**Parametry**
+
+- `normalVector` — wektor normalny do powierzchni, względem której następuje odbicie.
+- `resultVector` — wektor, do którego zostanie zapisany wynik.
+
+**Przykłady**
+
+```
+VINCIDENT^REFLECT("VNORMAL","VREFLECT");
+VINCIDENT^REFLECT(VNORMAL,VREFLECT);
+```
+
+## Sygnały
+
+### ONINIT
+
+Wywoływany w momencie inicjalizacji obiektu.
+
+### ONSIGNAL
+
+Wywoływany po otrzymaniu sygnału (zobacz [Zdarzenia i sygnały](../engine/events.md#onsignal)).

docs/pl/reference/VIRTUALGRAPHICSOBJECT.md

@@ -0,0 +1,213 @@
+# VIRTUALGRAPHICSOBJECT
+
+Wirtualny obiekt graficzny — pełni rolę proxy lub kompozytu dla rzeczywistego obiektu wskazanego polem [`SOURCE`](#source). Pozwala traktować inny element graficzny jak osobną encję z własną pozycją, priorytetem, maską i flagami kolizji.
+
+W skryptach gier ten typ pojawia się punktowo — głównie w *Reksio i Czarodzieje* (`common\classes\SinglePuzzle.class`).
+
+## Pola
+
+### ASBUTTON
+
+```
+BOOL ASBUTTON
+```
+
+Określa, czy obiekt ma być traktowany jako klikalny przycisk.
+
+### MASK
+
+```
+STRING MASK
+```
+
+Nazwa zmiennej graficznej używanej jako maska wycinająca przy renderowaniu obiektu.
+
+### MONITORCOLLISION
+
+```
+BOOL MONITORCOLLISION
+```
+
+Włącza monitorowanie kolizji z innymi obiektami graficznymi.
+
+### MONITORCOLLISIONALPHA
+
+```
+BOOL MONITORCOLLISIONALPHA
+```
+
+Włącza monitorowanie kolizji z uwzględnieniem kanału przezroczystości — kolizja jest wykrywana tylko, gdy nakładające się piksele są nieprzezroczyste.
+
+### PRIORITY
+
+```
+INTEGER PRIORITY
+```
+
+Priorytet rysowania (pozycja w osi Z).
+
+### SOURCE
+
+```
+STRING SOURCE
+```
+
+Nazwa zmiennej graficznej, której zawartość jest renderowana przez obiekt wirtualny.
+
+### TOCANVAS
+
+```
+BOOL TOCANVAS
+```
+
+Określa, czy obiekt jest rysowany na kanwie.
+
+### VISIBLE
+
+```
+BOOL VISIBLE
+```
+
+Określa, czy obiekt jest widoczny.
+
+## Metody
+
+### GETHEIGHT
+
+```
+INTEGER GETHEIGHT()
+```
+
+Zwraca wysokość obiektu w pikselach.
+
+**Zwraca**: [`INTEGER`](INTEGER.md) — wysokość.
+
+### GETPOSITIONX
+
+```
+INTEGER GETPOSITIONX()
+```
+
+Zwraca pozycję X obiektu.
+
+**Zwraca**: [`INTEGER`](INTEGER.md) — koordynata X.
+
+### GETPOSITIONY
+
+```
+INTEGER GETPOSITIONY()
+```
+
+Zwraca pozycję Y obiektu.
+
+**Zwraca**: [`INTEGER`](INTEGER.md) — koordynata Y.
+
+### GETWIDTH
+
+```
+INTEGER GETWIDTH()
+```
+
+Zwraca szerokość obiektu w pikselach.
+
+**Zwraca**: [`INTEGER`](INTEGER.md) — szerokość.
+
+### MOVE
+
+```
+void MOVE(INTEGER offsetX, INTEGER offsetY)
+```
+
+Przesuwa obiekt o zadane wartości względem aktualnej pozycji.
+
+**Parametry**
+
+- `offsetX`, `offsetY` — wektor przesunięcia.
+
+**Przykłady**
+
+```
+VGO^MOVE($1,$2);
+```
+
+### SETMASK
+
+```
+void SETMASK(STRING maskName)
+```
+
+Ustawia maskę wycinającą — odpowiednik pola [`MASK`](#mask).
+
+**Parametry**
+
+- `maskName` — nazwa zmiennej graficznej pełniącej rolę maski.
+
+**Przykłady**
+
+```
+VGO^SETMASK(MSK);
+```
+
+### SETPOSITION
+
+```
+void SETPOSITION(INTEGER posX, INTEGER posY)
+```
+
+Ustawia bezwzględną pozycję obiektu.
+
+**Parametry**
+
+- `posX`, `posY` — nowa pozycja.
+
+**Przykłady**
+
+```
+VGO^SETPOSITION($1,$2);
+```
+
+### SETPRIORITY
+
+```
+void SETPRIORITY(INTEGER priority)
+```
+
+Ustawia priorytet rysowania (pozycję w osi Z) — odpowiednik pola [`PRIORITY`](#priority).
+
+**Parametry**
+
+- `priority` — nowa wartość priorytetu.
+
+**Przykłady**
+
+```
+VGO^SETPRIORITY(1000);
+```
+
+### SETSOURCE
+
+```
+void SETSOURCE(STRING sourceName)
+```
+
+Ustawia zmienną graficzną wskazywaną przez pole [`SOURCE`](#source).
+
+**Parametry**
+
+- `sourceName` — nazwa zmiennej graficznej.
+
+**Przykłady**
+
+```
+VGO^SETSOURCE($2);
+```
+
+## Sygnały
+
+### ONINIT
+
+Wywoływany w momencie inicjalizacji obiektu.
+
+### ONSIGNAL
+
+Wywoływany po otrzymaniu sygnału (zobacz [Zdarzenia i sygnały](../engine/events.md#onsignal)).

docs/pl/reference/WORLD.md

@@ -0,0 +1,549 @@
+# WORLD
+
+Interfejs do silnika fizycznego 3D zbudowanego na bibliotece Sekai — cienkiego wrappera Open Dynamics Engine (ODE). Świat zarządza ciałami sztywnymi, ich połączeniami i ścieżkami, oraz emituje siły, grawitację i tłumienia. Wersja 3D używana w grach Piklib. Pojęciowo odpowiednik [`INERTIA`](INERTIA.md), ale z dostępem do trzeciej osi i własnym, znacznie szerszym API.
+
+Każdy obiekt w świecie identyfikowany jest liczbą całkowitą (`objectId`). Świat ładowany jest z pliku `.SEK`, który zawiera definicje obiektów, ich parametrów fizycznych, siatek kolizyjnych, listy punktów na scenie oraz ich połączeń.
+
+## Typy geometrii
+
+Wartości akceptowane przez parametr `geomType` metody [`ADDBODY`](#addbody):
+
+| Wartość | Geometria |
+| --- | --- |
+| `0` | prostopadłościan (box) |
+| `1` | cylinder |
+| `2` | sfera |
+| `3` | trimesh (siatka trójkątów; używana wyłącznie podczas ładowania z pliku `.SEK`) |
+| `4` | samochodzik (cztery koła + prostopadłościan) |
+
+## Pola
+
+### FILENAME
+
+```
+STRING FILENAME
+```
+
+Ścieżka do pliku `.SEK` z definicją świata fizycznego.
+
+## Metody
+
+### 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)
+```
+
+Tworzy w świecie nowe ciało fizyczne. Parametry `mass`, `mu`, `mu2`, `bounce` i `bounceVelocity` są mapowane bezpośrednio na odpowiednie parametry ODE: masa, tarcie, tarcie w drugim kierunku, wartość odbicia oraz minimalna prędkość wymagana do odbicia. `maxVelocity` ogranicza prędkość obiektu.
+
+Wymiary `dim1`, `dim2`, `dim3` zależą od `geomType`:
+
+- **box** — długości w osiach X, Y, Z.
+- **cylinder** — `dim1` to promień, `dim2` wysokość; `dim3` ignorowane.
+- **sfera** — `dim1` to promień; `dim2` i `dim3` ignorowane.
+
+**Parametry**
+
+- `objectId` — identyfikator nowego ciała.
+- `mass` — masa obiektu.
+- `mu`, `mu2` — współczynniki tarcia.
+- `bounce` — wartość odbicia.
+- `bounceVelocity` — minimalna prędkość wymagana do odbicia.
+- `maxVelocity` — limit prędkości obiektu.
+- `bodyType` — typ ciała (znaczenie zarezerwowane przez ODE).
+- `geomType` — typ geometrii (zobacz [Typy geometrii](#typy-geometrii)).
+- `dim1`, `dim2`, `dim3` — wymiary obiektu zgodnie z geometrią.
+
+**Przykłady**
+
+```
+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])
+```
+
+Przykłada siłę do obiektu w trzech osiach. Pominięcie `forceZ` jest równoważne podaniu `0.0`.
+
+**Parametry**
+
+- `objectId` — identyfikator obiektu.
+- `forceX`, `forceY`, `forceZ` — składowe siły.
+
+**Przykłady**
+
+```
+WORLD^ADDFORCE(100,VARFORCEX,VARFORCEY,0);
+WTEST^ADDFORCE(501,0,VARD_TMP1,0);
+```
+
+### ADDGRAVITYEX
+
+```
+void ADDGRAVITYEX(INTEGER objectId, INTEGER secondObjectId, BOOL gravityEx)
+```
+
+Dodaje rozszerzoną grawitację pomiędzy dwoma obiektami. Pełne znaczenie nie zostało ustalone.
+
+**Przykłady**
+
+```
+WTEST^ADDGRAVITYEX(VARI_ID,_I_,TRUE);
+```
+
+### FINDPATH
+
+```
+void FINDPATH(INTEGER objectId, INTEGER pointObjectId,
+              INTEGER targetX, INTEGER targetY, INTEGER targetZ,
+              BOOL saveIntermediates, [BOOL flag])
+```
+
+Wyznacza ścieżkę dla obiektu między aktualną pozycją a punktem docelowym, korzystając z grafu nawigacyjnego załadowanego z pliku `.SEK`. Wynik jest zapamiętywany przez silnik fizyczny i wykorzystywany w kolejnych wywołaniach [`FOLLOWPATH`](#followpath).
+
+**Parametry**
+
+- `objectId` — identyfikator obiektu, dla którego liczona jest ścieżka.
+- `pointObjectId` — identyfikator punktu nawigacyjnego (zaczepu).
+- `targetX`, `targetY`, `targetZ` — koordynaty punktu docelowego.
+- `saveIntermediates` — gdy `TRUE`, zapamiętywane są punkty pośrednie ścieżki.
+- `flag` — (opcjonalnie) flaga konfiguracyjna (znaczenie nieustalone).
+
+**Przykłady**
+
+```
+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)
+```
+
+Przemieszcza obiekt wzdłuż ścieżki wyznaczonej wcześniej przez [`FINDPATH`](#findpath). Zwraca pozostały dystans do celu.
+
+**Parametry**
+
+- `objectId` — identyfikator obiektu.
+- `arrivalRadius` — promień, w którym obiekt uważany jest za zatrzymany przy celu.
+- `turnClamp` — ograniczenie skrętu na jednym kroku.
+- `speed` — prędkość ruchu.
+
+**Zwraca**: [`DOUBLE`](DOUBLE.md) — pozostały dystans.
+
+**Przykłady**
+
+```
+WPATH^FOLLOWPATH(100,20,0.5,VARDMAXVEL);
+WPATH^FOLLOWPATH(101,20,0.5,VARD_KRETSPEED);
+```
+
+### GETANGLE
+
+```
+DOUBLE GETANGLE(INTEGER objectId)
+```
+
+Zwraca kąt wynikający z wektora prędkości obiektu (w stopniach).
+
+**Parametry**
+
+- `objectId` — identyfikator obiektu.
+
+**Zwraca**: [`DOUBLE`](DOUBLE.md) — kąt w stopniach.
+
+### GETBKGPOSX
+
+```
+INTEGER GETBKGPOSX()
+```
+
+Zwraca pozycję X tła powiązanego ze światem fizycznym.
+
+### GETBKGPOSY
+
+```
+INTEGER GETBKGPOSY()
+```
+
+Zwraca pozycję Y tła powiązanego ze światem fizycznym.
+
+### GETMOVEDISTANCE
+
+```
+DOUBLE GETMOVEDISTANCE(INTEGER objectId)
+```
+
+Zwraca dystans pokonany przez obiekt od ostatniego resetu pomiaru.
+
+**Parametry**
+
+- `objectId` — identyfikator obiektu.
+
+### GETPOSITIONX
+
+```
+INTEGER GETPOSITIONX(INTEGER objectId)
+```
+
+Zwraca pozycję X obiektu w układzie ekranu (po przesunięciu o `+400` względem początku układu fizyki).
+
+### GETPOSITIONY
+
+```
+INTEGER GETPOSITIONY(INTEGER objectId)
+```
+
+Zwraca pozycję Y obiektu w układzie ekranu (z odwróconą osią — `300 - Y`).
+
+### GETPOSITIONZ
+
+```
+INTEGER GETPOSITIONZ(INTEGER objectId)
+```
+
+Zwraca pozycję Z obiektu.
+
+### GETROTATIONZ
+
+```
+DOUBLE GETROTATIONZ(INTEGER objectId)
+```
+
+Zwraca kąt obrotu obiektu względem osi Z (w stopniach).
+
+### GETSPEED
+
+```
+DOUBLE GETSPEED(INTEGER objectId)
+```
+
+Zwraca prędkość obiektu (długość wektora prędkości liniowej).
+
+### 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])
+```
+
+Tworzy połączenie zawiasowe (hinge joint) pomiędzy dwoma ciałami. Opcjonalne argumenty wyznaczają oś obrotu — domyślnie `(0, 0, 1)`.
+
+**Parametry**
+
+- `firstId`, `secondId` — identyfikatory łączonych obiektów.
+- `anchorX`, `anchorY`, `anchorZ` — punkt kotwiczenia połączenia.
+- `limitMotor` — wartość siły potrzebna do zerwania połączenia.
+- `lowStop`, `highStop` — graniczne kąty obrotu.
+- `hingeAxisX`, `hingeAxisY`, `hingeAxisZ` — (opcjonalnie) oś obrotu.
+
+**Przykłady**
+
+```
+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)
+```
+
+Wiąże ciało fizyczne ze zmienną [`ANIMO`](ANIMO.md) lub [`IMAGE`](IMAGE.md) — pozycja grafiki jest aktualizowana na podstawie pozycji ciała.
+
+**Parametry**
+
+- `objectId` — identyfikator ciała.
+- `objectName` — nazwa zmiennej graficznej.
+
+**Przykłady**
+
+```
+WPATH^LINK(100,"ANNREX");
+WORLD^LINK(VARINT0,VARSTRING0);
+```
+
+### LOAD
+
+```
+void LOAD(STRING filename)
+```
+
+Resetuje silnik fizyczny i ładuje świat z pliku `.SEK`.
+
+**Parametry**
+
+- `filename` — ścieżka do pliku `.SEK`.
+
+**Przykłady**
+
+```
+WPATH^LOAD(SOBJECT|NAME);
+```
+
+### MOVEOBJECTS
+
+```
+DOUBLE MOVEOBJECTS()
+```
+
+Wykonuje jeden krok symulacji i przesuwa wszystkie obiekty zgodnie z prawami fizyki. Zwraca czas, który upłynął w symulacji w tym kroku.
+
+**Zwraca**: [`DOUBLE`](DOUBLE.md) — czas symulacji.
+
+**Przykłady**
+
+```
+WORLD^MOVEOBJECTS();
+```
+
+### REMOVEOBJECT
+
+```
+void REMOVEOBJECT(INTEGER objectId)
+```
+
+Usuwa obiekt z silnika fizycznego.
+
+**Przykłady**
+
+```
+WTEST^REMOVEOBJECT(60);
+```
+
+### SETACTIVE
+
+```
+void SETACTIVE(INTEGER objectId, BOOL active, BOOL collidable)
+```
+
+Ustawia stan aktywności obiektu.
+
+**Parametry**
+
+- `objectId` — identyfikator obiektu.
+- `active` — czy obiekt podlega symulacji.
+- `collidable` — czy obiekt bierze udział w wykrywaniu kolizji.
+
+**Przykłady**
+
+```
+WPATH^SETACTIVE(VARI_3DPATHID,$1,$2);
+```
+
+### SETBKGSIZE
+
+```
+void SETBKGSIZE(INTEGER leftX, INTEGER rightX, INTEGER topY, INTEGER bottomY)
+```
+
+Ustawia rozmiar prostokąta tła powiązanego ze światem.
+
+### SETG
+
+```
+void SETG(INTEGER objectId, DOUBLE g)
+```
+
+Ustawia indywidualną stałą grawitacyjną dla obiektu (modeluje magnesy). Domyślna wartość `0` oznacza brak przyciągania.
+
+**Parametry**
+
+- `objectId` — identyfikator obiektu.
+- `g` — stała grawitacyjna.
+
+**Przykłady**
+
+```
+WTEST^SETG(VARI_ID,VARD_MAGNESREACT);
+WTEST^SETG(501,-7000000);
+```
+
+### SETGRAVITY
+
+```
+void SETGRAVITY(DOUBLE gravityX, DOUBLE gravityY, DOUBLE gravityZ)
+```
+
+Ustawia wektor grawitacji globalnej dla całego świata.
+
+**Parametry**
+
+- `gravityX`, `gravityY`, `gravityZ` — składowe grawitacji.
+
+**Przykłady**
+
+```
+WORLD^SETGRAVITY(0,0,-1000);
+WORLD^SETGRAVITY(0,-15,0);
+```
+
+### SETGRAVITYCENTER
+
+```
+void SETGRAVITYCENTER(INTEGER objectId, BOOL gravityCenter)
+```
+
+Włącza lub wyłącza traktowanie obiektu jako źródła centralnego pola grawitacyjnego.
+
+**Parametry**
+
+- `objectId` — identyfikator obiektu.
+- `gravityCenter` — flaga włączająca.
+
+### SETLIMIT
+
+```
+void SETLIMIT(INTEGER objectId, INTEGER minX, INTEGER minY, INTEGER minZ,
+              INTEGER maxX, INTEGER maxY, INTEGER maxZ)
+```
+
+Ustawia ograniczenie pozycji obiektu (prostopadłościenny obszar dozwolonego ruchu).
+
+**Parametry**
+
+- `objectId` — identyfikator obiektu.
+- `minX`, `minY`, `minZ` — dolne granice w trzech osiach.
+- `maxX`, `maxY`, `maxZ` — górne granice w trzech osiach.
+
+**Przykłady**
+
+```
+WORLD^SETLIMIT(100,0,0,0,800,600,999999);
+```
+
+### SETMAXSPEED
+
+```
+void SETMAXSPEED(INTEGER objectId, INTEGER maxSpeed)
+```
+
+Ustawia maksymalną prędkość obiektu.
+
+**Przykłady**
+
+```
+WORLD^SETMAXSPEED(100,200);
+```
+
+### SETMOVEFLAGS
+
+```
+void SETMOVEFLAGS(BOOL moveX, BOOL moveY)
+```
+
+Włącza lub wyłącza ruch obiektu w osiach X i Y. Pełne znaczenie i kontekst zastosowania nie zostały ustalone.
+
+**Przykłady**
+
+```
+WPATH^SETMOVEFLAGS(VARITEMP0,VARITEMP1);
+```
+
+### SETPOSITION
+
+```
+void SETPOSITION(INTEGER objectId, DOUBLE x, DOUBLE y, DOUBLE z)
+```
+
+Ustawia bezwzględną pozycję obiektu (koordynaty w układzie ekranu — silnik przelicza je na układ fizyki).
+
+**Przykłady**
+
+```
+WORLD^SETPOSITION(100,150,400,0);
+WTEST^SETPOSITION(VARI_ID,VARI_X,VARI_Y,0);
+```
+
+### SETREFOBJECT
+
+```
+void SETREFOBJECT(INTEGER objectId)
+```
+
+Ustawia obiekt jako referencyjny — używany przy obliczeniach pozycji względem niego.
+
+**Przykłady**
+
+```
+WPATH^SETREFOBJECT(100);
+```
+
+### SETVELOCITY
+
+```
+void SETVELOCITY(INTEGER objectId, DOUBLE speedX, DOUBLE speedY, DOUBLE speedZ)
+```
+
+Ustawia prędkość obiektu w trzech osiach.
+
+**Przykłady**
+
+```
+WORLD^SETVELOCITY(207,5000000,0,0);
+WORLD^SETVELOCITY(VARPLAYERID,0,0,0);
+```
+
+### START
+
+```
+void START()
+```
+
+Uruchamia symulację (włącza timer silnika fizycznego).
+
+**Przykłady**
+
+```
+WORLD^START();
+```
+
+### STOP
+
+```
+void STOP()
+```
+
+Zatrzymuje symulację (wyłącza timer silnika fizycznego). Stan obiektów pozostaje zachowany.
+
+**Przykłady**
+
+```
+WORLD^STOP();
+```
+
+### UNLINK
+
+```
+void UNLINK(INTEGER objectId)
+```
+
+Zrywa powiązanie obiektu z animacją utworzone metodą [`LINK`](#link).
+
+**Przykłady**
+
+```
+WTEST^UNLINK(VARI_TMP2);
+```
+
+## Sygnały
+
+### ONINIT
+
+Wywoływany w momencie inicjalizacji obiektu.
+
+### ONSIGNAL
+
+Wywoływany po otrzymaniu sygnału (zobacz [Zdarzenia i sygnały](../engine/events.md#onsignal)).

docs/pl/reference/index.md

@@ -1,6 +1,6 @@
 # Referencja typów
 
-Spis typów danych dostępnych w skryptach silnika Piklib/BlooMoo. Lista będzie uzupełniana w miarę opracowywania kolejnych stron.
+Spis typów danych dostępnych w skryptach silnika Piklib/BlooMoo, pogrupowanych tematycznie.
 
 ## Typy używane w skryptach
 
@@ -32,6 +32,24 @@ Spis typów danych dostępnych w skryptach silnika Piklib/BlooMoo. Lista będzie
 - [EPISODE](EPISODE.md) — logiczny segment gry.
 - [SCENE](SCENE.md) — pojedyncza scena.
 
+### Interakcja i kompozycja
+
+- [BUTTON](BUTTON.md) — interaktywny przycisk z trzema stanami wizualnymi.
+- [CANVAS_OBSERVER](CANVAS_OBSERVER.md) — operacje na kanwie i tle.
+- [CNVLOADER](CNVLOADER.md) — dynamiczne ładowanie plików `.CNV`.
+- [GROUP](GROUP.md) — grupa zmiennych z delegowanymi wywołaniami metod.
+- [PATTERN](PATTERN.md) — wielowarstwowa plansza kafelkowa.
+- [STATICFILTER](STATICFILTER.md) — filtr graficzny (rotacja, skalowanie, blur).
+- [VIRTUALGRAPHICSOBJECT](VIRTUALGRAPHICSOBJECT.md) — wirtualny obiekt graficzny.
+
+### Dane
+
+- [DATABASE](DATABASE.md) — baza danych z kursorem.
+
+### Fizyka 3D
+
+- [WORLD](WORLD.md) — interfejs 3D silnika fizycznego opartego na ODE.
+
 ### Wbudowane obiekty I/O
 
 - [KEYBOARD](KEYBOARD.md) — stan klawiatury.
@@ -48,8 +66,11 @@ Spis typów danych dostępnych w skryptach silnika Piklib/BlooMoo. Lista będzie
 - [SOUND](SOUND.md) — krótki efekt dźwiękowy.
 - [TEXT](TEXT.md) — tekst wyświetlany na ekranie.
 
-## Pozostałe typy
+### Matematyczne i narzędziowe
 
-Strony dla poniższych typów zostaną dodane w następnej kolejności:
+- [EXPRESSION](EXPRESSION.md) — wyrażenie arytmetyczne dwuargumentowe.
-
+- [INERTIA](INERTIA.md) — interfejs wbudowanego silnika fizycznego 2D.
-BUTTON, CANVAS_OBSERVER, CNVLOADER, DATABASE, EXPRESSION, GROUP, INERTIA, MATRIX, PATTERN, STATICFILTER, STRUCT, TIMER, VECTOR, VIRTUALGRAPHICSOBJECT, WORLD.
+- [MATRIX](MATRIX.md) — siatka pól z systemem fizyki kamieni.
+- [STRUCT](STRUCT.md) — struktura danych z nazwanymi polami.
+- [TIMER](TIMER.md) — cykliczny licznik czasu.
+- [VECTOR](VECTOR.md) — N-wymiarowy wektor liczb zmiennoprzecinkowych.