Sashité for Developers
  1. Sashité for Developers
  2. Specifications
  3. PMN
  4. 1.0.0

Portable Move Notation (PMN) Specification

1. Status of this document

The key words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are to be interpreted as normative requirements.

Capitalized terms (Action, Active Player, Board, Displacement, Hand, Location, Move, Mutation, Pass Move, Piece, Position, Square) are defined in the Glossary. This document does not redefine those terms.

2. Overview

Portable Move Notation (PMN) is a human-readable string format for representing Moves (as defined by the Glossary).

A PMN string represents an ordered, finite sequence of zero or more Actions.

2.1. Purpose

PMN provides an operator-based syntax to describe, at protocol level, how a Move transforms a Position through:

2.2. Design principles

PMN is:

All geometric meaning belongs to Rule Systems, not to PMN.

3. Dependencies

PMN relies on two Sashité specifications:

Specification Purpose
CELL Coordinate encoding for Board Squares
EPIN Extended Piece identifiers

PMN treats CELL coordinates and EPIN identifiers as opaque but syntactically validated tokens.

4. Scope

4.1. What PMN defines

PMN defines:

4.2. What PMN does not define

PMN does not define:

Those concerns belong to the Rule System.

5. Terminology

PMN introduces the following notation-specific terms:

Term Definition
Operator A character (-, +, ~, *, ., =) indicating the Move category
Form A concrete syntactic shape using an operator (e.g., src+dst vs +square)
Direct effect The minimal ordered Action sequence implied by the PMN string (as defined in this spec)
Implicit effect Additional Actions triggered by the Rule System but not determined solely by the PMN string
Actor The Piece explicitly moved, dropped, or mutated by the PMN string
Actor transformation A Mutation applied to the Actor, encoded via =<piece>
Capture transformation A Mutation applied to a captured Piece, encoded via /<piece>
Captured Piece The Piece removed from the Board as part of a Capture-like effect (Board → Hand)

Note: A PMN string may imply Actions affecting more than one Piece across the whole Move. This is expected and is consistent with a Move being a sequence of Actions.

6. Operators and forms

PMN defines six operators and one special sequence. Some operators have multiple forms.

Form Operator Name Category
... — Pass Pass Move (zero Actions)
src-dst - Dash Movement to empty Square
src+dst + Plus (infix) Movement with Capture
+square + Plus (prefix) Static Capture (no movement)
src~dst ~ Tilde Special movement with possible implicit effects
[piece]*dst / *dst * Asterisk Drop to empty Square
[piece].dst / .dst . Period Drop with Capture
square=piece = Equals In-place Mutation

7. Format specification

7.1. General structure

A PMN string follows one of these patterns depending on the operator and form:

...                                           # Pass Move
<src>-<dst>[=<actor>]                         # Move to empty
<src>+<dst>[=<actor>][/<captured>]            # Move with Capture
<src>~<dst>[=<actor>][/<captured>]            # Special Move
+<square>[/<captured>]                        # Static Capture (no movement)
[<piece>]*<dst>[=<actor>]                     # Drop to empty
[<piece>].<dst>[=<actor>][/<captured>]        # Drop with Capture
<square>=<piece>                              # In-place Mutation

Where:

7.2. Components

Component Description Required
Source (<src>) Origin Square (CELL) Varies by form
Destination (<dst>) Target Square (CELL) Varies by form
Square (<square>) Target Square (CELL) Varies by form
Piece (<piece>) Dropped Piece (EPIN) Optional for Drops
Actor transformation (=<actor>) Mutation of the Actor Present iff Actor mutates
Capture transformation (/<captured>) Mutation of the captured Piece Present iff captured Piece mutates

7.3. Transformation suffix ordering

When both suffixes are present, they MUST appear in this order:

[=<actor>][/<captured>]

The actor transformation MUST precede the capture transformation.

7.4. Transformation suffix canonicalization (normative)

Transformation suffixes encode Mutations. Their presence or absence is determined by whether a Mutation occurs — not by convention or preference.

Actor transformation (=<actor>):

Capture transformation (/<captured>):

A Piece Identity change occurs when at least one of the following attributes differs between the pre-Mutation and post-Mutation state: Piece Side, Piece Name, Piece State, Piece Style, or Terminal Status.

This rule ensures that each Move has exactly one valid PMN representation. Implementations MUST enforce this rule. A PMN string that includes a no-op transformation suffix (where the EPIN encodes an unchanged identity) is non-conforming and MUST be rejected.

8. Direct effect decomposition (normative)

This section is normative. Each PMN form defines a direct effect: a minimal, ordered sequence of protocol-level Actions.

