# API

**Assembly:** `Spark.Quests` **Interface:** `IQuestsPlugin` **Implementation:** `QuestsPlugin`

## Interface

```csharp
public interface IQuestsPlugin
{
    // Quest lifecycle
    void AcceptQuest(SparkEntity actor, QuestEntry quest);
    void AbandonQuest(SparkEntity actor, string questId);
    void UpdateObjective(SparkEntity actor, string questId,
        int objectiveIndex, int progressDelta);
    void CompleteQuest(SparkEntity actor, string questId);
    void TurnInQuest(SparkEntity actor, string questId);

    // Reward selection
    void SelectReward(SparkEntity actor, string questId, int rewardIndex);
    void DeselectReward(SparkEntity actor, string questId, int rewardIndex);

    // Tracking
    void TrackQuest(string questId);
    void UntrackQuest(string questId);
    List<string> GetTrackedQuestIds();
    bool IsQuestTracked(string questId);

    // State queries
    bool CanAcceptQuest(SparkEntity actor, QuestEntry quest);
    bool IsQuestActive(SparkEntity actor, string questId);
    bool IsQuestCompleted(SparkEntity actor, string questId);

    // Progress data
    QuestProgressSaveData GetQuestProgress(SparkEntity actor, string questId);
    List<QuestProgressSaveData> GetActiveQuests(SparkEntity actor);
    List<QuestProgressSaveData> GetQuestHistory(SparkEntity actor);
}
```

## QuestEntry

Extends `SparkDatabaseEntry`. Defines a quest.

| Field                  | Type                         | Description                       |
| ---------------------- | ---------------------------- | --------------------------------- |
| `questCategory`        | QuestCategoryEntry           | Category for journal grouping     |
| `questJournalTurnIn`   | bool                         | Can turn in from journal UI       |
| `acceptRequirements`   | List\<RequirementGroupEntry> | Conditions to accept              |
| `objectives`           | List\<QuestObjective>        | Tasks to complete                 |
| `rewardsToSelectCount` | int                          | How many rewards the player picks |
| `selectableRewards`    | List\<QuestReward>           | Optional rewards to choose from   |
| `guaranteedRewards`    | List\<QuestReward>           | Rewards always granted            |

### QuestObjective

| Field           | Type                    | Description            |
| --------------- | ----------------------- | ---------------------- |
| `objectiveType` | QuestObjectiveTypeBase  | Type definition script |
| `objectiveData` | QuestObjectiveDataAsset | Configuration data     |

### QuestReward

| Field        | Type                 | Description              |
| ------------ | -------------------- | ------------------------ |
| `rewardType` | QuestRewardTypeBase  | Reward definition script |
| `rewardData` | QuestRewardDataAsset | Configuration data       |

## QuestProgressSaveData

Tracks runtime quest progress.

| Field                   | Type                          | Description             |
| ----------------------- | ----------------------------- | ----------------------- |
| `questId`               | string                        | Quest identifier        |
| `state`                 | QuestState                    | Active, Completed, etc. |
| `objectiveProgress`     | List\<QuestObjectiveProgress> | Per-objective progress  |
| `selectedRewardIndices` | List\<int>                    | Player's reward choices |

### QuestObjectiveProgress

| Field             | Type | Description      |
| ----------------- | ---- | ---------------- |
| `objectiveIndex`  | int  | Which objective  |
| `currentProgress` | int  | Current count    |
| `requiredCount`   | int  | Goal count       |
| `isCompleted`     | bool | Whether complete |

## Events

| Event                           | Description                     |
| ------------------------------- | ------------------------------- |
| `QuestAcceptedEvent`            | Quest accepted by actor         |
| `QuestCompletedEvent`           | All objectives completed        |
| `QuestTurnedInEvent`            | Rewards granted, quest finished |
| `QuestAbandonedEvent`           | Quest abandoned by actor        |
| `QuestObjectiveProgressedEvent` | Objective progress updated      |
| `QuestRewardSelectedEvent`      | Reward chosen by player         |
| `QuestRewardDeselectedEvent`    | Reward choice removed           |
| `QuestRewardsGrantedEvent`      | All rewards granted             |
| `QuestTrackedEvent`             | Quest added to tracker UI       |
| `QuestUntrackedEvent`           | Quest removed from tracker UI   |
| `QuestTurnInFailedEvent`        | Turn-in validation failed       |

## Commands

| Command                       | Fields                                 | Description         |
| ----------------------------- | -------------------------------------- | ------------------- |
| `AcceptQuestCommand`          | actorEntityId, questId                 | Accept a quest      |
| `CompleteQuestCommand`        | actorEntityId, questId                 | Mark quest complete |
| `UpdateQuestObjectiveCommand` | questId, objectiveIndex, progressDelta | Update progress     |
| `SelectQuestRewardCommand`    | questId, rewardIndex                   | Select a reward     |
| `DeselectQuestRewardCommand`  | questId, rewardIndex                   | Deselect a reward   |
| `TurnInQuestCommand`          | questId                                | Turn in for rewards |
| `AbandonQuestCommand`         | questId                                | Abandon the quest   |

## Components

### QuestTrackerEntity

MonoBehaviour that manages quest state per entity.

**Methods:**

```csharp
void AcceptQuest(QuestEntry quest)
void UpdateObjectiveProgress(string questId, int objectiveIndex, int delta)
void CompleteQuest(string questId)
void TurnInQuest(string questId)
void SelectReward(string questId, int rewardIndex)
void DeselectReward(string questId, int rewardIndex)
void TrackQuest(string questId)
void UntrackQuest(string questId)
void AbandonQuest(string questId)
```

Validates turn-in requirements, handles reward granting, and saves state through `QuestsSaveData`.

## Save Data

`QuestsSaveData` stores per-entity quest data including active quests, completed quest IDs, tracked quests, and quest history.

## Usage

```csharp
var quests = Spark.GetPlugin<IQuestsPlugin>();
if (quests != null)
{
    // Accept a quest
    if (quests.CanAcceptQuest(playerEntity, mainQuest))
    {
        quests.AcceptQuest(playerEntity, mainQuest);
    }

    // Update objective progress
    quests.UpdateObjective(playerEntity, "kill_wolves", 0, 1);

    // Check quest state
    if (quests.IsQuestCompleted(playerEntity, "kill_wolves"))
    {
        quests.SelectReward(playerEntity, "kill_wolves", 0);
        quests.TurnInQuest(playerEntity, "kill_wolves");
    }

    // Get active quests
    var active = quests.GetActiveQuests(playerEntity);
}
```


---

# 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/quests/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.