Home

What is this all about

In a game context, Recast.js is meant to be used with a file describing a scene geometry. Using the recastnavigation library, it will deduce a navigation mesh - a set of polygons on which your characters can move.

Once this navigation mesh is computed, it is possible to use built-in pathfinding operations like "find the shortest path between point A and point B", taking into account various user-defined variables like obstacles, slopes, and off-mesh connections.

If you decide to use it to animate your scene characters, it also provides a complete crowd system capable of managing all your characters movements using per-characters settings (speed, radius, ...)

Getting started

Assuming you've got an .obj file describing your scene geometry, you can get a Recast instance with:

// browser
var recast = window.recast;

// nodejs
// var recast = require('path/to/require');

recast.OBJLoader('path/to/geometry.obj', function() {
  // build the navmesh (buildSolor or buildTiled)
  recast.buildSolo();
    
  // get a random navigable point A
  recast.getRandomPoint(recast.cb(function(x, y, z) {

    // find the shortest route from origin to point A
    // we asume 0,0,0 is a navigable point
    recast.findPath(0, 0, 0, x, y, z, 1000, recast.cb(function(path) {
      console.log('The shortest route contains', path.length, 'corners');
      console.log('These corners are', path);
    }));
  }));
});

API

get a recast instance in a nodejs environment

var recast = require('recast');

get a recast instance in a browser (include /lib/recast.js)

var recast = window.recast;

create a recast worker instance in a nodejs environment

var recast = require('recast.withworker');
recast = new recast('recast');

create a recast worker instance in a browser (include /lib/recast.withworker.js)

var recast = new Recast('../lib/recast.js', callback);

General

• recast.settings - Apply new navigation mesh settings
• recast.OBJLoader - Load an .obj file
• recast.OBJDataLoader - Load an OBJ content
• recast.buildSolo - Build a single-object navigation mesh
• recast.buildTiled - Build a tiled navigation mesh

Basic navmesh operations

• recast.getRandomPoint - Get a random navigable position
• recast.findNearestPoint - Find the nearest navigable point
• recast.findNearestPoly - Find the nearest navigable polygon
• recast.queryPolygons - Find nearest polygons
• recast.setPolyFlags - Set flags on nearest polygons
• recast.setPolyFlagsByRef - Set flags on a single polygon
• recast.findPath - Find a path between two points

Basic agents operations

• recast.addAgent - Add an agent
• recast.updateCrowdAgentParameters - Add an agent settings
• recast.removeCrowdAgent - Remove an agent

Crowd

• recast.initCrowd - Initialize the crowd system
• recast.crowdRequestMoveTarget - Set an agent's destination
• recast.crowdUpdate - Update the crowd system
• recast.crowdGetActiveAgents - Retrieve all crowd agents
• recast.requestMoveVelocity - Set an agent's velocity

Temporary obstacles

• recast.addTempObstacle - Add a temporary obstacle
• recast.removeTempObstacle - Remove a temporary obstacle
• recast.getAllTempObstacles - Retrieve all temporary obstacles
• recast.clearAllTempObstacles - Remove all temporary obstacles

Off-mesh connections

• recast.addOffMeshConnection - Add an off-mesh connection

Zones

• recast.Zone - Create a new zone
• zone.isWalkable - Test if a zone is walkable
• zone.is - Test a specific flag
• zone.setFlags - Set specified flags
• zone.clearFlags - Clear specified flags
• zone.toggleFlags - Toggle specified flags

Troubleshooting

Some tips to help you getting rid of well-known traps

• test your geometry in Recast - it is easily runnable on Windows, MacOS and Linux
• adjust setting wisely. Again, test them in Recast if you are not sure.