godotengine / godotengine/godot-docs

Improve Navigation Documentation

Open
#12,358 1 comment 0 reactions 0 assignees View on GitHub
area:manual enhancement topic:navigation tracker
Dominant language
reStructuredText
Stars
5.7k
Forks
3.8k
Avg merge
1d 20h
Merged PRs (30d)
25

Description

The [Navigation](https://docs.godotengine.org/en/stable/tutorials/navigation/index.html) section of the manual needs some love to make the language clearer and the concepts easier to find. Here's a bunch of feedback on it.

I'm creating this issue as a brain-dump for all of my notes, gripes, and suggestions. I recognize that that isn't as helpful as creating separate issues, so I welcome any comments, suggestions, critiques, and edits, or just spinning these off into separate issues! If there's a better forum to discuss this, please let me know.

I'll do my best to write up PRs to address these issues myself, but due to life problems that came up right as I began to work on that, it will likely be slow going. I won't be salty if others address these issues with or without my input! I think a lot of this can be addressed in separate PRs, too, not just as one big mega commit.

### Minor improvements

- [ ] Grammar, punctuation, and general proper English
- [ ] More direct, less elaborate word choice and sentence structure
- [ ] Links to types and properties in the Class Reference should be added where those are missing
- [ ] Some code examples directly call the getters and setters of properties when they should be calling the properties directly
- [ ] Remove Tip and Note sections that repeat the same information given elsewhere in an article

### Larger changes
Since these are changes to the overall structure of the Navigation section of the manual, I'll first try to explain the reason for these changes in a little more detail to save everyone's time in discussion.

Overall, I think the Navigation section of the documentation is difficult to use because it is organized by classes rather than by use case. This means that information about a particular behavior that a dev might want to implement is split across the pages for the various classes involved in the interaction, rather than in one place. For instance, information about collision avoidance is spread across the [NavServer](https://docs.godotengine.org/en/stable/tutorials/navigation/navigation_using_navigationservers.html#server-avoidance-callbacks), [NavAgent](https://docs.godotengine.org/en/stable/tutorials/navigation/navigation_using_navigationagents.html#navigationagent-avoidance), and [NavObstacles](https://docs.godotengine.org/en/stable/tutorials/navigation/navigation_using_navigationobstacles.html#obstacles-and-agent-avoidance) pages, and buried near the bottom of each. This "by-class" system also means that some pages exist, but really don't have much useful information (like [NavPaths](https://docs.godotengine.org/en/stable/tutorials/navigation/navigation_using_navigationpaths.html)), and some information is duplicated, with minor differences, across pages (like the [2D](https://docs.godotengine.org/en/stable/tutorials/navigation/navigation_introduction_2d.html) and [3D](https://docs.godotengine.org/en/stable/tutorials/navigation/navigation_introduction_3d.html) overview pages). Overall, I'd like to suggest these changes to how the information is split across various pages.

**Class-specific pages should be re-arranged** into separate pages for different use cases and underlying mechanics. Instead of having these separate pages:
- Using NavigationServer
- Using NavigationMaps
- Using NavigationRegions
- Using navigation meshes
- Using NavigationPaths
- Using NavigationPathQueryObjects
- Using NavigationAgents
- Using NavigationObstacles
- Using NavigationLinks
- Using NavigationLayers

we should move the information in each to the relevant use case page to the actual class docs.

The [2D](https://docs.godotengine.org/en/stable/tutorials/navigation/navigation_introduction_2d.html) and [3D](https://docs.godotengine.org/en/stable/tutorials/navigation/navigation_introduction_3d.html) overview pages should be combined and folded into an overview/introduction page.

The overall result I'm envisioning would look like these pages:
- **Navigation overview** as the [index page](https://docs.godotengine.org/en/stable/tutorials/navigation/index.html), including
- A quick overview of the use cases for Astar, RVO, and "normal" navigation, with links to the pages (or main page) for each
- The Setup section from the [2D](https://docs.godotengine.org/en/stable/tutorials/navigation/navigation_introduction_2d.html) and [3D](https://docs.godotengine.org/en/stable/tutorials/navigation/navigation_introduction_3d.html) overview pages, with code tabs for 2D vs 3D so that we're not repeating ourselves
- **Navigation Regions**, including
- The various methods for baking or creating NavMeshes and NavPolys
- How to include NavObstacles in this process
- **Linking Navigation Regions**, including
- Overviews of NavMaps (as they pertain to collections of NavRegions) and NavLinks
- The information currently in [this page](https://docs.godotengine.org/en/stable/tutorials/navigation/navigation_connecting_navmesh.html)
- **Configuring Navigation Settings**, including
- An overview of NavMaps
- A conceptual overview of what exactly these voxel things are
- The information currently in [these](https://docs.godotengine.org/en/stable/tutorials/navigation/navigation_different_actor_types.html) [three](https://docs.godotengine.org/en/stable/tutorials/navigation/navigation_different_actor_locomotion.html) [pages](https://docs.godotengine.org/en/stable/tutorials/navigation/navigation_different_actor_area_access.html)
- An overview of [NavLayers](https://docs.godotengine.org/en/stable/tutorials/navigation/navigation_using_navigationlayers.html)
- **Navigation Server Timing**, including
- The NavigationServer timing guidelines that currently are split between [here](https://docs.godotengine.org/en/stable/tutorials/navigation/navigation_using_navigationservers.html#threading-and-synchronization) and [here](https://docs.godotengine.org/en/stable/tutorials/navigation/navigation_using_navigationservers.html#waiting-for-synchronization)
- **Advanced Navigation**, with
- Making direct queries to the NavigationServer API (the information [here](https://docs.godotengine.org/en/stable/tutorials/navigation/navigation_using_navigationpathqueryobjects.html) and whatever else is applicable)
- Other behind-the-scenes implementation details for the NavigationServer
- **Collision avoidance**, including
- A quick overview of how RVO works (including what it stands for), and/or links to external documentation
- How to set up collision avoidance between agents in godot
- How to set up collision avoidance between agents and obstacles in godot
- Either the information in the [Avoidance section of the NavServer](https://docs.godotengine.org/en/stable/tutorials/navigation/navigation_using_navigationservers.html#server-avoidance-callbacks) page, or a link to that information in the Timing page
- **Astar navigation**, since this is completely mechanically different from the rest of the navigation setup
- **[Debugging Navigation](https://docs.godotengine.org/en/stable/tutorials/navigation/navigation_debug_tools.html)**
- **[Performance](https://docs.godotengine.org/en/stable/tutorials/navigation/navigation_optimizing_performance.html)**, with more concrete examples (screenshots and code!)

Thanks for coming to my ted talk. I developed this feedback as I was trying to puzzle through how navigation works, and I'm certainly still no expert. If something here doesn't make sense based on your understanding of the system, it's probably because I'm wrong, so please tell me before I mislead anyone else!

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with tutorials/navigation/index.html, navigation_introduction_2d.html, and navigation_introduction_3d.html, then compare the linked class-specific navigation pages and their current structure. Break the brain-dump into scoped documentation changes, confirm the intended information architecture in the issue discussion, and consider the work done when each agreed page has clearer language, links, examples, and no unnecessary duplication.

Written by the indexing model from the issue text.

Assessment

Tech stack
godot
Domain
documentation, game-dev
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Needs clarification
Newbie friendliness
32/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.