Fix collision normal being referred to as surface normal in PhysicsDirectSpaceState doc

[DinkeyKing]

In the PhysicsDirectSpaceState class references (2D and 3D) the get_rest_info method descriptions state that the returned dictionary's "normal" field contains the surface normal at the contact point, but it's actually the collision normal.

[AThousandShips]

This wording needs to be clarified, as the "collision normal" is the normal of either object, if it's not this object it should be the other one I assume

[AThousandShips]

What would be the difference between the collision normal and the surface normal? From what I recall of physics the collision normal should be that of the surface contact?

[DinkeyKing]

What would be the difference between the collision normal and the surface normal? From what I recall of physics the collision normal should be that of the surface contact?

The collision/contact normal, to my knowledge, is the best direction by which to separate two colliding shapes. From my experience (I'm not an expert.): The collision normal at the contact point of the object often lines up with the surface normal, but, for example, when colliding the shape with a corner < , the collision normal be neither of the surface normals that make up that corner, but somewhere between the two, pointing away from the corner.

[AThousandShips]

Then this sounds good and I'll leave it to the physics team to give their opinion!

[mihe]

The change here is definitely more accurate than what's there currently, especially considering that this is already being called a collision normal in ShapeCast3D.get_collision_normal, which returns this exact normal.

The documentation for these result fields seems to be a bit ambiguous though, with it referring to the hit object as "the colliding object", "the intersecting object" and "the object" all at once.

I would probably rephrase the documentation for the normal to say that it's the collision normal of the query shape, since it describes the direction in which to move the query shape away from the collision and not the hit object. I would probably also specify which direction it's pointing in, for those who might not be familiar with this kind of physics speak.

Lastly, we might as well normalize "the colliding object", "the intersecting object" and "the object" as just "the intersecting object", since that might be a little bit less ambiguous, but would also line up better with most of the existing documentation. This would need to be done for get_rest_info, intersect_point, intersect_ray and intersect_shape.

[mihe]

LGTM. I'm seeing some other things that I'd like to change here, so I can do the above mentioned "normalization" in a separate PR.

[Repiteo]

Thanks! Congratulations on your first merged contribution! 🎉