Height Change

Export

The Height Change ability lets a grounded character enter a shorter stance such as crouching or crawling, then return to full height only when there is enough clearance. It coordinates the input, Animator Height parameter, State System state, and character collider rather than merely playing a crouch animation.

Before you begin

  • A character created with Standard Abilities may already have Height Change. Add another instance only when the character needs a separate stance with its own input and animation value.
  • The included Animator Controller uses Ability Index Parameter 3 for Height Change and reads the Height parameter to select the stance. A custom controller needs equivalent transitions.
  • Leave Detect Horizontal Collisions and Detect Vertical Collisions enabled on Ultimate Character Locomotion if the character must remain crouched beneath a low obstacle.
  • Make sure ceilings and other blocking geometry use a non-trigger collider on a layer included in Character Layer Manager > Solid Object Layers.

Configure a crouch stance

  1. Select the character GameObject, then find Ultimate Character Locomotion in the Inspector.
  2. Expand Abilities. If Height Change is not already present, select the plus button and add Height Change.
  3. Keep Height Change near the bottom of the list and below Speed Change, matching the standard character order. Higher-priority movement and airborne abilities can then take control while the stance remains active concurrently.
  4. Set Start Type to Button Down, Stop Type to Button Toggle, and Input Names to Crouch for a press-to-toggle crouch.
  5. Keep Concurrent Ability enabled when the crouch pose should remain available while another compatible ability runs.
  6. Keep State set to Crouch, Ability Index Parameter set to 3, and Height set to 1 when using the included Animator Controller.
  7. For a character without an Animator, tune Capsule Collider Height Adjustment so the capsule matches the shorter stance. The default adjustment is -0.4.
  8. Choose whether Allow Speed Change should permit the Speed Change ability while crouched.

Choose the stance behavior

Toggle or hold the input

The default Button Down start and Button Toggle stop make each press switch between standing and crouching. For hold-to-crouch, keep Start Type as Button Down and change Stop Type to Button Up. An AI-controlled character can instead start and stop the ability manually without an input name.

Coordinate the animation and collider

The standard crouch uses Height 1; 0 represents the standing state. A different nonzero value can select another stance only when the custom Animator Controller defines that value. A value of -1 tells Height Change not to change the Animator Height parameter.

On an animated character, Capsule Collider Positioner follows its configured end-cap targets as the pose changes. Capsule Collider Height Adjustment is used only when the character has no Animator and Capsule Collider Positioner creates its own second end cap. Tune the animation or end-cap setup for an animated character, and tune the numeric adjustment for an animatorless character.

The Crouch state can also change movement or other properties through the State System. Keep that state name aligned with the preset used by the character.

Allow or prevent faster movement

With Allow Speed Change disabled, starting Height Change stops an active Speed Change, and Speed Change cannot start while Height Change remains active. Enable it for a crouch-run or another stance that should retain the configured speed multiplier.

Add another height stance

Height Change supports more than one instance. For a crawl or other alternate stance, add a second Height Change and give it a distinct input or manual start rule, State, and Animator Height value. Make the start conditions mutually exclusive so two concurrent height stances do not activate together.

How Height Change runs

Height Change can start only while the character is grounded. When it starts, it saves the current collider dimensions, activates its configured State System state, sets the Animator Height value unless that value is -1, and requests the configured animatorless capsule adjustment.

Because the ability is concurrent by default, its Height value can remain active while another compatible ability supplies the main Ability Index. This allows an Animator to choose, for example, a jump animation that begins from a crouched pose. Jump and Fall prevent a new Height Change from starting once the character is already airborne.

When Height Change is asked to stop, it tests the character’s original collider shape against Solid Object Layers and ignores trigger colliders. If restoring the standing shape would overlap a solid object, the ability stays active. Once there is room, it restores the collider, resets Height to 0, and deactivates the configured state.

Verify in Play Mode

  1. Keep the character’s Ultimate Character Locomotion component and Unity’s Animator window visible.
  2. Start on the ground and press the crouch input. Confirm Height Change displays (Active), the pose becomes shorter, and Animator Height changes to 1.
  3. Move while crouched and confirm the collider continues to fit the visible pose. Test Speed Change both disabled and enabled according to Allow Speed Change.
  4. Enter a space with a low, non-trigger ceiling while crouched, then request standing. Height Change should remain active and Height should remain 1.
  5. Move into open space and request standing again. Confirm the full collider is restored, Height returns to 0, and (Active) disappears.
  6. If the game permits jumping from crouch, jump while Height Change is active and confirm the intended crouched jump animation uses the persistent Height value.

Troubleshoot Height Change

Symptom Check Fix
Crouch never starts. The character may be airborne, the ability or input may be disabled, or a higher-priority ability may block it. Test while grounded, confirm Enabled and the Crouch input mapping, then inspect the active abilities above Height Change.
The ability becomes active but the pose does not change. The Animator may not contain the Height parameter or transitions for Height 1 and Ability Index 3. Add the Version 3 parameters and compare the ability values with the Animator transition conditions.
The animated pose changes but the capsule does not fit it. Capsule Collider Positioner may have incorrect end-cap targets or height adjustment disabled. Correct the positioner’s targets and settings so it follows the animated crouch pose. Do not use Capsule Collider Height Adjustment as the animated-character fix.
An animatorless character keeps its standing capsule. Capsule Collider Height Adjustment may be 0 or too small. Use a negative adjustment and verify the resulting capsule still remains taller than twice its radius.
The character stands through a low ceiling. Horizontal or vertical collision detection may be disabled, the ceiling may be a trigger, or its layer may be absent from Solid Object Layers. Enable both collision checks and use a non-trigger collider on a solid-object layer.
Sprint stops when crouching or cannot start while crouched. Allow Speed Change is disabled by default. Enable it only when the crouched stance and animations support faster movement.
Two stance animations activate together. Multiple concurrent Height Change instances may share an input or start condition. Give each stance an exclusive input or manual start rule and a distinct Animator Height value.
  • Speed Change controls the movement-speed ability that Height Change can block or allow.
  • Jump and Fall explain the airborne abilities that interact with a persistent height stance.
  • Animator Parameters describes Height, Ability Index, and the other Version 3 parameters.
  • Abilities explains list priority, concurrency, input start and stop types, and shared ability settings.
  • State System explains the Crouch state activated by the ability.
  • Layer Manager explains Solid Object Layers, which control the standing-clearance test.

Developer reference

Height Change uses these Version 3 defaults and runtime rules:

  • Input Name: Crouch.
  • Start Type: Button Down; Stop Type: Button Toggle.
  • State: Crouch.
  • Ability Index Parameter: 3; Ability Int Data: 1.
  • Concurrent Ability: enabled; Height: 1; Capsule Collider Height Adjustment: -0.4; Allow Speed Change: disabled.
  • CanStartAbility requires the character to be grounded.
  • OnHeightChangeAdjustHeight sends the capsule adjustment at start and its inverse at stop. An animatorless Capsule Collider Positioner listens for this event.
  • A normal stop checks the saved capsule, sphere, and box collider shapes against Solid Object Layers with triggers ignored. A forced stop bypasses the clearance test.
  • An active Height Change blocks StoredInputAbilityBase. It also blocks or stops SpeedChange when Allow Speed Change is disabled.