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

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

```{r libs, echo = F, message = F}
# devtools::install_github("njlyon0/dndR", force = TRUE)
library(dndR)
```

## Searching for Spells

There are _a lot_ of spells in the various Dungeons & Dragons source books that your character might be able to invoke. Finding specific spells can be a daunting task in the face of the sheer number of spells that exist so `dndR` has some functions to hopefully make this effort more manageable for your magic-using player characters and NPCs.

The `spell_list` function lets you search through official spells based on several criteria that you specify. A dataframe including all of the big-picture information for spells that meet your criteria is returned to help orient you for any subsequent steps you plan on taking. Note that all `spell_list` arguments that accept characters are case _in_-sensitive and queries use partial string matching so you don't need to try to engineer exact matches.

This function lets you can query spells based on one or more of the following criteria:

- Spell name(s)
- Character classes with access to the spell(s)
- Minimum spell slot required to cast the spell and/or "cantrip"
- School(s) of magic to which the spell belongs (e.g., "abjuration", etc.)
- Whether or not the spell can be cast as a ritual
- Time to cast the spell (either the phase of a turn required or the in-game time for spells that take more than one turn to cast)

```{r spell_list-v1}
# Find all sorcerer spells that have the word 'bolt' in the name
bolt_df <- dndR::spell_list(name = "bolt", class = "sorcerer")

# Check the structure of that output
str(bolt_df)
```

```{r spell_list-v2}
# Find all seventh-level necromancy spells in the wizard spell list
necro_df <- dndR::spell_list(school = "necromancy", class = "wizard", level = 7)

# Check the structure
str(necro_df)
```

## Spell Descriptions

If you need to access the specific description of a particular spell (or spells), you can use the `spell_text` function. This returns an R-style dataframe equivalent of the sort of spell card information you'd find in the back of a typical D&D source book.

```{r spell_text}
# Get the Chill Touch spell description
dndR::spell_text(name = "chill touch")
```

I typically use this function to get more detail on a particular spell after searching more broadly with `spell_list` but I think it's also nice as a quick reference if you need to consult the specific language of the spell description or remind yourself how casting the spell with a higher level spell slot affects the spell.