D 2018-11-29T21:34:45.001
L Messages
P d6fd9cba94c9ecfcec9a2bd1b7de5a016b689eb4
U zzo38
W 11032
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 <tt>#</tt> 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.

<h2>ARRIVED</h2>

<h2>BEGIN_TURN</h2>
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.

<h2>CLEANUP</h2>
Sent to all objects during the cleanup phase.

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

<h2>COLLIDE</h2>
If an object tries to move (regardless of the reason), if the <tt>CollisionLayers</tt> 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 <tt>COLLIDE</tt> to the moving object and then <tt>COLLIDEBY</tt> 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 <tt>CollisionLayers</tt> attribute; in this case, the <tt>COLLIDE</tt> message isn't sent, but <tt>COLLIDEBY</tt> is.

Arg1 and Arg2 are the coordinates of the target location. From is the object causing the move.

If the return value is a number, the bits are used as follows:
  *  (TODO)

<h2>COLLIDEBY</h2>
See <tt>COLLIDE</tt>.

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:
  *  (TODO)

<h2>CREATE</h2>
Sent to an object that has just been created by the <tt>Create</tt> command. From is the object that executed the <tt>Create</tt> command.

<h2>CREATED</h2>

<h2>DEPARTED</h2>

<h2>DESTROY</h2>
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 <tt>Destroy</tt> 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.

<h2>DESTROYED</h2>

<h2>END_TURN</h2>
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.

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

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

<h2>HIT</h2>
During movement (see documentation about movement for more details), an object may hit another. In this case, first <tt>HIT</tt> is sent to the moving object, and then, if allowed, <tt>HITBY</tt> 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 <tt>HIT</tt> and <tt>HITBY</tt> message, although there are some exceptions).

The return value is a bit field. The bits have the following meaning:
  *  bit0 = Do not send the <tt>HITBY</tt> 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 <tt>HITBY</tt> 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 <tt>HITBY</tt> message to the target object. (Same as bit3 if used during the <tt>HITBY</tt> 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 <tt>Moved</tt> 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 <tt>MOVING</tt> 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.

<h2>HITBY</h2>
See <tt>HIT</tt>.

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

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

<h2>KEY</h2>
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 <tt>Input</tt> flag set.

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

<h2>LASTIMAGE</h2>
Sent during the animation phase to objects that have executed a <tt>Animate</tt> command with the <tt>ONCE</tt> flag (if the animation has not been overridden), after other events have occurred. At this time, the <tt>Image</tt> 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 <tt>Animate</tt> 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 <tt>Busy</tt> flag is set, the turn will be blocked until the animation finishes and then it will send <tt>LASTIMAGE</tt> 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 <tt>LASTIMAGE</tt> 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 <tt>LASTIMAGE</tt> message is sent. Another thing unlike Hero Mesh is that in Free Hero Mesh, animation orders are deterministic.

<h2>MOVED</h2>
Sent during the trigger phase to objects that have been moved by a <tt>Move</tt> command.

<h2>MOVING</h2>
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.

<h2>POSTINIT</h2>
Sent to all objects when a level is initialized, after <tt>INIT</tt> is sent to all objects. Arg3 is the bitwise OR of all numeric results from <tt>INIT</tt>.

<h2>SUNK</h2>
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 <tt>FLOATED</tt> message; the return value of this message is used there.

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