Support rendering for navmesh update frequency as a heatmap

Useful when need to find tiles with high number of updates.

Add debug Lua package with new functions to toggle render mode and set navmesh
render mode.

apps/openmw/CMakeLists.txt

@@ -23,7 +23,7 @@ add_openmw_dir (mwrender
     creatureanimation effectmanager util renderinginterface pathgrid rendermode weaponanimation screenshotmanager
     bulletdebugdraw globalmap characterpreview camera localmap water terrainstorage ripplesimulation
     renderbin actoranimation landmanager navmesh actorspaths recastmesh fogmanager objectpaging groundcover
-    postprocessor pingpongcull hdr pingpongcanvas transparentpass
+    postprocessor pingpongcull hdr pingpongcanvas transparentpass navmeshmode
     )
 
 add_openmw_dir (mwinput
@@ -61,7 +61,7 @@ add_openmw_dir (mwscript
 add_openmw_dir (mwlua
     luamanagerimp object worldview userdataserializer eventqueue
     luabindings localscripts playerscripts objectbindings cellbindings asyncbindings settingsbindings
-    camerabindings uibindings inputbindings nearbybindings postprocessingbindings stats
+    camerabindings uibindings inputbindings nearbybindings postprocessingbindings stats debugbindings
     types/types types/door types/actor types/container types/weapon types/npc types/creature
     )
 

apps/openmw/mwlua/debugbindings.cpp

@@ -0,0 +1,51 @@
+#include "debugbindings.hpp"
+#include "context.hpp"
+#include "luamanagerimp.hpp"
+
+#include "../mwbase/environment.hpp"
+#include "../mwbase/world.hpp"
+#include "../mwrender/renderingmanager.hpp"
+
+#include <components/lua/luastate.hpp>
+
+namespace MWLua
+{
+    sol::table initDebugPackage(const Context& context)
+    {
+        sol::table api = context.mLua->newTable();
+
+        api["RENDER_MODE"] = LuaUtil::makeStrictReadOnly(context.mLua->tableFromPairs<std::string_view, MWRender::RenderMode>({
+            {"CollisionDebug", MWRender::Render_CollisionDebug},
+            {"Wireframe", MWRender::Render_Wireframe},
+            {"Pathgrid", MWRender::Render_Pathgrid},
+            {"Water", MWRender::Render_Water},
+            {"Scene", MWRender::Render_Scene},
+            {"NavMesh", MWRender::Render_NavMesh},
+            {"ActorsPaths", MWRender::Render_ActorsPaths},
+            {"RecastMesh", MWRender::Render_RecastMesh},
+        }));
+
+        api["toggleRenderMode"] = [context] (MWRender::RenderMode value)
+        {
+            context.mLuaManager->addAction([value]
+            {
+                MWBase::Environment::get().getWorld()->toggleRenderMode(value);
+            });
+        };
+
+        api["NAV_MESH_RENDER_MODE"] = LuaUtil::makeStrictReadOnly(context.mLua->tableFromPairs<std::string_view, MWRender::NavMeshMode>({
+            {"AreaType", MWRender::NavMeshMode::AreaType},
+            {"UpdateFrequency", MWRender::NavMeshMode::UpdateFrequency},
+        }));
+
+        api["setNavMeshRenderMode"] = [context] (MWRender::NavMeshMode value)
+        {
+            context.mLuaManager->addAction([value]
+            {
+                MWBase::Environment::get().getWorld()->getRenderingManager()->setNavMeshMode(value);
+            });
+        };
+
+        return LuaUtil::makeReadOnly(api);
+    }
+}

apps/openmw/mwlua/debugbindings.hpp

@@ -0,0 +1,13 @@
+#ifndef OPENMW_MWLUA_DEBUGBINDINGS_H
+#define OPENMW_MWLUA_DEBUGBINDINGS_H
+
+#include <sol/sol.hpp>
+
+namespace MWLua
+{
+    struct Context;
+
+    sol::table initDebugPackage(const Context& context);
+}
+
+#endif // OPENMW_MWLUA_DEBUGBINDINGS_H

apps/openmw/mwlua/luabindings.cpp

@@ -41,7 +41,7 @@ namespace MWLua
     {
         auto* lua = context.mLua;
         sol::table api(lua->sol(), sol::create);
-        api["API_REVISION"] = 22;
+        api["API_REVISION"] = 23;
         api["quit"] = [lua]()
         {
             Log(Debug::Warning) << "Quit requested by a Lua script.\n" << lua->debugTraceback();

apps/openmw/mwlua/luamanagerimp.cpp

@@ -23,6 +23,7 @@
 #include "luabindings.hpp"
 #include "userdataserializer.hpp"
 #include "types/types.hpp"
+#include "debugbindings.hpp"
 
 namespace MWLua
 {
@@ -96,6 +97,7 @@ namespace MWLua
         mLocalStoragePackage = initLocalStoragePackage(localContext, &mGlobalStorage);
         mPlayerStoragePackage = initPlayerStoragePackage(localContext, &mGlobalStorage, &mPlayerStorage);
         mPostprocessingPackage = initPostprocessingPackage(localContext);
+        mDebugPackage = initDebugPackage(localContext);
 
         initConfiguration();
         mInitialized = true;
@@ -409,6 +411,7 @@ namespace MWLua
             scripts->addPackage("openmw.settings", mPlayerSettingsPackage);
             scripts->addPackage("openmw.storage", mPlayerStoragePackage);
             scripts->addPackage("openmw.postprocessing", mPostprocessingPackage);
+            scripts->addPackage("openmw.debug", mDebugPackage);
         }
         else
         {

apps/openmw/mwlua/luamanagerimp.hpp

@@ -141,6 +141,7 @@ namespace MWLua
         sol::table mLocalStoragePackage;
         sol::table mPlayerStoragePackage;
         sol::table mPostprocessingPackage;
+        sol::table mDebugPackage;
 
         GlobalScripts mGlobalScripts{&mLua};
         std::set<LocalScripts*> mActiveLocalScripts;

apps/openmw/mwrender/navmesh.cpp

@@ -12,6 +12,8 @@
 #include <osg/PositionAttitudeTransform>
 #include <osg/StateSet>
 
+#include <DetourNavMesh.h>
+
 #include "../mwbase/world.hpp"
 #include "../mwbase/environment.hpp"
 
@@ -43,6 +45,7 @@ namespace MWRender
         const osg::ref_ptr<osg::StateSet> mDebugDrawStateSet;
         const DetourNavigator::Settings mSettings;
         std::map<DetourNavigator::TilePosition, Tile> mTiles;
+        NavMeshMode mMode;
         std::atomic_bool mAborted {false};
         std::mutex mMutex;
         bool mStarted = false;
@@ -52,7 +55,8 @@ namespace MWRender
         explicit CreateNavMeshTileGroups(std::size_t id, DetourNavigator::Version version,
             std::weak_ptr<DetourNavigator::GuardedNavMeshCacheItem> navMesh,
             const osg::ref_ptr<osg::StateSet>& groupStateSet, const osg::ref_ptr<osg::StateSet>& debugDrawStateSet,
-            const DetourNavigator::Settings& settings, const std::map<DetourNavigator::TilePosition, Tile>& tiles)
+            const DetourNavigator::Settings& settings, const std::map<DetourNavigator::TilePosition, Tile>& tiles,
+            NavMeshMode mode)
             : mId(id)
             , mVersion(version)
             , mNavMesh(navMesh)
@@ -60,6 +64,7 @@ namespace MWRender
             , mDebugDrawStateSet(debugDrawStateSet)
             , mSettings(settings)
             , mTiles(tiles)
+            , mMode(mode)
         {
         }
 
@@ -79,10 +84,14 @@ namespace MWRender
                 return;
 
             std::vector<std::pair<DetourNavigator::TilePosition, Version>> existingTiles;
+            unsigned minSalt = std::numeric_limits<unsigned>::max();
+            unsigned maxSalt = 0;
 
-            navMeshPtr->lockConst()->forEachUsedTile([&] (const TilePosition& position, const Version& version, const dtMeshTile& /*meshTile*/)
+            navMeshPtr->lockConst()->forEachUsedTile([&] (const TilePosition& position, const Version& version, const dtMeshTile& meshTile)
             {
                 existingTiles.emplace_back(position, version);
+                minSalt = std::min(minSalt, meshTile.salt);
+                maxSalt = std::max(maxSalt, meshTile.salt);
             });
 
             if (mAborted.load(std::memory_order_acquire))
@@ -98,10 +107,15 @@ namespace MWRender
 
             std::vector<std::pair<TilePosition, Tile>> updatedTiles;
 
+            const unsigned char flags = SceneUtil::NavMeshTileDrawFlagsOffMeshConnections
+                | SceneUtil::NavMeshTileDrawFlagsClosedList
+                | (mMode == NavMeshMode::UpdateFrequency ? SceneUtil::NavMeshTileDrawFlagsHeat : 0);
+
             for (const auto& [position, version] : existingTiles)
             {
                 const auto it = mTiles.find(position);
-                if (it != mTiles.end() && it->second.mGroup != nullptr && it->second.mVersion == version)
+                if (it != mTiles.end() && it->second.mGroup != nullptr && it->second.mVersion == version
+                        && mMode != NavMeshMode::UpdateFrequency)
                     continue;
 
                 osg::ref_ptr<osg::Group> group;
@@ -114,7 +128,8 @@ namespace MWRender
                     if (mAborted.load(std::memory_order_acquire))
                         return;
 
-                    group = SceneUtil::createNavMeshTileGroup(navMesh->getImpl(), *meshTile, mSettings, mGroupStateSet, mDebugDrawStateSet);
+                    group = SceneUtil::createNavMeshTileGroup(navMesh->getImpl(), *meshTile, mSettings, mGroupStateSet,
+                        mDebugDrawStateSet, flags, minSalt, maxSalt);
                 }
                 if (group == nullptr)
                 {
@@ -147,12 +162,14 @@ namespace MWRender
             : mWorkItem(std::move(workItem)) {}
     };
 
-    NavMesh::NavMesh(const osg::ref_ptr<osg::Group>& root, const osg::ref_ptr<SceneUtil::WorkQueue>& workQueue, bool enabled)
+    NavMesh::NavMesh(const osg::ref_ptr<osg::Group>& root, const osg::ref_ptr<SceneUtil::WorkQueue>& workQueue,
+                     bool enabled, NavMeshMode mode)
         : mRootNode(root)
         , mWorkQueue(workQueue)
         , mGroupStateSet(SceneUtil::makeNavMeshTileStateSet())
         , mDebugDrawStateSet(SceneUtil::DebugDraw::makeStateSet())
         , mEnabled(enabled)
+        , mMode(mode)
         , mId(std::numeric_limits<std::size_t>::max())
     {
     }
@@ -261,11 +278,13 @@ namespace MWRender
             workItem->mId = id;
             workItem->mVersion = version;
             workItem->mTiles = mTiles;
+            workItem->mMode = mMode;
 
             return;
         }
 
-        osg::ref_ptr<CreateNavMeshTileGroups> workItem = new CreateNavMeshTileGroups(id, version, navMesh, mGroupStateSet, mDebugDrawStateSet, settings, mTiles);
+        osg::ref_ptr<CreateNavMeshTileGroups> workItem = new CreateNavMeshTileGroups(id, version, navMesh,
+            mGroupStateSet, mDebugDrawStateSet, settings, mTiles, mMode);
         mWorkQueue->addWorkItem(workItem);
         mWorkItems.push_back(std::move(workItem));
     }
@@ -290,4 +309,12 @@ namespace MWRender
         reset();
         mEnabled = false;
     }
+
+    void NavMesh::setMode(NavMeshMode value)
+    {
+        if (mMode == value)
+            return;
+        reset();
+        mMode = value;
+    }
 }

apps/openmw/mwrender/navmesh.hpp

@@ -1,6 +1,8 @@
 #ifndef OPENMW_MWRENDER_NAVMESH_H
 #define OPENMW_MWRENDER_NAVMESH_H
 
+#include "navmeshmode.hpp"
+
 #include <components/detournavigator/version.hpp>
 #include <components/detournavigator/tileposition.hpp>
 #include <components/misc/guarded.hpp>
@@ -11,6 +13,7 @@
 #include <map>
 #include <memory>
 #include <vector>
+#include <string_view>
 
 class dtNavMesh;
 
@@ -38,7 +41,7 @@ namespace MWRender
     {
     public:
         explicit NavMesh(const osg::ref_ptr<osg::Group>& root, const osg::ref_ptr<SceneUtil::WorkQueue>& workQueue,
-                         bool enabled);
+                         bool enabled, NavMeshMode mode);
         ~NavMesh();
 
         bool toggle();
@@ -57,6 +60,8 @@ namespace MWRender
             return mEnabled;
         }
 
