Portable Move Notation (PMN) Specification
- Version: 1.0.0
- Author: Sashité
- Published: May 1, 2025
- License: MIT License
Overview
Portable Move Notation (PMN) is a rule-agnostic, JSON-based format for describing the mechanical decomposition of moves in abstract strategy board games. PMN breaks down complex movements into sequences of atomic actions, revealing the underlying mechanics while remaining completely independent of specific game rules, validation logic, or gameplay concepts.
PMN provides a universal vocabulary for expressing how pieces physically move, interact, and transform during gameplay across any board game system, from traditional chaturanga to modern variants and hybrid games.
Terminology
For complete definitions of terms used in this document, see the Glossary.
Core Philosophy
Mechanical Decomposition
PMN treats every move as a sequence of atomic mechanical actions. Each action represents a single, indivisible transformation that occurs during move execution. Complex movements that appear as single “moves” in traditional notation are decomposed into their constituent mechanical steps.
Key principle: PMN describes what happens mechanically, not what is allowed or why it happens.
Atomic Actions
An atomic action is the smallest meaningful transformation in a game system:
- One piece moving from one location to another
- Optional specification of the piece’s final state
- All actions are independent and execute sequentially
Universal Applicability
PMN’s mechanical approach enables universal application across:
- Chaturanga family games: Western Chess, Japanese Shōgi, Chinese Xiangqi, Thai Makruk, Burmese Sittuyin
- Regional board games: Go placement and captures, mancala transfers
- Modern innovations: Fairy pieces, multi-dimensional boards
- Hybrid systems: Cross-game piece interactions
Dependencies
PMN builds upon three 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
These specifications define the building blocks that PMN composes into action sequences.
Format Structure
Flat Array Representation
A PMN move is a flat JSON array containing the complete action sequence:
[<element-1>, <element-2>, <element-3>, <element-4>, <element-5>, <element-6>, ...]
Action Sequence Parsing
The array is parsed by grouping elements into action sequences:
- Process elements left-to-right sequentially
- Group into sets of 3 consecutive elements
- If the final group contains only 2 elements, the piece is omitted (inferred from context)
- Each group represents one atomic action
Array length requirements:
- Minimum: 2 elements (one action with omitted piece)
- Multiple of 3, OR multiple of 3 plus 2 (final action with omitted piece)
Action Sequence Format
Each action follows this pattern:
[<source>, <destination>, <piece>?]
| Position | Element | Description |
|---|---|---|
| 0 | Source | Origin location (CELL coordinate or HAND "*") |
| 1 | Destination | Target location (CELL coordinate or HAND "*") |
| 2 | Piece | Final piece state after the action (QPI format, optional) |
Optional Piece Specification
When the piece is omitted, the game rules and position context must provide enough information to unambiguously determine:
- Which piece performs the action
- The piece’s final state after the action
This allows for concise representation when the context eliminates ambiguity.
Element Specification
Source Location
- Type: Non-empty string
- CELL coordinate: Any valid multi-dimensional board position (
"e4","e5","a1A") - HAND location:
"*"indicates placement from reserve/hand
Destination Location
- Type: Non-empty string
- CELL coordinate: Any valid multi-dimensional board position
- HAND location:
"*"indicates capture to reserve/hand
Piece State (Optional)
- Type: Non-empty string
- Format: Must conform to QPI specification (
<style>:<piece>) - Purpose: Describes the piece’s final state after the action
- Identity preservation: Use current identifier if piece unchanged
- Transformation: Use new identifier if piece changes state or ownership
- Omission: When omitted, piece state inferred from game rules and context
- QPI Constraints: Must respect QPI case-style consistency (uppercase pieces use uppercase style, lowercase pieces use lowercase style)
Constraint: Source and destination must be different in the same action (no self-referential transfers).
Mechanical Semantics
Execution Model
Actions execute sequentially in array order. Each action completes fully before the next begins, producing these deterministic effects:
- Source state change:
- CELL location → becomes empty
- HAND location (
"*") → remove specified piece from reserve/hand
- Destination state change:
- CELL location → contains the final piece state
- HAND location (
"*") → add specified piece to reserve/hand
-
Piece transformation: Piece assumes its final state (specified or inferred)
- Atomic commitment: All changes occur atomically per action
State Dependencies
Later actions may reference locations modified by earlier actions, enabling complex movement patterns like exchanges or multi-step captures.
JSON Schema
Schema URL: https://sashite.dev/schemas/pmn/1.0.0/schema.json
The JSON Schema provides structural validation for PMN format compliance. Format validation (CELL/HAND/QPI conformity) and semantic validation (piece existence, inference, and QPI consistency) must be implemented by applications based on current game state and dependency specifications.
Examples
See PMN Examples for practical implementation guidance.
Reference Implementations
Ruby
- PMN.rb – Complete mechanical decomposition support with full validation, piece inference, and QPI compliance checking.