Collision Normal vs Surface Normal in get_wall_normal()

Help Physics
, ,
1

Godot Version

4.3

Question

Question regarding this line in the documentation for the CharacterBody3D get_wall_normal() function:

Warning: The collision normal is not always the same as the surface normal.

What is the difference between the collision normal of the wall returned by this function and the wall’s surface normal?

For context, I’m working on wall movement, wherein the character will stick to the wall and start climbing when they collide with it. When they do, I’d like to rotate the player basis such that the character is aligned with the wall – to me, it seems like the best way to go about it is to align the player’s y basis with the wall normal, and update the x and z bases accordingly.

Here’s the code snippet I’m using so far to align the player with the wall - the wall_normal variable is the Vector3 returned by the get_wall_normal() function:

	player.up_direction = wall_normal
	player.basis = Basis(
		player.start_pos.basis.y, # This is "up" in the level's local space.
		wall_normal, # From the get_wall_normal() function
		player.basis.z # Since this is from a fixed side-on perspective, it stays the same.
	)
	player.basis.orthonormalized()
	state_active = true

It seems like the wall’s surface normal might actually be what I’m looking for here? Or is the collision normal from get_wall_normal() fine? If not, what’s the best way to get the wall’s surface normal?

Thanks!