+        void setMode(NavMeshMode value);
+
     private:
         struct Tile
         {
@@ -73,6 +78,7 @@ namespace MWRender
         osg::ref_ptr<osg::StateSet> mGroupStateSet;
         osg::ref_ptr<osg::StateSet> mDebugDrawStateSet;
         bool mEnabled;
+        NavMeshMode mMode;
         std::size_t mId;
         DetourNavigator::Version mVersion;
         std::map<DetourNavigator::TilePosition, Tile> mTiles;

apps/openmw/mwrender/navmeshmode.cpp

@@ -0,0 +1,16 @@
+#include "navmeshmode.hpp"
+
+#include <stdexcept>
+#include <string>
+
+namespace MWRender
+{
+    NavMeshMode parseNavMeshMode(std::string_view value)
+    {
+        if (value == "area type")
+            return NavMeshMode::AreaType;
+        if (value == "update frequency")
+            return NavMeshMode::UpdateFrequency;
+        throw std::logic_error("Unsupported navigation mesh rendering mode: " + std::string(value));
+    }
+}

apps/openmw/mwrender/navmeshmode.hpp

@@ -0,0 +1,17 @@
+#ifndef OPENMW_MWRENDER_NAVMESHMODE_H
+#define OPENMW_MWRENDER_NAVMESHMODE_H
+
+#include <string_view>
+
+namespace MWRender
+{
+    enum class NavMeshMode
+    {
+        AreaType,
+        UpdateFrequency,
+    };
+
+    NavMeshMode parseNavMeshMode(std::string_view value);
+}
+
+#endif

apps/openmw/mwrender/renderingmanager.cpp

@@ -435,7 +435,8 @@ namespace MWRender
         // It is unnecessary to stop/start the viewer as no frames are being rendered yet.
         mResourceSystem->getSceneManager()->getShaderManager().setGlobalDefines(globalDefines);
 
-        mNavMesh.reset(new NavMesh(mRootNode, mWorkQueue, Settings::Manager::getBool("enable nav mesh render", "Navigator")));
+        mNavMesh.reset(new NavMesh(mRootNode, mWorkQueue, Settings::Manager::getBool("enable nav mesh render", "Navigator"),
+                                   parseNavMeshMode(Settings::Manager::getString("nav mesh render mode", "Navigator"))));
         mActorsPaths.reset(new ActorsPaths(mRootNode, Settings::Manager::getBool("enable agents paths render", "Navigator")));
         mRecastMesh.reset(new RecastMesh(mRootNode, Settings::Manager::getBool("enable recast mesh render", "Navigator")));
         mPathgrid.reset(new Pathgrid(mRootNode));
@@ -1573,4 +1574,9 @@ namespace MWRender
         if (mObjectPaging)
             mObjectPaging->getPagedRefnums(activeGrid, out);
     }
