Class Reference for ShapeCasts should mention processing each physics_frame

[charjr]

Godot Version 4.4.1

Issue

When learning about ShapeCast nodes I was unsure when I get collision results.

Immediate collision overlaps can be done with the target_position set to Vector3(0, 0, 0) and by calling force_shapecast_update() within the same physics frame.

I guessed that collision_results updated once per physics frame, but I wasn't sure. It looked like I wanted force_shapecast_update, as I'm using it for on-demand sweeps. So I poked around there:

● void force_shapecast_update()

Updates the collision information for the shape immediately, without waiting for the next _physics_process call. Use this method, for example, when the shape or its parent has changed state.

Note: Setting enabled to true is not required for this to work.

This implies that it updates during each _physics_process and the note made me suspect that setting enabled to false would stop it from updating collision_results every physics frame.

enabled says this:

If true, collisions will be reported.

So collisions wont be reported, but are they still updated?.

I had to dig the cpp code to get a better idea.

Then I looked at Raycasts:

RayCast3D calculates intersection every physics frame, and it holds the result until the next physics frame. For an immediate raycast, or if you want to configure a RayCast3D multiple times within the same physics frame, use force_raycast_update().

This was incredibly clear and explicit in what happens and I immediately knew when and how I would get the results.

I found enabled equally lacking though.

Solution

I think the docs for ShapeCasts need to use the same wording as RayCasts.

I also think both docs need better wording for enabled: does it stop calculations/updates, or only reports? Are these the same thing? If so the wording should be consistent.