YO protocol V1.2 ================ The YO (Yell at Object) protocol defines the format and content of messages that may be passed between severs on a distributed MUD. It does not ferry objects around, as the OIF protocol does, but instead defines the messages that may be passed between objects. COOLMUD users and programmers do not need to know the YO protocol to program or use COOLMUD. This document is intended for people who want to know the internals of the COOLMUD system. YO packets consist of 7 parts: the message id, age, player object, from object, to object, message, and arguments. Any object can send any other object a message, but it must be directed to the appropriate server. Any messages which do not conform to this format may be silently discarded. Here's a dissection of a typical YO packet: 3245 0 #3@joemud #7@joemud #9@fredmud "tell" { 1 "howdy" } ^ ^ ^ ^ ^ ^ ^ | | | | | | | msgid age player from to msg args Msgid ----- This number uniquely identifies the message, as designated by the _sending_ server. Message id's are usually 32 bit ints, generated incrementally. If MAXINT is exceeded, the sending server may start again at zero. Each server is only responsible for ensuring uniqueness of the messages it sends. Reply messages use the same msgid as the message they are replying to (see Reply Messages, below). Age --- This is an integer field representing the depth of messages which have been passed. It's designed to prevent two servers spamming each other by sending mutually recursive messages. Each execution thread starts with an age of 0, which is incremented every time a new message is generated. If the age reaches MAX_AGE, the error E_MAXREC is raised and the message is discarded. Generally, the 'age' of a message is only set to zero by the server when a new 'parse' message is generated (ie., for each player command). Player ------ This is the object id of the player who is performing the current action. From ---- This is the object which sent the message. To -- This is the object to which the message was sent. Msg --- This is a string containing the name of the message. Messages should be a valid identifier: one word, no spaces, beginning with an alphabetic char or '_', subsequent chars being alphanumeric or '_'. Args ---- These are the arguments to the message, represented as a list. Reply Messages ============== All normal messages must receive one of two replies: "return" - normal return "raise" - an error occurred One of these two messages should be generated for each normal message sent. Reply messages do not need to be replied to, obviously. The reply message should have the same msgid and age as the sent message. Return ------ Execution completed normally, and a return value is indicated. There should only be one argument, which is the return value. Raise ----- An error condition has occurred in the 'To' object. There are two arguments to this message: the error value, and a traceback from the object giving diagnostic information. An object which receives this message as a reply can choose to continue, or to halt execution. If execution is halted, it should send 'raise' to its caller, and add its diagnostic information to the traceback string. DATATYPES in YO 1.2 =================== There are five basic datatypes in YO messages: number (integer), string, object, lists, and errors. NUM --- Numbers are integer values represented simply by their ASCII representation. No decimals or exponents are allowed. The "msgid" and "age" fields are examples of number values. Examples: 5 -3 0 1000 STR --- Strings are enclosed in double quotes, and may be any length. Strings may also contain embedded double quotes using the backslash character (\"), embedded tabs ("\t") or newlines ("\n"). The literal " and newline characters cannot be used. "foo" "The Rain In Spain" "They call me \"The Woodmaster\", son." Notice the embedded quotes in the last example. This would evaluate to: They call me "The Woodmaster", son. The "message" field of the YO packet is an example of a STR value. OBJ --- Object values consist of two parts: an object id, and a server id. Object values are preceeded by a # sign, and an '@' sign separates the objectid and server portions, like so: #5@coolmud The object id is a number, and the serverid is the name of the server. Each server maintains a mapping between these names and the IP address and YO port of the server. Two communicating COOLMUDs must agree on the names of all servers involved. The "player" "from" and "to" fields of the YO packet are examples of object values. LIST ---- A list value is a heterogenous collection of any of the 5 data types. Braces surround the elements of the list, and a number after the opening brace indicates the length of the list. Spaces separate the elements of the list. Each element's type is determined implicitly by the first character: a digit indicates a NUM value, a doublequote indicates a string value, a # sign indicates an object value, a brace indicates a list value, and an E indicates an error value. The following are examples of lists: { 5 1 2 3 4 5 } { 2 #3@coolmud #10@coolmud } { 3 "abc" "def" "ghi" } { 2 { 1 "foo" } { 1 "bar" } } { 5 1 "two" #3@coolmud E_NONE { 1 "foo" } } Notice that values of different types may be freely intermixed, as in the last example, and that lists may contain other lists. The arguments portion of the YO packet is an example of a list value. Note: Lists are the only type whose YO representation differs from their COOL representation. In COOL, items in a list are comma-separated, and there is no leading length value. ERR --- Error values are represented as an identifier with E_ as the first two characters. The following is a list of errors currently recognized by YO 1.2: E_NONE no error E_TYPE type mismatch E_RANGE range error E_DIV division by zero E_INVIND invalid indirection E_MAXREC maximum recursion exceeded E_METHODNF method not found E_VARNF variable not found E_STACKUND stack underflow E_STACKOVR stack overflow E_FOR for variable not a list E_INTERNAL internal server error Stephen White 16 July 92