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