kgsGtp

Introduction

kgsGtp is a java program that connects Go playing programs to the KGS Go server. It talks GTP to your engine (the Go program), giving commands like "play b c3" or "genmove w" and receives the engine's responses. It then does some clever proprietry KGS protocol stuff to get the moves enacted in the game running on the server.

If your engine can talk enough GTP to keep kgsGtp happy, people can play your program - cool!

Total RESPECT and thanks to wms for this.

Links to kgsGtp how-to pages

• The current documentation file kgsGtp.xhtml comes with the GTP client download, but is apparently not available anywhere on the web. An obsolete version for version 3.3.8 is available here.

• Connecting a Go-playing program to KGS

• Step-by-step instructions for GNU Go

A few other things you need to know

• If your engine tries to play an illegal move, kgsGtp terminates the engine process and your Bot 'escapes' from the game. This is very annoying to humans, so test the engine well before leaving it 'open' for others (You should log in yourself and resign to fix these escapes);

• If your engine spits out debugging information during a game (whoops!) because you forgot to take those printf's or whatever out before trying it live, kgsGtp usually kills the engine too. You aren't speaking legal GTP, so fair enough;

dnerra: You should have directed the debugging info to stderr in the first place.

• If you don't implement 'undo' in your engine, kgsGtp will reset the board and play out all previous moves up to the last one for you (clever!);

• If your engine is opening new games everytime it completes (open=true in kgsGtp config file up to version 3.3.8), it's quite hard to stop it cleanly without annoying the human. I get Dumbbot to check for a special file's presence after receiving a 'boardsize' command and terminating if it's there. This would work well, but I haven't implemented 'undo' yet and if 'undo' is given the above process is carried out; the board reset includes a 'boardsize' command which kills the engine :-( Don't fall down that hole.

• You must have java 1.5 to run a newish version of kgsGtp.

• Make sure your engine handles ko rules correctly. Several times people have complained that kgsGtp was killing their engine, leaving messages about illegal moves that they thought were legal moves. In fact, the moves were illegal by the superko rule, and the game was using a non-Japanese rule set, but the engine (and the engine operator) were both hazy on exactly how superko worked.^[1] The error message talks about "ko rule" only, even if it is superko.

Wishlist for kgsGtp

1. I'd love a 'kgs-get_comment' command which conveyed a message to the Bot and asked for a response. You could then ask it for info during the game or ask for a summary from it's perspective at the end. +

wms: Not a bad idea. One problem is that since GTP is a fully serial protocol, you won't get answers to your questions until after the computer is done thinking, so you either have to ask on your own time or sit and wait for the computer to move before you see an answer. Otherwise though it would be quite easy.
This would be a good start. I would very much appreciate that. However I don't see the problem with seriality: gtp allows you to use identifiers for your commands, so you could get the answers in another sequence than the commands. Then its up to the engine to handle the commands in whatever sequence (or parallel) it wishes. - Dolgan

dnerra: That is not true. The engine may not reorder the answers.
Dolgan: So what is the purpose of command ids? But even if you had to wait, it would be a great feature to ba able to use talk. dnerra: The command ids add redundance to make parsing of the answer stream easier (and less error-prone).
Dolgan: After re-reading the specs I have to say that you are right. But since 'kgs-get_comment' would be a kgs-only extension one could accept a breach of standard there (only for this command) and allow an out-of-the-order reply to kgs-get_comment. What do you think?

dnerra: I can pretty much promise you that this will never get implemented in GNU Go. I also doubt wms will want to implement this in kgsGtp. I think you underestimate how much the assumption of seriality is hardwired into the code.

wms: dnerra is right. Making all the commands serial makes it about 10x easier for both kgsGtp and for the engine. I'm not going to add this huge level of complexity unless absolutely necessary. And, in fact, I don't use command IDs, and I never send a command until I get a response from the previous - doing things in lockstep like this make the code much simpler, and makes debugging much much simpler.

Dolgan: Okay, okay. ;-) disrupting standards wouldn't be the best possible style , too. wms, are you going to implement the command in an in-order way? I think it would be really useful for debugging and things like that. Having to wait is not nice but not that bad either, the command would still be very useful.

