# Equipment

The equipment system lets characters wear items in defined slots. Equipped weapons and armor attach visual models, override animations, control body mesh visibility, and transition between combat and non-combat states.

## Equipment Slots

Create equipment slots in the Spark Editor under **Items > Equipment > Slots**. Each slot defines a position where an item can be worn.

| Field                 | Description                                                  |
| --------------------- | ------------------------------------------------------------ |
| Display Name          | Slot label shown in UI (e.g., "Head", "Main Hand", "Chest"). |
| Slot Type             | Determines slot behavior. See below.                         |
| Slot Icon Placeholder | Sprite displayed in UI when the slot is empty.               |

### Slot Types

| Type      | Description                                                             |
| --------- | ----------------------------------------------------------------------- |
| Generic   | Standard slot for armor, accessories, rings, etc.                       |
| Main Hand | Primary weapon slot. Used for main-hand and two-handed weapons.         |
| Off Hand  | Secondary weapon slot. Used for off-hand weapons and shields.           |
| Ranged    | Ranged weapon slot. Used for bows, crossbows, and other ranged weapons. |

Create one slot entry per equipment position your game needs: head, chest, legs, feet, hands, main hand, off hand, ring, necklace, etc. The slot type only matters for weapon slots — set armor and accessory slots to Generic.

## Character Sheets

Character sheets define which equipment slots are available for a character. Create them in **Items > Equipment > Character Sheets**.

| Field           | Description                                            |
| --------------- | ------------------------------------------------------ |
| Available Slots | List of equipment slot entries this character can use. |

A character sheet is a layout definition. Different character types can have different sheets — for example, a warrior might have main hand, off hand, head, chest, legs, feet, and two ring slots, while a mage might replace the off hand slot with a focus slot.

You can add multiple entries of the same slot type. For example, adding two ring slot entries lets the character wear two rings.

## Body Parts

Body parts define physical attachment points on a character model where weapons and other equipment visuals are placed. Create them in **Items > Equipment > Body Parts**.

| Field            | Description                                              |
| ---------------- | -------------------------------------------------------- |
| Display Name     | The part name (e.g., "Right Hand", "Left Hip", "Back").  |
| Default Position | Default local position offset for attached items.        |
| Default Rotation | Default local rotation offset for attached items.        |
| Default Scale    | Default local scale for attached items (default: 1,1,1). |

Body parts are referenced by weapon configurations to determine where a weapon appears on the character. For example, a sword might reference a "Right Hand" body part for combat and a "Left Hip" body part when sheathed.

## Body Mesh Types and Configurations

The body mesh system controls character mesh visibility when equipment is worn.

### Body Mesh Types

Create body mesh types in **Items > Equipment > Body Mesh Types**. Each type represents a category of meshes on the character model — for example: Hair, Beard, Hands, Head, Upper Body, Lower Body.

Body mesh types are simple named entries with no extra fields.

### Body Mesh Configurations

Create body mesh configurations in **Items > Equipment > Body Mesh Configurations**. Each configuration defines which body mesh types to hide when applied.

| Field                  | Description                                                                             |
| ---------------------- | --------------------------------------------------------------------------------------- |
| Hidden Body Mesh Types | List of body mesh type entries that should be hidden when this configuration is active. |

Armor items reference a body mesh configuration. When the armor is equipped, the specified mesh types are hidden. When unequipped, the meshes are restored.

**Example:** A helmet's body mesh configuration might hide the "Hair" mesh type. When the player equips the helmet, their hair mesh is hidden. When they unequip it, the hair reappears.

## Setting Up an Equipment Entity

To let a character wear equipment at runtime, add an **EquipmentEntity** component to the character's GameObject in the Inspector.

| Field                        | Description                                                                                      |
| ---------------------------- | ------------------------------------------------------------------------------------------------ |
| Character Sheet Entry        | The character sheet that defines available equipment slots.                                      |
| Custom Equipment Id          | Optional custom ID for this equipment set. Leave empty for auto-generated.                       |
| Auto Initialize On Start     | Automatically create equipment slots on Start (default: true).                                   |
| Auto Create Missing Items    | Automatically create item instances when equipping (default: true).                              |
| Is Persistent                | Save and load equipped items across sessions (default: false).                                   |
| Auto Save On Change          | Automatically save when equipment changes (default: true). Requires Is Persistent.               |
| Load On Initialize           | Load saved equipment data when initializing (default: true). Requires Is Persistent.             |
| Spark Entity                 | Reference to the SparkEntity on this character. Required for persistence.                        |
| Auto Update Visual Equipment | Automatically update weapon/armor visuals when items are equipped or unequipped (default: true). |
| Body Entity                  | Reference to the BodyEntity component for visual attachment points and mesh management.          |
| Is In Combat                 | Current combat state of the character (default: false). Determines weapon positioning.           |

## Setting Up a Body Entity

The **BodyEntity** component maps body part entries and body mesh types to actual transforms and GameObjects on the character model. Add it to the character's avatar GameObject.

| Field                | Description                                                                                                                      |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| Body Part Transforms | List of body part entries paired with their corresponding Transform on the character (e.g., "Right Hand" → the right hand bone). |
| Body Mesh References | List of body mesh types paired with their corresponding GameObjects on the character (e.g., "Hair" → the hair mesh objects).     |

