Rex-EMoolator-docs/docs/en/reference/ANIMO.md

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.

FILENAME

STRING FILENAME

Name of the .ANN file with the animation. Read at variable initialisation; can be overwritten via LOAD.

FPS

INTEGER FPS

Number of animation frames per second. Modified through SETFPS.

MONITORCOLLISION

BOOL MONITORCOLLISION

Whether the animation participates in collision detection. Modified through MONITORCOLLISION and 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 and HIDE.

Methods

GETANCHOR

STRING GETANCHOR()

Returns the currently configured anchor, in the form passed to 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 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 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 — 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 — 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 — 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 = TRUE and TOCANVAS = TRUE).

Returns: BOOL — 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

void MONITORCOLLISION()

Enables collision monitoring between this animation and other objects.

MONITORCOLLISIONALPHA

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.

REMOVEMONITORCOLLISIONALPHA

void REMOVEMONITORCOLLISIONALPHA()

Disables alpha-channel awareness in collision detection, previously enabled by MONITORCOLLISIONALPHA.

RESUME

void RESUME()

Resumes playback paused with 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.

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, 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 field.

Examples

ANNREX^SETPRIORITY(VARIPRIORITY);
ANNHEAD1^SETPRIORITY(15);

SHOW

void SHOW()

Shows the animation (sets VISIBLE to TRUE).

STOP

void STOP([BOOL emitSignal])

Stops the animation's playback.

Parameters

• emitSignal — (optional) if FALSE, the 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.

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

ONRELEASE

Fired when a mouse button is released over an animation configured as a button.

ONRESUMED

Fired when the animation is resumed via RESUME.

ONSIGNAL

Fired when a signal arrives (see Events and signals).

ONSTARTED

Fired when an event starts playing. Note: this signal arrives after ONFRAMECHANGED for the event's first frame.