Protocol Definition for Thousand Parsec

Version 0.3 (Final)

Last updated 20 February 2007.

Table of Contents

Introduction

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 Tim Ansell and any questions should be directed at these two or the tp-devel mailing list.

This version of the protocol extends the previous version (0.2). It should be mostly backwards compatible with the previous version. It extends (or clarifies) the protocol to include the following abilities

  • SSL support
  • HTTP tunnel support
  • server-client negotiation of features
  • better support of offline operations
  • Unicode support
  • modify on-server designs

Key

In this document a

  • 8 bit integer is shown as >n<
  • 32 bit integer is shown as <n>
  • 64 bit integer as <<n>>
  • A list is shown as <length>[item1, item2]
  • Unicode text is shown as preformatted text
  • Binary data is shown as preformatted italics
  • New features of this document are marked like this
  • Notes marked with this color are issues for consideration when implementing (normally to do with security)

Basics

TP will use, TCP port 6923 for unencrypted access and TCP port 6924 for encrypted access. The server can also be run on port 80 for unencrypted access and 443 for encrypted access.

  • All integers are in Network Byte Order (Big Endian).
  • Strings will be prefixed by the 32 bit integer number of bytes the string takes up. All strings will be transmitted in UTF-8.

    Previously all strings had to be terminate by a null character, this is no longer necessary. It is recommend that the null terminator is no longer transmitted.

  • 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.
  • Semi-signed Integers are integers which act like normal unsigned numbers except that the biggest possible number is considered -1, this should equal the normal signed representation for this number. These are noted as SInt<Size>.
  • All times are in 64 bit Unix time stamp format in the timezone of UTC (with no daylight savings).

    Note: Modified times should be relative to a person. If a person should not know about the thing which caused the change then they should not know that the object has been modified.

A client can connect to a TP server on the standard 6923 port and use the new negotiation frames to find out if the server supports tunneling or encrypted access (and other optional features). The client is not required to do this however.

Encrypted Access (Optional)

TP uses standard SSL for encrypted access to the server, no special extensions have been added and client certificates are not used.

