As in every object-oriented language, PbML procedures are always methods. We have further specialized methods in 3 categories, to help game designers in their task:
Each class can define zero or more of these methods.
Actions are method meant to behave as phase (or sub-phase) handlers. They can not have a return value since they are called in response to a phase, not a direct invocation.
Actions are invisible to the user, i.e. a player does not know what Actions one of his aeroplane has.
Actions are always executed during the phase they handle. Actions are the only phase handlers that can be recalled during the same phase, as explained in the paragraph below.
2.1.1 ACTION TERMINATION CONDITION
The engine gives every action the chance to be re-executed during a single phase. Each action can tell to the engine its termination status, to tell if it wants to be recalled.
Termination codes (that are syntactically equivalent to the "return" statement, are:
The default value is "canTerminate". This means that this method, for this particular object, won't be called again during this event/phase unless another method somwhere wants to be recalled.
If every action say "canTerminate" than no action is called again and the event/phase is ended.
"terminate" means that the action won't be called again.
"recallMe" tells the engine to recall this action.
Please ensure that there is a termination condition, i.e. at least one case in which an action returns with a "terminate" code! That's the reason why, to avoid deadlocks, the default is "canTerminate".
Please note that if the action is an handler to a sub-phase and it wish to be recalled, it will be recalled after all the sub-phases of the current phase are executed, and then after prior sub phases, if any.
So if action doCalc handles MATH.equation and the MATH phase is split in:
MATH.init
MATH.prepare
MATH.equation
MATH.assign
If doCalc is to be recalled, it will be after:
Commands are the other phase (or sub-phase) handlers, can not have a return value since they are called in response to an event, not a direct invocation.
Commands are visible to the user, i.e. a player does know all the Commands one of his objects (for example aeroplane) has, and can issue any of such commands.
Commands are the one and only way of interaction available to the human player (or the client program) to modify the PbML world.
An object or class is said to "export" its command to the player/client. Once the engine has collected all the commands from every player, it begins to call handlers for the phases, in sequence. Commands are called if a player has specified such a command for a particular object, and are executed in their belonging phase.
Please see 3.1.1 on how to enrich an object's list of commands.
Routines are plain methods, with return values. They can be invoked directly and typically they are just utilities used in other lines of code.
Routines are not event handlers.