游戏开发【免费下载链接】recastnavigationIndustry-standard navigation-mesh toolset for games项目地址https://gitcode.com/gh_mirrors/re/recastnavigation点击查看免费下载本篇技术指南以 RecastNavigation 官方文档《Building Integrating》为骨架系统讲解这个工业级导航网格navigation mesh工具集的构建、测试与工程集成全流程如何在 Windows / macOS / Linux 上编译 RecastDemo 演示程序如何通过预处理器宏定制库行为如何将 Recast、Detour、DetourCrowd、DetourTileCache 以源码方式集成进自有引擎以及如何自定义内存分配与断言处理。读完本文你将能独立完成 RecastNavigation 的本地构建、单元测试运行并把导航网格构建与查询能力嵌入自己的游戏或工具链。一、构建方式总览Premake5 与 CMake 两条路线RecastNavigation 的库代码Recast / Detour / DetourCrowd / DetourTileCache不依赖任何第三方库可以像普通源码一样直接加入任意构建系统。只有两个例外RecastDemo 演示程序依赖 SDL2仓库不附带需自行提供单元测试依赖 Catch2仓库已在Tests/Contrib/catch2/内置无需联网获取。为便于构建 RecastDemo 和进行库开发仓库同时提供了两套构建脚本Premake5RecastDemo/premake5.lua官方推荐除非你本身已熟悉 CMakeCMake顶层CMakeLists.txt适合已有 CMake 工作流的项目。从RecastDemo/premake5.lua的源码可以确认若干默认构建策略全工作区统一使用cppdialect C98见 RecastDemo/premake5.lua这是库本身保持的 C 标准基线默认启用快速浮点运算floatingpoint Fast并定义RC_FAST_MATH宏见 RecastDemo/premake5.lua关闭 RTTI 与异常exceptionhandling Off、rtti Off并在所有配置开启FatalCompileWarnings将警告视为错误Windows 下提供Win32/Win64两个平台Release 配置会自动定义RC_DISABLE_ASSERTS见 RecastDemo/premake5.lua。官方文档还提到可以参阅 GitHub Actions 的 CI 构建脚本.github/Build.yaml获取特定平台与工具链组合的构建示例以下各节给出本地实操步骤。二、构建 RecastDemo开始之前需要先安装Premake5从其官方发布页下载对应平台的 premake5 可执行文件并确保其所在目录已加入系统 PATH在命令行直接输入premake5 --version可验证。2.1 Windows获取最新版SDL2 开发库development library解压到RecastDemo/Contrib目录将解压后的 SDL 文件夹重命名使其满足路径RecastDemo/Contrib/SDL/lib/x86存在即 SDL2 的include与lib子目录位于RecastDemo/Contrib/SDL/下进入RecastDemo目录运行premake5 vs2022用 Visual Studio 2022 或 JetBrains Rider 打开生成的Build/vs2022/recastnavigation.sln将RecastDemo设为启动项目编译并运行。从 RecastDemo/premake5.lua 可看到 Windows 目标会自动链接SDL2、SDL2main、glu32、opengl32并在构建后将SDL2.dll复制到输出目录保证程序可直接运行。2.2 macOS获取 SDL2 开发库的 dmg 安装包将SDL2.framework放到RecastDemo/Bin目录进入RecastDemo目录运行premake5 xcode4用 Xcode 打开Build/xcode4/recastnavigation.xcworkspace将RecastDemo设为构建目标并编译。macOS 目标在 premake 脚本中会把RecastDemo声明为ConsoleApp避免 xcode4 生成器无法运行 WindowedApp 的问题并链接OpenGL.framework、SDL2.framework与Cocoa.framework见 RecastDemo/premake5.lua。2.3 Linux按发行版指引安装 SDL2 及其依赖通常为libsdl2-dev及 OpenGL 开发包premake 脚本通过pkg-config查找sdl2、gl、glu见 RecastDemo/premake5.lua进入RecastDemo目录运行premake5 gmake2进入生成目录并编译cd RecastDemo/Build/gmake2 make运行演示程序cd RecastDemo/Bin ./RecastDemo成功启动后即可看到 3D 场景与导航网格的可视化界面下图即官方文档中的 RecastDemo 运行截屏包含地牢风格场景网格、导航网格多边形以及标注 Start / End 的寻路路径2.4 补充使用 CMake 构建如果项目本身基于 CMake也可以走 CMake 路线。顶层 CMakeLists.txt 提供了完整的配置项除构建库与演示外还支持install安装与find_package包导出。常用配置开关见 CMakeLists.txt选项默认值作用RECASTNAVIGATION_DEMOON是否构建 RecastDemo 演示程序RECASTNAVIGATION_TESTSON是否构建单元测试启用后同时enable_testing()RECASTNAVIGATION_EXAMPLESON是否构建示例RECASTNAVIGATION_DT_POLYREF64OFF是否启用 64 位多边形引用对应宏DT_POLYREF64RECASTNAVIGATION_DT_VIRTUAL_QUERYFILTEROFF是否启用dtQueryFilter虚函数分发对应宏DT_VIRTUAL_QUERYFILTERRECASTNAVIGATION_ENABLE_ASSERTSDebug 为ON其他配置为OFF是否启用自定义断言典型的最小化构建命令仅构建库、跳过演示与测试为cmake -S . -B build -DRECASTNAVIGATION_DEMOOFF -DRECASTNAVIGATION_TESTSOFF cmake --build buildCMake 构建还支持将库安装到系统并生成recastnavigation-config.cmake、recastnavigation.pcpkg-config文件便于后续被其他 CMake 项目以find_package方式消费见 CMakeLists.txt。注意 RecastDemo 目标在 Windows 上仍需要RecastDemo/Contrib/SDL目录提供 SDL2见 RecastDemo/CMakeLists.txt。三、预处理器宏按需定制 Recast 行为构建 Recast 时可通过宏定义调整库的核心行为。官方文档给出的三个关键宏如下宏作用RC_DISABLE_ASSERTS关闭断言宏适合追求极致性能的 Release 构建也可通过自定义断言处理函数替代默认行为详见RecastAssert.h与DetourAssert.hDT_POLYREF64将多边形 ID 引用从 32 位切换为 64 位一般不需要但超大世界场景下可能有用DT_VIRTUAL_QUERYFILTER若计划子类化dtQueryFilter定义此宏可启用其中的虚析构函数3.1RC_DISABLE_ASSERTS关闭或接管断言Recast 与 Detour 分别提供rcAssert与dtAssert宏定义RC_DISABLE_ASSERTS后两个宏都会退化为空操作——通过(void)sizeof(x)引用表达式但不做任何检查连表达式求值都被消除见 Recast/Include/RecastAssert.h 与 Detour/Include/DetourAssert.h未定义该宏时rcAssert/dtAssert默认回落到标准assert()同时可通过rcAssertFailSetCustom()/dtAssertFailSetCustom()注入自定义失败处理函数在断言失败时接管如记录日志、断点触发或向调试器上报函数签名统一为void func(const char* expression, const char* file, int line)见 Recast/Include/RecastAssert.h 与 Detour/Include/DetourAssert.h。值得留意的是即使你不定义该宏Release 构建下 premake 脚本也会自动加上RC_DISABLE_ASSERTS见 RecastDemo/premake5.luaCMake 则通过RECASTNAVIGATION_ENABLE_ASSERTS按配置控制默认 Debug 开启、其他配置关闭。3.2DT_POLYREF64为超大世界启用 64 位多边形引用默认情况下dtPolyRef多边形句柄与dtTileRef瓦片句柄都是 32 位unsigned int。定义DT_POLYREF64后两者均切换为uint64_t见 Detour/Include/DetourNavMesh.h引用位分布相应调整盐值salt16 位、瓦片索引tile28 位、多边形索引poly20 位见 Detour/Include/DetourNavMesh.h在 64 位空间内提供更大的寻址容量。头文件中的注释明确提醒了两点限制见 Detour/Include/DetourNavMesh.h使用 64 位引用时需同时修改dtPolyRef与dtTileRef的类型并建议将dtHashRef()替换为真正的 64 位哈希用 32 位引用构建的瓦片数据与 64 位引用构建的瓦片数据互不兼容切换宏后必须重新烘焙导航网格。CMake 用户可直接通过-DRECASTNAVIGATION_DT_POLYREF64ON开启该宏还会同步写入 pkg-config 的 CFLAGS见 CMakeLists.txt。3.3DT_VIRTUAL_QUERYFILTER允许子类化查询过滤器dtQueryFilter负责导航网格查询时的多边形过滤与穿越代价计算。默认实现中passFilter()与getCost()都是非虚内联函数以最大化性能——头文件注释明确指出在某些平台上间接调用或虚函数调用开销昂贵因此默认采用非虚方案见 Detour/Include/DetourNavMeshQuery.h。当你需要自定义过滤逻辑例如让特定区域类型禁止通行、按区域动态调整代价时定义DT_VIRTUAL_QUERYFILTER后dtQueryFilter获得虚析构函数passFilter()与getCost()变为virtual允许安全地继承和重写见 Detour/Include/DetourNavMeshQuery.h。即便不开此宏默认实现本身也提供了实用的接口setIncludeFlags()/setExcludeFlags()控制哪些多边形可被访问setAreaCost()/getAreaCost()按区域 ID 调整穿越代价见 Detour/Include/DetourNavMeshQuery.h。四、运行单元测试单元测试同样由 premake 生成独立的Tests目标其工程定义见 RecastDemo/premake5.lua。测试工程使用 C14、开启 RTTI 与异常Catch2 需要并默认链接 Recast、Detour、DetourCrowd、DetourTileCache、DebugUtils 五个库。运行步骤按上文方式生成工程后构建名为Tests的目标编译产物是可执行文件Tests输出到RecastDemo/Bin/运行Tests它会执行全部单元测试报告失败项并统计成功数量。测试覆盖的范围可从 Tests/CMakeLists.txt 看到包括 Detour 核心Tests_Detour.cpp、Recast 构建与过滤Tests_Recast.cpp、Tests_RecastFilter.cpp、内存分配Tests_Alloc.cpp、路径走廊Tests_DetourPathCorridor.cpp以及rcVector容器基准Bench_rcVector.cpp。关于 Catch2 的依赖处理构建时会先尝试find_package(Catch2)若系统未安装则自动回退到仓库内置的Tests/Contrib/catch2/catch_amalgamated.cpp见 Tests/CMakeLists.txt所以测试目标无需额外下载依赖。Catch2 还提供了丰富的命令行选项如指定测试用例、输出格式等可按需查阅 Catch2 官方命令行文档。五、将 Recast 与 Detour 集成到你的项目官方推荐且最灵活的方式是源码集成——这也是项目从一开始就为之设计的形态。5.1 源码集成推荐根据实际需求把以下目录Include与Source子目录直接加入你的工程RecastRecast/核心导航网格构建系统负责从三角形网格体素化、区域划分到生成导航网格DetourDetour/运行时导航网格接口与查询系统负责寻路、射线检测、最近点查询等DetourCrowdDetourCrowd/运行时移动、避障与人群模拟系统DetourTileCacheDetourTileCache/运行时导航网格动态障碍与局部重新烘焙系统DebugUtilsDebugUtils/调试可视化辅助依赖以上各模块的 Include见 RecastDemo/premake5.lua。官方文档给出的经典分工示例关卡/场景烘焙工具可包含DebugUtils、Recast、Detour游戏运行时则只需要Detour如需要人群与动态障碍再追加DetourCrowd与DetourTileCache。各模块的依赖关系也可从 premake 工程定义确认DetourCrowd与DetourTileCache都包含Detour与Recast的头文件路径见 RecastDemo/premake5.lua。集成时注意两点库按 C98 标准编写但与你项目的 C 标准并不冲突可放心混用需要同时把对应模块的Include目录加入头文件搜索路径并链接其Source下的全部.cpp。5.2 通过 vcpkg 安装如果使用 vcpkg 依赖管理器可跳过源码集成直接安装预构建好的库vcpkg install recast该命令会下载、构建并安装 Recast含 Recast、Detour、DetourCrowd、DetourTileCache 等组件随后通过 vcpkg 的 integration 机制接入你的 CMake / MSBuild 工程。5.3 补充CMake 包方式源码级若希望以二进制包形式分发仓库顶层 CMakeLists.txt 已内置完整的安装导出流程执行cmake --install后会生成recastnavigation-config.cmake、版本文件与recastnavigation.pc并导出RecastNavigation::命名空间下的 CMake targets见 CMakeLists.txt。这样其他项目可以通过find_package(recastnavigation CONFIG REQUIRED) target_link_libraries(your_target PRIVATE RecastNavigation::Recast)来消费本库具体 target 名称以安装后导出的recastnavigation-targets.cmake为准。此外version.h会在构建时由version.h.in生成并安装见 CMakeLists.txt可用于在代码中读取库版本。六、自定义内存分配行为Recast 与 Detour 在设计中极力避免堆分配但在确实需要分配内存的场合所有分配都会统一路由到可替换的分配函数——默认实现只是简单包装malloc/free。两个库都定义了带生命周期提示的分配枚举RecastrcAllocHint取值RC_ALLOC_PERM调用结束后仍长期存活与RC_ALLOC_TEMP函数内临时使用见 Recast/Include/RecastAlloc.hDetourdtAllocHint同样提供DT_ALLOC_PERM/DT_ALLOC_TEMP见 Detour/Include/DetourAlloc.h。分配/释放函数指针类型分别为rcAllocFunc(size_t size, rcAllocHint hint)与rcFreeFunc(void* ptr)见 Recast/Include/RecastAlloc.hDetour 侧与之对应。接入自定义分配器有两种方式直接修改源文件编辑 Recast/Source/RecastAlloc.cpp或 Detour/Source/DetourAlloc.cpp把默认的rcAllocDefault/rcFreeDefault即malloc/free替换为你的实现运行时注入在程序启动早期调用rcAllocSetCustom(allocFunc, freeFunc)与dtAllocSetCustom(allocFunc, freeFunc)全局替换分配器——函数内部对空指针参数做了保护传入NULL会回落到默认实现见 Recast/Source/RecastAlloc.cpp 与 Detour/Source/DetourAlloc.cpp。典型场景包括接入游戏引擎已有的内存池 / 帧分配器、开启内存统计与泄漏追踪、对齐分配以满足 SIMD 需求等。此外RecastAlloc.h还提供了一套基于rcAlloc/rcFree的rcVectorBaseT, H容器含rcTempVector与rcPermVector两个特化以及向后兼容的rcIntArray底层存储全部走上述分配接口因此自定义分配器会全局生效见 Recast/Include/RecastAlloc.h。七、关于 DLL 导出与 C API 的说明Recast目前不提供稳定的 C API因此也不支持直接以 DLL 导出或作为其他语言的绑定接口使用。原因在于其设计大量依赖 C 特性模板、引用、重载等要提供稳定 C 接口需要对核心代码做较大改动。对需要跨语言调用的场景官方态度是社区中已存在多个非官方语言绑定项目可作参考官方支持 C API 目前处于开发路线图中详见 Docs/_99_Roadmap.md。若你的项目必须走动态链接从仓库现状看顶层 CMakeLists.txt 在 MSVC BUILD_SHARED_LIBS下开启了CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS这意味着在 Windows 上以共享库方式构建时符号会被自动导出但这并不等同于提供稳定的 C ABI跨版本兼容仍需自行评估。八、相关资源路径速查用途路径官方构建与集成文档Docs/_2_BuildingAndIntegrating.md官方路线图含 C API 计划Docs/_99_Roadmap.mdPremake 构建脚本RecastDemo/premake5.lua顶层 CMake 构建脚本CMakeLists.txtRecastDemo 的 CMake 脚本RecastDemo/CMakeLists.txt分配器接口RecastRecast/Include/RecastAlloc.h、Recast/Source/RecastAlloc.cpp分配器接口DetourDetour/Include/DetourAlloc.h、Detour/Source/DetourAlloc.cpp断言接口Recast/Include/RecastAssert.h、Detour/Include/DetourAssert.h64 位引用定义Detour/Include/DetourNavMesh.h查询过滤器定义Detour/Include/DetourNavMeshQuery.h单元测试工程Tests/CMakeLists.txt、Tests/综上所述RecastNavigation 的接入路径高度灵活演示与开发用 Premake5/CMake 一把梭正式项目既可以直接拷贝源码编译也可以通过 vcpkg 或 CMake 包方式集成通过RC_DISABLE_ASSERTS、DT_POLYREF64、DT_VIRTUAL_QUERYFILTER三个宏与全局可替换的分配器/断言接口几乎可以在不改动库代码的前提下把导航能力无缝嵌入任何引擎架构。赞分享游戏开发【免费下载链接】recastnavigationIndustry-standard navigation-mesh toolset for games项目地址https://gitcode.com/gh_mirrors/re/recastnavigation点击查看免费下载相关推荐GoogleTest 构建与编译配置完全指南从 CMake 集成到编译宏级定制GoogleTest 构建与编译配置完全指南从 CMake 集成到编译宏级定制 本篇指南以仓库内 googletest/README.md https://l测试质量保障开发工具miniblink49 内嵌 V8 的 Google Testgtest构建与集成指南从源码编译到宏级定制miniblink49 内嵌 V8 的 Google Testgtest构建与集成指南从源码编译到宏级定制 导读 本文以 miniblink49 仓库中前端桌面应用miniblink49 内嵌 Google Testgtest完整构建与配置指南从源码编译到宏定制miniblink49 内嵌 Google Testgtest完整构建与配置指南从源码编译到宏定制 导读 本文以 v8_6_7/testing/gtest前端桌面应用创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考