A user. Always an object. Users are sent in downstream messages, but upstream just the name is provided. It would have been cleaner to have the user flags a separate JSON fields, but users are sent a lot and I didn't want to use so much bandwidth.
| Field | Meaning |
|---|---|
| name | The user name |
| rank | The rank of the user. Optional; missing means no rank. |
| flags | A string. Each character in the string represents a flag. See below. |
| authLevel | Optional. One of normal, robot_ranked, teacher, jr_admin, sr_admin, or super_admin. If not present, then it is normal. |
| Flags | |
| g | Guest |
| c | Connected (logged in right now) |
| d | Account has been deleted |
| s | User is sleeping (more than 10 minutes since last interaction) |
| a | User has an avatar. |
| r | User is a robot. |
| TT | User has won a KGS tournament. |
| t | User has been runner up in a KGS tournament. |
| p | User is currently playing in a game. |
| P | User is currently playing in a KGS tournament game. |
| * | User is a KGS Plus subscriber. |
| ! | User is KGS Meijin |
| m | User is on a mobile device |
| = | User can play ranked games. |
| ~ | User plays stronger players far more often that weaker ones. |
A role indicates how a player is involved in a game. A player may hold more than one role in a game. Represented as a string. It can be one of:
Game flags are usually used as fields in a message, with a boolean value. The flags are:
On KGS, SGF files are dynamic. A change in an SGF file is reperesented by an SGF Event object. Every SGF event has two mandatory fields: nodeId that is the ID of the SGF node where the event takes place, and type, that indicates what happened and what type of data is in the object.
Playbacks have some additional "SGF Events." These aren't really related to SGF, but the playbacks store them mixed in with SGF changes so that as the file is played back, the SGF file will change in sync with the audio track and teacher's mouse poniter.
| type | Field | Meaning |
|---|---|---|
| PROP_ADDED | prop | A SGF property that has been added to the node. |
| PROP_REMOVED | prop | A SGF property that has been removed from the node. |
| PROP_CHANGED | prop | A SGF property that has been modified. Find another property with the same type and (if applicable) same location, and replace it with the property given here. |
| CHILDREN_REORDERED | children | An array of node IDs, indicating the children of this node, in their new ordering. Note: This SGF event type is only supported as a downstream event. Clients must not send it upstream to the server at this time. |
| CHILD_ADDED | childNodeId | The ID of the new child (which is a child of the current node). |
| position | Optional. This is the order, in the child list, of the current child. If this is missing, then it is child 0 (the first child) of the current node. | |
| PROP_GROUP_ADDED | props | A list of properties to add. |
| PROP_GROUP_REMOVED | props | A list of properties to remove. |
| ACTIVATED | prevNodeId | Indicates that the focus of the game has switched to this node. prevNodeId is the previous active node. |
| POINTER_MOVED | x | Floating point. The x-coordinate of the pointer. (For playbacks only). |
| y | Floating point.The y-coordinate of the pointer. (For playbacks only). | |
| TIMESTAMP | time | Floating point. Current time offset into the playback. |
| SPEEX_FPP | fpp | The frames per packet for SPEEX data in this playback. |
| SPEEX_MUTE_CHANGED | mute | Speex was muted/unmuted. Playbacks only. |
| SPEEX_DATA | data | base64 encoded SPEEX data. Playbacks only. |
The SGF in KGS is not quite like "standard" SGF. Multiple marks of the same type are considered different properties, so for example TR[aa][bb][cc] on KGS would be three different properties, one for each location. All rules-related properties (SZ[], TM[], etc) are grouped together in one "rules" property, etc. Furthere, some properties, such as DEAD, are not part of SGF but are used internally by KGS to track the state of the game board.
The fields present in a node may be:
| Property Name | Fields |
|---|---|
| RULES | The fields of a KGS rules object are present. |
| GAMENAME | text |
| PLAYERNAME | color, text |
| DATE | text |
| COPYRIGHT | text |
| GAMECOMMENT | text |
| EVENT | text |
| ROUND | text |
| PLACE | text |
| PLAYERTEAM | color, text |
| ANNOTATOR | text |
| SOURCE | text |
| TRANSCRIBER | text |
| MOVE | color, loc |
| CIRCLE | loc |
| PHANTOMCLEAR | loc |
| ADDSTONE | color, loc |
| TIMELEFT | color, float |
| LABEL | loc, text |
| TRIANGLE | loc |
| SQUARE | loc |
| TERRITORY | color, loc |
| DEAD | loc |
| COMMENT | text |
| RESULT | text; see score, although numeric results are in a string. |
| SETWHOSEMOVE | color |
| MOVENUMBER | int |
| MOVENAME | text |
| CROSS | loc |
| UNKNOWN | text |
| ARROW | loc, loc2 |
| LINE | loc, loc2 |
| DONESCORING | Special case: Will have fields black and white, as booleans, indicating which players have sent "done" status to the server. |
The rules for a game. Always represented as a JSON object.
| Field | Meaning |
|---|---|
| size | The size of the board. 2 through 38 are supported by KGS. |
| rules | One of japanese, chinese, aga, or new_zealand. |
| handicap | Not present for handicap 0. At most 9. |
| komi | A floating point number. Must be a multiple of 0.5, -100.0 through +100.0. |
| timeSystem | One of none, absolute, byo_yomi, or canadian. |
| mainTime | Time for the main time period, in seconds. Not needed when your time system is none. Up to 2147483 seconds. |
| byoYomiTime | Time for each byo-yomi period. Only needed for Canadian and Byo-Yomi time systems. Up to 2147483 seconds. |
| byoYomiPeriods | Number of byo-yomi periods. Only needed for byo-yomi time system. At most 255. |
| byoYomiStones | Number of stones per byo-yomi period. Only needed for Canadian time system. At most 255. |
A game summary is a permanent record of a game. Game channels come and go as games are loaded and closed, but a game summary stays for 6 months on the server (and forever in the online archives).
| Field | Meaning |
|---|---|
| size | The size of the board from this game. |
| timestamp | The time stamp of when this game was started. This is also used as a serverwide ID for the game; no two games will ever have the same timestamp, and the time stamp is used to refer to the game summary. |
| gameType | One of demonstration, review, rengo_review, teaching, simul, rengo, free, ranked, or tournament. |
| score | Optional. The score of the game. Not present if the game hasn't ended yet. |
| revision | Optional. The revision is used when downloading an SGF file; every SGF file has the path /games/year/month/day/white-black-revision.sgf. If revision is missing here, then it is not in the URL either. |
| players | An object mapping roles to user objects, telling who was in the game. The user objects in this map are snapshots of the players at the time the game started; you should ignore all the flags in them other than the rank information (which may not be the current rank of the player). |
| tag | Only present in tag archives. The tag associated with the game summary. |
| private | Optional. If set, this is a private game. If the flag is missing, that is the same as false. |
| inPlay | Optional. If set, the game is currently in play. If the flag is missing, that is the same as false. |
| tag | Only present when listing game summaries from a tag archive. This is the game for the game. |
A game channel is a game currently being played, or it may be a challenge (an attempt to set up a custom game). There are several cases where game channels are described in a message, and they always contain these fields.
| Field | Meaning |
|---|---|
| channelId | Channel ID of the game |
| gameType | The game type. |
| initialProposal | The proposal that the challenge owner uploaded initially. For challenge game types only. |
| Various | The fields for the rules of the game are present (not for challenge games). |
| score | The final score of the game. Missing if the game isn't over yet. |
| moveNum | The current move number of the game. |
| observers | The number of people observing the game. Missing if there are none. |
| roomId | The room that contains this game. |
| Various | The game flags. |
| name | Optional. If the game has a name, it is here. |
| players | An object mapping role to user. |
A proposal is an offer to start a game. It includes the rules and may include some or all of the players. If all the players needed are present in the proposal, then it is called a "complete" proposal.
Note: The first player in a proposal must always be the challenge owner. When manipulating a proposal, in general leave the player list in the order it started; if you want to change the roles for each player, change the role field and not the player field. You will get strange results if you don't do this.
| Field | Meaning |
|---|---|
| gameType | The game type of the game. |
| rules | The rules for the game. |
| nigiri | If set, that means nigiri will be used to determine who plays white. |
| Various | The game flags may be present. |
| players | A list of players. All roles for this game type must be present. |
| Player | |
| role | The role of the player. |
| name | Upstream only. The name of the player. In incomplete challenges, leave any unassigned roles with no player. |
| user | Downstream only. The user who is filling this role. Will not be present in incomplete challenges. |
| handicap | Only present for black players in simul games. The handicap for this player. |
| komi | Only present for black players in simul games. The komi for the player. |
Always a list. Each element of the list is an object. They indicate when you had a subscription, and thus which playbacks you can view (if you have a subscription now).
| Field | Meaning |
|---|---|
| start | Time of the start of this subscription period. |
| end | The end of this subscription period. |
Scores may be a floating point number, or a string. Numbers indicate the score difference (positive a black win, negative a white win). Strings may be UNKNOWN, UNFINISHED, NO_RESULT, B+RESIGN, W+RESIGN, B+FORFEIT, W+FORFEIT, B+TIME, or W+TIME.