Character Vault
Any Concept / Any System
Compendium
Your System Come To Life
Roll20 for Android
Streamlined for your Tablet
Roll20 for iPad
Streamlined for your Tablet

Personal tools

API:Objects/Path

From Roll20 Wiki

Jump to: navigation, search

Roll20 API

Getting Started


Reference


Cookbook (Examples)


Community Scripts

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.

Contents

Path Object

Property Default Value Notes
_id A unique ID for this object. Globally unique across all objects in this campaign. Read-only.
_type "path" Can be used to identify the object type or search for the object. Read-only.
_pageid ID of the page the object is in. Read-only.
_path A JSON string describing the lines in the path. Read-only. See Path Property below for more information.
fill "transparent" Fill color. Use the string "transparent" or a hex color as a string, for example "#000000"
stroke "#000000" Stroke (border) color.
rotation 0 Rotation (in degrees).
layer "" Current layer, one of "gmlayer", "objects", "map", or "walls". The walls layer is used for dynamic lighting, and paths on the walls layer will block light.
stroke_width 5 Width of the path's line in pixels.
width 0 Horizontal dimension of the path.
height 0 Vertical dimension of the path.
top 0 Y-coordinate for the center of the path
left 0 X-coordinate for the center of the path
scaleX 1 Horizontal scale factor for the path.
scaleY 1 Vertical scale factor for the path.
controlledby "" Comma-delimited list of player IDs who can control the path. Controlling players may delete the path. If the path was created by a player, that player is automatically included in the list.

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.

Array Example Description
["M", 0, 0] The first point in the polygon. For squares and rectangles, this is the top-left corner. For other polygons, this is the first point you clicked.
["L", 70, 0] A point
...
["L", 0, 70] A point
["L", 0, 0] The final point. If the path is a closed polygon (including squares and rectangles), this point will be equal to the M 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.
Circle Path M.png
["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.
Circle Path C1.png
["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.
Circle Path C2.png
["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.
Circle Path C3.png
["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.
Circle Path C4.png

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.

Array Example Description
["M", 0, 44] The first point.
["Q", 0, 44, 0.5, 44] Two points: a Bézier control point, and the ending point of the curve.
...
["Q", 366.5, 55, 368, 54.5] Two points: a Bézier control point, and the ending point of the curve.
["L", 369.5, 54] The final point.

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.