STN Examples

State Transition Notation (STN) v1.0.0
Author: Sashité
License: MIT License

Overview

This document provides comprehensive examples of STN (State Transition Notation) usage across various game types and transition scenarios. These examples illustrate practical applications of the STN specification while remaining rule-agnostic.

Note: All examples are for illustration purposes only. STN does not define or assume any game-specific rules, movement patterns, or win conditions.

Basic Examples

No Changes

{}

Interpretation:

No board positions change
No hand/reserve contents change
Active player remains the same (due to default toggle: false)

This represents scenarios such as position comparisons yielding identical results, null transformations, or baseline states.

Pass Move (Turn-Only Change)

{
  "toggle": true
}

Interpretation:

No board positions change
No hand/reserve contents change
Active player changes (explicit toggle: true)

This represents pass moves, forfeit turns, or any transition where only the turn changes.

Simple Movement (No Turn Change)

{
  "board": {
    "e2": null,
    "e4": "C:P"
  }
}

Interpretation:

Position e2 becomes empty
Position e4 now contains a white chess pawn
Same player remains active (implicit toggle: false)

Simple Movement (With Turn Change)

{
  "board": {
    "e2": null,
    "e4": "C:P"
  },
  "toggle": true
}

Interpretation:

Position e2 becomes empty
Position e4 now contains a white chess pawn
Turn passes to opponent (explicit toggle: true)

Hand/Reserve Examples

Drop from Reserve (No Turn Change)

{
  "board": {
    "e5": "S:P"
  },
  "hands": {
    "S:P": -1
  }
}

Interpretation:

Position e5 now contains a sente shogi pawn
One sente pawn removed from hand/reserve
Same player remains active

Drop from Reserve (With Turn Change)

{
  "board": {
    "e5": "S:P"
  },
  "hands": {
    "S:P": -1
  },
  "toggle": true
}

Interpretation:

Position e5 now contains a sente shogi pawn
One sente pawn removed from hand/reserve
Turn passes to opponent

Capture to Reserve

{
  "board": {
    "b1": "S:S",
    "c2": null
  },
  "hands": {
    "S:B": 1
  },
  "toggle": true
}

Interpretation:

Position b1 now contains a sente silver
Position c2 becomes empty
One sente bishop added to hand/reserve (captured piece)
Turn passes to opponent

Complex Movement Examples

Castling

{
  "board": {
    "e1": null,
    "g1": "C:K",
    "h1": null,
    "f1": "C:R"
  },
  "toggle": true
}

Interpretation:

King moves from e1 to g1
Rook moves from h1 to f1
Turn passes to opponent

En Passant

{
  "board": {
    "e5": null,
    "f6": "C:P",
    "f5": null
  },
  "hands": {
    "c:p": 1
  },
  "toggle": true
}

Interpretation:

White pawn moves from e5 to f6
Black pawn at f5 disappears (captured en passant)
One black pawn added to white’s reserve
Turn passes to opponent

Promotion with Capture

{
  "board": {
    "e7": null,
    "e8": "C:Q"
  },
  "hands": {
    "c:r": 1
  },
  "toggle": true
}

Interpretation:

Pawn moves from e7 to e8 and promotes to queen
Black rook at e8 was captured
One black rook added to white’s reserve
Turn passes to opponent

Multi-Dimensional Examples

3D Movement

{
  "board": {
    "e2A": null,
    "f3B": "R:B"
  },
  "toggle": true
}

Interpretation:

Piece moves from 3D coordinate e2A to f3B
Final piece is identified as R:B
Turn passes to opponent

Turn Management Examples

Multiple Moves (Same Player Active)

{
  "board": {
    "e2": null,
    "e4": "C:P",
    "e7": null,
    "e5": "c:p"
  }
}

Interpretation:

Net result of multiple moves: both e2→e4 and e7→e5
Original active player is still active (implicit toggle: false)
Represents cumulative state difference over multiple turns

Multiple Moves (Different Player Active)

{
  "board": {
    "e2": null,
    "e4": "C:P",
    "e7": null,
    "e5": "c:p",
    "f1": null,
    "d3": "C:B"
  },
  "toggle": true
}

Interpretation:

Net result of multiple moves including bishop movement
After all moves, opponent is now active (explicit toggle: true)
Represents odd number of moves or special turn logic

Complex Scenarios

Piece Exchange (No Turn Change)

{
  "board": {
    "a1": "S:S",
    "b2": "S:L",
    "c3": null
  },
  "hands": {
    "s:g": 1,
    "S:G": -1
  }
}

Interpretation:

Multiple pieces have moved on the board
Hand composition changed (captured vs dropped pieces)
Same player remains active (useful for multi-step sequences)

Multi-Location Drop Pattern

{
  "board": {
    "e5": "S:P",
    "f5": "S:P",
    "g5": "S:P"
  },
  "hands": {
    "S:P": -3
  },
  "toggle": true
}

Interpretation:

Three positions now contain sente pawns
Three sente pawns removed from hand
Turn passes to opponent
Could represent rapid successive drops or pattern setup

