Infohazard.HyperNav 1.1.5
3D Navigation for Flying Characters
No Matches
HyperNav Documentation

Table of Contents

  • HyperNav Documentation
    • Table of Contents
    • Introduction
    • Documentation and Support
    • License
    • Installation
      • Prerequisites
      • Asset Store
      • Package Manager (Git URL or Submodule)
    • Setup
      • General Setup
      • SRP Setup
    • Demos
      • HyperNavDemo (Pathfinding)
      • HyperNavAvoidanceDemo (Pathfinding Avoidance)
      • HyperNavAvoidanceScaleDemo (Many-Agent Standalone Avoidance)
      • HyperNavFloatingOriginDemo (Floating Origin System)
    • Features Guide
      • Volume Setup
      • Pathfinder Setup
      • Agent Setup
      • Spline Agent Setup
      • Avoidance
      • Moving Volumes and Floating Origin


HyperNav is a navmesh-like system for implementing volume-based navigation and 3D obstacle avoidance. Unlike a navmesh, which is bound to walkable surfaces, HyperNav creates volumes in which characters can navigate on all three axes. I developed it for Astral Horizon, an FPS with 6-DOF gameplay, and it is best suited to similar games (where characters with the ability to fly need to navigate enclosed spaces).

Documentation and Support

API Docs

Tutorial Playlist



HyperNav uses the standard Unity Asset Store per-seat license for tools.



HyperNav depends on the Infohazard.Core library, which you can get from the Asset Store or as a Package Manager package from Github. Regardless of how you install it, you should do so before importing HyperNav. You can see more information about the core library here

HyperNav also has three additional package manager dependencies: burst, collections, and editorcoroutines. However, these will automatically be installed when you import it, so no need to do anything here.

Asset Store

The main way to install HyperNav is through the asset store. Just install it as you would any other asset, and make sure you allow Unity to update package manager dependencies.

Package Manager (Git URL or Submodule)

Because HyperNav is a paid asset, the Github repository is not open source. However, if you wish to contribute to HyperNav and have purchased a seat, please feel free to email me and I can look into getting you read access to the repository.


General Setup

The only setup required beyond installation is to add references to the Infohazard.HyperNav assembly if you are using an assembly definition. If you are using the default assemblies (such as Assembly-CSharp), nothing is needed here.

SRP Setup

If you are using a scriptable render pipeline (URP, HDRP, etc) and wish to run the demos, you will need to upgrade the materials using your render pipeline's material upgrade system. The materials you'll need to upgrade are in Assets/Plugins/Infohazard/Demos/Infohazard.HyperNav/Materials and Assets/Plugins/Infohazard/Demos/Shared Demo Assets/Materials.


The following demo scenes are provided to cover the various features of HyperNav.

HyperNavDemo (Pathfinding)

This scene, located at Assets/Plugins/Infohazard/Demos/Infohazard.HyperNav/Scenes/HyperNavDemo.unity, demonstrates how to set up NavVolumes and a NavPathfinder, and use NavAgent and SplineNavAgent to find paths. Run the demo and click anywhere on the right side of the screen to set a destination, and use the WASD keys to rotate the camera on the left side of the screen.

HyperNavAvoidanceDemo (Pathfinding Avoidance)

This scene, located at Assets/Plugins/Infohazard/Demos/Infohazard.HyperNav/Scenes/HyperNavAvoidanceDemo.unity, demonstrates how you can use avoidance along with NavAgents to avoid agents getting stuck in a narrow maze. Try turning off avoidance by setting the agents' avoidance weights to zero to see the difference it makes.

HyperNavAvoidanceScaleDemo (Many-Agent Standalone Avoidance)

This scene, located at Assets/Plugins/Infohazard/Demos/Infohazard.HyperNav/Scenes/HyperNavAvoidanceScaleDemo.unity, deomonstrates how you can use avoidance without a NavAgent. It also shows that the avoidance system performs well even with a huge number of agents all avoiding one another.

HyperNavFloatingOriginDemo (Floating Origin System)

This scene, located at Assets/Plugins/Infohazard/Demos/Infohazard.HyperNav/Scenes/HyperNavFloatingOriginDemo.unity, deomonstrates how you can use HyperNav with a floating origin system. This is useful in very large scenes where you need to shift all objects such that the player remains close to the origin.

Features Guide

Volume Setup

The first step to setup navigation in your scene is to create a NavVolume, using the menu item Tools > Infohazard > Create > Nav Volume.

NavVolume Parameters Configuration

