API | Lines & Paths

These commands control the creation and use of lines, pathmaps and pathfinding.

- PS.line ( x1, y1, x2, y2 )
- PS.pathMap ( image )
- PS.pathFind ( pathmap, x1, y1, x2, y2, options )
- PS.pathData ( pathmap, left, top, width, height, data )
- PS.pathDelete ( pathmap )

PS.line ( x1, y1, x2, y2 )

PS.line() calculates a straight line between any two points.

Parameters:

**x1**:*integer***y1**:*integer***x2**:*integer***y2**:*integer*

Returns: *array* or **PS.ERROR**

The **x1** and **y1** parameters indicate the starting coordinates of the line,
and **x2** and **y2** indicate the ending coordinates.
All four *integers* are required. Non-integral values are floored.

If **x1, y1** and **x2, y2** specify the same coordinate, the array returned by PS.line() will
be empty (length = 0).

**Usage notes**

1. PS.line() operates in an arbitrary coordinate space of almost limitless extent. It has no idea how a line it has calculated will be used in your game. It's your responsibility to interpret the data returned by PS.line() in the context of your application, and to deal with boundary conditions that might cause errors if violated.

Return value

PS.line() returns an array of sub-arrays, each with the following structure:

- array[0] :
*integer*(x coordinate) - array[1] :
*integer*(y coordinate)

Each sub-array represents a single point in a straight line from **x1, y1** to **x2, y2**,
beginning with the first step away from **x1, y1**.
Points are presented in sequence, starting with element zero (0) of the returned array.
The final point is always **x2, y2**.

**PS.ERROR** is returned if an error occurs.

PS.pathMap ( image )

PS.pathMap() creates a pathmap from a specialized image *object*.

Parameters:

**image**:*object*

Returns: *string* or **PS.ERROR**

The required **image** parameter must be a reference to a valid image
*object* with the following characteristics:

**The image must be in format 1.**This means that its**image.data**array must contain exactly (**image.width * image.height**)*integers*in the range 0 to 0xFFFFFF inclusive, and its**image.pixelSize**property must be set to 1.- Each
*integer*in the**image.data**array indicates whether or not the corresponding map location is "walkable." Any non-zero value indicates that the coordinate should be considered by PS.pathFind() as a possible candidate for a path point. A value of zero (0) means that PS.pathFind() should*never*consider that coordinate for a path point. - A convenient
**image.data**value for a "walkable" coordinate is one (1). However, any*integer*greater than zero is acceptable. The values are interpreted as the relative "cost" of moving into that coordinate. You can use this feature to simulate different types of terrain. For example, flat terrain could be represented by the value 1, and steep terrain by the value 2. This would cause PS.pathFind() to prefer flat terrain when calculating paths, using steep terrain only if there is no other way to complete the path.

Return value

PS.pathMap() returns a string that uniquely identifies the newly created pathmap.

A new identifier is generated by each call to PS.pathMap(). If you call it with same
**image** more than once for some reason,
each instance will be assigned a different identifier.

**PS.ERROR** is returned if an error occurs.

PS.pathFind ( pathmap, x1, y1, x2, y2, options )

PS.pathFind() calculates a path between two points on a pathmap.

Parameters:

**pathmap**:*string***x1**:*integer***y1**:*integer***x2**:*integer***y2**:*integer*- (optional)
**options**:*object*

Returns: *array* or **PS.ERROR**

The required **pathmap** parameter must be string uniquely identifying a pathmap, of the type returned by
PS.pathMap().

The **x1** and **y1** parameters indicate the starting coordinates of the path, and **x2** and
**y2** indicate the ending coordinates.
All four *integers* are required. Non-integral values are floored.

The **x1** and **x2** coordinates should be between 0 and (**pathmap.width**-1) inclusive.

The **y1** and **y2** coordinates should be between 0 and (**pathmap.height**-1) inclusive.

The pathmap locations at **x1, y1** and **x2, y2** must be "walkable;" that is,
the corresponding data in the image passed to
PS.pathMap() to create the pathmap must be non-zero.

If either location is not walkable, an empty path is returned.

The optional **options** parameter should be an *object* with any of the following properties:

**.no_diagonals**:*boolean*or**PS.DEFAULT**(default:*false*)**.cut_corners**:*boolean*or**PS.DEFAULT**(default:*false*)