This can easily be implemented on the server side by using the stunnel (http://www.stunnel.org/) program in front of a normal unencrypted TP server.

On the client side SSL support will need to be added, the recommend way is to use library such as OpenSSL which will handle all the details for you.

HTTPS Tunneling (Optional)

No features need to be added to the server (apart from SSL support) to support HTTPS server. For full details on what needs to be implemented in the client to support HTTPS tunneling please see http://www.web-cache.com/Writings/Internet-Drafts/draft-luotonen-web-proxy-tunneling-01.txt

HTTP Tunneling (Optional)

To support HTTP tunneling additions need to be added to both the client and server. These changes are minimal however and only effect the connection setup.

On a connection, if the server finds a valid TP Connect frame then a normal connection occurs. Otherwise the server should wait until a valid POST request. The server should then respond with the correct HTTP headers to cause the proxy to not cache the connection and then continue with a normal TP connection.

The client should connect to the server as if POSTing to a standard web page with a random 12 digit ASCII numeric URL (for example /1a49fJKL12aU). It is important that the URL requested is random to stop broken proxy servers from caching the connection. Once the POST connection has been established a normal TP connection follows.

An example implementation of this can be found in libtpproto-py.

Frame format

A TP Frame has the following parts:

Fields Header Sequence Number Type Length Data Frame
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 "TP03" ("TP" plus version number), no null terminator. An incrementing number "sequence number". The sequence number should always be one more then the previous frames sequence number. Type of data, see table below Length of data in bytes The data
Example TP02 2345 2 21 <4>blah<5>blah2

The Client may start with any positive (it's an unsigned number) sequence number except zero (0). Server replies 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).

No frame may be bigger then 1048576 bytes (1 megabytes) long.

Frame Types

There are a number of types that can be put in types field of the frame. There is no meaning in odd/even distinction in this version. The types are listed below:

Note: Direction is defined as C2S (Client sent to Server) and S2C (Server to client).

Note: Valid Responses are the frames that a server can return for this C2S action. If the field is a dash refer to the base class.

FIXME: These Valid Responses should be links.

Value Name Description Base Dir Response
Generic Responses
These responses are the most common and generic that should be the first to be implemented.
0 Ok Ok, continue or passed S2C -
1 Fail Failed, stop or impossible S2C -
2 Sequence Multiple frames will follow S2C -
Base Frames
These packets don't really exist but are the common parts of other packets.
- Get with ID Gets things using ids (Objects, Boards) C2S
  • Sequence
    • Frame of type requested
    • Fail frame
  • Frame of type requested
  • Fail frame
- Get with ID and Slots Gets things on a thing using slots (Orders, Messages) C2S
  • Sequence
    • Frame of type requested
    • Fail frame
  • Frame of type requested
  • Fail frame
- Get ID Sequence Gets a sequence of IDs C2S
  • ID Sequence of type requested
  • Fail frame
- ID Sequence A sequence of IDs and their last modified times S2C -
Connecting
These frames are used for setting up the connection to a server.
3 Connect Can I connect? C2S
  • Okay frame
  • Fail frame
  • Redirect frame
4 Login Login with username/password C2S
  • Okay frame
  • Fail frame
  • Redirect frame
24 Redirect Redirects a client to a different server. S2C -
62 Account Create Creates an account with the given username, password, email and comment. C2S
  • Okay frame
  • Fail frame
Feature Negotiation
These frames are used for negotiation which features to use.
25 Get Features Get the features available on this server. C2S
  • Available Features frame
  • Fail frame
26 Available Features The features available on this server. S2C -
Keep alive (Optional)
These frames are used to keep a connection alive, these are often needed when using the tunneling connections. (Some broken NAT implementations also need this to keep open long running, low bandwidth connections.) These frames only required to be implemented if HTTP or HTTPS tunneling is supported.
27 Ping Get the server to respond with a OK request. C2S
  • Okay frame
Objects
These frames are used for getting objects.
5 Get Objects by ID Returns object with the given IDs. Get with ID - -
7 Object Description of an Object S2C -
28 Get Object IDs Get ID Sequence - -
29 Get Object IDs by Position Returns the IDs which are within a sphere. C2S
  • ID Sequence of Objects IDs
  • Fail frame
30 Get Object IDs by Container Returns the Object IDs which are within an Object. C2S
  • ID Sequence of Objects IDs
  • Fail frame
31 List of Object IDs A sequence of object IDs. ID Sequence - -
Orders
These frames are used for manipulating orders.
8 Get Order Description Returns a description of an order type Get with ID - -
9 Order Description Describes an order type and it's parameters S2C -
32 Get Order Description IDs Gets a sequence of order type IDs. Get ID Sequence - -
33 List of Order Description IDs A sequence of order type IDs. ID Sequence - -
10 Get Order Returns a description of an order Get with ID and Slots - -
11 Order Description of an order S2C -
12 Insert Order Insert order on object before slot C2S
  • Okay frame
  • Fail frame
13 Remove Order Remove an order from a slot of an object Get with ID and Slots - -
34 Probe Order Returns an order object which would be created if this was an Insert order C2S
  • Sequence
    • Order created with values requested
    • Fail frame
  • Fail frame
Time
These frames are used to find out when the next turn will occur.
14 Get Time Remaining Get the amount of time before the end of turn C2S
  • Okay frame
15 Time remaining The amount of time before the end of turn S2C -
Messages
These frames are used to manipulate the in game message boards. Each person has a message board and there are some shared message boards.
16 Get Boards Get message boards the player can see. Get with ID - -
17 Board A Message. S2C -
35 Get Board IDs Gets a list of board ids that the player can see. Get ID Sequence - -
36 List Of Board IDs The list of board ids the player can see. ID Sequence - -
18 Get Message Get a Message from a board. Get with ID and Slots - -
19 Message A Message. S2C -
20 Post Message Post a message to a board. C2S
  • Okay frame
  • Fail frame
21 Remove Message Remove a message from a board. Get with ID and Slots - -
Resources
These frames are used to get information about resources.
22 Get Resource Description Returns a description of an resource type Get with ID - -
23 Resource Description Describes a resource S2C -
37 Get Resource Description IDs Gets a list of resource type ids. Get ID Sequence - -
38 List Of Resource Description IDs A list of resource type ids. ID Sequence - -
Players
These frames are used to get information about other places/races.
39 Get Player Data Get the information about a player/race. C2S
  • Player Data frame
  • Fail frame
40 Player Data S2C -
Design Manipulation
These are the frames required to manipulate designs (such as those for ships or Weapons).
41 Get Category Get the details about a category Get with ID - -
42 Category Describes a category S2C -
43 Add Category Adds a new category Category C2S
  • Category frame
  • Fail frame
44 Remove Category Remove a category Get with ID - -
45 Get Category IDs Gets a list of category ids. Get ID Sequence - -
46 List Of Category IDs A list of category type ids. ID Sequence - -
 
47 Get Design Get the details about a design Get with ID - -
48 Design Describes a design S2C -
49 Add Design Adds a new design Design C2S
  • Design frame
  • Fail frame
50 Modify Design Modifies an old design Design C2S
  • Design frame
  • Fail frame
51 Remove Design Remove a design Get with ID - -
52 Get Design IDs Gets a list of design ids. Get ID Sequence - -
53 List Of Design IDs A list of design type ids. ID Sequence - -
 
54 Get Component Gets the details about a component Get with ID - -
55 Component Describes a component S2C -
56 Get Component IDs Gets a list of component ids. Get ID Sequence - -
57 List Of Component IDs A list of component ids. ID Sequence - -
 
58 Get Property Gets the details about a property Get with ID - -
59 Property Describes a property S2C -
60 Get Property IDs Gets a list of property ids. Get ID Sequence - -
61 List Of Property IDs A list of property ids. ID Sequence - -

Frame ID List

-Get with ID
-Get with ID and Slots
-Get ID Sequence
-ID Sequence
0Ok
1Fail
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
26Available 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
40Player 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

Frame formats

The different types have different formats for the Data Frame. Any Data Frame may have be extended at any time in a backward compatible manner. The program should just ignore any extra data in the Data Frame which it does not understand.

Generic Responses

OK Frame

The OK frame consists of:

  • a String, the string can be safely ignored - however it may contain useful information for debugging purposes)

Fail Frame

A fail frame consists of:

  • a Int32, error code
  • a String, message of the error
Current error codes consist of:
  • 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
  • 5 - Permission Denied, You don't have permission to do this operation
  • ...
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.

Sequence Frame

Sequence frame consist of:

  • a UInt32, giving the number of frames to follow

This frame will proceed a response which requires numerous frames to be complete.

Base Frames

Get with ID Frame

A Get with ID frame consist of:

  • a list of UInt32, IDs of the things requested

This packet is used to get things using their IDs. Such things would be objects, message boards, etc.

Get with ID and Slot Frame

Get with ID and Slot frame consist of:

  • a UInt32, id of base thing
  • a list of UInt32, slot numbers of contained things be requested

This packet is used to get things which are in "slots" on a parent. Examples would be orders (on objects), messages (on boards), etc.

Note: If this is really a Remove frame then slot numbers should be in decrementing value if you don't want strange things to happen. (IE 10, 4, 1)

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

Requirements:

  • 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
  • All requests must be continuous and ascending
  • Only one sequence key 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 and there are IDs left in the sequence
Other Information:
  • If the number of IDs to get is -1, then all (remaining) IDs should be returned.
  • If a key becomes invalid because of some change on the server (IE the ID order changes because of modification by another client) a Fail packet will be returned
  • If the client for a key requests any of the following a Fail packet will be returned
    • a range has already had any part already given (IE no overlaps)
    • a range specifies a range which starts below the ending (IE requesting from 6, 10 then 0 to 5)
    • a range is bigger then the remaining IDs left (IE requesting 6 when only 4 remain)

Note: All servers must follow all the requirements above even if the server could allow otherwise.

ID Sequence Frame

ID Sequence frame consist of:

  • a SInt32, the sequence key
  • a SInt32, the number of IDs remaining
  • a list of
    • a UInt32, the IDs
    • a UInt64, the last modified time of this ID

These IDs are not guaranteed to be in any order.

Connecting

Redirect Frame

Redirect frame consist of:

  • a String, the URI of the new server to connect too

This URI will be of the standard format. A server won't redirect to a different type of service (IE If you using the tunnel service it will only redirect to another tunnel service).

Example URIs:

  • tp://mithro.dyndns.org/ - Connect on standard tp port
  • tps://mithro.dyndns.org/ - Connect on standard tps port using SSL
  • tp://mithro.dyndns.org:6999/ - Connect on port 6999
  • http://mithro.dyndns.org/ - Connect using HTTP tunneling
  • https://mithro.dyndns.org/ - Connect using HTTPS tunneling

Connect Frame

The Connect frame consists of:

  • a String, a client identification string
The client identification string can be any string but will mostly used to produce stats of who uses which client. The server may return either a OK, Fail or Redirect frame.

If the server wants to return a Redirect and the client only supports the old protocol a Fail should be returned instead.

Login Frame

The Login frame consists of:

  • a String, the username of the player
  • a String, the password

Currently the password will be transmitted in plain text. To avoid interception SSL service should be used. Some servers may refuse to authenticate on the unencrypted service and only run it to allow detection of encryption support.

Account Create Frame

The Account Create frame consists of:

  • a String, the username of the player
  • a String, the password
  • a String, the email address of the player
  • a String, a comment

Currently the password will be transmitted in plain text. To avoid interception SSL service should be used. Some servers may refuse to authenticate on the unencrypted service and only run it to allow detection of encryption support.

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

Keep Alive

Ping Frame

The Ping frame is empty and is only used to keep a connection alive that would possibly terminate otherwise. No more then 1 ping frame every second should be sent and then only if no other data has been sent.

Objects

Get Objects by ID Frame

See Get With ID

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

See Get ID Sequence

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

See ID Sequence

Orders

Get Order Description Frame

See Get With ID

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,
  • 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).