+
+    void RenderingManager::setNavMeshMode(NavMeshMode value)
+    {
+        mNavMesh->setMode(value);
+    }
 }

apps/openmw/mwrender/renderingmanager.hpp

@@ -10,7 +10,7 @@
 #include <osgUtil/IncrementalCompileOperation>
 
 #include "objects.hpp"
-
+#include "navmeshmode.hpp"
 #include "renderinginterface.hpp"
 #include "rendermode.hpp"
 
@@ -253,6 +253,8 @@ namespace MWRender
 
         void setScreenRes(int width, int height);
 
+        void setNavMeshMode(NavMeshMode value);
+
     private:
         void updateTextureFiltering();
         void updateAmbient();

components/sceneutil/navmesh.cpp

@@ -10,6 +10,8 @@
 #include <osg/Material>
 #include <osg/PolygonOffset>
 
+#include <algorithm>
+
 namespace
 {
     // Copied from https://github.com/recastnavigation/recastnavigation/blob/c5cbd53024c8a9d8d097a4371215e3342d2fdc87/DebugUtils/Source/DetourDebugDraw.cpp#L26-L38
@@ -107,15 +109,46 @@ namespace
         dd->end();
     }
 
+    float getHeat(unsigned salt, unsigned minSalt, unsigned maxSalt)
+    {
+        if (salt < minSalt)
+            return 0;
+        if (salt > maxSalt)
+            return 1;
+        if (maxSalt <= minSalt)
+            return 0.5;
+        return static_cast<float>(salt - minSalt) / static_cast<float>(maxSalt - minSalt);
+    }
+
+    int getRgbaComponent(float v, int base)
+    {
+        return static_cast<int>(std::round(v * base));
+    }
+
+    unsigned heatToColor(float heat, int alpha)
+    {
+        constexpr int min = 100;
+        constexpr int max = 200;
+        if (heat < 0.25f)
+            return duRGBA(min, min + getRgbaComponent(4 * heat, max - min), max, alpha);
+        if (heat < 0.5f)
+            return duRGBA(min, max, min + getRgbaComponent(1 - 4 * (heat - 0.5f), max - min), alpha);
+        if (heat < 0.75f)
+            return duRGBA(min + getRgbaComponent(4 * (heat - 0.5f), max - min), max, min, alpha);
+        return duRGBA(max, min + getRgbaComponent(1 - 4 * (heat - 0.75f), max - min), min, alpha);
+    }
+
     // Based on https://github.com/recastnavigation/recastnavigation/blob/c5cbd53024c8a9d8d097a4371215e3342d2fdc87/DebugUtils/Source/DetourDebugDraw.cpp#L120-L235
     void drawMeshTile(duDebugDraw* dd, const dtNavMesh& mesh, const dtNavMeshQuery* query,
-        const dtMeshTile* tile, unsigned char flags)
+        const dtMeshTile* tile, unsigned char flags, float heat)
     {
+        using namespace SceneUtil;
+
         dtPolyRef base = mesh.getPolyRefBase(tile);
 
         int tileNum = mesh.decodePolyIdTile(base);
-        const unsigned int tileNumColor = duIntToCol(tileNum, 128);
         const unsigned alpha = tile->header->userId == 0 ? 64 : 128;
+        const unsigned int tileNumColor = duIntToCol(tileNum, alpha);
 
         dd->depthMask(false);
 
@@ -133,8 +166,10 @@ namespace
                 col = duRGBA(255, 196, 0, alpha);
             else
             {
-                if (flags & DU_DRAWNAVMESH_COLOR_TILES)
+                if (flags & NavMeshTileDrawFlagsColorTiles)
                     col = duTransCol(tileNumColor, alpha);
+                else if (flags & NavMeshTileDrawFlagsHeat)
+                    col = heatToColor(heat, alpha);
                 else
                     col = duTransCol(dd->areaToCol(p->getArea()), alpha);
             }
@@ -159,7 +194,7 @@ namespace
         // Draw outer poly boundaries
         drawPolyBoundaries(dd, tile, duRGBA(0,48,64,220), 2.5f, false);
 
-        if (flags & DU_DRAWNAVMESH_OFFMESHCONS)
+        if (flags & NavMeshTileDrawFlagsOffMeshConnections)
         {
             dd->begin(DU_DRAW_LINES, 2.0f);
             for (int i = 0; i < tile->header->polyCount; ++i)
@@ -246,7 +281,7 @@ namespace SceneUtil
 
     osg::ref_ptr<osg::Group> createNavMeshTileGroup(const dtNavMesh& navMesh, const dtMeshTile& meshTile,
         const DetourNavigator::Settings& settings, const osg::ref_ptr<osg::StateSet>& groupStateSet,
-        const osg::ref_ptr<osg::StateSet>& debugDrawStateSet)
+        const osg::ref_ptr<osg::StateSet>& debugDrawStateSet, unsigned char flags, unsigned minSalt, unsigned maxSalt)
     {
         if (meshTile.header == nullptr)
             return nullptr;
@@ -257,7 +292,7 @@ namespace SceneUtil
         DebugDraw debugDraw(*group, debugDrawStateSet, osg::Vec3f(0, 0, shift), 1.0f / settings.mRecast.mRecastScaleFactor);
         dtNavMeshQuery navMeshQuery;
         navMeshQuery.init(&navMesh, settings.mDetour.mMaxNavMeshQueryNodes);
-        drawMeshTile(&debugDraw, navMesh, &navMeshQuery, &meshTile, DU_DRAWNAVMESH_OFFMESHCONS | DU_DRAWNAVMESH_CLOSEDLIST);
+        drawMeshTile(&debugDraw, navMesh, &navMeshQuery, &meshTile, flags, getHeat(meshTile.salt, minSalt, maxSalt));
 
         return group;
     }

components/sceneutil/navmesh.hpp

@@ -19,11 +19,19 @@ namespace DetourNavigator
 
 namespace SceneUtil
 {
+    enum NavMeshTileDrawFlags : unsigned char
+    {
+        NavMeshTileDrawFlagsOffMeshConnections = 1,
+        NavMeshTileDrawFlagsClosedList = 1 << 1,
+        NavMeshTileDrawFlagsColorTiles = 1 << 2,
+        NavMeshTileDrawFlagsHeat = 1 << 3,
+    };
+
     osg::ref_ptr<osg::StateSet> makeNavMeshTileStateSet();
 
     osg::ref_ptr<osg::Group> createNavMeshTileGroup(const dtNavMesh& navMesh, const dtMeshTile& meshTile,
         const DetourNavigator::Settings& settings, const osg::ref_ptr<osg::StateSet>& groupStateSet,
-        const osg::ref_ptr<osg::StateSet>& debugDrawStateSet);
+        const osg::ref_ptr<osg::StateSet>& debugDrawStateSet, unsigned char flags, unsigned minSalt, unsigned maxSalt);
 }
 
 #endif

