In Air Melee Use

In Air Melee Use performs a dedicated melee attack after the character has left the ground, then drives a controlled rise, fall, and landing response. Use it for an aerial slash, downward strike, or ground-slam sequence that should not be available while grounded.

Before you begin

The character needs:

• an Inventory with the melee Character Item owned and equipped;
• a Character Item with a Melee Action;
• a melee Animator state that is allowed while airborne;
• a Look Source and normal Use prerequisites; and
• for a typical player-controlled sequence, Jump and Fall configured on the character.

In Air Melee Use resolves the equipped item by Slot ID and its component by Action ID, then discards every selected action that is not a MeleeAction. Shootable, Throwable, Magic, and general Usable Actions cannot run through this ability.

Configure In Air Melee Use

1. Select the melee Character Item and add or open the Melee Action intended for the airborne attack.
2. Give the action a unique ID. Use a separate action when the aerial attack needs a different animation, hitbox, impact, or damage setup from the grounded attack.
3. Configure an enabled Trigger module and its Animator Audio State. Disable Require Grounded for the airborne state.
4. Use the In Air Trigger when the same action must reject the normal Use ability while the character is airborne. Keep Require In Air Ability In Air enabled; it starts enabled in the released Version 3 source.
5. Configure the Melee Action’s Use Event, Use Complete Event, attack timing, collision module, and impact modules. The actual hit still occurs through the action’s normal module flow.
6. Select the character, expand Item Abilities on Ultimate Character Locomotion, select the plus button, and add In Air Melee Use.
7. Keep the inherited player defaults unless another input is intended: Start Type Button Down, Stop Type Button Up, Input Names Fire1, State Use, and Item State Index 2.
8. Set Slot ID and Action ID to the equipped Melee Action. Slot ID starts at -1 and Action ID starts at 0; a specific slot is safer when the two hands have different airborne attacks or eligibility.
9. Start with the built-in force values, then tune them against the character’s gravity, jump height, animation, and desired landing time.
10. Set On Grounded Substate Index to the Animator substate that represents the landing phase. Its starting value is 11.
11. Optionally assign Ground Impact and tune the positional and rotational camera recoil for the landing.
12. Keep this ability above Aim in the Item Abilities list when Item State Index 2 should control the aerial animation, then verify the complete takeoff-to-landing sequence in Play Mode.

The ability allows duplicate rows but cannot receive another start while it is already active. Use separate rows for different slots, Action IDs, or inputs, not to restart one aerial attack in mid-sequence.

Tune the airborne motion

The ability applies its forces relative to the character rather than in fixed world axes.

The downward force is applied once, on the first Late Update where local vertical velocity is below zero. It is not a continuous gravity replacement. Tune it after the normal Jump and gravity settings so the character does not hover at the apex or snap unnaturally to the ground.

The ability’s root-motion position and rotation settings default to No Override, preserving the locomotion controller’s current configuration. The Melee Action’s Force Root Motion Position and Force Root Motion Rotation flags default to disabled. Check both layers when tuning a force-driven trajectory; disabled action flags do not turn off root motion already enabled on the controller. Enable those action flags only for an airborne clip authored to control that motion, then retest forces and landing detection together.

Common scenarios

• Aerial slash: keep a modest upward force, use a lighter downward force, and let the normal melee Use and Use Complete events end the hit before landing.
• Downward strike: reduce or remove the upward push, use a stronger downward force after the apex, and keep a distinct landing substate.
• Ground slam: assign a Ground Impact, retain noticeable rotational recoil, and time the attack collision separately from the landing effect. Ground Impact is visual and audio feedback; the Melee Action’s impact modules still own damage.
• Different attacks per weapon or hand: use a slot-specific row and matching Action ID so one equipped item cannot accidentally supply another item’s aerial action.

Coordinate Jump, Use, and the melee action

In Air Melee Use can start only while Grounded is false. When it starts, it stops an active Jump and an active normal Use ability. While the aerial ability remains active, it blocks another Jump or Use from starting.

The Melee Action is still responsible for whether its modules can begin, when the hitbox becomes active, which targets are impacted, and when use completes. The ability only adds the airborne eligibility, force arc, landing substate, Ground Impact, and camera response.

With Slot ID -1, the inherited Use lookup checks every active slot before this subclass removes non-melee actions. The released Version 3 runtime can retain a Melee Action that failed its initial module eligibility check when another slot qualified. Prefer separate slot-specific rows when the equipped melee items can differ in cooldown, combo state, or another start condition.

How it runs

1. Input asks In Air Melee Use to start after the character is no longer grounded.
2. The inherited Use checks UI blocking, the Look Source, equipped Slot ID, Action ID, and each action’s module conditions.
3. In Air Melee Use removes every selected action that is not a Melee Action. It starts only when at least one Melee Action remains.
4. Starting the ability stops an active Jump or normal Use, activates the Use State, supplies Item State Index 2, begins the selected melee module flow, and applies Upward Force over the configured frames.
5. The Melee Action performs its attack at Use Event and supplies its normal module-composed Item Substate Index.
6. After local vertical velocity drops below zero, the ability applies Downward Force once over Downward Force Frames.
7. With the starting Allow In Air Stop value disabled, a normal stop request cannot end the ability while airborne.
8. When the grounded event becomes true, the ability asks any still-waiting Use Event to invoke its slot event, spawns Ground Impact, and sends the configured secondary camera forces.
9. If the Melee Action can stop, the ability ends immediately. Otherwise it supplies On Grounded Substate Index until the action completes and releases the ability.

