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

General Gameplay Notation (GGN) Specification

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 Name, State, and Style attributes, along with environmental pre-conditions required for those movements.

As defined in the Sashité Protocol, the move hierarchy progresses from Protocol-Valid Moves (respecting fundamental invariants) to Mechanically Possible Moves (adding piece capabilities) to Legal Moves (adding rule-specific constraints). GGN operates at the Mechanically Possible Move level, encoding what pieces can do geometrically without incorporating game-specific rules like check constraints, historical conditions, or win/loss implications.

Terminology

For complete definitions of terms used in this document, see the Glossary.

Key concepts:

Dependencies

GGN builds upon four foundational Sashité specifications:

Format Specification

JSON Structure

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

Component Definitions

Component Type Format Description
piece string QPI Piece identifier including Name, State, 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

Field Requirements

Required Fields

Optional Fields

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

Movement Capability Model

Core Question

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

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.

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.

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.

Environmental Pre-Conditions

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.

Evaluation Context

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

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.

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.

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.

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).

Validation Rules

Structural Validation

  1. JSON validity: 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)

Constraint Validation

  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

Semantic Validation

  1. Non-contradiction: Conditions for the same Location must 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)

Design Principles

What GGN Encodes

GGN describes movement capabilities - what pieces can do based on their intrinsic attributes:

What GGN Does Not Encode

GGN deliberately excludes game-specific concerns:

These concerns transform Mechanically Possible Moves into Legal Moves and belong to rule systems, not GGN.

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.

Common Patterns

Basic Movement

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

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

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.

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.

Placement from Hand

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

Pawn can be placed from Hand to e5 if empty.

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).

Usage Patterns

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"

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.

JSON Schema

Schema URL: https://sashite.dev/schemas/ggn/1.0.0/schema.json

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

Examples

See GGN Examples for comprehensive practical implementation guidance, including:

Implementation Considerations

Performance

GGN documents can grow large for games with many piece types and movement patterns. Implementers should consider:

Completeness

GGN documents should enumerate all mechanically possible movements for each piece from each source. Incomplete GGN documents may lead to missing move possibilities.

Validation

Implementers should validate GGN documents at load time to detect:

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

Relationship to Other Specifications

CELL

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

HAND

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

QPI

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

LCN

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

Game Protocol

GGN operates within the Sashité Protocol framework at the Mechanically Possible Move level, encoding piece movement capabilities while remaining independent of game-specific rule systems.

Summary

General Gameplay Notation provides a rule-agnostic foundation for describing Mechanically Possible Moves in abstract strategy board games. By encoding piece movement capabilities based on Name, State, and Style attributes, along with environmental pre-conditions, GGN enables:

GGN focuses exclusively on what pieces can do geometrically, leaving rule-specific constraints to individual game systems.

Reference Implementations

Ruby