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.
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
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.
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.
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.
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.
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.
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:
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.
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:
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:
Find the child GameObject on the character matching the armor's Armor GameObject Name.
Activate (show) that GameObject.
If the armor has a Body Mesh Configuration, hide the specified body mesh types on the BodyEntity.
Unequip flow:
Deactivate (hide) the armor GameObject.
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:
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:
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.
Last updated
Was this helpful?