|
|
Events
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 Position | Size | Description |
|---|
| 0 | 2 | Length of message |
| 2 | 4 | Last datagram id received from you (zero if none) |
| 6 | 4 | Datagram id |
| 10 | x | Null terminated command string |
| 10+x | y |
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 Symbol | Encoding |
|---|
| i | Four bytes in network byte order. |
| f | Eight bytes: units as 4-byte integer,
1000000th units as 4-byte integer. |
| s | Null 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:
127.0.0.1 5004 textureSet si
http://www.erinet.com/cunning1/pats/leaves.jpg
13
The full message list is here:
[ Message List ].
|
