@pixelburp/phaser3-navmesh-generation

phaser-navmesh-generation

Warning: this plugin is still heavy Work in Progress (WIP). It's possibly not stable enough for use in a production product - use at your own risk (for now!)

This Phaser plugin generates Navigation Meshes from supplied Phaser.TilemapLayer data and collison indices thereof. Contains configuration options

Current version: 0.2.2

Getting Started:

ES6 / Node

import it as you would any other project:

import NavMeshPlugin from 'phaser-navmesh-generation';

Legacy

If you're doing it the old fashioned way, simply add <script> tag after your main Phaser tag:

<script src="my/path/to/phaser.js"></script>
<script src="my/path/to/navmesh-plugin.js"></script>

Then in your game's JS code:

  preload() {
    var plugin = this.game.plugins.add(NavMeshPlugin);
  }

Usage:

1. First, we need to generate a new navigation mesh using the following method (options are below)

var navMesh = plugin.buildFromTileLayer({
  collisionIndices: [1, 2, 3],
  midPointThreshold: 0,
  useMidPoint: false,
  scene: Phaser.Scene,
  tileMap: <Phaser.Tilemaps.Tilemap>,
  tileLayer: <Phaser.Tilemaps.DynamicTilemapLayer|Phaser.Tilemaps.StaticTilemapLayer>,
  debug: {
    hulls: false,
    navMesh: false,
    navMeshNodes: false,
    polygonBounds: false,
    aStarPath: false
  }
});

2. Then, to find a path between two Phaser.Point instances, call:

navMesh.getPath(position, destination, offset);

navMeshPlugin.buildFromTileLayer()

Kind: instance method of NavMeshPlugin

Param	Type	Default	Description
options.tileMap	Phaser.Tilemaps.Tilemap
options.tileLayer	Phaser.Tilemaps.TilemapLayer
options.scene	Phaser.Scene
options.collisionIndices	Array.<Number>		an Array of collision indices that your tilemap uses for collisions
[options.midPointThreshold]	Number	0	a Number value telling how narrow a navmesh triangle needs to be before it's ignored during pathing
[options.timingInfo]	Boolean	false	Show in the console how long it took to build the NavMesh - and search for paths
[options.useMidPoint]	Boolean	true	a Boolean value on whether to include all triangle edge mid-points in calculating triangulation
[options.offsetHullsBy]	Number	0.1	a Number value to offset (expand) each hull cluster by. Useful to use a small value to prevent excessively parallel edges
options.debug	Object		various optional debug options to Render the stages of NavMesh calculation:
options.debug.hulls:	Boolean		Every (recursive) 'chunk' of impassable tiles found on the tilemap
options.debug.navMesh:	Boolean		Draw all the actual triangles generated for this navmesh
options.debug.navMeshNodes:	Boolean		Draw all connections found between neighbouring triangles
options.debug.polygonBounds:	Boolean		Draw the bonding radius between each navmesh triangle
options.debug.aStarPath:	Boolean		Draw the aStar path found between points (WIP debug, will remove later)

navMeshPlugin.getClosestPolygon(position, [includeOutOfBounds])

Finds the closest NavMesh polygon, based on world point

Kind: instance method of NavMeshPlugin

Param	Type	Default	Description
position	Phaser.Geom.Point | Phaser.Math.Vector2		The world point
[includeOutOfBounds]	Boolean	false	whether to include "out of bounds" searches

navMeshPlugin.getPath(position, position, offset)

Finds Calculate the shortest path to a given destination

Kind: instance method of NavMeshPlugin

Param	Type	Description
position	Phaser.Geom.Point | Phaser.Math.Vector2	startPosition
position	Phaser.Geom.Point | Phaser.Math.Vector2	endPosition
offset	Number	An offset value to keep a distance (optional, default 0)

navMeshPlugin.getAllTilesWithin(worldX, worldY, spriteWidth, spriteHeight) ⇒

Given world coords & "sprite" size, find all overlapping Tiles in the tileLayer

Kind: instance method of NavMeshPlugin
Returns: Array

Param	Type	Description
worldX	Number	World X coordinate
worldY	Number	World Y coordinate
spriteWidth	Number	width (in pixels) of the Sprite you wish to add
spriteHeight	Number	height (in pixels) of the Sprite you wish to add

navMeshPlugin.addSprite(worldX, worldY, spriteWidth, spriteHeight)

Adds a "sprite" (like an immovable prop), that navmesh should include in its calculations.

Kind: instance method of NavMeshPlugin

Param	Type	Description
worldX	Number	World X coordinate
worldY	Number	World Y coordinate
spriteWidth	Number	width (in pixels) of the Sprite you wish to add
spriteHeight	Number	height (in pixels) of the Sprite you wish to add

navMeshPlugin.removeSprite(worldX, worldY, spriteWidth, spriteHeight)

Find any previously cached "sprites" within these bounds, and reset to the original value

Kind: instance method of NavMeshPlugin

Param	Type	Description
worldX	Number	World X coordinate
worldY	Number	World Y coordinate
spriteWidth	Number	width (in pixels) of the Sprite you wish to remove
spriteHeight	Number	height (in pixels) of the Sprite you wish to remove