docs/source/reference/lua-scripting/api.rst

@@ -21,6 +21,7 @@ Lua API reference
     openmw_ui
     openmw_camera
     openmw_postprocessing
+    openmw_debug
     openmw_aux_calendar
     openmw_aux_util
     openmw_aux_time
@@ -47,54 +48,14 @@ It can not be overloaded even if there is a lua file with the same name.
 The list of available packages is different for global and for local scripts.
 Player scripts are local scripts that are attached to a player.
 
-+------------------------------------------------------------+--------------------+---------------------------------------------------------------+
+.. include:: tables/packages.rst
-| Package                                                    | Can be used        | Description                                                   |
-+============================================================+====================+===============================================================+
-|:ref:`openmw.interfaces <Script interfaces>`                | everywhere         | | Public interfaces of other scripts.                         |
-+------------------------------------------------------------+--------------------+---------------------------------------------------------------+
-|:ref:`openmw.util <Package openmw.util>`                    | everywhere         | | Defines utility functions and classes like 3D vectors,      |
-|                                                            |                    | | that don't depend on the game world.                        |
-+------------------------------------------------------------+--------------------+---------------------------------------------------------------+
-|:ref:`openmw.storage <Package openmw.storage>`              | everywhere         | | Storage API. In particular can be used to store data        |
-|                                                            |                    | | between game sessions.                                      |
-+------------------------------------------------------------+--------------------+---------------------------------------------------------------+
-|:ref:`openmw.core <Package openmw.core>`                    | everywhere         | | Functions that are common for both global and local scripts |
-+------------------------------------------------------------+--------------------+---------------------------------------------------------------+
-|:ref:`openmw.types <Package openmw.types>`                  | everywhere         | | Functions for specific types of game objects.               |
-+------------------------------------------------------------+--------------------+---------------------------------------------------------------+
-|:ref:`openmw.async <Package openmw.async>`                  | everywhere         | | Timers (implemented) and coroutine utils (not implemented)  |
-+------------------------------------------------------------+--------------------+---------------------------------------------------------------+
-|:ref:`openmw.world <Package openmw.world>`                  | by global scripts  | | Read-write access to the game world.                        |
-+------------------------------------------------------------+--------------------+---------------------------------------------------------------+
-|:ref:`openmw.self <Package openmw.self>`                    | by local scripts   | | Full access to the object the script is attached to.        |
-+------------------------------------------------------------+--------------------+---------------------------------------------------------------+
-|:ref:`openmw.nearby <Package openmw.nearby>`                | by local scripts   | | Read-only access to the nearest area of the game world.     |
-+------------------------------------------------------------+--------------------+---------------------------------------------------------------+
-|:ref:`openmw.input <Package openmw.input>`                  | by player scripts  | | User input.                                                 |
-+------------------------------------------------------------+--------------------+---------------------------------------------------------------+
-|:ref:`openmw.ui <Package openmw.ui>`                        | by player scripts  | | Controls :ref:`user interface <User interface reference>`.  |
-+------------------------------------------------------------+--------------------+---------------------------------------------------------------+
-|:ref:`openmw.camera <Package openmw.camera>`                | by player scripts  | | Controls camera.                                            |
-+------------------------------------------------------------+--------------------+---------------------------------------------------------------+
-|:ref:`openmw.postprocessing <Package openmw.postprocessing>`| by player scripts  | | Controls post-process shaders.                              |
-+------------------------------------------------------------+--------------------+---------------------------------------------------------------+
 
 **openmw_aux**
 
 ``openmw_aux.*`` are built-in libraries that are itself implemented in Lua. They can not do anything that is not possible with the basic API, they only make it more convenient.
 Sources can be found in ``resources/vfs/openmw_aux``. In theory mods can override them, but it is not recommended.
 