wms: Perhaps, but not anytime soon. (PS - got rid of all those nested ">" things, the nesting seemed to do no good but make it harder to read.)

bigfatcat working on KibitzBot i would like to suggest, that the KGS-GTP-client could offer an interface and a registration method for intercepting kgs-chat commands (asynchronously). After registration the chat will not be sent to the engine but be passed to the Implementation of the interface (java only). That would allow for a more elegant way to communicate to the engine while it is calculating a move. Currently i have "solved" this matter by using a second robot, that can be talked to instead.

2. I'd like the possibility to deny overriding of game settings. So you could ensure that you are under a given ruleset, timing, ... - Dolgan
3. The possibility to give more than one name in the opponent option. - Dolgan

wms: "opponent" option is meant so that you can test your engine against somebody specific (maybe another engine) by having them both come on then play each other while you watch. It's not meant to be a way to limit who is using the engine in general, just a way to make testing easier. I don't plan on allowing multiple users, it seems to me that it serves its intended use just fine as it is. This comment applies to #5 below also.

4. Inform the engine about the opponent, so that it can adapt its playing style to known weaknesses (Though that poses a possibility for cheaters) - Dolgan

bigfatcat: I would like to have such feature too, it would allow for a lot of features for bots and meta-engines. My suggestion would be to send something like "kgs-opponent <name>" to the engine, if the engine supports the command. If the answer from the engine is an error, a match with that player will not be accepted, this implies that the command would be one of the first ones on game setup. Probably this would more or less solve "3." in this list. If engines are not wanted to decline opponents, then "kgs-opponent <...>" would still be good to have.

5. A possibility to use both open and opponent options, so that the engine challenges any oppenent(s) given in the opponent option, and if none is available opens a game for all - Dolgan
6. If rulesets can be overwritten, I think the engine should be informed of the ruleset, and be able to reject it like boardsize - Dolgan
7. I would really appreciate an option to refuse rated games with improper handicap. That's what most humans do, after all. --dnerra

I second that one, it's really annoying --nando

8. Options as to what time / rules / board size settings are allowed. Current documentation says that the engine should return GTP errors to reject settings, but that is not correct use of GTP by my reading -- engines are in general required to accept commands they don't like if at all possible. So I would like a way for my engine to accept only some settings but still return truthful answers to the GTP commands. --Evand

wms: To my reading, if your engine cannot play a reasonable game with a certain time setting (or whatever), then returning an error is the right way to do so. The GTP spec doesn't say "return errors if you can't parse the data" or anything like that, it says that you should return errors if you cannot accept the command - and if you are asked to play with 5 seconds/move, and your engine's fastest setting is 30 seconds/move, then I would call that a command that you cannot accept. See below for more on this topic.

Evand: Particularly for rated games and time settings, I see a difference between the engine being able to play under certain settings and "wanting" to. For example, expecting GNU Go to play at blitz speed will work, and under normal circumstances it will drop its level of play to match the remaining time, but it will lose strength cery rapidly -- usually much faster than a person. So if the maintainer wants to establish a rating, they probably only want rated games slow enough to let GNU Go stay at whatever level they want it to play at.

Aloril: I think rated games are only possible if all settings are exactly as specified in options file: same ruleset, same time settings for example. If you change anything except handicap your game against bot turns into free. So I don't see any problems for rated games with current system.

wms: Aloril is right. Evand, I assumed all along you were talking about free games, because the problems you describe above don't exist in ranked games! In ranked games, they are rejected unlessy our opponent goes with *exactly* what the person who ran the engine specified. So it seems your requests were actually solved already, before you even submitted them. :-)

9. A way to have a program challenge an opponent but take white. Currently the only way to challenge is to set the opponent field, but that makes it impossible to take white. Specifically, I'd like to be able to challenge another computer program without having to get in touch with the maintainer to set up the game. --Evand

