Not to be confused with users, the ones typing the input, the player is the representation of the current viewpoint in the world. The purpose of the player is to define or constrain what is currently visible in terms of actions or objects.
Players can also hold objects. The objects held by a player are accessible so long as that player is current. Players also handle failed actions and other input errors before they are passed onto the world.
Players also can have a current room, which further controls what the player can both do and interact with. A TAME module is not required to have a player, but without players, you cannot set the current room.
player [INDENTIFIER] [INHERITANCE_CLAUSE]
{
/* Lifecycle */
init() { ... }
/* Events */
onAction(action) { ... }
onActionWith(action, object) { ... }
onActionWithAncestor(action, object) { ... }
onActionWithOther(action) { ... }
onModalAction(action, mode) { ... }
onUnhandledAction() { ... }
onUnhandledAction(action) { ... }
onUnknownCommand() { ... }
onMalformedCommand() { ... }
onMalformedCommand(action) { ... }
onIncompleteCommand() { ... }
onIncompleteCommand(action) { ... }
onAmbiguousCommand() { ... }
onAmbiguousCommand(action) { ... }
}
| [IDENTIFIER] | An internal identifier that represents this player in the rest of TAMEScript. This identifier must not be used to describe another element. |
| [INHERITANCE_CLAUSE] | If this player inherits entry points and functions from another player, you declare its parent player by adding a colon (:) plus the identifier of the parent player. |
| Command Name | Parameters | Description |
|---|---|---|
| Init | None | Called at module context initialization on each element. |
| OnAction | ACTION | Called when an action needs to be processed on a specific element. Action type decides the element entry point. |
| OnActionWith | ACTION, OBJECT | Called when a [di]transitive action needs to be processed with a specific object. |
| OnActionWithAncestor | ACTION, OBJECT | Called when a [di]transitive action needs to be processed with a matched ancestor object (if OnActionWith is unhandled). |
| OnActionWithOther | ACTION | Called when a [di]transitive action needs to be processed with a valid object, but the object is not handled by OnActionWith or OnActionWithAncestor. |
| OnModalAction | ACTION, STRING | Called when a modal action needs to be processed with a specific mode. |
| OnUnhandledAction | ACTION [optional] | Called when an action is not handled by the elements that should have handled it. |
| OnUnknownCommand | None | Called if an action is not interpreted. |
| OnMalformedCommand | ACTION [optional] | Called if an interpreted action has a part that isn't found, or if a strict command has more parsed than needed. |
| OnIncompleteCommand | ACTION [optional] | Called if an interpreted action is missing a element that is expected, but not parsed. |
| OnAmbiguousCommand | ACTION [optional] | Called if an interpreted action can have more than one possible object target based on the input. |
The keyword archetype can be used to create players that have common functions and entry points to share among similar players. Archetyped players can inherit from other parent players and archetyped players.
Archetyped players also cannot be used in commands as through they were real elements. Archetypes also do not hold a context state, nor is their context state saved.
player archetype [INDENTIFIER] [INHERITANCE_CLAUSE]
{
/* Lifecycle */
init() { ... }
/* Events */
onAction(action) { ... }
onActionWith(action, object) { ... }
onActionWithAncestor(action, object) { ... }
onActionWithOther(action) { ... }
onModalAction(action, mode) { ... }
onUnhandledAction() { ... }
onUnhandledAction(action) { ... }
onUnknownCommand() { ... }
onMalformedCommand() { ... }
onMalformedCommand(action) { ... }
onIncompleteCommand() { ... }
onIncompleteCommand(action) { ... }
onAmbiguousCommand() { ... }
onAmbiguousCommand(action) { ... }
}
TAMEScript's compiler is single-pass: it parses through the module code once, so if the compiler encounters a player identifier that has not been declared yet, it may need to be prototyped.
Prototyping a player is essentially declaring a player, but with a semicolon after its main declaration instead of a declaration body wrapped in curly-braces ({ }). A parent player to inherit from, if any, will need to be declared here.
If you have already declared a player as a prototype (or with a declaration body) and wish to add to it later in code, you'll need to extend it using the extend keyword. When using extend, you cannot change its lineage (parent).
player p_main;
extend player p_main
{
/* ...stuff goes here... */
}