Game Data

Status: Work In Progress

Goals

Concise, readable, discrete

Simple Data Types

GameType values are strings, e.g. "Chaos".

UnitType values are strings, e.g. "Knight", "DarkMagicWitch", "LightningWard".

ActionType values are strings, e.g. "move", "attack", "turn", "breakFocus", "endTurn".

TeamID values are index numbers for teams within the teams list.

UnitID values are serial numbers assigned to units in the first turn and do not change from one turn to the next.

Direction values are a single character, e.g. "N", "S", "E", "W".

TileRef values are tuple X/Y coordinates, e.g. [5, 5] is the center of the board.

DateTime values are strings in simplified extended ISO format (ISO 8601).

Complex Data Types

GameData

Notes:

• If a game type is set, then additional constraints may be placed on teams.
• teams order dictates turn order.
• A game starts and started is assigned once all teams are not null.
• Once a game starts, an initial entry is added to the turns list.
• If winnerId is null and ended is set, then the game ended in a draw.

{
  "type": GameType,                // optional
  "teams": [                       // Entries: 2-5
    TeamData | null
  ],
  "turns": [                       // Entries: 0+
    {
      "units": [                      // Entries: teams.length
        [ UnitData, ... ],
        ...
      ],
      "actions": [
        {
          "type": ActionType,
          "unit": UnitID,                  // used by: type=move,attack,turn
          "assignment": TileRef,           // used by: type=move
          "target": TileRef,               // used by: type=attack
          "direction": Direction,          // used by: type=move,attack,turn
          "colorId": ColorName,            // used by: type=phase (Chaos Seed/Dragon)
          "results": [ ActionResult, ... ]  // used by: type=attack,breakFocus,endTurn
        }
      ]
    }
  ],

  "created": DateTime,
  "started": DateTime,
  "ended": DateTime,

  "winnerId": TeamID | null
}

TeamData

Notes:

• playerId is not directly used in game-play, but is intended to reference an authenticated player.
• Normally, the set.assignment tiles must be north of board center.
• Team colors are dictated by the client, not the server.
• The default team name can be the name of the color assigned to the team by the client.

{
  "playerId": Number | String,     // optional
  "name": String,                  // optional
  "bot": Boolean,                  // optional; default: false
  "set": [                         // Entries: 1+
    {
      "type": UnitType,
      "assignment": TileRef,
    }
  ]
}

UnitData

Unit data describes a living unit at a given point-in-time during a game. At the minimum, unit data includes the unit's ID, type, and assignment. All other properties of a unit are assumed to have their default values unless explicitly changed here.

{
  "id": Number,
  "type": UnitType,
  "assignment": TileRef,
  ...
}

ActionResult

Each result of an action describes the effect of the action on a specific unit.

Notes:

• The result(s) of an action are played for the viewer one-at-a-time. For example, when a Cleric takes a heal action, the result of healing each unit is played for the viewer one-at-a-time.
• If an action result has sub results, they are played at the same time. For example, when an Enchantress breaks focus, the result is the Enchantress no longer being focused, but paralysis is also lifted from all affected units at the same time as (sub) results.
• The changes describe one or more changes to the unit using unit object property name and value pairs.

{
  "unit": UnitID,
  "changes": ChangeMap,
  "results": [ ActionResult, ... ]  // optional; Forbidden for sub results.
}