Set up one body part transform reference for each attachment point on your character model (right hand, left hand, back, hip, head, etc.). Set up one body mesh reference for each mesh category — each reference can contain multiple GameObjects that all belong to that mesh type.

## Weapon Visual System

When a weapon is equipped, Spark instantiates the weapon prefab and attaches it to the correct body part on the character. The weapon's position changes based on combat state.

### Combat vs. Non-Combat Positioning

Each weapon item configures two attachment states:

| State                     | Description                                                                                                  |
| ------------------------- | ------------------------------------------------------------------------------------------------------------ |
| **Non-Combat** (sheathed) | The weapon is attached to a resting body part (e.g., back, hip) with its own position and rotation offsets.  |
| **Combat** (drawn)        | The weapon is attached to an active body part (e.g., right hand) with its own position and rotation offsets. |

For example, a sword might be attached to the "Left Hip" body part when sheathed and the "Right Hand" body part when drawn.

### Per-Character Coordinate Overrides

Different character models may have slightly different proportions, so weapon placement may need per-character adjustments. Each weapon visual configuration includes a list of character-specific coordinate overrides that map a specific character entry to custom position and rotation values.

When positioning a weapon, Spark checks for a character-specific override first. If none exists, it falls back to the default coordinates.

### Sheath and Unsheath Transitions

When the character's combat state changes, equipped weapons transition between their non-combat and combat positions.

| Field                    | Description                                                                     |
| ------------------------ | ------------------------------------------------------------------------------- |
| Play Unsheath Animation  | Trigger an unsheath animation when entering combat (default: true).             |
| Play Sheathe Animation   | Trigger a sheath animation when exiting combat (default: true).                 |
| Unsheath Animation Delay | Seconds to wait before repositioning the weapon during unsheath (default: 0.3). |
| Sheathe Animation Delay  | Seconds to wait before repositioning during sheath (default: 0.3).              |

The delay lets you sync the weapon reposition with the animation — for example, waiting until the character's hand reaches the hip before the sword moves from hip to hand.

### Active Weapon Slot Type

The equipment system tracks an **active weapon slot type** which determines which weapon is currently drawn. When the active slot type changes, only the relevant weapon transitions to combat position while other weapons remain sheathed.

This supports weapon swapping systems — for example, switching from melee to ranged draws the bow while keeping the sword sheathed on the hip.

### Weapon Hand Configurations

The visual config used depends on the weapon's hand type:

| Hand Type  | Config Used                                                                                 |
| ---------- | ------------------------------------------------------------------------------------------- |
| Main Hand  | Single weapon visual config.                                                                |
| Off Hand   | Single weapon visual config.                                                                |
| Two Handed | Single weapon visual config.                                                                |
| Any Hand   | Separate main hand and off hand configs, depending on which slot the weapon is equipped in. |
| Ranged     | Ranged-specific config.                                                                     |

## Armor Visual System

When armor is equipped, Spark shows the armor piece and optionally hides body meshes.

**Equip flow:**

1. Find the child GameObject on the character matching the armor's **Armor GameObject Name**.
2. Activate (show) that GameObject.
3. If the armor has a **Body Mesh Configuration**, hide the specified body mesh types on the BodyEntity.

**Unequip flow:**

1. Deactivate (hide) the armor GameObject.
2. Restore any body meshes that were hidden by this armor's configuration.

## Animator Override Controllers

Both weapons and armor can specify an **Animator Override Controller**. When an item with an override is equipped, Spark replaces the character's current animator controller with the override. This lets different weapons play different animation sets (e.g., sword idle vs. bow idle vs. staff idle).

When the item is unequipped, the original animator controller is restored.

## Camera Overrides

Weapons can specify a **Camera Override** entry that adjusts camera settings when the weapon is equipped. This is useful for changing the camera angle or distance for different weapon types — for example, zooming out further for ranged weapons.

## Equipment-Related Requirements

The Items plugin adds requirement types that check equipment state. These can be used in triggers, abilities, quests, or anywhere requirements are supported:

| Requirement                 | Description                                                                 |
| --------------------------- | --------------------------------------------------------------------------- |
| Has Equipment Slot Equipped | Checks if the character has any item equipped in a specific equipment slot. |
| Has Item Equipped           | Checks if the character has a specific item equipped.                       |
| Has Weapon Type Equipped    | Checks if the character has a weapon of a specific weapon type equipped.    |

## Drag-and-Drop

Equipment slots participate in the inventory drag-and-drop system:

| Source         | Target         | Result                                               |
| -------------- | -------------- | ---------------------------------------------------- |
| Inventory Slot | Equipment Slot | Equip the item (if compatible and requirements met). |
| Equipment Slot | Inventory Slot | Unequip the item back to the inventory.              |
| Equipment Slot | Equipment Slot | Swap equipped items (if both slots are compatible).  |

## Persistence

When **Is Persistent** is enabled on the EquipmentEntity, equipped items are saved and loaded through Spark's save system. What is saved per slot includes the slot definition, slot index (for duplicate slots), and the equipped item entry. The character sheet entry is also stored so the correct slot layout is restored on load.


---

# 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/items/equipment.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.