Section II: Spacecalls, "How the MUX talks to the engine"
Spacecalls are MU* functions that act as a direct link between the MU* and the space engine. In an object-oriented sense these are the messages that the MU* sends the engine, while events (discussed in section III) are the messages that flow in the opposite direction. Spacecalls can only be made by objects with the SPACE flag set. Give out SPACE flags with the same hesitancy that you give out WIZARD flags. A player with a SPACE flag has ultimate cosmic power over the objects in space.
Before diving into the list of spacecalls, a few words need to be said about the general syntax of these functions. Spacecalls are called through the MU* function sc(), in the following manner:
sc(call_name, args, ...)
Some spacecalls return values, others do not. Usually they take the form of either a command or action, or ask the engine for a piece of information. Most of the spacecalls require the space coder to specify a valid space object, and quite often this object must be a ship. The object that the spacecall is to operate on or provide information about can be specified in several ways.
The most direct way to specify the space object is to pass it as the first argument of the spacecall, before the spacecall's normal arguments.
If the object is not given as an argument, the engine will look at the DB object that performed the spacecall. If a DATADBREF attribute appears on this object, as it would on a ship console, for example, the engine will use the value in DATADBREF as the object for the spacecall. If that attribute doesn't exist, the engine will simply use the object that executed the spacecall itself.
It is also possible to specify the object for the spacecall as a contact number. This is passed in the first argument to the spacecall as "C#", where # is the contact number. This contact number is taken relative to the object that executed the spacecall. Note that the executing object can also be a console; the DATADBREF attribute will be checked in the same way as mentioned in the previous paragraph. Specifying spacecall objects by contact number can be very handy, as events are often triggered with contact numbers as arguments (see SECTION III below).
Example:
Let's say that we want to execute the spacecall "pos" on space object #23 (whose DB object has dbref #23). "pos" returns the cartesian coordinates of the ship's absolute position in space. spacecall(pos) called by one of the ship's consoles (presumably with DATADBREF set to #23) will return the position of the ship, as will spacecall(pos, #23). The same values will be returned if spacecall(pos) is called by DB object #23 itself. In fact, any object with the SPACE flag can get the same result by calling spacecall(pos, #23).
Now, suppose that dbref #23 is on dbref #40's sensors as contact number 155. The position of object #23 can also be found if object #40 executes spacecall(pos, C155) either on its DB object or one of its consoles.
The above applies to all spacecalls. The nav console code for "set warp" contains the following:
$set warp *:think sc(nav_set_warp, %0)
The argument to the spacecall is the warp setting in this case. If any object with a SPACE flag wanted to set #23's warp to 5.0, assuming #23 is a ship, it could call spacecall(nav_set_warp, #23, 5.0).
Spacecall Listing, by category:
The listing should be pretty self explanatory. The "Obj" or "Ship" boxes are checked if an active space object must be specified either explicitly as the first argument, or implicitly. The object is specified implicitly if the spacecall is executed by a console or the space object's corresponding DB object itself. If the "Ship" box is checked, this space object must be an active ship.
II.2 Miscellaneous Coding Calls
II.4 Ship-Related Calls