Portable Action Notation (PAN) Specification

Version: 1.0.0
Author: Sashité
Published: October 19, 2025
License: MIT License

Overview

Portable Action Notation (PAN) is a rule-agnostic, compact string format for representing atomic actions in abstract strategy board games. PAN provides a canonical representation for identifying moves unambiguously through minimal notation that captures the essential transformation applied to a game position.

An action is an atomic operation that alters a position. PAN focuses on expressing the explicit transformations while allowing game rules to handle implicit consequences. The notation uses intuitive operators to express board transformations with minimal characters, making it ideal for move transmission, game recording, and user interfaces.

Terminology

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

Key concepts for this specification:

Action: An atomic operation that alters a position
Explicit effect: Transformation directly specified in the action notation and its direct consequences
Implicit effect: Side effect determined by game rules, not specified in notation
Movement: Displacing a piece from one location to another
Capture: Removing a piece from the board to a player’s reserve
Modification: Changing a piece’s attributes (promotion, demotion, style change)
Drop: Placing a piece from reserve onto the board
Castling: Special chess move involving simultaneous movement of king and rook

Dependencies

PAN builds upon two foundational Sashité specifications:

CELL: Multi-dimensional coordinate encoding for board positions
EPIN: Extended Piece Identifier Notation for style-aware piece representation

Action Philosophy

Core Principles

PAN operates on five fundamental principles:

Atomic operations: Each action represents a single, indivisible transformation
Move identification: Actions provide the minimum information needed to identify moves unambiguously
Explicit vs implicit: Actions specify primary transformations; game rules handle secondary effects
Turn change: Every action explicitly changes the active player
Rule independence: Actions express intent, not legality or complete consequences

Scope Boundaries

PAN actions specify:

The primary transformation (movement, capture, modification, drop, castling)
Direct consequences of the primary transformation
Explicit piece changes when needed for disambiguation
Active player change (always explicit)

PAN actions do NOT specify:

Secondary effects beyond direct consequences
Cascading captures or chain reactions
Legality validation
Indirect consequences determined by game rules

Action Types

PAN supports nine distinct action types organized by their primary transformation:

Action Type	Syntax	Description
Pass	`...`	Changes active player without board alteration
Movement	`<src>-<dst>[=<piece>]`	Moves piece to empty square
Capture Movement	`<src>+<dst>[=<piece>]`	Moves piece with capture at destination
Static Capture	`+<square>`	Captures piece without movement
Drop to Empty	`[<piece>]*<dst>[=<piece>]`	Places from reserve to empty square
Drop with Capture	`[<piece>].<dst>[=<piece>]`	Places from reserve, capturing at destination
In-Place Modification	`<square>=<piece>`	Modifies piece attributes without movement
King-side Castling	`0-0`	Chess king-side castling
Queen-side Castling	`0-0-0`	Chess queen-side castling

Format Specification

Grammar (BNF)

<pan> ::= <pass>
        | <movement>
        | <capture-movement>
        | <static-capture>
        | <drop-empty>
        | <drop-capture>
        | <modification>
        | <castling>

<pass> ::= "..."

<movement> ::= <square> "-" <square>
             | <square> "-" <square> "=" <epin>

<capture-movement> ::= <square> "+" <square>
                     | <square> "+" <square> "=" <epin>

<static-capture> ::= "+" <square>

<drop-empty> ::= <epin> "*" <square>
               | "*" <square>
               | <epin> "*" <square> "=" <epin>
               | "*" <square> "=" <epin>

<drop-capture> ::= <epin> "." <square>
                 | "." <square>
                 | <epin> "." <square> "=" <epin>
                 | "." <square> "=" <epin>

<modification> ::= <square> "=" <epin>

<castling> ::= "0-0"
             | "0-0-0"

<square> ::= <cell>           ; Per CELL specification
<epin> ::= <extended-piece>   ; Per EPIN specification

Operators

Operator	Name	Function
`-`	Dash	Movement to empty square
`+`	Plus	Movement with capture (including en passant)
`*`	Asterisk	Drop to empty square
`.`	Period	Drop with capture
`=`	Equals	Piece modification
`0`	Zero	Castling notation component

