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

Portable Chess Notation (PCN) Specification

Overview

Portable Chess Notation (PCN) is a comprehensive, JSON-based format for representing complete chess game records across variants. PCN leverages the Sashité ecosystem specifications, using CELL for multi-dimensional coordinates, HAND for reserve locations, GAN for piece identification, PMN for move representation, and FEEN for position representation, creating a unified and rule-agnostic game recording system.

PCN supports both traditional single-variant games and modern cross-variant scenarios where different players use different game systems.

Game Protocol Foundation

The fundamental game concepts used in this document are interpreted as described in the Game Protocol.

Dependencies

PCN builds upon five foundational Sashité specifications:

These specifications define the standardized formats that PCN uses for coordinate identification, reserve management, actor representation, move encoding, and position description.

Design Principles

JSON Structure

{
  "meta": {
    "name": "<string>",
    "event": "<string>",
    "location": "<string>",
    "round": "<integer>",
    "started_on": "<date>",
    "finished_at": "<datetime>",
    "href": "<url>"
  },
  "sides": {
    "north": {
      "name": "<string>",
      "elo": "<integer>"
    },
    "south": {
      "name": "<string>",
      "elo": "<integer>"
    }
  },
  "setup": "<feen_position>",
  "moves": [
    [<pmn_element>, <pmn_element>, <pmn_element>, ...],
    ...
  ],
  "state": {
    "status": "<status>",
    "winner": "<winner>"
  }
}

Field Specifications

Meta Section (Optional)

Standard game metadata following common conventions.

Field Type Description
name string Game or opening name
event string Tournament or event name
location string Venue or location
round integer Round number (≥ 1)
started_on date Game start date (ISO 8601)
finished_at datetime Game completion timestamp (ISO 8601)
href url Reference URL

Sides Section (Optional)

Player information for each side:

Field Type Description
north object North side player information
south object South side player information

Player Object Fields:

Field Type Description
name string Player name or identifier
elo integer Elo rating (≥ 0)

Note: The “north” and “south” terminology corresponds to the lowercase and uppercase style identifiers in FEEN, respectively. The north side uses lowercase styles (second in FEEN turn order), while the south side uses uppercase styles (first in FEEN turn order).

Setup Section (Required)

Initial game configuration using Forsyth-Edwards Enhanced Notation (FEEN):

Field Type Description
setup string Complete FEEN position string

This approach provides several advantages:

Important: All piece identifiers must use ASCII letters (a-z, A-Z) as required by the Piece Name Notation (PNN) specification.

Moves Section (Required)

Sequence of game moves using Portable Move Notation (PMN) format. Each move is a PMN array representing one player’s complete turn.

Move Array Structure: Each element in the moves array is a PMN sequence representing the complete mechanical decomposition of one player’s turn.

State Section (Required)

Current game state:

Field Type Description
status string Current game status
winner string or null Game winner when finished, null for draws

Game Status Values:

Winner Values:

Examples

Standard Chess Game

{
  "meta": {
    "name": "King's Gambit",
    "event": "Club Championship"
  },
  "sides": {
    "north": {"name": "Alice", "elo": 1650},
    "south": {"name": "Bob", "elo": 1720}
  },
  "setup": "+rnbq+kbn+r/pppppppp/8/8/8/8/PPPPPPPP/+RNBQ+KBN+R / CHESS/chess",
  "moves": [
    ["e2", "e4"],
    ["e7", "e5"],
    ["f2", "f4"],
    ["e5", "f4"]
  ],
  "state": {
    "status": "in_progress",
    "winner": null
  }
}

Completed Chess Game with Checkmate

{
  "sides": {
    "north": {"name": "Alice"},
    "south": {"name": "Bob"}
  },
  "setup": "+rnbq+kbn+r/pppppppp/8/8/8/8/PPPPPPPP/+RNBQ+KBN+R / CHESS/chess",
  "moves": [
    ["e2", "e4"],
    ["e7", "e5"],
    ["d1", "h5"],
    ["b8", "c6"],
    ["f1", "c4"],
    ["g8", "f6"],
    ["h5", "f7"]
  ],
  "state": {
    "status": "checkmate",
    "winner": "south"
  }
}

Cross-Game: Chess vs Xiongqi

{
  "sides": {
    "north": {"name": "Chess Player"},
    "south": {"name": "Xiongqi Player"}
  },
  "setup": "+rnbq+kbn+r/pppppppp/8/8/8/PPPPPPPP/2C2C2/RHBEKBHR / XIONGQI/chess",
  "moves": [
    ["e3", "e4"],
    ["e7", "e5"]
  ],
  "state": {
    "status": "in_progress",
    "winner": null
  }
}

Mare King Victory

{
  "sides": {
    "north": {"name": "Alice"},
    "south": {"name": "Bob"}
  },
  "setup": "+rnbq+kbn+r/pppppppp/8/8/8/8/PPPPPPPP/+RNBQ+KBN+R / CHESS/chess",
  "moves": [
    ["e2", "e4"],
    ["f7", "f6"],
    ["d1", "h5"],
    ["g7", "g6"],
    ["h5", "e8"]
  ],
  "state": {
    "status": "mare_king",
    "winner": "south"
  }
}

Relationship with Other Specifications

PCN serves as the comprehensive game recording layer in the Sashité ecosystem:

Specification Relationship to PCN
CELL Core dependency: Provides multi-dimensional coordinate format for board locations in PMN moves
HAND Core dependency: Provides reserve location notation ("*") for capture-and-drop mechanics in PMN
GAN Core dependency: Provides actor identification format throughout moves and positions
PMN Core dependency: Represents each player’s turn as atomic action sequences using CELL and HAND
FEEN Core dependency: Provides initial setup and enables position reconstruction
SNN Inherited through GAN/FEEN: Distinguishes different piece systems and variants
PNN Inherited through GAN: Foundation for piece identification with state modifiers

PCN unifies these specifications to provide complete game documentation, ensuring that any recorded game can be fully reconstructed, analyzed, and shared across different implementations and platforms with full support for multi-dimensional boards and reserve-based mechanics.

JSON Schema

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

Reference Implementations

This section lists available libraries and tools that implement the PCN specification.

Ruby