-+---------------------------------------------------------+--------------------+---------------------------------------------------------------+
+.. include:: tables/aux_packages.rst
-| Built-in library                                        | Can be used        | Description                                                   |
-+=========================================================+====================+===============================================================+
-|:ref:`openmw_aux.calendar <Package openmw_aux.calendar>` | everywhere         | | Game time calendar                                          |
-+---------------------------------------------------------+--------------------+---------------------------------------------------------------+
-|:ref:`openmw_aux.util <Package openmw_aux.util>`         | everywhere         | | Miscellaneous utils                                         |
-+---------------------------------------------------------+--------------------+---------------------------------------------------------------+
-|:ref:`openmw_aux.time <Package openmw_aux.time>`         | everywhere         | | Timers and game time utils                                  |
-+---------------------------------------------------------+--------------------+---------------------------------------------------------------+
-|:ref:`openmw_aux.ui <Package openmw_aux.ui>`             | by player scripts  | | User interface utils                                        |
-+---------------------------------------------------------+--------------------+---------------------------------------------------------------+
 
 **Interfaces of built-in scripts**
 

docs/source/reference/lua-scripting/openmw_debug.rst

@@ -0,0 +1,5 @@
+Package openmw.debug
+====================
+
+.. raw:: html
+   :file: generated_html/openmw_debug.html

