State Transition Notation (STN) Specification

Version: 1.0.0
Author: Sashité
Published: June 13, 2025
License: MIT License

Overview

State Transition Notation (STN) is a rule-agnostic, JSON-based format for describing state transitions in abstract strategy board games. STN captures the net changes between any two game positions by recording modifications in piece positions and hand/reserve contents using standardized CELL coordinates and QPI piece identification.

STN provides a concise way to represent position deltas without requiring knowledge of how those transitions were achieved. In other words, STN is purely a difference format - it does not track piece movements, action sequences, or the mechanics that produced the changes. While certain STN modifications may suggest specific moves, such interpretations are not guaranteed and fall outside this specification’s scope.

Terminology

For complete definitions of terms used in this document, see the Glossary.

Dependencies

STN builds upon two foundational Sashité specifications:

CELL: Multi-dimensional coordinate encoding for board positions
QPI: Qualified Piece Identifier for unambiguous piece identification

JSON Structure

{
  "board": {
    "<cell-coordinate>": "<qpi-piece | null>"
  },
  "hands": {
    "<qpi-piece>": <delta>
  },
  "toggle": <boolean>
}

All fields are optional. An empty object {} represents no changes between positions.

`board` field

Maps CELL coordinates to their final state after the transition:

Key: CELL coordinate (conforming to CELL specification)
Value: QPI piece identifier (string) or null (empty location)

`hands` field

Maps QPI piece identifiers to net count changes in reserves:

Key: QPI piece identifier (conforming to QPI specification)
Value: Non-zero integer delta (positive = added, negative = removed)

`toggle` field

Indicates whether the transition toggles the active player:

Type: Boolean
Default: true (toggle active player)
true: The active player changes to the opponent after applying the transition
false: The active player remains the same after applying the transition

When the toggle field is omitted from an STN record, it defaults to true, meaning the active player will change to the opponent after applying the transition. This reflects the standard behavior where most game transitions represent a player’s move followed by the turn passing to the opponent.

Example: In a chess game with C (white) vs c (black):

If C is currently active and toggle: true (or omitted), then c becomes the active player
If C is currently active and toggle: false, then C remains the active player

Common usage:

toggle: true or omitted - Normal move where turn passes to opponent (default behavior)
toggle: false - Cumulative changes over multiple moves, or special cases where turn doesn’t change

Relationship with Other Specifications

Specification	Relationship to STN
CELL	Core dependency: Provides coordinate format for board locations
QPI	Core dependency: Provides piece identification format
HAND	Conceptual alignment: STN hands field represents reserve deltas
FEEN	Source/target: STN describes transitions between FEEN positions
PMN	Result representation: STN captures net effect of PMN actions

STN serves as the position delta layer, providing efficient change representation using standardized coordinate and piece notation systems.

JSON Schema

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

Examples

See STN Examples for practical implementation guidance.

Reference Implementations

Ruby

STN.rb – Complete STN support with CELL coordinate validation, QPI piece parsing, and FEEN integration.