Ledge climbing allows characters to grasp and then climb up on to ledges.
This article refers to the ledge climbing capabilities of the movement Wall Movement->Ledge Climbing/Standard. Other types of ledge climbing are available via (for example) Special Movement->Mecanim but they are not covered in this article.
An older video (pre-release but still mostly accurate) walking through 2D ledge climbing is available here (Youtube).
Ledge climb has the following controls:
|Grab Ledge||Face towards ledge (not a control, but you wont grab a ledge you aren't facing so you may need to press towards it).|
|Climb ledge||Press up while grasping ledge.|
|Dismount Ledge||Press down, away or jump while grasping ledge.|
You could extend the class and override the following methods to change the controls:
Ledge Detection Overview
In order to determine if the character should reach out for or grab on to a ledge a number of conditions need to be met. When setting up your ledge climb its important to understand these as a failure at one point will cause the ledge climb to fail.
Reach and Grasp Decision
The following decision tree describes how the standard ledge climb determines if and when a reach and grasp should be triggered.
|Wall Detected||Character||Uses the characters wall detection in combination with the side colliders to determine if the character is near a wall.|
|Required Colliders||Character||Checks that enough colliders are colliding. Available in editor but usually you don't need to adjust (default 2). If its too high you won't be able to grab thin platforms.|
|Ledge Detected||Movement||Determine if the wall we are hitting is a ledge. Handled by the Ledge Detection Method. Use NONE if you want to put all your ledges in a specific layer or give them all a tag. Use BOX_COLLIDER if your ledges are in the standard layer but are always use BoxCollider2D. Use CIRCLE_CAST to handle more complex geometry.|
|Within Reach Limits||Movement||
Is the character the right y distance from the ledge. This is a min and max offset that specifies the distance between the ledge and the characters pivot.
To set leeway use the Grasp Leeway setting found in the Details section of the ledge climb settings. You can also press the Default button which will estimate your characters reach point based on their overall height.
|Gap Detected||Movement||Is there room for the character to stand up after the ledge climb (see image below). Use NONE if using a specific tag or layer for ledge climbing. Use RAYCAST_SIDES to use ray casts to check for room.|
|Input correct||Movement||Check that the user is pressing towards the ledge.|
|Reach Time Met||Movement||
In order to provide smoother animations you can require the character to reach out for a ledge for a minimum amount of time before they can grab it. Note that this makes it harder for a player to grab the ledge so use with caution.
To set leeway use the Minimum Reach Time setting found in the Details section of the ledge climb settings.
Sprite Set-up (2D)
To work with sprites set the Animation Targeting to SPRITE_PIVOT.
Each frame in the animation for the ledge hang and ledge climb animations should be set up such that the sprite pivot is the point that the character is hanging from (i.e. typically the hand).
Sample sprites with pivots set up around the hand:
Model Set-up (3D)
To work with 3D models set the Animation Targeting to BAKED.
Similar to sprites the character animations should pivot around the ledge hand point. The animations should be set up such that the movement is baked in to the animation:
You would expect to see red loop match indicators as the X and Y positions will not be matched.
When you set the state to baked you need to pick which bone the character hangs from (called the Grasping Bone in the settings). Typically its one of the hand bones.
The ledge offset is the distance between the detected ledge hang point (for example the corner of the BoxCollider2D) and the characters pivot point in the ledge hang animation:
The red circle indicates the pivot. The small blue arrow indicates the offset, it is used to slightly tweak the hang position of the character. Typically this is more useful for 3D models or when you are using CIRCLE_CAST ledge detection.
The stand offset is the difference between the pivot point of the final ledge climb frame and the first standing frame. For sprites this is also the same as the distance between the default pivot (for example sprites centre) and the pivot of the first ledge climb frame.
Sample stand offset for a sprite:
The red circles indicates the pivots. The blue arrow indicates the stand offset.
Note: if you are using gap detection the stand offset will be used as part of gap detection too (we need to check where the character will be standing after the offset is applied and make sure there is a gap).
Ledge Grasp to Ledge Hang - Animation Transition
In order to sync animations your mecanim animator needs all of the ledge climb states, and there must be an automatic transition from LEDGE_GRASP to LEDGE_HANG (usually with exit time as 1). See the Mr Sprite sample for an example: