Sashité for Developers
  1. Sashité for Developers
  2. Specifications
  3. GGN
  4. 1.0.0

General Gameplay Notation (GGN) Specification

1. Status of this document

The key words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are to be interpreted as normative requirements.

Capitalized terms (Board, Square, Hand, Location, Piece, Piece Name, Piece State, Piece Style, Active Player, Turn, Move, Protocol-Valid Move, Pseudo-Legal Move, Legal Move, Game Protocol, Rule System) are defined in the Glossary. This document does not redefine those terms.

2. Overview

General Gameplay Notation (GGN) is a rule-agnostic, JSON-based format for describing Mechanically Possible Moves (also called Pseudo-Legal Moves) in abstract strategy board games. GGN encodes the nominal movement capabilities of Pieces based on their Piece Name, Piece State, and Piece Style attributes, along with environmental pre-conditions required for those movements.

As defined in the Glossary, the Move hierarchy progresses from Protocol-Valid Moves (respecting fundamental invariants) to Pseudo-Legal Moves (adding Piece capabilities) to Legal Moves (adding Rule System-specific constraints). GGN operates at the Pseudo-Legal Move level, encoding what Pieces can do geometrically without incorporating Game-specific rules like check constraints, historical conditions, or win/loss implications.

3. Dependencies

GGN builds upon four foundational Sashité specifications:

Specification Purpose
CELL Multi-dimensional coordinate encoding for Board positions
HAND Reserve Location notation using * for off-board areas
QPI Qualified Piece Identifier for unambiguous Piece identification
LCN Location Condition Notation for environmental constraints

4. Scope

4.1 What GGN defines

GGN defines:

4.2 What GGN does not define

GGN is deliberately limited to Pseudo-Legal Moves. It does not define:

These concerns transform Pseudo-Legal Moves into Legal Moves and belong to Rule Systems, not to GGN.

5. Format specification

5.1 JSON structure

A GGN document is a JSON object with three-level nesting:

{
  "<piece>": {
    "<source>": {
      "<destination>": [
        {
          "must": { /* LCN conditions */ },
          "deny": { /* LCN conditions */ }
        }
      ]
    }
  }
}

5.2 Component definitions

Component Type Format Description
piece string QPI Piece identifier including Piece Name, Piece State, Piece Style
source string CELL/HAND Origin Location (Square or Hand)
destination string CELL/HAND Target Location (Square or Hand)
must object LCN Environmental conditions that MUST be satisfied
deny object LCN Environmental conditions that MUST NOT be satisfied

5.3 Field requirements

Required fields

Optional fields

When both must and deny are omitted or empty, the movement capability has no environmental pre-conditions.

6. Movement capability model

6.1 Core question

Each GGN entry answers: Can this Piece, with its current Piece Name, Piece State, and Piece Style, reach this destination from this source, given these environmental conditions?

6.2 Three-level addressing

GGN uses a three-level addressing structure:

  1. Piece level: Which Piece (identified by QPI)
  2. Source level: From which Location
  3. Destination level: To which Location

This structure naturally groups movement capabilities by Piece and source Location, enabling efficient queries for specific movement contexts.

6.3 Movement possibilities array

The destination value is an array of movement possibility objects. This array represents distinct ways the Piece can reach the destination:

"e4": [
  { "must": { "e4": "empty" } },
  { "must": { "e4": "enemy" } }
]

Each object in the array represents an independent movement possibility with its own environmental pre-conditions. The Active Player can execute the Move if any possibility’s conditions are satisfied.

6.4 Empty possibilities array

An empty array indicates the Piece has no mechanically possible way to reach that destination from that source:

"e4": []

This explicitly documents the absence of movement capability, distinct from omitting the destination entirely.

7. Environmental pre-conditions

7.1 LCN integration

Environmental pre-conditions use Location Condition Notation (LCN) within the must and deny fields. LCN provides a standardized format for expressing Location state constraints.

7.2 Evaluation context

