Scarfski/recastnavigation
1
0
Fork 0
mirror of https://github.com/recastnavigation/recastnavigation.git synced 2026-06-08 00:03:47 +00:00
Code Issues Packages Projects Releases Wiki Activity

Docs Overhaul (#680)

Browse Source 
A lot of the auxiliary project documentation was pretty old, redundant, or could use some polishing.  This change fixes up some wording, grammar, layout and generally cleans up the docs a bit.  It's not perfection, but it's an improvement

I also tried to streamline and beautify the top-level `README.md` to be more appealing, clear, and to direct people to the official docs.  To this end, I moved the building instructions to This is based on what I've seen in some other popular github projects.
This commit is contained in:
Graham Pentheny
2023-12-28 17:06:03 -05:00
committed by GitHub
parent c393777d26
commit 53089459fa
10 changed files with 217 additions and 292 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
CODE_OF_CONDUCT.md
View File

@@ -1,5 +1,5 @@
# Contributor Covenant Code of Conduct
# Code of Conduct
## Our Pledge

165
CONTRIBUTING.md
View File

@@ -1,156 +1,67 @@
# Contributing to Recast and Detour
# Contribution Guidelines
We'd love for you to contribute to our source code and to make Recast and Detour even better than they are
today! Here are the guidelines we'd like you to follow:
We'd love for you to contribute to Recast and Detour and help make them even better than they are today! Here are the guidelines we'd like you to follow:
## Code of Conduct
This project adheres to the [Contributor Covenant code of conduct][code-of-conduct].
By participating, you are expected to honor this code.
## Got a Question or Problem?
This project adheres to the [Contributor Covenant Code of Conduct][code-of-conduct]. By participating in the Recast community, you are required to adhere to this code.
If you have questions about how to use Recast or Detour, please direct these to the [Google Group][groups]
discussion list. We are also available on [Gitter][gitter].
## Have a Question or Problem?
## Have a question?
Questions about how to best use Recast, what it's capable of, and other inquiries should be directed to the [Q&A section of Github Discussions][q-and-a]. Questions submitted as Github issues will be converted to discussions.
Questions about how to best use Recast, what it's capable of, and other inquiries should be directed to the [Q&A section of Github Discussions][q-and-a]. Questions submitted as Github issues will be converted to discussions.
## Found an Issue?
If you find a bug in the source code or a mistake in the documentation, you can help us by
submitting an issue to our [GitHub Repository][github]. Even better you can submit a Pull Request
with a fix.
You can also submit questions to the older Recast [Google Group][groups] discussion list, or chat on [Gitter][gitter].
**Please see the Submission Guidelines below**.
## Want a New Feature?
## Want a Feature?
You can request a new feature by submitting an issue to our [GitHub Repository][github]. If you
would like to implement a new feature then consider what kind of change it is:
Check out our [development roadmap](Docs/Roadmap.md) to see what new features are already planned. The roadmap is a great resource if you're looking to help out with Recast but aren't sure where to start.
* **Major Changes** that you wish to contribute to the project should be discussed first on our
[Google Group][groups] or in [GitHub Issues][github-issues] so that we can better coordinate our efforts, prevent
duplication of work, and help you to craft the change so that it is successfully accepted into the
project.
* **Small Changes** can be crafted and submitted to the [GitHub Repository][github] as a Pull Request.
You can request a new feature by submitting a github issue. See below for guidelines on submitting issues.
## Submission Guidelines
If you would like to implement a new feature then consider what category of change it is:
* **Major Changes** that you wish to contribute to the project should be discussed first in a [GitHub Issue][github-issues] or in our [Google Group][groups] so that we can coordinate efforts, prevent duplication of work, and help you to craft the change so that it is successfully accepted.
* **Small Changes** can be submitted as pull requests on [GitHub][github].
## Found a Bug?
If you've found a bug or an issue with the documentation you can help us by submitting an issue to our [GitHub Repository][github]. Even better you can submit a Pull Request with a fix.
### Submitting an Issue
Before you submit your issue search the [GitHub Issues][github-issues] and [Github Discussions][q-and-a] archives,
maybe your question was already answered.
If your issue appears to be a bug, and hasn't been reported, open a new issue.
Help us to maximize the effort we can spend fixing issues and adding new
features, by not reporting duplicate issues. Providing the following information will increase the
chances of your issue being dealt with quickly:
Before you submit your issue search the [GitHub Issues][github-issues] and [Github Discussions][q-and-a] archives, maybe your question was already answered.
If your issue is a bug and hasn't been reported, open a new issue. Providing the following information will increase the chances of your issue being dealt with quickly:
* **Overview of the Issue** - what type of issue is it, and why is it an issue for you?
* **Callstack** - if it's a crash or other runtime error, a callstack will help diagnosis
* **Screenshots** - for navmesh generation problems, a picture really is worth a thousand words.
Implement `duDebugDraw` and call some methods from DetourDebugDraw.h. Seriously, just do it, we'll definitely ask you to if you haven't!
* **Screenshots** - for navmesh generation problems, a picture really is worth a thousand words. Implement `duDebugDraw` and call some methods from DetourDebugDraw.h. Seriously, just do it, we'll definitely ask you to if you haven't!
* **Logs** - stdout and stderr from the console, or log files if there are any.
If integrating into your own codebase, be sure to implement the log callbacks in `rcContext`.
* **Reproduction steps** - a minimal, unambiguous set of steps including input, that causes the error for you.
e.g. input geometry and settings you can use to input into RecastDemo to get it to fail.
Note: These can be saved by pressing the 9 key in RecastDemo, and the resulting .gset file can be shared (with the .obj if it is not one of the default ones).
* **Recast version(s) and/or git commit hash** - particularly if you can find the point at which the error first started happening
* **Reproduction steps** - a minimal, unambiguous set of steps including input, that causes the error for you. e.g. input geometry and settings you can use to input into RecastDemo to get it to fail.
* Note: In RecastDemo you can save the intput parameters to Recast by pressing the `9` key. The resulting `.gset` file can be shared with the `.obj` (if it is not one of the default ones) which will help tremendously in getting your bug repro'd and fixed.
* **Recast version(s) and/or git commit hashes** - particularly if you can find the point at which the error first started happening
* **Environment** - operating system, compiler etc.
* **Related issues** - has a similar issue been reported before?
* **Suggest a Fix** - if you can't fix the bug yourself, perhaps you can point to what might be
causing the problem (line of code or commit)
* **Related issues** - have similar issues been reported before?
* **Suggest a Fix** - if you can't fix the bug yourself, perhaps you can point to what might be causing the problem (line of code or commit)
Here is a great example of a well defined issue: https://github.com/recastnavigation/recastnavigation/issues/12
**If you get help, help others. Good karma rulez!**
### Submitting a Pull Request
Before you submit your pull request consider the following guidelines:
* Search [GitHub Pull Requests][github-pulls] for an open or closed Pull Request
that relates to your submission. You don't want to duplicate effort.
* Make your changes in a new git branch:
Check out [Github's official documentation](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) on how best to crete, work with and submit pull requests.
```shell
git checkout -b my-fix-branch master
```
Before you submit your pull request consider the following:
* Implement your changes, **including appropriate tests if appropriate/possible**.
* Commit your changes using a descriptive commit message that follows our commit message conventions (see below).
```shell
git commit -a
```
Note: the optional commit `-a` command line option will automatically "add" and "rm" edited files.
* Squash any work-in-progress commits (by rebasing) to form a series of commits that make sense individually.
Ideally the pull request will be small and focused enough that it fits sensibly in one commit.
```shell
git rebase -i origin/master
```
* Push your branch to GitHub:
```shell
git push origin my-fix-branch
```
* In GitHub, send a pull request to `recastnavigation:master`.
* If we suggest changes then:
* Make the required updates.
* Commit your changes to your branch (e.g. `my-fix-branch`).
* Squash the changes, overwriting history in your fix branch - we don't want history to include incomplete work.
* Push the changes to your GitHub repository (this will update your Pull Request).
If you have rebased to squash commits together, you will need to force push to update the PR:
```shell
git rebase master -i
git push origin my-fix-branch -f
```
That's it! Thank you for your contribution!
#### After your pull request is merged
After your pull request is merged, you can safely delete your branch and pull the changes
from the main (upstream) repository:
* Delete the remote branch on GitHub either through the GitHub web UI or your local shell as follows:
```shell
git push origin --delete my-fix-branch
```
* Check out the master branch:
```shell
git checkout master -f
```
* Delete the local branch:
```shell
git branch -D my-fix-branch
```
* Update your master with the latest upstream version:
```shell
git pull --ff upstream master
```
## Git Commit Guidelines
### Commit content
Do your best to factor commits appropriately, i.e not too large with unrelated
things in the same commit, and not too small with the same small change applied N
times in N different commits. If there was some accidental reformatting or whitespace
changes during the course of your commits, please rebase them away before submitting
the PR.
* Search [GitHub Pull Requests][github-pulls] for an open or closed Pull Request that relates to your submission. You don't want to duplicate effort.
* Do your best to factor commits appropriately. It's better to submit multiple pull separate requests than include every change in a single one. For example, if you're cleaning up some code and submitting a bug fix, it's best to submit a PR for the cleanup work separately from the bugfix. This helps ensure your PR's are reviewed and merged quickly, and that an issue with some part of your changes doesn't hold back all of them.
* If applicable, please try to include some unit tests that test the issue and fix that you're submitting.
* Ensure your PR is rebased onto the head of `main`. If you don't do this, you'll have some issues when github does it for
you.
### Commit Message Format
Please format commit messages as follows (based on this [excellent post](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)):
Please format PR messages as follows (based on this [excellent post](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)):
```
Summarize change in 50 characters or less
@@ -162,15 +73,13 @@ If the change fixes an issue, leave another blank line after the final
paragraph and indicate which issue is fixed in the specific format
below.
Fix #42
Fixes #42
```
Important things you should try to include in commit messages include:
Important things you should try to include in PR messages include:
* Motivation for the change
* Difference from previous behaviour
* Whether the change alters the public API, or affects existing behaviour significantly
* Differences from previous behaviour
* Whether the change alters the public API, or meaningfully affects existing behaviour
[code-of-conduct]: https://github.com/recastnavigation/recastnavigation/blob/main/CODE_OF_CONDUCT.md
[q-and-a]: https://github.com/recastnavigation/recastnavigation/discussions/categories/q-a

83
Docs/BuildingAndIntegrating.md Normal file
View File

@@ -0,0 +1,83 @@
# Building & Integrating
Recast is designed to be integrated into your project as source files and built with whatever build system you use.
For building RecastDemo and for Recast library development there are [premake5](http://premake.github.io/) and [cmake](https://cmake.org/) build scripts. Premake5 is recommended unless you're already familiar with cmake.
## Building RecastDemo
While Recast and Detour don't require any dependencies, RecastDemo requires SDL (not included), and the unit tests rely on Catch2 (included in the repository).
The following steps outline the process to install SDL2 in the appropriate location and build RecastDemo with Premake and your local . Before you begin, you'll need to [download](https://github.com/premake/premake-core/releases) and install premake5 and ensure that the `premake5` executable location is included in your system path.
You can also reference the github actions build script `.github/Build.yaml` for examples of building with specific platform and toolchain combinations.
### Windows
- Grab the latest SDL2 development library release from [here](https://github.com/libsdl-org/SDL) and unzip it into `RecastDemo/Contrib`. Rename the SDL folder such that the path `RecastDemo/Contrib/SDL/lib/x86` is valid.
- Navigate to the `RecastDemo` folder and run `premake5 vs2022`
- Open `Build/vs2022/recastnavigation.sln` in Visual Studio 2022 or Jetbrains Rider.
- Set `RecastDemo` as the startup project, build, and run.
### macOS
- Grab the latest SDL2 development library dmg from [here](https://github.com/libsdl-org/SDL) and place `SDL2.framework` in `RecastDemo/Bin`
- Navigate to the `RecastDemo` folder and run `premake5 xcode4`
- Open `Build/xcode4/recastnavigation.xcworkspace` in XCode
- Set the RecastDemo project as the target and build.
### Linux
- Install SDL2 and its dependencies according to your distro's guidelines.
- Navigate to the `RecastDemo` folder and run `premake5 gmake2`
- Navigate to `RecastDemo/Build/gmake2` and run `make`
- Navigate to `RecastDemo/Bin` and run `./RecastDemo`
## Preprocessor Defines
There are a few symbols you may wish to define when building Recast.
| Symbol | Usage |
|-------------------------|--------------------------------------------------------------------------------------------------------------------------|
| `RC_DISABLE_ASSERTS` | Disables assertion macros. Useful for release builds that need to maximize performance. You can also customize Recasts's assetion behavior with your own assertion handler. See `RecastAssert.h` and `DetourAssert.h`.
| `DT_POLYREF64` | Use 64 bit (rather than 32 bit) polygon ID references. Generally not needed, but sometimes useful for very large worlds. |
| `DT_VIRTUAL_QUERYFILTER`| Define this if you plan to sub-class `dtQueryFilter`. Enables the virtual destructor in `dtQueryFilter`. |
## Running Unit tests
- Follow the instructions to build RecastDemo above. Premake should generate another build target called "Tests".
- Build the "Tests" project. This will generate an executable named "Tests" in `RecastDemo/Bin/`
- Run the "Tests" executable. It will execute all the unit tests, indicate those that failed, and display a count of those that succeeded. Check out the [Catch2 documentation](https://github.com/catchorg/Catch2/blob/devel/docs/command-line.md#top) for information on additional command line options.
## Integration
There are a few ways to integrate Recast and Detour into your project. Source integration is the most popular and most flexible, and is what the project was designed for from the beginning.
### Source Integration
It is recommended to add the source directories `DebugUtils`, `Detour`, `DetourCrowd`, `DetourTileCache`, and `Recast` directly into your project depending on which parts of the project you need. For example your level building tool could include `DebugUtils`, `Recast`, and `Detour`, and your game runtime could just include `Detour`.
- *Recast*: Core navmesh building system.
- *Detour*: Runtime navmesh interface and query system
- *DetourCrowd*: Runtime movement, obstacle avoidance and crowd sim systems
- *DetourTileCache*: Runtime navmesh dynamic obstacle and re-baking system
### Installation through vcpkg
If you are using the [vcpkg](https://github.com/Microsoft/vcpkg/) dependency manager you can alternatively download, build, and install Recast with:
```
vcpkg install recast
```
## Customizing Allocation Behavior
Recast and Detour strive to avoid heap allocations whenever possible. In the cases where they are needed, all allocations are routed through allocation functions that by default just wrap `malloc` and `free`. Additionally, the `rcAllocHint` enum gives some coarse-grained information about the intended lifetime of the allocation.
You can specify your own `rcAlloocFunc` and `rcFreeFunc` in `RecastAlloc.cpp` (and similarly in `DetourAlloc.cpp`) to tune heap usage to your specific needs.
## A Note on DLL exports and C API
Recast does not yet provide a stable C API for use in a DLL or as bindings for another language. The design of Recast relies on some C++ specific features, so providing a stable API is not easy without a few significant changes to Recast.
There are a number of projects that offer unofficial language bindings for Recast, but official support for a C API is currently on our [development roadmap](Roadmap.md).

BIN
Docs/Images/logo.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 26 KiB

34
Docs/Readme.md Normal file
View File

@@ -0,0 +1,34 @@
This directory contains source files for the documentation as well as the generated doxygen output.
# Directory Layout
`. (Docs root)` High level content and format files. (E.g. css, header, footer.)
`./Extern` API documentation that is located outside the source files. When the API documentation gets too big or complex for the header and source files, it goes in this directory.
`./Images` Images related to the documentation.
`./html` The target for the Doxygen build. (Created during the build process.)
# Documentation Style
One of the requirements for the API documentation is that it
has the minimum possible impact on the declarations in the
header files. So, in general, the header file declarations only
contain summary documentation. The detail documentation
is placed as follows:
1. If an element is defined in a cpp file, then place
the detail documentation in the source file.
2. If an element does not have an associated cpp file, then
place the detail documentation at the end of the header file.
3. If there is a lot of detail documentation cluttering up
the end of a header file, then the content is moved to
a separate file in the Extern directory.
# Building the Documentation
1. Download and install the appropriate Doxygen version. (See the first line in the Doxyfile for the current version.)
2. Run "doxygen" in the project root directory. (The location of the Doxyfile.) No arguments are required.
The generated html files will be located in the /Docs/html directory.

59
Docs/Readme.txt
View File

@@ -1,59 +0,0 @@
This directory contains source for the documentation. It is also the
build target for doxygen output.
Directory Layout
. (Docs root)
High level content and format files. (E.g. css, header, footer.)
./Extern
API documentation that is located outside the source files.
When the API documentation gets too big or complex for the header
and source files, it goes in this directory.
./Images
Images related to the documentation.
./html
The target for the Doxygen build. (Created during the build process.)
Miscellany
One of the requirements for the API documentation is that it
has the minimum possible impact on the declarations in the
header files. So, in general, the header file declarations only
contain summary documentation. The detail documentation
is placed as follows:
1. If an element is defined in a cpp file, then place
the detail documentation in the source file.
2. If an element does not have an associated cpp file, then
place the detail documentation at the end of the header file.
3. If there is a lot of detail documentation cluttering up
the end of a header file, then the content is moved to
a separate file in the Extern directory.
Building the Documentation
1. Download and install the appropriate Doxygen version. (See the first
line in the Doxyfile for the current version.)
2. Run "doxygen" in the project root directory. (The location of the Doxyfile.)
No arguments are required.
The generated html files will be located in the /Docs/html directory.
If you want to "version" the documentation, you can set the PROJECT_NUMBER
setting in the Doxyfile. E.g. PROJECT_NUMBER = "(2014-04-23)". The project
number will be added to the header of the documentation.
E.g. "Recast Navigation (2014-04-23)"

16
Roadmap.md → Docs/Roadmap.md
View File

@@ -1,20 +1,20 @@
# Recast Development Roadmap
# Development Roadmap
This document describes the current development roadmap for Recast and Detour. It is initially focused on maintaining and polishing the current functionality in a way that makes it more appealing and easier to use. There are a number of large areas of new functionality that are appealing as well.
This document describes the current development roadmap for Recast and Detour. It is initially focused on maintaining and polishing the current functionality in a way that makes it more appealing and easier to use, but also covers a few large pieces of new functionality.
If you're excited about contributing to Recast or want to understand what its future looks like, this roadmap is a great place to start.
## Short Term
### Documentation & Web Presence
- **Project website** (GitHub pages). A home for docs, info, tutorials, etc. that's easy to find and navigate. There's stuff like the wiki system in GitHub that can serve this purpose, but it's not the greatest.
- **Hosted API Reference**: We have extensive doxygen docs that we should also host on github pages. Ideally this would be implemented as a job for the CI process.
### Documentation & Web Presence (WIP)
- ✅ **Project website** (GitHub pages). A home for docs, info, tutorials, etc. that's easy to find and navigate. There's stuff like the wiki system in GitHub that can serve this purpose, but it's not the greatest.
- ✅**Hosted API Reference**: We have extensive doxygen docs that we should also host on github pages. Ideally this would be implemented as a job for the CI process.
- **High-level design/overview**. Basically taking a lot of the "how does Recast work?" docs we have (and stuff on Mikko's blog) and surfacing them in a place that's easier to find. e.g. [this information](http://digestingduck.blogspot.com/2010/02/slides-from-past.html) should be integrated to the documentation.
- **FAQ** to include answers to common questions like "can I use Recast on a spherical world?" etc. The small group of questions that come up often.
- **Expand on configuration parameter docstrings**. Expand on the docstrings for the fields in `rcConfig`.
- **Projects using recast page**. A place to show off integrations of Recast into different games and engines. Having this visible will help give people confidence in the quality of Recast.
### More explicit variable names
### More explicit variable names (WIP)
There's quite a few variables that are single-letter or very condensed acronyms. Stuff like `u`, `v`, `cs`, `nnei` etc. These are certainly easier to type than more descriptive names, and can allow for some nice code formatting, but the readability gains of less condensed names outweigh that. These should be updated to be more easily maintainable and less of a hurdle for newcomers.
### Opt-in config value validation system
@@ -31,7 +31,7 @@ Currently Recast provides no specific threading support. Many aspects of navmes
### More Tests
This is a good place to start when making any changes to the internals or fixing bugs. It's important to have a way to validate that bugfixes or enhancements are not adversely affecting the base Recast functionality. Lots of parts of the code are fairly simple to test, but some would require some extra effort with mocking data or similar.
### More POD structs for clarity in internals
### More POD structs for clarity in internals (WIP)
Small structs like a simple 3-float POD vector would go a long way to help clarify a lot of the internals. Any changes here shouldn't impact performance or functionality. They should just be simple POD structs that get optimized away but make the code a bit clearer to read and work with.
### Revisit structural organization
@@ -47,7 +47,7 @@ This would help tremendously with adoption. There are a number of integrations o
There's enough cases where we pass around object pointers in API calls that may cause this to be a bit more work than it seems.
# Roadmap for New Recast/Detour Functionality
# New Recast/Detour Functionality
### Nav Volumes & 3D Navigation
Obviously a big feature that would enable flying agents. Probably not terribly difficult to integrate due to the voxelization process, but it's probably a lot of detailed geometric processes and challenges. We'd at least need to retain unwalkable polygons longer in the process (they get thrown away pretty early) so we should ensure it doesn't have any adversarial affects to the perf or capabilities of the normal navmesh process. 3d navigation should be a separate set of APIs, as the considerations and use cases are quite different than normal navmesh navigation.

9
Doxyfile
View File

@@ -959,7 +959,8 @@ INPUT_FILE_ENCODING =
FILE_PATTERNS = *.cpp \
*.h \
*_c.txt \
*_api.txt
*_api.txt \
*.md
# The RECURSIVE tag can be used to specify whether or not subdirectories should
# be searched for input files as well.
@@ -976,12 +977,12 @@ RECURSIVE = YES
EXCLUDE = Doxyfile \
License.txt \
Readme.txt \
TODO.txt \
Docs/Readme.md \
RecastDemo/Contrib \
RecastDemo/Build \
RecastDemo/Bin \
Tests
Tests \
Docs/doxygen-awesome-css
# The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
# directories that are symbolic links (a Unix file system feature) are excluded

32
Integration.md
View File

@@ -1,32 +0,0 @@
# Integration
There are a few ways to integrate Recast and Detour into your project. Source integration is the most popular and most flexible, and is what the project was designed for from the beginning.
## Source Integration
It is recommended to add the source directories `DebugUtils`, `Detour`, `DetourCrowd`, `DetourTileCache`, and `Recast` directly into your project depending on which parts of the project you need. For example your level building tool could include `DebugUtils`, `Recast`, and `Detour`, and your game runtime could just include `Detour`.
- *Recast*: Core navmesh building system.
- *Detour*: Runtime navmesh interface and query system
- *DetourCrowd*: Runtime movement, obstacle avoidance and crowd sim systems
- *DetourTileCache*: Runtime navmesh dynamic obstacle and re-baking system
## Install through vcpkg
If you are using the [vcpkg](https://github.com/Microsoft/vcpkg/) dependency manager you can alternatively download and install Recast with:
```
vcpkg install recast
```
# DLL and C API exports
Recast does not currently provide a stable C API for use in a DLL or as bindings for another language. The design of Recast currently relies on some C++ features, so providing a stable API is not possible without a few large changes to Recast. There are a number of projects that offer unofficial language bindings for Recast, but official support for a C API is currently on our [Roadmap](Roadmap.md).
# Preprocessor defines
`RC_DISABLE_ASSERTS`: Disables assertion macros. Useful for release builds that need to maximize performance.
`DT_POLYREF64`: Use 64 bit (rather than 32 bit) polygon ID references. Generally not needed, but sometimes useful for very large worlds.
`DT_VIRTUAL_QUERYFILTER`: Define this if you plan to sub-class `dtQueryFilter`. Enables the virtual destructor in `dtQueryFilter`

109
README.md
View File

@@ -1,84 +1,73 @@
<p align="center">
<a href="recastnav.com"><img src="/recastnavigation/recastnavigation/raw/main/Docs/Images/logo.png" /></a>
</p>
Recast & Detour
===============
<h3 align="center"><b>Recast Navigation</b></h3>
<p align="center">
<i>State-of-the-art navmesh generation and navigation for games.</i><br /><br />
<a href="https://github.com/recastnavigation/recastnavigation/actions/workflows/Build.yaml"><img src="https://github.com/recastnavigation/recastnavigation/actions/workflows/Build.yaml/badge.svg"></a>
<a href="https://github.com/recastnavigation/recastnavigation/actions/workflows/Tests.yaml"><img src="https://github.com/recastnavigation/recastnavigation/actions/workflows/Tests.yaml/badge.svg"></a>
</p>
[![Build](https://github.com/recastnavigation/recastnavigation/actions/workflows/Build.yaml/badge.svg)](https://github.com/recastnavigation/recastnavigation/actions/workflows/Build.yaml)
[![Tests](https://github.com/recastnavigation/recastnavigation/actions/workflows/Tests.yaml/badge.svg)](https://github.com/recastnavigation/recastnavigation/actions/workflows/Tests.yaml)
![Recast Demo](/Docs/Images/screenshot.png)
![screenshot of a navmesh baked with the sample program](/Docs/Images/screenshot.png)
## 🚀 Features
## Recast
Recast is state of the art navigation mesh construction toolset for games.
Recast is...
* 🤖 **Automatic** - throw any level geometry at it and you will get a robust navmesh out
* 🤖 **Automatic** - Recast can generate a navmesh from any level geometry you throw at it
* 🏎️ **Fast** - swift turnaround times for level designers
* 🧘 **Flexible** - easily customize the navmesh generation and runtime navigation systems to suit your specific game's needs.
* 🧘 **Flexible** - detailed customization options and modular design let you tailor functionality to your specific needs
* 🚫 **Depency-Free** - building Recast & Detour only requires a C++ compiler
* 💪 **Industry Standard** - Recast powers AI navigation features in Unity, Unreal, Godot, O3DE and countless AAA and indie games and engines
Recast constructs a navmesh through a multi-step rasterization process:
Recast Navigation is divided into multiple modules, each contained in its own folder:
1. First Recast voxelizes the input triangle mesh by rasterizing the triangles into a multi-layer heightfield.
2. Voxels in areas where the character would not be able to move are removed by applying simple voxel data filters.
3. The walkable areas described by the voxel grid are then divided into sets of 2D polygonal regions.
4. The navigation polygons are generated by triangulating and stiching together the generated 2d polygonal regions.
- `Recast/` - Navmesh generation
- `Detour/` - Runtime loading of navmesh data, pathfinding, navmesh queries
- `DetourTileCache/` - Navmesh streaming. Useful for large levels and open-world games
- `DetourCrowd/` - Agent movement, collision avoidance, and crowd simulation
- `DebugUtils/` - API for drawing debug visualizations of navigation data and behavior
- `Tess/` - Unit tests
- `RecastDemo/` - Standalone, comprehensive demo app showcasing all aspects of Recast & Detour's functionality
## Detour
## ⚡ Getting Started
Recast is accompanied by Detour, a path-finding and spatial reasoning toolkit. You can use any navigation mesh with Detour, but of course the data generated with Recast fits perfectly.
Check out [BuildingAndIntegrating.md](Docs/BuildingAndIntegrating.md) for information on how to build the comprehensive RecastDemo project, as well as guidance on integrating Recast & Detour into your own project.
Detour offers a simple static navmesh data representation which is suitable for many simple cases. It also provides a tiled navigation mesh representation, which allows you to stream of navigation data in and out as the player progresses through the world and regenerate sections of the navmesh data as the world changes.
If you are new to Recast & Detour, check out [Sample_SoloMesh.cpp](/RecastDemo/Source/Sample_SoloMesh.cpp) in RecastDemo to get started with building navmeshes and [NavMeshTesterTool.cpp](/RecastDemo/Source/NavMeshTesterTool.cpp) for building paths with Detour.
## RecastDemo
## ⚙ How it Works
You can find a comprehensive demo project in the `RecastDemo` folder. It's a kitchen sink demo showcasing all the functionality of the library. If you are new to Recast & Detour, check out [Sample_SoloMesh.cpp](/RecastDemo/Source/Sample_SoloMesh.cpp) to get started with building navmeshes and [NavMeshTesterTool.cpp](/RecastDemo/Source/NavMeshTesterTool.cpp) to see how Detour can be used to find paths.
Recast constructs a navmesh through a multi-step mesh rasterization process.
### Building RecastDemo
1. First Recast rasterizes the input triangle meshes into voxels.
2. Voxels in areas where agents would not be able to move are filtered and removed.
3. The walkable areas described by the voxel grid are then divided into sets of polygonal regions.
4. The navigation polygons are generated by re-triangulating the generated polygonal regions into a navmesh.
RecastDemo uses [premake5](http://premake.github.io/) to build platform specific projects. Download it and make sure it's available on your path, or specify the path to it.
You can use Recast to build a single navmesh, or a tiled navmesh.
Single meshes are suitable for many simple, static cases and are easy to work with.
Tiled navmeshes are more complex to work with but better support larger, more dynamic environments. Tiled meshes enable advance Detour features like re-baking, heirarchical path-planning, and navmesh data-streaming.
#### Linux
## 📚 Documentation & Links
- Install SDL2 and its dependencies according to your distro's guidelines.
- Navigate to the `RecastDemo` folder and run `premake5 gmake2`
- Navigate to `RecastDemo/Build/gmake2` and run `make`
- Navigate to `RecastDemo/Bin` and run `./RecastDemo`
Official documentation is available at [recastnav.com](https://recastnav.com)
#### macOS
Docs are generated via [Doxygen](https://www.doxygen.nl/) from source file comments and from markdown files in the `Docs/` directory.
- Grab the latest SDL2 development library dmg from [here](https://github.com/libsdl-org/SDL) and place `SDL2.framework` in `RecastDemo/Bin`
- Navigate to the `RecastDemo` folder and run `premake5 xcode4`
- Open `Build/xcode4/recastnavigation.xcworkspace`
- Set the RecastDemo project as the target and build.
- [Development Roadmap](Docs/Roadmap.md)
- [Changelog](CHANGELOG.md)
- [Contribution Guidelines](CONTRIBUTING.md)
- [Code of Conduct](CODE_OF_CONDUCT.md)
- [Github](https://github.com/recastnavigation/recastnavigation)
#### Windows
## ❤ Community
- Grab the latest SDL2 development library release from [here](https://github.com/libsdl-org/SDL) and unzip it `RecastDemo\Contrib`. Rename the SDL folder such that the path `RecastDemo\Contrib\SDL\lib\x86` is valid.
- Navigate to the `RecastDemo` folder and run `premake5 vs2022`
- Open `Build/vs2022/recastnavigation.sln`.
- Set `RecastDemo` as the startup project, build, and run.
Ask questions, voice ideas, or request new features over on [Github Discussions](https://github.com/recastnavigation/recastnavigation/discussions) or on our old [Google Group](http://groups.google.com/group/recastnavigation) list.
### Running Unit tests
Check out the [Development Roadmap](Docs/Roadmap.md) to see what features and functionality you might be able to help with, and the [Contribution Guidelines](CONTRIBUTING.md) for information on how to make contributions.
- Follow the instructions to build RecastDemo above. Premake should generate another build target called "Tests".
- Build the "Tests" project. This will generate an executable named "Tests" in `RecastDemo/Bin/`
- Run the "Tests" executable. It will execute all the unit tests, indicate those that failed, and display a count of those that succeeded.
Our [Code of Conduct](CODE_OF_CONDUCT.md) applies to all Recast Navigation community channels.
## Integrating with your game or engine
## ⚖ License
- See [Integration.md](Integration.md)
- See [official docs](https://recastnav.com)
- See [official repo](https://github.com/recastnavigation/recastnavigation)
## Contribute
Check out the [Project Roadmap](Roadmap.md) to see what features and functionality you might be able to help with, and the [Contributing doc](CONTRIBUTING.md) for guidance on making contributions.
## Discuss
- Discuss Recast & Detour: http://groups.google.com/group/recastnavigation
- Development blog: http://digestingduck.blogspot.com/
## License
Recast & Detour is licensed under ZLib license, see License.txt for more information.
Recast & Detour is licensed under the ZLib license. See [License.txt](License.txt) for more.