Getting Started News RSS Feed Screenshots Documents Downloads Developers FAQ Lists Forums Links
Home Documents Code Breakdown Source Code Wiki GIT Web Bugs

Protocol Discussions for Version 0.4

Unlike previous versions of the protocol, the version 0.4 will be total specified in an XML specification. The main purpose of this document is to collect ideas until they are fully implemented in the XML specification.

THIS IS NOT A PROTOCOL SPECIFICATION!

Currently in tp03

The current version of the protocol currently has the following features. As tp04 is being built on top of tp03 it will also include these features.

Dynamic Orders
Thousand Parsec servers can define new orders and clients can automatically discover these orders and show the user quite a bit of detail about what arguments should be given to the order.
Comprehensive Design Support with tpcl
Designing things is a very important part of most empire building games. tp03 includes support for building designs out of "components", these components dynamical describe their properties and requirements. They can be either calculated on the server or calculated on the client. It is quite possible to have components which require other components, forbid other components via either specific exclusion
Dynamic Resources
Resources which are used for doing things are dynamical described by the server.
Message and Board system
Support for a wide variety of messages including referencing objects related to a message (IE This message came from this object). Servers can also have both private and public boards.
Partial Design Discover
Although no server currently implements a system where as you can only discover partial information about enemy designs, this option is total supported.

New to tp04