10. Some way for the program to know a game is over, eg a "kgs-cleanup" command. My program tends to invalidate sections of its opening book in play, with the result that the first move of the next game is very slow. This could be fixed by doing the cleanup between games, but I would prefer not to do it by eg thinking a lot in response to a "boardsize" command. --Evand

wms: One issue I have with a lot of these requests is that I think you are ignoring your opponent's wants. I feel that putting go engines on KGS should be an exchange; the engine author gets a lot of games to look at for help improving the engine, and gets some fame (notoriety?) for their engine; and in return, the people who play the engine get to have fun doing so. If somebody wants to play your engine in a free game with ridiculous handicap/komi/time settings/whatever, then they should be able to do so! It doesn't cost you much, and it's fun for the user, so why not just let it happen? To say "this engine is on KGS, trolling for opponents, but it will only play exactly the type of games I want", well, to me that's just being sort of selfish. If you want games with KGS players, you have to let them choose the komi and handicap if they want...on the other hand, if your engine just collapses when New Zealand rules (for example) are used, that is a problem, because AFAIK there is no way to express rule sets in GTP. Anybody know, is there a way to do it? If not, is there any interest in making a GTP extension to do so?

Evand: That said, I think there needs to be some fairness to the engine authors too. I think that particularly for rated games, engine authors should get as much say as any other player in what games to accept or not. If other people don't like the settings the program wants to play under, then the program won't get many games. As a matter of courtesy, I think programs (and human players too!) should try to accept a broad range of settings, especially in free games, but I don't think that should be enforced by anything other than natural social pressures. All that said, thanks very much for providing kgsGtp -- it's a very useful tool to have around.

wms: Evand, as I said above, it is already the way you want. Engine authors get to decide exactly what the rules and time limits of ranked games will be. It is the "for-fun" free games where I think you should let the human players decide what the game looks like...if they put in stupid settings to make it easy for them to win, well, that's their business.

dnerra: Apart from my wish to refuse rated games with improper handicap :) I really think it would be in the best of the KGS rating system, too, because users having found a particular weakness of an engine can inflate their ranks by playing games with improper handicap again and again...

I don't see a way to set the ruleset in GTP. I think that's a fundamental enough thing that it should be specified in standard GTP, rather than as a KGS extension. I would suggest bringing up the question on the GTP mailing list.

11. Some way to cleanly turn the bot OFF in such a way that you can make sure it is not in the middle of a game when it happens. At the moment, the only way I know of to stop my bot is to wait until its game is almost done then run over to my server and Ctrl+C the process. I see two ways of implementing this.

1. A disconnect is triggered by a certain string in chat from a certain user, declared in the conf file.

2. The conf file specifies how many games are played until a disconnect. Then it is simple to set that value to '1' and make a shell script to keep reconnecting the program until some environment variable is changed. Anonymous- I think, too, that this is the best solution; it avoids also that you have to make changes in the engine (for example by not implementing the "clear_board" command, and other hacks)

Or does something like this already exist and I am simply unaware of it?

hgmichna: Consider that a powerful computer with multiple processor cores can easily run something like 8 bots at a time. It would be best to have a quick and simple way to have them all stop after each has finished the current game. A stop file in the folder where kgsGtp resides would be one simple way to do that. In fact, I rarely run bots, only because I don't know how to stop them without interrupting games.

bigfatcat: The functionality can be programmed and actually has been programmed (how many times ever). I tried python first, which did not work, probably due to threading issues. But java just works fine, though intercepting commands and sending them to the engine or answering directly takes a bit of queueing and so on. It is a hack, somehow, extending list_commands answer by kgs-chat and kgs-game_over, if necessary. This allows for shutting down after a number of games, on chat messages and similar. Maybe i will provide source and jar some time.

12. A way to change/reduce the amount of time kgsGtp will wait for an escaper to return. The default currently ties up bots for 5 mins per escaper (when other people might want to play).

