godotengine
ShapeCast2D documentation does not explain what the node does and contains ambiguities
Your Godot version: v4.1.2.stable.official [399c9dc39]
Issue description: The documentation does not help me to understand the intended use-case for this node. In particular, what is its intended purpose as opposed to Area2D? The text refers to differences between it and Area2D, but these differences are not explained.
For example:
It is useful for things like wide laser beams or snapping a simple shape to a floor.
Why is it useful for these? It does not explain why.
How would the reader know in what way the node can be used to help snap a simple shape to a floor?
The RayCast2D docs state:
A raycast represents a ray from its origin to its target_position that finds the closest CollisionObject2D along its path, if it intersects any.
Does the ShapeCast2D also do this? The documentation does not state that. It just makes vague statements about sweeping:
This is similar to RayCast2D but it allows for sweeping a region of space, rather than just a straight line.
The ShapeCast2D documentation should make sense on its own without needing to refer to another Node's documentation page, especially if that Node (RayCast2D) is not further up the inheritance hierarchy.
In terms of style, there is a problem - this sentence contains a dangling modifier and is therefore ambiguous:
This helps to overcome some limitations of Area2D when used as an instantaneous detection area, as collision information isn't immediately available to it.
Available to what? The Area2D or the ShapeCast2D?
I do not know the intended use case for ShapeCast2D so I cannot suggest a fix.
URL to the documentation page (if already existing): https://docs.godotengine.org/en/4.1/classes/class_shapecast2d.html
Shape casting allows to detect collision objects by sweeping its shape along the cast direction determined by target_position.
What is not clear about this? It says exactly what it does
It detects the positions of intersections and what it intersects with, as you can see from the methods
Does the ShapeCast2D also do this
No, as it says it detects multiple intersections, not just the closest
Some more details on how to use it would be helpful, but the documentation says what it is and does
Some more details on how to use it would be helpful, but the documentation says what it is and does
Thanks for the response.
You are correct on both counts.
- Since working out how to use it myself, I can see that the documentation says what it is and does.
- And, the documentation page really isn't that helpful. As you say, to be helpful, it needs more details about how to use it.
The changes I think that need to happen are:
- Make the page stand alone without requiring the new user also read and understand the RayCast2D docs.
- Add an example or other details, so the page is actually helpful.
Perhaps the vague references to actual use cases could be upgraded to full examples with code.
I'm jumping on this for a bit different reasons, but the title of this issue still fits.
I found it unintuitive how the ShapeCast2D works from reading the docs. To me, it seemed like it would do a scan of all the shapes between the source and the target and return the results. This is not how it works however. The first shape that collides with an object stops the cast and whatever objects were in that shape are returned, nothing more. The example (wide laser beam) definitely didn't push me to understand it like this as you'd imagine a wide laser beam to keep going even after being partially block by some object. The only hint that this might be how it works is the part where it says to set your target to (0, 0) for immediate collision overlaps, but even this is a little vague as it doesn't mention the size or position of shape to use to achieve this. I think adding the following would be super helpful:
- How the sweep works
- How to choose a shape size
- How the ShapeCast2d decides the number of scans to do with the shape along the sweep. It's not just a simple cast size / shape size and it's not obvious what it's doing. Different sizes produce different amounts of overlap between the shapes along the cast.
You chose the shape with shape, you can't change it's size directly like that, you need to use the shape you want
It returns multiple intersections if there are any, what does get_collision_count return?
What do you mean with number of scans? Do you mean how small steps it works with?
Trying to add pictures to make it more clear what I mean. Note that I'm describing the behavior I'm seeing, I don't know the underlying engine code.
In the photo above, the cast will start with the first (left most) rect and keep moving to the next rect to check if anything is inside it until it find a rect along the sweep that contains some object. Once the shape that contains the red obj is tested, the cast ends and 1 result is returned containing the red obj. I would've expected all shapes to be tested and all results returned (both the red and green obj returned)
If I make the shape bigger, the shapes used along the cast start to overlap, and it's unclear how the number of tests to do is being chosen.
I.e. Why are there not just 5 shapes along the cast in this photo? The cast is 100px long and the shape is 20px wide. 5 shapes would cover it.
If I make the shape size the size of the cast itself, I get this:
Still a little strange since it seems like it'll do 3 check and return objects before the cast's (start) position and after the cast's target pos. This cast will still only return the red obj.
Finally, setting the target to (0, 0) and moving the cast's position halfway between the start and intended target positions would return the results I initially expected
Both the green and red objects will be returned from the result of this cast
Another weird quirk is that it seems like it can miss things with a small shape size (this one I didn't actually test, but I'm just going by what the visuals are showing).
How this all works isn't really described in the docs. Reiterating what I said above, the docs should describe how the scan process works (Based on shape size, it'll do X scans and return results for the first shape scan that includes something), how the shape size effects the scan, how the number of tests the scan will do are chosen.
That's not how it works as far as I know, I'm not sure what you're basing these assumptions on
Id suggest opening a bug report as this seems to be an issue, but without more details I can't tell if it's configuration error or a bug
I wouldn't say they're assumptions (except the last one I mentioned I didn't test). It's the behavior I see when I use the ShapeCast2D. I'll open a bug report.
Looking at the actual code I'd say that's not at all how it works, no matter how it looks, so it's something else that's going on
After playing around with an MRP, it is definitely not exactly what I initially thought of it just returning at the earliest chance, but it's still definitely very weird behavior overall.
edit - Accidently left out the "not" in front of exactly initially. Added it now. I meant to say it's not behaving how I thought here, sorry.