A description of the easily parseable ICC output formats Original Authors Herbert Enderton Daniel Sleator Copyright (C) 1996-2010 Internet Chess Club Note: This description of ICC's formats, and the formats themselves are copyrighted by the Internet Chess Club. The information in this document is only for use by people writing software that uses these formats while connected to ICC. If you were intending to make some other use of this information, then read no further and delete this document now. 1. Introduction. We have introduced a new format for data to be presented by the ICC. The purposes of the new format are: (1) To give capabilities to clients and robots that they would not otherwise have. (2) To make it easier for client and robot writers to process the ICC output. (3) To obviate the need for clients and robots to depend on specific wordings of messages (intended for humans). The design of the new format is flexible. It will allow us to continue to add to it without disturbing existing clients at all. It will allow each client or robot to choose exactly which of the options it wants. The behavior of the chess server currently has (and will always have) the following properties: The server receives data from the clients as a sequence of lines, each of which is one "command". The server orders the commands for execution (in the order in which the commands are received). It fully completes each command before starting the next one. Each command causes some data to be sent to various players. A response is always generated to the issuer of a command. The data generated in response to a command that is sent to a particular player is called a "unit". (It's also possible for the server itself to generate messages to players; e.g., the response to a ping.) Here is some terminology for the formats under discussion. Level 0: This is what the server generates by default. Level 1: This is the same as level 0, (not counting the prompt, which will not be generated) but the start and end of each unit is clearly delimited, and also labeled with the "command number" of the command generating it, and the player generating it. (the player who issued that command). Level 2: The information has been reformatted for ease of parsing by client. A unit in this format is called a "DG". (We used to call it a "datagram" but that term has a completely unrelated technical meaning to network programmers.) Level 1 can be turned on, which suppresses the ICC prompt, and introduces bracketing of units of output from the ICC. The purpose of level1 was simply to group the existing ICC output into discrete units according to the command and player that generated it. Independently level2 is controlled by around 150 binary variables, each of which controls the generating of a special DG of the given type, corresponding to the occurrence of some event. Level1 makes it easy for a client to know when the output of a command has ended, what the command was, and who issued it. Certain other types of information (not generated by a command) are also easily identified in level1, such as the list of events of the week, and list of news items one gets when one logs in. Level2 makes some of the following things possible (and easy): * Maintaining a list of all logged in players and their ratings. * Maintaining a list of all current games. * Maintaining a list of everybody watching my game. * Processing of match requests * move lists for my game, or a game I'm observing. 2. Turning it on. To turn on level1 style output, you can issue the command set level1 1 Well, actually it has gotten more complex than that, because we hacked in meanings to the 2's 4's and 8's bits. I.e., the level1 ICC variable takes values 0-15. If it's odd, that enables the level1 groupings described below. If (level1 & 2), that tells the server to send "\031<" (control-Y <) to the user when starting to interpret his or her command, and "\031>" upon completing that command (unless the command was something like "exit"). The (level1 & 4) and (level1 & 8) features are described below. For each level 2 data type there is a corresponding binary variable that the user can set. The command to set it is: set-2 23 1 Which will set level-2 variable 23 to a value of 1. Another way for a robot or a client to set these variables is to do it on the "login:" line. If a string like "level1=1" is entered at "login:" then level1 is turned on. The ICC then goes back to waiting for your name. Similarly, at the login prompt you can write: level2settings=10010101010101000101011110101001001101001100 where the string to the right of the equal sign is a sequence of bits. The leftmost bit becomes your level2setting[0], and so forth. There are some level-2 units (noted as "verbose" in the descriptions below) which are expensive to turn on, in the sense that turning them on results in the sending of lots of data. Turning them all on at once can cause a buffer overflow and lost data (see appendix 3), so those should be turned on individually with set-2 commands, and only when the user takes some action (such as asking for a player list), because of the lag that will ensue. 3. Level 1. When you have level1 1, all output to you is bracketed by a header line (starting with "^Y[" (control Y followed by "[") and detailed below) and an ending with "^Y]". These bracketings can be nested up to at most 3 levels currently (eventually it may go higher). The header lines have the following form: where is "^Y[", is a number corresponding to the command that resulted in the output (see Appendix 1 below), and is the name of the player issuing that command, or * if it was you. In a couple of special cases might be "$server$" or "$LoggingIn$" or some such. With level1 1, you do not get prompts. (Not the normal prompt, anyway; you still see prompts like "password:", but that's not really a prompt in the same sense "aics%" is; it's really the output of the login command). How will the client know when it has gotten all the output for the user's command? First of all the client should be keeping track of the nesting depth of the level1 brackets. Secondly, the output to a user's command will begin with a header line of the form "^Y[ command-number *", and end with "^Y]". So when the client sees the ^Y] that corresponds to a top-level level1 header containing a *, that's the end of the output for that command. Or you could set level1=3 (or 2) and go by the ^Y< and ^Y> delimiters. Note that ALL output that results from your (or somebody else's) execution of a command will be put within the brackets. E.g. there may well be stuff inside a CN_TELL bracketing besides the message; send yourself a message for an example. Example of nesting: Fishbait, an admin, has tell=0 when he types "spoof guest53 partner fishbait". guest53, if he has formatllevel 1, sees something like this: ^Y[328 fishbait fishbait spoofs you: "partner fishbait" ^Y[199 * Sending a 'tell' message to inform your chosen partner... ^Y[101 * Not sent -- fishbait does not get messages from unregistered players. ^Y]^Y]^Y] There are very few commands which spawn off other commands in this way. Actually, we will probably do away with level1 nesting, because it just seems to get in the way. See Appendix 1 for a current list of command numbers, taken verbatim from config.h. More command numbers will be added over time, and some of these command numbers will fall into disuse, but we don't intend to change any of the bindings outright. A few explanations about some of the command codes and associated symbols: The distinction between SCN and CN commands is only meaningful if you look at the server code. Don't worry about it. E.g. SCN_BAD is the code for output like "You can say 'abort' while playing" or "No such command", while CN_BAD is for commands such as "shutdow" that always produce the same boring error messages. Not an important distinction, I wouldn't think. If you have gin=1, you'll get a message when somebody starts a game, but the command number will depend on the command they use to start it (e.g. match or accept). There are a few other similar cases, where the command number depends on the command typed rather than the type of action that results. On the other hand some commands use the same command codes, such as "refresh" and "prefresh". Then there's "tell", which uses a different command number for channel tells and personal tells. Some of these choices were arbitrary. CN_FOLLOW0 is for follow with no arguments. Similarly CN_OBSERVE0 etc. 'tell' messages are further broken down as CN_TELL, CN_CHANNELTELL, CN_QTELL, and CN_CHANNELQTELL. Oh also CN_PTELL. The info shown when you join the server, if you've entered level1 before before entering your login name, is bracketed by category, more or less. Thus the event list is bracketed with an SCN_EVENTS header and so forth, with all of it nested within an SCN_REALLY_LOG_IN header. Try it. I'm not too sure about all the funny cases that can come up, e.g. if you start registering at the login prompt, or the server is full so you're forced to quit. Logout info is similarly grouped. When a user disconnects the server sends one extra ^Y] at the end of all other output, if that user has level1 on. Level 1 is not really needed (e.g. Blitzin 1.72 doesn't use it), but it was handy when we didn't have Level 2 developed. Blitzin 2.34 uses level1=15. It ignores the command number; it just needs level1 to know which output is due to the user's own commands and which window to send it to. New as of September 1998: If (level1 & 5) and you send a command to the server prefixed with (e.g. `asdf`history) the arbitrary-word will be echoed back to you as follows ^Y[ \n^Y] Since the arbitrary string only occurs when you use the backquotes, the player-name field will always be * (yourself), except maybe for ping responses in which case it will be $server$. (But please don't freak out if in the future it is something else.) Arbitrary-word can be up to 99 characters and may not contain whitespace. Blitzin2 uses this to guide response output to the window where the command was entered. And if (level1 & 8), the level1 header will just have * or % in place of the command issuer's name, depending on whether it was you sending the command or someone else. (Plus maybe $server$ for ping responses.) When level 1 units get nested, only the outermost unit echoes the arbitrary string. Note also that level 2 DGs are (almost always) bracketed inside level 1 units (if they're both turned on), so with some clever parsing, you can associate the arbitrary string with level 2 DGs. 4. Level 2. Every level 2 DG looks like: A "^Y(" followed by a decimal number which is the level 2 data type number, followed by a series of blank separated arguments. Followed by a "^Y)". In general, setting a specific level-2 variable to 1 turns on messages of that type. Some of them have other effects, like causing a list to be generated. (E.g. if you turn on DG_GAME_STARTED with "set-2 12 1" you'll effectively get a list of the current games, one DG per game. If your level2setting[12] was already 1, you'll get the list anyway, even though you should have known it already.) The client should not break if a DG has more fields than it expects. It should just ignore any fields after the last one that it expects to find. This allows us to add more information to DGs without breaking existing clients. (Another and more common way for us to do this is for us to add a new DG type.) The following will be adhered to: You will ONLY get DGs of the type that you've requested. This means that there may be more than one type of DGs that are EXACTLY the same except for the number. It's also possible to set up level-2 variable assignments that don't make any sense. For example, asking for the moves of games I'm observing while not asking for notification of which games I'm observing. (But we give you the DGs you ask for; if they make sense to you, great.) Below are the level-2 DG types. Notes: The "form" shows some things in parentheses. This omits the ^Y and the DG number. The titles are a string, such as {GM TD}. Titles currently include: (GM) grandmaster (IM) international master (FM) FIDE master (WGM) woman grandmaster (WIM) woman international master (WFM) woman FIDE master (TD) tournament director (C) computer (U) unregistered (*) administrator (DM) display master (H) helper A few of the items below are merely variables with no corresponding DG -- instead, they just control the information included in other DGs. The delimiters "^Y{" and "^Y}" and "{" and "}" are used to quote strings. This allows a string to contain any sequence of printable characters. (Strings quoted by "{" and "}" will not contain curly braces.) Number meaning 0 DG_WHO_AM_I Form: (myname titles) This is sent right after I login. It tells the client what my name is. This is needed because level 2 DGs do not use a "*" for my name (to avoid having to generate different messages for everybody) and because if I login with "g" the client needs to be told what my name is. ---------------PLAYER SETS------------------- Use the following DG types if you want to maintain a list of current players. The player info items such as DG_BULLET can be used only in conjunction with DG_PLAYER_ARRIVED. These DGs are considered verbose; they don't scale up well, resulting in too much data sent to the user when there are 1000+ people logged on. We no longer support these except for specially designated accounts such as Tomato. Here is the list of verbose DGs: DG_PLAYER_ARRIVED DG_PLAYER_LEFT DG_GAME_STARTED DG_GAME_RESULT DG_EXAMINED_GAME_IS_GONE DG_PEOPLE_IN_MY_CHANNEL DG_CHANNELS_SHARED DG_SEES_SHOUTS Currently, only TDs like Tomato can use these. As of the next boot after 12-Jan-2003, the following DGs are not shown if to you if you have tell=0 and the guy is a guest (just to save bandwidth to Tomato): DG_PLAYER_ARRIVED DG_GAME_STARTED 1 DG_PLAYER_ARRIVED This indicates that the client wants to maintain the set of logged in players. Whenever a player connects a DG_PLAYER_ARRIVED DG is generated of the following form: (playername ) The info depends on the setting of these level-2 variables described below: DG_BULLET, DG_BLITZ, DG_STANDARD, DG_WILD, DG_BUGHOUSE, DG_LOSERS, DG_CRAZYHOUSE, DG_FIVEMINUTE, DG_ONEMINUTE, DG_CORRESPONDENCE_RATING, DG_FIFTEENMINUTE, DG_THREEMINUTE, DG_FORTYFIVEMINUTE, DG_CHESS960. A rating will be sent for each rating datagram that has been turned on. Ratings are sent in pairs of numbers, first the rating and then the annotation, as described in DG_BULLET. The ratings will be sent in DG order, as listed above. Turn on modifier variables (e.g. DG_BULLET) before turning on this one. The info is a single number, as described in DG_OPEN. The info is a pair of fields (state plus game number), as described in DG_STATE. When this DG is turned on (with set-2 or during login), a raw list of DGs of this type is sent to me for all the current players. Note that when the server is crowded this can be a lot of data, so it is not recommended that this happen without the user expressly requesting it. 2 DG_PLAYER_LEFT A player disconnected. Form: (playername) 3 DG_BULLET "bullet" rating. The form of every rating is the following: (playername rating annotation) The rating is a decimal number. The annotation is 0 if the player has no rating in that category, 1 for a provisional rating, 2 for an established rating. Shouldn't get rating DGs for unregs. However this information will be included in the DG_PLAYER_ARRIVED type DG (just as a "0 0" for each rating selected). When level2setting[DG_BULLET]=1 and level2setting[DG_PLAYER_ARRIVED]=1, I get a rating DG any time someone's rating changes (i.e. when their game ends), and a dg_player_arrived message instead when I or he connect. If level2setting[DG_PLAYER_ARRIVED]=1, and I do a set-2 to enable DG_BULLET ratings, I get a list of bullet rating messages. No rating DG messages are sent unless DG_PLAYER_ARRIVED is also enabled. 4 DG_BLITZ "blitz" rating. (See DG_BULLET.) 5 DG_STANDARD "standard" rating. (See DG_BULLET.) 6 DG_WILD "wild" rating. (See DG_BULLET.) 7 DG_BUGHOUSE "bughouse" rating. (See DG_BULLET.) 88 DG_LOSERS "loser's" chess rating. (See DG_BULLET.) 121 DG_CRAZYHOUSE "crazyhouse" rating. (See DG_BULLET.) 125 DG_FIVEMINUTE "5-minute" rating. (See DG_BULLET.) 126 DG_ONEMINUTE "1-minute" rating. (See DG_BULLET.) 140 DG_CORRESPONDENCE_RATING "correspondence" rating. (See DG_BULLET.) 145 DG_FIFTEENMINUTE "15-minute" rating. (See DG_BULLET.) 149 DG_THREEMINUTE "3-minute" rating. (See DG_BULLET.) 150 DG_FORTYFIVEMINUTE "45 45 pool" rating. (See DG_BULLET.) 151 DG_CHESS960 "Fisher random pool" 3 1 rating. (See DG_BULLET.) Special note about DG_TIMESTAMP, DG_TITLES, DG_OPEN, and DG_STATE: Like the update messages above, these are only sent if you also have DG_PLAYER_ARRIVED enabled. This test was inadvertently omitted prior to Sept 1997. 8 DG_TIMESTAMP form: (playername timestamp-client-number) Timestamp Client information of this player: Actually these are never sent; they only appear as part of a player-arrived DG. 9 DG_TITLES form: (playername titles) Title DGs are rarely sent (only when somebody's titles change; most commonly, when an admin turns their "*" on or off). Again, these player-info DGs are only sent when DG_PLAYER_ARRIVED messages are also enabled. 10 DG_OPEN 0 or 1 11 DG_STATE form: (playername P 23) State information (including game number) P=playing E=examining S=playing simul X=none of the above indicates that this player is now playing game 23. If the state is X, then a game number of 0 is used. We haven't decided what the game number should be for someone giving a simul. It might be garbage for now, and/or a list of games in the future. 55 DG_PLAYER_ARRIVED_SIMPLE (name) This would be equivalent to having DG_PLAYER_ARRIVED without any the companion items enabled, except for one thing: when DG_PLAYER_ARRIVED is disabled during bandwidth emergencies, this one stays active. ---------------GAME LIST----------------- If you want to maintain a list of games in progress, use the following three DG types. It only makes sense to use all or none of them. These DGs are considered verbose; they don't scale up well, resulting in too much data sent to the user when there are 1000+ people logged on. We no longer support these except for specially designated accounts such as Tomato. 12 DG_GAME_STARTED Form: (gamenumber whitename blackname wild-number rating-type rated white-initial white-increment black-initial black-increment played-game {ex-string} white-rating black-rating game-id white-titles black-titles irregular-legality irregular-semantics uses-plunkers fancy-timecontrol promote-to-king) Indicate to me the start of games. (Or it may have started a while ago and I just logged in.) When this feature is activated, I get a list of all the games. It includes both regular and examined games. The list may take a while to transmit. whitename and blackname may contain punctuation, and while they currently have no spaces and are 15 characters or less, don't count on that. rating-type is a string such as "Blitz". rated is 1 or 0. white-initial and black-initial are in minutes. white-increment and black-increment are in seconds. played-game is 1 for real games and 0 for examined games. ex-string might be "Ex: continuation", and is at most 30 characters. white-rating and black-rating are the player's relevant ratings at game start, and are 0 for unrated players. game-id is a number that can be used to specify a stored game, e.g. with "sposition #902425349". So far, it's close to the Unix time of the game start, but that will no longer be true when we surpass 84000 games/day. irregular-legality is 0 normally, 1 if there are legal moves that wouldn't be legal in chess (i.e., turn off client-side legal move checking unless the client is familiar with this wild type) irregular-semantics is 0 normally, 1 for atomic chess and other variants where you can't update the board based on the last move by usual rules. (see also DG_SET_BOARD) uses-plunkers is 0 normally, 1 for bughouse and similar variants. fancy-timecontrol if non-null specifies a time control that supercedes the white-initial white-increment black-initial black-increment fields. The format is as in PGN, although we might extend that to allow Bronstein delays, time odds, and other strange situations. and to improve readability. Examples you might actually see: 40/7200:20/3600 (2 hours, plus an hour after 40th, 60th move, 80th move...) 40/5400+30:900+30 (90 minutes, plus 15 minutes after 40th move, plus 30 second increment throughout) ? (unknown -- best not to display clocks) - (untimed -- best not to display clocks) promote-to-king is 0 normally, 1 if it may sometimes be legal to promote a pawn to a king. 13 DG_GAME_RESULT Form: (gamenumber become-examined game_result_code score_string2 description-string ECO) This is sent when a played game ends. The "become-examined" bit is 1 if the game becomes an examined game. If it is zero, then the game is gone. This may also be sent when you look at a game which isn't currently being played; i.e., with sposition, or when you refresh or begin to observe an examined game. There are three outcome codes, given in the following order: (1) game_result, e.g. "Mat" (the 3-letter codes used in game lists) (2) score_string2, "0-1", "1-0", "1/2-1/2", "*", or "aborted" (3) description_string, e.g. "White checkmated" The ECO field is new as of November 2001. It may be "?" in many cases (maybe all cases) especially if it turns out that computing this is expensive, but we'll try it for now. 14 DG_EXAMINED_GAME_IS_GONE Form: (gamenumber) The last step of the life cycle of a game. Only generated for examined games. ---------------MY GAMES----------------- The following variables are used if you want to maintain more detailed information about "your" games, namely, the ones that you're playing, examining, or observing. We start with the most basic ones, which just let me identify the games that are "mine" and some basic information about them. The first three of these are identical to the three above. There is never any reason to use both. The server is supposed to send out the game-started DGs prior to the other detailed information (move lists etc). That way clients know upon receiving a DG_MY_GAME_STARTED or DG_STARTED_OBSERVING to create a game record and note the players' names, time controls etc, and then have a place to put other data as it comes in. The simplest way for the client to know when it is safe to destroy that game record is probably to watch for DG_MY_RELATION_TO_GAME messages with symbol "X". 15 DG_MY_GAME_STARTED This generates a DG that's exactly like DG_GAME_STARTED. Except that I know it's my game, and that I just started playing or examining. (If they're both turned on, then redundant messages are generated, but there's no need for them both to be on.) 16 DG_MY_GAME_RESULT Same as DG_GAME_RESULT. Generated for any game I'm playing, examining or observing. 17 DG_MY_GAME_ENDED Same as DG_EXAMINED_GAME_IS_GONE. I might be examining or observing the game, but note that I only get this when an examined game ends -- for played games ending, I get DG_MY_GAME_RESULT instead. 18 DG_STARTED_OBSERVING This is exactly the same as DG_MY_GAME_STARTED, but I'm an observer of the game, not a player or examiner. 19 DG_STOP_OBSERVING Form: (gamenumber) I just stopped observing a game. This is not sent if the game I'm watching ends, only if I stop watching it while it still exists. [This DG is probably not needed, given that you have DG_MY_RELATION_TO_GAME.] 40 DG_ISOLATED_BOARD This is the same as DG_STARTED_OBSERVING (and DG_GAME_STARTED etc), but I'm not observing the game, I just asked for an isolated peek (with "refresh " or "prefresh"). The commands sposition and smoves can also generated one of these, in which case the gamenumber will be -1. 20 DG_PLAYERS_IN_MY_GAME To keep track of who is observing the games I'm observing (or playing or examining). If this is set then when I start observing (or playing or examining) a game, I get a sequence of messages like: (gamenumber playername symbol kibvalue) The symbol indicates if this player is observing, playing, or examining the game. O=observing PW=playing white PB=playing black SW=playing simul and is white SB=playing simul and is black E=Examining X=None (has left the table) Note that the above are pair-wise mutually exclusive. The kibvalue indicates whether or not this player hears kibitzes or whispers. A player giving a simul might show up as PW when "at the board" and SW the rest of the time. 21 DG_OFFERS_IN_MY_GAME Form: (gamenumber wdraw bdraw wadjourn badjourn wabort babort wtakeback btakeback) Display of offers. The first 6 of these (after gamenumber) are bits. The last 2 indicate the number of moves requested to be taken back. [Any move resets opponent's offers. Currently an offer DG is NOT sent in this case. Turning on the DG does not squelch the text message.] 22 DG_TAKEBACK Form: (gamenumber takeback-count) A takeback occurred in the game that I'm observing or playing. 23 DG_BACKWARD Form: (gamenumber backup-count) A player backed up in an examined game. Also generated by the "revert" command. The following four variables control the format of the DG_SEND_MOVES and DG_MOVE_LIST DGs. These four are just variables and have no corresponding DGs, just entries in the DG_SEND_MOVES and DG_MOVE_LIST DGs. See also DG_IS_VARIATION. 33 DG_MOVE_ALGEBRAIC A.k.a. pretty or short form of move, e.g. Nf3 or fxg8=Q+. 34 DG_MOVE_SMITH This format is defined as follows: [][] 2 chars 2 chars 0 or 1 char 0 or 1 char The capture indicator is one of pnbrqkEcC. It indicates the type of piece captured. "c" indicates a short castling move (in which case the coordinates are for the king's movements), and C indicates a long castling move. A "E" indicates an en-passant capture. If it's not a capture, or castling move, the field is empty. The promotion information is one of "NBRQ", indicating the promoted piece. example: e4g5p is a N move from e4 to g5 capturing a pawn. f7f8Q is a queening move f7g8nQ is a pawn move capturing a knight and queening. One advantage of this system that it's easy to parse, and it's reversible--you can walk forward and backward through the move list only knowing the current position at a given time. The notation is a "improvement" of a notation suggested by Warren Smith. Note: bughouse plunks are the same in all move formats, e.g. "Q@f7+" Mystery kriegspiel moves are either "?" or of the form "?xb1". 35 DG_MOVE_TIME Number of seconds used by the player to make this move. 36 DG_MOVE_CLOCK Time (in seconds) on the player's clock after making this move (after incrementing). 24 DG_SEND_MOVES A move was made. Also sent when an examiner uses "forward". Form: (gamenumber algebraic-move smith-move time clock is-variation) where last five fields are OPTIONAL, controlled by the variables described above. With these and the DG_MOVE_LIST or DG_POSITION_BEGIN DGs, a smart client can reasonably disable sending of the board by using style 13. 25 DG_MOVE_LIST Loading of move list. If this variable is set, I get one of these DGs when: (1) I start observing a game. (2) I start playing or examining a game (though in this case it usually just looks like (gamenumber *), unless I'm resuming an adjourned game or it's a wild game. (3) I use the "refresh " command. (4) I use the "copygame" command. (5) An examiner edits the position of a game I'm observing or examining. (gamenumber initial-position {white-move1-info}{black-move1-info}{white-move2-info} ...) Initial-position is either "*" in the case of the normal initial position, or 64 characters indicating what occupies (-PNBRQKpnbrqk) each square, in lexigraphic order (a8 b8 ... h1). The move info is just as in DG_SEND_MOVE: five optional fields, algebraic-move, smith-move, time, clock, and is-variation. Turning it on with set-2 results in a DG_MOVE_LIST being sent for each game of one's games. gamenumber could be -1 in the case of a stored position (spos or smoves). See DG_POSITION_BEGIN for a better version of this information. 37 DG_BUGHOUSE_HOLDINGS Form: (gamenumber {white-holding} {black-holding}) where white-holding is a string such as PPNQ You won't get lines if you have these on and use style 13. 57 DG_BUGHOUSE_PASS (gamenumber color piece) Not implemented; if you want it, let me know. color is W or B. piece is one of PNBRQ. Only sent when there's a capture on partner's board. You also need DG_BUGHOUSE_HOLDINGS if only to find out the holdings when you start observing an ongoing bughouse game. (But it's probably safe to discard all but the first DG_BUGHOUSE_HOLDINGS message of any game and then maintain the list using these and the moves.) 26 DG_KIBITZ This is the level 2 version of kibitz. Form: (gamenumber playername titles kib/whi ^Y{kib string^Y}) kib/whi is 1 if it's a kibitz 0 if whisper. Normal form is inhibited if I get the level2 version. 38 DG_SET_CLOCK (gamenumber white-clock black-clock) Sent when a game I'm involved in has a clock adjusted, say by the moretime command. 39 DG_FLIP (gamenumber flip) flip=1 means I am Black or have asked to watch from Black's point of view. Normally precedes a DG_MOVE_LIST, and is sent in roughly the same situations, i.e. when I first see a game. Also sent in response to the flip command, in which case a dg_refresh follows. The client should not have to display the board on receiving the dg_flip, because either a dg_move_list or a dg_refresh will follow. 41 DG_REFRESH (gamenumber) [maybe not needed] This is the only DG I might get when you do "refresh " for a game which I am already observing or playing. Also sent on flip command. 42 DG_ILLEGAL_MOVE (gamenumber movestring reason) Sent when I issued an illegal move (and am playing or examining). The movestring is what I typed, up to a blank or 20 characters. Reason codes include: 1 Bad or ambiguous notation 2 Illegal (covers most of rules of chess) 3 King in check (don't ask why this is singled out) 4 Not your move 5 Bughouse and don't have the piece you're trying to drop 6 Bughouse and drop-square isn't empty 7 Bughouse and pawn drop attempted on first or eighth rank 8 Special restriction in some future wild game type 9 Wait a few seconds before entering moves in examine mode 10 You lost on time before making that move I get the text message anyway. 43 DG_MY_RELATION_TO_GAME (gamenumber symbol) Same as DG_PLAYERS_IN_MY_GAME, but just for me, and only has the two fields gamenumber and symbol. 44 DG_PARTNERSHIP (name name forming) Indicates a bughouse partnership has formed or dissolved. forming is 1 or 0. 49 DG_JBOARD The fields are: 64-char-board side on move (B or W) double-push-file as integer -1 to 7 castling rights (style-12 way e.g. 1 1 0 1 for any except Black O-O) move number of next move (1 + number-of-half-moves-made/2) algebraic last move (or {}) smith last move (handy for highlighting, I guess) white clock black clock status: played (1), examined (0), or stored (-1) flip Snapshot of a game info that could be derived from DG_MOVE_LIST, for clients that do not want to go that route. The J is for Java, because this was originally implemented for jicc (coffeehouse). DG_JBOARD is sent in approximately (maybe exactly) the same places as a style 12 board would be generated, if you were using that style. If you'd like a variation on this format added, email fishbait with detailed specifications and he might add it. 70 DG_FEN (gamenumber {FEN-string}) Presents the current position in Forsyth-Edwards notation. http://www.research.digital.com/SRC/personal/Tim_Mann/Standard has a description of FEN. DG_FEN is not sent on every move, but only on the same occasions that DG_MOVE_LIST might be sent. 56 DG_MSEC (gamenumber color msec running) Number of milliseconds on the clock (in range -2^31 to 2^31-1). Color is "W" or "B". Running is 0 or 1, and is intended to tell the client whether to make that clock tick down. These DGs are sent in the following situations: Played-game cases: (1) when someone makes a move in a played game, to give their new clock value, including increment earned. (2) when someone's clock starts running (2a) no-timestamp case, when it becomes his/your move (2b) timestamp case, not you, ack-board received (2c) timestamp case, your move now (inside ts signals) (3) when a played game starts (4) when a played game ends (5) on a takeback (6) setwhiteclock/setblackclock (but setting a moving clock is unpredictable) (~7) It is NOT sent in response to a moretime command. Examine-mode cases: [unclear what behavior we want here, but for now running=0 for these] (8) move in examined game (9) start of examined game (10) backward or revert (11) forward (12) setwhiteclock/setblackclock Misc: (13) spos (14) refresh of game not being observed 61 DG_MORETIME (gamenumber color seconds) Number of seconds added to color's clock in gamenumber. Color is "W" or "B". This one is superior to DG_MSEC when adjusting a moving clock. (Do not adjust timestamp alarm in response.) ---------------CHANNELS----------------- 28 DG_CHANNEL_TELL The level 2 version of a channel tell. If this is on, the normal form is inhibited. Form: (channel playername titles ^Y{tell string^Y} type) Type is similar to DG_PERSONAL_TELL: 1 normally, but 4 for an "atell" (typically a helper's response to your question). Below are DGs useful if you want to keep track of who else in the channels you're in. These DGs are considered verbose, and similar comments apply as for DG_PLAYER_ARRIVED and DG_GAME_STARTED. 27 DG_PEOPLE_IN_MY_CHANNEL Show who is in my channels. (channel playername come/go) "come/go" is 1 if he/she is in the channel 0 if not in the channel. A sequence of these with come/go=1 is generated whenever I enter a channel. I do get one for myself when I enter or leave a channel. When someone connects, if they subscribe to channels it is as if they join each one, unless I have DG_CHANNELS_SHARED on which presents the relevant data more compactly (see below). When I connect, if I don't have DG_CHANNELS_SHARED on I get many DG_PEOPLE_IN_MY_CHANNEL messages instead, which can easily overflow my output buffer. 46 DG_CHANNELS_SHARED (playername channels) A list of the channels that both the player and I are in. Not sent if the list is empty. Sent only when someone connects, and a list of them when I connect, or I do a set-2. Use DG_PEOPLE_IN_MY_CHANNEL to get updates about people joining or leaving channels. DG_CHANNELS_SHARED being on inhibits the sending of lists of DG_PEOPLE_IN_MY_CHANNEL messages on connection. This can still be a lot of characters, if you connect onto a crowded server while subscribed to many channels. See appendix 3. 45 DG_SEES_SHOUTS (playername bitvector) In the spirit of DG_PEOPLE_IN_MY_CHANNEL, for clients that want to have the same information for shouts and sshouts as for channels. Considered verbose. Bitvector is 0 if player sees neither 1 if player sees shouts but not sshouts 2 if player sees sshouts but not shouts 3 if player sees both Sent whenever somebody changes their shout or sshout variable, or if they connect and they see shouts or sshouts, or if I connect (in which case I get the list of people who see either). I get might it twice for myself on login. Not sent when a player disconnects. ---------------MATCHES----------------- 29 DG_MATCH This happens when I'm successfully challenged for a match. or when I successfully challenge another for a match. The text version is sent anyway. (We used to suppress it, but everybody seems to want it anyway.) Form: (challenger-name challenger-rating challenger-titles receiver-name receiver-rating receiver-titles wild-number rating-type is-it-rated is-it-adjourned challenger-time-control receiver-time-control challenger-color-request [assess-loss assess-draw assess-win] fancy-time-control) challenger-rating and receiver-rating are two numbers each: a rating and 0-2 as in rating DGs above. challenger-time-control is also two numbers (initial and increment). challenge-color-request is -1 normally, 0=Black, 1=White The assessment data is only included if DG_MATCH_ASSESSMENT is on. fancy-time-control is usually null {}, but if it isn't, see the notes of DG_GAME_STARTED for info on what it means. It overrides the time and inc if present, but those can still be used to estimate etime and we'll try to keep them vaguely close to the real TC. If you turn on DG_MATCH with set-2 you get one DG_MATCH message per pending challenge. 30 DG_MATCH_REMOVED This happens when a challenge is removed. The challenge is identified by the challenger-name and receiver-name. Form: (challenger-name receiver-name ^Y{Explanation string^Y}) Notice that this will break if we ever let you issue simultaneous challenges to the same person. When you start playing a game, you'll get DG_MATCH_REMOVED for other challenges to you, but those challenges aren't entirely gone -- when you stop playing if they're still there you'll get DG_MATCH for them again. 50 DG_SEEK Level-2 form of "seeking" messages, useful for maintaining the sought list at the client. Form: (index name titles rating provisional-status wild rating-type time inc rated color minrating maxrating autoaccept formula fancy-time-control) By the way, the maximum seeking index is currently 1999, although that could be increased if we start trying to handle thousands of people with one server. provisional-status is 0 (no games), 1 (provisional), or 2 (established), similar to other DGs that have ratings. fancy-time-control is usually null ({}), but if it isn't, see the notes of DG_GAME_STARTED for info on what it means. It overrides the time and inc if present, but those can still be used to estimate etime and we'll try to keep them vaguely close to the real TC. Enabling this DG causes the sought list to be sent as a series of these DGs. Normal text seek messages are suppressed when this DG is on. This DG accounts for a large fraction of the I/O sent from the server, it turns out. But it's awfully useful, so I can't see us doing away with it. We do disable it while you're playing, but then when your game is over it catches up. 51 DG_SEEK_REMOVED Form: (index reasoncode) Reason codes are 1 Seeker left 2 Seeker is playing 3 Seeker removed ad 4 Seeker replaced ad 5 Seeker not available (misc reasons) The server may send DG_SEEK_REMOVED for a DG_SEEKING which was not sent. 52 DG_MY_RATING (bullet-rating blitz-rating standard-rating wild-rating bughouse-rating) Your ratings. -1 if unregistered, 0 if registered but played no games. Sent when turned on, and when rating changes. Unfortuantely, the order does not match that of DG_RATING_TYPE_KEY, so I recommend using DG_NEW_MY_RATING intead. This one will probably not be extended for new rating types. 87 DG_NEW_MY_RATING (rating-0 rating-1 rating-2 ...) Your ratings, in the order specified by DG_RATING_TYPE_KEY. Rating of -1 if unregistered, 0 if registered but played no games. (Yes, I know, both are possible actual ratings, but big deal.) Sent when turned on, and when rating changes. ---------------COMMUNICATION----------------- 31 DG_PERSONAL_TELL The level 2 version of a personal tell. If this is on, the normal form is not generated. Form: (playername titles ^Y{tell string^Y} type) The type is 0 for "say", 1 for "tell", 2 for "ptell" (from bughouse partner), 3 would be qtell if we sent qtells this way (which we don't, they go with DG_PERSONAL_QTELL), and 4 for "atell" (from admin or helper). 62 DG_PERSONAL_TELL_ECHO Form: (receivername type ^Y{string^Y}) This indicates that the user sent a tell or say. String is the content of the tell. Type is 0 for "say", 1 for "tell", 2 for "ptell", 3 for qtell(?), 4 for atell. Perhaps we'll append some version of the diagnostic (e.g. "idle 6 minutes") to the end, or add another DG for that if there's need. [This documentation used to list the arguments in the wrong order.] 32 DG_SHOUT The level 2 form of shout, sshout and announce. Inhibits normal reception of these. Form: (playername titles type ^Y{shout string^Y}) The type is 0 for regular shouts, 1 for "I" type shouts, 2 for sshouts and 3 for announcements. ------- Miscellaneous ------- 47 DG_MY_VARIABLE Form: (variable-name value) Shows the value of some of the user-settable variables. Sent when one changes. All of them sent when this DG is turned on with set-2. Only the numeric variables are shown this way, so value is an integer. 48 DG_MY_STRING_VARIABLE Form: (variable-name value) Shows the value of some of the user-settable variables. Sent when one changes. All of them sent when this DG is turned on with set-2. These are the string-valued variables such as formula. The value is enclosed in OPENQ CLOSEQ quotes. 53 DG_SOUND Form: (code) Accompanies some or all bells (^G) sent to user. The code is small integer indicating a reason for the sound. #define SOUND_BELL 0 /* default not used */ #define SOUND_HELLO 1 #define SOUND_GOODBYE 2 #define SOUND_GNOTIFY 3 #define SOUND_CHALLENGE 4 #define SOUND_OFFER 5 #define SOUND_START 6 #define SOUND_END 7 #define SOUND_MOVE 8 /* not used yet: #define SOUND_USER_MOVE 9 #define SOUND_OPPONENT_MOVE 10 #define SOUND_OBSERVED_MOVE 11 #define SOUND_CHECK 12 #define SOUND_END_WIN 13 #define SOUND_END_LOSS 14 #define SOUND_OBSERVED_START 15 */ If you get a DG_NOTIFY_LEFT, please infer a SOUND_GOODBYE, because one is not sent. Similarly a DG_NOTIFY_ARRIVED implies a SOUND_HELLO that usually isn't sent (depends if there is an adjourned game involved). SOUND_MOVE should probably not be sent if you get DG_SEND_MOVES, because that's the worst place to waste bandwidth. I'm planning to make this change after checking with the other client writers. 63 DG_SUGGESTION Form: (command-string text-string priority suggester subject id) Sent by TDs or admins with qsuggest, and sometimes by server to encourage resumption of adjourned games. The idea is for the client to display both strings (with different colors or fonts?) in a message box (always-on-top but not modal?) and if the user clicks a YES button, send the command back to ICC. Normal priority is 0, meaning (perhaps) show it only if the user is not playing, and perhaps not if the user has commands pending. Perhaps priority 5 could mean always show it and make it task-modal, and 1-4 is in-between. ID is a string for use by DG_QRETRACT, to retract the suggestion. The current qsuggest command has the bizarre syntax: qsuggest [priority] player command-string#text-string#subject#id 59 DG_CIRCLE Form: (gamenumber examiner coordinate) Sent to observers and examiners when an examiner does the circle command. coordinate is of the form e4. The idea is that the examiner can highlight one or more squares with circles, and also draw arrows (see DG_ARROW), and these should all vanish when the position changes (a move forward or back). 60 DG_ARROW Form: (gamenumber examiner origin destination) Sent to observers and examiners in response to an arrow command. e.g. (37 fishbait e2 e4) ------- Notify list DGs and other new stuff ------ 64 DG_NOTIFY_ARRIVED Same form as DG_PLAYER_ARRIVED (with all of the same optional fields), but only for players on your notify list. Group names such as "&gm" are now interpreted in this mechanism. When you add someone who is present to your notify list, you do NOT get one of these, so you might want to refresh your friends-who-are-present list by setting this on again. How do you tell whether a received DG_NOTIFY_ARRIVED is the result of the initial stream of arrived messages? (rather than a user that has just arrived) Some clients manage this by bracketing the request for the notify list in DG_DUMMY_RESPONSEs. Anything in between the DG_DUMMY_RESPONSES is one of those: multi Set-2 81 1; Set-2 64 1; Set-2 81 1 Note: The disabling of text notifications when the datagrams are on is inconsistent. Setting DG_NOTIFY_ARRIVED and DG_NOTIFY_LEFT doesn't generate messages like "Notification: clientx has arrived." and "Notification: clientx has departed." If you want the text notifications, but have turned on the flags to get DG_NOTIFY_ARRIVED and DG_NOTIFY_LEFT datagram messages instead, you could generate the desired text messages yourself when you receive the datagrams. You'd probably only want to do this when these datagrams were not generated by DG_MY_NOTIFY_LIST. 65 DG_NOTIFY_LEFT Like DG_PLAYER_LEFT but only for players on your notify list. (Beware, you might get one for someone that you didn't realize was here, if the user modified his notify list in the meantime.) 66 DG_NOTIFY_OPEN Like DG_OPEN but only for people on your notify list. 67 DG_NOTIFY_STATE Like DG_STATE but only for people on your notify list. 68 DG_MY_NOTIFY_LIST (name yes/no) Sent when the user adds or removes a player (or group-name) from her notify list, and also a series of these is sent when first enabled. 69 DG_LOGIN_FAILED (code explanation-string) When the user's client gives us a name and password on the same line, we should get either issue DG_WHO_AM_I indicating success, or one of these. Maybe we send them in some of the password-on-separate-line cases too. Codes and explanation strings are currently as follows: 1 To register, please connect to the main server (chessclub.com). 2 Sorry, names may be at most 15 characters long. Try again. 3 A name should be at least two characters long! Try again. 4 Sorry, a name must begin with a letter and consist of letters and digits. Try again. 5 is a registered name. If it is yours, type the password. 6 is not a registered name. [and you gave a password] 7 is not a registered name. [n filtered] 8 is not a registered name. [but okay, hit return to enter] 9 Try again. [user typed null password] 10 Something is wrong. 11 Invalid password. 12 The administrators have banned you from using this chess server. 13 Something is wrong. 14 , whose name matches yours, is already logged in. Sorry. 15 StratLabs client trial expired. 16 Sorry, but this server cannot process account renewals or new accounts. Please connect to the main ICC server, chessclub.com, in order to activate your membership 17 The chess server is currently only admitting registered players. 18 The chess server is currently only admitting registered players. [full, no unregs allowed on queue] 19 The chess server is full. [quota] 20 You have entered the queue. Your current position is %d. 21 To register, please use our web page www.chessclub.com/register. 22 The account is restricted to using Blitzin and only on one particular computer. 72 DG_GAMELIST_BEGIN (command {parameters} nhits first last {summary}) command is one of search, history, liblist, or stored. parameters were the arguments to the command. nhits is the number of items in the list, but in the case of search (and possibly in future in the case of libraries) we don't necessarily show you the whole list. E.g. maybe we'll show items 1-20 (if your "height" is 24) and in that case first=1, last=20, and "more" can be used. "First" is usually 1, not the the index of the first DG_GAMELIST_ITEM. (Those indices are too screwy, wrapping modulo 100 in the case of history, and skipping integers in the case of libraries.) 73 DG_GAMELIST_ITEM (index id event date time white-name white-rating black-name black-rating rated rating-type wild init-time-W inc-W init-time-B inc-B eco status color mode {note} here) E.g. "16 898117179 ? 1998.06.17 16:59:39 heatwave 2461 SaabMaster 2383 1 1 0 3 0 3 0 B90 0 0 0 0 {}" The index is a history number, search hit number, liblist index, or adjourned game index. The id is ICC's internal game id, and can be used e.g. "examine #898117179". Any fields containing spaces will be quoted with curly braces. Unknown fields (or parts of a field in case of date & time) are given as ?, as per PGN. Event is usually ?, but could be a tournament id (typically 7 characters or less). Date is in the form YYYY.MM.DD, time is in the form HH:MM:SS (as per PGN spec), this is when the game started (and the format is as in PGN spec). Names are at most 15 characters, but are not necessarily ICC user names. Ratings may be - (meaning unrated) or numerical or ? (unknown). Rating-type is a small integer. For now, 0=wild, 1=blitz, 2=standard, 3=bullet, 4=bughouse. But see DG_RATING_TYPE_KEY. A time control given as "-" means untimed. Status, color, and mode are how ICC records a game result or adjournment: Status is 0=win 1=draw 2=adjourned 3=abort. Color is 0=black 1=white, and is the side that lost (for status 0) or maybe acted. Mode is a small integer, and the meanings of the various status-mode pairs are (Assume color is 0 for these, and the 3-letter code is just what is in history output): status 0: mode 0: (Res) Black resigns mode 1: (Mat) Black checkmated mode 2: (Fla) Black forfeits on time. mode 3: (Adj) White declared the winner by adjudication mode 4: (BQ) Black disconnected and forfeits mode 5: (BQ) Black got disconnected and forfeits mode 6: (BQ) Unregistered player Black disconnected and forfeits mode 7: (Res) Black's partner resigns mode 8: (Mat) Black's partner checkmated mode 9: (Fla) Black's partner forfeits on time mode 10: (BQ) Black's partner disconnected and forfeits mode 11: (BQ) Black disconnected and forfeits [obsolete?] mode 12: (1-0) White wins [specific reason unknown] status 1: mode 0: (Agr) Game drawn by mutual agreement mode 1: (Sta) Black stalemated mode 2: (Rep) Game drawn by repetition mode 3: (50) Game drawn by the 50 move rule mode 4: (TM) Black ran out of time and White has no material to mate mode 5: (NM) Game drawn because neither player has mating material mode 6: (NT) Game drawn because both players ran out of time mode 7: (Adj) Game drawn by adjudication mode 8: (Agr) Partner's game drawn by mutual agreement mode 9: (NT) Partner's game drawn because both players ran out of time mode 10: (1/2) Game drawn [specific reason unknown] status 2: mode 0: (?) Game adjourned by mutual agreement mode 1: (?) Game adjourned when Black disconnected mode 2: (?) Game adjourned by system shutdown mode 3: (?) Game courtesyadjourned by Black mode 4: (?) Game adjourned by an administrator mode 5: (?) Game adjourned when Black got disconnected status 3: mode 0: (Agr) Game aborted by mutual agreement mode 1: (BQ) Game aborted when Black disconnected mode 2: (SD) Game aborted by system shutdown mode 3: (BA) Game courtesyaborted by Black mode 4: (Adj) Game aborted by an administrator mode 5: (Sho) Game aborted because it's too short to adjourn mode 6: (BQ) Game aborted when Black's partner disconnected mode 7: (Sho) Game aborted by Black at move 1 mode 8: (Sho) Game aborted by Black's partner at move 1 mode 9: (Sho) Game aborted because it's too short mode 10: (Adj) Game aborted because Black's account expired mode 11: (BQ) Game aborted when Black got disconnected mode 12: (?) No result [specific reason unknown] Note is the libannotate string that sometimes accompanies a library game. Here is 1 if it's a stored list and opponent is present, otherwise 0. 74 DG_IDLE (name idle-time time-since-read) Idle-time is how long since the user entered something. Time-since-read is how long since the server has read anything on that input stream, including ping acknowledgements; values much higher than about 10 indicate the guy is lagged out. This is sent to TDs for players in their tournaments when idle time goes about 30 seconds, then again if it goes over 60 seconds, then 120, etc (keeps doubling). Soon I'll have it sent to the opponent in a game too. It is also sent when the player unidles (by typing or something) after having been idle for more than 30 seconds. 75 DG_ACK_PING (name lag-in-ms mean variance) Sent to TD when the server gets a ping back on a ping that it sent on its own (because the player was idle for 10+ seconds). Also sent to opponents. 76 DG_RATING_TYPE_KEY (index string) This is just a way for the server to tell the client the mapping between rating-type indexes and their usual English names. Turn it on and you'll get (0 Wild)(1 Blitz) etc, and then nothing thereafter. DG_MY_RATINGS should come in the same order, rating-type 0 first, but currently that is not the case. 77 DG_GAME_MESSAGE (gamenumber string) Encapsulates the text generated by miscellaneous commands that affect a particular game, e.g. mexamine, setwhiteclock, draw. [Implementation may be complete or redundant with other DGs?] 78 DG_UNACCENTED Not a DG at all, just a variable that tells the server that output to you should only contain US ASCII (plus the telnet codes for turning echo on and off, and stuff that timestamp deals with). Chars 191-254 in the ISO Latin-1 set, which are allowed in messages and so forth, are replaced some similar US ASCII character. (Blitzin 1.72 and older has this turned on artificially by the server, and similar arrangements can be made for your old clients if needed.) 79 DG_STRINGLIST_BEGIN (nhits {description}) At present this is for lists of strings that are normally presented in columns, such as the output of "=gm". It will be followed by a series of nhits DG_STRING_ITEMs. Enabling this suppresses the usual textual output, where it applies. (You may still get some diagnostic output as text in response to the command that generates the list.) 80 DG_STRINGLIST_ITEM (string) You'll have to note the DG_STRINGLIST_BEGIN and count, to know what list this belongs to. 81 DG_DUMMY_RESPONSE This DG does absolutely nothing, except that when you turn it on you get a DG_DUMMY_RESPONSE in response. 82 DG_CHANNEL_QTELL (channel name titles ^Y{qtell-string^Y}) qtells come from TD robots, and come with their own formatting information, specifically the symbol \n (two characters -- that's a real backslash) means break to a new line, \H \h delimit something that should be in bold, and \b is to be a bell. In the text form (which is suppressed when this DG is on) each line begins with the symbol >. Your client is not constrained to follow any of these suggestions, of course, but the \n one is important for Tomato's output to look nice. (Just eat the \H's if you don't want to bother boldifying). Qtell strings can be up to 1024 characters long. 83 DG_PERSONAL_QTELL Form: (playername titles ^Y{qtell-string^Y}) Qtells come from TD robots like Tomato. The string may contain some format info. See DG_CHANNEL_QTELL. 84 DG_SET_BOARD Form: (gamenumber 64-character-board side-to-move) The board position is given from a8, b8 ... h1, where N is a white knight etc. Side-to-move is W or B. This DG is only to be sent for irregular-semantics games such as atomic chess or fischer-random (which is irregular only in its castling moves, but that's enough). 85 DG_MATCH_ASSESSMENT Not a DG -- just modifies the semantics of DG_MATCH. 86 DG_LOG_PGN Sent only in response to the logpgn command. The contents are the PGN form of the game, one ^Y{quoted^Y} argument per line. 89 DG_UNCIRCLE Form: (gamenumber examiner coordinate) Sent to observers and examiners when an examiner does the uncircle command. coordinate is of the form e4. Do you want these also to be sent when the position changes? I'll assume not. There is currently no guarantee that there was ever a circle there, so don't assume anything. 90 DG_UNARROW Form: (gamenumber examiner origin destination) Sent to observers and examiners in response to an unarrow command. e.g. (37 fishbait e2 e4) 91 DG_WSUGGEST Form: (URL text-string priority suggester subject id) Similar to DG_SUGGESTION, but instead of a command-string the suggestion is a URL. The client should ideally pop up a dialog giving the user the option of going to that URL in their default browser. Priority value is the same as in DG_SUGGESTION. For priority 5+, we recommend just opening the page without waiting for confirmation. (Maybe the admin doing the wsuggest should send an explanatory personal tell in that case.) 94 DG_MESSAGELIST_BEGIN Form: (command-string) Sent before a set of DG_MESSAGELIST_ITEMS. 95 DG_MESSAGELIST_ITEM Form: (index sender time date message) One is sent with each message to you displayed by the messages command. ("messages " also lists messages from you to that player, but these are NOT sent in the DG form.) The text form is sent in any case. 96 DG_LIST Form: (header rowstart item1 item2 ....) Typical example is a list of players, e.g. the output of "=censor". The server normally displays these in columns, the way the UNIX command "ls" does. But that's no good if you don't use a fixed-width font, or if the server doesn't know the width of the window. So here's what you can use to do that yourself. Header is not used yet, but will probably at some point contain some description of what the collection of data is. If the header is present, I recommend displaying it before the list, then a colon and newline. rowstart is usually a string like " " which the server likes to put at the beginning of each row. You can ignore it. The items are in some kind of sorted order, although for most (all?) situations that order is not all that crucial. Sometimes the list is empty. 97 DG_SJI_AD Form: (free-form-text) This is for the Simple Java Interface, to feed it the text or URLs to display, stuff like "Want to watch grandmasters play? Download BlitzIn and join the Internet Chess Club!". Sent to by the admin command sji-ad. (Currently it is not sent when you turn it on, but I'm flexible.) 99 DG_QRETRACT Form: (id) Retract the DG_SUGGESTION or DG_WSUGGEST with the same id, if any such suggestion is still pending. 100 DG_MY_GAME_CHANGE Form: same as DG_GAME_STARTED This is just like DG_MY_GAME_STARTED except that the game didn't just start, but instead one or more parameters changed, such as the name of the White player. 101 DG_POSITION_BEGIN (gamenumber {initial-FEN} nmoves-to-follow) Designed as a replacement for DG_MOVE_LIST. Advantages are that the initial position can specify Black on move, and can specify castling rights, en passant legality, and initial move number (but you could ignore the move number if you want). And also DG_MOVE_LIST was sometimes too big for a really long game, while with this method no DG is excessively long. If you have this on and also have DG_SEND_MOVES on, then you get this followed by nmoves-to-follow DG_SEND_MOVES. If the initial position is the standard one, the initial-FEN field can be null (but don't count on it). DG_POSITION_BEGIN2 might be slightly more convenient. 103 DG_TOURNEY (index bitfield description join-command watch-command info-command confirm-text) Designed to allow an easy way for users to see what tourneys they can join, and a way to join them just by clicking. The join-command (and watch-command and info-command) may include multiple commands separated by &, and a backslash in one of those strings quotes the character after it. If the index matches a DG_TOURNEY already sent, this one supercedes it (typically, to update information about how many people have already joined). Naturally, DG_TOURNEY can also be used for simuls, play-the-master, observing championships, and other such events. If confirm-text is non-empty, the client should pop up an OK/Cancel box displaying that text, and only issue the join-command on an OK. When you turn on DG_TOURNEY you get a list of the ongoing events. Turning on DG_TOURNEY does NOT suppress any sshouts or whatever that Tomato might do. The index is just some integer used to identify the event within the tourney list. Bitfield is an integer, where (bitfield & 1) means guests can perhaps watch and/or join, (bitfield & 2) means don't make a new window when sending the join commands, (bitfield & 4) means don't make a new window when sending the watch commands, and (bitfield & 8) means don't make a new window when sending the info commands. It's no big deal if you ignore these bits. Here's a sample DG_TOURNEY: 6 0 {tell Tomato join & +chan 46} {Tomato Blitz tournament, Swiss system, 5-minute games, have 3 players, looking for 8..16} {This tournament will take an hour or two, are you sure you will have time to complete it?} TD/admin commands for managing this list of events: qaddevent | | | | | The pipe character '|' is used to separate the categories of commands, and '&' may be used to separate multiple commands within a category. \| and \& serve if you want those characters. If the group field is present, only members of that group will see this item. Examples: qaddevent 1 7 Kasparov - Leko game (being played at Linares, Spain) live discussion and analysis. | | observe 1 | finger Linares2000 | qaddevent 100 4 Blitz tournament! Tomato 5 0 Swiss, have 3 players, looking for 8..16. | tell tomato join & tell 46 Hi, I'm in | | tell tomato info | This tournament will take an hour or two, are you reasonably sure you will have time to complete it? qremoveevent The qaddevent line may be long (1000 characters perhaps). Description and confirm-text are limited to 319 characters each, and the command lists are limited to at most 99 characters each. It is up to the TDs and admins to manage the indices and not to trod on each others toes. TDs are limited to indices 40-999, and could perhaps just use their traditional channel numbers. General-use command for listing the events just as text: "events". 104 DG_REMOVE_TOURNEY (index) Indicates that that tourney or special event is no longer open or interesting. The client should happily ignore any of these that it gets for events where it never saw the corresponding DG_TOURNEY. The DG_DIALOG stuff is so the server can describe a dialog window (like a form) to Blitzin. The order they'll be sent in is as follows: DG_DIALOG_START One or more DG_DIALOG_DATA Loop until server decides the user has dealt with this dialog correctly: Zero or more DG_DIALOG_DEFAULT DG_DIALOG_END DG_DIALOG_RELEASE (maybe) These will not be nested; you'll only have to deal with them one at a time. If you get a DG_DIALOG_START before having gotten a DG_DIALOG_RELEASE for the previous dialog, please imagine you got the DG_DIALOG_RELEASE. (Currently the code never sends the release, but maybe I'll fix that.) 105 DG_DIALOG_START (size-in-bytes) Precedes any other DG_DIALOG_* units. The size is the total number of 8-bit bytes that the DG_DIALOG_DATA blocks that follow specify. characters per byte). 106 DG_DIALOG_DATA (one-block-of-encoded-binary-data) This is a binary description of the dialog window (.res format). Each two characters represents one byte, as follows: 'a' + (n >> 4) 'a' + (0x0f & n) One or more of these DGs can occur in a row. 107 DG_DIALOG_DEFAULT (control-number type value) Assigns a default value to a control in the dialog. "type" separates string from boolean controls (radiobuttons and checkboxes), and can have the value "s" (string), "b" (boolean), "c" (combo box), or "l" (list box). "value" is the string itself, or "0" or "1" or booleans, or a 0-based index of the selected item in a combo or list box. Zero or more of these DGs can occur in a row. 108 DG_DIALOG_END (is-modal focus command-on-OK command-on-CANCEL command-on-IDYES command-on-IDNO) This causes the dialog to be displayed. It's probably okay to do the dialog as modal even if is-modal is False, but not the other way around, please. Focus is the control number of the control that should have the focus initially. The command string is arbitrary, and often will contain newlines, including a newline at the end (so don't add one). It also contains printf-like text-substitution symbols: %15s extracts the string value of the 15th control %7b extracts the boolean value ("0" or "1") of the 7th control %3c returns the index of the currently selected item in the combo box at position 3, 0 for the topmost item, etc. Similarly for %5l and list boxes. (I'm not sure list boxes are useable because it's not clear to me how to get the choices listed.) Trivial example: "tell ROBOAdmin ratings %2s %3s %4s\n" [is that backslash-n or newline?] 109 DG_DIALOG_RELEASE () Sent after the server figures you're done with that dialog. Until then, keep the data and default values because you may get more DG_DIALOG_DEFAULTs and another DG_DIALOG_END, e.g. if the user sends some unacceptable value. 110 DG_POSITION_BEGIN2 Same as DG_POSITION_BEGIN, but instead of DG_SEND_MOVEs follow, you get DG_PAST_MOVEs. 111 DG_PAST_MOVE Same form as DG_SEND_MOVE Used only in conjunction with DG_POSITION_BEGIN2 112 DG_PGN_TAG (gamenumber tagname value) Useful for building the PGN (Portable Game Notation) representation of a game, or for getting fuller information about an ongoing game (especially a broadcast game) such as site or full names, when that information is known to the server. Only sent for games you're playing or watching, not for things like sposition at this time, though that may change. For now, only the seven required tags are sent. 113 DG_IS_VARIATION Appends a (is-variation) field to DG_SEND_MOVE. This is intended for Bert's logit application which is building a variation tree when observing a game. Even with all of this, logit is unlikely to build a sensible tree, but it's a start. Possible values are: 0 MOVE_INITIAL Main line, part of a DG_POSITION_BEGIN (either play or examine mode) 1 MOVE_PLAYED Main line, play mode. 2 MOVE_FORWARD Main line, examine mode, the result of "forward 1", for example. 3 MOVE_EXAMINE A move in examine mode, make what of it you will. 4 MOVE_OVERWRITE A move in examine mode, intended to overwrite a previous line. (Not implemented yet) 5 MOVE_MAINLINE A move in examine mode, intended to be the new main line. (Not implemented yet) 6 MOVE_SIDELINE A move in examine mdoe, intended to be a side line. (Not implemented yet) 114 DG_PASSWORD Form: (new-password handle) Sent when you change your own password (in the normal case where you know what you're changing it to). It's conceivable that it could be sent to you for someone else's account for some reason, e.g. when creating a non-free-trial-eligible account, but we're not there yet. 116 DG_WILD_KEY (index string) This is a way for the server to tell the client what to name the chess variants. Turn it on and you'll get (0 {Chess}) (1 {Shuffle both}) etc., and nothing thereafter. Long-time users are more used to the wild numbers than the names, so you probably want to include both in the display. There's some chance that we may have a server where you can only play certain wild types, so don't assume consecutive integers. 120 DG_SWITCH_SERVERS (server-name port IP-number) The server name will be something like "rook.chessclub.com". The client should close the connection to the server (or just wait for it to close -- the server will kick the user out when it sends this DG) and reconnect to the specified server. Use the same handle and password there. 124 DG_SET2 (dg-code off/on) Sent in acknowledgement of a set-2 command. 128 DG_MUGSHOT (Player URL gamenumber) e.g. DG_MUGSHOT Darooha http://www.chessclub.com/mugshots/darooha.jpg 312 Indicates that there's a picture of this player at the specified web site, and that it would probably be appropriate to show it. Sent along with game info when starting a game (or starting to observe one), and also with finger, and maybe at other times during a game. Gamenumber might be -1, e.g. for the finger case. The player name will usually be one of the two players, or it might be just W or B to indicate the color (esp. for examined games with weird player names.) 129 DG_TRANSLATION_OKAY Set this if it's okay for the server to translate text to the user's language. This may include things like "Illegal move" which some existing clients parse (instead of using DGs like good little clients). Blitzin doesn't need to set this, it's just assumed that Blitzin can handle translations. 131 DG_UID Adds a field to DG_PLAYER_ARRIVED, the unique permanent user id number for this account. 132 DG_KNOWS_FISCHER_RANDOM Enable this if your client knows the castling rules to Fischer Random Chess (wild 22), and can therefore update the board just given DG_SEND_MOVE. 136 DG_COMMAND (command all-arguments) Echoes the command being done. This is only sent to the user issuing the command. There would be one of these for each command processed in a multi-command line. Aliases are expanded. Note that even if the command took several arguments, this DG has only the two fields. 137 DG_TOURNEY_GAME_STARTED (event-label white black id gamenumber) Notification that a tournament game has started or resumed. The server assumes it's a tournament game if event-label is non-empty. 138 DG_TOURNEY_GAME_ENDED (event-label white black id score-string2) Notification that a tournament game has ended or been adjourned. scores-string2 is the same as in DG_GAME_RESULT: "0-1", "1-0", "1/2-1/2", "*", or "aborted". 139 DG_MY_TURN (gamenumber) Sent when it becomes my turn to play in a game. The information about the board position and clocks will already have been sent. This DG is mainly intended for robots. 141 DG_DISABLE_PREMOVE (gamenumber) This means don't allow premove during this game. (This DG cannot be turned off, once you've turned it on.) 142 DG_PSTAT (initiated, kind, p1, p2, ...) initiated: 0 - by the start of a game 1 - by a command p1: player1 name p2: player2 name The next section repeats for each rating type (bullet, blitz, etc.) Each rating record is seperated by a | with p1 having white * p1 wins * p2 wins * draws with p1 having black * reverse color p1 wins * reverse color p2 wins * reverse color draws * rating number Example: icc% set-2 142 1 icc% pstat wohl fishbait (142 1 wohl fishbait 0 0 0 1 0 0 1 | 0 1 0 0 0 0 1 | 5 4 6 2 1 3 1)icc% If the player receiving the DG is either player then they are always p1 You can only a receive a DG_PSTAT with 0 game start for a game your in For 1 - pstat command p1 is the player listed first on the command line if two players are listed that is. If only one player is given to the pstat command the other is defaulted to the giver of the command and will therefore become p1 under if your one of the results your listed first rule. vars shows pstat variable after allowkib set pstat 0 (default does not send pstat info) set pstat 1 (sends pstat info on game start) pstat wimpc shows my scores vs wimpc pstat jeeves wimpc shows scores of wimpc vs jeeves As always, for the command pstat version (pstat foo) the L2 DG_PSTAT is sent embedded inside a L1 datagraom for the CN_PSTAT. As always if the user does pstat lalala (where lalala doesnt exist) there is no DG_PSTAT response (commands that generate a DG dont do so on error). The level 1 DG for CN_PSTAT will have the error text. The game started DG_PSTAT is probably sent inside the CN_ for whichever command started the game if the current user did it else bare. So if I did "accept" the DG_PSTAT would be inside the CN_ACCEPT L1 but for the user who matched me the DG_PSTAT would be top level. If the user does pstat lalala and lalala does exist but has no records vs the user then the DG_PSTAT is sent with no rating record If a game starts and they players have no record in that rating catagory a record is still sent with zeros for the stats in that one rating type Game start records only have one record, the one for that games rating type 143 DG_BOARDINFO (143 game-number examiner-name type coord1 coord2 color) Examined game artwork like (see DG_ARROW or DG_CIRCLE for similar). type (integer) 0 clear all lecture marks 1 undo 4 arrow 5 rectangle 6 highlight 7 throbbing pieces 8 ghost pieces coord1 (two character string, e.g. a1) coord2 (two character string, e.g. b2) color (integer) 0 black 1 red 2 orange 3 yellow 4 light green 5 dark green 6 light blue 7 dark blue 8 pink 9 white 144 DG_MOVE_LAG (143 player lag) player: text name of the user who just made a move and whos lag info is reported lag: lag in milliseconds. Lag is the time charged to the move, that is, if the move took 25 ms and the user was charged 100 ms due to the minimum this number would be 100. Only goes to the two players, not to observers. DG is only sent if timestamping is on. ------------------------------------- Some possibly useful client commands: ======================================= set-quietly "variable" "value" Like set, but doesn't echo anything. ======================================= yfinger ["player"] A weird version of finger. ======================================= Command : boardinfo Usage : boardinfo [] boardinfo is used by Dasher to tell the server about a lecture mark made in examine mode. Like circle and arrow this is only valid while examining. It is undocumented, but issuable by all users. should be one of the following values: 0 clear all lecture marks 1 undo 4 arrow 5 rectangle 6 highlight 7 throbbing pieces 8 ghost pieces and are algebraic squares, such as e4. They define the square(s) that are affected by the mark. For type 0 and 1, these arguments are ignored. For type 4 (arrow), is the origin and is the destination. Otherwise, and are assumed to be the two corners of a rectangle on the chess board. Pass the same square for both and to operate on a single square. affects arrows and highlighted squares. If given, it should be one of the following values: 0 black 1 red 2 orange 3 yellow 4 light green 5 dark green 6 light blue 7 dark blue 8 pink 9 white Examples: boardinfo 4 a1 h8 8 <-- Draws a pink arrow from a1 to h8 boardinfo 5 d4 e5 <-- Draws a rectangle around d4, e4, d5, and e5 boardinfo 6 e1 e1 3 <-- Highlights the e1 square in yellow BlitzIn only supports arrows and circles. BlitzIn users will see type 4 marks as arrows. They will see type 6, 7, and 8 marks as circles on every square in the rectangle. Similarly, Dasher users will see BlitzIn circles as highlighted squares. Known bugs/limitations: * The type and color ranges aren't validated and do not produce error messages. * Undo in Dasher can only handle up to 127 marks. * With 5,000 people observing an examined game, it could be a bit of bandwidth to send all those unarrows and uncircles on type 0 and 1. See also: arrow, circle ------------------------------------- Appendix 1: Command code numbers for level 1. /* command codes for level 1 */ /* moves and other special commands */ /* CN stands for command number */ #define SCN_UNKNOWN 0 #define SCN_ILLEGAL_MOVE 1 #define SCN_MOVE 2 #define SCN_EDIT_EXAMINED 3 #define SCN_PING_RESPONSE 10 #define SCN_WEIRD 11 #define SCN_REALLY_LOG_IN 12 #define SCN_MOED 13 #define SCN_EVENTS 14 #define SCN_NEWS 15 #define SCN_LOGOUT 16 #define SCN_TIMEOUT 17 #define SCN_CONNECT 18 #define SCN_REALLY_QUIT 19 #define SCN_LOGIN 20 #define SCN_PASSWORD 21 #define SCN_REGISTRATION 22 #define SCN_EXTENSION 23 #define SCN_AUTHENTICATION 24 #define SCN_BAD 25 #define SCN_AUTOMATIC 26 #define SCN_CONFIRM 27 #define SCN_MULTI_DISCARD 28 #define SCN_IDLE 29 #define SCN_ACK_PING 30 #define SCN_MISCELLANEOUS 31 /* commands in command list */ #define CN_TELL 101 #define CN_I 102 #define CN_SHOUT 103 #define CN_SHOUT0 104 #define CN_SLASH 105 #define CN_WHO 106 #define CN_SET 107 #define CN_FLAG 108 #define CN_SAY 109 #define CN_CHANNELTELL 110 #define CN_SSHOUT 111 #define CN_BAD 112 #define CN_KIBITZ 113 #define CN_WHISPER 114 #define CN_EXAMINE 115 #define CN_MEXAMINE 116 #define CN_COPYGAME0 117 #define CN_COPYGAME 118 #define CN_FORWARD 119 #define CN_BACK 120 #define CN_MATCH 121 #define CN_MATCH0 122 #define CN_ACCEPT 123 #define CN_HELP0 124 #define CN_HELP 125 #define CN_MORE 126 #define CN_NEWS 127 #define CN_NEWS0 128 #define CN_HISTORY 129 #define CN_FINGER 130 #define CN_VARS 131 #define CN_UPSTATISTICS 132 #define CN_UNEXAMINE 133 #define CN_ADJOURN 134 #define CN_ASSESS 135 #define CN_OBSERVE0 136 #define CN_OBSERVE 137 #define CN_FOLLOW0 138 #define CN_FOLLOW 139 #define CN_ECO 140 #define CN_STYLE 141 #define CN_BELL 142 #define CN_OPEN 143 #define CN_DECLINE 144 #define CN_REFRESH 145 #define CN_RESIGNADJ 146 #define CN_REVERT 147 #define CN_RATED 148 #define CN_RANK 149 #define CN_MOVES 150 #define CN_MAILOLDMOVES 151 #define CN_MAILSTORED 152 #define CN_MAILHELP 153 #define CN_PENDING 154 #define CN_GAMES 155 #define CN_ABORT 156 #define CN_ALLOBSERVERS 157 #define CN_INCHANNEL 158 #define CN_INFO 159 #define CN_MORETIME 160 #define CN_BEST 161 #define CN_QUIT 162 #define CN_QUOTA 163 #define CN_LLOGONS 164 #define CN_LHISTORY 165 #define CN_LOGONS 166 #define CN_TIME 167 #define CN_TAKEBACK 168 #define CN_SEARCH 169 #define CN_SEARCH0 170 #define CN_SMOVES 171 #define CN_SPOSITION 172 #define CN_PASSWORD 173 #define CN_MESSAGE 174 #define CN_MESSAGE0 175 #define CN_CLEARMESSAGES 176 #define CN_DATE 177 #define CN_LIST 178 #define CN_PLUS 179 #define CN_MINUS 180 #define CN_ZNOTL 181 #define CN_FLIP 182 #define CN_PROMOTE 183 #define CN_EXPUNGE 184 #define CN_IWCMATCH 185 #define CN_LIMITS 186 #define CN_PING 187 #define CN_EXTEND 188 #define CN_QTELL 189 #define CN_GETPI 190 #define CN_STARTSIMUL 191 #define CN_GOTO 192 #define CN_SETCLOCK 193 #define CN_LIBLIST 194 #define CN_LIBSAVE 195 #define CN_LIBDELETE 196 #define CN_LIBANNOTATE 197 #define CN_LIBKEEPEXAM 198 #define CN_PARTNER 199 #define CN_PARTNER0 200 #define CN_PTELL 201 #define CN_BUGWHO 202 #define CN_WILDRANK 204 #define CN_XOBSERVE 205 #define CN_PRIMARY 206 #define CN_DRAW 207 #define CN_RESIGN 208 #define CN_STATISTICS 209 #define CN_STORED 210 #define CN_CHANNELQTELL 211 #define CN_XPARTNER 212 #define CN_YFINGER 213 #define CN_SEEKING 214 #define CN_SOUGHT 215 #define CN_SET2 216 #define CN_PLAY 217 #define CN_UNSEEKING 218 #define CN_AWAY 219 #define CN_LAGSTATS 220 #define CN_COMMANDS 221 #define CN_REMATCH 222 #define CN_REGISTER 223 #define CN_RESUME 224 #define CN_CIRCLE 225 #define CN_ARROW 226 #define CN_BLANKING 227 #define CN_RELAY 228 #define CN_LOADGAME 229 #define CN_DRAWADJ 230 #define CN_ABORTADJ 231 #define CN_MAILNEWS 232 #define CN_QSET 233 #define CN_CC_START 234 #define CN_CC_LIST 235 #define CN_CC_MOVE 236 #define CN_CC_DELETE 237 #define CN_CC_QSTART 238 #define CN_CC_QLIST 239 #define CN_CC_QLABEL 240 #define CN_CC_QDELETE 241 #define CN_CC_QADJUDICATE 242 #define CN_CC_ASK_DIRECTOR 243 #define CN_LOADFEN 244 #define CN_GETPX 245 #define CN_UNRELAYED 246 #define CN_NORELAY 247 #define CN_REFER 248 #define CN_PGN 249 #define CN_SPGN 250 #define CN_QFOLLOW 251 #define CN_QUNFOLLOW 252 #define CN_QMATCH 253 #define CN_QPARTNER 254 #define CN_ISREGNAME 255 #define CN_REQUIRETICKET 256 #define CN_ANNOTATE 257 #define CN_CLEARBOARD 258 #define CN_REQUEST_WIN 259 #define CN_REQUEST_DRAW 260 #define CN_REQUEST_ABORT 261 #define CN_LOGPGN 262 #define CN_RESULT 263 #define CN_FEN 264 #define CN_SFEN 265 #define CN_SETGAMEPARAM 266 #define CN_TAG 267 #define CN_TOMOVE 268 #define CN_REGENTRY 269 #define CN_PERSONALINFO 270 #define CN_EVENTS 271 #define CN_QADDEVENT 272 #define CN_GLISTGROUPS 273 #define CN_GLISTMEMBERS 274 #define CN_GINVITE 275 #define CN_GJOIN 276 #define CN_GLISTINVITED 277 #define CN_GLISTJOINING 278 #define CN_GDESCRIBE 279 #define CN_GKICK 280 #define CN_GBEST 281 #define CN_SIMULIZE 282 #define CN_GAMEID 283 #define CN_FIVEMINUTE 284 #define CN_QIMPART 285 #define CN_GMESSAGE 286 #define CN_COMPLAIN 287 #define CN_LASTTELLS 288 #define CN_VIEW 289 #define CN_SHOWADMIN 290 #define CN_PSTAT 291 #define CN_BOARDINFO 292 Appendix 2. DG code numbers for level 2. /* level 2 codes */ /* (DG stands for datagram, but that's a misnomer) */ #define DG_WHO_AM_I 0 #define DG_PLAYER_ARRIVED 1 #define DG_PLAYER_LEFT 2 #define DG_BULLET 3 #define DG_BLITZ 4 #define DG_STANDARD 5 #define DG_WILD 6 #define DG_BUGHOUSE 7 #define DG_TIMESTAMP 8 #define DG_TITLES 9 #define DG_OPEN 10 #define DG_STATE 11 #define DG_GAME_STARTED 12 #define DG_GAME_RESULT 13 #define DG_EXAMINED_GAME_IS_GONE 14 #define DG_MY_GAME_STARTED 15 #define DG_MY_GAME_RESULT 16 #define DG_MY_GAME_ENDED 17 #define DG_STARTED_OBSERVING 18 #define DG_STOP_OBSERVING 19 #define DG_PLAYERS_IN_MY_GAME 20 #define DG_OFFERS_IN_MY_GAME 21 #define DG_TAKEBACK 22 #define DG_BACKWARD 23 #define DG_SEND_MOVES 24 #define DG_MOVE_LIST 25 #define DG_KIBITZ 26 #define DG_PEOPLE_IN_MY_CHANNEL 27 #define DG_CHANNEL_TELL 28 #define DG_MATCH 29 #define DG_MATCH_REMOVED 30 #define DG_PERSONAL_TELL 31 #define DG_SHOUT 32 #define DG_MOVE_ALGEBRAIC 33 #define DG_MOVE_SMITH 34 #define DG_MOVE_TIME 35 #define DG_MOVE_CLOCK 36 #define DG_BUGHOUSE_HOLDINGS 37 #define DG_SET_CLOCK 38 #define DG_FLIP 39 #define DG_ISOLATED_BOARD 40 #define DG_REFRESH 41 #define DG_ILLEGAL_MOVE 42 #define DG_MY_RELATION_TO_GAME 43 #define DG_PARTNERSHIP 44 #define DG_SEES_SHOUTS 45 #define DG_CHANNELS_SHARED 46 #define DG_MY_VARIABLE 47 #define DG_MY_STRING_VARIABLE 48 #define DG_JBOARD 49 #define DG_SEEK 50 #define DG_SEEK_REMOVED 51 #define DG_MY_RATING 52 #define DG_SOUND 53 #define DG_PLAYER_ARRIVED_SIMPLE 55 #define DG_MSEC 56 #define DG_BUGHOUSE_PASS 57 #define DG_IP 58 #define DG_CIRCLE 59 #define DG_ARROW 60 #define DG_MORETIME 61 #define DG_PERSONAL_TELL_ECHO 62 #define DG_SUGGESTION 63 #define DG_NOTIFY_ARRIVED 64 #define DG_NOTIFY_LEFT 65 #define DG_NOTIFY_OPEN 66 #define DG_NOTIFY_STATE 67 #define DG_MY_NOTIFY_LIST 68 #define DG_LOGIN_FAILED 69 #define DG_FEN 70 #define DG_TOURNEY_MATCH 71 #define DG_GAMELIST_BEGIN 72 #define DG_GAMELIST_ITEM 73 #define DG_IDLE 74 #define DG_ACK_PING 75 #define DG_RATING_TYPE_KEY 76 #define DG_GAME_MESSAGE 77 #define DG_UNACCENTED 78 #define DG_STRINGLIST_BEGIN 79 #define DG_STRINGLIST_ITEM 80 #define DG_DUMMY_RESPONSE 81 #define DG_CHANNEL_QTELL 82 #define DG_PERSONAL_QTELL 83 #define DG_SET_BOARD 84 #define DG_MATCH_ASSESSMENT 85 #define DG_LOG_PGN 86 #define DG_NEW_MY_RATING 87 #define DG_LOSERS 88 #define DG_UNCIRCLE 89 #define DG_UNARROW 90 #define DG_WSUGGEST 91 #define DG_TEMPORARY_PASSWORD 93 #define DG_MESSAGELIST_BEGIN 94 #define DG_MESSAGELIST_ITEM 95 #define DG_LIST 96 #define DG_SJI_AD 97 #define DG_RETRACT 99 #define DG_MY_GAME_CHANGE 100 #define DG_POSITION_BEGIN 101 #define DG_TOURNEY 103 #define DG_REMOVE_TOURNEY 104 #define DG_DIALOG_START 105 #define DG_DIALOG_DATA 106 #define DG_DIALOG_DEFAULT 107 #define DG_DIALOG_END 108 #define DG_DIALOG_RELEASE 109 #define DG_POSITION_BEGIN2 110 #define DG_PAST_MOVE 111 #define DG_PGN_TAG 112 #define DG_IS_VARIATION 113 #define DG_PASSWORD 114 #define DG_WILD_KEY 116 #define DG_SWITCH_SERVERS 120 #define DG_SET2 124 #define DG_FIVEMINUTE 125 #define DG_ONEMINUTE 126 #define DG_TRANSLATIONOKAY 129 #define DG_UID 131 #define DG_KNOWS_FISCHER_RANDOM 132 #define DG_COMMAND 136 #define DG_TOURNEY_GAME_STARTED 137 #define DG_TOURNEY_GAME_ENDED 138 #define DG_MY_TURN 139 #define DG_CORRESPONDENCE_RATING 140 #define DG_DISABLE_PREMOVE 141 #define DG_PSTAT 142 #define DG_BOARDINFO 143 #define DG_MOVE_LAG 144 #define DG_FIFTEENMINUTE 145 #define DG_PHRASELIST_UPDATE 146 #define DG_PHRASELIST_ITEM 147 #define DG_MENU_SPEAK 148 #define DG_THREEMINUTE 149 #define DG_FORTYFIVEMINUTE 150 #define DG_CHESS960 151 Appendix 3: Sizes of various fields and buffers Names (player handles) are at most 15 characters, presently, but it is possible that we might go to longer names at some point. The ex-string describing an examined game is at most 25 characters. The description-string in a game result is at most 100 characters. Games are now limited to 10000 moves for each color. Tells are less than 2000 characters. Except for qtells, they should all be 320 characters or fewer. But don't count on that in a big way. qtells can be 1000 or so. Each player's output buffer is about 122000 characters. After that, you get a control-Z, and the remainder of the output to you from the offending command is discarded. Turning on all the DGs and logging in when the server has a lot of players might well overflow your buffer. Client writers are encouraged to minimize bandwidth requirements, both for the benefit of their own users and to reduce the total bandwidth load on the server. Count on ICC growing, and make sure your client can scale up. If a client does encounter output-buffer overflow, a reasonable way to try to recover is to turn off all DGs, then turn on the essential ones one at a time. Note that you will have missed some data, so any lists you were maintaining might now be wrong. Where possible, it's better to turn on DGs one at a time after logging in, instead of turning them on at login prompt. Although as things stand now, the user might be reattaching and thrown into a game instantly, so it's good to have enough DGs on that he can play his game. But certainly anything nonessential like DG_SEEK should be turned on using set-2 after logging in.