godotengine / godotengine/godot-docs
Class Reference for ShapeCasts should mention processing each physics_frame
- Dominant language
- reStructuredText
- Stars
- 5.7k
- Forks
- 3.8k
- Avg merge
- 1d 20h
- Merged PRs (30d)
- 25
Description
## 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.
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.