mirror of
https://github.com/recastnavigation/recastnavigation.git
synced 2026-06-08 08:13:49 +00:00
190 lines
12 KiB
HTML
190 lines
12 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml" lang="en-US">
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
|
|
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
|
|
<meta name="generator" content="Doxygen 1.9.8"/>
|
|
<meta name="viewport" content="width=device-width, initial-scale=1"/>
|
|
<title>Recast Navigation: Building & Integrating</title>
|
|
<link href="tabs.css" rel="stylesheet" type="text/css"/>
|
|
<script type="text/javascript" src="jquery.js"></script>
|
|
<script type="text/javascript" src="dynsections.js"></script>
|
|
<link href="navtree.css" rel="stylesheet" type="text/css"/>
|
|
<script type="text/javascript" src="resize.js"></script>
|
|
<script type="text/javascript" src="navtreedata.js"></script>
|
|
<script type="text/javascript" src="navtree.js"></script>
|
|
<link href="search/search.css" rel="stylesheet" type="text/css"/>
|
|
<script type="text/javascript" src="search/searchdata.js"></script>
|
|
<script type="text/javascript" src="search/search.js"></script>
|
|
<link href="doxygen.css" rel="stylesheet" type="text/css" />
|
|
<link href="doxygen-awesome.css" rel="stylesheet" type="text/css"/>
|
|
<link href="doxygen-awesome-sidebar-only.css" rel="stylesheet" type="text/css"/>
|
|
</head>
|
|
<body>
|
|
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
|
|
<div id="titlearea">
|
|
<table cellspacing="0" cellpadding="0">
|
|
<tbody>
|
|
<tr id="projectrow">
|
|
<td id="projectlogo"><img alt="Logo" src="logo.png"/></td>
|
|
<td id="projectalign">
|
|
<div id="projectname">Recast Navigation
|
|
</div>
|
|
<div id="projectbrief">Navigation-mesh Toolset for Games</div>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
<!-- end header part -->
|
|
<!-- Generated by Doxygen 1.9.8 -->
|
|
<script type="text/javascript">
|
|
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
|
|
var searchBox = new SearchBox("searchBox", "search/",'.html');
|
|
/* @license-end */
|
|
</script>
|
|
<script type="text/javascript" src="menudata.js"></script>
|
|
<script type="text/javascript" src="menu.js"></script>
|
|
<script type="text/javascript">
|
|
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
|
|
$(function() {
|
|
initMenu('',true,false,'search.php','Search');
|
|
$(document).ready(function() { init_search(); });
|
|
});
|
|
/* @license-end */
|
|
</script>
|
|
<div id="main-nav"></div>
|
|
</div><!-- top -->
|
|
<div id="side-nav" class="ui-resizable side-nav-resizable">
|
|
<div id="nav-tree">
|
|
<div id="nav-tree-contents">
|
|
<div id="nav-sync" class="sync"></div>
|
|
</div>
|
|
</div>
|
|
<div id="splitbar" style="-moz-user-select:none;"
|
|
class="ui-resizable-handle">
|
|
</div>
|
|
</div>
|
|
<script type="text/javascript">
|
|
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
|
|
$(document).ready(function(){initNavTree('md_Docs_2__2__BuildingAndIntegrating.html',''); initResizable(); });
|
|
/* @license-end */
|
|
</script>
|
|
<div id="doc-content">
|
|
<!-- window showing the filter options -->
|
|
<div id="MSearchSelectWindow"
|
|
onmouseover="return searchBox.OnSearchSelectShow()"
|
|
onmouseout="return searchBox.OnSearchSelectHide()"
|
|
onkeydown="return searchBox.OnSearchSelectKey(event)">
|
|
</div>
|
|
|
|
<!-- iframe showing the search results (closed by default) -->
|
|
<div id="MSearchResultsWindow">
|
|
<div id="MSearchResults">
|
|
<div class="SRPage">
|
|
<div id="SRIndex">
|
|
<div id="SRResults"></div>
|
|
<div class="SRStatus" id="Loading">Loading...</div>
|
|
<div class="SRStatus" id="Searching">Searching...</div>
|
|
<div class="SRStatus" id="NoMatches">No Matches</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<div><div class="header">
|
|
<div class="headertitle"><div class="title">Building & Integrating</div></div>
|
|
</div><!--header-->
|
|
<div class="contents">
|
|
<div class="textblock"><p><a class="anchor" id="building--integrating"></a> Recast is designed to be integrated into your project as source files and built with whatever build system you use.</p>
|
|
<p>For building RecastDemo and for Recast library development there are <a href="http://premake.github.io/">premake5</a> and <a href="https://cmake.org/">cmake</a> build scripts. Premake5 is recommended unless you're already familiar with cmake.</p>
|
|
<h1><a class="anchor" id="building-recastdemo"></a>
|
|
Building RecastDemo</h1>
|
|
<p>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).</p>
|
|
<p>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 <a href="https://github.com/premake/premake-core/releases">download</a> and install premake5 and ensure that the <code>premake5</code> executable location is included in your system path.</p>
|
|
<p>You can also reference the github actions build script <code>.github/Build.yaml</code> for examples of building with specific platform and toolchain combinations.</p>
|
|
<h2><a class="anchor" id="windows"></a>
|
|
Windows</h2>
|
|
<ul>
|
|
<li>Grab the latest SDL2 development library release from <a href="https://github.com/libsdl-org/SDL">here</a> and unzip it into <code>RecastDemo/Contrib</code>. Rename the SDL folder such that the path <code>RecastDemo/Contrib/SDL/lib/x86</code> is valid.</li>
|
|
<li>Navigate to the <code>RecastDemo</code> folder and run <code>premake5 vs2022</code></li>
|
|
<li>Open <code>Build/vs2022/recastnavigation.sln</code> in Visual Studio 2022 or Jetbrains Rider.</li>
|
|
<li>Set <code>RecastDemo</code> as the startup project, build, and run.</li>
|
|
</ul>
|
|
<h2><a class="anchor" id="macos"></a>
|
|
macOS</h2>
|
|
<ul>
|
|
<li>Grab the latest SDL2 development library dmg from <a href="https://github.com/libsdl-org/SDL">here</a> and place <code>SDL2.framework</code> in <code>RecastDemo/Bin</code></li>
|
|
<li>Navigate to the <code>RecastDemo</code> folder and run <code>premake5 xcode4</code></li>
|
|
<li>Open <code>Build/xcode4/recastnavigation.xcworkspace</code> in XCode</li>
|
|
<li>Set the RecastDemo project as the target and build.</li>
|
|
</ul>
|
|
<h2><a class="anchor" id="linux"></a>
|
|
Linux</h2>
|
|
<ul>
|
|
<li>Install SDL2 and its dependencies according to your distro's guidelines.</li>
|
|
<li>Navigate to the <code>RecastDemo</code> folder and run <code>premake5 gmake</code></li>
|
|
<li>Navigate to <code>RecastDemo/Build/gmake</code> and run <code>make</code></li>
|
|
<li>Navigate to <code>RecastDemo/Bin</code> and run <code>./RecastDemo</code></li>
|
|
</ul>
|
|
<h1><a class="anchor" id="preprocessor-defines"></a>
|
|
Preprocessor Defines</h1>
|
|
<p>There are a few symbols you may wish to define when building Recast.</p>
|
|
<table class="markdownTable">
|
|
<tr class="markdownTableHead">
|
|
<th class="markdownTableHeadNone">Symbol </th><th class="markdownTableHeadNone">Usage </th></tr>
|
|
<tr class="markdownTableRowOdd">
|
|
<td class="markdownTableBodyNone"><code>RC_DISABLE_ASSERTS</code> </td><td class="markdownTableBodyNone">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 <code><a class="el" href="RecastAssert_8h.html">RecastAssert.h</a></code> and <code><a class="el" href="DetourAssert_8h.html">DetourAssert.h</a></code>. </td></tr>
|
|
<tr class="markdownTableRowEven">
|
|
<td class="markdownTableBodyNone"><code>DT_POLYREF64</code> </td><td class="markdownTableBodyNone">Use 64 bit (rather than 32 bit) polygon ID references. Generally not needed, but sometimes useful for very large worlds. </td></tr>
|
|
<tr class="markdownTableRowOdd">
|
|
<td class="markdownTableBodyNone"><code>DT_VIRTUAL_QUERYFILTER</code> </td><td class="markdownTableBodyNone">Define this if you plan to sub-class <code><a class="el" href="classdtQueryFilter.html" title="Defines polygon filtering and traversal costs for navigation mesh query operations.">dtQueryFilter</a></code>. Enables the virtual destructor in <code><a class="el" href="classdtQueryFilter.html" title="Defines polygon filtering and traversal costs for navigation mesh query operations.">dtQueryFilter</a></code>. </td></tr>
|
|
</table>
|
|
<h1><a class="anchor" id="running-unit-tests"></a>
|
|
Running Unit tests</h1>
|
|
<ul>
|
|
<li>Follow the instructions to build RecastDemo above. Premake should generate another build target called "Tests".</li>
|
|
<li>Build the "Tests" project. This will generate an executable named "Tests" in <code>RecastDemo/Bin/</code></li>
|
|
<li>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 <a href="https://github.com/catchorg/Catch2/blob/devel/docs/command-line.md#top">Catch2 documentation</a> for information on additional command line options.</li>
|
|
</ul>
|
|
<h1><a class="anchor" id="integration"></a>
|
|
Integration</h1>
|
|
<p>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.</p>
|
|
<h2><a class="anchor" id="source-integration"></a>
|
|
Source Integration</h2>
|
|
<p>It is recommended to add the source directories <code>DebugUtils</code>, <code>Detour</code>, <code>DetourCrowd</code>, <code>DetourTileCache</code>, and <code>Recast</code> directly into your project depending on which parts of the project you need. For example your level building tool could include <code>DebugUtils</code>, <code>Recast</code>, and <code>Detour</code>, and your game runtime could just include <code>Detour</code>.</p>
|
|
<ul>
|
|
<li><em>Recast</em>: Core navmesh building system.</li>
|
|
<li><em>Detour</em>: Runtime navmesh interface and query system</li>
|
|
<li><em>DetourCrowd</em>: Runtime movement, obstacle avoidance and crowd sim systems</li>
|
|
<li><em>DetourTileCache</em>: Runtime navmesh dynamic obstacle and re-baking system</li>
|
|
</ul>
|
|
<h2><a class="anchor" id="installation-through-vcpkg"></a>
|
|
Installation through vcpkg</h2>
|
|
<p>If you are using the <a href="https://github.com/Microsoft/vcpkg/">vcpkg</a> dependency manager you can alternatively download, build, and install Recast with:</p>
|
|
<div class="fragment"><div class="line">vcpkg install recast</div>
|
|
</div><!-- fragment --><h1><a class="anchor" id="customizing-allocation-behavior"></a>
|
|
Customizing Allocation Behavior</h1>
|
|
<p>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 <code>malloc</code> and <code>free</code>. Additionally, the <code>rcAllocHint</code> enum gives some coarse-grained information about the intended lifetime of the allocation. <br />
|
|
</p>
|
|
<p>You can specify your own <code>rcAllocFunc</code> and <code>rcFreeFunc</code> in <code><a class="el" href="RecastAlloc_8cpp.html">RecastAlloc.cpp</a></code> (and similarly in <code><a class="el" href="DetourAlloc_8cpp.html">DetourAlloc.cpp</a></code>) to tune heap usage to your specific needs.</p>
|
|
<h1><a class="anchor" id="a-note-on-dll-exports-and-c-api"></a>
|
|
A Note on DLL exports and C API</h1>
|
|
<p>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. <br />
|
|
</p>
|
|
<p>There are a number of projects that offer unofficial language bindings for Recast, but official support for a C API is currently on our <a class="el" href="md_Docs_2__99__Roadmap.html">development roadmap</a>. </p>
|
|
</div></div><!-- contents -->
|
|
</div><!-- PageDoc -->
|
|
</div><!-- doc-content -->
|
|
<!-- HTML footer for doxygen 1.8.6-->
|
|
<!-- start footer part -->
|
|
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
|
|
<ul>
|
|
<a href="https://github.com/recastnavigation/recastnavigation">Project Home</a>
|
|
| <a href="./License.txt">Licence (ZLib)</a>
|
|
| Copyright 2009 Mikko Mononen
|
|
</ul>
|
|
</div>
|
|
</body>
|
|
</html>
|