Full XML protocol specification
The protocol will be completely specified in an XML document. This will allow more dynamic languages (such as Python, Ruby and PHP) to read in the protocol document and dynamical create the correct data. This doesn't mean our good documentation is going away (for those people who want to implement it the "hard way"), instead it will be more accurate and contain better linking, lot more useful tables and even an index. The documentation will all be generated using XSLT from the protocol XML document so it will also always be current.
Meta Protocol definition
A definition on how to talk the "meta protocol", IE talking to the metaserver and find local games will be specified. It will be almost identical to the current protocol specified separately.
Filter Support
The protocol will support filters such as encryption and compression (or even a 32bit aligned strings filter), there will be a way to negotiate which filters to use.
Difference Support
The protocol will include (and servers will be required to support) a proper method for downloading "what has changed" lists. This will be extended from the current "get id sequence" stuff but made so it doesn't require downloading every single ID in the universe to find out the differences.
Dynamic Objects
Like how servers can define new a interesting order types, with tp04 servers will also be able to do the same for objects. A wide variety of object properties types will exist, from Graph like properties to just plain strings. This will rapidly allow many more advanced rulesets to exist.
Old Data support
As a side effect of Dynamic Objects, object properties will be able to be "aged". This means that if you could detect/determine the value in the past, but can't determine the value now, the client will be able to understand this.
Multiple Instruction queue support
As another side effect of Dynamic Objects, objects will be able to have multiple instruction queues. These will allow for things like "standing battle orders" and "research queues" (and probably plenty of other things I can't think of at this very moment).
Media support
The current "media support" is just a hack in tpclient-pywx. The dynamic objects will allow proper specification of what media should be used for objects and such.
Research support
The protocol will include support for figuring out which "Research options" are available. It will support a wide range of research methods too (from researching for a specific object, to researching researching in a general area).
EOT Support
There will be support for things like saying "I'm Done" and "Please end the turn now.". This will mean we are no longer just stuck with the EOT at a certain time problem like in tpserver-cpp (or when admin runs a special program like in tpserver-py).
Frame Type Versions
Support for changing frames (in a backward compatible way) separately. This will allow better updates of the protocol without having to do a complete new version.

Server Location (Meta) Protocol

There are two parts to server location. The first is finding servers on a local network, for this ZeroConf is used. The second is finding servers on the Internet, for this a metaserver is used. The protocol used in both situations is basically the same, the transport mechanism is just a little different.

The unit of discovery is not "a server" as one might first think, rather it is "a game". Each game has a set of "locations" which is can be found at.

"A game" is describe by the following properties

Required Parameters

ln Long (human) name of the game (this must be globally unique!)
tp comma seperated list of version strings (0.3, 0.2)
server version of the server
servtype server type (tpserver-cpp, tpserver-py)
rule ruleset name (MiniSec, TPSec, MyCustomRuleset)
rulever version of the ruleset

Note: The long name of a game should never change. Hence the long name can be considered immutable (and the metaserver will assume this property).

Optional parameters

plys 1 number of players in the game
cons 2 number of clients currently connected
objs 3 number of "objects" in the game universe
admin 4 admin email address
cmt 5 comment about the game
next 6 unixtime stamp (GMT) when next turn is generated
ln 7 human readable name of the game
sn 8 short name (computer readable) name for the game
turn 9 the current turn the game is at
prd 10 the time between turns in seconds

Location Parameters

A location is specified as a tuple of:

protocol tp, tps, tphttp, tphttps
dns A resolvable name of the server
ip Resolved ip address of the server
port The port of the server

Local LAN Discovery

Local LAN discovery is being done with ZeroConf MDNS. Each server should advertise a record PER GAME (per location). The location details are automatically discovered. The required and optional parameters should be found in the TXT record.

The service name should be the "ln" parameter. The "sn" should then be sent as an optional parameter.

Internet Discovery

Registration

There are two ways to register with a Metaserver. The primary Thousand Parsec Metaserver can be found at metaserver.thousandparsec.net.

When registering with a metaserver you must also send a "key". If the game with this (long) name has never been seen before the key will be stored, the key is then checked for all updates for that game (long) name to take effect. (You should think of the "key" as a password for a given short name.)

The server should send a registration/update request at least once every 10 minutes. A server which hasn't send a request in the last 10 minutes will be removed from the list of known servers. A server should send a registration/update request no more then once every 5 minutes.

HTTP Registration

To register a new game you must send either a HTTP GET or POST request with the require parameters.

To encode locations in a game you append a number to the text fields, IE 

type0, dns0, ip0, port0 - details for first location
type1, dns1, ip1, port1 - details for second location

An example (using get) would be the following, url

One request should be sent for each game. The HTTP Registration supports HTTP/1.1 keep alive, so they can be sent in one connection.

On a protocol or other HTTP error, the metaserver will return a plain text response with the appropriate error code. (IE 404 Not Found.)

Other errors should be returned using a tp04 Fail frame.

TCP Registration

To register a new game you must connect to the metaserver on port XXXX. There you send a tp04 Sequence frame describing the number of games you are about to send. You then send the tp04 Game frames.

UDP Registration

To register a new game you send a single UDP frame to the metaserver on port XXXX. The UDP frame will contain a single tp04 Game frame.




Discovery

The server will return a Sequence frame telling the number of "Game" frames to come. Game frames are described as follows,

  • a string, (ln) Game (long) name
  • a string, (key) Empty on receive
  • a list of Strings, (tp) List of protocol versions supported
  • a string, (server) Server Version
  • a string, (servtype) Server Type
  • a string, (rule) Ruleset Name
  • a string, (rulever) Ruleset version
  • a list of,
    • a string, (type) Connection type (tp, tps, ...)
    • a string, (dns) Resolvable DNS name
    • a string, (ip) IP Address
    • a UInt32, (port) Port to connect on
  • a list of,
    • a id, Optional param id
    • a string, Optional param string value
    • a UInt32, Optional param int value

HTTP Discovery (Optional)

To get the details about which servers exist the client should send a HTTP Get request to the metaserver.

An example of this is "http://metaserver.thousandparsec.net/?action=get".

On success the server will return a HTTP response with the data body being tp04 frames describing the current games. On a protocol or other HTTP error, the metaserver will return a plain text response with the appropriate HTTP error code. (IE 404 Not Found.) Other errors should be returned using a tp04 Fail frame.

TCP Discovery

To get the details about which games exist the client should connect to the metaserver on port XXXX. It should then then send a Get Games frame.

Formatted Strings are exactly like normal strings but use the structured text method for formatting their contents. For a complete description of structured text please see the following document. This allows display of color, underline, super/subscript and much more. It is also easy to convert to plain text or HTML.

Frames which have been added

??Get Object Description
??Object Description
??Get Object Description IDs
??Object Description ID Sequence
??Get Games
??Game
??Set Filters
??Get Research Items
??Research Item
??Get Research Item IDs
??Research Item ID Sequence
??Player Finished/Request Turn End

Frames which are obsolete

Frames which have changed

-Get ID Sequence
1Fail
26Available Features
40Player Data

Frames which haven't changed

-Get with ID
-Get with ID and Slots
-ID Sequence
0Ok
2Sequence
3Connect
4Login
5Get Objects by ID
7Object
8Get Order Description
9Order Description
10Get Order
11Order
12Insert Order
13Remove Order
14Get Time remaining
15Time remaining
16Get Boards
17Board
18Get Message
19Message
20Post Message
21Remove Message
22Get Resource Description
23Resource Description
24Redirect
25Get Features
27Ping
28Get Object IDs
29Get Object IDs by Position
30Get Object IDs by Container
31List of Object IDs
32Get Order Description IDs
33List of Order Description IDs
34Probe Order
35Get Board IDs
36List Of Board IDs
37Get Resources IDs
38List Of Resources IDs
39Get Player Data
41Get Category
42Category
43Add Category
44Remove Category
45Get Category IDs
46List Of Category IDs
47Get Design
48Design
49Add Design
50Modify Design
51Remove Design
52Get Design IDs
53List Of Design IDs
54Get Component
55Component
56Get Component IDs
57List Of Component IDs
58Get Property
59Property
60Get Property IDs
61List Of Property IDs
62Account Create

Protocol "Filter" Negotiation

Filter negotiation will be performed in the following way.

  • Extra Id's will be added to the features frame to add different filters.
  • The client will choose which filters are used.
  • Server has "right of refusal".
  • Filter negotiation can not be pipelined.
  • New "Set Filters" frame will be created.

An example session would be as follows, 

Client  -- connect ----->  Server
        <- okay ---------
        -- get features >
        <-- features ----
        -- set filters ->
        <-- okay --------
 --- filters are activated here ---

If SSL filter is used it should always be the outer most filter. There should only be one compression filter in use.

EOT Notification

A new frame will be added to allow clients to request that a turn be ended. The Time Remaining frame will had a new field added which explains why this Time Remaining frame was sent.

This should allow the following cases,

  • EOT when everyone finished.
  • EOT at timeout.
  • EOT after short timeout when majority finished.
For example, say 6 players are playing. After 4 players submit "Finished" frames, the other players get a "Time Remaining frame" with, say, 2 minutes left and an ID which says "All other players finished".

Media

The Game frame will be extended to have a "base media" URL. All other media URL that are sent will be relative to this URL.

Each media server will provide a "media.gz" which includes a file listing as follows 

<filename> <size> <last modtime> <checksum>
URLs will not specify the file type. It is up to the client to choose the file type. (For example PNG, MNG, etc)

Difference support

The Get ID's frames will have a "from" field added. This is a SInt64 which is the timestamp to get changes from. If it is -1 then it should be all objects.

It is important to note that the Get ID's frame when called with a valid time stamp, the server should send ID's for objects which may have been destroyed or no longer exist.

Frame type Versioning

The TP03 header will be changed to a "TP<protocol version byte>< frame version byte>". The bytes are in binary not ASCII.

As new versions of frames are added the frame version byte will be incremented. (They all start at zero for the first release of a major protocol version.) A frame will not change in an non-backwards compatible way within a major protocol.

Although this frame type versioning was only introduced in tp04 protocol. The method can be used by tp03 clients with a protocol version byte set to 3 and frame version byte set to 0.

Object Parametrisation/Last seen

It was decided that Last seen ended up to not be needed on anything except objects. The new Object parametrisation (as describe in other emails) includes support for Last Seen.

One important property is the Order Queue. Order Queue's will have their own ID which the Order frames will now refer to (instead of using Object ID's). For this to be backwards compatible the default order queue will always have the same ID as the Object ID.

