---
title: "Get started"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{chess}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  eval = identical(Sys.getenv("CHESS_TEST", unset = "0"), "1")
)
```

Making moves with `{chess}` is easier than it looks. It has a PGN-like syntax
that facilitates interaction and translation, so using the package should not
be a problem if you have ever seen moves written down in a chess book.

If you haven't, [PGN](https://en.wikipedia.org/wiki/Portable_Game_Notation)
means Portable Game Notation and is "a standard plain text format for recording
chess games (both the moves and related data), which can be read by humans and
is also supported by most chess software."

Here you can see the beginning of a game between Fischer and Sherwin, played in
1957 at the New Jersey Open Championship. Each move is recorded in
[SAN](https://en.wikipedia.org/wiki/Algebraic_chess_notation) and numbers
followed by periods indicate the turn for each pair of half-moves. A number
followed by three periods indicates the second half of the turn, or the move
made by Black. Finally, parentheses indicate variations (not to be confused
with [variants](https://en.wikipedia.org/wiki/Chess_variants)) which are
"commentaries" made by the annotator, showcasing one or more alternatives for a
move and how the game could have been.

```
1. e4 c5 2. Nf3 e6 3. d3 Nc6 4. g3 Nf6 ( 4... d5 5. Nbd2 Bd6 6. Bg2 Nge7 7. O-O
O-O 8. Nh4 ) 5. Bg2 Be7 6. O-O O-O ( 6... d5 ) 7. Nbd2
```

If you think about it as a tree, this is what it would look like (rotated 90°):

```
                                                                ,->  d5
                                                                |
e4-> c5-> Nf3-> e6-> d3-> Nc6-> g3-> Nf6-> Bg2->  Be7-> O-O-> O-O->  Nbd2
                                 |
                                 `-> d5->  Nbd2-> Bd6-> Bg2-> Nge7-> O-O-> O-O-> Nh4
```

In R, the only way we can create a data structure that allows for nested
substructures is with `list()`s. If each move was a string and each parenthesis
(branch of the tree) was a `list()`, we would have something like this:

```r
"e4", "c5", "Nf3", "e6", "d3", "Nc6", "g3", "Nf6", list("d5", "Nbd2", "Bd6", "Bg2",
"Nge7", "O-O", "O-O", "Nh4"), "Bg2", "Be7", "O-O", "O-O", list("d5"), "Nbd2"
```

Now we can pass this on to `move()` and create a faithful reproduction to
Fisher's annotations in `{chess}`, and, since the function is very flexible, you
can also break down the tree into multiple moves:

```{r}
library(chess)

# Add moves to a new game
fischer_sherwin <- game() %>%
  move(
    "e4", "c5", "Nf3", "e6", "d3", "Nc6", "g3", "Nf6", list("d5", "Nbd2", "Bd6", "Bg2",
    "Nge7", "O-O", "O-O", "Nh4"), "Bg2", "Be7", "O-O", "O-O", list("d5"), "Nbd2"
  )

# See the last move from the mainline
fischer_sherwin

# Mainline and variations added separately
fischer_sherwin <- game() %>%
  move("e4", "c5", "Nf3", "e6", "d3", "Nc6", "g3", "Nf6") %>%
  move(list("d5", "Nbd2", "Bd6", "Bg2", "Nge7", "O-O", "O-O", "Nh4")) %>%
  move("Bg2", "Be7", "O-O", "O-O") %>%
  move(list("d5")) %>%
  move("Nbd2")

# The same as above
fischer_sherwin
```

With the game fully prepared, we can start to move up and down the tree,
exploring each element of the game as well as its variations. `forward()` and
`back()` advance and go back through the game, while `variations()` and
`variation()` make seeing and entering variations possible.

```{r}
# Get the start of the game
start <- root(fischer_sherwin)

# Checkout the first move
start %>%
  forward()

# Checkout the seventh move
start %>%
  forward(7)

# See possibilities for eighth move
start %>%
  forward(7) %>%
  variations()

# Checkout the first move of variation
start %>%
  forward(7) %>%
  variation(2)

# Variation 1 is always the "trunk"
start %>%
  forward(7) %>%
  variation(1)

# Checkout second move of variation
start %>%
  forward(7) %>%
  variation(2) %>%
  forward()

# Checkout second to last move
fischer_sherwin %>%
  back()

# Checkout other possibilities for that
fischer_sherwin %>%
  back(2) %>%
  variations()
```