There are a lot of parameters in NavVolume, which you can read about in full in the API Docs. The most important properties that you will probably want to configure here are:

  • Bounds: The boundaries of the volume, which you can edit visually.
  • BlockingLayers: The layers that are considered impassible to agents.
  • MaxAgentRadius: Paths in this volume must be able to accommodate an agent of this radius.
  • VoxelSize: Size of voxel samples when baking, which is a tradeoff between accuracy and performance (both baking and at runtime).


Once your parameters are configured, you can bake the NavVolume! Just hit the "Bake" button and wait for it to finish (it should be fairly quick). If the baking is taking a long time, consider breaking your volume up into multiple smaller volumes. By default, when baking is done, you should see the baked results rendered as a blue mesh in the scene view when the volume is selected.

External Links

If you are using multiple volumes, you most likely will want agents to be able to find paths between them. This is accomplished using external links. Simply use the "Generate External Links" button after all volumes are baked, or, for convenience, "Generate All External Links" to generate links on all loaded NavVolumes. Once the external links are generated, you should see them as green lines in the scene view when a volume is selected.

Note that if you re-bake a volume, you will need to regenerate not only its external links but the external links of all of its neighbors. If you don't do this, you will get links leading to the wrong region, and potentially paths that cross through impassible areas. The "Generate All External Links" button comes in handy here.

Pathfinder Setup

Before you can start pathfinding, you also need to create a NavPathfinder, using the menu item Tools > Infohazard > Create > Nav Pathfinder. You can create a NavPathfinder in each scene that needs one, or you can create one that persists through level loading.

NavPathfinder Parameters Configuration

Like with volumes, there are a lot of parameters in NavPathfinder, which you can read about in full in the API Docs. The most important properties that you will probably want to configure here are:

  • PathfindingMode: Where paths are calculated. To enjoy the performance boost of the C# Job System and Burst, I recommend leaving this as Worker Thread (Job).
  • MaxConcurrentJobs: How many pathfinding jobs can be running at once. This should be kept fairly low. Additional jobs will be kept in a queue.
  • MaxCompletionFrames: How many frames pathfinding jobs are allowed to take to complete. I recommend starting this at three, as that is the max allowed when using high-performance TempJob memory. If your paths are consistently taking longer than three frames (this will print warning messages in the console), increase it as needed.

Agent Setup

The final step to start pathfinding is to set up agents. A NavAgent is the easiest way to start finding paths from code. Simply add the NavAgent to your GameObject, set its Destination, and read its DesiredVelocity.

NavAgent Parameters Configuration

You can find full parameter documentation in the API Docs. The main paremeters you'll want to configure for NavAgent are:

  • Acceptance: How close the agent must get to a waypoint before it is considered arrived. If acceptance is too low, the agent may not be able to feasibly reach its destination (depending on your movement system).
  • AccelerationEstimate: How fast the agent is able to accelerate. This value is used so that it knows when to slow down. You can set this dynamically if your character's acceleration changes.
  • SampleRadius: Radius outside the agent to search for a NavVolume. If no NavVolume is found within this radius, pathfinding cannot occur.

Agent Usage

With your agent set up, you'll need to reference it in code. Your movement code should set NavAgent.Destination to start finding a path, and use NavAgent.DesiredVelocity to determine the direction and speed to move in. You can check NavAgent.Arrived to see if the agent has reached its destination or not.

Spline Agent Setup

If you wish to use the spline path system to achieve smoother navigation paths, simply replace the NavAgent with a SplineNavAgent. SplineNavAgent provides the same properties as NavAgent (as it is a subclass) with some additional properties.

SplineNavAgent Paremeters Configuration

SplineNavAgent's parameters are documented in the API Docs. In addition to the parameters offered by NavAgent, SplineNavAgent contains the following parameters that you may want to set:

  • TangentScale: This value controls the curviness of the path. The default value of 0.5 usually works well.
  • MaxAlignmentVelocityDistance: The further the agent drifts from the spline, the more it attempts to move back towards the spline. This is the distance at which the entire DesiredVelocity is devoted to returning to the spline.
  • CurvatureOfMaxSlowdown: The agent's DesiredVelocity will slow down on parts of the spline with higher curvature. This is the curvature value at which the slowdown will be the greatest. By turning on DebugPath, you can see the curvature values scaled from green (no curvature) to red (this curvature value) to determine the right value for you.
  • MaxCurvatureSlowdown: The multiplier on desired velocity to use when the spline curvature is at CurvatureOfMaxSlowdown. At lower curvature values, the velocity multiplier scales from 1 to this value.

