Variations (PCN v1.0.0)

This page demonstrates variations — alternative move sequences that branch from the main line for analysis, study, or annotation purposes.

All examples are shown in both TOML and JSON formats.

Quick Reference

Variation Structure

Each ply can have a variations property containing alternative continuations. Each variation is a wrapper object with optional line-level metadata and a required plies sequence:

ply
├── pmn (main line move)
├── comment
└── variations[] (alternative lines)
    ├── [0] (first alternative)
    │   ├── name     — short label for the line (optional)
    │   ├── comment  — annotation on the line as a whole (optional)
    │   └── plies[]  — sequence of moves forming this line (required)
    └── [1] (second alternative)
        ├── name
        ├── comment
        └── plies[]

The two annotation levels are distinct:

Line-level (name, comment on the variation object) — describes the alternative as a whole.
Ply-level (assessment, check, comment on each entry in plies) — describes individual moves within the line.

Use Cases

Use Case	Description
Opening analysis	Compare different opening responses
Critical moments	Show what-if scenarios at key positions
Annotated games	Explain alternative possibilities
Training	Present puzzles with multiple solutions

1. Simple Variation — One Alternative

A single alternative line at move 5.

TOML

[meta]
name = "Italian vs Two Knights"

[setup]
feen = "-rnbqk^bn-r/+p+p+p+p+p+p+p+p/8/8/8/8/+P+P+P+P+P+P+P+P/-RNBQK^BN-R / C/c"

[[plies]]
pmn = "e2-e4"

[[plies]]
pmn = "e7-e5"

[[plies]]
pmn = "g1-f3"

[[plies]]
pmn = "b8-c6"

[[plies]]
pmn = "f1-c4"
comment = "Italian Game"

  [[plies.variations]]
  name = "Two Knights Defense"

    [[plies.variations.plies]]
    pmn = "g8-f6"
    comment = "The Two Knights alternative"

    [[plies.variations.plies]]
    pmn = "d2-d3"

[[plies]]
pmn = "f8-c5"
comment = "Giuoco Piano"

JSON

{
  "meta": {
    "name": "Italian vs Two Knights"
  },
  "setup": {
    "feen": "-rnbqk^bn-r/+p+p+p+p+p+p+p+p/8/8/8/8/+P+P+P+P+P+P+P+P/-RNBQK^BN-R / C/c"
  },
  "plies": [
    { "pmn": "e2-e4" },
    { "pmn": "e7-e5" },
    { "pmn": "g1-f3" },
    { "pmn": "b8-c6" },
    {
      "pmn": "f1-c4",
      "comment": "Italian Game",
      "variations": [
        {
          "name": "Two Knights Defense",
          "plies": [
            { "pmn": "g8-f6", "comment": "The Two Knights alternative" },
            { "pmn": "d2-d3" }
          ]
        }
      ]
    },
    { "pmn": "f8-c5", "comment": "Giuoco Piano" }
  ]
}

2. Multiple Variations — Several Alternatives

Multiple alternative lines from the same position.

TOML

[meta]
name = "Sicilian Defense Choices"

[setup]
feen = "-rnbqk^bn-r/+p+p+p+p+p+p+p+p/8/8/8/8/+P+P+P+P+P+P+P+P/-RNBQK^BN-R / C/c"

[[plies]]
pmn = "e2-e4"

[[plies]]
pmn = "c7-c5"
comment = "Sicilian Defense - multiple White responses"

  [[plies.variations]]
  name = "Closed Sicilian"

    [[plies.variations.plies]]
    pmn = "b1-c3"

    [[plies.variations.plies]]
    pmn = "b8-c6"

  [[plies.variations]]
  name = "Alapin Variation"

    [[plies.variations.plies]]
    pmn = "c2-c3"

    [[plies.variations.plies]]
    pmn = "d7-d5"

  [[plies.variations]]
  name = "Smith-Morra Gambit"

    [[plies.variations.plies]]
    pmn = "d2-d4"

    [[plies.variations.plies]]
    pmn = "c5+d4"

    [[plies.variations.plies]]
    pmn = "c2-c3"

[[plies]]
pmn = "g1-f3"
comment = "Main line: Open Sicilian"

JSON

