Revision as of 04:24, 5 November 2014

The path object is special in a few ways; most notably, paths may be placed on the Dynamic Lighting layer to create shadows while dynamic lighting is enabled. It's also the only means to create maps without loading images.

Path Object

Most of these properties are either self-explanatory or easy to grasp. It is the _path property, however, which is complicated and requires some further study.

Path Property

The _path property is a JSON string, and is a read-only property of the Path object. In order to make use of the _path property, you must use JSON.parse(myPath.get("path")).

Once parsed, you'll see that the _path is an array of arrays. Depending on the type of path, the arrays will be different. There are three possible types of paths:

• Polygon: this includes open polygons, closed polygons, line segments, rectangles, and squares. Squares and rectangles are formed with the "Draw Shape" tool without holding the Alt key. All other polygons are formed with the "Polygon/Line" tool.
• Oval: this includes both ovals and circles. Both are formed with the "Draw Shape" tool while holding the Alt key.
• Freehand: formed with the "Freehand" tool.

Polygonal Paths

Square and rectangle paths are quite easy to read, as they only contain five arrays. Similarly, line segments and polygons with a few sides are not much trouble. All polygonal paths follow the same format: some number of arrays, containing three elements each. The first element of each array is a letter, and the second and third elements form a point.

Oval Paths

Oval paths are a little bit more complicated. However, every oval path is the same size: five arrays, the first of which contains three elements, and the other four contain seven elements each. The first element of each is a letter, and the remaining six elements each form three points.

Array Example	Description
["M", 0, 35]	The midpoint of the left edge of the oval.
["C", 0, 17.5, 17.5, 0, 35, 0]	Three points along the oval's bounding box near the top-left corner. The first two points are Bézier control points, and the third is an endpoint for the Bézier curve.
["C", 52.5, 0, 70, 17.5, 70, 35]	Three points along the oval's bounding box near the top-right corner. The first two points are Bézier control points, and the third is an endpoint for the Bézier curve.
["C", 70, 52.5, 52.5, 70, 35, 70]	Three points along the oval's bounding box near the bottom-right corner. The first two points are Bézier control points, and the third is an endpoint for the Bézier curve.
["C", 17.5, 70, 0, 52.5, 0, 35]	Three points along the oval's bounding box near the bottom-left corner. The first two points are Bézier control points, and the third is an endpoint for the Bézier curve. The third point is equal to the M point.

In all of the demonstration images above for the C arrays, the blue arrow is pointing at the midpoint of the relevant edge of the rectangle. The red and green arrows are pointing at approximately the 1/4 or 3/4 mark of the relevant edges, as appropriate. The red and green arrows are not pointing at the circle itself.

Freehand Paths

Freehand paths take up the most space, as freehand drawings are -- essentially -- a long poly-line with very short line segments. Like polygons, freehand paths have a variable number of arrays. The first and last array in the path each have three elements: a letter and a point. The arrays between the first and the last have five elements: a letter and two points.

Because of how the freehand paths are drawn, the Bézier curves that compose it will generally be very short; the control points will generally be very close to the start point of the curve (the end point of the previous curve).

Analyzing Path Values

All points in the _path property are relative to the top-left corner of the path's bounding rectangle. So, a point of 0,0 is at the top of the path and the left of the path, but that does not necessarily mean the path is at the top-left of the map -- that's taken care of by the top and left properties.

If you rotate or resize a path after drawing it, the points do not change. Those changes are accounted for with the rotation, scaleX, and scaleY properties.

Paths are not necessarily all clockwise or all counterclockwise; you cannot guarantee that any algorithm that cares about winding order will function as desired, not to mention the possibility of complex polygons. Squares and rectangles are clockwise, but there is nothing to distinguish a rectangle from some other arbitrary polygon.