Repository: godot
Issue: ShapeCast2D debug visuals and intended behaviour
Labels: topic:physics,needs testing

### Tested versions

- Reproducible in v4.2.stable.official [46dc27791]

### System information

Godot v4.2.stable - Windows 10.0.22000 - Vulkan (Forward+) - dedicated NVIDIA GeForce RTX 2070 SUPER (NVIDIA; 31.0.15.3713) - Intel(R) Core(TM) i7-9700K CPU @ 3.60GHz (8 Threads)

### Issue description

This issue is being created in relation to discussion in https://github.com/godotengine/godot-docs/issues/8508. The way the ShapeCast2D works isn't super intuitive, and I'd like the documentation to being updated to better describe how it works. I'd also argue there are some UI bugs with how the ShapeCast2D is shown within the Godot Editor. And finally, there may (?) be some bugs with how the ShapeCast2D works.

Here's what I would say is the UI bug. The ShapeCast2D look like it's checking several small shapes along the sweep path, but is leaving gaps. This however isn't actually what's happening as you can see in my example that the object is still detected.
![image](https://github.com/godotengine/godot/assets/4305699/5bc3799e-57f6-4dc6-baee-d74bb3d3b281)

When you have multiple objects in the shapecast and your shape is smaller, it seems to often only show results for the for the first object that appears in one of the shapes. E.g.
![image](https://github.com/godotengine/godot/assets/4305699/7812eaeb-43cc-411c-b493-21214f6838da)
![image](https://github.com/godotengine/godot/assets/4305699/ed264e1d-e64f-4e75-859a-ccb8c80a76c5)
![image](https://github.com/godotengine/godot/assets/4305699/853f4bf5-a765-45f4-a7fb-395427506e40)
![image](https://github.com/godotengine/godot/assets/4305699/e6e66a3d-53da-49d0-b16a-ad9458f54765)

Currently the docs make it seem like all objects in the cast will be returned and this is not the case (For the wide laser beam example, I'd expect it to keep going if only partially blocked). To get the behavior I expect (all bodies in the shapecast returned), you have to set the target to (0, 0), make the size of the shape the size of the whole shapecast you want, and move the cast halfway between the start and intended target locations. E.g.
![image](https://github.com/godotengine/godot/assets/4305699/59bb02c7-8d19-4553-96d2-7ad0165d6e49)
![image](https://github.com/godotengine/godot/assets/4305699/f81c3ff4-a95d-4e47-b2a2-766b0fe08dcb)

This may just be related to the initial UI bug I've mentioned but it's not intuitive how the UI is displaying the shapecast when the sizes are a little bigger either. Here we can see overlapping shapes when using a width of 10px for a 100px wide cast. Why are there not just 10 shapes?
![image](https://github.com/godotengine/godot/assets/4305699/f7ab0f0a-c8d5-4162-a2b0-c726949b2e43)

Here's another weird case I just noticed while finishing this write up. If I have the 2 object near each other at the start of the cast they are both returned, and slightly further in they have to be inline to be both returned. Near the end of the video, green ends up being the one collider returned a couple times even though it's behind blue.

https://github.com/godotengine/godot/assets/4305699/457c2330-a24a-4a1e-ac26-848423b8b93e


In summary:
- I think there are some UI bugs to how the ShapeCast2D is displayed versus how it works
- I think the docs don't accurately (or at least in enough detail to be understood by a user) describe how the ShapeCast2D works.
- There may be bugs with how this shapecast works? It may be intended behavior, but I haven't been able to grok what's supposed to be happening.

cc @AThousandShips from the related docs issue.

### Steps to reproduce

- Open the MRP and turn on Visible Collision Shapes
- Play around with the sizes the shape and position of the objects (you can drag them around) to recreate the states in the issue description
    - E.g. With the default size (5), move blue near the beginning and green near the end. See that only blue is returned. Move green in front of blue and see that now green is only returned. Moved them vertically inline and see that both are returned.
     

### Minimal reproduction project (MRP)

[ShapeCast2DTest.zip](https://github.com/godotengine/godot/files/14131921/ShapeCast2DTest.zip)