Skip to content

Latest commit

 

History

History
327 lines (194 loc) · 11.4 KB

API.md

File metadata and controls

327 lines (194 loc) · 11.4 KB

General

var recast = new Recast(optionnal_path_to_worker) // Creates a new instance

Parameters types

  • coordinates and extends are specified in floats, in the geometry datum
  • other values are integers
  • flags and areas types are specified in bitmasks combinations of
  • recast.FLAG_WALK
  • recast.FLAG_SWIM
  • recast.FLAG_DOOR
  • recast.FLAG_JUMP
  • recast.FLAG_DISABLED
  • recast.FLAG_ALL

You can mix multiple flags with bitwise operations:

flags = recast.FLAG_WALK | recast.FLAG_JUMP

# recast.settings(options)

Apply new navigation mesh settings. It is required to build() the navmesh to have them applied.
Have a look to Mikko's post about settings for details.
Supported options and their default value are:

cellSize        :  0.3   // voxelization cell size
cellHeight      :  0.2   // voxelization cell height
agentHeight     :  2.0   // agent capsule  height
agentRadius     :  0.4   // agent capsule  radius
agentMaxClimb   :  0.9   // how high steps agents can climb, in voxels
agentMaxSlope   : 30.0   // maximum slope angle, in degrees
regionMinSize   :  8.0   // minimum isolated region size that is still kept
regionMergeSize : 20.0   // how large regions can be still merged
edgeMaxLen      : 12.0   // maximum edge length, in voxels
edgeMaxError    :  1.3   // how loosely the simplification is done

# recast.OBJLoader(path or url, callback)

Load an .obj file by its path. It uses fs.readFile() in Node and an XmlHttpRequest in the browser. You must do further operations on recast in the callback.

# recast.OBJDataLoader(OBJ contents as string)

Load an OBJ directly with its content. Useful in some cases when you want to manage geometries on your own. You must do further operations on recast in the callback.

# recast.buildSolo()

Build a single-object navigation mesh. It's generally slower to generate than a tiled navmesh and faster to update, but disable some features like temporary obstacles (unlikely to change limitation).

# recast.buildTiled()

Build a tiled navigation mesh. It's generally faster to generate than a solo navmesh and slower to update, but disable some features like off-mesh connections (current limitation, likely to be enabled in the future).

# recast.saveTileMesh(path, callback)

Returns a navmesh blob buffer. You can save this blob in a file to load it later.

# recast.loadTileMesh(path, callback)

Load a navmesh blob. It is significantly faster than compute the navmesh from scratch.

# recast.saveTileCache(path, callback)

Returns a navmesh tilecache blob buffer. You can save this blob in a file to load it later.

# recast.loadTileCache(path, callback)

Load a navmesh tilecache blob. It is significantly faster than compute the navmesh from scratch.

Basic navmesh operations

# recast.getRandomPoint(callback)

Get a random navigable position. callback is called with 3 arguments x, y, z.

# recast.findNearestPoint(near_x, near_y, near_z, extend_x, extend_y, extend_z, callback)

Find the nearest navigable point. callback is called with 3 arguments x, y, z.

# recast.findNearestPoly(near_x, near_y, near_z, extend_x, extend_y, extend_z, callback)

Find the nearest navigable polygon. callback is called with 1 argument polygon.

callback(polygon) {
    polygon.ref      // the polygon_id,
    polygon.vertices // array of vertices
}

# recast.queryPolygons(near_x, near_y, near_z, extend_x, extend_y, extend_z, max, callback)

Find all or up to max nearest polygons from near point. callback is called with 1 argument: an array of polygons.

callback(polygons) {
    polygon[0].ref      // the polygon_id,
    polygon[0].vertices // array of vertices
}

# recast.setPolyFlags(near_x, near_y, near_z, extend_x, extend_y, extend_z, flags)

Set flags on nearest polygons from near point.

