godotengine / godotengine/godot-docs
Clarify performance differences between using `PhysicsShapeQueryParameters3D.shape` and `PhysicsShapeQueryParameters3D.shape_rid`.
- Dominant language
- reStructuredText
- Stars
- 5.7k
- Forks
- 3.8k
- Avg merge
- 1d 20h
- Merged PRs (30d)
- 25
Description
**Your Godot version:**
4.6
**Issue description:**
The description for `PhysicsShapeQueryParameters3D.shape` says to "always prefer using this over `shape_rid`", because it stores a reference which avoids releasing the shape (Maybe? The English wording is awkward, so I can't be certain if that's the meaning). Meanwhile, the description for `PhysicsShapeQueryParameters3D.shape_rid` says to prefer using it over `shape` if you want to optimize for performance.
At best, these descriptions are vague and don't offer enough insight into when exactly to prefer using one over the other. At worst, they seem to present a contradiction, because "storing to avoid releasing" is itself a performance optimization. Also the wording of "always prefer using this" doesn't leave much room for interpretation or nuance.
**URL to the documentation page (if already existing):**
https://docs.godotengine.org/en/4.6/classes/class_physicsshapequeryparameters3d.html
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with the linked PhysicsShapeQueryParameters3D documentation page and compare the descriptions of shape and shape_rid. Determine the performance and lifetime distinction that the existing wording is trying to explain, then revise both descriptions so their guidance is clear and non-contradictory. Done when the page states when each property should be preferred.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100