General Gameplay Notation (GGN) Specification

Version: 1.0.0
Author: Sashité
Published: March 8, 2014
License: MIT License

Overview

General Gameplay Notation (GGN) is a rule-agnostic, JSON-based format for describing pseudo-legal moves in abstract strategy board games. GGN expresses whether a move is possible under basic movement constraints, while remaining completely silent about higher-level, game-specific legality questions (e.g., check, ko, repetition, castling paths) and mechanical execution details.

GGN serves as a pure movement possibility oracle: given a piece, source location, and destination location, it determines if the movement is feasible under specified pre-conditions.

Terminology

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

Dependencies

GGN builds upon four foundational Sashité specifications:

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
STN: State Transition Notation for representing position changes

These specifications define the building blocks that GGN uses for movement possibility definitions.

Core Philosophy

Movement Possibility Model

A single GGN entry answers the fundamental question:

Can this piece, currently at this location, reach that location?

It encodes:

Which piece (via QPI format: style:piece)
From where (source location using CELL coordinates or HAND “*”)
To where (destination location using CELL coordinates or HAND “*”)
Which pre-conditions must hold (must)
Which pre-conditions must not hold (deny)
What changes occur if the move is executed (diff)

JSON Structure

{
  "<Piece>": {
    "<Source location>": {
      "<Destination location>": [
        {
          "must":  { "<location>": "<required state>", … },
          "deny":  { "<location>": "<forbidden state>", … },
          "diff":  { /* STN format */ }
        }
      ]
    }
  }
}

Core Fields

Field	Type	Required	Description
Piece	string	yes	Piece identifier in QPI format (`style:piece`)
Source location	string	yes	Origin location (CELL coordinate or HAND “*”)
Destination location	string	yes	Target location (CELL coordinate or HAND “*”)
must	object	yes	Pre-conditions that must be satisfied
deny	object	yes	Pre-conditions that must not be satisfied
diff	object	yes	State transition in STN format

Location Constraints

Source location: CELL coordinate or “*” (piece from hand/reserve)
Destination location: CELL coordinate or “*” (piece to hand/reserve)
Restriction: Source and destination cannot be identical

HAND Integration: The "*" notation follows the HAND specification for representing reserve/off-board locations, enabling representation of piece placement and capture mechanics.

Piece Identification

Format: Must conform to QPI specification (<style>:<piece>)
Examples: "C:K", "c:p", "S:+P", "x:c"
Consistency: Must be consistent within a single GGN document

Pre-Conditions and State Changes System

Logical Semantics

must: All conditions must be satisfied (logical AND)
deny: Move forbidden if any condition is satisfied (logical OR)
diff: State transition that occurs when the move is executed (STN format)
Consistency: Same state cannot appear in both must and deny for the same location

State Transition Integration

The diff field uses State Transition Notation (STN) format to describe the complete state change that results from executing the move. This enables GGN to specify not only the conditions for move validity but also the mechanical outcome of the move execution.

Location States

State	Meaning
`"empty"`	Location must be empty
`"enemy"`	Location must contain an opposing piece
Piece	Location must contain exactly the specified piece

Implicit States (via `deny`)

Expression	Implicit Meaning
`"deny": { "a1": "empty" }`	Location must be occupied (by any piece)
`"deny": { "a1": "enemy" }`	Location must contain a friendly piece

Constraint Examples

Desired Condition	GGN Expression
Location must be empty	`"must": { "a1": "empty" }`
Location must contain enemy	`"must": { "a1": "enemy" }`
Location must contain ally	`"deny": { "a1": "enemy" }`
Location must be occupied	`"deny": { "a1": "empty" }`
Location must contain specific piece	`"must": { "a1": "CHESS:K" }`
Location must not contain specific piece	`"deny": { "a1": "CHESS:K" }`

JSON Schema

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

The JSON Schema provides structural validation for GGN format compliance, ensuring proper movement possibility structure with valid pre-conditions.

Examples

See GGN Examples for practical implementation guidance.

Reference Implementations

Ruby

GGN.rb – Ruby implementation providing parsing and validation capabilities for GGN documents. Enables pure movement possibility queries with FEEN integration and PMN coordination.