docs/engines.json.5

   1 .Dd April 10, 2012
   2 .Dt ENGINES.JSON 5
   3 .Os
   4 .Sh NAME
   5 .Nm engines.json
   6 .Nd Cute Chess engine configuration file
   7 .Sh DESCRIPTION
   8 .Nm
   9 is the chess engine configuration file for
  10 .Xr cutechess-cli 6 .
  11 An engine configuration defines name, command, working directory and
  12 many other options.
  13 These options can be then used in
  14 .Xr cutechess-cli 6
  15 with the
  16 .Cm conf
  17 command-line option.
  18 .Pp
  19 Engine configurations are defined in JavaScript Object Notation (JSON) format.
  20 See
  21 .Sx JSON FORMAT .
  22 .Sh JSON FORMAT
  23 .Ss Values
  24 A JSON value must be one of:
  25 .Ar object ,
  26 .Ar array ,
  27 .Ar number ,
  28 .Ar string ,
  29 .Cm false ,
  30 .Cm true
  31 or
  32 .Cm null .
  33 .Ss Objects
  34 A
  35 .Ar object
  36 is structure of name-value pairs enclosed in curly brackets.
  37 A name is a
  38 .Ar string .
  39 Name and value are separated by a single colon.
  40 Pairs are separated by commas.
  41 .Pp
  42 Example objects would be:
  43 .Bd -literal -offset indent
  44 { "Finland" : ".fi", "Sweden" : ".se" }
  45
  46 {
  47   "firstName" : "JC",
  48   "lastName"  : "Denton",
  49   "age"       : 28,
  50   "languages" : [ "English", "French", "Spanish" ]
  51 }
  52 .Ed
  53 .Ss Arrays
  54 An
  55 .Ar array
  56 is a structure of zero or more values enclosed in square brackets.
  57 Values are separated by commas.
  58 .Pp
  59 Example arrays would be:
  60 .Bd -literal -offset indent
  61 [ "Cute", "Chess" ]
  62
  63 [
  64   [ 1, 0, 0 ],
  65   [ 0, 1, 0 ],
  66   [ 0, 0, 1 ]
  67 ]
  68 .Ed
  69 .Ss Numbers
  70 A
  71 .Ar number
  72 consists of an integer part and optional fractional and/or exponent part.
  73 The integer part can be prefixed with a minus sign.
  74 Fractional part is a decimal point followed by one or more digits.
  75 Exponent part begins with a letter E in upper or lowercase which may be
  76 followed by a plus or minus sign.
  77 The E and optional sign are followed by one or more digits.
  78 .Pp
  79 Octal and hex forms are not allowed.
  80 .Pp
  81 Example numbers would be:
  82 .Bd -literal -offset indent
  83 128
  84 -1.04
  85 2e32
  86 -18E-20
  87 .Ed
  88 .Ss Strings
  89 A
  90 .Ar string
  91 is sequence of characters enclosed in quotation marks.
  92 All Unicode characters may be placed within the quotation marks except
  93 for the characters that must be escaped: quotation mark, backslash, and
  94 control characters.
  95 .Pp
  96 Available two-character escape sequences are as follows:
  97 .Pp
  98 .Bl -tag -width Ds -offset indent -compact
  99 .It Cm \e\e
 100 Backslash character.
 101 .It Cm \e/
 102 Forward slash character.
 103 .It Cm \e\(dq
 104 Quotation mark.
 105 .It Cm \eb
 106 Bell character.
 107 .It Cm \ef
 108 Form feed character.
 109 .It Cm \en
 110 Line feed character.
 111 .It Cm \et
 112 Vertical tab character.
 113 .It Cm \eu Ns Ar num
 114 Unicode character where
 115 .Ar num
 116 is a four hexadecimal digits that encode the character's code point.
 117 .El
 118 .Pp
 119 Example strings would be:
 120 .Bd -literal -offset indent
 121 "Hello, world!"
 122
 123 "Please place all items \e"carefully\e" in bins."
 124
 125 "\eu03a6 is one of the letters of Greek alphabet."
 126 .Ed
 127 .Sh ENGINE CONFIGURATION
 128 The configuration file consist of an
 129 .Ar array
 130 of
 131 .Ar objects .
 132 Each object defines a single engine configuration.
 133 Required options for each engine configuration are:
 134 .Bl -tag -width Ds
 135 .It Ic name No : Ar string
 136 The name of the engine.
 137 .It Ic command No : Ar string
 138 The engine command.
 139 .It Ic protocol No : \(dquci\(dq | \(dqxboard\(dq
 140 The chess engine protocol used by this engine.
 141 .El
 142 .Pp
 143 Other available options for an engine configuration are:
 144 .Bl -tag -width Ds
 145 .It Ic workingDirectory No : Ar string
 146 The working directory of the engine.
 147 .It Ic initStrings No : Ar array No of Ar string
 148 Array of strings sent to the engine's standard input at startup.
 149 .It Ic whitepov No : Cm true | Cm false
 150 When
 151 .Cm true
 152 invert the engine's scores when it plays black.
 153 The default is
 154 .Cm false .
 155 .Pp
 156 This option should be used with engines that always report scores from
 157 white's perspective.
 158 .El
 159 .Sh EXAMPLES
 160 A minimal engine configuration file for the Sloppy chess engine:
 161 .Bd -literal -offset indent
 162 [
 163   {
 164     "name": "Sloppy",
 165     "command": "sloppy",
 166     "protocol": "xboard"
 167   }
 168 ]
 169 .Ed
 170 .Pp
 171 Using the above engine configuration file with the
 172 .Cm conf
 173 command-line option:
 174 .Pp
 175 .Dl $ cutechess-cli \-engine conf=Sloppy -engine conf=Sloppy -each tc=40/60 -rounds 10
 176 .Sh SEE ALSO
 177 .Xr cutechess-cli 6
 178 .Rs
 179 .%R RFC 4627
 180 .%T "The application/json Media Type for JavaScript Object Notation (JSON)"
 181 .%D July 2006
 182 .Re