Orestis 3D Pathfinding

What is it?

Navigation mesh generation inside the PlayCanvas editor in seconds and a 3D pathfinding runtime to animate any entity on a path.

Easily created navigation zones, find paths and animate your entities on them.

../_images/playground.jpg

Features

  • Navigation mesh generation inside the PlayCanvas Editor using Recast, all settings are exposed to tweak.
  • The source .obj of each navigation mesh (navMesh) is added to your project. You can easily download and further edit it.
  • Parse any number of selected entities or even the whole scene.
  • Easily manage your pathfinding zones, simple API to switch active zone on runtime.
  • Pathfinding runtime API to find paths and animate entities on them.
  • THREE-Pathfinding is used as the pathfinding solver.

Where to find?

After you enable the extension in the PIC browser extension, reload your PlayCanvas editor and head to Settings -> Orestis 3D Pathfinding.

How it works?

Orestis 3D Pathfinding provides two main services to your project:

  • NavMesh generation of part or all of your scene.
  • Pathfinder solver to easily find paths and animate entities on them.

The usual workflow in using this extension would be the following.

  1. Select part or all of your scene by referencing the parent entity to the Entities field of the extension.
  2. Set appropriate settings that fit your scene and moving entities.
  3. Generate the required navigation meshes (1 or more).
  4. Attach the runtime script (orestis-path-runtime.js) to an entity.
  5. Use one of the exposed API methods to access the pathfinding logic in your scripts.
../_images/script-order.jpg

Note

The first time you generate a nav mesh the required scripts and libraries for pathfinding will be added automatically to your project.

The order of the two libraries added is important for them to function properly, the three-polyfill.js script should come before the three-pathfinding.js script.

How to use the scripts

There are two PlayCanvas scripts (pc.ScriptType) that are added to your project:

  1. orestis-path-zone.js
  2. orestis-path-runtime.js

Script: Orestis Path Zone

This script will automatically be added to each entity that is added to your hierarchy when generating a navMesh.

It is responsible for parsing the navMesh mesh and feeding its geometry to the pathfinding solver. Normally you don’t have to do anything in addition unless your project requires it.

../_images/orestis-path-zone.png

Note

The navMesh is parsed automatically in the initialize() method. Which means when the entity is enabled for the first time in your app’s life cycle.

If you want to load it later you can easily remove the createPathfindingZone() method from the initialise() code block and call it from your code.

Script: Orestis Path Runtime

This script is responsible for getting all the pieces together and acting as the point of communication with the pathfinding solver. Basically all of your requests should be targeting the events and methods exposed in this script.

This script is meant to be attached to a single entity in your scene (singleton).

You can call the methods in this scripts in two ways:

  • Using pc.Events
  • Directly referencing the script instance and method on the entity that the script is attached to.

The following code samples are using the first way which is easier to work as a beginner.

How to find a path?

You need to provide two points, starting and ending, as valid pc.Vec3 objects. A callback method is fired with the found path.

If no path is found the method will return false.

this.app.fire('Orestis:findPath', fromPoint, toPoint, function(path){

    // iterate through the points of the path, if a path was found
    if( path ){
        path.forEach( function(point){

            // each point is a pc.Vec3 object
            console.log(point.x, point.y, point.z);
        });
    }
});

How to set the active zone?

To set the active pathfinding zone you just call a method and pass the name of that zone. The zones are named automatically after the entity name that is holding the nav mesh.

this.app.fire('Orestis:setActiveZone', 'level2_navMesh');

How to get a point on a path?

PlayCanvas provides a helper class called pc.Curve that exposes useful methods to interpolate between values. Orestis provides a nice method which takes a path that you calculated and returns an array of three pc.Curve objects (one for each axis (x,y,z) and the total path length.

You then use that to find any given point on the path just by passing the distance from start.

this.app.fire('Orestis:createCurvesFromPath', path, function(curves){

    // get interpolated point on path
    var distanceFromStart = 7.5;
    var percent = distanceFromStart / curves.pathLength;

    // position entity on path
    myEntity.setPosition(curves.px.value(percent), curves.py.value(percent), curves.pz.value(percent));
});

How to animate an entity on a path?

Usually this is a fairly game specific need but Orestis provides a simple method that given an end point does the following: * Finds a valid path from the current position of the entity. * Gets a sets of curves to be able to find points on the path * Starts animating the entity on the path.

The animation speed is a global property on the script, called animationSpeed.

this.app.fire('Orestis:animateEntityTo', this.entity, endPoint);

There three additional methods provided to help you control the animation:

// pauses the active animation
this.app.fire('Orestis:pauseAnimation');

// resumes the active animation
this.app.fire('Orestis:resumeAnimation');

// stops the active animation and resets all values
this.app.fire('Orestis:stopAnimation');

Note that requesting a new animation for an entity will stop any animation currently playing.