PolyNav

   Get PolyNav on the Unity Asset Store!   

PolyNav is a lightweight polygonal-based 2D pathfinding solution using A* that is extremely easy to set up and use, made specifically for your Unity 2D games!

  • Define the walkable and obstacle area polygons with ease!
  • Generate or update the navigation areas in runtime for procedural levels!
  • Includes a complete steering agent component!
  • Use an easy API to control your agents!
  • Support for multiple maps, agent avoidance, and edge offsetting.

PolyNav can be great for Adventure, Isometric, Side-Scrollers, and Top-Down 2D Games!

Documentation

There are three main components in PolyNav that you should be aware of:

  • PolyNav2D is the main component responsible for navigation map generation. You can create one through “Tools/ParadoxNotion/PolyNav/Create PolyNav Map”. There can be multiple in the scene if required.
  • PolyNavObstacle is a component responsible for marking a gameobject that has a Collider2D as an obstacle (or hole) for a PolyNav2D navigation map.
  • PolyNavAgent is the component that you should attach to any game object that you would like to navigate around the world. This is not mandatory as you can create your own if you want to.

Step 1: PolyNav Maps

The first thing to do is to create your first PolyNav2D map through the Unity top menu “Tools/ParadoxNotion/Create PolyNav Map”. A PolygonCollider2D will automatically be attached as well on that newly created gameobject. By using the default Unity controls for adjusting such a collider, you can define any shape for the navigation polygon that you want. This shape will be the outer boundaries of your map (within which obstacles can exist).

The options on the PolyNav2D component itself are rather few.

  • Obstacles Mask defines which layers this map will look for PolyNavObstacles to take into account when the map is generated. As such you can fine grain which NavObstacles are meant for which PolyNav2D maps, but you can of course also use the same NavObstacles on any number of different maps.
  • Auto Regenerate Interval is the interval in frames which the map will check for NavObstacles changes (enable, disable or transform change) and if any occurs, the map will automatically be regenerated. You can set this option to 0 to basically disable this feature since it can be very costly on performance and rather manually regenerate the map using “PolyNav2D.GenerateMap();” whenever it is really required through code.
  • Radius Offset is the offset from the edges of the map that τηε agents will keep a distance from. Typically, you set this radius to be equal to the radius of the agents that will use this map.
  • Invert Master Polygon is used if you accidentally shaped your polygon in the wrong winding (see the end of documentation).

Step 2: PolyNav Obstacles

To create an obstacle within the master navigation map polygon, you can do so through “Tools/ParadoxNotion/PolyNav/Create PolyNav Obstacle”. Since NavObstacles also come with a PolygonCollider2D, you can edit them the same way as you would the master map polygon. You don’t have to be exact. You can have half an obstacle inside the walkable area, or multiple obstacles overlapping each other if required. The PolyNavObstacle component can of course also be added manually on a gameobject that you want to make an obstacle. This gameobject can pre-exist in the scene or be part of a runtime instantiated prefab if required.

There are a few options in the PolyNavObstalce component:

  • Shape Type is the shape of the obstacle. It can either be Polygon, Box, or Composite. Depending on the shape a different __Collider2D will be attached. The default is Polygon.
  • Extra Offset is an extra offset for this specific polygon that you want the agents to keep a distance from.
  • Invert Polygon is used if you accidentally shaped your polygon in the wrong winding (see the end of documentation).

Step 3: PolyNav Agents

