godotengine / godotengine/godot-docs

PhysicsServer2D Capsule Shape Data Documentation Ambiguity

Open
#11,562 0 comments 0 reactions 0 assignees View on GitHub
area:class reference enhancement
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.