| Home | Documents | Code Breakdown | Source Code | Wiki | GIT Web | Bugs (70 open) |
Protocol Definition for Thousand Parsec
Version 0.2
Last updated 5 November 2004.
This protocol definition is for the Thousand Parsec project. It is designed as a simple, easy to implement protocol. It is designed by Lee Begg (and modified by Tim Ansell) and any questions should be directed at these two or the tp-devel mailing list.
This version of the protocol replaces the previous version (0.1) and has improvements where we noticed we could have done better. Any server should try to remain backward compatible with version 0.1 for a period to allow the clients to be ported gradually.
This protocol will only change in a backward compatible way, with respect to current versions and revisions that the client(s) and server are using. Any change that is not backward compatible will change the version number of the protocol.
Basics
TP will use TCP port 6923. This port is not known to have any other services on it.
Data does not need to be 32 bit aligned. Strings will be prefixed by the 32 bit integer length (include null terminator) with no padding necessary. A list will be of only one type (IE Int32 or Int64) and be prefixed by an Int32 for the number of items in the list.
All integers are in Network Byte Order (Big Endian).
In this document a 32 bit integer is shown as <n> and a 64 bit integer as <<n>>. ASCII text is shown as normal.
TP Frame format
A TP Frame has the following parts:
| Fields | Header | Sequence Number | Type | Length | Data Packet |
| Sizes | 32 bits | 32 bits | 32 bits | 32 bits | length * 8 bits |
| Type | 4 * Char | UInt32 | UInt32 | UInt32 | data |
| Description and notes | Always has value "TP02" ("TP" plus version number), no null terminator. | An incrementing number "sequence number". The sequence number should alway be one more then the previous packets sequence number. | Type of data, see table below | Length of data in bytes | The data |
| Example | TP02 | 2345 | 2 | 21 | <5>blah\0<6>blah2\0 |
The Client may start with any positive (it's an unsigned number) sequence number except zero (0). Server replies with have sequence numbers that are the same as the sequence number on the operation they are a response to. If the server sends a frame that is not a response, the frames sequence number will be zero (0).
Types
There are a number of types that can be put in types field of the packet. There is no meaning in odd/even distinction in this version. The types are listed below:
If there is no C++ enum value, it is not current implemented yet and should be taken as advisory only.
Warning: these values have changed from version 0.1 to 0.2.
| Value | Name | Java Constant | C++ enum | Description | ParsecStone |
| Generic Responses | |||||
| 0 | Ok | ft02_OK | Ok, continue or passed | Alpha | |
| 1 | Fail | ft02_Fail | Failed, stop or impossible | Alpha | |
| 2 | Sequence | ft02_Sequence | Multiple frames will follow | Alpha | |
| Connecting | |||||
| 3 | Connect | ft02_Connect | Can I connect? | Alpha | |
| 4 | Login | ft02_Login | Login with username/password | Alpha | |
| Objects | |||||
| 5 | Get Objects by ID | ft02_Object_GetById | Returns object with the IDs. | Bravo | |
| 6 | Get Objects by Position | ft02_Object_GetByPos | Returns all objects within a sphere. | Bravo | |
| 7 | Object | ft02_Object | Description of an Object | Bravo | |
| Orders | |||||
| 8 | Get Order Description | ft02_OrderDesc_Get | Returns a description of an order type | Charlie | |
| 9 | Order Description | ft02_OrderDesc | Describes an order type and it's parameters | Charlie | |
| 10 | Get Order | ft02_Order_Get | Returns a description of an order | Charlie | |
| 11 | Order | ft02_Order | Description of an order | Charlie | |
| 12 | Insert Order | ft02_Order_Insert | Insert order on object before slot | Charlie | |
| 13 | Remove Order | ft02_Order_Remove | Remove an order from a slot of an object | Charlie | |
| Time | |||||
| 14 | Get Time remaining | ft02_Time_Remaining_Get | Get the amount of time before the end of turn | Echo | |
| 15 | Time remaining | ft02_Time_Remaining | The amount of time before the end of turn | Echo | |
| Messages | |||||
| 16 | Get Boards | ft02_Board_Get | Get a list of message boards the player can see. | Foxtrot | |
| 17 | Board | ft02_Board | A Message. | Foxtrot | |
| 18 | Get Message | ft02_Message_Get | Get a Message from a board. | Foxtrot | |
| 19 | Message | ft02_Message | A Message. | Foxtrot | |
| 20 | Post Message | ft02_Message_Post | Post a message to a board. | Foxtrot | |
| 21 | Remove Message | ft02_Message_Remove | Remove a message from a board. | Foxtrot | |
| Resources | |||||
| 22 | Get Resource Description | ft02_ResDesc_Get | Returns a description of an resource type | Foxtrot | |
| 23 | Resource Description | ft02_ResDesc | Describes a resource | Foxtrot | |
Data Packet formats
The different types have different formats for the Data Packet. Any Data Packet may have be extended at any time in a backward compatible manner. The program should just ignore any extra data in the Data Packet which it does not understand.
OK Packet
The OK packet consists of:
- a String, the string can be safely ignored - however it may contain useful information for debugging purposes)
Fail Packet
A fail packet consists of:
- a Int32, error code
- a String, message of the error
- 0 - Protocol Error, Something went wrong with the protocol
- 1 - Frame Error, One of the frames sent was bad
- 2 - Unavailable Permanently, This operation is unavailable
- 3 - Unavailable Temporarily, This operation is unavailable at this moment
- 4 - No such thing, The object/order/message does not exist
- ...
Sequence Packet
Sequence packet consist of:
- a UInt32, giving the number of packets to follow
Connect Packet
The Connect packet consists of:
- a String, a client identification string
Login Packet
The Login packet consists of:
- a String, the username of the player
- a String, the password
Get Object by ID Packet
A Get Object by ID packet consist of:
- a list UInt32, object IDs of the object requested
Object Packet
An Object packet 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
- 4 by UInt32 of padding, for future expansion of common attributes
- extra data, as defined by each object type
Get Objects by Position Packet
A Get Objects by Position packet consist of:
- 3 by Int64, giving the position of center the sphere
- a UInt64, giving the radius of the sphere
Get Order Packet, Remove Order Packet
Get Order packet and Remove Order packet consist of:
- a UInt32, id of object to be changed
- a list UInt32, slot numbers of orders to be sent/removed
Note: You should sent Remove Order slot numbers in decrementing value if you don't want strange things to happen. (IE 10, 4, 1)
Order Packet, Insert Order packet
A Order packet consist of:
- a UInt32, Object ID of the order is on/to be placed on
- a UInt32, Slot number of the order/to be put in, -1 will insert at the last position, otherwise it is inserted before the number
- a UInt32, Order Type ID
- a UInt32, (Read Only) The number of turns the order will take
- a list of
- a UInt32, The resource ID
- a UInt32, The units of that resource required
- extra data, required by the order is appended to the end
Note: Order type ID's below 1000 are reserved for orders defined by the extended protocol specification.
Describe Order Packet
This packet contains a list of Int32 which are the order types to be described.
Order Description Packet
The Order Description packet contains:
- a UInt32, order type
- a String, name
- a String, description
- a list of
- a String, argument name
- a UInt32, argument type ID
- a String, description
| Name | Int32 Code | C++ Enum | Description | Expected Format |
| Absolute Space Coordinates | 0 | opT_Space_Coord_Abs | Coordinates in absolute space. (Relative to the center of the Universe) |
|
| Time | 1 | opT_Time | The number of turns before something happens. |
|
| Object | 2 | opT_Object_ID | An object's ID number. |
|
| Player | 3 | opT_Player_ID | A player's ID number, Int32 |
|
| Relative Space Coordinates | 4 | opT_Space_Coord_Rel | Coordinates in absolute space relative to an object |
|
| Range | 5 | opT_Range | A number value from a range |
|
| List | 6 | opT_List | A list in which numerous objects can be selected |
The possible selections, A list of:
|
| String | 7 | opT_String | A number textual string |
|
Get Time Remaining
Get the time remaining before the end of turn. No data
Time Remaining
Contains one UInt32, with the time in seconds before the next end of turn starts. Can be sent at any time. If the value is 0 then the end of turn has just started.
Get Board Packet
A Get Board packet consist of:
- a list UInt32, Board IDs of the boards requested
Board Packet
A Board packet consist of:
- a UInt32, Board ID
- a String, name of the Board
- a String, description of the Board
- a UInt32, number of messages on the Board
Get Message Packet, Remove Message Packet
Get Message packet and Remove Message packet consist of:
- a UInt32, id of board to be changed
- a list UInt32, slot numbers of orders to be sent/removed
Note: You should sent Remove Message slot numbers in decrementing value if you don't want strange things to happen. (IE 10, 4, 1)
Message Packet, Post Message packet
A Message packet consist of:
- a UInt32, Board ID of the message is on/to be placed on
- a UInt32, Slot number of the message/to be put in, -1 will insert at the last position, otherwise it is inserted before the number
- a list UInt32, type of message (can be multiple types at once).
- a String, Subject of the Message
- a String, Body of the Message
Message types are "or"ed together to produce the type field.
- Order Completion, this message refers to a completion of an order
- Order Canceled, this message refers to the cancellation of an order
Get Resource Description
Get the Resource Description.
Resource Description
A Resource is something that things are build out of, or consumed in production of something (IE work units). A Resource Description consist of:
- a UInt32, Resource ID
- a String, singular name of the resource
- a String, plural name of the resource
- a String, singular name of the resources unit
- a String, plural name of the resources unit
- a String, description of the resource
- a UInt32, weight per unit of resource (0 for not applicable)
- a UInt32, size per unit of resource (0 for not applicable)
Other Packets
All other data packets are not defined yet and shall be added to this protocol version (unless the protocol is revised).
Example
The following is a simple example of the first interaction.
| From | type | Data Packet | Description |
| Client | Connect | Can I connect? (version check) | |
| Server | Ok | You can connect | |
| Client | Login | <5>blah\0<6>blah2\0 | This is my username and password |
| Server | Ok | Username/password accepted | |
| Client | Get Object | <0> | Get the Universe object |
| Server | Object | <0><0><9>Universe\0<<2^64-1>><<0>><<0>><<0>> <<0>><<0>><<0>> <2><1><2><0><0> | Universe object |
TODO
Stuff we have to do before we can consider this protocol to be complete enough to move onto another version.
- Figure out how to do masking for the opT_Object_ID Order Argument type (IE like opT_Object_Type)
- Add references to Messages (IE This message refers to these objects/orders/players)
- Add From to Messages
- Add turn to the Message (IE the Turn the message was generated on).
- Finish adding categories to Messages
- Solve the -1 is an error condition yet using unsigned numbers
- Figure out how to support renaming objects
- Figure out a way for the opT_List_ID to "suggest" maximums as well as hard maximums
- Anything else I have forgotten
