[Mickeon]

TL:DR: This particular page bothers me.

This PR currently exists as a draft just to showcase my intention.

[AThousandShips]

Just a pass on pure format, will do a proper pass when it is ready otherwise

[Mickeon]

Yeah, I would like to first assess, perhaps with the help of @\smix8, if there's anything worth mentioning because this page is in an awkward spot. The whole thing about bitmask helpers is particularly out-of-place, but there's also a lot of minor details that I find odd.

[smix8]

The reason that page has all the manual bitmask examples is because the entire Godot documentation has/had none how to really use them in such context. So telling users to use an int as a bitmask with zero example or helpers around the entire engine was cursed documentation which is why it was added to that page here.

The most important part to mention about using navigation_layers is that they do not affect the geometry of a navigation map, they only affect what gets included or excluded within a path query.

The reason this is so important to mention and drive home is because users still think they can use those layers to stack all kinds of navmesh geometry all over each other. All that such stacking does is create bugs and performance problems, it never worked like that and never will. The point of navigation_layers is to filter things out on a specific query WITHOUT changing the entire navigation map geometry as that would be very performance heavy.

[Mickeon]

So telling users to use an int as a bitmask with zero example or helpers around the entire engine was cursed documentation which is why it was added to that page here.

This is exactly why one should, instead, make a page about bitmasks, even a bit of a shoddy one, that contains this information in a way that can be shared by multiple other pages. Putting it all here is a hacky solution and very hard one to find.
It doesn't help that the bit operations have the corresponding methods, which makes the example a bit moot because most users will be satisfied with this basic purpose.

The most important part to mention about using navigation_layers is that they do not affect the geometry of a navigation map, they only affect what gets included or excluded within a path query.

Since it's pertinent to path queries specifically, wouldn't all of this be better explained in "Using NavigationPathQuery objects" instead of having a whole separate page on navigation layers?

[Billy-The-Squid]

Just my two cents, but this is just one symptom of the entire navigation tutorial needing reorganization. I've got some additional ideas of how to do that in #12358

[Billy-The-Squid]

Suggested change

	If a region does not have any compatible navigation layer with the ``navigation_layers``
	If a region does not have any navigation layers that are compatible with the ``navigation_layers``

The wording still feels awkward

[Billy-The-Squid]

An example here might be helpful? Something to show the context/scenario in which this could be useful a little more concretely