Difference between revisions of "Mod:Objects/Path"
From Roll20 Wiki
(→Oval Paths: updated doc to describe the bezier curve stuff) |
Andreas J. (Talk | contribs) m (1223200 moved page API:Objects/Path to Mod:Objects/Path) |
||
| (8 intermediate revisions by 3 users not shown) | |||
| Line 1: | Line 1: | ||
| − | {{apibox}} | + | <noinclude>{{revdate}}{{apibox}} |
| − | + | {{main|Mod:Objects}} | |
| − | The | + | 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 == | == Path Object == | ||
| − | + | </noinclude> | |
{| class="wikitable" | {| class="wikitable" | ||
|- | |- | ||
| Line 13: | Line 13: | ||
| _id | | _id | ||
| | | | ||
| − | | A unique ID for this object. Globally unique across all objects in this | + | | A unique ID for this object. Globally unique across all objects in this game. Read-only. |
|- | |- | ||
| _type | | _type | ||
| Line 25: | Line 25: | ||
| _path | | _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 | | fill | ||
| "transparent" | | "transparent" | ||
| − | | Fill color. Use the string | + | | Fill color. Use the string {{c|transparent}} or a hex color as a string, for example {{c|#000000}} |
|- | |- | ||
| stroke | | stroke | ||
| Line 41: | Line 41: | ||
| layer | | layer | ||
| "" | | "" | ||
| − | | Current | + | | 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 | | stroke_width | ||
| Line 70: | Line 70: | ||
| 1 | | 1 | ||
| Vertical scale factor for the path. | | 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 | | 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. | | 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. | 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 84: | Line 94: | ||
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: | 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 === | === Polygonal Paths === | ||
| Line 137: | Line 147: | ||
|} | |} | ||
| − | In all of the demonstration images above for the | + | 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 === | === Freehand Paths === | ||
| Line 165: | Line 175: | ||
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). | 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 <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. | 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. | 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 | + | = 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> | ||
Latest revision as of 08:30, 9 June 2024
 | Page Updated: 2024-06-09 |
Roll20 Mod
Use Mods
- Use & Install
- Mod:Script Index & Suggestions
- Short Community Scripts
- Meta Scripts
- User Documentation
- Mod Scripts(Forum)
- Mod Update 2024🆕
- Macro Guide
Mod Development
Reference
- Objects
- Events
- Chat Events & Functions
- Utility Functions
- Function
- Roll20 object
- Token Markers
- Sandbox Model
- Debugging
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.
Contents |
[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. |
| oneWayReversed | false or true . For One-Way Barrier. helpful in changing the direction the arrows are facing | |
| 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 |
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.