Properties will be grouped.

History Support

History support will wait till tp05.

But should be stored server side in preparation for tp05.

Settable information

Object settable information will be done by sending the full object to be consistent with other things such as Designs and Orders. The object parametrisation will describe if fields are user modifiable.

Virtual Hosting/Game Frames

A new "Get Games" frame will exist. This will return the same frames which the metaserver currently returns.

Virtual Hosting support will use the current @ system. Servers which only support one game should ignore everything after the first @.

Async Frames

If something changes on the server is can send a frame at any time saying so. This is mainly used when a creating a Design might add a new component. (For example, creating a new Torpedo design would create a new Torpedo component.)

Currently only components are on this list (other than the time remaining frames). Once research/technology is implemented, there could be others. I would rather have a set list.

Currently the frames which can appear in an async manner are,

  • Time Remaining Frame
  • Component Frame

Research / Technology Frames

A new frame will be added which describes things which can be researched. The standard get ids, etc frames will be added for these objects. This frame will have at least the following,

  • Name
  • Description
  • Generic Reference System List of things which this technology brings
Each technology which describe which technology it depends on and which technology is an anti-dependency. How these dependencies are described is yet to be figured out.

Object Property Discussion

Locational Properties

These are properties which describe where an object is on a starmap (and where they are going). Things like wormholes could have multiple positions.

