Reese's DOTS Pathing

This project is archived—no longer maintained. So long, and thanks for all the fish!

Introduction

This was forked from the navigation package, and stripped of everything except what's required for setting destinations and pathing. Thus, there is no physics-related code (which includes surface management and obstacle avoidance), lerping, terrain support, etc. You must supply world positions and anticipate world positions as output—there is no support for local positioning, unlike the aforementioned navigation package.

Furthermore, because physics is ripped out entirely from this package, you may have to do more to validate correctness of the positions you supply. Remember, unlike the navigation package, this one does not raycast underneath agents to check for a potential surface.

And unlike the navigation package, which includes NavMeshComponents by default, you must install it yourself for this package to work properly.

Import

This requires Unity editor 2019.3 or greater. Copy one of the below Git URLs:

• HTTPS: https://github.com/reeseschultz/ReeseUnityDemos.git#path
• SSH: git@github.com:reeseschultz/ReeseUnityDemos.git#path

Then go to Window ⇒ Package Manager in the editor. Press the + symbol in the top-left corner, and then click on Add package from git URL. Paste the text you copied and finally click Add.

Usage at a Glance

For a working example of how to use this package, see these demo scripts, which include flocking!

In this package, there's only one concept you need to be familiar with: the agent (technically the PathAgent component), which is an actor or character who is in need of path planning.

There is also an associated authoring component you may want to use: PathAgentAuthoring.

The flow of usage works like this: you supply a PathDestination component to a PathAgent. This package will automatically supply a PathPlanning component to said agent when ready. After that, the PathPlanning and PathDestination components will be removed when a path is found, or if there's a problem (if there's a problem, the PathProblem component will be added to the agent for you to inspect). Assuming planning is successful, the agent's path buffer (which you can access by way of the PathBufferElement) will be populated for you to consume. That is the buffer you may use for interpolation.

Usage with GameObjects

To retain path-planning agents as GameObjects, rather than converting them into entities, add the PathAgentHybrid to them instead of PathAgentAuthoring. FYI, this component works by creating an invisible entity with the PathAgent component in the background. Even though the pathing package does not feature interpolation, the PathAgentHybrid updates its GameObject translation and rotation to match that of the associated entity, for your convenience.

API

---

PathAgentHybrid (exclusively for GameObjects)

Public Methods

Initialization Variables

Variable	Type	Description	Default Value
TypeID	string	The agent's type.	Humanoid
Offset	Vector3	The agent's offset.	(0, 0, 0)

Status Variables

Variable	Type	Description	Default Value
IsPlanning	bool	true if the agent is planning, false if not.	false
HasProblem	PathQueryStatus?	Has a value of PathQueryStatus if the agent has a problem, null if not. Problems tend to arise to due incorrect values set in NavConstants, which is discussed later.	null

Destination Variables

Variable	Type	Description	Default Value
WorldDestination	Vector3	The agent's world destination.	(0, 0, 0)
FollowTarget	GameObject	Set if this agent should follow another GameObject with a PathAgentHybrid component.	null
FollowMaxDistance	float	Maximum distance before this agent will stop following the target Entity. If less than or equal to zero, this agent will follow the target Entity no matter how far it is away.	0
FollowMinDistance	float	Minimum distance this agent maintains between itself and the target Entity it follows.	0

---

PathAgent (exclusively for entities)

Initialization Variables

Variable	Type	Description	Recommended Value
TypeID	int	This is the type of agent in terms of the NavMesh system.	PathUtil.GetAgentType("Humanoid")
Offset	float3	The agent's offset.	(0, 0, 0)

Status Components & Variables

Here are the internally-managed components (defined in PathAgentStatus) that are applied to PathAgents throughout the navigation lifecycle. Do not write to these, just query them to check existence:

IComponentData	Description
PathPlanning	Exists if the agent is planning.

Other components you may add and write to:

IComponentData	Description
PathDestination	Exists if the agent needs a destination. In this struct, there's a self-explanatory float3 named WorldPoint.
PathFollow	Exists if the agent should follow an entity. Remember, the pathing package does not interpolate, so you're still responsible for interpolating a "follower," but this will generate destinations for said follower. One important property is the Entity Target, which is self-explanatory. There's also the float MaxDistance, which is the maximum distance before this agent will stop following the target entity. If MaxDistance is less than or equal to zero, this agent will follow the target entity no matter how far it is away. Finally, the float MinDistance is that which the agent maintains between itself and the target entity it follows.

Runtime Settings

The pathing package has many settings you may override (at runtime), hence why the NavSettingsOverrides class is included for your convenience in the demo code (keep in mind that while these overrides are for the navigation package, you can do something similar for pathing). This class makes it easy to retain your changes even when you update the package via UPM.

Now, what settings are there to override, anyway?

Setting	Type	Description	Default Value
DestinationRateLimitSeconds	float	Duration in seconds before a new destination will take effect after another. Prevents planning from being clogged with destinations which can then block interpolation of agents.	0.8f
PathSearchMax	int	Upper limit on the search area size during path planning.	1000
IterationMax	int	Upper limit on the iterations performed in a NavMeshQuery to find a path in the NavPlanSystem.	1000

Compile-Time Constants

In addition to settings, there are also compile-time constants. You can change them directly in PathConstants, although that usually shouldn't be necessary. Plus, the constants will reset when you update via UPM.

Constant	Type	Description	Default Value
PATH_NODE_MAX	int	Upper limit on the possible path nodes available for the buffer.	1000
HUMANOID	string	The 'Humanoid' NavMesh agent type as a string.	"Humanoid"

Credits

This package uses PathUtils (licensed with zlib) by Mikko Mononen, and modified by Unity Technologies. Did you know that Mikko is credited in Death Stranding for Recast & Detour?

Contributing

All contributions to this repository are licensed under MIT.