Atlas protocol proposal

Connection (<atlas>) One login session
Transfer unit (<msg>) Delimits blocks transferred
Operation (<op>) One action or info
Id (<id>) Identifier
Routing (<from>, <to>) Who sent, who received operation
Time (<time>) Time of operation
Entity (<ent>) Id and attributes for operation, object or type entity
Type (<type>) Parent type (attributes inherited from)
Instance (<instance>) Entities that inherit attributes from this entity
Location (<loc>) Location of entity
Contains (<contains>) Objects that use this entity as reference system
Stamp (<stamp>) Stamp (when object changed or something similar)
Attribute (<attr>) Name and value for attribute

Connection

Connection: Login, play session, logout
Version tag contains Atlas protocol version this uses.
<atlas> surrounds whole connection and it could be saved to file as a XML document.

Connection consist of transfer units.

Example:

      <atlas version="0.2">
        <msg/>
        <msg/>
        <msg/>
      </atlas>
    

Transfer unit

Transfer unit: 0 or more operations. This is transferred as one block and then interpreted by Atlas library. It's surrounded by <msg> -tag and thus can be interpreted as XML document too.

Each msg might contain serial number. Communication library will use it to request retransmission of msg if needed. Retransmission is requested when gap in serial number or missing msg is detected.

Example:

      <msg no="1">
        <op/>
        <op/>
      </msg>
    

Operation

Operation consist of id tag and arguments for operation.
It can include optional from,to and time tags.
It can include optional no and refno attributes.

Example (body of character '123' hit you and now you have 40 HP):

       <op no="200">
         <from>123</from>
         <to>777</to>
         <time s="16874695545.78">542-12-30 17:44:01.78</time>
         <id>change</id>
         <ent>
           <id>777</id>
           <attr name="HP" type="int">40</attr>
         </ent>
       </op>
    
Note that mind of character '123' likely sent something like: "swing this sword that way".

no and refno -attributes:

Client can set this to some number (likely serial no starting from 1) and when server answers it might include in answer refid attribute to tell with operation it's answering.

Example:

      <op no="100">
        <id>move</id>
        <ent>
          <id>9899</id>
          <loc><id>11</id><coords>12.3,3,0</coords></loc>
        </ent>
      </op>
    
Answer from server (character is somewhat drunken):
      <op no="1234" refno="100">
        <id>sight</id>
        <ent>
          <id>9899</id>
          <loc><id>11</id><coords>12.2,3.2,-0.1</coords></loc>
        </ent>
      </op>
    

Id

Complete format for id tag is:
host_name:id_string#sub_id#sub_sub_id
There could be 'any' amount of sub ids.
host_name part is optional if it's server where connection has been made.

Id strings cannot contain ':' or '#' characters.

Examples:

       <id>magicworld.org:funny_ape_123#arm#thumb</id>
       <id>magicworld.org:98123#8#1</id>
       <id>98123#8#1</id>
       Inside '98123' entity description: <id>#8#1</id>
    

Routing

From tag tells where operation originates.
To tag tells target for operation.
These tag have same content as id tag.


Time

Time tag tells when operation happened.
It has s attribute that tells in seconds current time.
It might have sadd attribute that tells how much in the future operation should happen.

Content tells current time using format similar to ISO format: YYYY-MM-DD hh:mm:ss (why not exactly same: because calendar might be totally different).

Example (unusual year and month):

      <time s=372225899200.7>12007-103-05 47:05:45.7</time>
    
If server omits content, then client can assume our real world calendar.

Example:

      <time s=62034870000.45/>
    
sadd attribute: client (and maybe server too) can specify operation time into future.

Example: move sword here, then move it there after 0.X seconds, then move it here after 0.X+0.Y seconds etc... (time fields here)

XML Example:

      <op>
        <time sadd="0.1"/>
        <id>move<id>
        <id>sword_88</id>
        <loc><id>joe_123</id><vector>0.5,0,0</vector></loc>
      </op>
    

