godotengine / godotengine/godot-docs
PhysicsServer2D Capsule Shape Data Documentation Ambiguity
- Dominant language
- reStructuredText
- Stars
- 5.7k
- Forks
- 3.8k
- Avg merge
- 1d 20h
- Merged PRs (30d)
- 25
Description
**Your Godot version:**
4.5
**Issue description:**
In page Godot's online documentation for 4.5, "PhysicsServer2D", the documentation below function `shape_set_data` is inherently ambiguous regarding `SHAPE_CAPSULE` type objects.
For `shape_set_data`'s documentation, the parameter for `SHAPE_CAPSULE` type shapes is stated to be "an array of length two (or a [Vector2](https://docs.godotengine.org/en/4.5/classes/class_vector2.html#class-vector2)) containing a [float](https://docs.godotengine.org/en/4.5/classes/class_float.html#class-float) `height` and a [float](https://docs.godotengine.org/en/4.5/classes/class_float.html#class-float) `radius`" -- but it is left ambiguous as to if the first variable is supposed to be the height and the second variable is to be the radius, or vice versa.
Throughout the rest of this manual, there exists no explicit documentation stating whether the first value (when setting/getting `SHAPE_CAPSULE` shape related data from `PhysicsServer2D`) should be the `radius` or the `height`.
Additionally, contrary to the implied ordering of `(height, radius)` as implied by the documentation for `shape_set_data`, the documentation for `enum ShapeType, SHAPE_CAPSULE` instead implies that the ordering of `SHAPE_CAPSULE` should be `(radius, height)`, as per the wording of "(...) A capsule shape is defined by a radius and a length (...)."
Consequently, it is exceedingly unclear on what ordering -- `(height, radius)` or `(radius, height)` -- should be used when interacting with `PhysicsServer2D` `SHAPE_CAPSULE` type shapes.
I ultimately did a little bit of testing (plus a bit of research into Godot's manual regarding `CapsuleShape2D`) that *appears* to indicate that the correct ordering should be `(radius, height)` -- but as I am still quite new to using Godot, I'd like a second opinion before stating this as fact.
Regardless, the intent of this issue is to request that the docs for `SHAPE_CAPSULE` type shape's `data` to *explicitly clarify* the ordering of the `height` and `radius` values from the array/Vector2 data structures associated with a `SHAPE_CAPSULE` shape in `PhysicsServer2D`; such an explicit clarification would mean that no one else would need to experiment/etc to determine the correct ordering of values.
If this is deemed to be an excessive/redundant enhancement, then I will concede.
**URL to the documentation page (if already existing):**
https://docs.godotengine.org/en/4.5/classes/class_physicsserver2d.html
https://docs.godotengine.org/en/4.5/classes/class_capsuleshape2d.html
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with the PhysicsServer2D page's shape_set_data entry and compare it with the SHAPE_CAPSULE wording and the CapsuleShape2D page linked in the issue. Confirm the ordering used for the capsule data values, then update the documentation so height and radius ordering is explicit and consistent.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- godot
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 52/100