docs/source/reference/lua-scripting/overview.rst

@@ -340,37 +340,7 @@ It can not be overloaded even if there is a lua file with the same name.
 The list of available packages is different for global and for local scripts.
 Player scripts are local scripts that are attached to a player.
 
-+------------------------------------------------------------+--------------------+---------------------------------------------------------------+
+.. include:: tables/packages.rst
-| Package                                                    | Can be used        | Description                                                   |
-+============================================================+====================+===============================================================+
-|:ref:`openmw.interfaces <Script interfaces>`                | everywhere         | | Public interfaces of other scripts.                         |
-+------------------------------------------------------------+--------------------+---------------------------------------------------------------+
-|:ref:`openmw.util <Package openmw.util>`                    | everywhere         | | Defines utility functions and classes like 3D vectors,      |
-|                                                            |                    | | that don't depend on the game world.                        |
-+------------------------------------------------------------+--------------------+---------------------------------------------------------------+
-|:ref:`openmw.storage <Package openmw.storage>`              | everywhere         | | Storage API. In particular can be used to store data        |
-|                                                            |                    | | between game sessions.                                      |
-+------------------------------------------------------------+--------------------+---------------------------------------------------------------+
-|:ref:`openmw.core <Package openmw.core>`                    | everywhere         | | Functions that are common for both global and local scripts |
-+------------------------------------------------------------+--------------------+---------------------------------------------------------------+
-|:ref:`openmw.types <Package openmw.types>`                  | everywhere         | | Functions for specific types of game objects.               |
-+------------------------------------------------------------+--------------------+---------------------------------------------------------------+
-|:ref:`openmw.async <Package openmw.async>`                  | everywhere         | | Timers (implemented) and coroutine utils (not implemented)  |
-+------------------------------------------------------------+--------------------+---------------------------------------------------------------+
-|:ref:`openmw.world <Package openmw.world>`                  | by global scripts  | | Read-write access to the game world.                        |
-+------------------------------------------------------------+--------------------+---------------------------------------------------------------+
-|:ref:`openmw.self <Package openmw.self>`                    | by local scripts   | | Full access to the object the script is attached to.        |
-+------------------------------------------------------------+--------------------+---------------------------------------------------------------+
-|:ref:`openmw.nearby <Package openmw.nearby>`                | by local scripts   | | Read-only access to the nearest area of the game world.     |
-+------------------------------------------------------------+--------------------+---------------------------------------------------------------+
-|:ref:`openmw.input <Package openmw.input>`                  | by player scripts  | | User input                                                  |
-+------------------------------------------------------------+--------------------+---------------------------------------------------------------+
-|:ref:`openmw.ui <Package openmw.ui>`                        | by player scripts  | | Controls :ref:`user interface <User interface reference>`   |
-+------------------------------------------------------------+--------------------+---------------------------------------------------------------+
-|:ref:`openmw.camera <Package openmw.camera>`                | by player scripts  | | Controls camera                                             |
-+------------------------------------------------------------+--------------------+---------------------------------------------------------------+
-|:ref:`openmw.postprocessing <Package openmw.postprocessing>`| by player scripts  | | Controls postprocess shaders                                |
-+------------------------------------------------------------+--------------------+---------------------------------------------------------------+
 
 openmw_aux
 ----------
