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
- PAN is rule-agnostic and does not encode piece types, legality, or game-specific conditions
- PAN provides compact representation suitable for move logs and transmission
- PAN supports three fundamental move types: movement, capture, and placement
- PAN uses intuitive algebraic coordinates familiar from chess notation
- PAN requires external context for complete move interpretation
Constraints
- Coordinate format: Each coordinate must consist of exactly one alphabetic character followed by exactly one numeric character
- Source-destination distinction: Source and destination coordinates must be different to avoid ambiguity
- Board dimensions: Limited to 26×10 coordinate system (260 squares maximum)
- Two-dimensional: Designed for 2D boards only
- Move type restriction: Limited to exactly three move types (move, capture, drop)
- Promotion disambiguation: Cannot specify promotion choices or optional promotions
- Piece identity blindness: No encoding of piece types or identities
- Single action limitation: Cannot represent compound or multi-piece moves
- State change opacity: No indication of piece state modifications or transformations
- 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:
- Simple moves (
-
) - Moving a piece from one square to another empty square - Captures (
x
) - Moving a piece from one square to another occupied square - 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:
- Alphabetic character: A single letter (
a-z
) - Numeric character: A single digit (
0-9
)
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
- Moves a piece from
e2
toe4
- Implies source square is occupied
- Implies destination square is empty
- Does not specify: which piece type is moving or any state changes
Capture Move
<source>x<destination>
Example: e4xd5
- Moves a piece from
e4
tod5
, capturing the piece atd5
- Implies source square is occupied
- Implies destination square is occupied (and will be captured)
- Does not specify: which piece types are involved or what happens to captured piece
Drop/Placement
*<destination>
Example: *e4
- Places a piece at
e4
from off-board (hand, reserve, etc.) - Implies destination square is empty
- Does not specify: which piece type is being dropped
Syntax Rules
Coordinate Format
- Alphabetic character: Single letter
a-z
(lowercase only) - Numeric character: Single digit
0-9
- Order: Alphabetic character followed immediately by numeric character
- Case sensitivity: Letters must be lowercase
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
- Source coordinates (when present) must be valid algebraic coordinates
- Destination coordinates must be valid algebraic coordinates
- No spaces allowed within a move string
- Case consistency - letters must be lowercase, numbers must be single digits
- Operator consistency - exactly one operator per move
- 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 (-
)
- Source square must be occupied
- Destination square must be empty
- Legal movement path (determined by game rules)
- Cannot encode: piece state changes during movement
Captures (x
)
- Source square must be occupied
- Destination square must be occupied
- Cannot encode: what happens to captured piece (removed vs. to hand)
Drops (*
)
- Destination square must be empty
- Piece availability in hand/reserve (determined by game rules)
- Cannot encode: which specific piece from available options
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
- Problem: Does not encode which piece is moving or being captured
- Impact: Ambiguous when multiple pieces can reach the same destination
- Example:
a1-a8
could be various piece types
2. Promotion Choice Ambiguity
- Problem: Cannot distinguish between different promotion options
- Impact: Incomplete representation of player choice in promotion scenarios
- Example:
g7-g8
doesn’t specify promotion choice
3. Game Context Dependency
- Problem: Requires external context for complete interpretation
- Impact: PAN strings are meaningless without board state and game rules
- Example: Move validity depends on current position
4. Compound Move Limitation
- Problem: Cannot represent multi-step or simultaneous piece movements
- Impact: Complex moves like castling require multiple PAN strings
- Example: Castling needs separate representation for different pieces
5. State Transition Opacity
- Problem: No support for piece state changes or transformations
- Impact: Cannot represent promotion, enhancement, or state modifiers
- Example: Cannot distinguish promoted vs. unpromoted piece movement
6. Capture Mechanics Blindness
- Problem: No information about captured piece handling
- Impact: Cannot distinguish removal vs. capture-to-hand mechanics
- Example: Different capture mechanics have different implications
7. Drop Source Ambiguity
- Problem: Cannot specify which piece type is being dropped
- Impact: Ambiguous when multiple piece types are available
- Example:
*e4
unclear which piece type is being placed
8. Conditional Legality Ignorance
- Problem: No encoding of context-dependent move restrictions
- Impact: Cannot represent moves that are conditionally legal/illegal
- Example: Cannot encode “illegal due to check” or “requires specific game state”
9. Turn Sequence Agnosticism
- Problem: No player or turn sequence information
- Impact: Moves cannot be interpreted without external turn tracking
- Example: Same PAN string could represent different players’ moves
10. Multi-Dimensional Incompatibility
- Problem: Designed only for 2D coordinate systems
- Impact: Cannot represent 3D games or higher-dimensional variants
- Example: Cannot address 3D coordinates
Advantages
- Intuitive: Based on familiar algebraic notation
- Compact: Minimal character overhead (3-5 characters per move)
- Visual: Operators clearly indicate move type at a glance
- Unambiguous syntax: Each move type has distinct, parseable format
- Rule-agnostic: Works with any coordinate-based game
- Human-readable: Easy to read and write manually
- Parseable: Simple regular expression parsing
- Storage efficient: Excellent for large game databases
When to Use PAN
Optimal Use Cases
- Move logs: Simple game records where context is available
- User interfaces: Command input for move entry
- Network protocols: Compact move transmission between systems
- Databases: Space-efficient storage when coupled with position data
- Quick notation: Manual notation for simple games
When PAN is Insufficient
- Ambiguous games: Games where multiple pieces can make the same spatial move
- Complex promotions: Games with multiple promotion choices
- Compound moves: Games with castling, multi-piece moves, or piece swapping
- Drop games with choices: When multiple piece types can be dropped
- State-dependent games: When piece state significantly affects representation
- Analysis tools: When piece identity is crucial for move evaluation
- Complete game notation: When self-contained move records are needed
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:
- Group 1: Source with operator (
*
, or coordinate followed by-
orx
) - Group 2: Destination coordinate
Validation Constraints
- Source and destination coordinates must be different (when source is present)
- Coordinates must be within valid board dimensions for the specific game
- Coordinates must follow the
<letter><digit>
format
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
- Simple move logging: Recording moves with available game context
- User input: Command-line or text-based move entry
- Network transmission: Sending moves between clients with shared state
- Database storage: Compact storage when combined with position records
- Manual notation: Quick handwritten game records
Consider Alternatives When
- Self-contained records needed: Use PMN for complete move information
- Multiple promotion choices: Requires disambiguation mechanism
- Cross-game scenarios: May need GAN-qualified piece identifiers
- Complex move analysis: Piece identity crucial for evaluation
- Archival purposes: Long-term storage without guaranteed context
Best Practices
- Always pair with context: Store board state alongside PAN moves
- Document assumptions: Clearly specify how ambiguities are resolved
- Validate rigorously: Check both syntax and semantic validity
- Consider alternatives: Evaluate if PAN’s limitations affect your use case
- Plan for edge cases: Handle promotion and drop ambiguities explicitly
Reference Implementation
Ruby
- Pan.rb - Full implementation of PAN specification for Ruby, including parsing, validation, and context integration utilities