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

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

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.

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

1. 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.
2. 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.
3. 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.

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 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.

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().

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.