Free Hero Mesh

Update of "Messages"
Login
This is a mirror of the main repository for Free Hero Mesh. New tickets and changes will not be accepted at this mirror.
Overview

Artifact ID: 1582809378f8b4263127e0d291f89f0879bd1fe0
Page Name:Messages
Date: 2018-11-30 04:42:21
Original User: zzo38
Parent: 02833b0de1a80beeeef68dd54fb0253502c8596c (diff)
Content

When a message is sent to an object, the code for that message block in the class of the target object is executed, and can return a value to the calling code (or the game engine can also send messages). When a message is executed there are three variables:

From is always an object or zero, but Arg1, Arg2, Arg3 can be any value.

There are built-in messages and user messages. User messages always have # prefix on their name.

The following sections describe when the game engine sends built-in messages to objects, why, with what argument values, what it does with return value, etc. If not otherwise specified, From, Arg1, Arg2, and Arg3 are all zero, while the return value is ignored. See also: Turn order

This document is currently a draft; the stuff mentioned here is not yet implemented.

ARRIVED

BEGIN_TURN

Sent to all objects during the begin phase. From is the last player object found during this turn, and Arg1 and Arg2 are the X and Y coordinates of that object as the begin phase begins.

CLEANUP

Sent to all objects during the cleanup phase.

Note that many commands cannot be used during the cleanup phase.

COLLIDE

If an object tries to move (regardless of the reason), if the CollisionLayers attribute of the moving object has any bits set shared with any object at the target location, then it can't move; in this case, it sends COLLIDE to the moving object and then COLLIDEBY to any conflicting objects at the target location.

There is also the possibility that an object cannot be created because of a conflict in the CollisionLayers attribute; in this case, the COLLIDE message isn't sent, but COLLIDEBY is.

Arg1 and Arg2 are the coordinates of the target location. Arg3 is all of the collision bits that are conflicting (always nonzero). From is the object causing the move.

If the return value is a number, the bits are used as follows:

COLLIDEBY

See COLLIDE.

If the message is sent due to an attempted creation, then From is 0; otherwise, From is the object that is attempting to be moved. Arg1 and Arg2 are the coordinates of that object (or 0 if From is 0). Arg3 is the class of the object that is about to be moved or created.

If the return value is a number, the bits are used as follows:

In the case of bit4 and bit5 and bit6, it will only perform those actions if it is found that (in the state after all COLLIDEBY messages are sent) the specified actions are all possible and will allow the movement to occur. Even if it is found to be possible, some objects may refuse to be destroyed (or some messages sent during the attempt of these actions may cause other problems); if this happens, it will still try to perform as many actions as possible before failing.

CREATE

Sent to an object that has just been created by the Create command. From is the object that executed the Create command.

CREATED

DEPARTED

DESTROY

Sent to an object which is about to be destroyed. If the return value isn't zero, it isn't destroyed; if it returns zero then it is destroyed.

From is the object causing the destruction. Arg3 is 0 if it is destroyed by the Destroy command, or 1 if it is destroyed because something sharp moved into it, or 2 if it is destroyed because this object moved into something sharp.

Note that even if it returns zero, the object isn't garbage collected yet; its variables can still be read and written, and so on, although movements and many other things will ignore its existence.

DESTROYED

END_TURN

Sent to all objects during the end phase. Arg1 is the number of end phases that have occurred during the current turn before this end phase. Arg3 is the bitwise OR of all numeric return values of these events during the same end phase.

If the return value is nonzero, or if there are any more pending triggers, then there is another trigger phase followed by another end phase.

FLOATED

If an object moves to or is created at a location where it is not the topmost object, then after sending the SUNK message, the FLOATED message is sent to all objects above it. From is the object that sunk, while Arg3 is the return value from the SUNK message.

This has nothing to do with sinking or floating in water.

HIT

During movement (see documentation about movement for more details), an object may hit another. In this case, first HIT is sent to the moving object, and then, if allowed, HITBY is sent to the other object.

From is the other object in the collision, other than the current object. Arg1 and Arg2 are the X and Y coordinates of that object. Arg3 has the current hit flags (normally, it is initially zero, and is ORed with the return value of HIT and HITBY message, although there are some exceptions).

The return value is a bit field. The bits have the following meaning:

In compatibility mode, some bits are masked out of the return value. Specifically, the ones with asterisks are ignored.

HITBY

See HIT.

INIT

Sent to all objects when a level is initialized. The return value is used with POSTINIT (below), but is ignored unless it is a number.

JUMPED

Sent to an object that has been teleported (moved by the JumpTo command). It is sent immediately, rather than during the trigger phase like the MOVED message is. Arg1 and Arg2 are the X and Y coordinates that it has moved from.

KEY

Sent during the input phase. If there is a popup quiz object, it is sent to that object only; otherwise, it is sent to all objects with the Input flag set.

Arg1 is the key code (also accessible by the Key command). Arg2 is the return value of the previous object that has been sent the KEY message, or zero if this is the first one.

LASTIMAGE

Sent during the animation phase to objects that have executed a Animate command with the ONCE flag (if the animation has not been overridden), after other events have occurred. At this time, the Image variable is set to the last image of the animation.

If this code changes the appearance or visibility of the object (without moving it to another location), the change in the display is deferred until the animation is finished. Any animation queued during this time will begin to be displayed only once the first animation is finished, although LASTIMAGE is sent as soon as possible. If the object is destroyed during the LASTIMAGE event, it remains visible until the animation is complete (even though it no longer has any effect on the game other than being displayed on the screen).

There is a limit to the animation queue, which is normally 32. If it attempts to queue an animation in a LASTIMAGE event of the same turn that 32 animation phases with LASTIMAGE events have already occurred, the Animate command silently fails without queueing anything. However, queueing a new animation before the LASTIMAGE event will cancel the old one.

There is an exception to the above rules: If the object's Busy flag is set, the turn will be blocked until the animation finishes and then it will send LASTIMAGE during the trigger phase. The order of animations finishing is deterministic and they will always execute in the correct order.

Use of any movement commands is prohibited during the LASTIMAGE event processing of compatible objects (only if sent by the game engine, but regardless of how deeply nested the movement commands are); attempting to do so anyways results in an error and loss of game. Incompatible objects are not subject to this prohibition.

Note: Unlike Hero Mesh, the player does not get any chances to play moves before the LASTIMAGE message is sent; it is sent even before the animation is completed. However, also unlike Hero Mesh, the animation will still be displayed after the LASTIMAGE message is sent. Another thing unlike Hero Mesh is that in Free Hero Mesh, animation orders are deterministic.

MOVED

Sent during the trigger phase to objects that have been moved by a Move command.

MOVING

Sent if an object is about to move (whether due to normal movement or due to teleportation); if it returns nonzero, the move is aborted. From is the object that caused the move, and Arg1 and Arg2 are the target X and Y coordinates it is about to be moved to. Arg3 is the reason for the movement.

POSTINIT

Sent to all objects when a level is initialized, after INIT is sent to all objects. Arg3 is the bitwise OR of all numeric results from INIT.

SUNK

If an object moves to or is created at a location where it is not the topmost object, this message is sent to it.

See also the FLOATED message; the return value of this message is used there.

This has nothing to do with sinking or floating in water.