Thousand Parsec: Protocol Definition Ver 0.3

Get Objects by Position Frame

This frame type is deprecated in TP03, see TP02 protocol documentation for compatibility frame format. Clients and servers that also support TP02 must implement this frame.

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.

Get Object IDs Frame

Get Object IDs by Position Frame

A Get Object IDs by Position frame consist of:

3 by Int64, giving the position of center the sphere
a UInt64, giving the radius of the sphere

This will return an ID Sequence which contains all the object IDs which are inside the sphere. If a sphere size of zero is used all object IDs at the point will be returned.

Get Object IDs by Container Frame

A Get Object IDs by Container frame consist of:

a UInt32, object that is the container

This will return an ID Sequence which contains all the object IDs which are directly contained by this object. To get all objects inside a container you will need to call this recursively on the IDs returned.

List of Object IDs Frame

Orders

Get Order Description Frame

Order Description Frame

The Order Description frame 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

a UInt64, the last time this description was modified

The Argument Types are given below:

Name	Int32 Code	Description	Expected Format
Absolute Space Coordinates	0	Coordinates in absolute space. (Relative to the center of the Universe)	a Int64, read write, X value a Int64, read write, Y value a Int64, read write, Z value
Time	1	The number of turns before something happens.	a UInt32, read write, number of turns a UInt32, read only, maximum number of turns
Object	2	An object's ID number.	a UInt32, read write, objects id
Player	3	A player's ID number, Int32	a UInt32, read write, players id a UInt32, read only, mask (ON bits are NOT allowed to chosen), 0x00000001 - Allies 0x00000002 - Trading Partner 0x00000004 - Neutral 0x00000008 - Enemies 0x00000010 - Non-player
Relative Space Coordinates	4	Coordinates in absolute space relative to an object	a UInt32, read write, ID of the object these coordinates are relative to a Int64, read write, X value a Int64, read write, Y value a Int64, read write, Z value
Range	5	A number value from a range	a Int32, read write, value a Int32, read only, minimum value a Int32, read only, maximum value a Int32, read only, value to increment by
List	6	A list in which numerous items can be selected	The possible selections, A list of: a UInt32, read only, id of what can be selected a String, read only, String Name of can be selected a UInt32, read only, Maximum number of can to be selected The selection, A list of: a UInt32, read write, id of the selection a UInt32, read write, number of the selection
String	7	A string which includes a maximum specified length.	a UInt32, read only, maximum length of the string a String, read write, the string Be very careful with this type of argument. It is very easy to confuse the maximum length of the string with the actual length of the string. Example: <1024> <5> Hello This means that the maximum string length is 1024, and the actual string is the 5 character string "Hello".
Generic Reference	8	A reference to something.	A read write reference, as describe in the Generic Reference System section. The valid reference types, A list of: a UInt32, read only, id of valid reference types
Generic Reference List	9	A list of reference to something.	A read write list of, A reference, as describe in the Generic Reference System section. The valid reference types, A list of: a UInt32, read only, id of valid reference types

NOTE: read only fields should be transmitted by the client as 0, empty lists or empty string to conserve bandwidth. The server will ignore any information in read only field (even if they are non-empty).

Order Frame, Insert Order Frame

A Order frame consist of:

a UInt32, Object ID of the order is on/to be placed on
a SInt32, 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

The extra data is defined by Order descriptions frames. The number of turns and the size of the resource list should be zero (0) when sent by the client.

Note: Order type IDs below 1000 are reserved for orders defined by the extended protocol specification.

Note: Order's do not have a last modified time. Instead when an order changes the object which they are on has it's last modified time updated. This is because orders can change position and do all types of other weird stuff.

Probe Order Frame

A Probe Order frame gets an order as if the order given was put in the object's order queue. These probes should occur as if no orders currently exist on object and should have no side-effects. This is used to get the read-only fields for an order which is needed for good offline operation.

The data in this frame is the same as an Insert Order frame. The server replies with the Order frame as if they were already on the object. Fail frames are possible if the order type is not allowed, or the object or order type doesn't exist.

Note:This data should only be used as a guide, complex interactions may cause the read-only fields to be different in some cases.

Time

Get Time Remaining Frame

Get the time remaining before the end of turn. No data

Time Remaining Frame

A Time Remaining frame consist of:

a UInt32, the time in seconds before the next end of turn starts

If the value is 0 then the end of turn has just started.

Messages

Get Boards Frame

Board Frame

A Board frame consist of:

a UInt32, Board ID
a String, name of the Board
a Formatted String, description of the Board
a UInt32, number of messages on the Board
a UInt64, the last modified time

Note:The last modified time should be updated every time a message on the board has changed.

Get Board IDs Frame

List Of Board IDs Frame

Get Message Frame, Remove Message Frame

See Get With ID and Slot

Message Frame, Post Message Frame

A Message frame consist of:

a UInt32, Board ID of the message is on/to be placed on
a SInt32, 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, ignored as of TP03 - should be empty list
a Formatted String, Subject of the message
a Formatted String, Body of the message
a UInt32, Turn the message was generated on
a list of as described in the Generic Reference System

