MAILBOXES

Mailboxes are one system by which objects can communicate with other objects. Mailboxes contain data which other objects use to store and move data.

A mailbox can be accessed in exactly two ways - a numerical value is written to it, or a numerical value is read from it. For programmers, think of mailboxes as memory locations with memory-mapped I/O. Some memory locations are simply storage - you write a number to it, and you read the same number back. These correspond to LOCAL, GLOBAL, and SCRATCH mailboxes. Some memory locations are mapped to I/O devices - you write a number to it, and this causes some computation to occur (possibly using the number and/or other memory locations as parameters). Or you can read a number from a memory-mapped I/O address, and the value is not from RAM, but instead reflects the state of some device. These memory-mapped I/O locations are like SYSTEM GLOBAL and SYSTEM LOCAL mailboxes - writing to or reading from SYSTEM mailboxes does not (only) cause storage of a value, but can trigger an action in the engine.

Again, to summarize - mailboxes are like an address space with memory-mapped I/O. Some addresses are simply storage. Some addresses trigger actions or reflect the value of game state. The game engine allows you to change its state and control its action by exposing certain behaviors through SYSTEM mailboxes.

There are five different types of mailboxes. They are:

GLOBAL

Range: 0-999

Mailbox 0 always contains 0. Mailbox 1 always contains 1. Notes: Even if you write to mailbox 0 or 1, you cannot change the values contained in these mailboxes. If there are fields which write to mailboxes you don’t want to use (mailbox to write upon death, for example), you can set them to write to mailbox 0, and their effect will be ignored. If you want a mailbox which is always enabled(visibility, for example), set it to 1 and it will always be enabled. If you want a mailbox which is always disabled (visibility, for example), set it to 0 and it will always be disabled.

SYSTEM GLOBAL

Range: 1000-1999 When a value is written to one of these mailboxes, typically some action is performed using the data written as a parameter. See system mailbox list for details

LOCAL

Range: 2000-2999 Local mailboxes are allocated on an actor by actor basis (specified on the Common page). Each object has its own set of local mailboxes, so changing a local in one object does not affect the local in another.

SYSTEM LOCAL

Range: 3000-3999 Similar to System Global mailboxes. When a value is written to one of these mailboxes, typically some action is performed using the data written as a parameter. In this case, however, the action performed needs to be relative to a given actor. For example, creating a sound effect uses a local mailbox because the game needs to know which object the sound came from in order to place the audio in 3 space.

SCRATCH

Range: 4000-4999 Scratch mailboxes are only for use in a script, and are only valid until the end of the script execution. There are some system scratch mailboxes which contain some useful information about the current object. See the mailbox list for details.

---

Data in mailboxes are interpreted in one of three different ways

Switch (or Boolean) In the same way that a light switch functions, a mailbox containing "switch" data means either "OFF" or "ON." If a mailbox contains a value of zero, the value is "OFF." If a mailbox contains any value other than zero, the value is "ON." Object Reference In this circumstance, the mailbox contains data that refers to another object. For example, if you wanted a Camera to track a specific object, you would write that object's identifying value into the Camera's mailbox. Value A mailbox can contain a specific numeric value, such as the amount of Hit Points or Economic Units that the object has at a particular stage in the game.