z* home on SourceForge Logo
General Info
Message List
Web Links
Misc. Info
Development Model
Client Commands


Protocol Reference

I have been working for the past month on changing the way the zstar servers interact with the universe.

The event model is similar to what it was, but I have decided that it is important for it to be easier to program to.

I am considering eliminating atoms and going for a simple remote-call mechanism (currently outlined in zstar/exp) which allows named commands to be sent without atoms or an atom registry. This provides some nice benefits:

  • I have taken away the windowed udp protocol in favor of one that exactly mirrors tcp. The reason for this is that the other one was too complicated, and didn't allow for programs to be able to do their own socket handling.

    While this had been one of our goals, we have reconsidered this, and now think that the presence of a clear underlying protocol will suffice. Therefore, I designed the following simple protocol for UDP transport (described below).

  • This format translates more easily to be carried on TCP, or as text. You can use a TCP socket to carry these messages, and then get them distributed by a UDP repeater, or you can converse on a stream socket in text and have a proxy do all of the work for you. This allows perl, tcl, and other scripters to script pieces of a game without working too hard, which is important for the next benefit.

  • Because the buffering has been mostly eliminated from the udp sockets (there is still a connection, but it no-longer needs 32k of buffer space), It is cheaper (and somewhat easier) for the client to make more connections at once, and also easier for server to talk to one-another in an easy way, because socket setups are not a headache anymore.

The binary protocol

If carried over a connection-oriented protocol, each message must be prefixed by a six-byte destination with a 4-byte ip address, and a 2-byte port in network byte-order.

Note: everything is in network byte order

Byte PositionSizeDescription
02Length of message
24Last datagram id received from you (zero if none)
64Datagram id
10xNull terminated command string
10+xy Null terminated format string

Arguments are i (integer), f (float), and s (string). The special "no-argument" character is #, and arrays of f, i, or s are [nF where n is the number of items in the array, and F is the format character (from above).

10+x+y Arguments:
Format SymbolEncoding
iFour bytes in network byte order.
fEight bytes: units as 4-byte integer, 1000000th units as 4-byte integer.
sNull terminated string. The null is considered part of the string

The text protocol

If carried over a connection oriented protocol, the first line of the message is prepended with the ip-address of the recipent and the port (as text).

The first line is:
[ip-address] [port] command format

Each subsequent line is a value from the format string. If the value is an array, then the elements of the array are listed one per line.

Each message is terminated with one blank line.

The following demonstates a correct text message: 5004 textureSet si

The full message list is here: [ Message List ].