@@ -378,15 +348,7 @@ openmw_aux
 ``openmw_aux.*`` are built-in libraries that are themselves implemented in Lua. They can not do anything that is not possible with the basic API, they only make it more convenient.
 Sources can be found in ``resources/vfs/openmw_aux``. In theory mods can override them, but it is not recommended.
 
-+---------------------------------------------------------+--------------------+---------------------------------------------------------------+
+.. include:: tables/aux_packages.rst
-| Built-in library                                        | Can be used        | Description                                                   |
-+=========================================================+====================+===============================================================+
-|:ref:`openmw_aux.calendar <Package openmw_aux.calendar>` | everywhere         | | Game time calendar                                          |
-+---------------------------------------------------------+--------------------+---------------------------------------------------------------+
-|:ref:`openmw_aux.util <Package openmw_aux.util>`         | everywhere         | | Miscellaneous utils                                         |
-+---------------------------------------------------------+--------------------+---------------------------------------------------------------+
-|:ref:`openmw_aux.time <Package openmw_aux.time>`         | everywhere         | | Timers and game time utils                                  |
-+---------------------------------------------------------+--------------------+---------------------------------------------------------------+
 
 They can be loaded with ``require`` the same as API packages. For example:
 

docs/source/reference/lua-scripting/tables/aux_packages.rst

@@ -0,0 +1,11 @@
++---------------------------------------------------------+--------------------+---------------------------------------------------------------+
+| Built-in library                                        | Can be used        | Description                                                   |
++=========================================================+====================+===============================================================+
+|:ref:`openmw_aux.calendar <Package openmw_aux.calendar>` | everywhere         | | Game time calendar                                          |
++---------------------------------------------------------+--------------------+---------------------------------------------------------------+
+|:ref:`openmw_aux.util <Package openmw_aux.util>`         | everywhere         | | Miscellaneous utils                                         |
++---------------------------------------------------------+--------------------+---------------------------------------------------------------+
+|:ref:`openmw_aux.time <Package openmw_aux.time>`         | everywhere         | | Timers and game time utils                                  |
++---------------------------------------------------------+--------------------+---------------------------------------------------------------+
+|:ref:`openmw_aux.ui <Package openmw_aux.ui>`             | by player scripts  | | User interface utils                                        |
++---------------------------------------------------------+--------------------+---------------------------------------------------------------+

docs/source/reference/lua-scripting/tables/packages.rst

@@ -0,0 +1,33 @@
++------------------------------------------------------------+--------------------+---------------------------------------------------------------+
+| Package                                                    | Can be used        | Description                                                   |
++============================================================+====================+===============================================================+
+|:ref:`openmw.interfaces <Script interfaces>`                | everywhere         | | Public interfaces of other scripts.                         |
++------------------------------------------------------------+--------------------+---------------------------------------------------------------+
+|:ref:`openmw.util <Package openmw.util>`                    | everywhere         | | Defines utility functions and classes like 3D vectors,      |
+|                                                            |                    | | that don't depend on the game world.                        |
++------------------------------------------------------------+--------------------+---------------------------------------------------------------+
+|:ref:`openmw.storage <Package openmw.storage>`              | everywhere         | | Storage API. In particular can be used to store data        |
+|                                                            |                    | | between game sessions.                                      |
++------------------------------------------------------------+--------------------+---------------------------------------------------------------+
+|:ref:`openmw.core <Package openmw.core>`                    | everywhere         | | Functions that are common for both global and local scripts |
++------------------------------------------------------------+--------------------+---------------------------------------------------------------+
+|:ref:`openmw.types <Package openmw.types>`                  | everywhere         | | Functions for specific types of game objects.               |
++------------------------------------------------------------+--------------------+---------------------------------------------------------------+
+|:ref:`openmw.async <Package openmw.async>`                  | everywhere         | | Timers (implemented) and coroutine utils (not implemented)  |
++------------------------------------------------------------+--------------------+---------------------------------------------------------------+
+|:ref:`openmw.world <Package openmw.world>`                  | by global scripts  | | Read-write access to the game world.                        |
++------------------------------------------------------------+--------------------+---------------------------------------------------------------+
+|:ref:`openmw.self <Package openmw.self>`                    | by local scripts   | | Full access to the object the script is attached to.        |
++------------------------------------------------------------+--------------------+---------------------------------------------------------------+
+|:ref:`openmw.nearby <Package openmw.nearby>`                | by local scripts   | | Read-only access to the nearest area of the game world.     |
++------------------------------------------------------------+--------------------+---------------------------------------------------------------+
+|:ref:`openmw.input <Package openmw.input>`                  | by player scripts  | | User input.                                                 |
++------------------------------------------------------------+--------------------+---------------------------------------------------------------+
+|:ref:`openmw.ui <Package openmw.ui>`                        | by player scripts  | | Controls :ref:`user interface <User interface reference>`.  |
++------------------------------------------------------------+--------------------+---------------------------------------------------------------+
+|:ref:`openmw.camera <Package openmw.camera>`                | by player scripts  | | Controls camera.                                            |
++------------------------------------------------------------+--------------------+---------------------------------------------------------------+
+|:ref:`openmw.postprocessing <Package openmw.postprocessing>`| by player scripts  | | Controls post-process shaders.                              |
++------------------------------------------------------------+--------------------+---------------------------------------------------------------+
+|:ref:`openmw.debug <Package openmw.debug>`                  | by player scripts  | | Collection of debug utils.                                  |
++------------------------------------------------------------+--------------------+---------------------------------------------------------------+