# recast.setPolyFlagsByRef(polygon_id, flags)

Set flags on a single polygon.

# recast.findPath(from_x, from_y, from_z, to_x, to_y, to_z, max, callback)

Find all - or up to max - waypoints points between two points. callback is called with 1 argument: an array of waypoints.

callback(waypoints) {
    waypoints[0] == { x:value, y:value, z:value }
    ...
}

Basic agents operations

# recast.addAgent(options)

Add an agent on the navmesh and returns its agent_id. Supported options are:

position: { x:0, y:0, z:0 }, // initial position
radius: 0.8,                 // agent radius
height: 0.5,                 // agent height
maxAcceleration: 1.0,        // maximum acceleration factor
maxSpeed: 2.0,               // maximum speed
updateFlags: 0,              // update flags
separationWeight: 20.0       // separation factor

# recast.updateCrowdAgentParameters(agent_id, options)

Update an agent settings.

# recast.removeCrowdAgent(agent_id)

Remove an agent from the crowd

Crowd

# recast.initCrowd(max, radius)

Initialize the crowd system with a maximum of max agents and a radius reference of radius.

# recast.crowdRequestMoveTarget(agent_id, dest_x, dest_y, dest_z)

Set agent_id's destination to dest point.

# recast.crowdUpdate(time_delta)

Tick the crowd system, and update all its agents positions. It internally emits an update event with the result of crowdGetActiveAgents.

# recast.crowdGetActiveAgents(callback)

Retrieve all crowd agents. callback is called with 1 argument: an array containing all agents with their position, speed, velocity and neighbors count.

callback(agents) {
    agents[0].position      // current position
    agents[0].velocity      // current velocity
    agents[0].neighbors     // number of current neighbors
    agents[0].desiredSpeed  // desired speed
    ...
}

# recast.requestMoveVelocity(agent_id, x, y, z)

Set an agent's velocity. You can use this method to set an agent movements from gamepad values.

Temporary obstacles

# recast.addTempObstacle(x, y, z, radius)

Add a temporary obstacle at desired position with a specified radius.

# recast.removeTempObstacle(obstacle_id)

Remove obstacle_id temporary obstacle.

# recast.getAllTempObstacles(callback)

Retrieve all temporary obstacles. callback is called with 1 argument: an array of all current temporary obstacles with their position and radius.

# recast.clearAllTempObstacles()

Remove all temporary obstacles.

Off-mesh connections

# recast.addOffMeshConnection(from_x, from_y, from_z, to_x, to_y, to_z, radius, both_directions)

Add an off-mesh connection. If both_directions is true, connection will available in both directions. It is required to build() the navmesh to have them applied.

Events

recast.vent is an event emitter on which you should listen for update events, to retrieve and apply all agents positions.

recast.vent.on('update', function (all_agents) {

    for (var i = 0; i < all_agents.length; i++) {

        var agent     = all_agents[i];
        var character = scene.characters[agent.idx];

        // apply new position
        character.position.copy(agent.position);

        // apply rotation from velocity
        var angle = Math.atan2(- agent.velocity.y, agent.velocity.x);
        character.rotation.y = angle;
    }
})

Zones

A Recast.js zone is a collection of some navigation mesh polygons. It can be used to quickly toggle flags on some polygons. Please note that these polygons do not necessarily match the original geometry vertices.

To easily define zones from your navigation mesh, it is recommended to use the recast.js editor

# new recast.Zone(name, data)

Create a new zone named name described by the data object. This object is required to have a refs attribute - an array of polygon references - and flags a flags bitmask.

# new recast.Zone(name, data)

# zone.isWalkable()

Returns true if this zone is walkable.

# zone.is(flag)

Returns true if this flag is applied on this zone.

# zone.setFlags(flags)

Set the specified flags on this zone.

# zone.clearFlags(flags)

Remove the specified flags from this zone.

# zone.toggleFlags(flags)

Toggle the specified flags on this zone.