> ## Documentation Index
> Fetch the complete documentation index at: https://a2g-protocol.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Game Specification Format

> Machine-readable game specifications that clients learn at runtime.

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

```yaml theme={null}
---
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:

1. **Formally valid** — Valid according to the JSON Schema specification
2. **Machine-parseable** — Clients MUST be able to parse and validate against them without ambiguity
3. **Complete** — Include all fields present in actual messages, with types and constraints
4. **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:

```typescript theme={null}
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.