The Melee Weapon Item Action allows the character to attack using a melee weapon such as a sword or a baseball bat. Using the Animator Audio State Set from the parent Usable component the melee weapon can chain animations together allowing for combos. The First/Third Person Melee Weapon Properties component will also be attached to the item and this component contains the properties that are specific for that perspective.

Hitboxes

The First/Third Person Melee Weapon Perspective  contains a “Hitboxes” foldout and within this foldout you can specify the hitboxes that the weapon should use. For most melee weapons you’ll only have one hitbox – a collision box representing the area that the area of the melee weapon that can impact with other objects. In the case of the body item there are four hitboxes: two for the character’s hands and two for the character’s feet. This allows the character to punch or kick using the same item. Hitboxes can use a SphereCollider, BoxCollider, or CapsuleCollider.

In this screenshot the right fist is selected. A Damage Multiplier can be specified which will multiply the Melee Weapon’s Damage Amount by the specified value. This allows certain colliders to inflict more damage compared to others, such as a kick inflicting more damage than a punch.

The Minimum Y Offset and Minimum Z Offset fields specify the relative offset that the collider position needs to be above in order to inflict damage. This is useful for the leg collider as it prevents a hit from occurring when the foot is on the ground. Single Hit should be enabled if the collider should only do damage once per melee attack. The Surface Impact field allows you to specify a Surface Impact for when the melee weapon collides with another object.

You’ll see a colored gizmo rendered in the scene view when the item is selected in the hierarchy:

The color will interpolate between green, yellow, and red. The lower the Damage Multiplier value the more green the hitbox will be. The higher the Damage Multiplier the more red the hitbox will be.

Melee Trail

The melee trail object can dynamically draw a smooth curve indicating the previous position of the melee object. This is most often used when the Melee Weapon is attacking, but it can also always be shown (this is set with the Trail Visibility field). A new melee trail object should be created with the Object Manager:

  1. Open the Object Manager and create a new object of type Melee Trail.
  2. Assign the new trail object to the Melee Weapon’s Trail field.
  3. Create a child GameObject that specifies the location that the trail should spawn at. This object should be created for each perspective and should be a child of the perspective’s visible object.
    First Person Trail ObjectThird Person Trail Object
  4. Specify the newly created GameObject under the Trail Location field of the First Person and Third Person Melee Weapon Properties.
  5. Specify when the trail should show with the Trail Visibility field on the Melee Item.

Combos

If Allow Attack Combos is enabled the weapon can transition to the next attack state before the current attack state has completed. A new combo can be started after the Use Event has been triggered and before the Use Complete Event has been triggered. Lets say that you have the following states listed for your Melee Weapon:

Lets say that the state with an Item Substate Index of 2 is currently playing and the Use Event is triggered after 1 second. The Use Complete event is then triggered 0.5 seconds after the Use Event. With this setup the following flow will occur:

  • The state is started at a time of 0 seconds.
  • Another attack input is received at 0.6 seconds, the current state is not interrupted because the Use Event has not triggered.
  • The Use Event is triggered at 1 second.
  • Another attack input is received at 1.1 seconds, the current state transitions to the next state (with an Item Substate Index of 3) because at this point the Use Event has triggered.
  • Another attack input is received at 1.5 seconds, the current state is not interrupted because the Use Event has not triggered.
  • The Use Event is triggered at 2.1 seconds.
  • The Use Complete Event is triggered at 2.6 seconds.

Impact Callback

When the melee weapon collides with another object the “OnObjectImpact” event will be sent from the built-in Event System. A corresponding Unity event will also be sent. This event allows you to add new functionality when the impact occurs without having to change the class at all. The following example will subscribe to this event from a new component:

using UnityEngine;
using Opsive.UltimateCharacterController.Events;

public class MyObject : MonoBehaviour
{
    /// <summary>
    /// Initialize the default values.
    /// </summary>
    public void Awake()
    {
        EventHandler.RegisterEvent<float, Vector3, Vector3, GameObject, Collider>(gameObject, "OnObjectImpact", OnRespawn);
    }

    /// <summary>
    /// The object has been impacted with another object.
    /// </summary>
    /// <param name="amount">The amount of damage taken.</param>
    /// <param name="position">The position of the damage.</param>
    /// <param name="forceDirection">The direction that the object took damage from.</param>
    /// <param name="attacker">The GameObject that did the damage.</param>
    /// <param name="hitCollider">The Collider that was hit.</param>
    private void OnImpact(float amount, Vector3 position, Vector3 forceDirection, GameObject attacker, Collider hitCollider)
    {
        Debug.Log(name + " impacted by " + attacker + " on collider " + hitCollider + ".");
    }

    /// <summary>
    /// The GameObject has been destroyed.
    /// </summary>
    public void OnDestroy()
    {
        EventHandler.UnregisterEvent<float, Vector3, Vector3, GameObject, Collider>(gameObject, "OnObjectImpact", OnImpact);
    }
}

Inspected Fields

Require In Air Melee Ability In Air

Does the weapon require the In Air Melee Use Item Ability in order to be used while in the air?

Require Counter Attack Ability

Does the weapon require the Melee Counter Attack Item Ability in order to be used?

Consumable Item Type

The ItemType that is consumed by the item (can be null). This ItemType should be specified if the melee weapon use is finite.

Aim Item Substate Index Addition

The value to add to the Item Substate Index when the character is aiming.

Max Collision Count

The maximum number of collision points which the melee weapon can make contact with.

Forward Shield Sensitivity

The sensitivity amount for how much the character must be looking at the hit object in order to detect if the shield should be used (-1 is the most sensitive and 1 is least).

Single Hit

When the weapon attacks should only one hit be registered per use?

Multi Hit Frame Count

If multiple hits can be registered, specifies the minimum frame count between each hit.

Can Hit Delay

The delay after the weapon has been used when a hit can be valid.

Allow Attack Combos

Can the next use state play between the ItemUsed and ItemUseComplete events?

Impact Layers

A LayerMask of the layers that can be hit by the weapon.

Damage Amount

The amount of damage done to the object hit.

Impact Force

The amount of force to apply to the object hit.

Impact Force Frames

The number of frames to add the impact force to.

Impact State Name

The name of the state to activate upon impact.

Impact State Disable Timer

The number of seconds until the impact state is disabled. A value of -1 will require the state to be disabled manually.

Surface Impact

The Surface Impact triggered when the weapon hits an object.

Apply Recoil

Should recoil be applied when the weapon hits an object?”

Recoil Animator Audio State Set

Specifies the animator and audio state from a recoil.

Trail

A reference to the trail prefab that should be spawned.

Trail Visibility

Specifies when the melee weapon trail should be shown.

  • Attack: The trail is only visible while attacking.
  • Always: The trail is always visible.
Trail Spawn Delay

The delay until the trail should be spawned after it is visible.

Attack Stop Trail Event

Specifies if the item should wait for the OnAnimatorStopTrail animation event or wait for the specified duration before stopping the trail during an attack.

On Impact Event

Unity event invoked when the weapon hits another object.