> For the complete documentation index, see [llms.txt](https://docs.sparkframework.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sparkframework.dev/documentation/developer-guide/core-systems/requirements-system/api.md).

# API

**Assembly:** `Spark.Requirements` **Interface:** `IRequirementsPlugin` **Implementation:** `RequirementsPlugin`

## Interface

```csharp
public interface IRequirementsPlugin
{
    RequirementCheckResult CheckRequirement(RequirementEntry entry,
        RequirementContext context);
    RequirementCheckResult CheckRequirements(
        List<RequirementGroupEntry> groups, RequirementContext context);
    RequirementCheckResult CheckRequirementGroup(
        RequirementGroupEntry group, RequirementContext context);
    DetailedRequirementCheckResult CheckRequirementsDetailed(
        List<RequirementGroupEntry> groups, RequirementContext context);

    List<RequirementEntry> GetAllRequirementEntries();
    RequirementEntry GetRequirementEntry(string id);
}
```

## Methods

### CheckRequirement

```csharp
RequirementCheckResult CheckRequirement(RequirementEntry entry,
    RequirementContext context)
```

Checks a single requirement. Delegates to the entry's `RequirementTypeBase` evaluator.

### CheckRequirements

```csharp
RequirementCheckResult CheckRequirements(
    List<RequirementGroupEntry> groups, RequirementContext context)
```

Checks all requirement groups. All groups must pass for the result to pass.

### CheckRequirementGroup

```csharp
RequirementCheckResult CheckRequirementGroup(
    RequirementGroupEntry group, RequirementContext context)
```

Checks a single group using its configured logic (AND, OR, etc.).

### CheckRequirementsDetailed

```csharp
DetailedRequirementCheckResult CheckRequirementsDetailed(
    List<RequirementGroupEntry> groups, RequirementContext context)
```

Returns per-requirement breakdowns for UI display or debugging.

## RequirementEntry

Extends `SparkDatabaseEntry`. Defines a single requirement.

| Field                 | Type                 | Description                        |
| --------------------- | -------------------- | ---------------------------------- |
| `requirementType`     | RequirementTypeBase  | The evaluator script               |
| `requirementTypeData` | RequirementDataAsset | Configuration for the evaluator    |
| `failureMessage`      | string               | Message shown when the check fails |

## RequirementGroupEntry

Groups multiple requirements with logic operators.

| Field             | Type                         | Description                        |
| ----------------- | ---------------------------- | ---------------------------------- |
| `groupName`       | string                       | Label for the group                |
| `logic`           | RequirementGroupLogic        | How checks combine                 |
| `minimumRequired` | int                          | Required passes for Threshold mode |
| `checks`          | List\<RequirementCheckEntry> | Individual checks                  |

Each `RequirementCheckEntry` references a `RequirementEntry` and has an `invertResult` flag to negate the outcome.

## RequirementGroupLogic

```csharp
public enum RequirementGroupLogic
{
    And,        // All must pass
    Or,         // At least one must pass
    Nand,       // At least one must fail
    Nor,        // All must fail
    Xor,        // Exactly one must pass
    Threshold   // At least N must pass (uses minimumRequired)
}
```

## RequirementContext

Carries data for requirement evaluation.

| Property      | Type                        | Description                     |
| ------------- | --------------------------- | ------------------------------- |
| `Source`      | GameObject                  | The entity being checked        |
| `Target`      | GameObject                  | Optional target entity          |
| `SourceEntry` | SparkDatabaseEntry          | Optional related database entry |
| `CustomData`  | Dictionary\<string, object> | Arbitrary key-value data        |

**Methods:**

```csharp
// Fluent builders
RequirementContext WithTarget(GameObject target)
RequirementContext WithEntry(SparkDatabaseEntry entry)
RequirementContext WithData(string key, object value)

// Data access
T GetData<T>(string key, T defaultValue)
```

## RequirementCheckResult

Returned by all check methods.

```csharp
public struct RequirementCheckResult
{
    public bool Passed;
    public string FailureReason;
    public RequirementEntry RequirementEntry;

    public static RequirementCheckResult Success();
    public static RequirementCheckResult Failure(string reason,
        RequirementEntry entry);
}
```

## DetailedRequirementCheckResult

Extended result with per-group and per-requirement breakdowns, including pass/fail counts.

## Events

| Event                    | Description                                               |
| ------------------------ | --------------------------------------------------------- |
| `RequirementFailedEvent` | Published when a requirement check fails (for logging/UI) |

## Creating Custom Requirement Types

Extend `RequirementTypeBase`:

```csharp
[CreateAssetMenu(menuName = "Spark/Requirements/My Requirement")]
public class MyRequirementType : RequirementTypeBase
{
    public override RequirementCheckResult Check(
        RequirementContext context, RequirementDataAsset data)
    {
        // Your validation logic
        if (conditionMet)
            return RequirementCheckResult.Success();
        return RequirementCheckResult.Failure("Condition not met", null);
    }

    public override Type GetExpectedDataType()
    {
        return typeof(MyRequirementData);
    }
}
```

## Usage

```csharp
var reqPlugin = Spark.GetPlugin<IRequirementsPlugin>();
if (reqPlugin != null)
{
    var context = new RequirementContext { Source = playerObject }
        .WithTarget(npcObject)
        .WithData("questId", "main_quest_01");

    // Simple check
    var result = reqPlugin.CheckRequirements(requirementGroups, context);
    if (result.Passed)
    {
        Debug.Log("All requirements met!");
    }
    else
    {
        Debug.Log($"Failed: {result.FailureReason}");
    }

    // Detailed check for UI display
    var detailed = reqPlugin.CheckRequirementsDetailed(requirementGroups, context);
    // Iterate per-group and per-requirement results
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.sparkframework.dev/documentation/developer-guide/core-systems/requirements-system/api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.