InventoryEquipment
Last modified: 17 November 2024Represents an Item in the Game World.
Configured using an Equipment Definition, which is added to an item's Equipment Fragment.
Equipment Definitions require at least one state.
States define visual and gameplay aspects of the equipment.
Complex equipment behavior or cosmetics can be implemented using Equipment Actors.
Slots are placement markers used by Equipment.
Equipment is the physical representation of items in the game world.
Equipment Definition
The Equipment Definition specifies the equipment's behavior for each state. Each state can modify the user in many ways, such as:
Modify Skeletal Meshes assigned to certain slots. For example, replacing a shirt with an armor vest.
Hide Component Slots conflicting with the current state. For example, hiding facial hair when a mask is added.
Spawn Actors with additional features needed to represent an item. For example, spawning weapons with their own logic.
Link or unlink Animation Layers, which is useful to modify stances for certain types of equipment. For example, switching from unarmed to sword and shield animations.
Apply gameplay elements, such as Attributes, Effects, and Abilities.
Equipment Definitions are a Primary Data Asset, represented by the class NinjaEquipmentDataAsset
. You can create new definitions using the Context Menu and navigating to the Inventory category.
Once configured, the Equipment Definition is set to an item via the Equipment Fragment. You can reuse Equipment Definitions across different items.
Configuring Assets for States
While configuring your assets for each state, keep the following general concepts in mind:
Unused Slot Tags: These are Slot Tags that will be hidden while the state is active.
Slot Tag: Refers to a Container/Mesh Component or Socket that can be used as the placement anchor.
Socket Name: Applicable to Mesh Components that must be attached to different sockets.
Compatibility Checks: You can use or create checks that must be valid for the asset to be used. This is useful to handle things like different body types.
Scene Component Selector: Allow you to determine where a given Slot should be encountered. By default, this is the Character Mesh, but you might want to use other selection rules.
Equipment Instance
The Equipment Fragment is responsible for monitoring the container in which its owning item is currently stored.
Once the item is stored in an Equipment Slot — a container with the Equipment tag — its Equipment Fragment will initialize the Equipment or synchronize its state.
Initializing the equipment involves providing the item along with its Equipment Definition to the Equipment Manager, which will create a new Equipment Instance and replicate it to all clients.
The Equipment Instance is responsible for managing the equipment's state and performing any changes to the owner, as per the state's configuration.
tip
Extending the Equipment Instance
Since the Equipment Instance primarily handles state management, modifications to this class are generally unnecessary unless you need to override how certain state elements are handled or introduce new ones.
note
Equipment Tags
Equipments can be identified and classified by tags. Obtaining the Equipment Tags will return all tags from the backing item and current container.
State Management
Equipment Instances can change their current states in one of two ways:
By being moved into an Equipment Slot that sets a default state for its items. This is tracked by the Equipment Fragment.
By activating the State Gameplay Abilities, which target a specific Equipment Instance.
Once these events are detected, the Equipment Manager will synchronize the correct Equipment Instance, ensuring that the appropriate state is updated.
Equipment Actors
Equipment Actors are used when an item's Equipment requires more complex logic or visual representation.
A common example would be creating weapons, which may require additional logic, such as performing melee traces or executing their own Animation Blueprints.
Equipment Actor Interface
Any Actor can be used for this purpose, but they must implement the EquipmentActorInterface
. This interface includes a few important methods:
Getters and Setters for the Equipment Instance that manages the actor, allowing access to the item, manager components, and pawn.
A function that marks the equipment as the Effect Causer when Gameplay Effects are applied from it. For example, weapons should typically be marked as the Effect Causer of a damage effect.
tip
Multiple Equipment Actors
A state can have multiple actors attached to it, but usually, only one should be marked as the Effect Causer.
Default Equipment Actor
The framework provides a base implementation of EquipmentActorInterface
, which can be used as the parent class for specific Equipment Actors.
This class provides the following features:
Configures minimal replication settings, including replicating the Equipment Instance.
A default boolean property that can be toggled to determine if the equipment is an Effect Causer.
Equipment Slots
An Equipment Slot is a placement marker for equipment in the inventory. Slots are identified by Gameplay Tags, which can link them to specific Mesh Components, or by Sockets.
Configuration
Containers can be configured as Equipment Slots. In this case, they can only store a single item. The item must have an Equipment Fragment and must pass the compatibility query.
The primary characteristic of an Equipment Slot is the presence of the Inventory.Container.Equipment
tag. This tag restricts the container to store only one item.
When Containers are configured as Equipment Slots, the inventory system expects a match between the container tag and a Mesh Component on the avatar with the same tag. You will need to map Containers and Components when your equipment representation is a Skeletal or Static Mesh.
Sockets
Sockets provide another method for defining Equipment Slots. They are particularly useful when your Equipment is represented by an Actor, making traditional Mesh Components less viable.
The mapping between Slot Tags and Skeleton Sockets is done in the Equipment Manager. A common use case would be for weapons that are implemented using Actors.
Default Meshes
You can set Default Meshes for slots without any equipment assigned to them. This is useful when a mesh needs to be displayed to represent an empty slot, such as a shirt or a naked torso.
To configure this, create a new Equipment Slot Setup, and add all appropriate meshes with the correct Slot Tags. This configuration also supports Compatibility Checks, which is useful if you need to support multiple body types using the same Data Asset.
The following example shows what this asset could look like. In the example, setting default meshes for the Head, Facial Hair and the Body.
Skeletal Meshes
Some slots will be Skeletal Meshes representing items worn by the character, such as an Armor Vest or Pants. It's expected that these components will follow the Primary Mesh in any animations.
The most common way to do that is by setting up a Leader Pose Component, so all relevant equipment slots are set as followers of the main mesh driving the animation
When configuring your Leader Mesh, make sure to adjust these settings:
VisibilityBasedAnimTickOption
:AlwaysTickPoseAndRefreshBones
bLightAttachmentsAsGroup
:true
As for your Follower Meshes, make sure to adjust these settings:
bUseBoundsFromLeaderPoseComponent
:true
;bUseAttachParentBound
:true
;
tip
Merge Mesh
In the future, Mesh Merge support is planned as well.