Action Semantics

Pass Action

Syntax: ...

The pass action allows a player to voluntarily conclude their turn without altering the board state. This changes the active player to the opponent while maintaining all piece positions unchanged.

Movement to Empty Square

Syntax: <src>-<dst>[=<piece>]

Moves a piece from the source square to an empty destination square. The optional =<piece> suffix explicitly specifies the piece’s final state after movement, useful for promotions or transformations. Without this suffix, any transformations are determined by game rules (such as mandatory promotion zones).

Constraints: Source and destination must be different squares.

Movement with Capture

Syntax: <src>+<dst>[=<piece>]

Moves a piece from the source square to the destination square, capturing any piece present. This notation is also used for en passant captures in chess, where the destination square is empty but a capture occurs as an implicit effect.

For en passant, the + operator correctly indicates that a capture occurs during the move, even though the destination square itself is empty. The actual removal of the captured pawn (at a different square) is handled as an implicit effect by chess rules.

Constraints: Source and destination must be different squares.

Static Capture

Syntax: +<square>

Captures the piece at the specified square without any piece movement. This is used in games with custodian capture, area effects, or other non-movement capture mechanics. The captured piece moves to the active player’s reserve.

Drop to Empty Square

Syntax: [<piece>]*<dst>[=<piece>]

Places a piece from the active player’s reserve onto an empty board square. The piece can be explicitly specified or inferred from context. The optional transformation suffix allows for pieces that change state upon placement.

Drop with Capture

Syntax: [<piece>].<dst>[=<piece>]

Places a piece from the active player’s reserve onto an occupied square, capturing the existing piece. This rare action type combines placement with capture in a single atomic operation.

In-Place Modification

Syntax: <square>=<piece>

Transforms the piece at the specified square without changing its location. Used for promotions without movement, state changes, or style conversions. The piece must change to a different state than its current one.

Castling

Syntax: 0-0 (king-side) or 0-0-0 (queen-side)

Special notation for chess castling moves, providing a canonical representation independent of the actual king and rook positions. These actions are universal across all chess positions:

0-0: King-side castling (short castling)
0-0-0: Queen-side castling (long castling)

The implicit effects (specific king and rook movements) are determined by the chess variant being played and the current player. This notation elegantly handles castling for both players without needing position-specific notation.

Implicit Consequences

Actions trigger explicit effects (specified in notation) and implicit effects (determined by game rules). The distinction ensures PAN remains rule-agnostic while providing complete move identification.

Chess Examples

Castling: 0-0

Explicit: King-side castling action for the active player
Implicit: Specific king and rook movements based on player side and chess variant

En Passant: e5+f6

Explicit: Pawn moves from e5 to f6 with capture indication
Implicit: Enemy pawn at f5 is removed (en passant rule)

Pawn Promotion: e7-e8=Q

Explicit: Pawn moves to e8 and becomes a queen
Implicit: None (transformation is explicit)

Shōgi Examples

Mandatory Promotion: g8-g9

Explicit: Piece moves from g8 to g9
Implicit: Piece promotes to enhanced state (mandatory zone rule)

Capture with Ownership Change: b2+b8

Explicit: Piece captures from b2 to b8
Implicit: Captured piece changes ownership and enters capturer’s reserve

Design Properties

PAN embodies several key design properties that ensure its effectiveness as a universal action notation:

Atomic representation: Each action is indivisible and complete
Canonical form: Each unique action has exactly one valid representation
Minimal notation: Uses the fewest characters necessary for unambiguous identification
Intuitive operators: Symbol choices reflect their semantic meaning
Rule-agnostic: Independent of specific game mechanics or variants
Context-aware: Supports both explicit and inferred specifications
Turn consistency: Every action explicitly changes the active player

The notation achieves a balance between brevity and clarity, making it suitable for both human use and machine processing. The addition of specialized notations for common complex moves (like castling) demonstrates PAN’s pragmatic approach to real-world usage.

Examples

See PAN Examples for comprehensive implementation guidance covering all action types and game scenarios.

Reference Implementations

Ruby

PAN.rb — Reference implementation with full validation, parsing, and generation support for all PAN action types including castling notation.