godotengine / godotengine/godot-docs

Clarify performance differences between using `PhysicsShapeQueryParameters3D.shape` and `PhysicsShapeQueryParameters3D.shape_rid`.

Open
#11,741 3 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.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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.