Protocol Definition for Thousand Parsec

Version 0.1

Last updated 2 May 2003.

This protocol definition is for the Thousand Parsec project. It is designed as a simple, easy to impliment protocol. It is desgined by Lee Begg and any questions should be directed to him.

This protocol will only change in a backward compatable way, with respect to current versions and revisions that the client(s) and server are using. Any change that is not backward compatable will change the version number of the protocol.

This document has been superseded by TP02 Protocol doc. Support for TP01 will be removed from the server at ParseStone Echo.

Basics

TP will use TCP port 6923. This port is not known to have any other services on it.

All data will be 32 bit aligned. Strings will be prefixed by the 32 bit integer length (include null terminator) and then padded with nulls ('\0') to the next 32 bit boundary (if necessary). 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>>

TP Frame format

A TP Frame has the following parts:

Types

There are a number of types that can be put in types field of the packet. Even values are sent from the client, odd values from the server. 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.

Data Packet formats

The different types have different formats for the Data Packet.

Connect Packet

No Data Packet. The length is zero.

OK Packet

the OK packet in the frame may contain a string. The string can be safely ignored.

Login Packet

The login packet consists of two strings. The first is the username of the player and/or character. The second is Password. The password will be transmitted in plaintext, futher security will be added in future version.

Fail Packet

A fail packet consists of a integer code, a text string of the error.

Get Object Packet

Packet contains the int32 object ID of the object requested. Object 0 is the top level Universe object.

Object Packet

An object packet contains:

1. int32 object ID,
2. int32 object type,
3. string name,
4. unsigned int64 size (diameter),
5. 3 by signed int64 position,
6. 3 by signed int64 velocity,
7. 3 by signed int64 acceleration,
8. a list of int32 object IDs of objects contained in the current object, prefixed by the int32 of the number of items in the list,
9. a list of int32 order types that the player can send to this object prefixed by the number of items in the list,
10. an int32 number of orders currently on this object from the player.

Get Order Packet, Remove Order Packet

Get Order packet and Remove Order packet have the int32 id of the object it's on, and the int32 slot number the order is in to be sent or removed.

Order Packet, Add Order packet

An Order Packet or Add Order packet has int32 Object ID of the object it's on (or to be put on), int32 type, and which slot number it is in or should go in, -1 for last. Any extra data required by the order is appended to the end and is defined on a type by type basis.

Describe Order Packet

This packet contains a single int32, the order type to be described.

Order Description Packet

The Order Description packet contains: int32 order type, string name, string description, int32 number of parameters and then of each parameter: string name, int32 typeID, string desc. The Parameter Types are given below:

Get Outcome

The Get Outcome data packet consists of int32 Object id and int32 order slot number.

Outcome

The Outcome Frame contains int32 Objet id, int32 order slot number, int32 turns to completion, followed by more data to be specified in future.

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.