Latest revision as of 08:30, 9 June 2024

Roll20 Mod
Use Mods

Mod Development

Reference

Cookbook

Main Page: Mod:Objects

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.

[edit] Path Object

‎

Property	Default Value	Notes
_id		A unique ID for this object. Globally unique across all objects in this game. 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 b 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 between tokens.
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.
barrierType	"wall"	'oneWay', 'wall' or 'transparent'. For creating One-Way Barrier or an invisible barrier. ^{April 14, 2022}
oneWayReversed		false or true . For One-Way Barrier. helpful in changing the direction the arrows are facing^{April 14, 2022}
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. All Players is represented by having `all` 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.

[edit] 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.

[edit] 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.

[edit] 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.

[edit] 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).

[edit] 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.

[edit] See Also

@@ Line 1: / Line 1: @@
-{{apibox}}
+<noinclude>{{revdate}}{{apibox}}
+{{main|Mod:Objects}}
-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.
+The {{code|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 ==
+‎</noinclude>
 {| class="wikitable"
 |-
@@ Line 13: / Line 13: @@
 | _id
 |
-| A unique ID for this object. Globally unique across all objects in this campaign. Read-only.
+| A unique ID for this object. Globally unique across all objects in this game. Read-only.
 |-
 | _type
@@ Line 25: / Line 25: @@
 | _path
 |
-| A JSON string describing the lines in the path. Read-only. See [[#Path Property|Path Property]] below for more information.
+| A JSON string describing the lines in the path. Read-only. See [[Mod:Objects/Path#Path Property|Path Property]] below for more information.
 |-
 | fill
 | "transparent"
-| Fill color. Use the string "transparent" of a hex color as a string, for example "#000000"
+| Fill color. Use the string {{c|transparent}} or a hex color as a string, for example {{c|#000000}}
 |-
 | stroke
@@ Line 41: / Line 41: @@
 | 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.
+| Current <span style="font-family:Pictos;">b</span> [[Layer]], one of <code>gmlayer</code>, <code>objects</code>, <code>map</code>, or <code>walls</code>. The <code>walls</code>-layer is used for [[Dynamic Lighting]], and paths on the <code>walls</code>-layer will block light between [[tokens]].
 |-
 | stroke_width
@@ Line 70: / Line 70: @@
 | 1
 | Vertical scale factor for the path.
+|-
+| barrierType
+| "wall"
+| 'oneWay', 'wall' or 'transparent'. For creating [[One-Way Barrier]] or an invisible barrier. {{source|https://app.roll20.net/forum/permalink/10808632/ April 14, 2022}}
+|-
+| oneWayReversed
+|
+| false or true . For [[One-Way Barrier]]. helpful in changing the direction the arrows are facing{{source|https://app.roll20.net/forum/permalink/10808632/ April 14, 2022}}
 |-
 | 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.
-|}
+'''All Players''' is represented by having {{code|all}} in the list.
+|}
+‎<noinclude>
 Most of these properties are either self-explanatory or easy to grasp. It is the <code>_path</code> property, however, which is complicated and requires some further study.
@@ Line 82: / Line 92: @@
 The <code>_path</code> property is a JSON string, and is a read-only property of the Path object. In order to make use of the <code>_path</code> property, you must use <code>JSON.parse(myPath.get("path"))</code>.
-Once parsed, you'll see that the <code>_path</code> is an array of arrays. Depending on the type of path, the arrays will be different. There are three possible type of paths:
+Once parsed, you'll see that the <code>_path</code> 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.
+* [[#Polygonal 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 {{button|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.
+* [[#Oval Paths|Oval]]: this includes both ovals and circles. Both are formed with the "Draw Shape" tool while holding the {{button|Alt}} key.
-* Freehand: formed with the "Freehand" tool.
+* [[#Freehand Paths|Freehand]]: formed with the "Freehand" tool.
 === Polygonal Paths ===
@@ Line 125: / Line 135: @@
 |-
 | <code>["C", 0, 17.5, 17.5, 0, 35, 0]</code>
-| Three points along the oval's bounding box near the top-left corner.<br>[[File:Circle Path C1.png]]
+| 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.<br>[[File:Circle Path C1.png]]
 |-
 | <code>["C", 52.5, 0, 70, 17.5, 70, 35]</code>
-| Three points along the oval's bounding box near the top-right corner.<br>[[File:Circle Path C2.png]]
+| 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.<br>[[File:Circle Path C2.png]]
 |-
 | style="white-space:nowrap" | <code>["C", 70, 52.5, 52.5, 70, 35, 70]</code>
-| Three points along the oval's bounding box near the bottom-right corner.<br>[[File:Circle Path C3.png]]
+| 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.<br>[[File:Circle Path C3.png]]
 |-
 | <code>["C", 17.5, 70, 0, 52.5, 0, 35]</code>
-| Three points along the oval's bounding box near the bottom-left corner. The third point is equal to the ''M'' point.<br>[[File:Circle Path C4.png]]
+| 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.<br>[[File: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 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.
+In all of the demonstration images above for the {{code|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 ===
@@ Line 152: / Line 162: @@
 |-
 | <code>["Q", 0, 44, 0.5, 44]</code>
-| Two points: the previous point in the path, and the current point in the path.
+| Two points: a Bézier control point, and the ending point of the curve.
 |-
 | colspan="3" | ...
 |-
 | style="white-space:nowrap" | <code>["Q", 366.5, 55, 368, 54.5]</code>
-| Two points: the previous point in the path, and the current point in the path.
+| Two points: a Bézier control point, and the ending point of the curve.
 |-
 | <code>["L", 369.5, 54]</code>
@@ Line 163: / Line 173: @@
 |}
-While the freehand path is essentially a linked list of points, there are occasionally small differences (less than one pixel) between the "current point in the path" of one array and the "previous point in the path" of the next array.
+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 ===
+== Analyzing Path Values ==
 All points in the <code>_path</code> property are relative to the top-left corner of the path's bounding rectangle. So, a point of <code>0,0</code> 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 <code>top</code> and <code>left</code> properties.
@@ Line 173: / Line 183: @@
 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.
-[[Category:API|Path]]
+= See Also=
+* [https://en.wikipedia.org/wiki/B%C3%A9zier_curve Bézier curve]
+* [https://pomax.github.io/bezierinfo/ A Primer on Bézier Curves]
+[[Category:API Development]]
+</noinclude>

Roll20 Wiki

Navigation

Personal tools

Toolbox

Difference between revisions of "Mod:Objects/Path"

From Roll20 Wiki