2005-12-02 Richard D. Worth <richard@theworths.org>
[ttt] / PROTOCOL
1                      Tic-tac-toe Protocol (TTTP)
2                            Version 0.0.1
3                              2005-11-05
4                 
5        Carl Worth           Richard Worth           Kevin Worth
6    carl@theworths.org   richard@theworths.org   kevin@theworths.org
7
8 Introduction
9
10 TTTP is a network protocol for playing the game tic-tac-toe. It permits
11 a single server to host multiple games with named participants. The
12 protocol is designed so that people can play using only telnet, but it is
13 expected that graphical interfaces will be able to drive the protocol as
14 well.
15
16 TTTP borrows heavily from RRGP (Ricochet Robot Game Protocol) by Keith
17 Packard and indirectly from other network protocols like SMTP using a
18 synchronous command interface.
19
20 Document Conventions
21
22         All commands include a response (yeah, synchronous protocols are
23         bad.  tough)
24
25         <command> <args> 
26
27         ->
28
29         <response>
30
31         <response> is one of:
32
33         <command> <args>
34         ERROR <message>
35
36 1. Requests
37
38 1.1 Connection setup
39
40     The TTTP server has no well defined port; agreement on which port to
41     use must be done through some external mechanism.  Once connected,
42     the client must identify itself:
43     
44     HELO <username>
45     
46     ->
47     
48     HELO <username> <server-addr> <server-port>
49
50     Possible errors: INVALIDNAME
51
52 1.2. Global commands
53
54     1.2.1 Listing available users
55
56         WHO
57
58         ->
59
60         WHO <username1> <games1> <username2> <games2> ...
61
62         Lists connected users and the number of games they've won.
63
64         Possible errors: NONAMESET
65
66     1.2.2. Message
67
68         MESSAGE <text>
69
70         ->
71         
72         MESSAGE
73
74         Sends a message to all connected users. The text must be a
75         single token. Use a quoted-string to include spaces in the
76         message text.
77
78         Possible errors: NONAMESET
79
80     1.2.3. Help
81
82         HELP { <command> }
83
84         Displays help.  If <command> is provided, displays more
85         detailed help on a specific command, otherwise displays an
86         overview of all commands.
87
88     1.2.4. Quit
89
90         QUIT
91
92         ->
93
94         QUIT
95
96         Disconnects the client from the server.
97
98     1.2.5. Version
99
100         VERSION <client-version-number>
101
102         ->
103
104         VERSION <server-version-number>
105
106         Negotiates version number between client and server.  The server
107         will respond with a version no higher than the client version
108         number, but it may be lower.  Version numbers are integers.
109
110         This document describes protocol version 1.
111
112 1.3. Game management commands
113
114     1.3.1. Inviting a player to play a game
115
116         INVITE <username>
117
118         ->
119
120         INVITE
121
122         Possible errors: NOUSER, BUSY, NONAMESET
123
124     1.3.2. Accepting an invitation
125
126         ACCEPT <username>
127
128         ->
129
130         ACCEPT
131
132         Possible errors: NONAMESET
133
134 1.4. In-game commands
135
136     1.4.1. Get the game contents
137     
138         SHOW
139     
140         ->
141     
142         SHOW <game-board>
143     
144         <game-board> is a quoted multi-line string containing an
145         diagram of the tic-tac-toe board, which is a 3x3 array of
146         cells:
147     
148         c|c|c
149         c|c|c
150         c|c|c
151     
152         c = '_' for empty or 'X' or 'O' for a played space
153     
154         For example:
155     
156         SHOW "
157         _|X|O 
158         _|X|_
159         X|O|O"
160     
161         Possible errors: NOTINGAME, NONAMESET
162     
163     1.4.2. Part
164     
165         PART
166     
167         ->
168     
169         PART
170     
171         Departs the current game
172
173         Possible errors: NOTINGAME, NONAMESET
174     
175     1.4.3. Making a move
176
177         MOVE <number>
178     
179         ->
180     
181         MOVE
182
183         <number> indicates a number in the tic-tac-toe grid as
184         follows:
185
186         0|1|2
187         3|4|5
188         6|7|8
189     
190         Possible errors: NOTINGAME, NOTYOURMOVE, NOTGRID, NONAMESET
191     
192 2. Asynchronous notification.  
193
194     The server will send notices to each user in a game whenever
195     there is a move. It will also send notices to every connected
196     client when additional people join or new games are
197     started. These are of the form:
198
199         NOTICE <notice-code> <args>
200
201     Game-specific notices are sent to users involved in the related
202     game, other notices are sent to all users.  Note that even the user
203     originating the notice receives a copy.
204
205 2.1. Global notices
206
207     These notices are sent to all connected clients
208
209     2.1.1. New users
210     
211         NOTICE USER <username>
212     
213     2.1.2. Disconnected user
214     
215         NOTICE QUIT <username>
216     
217     2.1.3. Game invitation
218     
219         NOTICE INVITE <username>
220     
221     2.1.4. Terminated games
222     
223         NOTICE DISPOSE <game>
224     
225     2.1.5. Message
226
227         NOTICE MESSAGE <username> <text>
228
229 2.2. Game notices
230
231     These notices are sent to all players and watchers in
232     the affected game
233
234     2.2.1. Global game notices
235
236         2.2.1.1. New game begins
237
238             NOTICE NEWGAME <username> <username>
239
240             The first username listed will go first
241
242         2.2.1.2. Game over, and winner
243
244             NOTICE GAMEOVER <outcome> <username>
245
246             <outcame> is either WON in which case <username> indicates
247             the winner or CATSGAME in which case <username> is "".
248
249     2.2.2. Move notices
250
251         2.2.2.1. Move
252         
253             NOTICE MOVE <username> <number>
254
255 3. Errors
256
257     The following error codes may be returned.
258
259 3.1. Connection setup errors
260
261     These errors occur during connection setup.
262
263     3.1.1. No name set
264     
265         ERROR NONAMESET
266     
267         'helo' must be sent before any command other than 'help',
268         'version', 'quit'.
269
270         Possibly returned by: WHO MESSAGE INVITE ACCEPT SHOW PART MOVE
271     
272     3.1.2. Invalid name
273     
274         ERROR INVALIDNAME
275     
276         All names must be of non-zero length and must be unique.
277
278         Possibly returned by: HELO
279
280 3.2. Command format errors
281
282     Errors caused by ill-formed commands
283     
284     3.2.1. Command
285     
286         ERROR COMMAND
287     
288         An invalid command was specified
289     
290     3.2.2. Syntax
291     
292         ERROR SYNTAX
293     
294         A syntax error was detected
295     
296     3.2.3. Not number
297     
298         ERROR NOTNUMBER
299     
300         A non-numeric value was supplied where a number was required
301         
302     3.2.4. Not a grid number
303     
304         ERROR NOTGRID
305     
306         The number specified in the command was not a valid grid number
307     
308 3.3. Global command errors.
309
310     There are no errors from any of the global commands
311
312 3.4. Game management errors.
313
314     Errors from game management commands
315     
316     3.4.1. No such game
317         
318         ERROR NOGAME
319         
320         A game name was provided that does not exist.
321         
322 3.5. User information errors
323
324     3.5.1. No such user
325     
326         ERROR NOUSER
327
328         A user name was provided that does not exist.
329
330 3.6. In-game errors
331
332     3.6.1. Global game errors
333     
334         3.6.1.1. Not in game
335     
336             ERROR NOTINGAME
337     
338             A game playing command was made, but the user is not a
339             particpant of any game.
340     
341             Possibly returned by: MOVE
342
343         3.6.1.2. Not playing
344
345             ERROR NOTPLAYING
346
347             A command was executed by a watching user that is
348             permitted only to players
349     
350     3.6.2. Moving errors 
351     
352         3.6.2.1. Not your turn
353
354             ERROR NOTYOURTURN
355     
356             A move was submitted during the other player's turn
357
358             Possibly returned by: MOVE