Mercuna Any Surface Navigation builds upon Mercuna Ground Navigation by enabling agents to traverse arbitrarily oriented surfaces, including walls and ceilings. This guide highlights the differences between surface navigation and ground navigation. For a complete understanding, it should be read alongside the Mercuna Ground Navigation User Guide.
Surface navigation allows agents to navigate across all surfaces, including floors and walls. A key difference between Ground and Surface navigation is that Ground navigation assumes agents are always oriented vertically, with their up direction along the z-axis. In contrast, Surface navigation orientates agents perpendicular to the surface they are on.
Mercuna Any Surface Navigation is installed together with Mercuna Ground Navigation as part of a single plugin that includes all Mercuna Navigation functionality. See the Mercuna Ground Navigation User Guide for installation and initial set up instructions for the plugin.
Similar to Ground Navigation, Mercuna Any Surface Navigation provides pathfinding and following based on pre-configured agent types. Since the constraints on an agent differ when navigating arbitrary surfaces, a separate set of surface agent type settings is provided.
In the UE5 editor, under Edit | Project Settings… | Plugins | Mercuna you will find Surface Agent Types. These specify the settings for the different kinds of agents that will navigate using Mercuna Any Surface navigation.
You must set up at least one Surface Agent Type in order to use Any Surface Navigation, and there is no restriction on the maximum number of agent types you can have configured. The settings of these agent types must be set up on a per-project basis.
The Max Angle Change setting allows you to control when navigation is possible between surfaces at different angles. For example, if your character is able to navigate over a smoothly curving ramp between the floor and a wall, but is unable to make the transition without the ramp, then use a 45 or 30 degree max angle change. Alternatively, if your character is able to transition directly from the floor to the wall over a sharp transition, use a 90 degree max angle change. Max Angle Change above 90 degrees is not supported.
The other settings have the same meaning as in Ground Navigation.
Note that steps are not currently handled correctly by the Any Surface Navigation grid generation so the configured Step Height is not properly respected. This will be fixed in a later version.
A Mercuna Nav Surface Grid is used to find paths for agents. A Nav Surface Grid is generated in the level everywhere that is within the Mercuna Nav Grid Volumes that belong to the Grid.
The settings controlling generation and runtime options for the Nav Grid work in the same way as the Mercuna Nav Ground Grid – see the Mercuna Ground User Guide for details.
Mercuna Nav Grid Volume actors are used to identify what parts of the level should be navigable using the Nav Surface Grid.
Optionally, Mercuna Nav Seed actors can be placed to define areas of the navigable space that are important. When nav seeds are used, isolated islands of navigable space are removed, saving memory.
A particular box volume can be completely excluded from navigable space by adding a Mercuna Nav Exclusion Volume actor to the level.
See the Mercuna Ground User Guide for more information on how to configure the navigable space.
Unless runtime generation is being used, the Nav Grid must be built after it is first configured and any time the level geometry is changed. This can be done by selecting Build Grid from the Mercuna menu (accessed by clicking the Mercuna button in the Toolbar). An on screen notification displays the progress of the nav grid construction.
See the Mercuna Ground User Guide for more information.
World Partition and Level Streaming are supported by the Mercuna Surface Navigation in the same way as for Mercuna Ground Navigation. See the Mercuna Ground User Guide for more information.
Runtime spawning, building and rebuilding of the Mercuna Nav Surface Grid is supported by the Mercuna Surface Navigation in the same way as for Mercuna Ground Navigation.
Nav Invokers are not currently supported for Surface Navigation.
See the Mercuna Ground User Guide for more information.
Mercuna Surface Navigation creates 6 connected sets of quadtrees oriented along the major axes to represent the navigable surfaces in the game world. Similar to ground navigation, a polymesh is constructed summarising the information in the quadtrees, and this is used to accelerate certain queries through the navigation graph.
Pathfinding is performed using an A* search. Currently this search is performed through the quadtrees, but in future releases the polymesh will be used to accelerate the search. This will also allow longer searches to be performed.
The A* search is followed by aggressive path straightening by raycasting through the quadtrees to remove artefacts that are often created by A* pathfinds. Finally, a smooth path made of parabolic sections is fitted to the straight line path, allowing agents to move naturally through the game world.
Mercuna can also support partial paths. A partial path is returned when a complete path can’t be found to the specified destination, for example if it is disconnected from the start point. Instead Mercuna returns a path to the closest point to the destination that is reachable. Partial path functionality is optional on pathfinding and movement requests, and by default partial paths are not used.
Finding paths through the Mercuna Surface Nav Grid can be done implicitly by making your pawn movement controlled by Mercuna. This method allows you to take advantage of the Mercuna steering system. Alternatively, you can query for paths directly using methods on the Mercuna Nav Surface Grid actor, or explore the pathfinding results using Mercuna Nav Grid Testing actors.
For pathfinds that originate from actors, the actor’s orientation is used to select the correct surface when clamping the start point. For instance, a character with a default orientation standing on a floor near a wall will start its path from the floor, even if its position (i.e. its centre) is closer to the wall.
For pathfinds that go to an actor, the option bUseEndActorOrientation, controls whether to consider the end actor’s orientation when determining the closest surface. This is often useful, but in some cases, for example if the end actor is a TargetPoint placed on a wall without an explicitly set orientation, it is better to disable this option so that the closest surface is used.
See the Mercuna Ground User Guide for more information about Nav Grid Testing actors.
In order to allow pawns to use Mercuna to navigate they need to have the following components:
The navigation component offers both a C++ and Blueprint interface for making movement requests to the pawn.
Mercuna will try to automatically find a Mercuna Nav Grid that is compatible with the Agent Type set on the Surface navigation component, and automatically fill in steering parameters based on the setup of the pawn. Alternatively, these can be explicitly overridden here.
These parameters work analogously to the settings on the Character Movement Component and should be kept in sync with the movement component’s configuration, so that Mercuna’s control of the agent is consistent with what the agent is actually able to do.
Any actor can be made a dynamic obstacle by adding a Mercuna Obstacle component. See the Mercuna Ground User Guide for more information.
The default Unreal Engine Character Movement Component has many assumptions about the up direction of characters being in the vertical z direction and is therefore unsuitable for traverse of non horizontal surfaces.
To use a movement component that derives from the Character Movement Component but that has been generalised for any surface navigation, you only need to set the CharacterMovementComponent property on the surface navigation component.
The free Ninja Character Plugin offers a movement component that can be used with the default Unreal character and supports movement at any orientation. It is available from the UE marketplace https://unrealengine.com/marketplace/en-US/product/ninja-character-plugin.
There is no need to use a movement component that derives from the Unreal Character Movement Component. You can use your own movement component, or no movement component, by deriving a component from the Mercuna Surface Navigation Component and overriding the following four functions:
Nav Grid Modifier Volumes provide a mechanism for designers to influence and limit navigation within specific regions. See the Mercuna Ground User Guide for more information.
Manually placed Nav Links are used with Mercuna Surface Navigation in the same way as for Mercuna Ground Navigation. When using Nav Links with Surface Navigation make sure to correctly orient the Nav Link endpoints so that the link attaches to the correct surface. See the Mercuna Ground User Guide for more information on setting up nav links.
While Mercuna can handle sharp angle changes up to 90 degrees, transitioning between surfaces with large angle differences (e.g. from floor to ceiling) can be challenging to make look good using only the agent’s standard locomotion animations. In such cases, it may be preferable to configure a smaller maximum angle change in the agent type settings and instead set up nav links to connect the surfaces. At runtime, when a request is made that moves an agent to or through a different surface, it will then use the nav link, allowing the game code to play a specific transition animation.
There is no automatic generation of nav links for Surface Grids.
Mercuna generates smooth polynomial curves between path points in a similar manner to Ground Navigation. The Mercuna Surface Navigation Component will steer an actor with a suitable movement component along these curves.
Whereas the pathfind is performed when an agent is given a destination, the smooth curve is generated on demand. If the agent is pushed, or has to avoid other actors causing it to move away from the curve, then the curve and, if necessary, the underlying path are automatically regenerated.
Mercuna offers dynamic obstacle avoidance to ensure that pawns don’t collide while moving. Any actor with a Mercuna Obstacle Component is automatically considered as an obstacle that needs to be steered around for the purpose of avoidance.
Surface navigation supports ORCA avoidance, allowing agents to make local changes to their movement based upon nearby obstacles. For the purpose of avoidance, the shape of obstacles will be projected into a local plane based upon the current orientation of the avoiding agent.
The Avoidance Mode on the Surface Navigation Component allows ORCA to be enabled or disabled for the agent. The Context Steering avoidance mode is not supported by the Surface Navigation.
For further details on the ORCA configuration parameters, see the Mercuna Ground User Guide.
Surface Navigation provides the same Blueprint functionality as Ground Navigation. Be sure to use the Surface Navigation version of Blueprint functions.
See the Mercuna Ground User Guide for details on the available nodes.
Mercuna Surface Navigation offers Navigable, Reachable, Raycast and Path Length EQS tests. These work analogously to the Ground Navigation versions – see the Mercuna Ground User Guide for details.
The Project test works slightly differently in Surface Navigation because the projection direction must be specified. The test will move the point up or down along the specified projection direction. The “up” direction is along the specified projection direction, whereas “down” is in the opposite direction. The projection direction can either be specified explicitly, or by providing a context from which to use its up direction.
Mercuna Surface Navigation also offers the EQS generators:
Spawning, removing, or transforming Modifier Volumes does not automatically update the Surface Grid. Rebuild Volume must be called on the Nav Surface Grid actor to update the modified parts of the level.
Changes to enable/disable a modifier volume, or update costs or usage flags, are reflected immediately without a rebuild.
The maximum pathfinding distance is significantly shorter than for Ground Navigation. In this version, with the default cell size setting of 20cm and a reasonably well connected environment, searches should work to distances of at least 50m.
Mercuna Surface Navigation works well on surfaces with smooth transitions between different orientations. Steps that are within the configured step height, and staircases of many steps currently do not generate navigation correctly.
Nav Raycasts between surfaces that have orientation differences of more than 90 degrees apart may incorrectly fail.
Character acceleration limits aren’t fully respected, meaning that characters may not be able to correctly follow paths around corners at the requested speeds.
The following features of the Mercuna Ground Navigation are not supported for Surface Navigation: