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 consist of transfer units.
Example:
<atlas version="0.2"> <msg/> <msg/> <msg/> </atlas>
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>
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 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>
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>
<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>
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>
Example:
<type>human</type>
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.
Example:
<contains> <id>backpack_322</id> <id>sword_1322</id> </contains>
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>
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
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>