SplineNavAgent Usage

Usage of SplineNavAgent is exactly the same as NavAgent - set the Destination and use the DesiredVelocity.


Whereas NavAgent and SplineNavAgent are used to plan paths between two points, avoidance is used to steer clear of obstacles that might obstruct that path. These obstacles might be moving objects or even other navigating agents, so they can't be baked into the NavVolume. Instead, you should use the obstacle avoidance system.

AvoidanceManager Setup

In order to use avoidance, there must be an AvoidanceManager present in your scene. To create an AvoidanceManager, use the menu item Tools > Infohazard > Create > Avoidance Manager.

AvoidanceManager Parameters Configuration

AvoidanceManager's parameters are documented in the API Docs. You may want to configure these parameters to achieve optimal performance and accuracy:

  • TimeHorizon: How many seconds into the future to look for obstacles to avoid.
  • MaxObstaclesConsidered: The most obstacles within range an agent can consider each frame.

AvoidanceAgent Setup

If you want an object to avoid obstacles, you should add an AvoidanceAgent script. This script needs to know the maximum speed the agent can travel at, the agent's size, and several other properties.

AvoidanceAgent Usage

To use an AvoidanceAgent from your code, you must supply an input velocity (the velocity the agent wants to move in) and read its AvoidanceVelocity (the velocity it should move in to avoid obstacles). The input velocity is provided via a delegate, allowing you to connected it to whatever source you want.

AvoidanceAgent With NavAgent

When you want to use avoidance with a NavAgent or SplineNavAgent, the usage is simpler. The NavAgent should have a button to create an AvoidanceAgent on the object and instantly connect it to the NavAgent. The NavAgent will handle the input and output velocity for the AvoidanceAgent, so you can simply read the NavAgent's DesiredVelocity which now includes avoidance.

AvoidanceAgent Parameters Configuration

AvoidanceAgent's parameters are documented in the API Docs. You may want to configure these parameters:

  • Radius: How big the agent is.
  • MaxSpeed: How fast the agent can move. You may also want to set this dynamically. If you are using a NavAgent, this value can be accessed through the NavAgent's AvoidanceMaxSpeed property.
  • AvoidanceWeight: How much effort this agent makes to avoid other agents, relative to their own AvoidanceWeight. If all agents make equal effor to avoid each other, just leave this at 1.
  • AvoidancePadding: Extra room to leave between this agent and any obstacle it is avoiding.
  • AvoidedTags: Tags of obstacles to avoid. By default this is set to all obstacles.

AvoidanceObstacle Setup

While AvoidanceAgents will automatically avoid each other, you may wish to add additional obstacles that are not agents. This can be done using AvoidanceObstacleBase or any of its subclasses (which determine the current velocity using different methods). Just add one of these scripts to an object and the obstacle is good to go:

  • AvoidanceObstacleBase: Does not calculate a velocity, so it is assumed to be stationary. You can inherit from it to add your own velocity calculations.
  • SimpleAvoidanceObstacle: Calculates its velocity by measuring delta position / delta time every frame.
  • RigidbodyAvoidanceObstacle: Uses the current velocity of an attached Rigidbody component.

AvoidanceObstacle Parameters Configuration

AvoidanceObstacleBase's parameters are documented in the API Docs. Because agents are already obstacles, they share some parameters. The main parameters you'll want to configure are:

  • Radius: How big the agent is.
  • MaxSpeed: How fast the agent can move. You may also want to set this dynamically.

Moving Volumes and Floating Origin

You may need to occasionally move NavVolumes, either individually or all together. When this occurs, the native data for the volumes needs to be updated. For moving individual volumes, you can enable AutoDetectMovement on the volumes and the data updating will be handled automatically. For moving all volumes at once such as in a floating origin system, it will be more performant to use NavVolume.UpdateAllTransforms() after they are moved.

Moving Volume Limitations

In both cases, any pathfinding operations currently underway will automatically be restarted. Any agents that already have paths, however, will need to be manually stopped by calling Stop() and the destination re-supplied in shifted space.

Moving volumes does update the external link positions, so two volumes with links to one another that move together will have the links updated correctly. However, if one volume moves relative to another volume that it shares links with, the link positions will stay relative to the originating volume. Links cannot currently be re-baked at runtime.

While individual moving volumes are supported, note that when a volume is moved, any calculating paths will be canceled. So if a volume is moving every frame, the paths will be continuously canceled before they can complete. You can get past this by putting the NavPathfinder in Main Thread End Of Frame mode, but that will likely lead to stutters.