Sashité for Developers

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.

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:

Universal Applicability

PMN’s mechanical approach enables universal application across:

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 of exactly 3 elements:

  1. Process elements left-to-right sequentially
  2. Group into sets of 3 consecutive elements
  3. Each group represents one atomic action

Array length must be divisible by 3 (complete action sequences only).

Action Sequence Format

Each action follows this fixed pattern:

[<source>, <destination>, <piece>]
Position Element Description
0 Source Origin location ("*" for drop from hand)
1 Destination Target location ("*" for capture to hand)
2 Piece Final piece state after the action

Element Specification

Source Location

Destination Location

Piece State

Constraint: Source and destination cannot both be "*" in the same action.

Mechanical Semantics

Execution Model

Actions execute sequentially in array order. Each action completes fully before the next begins, producing these deterministic effects:

  1. Source state change:
    • Board location → becomes empty
    • Hand ("*") → remove specified piece from hand/reserve
  2. Destination state change:
    • Board location → contains the final piece state
    • Hand ("*") → add specified piece to hand/reserve

  3. Piece transformation: Piece assumes its final state as specified

  4. 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.

Examples by Complexity

Note: The following descriptions represent common interpretations of PMN sequences, not inherent properties of the notation itself. PMN describes only mechanical transformations.

Basic Movements

Simple move (international chess):

["e2", "e4", "P"]

Piece P moves e2 → e4

Simple move (shōgi):

["7g", "7f", "P"]

Piece P moves 7g → 7f

Simple move (xiangqi):

["e4", "e5", "兵"]

Piece 兵 moves e4 → e5

Transformation (international chess):

["e7", "e8", "Q"]

Piece moves e7 → e8 and becomes Q

Drop from hand (shōgi):

["*", "5e", "P"]

Place piece P from hand onto 5e

Capture Mechanics

Simple capture with elimination (international chess):

["f3", "e4", "K"]

Piece K moves f3 → e4

Capture with retention (shōgi):

["2b", "*", "K", "2c", "2b", "S"]

Two actions: (1) Piece K at 2b goes to hand, (2) Piece S moves 2c → 2b

Cannon capture (xiangqi):

["a1", "a4", "車"]

Piece 車 moves a1 → a4

Complex Movements

Castling (international chess):

["e1", "g1", "K", "h1", "f1", "R"]

Two actions: (1) Piece K moves e1 → g1, (2) Piece R moves h1 → f1

En passant (international chess):

["d4", "e4", "P", "e4", "e3", "P"]

Two actions: (1) Piece P moves d4 → e4, (2) Piece P moves e4 → e3

Promotion with capture retention (shōgi):

["7f", "*", "S", "7g", "7f", "+P"]

Two actions: (1) Piece S at 7f goes to hand, (2) Piece moves 7g → 7f, becomes +P

Palace movement (xiangqi):

["e1", "f2", "仕"]

Piece 仕 moves e1 → f2

Piece exchange:

["e2", "*", "A", "e3", "e2", "B", "*", "e3", "A"]

Three actions: (1) Piece A at e2 goes to hand, (2) Piece B moves e3 → e2, (3) Piece A from hand goes to e3

Validation Requirements

Structural Validation

Semantic Validation

JSON Schema

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

The JSON Schema provides structural validation for PMN format compliance. Semantic validation (piece existence) must be implemented by applications based on current game state.

Ecosystem Integration

PMN serves as the execution layer in the Sashité notation ecosystem:

PMN uniquely focuses on mechanical decomposition, complementing formats that handle piece identification, position representation, and movement analysis.

Implementations

Ruby