To make a gameobject pathfind in a PolyNav map, select the gameobject you want and attach the PolyNavAgent component to it.

  • Map is the PolyNav2D map that this agent is bound to move within. If left at None, then the first map found in the scene will be used. It is also quite possible to alter this property in runtime to make the agent change the map it is bound to.
  • Max Speed is the maximum speed that the agent can move.
  • Max Force is the maximum force that can be applied to the agent to move. This is like affecting the mass of the agent.
  • Stopping Distance is the distance from the goal that the agent will have considered reached.
  • Slowing Distance is the distance from the goal that the agent will begin slowing down.
  • Look Ahead Distance is the distance that the agent looks ahead for obstacles or other agents (if other agents have an Avoidance Radius). You can set this value to 0 to disable obstacle and agent look ahead features.
  • Avoid Radius is the agent avoidance radius with other agents. Leave it at 0 if you don’t need avoidance.
  • Avoidance Consider Stucked Time is the maximum time allowed for the agent to keep trying to avoid another agent without success. After this time has elapsed, the agent will consider the goal unreachable and stop pathfinding.
  • Avoidance Consider Reached Distance is the maximum distance to the goal that the agent will consider as successfully reached if it stops pathfinding due to being stuck trying to avoid another agent (relevant to the above parameter).
  • Rotate Transform if checked will also rotate the agent to face towards the path it is following.
  • Rotate Speed is the speed that the agent will rotate if Rotate Transform is checked.
  • Center Offset is a virtual offset from the transform.position that the pathfinding will work with. This can be useful if you want to basically re-pivot the agent center without changing the sprite real center.
  • Repath. If enabled the agent will recalculate its pathfinding towards the desired goal whenever a path point is reached or the map is changed. Disable this for performance.
  • Restrict. If enabled will force the agent position within valid areas only. Disable this for performance.
  • Closer Point On Invalid. If enabled will make the agent go to the closest possible position if the requested goal is invalid.
  • Debug Path. If enabled will draw the current agent path gizmo.

There are various demo scripts provided to move the agent about for a quick start like for example ClickToMove and PatrolWaypointsRandom. ClickToMove will simply move the agent at the clicked position, while PatrolWaypointsRandom will move the agent
between some preset waypoints at a random selection. Simply attach either on the agent gameobject if you want a quick start!
There are also some other helpful scripts included under the “DEMO/Scripts” folder, worth checking out!

Step 4: Scripting Basics

Regarding scripting, there are 2 important methods in the PolyNavAgent:

bool SetDestination(Vector2 goal, Action<bool> callback = null)
Sets a new goal for the agent. You can optionally provide a callback method that will be called on either arrival with a True argument, or if the destination is or becomes invalid with a False argument. The method itself returns whether or not the destination is valid in the first place.

Stop()
Will simply stop the agent from moving.

There are also some important properties that you can use:

  • bool pathPending is any path pending right now for the agent?
  • bool hasPath does the agent has any active path?
  • Vector2 nextPoint the next point in the path that the agent is moving towards.
  • float remainingDistance the remaining distance along the path for the goal.
  • Vector2 movingDirection the direction the agent is currently moving at.

Of course, there are a lot more methods and properties in the PolyNavAgent worth checking out!

The PolyNavAgent also has a few events that you can subscribe to and use:

  • OnDestinationReached.
  • OnDestinationInvalid.
  • OnNavigationStarted.
  • OnNavigationPointReached (this is when a path corner point is reached).

Please check the demo scripts ClickToMove and PatrolWaypointsRandom for example use!

Extra

Notice that you can also request a path directly without using the PolyNavAgent component at all, but rather directly from a PolyNav2D map instance and for any purpose. You can do this like so:

PolyNav2D.FindPath( Vector2 start, Vector2 end, Action<Vector2[]> callback)
The callback will provide the resulting path, or null if a path is impossible or not found.

Polygon Winding

The following image shows a map with a single obstacle within. You will notice that both the master polygon and the obstacle polygon have two different colored lines on their edges, one being Green and another being Grey. When modifying your polygons you need to make sure that the Green line is on the outside while the Grey line on the inside of the navigation area (like shown in the image). If a polygon is not shown as such, you can use the Inveryt Polygon option (found in both the PolyNav2D and PolyNavObstacle inspectors) to fix the winding of the polygon as to be like in the image bellow.

Remember that you can enable “Gizmos” in play mode on the top right of the “Game” tab, so that you are able to view the polygon map, obstacles, and agent paths for debugging.

If you have any questions, please contact us or join us on Discord!