mpMUD's Output System(s) Explained

June, 2001

--- Warning -------------------------------------------------------------------

This document describes the current ways output works in mpMUD, and may become incorrect over time; it also makes little distinction between that which is part of mpMUD's core and that which is part of the set of modules currently in use.

--- Overview ------------------------------------------------------------------

   Internet                    |  mpMUD: IO system
                               |
+-----------------+            |  +-------------+  +-----------------+
|   Text clients  |<---Telnet--|->|             |--| MTerminal::ANSI |
+-----------------+            |  | MConnection |  +-----------------+
                               |  |             |
+-----------------+    Telnet  |  | subclasses  |  +-----------------+
| Special clients |<-----or----|->|             |--| MTerminal::XML  |
+-----------------+    others  |  +-------------+  +-----------------+
                               |    /\         |         +--------------------+
                               |    ||         +-------->| User interface     |
                               |    |+------------------<| defined by modules |
                               |    |                    |                    |
                               |    |                    +--------------------+
                               |    |                             |   /|\
-------------------------------+----|-----------------------------|----|-------
mpMUD: world system                 SX                            |    | 
                                    |                             |    |
                      +-------------|--------------+              |    |  
                      |             |              |              |    |  
                      |             |              |              |    |  
                      | +-----------|------------+ |             \|/   |  
                      | |   Methods | defined by | |    +---------------------+
                      | |           |    modules | |    | Command interpreter |
                      | | +----------+           |<---->| (is a module)       |
                      | | | desc_gen :           | |    +---------------------+
                      | | +----------+           | |
                      | +------------------------+ |
                      | MObject (world objects)    |
                      +----------------------------+
--- An example ----------------------------------------------------------------

Let's take as an example the text "Marn sits down on the chair." and see how it is generated by the command 'sit'.

First, the player controlling Marn types 'sit'. This text comes into mpMUD, most likely over some type of TCP/IP connection. It is received by an instance of a subclass of MConnection, and an instance of MTerminal splits it into lines and sends it back to the connection, which then passes it on to the handler for the current state of the connection.

A connection may be 'attached' to an object[1]; this relationship causes output sent to the object to be passed on to its connection(s), and connections may manipulate the object in various ways.

Specifically, the connection in our example is currently in the 'command' state, which means input lines are passed to the command interpreter, which is defined in a module.

The command interpreter will run the code that defines the command 'sit'.

The 'sit' command does:
  $self->nact('<self> sit<self!s> down <target.prep> <target>.',
    target => $into);

(This is not the best approach, as there is a new system which allows such messages to be produced in a form more useful for NPC programming. See later section.)

The 'nact' method uses a string in a markup language known as 'desc_gen', after the function that parses it. This name is now incorrect, as the function used to be a method that generated text descriptions for specific viewpoints; now, it generates SX which is equivalent to the string.

For example, the desc_gen string:

  '<self> sit<self!s> down <target.prep> <target>.'
 
 becomes the SX:
  
  ['obj', {oid => '48', part => 'nphr'}], ' sit', ['if', {}, ['test', {}, ['obj', {oid => '48', part => 'is'}]], ['then', {}], ['else', {}, 's']], ' down ', ['obj', {oid => '92', part => 'prep'}], ' ', ['obj', {oid => '92', part => 'nphr'}], '.'

or equivalent XML:

<obj oid='48' part='nphr'/> sit<if><test><obj oid='48' part='is'/></test><then/><else>s</else></if> down <obj oid='92' part='prep'/> <obj oid='92' part='nphr'/>.

The 'nact' method then calls the 'sact' method with the above SX structure.

"sact"'s job is to send a description of an action to all nearby objects. For each such object, it calls the 'send' method.

The 'send' method passes on its argument to all connections attached to the object.

The connection filters the SX, mainly converting object references into appropriate words for the viewpoint of the object that received the message.

After processing, the connection passes the SX to its associated MTerminal object, which turns it into a sequence of characters suitable for sending over the Telnet connection. Current MTerminal classes are MTerminal::ANSI (conventional text-mud type output, with ANSI color), and MTerminal::XML (which just converts the SX into XML, and is useful mainly for debugging and the possibility of a custom client).
 
The MTerminal object then passes the text back to the MConnection, which is most likely a MConnection::Telnet, which sends the text over the socket after escaping IAC (255) codes as required by RFC 854.
 
[1] When the term 'object' is used here, it refers not to Perl objects in general, but rather instances of the class MObject, also known as 'world-objects'.

--- SX ------------------------------------------------------------------------

SX is a representation of XML as a Perl data structure. It can represent all of the information contained in an XML document, except <?xml?> and <!...>. The format of an SX element is, in Perl syntax:

  [
    'elementName',
    {'attributeName', 'attributeValue', },
    'content',
    'content',
    'content',
  ]
  
where 'content' can be text or another SX element.

Note that SX elements are not blessed, though there is no fundamental reason they cannot be; I consider the operations for manipulating SX to be simple enough that there is no need for SX elements to be objects.

In some parts of mpMUD, Perl objects are used inside SX elements. This prevents direct conversion to XML, but is not a problem for XML output because postprocessing eliminates the objects.

--- NPCs, Custom Clients, and Action Messages ---------------------------------

mpMUD has a new system for action messages which allows the production of output more useful for NPCs and specialized clients. This mainly consists of the 'acti' (action info) SX element.

The 'acti' element can have two attributes, 'type' and 'subtype'. These define what the action was. The 'type' is the general category of the action; for example, 'motion', 'attack' or 'speech'. The 'subtype' is the specific action. 

To specify what objects are involved, the content of the 'acti' element consists of 'obj' elements. Each one must have the attribute 'role', which I hope does not need explaining, other than that it is a string.

The typical processing of 'acti' is that it is replaced by an action description using desc_gen, but this will eventually be overridable for receivers which can use the direct information.