Atlas protocol proposal

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

Connection

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

Connection consist of transfer units.

Example:

                
                  
                  
                  
                
         


Transfer unit

Transfer unit: 0 or more operations. This is transferred as one block and then interpreted by Atlas library. It's surrounded by -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:

                
                  
                  
                
         


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):

                 
                        123
                        777
                        
                        change
                        
                          777
                          40
                        
                 
         
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:

                
                  move
                  
                         9899
                         1112.3,3,0
                  
                
         
Answer from server (character is somewhat drunken):
                
                  sight
                  
                         9899
                         1112.2,3.2,-0.1
                  
                
         


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:

                 magicworld.org:funny_ape_123#arm#thumb
                 magicworld.org:98123#8#1
                 98123#8#1
                 Inside '98123' entity description: #8#1
         


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):

                
         

If server omits content, then client can assume our real world calendar.

Example:

                

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:

                
                  
         


Entity

Entity can be description for operation, object or type description. It can include id, type, instance, loc, contains, stamp and attr tags.

Example:

                
                        Brian_789
                        human
                        
                          backpack_322
                          sword_1322
                        
                        
                          house_879
                          12.4,7.4,3.5
                        
                        122143.5
                        40
                
         

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 tag.

Example:

                
                  talk
                  
                         What has happened there?
                  
                
         


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:

                 human
         


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:

                 
                        house_879
                        12.4,7.4,3.5
                 
         

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:

                 
                        backpack_322
                        sword_1322
                 
         


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:

                
                  path1989.24
                  tree11989.24
                  Joe1233011.43
                
         

When querying include stamp from cache, so server can send only changed parts, exmpale:

                look
                  
                         Joe123
                         2811.99
                  
                
         

Example answer from server:

                sight
                  
                         Joe123
                         3011.43
                         shield847
                  
                
         


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:

                187
                -87.09
                
                2.56
         
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:

                 40
         

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

Example:

                
                  Give entity some name!
                  1.0
                
         


Aloril