> For the complete documentation index, see [llms.txt](https://malbersanimations.gitbook.io/animal-controller/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://malbersanimations.gitbook.io/animal-controller/main-components/manimal-controller/states/ledge-grab.md). # Ledge Grab ## Ledge Grab **State ID:** 8 The **Ledge Grab** state quickly climbs a flat ledge. It raycasts ahead, finds valid ledges, then plays a climbing animation. One state can contain multiple **profiles**. Each profile has its own animation, height, and detection settings. Use profiles for grounded, jumping, or falling approaches.

## Creating the state Create a **Ledge Grab** state in either way: * Select **+** in the animal's **States** list. Then select **Climb → Ledge Grab**. * Duplicate an existing **Ledge Grab** state asset. Add it to the animal's **States** list.

## Priority Set this state above [**Idle**](/animal-controller/main-components/manimal-controller/states/idle.md), [**Locomotion**](/animal-controller/main-components/manimal-controller/states/locomotion.md), and [**Fall**](/animal-controller/main-components/manimal-controller/states/fall.md). Set it below [**Death**](/animal-controller/main-components/manimal-controller/states/death.md). States use priority. Give [**Jump**](/animal-controller/main-components/manimal-controller/states/jump.md) or [**Fly**](/animal-controller/main-components/manimal-controller/states/fly.md) a higher priority to interrupt ledge grabbing. ## How it works The state casts rays ahead of the character to find a ledge. Target colliders must use the **Ledge Layer**. They can also match the optional **Ledge Tags** filter.

### Detection rays | Ray | Color | Condition | Purpose | | ------------------ | ------ | ------------------ | ------------------------------------------------ | | **Top / Forward** | Green | Must be **clear** | Confirms no obstacle exists at ledge-top height. | | **Ledge (Down)** | Red | Must **hit** | Finds the flat top surface. | | **Wall (Forward)** | Yellow | Must **hit (red)** | Finds the vertical wall below the ledge. |

The state can activate when the top ray is clear. The down and wall rays must hit valid colliders. The top surface must be within **Min Terrain Angle**. The wall must exceed **Wall Front Angle**. ### Ledge size validation Detection can find ledges that are too small to stand on. An optional footprint check rejects thin poles, small blocks, and stacked boxes. Leave **Min Ledge Depth** and **Min Ledge Width** at `0` to disable this check. | Ray | Color | Condition | Purpose | | ------------------- | ------- | ----------------- | ------------------------------------------------------- | | **Depth floor** | Magenta | Must **hit** | Confirms the ledge extends back by **Min Ledge Depth**. | | **Depth clearance** | Green | Must be **clear** | Rejects walls behind the ledge lip. | | **Width** (×2) | Orange | Must **hit** | Confirms the ledge width meets **Min Ledge Width**. | **Effective value = Global + Local.** Depth and width each have a state value and a profile value. The footprint check uses their sum. ## Activation methods ### Input The state activates when its **Input** is pressed, and the rays find a valid ledge.

### Automatic Enable **Automatic** to activate as soon as a valid ledge is detected.

### Automatic by state Use **Automatic By State** to make ledge grabbing automatic during selected states. Examples include **Climb**, **Jump**, **Fall**, and **Swim**. ### Zones A Zone can force the state to try activation. ### Reactions Animal Reactions can activate the state from code or events. See [**Reactions**](/animal-controller/main-components/reactions.md). ## Exit conditions The state exits when the active profile reaches **Exit Time**. This value uses normalized animation time. The state then calls `AllowExit()`. Lower-priority states can activate. The character returns to **Grounded**. ## Animator setup Use a sub-state machine for Ledge Grab animations.

The Transition Enter Condition of this state is State=8

### Transition duration Use **State = 8** for the transition into the sub-state machine. Keep its duration short. The default is **0.1 seconds**. {% hint style="danger" %} **Align Offset** is tightly coupled to the transition duration. Update it when the duration changes. {% endhint %}

### Core animation Tag every core animation with the state ID name: **LedgeGrab**. The **Enter Status** value selects the profile animation.

Value of the State Enters Status Parameter on the Animator

Value of the Enter Status on the ProfileState

## Configuration tabs ### General Basic state settings shared across animals.

### Tags

Enable **RootMotion**, **+Rot**, **+Pos**, and **Ignore Lower States**. Disable the remaining modifiers. The character is not grounded during this state. Gravity and ground orientation are disabled. ### Limits

Disable the state for selected character states, modes, or stances. For example, disable ledge grabbing while swimming underwater. ### Speeds

No speed modifiers are required. Root motion or profile curves drive all movement. ## Ledge parameters

### Ledge Layer Layer used to identify climbable surfaces. ### Ledge Tags Optional tag filter. Only matching collider tags count as ledges. ### Automatic Climb automatically near a valid ledge. No input is required. ### Automatic By State States during which Ledge Grab behaves automatically. ### Kinematic Sets the character Rigidbody to kinematic while active. This prevents colliders interfering with the ledge. ### Disable Main Collider Disables the Main Collider while active. It is restored on exit. ### Wall Distance Target distance between the character and the wall.

### Wall Front Angle Minimum angle between the wall normal and character forward required for activation. ### Min Terrain Angle The top surface must be flatter than this angle.

angle 35 wont activate the state if the value of Min Terrain is lower than 35

### Forward Length Global distance for the green forward detection ray. ### Wall Checker Vertical offset below the ledge that confirms a wall exists.

### Min Ledge Depth Global minimum depth behind the ledge edge. This is added to each profile's local value. Set `0` to disable the global depth check. ### Min Ledge Width Global minimum sideways width. This is added to each profile's local value. Set `0` to disable the global width check. ### Hit Transform Name of a child transform that stores the ledge ray hit point. Use it for UI or aiming. ### Update Hit Transform UI Updates the **Hit Transform** during every check. Enable it only for UI or aiming, as it adds raycasts. ### Add Hit Transform To Aim Uses the **Hit Transform** as a temporary Aim target while a ledge is detected. ## Profile settings

### Name Profile identifier. ### Enter Status Animator **Enter Status** value that selects this profile's animation.

"Ledge Grab" has a Enter Status of 0 and "Step Up 1 Meter" has Enter Status of 1

### Max V Speed Maximum vertical speed for this profile to be checked. Use `0` to ignore speed. ### Last State Only checks this profile when the selected state was previously active. ### Check Upwards Casts an upward ray to confirm no roof or overhang blocks the ledge. ### Only Grounded Only checks this profile while the character is grounded. ### Forward Multiplier Local multiplier for the global **Forward Length**. ### Height Vertical offset of the green forward ray. ### Ledge Exit Distance Length of the red down ray that finds the ledge top.

### Min Ledge Depth Extra depth added to the global **Min Ledge Depth** for this profile. ### Min Ledge Width Extra width added to the global **Min Ledge Width** for this profile. ### Exit Time Normalized animation time that calls `AllowExit()`. The default is `0.9`. ### Align Offset Horizontal (X) and vertical (Y) alignment offset. Use it to align the character with the ledge.

{% hint style="warning" %} This value is tightly coupled to the Animator transition duration. {% endhint %} ### Orient Faces the character perpendicular to the wall normal.

### Orient Smoothness Smoothing speed for orientation to the wall. ### Additive Position Adds procedural movement when the animation has little or no root motion.

### Height Speed Magnitude of the additive vertical push. ### Forward Speed Magnitude of the additive forward push. ### Height Curve Scales the vertical push over the animation. ### Forward Curve Scales the forward push over the animation.