Overhaul Node3D documentation

[Mickeon]

Closes #87896
Closes #93651
May address godotengine/godot-docs#9930 (?)

Related to several other past efforts, but especially the Basis and Transform3D ones.

This PR aims to completely overhaul Node3D's class reference in an attempt to make it more easy to digest, as well as bring on par with the rest of the documentation.

Why? It generally suffers from the same issues highlighted in the past. The most notable of which being that a lot of descriptions are dull, succinct, or put the focus on the wrong subject:

• "Set subgizmo selection for this node in the editor."
• "Updates all the [Node3D] gizmos attached to this node."
• "Transforms [param global_point] from world space to this node's local space."
• "Rotates the local transformation around the X axis by angle in radians."

More specific notes:

• Remove any leftover references to "Spatial" nodes from the class reference.
• Modified to_local and to_global's descriptions to imply they do return something.
• Elaborate on when visibility_changed is emitted.
  • The sentence is almost word-for-word from the way some NOTIFICATION constants are written in the Node class.
• Revamp the descriptions of NOTIFICATION_TRANSFORM_CHANGED & similar.
  • "In order for [constant NOTIFICATION_TRANSFORM_CHANGED] to work, users first need to ask for it, with [method set_notify_local_transform]."
    a grand majority of Node3Ds will receive NOTIFICATION_TRANSFORM_CHANGED without needing for the "user" to opt-in. They need this otherwise they would not work.

---

This PR may contain commented XML. I use it as a point of reference or to symbolize alternatives of the same sentence. Even if this is a draft, feedback on things worth mentioning is still very welcome.

[RedMser]

One bit of the Node3D methods (and corresponding docs) always confused me as a user. I've added comments there, but am unsure about proper terminology.

[RedMser]

From how I understand it, rotate and rotate_[xyz] specify the axis in global space (parent space? not sure about proper terminology), but both modify the local space transform. Whereas rotate_object_local also transforms the rotation axis into local space. Right now, both of these methods have the same description.

[Mickeon]

I have kept these in mind for further testing. These methods have also always confused me so it would be nice to finally write something easier to understand.

[Mickeon]

Just to give closure, rotate is indeed in parent space (same as the transform property). If the position was anything but Vector3(0, 0, 0), the node would rotate and move around the parent.

[RedMser]

From how I understand it, translate specifies the offset in global space (parent space? not sure about proper terminology), but modifies the local space transform. Whereas translate_object_local also transforms the offset into local space. Right now, both of these methods have the same description.

[lostminds]

Node2D has a lot of the same properties as the 3D version, and often with very short descriptions in the docs. So if you add improved descriptions of the concepts in the Node3D versions perhaps some of them can be applied to Node2D as well? Like for example what the global_position and global_transform properties do and how they work.

[Mickeon]

That's the idea! One thing at the time. I decided to tackle Node3D first because it's fresh on the mind after both #87175 and #87334.

[Mickeon]

I have updated the PR with just... more. I am still not fully happy on what is here, as there's a constant fear of losing important information through all of this. So this is still gonna be WIP for a bit more time until I come back with a fresher mind and answers to some questions.

[Mickeon]

HEAVY indecision between these two. Above is entirely correct, but does not explain why this method exists.

[Mickeon]

Affine, direct Affine operations... 😖

[Mickeon]

I still find a bit difficult to understand what this is for, despite my best efforts.

[fire]

can be related to hlod lod systems. Let me know if you need more keywords

[Mickeon]

It would certainly be nice to get more information about it. But changing this description can also be done in a separate PR.

[Mickeon]

Marking this as ready to be lynched by anyone more savvy than me, no beating around the bush.

[kleonc]

Only skimmed through, added some brief notes. Please fix these "local space (relative to the parent)".

AFAIK "local" in Godot's properties/method names always refer to object-local, not to parent-local. Docs should be consistent with this.
If there are some exceptions that I'm not aware of, please point to them. 🙂

[aaronfranke]

We should avoid using the word "local" for multiple things. See @kleonc's comments.

In general, Godot's properties are parent-relative by default unless further qualified, where the word global qualifies it as fully global relative to the world space, and the word local qualifies it as relative to within the node's own transform. For the docs where we need to clarify this, let's use "parent-relative", not "local".

[Mickeon]

Given your recent review I'll revisit this soonish. The "local" distinction is bit overwhelming to think about, but I must pursue for the sake of a nicer class reference.

[Mickeon]

I have updated to add "and preserves the position" where appropriate, as well as update translate and translate_object_local again.

Anyway, if we'd want to use e.g. "object-local" instead of just "local" then we should probably do so consequently across the whole docs. AFAICT currently we use just "local" to refer to the given object/node, so I'm saying let's keep using it.

Mhm. Hence my reluctance to say object-local space. If it needs to be clarified it needs to be done in one huge swoop across the docs.

• I have handled similar descriptions as suggested, but the idea of saying "around the global [param axis] going through this node's origin" interests me. It sounds a whole lot easier to imagine the whole operation that way.

Again, nothing against clarifications. The purpose of the docs is not to be as concise as possible (while being correct). So if the descriptions can be made a little longer but easier to grasp for "a regular user" then sure it's welcomed (we'll try to keep them correct).

Problem here is that I'd have to give up on directly mentioning the basis otherwise the sentence doesn't make sense, and for consistency that may need to escalate for the surrounding descriptions as well.

Same as [method translate_object_local], for compatibility reasons. Prefer using it instead.

This sounds exactly like a deprecation message, but the method is not deprecated until we decide that separately. So it's a bit odd to do this right now.

[aaronfranke]

@Mickeon Can you rebase this PR? There's a lot of good here, we should try to get this merged sometime soon.

[Mickeon]

Rebased after 8af5072 and d0c4219 . Wew, what a trip.

The descriptions affected were is_visible_in_tree and look_at. In particular, see #100991 (comment) too.

[Mickeon]

Pushed to address incorrect constants in the global_* properties

[Repiteo]

Thanks!