UniversalHiveProtocol

Draft Proposal

Introduction

Definitions

Pieces

Positioning

Engine Structure

String Definitions

GameString

A GameString describes the complete state of the game. It is composed of various other strings joined by semi-colons. It should start as follows:

GameTypeString;BoardStateString;TurnString

After that there should be a semi-colon followed by a semi-colon separated list of MoveStrings for every move that has occurred so far in the game.

GameTypeString;BoardStateString;TurnString;MoveString1;MoveString2;MoveStringN

Note that there should be no trailing semi-colon at the end of the GameString.

Examples:

Base;NotStarted;White[1]
Base;InProgress;Black[1];wS1
Base;InProgress;White[2];wS1;bS1 wS1-

GameTypeString

A GameTypeString identifies the expansion pieces (if any) available in the current game. All GameTypeStrings start with Base, and if there are any expansion pieces, a single + and any combination of: M for Mosquito, L for Ladybug, P for Pillbug.

Examples:

Base
Base+M
Base+L
Base+P
Base+ML
Base+MP
Base+LP
Base+MLP

BoardStateString

A BoardStateString represents whether the game is in progress or not, and can be any of the following values:

BoardStateString	Description
NotStarted	The game has not started, no moves have been made.
InProgress	The game is in progress, at least one move has been made.
Draw	The game is over, the result is a draw.
WhiteWins	The game is over, the white side has won.
BlackWins	The game is over, the black side has won.

TurnString

A TurnString represents which side's turn it is, as well as the turn number. The string starts with the color of the current side's turn, White or Black. After that is the turn number inside of square brackets [ and ].

Examples in order of moves:

White[1]
Black[1]
White[2]
Black[2]

Note that the turn number starts at 1, and that each side gets to play a move before the turn number increments.

MoveString

A MoveString represents a piece to be moved and the destination position on the board where the piece should be moved to. UHP uses the (de-facto) standard move notation developed by BoardSpace. The notation assumes you're looking down at the board and that the top of the pieces are pointed (not flat).

The string starts with the piece to move's short name, followed by a space, followed by a position relative to another piece on the board. This relative position is given by listing the other piece (near the destination), and (usually) prepending or appending one of three relative direction indicators: - / .

MoveString	Description
bS1 wS1/	Place the first black spider on the top right edge first white spider.
bS1 wS1-	Place the first black spider on the right-hand edge of the first white spider.
bS1 wS1\	Place the first black spider on the bottom right edge of the first white spider.
bS1 /wS1	Place the first black spider on the bottom left edge of the first white spider.
bS1 -wS1	Place the first black spider on the left-hand edge of the first white spider.
bS1 \wS1	Place the first black spider on the top left edge of the first white spider.

For the first move of the game, simply state the piece being played.

MoveString	Description
wS1	White started the game by placing the first white spider.

For moving pieces on top of the hive (as the beetle, or the mosquito adopting the Beetle's movement), simply state the target piece that is about to be covered.

MoveString	Description
wB1 wS1	Move the first white beetle on top of the first white spider.

A passing move (made because a side has no other moves) is simply pass. (Some users of this notation do not indicate when passes have occurred, but this protocol requires it).

MoveString	Description
pass	The player had no valid moves and passed their turn.

Note, because the positioning notation is relative in nature, it is possible that two different MoveStrings can describe the same actual move.

Commands

All commands should output ok after completing to signal that completion back to the viewer.

info

info

The info command asks the engine to return its identifier string, optionally followed by a list of capabilities that the engine supports. All engines are required to output the result of the info command automatically after starting, so that the viewer can immediately know: what engine is running, what capabilities it supports, and that the engine is ready for commands.

The identifier string is given with id followed by the name of the engine. For an engine with no capabilities to declare, it might look like this:

info
id Mzinga.Engine v1.0.0.0
ok

If the engine does have capabilities to declare, they should be returned as a one-line semi-colon separated list after the identifier string. Here is the current list of recognized capability flags:

Flag	Description
Mosquito	The engine supports games with the mosquito expansion piece.
Ladybug	The engine supports games with the ladybug expansion piece.
Pillbug	The engine supports games with the pillbug expansion piece.

Example:

info
id Mzinga.Engine v1.0.0.0
Mosquito;Ladybug;Pillbug
ok

newgame

newgame [GameTypeString]

The newgame command asks the engine to start a new game should return a GameString. The GameTypeString parameter is optional, and if it's omitted, the engine should default to a base game with no expansion pieces.

Example without GameTypeString:

newgame
Base;NotStarted;White[1]
ok

Example with GameTypeString:

newgame Base+MLP
Base+MLP;NotStarted;White[1]
ok

play

play MoveString

The play command asks to engine to play the specified MoveString and should return the updated GameString if successful.

Example:

newgame
Base;NotStarted;White[1]
ok
play wS1
Base;InProgress;Black[1];wS1
ok

pass

pass

The pass command asks the engine to play a pass move and should return the updated GameString if successful. It is the equivalent of play pass.

validmoves

validmoves

The validmoves command asks the engine for every valid move for the current board, returned as a semi-colon separated list of MoveStrings.

Example:

newgame
Base;NotStarted;White[1]
ok
validmoves
wS1;wB1;wG1;wA1
ok

bestmove

bestmove time MaxTime
bestmove depth MaxDepth

The bestmove command asks the engine's AI for the best move on the current board with the specified depth or time limit, and returns the MoveString for that move. The engine may optionally return moves incrementally as it thinks, as long as each MoveString is presented on its own line.

When using bestmove time, MaxTime is the engine's time limit to think, and it should be in the format hh:mm:ss.

Example with a 5 second time limit:

newgame
Base;NotStarted;White[1]
ok
bestmove time 00:00:05
wS1
ok

When using bestmove depth, MaxDepth is the number of plies (moves or turns) to look ahead, and should be a non-negative integer value.

Example with a two ply limit:

newgame
Base;NotStarted;White[1]
ok
bestmove depth 2
wS1
ok

undo

undo [MovesToUndo]

The undo command asks the engine to undo one or more previous moves and should return the updated GameString if successful.

Example without MovesToUndo:

newgame
Base;NotStarted;White[1]
ok
play wS1
Base;InProgress;Black[1];wS1
ok
undo
Base;NotStarted;White[1]
ok

Example with MovesToUndo:

newgame
Base;NotStarted;White[1]
ok
play wS1
Base;InProgress;Black[1];wS1
ok
undo 1
Base;NotStarted;White[1]
ok

Errors

Occasionally a user may input bad command into the engine, and the engine may which to message the user that an error has occurred. The engine should respond with err followed by a description of the error, and as with any command, return an ok.

Example:

hi
err Invalid command. Try 'help' to see a list of valid commands.
ok

In the special case that the user is trying to play an illegal move, the engine may use invalidmove instead of err.

Example:

newgame Base
Base;NotStarted;White[1]
ok
validmoves
wS1;wB1;wG1;wA1
ok
play wQ
invalidmove You can't play your Queen Bee on your first turn.
ok