info json: a proposal to extend UCI protocol

1. Why?

The new generation of chess engines such as Leela Chess Zero may have a lot of information to show developers and users. Unfortunately, all current popular chess GUIs cannot help much to receive as well as to show that info to users.

Basically info transmission between chess engines and GUIs is strictly standardized, fixed and limited by definitions in chess protocols such as Windboard and UCI. They all cannot go out of the box without hacking (e.g. Lc0 has to send extra info as normal strings).

To add more info for transmission, programmers of both engines and GUIs must sit down and discuss together. It is a long process and hard to get agreements since people usually have different opinions and requirements. The current state of using a simple text format makes harder since we cannot add too much data at once, cannot use abstract data either. If we are lucky and get an agreement of adding some new types of data, all have to wait for at least a chess GUI to support it. The process may take years. Then if an engine/programmer wants to add a new data type, he has to start the process again.

JSON data may be useful to solve the above problem. Itself is a data structure with some basic data types such as arrays, maps, strings, integers, booleans… It can be used to create some abstract data types. Engines’ programmers may have much freedom to transmit and show info in GUIs. They don’t need to ask and wait for GUI’s programmers to add new data types.

Limitations

As the first-word “info” of the proposal’s name, there are some limitations of using:

• One-way only, from engines to GUIs
• To transmit only information, not for controlling
• Mostly for displaying data in one of three forms: tables, arrows, and bubbles

2. How?

Before sending any JSON data, engines, GUIs and users must turn it on via a special option UCI_InfoJSON:

option name UCI_InfoJSON type check default false

If it is on, engines can start sending info in JSON format:

info json {}

3. What?

Chess engines can send data to chess GUIs to display visually them in 3 forms: tables, arrows, and bubbles.

a. Tables

A row of a table is an array. In JSON, data may be any JSON data standard types: integers, doubles, boolean or strings:

[ 245, 16.2, "Good data" ]

A table may be declared as simple as the following command:

info json { "table": { "row": [ 23, 1, 3.5 ] }}

There may be some tables. They are distinguished by their names (if there is one table only, its name could be omitted). For multi-tables cases, each time the engine should send data of one table only (to avoid JSON errors).

info json { “table”: { “name” : “WDL stats”, “row”: [ 23, 320, 35 ] }}

A table may have no or a header with names of columns. The bellow table has names for columns. Engines don’t need to send “header” all the time but only once at the beginning.

info json { "table": { "header": ["W", "D", "L"], "row": [23, 1, 45]}}

A table may have many rows. Rows are actually an array of rows (each row is an array too):

{ "table": { "header": ["N", "Q", "Q%", "notes"], "rows": [[ 452, 0.05, 35, "Not too bad"], [ 556, 0.045, 43, "Above the limit"]]}}

All the above tables will be replaced completely by the latest ones. To keep old data and update only one or a few rows, engines should show the column name as the key to update (updatedby). The GUI will search for old data and replace the corespondent data (if not found, new rows will be appended to the end of the table).

{ "table": { "updatedby" : "Q", "row": [ 556, 0.045, 43, "Above the baseline"]}}

Table keywords: table, name, header, row, rows, updatedby

b. Arrows

An arrow will be drawn between two cells in a coordinate format. There may be some arrows at once:

info json {"arrow":[ "a1d6", "a8c6"]}

Arrow keywords: arrow

c. Bubbles

A bubble is a plain color circle with some numbers and/or strings:

info json {"bubble":[ {"move" : "a1d6", "value": 345 }, {"cell" : "a5", "value": [345, 76.8] ]}}

Bubble keywords: bubble, move, cell, value

Notes:

All tables, arrows, bubbles will be cleared when the game starts thinking for a new move.

4. Q&A

Who?

The idea of using JSON to transmit data between engines and GUIs is from Crem in a topic forum (started by Gian-Carlo Pascutto). We have developed the idea into this proposal.

JSON libraries for engines?

No. It is a one-way transmission. Chess engines create and send JSON data to GUIs but not receive nor parse it. Create is always easy and doesn’t need any extra library. Just using some printing commands is more than enough.

Examples of use/benefits?

• When developing chess engines, programmers can display visually on GUIs any information they want.
• Tables themselves can show data in a good way to study, examine, columns can be sorted
• Arrows, bubbles are very useful for training

Supported GUIs?

It is totally a new idea/proposal, thus there is no chess GUIs support it yet. However, we are going to release our chess GUI – Banksia GUI which will definitely support it.

It is wrong to let engines decide data format and/or tell chess GUIs what to do

We believe it is not wrong since:

• Those are suggestions, not decisions. Any additional information will be good to help chess GUIs to parse and show data. In the end, users via GUIs have all rights and power to see/show data in the format they want
• Having more voices in the system engine-GUI is much better for all engines-GUIs and their developers
• Having more active-cooperation between engines and GUIs much be betters too

Bad idea, it may violate MVC programming paradigms…

It is true for old good days. However, nowadays there are many new techs, paradigms, such as data-driven programming.

A trial?

Yes, more or less, that is a trial, an additional function to chess GUIs! There is no agreement between developers on it yet. Developers/users may simply ignore if they don’t like it.

IMO, it is better to look out of the box and try new things. Following strictly old ways, old models is not our plan. Even crazy ideas may need to try too. Franky speaking, we get bored if all systems of engine-GUI are similar both inside and outside as ones of the 1990s.

The main target is to improve the user’s experience. They will be the ultimate voices to keep or to dump new functions.