docs/source/reference/modding/settings/navigator.rst

@@ -204,11 +204,22 @@ enable nav mesh render
 :Range:		True/False
 :Default:	False
 
-Render nav mesh.
+Render navigation mesh.
 Allows to do in-game debug.
 Every nav mesh is visible and every update is noticable.
 Potentially decreases performance.
 
+nav mesh render mode
+--------------------
+
+:Type:		string
+:Range:		"area type", "update frequency"
+:Default:	"area type"
+
+Render navigation mesh in specific mode.
+"area type" - show area types using different colours.
+"update frequency" - show tiles update frequency as a heatmap.
+
 enable agents paths render
 --------------------------
 

files/builtin_scripts/scripts/omw/console/player.lua

@@ -78,6 +78,7 @@ local env = {
     ui = require('openmw.ui'),
     camera = require('openmw.camera'),
     aux_util = require('openmw_aux.util'),
+    debug = require('openmw.debug'),
     view = require('openmw_aux.util').deepToString,
     print = printToConsole,
     exit = exitLuaMode,

files/lua_api/CMakeLists.txt

@@ -14,9 +14,9 @@ set(LUA_API_FILES
     openmw/world.lua
     openmw/types.lua
     openmw/postprocessing.lua
+    openmw/debug.lua
 )
 
 foreach (f ${LUA_API_FILES})
     copy_resource_file("${CMAKE_CURRENT_SOURCE_DIR}/${f}" "${OpenMW_BINARY_DIR}" "resources/lua_api/${f}")
 endforeach (f)
-

files/lua_api/openmw/debug.lua

@@ -0,0 +1,44 @@
+---
+-- `openmw.debug` is an interface to the engine debug utils.
+-- Can be used only by local scripts, that are attached to a player.
+-- @module debug
+-- @usage local debug = require('openmw.debug')
+
+
+---
+-- Rendering modes
+-- @type RENDER_MODE
+-- @field [parent=#RENDER_MODE] #number CollisionDebug
+-- @field [parent=#RENDER_MODE] #number Wireframe
+-- @field [parent=#RENDER_MODE] #number Pathgrid
+-- @field [parent=#RENDER_MODE] #number Water
+-- @field [parent=#RENDER_MODE] #number Scene
+-- @field [parent=#RENDER_MODE] #number NavMesh
+-- @field [parent=#RENDER_MODE] #number ActorsPaths
+-- @field [parent=#RENDER_MODE] #number RecastMesh
+
+---
+-- Rendering mode values
+-- @field [parent=#debug] #RENDER_MODE RENDER_MODE
+
+---
+-- Toggles rendering mode
+-- @function [parent=#debug] toggleRenderMode
+-- @param #RENDER_MODE value
+
+---
+-- Navigation mesh rendering modes
+-- @type NAV_MESH_RENDER_MODE
+-- @field [parent=#NAV_MESH_RENDER_MODE] #number AreaType
+-- @field [parent=#NAV_MESH_RENDER_MODE] #number UpdateFrequency
+
+---
+-- Navigation mesh rendering mode values
+-- @field [parent=#debug] #NAV_MESH_RENDER_MODE NAV_MESH_RENDER_MODE
+
+---
+-- Sets navigation mesh rendering mode
+-- @function [parent=#debug] setNavMeshRenderMode
+-- @param #NAV_MESH_RENDER_MODE value
+
+return nil

files/settings-default.cfg

@@ -941,6 +941,9 @@ nav mesh path prefix =
 # Render nav mesh (true, false)
 enable nav mesh render = false
 
+# Navigation mesh rendering mode (default, update frequency)
+nav mesh render mode = area type
+
 # Render agents paths (true, false)
 enable agents paths render = false