Home    News    Mailing List/irc    Documentation    Download    Screenshots   

Terranova Project - Technical Specification of XML-TN, the client-server protocol

Printable version, click here

Overview

This specification describes the technical side of the protocol used to communicate between the server and client of the Terranova game. This is the protocol for version 0.0.1, see the Battleplan for more information. It is in no sense complete untill the code is fully functional.

Some clarifications

XML

The choice of XML is a simple one: it's an open standard that's designed to be robust. This fact lends itself naturally to an open-source project. One of Terranova's objectives is to use XML in various ways to provide media content and make a game out of that. XML is a markup language for describing content of any kind. It has been used in word processing, web pages (XHTML) and other protocols (XML-RPC).

XML and SVG

Since graphics are stored on the server, the obvious choice would be to send embedded SVGs inside an XML protocol. However, in providing services for other types of SVG or XML-TN clients, the SVGs will be stored on a webserver and links to the SVGs will be sent instead. For example, an SVG-enabled webbrowser can still view the SVGs in the picture archive on the webserver.

BNF of XML-TN

Here's a draft version of a server-side XML-TN BNF. The map protocol should be usable, the rest needs more work after the 0.0.1 release is done. Here's the client-side XML-TN BNF. DTDs will follow later.

Order of a client-server stream

1. A client connects successfully to the server:
client sends:

<xml-tn header>
   <hello />
</xml-tn header>

the server sends an acknowledge with a copy of the command:

<xml-tn header>
   <ack>hello</ack>
</xml-tn header>



or an error:
<xml-tn header>
   <err>hello</err>
   <msg>server shutting down in 5 minutes, try again later</msg>
</xml-tn header>


2. The client asks for the map and a viewport:
client sends:

<xml-tn header>
   <map />
</xml-tn header>

Server responds with a map stream (See BNF, XML-TNS clause with XML-MAP in it):
<xml-tn header>
   <ack>map<ack/>
   <map>
      <dim>
         <x>8000</x>
         <y>6000</y>
      </dim>
      <ent>
         <id>1</id>
         <x>2000</x>
         <y>500</y>
         <bhr>1</bhr>
         <svg src="http://foo.bar/fred-move-1.svg" />
         <svg src="http://foo.bar/fred-move-2.svg" />
         <svg src="http://foo.bar/fred-move-3.svg" />
         <bhr>2</bhr>
         <svg src="http://foo.bar/fred-pickup.svg" />
         <bhr>3</bhr>
         <svg src="http://foo.bar/fred-frozen.svg" />
      </ent>
      <ent>
         <id>1000</id>
         <x>2075</x>
         <y>575</y>
         <bhr>0</bhr>
         <svg src="http://foo.bar/gem-1.svg" />
         <bhr>1</bhr>
         <svg src="http://foo.bar/gem-inventory1.svg" />
      </ent>
   </map>
</xml-tn header>
The mapstream contains the setting of the first scene; suppose we have an entity Fred which starts moving around a bit which walks to a gem lying before him, picks it up, looks at it and is struck by some kind of frost spell. I'll explain how this info is present in the map.
If we look at the XML-TN code we see an acknowledge of the map command followed by a map tag. The total dimensions of the map are 8000 pixels in width and 6000 in height (between dim tags). Next is the Fred entity (ent tag) with an ID of 1. It must be placed on a position (relative to the top-left corner of the map) x,y=2000,500 to begin with. It has 2 behaviours (bhr tags) with values 1 and 2. Suppose, the client has a database of behaviours where behaviour 1 means 'movement which consists of pausing between each frame according to the velocity which will be sent later on'. The 3 svg tags which follow, contain the framesequence which repeats itself. On a sidenote, the server will send updates in translational velocity and rotation which will make the entity move towards the gem. To make Fred pick up the gem, the server will send some XML-TN stream with a behaviour 2 tag in it, which will tell the client that it must use the frames in the sequence, in this case only 1 frame with SVG image 'fred-pickup.svg' .
OK, back to the map code. The next entity is the gem itself. It has an ID which is 1000. Items just lie on the map and the gem lies on it at position x,y=2075,575. It has a behaviour 0 with only one SVG image which is the appearance of the gem on the map. It can apparently be picked up by a player character because the second behaviour contains an image of what it would look like on an inventory screen.

Finally the client ask for an initial viewport:

<xml-tn header>
   <viewport />
</xml-tn header>

Server responds with viewport line (See BNF):
<xml-tn header>
   <ack>viewport<ack/>
   <viewport>
      <x>1800</x> <y>300</y>
   </viewport>
</xml-tn header>
The viewport contains the x,y coordinate of the upper left corner of the client's viewport relative to the map's origin (hacked clients with a larger screenresolution can see no more of the map than the a regular client since the client needs to send the SVGs of the rest of the map first.)

3. Future development: Client sends commands to the server and vv.:
Note: this is not part of protocol version 0.0.0
Later on the client or server will send updates of changes of behaviour in entities or changes in velocity or rotation, for example a book gets picked up and it's behviour changes from 2 (lying on the map) to 3 (in inventory). Behaviour can also be used to describe a sprite's random moves to the client in combination with the SVGs already stored there. To prevent that a hacked client can be more advantageous in the game, the order of sending updates is: do stuff in client -> ask server -> server sends response -> update client. Another thing is that acknowledged responses from the server always contain the command which the client sent for. If the server sees the need to update the client without receiving a command it puts a <cmd /> string in it. This can happen for various reasons, for example, a flower sprite needs to change its behaviour (and thus its appearance in the client) because it starts raining.

Open issues and ideas

  • Sending a map checksum for comparing against the client-cached map when loading a game
  • Usefulness of having prefixes for unique id's. For example, s12 is a sprite, p3 is a player character etc.
  • More security (eg. man-in-the-middle attack)
  • compression and/or encryption of datastream
  • Sending the whole world map at once will probably leave the client busy for too long. A solution would be to send more pieces of the map once the viewport of the client encounters new terrain types or entities. These should be server-side, so that a hacked client doesn't know too much.
  • Before ending a protocol stream with </xml-tn header> clients and servers can embed debugging messages there in a description tag.
  • Use of a custom xml-tn header or a real xml header (it's custom for now)
  • built-in backwards compatiblity layer for future versions
  • ...

Contact

Author: Johan Ceuppens (jceuppen at sourceforge)

Terranova Project - Last update: Apr 6 2003