The Manabrew Protocol

Manabrew separates the engine (the rules) from the client (the UI). Any engine that speaks this protocol can drive the a Manabrew client, and any client that implements it can host a Manabrew compatible engine.

What we hope to achieve by putting effort and love into the spec, is that more people and projects start adopting it. We see huge potential in a truly open-standard for online card gaming, and we dream of a day where UIs and Engines for all sorts of games will be able to be inter-changed for a superior community driven ecosystem.

- Witches of the Hill

The protocol ensures:

• A transport-agnostic JSON message format - a client written against this spec can talk to any conforming engine.
• Complete enough to drive interactive play: priority, targeting, combat, cost payment, library manipulation, dice, and the opening-hand procedure.

Enforcing the rules is up to the particular engine implementing the protocol.

Message families

The engine → client channel carries four separate kinds of message:

state

A StateUpdate carrying the full gameView - the only carrier of game state. The client re-renders the board from it.

display

[⚠️ Work in Progress] A DisplayEvent - a transient, potentially very frequent UI display information. Carries no authoritative state. This could be used to sync up the fields, as well as the cursors positions of the players for multiplayer “livelyness”.

prompt

An AgentPrompt - a call to action. The engine has paused and needs a decision from a specific player.

error

A ProtocolError - the engine rejected the last response. See Errors.

The client → engine channel carries two:

response

A PromptOutput answering the open prompt, echoing its promptId. Strictly paired: one response per prompt. See Answering a prompt.

directive

A DirectiveInput - out-of-band and fire-and-forget, never paired with a prompt. Currently only concede, legal at any time.

Prompts deliberately carry no gameView: the client already has the latest state from the most recent StateUpdate message.

The prompt envelope

Every prompt is wrapped in an AgentPrompt:

interface AgentPrompt {
  promptId: number; // correlate the response back to this prompt
  decidingPlayerId: string; // who must answer
  sourceCard?: CardDto; // the complete card that caused this prompt, if any
  input: PromptInput; // each prompt type defines the shape of its input
}

Answering a prompt

type ClientToServerMessage =
  | { kind: "response"; promptId: number; action: PromptOutput }
  | { kind: "directive"; directive: DirectiveInput }; // out-of-band; currently { type: "concede" }

It is important promptId is always the same as the last promptId emitted by the engine.

// engine → client
{ "promptId": 7, "decidingPlayerId": "player-0", "input": { "type": "chooseNumber", ... } }

// client → engine
{ "kind": "response", "promptId": 7,
  "action": { "type": "chooseNumber", "output": { "type": "numberDecision", "chosenNumber": 3 } } }

Errors

type ProtocolError = { code: ProtocolErrorCode; message: string; promptId?: number };

type ProtocolErrorCode =
  | "stalePrompt"
  | "wrongPlayer"
  | "wrongPromptType"
  | "unknownActionId"
  | "invalidShape";

The prompt catalogue

Careful about the type blocks

For language convenience, we show the type blocks in multiple languages. Be mindful that the correct protocol on the wire is camelCase. Follow the TypeScript type definitions for the exact protocol.

Every prompt the engine can send. Each links to its arguments, response shape, and a wire example.

Choices & information

• chooseNumber - pick a number in a range.
• chooseCards - select cards from a set.
• chooseColor - choose one or more colors.
• chooseBoolean - a yes/no decision.
• chooseFromSelection - pick spell modes.
• revealCards - acknowledge revealed cards.
• scry - sort cards into destination zones.
• reorder - put cards in a chosen order.
• diceRolled - acknowledge a dice roll.

Priority & costs

• chooseAction - take an action or pass priority.
• payManaCost - pay a mana cost interactively.

Mulligan

• mulligan - keep or mulligan the opening hand.
• mulliganPutBack - London-mulligan put-back.

Combat & targeting

• chooseAttackers - declare attackers.
• chooseBlockers - declare blockers.
• chooseDamageAssignmentOrder - order multiple blockers.
• chooseCombatDamageAssignment - assign combat damage.
• chooseBoardTargets - choose targets on the board.

End

• gameOver - the game has ended.

License

This protocol specification - every page under /protocol/ - is licensed Creative Commons Attribution 4.0 International (CC-BY-4.0), deliberately separate from the reference implementation, so that anyone may describe or implement the same wire format without depending on this repository.

The reference implementation (the rest of the project) is AGPL-3.0-or-later. Independent re-implementations of this protocol under any license are explicitly invited.