NavigationMesh's vertices property isn't listed

[DrAlta]

Your Godot version: v3.5.1.stable.official [6fed1ffa3]

Issue description: nowhere is the vertices property mentioned.

URL to the documentation page: https://docs.godotengine.org/en/stable/classes/class_navigationmesh.html?highlight=navigationmesh

[Calinou]

The get_vertices() and set_vertices() methods are listed instead, which appears consistent with how the class reference XML is laid out in 3.x:

https://github.com/godotengine/godot/blob/eb0b5d38d1672481822a921389bd0184c71b5cbb/doc/classes/NavigationMesh.xml#L53-L58

https://github.com/godotengine/godot/blob/eb0b5d38d1672481822a921389bd0184c71b5cbb/doc/classes/NavigationMesh.xml#L68-L74

vertices is bound as a property, but it's marked as being invisible in the editor and internal: https://github.com/godotengine/godot/blob/eb0b5d38d1672481822a921389bd0184c71b5cbb/scene/resources/navigation_mesh.cpp#L506 Therefore, it's expected not to appear in the class reference.

[DrAlta]

So we are supposed to use the vertices property that is hidden from the docs, instead of the get/set_vertices methods that hidden from the editor?

smix8 commented 28 days ago •

You don't see set/get methods as a GDScript hint when they are bound to a property, only the property shows up in the hint e.g. in this case NavigationPolygon.vertices shows up.

@Calinou Calinou commented 28 days ago •

This is not a bug – see @smix8's comment above. Using the property syntax is recommended since Godot 3.0, but getter/setter methods are kept for interoperability with non-GDScript languages (which generally don't support this syntax with encapsulation).

[smix8]

As a power-user you can use the set/get methods or the hidden property. The hidden property is just a shortcut that calls the set/get method so use whatever suits your fancy.

That both vertices and polygons properties are hidden from the Editor inspector is intentional as it is an easy way to corrupt the navmesh and the navigation system if handled wrong by inexperienced users and it can be very large data arrays that make the inspector lag from rebuilds. The inspector use is after all targeted at beginners and normal users while specialized set/get methods to access and work with internals or hidden properties are made available for power-users that already know somehow what they are doing. Godot can expect from power-users that they know that if they manipulate navmesh vertices they also need to manipulate navmesh polygon indices to match. This is nothing that Godot can expect from a beginner or normal user nor should a normal user touch this as Godot has both navmesh baking as well as a create_from_mesh() function available for this user groups.

[DrAlta]

Why is the hidden (from the doc) property not hidden(in the CODE editor) but the not hidden get/set methods are hidden?

[YuriSizov]

I think we should remove the PROPERTY_USAGE_INTERNAL hint from the property. It's fine that it is hidden from the inspector, but PROPERTY_USAGE_INTERNAL only makes it hidden from the docs with no other side effects. Which seems to be the problem here, and as it is allowed to be used as a property, we should document it as one.