Remote Protocol
The remote protocol for external players in different processes or on a distributed network consist of five pieces: (0) the sign-up phase, (1) the start-up phase, (2) the beginning of a turn (step 1), (3) the request to players to choose actions with their cards (steps 2 and 3), and (4) the question to players to pick the next action during the feeding cycle. The last four correspond to the four steps of the API; the first one sets up the connections.
Each of these steps comes with a data format for the remote interactions. Besides these there is no communication between the external player and the dealer.
Changed in version 1.3: Mon Apr 18 16:01:30 EDT 2016
for 14 —Strategy Changed in version 1.2: Sat Apr 16 10:22:53 PDT 2016
in response to Klayton and Sean’s question about chooseChanged in version 1.1: Fri Apr 15 15:37:40 PDT 2016
in response to Kaylie and Lyn’s question about info and okAdded in version 1.0.
Sign Up
In a realistic setting, the server would spawn off one game and then start collecting players for the next one. It would also start managing loads and such.
+---------------+
+--------+ | remote site 1 |
| server | +---------------+
+--------+ |
| |
| TCP connect |
| <============ |
| |
| r1 = sign-up(info)
| <~~~~~~~~~~~- |
| |
| return(ok) |
| ============> |
| |
| p1 = new(r1) +--------------+
| ------------------> | proxy-player |
| +--------------+
| | |
... ... ... (A)
| | |
| | |
-------------------------------------------- start
| | |
| | |
| | sign-up | +---------------+
| <~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | remote site N |
| | | +---------------+
info ~ any JSON string the client wishes to send
ok ~ "ok"
The figure 6 diagram is provided as a suggestion on how to organize a client. It does not show anything related to the remote protocol other than the signUp message.
+-------------+
| remote-main |
+-------------+
|
| p = new() +--------+
| ------------------------------>| player |
| +--------+
| |
| new(p) +--------------+ |
| ---------> | proxy-dealer | |
| +--------------+ |
& | | (A)
signUp(info) | |
<~~~~~~~~~~~~~~~~~~~~~~~~ | |
| |
(A) You could terminate 'remote-main' here.
Start Up
Remains mostly the same; see figure 1. The server creates
a dealer and hands it the proxy players instead of the actual
players. Because these proxies live up to the same interface as proper
players, the dealer does not notice a difference—
Turn: Step 1
The dealer hands each external player the necessary pieces at the beginning of a turn: a species board (if needed) and additional cards to play the turn.
+--------+ +------+ +------+ +------+ +----------+
| dealer | | py 1 | | py 2 | | pd 1 | | player 1 |
+--------+ +------+ +------+ +------+ +----------+
| | | | |
| start(w) | | | |
|-----------> | start(v) | | |
| |~~~~~~~~~~~~~~~~~~~> |start(w) |
| | | |----------> |
| | | | |
| | | | |
| start(w) | | | |
|----------------------> |start(v) | |
| | |~~~~~~~~~~~~~~~~~~~~~~~~~> site2
| | | | |
| | | | |
py ~ proxy player
pd ~ proxy dealer
w ~ current state of self and the watering hole
v ~ w in JSON: [Natural,Natural,[Species+, ..., Species+], Cards]
Notice the additional first field in the array.
Turn: Steps 2 and 3
The dealer asks the players how they wish to use their cards. With this request the dealer reveals some knowledge about the other players, including the order in which they will take the turn.
+--------+ +------+ +------+ +------+ +----------+
| dealer | | py 1 | | py 2 | | pd 1 | | player 1 |
+--------+ +------+ +------+ +------+ +----------+
| | | | |
| choose(c,d) | | | |
|-----------> | choose(cj+dj) | |
| |~~~~~~~~~~~~~~~~~> | choose(c,d) |
| | | |-----------> |
| | | | |
| | | | return(r) |
| | return(rj) | <===========|
| return(r) | <~~~~~~~~~~~~~~~~ | |
| <========== | | | |
... ... ... ... ...
| | | | |
c ~ the state of all players that precede this one for the turn
turn minus their cards and food in bag
d ~ the state of all players that come after this one for the
turn minus their cards and food in bag
r ~ a representation of the following choices:
-- the food card required (step 2)
-- the card exchanges for (step 3):
-- growing the populations of species boards
-- growing the bodies of species boards
-- adding new species board (to the right)
-- replacing traits of existing species boards
rj ~ r in JSON : Action4
Turn: Step 4
The dealer executes the choices that the players made and then runs the feeding phase of the turn. For the latter, it will interact with the external players as needed.
+--------+ +------+ +------+ +------+ +----------+
| dealer | | py 1 | | py 2 | | pd 1 | | player 1 |
+--------+ +------+ +------+ +------+ +----------+
| | | | |
| | | | |
feeding() | | | |
+-- | | | | |
| | feedNext(ys)| | | |
| |-----------> | feedNext(zs) | |
| | | ~~~~~~~~~~~~~~~~>| feedNext(ys)|
| | | | |-----------> |
| | | | | |
| | | | | return(fc) |
| | | return(gc) | <===========|
| | return(fc) | <~~~~~~~~~~~~~~~~| |
| | <===========| | | |
| | | | | |
... ... ... ... ... ...
| | | | | |
+-> | | | | |
| | | | |
ys ~ the dealer's current knowledge of the watering hole and
the players in attackable order [all playes starting from
current, in turn order]
+ the player's current state (bag, cards, species)
fc ~ food choice (what to eat next)
zs ~ ys in JSON : State
gc ~ fc in JSON : FeedingChoice
JSON Specifications
To simplify your life, this section collects most JSON data descriptions needed (all except for some rather basic ones, which are linked to their original definitions). Each definition comes with a margin note that takes you back to the place where the same or a similar JSON data definition is introduced for testing.
12 —
Interpretation A State represents the player’s complete current state and the public state of the competitors. Specifically, [bg,bd,c,w,others] consists of the player’s current bag, the current species boards, the current cards, the number of available food tokens, and the species boards of all other players (in turn order).
6 —
A Boards is [Species+,...,Species+].
8 —
An Action4 is [Natural, [GP, ...], [GB, ...], [BT, ...], [RT, ...]].
11 —
An RT is [Natural, Natural, Natural].
A VegetarianChoice is a Natural.