| Artifact ID: | e45e6fa35c235e855f956c1157be3b6b2d91e9cc |
|---|---|
| Page Name: | Messages |
| Date: | 2018-11-29 04:57:58 |
| Original User: | zzo38 |
| Next | 7d9e8f45b7bb267f54f9f7829a7e9172db980b97 |
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.
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.CREATE
Sent to an object that has just been created by the Create command. From is the object that executed the Create command.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 with more Sharpness than this object's Hardness touched it.
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.
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.
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.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.