State Transition Patterns

Incremental Position Building

Step 1 - Initial move:

{
  "board": {
    "e2": null,
    "e4": "C:P"
  },
  "toggle": true
}

Step 2 - Response move:

{
  "board": {
    "e7": null,
    "e5": "c:p"
  },
  "toggle": true
}

Cumulative result (from initial position):

{
  "board": {
    "e2": null,
    "e4": "C:P",
    "e7": null,
    "e5": "c:p"
  }
}

Position Comparison

Position A: Standard opening Position B: After player development

STN diff (A → B):

{
  "board": {
    "e2": null,
    "e4": "C:P",
    "g1": null,
    "f3": "C:N",
    "f1": null,
    "c4": "C:B"
  }
}

This shows the net development without indicating turn sequence.

Integration with FEEN

Standard Chess Example

Given the initial Western Chess position:

+rnbq+kbn+r/+p+p+p+p+p+p+p+p/8/8/8/8/+P+P+P+P+P+P+P+P/+RNBQ+KBN+R / C/c

After the first move (e2-e4):

+rnbq+kbn+r/+p+p+p+p+p+p+p+p/8/8/4P3/8/+P+P+P+P1+P+P+P/+RNBQ+KBN+R / c/C

STN representation:

{
  "board": {
    "e2": null,
    "e4": "C:P"
  },
  "toggle": true
}

After the second move (e7-e5):

+rnbq+kbn+r/+p+p+p+p1+p+p+p/8/4p3/4P3/8/+P+P+P+P1+P+P+P/+RNBQ+KBN+R / C/c

STN representation (cumulative from initial):

{
  "board": {
    "e2": null,
    "e4": "C:P",
    "e7": null,
    "e5": "c:p"
  }
}

Note: toggle: false (default) because after two moves, we’re back to the original active player.

Shogi Drop Example

Before drop:

+l+n+s+g+k+g+s+n+l/1+r5+b1/+p+p+p+p+p+p+p+p+p/9/9/9/PPPPPPPPP/1B5R1/LNSGKGSNL / S/s

After pawn drop to 5e:

+l+n+s+g+k+g+s+n+l/1+r5+b1/+p+p+p+p+p+p+p+p+p/9/4P4/9/PPPP1PPPP/1B5R1/LNSGKGSNL / s/S

STN representation:

{
  "board": {
    "e5": "S:P"
  },
  "hands": {
    "S:P": -1
  },
  "toggle": true
}

Understanding STN Semantics

What STN Represents

Net changes between two complete positions
Final states of changed locations
Delta quantities in hand/reserve counts
Active player after transition (explicit toggle control)

What STN Does NOT Represent

How the changes occurred
Order of actions or moves
Intermediate positions during transition
Legality or validation of transitions

Toggle Semantics

Default behavior: toggle: false (same player remains active)
Explicit turn change: toggle: true (player changes)
Empty object: {} means genuinely no changes (including turn)
Pass move: {"toggle": true} means only turn changes

Best Practices

When to Use STN

Position comparison:

// Calculate difference between two positions
const stn = diffPositions(positionA, positionB);

Move validation:

// Check if proposed change is valid
if (isValidTransition(currentPosition, proposedSTN)) {
  applySTN(currentPosition, proposedSTN);
}

Undo/redo systems:

// Store reversible changes
const undoSTN = invertSTN(forwardSTN);
historyStack.push(undoSTN);

Network synchronization:

// Send only what changed
sendToClients(stnDelta);

Optimization Patterns

Minimal representation: Only include changed locations/pieces

// Good - only changed elements
{
  "board": { "e2": null, "e4": "C:P" },
  "toggle": true
}

// Avoid - unnecessary elements
{
  "board": { "e2": null, "e4": "C:P", "a1": "C:R" },
  "toggle": true
}

Batch changes: Combine related modifications

// Efficient - combined castling
{
  "board": {
    "e1": null, "g1": "C:K",
    "h1": null, "f1": "C:R"
  },
  "toggle": true
}

Toggle optimization: Use default behavior when possible

// Good - implicit toggle: false
{
  "board": { "e2": null, "e4": "C:P" }
}

// Unnecessary - explicit false
{
  "board": { "e2": null, "e4": "C:P" },
  "toggle": false
}

Common Pitfalls

Forgetting explicit toggle: Remember pass moves need toggle: true

// Wrong - this means no changes at all
{}

// Correct - pass move
{"toggle": true}

Zero hand deltas: Hand values must be non-zero

// Wrong
{
  "hands": { "S:P": 0 }
}

// Correct - omit unchanged hands
{}

Incomplete position tracking: Ensure all aspects are captured

// Consider all position components:
// - Board state
// - Hand/reserve contents
// - Active player status

Invalid QPI consistency: Use consistent piece identification

// Ensure QPI format compliance
{
  "board": { "e4": "C:P" },  // Valid QPI
  "hands": { "c:p": 1 }      // Consistent case
}