Get Order Description IDs Frame

See Get ID Sequence

List of Order Description IDs Frame

See ID Sequence

Get Order Frame, Remove Order Frame

See Get With ID and Slot

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

See Get With ID

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

See Get ID Sequence

List Of Board IDs Frame

See ID Sequence

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

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

Player Action

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

Order Action

  1. Order Completion, this message refers to a completion of an order
  2. Order Canceled, this message refers to the cancellation of an order (IE Building a ship and ship yard destroyed)
  3. 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)
  4. Order Invalid, this message refers to an order which is invalid (IE Mine order on a fleet with no remote miners)

Object Action

  1. 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

See Get With ID

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

See Get ID Sequence

List Of Resource Description IDs Frame

See ID Sequence

Players

Get Player Data Frame

See Get With ID

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

See Get With ID

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

See Get ID Sequence

List Of Category IDs

See ID Sequence

Get Design Frame, Remove Design Frame

See Get With ID

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

See Get ID Sequence

List Of Design IDs

See ID Sequence

Get Component Frame

See Get With ID

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

See Get ID Sequence

List Of Component IDs

See ID Sequence

Get Property Frame

See Get With ID

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

See Get ID Sequence

List Of Property IDs

See ID Sequence

Example

The following is a simple example of the first interaction.

From type Data Frame Description
Client Connect   Can I connect? (version check)
Server Ok   You can connect
Client Login <4>blah<5>blah2 This is my username and password
Server Ok   Username/password accepted
Client Get Object <0> Get the Universe object
Server Object <0><0><8>Universe<<2^64-1>><<0>><<0>><<0>> <<0>><<0>><<0>> <2><1><2><0><0> Universe object

TO DO

Stuff we have to be considered fixed...

  • Figure out how to do masking for the opT_Object_ID Order Argument type (IE like opT_Object_Type)
  • Figure out how to support renaming objects
  • Figure out how to support object descriptions (ie similar to order stuff)
  • Figure out a way for the opT_List_ID to "suggest" maximums as well as hard maximums
  • Help support?
  • Permissions to change your stuff? Not really needed for now...
  • Multi-language support?
  • Add Research support
  • Anything else I have forgotten