# API

**Assembly:** `Spark.Triggers` **Interface:** `ITriggersPlugin` **Implementation:** `TriggersPlugin`

## Interface

```csharp
public interface ITriggersPlugin
{
    void ExecuteTrigger(TriggerEntry triggerEntry,
        TriggerExecutionContext context);
    void ExecuteTriggers(List<TriggerEntry> triggerEntries,
        TriggerExecutionContext context);
    void ExecuteTriggerInstance(TriggerInstance triggerInstance,
        TriggerExecutionContext context);
    void ExecuteTriggerInstances(List<TriggerInstance> triggerInstances,
        TriggerExecutionContext context);
    void ExecuteTriggersWithDelay(List<TriggerEntry> triggerEntries,
        TriggerExecutionContext context, float delay);
    void RegisterTriggerEntity(TriggerEntity entity);
    void UnregisterTriggerEntity(TriggerEntity entity);
}
```

## TriggerEntry

Extends `SparkDatabaseEntry`. Defines a configurable action.

| Field                     | Type             | Description                           |
| ------------------------- | ---------------- | ------------------------------------- |
| `triggerType`             | TriggerTypeBase  | The trigger definition script         |
| `triggerTypeData`         | TriggerDataAsset | Nested configuration data             |
| `executionDelay`          | float            | Delay before execution (0-10 seconds) |
| `allowMultipleExecutions` | bool             | If false, fires only once per entity  |

**Methods:**

```csharp
T GetTriggerData<T>()              // Cast data to expected type
TriggerTypeBase GetTriggerType()   // Get the trigger type
```

## TriggerInstance

Wraps a `TriggerEntry` with optional delay overrides. Used in lists where each trigger may have a custom delay.

| Field           | Type         | Description                    |
| --------------- | ------------ | ------------------------------ |
| `template`      | TriggerEntry | Reference to the trigger entry |
| `overrideDelay` | bool         | Override the entry's delay     |
| `customDelay`   | float        | Custom delay value (0-10)      |

**Methods:**

```csharp
float GetEffectiveDelay()  // Returns custom delay if overridden, otherwise entry delay
T GetTriggerData<T>()      // Shortcut to template's trigger data
```

## TriggerExecutionContext

Carries data for trigger execution.

| Property          | Type            | Description                   |
| ----------------- | --------------- | ----------------------------- |
| `Source`          | GameObject      | Entity executing the trigger  |
| `Target`          | GameObject      | Target of the trigger         |
| `Position`        | Vector3         | World position                |
| `TriggerEntry`    | TriggerEntry    | The trigger being executed    |
| `TriggerInstance` | TriggerInstance | Instance data (if applicable) |
| `AdditionalData`  | object          | Arbitrary extra data          |
| `EventName`       | string          | Associated event name         |
| `EventValue`      | float           | Associated numeric value      |

**Builder Methods:**

```csharp
TriggerExecutionContext WithTarget(GameObject target)
TriggerExecutionContext WithPosition(Vector3 position)
TriggerExecutionContext WithEventData(string eventName, float eventValue)
TriggerExecutionContext WithAdditionalData(object data)
```

**Accessor Methods:**

```csharp
SparkEntity GetSourceEntity()
SparkEntity GetTargetEntity()
T GetComponent<T>()
T GetAdditionalDataAs<T>()
```

## TriggerTypeBase

Abstract ScriptableObject base for trigger implementations.

```csharp
public abstract class TriggerTypeBase : ScriptableObject
{
    public TriggerDataAsset defaultData;

    public abstract void Execute(TriggerExecutionContext context);
    public abstract Type GetExpectedDataType();

    public virtual bool CanExecute(TriggerExecutionContext context) => true;
    public virtual T GetData<T>() where T : TriggerDataAsset;
}
```

## TriggerDataAsset

Abstract base for trigger-specific configuration. Extends `SparkDatabaseEntryNestedData`.

```csharp
public abstract class TriggerDataAsset : SparkDatabaseEntryNestedData
{
    public virtual float GetDelay() => 0f;
}
```

## TriggerEntity

MonoBehaviour that tracks one-shot trigger execution state.

**Methods:**

```csharp
void ExecuteDelayed(TriggerEntry entry, TriggerExecutionContext context,
    float delay)
// Executes a trigger after a delay via coroutine.

void ResetExecutedTriggers()
// Clears the one-shot tracking, allowing triggers to fire again.

static TriggerEntity EnsureExistsOn(GameObject gameObject)
// Gets or adds a TriggerEntity component.
```

## Commands

| Command                 | Fields                                    | Description                            |
| ----------------------- | ----------------------------------------- | -------------------------------------- |
| `ExecuteTriggerCommand` | `TriggerEntry`, `TriggerExecutionContext` | Executes a trigger through the network |

## Creating Custom Triggers

```csharp
[CreateAssetMenu(menuName = "Spark/Triggers/Teleport")]
public class TeleportTriggerType : TriggerTypeBase
{
    public override void Execute(TriggerExecutionContext context)
    {
        var data = context.TriggerEntry.GetTriggerData<TeleportTriggerData>();
        if (data == null || context.Source == null) return;

        context.Source.transform.position = data.targetPosition;
    }

    public override Type GetExpectedDataType() => typeof(TeleportTriggerData);
}

[System.Serializable]
public class TeleportTriggerData : TriggerDataAsset
{
    public Vector3 targetPosition;
}
```

## Usage

```csharp
var triggers = Spark.GetPlugin<ITriggersPlugin>();
if (triggers != null)
{
    var context = new TriggerExecutionContext
    {
        Source = playerObject
    }.WithTarget(npcObject);

    // Execute a single trigger
    triggers.ExecuteTrigger(rewardTrigger, context);

    // Execute a list of triggers
    triggers.ExecuteTriggers(questRewards, context);

    // Execute with delay
    triggers.ExecuteTriggersWithDelay(delayedRewards, context, 2f);
}
```


---

# 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/core-systems/triggers-system/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.