As specified in the LCN specification, the "enemy" keyword is evaluated from the Active Player’s perspective. This aligns with the Glossary’s definition of Active Player as the Player whose Turn it currently is.

7.3 Condition logic

Must conditions (conjunction)

All conditions in the must object MUST be satisfied simultaneously (AND logic):

{
  "must": {
    "e2": "empty",
    "e3": "empty",
    "e4": "empty"
  }
}

This requires e2, e3, and e4 to all be empty.

Deny conditions (disjunction)

Movement is prevented if any condition in the deny object is satisfied (OR logic):

{
  "deny": {
    "e4": "C:K",
    "e4": "C:Q"
  }
}

This prevents movement if e4 contains either a king or queen.

Combined conditions

When both must and deny are present, all must conditions MUST be satisfied and none of the deny conditions MAY be satisfied:

{
  "must": { "e4": "enemy" },
  "deny": { "e4": "c:k" }
}

This requires an enemy Piece at e4, but not specifically the black king.

7.4 Source Location exclusion

The source Location MUST NOT appear in environmental pre-conditions. The source Piece’s presence at its starting Location is implicit in the movement context and SHOULD NOT be redundantly specified.

7.5 Pre-condition scope

Environmental pre-conditions MAY reference:

Pre-conditions describe the required state of the Game environment for the movement capability to be mechanically possible.

8. Authorized movement types

GGN encodes three types of movements, corresponding to the protocol’s authorized Displacement types:

Source Destination Movement Type Example
CELL CELL Board-to-Board movement Rook sliding
CELL HAND (*) Board-to-Hand (Capture) Capturing Piece
HAND (*) CELL Hand-to-Board (Placement) Dropping Piece

Invalid: Entries where both source = "*" and destination = "*" are prohibited (Hand-to-Hand movements are not authorized by the protocol).

9. Validation rules

9.1 Structural validation

A GGN document MUST satisfy:

  1. JSON validity — The document MUST be well-formed JSON.
  2. QPI compliance — Piece identifiers MUST conform to QPI specification.
  3. Location format — Source and destination MUST be valid CELL coordinates or HAND notation.
  4. LCN compliance — Condition objects MUST conform to LCN specification.
  5. Array requirement — Destination values MUST be arrays (even if empty).

9.2 Constraint validation

A GGN document MUST satisfy:

  1. Hand-to-Hand prohibition — Entries with source * and destination * are invalid.
  2. Source exclusion — Source Location MUST NOT appear in pre-conditions.
  3. Location validity — All Locations referenced in conditions MUST be valid.

9.3 Semantic validation

A GGN document SHOULD satisfy:

  1. Non-contradiction — Conditions for the same Location SHOULD NOT contradict between must and deny.
  2. Possibility distinction — Movement possibilities in the same array SHOULD be meaningfully distinct.
  3. Condition satisfiability — Conditions SHOULD be theoretically satisfiable (implementers MAY warn about impossible conditions).

10. Design principles

10.1 What GGN encodes

GGN describes movement capabilities — what Pieces can do based on their intrinsic attributes:

10.2 What GGN does not encode

GGN deliberately excludes Game-specific concerns:

These concerns transform Pseudo-Legal Moves into Legal Moves and belong to Rule Systems, not GGN.

10.3 Rule System integration

Rule Systems can use GGN as a foundation by:

  1. Querying GGN for mechanically possible movements
  2. Filtering based on Game-specific rules
  3. Presenting Legal Moves to Players

This separation allows GGN to remain rule-agnostic while supporting diverse Rule Systems.

11. Common patterns

11.1 Basic movement

{
  "C:R": {
    "a1": {
      "a4": [
        {
          "must": { "a2": "empty", "a3": "empty", "a4": "empty" }
        }
      ]
    }
  }
}

Rook can move to a4 if path and destination are clear.

11.2 Movement or Capture

{
  "C:R": {
    "a1": {
      "a4": [
        {
          "must": { "a2": "empty", "a3": "empty", "a4": "empty" }
        },
        {
          "must": { "a2": "empty", "a3": "empty", "a4": "enemy" }
        }
      ]
    }
  }
}

