Included gomill framework for SGF and GTP support, and sketched out SGF game-loading code.
This commit is contained in:
parent
700a6a2f32
commit
692dc294d6
119 changed files with 27458 additions and 3 deletions
133
gomill/docs/gtp_extensions.rst
Normal file
133
gomill/docs/gtp_extensions.rst
Normal file
|
@ -0,0 +1,133 @@
|
|||
GTP extensions
|
||||
==============
|
||||
|
||||
Gomill supports a number of |gtp| extension commands. These are all named with
|
||||
a ``gomill-`` prefix.
|
||||
|
||||
|
||||
The extensions used by the ringmaster are as follows:
|
||||
|
||||
.. gtp:: gomill-explain_last_move
|
||||
|
||||
Arguments: none
|
||||
|
||||
Return a string containing the engine's comments about the last move it
|
||||
generated.
|
||||
|
||||
This might include the engine's estimate of its winning chances, a principal
|
||||
variation, or any other diagnostic information.
|
||||
|
||||
The intention is that |gtp| controllers which produce game records should
|
||||
use this command to write a comment associated with the move.
|
||||
|
||||
Any non-ASCII characters in the response should be encoded as UTF-8.
|
||||
|
||||
If no information is available, return an empty string.
|
||||
|
||||
The behaviour of this command is unspecified if a command changing the board
|
||||
state (eg :gtp:`!play` or :gtp:`!undo`) has occurred since the engine last
|
||||
generated a move.
|
||||
|
||||
|
||||
.. gtp:: gomill-describe_engine
|
||||
|
||||
Arguments: none
|
||||
|
||||
Return a string with a description of the engine's configuration. This
|
||||
should repeat the information from the :gtp:`!name` and :gtp:`!version`
|
||||
commands. Controllers should expect the response to take multiple lines.
|
||||
|
||||
The intention is that |gtp| controllers which produce game records should
|
||||
use the output of this command as part of a comment for the game as a whole.
|
||||
|
||||
If possible, the response should include a description of all engine
|
||||
parameters which affect gameplay. If the engine plays reproducibly given the
|
||||
seed of a random number generator, the response should include that seed.
|
||||
|
||||
Any non-ASCII characters in the response should be encoded as UTF-8.
|
||||
|
||||
|
||||
.. gtp:: gomill-cpu_time
|
||||
|
||||
Arguments: none
|
||||
|
||||
Return a float (represented in decimal) giving the amount of CPU time the
|
||||
engine has used to generate all moves made so far (in seconds).
|
||||
|
||||
For engines which use multiple threads or processes, this should be the
|
||||
total time used on all CPUs.
|
||||
|
||||
It may not be possible to meaningfully respond to this command (for example,
|
||||
if an engine runs on multiple processors which run at different speeds); in
|
||||
complex cases, the engine should document how the CPU time is calculated.
|
||||
|
||||
|
||||
.. gtp:: gomill-genmove_ex
|
||||
|
||||
Arguments: colour, list of keywords
|
||||
|
||||
This is a variant of the standard :gtp:`!genmove` command. Each keyword
|
||||
indicates a permitted (or desired) variation of behaviour. For example::
|
||||
|
||||
gomill-genmove_ex b claim
|
||||
|
||||
If :gtp:`!gomill-genmove_ex` is sent without any arguments (ie, no colour is
|
||||
specified), the engine should return a list of the keywords it supports (one
|
||||
per line, like :gtp:`!list_commands`).
|
||||
|
||||
Engines must ignore keywords they do not support. :gtp:`!gomill-genmove_ex`
|
||||
with no keywords is exactly equivalent to :gtp:`!genmove`.
|
||||
|
||||
The following keywords are currently defined:
|
||||
|
||||
``claim``
|
||||
In addition to the usual responses to :gtp:`!genmove`, the engine may also
|
||||
return ``claim``, which indicates that the engine believes it is certain
|
||||
to win the game (the engine must not assume that the controller will act
|
||||
on this claim).
|
||||
|
||||
|
||||
There is also an extension which is not used by the ringmaster:
|
||||
|
||||
.. gtp:: gomill-savesgf
|
||||
|
||||
Arguments: filename, list of |sgf| properties
|
||||
|
||||
Write an |sgf| game record of the current game.
|
||||
|
||||
See the :term:`GTP` specification's description of :gtp:`!loadsgf` for the
|
||||
interpretation of the ``filename`` argument.
|
||||
|
||||
The |sgf| properties should be specified in the form
|
||||
:samp:`{PropIdent}={PropValue}`, eg ``RE=W+3.5``. Escape spaces in values
|
||||
with ``\_``, backslashes with ``\\``. Encode non-ASCII characters in UTF-8.
|
||||
|
||||
These |sgf| properties should be added to the root node. The engine should
|
||||
fill in any properties it can (at least ``AP``, ``SZ``, ``KM``, ``HA``, and
|
||||
``DT``). Explicitly-specified properties should override the engine's
|
||||
defaults.
|
||||
|
||||
The intention is that engines which have 'comments' about their moves (as
|
||||
for :gtp:`gomill-explain_last_move`) should include them in the game record.
|
||||
|
||||
Example::
|
||||
|
||||
gomill-savesgf xxx.sgf PB=testplayer PW=GNU\_Go:3.8 RE=W+3.5
|
||||
|
||||
.. note::
|
||||
|
||||
|gtp| engines aren't typically well placed to write game records, as they
|
||||
don't have enough information to write the game metadata properly (this is
|
||||
why :gtp:`!gomill-savesgf` has to take the |sgf| properties explicitly).
|
||||
It's usually better for the controller to do it. See the
|
||||
:script:`kgs_proxy.py` example script for an example of when this command
|
||||
might be useful.
|
||||
|
||||
|
||||
The :gtp:`gomill-explain_last_move`, :gtp:`gomill-genmove_ex`, and
|
||||
:gtp:`gomill-savesgf` commands are supported by the Gomill :mod:`!gtp_states`
|
||||
module.
|
||||
|
||||
.. The other extension is gomill-passthrough (used by proxies), but I don't
|
||||
think it makes sense to document it as a generic extension
|
||||
|
Loading…
Add table
Add a link
Reference in a new issue