docs/engines.json.5

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