If the **.no_diagonals** property of **options** is *true* or any non-zero number,
PS.pathFind() will not use diagonal steps when calculating paths.
If **.no_diagonals** is false, zero (0), **PS.DEFAULT** or not supplied, diagonal steps are enabled.

If the **.cut_corners** property of **options** is *true* or any non-zero number,
PS.pathFind() will use diagonal steps to cut across square corners.
If **.cut_corners** is false, zero (0),
**PS.DEFAULT** or not supplied, the pathfinder will step around square corners.
Note that this option is only relevant if diagonal steps are enabled (the default behavior).

If **options** is **PS.DEFAULT** or not supplied, all default PS.pathFind() settings are used.

Usage notes

1. PS.pathFind() uses a modified A* pathfinding algorithm. The data you supply in the image used to create the pathmap can be used to influence the behavior of the algorithm. See PS.pathMap() for details.

2. If your pathmap uses only one value (such as 1) to indicate walkable locations, setting
**options.direct** to *true* will improve the speed of the pathfinder.

Return value

PS.pathFind() returns an array of sub-arrays, each with the following structure:

- array[0] :
*integer*(x coordinate) - array[1] :
*integer*(y coordinate)

Each sub-array represents a single point in a path from **x1, y1** to **x2, y2**,
beginning with the first step away from **x1, y1**.
Points are presented in sequence, starting with element zero (0) of the returned array.
The final point is always **x2, y2**.

All coordinates are zero-based, relative to the top-left corner of the associated pathmap.

If **x1, y1** and **x2, y2** specify the same coordinate, or if the coordinate at either
**x1, y1** or **x2, y2** is defined as non-walkable (data = 0),
the array returned by PS.pathFind() will be empty (length = 0).

**PS.ERROR** is returned if an error occurs.

PS.pathData( pathmap, left, top, width, height, data )

PS.pathData() inspects and replaces the data in a region of a pathmap.

Parameters:

**pathmap**:*string***left**:*integer***top**:*integer***width**:*integer*or**PS.DEFAULT****height**:*integer*or**PS.DEFAULT**- (optional)
**data**:*integer*,**PS.CURRENT**or**PS.DEFAULT**

Returns: *array* or **PS.ERROR**

The required **pathmap** parameter must be string uniquely identifying a pathmap, of the type returned by
PS.pathMap().

The required **left**, **top**, **width** and
**height** parameters specify a zero-based rectangular region,
relative to the top-left corner of the pathmap. Non-integral values are floored.

The **left** and **top** *integers* indicate the top-left coordinates of the region.
The **left** coordinate should be between 0 and (**pathmap.width** - 1) inclusive.
The **top** coordinate should be between 0 and (**pathmap.height** - 1) inclusive.
Values outside these limits will cause an error.

The **width** and **height** *integers* indicate the dimensions of the region.
The **width** parameter should be between 1 and (**pathmap.width** - **left**) inclusive.
The **height** parameter should be between 1 and (**pathmap.height** - **top**)
inclusive.
Values outside these limits are clamped.

If **width** or **height** are PS.DEFAULT, the value one (1) is used.

The optional
**data** parameter indicates the data that will replace the current values in the pathmap. It can be any
positive
*integer*. Non-integral values are floored.

If **data** is
**PS.DEFAULT**, the data in the pathmap at the specified coordinates is restored to the values in place
when the pathmap was originally created by
PS.pathMap().

If **data** is **PS.CURRENT** or not supplied, the data in the pathmap is not changed.

Return value

PS.pathData() returns an array of
*integers* indicating the current data in the specified region of the pathmap.
The array contains (**width** * **height**) elements in ascending row order,
beginning with the top-left corner of the region.

PS.ERROR is returned if an error occurs.

PS.pathDelete( pathmap )

PS.pathDelete() deletes a pathmap created by a previous call to PS.pathMap().

Parameters:

**pathmap**:*string*

Returns: **PS.DONE** or **PS.ERROR**

The required **pathmap** parameter must be string uniquely identifying a pathmap, of the type returned by
PS.pathMap().

The specified pathmap is deleted from the engine, and its pathmap identifier becomes invalid. Subsequent use of the identifier with any pathmap command will cause an error.

Usage notes

1. The pathmaps created by PS.pathMap() require a lot of memory. When you're done using a pathmap, call PS.pathDelete() to free resources.

Return value

PS.pathDelete() returns **PS.DONE** if the call succeeds, else **PS.ERROR**.