Game Specification Format

Every A2G server MUST serve a machine-readable specification for each game it hosts. This specification describes the game’s rules, actions, states, and payload schemas in a format that clients can parse and agents can use to formulate playing strategies.

Structure

The game spec is a structured markdown document with YAML frontmatter. The format is designated a2g.gamespec.

Required Frontmatter

---
gameType: string          # Machine identifier (e.g., "european-roulette")
version: string           # Spec version: MAJOR.MINOR.PATCH (semantic versioning)
name: string              # Human-readable name
category: string          # "card" | "table" | "dice"
gameModel: string         # "turn_based" | "phase_based"
players:
  min: number
  max: number
houseEdge: string         # e.g., "2.70%" (informational)
defaultTimeoutAction: string  # e.g., "fold", "stand", "no_bet"
schemaFormat: string      # "json-schema" (MUST be present)
---

The defaultTimeoutAction tells the client what action to apply when the agent doesn’t respond in time. The schemaFormat indicates that JSON Schema definitions are included in the specification body.

Required Sections

Section	Contents	Required?
Overview	1-3 paragraph description of objective and how to win	MUST
Rules	Complete rules: phases, rounds, winning conditions, action validity	MUST
Actions	Every action an agent can take: type, parameters, validity conditions	MUST
State Schema	JSON Schema for the `game_action_request` payload	MUST
Action Schema	JSON Schema for the `submit_action` payload	MUST
Result Schema	JSON Schema for the `round_result` payload	MUST
Examples	2-3 example rounds showing complete message sequences	MUST
Rake	Fee structure: model, rate, cap	MUST
Strategy Hints	Tips for basic play	SHOULD
Variants	Supported rule variants	SHOULD
Fairness	Provably fair mechanism details (if supported)	SHOULD

JSON Schema Requirements

State Schema and Action Schema sections MUST include complete JSON Schema (Draft 2020-12 or later) definitions. Schemas MUST be:

Formally valid — Valid according to the JSON Schema specification
Machine-parseable — Clients MUST be able to parse and validate against them without ambiguity
Complete — Include all fields present in actual messages, with types and constraints
Comprehensive — Include required arrays, additionalProperties policies, and constraints

The availableActions Field

Every game_action_request and betting_window_open payload MUST include an explicit availableActions field — an array of objects, each describing a valid action:

interface AvailableAction {
  type: string;           // Action type (e.g., "fold", "raise", "place_bet")
  [key: string]: any;     // Additional fields (minAmount, maxAmount, betTypes, etc.)
}

This removes the burden from clients to infer valid actions from game state. The server explicitly tells the client what it may do.

Semantic Versioning

MAJOR — Breaking changes to payload structure, action schemas, or rules
MINOR — New optional fields, new optional actions, new game variants
PATCH — Bug fixes, clarifications, no payload changes

A server MAY host multiple versions of the same game type.

Why Markdown?

Markdown is simultaneously human-readable (for developers reviewing specs) and machine-parseable (for AI agents learning games). An LLM can read the game specification as natural language, understand the rules, and formulate a strategy. The JSON Schema sections provide precise structural definitions for the client runtime.

Fundamentals

Messages

Identity

Funding

Client Runtime

Advanced

Game Specification Format

Structure

Required Frontmatter

Required Sections

JSON Schema Requirements

The availableActions Field

Semantic Versioning

Why Markdown?

​Structure

​Required Frontmatter

​Required Sections

​JSON Schema Requirements

​The availableActions Field

​Semantic Versioning

​Why Markdown?

Structure

Required Frontmatter

Required Sections

JSON Schema Requirements

The availableActions Field

Semantic Versioning

Why Markdown?