Entity

Entity can be description for operation, object or type description. It can include id, type, instance, loc, contains, stamp and attr tags. Example:
      <ent>
         <id>Brian_789</id>
         <type>human</type>
         <contains>
           <id>backpack_322</id>
           <id>sword_1322</id>
         </contains>
         <loc>
           <id>house_879</id>
           <coords>12.4,7.4,3.5</coords>
         </loc>
         <stamp>122143.5</stamp>
         <attr name="HP" type="int">40</attr>
      </ent>
    

Id

Id describes entity uniquely or if id is not given then entity is temporary.

Temporary entity means that you can't refer to it in the future or in the other words it's 'available' only inside <op> tag. Example:

      <op>
        <id>talk</id>
        <ent>
          <attr name="say">What has happened there?</attr>
        </ent>
      </op>
    

Type

Parent type: Entity inherits attributes from parent type. It can then override them, remove them or add new attributes. There might be more than one parent type (multiple inheritance).

Example:

       <type>human</type>
    

Instance

Lists all entities that have this as parent type.


Location

Location of entity. Id tag contains id for entity that acts as reference for location. This entity is not necessary inside or on top of reference object.

Coords tag contains coordinates (usually x,y or x,y,z)

Instead of 'coords' it might be 'vector': then coordinates are relative to op receiver.

Example:

       <loc>
         <id>house_879</id>
         <coords>12.4,7.4,3.5</coords>
       </loc>
    
More about movement here.


Contains

Lists things that use this entity as reference system. List may not be complete (you don't notice/see everything; for admin client it might still be complete)

Example:

       <contains>
         <id>backpack_322</id>
         <id>sword_1322</id>
       </contains>
    

Stamp

In sight operations you usually receive list of entities containing id and stamp. You can them compare stamp with your stamp from local cache and then requery about that object if they differ (it has changed clothing, for example)

Example:

      <contains>
        <ent><id>path1</id><stamp>989.24</stamp></ent>
        <ent><id>tree1</id><stamp>1989.24</stamp></ent>
        <ent><id>Joe123</id><stamp>3011.43</stamp></ent>
      </contains>
    
When querying include stamp from cache, so server can send only changed parts, exmpale:
      <op><id>look</id>
        <ent>
          <id>Joe123</id>
          <stamp>2811.99</stamp>
        </ent>
      </op>
    
Example answer from server:
      <op><id>sight</id>
        <ent>
          <id>Joe123</id>
          <stamp>3011.43</stamp>
          <contains><id>shield847</id></contains>
        </ent>
      </op>
    

Attribute

This is generic method for describing entity attributes. It has optional 'name' -attribute for naming entity attributes.

It has optional 'type' -attribute for giving type of entity attribute. If type is not given, then it's assumed to be same type as attribute with same name in parent entity type. If it's not given anywhere in entity type hierarchy, then it's assumed to be string.

Valid types: int, float, string, list, range, id, attr, ent, delete, Xlist
list, range, Xlist, attr, ent, delete types will likely change after discussion at scripting@worldforge.org!

int: integer (likely 32 bit signed int, though it might be 64 bit too)
float: floating point number (likely float or double)
string: arbitrary string (should not contain \0)
list: contains list of arbitrary types; surround each element with type tag:

      <int>187</int>
      <float>-87.09</float>
      <list/>
      <attr name="height" type="float">2.56</attr>
    
range: start-end
id: see id tag
attr: sub attribute
ent: attribute list
delete: parent type entity has this attribute, but this doesn't
Xlist: list of one type: intlist, floatlist, stringlist or rangelist

Example:

       <attr name="HP" type="int">40</attr>
    

There should be root type entity for all objects that defines types for common attributes.

Example:

      <ent>
        <attr name="name" type="string">Give entity some name!</>
        <attr name="health" type="float">1.0</>
      </ent>
    

Aloril
Last modified: Mon Jul 5 17:52:57 EEST 1999