# API

**Assembly:** `Spark.Combat` **Interface:** `ICombatPlugin` **Implementation:** `CombatPlugin`

## Interface

```csharp
public interface ICombatPlugin
{
    // Ability execution
    void ExecuteAbility(GameObject caster, AbilityEntry actionEntry,
        CombatContext context);
    void ApplyEffectsToTargets(CombatContext context, List<GameObject> targets);

    // Type registration
    void RegisterAbilityType(Type abilityType, CombatTypeInfo info);
    void RegisterEffectType(Type effectType, CombatTypeInfo info);
    IReadOnlyDictionary<string, CombatTypeInfo> GetRegisteredAbilityTypes();
    IReadOnlyDictionary<string, CombatTypeInfo> GetRegisteredEffectTypes();
    AbilityTypeBase CreateAbilityTypeInstance(string typeId);
    EffectTypeBase CreateEffectTypeInstance(string typeId);

    // Stat system
    StatModificationBuilder Modify(GameObject target);
    StatModificationBuilder Modify(StatEntity statEntity);
    float GetValue(GameObject target, string statId, string propertyId);
    float GetValue(StatEntity statEntity, string statId, string propertyId);
    void ApplyModifier(GameObject target, StatModifierEntry statModifier);
    void RemoveModifier(GameObject target, StatModifierEntry statModifier);
    List<StatEntry> GetAllStatEntries();
    void ClearStatEntriesCache();
    StatEntry GetStatEntry(string statId);
}
```

## CombatContext

Carries data through the ability execution pipeline.

| Property         | Type               | Description                |
| ---------------- | ------------------ | -------------------------- |
| `CasterEntity`   | SparkEntity        | Entity casting the ability |
| `AbilityEntry`   | AbilityEntry       | The ability being executed |
| `TargetPosition` | Vector3            | World position target      |
| `TargetEntity`   | SparkEntity        | Single target entity       |
| `HitTargets`     | List\<SparkEntity> | All entities hit           |

## StatModificationBuilder

Fluent API for applying stat changes.

```csharp
var combat = Spark.GetPlugin<ICombatPlugin>();
combat.Modify(targetObject)
    .Stat("health")
    .Property("current")
    .Add(-50f)
    .Apply();
```

## Key Database Entries

### AbilityEntry

Defines an ability with a targeting type and activation type. See [Ability Types](broken://pages/yoxirTifaygucdVzEBHL) for the full list of targeting and activation types.

### StatEntry

Defines a character stat (health, mana, strength, etc.) with associated properties.

### StatModifierEntry

Defines a reusable stat modification (buff, debuff, equipment bonus).

### DamageTypeEntry / HealingTypeEntry

Define damage and healing categories with associated scaling.

### FactionEntry

Defines NPC factions with relationship data.

### StatusTagEntry

Tags for status effects (stunned, burning, frozen, etc.).

## Abstract Base Classes

### AbilityTypeBase

Base for ability targeting types. Override to create custom targeting behavior.

### EffectTypeBase

Base for ability effects. Override to create custom damage, healing, or utility effects.

### StatDataAsset

Abstract base for stat-specific nested data (ValueStatDataAsset, ResourceStatDataAsset, etc.).

### AbilityDataAsset

Abstract base for ability execution configuration (TargetAbilityDataAsset, AoEAbilityDataAsset, ProjectileAbilityDataAsset, etc.).

### EffectDataAsset

Abstract base for effect execution configuration.

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

## Events

| Event                        | Description                                      |
| ---------------------------- | ------------------------------------------------ |
| `AbilityExecutedEvent`       | Ability finished executing (targets, success)    |
| `AbilityHitEvent`            | Ability hit targets with effects                 |
| `StatModificationEvent`      | Single stat modified (target, stat, value, type) |
| `BatchStatModificationEvent` | Multiple stats modified at once                  |
| `StatusAppliedEvent`         | Status effect applied                            |
| `StatusRemovedEvent`         | Status effect removed                            |
| `StatusRefreshedEvent`       | Status effect duration refreshed                 |
| `StatusTickEvent`            | Status effect ticked                             |
| `StatusImmuneEvent`          | Target immune to status                          |
| `RevivePlayerRequestedEvent` | Player revival requested                         |
| `TargetLockedEvent`          | Target lock acquired                             |
| `TargetUnlockedEvent`        | Target lock released                             |

## Commands

| Command                 | Description                      |
| ----------------------- | -------------------------------- |
| `ModifyStatCommand`     | Modify a stat on a target entity |
| `RemoveModifierCommand` | Remove a stat modifier           |

## Components

| Component                              | Description                                 |
| -------------------------------------- | ------------------------------------------- |
| `StatEntity`                           | Manages stat values on a GameObject         |
| `ObjectCombatEntity`                   | Combat identity and faction on a GameObject |
| `CombatInputTriggerSlot`               | Input binding for ability execution         |
| `ThirdPersonTargetLock`                | Target lock-on system                       |
| `CharacterControllerKnockbackReceiver` | Knockback physics                           |

## Usage

```csharp
var combat = Spark.GetPlugin<ICombatPlugin>();
if (combat != null)
{
    // Get a stat value
    float health = combat.GetValue(playerObject, "health", "current");

    // Modify a stat
    combat.Modify(playerObject)
        .Stat("health")
        .Property("current")
        .Add(-25f)
        .Apply();

    // Execute an ability
    var context = new CombatContext
    {
        CasterEntity = playerEntity,
        AbilityEntry = fireballAbility,
        TargetEntity = enemyEntity
    };
    combat.ExecuteAbility(playerObject, fireballAbility, context);

    // Apply/remove modifiers
    combat.ApplyModifier(playerObject, strengthBuff);
    combat.RemoveModifier(playerObject, strengthBuff);
}
```


---

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