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, Board, Displacement, Hand, Location, Move, Mutation, Pass Move, Piece, Position, Square) are defined in the Glossary and the Game Protocol. 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 Game Protocol).

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/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 Optional
Capture transformation (/<captured>) Mutation of the captured Piece Optional

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.

8. Direct effect decomposition (normative)

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

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.

Constraints:

8.3. Movement with capture (src+dst)

Syntax:

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

Direct effect (minimal Action sequence):

  1. Capture Action: Board(<destination>) → Hand(rule-defined)

    • If /<captured> is present, apply the captured-piece Mutation as part of this Action.

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

    • If =<actor> is present, apply the Actor Mutation as part of this Action.

This ordering is chosen so that the intermediate state (between Actions 1 and 2) can remain occupancy-safe under a typical representation.

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.

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. If no capture occurs, the capture transformation has no effect.

Constraints:

8.5. Static capture (+square)

Syntax:

+<square>[/<captured>]

Direct effect (minimal Action sequence):

  1. Capture Action: Board(<square>) → Hand(rule-defined)

    • If /<captured> is present, apply the captured-piece Mutation as part of this Action.

Constraints:

8.6. Drop to empty Square (*)

Syntax:

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

Direct effect (minimal Action sequence):

  1. Actor Action: Hand(rule-defined) → Board(<destination>)

    • If <piece> is present, it identifies the dropped Piece.
    • If =<actor> is present, apply the Actor Mutation as part of this Action.

Constraints:

8.7. Drop with capture (.)

Syntax:

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

Direct effect (minimal Action sequence):

  1. Capture Action: Board(<destination>) → Hand(rule-defined)

    • If /<captured> is present, apply the captured-piece Mutation as part of this Action.

  2. Actor Action: Hand(rule-defined) → Board(<destination>)

    • If <piece> is present, it identifies the dropped Piece.
    • If =<actor> is present, apply the Actor Mutation as part of this Action.

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

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 *)

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 in §9.1.
  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 guidelines (informative)

PMN does not enforce semantic correctness. Implementations SHOULD consider:

  1. Movement sanity: Source and destination SHOULD differ.
  2. Transformation relevance: Transformations SHOULD change at least one attribute.
  3. Capture context: Capture transformations SHOULD only appear with capture-capable forms (src+dst, +square, src~dst, [piece].dst).
  4. Context completeness: Omitted <piece> in drops requires unambiguous context.

11. Protocol alignment

11.1. Mapping to Game Protocol concepts

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

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 → 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 → Hand Action (captured)
[<piece>]*dst[=<actor>] Direct effect includes one Hand → Board Action (Actor)
[<piece>].dst[=<actor>][/<captured>] Direct effect includes one Board → Hand Action (captured) + one 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. Invariant preservation

The Action ordering in multi-Action forms (§8.3, §8.7) ensures that:

12. Examples summary

12.1. Movement examples

PMN Description Actions
e2-e4 Simple move 1
e7-e8=Q Move with promotion 1
d1+f3 Capture 2
b7+a8=Q/r Capture with both transformations 2
e1~g1 Castling (rook move implicit) ≥ 1
e5~f6/p En passant (capture implicit) with capture mutation ≥ 1

12.2. Drop examples

PMN Description Actions
P*e5 Drop pawn 1
*d4 Contextual drop 1
S*c3=+S Drop with actor mutation 1
L.b4 Drop with capture 2

12.3. Other examples

PMN Description Actions
+d4 Static capture 1
+d4/p Static capture with captured mutation 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)”.