Actions within a direct effect are applied sequentially, consistent with the Game Protocol’s Action ordering semantics. Each Action is evaluated against the state produced by all preceding Actions.

Capture destination: As defined by the Game Protocol, all Board → Hand Displacements (captures) target the Active Player’s Hand. PMN does not encode which Hand receives the captured Piece; this is determined by the Protocol based on who is performing the Move.

Rule Systems MAY add implicit effects (additional Actions) as needed.

8.1. Pass Move

Syntax:

...

Direct effect:

Constraints:

8.2. Movement to empty Square (-)

Syntax:

<source>-<destination>[=<actor>]

Direct effect (minimal Action sequence):

  1. Actor Action: Board(<source>) → Board(<destination>)

    • If =<actor> is present, apply the Actor Mutation as part of this Action.
    • =<actor> MUST be present if and only if the Actor’s Piece Identity changes.

8.3. Movement with Capture (src+dst)

Syntax:

<source>+<destination>[=<actor>][/<captured>]

Direct effect (minimal Action sequence):

  1. Capture Action: Board(<destination>) → Active Player’s Hand

    • If /<captured> is present, apply the captured-Piece Mutation as part of this Action.
    • /<captured> MUST be present if and only if the captured Piece’s Piece Identity changes.

  2. Actor Action: Board(<source>) → Board(<destination>)

    • If =<actor> is present, apply the Actor Mutation as part of this Action.
    • =<actor> MUST be present if and only if the Actor’s Piece Identity changes.

This ordering ensures that the destination Square is vacated before the Actor arrives, maintaining Square Occupancy throughout the sequential application of Actions.

Constraints:

8.4. Special movement (~)

Syntax:

<source>~<destination>[=<actor>][/<captured>]

Direct effect (minimal Action sequence):

  1. Actor Action: Board(<source>) → Board(<destination>)

    • If =<actor> is present, apply the Actor Mutation as part of this Action.
    • =<actor> MUST be present if and only if the Actor’s Piece Identity changes.

Implicit effects (Rule System-defined):

If /<captured> is present, it specifies the Mutation to apply to the captured Piece if and only if a Capture-like implicit effect occurs. Any such implicit capture targets the Active Player’s Hand as defined by the Game Protocol.

/<captured> MUST be present if and only if a Capture does occur and the captured Piece’s Piece Identity changes. If no Capture occurs, /<captured> MUST be omitted. If a Capture occurs but the captured Piece is unchanged, /<captured> MUST also be omitted.

Constraints:

8.5. Static Capture (+square)

Syntax:

+<square>[/<captured>]

Direct effect (minimal Action sequence):

  1. Capture Action: Board(<square>) → Active Player’s Hand

    • If /<captured> is present, apply the captured-Piece Mutation as part of this Action.
    • /<captured> MUST be present if and only if the captured Piece’s Piece Identity changes.

Constraints:

8.6. Drop to empty Square (*)

Syntax:

[<piece>]*<destination>[=<actor>]

Direct effect (minimal Action sequence):

  1. Actor Action: Active Player’s Hand → Board(<destination>)

    • If <piece> is present, it identifies the dropped Piece.
    • If =<actor> is present, apply the Actor Mutation as part of this Action.
    • =<actor> MUST be present if and only if the Actor’s Piece Identity changes.

Constraints:

Note: Drops originate from the Active Player’s Hand, as only the Active Player performs Moves.

8.7. Drop with Capture (.)

Syntax:

[<piece>].<destination>[=<actor>][/<captured>]

Direct effect (minimal Action sequence):

  1. Capture Action: Board(<destination>) → Active Player’s Hand

    • If /<captured> is present, apply the captured-Piece Mutation as part of this Action.
    • /<captured> MUST be present if and only if the captured Piece’s Piece Identity changes.

  2. Actor Action: Active Player’s Hand → Board(<destination>)

    • If <piece> is present, it identifies the dropped Piece.
    • If =<actor> is present, apply the Actor Mutation as part of this Action.
    • =<actor> MUST be present if and only if the Actor’s Piece Identity changes.

This ordering ensures that the destination Square is vacated before the dropped Piece arrives, maintaining Square Occupancy throughout the sequential application of Actions.

Constraints:

8.8. In-place Mutation (=)

Syntax:

<square>=<piece>

Direct effect (minimal Action sequence):

  1. Mutation-only Action: mutate the Piece at Board(<square>) to match <piece>.

This Action consists of a Mutation without a Displacement, which is a valid Action composition per the Game Protocol.

Constraints:

9. Grammar

9.1. EBNF

pmn                    = pass-move
                       | movement-move
                       | static-capture
                       | drop-move
                       | in-place-mutation ;

pass-move              = "..." ;

movement-move          = move-quiet
                       | move-capture
                       | move-special ;

