# NPCs

NPC entries define non-player characters in the database with death behavior configuration.

## Creating an NPC Entry

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

Each NPC entry defines:

| Field             | Description                                                        |
| ----------------- | ------------------------------------------------------------------ |
| Display Name      | NPC name shown in-game (e.g., "Blacksmith Kara", "Guard Captain"). |
| Description       | NPC description text.                                              |
| Icon              | Sprite for the NPC in UI.                                          |
| On Death Triggers | List of triggers to execute when this NPC dies (see below).        |

### On Death Triggers

Each on-death trigger specifies:

| Field                        | Description                                                                                                  |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------ |
| Trigger                      | The trigger entry to execute when this NPC dies (e.g., roll loot table, grant experience, advance quest).    |
| Require Player Participation | If enabled, the trigger only fires if the player was in the NPC's threat table when it died (default: true). |

This lets you configure rewards that only fire when the player contributed to the kill, preventing exploits where NPCs kill each other and the player gets credit.

## Setting Up an NPC Entity

To mark a GameObject as an NPC, add an **NPCEntity** component in the Inspector.

| Field | Description                                             |
| ----- | ------------------------------------------------------- |
| NPC   | Reference to the NPC database entry for this character. |

The NPCEntity component automatically sets the character's display name from the database entry and listens for the character's death to execute on-death triggers.

## NPC Spawner

The **NPCSpawner** component automates spawning NPCs in a defined area with weighted selection and respawn support.

### Spawn Area

| Field            | Description                                                                     |
| ---------------- | ------------------------------------------------------------------------------- |
| Spawn Shape      | **Box**, **Sphere**, or **Circle**. Defines the shape of the spawn volume.      |
| Box Size         | Size of the box area (default: 10, 5, 10). Only for Box shape.                  |
| Sphere Radius    | Radius of the sphere area (default: 10). Only for Sphere shape.                 |
| Circle Radius    | Radius of the circle area in the XZ plane (default: 10). Only for Circle shape. |
| Spawn On Surface | If enabled, spawns on the surface of the shape instead of within the volume.    |

### Spawn Validation

| Field                   | Description                                                                   |
| ----------------------- | ----------------------------------------------------------------------------- |
| Use Spawn Validation    | Enable spawn point validation (default: true).                                |
| Validation Method       | **Raycast Down**, **Raycast Up**, **Collision Check**, or **NavMesh Sample**. |
| Raycast Layer Mask      | Layers the raycast should hit for valid points.                               |
| Raycast Distance        | Maximum raycast distance (default: 100).                                      |
| Collision Check Radius  | Radius for overlap checks — a valid point has no collisions (default: 0.5).   |
| Max Validation Attempts | Attempts to find a valid point per spawn (default: 10).                       |

### NPC Entries

| Field             | Description                                                                                                                                                 |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| NPC Spawn Entries | List of NPC prefabs that can spawn, each with a **Spawn Weight** (higher = more likely), **Random Rotation** toggle, and optional fixed **Spawn Rotation**. |

### Spawn Limits

| Field            | Description                                                                                  |
| ---------------- | -------------------------------------------------------------------------------------------- |
| Max Active NPCs  | Maximum NPCs alive at once. Set to 0 for unlimited (default: 10).                            |
| Max Total Spawns | Maximum total NPCs spawned over the spawner's lifetime. Set to 0 for unlimited (default: 0). |
| Spawn Parent     | Parent transform for spawned NPCs. Null uses the spawner's transform.                        |

### Spawn Timing

| Field                   | Description                                                   |
| ----------------------- | ------------------------------------------------------------- |
| Spawn On Start          | Spawn initial NPCs when the component starts (default: true). |
| Initial Spawn Count     | Number of NPCs to spawn immediately (default: 3).             |
| Use Continuous Spawning | Enable interval-based spawning (default: false).              |
| Spawn Interval          | Seconds between spawn attempts (default: 5).                  |
| NPCs Per Interval       | NPCs to spawn each interval (default: 1).                     |
| Use Respawn On Death    | Respawn NPCs when they die (default: true).                   |
| Respawn Delay           | Seconds to wait before respawning after death (default: 3).   |

### Gizmos

The spawner draws spawn area gizmos in the Scene view (configurable color, toggle for area and spawn point display) to help visualize the spawn volume during level design.


---

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