Sashité for Developers

Portable Action Notation (PAN) Specification

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


Overview

Portable Action Notation (PAN) is a compact, string-based format for representing executed moves in abstract strategy board games played on coordinate-based boards. PAN provides a human-readable and space-efficient notation for expressing move actions in a rule-agnostic manner.

PAN focuses on representing the spatial aspects of moves: where pieces move from and to, and whether the move involves capture or placement. The notation is designed to be intuitive and compatible with standard algebraic coordinate systems.

Important: PAN is intentionally minimal and rule-agnostic. It represents only the basic spatial transformation of a move, without encoding piece types, promotion choices, game state, or complex move mechanics.


Properties


Constraints

  1. Coordinate format: Each coordinate must consist of exactly one alphabetic character followed by exactly one numeric character
  2. Source-destination distinction: Source and destination coordinates must be different to avoid ambiguity
  3. Board dimensions: Limited to 26×10 coordinate system (260 squares maximum)
  4. Two-dimensional: Designed for 2D boards only
  5. Move type restriction: Limited to exactly three move types (move, capture, drop)
  6. Promotion disambiguation: Cannot specify promotion choices or optional promotions
  7. Piece identity blindness: No encoding of piece types or identities
  8. Single action limitation: Cannot represent compound or multi-piece moves
  9. State change opacity: No indication of piece state modifications or transformations
  10. Context dependency: Requires external game state for complete move interpretation

Core Concepts

PAN represents moves as simple text strings that describe piece movement on a coordinate-based board. The notation distinguishes between three fundamental types of moves:

  1. Simple moves (-) - Moving a piece from one square to another empty square
  2. Captures (x) - Moving a piece from one square to another occupied square
  3. Drops/Placements (*) - Placing a piece from off-board to an empty square

Critical limitation: PAN cannot distinguish between different outcomes of the same spatial move (e.g., different promotion choices, optional promotions, or piece state changes).


Coordinate System

PAN uses algebraic coordinates consisting of:

Examples: e4, a1, h8, d5

This coordinate system supports boards up to 26×10 squares, which covers the vast majority of abstract strategy games but excludes larger variants and multi-dimensional games.

Format requirement: Coordinates must always follow the pattern <letter><digit>, where the letter precedes the digit.


Format Structure

Simple Move (Non-capture)

<source>-<destination>

Example: e2-e4

Capture Move

<source>x<destination>

Example: e4xd5

Drop/Placement

*<destination>

Example: *e4


Syntax Rules

Coordinate Format

Move Operators

Operator Symbol Meaning Limitations
Move - Simple movement to empty square Cannot distinguish promotion choices
Capture x Movement with capture Cannot specify captured piece type
Drop * Placement from off-board Cannot specify dropped piece type

Validation Rules

  1. Source coordinates (when present) must be valid algebraic coordinates
  2. Destination coordinates must be valid algebraic coordinates
  3. No spaces allowed within a move string
  4. Case consistency - letters must be lowercase, numbers must be single digits
  5. Operator consistency - exactly one operator per move
  6. Coordinate uniqueness - source and destination must be different

Examples with Limitations

Basic Examples

e2-e4      # Simple move from e2 to e4
d4xe5      # Capture move from d4 to e5
*h1        # Piece placement at h1
a1-a8      # Long-range move
g7-g8      # Move that could involve promotion (choice not specified)

Ambiguity Examples

# Multiple possible interpretations:
g7-g8      # Could be: pawn→queen, pawn→rook, pawn→bishop, pawn→knight
*g4        # Could be: drop any available piece type
a1-a8      # Could be: various piece types moving

Board State Implications

While PAN is rule-agnostic, the notation implies certain board state requirements:

Simple Moves (-)

Captures (x)

Drops (*)


Error Conditions

Invalid Syntax

E2-e4      # Invalid: uppercase letter
e2-E4      # Invalid: uppercase destination letter
e2 - e4    # Invalid: spaces
e2--e4     # Invalid: double operator
e24-e4     # Invalid: multiple digits
e2-e2      # Invalid: source equals destination
2e-4e      # Invalid: digit-letter order (reversed coordinates)
g2-2f      # Invalid: destination has digit-letter order
2g-2f      # Invalid: both coordinates have digit-letter order
2g-f2      # Invalid: source has digit-letter order

Semantic Conflicts

*e2xe4     # Invalid: mixed drop and capture syntax
e2-        # Invalid: missing destination
xe4        # Invalid: missing source for capture
--e4       # Invalid: double operator

Context-Dependent Invalidity

# These may be syntactically valid but contextually invalid:
e2-e4      # Invalid if e2 is empty or e4 is occupied
e4xe5      # Invalid if e5 is empty
*e4        # Invalid if e4 is occupied or no pieces available to drop

Limitations

1. Piece Identity Blindness

2. Promotion Choice Ambiguity

3. Game Context Dependency

4. Compound Move Limitation

5. State Transition Opacity

6. Capture Mechanics Blindness

7. Drop Source Ambiguity

8. Conditional Legality Ignorance

9. Turn Sequence Agnosticism

10. Multi-Dimensional Incompatibility


Advantages

  1. Intuitive: Based on familiar algebraic notation
  2. Compact: Minimal character overhead (3-5 characters per move)
  3. Visual: Operators clearly indicate move type at a glance
  4. Unambiguous syntax: Each move type has distinct, parseable format
  5. Rule-agnostic: Works with any coordinate-based game
  6. Human-readable: Easy to read and write manually
  7. Parseable: Simple regular expression parsing
  8. Storage efficient: Excellent for large game databases

When to Use PAN

Optimal Use Cases

When PAN is Insufficient


Formal Grammar (BNF)

<pan-move> ::= <simple-move> | <capture-move> | <drop-move>

<simple-move> ::= <coordinate> "-" <coordinate>
<capture-move> ::= <coordinate> "x" <coordinate>
<drop-move> ::= "*" <coordinate>

<coordinate> ::= <letter> <digit>

<letter> ::= "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" | "i" | "j"
          | "k" | "l" | "m" | "n" | "o" | "p" | "q" | "r" | "s" | "t"
          | "u" | "v" | "w" | "x" | "y" | "z"

<digit> ::= "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"

Additional Constraint

For all move types, source coordinate and destination coordinate must be different when both are present.


Regular Expression Pattern

\A(\*|[a-z][0-9][-x])([a-z][0-9])\z

This pattern captures:

Validation Constraints


Relationship to Other Notations

Notation Purpose Relationship to PAN Complementarity
PMN Structured move data with piece identity PAN is compact alternative PMN provides what PAN lacks
FEEN Board state representation PAN moves transform FEEN positions Essential for PAN context
GGN Move possibility rules PAN represents executed moves matching GGN rules GGN validates PAN moves
PNN Piece identification PAN works with any piece notation PNN provides piece context
GAN Game-qualified piece identifiers PAN is agnostic to piece games GAN clarifies cross-game pieces

Use Cases and Recommendations

Ideal for PAN

Consider Alternatives When

Best Practices

  1. Always pair with context: Store board state alongside PAN moves
  2. Document assumptions: Clearly specify how ambiguities are resolved
  3. Validate rigorously: Check both syntax and semantic validity
  4. Consider alternatives: Evaluate if PAN’s limitations affect your use case
  5. Plan for edge cases: Handle promotion and drop ambiguities explicitly

Reference Implementation

Ruby