# Factions

Factions define group allegiances and relationships between characters. They control who is friendly, neutral, or hostile to whom, and determine ability targeting, NPC behavior, and combat engagement.

## Creating a Faction

Open the Spark Editor, go to **Combat > Factions** and click **Create New**.

Each faction entry has:

| Field                | Description                                                                             |
| -------------------- | --------------------------------------------------------------------------------------- |
| Display Name         | Faction name (e.g., "Alliance", "Bandits", "Wildlife").                                 |
| Description          | Faction description.                                                                    |
| Icon                 | Sprite for UI display.                                                                  |
| Default Relationship | The default relationship with any faction not explicitly defined (defaults to Neutral). |
| Relationships        | List of explicit relationships with other factions.                                     |

## Faction Relationships

Each relationship entry defines how this faction views another:

| Field          | Description                            |
| -------------- | -------------------------------------- |
| Target Faction | The other faction.                     |
| Relationship   | **Ally**, **Neutral**, or **Hostile**. |

Relationships are **directional** — faction A being hostile to faction B does not automatically mean faction B is hostile to faction A. You must define both directions separately if you want symmetry.

### Relationship Types

| Type        | Description                                                                                                        |
| ----------- | ------------------------------------------------------------------------------------------------------------------ |
| **Self**    | Automatically assigned when checking an entity against itself.                                                     |
| **Ally**    | Entities in the same faction, or factions explicitly set as allies. Targets for friendly abilities (heals, buffs). |
| **Neutral** | Default relationship. Entities do not attack on sight but can be targeted.                                         |
| **Hostile** | Enemies. NPCs will engage in combat, abilities can target them as enemies.                                         |

Relationship types support bitwise combinations, meaning ability effects can specify which relationship types they affect (e.g., "this heal targets Self and Ally").

### Relationship Lookup

When checking the relationship between two entities:

1. If they are the same entity, return **Self**.
2. If they are in the same faction, return **Ally**.
3. Check the explicit relationships list for the target's faction.
4. If no explicit relationship is found, use the **Default Relationship**.

## Faction Settings

Global faction settings are configured in **Combat > Factions > Settings**:

| Field               | Description                                                                                                       |
| ------------------- | ----------------------------------------------------------------------------------------------------------------- |
| Ally Color          | UI color for allied entities (default: green).                                                                    |
| Neutral Color       | UI color for neutral entities (default: yellow).                                                                  |
| Hostile Color       | UI color for hostile entities (default: red).                                                                     |
| Out Of Combat Timer | Seconds after the last hostile action before an entity automatically exits combat state (default: 5, range 0–60). |

## How Factions Affect Combat

Factions integrate with the combat system in several ways:

* **Ability targeting**: Effects filter valid targets by relationship type. A hostile damage ability only hits enemies; a friendly heal only hits allies.
* **Combat state**: When a hostile or neutral effect hits an entity, both the caster and target are set to "IN\_COMBAT" state.
* **NPC behavior**: Hostile NPCs engage players on sight. Neutral NPCs only fight back when attacked.
* **UI**: Nameplates, health bars, and other UI elements use faction colors to indicate friend or foe.


---

# 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/user-guide/plugins/combat/factions.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.