---
title: "Effect commands"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Effect commands}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

## What are effect commands {#what}

A pattern table is composed of cells telling the tracker which notes to play
in which order. It also has a field for effect commands. It is often represented
as a three digit hexadecimal value. The first hex digit represents the effect
command, the latter represent parameter values used by the command. The
table below (based on `data(effect_commands)`) summarises all available effects
in ProTracker.

More details on the tracker pattern structure can be found in `vignette("s3class")`.
Some examples of the effects that can be applied are [provided below](#examples).
Note that this vignette does not intend to be a complete tutorial. It merely
addresses how you can manipulate ProTracker modules programmatically in R.
For more in depth information please check the [references](#references).

```{r tab-effect-commands, echo=FALSE, message=FALSE, warning=FALSE}
library(ProTrackR2)
library(kableExtra)
data(effect_commands)
effect_commands |> kbl()
```

## Extracting and updating effect commands {#updating}

To get an effect command from a ProTracker module, you can simply call
`pt2_command()` to a `pt2cell` or `pt2celllist` class object (see `vignette("s3class")` for
a ProTrackR2 object tree). There, are several ways of extracting cells as
documented in `vignette("sel_assign")`. In the example below there is one way shown
of getting the effect commands of the first 8 rows of the second column in
the third pattern.

```{r select-command}
## load the demo-mod included with the package
mod <- pt2_read_mod(pt2_demo())

pt2_command(
  mod$patterns[[ 3 ]] [ 1:8, 2 ])
```

You can also assign new effect commands to your selection like this:

```{r assign-command}
pt2_command(
  mod$patterns[[ 3 ]] [ 1:8, 2 ]) <- "C10"
```

## Examples of some common effects {#examples}

Using the description in the
[table above](#what),
and the assignment procedure
[explained above](#updating), some examples are implemented below:

```{r command-examples}

## create a new mod te demonstrate commands
mod_command <- pt2_new_mod("commands")
## copy the samples from the mod above
mod_command$samples <- mod$samples

if (interactive()) {
  mod_command$patterns[[1]][1,1] <- "C-3 01 000"
  ## Reduce sample volume
  pt2_command(mod_command$patterns[[1]][,1]) <- "C10"
  play(mod_command)
  
  mod_command$patterns[[1]][1,1] <- "C-3 03 000"
  ## Simulate major chord:
  pt2_command(mod_command$patterns[[1]][,1]) <- "047"
  play(mod_command)
  
  ## Simulate minor chord
  pt2_command(mod_command$patterns[[1]][,1]) <- "037"
  play(mod_command)

  ## Porta up:
  pt2_command(mod_command$patterns[[1]][,1]) <- "101"
  play(mod_command)

  ## Porta down:
  pt2_command(mod_command$patterns[[1]][,1]) <- "201"
  play(mod_command)
  
  ## Porta to note:
  mod_command$patterns[[1]][1,1] <- "C-3 03 000"
  mod_command$patterns[[1]][2:64,1] <- "E-3 03 000"
  pt2_command(mod_command$patterns[[1]][2:64,1]) <- "301"
  play(mod_command)
  
  mod_command$patterns[[1]] <- pt2_new_pattern() # reset pattern
  mod_command$patterns[[1]][1,1] <- "C-3 03 000"
  ## Vibrato:
  pt2_command(mod_command$patterns[[1]][,1]) <- "464"
  play(mod_command)
  
  ## Tremolo:
  pt2_command(mod_command$patterns[[1]][,1]) <- "743"
  play(mod_command)

  ## Fade out:
  pt2_command(mod_command$patterns[[1]][,1]) <- "A01"
  play(mod_command)

  mod_command$patterns[[1]][1,1] <- "C-3 03 C00"
  ## Fade in:
  pt2_command(mod_command$patterns[[1]][2:63,1]) <- "A10"
  play(mod_command)
}

```

## Effect of instrument number on effects

The cells in a ProTracker pattern also hold information on the instrument
number. The function `pt2_instrument()` can be used to get or set an instrument
number. The reason for mentioning it here is that setting (or omitting) the
instrument number can affect how a `pt2_command()` is interpreted.

By setting the instrument number in combination with an effect command, can
cause the player to reset the sample's previous state. I'm not going
to show all features as there are many. But just as an example see what happens
when you apply a volume slide in combination with setting the instrument number.
The volume is reset each row of the pattern:

```{r effect-instrument}
mod$patterns[[1]] <- pt2_new_pattern()
mod$patterns[[1]][1,1] <- "C-3 03 000"
## Slide the volume down in the entire track:
pt2_command(mod$patterns[[1]][,1]) <- "A08"
## Reset the volume each row by setting the sample
## number for the entire track
pt2_instrument(mod$patterns[[1]][,1]) <- 3L
if (interactive()) {
  play(mod)
}

```

## References

 * [YouTube tutorial](https://www.youtube.com/playlist?list=PLVoRT-Mqwas9gvmCRtOusCQSKNQNf6lTc)
 * [OpenMPT documentation on effects](https://wiki.openmpt.org/Manual:_Effect_Reference)