Player Items

Adding New Player Items

1. To add a new player item, locate the Hands object inside the HEROPLAYER object. Create a new game object in the Hands object and name it as you want, but to keep the structure clean, name it, for example: FlashlightItem

2. Add your player item model with animations to the newly created player item object and name it, for example: FlashlightAnims.

3. (optional) If you want to add a nice sway effect to the item when you move the camera, create a new object inside your newly created item and name it, for example Pivot, and position it at the pivot point in the player item model. Then add the item model object to the Pivot object, as shown in the image at Step 1.

4. If you don't have one, create a new Animator Controller asset. Add your item animation states to it and create transitions between them. After creating the Animator Controller asset and setting up the animation states and transitions, assign the Controller reference in the Animator component of the FlashlightAnims object.

5. To handle all the logic of the player item, create a new script. For this guide, I'll name it Flashlight and derive it from the PlayerItemBehaviour class.

6. After deriving from the PlayerItemBehaviour class, you will be prompted to implement the four main functions that handle when the item is selected or deselected.

using UnityEngine;
using UHFPS.Runtime;

public class Flashlight : PlayerItemBehaviour
{
    public ItemGuid BatteryItem;

    public override void OnItemSelect()
    {
        // do something when the item is selected
    }
    
    public override void OnItemDeselect()
    {
        // do something when the item is deselected
    }
    
    public override void OnItemActivate()
    {
        // do something when the item is activated
    }
    
    public override void OnItemDeactivate()
    {
        // do something when the item is deactivated
    }
}

Your script inspector may look messy after deriving from the PlayerItemBehaviour class. To achieve a clean look, create a new editor script for your player item script and name it, for example, FlashlightEditor.

• In the editor script, derive from the PlayerItemEditor class and override the OnInspectorGUI() function to define how your script should look in the inspector. Here is a code snippet for the FlashlightEditor script:

using UnityEngine;
using UnityEditor;
using ThunderWire.Editors;

namespace UHFPS.Editors
{
    [CustomEditor(typeof(Flashlight))]
    public class FlashlightEditor : PlayerItemEditor<Flashlight>
    {
        public override void OnEnable()
        {
            // when overriding OnEnable(), do not remove the base.OnEnable()
            base.OnEnable();
        }
    
        public override void OnInspectorGUI()
        {
            EditorDrawing.DrawInspectorHeader(new GUIContent("Flashlight"), Target);
            EditorGUILayout.Space();

            serializedObject.Update();
            {
                base.OnInspectorGUI(); // this will draw settings dropdown
                EditorGUILayout.Space();

                Properties.Draw("<ItemObject>k__BackingField");
                Properties.Draw("BatteryItem");
            }
            serializedObject.ApplyModifiedProperties();
        }
    }
}

Make sure to put the editor script in the Editor folder, otherwise you won't be able to find some editor class references.

You can use Properties.Draw("property name") to easily draw your player item script properties. Note that a reference to Properties is only available when you derive from PlayerItemEditor or MonoBehaviourEditor.

If you're unsure how to write editor scripts, you can take a look at the editor scripts that come with the asset for player items. They can be found at Scripts\Editor\Runtime\PlayerItems.

7. Add the Flashlight script to the Flashlight object and set the Item Object reference to the FlashlightAnims object where the Animator is located.

8. (optional) To enable the Item Motions, simply enable the Motion Preset feature and assign the Motion Preset and Motion Pivot. You can also leave the Motion Pivot object unassigned if you want to use the default camera pivot object.

To enable wall detection, you can toggle the Wall Detection feature. This will prevent the player item from clipping through walls or other objects by hiding it when you come close to them.

7. Add your newly created player item to the Player Items Manager component in FPView inside the HEROPLAYER object.

8. To make an item equippable, you can open the inventory builder and enable the Is Usable setting. After that, set the Usable Type to Player Item and assign the Player Item reference.

External Motions

When using a player item, you can define external camera movements to create a realistic camera wobble effect.

1. To enable external motions, go to the player item script and enable Camera Motions.

2. Add external motion states and define a custom Event ID that will be used to identify the state to be played from the player item script.

3. Add motion modules to the motion state. Currently there are only a few, but you can create your own modules very easily.

pageExternal Motions

4. Finally, you can apply external motions by calling the ApplyEffect() method in the Player Item script, which inherits from PlayerItemBehaviour.

You can also adjust the settings of the base External Motion module, which applies motions directly to the camera in the MotionController component in the Default state.