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 = The object that sent it (sometimes 0 if sent by the game engine).
- Arg1
- Arg2
- Arg3
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:
- bit0 = Do not move the object. It will still send COLLIDEBY messages unless bit1 is also set.
- bit1 = Do not send any COLLIDEBY messages.
- bit2 = Pretend the move attempt was successful even if it isn't.
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:
- bit0 = Do not move or create the object.
- bit1 = Do not send any more COLLIDEBY messages to further objects.
- bit2 = Pretend the move attempt was successful even if it isn't. (Has no effect in case of creation.)
- bit4 = Permit destroying this object to make room if necessary.
- bit5 = Permit exchaging the position of this object with the other one to make room if necessary. (This might not be possible if this object has multiple CollisionLayers bits set; it will check if it is possible.)
- bit6 = Permit moving this object into or out of the bizarro world to make room if necessary. (Only if the bizarro world is implemented; I am unsure if I will implement it or not.)
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:
- bit0 = Do not send the HITBY message to the target object.
- bit1 = Ignore hardness/sharpness with the target object.
- bit2 = Do not attempt to push the target object.
- bit3 = Abort the move attempt immediately.
- bit4 = Do not send the HITBY message to the target object or any other objects at the same location.
- bit5 = Ignore hardness/sharpness with the target object or any other objects at the same location.
- bit6 = Do not attempt to push the target object or any other objects at the same location.
- bit7* = Do not try sliding this object against anything.
- bit8 = Abort after sending the HITBY message to the target object. (Same as bit3 if used during the HITBY message.)
- bit9 = Abort after checking hardness/sharpness with the target object.
- bit10 = Abort after attempting shoving the target object.
- bit11 = See bit15. Setting this bit by yourself has no meaning.
- bit12* = If the move fails, pretend it was successful, without actually moving the object.
- bit13* = Abort before actually moving the object and before trying sliding.
- bit14* = Do not set the Moved flag if successful.
- bit15 = Try again after trying shoving (whether or not the shoving is successful, or even attempted; if it is successful, it automatically sets this bit). If this bit is set, then bit11 is set during the next attempt (and will initially be the only bit set).
- bit16 = Set by the game engine if this event is due to trying to slide an object.
- bit17* = Do not actually move the object (does not send the MOVING message, nor any arrivals/departures/float/sunk), but still try everything and see if it is successful or not.
- bit18* = (reserved)
- bit19* = (reserved)
- bit20* = (reserved)
- bit21* = (reserved)
- bit22* = (reserved)
- bit23* = (reserved)
- bit24* = (reserved)
- bit25* = (reserved)
- bit26* = (reserved)
- bit27* = (reserved)
- bit28 = User flag with no meaning to the game engine.
- bit29 = User flag with no meaning to the game engine.
- bit30 = User flag with no meaning to the game engine.
- bit31 = User flag with no meaning to the game engine.
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.