move-quiet             = square "-" square [ actor-transformation ] ;
move-capture           = square "+" square [ actor-transformation ] [ capture-transformation ] ;
move-special           = square "~" square [ actor-transformation ] [ capture-transformation ] ;

static-capture         = "+" square [ capture-transformation ] ;

drop-move              = drop-quiet
                       | drop-capture ;

drop-quiet             = [ piece ] "*" square [ actor-transformation ] ;
drop-capture           = [ piece ] "." square [ actor-transformation ] [ capture-transformation ] ;

in-place-mutation      = square "=" piece ;

actor-transformation   = "=" piece ;
capture-transformation = "/" piece ;

square                 = cell ;   (* CELL specification *)
piece                  = epin ;   (* EPIN specification *)

The grammar defines syntactic structure. The canonicalization rule above (transformation suffixes are present if and only if a Mutation occurs) is a semantic constraint layered on top: syntactically valid strings that violate this rule are non-conforming.

9.2. Regular expressions

The following patterns validate each PMN category. All patterns MUST be applied with full-string anchoring.

Pass Move:

^\.{3}$

Movement to empty Square:

^[a-z]+(?:[1-9][0-9]*[A-Z]+[a-z]+)*(?:[1-9][0-9]*[A-Z]*)?-[a-z]+(?:[1-9][0-9]*[A-Z]+[a-z]+)*(?:[1-9][0-9]*[A-Z]*)?(=[+-]?[A-Za-z]\^?'?)?$

Movement with Capture (infix +):

^[a-z]+(?:[1-9][0-9]*[A-Z]+[a-z]+)*(?:[1-9][0-9]*[A-Z]*)?\+[a-z]+(?:[1-9][0-9]*[A-Z]+[a-z]+)*(?:[1-9][0-9]*[A-Z]*)?(=[+-]?[A-Za-z]\^?'?)?(/[+-]?[A-Za-z]\^?'?)?$

Special movement:

^[a-z]+(?:[1-9][0-9]*[A-Z]+[a-z]+)*(?:[1-9][0-9]*[A-Z]*)?~[a-z]+(?:[1-9][0-9]*[A-Z]+[a-z]+)*(?:[1-9][0-9]*[A-Z]*)?(=[+-]?[A-Za-z]\^?'?)?(/[+-]?[A-Za-z]\^?'?)?$

Static Capture (prefix +):

^\+[a-z]+(?:[1-9][0-9]*[A-Z]+[a-z]+)*(?:[1-9][0-9]*[A-Z]*)?(/[+-]?[A-Za-z]\^?'?)?$

Drop to empty Square:

^([+-]?[A-Za-z]\^?'?)?\*[a-z]+(?:[1-9][0-9]*[A-Z]+[a-z]+)*(?:[1-9][0-9]*[A-Z]*)?(=[+-]?[A-Za-z]\^?'?)?$

Drop with Capture:

^([+-]?[A-Za-z]\^?'?)?\.[a-z]+(?:[1-9][0-9]*[A-Z]+[a-z]+)*(?:[1-9][0-9]*[A-Z]*)?(=[+-]?[A-Za-z]\^?'?)?(/[+-]?[A-Za-z]\^?'?)?$

In-place Mutation:

^[a-z]+(?:[1-9][0-9]*[A-Z]+[a-z]+)*(?:[1-9][0-9]*[A-Z]*)?=[+-]?[A-Za-z]\^?'?$

9.3. Anchoring requirement

Implementations MUST validate PMN strings using full-string matching:

10. Validation

10.1. Syntactic validity

A PMN string is syntactically valid if and only if:

  1. It conforms to the EBNF grammar defined in the Grammar section of this specification.
  2. All Squares are syntactically valid CELL coordinates.
  3. All Pieces are syntactically valid EPIN identifiers.
  4. Transformation suffixes appear in the correct order (= before /).
  5. The string contains no extraneous characters.

10.2. Semantic conformance (normative)

Beyond syntactic validity, a conforming PMN string MUST satisfy the following semantic constraints, evaluated against the Position to which the Move is applied:

  1. Transformation necessity: =<actor> MUST appear if and only if the Actor’s Piece Identity changes. /<captured> MUST appear if and only if the captured Piece’s Piece Identity changes. A PMN string with a no-op transformation suffix (encoding an unchanged identity) MUST be rejected.
  2. Movement sanity: Source and destination SHOULD differ.
  3. Capture context: /<captured> MUST only appear with Capture-capable forms (src+dst, +square, src~dst, [piece].dst).
  4. Context completeness: Omitted <piece> in Drops requires unambiguous context.

Constraint 1 is normative and enforced at the semantic level. Constraints 2–4 are enforced where checkable without Rule System knowledge.

11. Protocol alignment

11.1. Mapping to Game Protocol concepts

PMN encodes Moves, i.e., ordered sequences of Actions.

PMN coordinates (CELL strings) represent Squares on the Board. The validity of a Square identifier depends on the Board structure, which is defined by the Rule System. PMN performs syntactic validation of CELL coordinates but does not verify that a coordinate corresponds to an existing Square on any particular Board.

PMN form Protocol interpretation
... Pass Move (zero Actions)
src-dst[=<actor>] Direct effect includes one Board → Board Action (Actor)
src+dst[=<actor>][/<captured>] Direct effect includes one Board → Active Player’s Hand Action (captured) + one Board → Board Action (Actor)
src~dst[=<actor>][/<captured>] Direct effect includes one Board → Board Action (Actor) + possible implicit Actions
+square[/<captured>] Direct effect includes one Board → Active Player’s Hand Action (captured)
[<piece>]*dst[=<actor>] Direct effect includes one Active Player’s Hand → Board Action (Actor)
[<piece>].dst[=<actor>][/<captured>] Direct effect includes one Board → Active Player’s Hand Action (captured) + one Active Player’s Hand → Board Action (Actor)
square=piece Direct effect includes one Mutation-only Action

Transformations:

11.2. Displacement patterns

Every Displacement in PMN conforms to the three patterns allowed by the Game Protocol:

Pattern PMN forms
Board → Board src-dst, src+dst (Actor step), src~dst (direct effect)
Board → Hand src+dst (Capture step), +square, [piece].dst (Capture step), src~dst (implicit only, if Rule System captures)
Hand → Board [piece]*dst, [piece].dst (Drop step)

11.3. Capture destination

As defined by the Game Protocol, all Board → Hand Displacements target the Active Player’s Hand.

PMN does not encode which Hand receives captured Pieces because this is deterministic at the Protocol level: the Active Player (the one performing the Move) always receives captured Pieces in their Hand.

This applies to:

11.4. Drop origin

Drops ([piece]*dst, [piece].dst) originate from the Active Player’s Hand.

Since only the Active Player can perform a Move, drops naturally come from that Player’s Hand. The Rule System defines which Pieces in the Hand may be dropped and under what conditions.

11.5. Invariant preservation

The Action ordering in multi-Action forms (Movement with Capture and Drop with Capture) ensures that:

This ordering is consistent with the sequential Action application defined by the Game Protocol. Each Action in a PMN direct effect is applied against the state produced by all preceding Actions, ensuring that intermediate states remain valid throughout the Move.

11.6. Action composition

PMN supports all valid Action compositions defined by the Game Protocol:

Action type PMN encoding Example
Displacement only Movement without transformation e2-e4
Mutation only In-place Mutation e4=+P
Displacement + Mutation Movement with actor transformation e7-e8=Q

12. Examples summary

12.1. Movement examples

PMN Description Actions
e2-e4 Simple Move (actor unchanged — no suffix) 1
e7-e8=Q Move with Promotion (Pawn → Queen — actor mutates) 1
d1+f3 Capture (captured Piece unchanged — no suffix) 2
d4+e5/S Capture: promoted piece reverts on capture (+S → S — piece mutates) 2
d4+e5/s Capture: piece changes side (S → s — piece mutates) 2
b7+a8=Q/r Capture with both transformations 2
e1~g1 Castling (actor unchanged, rook move is implicit — no suffix) ≥ 1
e5~f6/p En passant: captured Ōgi Pawn changes side (piece mutates — suffix present) ≥ 1

12.2. Drop examples

PMN Description Actions
P*e5 Drop pawn (actor unchanged — no suffix) 1
*d4 Contextual Drop (actor unchanged — no suffix) 1
S*c3=+S Drop with actor Mutation (Pawn → promoted Pawn) 1
L.b4 Drop with Capture (captured Piece unchanged) 2

12.3. Other examples

PMN Description Actions
+d4 Static Capture (captured Piece unchanged — no suffix) 1
+d4/p Static Capture with Mutation (piece changes side or state) 1
e4=+P In-place Mutation 1
... Pass Move 0

13. Examples

See PMN Examples for comprehensive usage patterns across different Game types and Rule Systems.

14. Reference implementations

The following reference libraries are maintained by Sashité and are intended to be idiomatic, fully tested, and spec-accurate implementations of PMN.

They generally provide:

If a library behavior appears to conflict with this document, this specification is normative. Please report issues (or propose clarifications) on the relevant repository.

15. License

This specification is made available under the terms of the Open Web Foundation Agreement 1.0 (OWFa 1.0).

The authoritative legal text is the OWF “Final Specification Agreement (OWFa 1.0)”.