Thinking about it, we really only need two: Free space (3d) and "bound". In most cases, we don't need to specify where they are bound to.

So either the 3 int64 position, or a uint32 object id that the object is bound to.

Time properties

Describe which turn something has occured or when something will occur. In turns.

Descriptional Properties

These are properties which are for the players information when making decisions. As far as the client is concerned they don't have any effect on the game. These would include things like "Name", "Description", etc.

Habitation Properties

These are properties which describe if a race can survive at an object. Things like temperature, atmosphere, etc. They are most likely to be found on planets.

Many of these descriptional properties can be edited (like changing a name) without affected the game at all. It might be nice to be able to edit them without sending the whole object.

Resource Properties

These describe what is available to be used/mined/etc at a location. Found generally on planets, asteroid fields,

Goodness Properties

These describe how good X is at doing something. For example production capability or population size.

Order Queues

Currently we only have one order queue. There is no real reason an object couldn't have multiple order queue's.

This could be used for where you want a separate "Build Queue" to an "Action Queue". It could also be used on ships where you have an "Battle Queue" which specifies what the fleet should do in battle (IE Attack hard for X turns, run away).

Another option would be a "Default Order Queue". IE If you wanted new fleets to have a "move to x", "remote mine" default order queue.

I think the client should handling "Order Queue"s which only have one type of order specially.

Maybe order queues could also have a possible "limit" on the number of orders can be put in them.

I was thinking per planet. IE A planet could have the following order queues (on one particular server).

  1. Build Queue - Things to build, Order Types (Build Fleet, Build Infrastructure, Nop)
  2. Priority Queue - What the planet should concentrate on, (Nop, Research, Production, Defence)
  3. New Fleet Queue - What orders are given to a new fleet (Any order valid to a fleet this planet can build - IE Move, Remote Mine, Create Minefield, Merge Fleet.)

We could also have a "hidden" object which could has queues to be use for planet defaults or something.

Each queue specifies (on each object) which type of order is allowed in that queue. (Rather then the current per object order types.)

Maybe order queues could also have a possible "limit" on the number of orders can be put in them.

Not hard to do either. Although most of the time, the limit will be one of these things:

  • - the human player's patience entering the orders
  • - the resources at the object (fuel, supplies (endurance), or other normal resources)
  • - boredom

Property types

Properties also have a general type,

  • Text Property - Just a string, HTML or some other Formatted String, etc.
  • Integer Property - Just a plan number.
  • Range Property - Some type of range, for example the bars in Stars! habitability.
  • Gauge Property - Some type of thing which fills up, like the fuel bars or the cargo bar in Stars!
  • Reference Property - Refers to something else (for example a player, a design, etc)
  • List Property - Lists a bunch of other properties (IE Resources would be a list of reference properties?)
  • Choice Property - Can make a choice of something.

Object Property Definition

Object Frame

  • a UInt32, Object ID
  • a UInt32, Object type
  • a String, Name of object
  • a String, Description of the object
  • a SInt32, Object ID that is this object's parent. -1 On the top level object.
  • a list of UInt32, Object IDs of objects contained in the current object
  • a UInt64, The last modified time
  • x by UInt32 of padding, for future expansion of common attributes
  • Extra data as describe by the Object Description

Object Description Frame

  • Stuff should go here
  • A List of
    • UInt32, Property Group ID
    • A String, Object Property Group Name
    • A String, Object Property Group Description
    • A List of
      • UInt32, Object Property Type,
      • List of UInt32, Object Property Categories
      • A String, Object Property Name
      • A String, Object Property Description
      • ?? UInt32, Number of bytes of "extra" details ??

