# Spellbooks

The Spellbooks plugin organizes abilities into collections that can be learned, granted, and displayed. Each spellbook contains a list of abilities, and abilities can be automatically added to the player's ability bar when the spellbook is learned.

## Creating a Spellbook Entry

Open the Spark Editor, go to **Spellbooks** and click **Create New**.

Each spellbook entry defines:

| Field        | Description                                                                              |
| ------------ | ---------------------------------------------------------------------------------------- |
| Display Name | Spellbook name shown in-game (e.g., "Fire Magic", "Holy Prayers", "Warrior Techniques"). |
| Description  | Spellbook description text.                                                              |
| Icon         | Sprite for the spellbook in UI.                                                          |
| Abilities    | List of abilities in this spellbook. Each ability has the fields below.                  |

### Spellbook Abilities

Each ability in the spellbook has:

| Field           | Description                                                                                                                                             |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Ability         | Reference to an ability entry from the Combat plugin.                                                                                                   |
| Auto Add To Bar | If enabled, this ability is automatically added to the player's ability bar when the character enters the game (if the ability's requirements are met). |

## Learning and Removing Spellbooks

Spellbooks are learned and removed through the trigger system.

| Trigger       | Description                                                                                        |
| ------------- | -------------------------------------------------------------------------------------------------- |
| Add Spellbook | Grants or removes a spellbook. Configure the spellbook entry and whether to remove instead of add. |

Learned spellbooks persist through the save system.

## Auto-Add to Ability Bar

Abilities marked with **Auto Add To Bar** are automatically placed in the player's ability bar when the character first enters the game. This uses the **SpellbookAutoAddHandler** component.

To set up auto-add, add a **SpellbookAutoAddHandler** component in the Inspector:

| Field              | Description                                                                                          |
| ------------------ | ---------------------------------------------------------------------------------------------------- |
| Ability Bar Entity | Reference to the AbilityBarEntity where abilities should be placed.                                  |
| Bar Identifier     | Name of the ability bar to target (default: "AbilityBar\_1").                                        |
| Number Of Slots    | Number of slots to create if the bar doesn't already exist.                                          |
| Process On Enable  | If enabled, auto-add runs when the component is enabled. If disabled, it must be triggered manually. |

Auto-add only processes once per game session and only fills empty slots. It also respects ability requirements — abilities whose requirements aren't met are skipped.

## Spellbook Panel UI

The Spellbooks plugin includes a **SpellbookPanelUI** component for displaying learned spellbooks and their abilities.

| Field                 | Description                                         |
| --------------------- | --------------------------------------------------- |
| Toggle Input Entry    | Input entry to toggle the panel open and closed.    |
| Close Button          | Button to close the panel.                          |
| Spellbooks Content    | Parent transform where spellbook slots are created. |
| Spellbook Slot Prefab | Prefab for each spellbook button in the sidebar.    |
| Abilities Content     | Parent transform where ability slots are created.   |
| Ability Slot Prefab   | Prefab for each ability in the detail view.         |

The panel shows a list of learned spellbooks on the left. When a spellbook is selected, its abilities are displayed on the right. Abilities that don't meet their requirements appear locked.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.sparkframework.dev/documentation/user-guide/plugins/spellbooks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.