hgmichna: Some people, including me, think that 5 min are just fine. No urgency here. Consider that a temporary communications or computer failure, perhaps requiring a reboot of the user's computer, can eat up much of 5 min. The really bad thing is that kgsGtp also waits 5 minutes until it tries to reconnect after it got disconnected. That is far too long, and, unfortunately, disconnects are a regular occurrence on KGS.

13. Perhaps a way to specify a range of acceptable values for things the opponent can change (ruleset, time limit, handicap, komi, etc..). For example: {chinese, aga} (but not jp or nz); an upper and lower bound on absolute time (I've had people set the time limit to hours and then do nothing... DoS), and a per move range for overtime; and an allowable komi range would be nice (people sometimes set +/- 80), and a way to suggest the default komi (since the (5, 8) komi is usually incorrect for non-standard board sizes).

I think the above could best be accomplished by introducing a private GTP extension, kgs-settings: where the opponents requested settings are sent (encoded in one line), and the bot replies with the closest settings that it will accept. This kills 2 birds with 1 stone: constrains the settings that the bot will play under, and informs the bot of the settings it's playing under. Or even just allow this on a per command basis (i.e. handle komi, rules, etc... like time_settings). Whatever, just let me recommend and reject komi!

14. Open up kgsGtp source code, and I (and no doubt many others) will add features for you!

15. I am 100% pleased with kgs-time_settings. time_settings is certainly a gaping hole in the GTP spec. I am less than pleased with time_left for byo-yomi, however. Since the current protocol does not specify what to do for byo-yomi, I understand that some choice needed to be made. But why not: color period_time num_periods? In canadian byo-yomi you get time and number of stones... doesn't period_time and num_periods seem to make a nice parallel construction? And like canadian b-y, when we are still in main time "periods" would be zero, just like "stones". But perhaps you have adopted a sort of de facto standard that's been created in absence of GTP specs and I am not aware of it. So I guess my wish is: let's have time_settings make better sense under byo-yomi. erislover

16. Robots are no escapers. Applying the escaper policy to them is pretty much pointless and clearly unfair (since they can't do anything about it).

Riff Raff: Though it certainly depends on the programmer. You could easily program a bot that disconnects itself from KGS when, for example, GNU Go would normally resign. From the server's perspective, it can't trust bot programs to behave well any more than it can assume humans will.

nando: Well, that would certainly be even more ridiculous than human escapers. In any case, what chances are given to bots to show their "good will" ? Can they automatically resume unfinished games when opponents are around ? If yes (maybe I missed it), how ? If not, how can I implement a routine to get my bot to resign all games where it got disconnected and the opponent didn't wait long enough ? or refuses to resume ? (and please don't forget that bots do play a lot more games than humans)

17. kgsGtp should automatically claim wins on time.

18. Following up on my comment in point 16, I'm often noticing lines like Game "xxx [8k] vs. yyy [6k]" loaded, I'm already playing, so I can't join in the kgsGtp output. Since bots are a lot less idle than human players, what about getting the bot to propose resuming unfinished games when it's possible (opponent is present and not playing) before it sets a new game up ?

19. The error message in case the client engine violates the superko rule should contain the word "superko". This may save some time for beginners.

20. I'd like to get rid of the "ACTION IS TO MOVE OR SCORE" line that is written to the terminal window when I start the client the java -jar .. way.

21. A "stopAfterFinish"- method at the GtpClient? client would be fine (for programmers who use the java library way). In that case the program could end connection when it sends the "kgs-game_over" GTP-command.

22. A few player play with AyaMC2 10-20 games in a day. I want various people. Is there any restriction that one person can play 3 games in a day against one bot? HYamashita(Aya's author)

[1]Hikaru79: Not just superko -- some engines (GNU Go) cannot deal with suicide moves if you're under New Zealand rules. It took me quite a while to figure out why my engine kept crashing due to "illegal moves" until I actually saw one of those games in action. I changed the ruleset to Japanese and no more problems have happened since then. So a note to bot owners: New Zealand rules is not good for GNU Go just yet.

See also

• KGSWishlist/kgsGtp Other Wishes are on this page