# API

**Assembly:** `Spark.Spellbooks` **Interface:** `ISpellbooksPlugin` **Implementation:** `SpellbooksPlugin`

## Interface

```csharp
public interface ISpellbooksPlugin
{
    List<SpellbookEntry> GetAllSpellbooks();
    SpellbookEntry GetSpellbook(string spellbookId);
}
```

## Methods

### GetAllSpellbooks

```csharp
List<SpellbookEntry> GetAllSpellbooks()
```

Returns all spellbook entries in the database.

### GetSpellbook

```csharp
SpellbookEntry GetSpellbook(string spellbookId)
```

Returns the spellbook with the given ID, or `null` if not found.

## SpellbookEntry

Extends `SparkDatabaseEntry`. Defines a collection of abilities.

| Field       | Type                        | Description                 |
| ----------- | --------------------------- | --------------------------- |
| `abilities` | List\<SpellbookAbilityData> | Abilities in this spellbook |

**Methods:**

```csharp
List<AbilityEntry> GetAbilities()
bool HasAbility(AbilityEntry ability)
bool HasAbility(string abilityId)
List<SpellbookAbilityData> GetAbilitiesData()
```

### SpellbookAbilityData

| Field          | Type         | Description                                   |
| -------------- | ------------ | --------------------------------------------- |
| `ability`      | AbilityEntry | The ability                                   |
| `autoAddToBar` | bool         | Auto-add to ability bar when requirements met |

## Components

### SpellbookAutoAddHandler

MonoBehaviour that handles one-time auto-addition of abilities to the ability bar.

| Field             | Type   | Description                 |
| ----------------- | ------ | --------------------------- |
| `barIdentifier`   | string | Target ability bar          |
| `numberOfSlots`   | int    | Slots to fill               |
| `processOnEnable` | bool   | Process on component enable |

**Methods:**

```csharp
void ProcessAutoAddAbilities()
```

Checks ability requirements using `IRequirementsPlugin` and adds qualifying abilities to `AbilityBarEntity`. Tracks which abilities have been auto-added to avoid duplicates.

## Trigger Types

| Trigger                   | Description                   |
| ------------------------- | ----------------------------- |
| `AddSpellbookTriggerType` | Grants or removes a spellbook |

### AddSpellbookTriggerDataAsset

| Field             | Type           | Description             |
| ----------------- | -------------- | ----------------------- |
| `spellbookEntry`  | SpellbookEntry | Spellbook to add/remove |
| `removeSpellbook` | bool           | Remove instead of add   |
| `delay`           | float          | Execution delay         |

## Save Data

### SpellbookSaveData

Extends `SaveDataEntry`.

**Methods:**

```csharp
void AddSpellbook(string spellbookId)
void RemoveSpellbook(string spellbookId)
List<string> GetSpellbooks()
bool HasSpellbook(string spellbookId)

void MarkAbilityAsAutoAdded(string abilityId)
bool WasAbilityAutoAdded(string abilityId)

bool HasProcessedInitialSpellbooks()
void SetProcessedInitialSpellbooks()
```

Tracks spellbook ownership and which abilities have been auto-added to bars to prevent re-adding.

## Usage

```csharp
var spellbooks = Spark.GetPlugin<ISpellbooksPlugin>();
if (spellbooks != null)
{
    // Get all spellbooks
    var allBooks = spellbooks.GetAllSpellbooks();

    // Get a specific spellbook
    SpellbookEntry fireBook = spellbooks.GetSpellbook("fire_spellbook");

    // List abilities in a spellbook
    var abilities = fireBook.GetAbilities();
    foreach (var ability in abilities)
    {
        Debug.Log(ability.DisplayName);
    }

    // Check if spellbook contains an ability
    bool hasFireball = fireBook.HasAbility("fireball");
}
```


---

# 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/developer-guide/plugins/spellbooks/api.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.