{
  "meta": {
    "name": "Sicilian Defense Choices"
  },
  "setup": {
    "feen": "-rnbqk^bn-r/+p+p+p+p+p+p+p+p/8/8/8/8/+P+P+P+P+P+P+P+P/-RNBQK^BN-R / C/c"
  },
  "plies": [
    { "pmn": "e2-e4" },
    {
      "pmn": "c7-c5",
      "comment": "Sicilian Defense - multiple White responses",
      "variations": [
        {
          "name": "Closed Sicilian",
          "plies": [
            { "pmn": "b1-c3" },
            { "pmn": "b8-c6" }
          ]
        },
        {
          "name": "Alapin Variation",
          "plies": [
            { "pmn": "c2-c3" },
            { "pmn": "d7-d5" }
          ]
        },
        {
          "name": "Smith-Morra Gambit",
          "plies": [
            { "pmn": "d2-d4" },
            { "pmn": "c5+d4" },
            { "pmn": "c2-c3" }
          ]
        }
      ]
    },
    { "pmn": "g1-f3", "comment": "Main line: Open Sicilian" }
  ]
}

3. Nested Variations — Variations Within Variations

Deeply nested alternative lines.

TOML

[meta]
name = "Deep Analysis"

[setup]
feen = "-rnbqk^bn-r/+p+p+p+p+p+p+p+p/8/8/8/8/+P+P+P+P+P+P+P+P/-RNBQK^BN-R / C/c"

[[plies]]
pmn = "e2-e4"

[[plies]]
pmn = "e7-e5"

[[plies]]
pmn = "g1-f3"

[[plies]]
pmn = "b8-c6"

[[plies]]
pmn = "f1-b5"
comment = "Ruy Lopez"

  [[plies.variations]]
  name = "Italian Game"

    [[plies.variations.plies]]
    pmn = "f1-c4"

    [[plies.variations.plies]]
    pmn = "f8-c5"
    comment = "Giuoco Piano"

      [[plies.variations.plies.variations]]
      name = "Two Knights"

        [[plies.variations.plies.variations.plies]]
        pmn = "g8-f6"

        [[plies.variations.plies.variations.plies]]
        pmn = "g1-f3"

[[plies]]
pmn = "a7-a6"
comment = "Morphy Defense"

JSON

{
  "meta": {
    "name": "Deep Analysis"
  },
  "setup": {
    "feen": "-rnbqk^bn-r/+p+p+p+p+p+p+p+p/8/8/8/8/+P+P+P+P+P+P+P+P/-RNBQK^BN-R / C/c"
  },
  "plies": [
    { "pmn": "e2-e4" },
    { "pmn": "e7-e5" },
    { "pmn": "g1-f3" },
    { "pmn": "b8-c6" },
    {
      "pmn": "f1-b5",
      "comment": "Ruy Lopez",
      "variations": [
        {
          "name": "Italian Game",
          "plies": [
            { "pmn": "f1-c4" },
            {
              "pmn": "f8-c5",
              "comment": "Giuoco Piano",
              "variations": [
                {
                  "name": "Two Knights",
                  "plies": [
                    { "pmn": "g8-f6" },
                    { "pmn": "g1-f3" }
                  ]
                }
              ]
            }
          ]
        }
      ]
    },
    { "pmn": "a7-a6", "comment": "Morphy Defense" }
  ]
}

4. Annotated Variation — With Assessments

Variations with move quality annotations and line-level comments.

TOML

[meta]
name = "Critical Position Analysis"

[setup]
feen = "-r1bqk^b1-r/+p+p+p+p1+p+p+p/2n2n2/4p3/2B1P3/5N2/+P+P+P+P1+P+P+P/-RNBQK^2+R / C/c"

[[plies]]
pmn = "b8-c6"

[[plies]]
pmn = "d2-d3"
comment = "Solid continuation"

  [[plies.variations]]
  name = "Aggressive alternative"
  comment = "Sharper and more complex"

    [[plies.variations.plies]]
    pmn = "g1-f3"
    assessment = "good"
    comment = "Developing with tempo"

    [[plies.variations.plies]]
    pmn = "g8-f6"

    [[plies.variations.plies]]
    pmn = "f3-g5"
    assessment = "interesting"
    comment = "The Fried Liver Attack!"

      [[plies.variations.plies.variations]]
      name = "Declining"
      comment = "Safer option"

        [[plies.variations.plies.variations.plies]]
        pmn = "d7-d5"
        assessment = "good"

      [[plies.variations.plies.variations]]
      name = "Accepting (risky)"
      comment = "Wild complications"

        [[plies.variations.plies.variations.plies]]
        pmn = "f6+e4"
        assessment = "dubious"

