
                      ##################################
                     #                                  #
                     #   OKP: The OpenKropki Protocol   #
                     #                                  #
                      ##################################
                                 last update: 2020.09.10


OKP is a protocol designed as a simple way for "kropki" implementations to
exchange information. It defines two things: a way of describing the playfield
and a way to feed back move decisions (potentially allowing different AIs to
play against each other).


## The playfield description #################################################

A playfield is described through a printable string of characters. This string
is composed of "chunks", where each chunk starts with a 2-letter unique
identifier, followed by the chunk's body and terminated by a single '$'
character. The order of each chunk does not matter. The entire string ends
with a single <LF> character. Possible chunk identifiers are:

 fs = field size (in playable positions): provided as two numbers separated by
      a dot, width first then height. Example: fs100.60$ (for a 100x60 field)

 fc = field content: list of all fields, from top to bottom, left to right.
      each field is described by one character that is computed as follows:
   what dot occupies the space?
       a  = A player's dot
       b  = B player's dot
       c  = empty space
   who owns this space? (who captured it - if anyone at all)
       player A: +3 (eg. c -> f)
       player B: +6 (eg. a -> g)
   if it's a wall, subtract 32 (ie. "turn uppercase", eg. g -> G)

 lm = last move: the x.y position of the dot last placed on the field.

 me = indication who the peer plays as (player A or B).

 wl = wall: this chunk may appear many times and provides information about
      a wall element, ie. the coordinates of a wall that spans between two
      *adjacent* dots. It effectively conveys 4 numbers - x1, y1, x2, y2, each
      being separated by a dot. Example: wl21.17.22.18$


## Move decision feedback ####################################################

When presented with a playfield description, an AI may choose to provide his
move choice. To do so, it simply has to answer with an "mv" (move) answer,
followed by the two numbers that represent the coordinates of the move, where
"0.0" points to the top left corner. The numbers must be separated by a single
dot and the last number must be followed by a single <LF> character.


## Hello #####################################################################

Whenever a "server" (playfield provider) talks to a "client" (something that
is expected to send back move choices), it must start by sending a "he$"
command terminated by a single <LF>. The client must answer with an "ok$"
string, also terminated by a single <LF>. This ensures that both participants
speak the same language. The hello message acts at the same time as a reset,
meaning that it should be issued not only at the start of the communication,
but every time that a new game starts, so the client may flush any data it
has about the ongoing game.


## Example ###################################################################

A simple example of this protocol dialog between a server (S) and a client (C)
can be found below.

S: he$
C: ok$
S: fs5.4$fccccccccccccccccccccccc$mea$
C: mv3.0$
(...)
S: fs5.4$fcbAAbcAefAcaAAcbccbbc$lm3.1$mea$wl1.0.2.0$wl2.0.3.1$wl0.1.1.0$
   wl0.1.1.2$wl1.2.2.2$wl2.2.3.1$
C: mv1.3$


## Transport #################################################################

This document describes only the "application-level" protocol, as defined
above. It does not provide any recommendations about how to transport such
communication - this is left as an implementation choice. Might be a TCP
connection, a unix socket, a pair of system pipes, a library call or anything
else that allows for a reliable request/reply ASCII communication between two
entities.


####################################################################### EOF ##