Each object will have a list of properties groups (which are a list of properties) they have.

The properties will be divided into groups so that multiple properties can be put together, for example to have a property which describes a position 6 turns ago you would have a Time Property and Position property in one group.

Property Types

Each property type has a two parts, arguments which are part of the description and arguments which are different for each object. For example, a range would have a possible maximum, possible minimum - which are part of the description, and each instance of the object has it's own value.

Order Descriptions don't need anything extra - instead everything is specified on the order. Maybe we should do this with Objects too? This would mean that there could be a lot of duplication of data (IE Graph) but would be more flexible.

Positioning

  • Position, Velocity or Acceleration
    • On the Object
      • 3 * Int64, Position of Object
      • UInt64, Object ID this position is relative to
    • On the Object Description
      • None
  • Bound Position
    • On the Object
      • Int32, Object Slot Position
      • UInt64, Object ID that this Object is bound too
    • On the Object Description
      • None

Telling things what to do?

  • "Order Queue"
    • On the Object
      • UInt32, Queue ID
      • UInt32, Current number of orders on this object
      • List of UInt32, Order Type (Description) ID's which are valid in this queue
    • On the Object Description
      • UInt32, Number of the slots the queue

    The "default" order queue (IE The most use queue) should have the same ID as the object it is on. Other order queue's can have any ID but the ID should not be the same as an object ID (as it would conflict with the information above). How servers solve this problem is up to them.

    If Queue IDs are only a UInt32 then you can only have 1 queue per object.

Descriptional

  • Reference
    • On the Object
      • A reference as described by the Generic Reference System.
    • On the Object Description
      • ?Acceptable references?
  • Time (Turn)
    • On the Object
      • A UInt64, The Turn
    • On the Object Description
      • None
  • Time (Real)
    • On the Object
      • A UInt64, A Unix timestamp in UTC
    • On the Object Description
      • None
  • Enumeration (Argument)
    • On the Object
      • UInt32, the actual choice
    • On the Object Description
      • A list of Strings, the text value of the enumeration value
  • Graph
    • On the Object
      • UInt32, the value on the graph
      • UInt32, the current "heading" of the value of the graph
    • On the Object Description
      • Enumeration, the Type of the X axis
        1. Linear
        2. Logarithmic Base 2
        3. Logarithmic Base 8
        4. Logarithmic Base 10
        5. dB (10*log(x^2))
        6. ???
      • A String, the X axis label
      • Enumeration, the Type of the Y axis (same as above)
      • A String, the Y axis label
      • a List of (which are the points on the graph)
        • UInt32, The X value
        • UInt32, The Y value
  • Range
    • On the Object
      • Int64, the value
      • Int64, the current "heading" of the value of the range
    • On the Object Description
      • Int64, Smallest possible value
      • Int64, Largest possible value
      • Int32, Smallest Delta (IE Step Size)
      • Enumeration, a transform type for the value
        1. Linear
        2. Logarithmic Base 2
        3. Logarithmic Base 8
        4. Logarithmic Base 10
        5. dB (10*log(x^2))
        6. ???
  • String
  • Settable String

Examples: 


Planet Description
 0, "Where", "Position and heading of the Planet"
	- POSITION, [], "Position", "Current Position of the Planet"
	- VELOCITY, [], "Velocity", "Current Velocity of the Planet"
	- ACCELERATION, [], "Acceleration", "Current Acceleration of the Planet"

 1, "Resources", "Resources available on the Planet",
	- LIST
		- GRS, [], "Resource", "The Resource"
		- INTEGER, [], "Surface", "Amount of the resource on surface"
		- INTEGER, [], "Minable", "Amount of the resource which can be mined"
		- INTEGER, [], "Availiable", "Amount of the resource which might be mined given better technology"
	- TURNS, "Age", "Age of this information"

 2, "Owner", "Person who owns the Planet",
	- GRS, [], "Player", "Player who owns the planet"
	- TURNS, "Age", "Age of this information"

 3, "Production", "Current production capabilities of the planet."
	- GRAPH, [], "Workers", "The number of workers in factories", 
		Linear, "Workers", 
		Linear, "Production Points per Factory", 
		[[0,0], [10,5], [20, 7], [30, 8], [40, 9], [50, 10]]
	- INTEGER, [], "Factories", "Number of factories on this planet",  
	- INTEGER, [], "Production Points", "Number of production points this planet produces each turn",
	- TURNS, "Age", "Age of this information"

