Item Troubleshooting

On this page you will find a list of common errors that occur during item setup.

Item is not equipping

1) Ensure the item is in the Inventory:

If the item is not there then it hasn’t been added to the Inventory. The item should be added to the Default Loadout or made an Item Pickup.

If the the item name is bold with the suffix “(Slot X)” then the item is equipped.

2) Check the ItemSetManager and ensure there is an ItemSet that contains your item in the correct slot.

The colored indicator gives you the state of your ItemSet:

Green: Active/equipped.
Yellow: Enabled.
Red: Disabled or invalid.

Review your ItemSetRules to ensure there is a rule that will create an ItemSet for your item if the ItemSet does not exist.

Check if a State is disabling the ItemSet or if the related ItemSetRule sets the ItemSet as invalid if the ItemSet is invalid.

3) Check that the CharacterItem is not waiting for an animation event that does not exist.

In the CharacterItem component find the Equip (and Unequip) sections and see if you are waiting for an Animation Event.

Disable the Wait for Animation Event option if you do not have an animation event.

If you do want to use animation events ensure the character animation has an animation state with the event and that they are being played.

4) Ensure the item’s visible GameObject is active.

Double click (or press ‘F’) on the visible item to focus it in the Scene View. It is possible that the scale is so big or so small that it cannot be seen relative to the character. The item may also be very far away from the character. Refer to the item tips page to learn different ways to place your items.

Third Person:

First Person:

If the visible object is visible in the Scene view but not the Game view it might be on the wrong layer. First person items should be on the Overlay layer. Third person visible items should be on the SubCharacter Layer

In first person in can happen that the item is being clipped by the render frustum of the camera. Increase the Bounds setting on the Renderer to fix it.

Or change the Clipping Planes on the camera.

The item is not in the correct location.

By default the item visible object will be parented to their matching ItemSlot component. And their local position, rotation and scale can be set in the First/Third person perspective item component.

To easily place the item in the correct spot, enter play mode and pause the game with the character that has the item equipped. Move, rotate and scale the item or its parent until it is placed perfectly. Copy the component values. Exit play mode and paste the values in the item parent. Or copy the values in a sticky note and paste them in the local offsets of the First/Third Person Perspective component.

In many cases a more versatile solution is to have another Transform to parent the visible object to. These can be identified using an ObjectIdentifier.

This abstraction is often required when using the item on multiple character models if they have different proportions.

In first person view you might not see the first person objects in the scene view. That’s can be caused by the Material Swapper component. On the Main camera and the First Person Camera tick the Manual Swap field on the Material Swapper component to see the items in the scene view. Then you’ll be able to position your items correctly.

The item doesn’t do anything when the Use Ability starts.

Find the item in the hierarchy and scroll to the ItemAction component. The Debug section will contain information of the state of the item.

Try using the item and see if there is anything preventing the item from being used.

Waiting for an animation event or incorrectly setup modules are the most common reason the item won’t be used.

The item locks up after being used preventing any abilities from being used.

This can happen when something prevents the item from completing its use or prevents the use ability from stopping. Find the item in the hierarchy and scroll to the ItemAction component. The debug section will contain information on the state of the item. Toggle the debug option if the inspector info is not enough.

The two common problems are:

Waiting for an animation event or an Animation Event happening earlier than expected.
The TriggerModule used is not compatible with the Animator Controller states and transition. Refer to the TriggerModule section to learn more.

The item locks up randomly or when spamming the input.

This is most likely related to the item waiting for an Animation Event which is not occurring due to the item being stuck in an animation. In the case of random or input spamming the issue is sometimes related to animation transitions not being updated at the correct moment or fast enough.

Ensure the Animator Controller has a way to re-enter the animation state by using the SlotXItemStateIndexChange paramenter and forcing it with a TriggerModule. Ensure the transitions exist for the ItemSubstateIndex values that are setup. Learn more about setting up Item animations here.

Changing perspective makes the item disappear.

The most common culprit is related to placing the item not being rendered in the correct camera because of the layer or the item being placed/scaled incorrectly.

First person items should be on the Overlay layer.
Third person visible items should be on the SubCharacter layer.

The first person item shows up in the third person view (or vice-versa).

This is a simple issue of the visible object being on the wrong layer

First person items should be on the Overlay layer.
Third person visible items should be on the SubCharacter layer.

The characters arms are entering the body in third person when rotating the camera.

This is usually caused by the CharacterIK component. You can use the state system to adjust the weight of the limbs to prevent the arms from entering the body

On the Use Ability the character can also be force rotated in the direction of the use:

The Item Action can also force root motion:

Module became NULL after refactoring its name or namespace.

The modules are serialized by the Unity [SerializeReference] attribute which does not fair well when a class has changed name or namespace. To avoid losing you serialized data specify the previous name/namespace of the class using the [MovedFrom] Attribute:

[UnityEngine.Scripting.APIUpdating.MovedFrom(true, sourceClassName : "MyPreviousClassName", sourceNamespace: "My.PreviousNamespace.Name")]

Ensure all objects are reserialized after using the [MovedAfter] attribute. The attribute can be removed after reserialization.

ERROR: Objects are trying to be loaded during a domain backup. This is not allowed as it will lead to undefined behaviour!

This error happens when a [SerializeReference] object has a missing reference to another asset. This is a Unity bug and there is nothing we can do about it. Unfortunately the error message has no indication of what object is missing a reference and therefore makes it extremely hard to debug. It is suggested to return to a previous commit as soon as this error comes back and trace back where it comes from.

Let Unity know it should fix this issue by voting here.