This post is for the documentation related to the Path3D module, for information regarding the editor, demos, or a general overview, see here.
Get the module here.
Get the editor (not required) here.
Static Methods
These methods are all contained within the Path3D module returned fromrequire()
Static Methods
Path3D.fromPathString(pathString, position, lengthOptions): Path3D
Path3D.fromPathString()
This method creates a new Path3D instance from the given path string, positioning it at the given position and evaluating its length using the given length options.
pathString: string
This is the string representation of the Path3D, generated either by the Path3D Editor or by hand. Further information on the formatting of the path string can be found at the end of this post.position: Vector3
(Defaults to 0, 0, 0)This is the location of the Path3D's pivot point. Changing this changes the location of all the anchors and control points as well.
lengthOptions: Path3DLengthOptions
(Defaults to:recordedSplits = 35
minimumLength = 0.5
minimumSuccesses = 2
minimumSplits = 0
maximumSplits = 0)
This parameter controls how the length of the Path3D will be evaluated, further details on what each setting does can be found under Path3D.newLengthOptions()
Return: Path3D
This is the Path3D that the path string represents, located at the given position, and with its length evaluated using the given length optionsPath3D.newLengthOptions(recodedSplits, minimumLength, minimumSuccesses, minimumSplits, maximumSplits): Path3DLengthOptions
Path3D.newLengthOptions()
This function creates a new length options table which will tell Path3D.fromPathString() how to evaluate the length of the path. When evaluating the length of a path, the module will first split the path into the individual Bézier that make it up. From there, each curve will be split into a number of segments determined by recordedSplits, and these individual splits are then used to linearize the distribution of t values when using Path3D:GetPositionOnCurve(). Each individual split is then recursively split in half, with the minimum and maximum depth of the function being controlled by minimumSplits and maximumSplits. This is continued until the distance between the start and the ending point that the function is evaluating has been less than minimumLength minimumSuccesses times in a row, at which point the function will return the distance between the two points, summing each individual segment, and determining the length of the Path3D. For most purposes, you can just leave this as the default and it’ll work fine.
recordedSplits: number
(Defaults to 35, must be greater than 0)This is the total amount of splits that will be in each segment, being used by
Path3D:GetPositionOnCurve() to linearize t values. If you notice that parts travelling along your Path3D tend to "slow down" around corners and "speed up" on straight sections, this could be caused by this value being too small.
minimumLength: number
(Defaults to 0.5, must be greater than 0)This is the minimum distance that two points on the curve must be from each other before the length evaluator will simply return the distance between the two points instead of splitting the curve in half once more.
minimumSucces: number
(Defaults to 2, must be greater than or equal to 0)This is the amount of times that the length evaluator must concurrently find that the distance between two points is less than
minimumLength before it will stop splitting the curve. Setting this too low or disabling it can result in cases where the evaluator may mistake the intersection formed by a cusp to simply be a normal part of the curve, causing the length of the cusp to skipped, resulting in issues with the length of the Path3D. Setting this to 0 disables this.
minimumSplits: number
(Defaults to 0, must be greater than or equal to 0)This is the minimum recursion depth that the length evaluator must reach before it will stop splitting the curve. This helps solve edge cases where the start and end of the curve are next to each, causing the evaluator to believe them to on the curve, stopping immediately. In practice this is largely replaced by
minimumSuccess which is why it is disabled by default, however it is included in case you want more control over the length evaluator. Setting this to 0 disables this.
maximumSplits: number
(Defaults to 0, must be greater than or equal to 0)This setting allows you to determine the maximum recursion depth that the length evaluator may reach before simply returning the distance between two points. Setting this to low values may result in segments of the curve being "skipped," resulting in the given length being inaccurate, potentially causing more problems. Using this isn't recommended due to the potential problems it can cause, so this acts more as an intermediary solution should the length evaluator get stuck in an infinite loop. If you do encounter something like this, please report it to me immediately so I can fix it. Setting this to 0 disables this.
Return: Path3DLengthOptions
This returns aPath3DLengthOptions table with the provided settings.
Path3D Instance Properties
These properties are all contained within a Path3D instance, returned fromPath3D.fromPathString().
Path3D Instance Properties
Path3D.Length: number
Read OnlyThis contains the length of the Path3D, calculated when it was created using the provided length options
Path3D.Position: Vector3
This is the position of the pivot point of the Path3D, changing this also changes the position of all anchor and control points to maintain their offsets.Path3D.ClassName: "Path3D"
Read OnlyAlthough a Path3D is not technically an Instance, ClassName is included to allow you to dynamically check if something is or isn't a Path3D
Path3D.__type: "Path3D"
Read OnlyIdentical to Path3D.ClassName, included to allow you to check types however you prefer.
Path3D._internalData
Read OnlyInternal data used to run the Path3D's functions. Don't use this at all, it is subject to change without notice and any information within it is also provided through other methods. Just forget I even mentioned it.
Path3D Instance Methods
These methods are contained within a Path3D instance created usingPath3D.fromPathString() and are accessed using instance notation.
Path3D Instance Methods
Path3D:GetPositionOnCurve(t): Vector3
Path3D:GetPositionOnCurce()
This function evaluates the Path3D, taking in a percentage of how far along the path the point should be sampled at and returning where in the world that point is. Note that traditionally t values in Bézier curves are not distributed linearly across the curve, however this function applies an adjustment to the provided t value to ensure they are distributed linearly. If you notice parts following a Path3D are “slowing down” and “speeding up” throughout their journey despite t increasing linearly, it may be because your Path3DLengthOptions.recordedSplits is too small. For an alternative that does not adjust the provided t value, see Path3D:GetUnadjustedPositionOnCurve().
t: number
(Must be in the range of 0-1) This is the percentage as a decimal of how far across the path the point should be sampled at. For example, a t value of 0.5 would return a point halfway along the curve.Return: Vector3
This returns where in the world the point at the given t value is, accounting for the Path3D's position.Path3D:GetUnadjustedPositionOnCurve(t): Vector3
Path3D:GetUnadjustedPositionOnCurve()
This function is nearly identical to Path3D:GetPositionOnCurve(), however it does not apply any adjustments to the provided t value, instead feeding the directly into the BĂ©zier formulas. In practice this means that, for example, a t value of 0.9 will not necessarily return the point 90% of the way along the Path3D.
t: number
(Must be in the range of 0-1) This is the percentage along the curve that the point will be sampled at as a decimal.Return: Vector3
This is the point along the Path3D at the given t value.Path3D:GetSegmentLengths(): {number}
Path3D:GetSegmentLengths()
This function returns an array containing the length of each individual curve in the Path3D, ordered from the start (t = 0) to the end (t = 1).
Return: {number}
This is an array with the length of curve in the Path3DPath3D:GetAnchorTables(): {Path3DAnchorTable}
Path3D:GetAnchorTables()
This function returns an array of tables representing every single anchor and control point in the Path3D. These tables are what the module uses internally to represent the Path3D, and information on what they contain can be found below.
Return: {Path3DAnchorTable}
This is an array of all the Path3DAnchorTables that make up the given Path3D.Path3DAnchorTable Properties
These are all of the properties of thePath3DAnchorTables returned from Path3D:GetAnchorTables().
Path3DAnchorTable Properties
Path3DAnchorTable.priorControlPoint: Vector3
This is the position of one of the control points (p2) of the previous curve, recorded as an offset from the position of its anchor point.Path3DAnchorTable.anchor: Vector3
This is the position of an anchor point in a Path3D, recorded as an offset from the pivot point.Path3DAnchorTable.nextControlPoint: Vector3
This is the position of one of the control points (p1) of the next curve, recorded as an offset from the position of its anchor point.The Path String
The path string. The thing that runs the whole module. I've tried to strike a balance between ensuring this string doesn't get excessively long, while still being easy to create by hand if you don't own the editor. If you do own the editor, you probably don't need to worry about this, otherwise, here's how to format the path string. Future me here, just finished writing this section and I realized it looks really intimidating, but trust me, it's actually quite simple, this just goes into very thorough detail on exactly what everything does. If you are not familiar with the path string format, I highly recommend going through each section in order, as each one builds off the last.The Path String
Path String Version 1:
Terminology:
Terminology
This next section uses some terminology, and while they should be fairly intuitive, they’re listed here to make sure everyone understands.
Anchor Point: An anchor point is simply a point where one curve in the Path3D ends and another one begins.
Prior Control Point: The prior control point is the control point for the curve before the anchor it is associated with. For those familiar with cubic BĂ©zier curves, this is p2 in the previous curve.
Next Control Point: The next control point is the control point for the curve after the anchor it is associated with. For those familiar with cubic BĂ©zier curves, this is p1 in the next curve.
Control Point Identifier: This one isn’t really intuitive. and what it means is explained under Anchor Point Groups.
Basic Outline:
Basic Outline
(Version)/(Anchor Point Group 1)/(Anchor Point Group 2)/(Anchor Point Group 3)…
This here is the basic outline of a path string, starting with a version number which indicates what version of the path string format you are using (currently 1). This ensures that even if the formatting of this string does ever change, old path strings will continue to function as they do now without needing to go through and update them. Next up we have the anchor point group. The formatting of this gets a bit more complicated and is explained below, but after the version number you can list as many of these as you would like, with each anchor point group extending the path. Finally, separating all of these, we have forward slashes (/). Omitting the anchor groups for now, an actual path string would look something like this:
1/(Anchor Point Group 1)/(Anchor Point Group 2)/(Anchor Point Group 3)/(Anchor Point Group 4)
The 1 at the very start indicates that this path string is using path string format 1. Then, we have a forward slash to separate it from the first anchor point group. Next, we also include a forward slash in between each anchor point group, separating them from each other. This particular path string has 4 anchor points, meaning that the final Path3D will have 3 segments.Anchor Point Groups:
Anchor Point Groups
(Control Point Identifier)(Prior Control Point Offset)(Anchor Point Offset)(Next Control Point Offset)
IMPORTANT: This general format has had its spaces ( ) replaced with underscores () to make it more readable, the actual path string uses spaces instead of underscores.
Above is a general template for how the anchor point group is formatted. Each anchor point group starts off with a number known as the control point identifier. The control point identifier tells the module how many and which control points have been listed, and it is important that this matches with what is actually listed. The possible values for the control point identifier and what they indicate is listed below.
0: This indicates that there are no control points present, only the anchor point
1: This indicates that only the prior control point and the anchor point are present.
2: This indicates that only the next control point and the anchor point are present.
3: This indicates that both the prior control point, the next control point and the anchor point are present.
Following the control point identifier, a space (not an underscore) is used to separate it from the first offset. The prior control point, anchor point, and next control are always listed in that order (prior, anchor, next). If a point is missing, for example if you only have an anchor point and a next control point, then you simply skip the point that you don’t have. Each anchor point’s position is listed as an offset from the path’s pivot point, and each control point is listed as an offset from its anchor point. A list of how an anchor point group would be structured for each control point identifier is listed below:
Examples
0: 0 (Anchor)
1: 1 (Prior Control Point) (Anchor)
2: 2 (Anchor) (Next Control Point)
3: 3 (Prior Control Point) (Anchor) (Next Control Point)
Offset Format:
Offset Format
(X),(Y),(Z)
By far the simplest part of the path string, each offset is simply listed as x, y, z coordinates separated with commas. One important detail to note however is that there are no spaces between the commas and the next axis. For example, an anchor offset from the pivot by 10, 0, 3 with no control points would have an anchor point group of:
0 10,0,3
Putting it all Together:
Putting it all Together
In order to bring everything about the path string all together, I’ll show how to recreate the path string from the Path3D Editor’s default path.
To start off with, the most recent path string version is 1, and that’s the same one the editor uses, so we’ll start our path string with 1.
1
Next we need to separate our first anchor point group.
1/
Now we start our first anchor point group. Because the default path has both control points, we’ll use 3
1/3
Next up we have the prior control point. The prior control point is offset from the first anchor by 10, 0, 0, so we’ll put that in.
1/3 10,0,0
After that there’s the anchor point. The anchor point is offset from the path’s pivot point by 0, 0, -10, so we put that in.
1/3 10,0,0 0,0,-10
Then we have the next control point. The next control point is offset from the anchor point by -10, 0, 0, so we put that in.
1/3 10,0,0 0,0,-10 -10,0,0
And now we have our first anchor point group done! Since this is the starting anchor, the prior control point doesn’t actually do anything, however the module doesn’t care about that, and the Path3D Editor will still include it. In order to demonstrate different control point identifiers though, the final anchor point will omit the next control point.
Continuing on, we insert our separator and our control point identifier. Because we are listing a prior control point and an anchor point, we’ll use 1.
1/3 10,0,0 0,0,-10 -10,0,0/1
As with the first anchor point group, the prior control point is offset by 10, 0, 0, so we put that in.
1/3 10,0,0 0,0,-10 -10,0,0/1 10,0,0
Finally, we add on the anchor point’s offset from the pivot, that being 0, 0, 10.
1/3 10,0,0 0,0,-10 -10,0,0/1 10,0,0 0,0,10
And that there is the path string for the Path3D Editor’s default path. Since we don’t have a next control point, and we’ve told the module that by using 1 as our control point identifier, we can simply leave out the final control point and the path string will still function. Don’t forget to test your path strings as you go, otherwise you might make a dumb mistake like mixing up your X and Z axis (something I definitely, absolutely did not do in that last section).
And those are the docs! If you encounter any problems, please report them to me on the Path3D announcement post (first link at the top).
That was a lot to write