Two distinct possibilities: move to empty Square or Capture enemy Piece.

11.3 State-dependent movement

{
  "C:+K": {
    "e1": {
      "g1": [
        {
          "must": { "f1": "empty", "g1": "empty", "h1": "C:+R" }
        }
      ]
    }
  }
}

Enhanced king (with castling capability) can castle if conditions are met.

11.4 Placement from Hand

{
  "S:P": {
    "*": {
      "e5": [
        {
          "must": { "e5": "empty" }
        }
      ]
    }
  }
}

Pawn can be placed from Hand to e5 if empty.

11.5 Complex environmental constraints

{
  "x:c": {
    "b2": {
      "b8": [
        {
          "must": {
            "b3": "empty",
            "b4": "empty",
            "b5": "empty",
            "b6": "empty",
            "b8": "enemy"
          },
          "deny": { "b7": "empty" }
        }
      ]
    }
  }
}

Xiangqi cannon requires exactly one platform Piece to Capture (path clear except for one non-empty Square).

12. Usage patterns

12.1 Movement capability queries

GGN supports natural queries about Piece movement capabilities:

Query: “From e2, where can this pawn move?” Response: All destination entries under C:P → e2

Query: “Can this knight reach f6 from e4?” Response: Check if f6 exists under C:N → e4

Query: “What environmental conditions allow this rook to Capture at a8?” Response: Examine possibilities under C:R → a1 → a8 where must includes "a8": "enemy"

12.2 Cross-Style Games

GGN naturally supports Games where Pieces follow different Style traditions:

{
  "C:Q": { /* Chess queen movements */ },
  "x:m": { /* Xiangqi horse movements */ }
}

Different Styles can coexist in the same GGN document, each with their distinct movement patterns.

13. Implementation considerations

13.1 Performance

GGN documents can grow large for Games with many Piece types and movement patterns. Implementers SHOULD consider:

13.2 Completeness

GGN documents SHOULD enumerate all mechanically possible movements for each Piece from each source. Incomplete GGN documents MAY lead to missing Move possibilities.

13.3 Validation

Implementers SHOULD validate GGN documents at load time to detect:

13.4 Integration

When integrating GGN with Rule Systems:

  1. Use GGN as the foundation for movement capabilities
  2. Layer Game-specific constraints on top
  3. Document clearly which constraints come from GGN vs. rules
  4. Ensure Active Player context is properly provided for "enemy" evaluation

14. Relationship to other specifications

14.1 CELL

GGN uses CELL for Board coordinate representation, inheriting its multi-dimensional support and systematic character encoding.

14.2 HAND

GGN uses HAND (*) to represent off-board reserve Locations, enabling notation for Placement and Capture mechanics.

14.3 QPI

GGN uses QPI to identify Pieces with full attribute specification (Piece Name, Piece Side, Piece State, Piece Style), enabling precise movement capability encoding.

14.4 LCN

GGN uses LCN for environmental pre-conditions, providing a standardized format for Location state constraints.

14.5 Game Protocol

GGN operates within the Game Protocol framework at the Pseudo-Legal Move level, encoding Piece movement capabilities while remaining independent of Game-specific Rule Systems.

15. JSON Schema

A JSON Schema for GGN is published for programmatic validation:

The schema provides structural validation for GGN documents, ensuring proper JSON structure, valid component formats, and LCN conformance for conditions.

16. Examples

See GGN Examples for comprehensive practical implementation guidance, including:

17. Reference implementations

The following reference libraries are maintained by Sashité and are intended to be idiomatic, fully tested, and spec-accurate implementations of GGN v1.0.0.

They generally provide:

If a library behavior appears to conflict with this document, this specification is normative. Please report issues (or propose clarifications) on the relevant repository.

18. License

This specification is made available under the terms of the Open Web Foundation Agreement 1.0 (OWFa 1.0).

The authoritative legal text is the OWF “Final Specification Agreement (OWFa 1.0)”.