-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathnew-biller-prot.html
executable file
·346 lines (307 loc) · 20.8 KB
/
new-biller-prot.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<meta http-equiv="content-type" content="application/xhtml+xml; charset=UTF-8" />
<meta name="description" content="subspace billing server protocol proposal version 1.3.1" />
<meta name="author" content="Grelminar" />
<title>New Biller Protocol</title>
</head>
<body style="font-family:Lucida Console; font-size:10pt;">
<p>
subspace billing server protocol proposal<br />
version 1.3.1<br />
<a href="mailto:grelminar@yahoo.com">grelminar@yahoo.com</a>
</p>
<p>
all communication goes over a single tcp socket. messages are lines,<br />
delimited by linefeed characters (ascii 10) (although servers and<br />
clients should accept CR, LF, and CRLF). fields within a message are<br />
delimited by colons (ascii 58). the first field is the type of the<br />
message. each type has a fixed number of fields to expect, so the last<br />
field can contain colons without confusing anything. integer values in<br />
fields should be in decimal. all lines will be no more than 1023<br />
characters in length (including LF). either side may discard lines<br />
longer than that length if it receives them.
</p>
<p>
the game server will initiate a tcp connection to the billing server on<br />
the agreed port.
</p>
<p>
(from now on, I'm going to get lazy, and call the game server "the<br />
server", and the billing server "the biller". i'll use <span style="color:indigo;">g->b</span> and <span style="color:forestgreen;">b->g</span> to<br />
describe the two directions.)
</p>
<p>
the protocol is versioned with a three-part number (major revision,<br />
minor revision, patch). backwards compatbility is guaranteed when two<br />
version differ only by the patch number. when two versions differ by a<br />
major or minor revision number, all bets are off.
</p>
<p>
the server sends the protocol version that it speaks to the biller. if<br />
the biller supports it (and everything else is ok), the biller can reply<br />
successfully and a connection is established. if the biller doesn't<br />
support the version requested (module the patch number), or if anything<br />
else is wrong with the login, it should return failure and close the<br />
connection. no further protocol version negociation takes places.
</p>
<ul style="margin-top:30px;">
<li><a href="#login">server login stuff</a></li>
<li><a href="#plogin">player login stuff</a></li>
<li><a href="#registration">player registration (optional)</a></li>
<li><a href="#banners">banners</a></li>
<li><a href="#status">player status changes</a></li>
<li><a href="#messaging">messaging</a></li>
<li><a href="#misc">misc.</a></li>
</ul>
<p style="margin-top:30px;"><b><a name="login">::::: server login stuff</a></b></p>
<p>
to login:<br />
<span style="color:indigo;">g->b</span>: "<span style="color:red;">CONNECT:version:swname:zonename:hostname:password</span>"<br />
<span style="color:blue">version</span> is the version of the protocol used. it should have three<br />
<span style="color:blue">numbers</span> separated by dots (major, minor, patch). the current version<br />
is at the top of this document.<br />
<span style="color:blue">swname</span> is something idenifying the software used, like "<span style="color:red;">asss 1.0.5</span>".<br />
<span style="color:blue">zonename</span> is the name of this zone, like "<span style="color:red;">A Small Warzone</span>".<br />
<span style="color:blue">hostname</span> is where this zone is hosted, like "<span style="color:red;">SSCX</span>".<br />
<span style="color:blue">password</span> is a password to authenticate this zone.
</p>
<p>
the response will either be this:<br />
<span style="color:forestgreen;">b->g</span>: "<span style="color:red;">CONNECTOK:swname:billername</span>"<br />
<span style="color:blue">swname</span> is something identifying the biller used, like "<span style="color:red;">mybiller 0.29</span>".<br />
<span style="color:blue">billername</span> is a string identifying this biller network, like "<span style="color:red;">SSC</span>".<br />
or<br />
<span style="color:forestgreen;">b->g</span>: "<span style="color:red;">CONNECTBAD:swname:billername:reason</span>"<br />
<span style="color:blue">swname</span> and <span style="color:blue">billername</span> are as above.<br />
reason is something describing why the connection was refused, like<br />
"<span style="color:red;">bad password</span>", or "<span style="color:red;">wrong protocol version</span>".
</p>
<p>
the biller will most likely close the connection after sending a<br />
CONNECTBAD, but if it doesn't, the game server should.
</p>
<p>
the rest can only be used after a successful connection.
</p>
<p style="margin-top:30px;"><b><a name="plogin">::::: player login stuff</a></b></p>
<p>
game sends:<br />
<span style="color:indigo;">g->b</span>: "<span style="color:red;">PLOGIN:pid:flag:name:pw:ip:macid:contid</span>"<br />
<span style="color:blue">pid</span> is the player id assigned to this player by the server.<br />
<span style="color:blue">flag</span> is 0 for a normal login, 1 for "<span style="color:red;">i want to create a new player</span>".<br />
<span style="color:blue">name</span> is the name that's trying to log in.<br />
<span style="color:blue">pw</span> is the password he's using.<br />
<span style="color:blue">ip</span> is the address he's connecting from (in dotted decimal).<br />
<span style="color:blue">macid</span> is the standard machine id of the player.<br />
<span style="color:blue">contid</span> is the id data from continuum players. if the player isn't<br />
using cont, it should be empty. if the player is using cont, it will<br />
be the cont id, encoded in 128 characters, using plain hex encoding<br />
with lowercase letters.
</p>
<p>
biller responds with either:<br />
<span style="color:forestgreen;">b->g</span>: "<span style="color:red;">POK:pid:rtext:name:squad:billerid:usage:firstused</span>"<br />
<span style="color:blue">pid</span> is the player id that was passed in PLOGIN.<br />
<span style="color:blue">rtext</span> is additional text that can be delivered to the client. if<br />
there are no complications logging in, it should be empty.<br />
<span style="color:blue">name</span> is the name assigned by the biller (the biller can change the<br />
name of a player if desired).<br />
<span style="color:blue">squad</span> is the player's squad.<br />
<span style="color:blue">billerid</span> is an id number assigned by the billing server.<br />
<span style="color:blue">usage</span> is the number of seconds that this player has ever been<br />
connected to this biller.<br />
<span style="color:blue">firstused</span> is a string describing when this named account was<br />
created, in roughly this form: "<span style="color:red;">1-2-1999 6:13:35</span>"<br />
or<br />
<span style="color:forestgreen;">b->g</span>: "<span style="color:red;">PBAD:pid:newname:rtext</span>"<br />
<span style="color:blue">pid</span> is the player id passed in PLOGIN.<br />
<span style="color:blue">newname</span> is 1 if the requested name doesn't exist in the biller's<br />
database and is available for creation. it is 0 otherwise.<br />
<span style="color:blue">rtext</span> is some text describing the reason this login was denied.
</p>
<p style="margin-top:30px;"><b><a name="registration">::::: player registration (optional)</a></b></p>
<p>
_before_ sending a POK, the biller can request registration information<br />
by sending:<br />
<span style="color:forestgreen;">b->g</span>: "<span style="color:red;">WANTREG:pid</span>"<br />
<span style="color:blue">pid</span> is the pid for which registration information is requested.
</p>
<p>
the server may eventually respond:<br />
<span style="color:indigo;">g->b</span>: "<span style="color:red;">REGDATA:pid:data</span>"<br />
<span style="color:blue">pid</span> is the pid of the player whose information is being submitted.<br />
<span style="color:blue">data</span> is hex-encoded binary data containing the registration<br />
information. the format or length of this data is not specified in<br />
this document, and may be client-specific.
</p>
<p style="margin-top:30px;"><b><a name="banners">::::: banners</a></b></p>
<p>
the biller can send this any any time, but will typically send it right<br />
after a PLOGINOK message:<br />
<span style="color:forestgreen;">b->g</span>: "<span style="color:red;">BNR:pid:banner</span>"<br />
<span style="color:blue">pid</span> is the pid of the player setting his banner.<br />
<span style="color:blue">banner</span> is a 96-byte banner, encoded using standard hex encoding with<br />
lowercase letters, so it will be 192 bytes long.
</p>
<p>
when a player sets his banner, the server will update the biller with:<br />
<span style="color:indigo;">g->b</span>: "<span style="color:red;">BNR:pid:banner</span>"<br />
<span style="color:blue">pid</span> the the pid of the player setting his banner.<br />
<span style="color:blue">banner</span> is the new banner, encoded as above.
</p>
<p style="margin-top:30px;"><b><a name="status">::::: player status changes</a></b></p>
<p>
when a player enters an arena for the first time after logging in, the<br />
server sends:<br />
<span style="color:indigo;">g->b</span>: "<span style="color:red;">PENTERARENA:pid</span>"
</p>
<p>
when a player disconnects from the server, the server sends:<br />
<span style="color:indigo;">g->b</span>: "<span style="color:red;">PLEAVE:pid</span>"
</p>
<p>
the biller can request that the server disconnect a player by sending:<br />
<span style="color:forestgreen;">b->g</span>: "<span style="color:red;">PKICK:pid:reason</span>"<br />
<span style="color:blue">pid</span> is the pid of the player to be kicked.<br />
<span style="color:blue">reason</span> is some text describing the reason the player was kicked.
</p>
<p style="margin-top:30px;"><b><a name="messaging">::::: messaging</a></b></p>
<p>
when a player sends a ?chat message, the server sends:<br />
<span style="color:indigo;">g->b</span>: "<span style="color:red;">CHAT:pid:channel:sound:text</span>"<br />
<span style="color:blue">pid</span> is the sending player.<br />
<span style="color:blue">channel</span> is the name of the channel. alternatively, it can be a<br />
number signifying which of the player's channels the message is<br />
intended for.<br />
<span style="color:blue">sound</span> is a sound code, to be interpreted by the client.<br />
<span style="color:blue">text</span> is the text of the message.
</p>
<p>
when a player gets a ?chat message, the server receives:<br />
<span style="color:forestgreen;">b->g</span>: "<span style="color:red;">CHATTXT:channel:sender:sound:text</span>"<br />
<span style="color:forestgreen;">b->g</span>: "<span style="color:red;">CHAT:pid:number</span>"<br />
<span style="color:blue">channel</span> is the name of the channel that this message is on.<br />
<span style="color:blue">sender</span> is the name of the player who sent the message.<br />
<span style="color:blue">sound</span> is a sound code.<br />
<span style="color:blue">text</span> is the text of the message.<br />
<span style="color:blue">pid</span> is the pid of a player who received the message.<br />
<span style="color:blue">number</span> is what channel that player should see the message as coming<br />
from.
</p>
<p>
the CHATTXT message is used so that the biller can send a chat<br />
message to many players on one server without sending the full text<br />
and sender name to each of them. the contents of the CHATTXT message<br />
should be cached on the server, and the text used for any following<br />
CHAT messages, until the next CHATTXT. for example, if the server<br />
gets "<span style="color:red;">CHATTXT:sscx:player:0:hello</span>" and then "<span style="color:red;">CHAT:22:3</span>", player 22<br />
should see something like "<span style="color:red;">3:player> hello</span>".
</p>
<p>
when a player sends a remote private message:<br />
<span style="color:indigo;">g->b</span>: "<span style="color:red;">RMT:pid:destination:sound:text</span>"<br />
<span style="color:blue">pid</span> is the pid of the sending player.<br />
<span style="color:blue">destination</span> is the player the message is being sent to.<br />
<span style="color:blue">sound</span> is a sound code.<br />
<span style="color:blue">text</span> is the text of a message.
</p>
<p>
when a player receives a remove private message:<br />
<span style="color:forestgreen;">b->g</span>: "<span style="color:red;">RMT:pid:sender:sound:text</span>"<br />
<span style="color:blue">pid</span> is the pid of the player receiving the message.<br />
<span style="color:blue">sender</span> is the name of the sending player.<br />
<span style="color:blue">sound</span> is a sound code.<br />
<span style="color:blue">text</span> is the text of the message.
</p>
<p>
when a player sends a squad message:<br />
<span style="color:indigo;">g->b</span>: "<span style="color:red;">RMTSQD:pid:destsquad:sound:text</span>"<br />
<span style="color:blue">pid</span> is the pid of the sender.<br />
<span style="color:blue">destsquad</span> is the name of the squad whose players should receive the<br />
<span style="color:blue">message</span> (no leading #).<br />
<span style="color:blue">sound</span> is a sound code.<br />
<span style="color:blue">text</span> is the text of the message.
</p>
<p>
when a player receives a squad message:<br />
<span style="color:forestgreen;">b->g</span>: "<span style="color:red;">RMTSQD:destsquad:sender:sound:text</span>"<br />
<span style="color:blue">destsquad</span> is the squad that the message is for.<br />
<span style="color:blue">sender</span> is the name of the sending player.<br />
<span style="color:blue">sound</span> is a sound code.<br />
<span style="color:blue">text</span> is the text of the message.
</p>
<p>
when a player types a command that the server doesn't interpret, or that<br />
the server knows should go to the billing server:<br />
<span style="color:indigo;">g->b</span>: "<span style="color:red;">CMD:pid:cmdname:args</span>"<br />
<span style="color:blue">pid</span> is the pid of the sending player.<br />
<span style="color:blue">cmdname</span> is the name of the command.<br />
<span style="color:blue">args</span> is the arguments to the command (what was typed after the<br />
command name.
</p>
<p>
when the server wants to send a player some message (usually as the<br />
result of a command):<br />
<span style="color:forestgreen;">b->g</span>: "<span style="color:red;">MSG:pid:sound:text</span>"<br />
<span style="color:blue">pid</span> is the pid of the recipient.<br />
<span style="color:blue">sound</span> is a sound code.<br />
<span style="color:blue">text</span> is the text of the message.
</p>
<p>
when the server wants to send some of its log output to the biller,<br />
perhaps so logs document malicious activity can be gatherd and analyzed<br />
for many zones at once, it can send:<br />
<span style="color:indigo;">g->b</span>: "<span style="color:red;">LOG:pid:logtext</span>"<br />
if the log message refers to the activity of a specific player, the<br />
<span style="color:blue">pid</span> field will hold the pid of that player. if not, it should be<br />
empty (zero-length).<br />
logtext is the text of the log message, in whatever format the<br />
server chooses.
</p>
<p>
if the biller wants to send a message to only staff members of a zone,<br />
it can send:<br />
<span style="color:forestgreen;">b->g</span>: "<span style="color:red;">STAFFMSG:sender:sound:text</span>"<br />
<span style="color:blue">sender</span> is the optional name of whoever sent this message. if it was<br />
generated by the billing server, it should be empty.<br />
<span style="color:blue">sound</span> is a sound code.<br />
<span style="color:blue">text</span> is the text of the message.
</p>
<p>
if the biller wants to send a message to the entire zone (e.g., for<br />
scheduled downtime or other important events), it can send:<br />
<span style="color:forestgreen;">b->g</span>: "<span style="color:red;">BROADCAST:sender:sound:text</span>"<br />
<span style="color:blue">sender</span> is the optional name of whoever sent this message. if it was<br />
generated by the billing server, it should be empty.<br />
<span style="color:blue">sound</span> is a sound code.<br />
<span style="color:blue">text</span> is the text of the message.
</p>
<p>
if the server is going down (for a shutdown or whatever), it should<br />
close the tcp socket. if the biller is going down (for any reason), it<br />
should close the tcp socket.
</p>
<p style="margin-top:30px;"><b><a name="misc">::::: misc.</a></b></p>
<p>
either side is allowed to send ping messages which act as a keepalive to<br />
force tcp to detect when one or the other side of the connection crashes<br />
or becomes unavailable. a suggested interval between pings is 180<br />
seconds, although neither side should assume anything about the interval<br />
that the other side is using, and should send its own keepalives if it<br />
wants quick notification if the other side crashes or becomes<br />
unavailable.
</p>
<p>
<span style="color:forestgreen;">b->g</span>: "<span style="color:red;">PING</span>"<br />
<span style="color:indigo;">g->b</span>: "<span style="color:red;">PING</span>"
</p>
<p>
the biller can indicate that it's time for a scorereset by sending:<br />
<span style="color:forestgreen;">b->g</span>: "<span style="color:red;">SCORERESET</span>"
</p>
<p style="color:green; margin-top:30px"># dist: public</p>
</body>
</html>