2005-11-24 Carl Worth <cworth@cworth.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     1.2.2. Message
65
66         MESSAGE <text>
67
68         ->
69         
70         MESSAGE
71
72     1.2.3. Help
73
74         HELP { <command> }
75
76         Displays help.  If <command> is provided, displays more
77         detailed help on a specific command, otherwise displays an
78         overview of all commands.
79
80     1.2.4. Quit
81
82         QUIT
83
84         ->
85
86         QUIT
87
88     1.2.5. Version
89
90         VERSION <client-version-number>
91
92         ->
93
94         VERSION <server-version-number>
95
96         Negotiates version number between client and server.  The server
97         will respond with a version no higher than the client version
98         number, but it may be lower.  Version numbers are integers.
99
100         This document describes protocol version 1.
101
102 1.3. Game management commands
103
104     1.3.1. Inviting a player to play a game
105
106         INVITE <username>
107
108         ->
109
110         INVITE
111
112         Possible errors: NOUSER, BUSY
113
114     1.3.2. Accepting an invitation
115
116         ACCEPT <username>
117
118         ->
119
120         ACCEPT
121
122 1.4. In-game commands
123
124     1.4.1. Get the game contents
125     
126         SHOW
127     
128         ->
129     
130         SHOW <game-board>
131     
132         <game-board> is a quoted multi-line string containing an
133         diagram of the tic-tac-toe board, which is a 3x3 array of
134         cells:
135     
136         c|c|c
137         c|c|c
138         c|c|c
139     
140         c = '_' for empty or 'X' or 'O' for a played space
141     
142         For example:
143     
144         SHOW "
145         _|X|O 
146         _|X|_
147         X|O|O"
148     
149         Possible errors: NOTINGAME
150     
151     1.4.2. Part
152     
153         PART
154     
155         ->
156     
157         PART
158     
159         Departs the current game
160
161         Possible errors: NOTINGAME
162     
163     1.4.3. Making a move
164
165         MOVE <number>
166     
167         ->
168     
169         MOVE
170
171         <number> indicates a number in the tic-tac-toe grid as
172         follows:
173
174         1|2|3
175         4|5|6
176         7|8|9
177     
178         Possible errors: NOTINGAME, NOTYOURMOVE, NOTGRID
179     
180 2. Asynchronous notification.  
181
182     The server will send notices to each user in a game whenever
183     there is a move. It will also send notices to every connected
184     client when additional people join or new games are
185     started. These are of the form:
186
187         NOTICE <notice-code> <args>
188
189     Game-specific notices are sent to users involved in the related
190     game, other notices are sent to all users.  Note that even the user
191     originating the notice receives a copy.
192
193 2.1. Global notices
194
195     These notices are sent to all connected clients
196
197     2.1.1. New users
198     
199         NOTICE USER <username>
200     
201     2.1.2. Disconnected user
202     
203         NOTICE QUIT <username>
204     
205     2.1.3. Game invitation
206     
207         NOTICE INVITE <username>
208     
209     2.1.4. Terminated games
210     
211         NOTICE DISPOSE <game>
212     
213     2.1.5. Message
214
215         NOTICE MESSAGE <username> <text>
216
217 2.2. Game notices
218
219     These notices are sent to all players and watchers in
220     the affected game
221
222     2.2.1. Global game notices
223
224         2.2.1.1. New game begins
225
226             NOTICE NEWGAME <username> <username>
227
228             The first username listed will go first
229
230         2.2.1.2. Game over, and winner
231
232             NOTICE GAMEOVER <outcome> <username>
233
234             <outcame> is either WON in which case <username> indicates
235             the winner or CATSGAME in which case <username> is "".
236
237     2.2.2. Move notices
238
239         2.2.2.1. Move
240         
241             NOTICE MOVE <username> <number>
242
243 3. Errors
244
245     The following error codes may be returned.
246
247 3.1. Connection setup errors
248
249     These errors occur during connection setup.
250
251     3.1.1. No name set
252     
253         ERROR NONAMESET
254     
255         'helo' must be sent before any command other than 'quit'.
256     
257     3.1.2. Invalid name
258     
259         ERROR INVALIDNAME
260     
261         All names must be of non-zero length and must be unique.
262
263         Possibly returned by: HELO
264
265 3.2. Command format errors
266
267     Errors caused by ill-formed commands
268     
269     3.2.1. Command
270     
271         ERROR COMMAND
272     
273         An invalid command was specified
274     
275     3.2.2. Syntax
276     
277         ERROR SYNTAX
278     
279         A syntax error was detected
280     
281     3.2.3. Not number
282     
283         ERROR NOTNUMBER
284     
285         A non-numeric value was supplied where a number was required
286         
287     3.2.4. Not a grid number
288     
289         ERROR NOTGRID
290     
291         The number specified in the command was not a valid grid number
292     
293 3.3. Global command errors.
294
295     There are no errors from any of the global commands
296
297 3.4. Game management errors.
298
299     Errors from game management commands
300     
301     3.4.1. No such game
302         
303         ERROR NOGAME
304         
305         A game name was provided that does not exist.
306         
307 3.5. User information errors
308
309     3.5.1. No such user
310     
311         ERROR NOUSER
312
313         A user name was provided that does not exist.
314
315 3.6. In-game errors
316
317     3.6.1. Global game errors
318     
319         3.6.1.1. Not in game
320     
321             ERROR NOTINGAME
322     
323             A game playing command was made, but the user is not a
324             particpant of any game.
325     
326             Possibly returned by: MOVE
327
328         3.6.1.2. Not playing
329
330             ERROR NOTPLAYING
331
332             A command was executed by a watching user that is
333             permitted only to players
334     
335     3.6.2. Moving errors 
336     
337         3.6.2.1. Not your turn
338
339             ERROR NOTYOURTURN
340     
341             A move was submitted during the other player's turn
342
343             Possibly returned by: MOVE