A few actual planets,


0, PlanetType, "Tim's Planet", "Tim's magnificent planet!", [], 11:45am 2006-07-10, 

	- 10000, 10000, 10000, 0, 0, 0, 0, 0, 0

	- 3 [
		- GRS(Resource, 100 - Kryptonite), 100, 400000, 0
		- GRS(Resource, 56 - Uranium), 10, 1000000, 770000
	], 0

	- GRS(Player, 100 - Tim), 0

	- 3, 5,   12, 12,  39, 41

The first line is the stuff for Group 0 (Where) - It says this object was seen last turn at 10000, 10000, 10000 going nowhere. The second line is the stuff for Group 1 (Resources) - It says that there is 100 units of Kryptonite on the surface, while only 10 units of Uranium on the surface. There is also 400,000 units of minable Kryptonite and 1 million units of minable uranium. Lastly there is no more kryptonite I might be able to access but there are 770,000 units of uranium which might be accessible. The third line is the stuff for Group 2 (Owner) - It says that I own the planet. The four line is the stuff for Group 3 (Production) - It says that I'm currently have 3 "Workers", producing 6 points of production per factory. Things are also going well, in the fact that it will soon be 5 workers giving 10 production points per factory. It is also saying that there are 12 factories, but I'm not in line to produce any more. I'm also producing 39 production points a turn (and it soon will be 41). (3*12 != 39 - Maybe I'm getting a bonus production points?). It would probably be displayed in the client like the following,

[+] Where
 Position1000, 1000, 1000[GOTO]
 Velocity0, 0, 0
 Acceleration0, 0, 0
[+] Resources
 KryptoniteSurface: 0, Minable: 400,000, Other: 0
 UraniumSurface: 0, Minable: 1,000,000, Other: 770,000
[+] Owner
 PlayerTim Ansell[MESSAGE]
[+] Production
 Workers
 Factories12
 Production Points39

Fail Frame

A fail frame consists of:

  • a Int32, error code
  • a String, message of the error
  • List of GRS, Describes what the error message refers to
Current error codes consist of:
  • 0 - Protocol Error, Something went wrong with the protocol

    This error it means that your frame header has something which wasn't valid. Specific errors include,

    • Something or rather

    This error is a fatal error and the server can hang up after this error.

  • 1 - Frame Error, One of the frames sent was bad

    This means that the frame header and data was okay, but something else about the frame was invalid.

  • 2 - Unavailable Permanently, This operation is unavailable

    This error means that a request you sent doesn't work on this server (and will not work). An example would be a server which doesn't support Designs.

  • 3 - Unavailable Temporarily, This operation is unavailable at this moment (IE The server is currently overloaded)

    This operation has been temporarily disabled. This means that the server may be overloaded and can't service this request at the moment.

  • 4 - No such thing, The object/order/message does not exist.

    This object does not exist (and probably never will exist). This is useful for returning when the client asked for something silly in regards to your server (IE Maybe your server can only have IDs from 100-400, and the client asks for ID 401 - probably a stupid example).

  • 5 - Permission Denied, You don't have permission to do this operation

    This means you are trying to access an admin only functionality. (Or other functionality that is server, not game, restricted).

  • 6 - Permission Denied, You don't have permission to access this object/order/message

    The object you are trying to access (and can see), you don't have permission to get this type of detail about. Servers should NOT return this error on objects/order/messages that the player can't see.

  • 7 - Gone Permanently, The object/order/message has been destroyed or similar

    An object has been removed and will never be seen again.

  • 8 - Gone Temporarily, The object/order/message has been obscured from your view

    An object can no longer be seen. It may be seen again some time in the future.

  • 9 - Version not Supported, The server doesn't support that version of the packet

    You have sent a packet with a version number that the server doesn't support. This will only occur when there is a protocol version mismatch. As frame versions are backwards compatible there should not be a failure.

  • 10 - Response too Big, The request would make a server return a Frame that would violate the TP size specifications.

    The only time I can see this occurring is when you request to many IDs at once?

  • 11 - ???
  • 12 - ???

