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