Added part of docs

2026-05-19 20:51:59 +02:00
parent e91fd2e42a
commit df6cf2f3d3
66 changed files with 11821 additions and 0 deletions
--- a/docs/en/reference/ANIMO.md
+++ b/docs/en/reference/ANIMO.md
@@ -0,0 +1,875 @@
+# ANIMO
+
+An animation loaded from an `.ANN` file. The most complex visual type in the engine — supports multiple events (frame sequences), variable FPS, an anchor point, opacity, collision monitoring, and a button mode.
+
+An animation is made up of **events**, each of which is a sequence of **frames**. The frame index inside an event starts at `0`, and the global frame index across the whole animation is also tracked separately from `0`.
+
+## Fields
+
+### ASBUTTON
+
+```
+BOOL ASBUTTON
+```
+
+Treats the animation as a clickable button. Modified through [`SETASBUTTON`](#setasbutton).
+
+### FILENAME
+
+```
+STRING FILENAME
+```
+
+Name of the `.ANN` file with the animation. Read at variable initialisation; can be overwritten via [`LOAD`](#load).
+
+### FPS
+
+```
+INTEGER FPS
+```
+
+Number of animation frames per second. Modified through [`SETFPS`](#setfps).
+
+### MONITORCOLLISION
+
+```
+BOOL MONITORCOLLISION
+```
+
+Whether the animation participates in collision detection. Modified through [`MONITORCOLLISION`](#monitorcollision-1) and [`REMOVEMONITORCOLLISION`](#removemonitorcollision).
+
+### MONITORCOLLISIONALPHA
+
+```
+BOOL MONITORCOLLISIONALPHA
+```
+
+Whether collision detection takes the alpha channel into account.
+
+### PRELOAD
+
+```
+BOOL PRELOAD
+```
+
+Whether the animation data is loaded eagerly at initialisation.
+
+### PRIORITY
+
+```
+INTEGER PRIORITY
+```
+
+Rendering priority (`Z`) relative to other scene objects.
+
+### TOCANVAS
+
+```
+BOOL TOCANVAS
+```
+
+Whether the animation is drawn on the scene's main canvas. Setting this to `FALSE` hides the animation visually, but the engine keeps playing it and firing the associated events.
+
+### VISIBLE
+
+```
+BOOL VISIBLE
+```
+
+Animation visibility. Modified through [`SHOW`](#show) and [`HIDE`](#hide).
+
+## Methods
+
+### GETANCHOR
+
+```
+STRING GETANCHOR()
+```
+
+Returns the currently configured anchor, in the form passed to [`SETANCHOR`](#setanchor).
+
+**Returns**: the anchor name or its coordinates.
+
+### GETCENTERX
+
+```
+INTEGER GETCENTERX()
+```
+
+Returns the X coordinate of the centre of the current frame's bounding box.
+
+**Returns**: centre X.
+
+**Examples**
+
+```
+ANNREX^GETCENTERX();
+```
+
+### GETCENTERY
+
+```
+INTEGER GETCENTERY()
+```
+
+Returns the Y coordinate of the centre of the current frame's bounding box.
+
+**Returns**: centre Y.
+
+### GETCFRAMEINEVENT
+
+```
+INTEGER GETCFRAMEINEVENT()
+```
+
+Returns the index of the current frame inside the currently playing event (counted from `0`).
+
+**Returns**: the frame's index in the event.
+
+**Examples**
+
+```
+ANNREX^GETCFRAMEINEVENT();
+```
+
+### GETCURRFRAMEPOSX
+
+```
+INTEGER GETCURRFRAMEPOSX()
+```
+
+Returns the X offset of the currently displayed frame image (per-frame, defined in the animation file).
+
+**Returns**: frame X offset.
+
+### GETCURRFRAMEPOSY
+
+```
+INTEGER GETCURRFRAMEPOSY()
+```
+
+Returns the Y offset of the currently displayed frame image.
+
+**Returns**: frame Y offset.
+
+### GETENDX
+
+```
+INTEGER GETENDX()
+```
+
+Returns the right edge of the current frame's bounding box.
+
+**Returns**: right edge X.
+
+### GETENDY
+
+```
+INTEGER GETENDY()
+```
+
+Returns the bottom edge of the current frame's bounding box.
+
+**Returns**: bottom edge Y.
+
+### GETEVENTNAME
+
+```
+STRING GETEVENTNAME()
+```
+
+Returns the name of the currently playing event.
+
+**Returns**: event name.
+
+**Examples**
+
+```
+ANNREX^GETEVENTNAME();
+```
+
+### GETFRAME
+
+```
+INTEGER GETFRAME()
+```
+
+Returns the global index of the currently displayed frame (independent of the event subdivision).
+
+**Returns**: the global frame index.
+
+### GETFRAMENAME
+
+```
+STRING GETFRAMENAME()
+```
+
+Returns the name of the currently displayed frame (the frame image file name).
+
+**Returns**: the frame name.
+
+### GETHEIGHT
+
+```
+INTEGER GETHEIGHT()
+```
+
+Returns the height of the current animation frame.
+
+**Returns**: height in pixels.
+
+### GETMAXHEIGHT
+
+```
+INTEGER GETMAXHEIGHT()
+```
+
+Returns the maximum height across all of the animation's frames.
+
+**Returns**: the largest height in pixels.
+
+### GETMAXWIDTH
+
+```
+INTEGER GETMAXWIDTH()
+```
+
+Returns the maximum width across all of the animation's frames.
+
+**Returns**: the largest width in pixels.
+
+**Examples**
+
+```
+ANN_STATEK^GETMAXWIDTH();
+```
+
+### GETNAME
+
+```
+STRING GETNAME()
+```
+
+Returns the animation variable's name.
+
+**Returns**: the variable's name.
+
+### GETNOE
+
+```
+INTEGER GETNOE()
+```
+
+Returns the number of events in the animation (short for *Number Of Events*).
+
+**Returns**: event count.
+
+**Examples**
+
+```
+ANNLISCIESLOTY^GETNOE();
+ANNBTN^GETNOE();
+```
+
+### GETNOF
+
+```
+INTEGER GETNOF()
+```
+
+Returns the total number of frames in the animation (short for *Number Of Frames*).
+
+**Returns**: frame count.
+
+### GETNOFINEVENT
+
+```
+INTEGER GETNOFINEVENT(INTEGER eventId)
+INTEGER GETNOFINEVENT(STRING eventName)
+```
+
+Returns the number of frames in the given event. The event can be identified by its number (from `0`) or by its name (case-insensitive). For a non-existent event, `0` is returned.
+
+**Parameters**
+
+- `eventId` / `eventName` — event identifier.
+
+**Returns**: frame count in the event.
+
+**Examples**
+
+```
+ANNREX^GETNOFINEVENT(VARSTEMP0);
+ANNUKLAD^GETNOFINEVENT(0);
+ANNPLANNAK^GETNOFINEVENT("IDLE");
+```
+
+### GETPOSITIONX
+
+```
+INTEGER GETPOSITIONX([BOOL absolute])
+```
+
+Returns the X coordinate of the current frame's top-left corner on the canvas. The variant with a `BOOL` argument returns the absolute position, ignoring per-frame offsets defined in the animation file.
+
+**Parameters**
+
+- `absolute` — (optional) `TRUE` to skip per-frame offsets.
+
+**Returns**: position X.
+
+### GETPOSITIONY
+
+```
+INTEGER GETPOSITIONY([BOOL absolute])
+```
+
+Returns the Y coordinate of the current frame's top-left corner on the canvas. The variant with a `BOOL` argument returns the absolute position.
+
+**Parameters**
+
+- `absolute` — (optional) `TRUE` to skip per-frame offsets.
+
+**Returns**: position Y.
+
+### GETPRIORITY
+
+```
+INTEGER GETPRIORITY()
+```
+
+Returns the animation's rendering priority (`Z`).
+
+**Returns**: the value of the [`PRIORITY`](#priority) field.
+
+### GETWIDTH
+
+```
+INTEGER GETWIDTH()
+```
+
+Returns the width of the current animation frame.
+
+**Returns**: width in pixels.
+
+### HIDE
+
+```
+void HIDE()
+```
+
+Hides the animation visually without stopping its playback. Calling [`PLAY`](#play) automatically restores visibility.
+
+### ISAT
+
+```
+BOOL ISAT(INTEGER posX, INTEGER posY)
+```
+
+Checks whether the point at the given coordinates lies inside the current frame's bounding box.
+
+**Parameters**
+
+- `posX` — point X coordinate.
+- `posY` — point Y coordinate.
+
+**Returns**: [`BOOL`](BOOL.md) — `TRUE` if the point is inside the bounding box.
+
+### ISNEAR
+
+```
+BOOL ISNEAR(STRING animoName, INTEGER iouThresholdPercent)
+```
+
+Checks whether this animation is close to another animation. Internally, the Jaccard index (*Intersection over Union*, IoU) of the two animations' bounding boxes is computed; if the IoU exceeds the given threshold (in percent), `TRUE` is returned.
+
+**Parameters**
+
+- `animoName` — name of the other animation.
+- `iouThresholdPercent` — IoU threshold in percent.
+
+**Returns**: [`BOOL`](BOOL.md) — `TRUE` if the IoU exceeds the threshold.
+
+**Examples**
+
+```
+ENEMY^ISNEAR("HERO", 1);
+ANNORKA^ISNEAR("ANNLODKA", 12);
+```
+
+### ISPLAYING
+
+```
+BOOL ISPLAYING()
+BOOL ISPLAYING(STRING eventName)
+```
+
+Checks whether the animation is currently playing. The no-argument variant returns whether any event is currently playing; with a name, the check is limited to that specific event.
+
+**Parameters**
+
+- `eventName` — (optional) name of the event to check.
+
+**Returns**: [`BOOL`](BOOL.md) — `TRUE` if the animation (or the specific event) is playing.
+
+**Examples**
+
+```
+ANNREX^ISPLAYING();
+ANNREXGLOWA^ISPLAYING("SPI");
+```
+
+### ISVISIBLE
+
+```
+BOOL ISVISIBLE()
+```
+
+Checks whether the animation is visible ([`VISIBLE`](#visible) = `TRUE` and [`TOCANVAS`](#tocanvas) = `TRUE`).
+
+**Returns**: [`BOOL`](BOOL.md) — `TRUE` if the animation is visible.
+
+### LOAD
+
+```
+void LOAD(STRING path)
+```
+
+Loads an animation from an `.ANN` file, replacing the previous contents.
+
+**Parameters**
+
+- `path` — `.ANN` file path in the game's VFS.
+
+**Examples**
+
+```
+ANNBKG^LOAD(SOBJECT|NAME);
+ANNCHARACTER^LOAD("PIXEL.ANN");
+ANNMINIMAPA^LOAD([""+ILEVEL+"_MINIMAPA.ANN"]);
+```
+
+### MONITORCOLLISION {#monitorcollision-1}
+
+```
+void MONITORCOLLISION()
+```
+
+Enables collision monitoring between this animation and other objects.
+
+### MONITORCOLLISIONALPHA {#monitorcollisionalpha-1}
+
+```
+void MONITORCOLLISIONALPHA()
+```
+
+Enables alpha-channel awareness in collision detection.
+
+### MOVE
+
+```
+void MOVE(INTEGER offsetX, INTEGER offsetY)
+```
+
+Moves the animation by the given offsets relative to its current position.
+
+**Parameters**
+
+- `offsetX` — X offset.
+- `offsetY` — Y offset.
+
+**Examples**
+
+```
+ANNELEMENT^MOVE(-200, 0);
+ANNPLAYER^MOVE(VARDX, VARDY);
+ANNITEMDRAGGING^MOVE([IMOUSEX-IMOUSELASTX], [IMOUSEY-IMOUSELASTY]);
+```
+
+### NEXTFRAME
+
+```
+void NEXTFRAME()
+```
+
+Advances the animation to the next frame of the current event.
+
+### NPLAY
+
+```
+void NPLAY(INTEGER eventId)
+```
+
+Starts playing the event with the given index (counted from `0`).
+
+**Parameters**
+
+- `eventId` — event index.
+
+**Examples**
+
+```
+ANNDARK0^NPLAY(VARITEMP2);
+CZAS^NPLAY(0);
+```
+
+### PAUSE
+
+```
+void PAUSE()
+```
+
+Pauses the animation on the current frame.
+
+### PLAY
+
+```
+void PLAY([STRING eventName])
+```
+
+Starts playing an event. The no-argument variant restarts the previously played event from the beginning.
+
+**Parameters**
+
+- `eventName` — (optional) name of the event to play (case-insensitive).
+
+**Examples**
+
+```
+G_STLPAGE^PLAY("ELAPSE");
+ANNREX^PLAY(VARITEMP0);
+ANNKRET^PLAY(["IDLE_"+ANNKRET^GETEVENTNAME()]);
+ANIMOREKSIO^PLAY($1);
+```
+
+### PREVFRAME
+
+```
+void PREVFRAME()
+```
+
+Moves the animation to the previous frame of the current event.
+
+### REMOVEMONITORCOLLISION
+
+```
+void REMOVEMONITORCOLLISION()
+```
+
+Disables collision monitoring previously enabled by [`MONITORCOLLISION`](#monitorcollision-1).
+
+### REMOVEMONITORCOLLISIONALPHA
+
+```
+void REMOVEMONITORCOLLISIONALPHA()
+```
+
+Disables alpha-channel awareness in collision detection, previously enabled by [`MONITORCOLLISIONALPHA`](#monitorcollisionalpha-1).
+
+### RESUME
+
+```
+void RESUME()
+```
+
+Resumes playback paused with [`PAUSE`](#pause).
+
+### SETANCHOR
+
+```
+void SETANCHOR(STRING anchor)
+void SETANCHOR(INTEGER offsetX, INTEGER offsetY)
+```
+
+Sets the animation's anchor — the offset that is subtracted from coordinates passed to [`SETPOSITION`](#setposition).
+
+The `STRING` variant accepts a named position derived from the bounding box: `CENTER`, `LEFTUPPER`, `RIGHTUPPER`, `LEFTLOWER`, `RIGHTLOWER`, `LEFT`, `RIGHT`, `TOP`, `BOTTOM`.
+
+The two-`INTEGER` variant accepts the anchor coordinates directly.
+
+**Parameters**
+
+- `anchor` — bounding-box position name.
+- `offsetX, offsetY` — anchor coordinates.
+
+**Examples**
+
+```
+ANNSELECT^SETANCHOR("CENTER");
+ANNREX^SETANCHOR("LEFTLOWER");
+ANNREX^SETANCHOR(0, -100);
+```
+
+### SETASBUTTON
+
+```
+void SETASBUTTON(BOOL enabled, BOOL changeCursor)
+```
+
+Configures the animation as a clickable button. Regardless of the argument values, the call makes the animation visible.
+
+**Parameters**
+
+- `enabled` — `TRUE` to activate click handling.
+- `changeCursor` — `TRUE` for the cursor to change on hover.
+
+**Examples**
+
+```
+ANNEXIT^SETASBUTTON(TRUE, TRUE);
+ANIMOPOWROT^SETASBUTTON(FALSE, FALSE);
+```
+
+### SETBACKWARD
+
+```
+void SETBACKWARD()
+```
+
+Sets the playback direction to backwards.
+
+### SETFORWARD
+
+```
+void SETFORWARD()
+```
+
+Sets the playback direction to forward (the natural direction).
+
+### SETFPS
+
+```
+void SETFPS(INTEGER fps)
+```
+
+Changes the animation's playback speed.
+
+**Parameters**
+
+- `fps` — frames per second.
+
+**Examples**
+
+```
+STLMAGIC^SETFPS(5);
+ANNMUCHA1^SETFPS(30);
+ANNKON^SETFPS([IKONFPS*8]);
+```
+
+### SETFRAME
+
+```
+void SETFRAME(INTEGER frameNumber)
+void SETFRAME(STRING eventName, INTEGER frameNumber)
+void SETFRAME(STRING eventName, STRING frameName)
+```
+
+Sets the animation to a specific frame. The one-argument variant selects a frame by its global index. The two-argument variant selects an event and then a position in it (by frame number or frame name).
+
+**Parameters**
+
+- `eventName` — event name.
+- `frameNumber` — frame index within an event (from `0`) or a global frame index.
+- `frameName` — specific frame name within the event.
+
+**Examples**
+
+```
+ANNREX^SETFRAME(VARSTEMP0, [VARITEMP2-1]);
+ANNSCIAGA^SETFRAME("PLAY", VARIREPEATSPELL);
+OFERTA^SETFRAME(3);
+ANN_H_PIECYK^SETFRAME("ROT", "PIECYK4");
+```
+
+### SETFRAMENAME
+
+```
+void SETFRAMENAME(INTEGER eventId, INTEGER frameNumber, STRING name)
+```
+
+Changes the name of a specific frame inside the given event.
+
+**Parameters**
+
+- `eventId` — event index (from `0`).
+- `frameNumber` — frame index within the event (from `0`).
+- `name` — the new frame name.
+
+**Examples**
+
+```
+ANNKALAREPA^SETFRAMENAME(0, 0, "200");
+ANNKALAREPA^SETFRAMENAME(1, 0, "300");
+```
+
+### SETOPACITY
+
+```
+void SETOPACITY(INTEGER opacity)
+```
+
+Sets the animation's opacity in the `0–255` scale (`0` — fully transparent, `255` — fully opaque).
+
+**Parameters**
+
+- `opacity` — alpha-channel value.
+
+**Examples**
+
+```
+ANNPLAYER0^SETOPACITY(255);
+ANNPLAYER^SETOPACITY(100);
+```
+
+### SETPOSITION
+
+```
+void SETPOSITION(INTEGER posX, INTEGER posY)
+```
+
+Sets the animation's absolute position. If an anchor has been set via [`SETANCHOR`](#setanchor), its coordinates are subtracted from the arguments.
+
+**Parameters**
+
+- `posX` — X coordinate.
+- `posY` — Y coordinate.
+
+**Examples**
+
+```
+ANNREX^SETPOSITION(400, 300);
+ANNEXIT^SETPOSITION(-700, -450);
+ANNBKG^SETPOSITION([VARIBKGOFFSETX-VARDTEMP0], [VARIBKGOFFSETY-VARDTEMP1]);
+```
+
+### SETPRIORITY
+
+```
+void SETPRIORITY(INTEGER priority)
+```
+
+Sets the rendering priority.
+
+**Parameters**
+
+- `priority` — the new value of the [`PRIORITY`](#priority) field.
+
+**Examples**
+
+```
+ANNREX^SETPRIORITY(VARIPRIORITY);
+ANNHEAD1^SETPRIORITY(15);
+```
+
+### SHOW
+
+```
+void SHOW()
+```
+
+Shows the animation (sets [`VISIBLE`](#visible) to `TRUE`).
+
+### STOP
+
+```
+void STOP([BOOL emitSignal])
+```
+
+Stops the animation's playback.
+
+**Parameters**
+
+- `emitSignal` — (optional) if `FALSE`, the [`ONFINISHED`](#onfinished) signal is suppressed. By default, the signal is fired.
+
+**Examples**
+
+```
+G_STLPAGE^STOP(FALSE);
+ANNREX^STOP(FALSE);
+ANNBLANK^STOP();
+```
+
+### TOP
+
+```
+void TOP([BOOL flag])
+```
+
+Modifies how the animation is rendered relative to the scene's top layer. The exact behaviour depends on the current scene composition.
+
+**Parameters**
+
+- `flag` — (optional) a flag changing the rendering mode.
+
+**Examples**
+
+```
+ANNWAND0^TOP(FALSE);
+ANNHEAD0^TOP(FALSE);
+```
+
+## Signals
+
+### ONCLICK
+
+Fired when the animation is clicked, provided it is configured as a button via [`SETASBUTTON`](#setasbutton).
+
+### ONCOLLISION
+
+Fired when a collision is detected.
+
+### ONCOLLISIONFINISHED
+
+Fired when an ongoing collision ends.
+
+### ONDONE
+
+Fired after all of the animation's events have finished.
+
+### ONFINISHED
+
+Fired when an event finishes playing. The signal is [parameterised](../engine/events.md#parameterised-signals) by the event name, so a handler can target a specific event:
+
+```
+ANIMATION:ONFINISHED^IDLE=BEHAFTERIDLE
+```
+
+### ONFIRSTFRAME
+
+Fired when the event's first frame is displayed.
+
+### ONFOCUSON
+
+Fired when the cursor moves onto the animation, provided it is configured as a button.
+
+### ONFOCUSOFF
+
+Fired when the cursor moves off the animation, provided it is configured as a button.
+
+### ONFRAMECHANGED
+
+Fired when the animation's frame changes.
+
+### ONINIT
+
+Fired when the object is initialised.
+
+### ONPAUSED
+
+Fired when the animation is paused via [`PAUSE`](#pause).
+
+### ONRELEASE
+
+Fired when a mouse button is released over an animation configured as a button.
+
+### ONRESUMED
+
+Fired when the animation is resumed via [`RESUME`](#resume).
+
+### ONSIGNAL
+
+Fired when a signal arrives (see [Events and signals](../engine/events.md#onsignal)).
+
+### ONSTARTED
+
+Fired when an event starts playing. Note: this signal arrives after [`ONFRAMECHANGED`](#onframechanged) for the event's first frame.