Exception: If the connect frame is not valid TP frame, this frame will not be returned, instead a plain text string will be sent saying that the wrong protocol has been used. A fail frame may be send if the wrong protocol version is detected. This does not affect clients as they should always get the connect frame right.

The server needs to be careful that it doesn't disclose extra information by returning different fail codes.

Get ID Sequence Frame

Get ID Sequence frame consist of:

  • a SInt32, the sequence key
  • a UInt32, the starting number in the sequence
  • a SInt32, the number of IDs to get
  • a UInt64, the time to get IDs with changes from

Valid Responses

There are only two valid responses to a Get ID Sequence Frame. Either a Fail frame, or a IDSequence frame with the number of IDs requested.

Getting a Sequence

  • To start a sequence, the key of -1 should be sent in the first request.
  • Subsequent requests in a sequence should use the key which is returned from the first request.
  • All requests must be continuous and ascending.
  • Only one sequence key (for each real frame type) can exist at any time, starting a new sequence causes the old one to be discarded.
  • Key persist for only as long as the connection remains open and there are IDs left in the sequence.
If the client requests any of the following a Fail packet will be returned (as they are a violation of the requirements specified above).
  • a range has already had any part already given (IE no overlaps)
  • a range specifies a range which starts below the previously ending number (IE requesting from 6 to 10 then 0 to 5)
  • a range is bigger then the remaining IDs left (IE requesting 6 when only 4 remain)
  • try to use a key from a previous connection
Note: All servers must follow all the requirements above even if the server could provide support for certain violations.

The server may also return a Fail Packet if a key becomes invalid. This may occur when, the order of the returned IDs changes or when the number of IDs changes. This may be caused by new changes become available (such as a turn generation had just started) or for any other reason. It is up to the client to restart the request from the beginning.

Using "Changes From" field

The changes from field is used to download a partial update of the Universe. When the changes from field is non-zero, the ID list will only include objects which have a modification time newer then the given number.

Servers will return all objects which have been modified after the number given, including those which may have been destroyed, deleted or otherwise no longer accessible.

When the Changes From field is zero, the list will return only those objects which currently exist (as Get ID Sequence had previously).

Feature Negotiation

Get Features Frame

The Get Features frame has no data. Get the features this server supports. This frame can be sent before Connect.

Features Frame

The Features frame consists of:

  • a list of UInt32, list of available features

The feature codes that are currently available,

  • 0x1 - Secure Connection available on this port
  • 0x2 - Secure Connection available on another port
  • 0x3 - HTTP Tunneling available on this port
  • 0x4 - HTTP Tunneling available on another port
  • 0x5 - Support Keep alive frames
  • 0x6 - Support server side property calculation
  • 0x3E8 - Account creation is allowed

Optimizations are features which allow the clients to take certain shortcuts. All optimization are highly optional. Optimizations have ids greater then 0xffff,

  • 0x10000 - Sends Object ID Sequences in descending modified time order
  • 0x10001 - Sends Order Description ID Sequences in descending modified time order
  • 0x10002 - Sends Board ID Sequences in descending modified time order
  • 0x10003 - Sends Resource Description ID Sequences in descending modified time order
  • 0x10004 - Sends Category Description ID Sequences in descending modified time order
  • 0x10005 - Sends Design ID Sequences in descending modified time order
  • 0x10006 - Sends Component ID Sequences in descending modified time order
  • 0x10007 - Sends Property ID Sequences in descending modified time order

Object Frame

An Object frame consist of:

  • a UInt32, object ID
  • a UInt32, object type
  • a String, name of object
  • a UInt64, size of object (diameter)
  • 3 by Int64, position of object
  • 3 by Int64, velocity of object
  • a list of UInt32, object IDs of objects contained in the current object
  • a list of UInt32, order types that the player can send to this object
  • a UInt32, number of orders currently on this object
  • a UInt64, the last modified time
  • 2 by UInt32 of padding, for future expansion of common attributes
  • extra data, as defined by each object type

Note: The number of orders should be the number of orders the person can see on the object. Not the total number of orders on the object.