The landing fallback in step 8 invokes the slot-specific Use Event. It resolves a waiting event only when Wait For Slot Event is enabled on that action’s Use Event. With animation-event-only timing, make sure OnAnimatorItemUse occurs before landing or use a tested timed event so a short fall cannot leave the action waiting.

Verify in Play Mode

1. Stand on the ground and press the In Air Melee Use input. Confirm the ability does not start.
2. Jump, wait until the character is airborne, and press Fire1. Confirm In Air Melee Use (Active) appears and the active Jump ability stops.
3. Confirm the selected component is the intended Melee Action ID. A Shootable, Throwable, Magic, or general Usable Action with the same ID must not participate.
4. Watch the trajectory frame by frame. Confirm the upward force begins at ability start and the downward force is applied once after the local vertical velocity becomes negative.
5. Confirm the melee hitbox and damage occur at the Melee Action’s configured attack timing, not merely when the airborne ability starts.
6. Try Jump and normal Use again while the ability is active. Confirm both are blocked.
7. Land before the action has fully completed. Confirm Item Substate Index changes to On Grounded Substate Index, then returns after the action releases the ability.
8. Confirm the assigned Surface Impact appears at the grounded raycast hit and the camera receives the expected positional or rotational recoil.
9. Repeat from a very short drop and a tall jump. Confirm Use Event, Use Complete Event, landing substate, and stop behavior remain consistent.
10. Test every supported weapon, slot, perspective, gravity direction, and time scale used by the project.

Troubleshoot In Air Melee Use

• The ability will not start: confirm the character is not grounded, the Character Item is equipped in Slot ID, Action ID matches a Melee Action, a Look Source is attached, and the pointer is not over UI while Block Over UI is enabled.
• The normal Use ability performs the aerial action instead: use the Melee Action’s In Air Trigger and keep Require In Air Ability In Air enabled, then target the intended Action ID from this ability.
• The ability becomes active but no attack occurs: disable Require Grounded on the selected Animator Audio State and check the Melee Action’s main Trigger, Use Event, attack timing, collision module, and impact modules.
• A gun, throwable, spell, or custom action does nothing through this row: this is expected. In Air Melee Use filters for Melee Action instances after the inherited Use lookup.
• The character rises or falls too sharply: adjust force magnitude and frame count together, then retest with the actual gravity, Jump, time scale, and root-motion settings.
• The downward force never applies: confirm the character’s local vertical velocity becomes negative before landing. A short fall or root-motion clip can reach ground before that Late Update condition occurs.
• The attack never stops after landing: check Use Complete Event and whether the Melee Action can stop. If the action may land before Use Event, enable Wait For Slot Event or use reliable animation/timed event placement.
• The landing animation is wrong: confirm Item State Index 2, the aerial action’s normal substate, On Grounded Substate Index 11, and this ability’s priority above Aim.
• No landing effect appears: assign Ground Impact, confirm the grounded raycast hits a configured surface, and verify the Surface System setup.
• The camera does not react on landing: check both recoil ranges and confirm the active camera listens for the secondary camera-force event. Positional recoil starts at zero.
• Jump or normal Use stops when the aerial attack begins: this is expected. In Air Melee Use explicitly stops and then blocks both ability types while active.
• Enabling Allow In Air Stop does not let the attack stop: the released Version 3 condition is inverted. When Jump is inactive, enabling this field prevents a normal stop both in the air and after grounding. Leave it disabled and use a force-stop or a project-specific subclass when the attack must end before landing.

Related tasks

• Use explains Slot ID, Action ID, input, Animator timing, and the shared usable-action lifecycle.
• Melee Action explains attack, collision, impact, recoil, and Trigger modules.
• Jump and Fall explain the locomotion abilities surrounding the aerial sequence.
• Animator Parameters explains Item State Index and Item Substate Index.
• Surface Impacts explains the optional Ground Impact response.
• Item Abilities explains list order and ability concurrency.

Developer reference

The writable public properties are UpwardForce, UpwardForceFrames, DownwardForce, DownwardForceFrames, AllowInAirStop, GroundPositionCameraRecoil, and GroundRotationCameraRecoil. On Grounded Substate Index and Ground Impact are serialized protected fields without public properties in the released class.

In Air Melee Use inherits the Use properties and events described on the Use page. It cannot receive multiple starts. Its CanStartAbility override requires an airborne character and at least one selected MeleeAction; ShouldStopActiveAbility and ShouldBlockAbilityStart coordinate Jump and normal Use.

The ability listens for OnCharacterGrounded (bool grounded). On landing it calls the Surface Manager and sends OnAddSecondaryCameraForce (Vector3 position, Vector3 rotation, float) with a duration value of 0. It does not emit a unique In Air Melee Use event; use the standard character item-ability lifecycle or inherited Use events when another system needs to observe it.