Please note that messages should be immutable, once posted/created they should not change. Maybe we should have a modified time, then we could remove this restriction?

Generic Reference System

The new reference system is similar to the old type system but has been expanded to cover more features.

The reference system uses two integers to reference any object in the game. The first integer indicated what type of thing is being referenced and the second gives the ID of the thing being referenced.

a Int32, type of thing being referenced
a UInt32, the ID of the object being referenced

As well the references system has a bunch of references which point to "actions" (from example an order completing). As these do not refer to actual items in the game the type is negative.

The types used in the reference system are described below,

-1000 - Server specific action reference
-5? - Design action reference
-4? - Player action reference
-3? - Message action reference
-2 - Order action special reference
-1 - Object action reference
0 - Misc special reference
1 - Object
2 - Order Type (IE A type of order)
3 - Order Instance (An actual order on an object, should also include an Object reference)
4 - Board
5 - Message (Should also include a Board reference)
6 - Resource Description
7 - Player
8? - Category
9? - Component

The special references are listed below,

Misc

System Message, this message is from a the internal game system
Administration Message, this message is an message from game administrators
Important Message, this message is flagged to be important
Unimportant Message, this message is flagged as unimportant

Player Action

Player Eliminated, this message refers to the elimination of a player from the game
Player Quit, this message refers to a player leaving the game
Player Joined, this message refers to a new player joining the game

Order Action

Order Completion, this message refers to a completion of an order
Order Canceled, this message refers to the cancellation of an order (IE Building a ship and ship yard destroyed)
Order Incompatible, this message refers to the inability to complete an order (IE Build Ship A when not enough material for Ship A is available)
Order Invalid, this message refers to an order which is invalid (IE Mine order on a fleet with no remote miners)

Object Action

Object Idle, this message refers to an object having nothing to do

Examples:

(1, 6) would be a message about/from player 6
(0, 1) would be a system message
(-1, 3) would be a player joined message

Resources

Get Resource Description Frame

Resource Description Frame

A Resource is something that things are build out of, or consumed in production of something (IE work units).

A Resource Description frame consist of:

a UInt32, Resource ID
a Formatted String, singular name of the resource
a Formatted String, plural name of the resource
a Formatted String, singular name of the resources unit
a Formatted String, plural name of the resources unit
a Formatted 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)
a UInt64, the last modified time of this resource description

Get Resource Description IDs Frame

List Of Resource Description IDs Frame

Players

Get Player Data Frame

Note: Getting id 0 will return the current player and the returned player object will have the correct player id set.

Player Data Frame

A Player Data frame consists of:

a UInt32, the Player id
a String, the Player's name
a String, the Race's name
(more?)

FIXME: Should this include details about a race? What happens if a player controls more then once race? What if a player can have partial control over an allies race? What about player governors?

Design Manipulation

Get Category Frame, Remove Category Frame

Category Frame, Add Category Frame

A Category frame consist of:

a SInt32, Category ID
a UInt64, the last modified time of this category description
a Formatted String, name of the category
a Formatted String, description of the category

Note: If adding a category send the ID as -1. The returned Category frame will contain the ID of the newly added category.

Note: If adding the last modified time will be ignored.

Get Category IDs

List Of Category IDs

Get Design Frame, Remove Design Frame

Design Frame, Add Design Frame, Modify Design Frame

A Design frame consist of:

a UInt32, Design ID
a UInt64, the last modified time of this design description
a list of UInt32, categories this design is in
a Formatted String, name of the design
a Formatted String, description of the design
a SInt32, number of times the design is in use
a SInt32, owner of the design
a list of,
- a UInt32, component id
- a UInt32, the number of components
a Formatted String, human readable feedback on the design
a list of,
- a UInt32, property id
- a Formatted String, property display string

Note: If adding a design send the ID as -1. The returned Design frame will contain the ID of the newly added design.

Note: If adding the following fields will be ignored by the server so should be transmitted as empty (although not required to be),

last modified time
number of times in use
feedback string
property list

Note: If usage is -1, then the design is unusable.

Note: If owner is -1, then the design is owned by an unknown player (or not owned by anyone).

Get Design IDs

List Of Design IDs

Get Component Frame

Component Frame

A Component frame consist of:

a UInt32, component ID
a UInt64, the last modified time of this component
a list of UInt32, categories this component is in
a Formatted String, name of the component
a Formatted String, description of the component
a String, TPCL "Requirements" function (see TPCL Document for more information)
a list of
- a UInt32, Property ID
- a String, TPCL "Property Value" function (see TPCL Document for more information)

Get Component IDs

List Of Component IDs

Get Property Frame

Property Frame

A Property frame consist of:

a UInt32, property ID
a UInt64, the last modified time of this property
a list of UInt32, categories this property is in
a UInt32, rank of the property
a String, name of the property (must be a valid TPCL identifier)
a Formatted String, display name of the property
a Formatted String, description of the property
a String, TPCL "Calculate" function (see TPCL Document for more information)
a String, TPCL "Requirements" function (see TPCL Document for more information)

Get Property IDs

List Of Property IDs