JSON

{
  "meta": {
    "name": "Critical Position Analysis"
  },
  "setup": {
    "feen": "-r1bqk^b1-r/+p+p+p+p1+p+p+p/2n2n2/4p3/2B1P3/5N2/+P+P+P+P1+P+P+P/-RNBQK^2+R / C/c"
  },
  "plies": [
    { "pmn": "b8-c6" },
    {
      "pmn": "d2-d3",
      "comment": "Solid continuation",
      "variations": [
        {
          "name": "Aggressive alternative",
          "comment": "Sharper and more complex",
          "plies": [
            {
              "pmn": "g1-f3",
              "assessment": "good",
              "comment": "Developing with tempo"
            },
            { "pmn": "g8-f6" },
            {
              "pmn": "f3-g5",
              "assessment": "interesting",
              "comment": "The Fried Liver Attack!",
              "variations": [
                {
                  "name": "Declining",
                  "comment": "Safer option",
                  "plies": [
                    { "pmn": "d7-d5", "assessment": "good" }
                  ]
                },
                {
                  "name": "Accepting (risky)",
                  "comment": "Wild complications",
                  "plies": [
                    { "pmn": "f6+e4", "assessment": "dubious" }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

5. Puzzle with Solution Variations

A tactical puzzle showing correct and incorrect tries.

TOML

[meta]
name = "Mate in 2"
comment = "White to play and mate"

[setup]
feen = "2r3k^1/5+p+p+p/8/8/8/5Q2/5+P+P+P/6K^1 / C/c"

[[plies]]
pmn = "f3-f8"
check = true
comment = "Correct! Back rank threat"

  [[plies.variations]]
  name = "Wrong try"
  comment = "This allows Black to escape"

    [[plies.variations.plies]]
    pmn = "f3-a8"
    check = true
    assessment = "mistake"
    comment = "This allows escape"

    [[plies.variations.plies]]
    pmn = "c8-c1"
    check = true
    comment = "Black counterattacks"

[[plies]]
pmn = "c8+f8"
comment = "Forced"

[[plies]]
pmn = "..."
comment = "White mates with any move (placeholder)"

JSON

{
  "meta": {
    "name": "Mate in 2",
    "comment": "White to play and mate"
  },
  "setup": {
    "feen": "2r3k^1/5+p+p+p/8/8/8/5Q2/5+P+P+P/6K^1 / C/c"
  },
  "plies": [
    {
      "pmn": "f3-f8",
      "check": true,
      "comment": "Correct! Back rank threat",
      "variations": [
        {
          "name": "Wrong try",
          "comment": "This allows Black to escape",
          "plies": [
            {
              "pmn": "f3-a8",
              "check": true,
              "assessment": "mistake",
              "comment": "This allows escape"
            },
            {
              "pmn": "c8-c1",
              "check": true,
              "comment": "Black counterattacks"
            }
          ]
        }
      ]
    },
    { "pmn": "c8+f8", "comment": "Forced" },
    { "pmn": "...", "comment": "White mates with any move (placeholder)" }
  ]
}

6. Opening Repertoire — Multiple First Moves

Comparing different opening choices.

TOML

[meta]
name = "Opening Repertoire for White"

[setup]
feen = "-rnbqk^bn-r/+p+p+p+p+p+p+p+p/8/8/8/8/+P+P+P+P+P+P+P+P/-RNBQK^BN-R / C/c"

[[plies]]
pmn = "e2-e4"
comment = "Main choice: King's Pawn"

  [[plies.variations]]
  name = "Queen's Pawn"

    [[plies.variations.plies]]
    pmn = "d2-d4"

    [[plies.variations.plies]]
    pmn = "d7-d5"

    [[plies.variations.plies]]
    pmn = "c2-c4"
    comment = "Queen's Gambit"

  [[plies.variations]]
  name = "English Opening"

    [[plies.variations.plies]]
    pmn = "c2-c4"

    [[plies.variations.plies]]
    pmn = "e7-e5"

  [[plies.variations]]
  name = "Réti Opening"

    [[plies.variations.plies]]
    pmn = "g1-f3"

    [[plies.variations.plies]]
    pmn = "d7-d5"

    [[plies.variations.plies]]
    pmn = "c2-c4"

[[plies]]
pmn = "e7-e5"

JSON

{
  "meta": {
    "name": "Opening Repertoire for White"
  },
  "setup": {
    "feen": "-rnbqk^bn-r/+p+p+p+p+p+p+p+p/8/8/8/8/+P+P+P+P+P+P+P+P/-RNBQK^BN-R / C/c"
  },
  "plies": [
    {
      "pmn": "e2-e4",
      "comment": "Main choice: King's Pawn",
      "variations": [
        {
          "name": "Queen's Pawn",
          "plies": [
            { "pmn": "d2-d4" },
            { "pmn": "d7-d5" },
            { "pmn": "c2-c4", "comment": "Queen's Gambit" }
          ]
        },
        {
          "name": "English Opening",
          "plies": [
            { "pmn": "c2-c4" },
            { "pmn": "e7-e5" }
          ]
        },
        {
          "name": "Réti Opening",
          "plies": [
            { "pmn": "g1-f3" },
            { "pmn": "d7-d5" },
            { "pmn": "c2-c4" }
          ]
        }
      ]
    },
    { "pmn": "e7-e5" }
  ]
}

7. Shōgi Variations — With Drops

Variations in a shōgi game showing different drop strategies.

TOML

[meta]
name = "Shōgi Drop Analysis"

[sides.first]
variant = "Shogi"

[sides.second]
variant = "Shogi"

[setup]
feen = "lnsgk^gsnl/1r5b1/ppppppppp/9/9/9/PPPPPPPPP/1B5R1/LNSGK^GSNL P/ S/s"

[[plies]]
pmn = "7g-7f"

[[plies]]
pmn = "8c-8d"

[[plies]]
pmn = "P*8e"
comment = "Aggressive pawn drop"

  [[plies.variations]]
  name = "Positional approach"
  comment = "Develops without using the pawn in hand"

    [[plies.variations.plies]]
    pmn = "2g-2f"
    comment = "Advances the rook pawn instead"

    [[plies.variations.plies]]
    pmn = "3c-3d"

    [[plies.variations.plies]]
    pmn = "P*5e"
    comment = "Central drop later"

JSON

{
  "meta": {
    "name": "Shōgi Drop Analysis"
  },
  "sides": {
    "first": { "variant": "Shogi" },
    "second": { "variant": "Shogi" }
  },
  "setup": {
    "feen": "lnsgk^gsnl/1r5b1/ppppppppp/9/9/9/PPPPPPPPP/1B5R1/LNSGK^GSNL P/ S/s"
  },
  "plies": [
    { "pmn": "7g-7f" },
    { "pmn": "8c-8d" },
    {
      "pmn": "P*8e",
      "comment": "Aggressive pawn drop",
      "variations": [
        {
          "name": "Positional approach",
          "comment": "Develops without using the pawn in hand",
          "plies": [
            { "pmn": "2g-2f", "comment": "Advances the rook pawn instead" },
            { "pmn": "3c-3d" },
            { "pmn": "P*5e", "comment": "Central drop later" }
          ]
        }
      ]
    }
  ]
}

Variation Structure

Variation Object Properties

Property	Type	Required	Description
`name`	string	No	Short label for the line (e.g., `"Ruy Lopez"`, `"Berlin Defense"`)
`comment`	string	No	Commentary on the line as a whole
`plies`	array	Yes	Sequence of plies forming this alternative line

The comment on a variation object describes the line — it is distinct from comment on individual plies inside plies, which describes specific moves.

Ply Properties in Variations

Plies within variations support all standard ply properties:

Property	Description
`pmn`	The move in PMN format
`feen`	Resulting position after this ply
`elapsed_ms`	Thinking time in milliseconds
`assessment`	Move quality (`"good"`, `"mistake"`, `"brilliant"`, `"blunder"`, `"interesting"`, `"dubious"`)
`check`	Whether this move delivers check
`mate`	Whether this move delivers checkmate
`comment`	Free-text annotation on this specific move
`variations`	Nested variations — recursive, supports arbitrary depth

Variations (PCN v1.0.0)

Quick Reference

Variation Structure

Use Cases

1. Simple Variation — One Alternative

TOML

JSON

2. Multiple Variations — Several Alternatives

TOML

JSON

3. Nested Variations — Variations Within Variations

TOML

JSON

4. Annotated Variation — With Assessments

TOML

JSON

5. Puzzle with Solution Variations

TOML

JSON

6. Opening Repertoire — Multiple First Moves

TOML

JSON

7. Shōgi Variations — With Drops

TOML

JSON

Variation Structure

Variation Object Properties

Ply Properties in Variations

See Also