Sample Projects
All of these demos are available to download here* (un-copylocked place).
* The (incomplete) witch model is for one of my own projects, so while the code for the first demo is available, the model is not
What is Path3D?
Path3D is a custom, 3d alternative to the existing Path2D instance. With it you can easily create smooth, curved paths, similar to beams. These paths can then be used in animations to control an NPC's movement, used to create paths and other models, or anything else which needs a smoothly curving line.Overview of the Module
Full documentation of the module can be found here.
The module offers two ways to create a Path3D instance, Path3D.fromPathString() or Path3D.fromAnchorTables(). If you own the editor, Path3D.fromPathString() offers a simpler way to create Path3D instances. Alternatively, Path3D.fromAnchorTables() can be used to create Path3D instances from Vector3’s, offering an alternative if you do not own the editor. For the sake of simplicity, these demos will use Path3D.fromPathString() but details on how to use Path3D.fromAnchorTables() can be found in the documentation.
This code samples demonstrates how you can use Path3D.fromPathString() to create a new Path3D instance.
local Path3D = require(script.Parent.Path3D) --Replace with the path to the module
local PATH_STRING = script.PathString.Value --Assuming a StringValue child
local path = Path3D.fromPathString(PATH_STRING)
From there, you can simply use Path3D:GetCFrameOnCurve() to get points along the path. For example, making a part move smoothly along the path is as simple as this:
local Path3D = require(script.Parent.Path3D)
local PATH_STRING = script.PathString.Value
local PATH_CENTER = Vector3.new(0, 0, 0)
local TRACKING_PART = workspace.TrackingPart
local path = Path3D.fromPathString(PATH_STRING, PATH_CENTER)
local tweenValue = Instance.new("NumberValue")
tweenValue.Value = 0
tweenValue.Changed:Connect(function(newValue)
trackingPart:PivotTo(path:GetCFrameOnCurve(newValue))
end)
local tweenInfo = TweenInfo.new(
5,
Enum.EasingStyle.Linear,
Enum.EasingDirection.In,
0,
false,
0
)
local tweenGoal = {Value = 1}
local tween = game:GetService("TweenService"):Create(tweenValue, tweenInfo, tweenGoal)
tween:Play()
Additional properties and methods can be found in the module’s documentation found here.
Overview of the Editor
Along with the module, Path3D also comes with an editor to simplify the creation of the path strings. Although not required to use the module, the editor does simplify the process considerably. Below you'll find a quick overview of each of the features.
Settings
Settings
Always Display Paths: When enabled, the pivot and anchor points of paths will always be displayed regardless of whether or not they are actually selected.
Always Display Control Points: When enabled, control points will always be displayed as long as their path is selected or Always Display Paths is enabled, regardless of whether or not their anchor point is selected.
Enable Highlights: When enabled, highlights will displayed on the selected path's pivot point, as well as on the selected anchor and its control points.
Pivot Point Colour: An RGB value determining the colour of pivot points.
Anchor Point Colour: An RGB value determining the colour of anchor points.
Control Point Colour: An RGB value determining the colour of control points.
Path Actions
Path Actions
Create Path: This will create a new path for you to edit.
Insert Anchor Point: This will insert new anchor point after the selected anchor point, or at the end of the path if no anchor is selected.
Add Control Points: This will re-add an anchor's control points if you have previously deleted them (which the module does support).
Separate Control Points: This will separate the anchor's two control points, allowing you to move one without it updating the position of the other.
Link Control Points: This will link the anchor's two control points, causing them to mirror each other across the anchor. Generally, this results in smoother paths.
Link Output Value: In order to use this, you must select a path and a StringValue. When clicked, this will cause the path's output to link to the selected StringValue, resulting in any path string generated with the Generate Path String button to also be copied into that value. This helps so that you don't have to continually dig through scripts looking for which variable held the path string whenever you make a change, and also reduces the clutter too.
Generate Path String: When clicked, this will evaluate the selected path, generating a path string representation of it which will be available in the TextBox above the button, and if an output value is linked, it will also copy it there. The path string in the TextBox will automatically disappear after 5 seconds to ensure you don't accidentally copy an old path string.
Tips
Tips
- Generally, I’d recommend ensuring your tools are in global mode (
Ctrl + Lto toggle) when editing the control points, as the rotation of them can cause some issues if you are in local mode. If however you want to simply move a control point further away without changing the angle, switching to local mode lets your do this.
Known Issues
Known Issues
These almost entirely relate to undo/redo
- When performing an undo/redo action, you may occasionally get an error message saying something like “
Maximum event re-entrancy depth exceeded.” This can be safely ignored, this seems to be caused by undo/redo not properly firing Selection.SelectionChanged, which causes issues for control points mirroring each other. While there are measures in place to reduce the likelihood of this, I have still seen it happen occasionally. - Also related to Selection.SelectionChanged not firing properly on an undo/redo, sometimes when performing an action after an undo/redo, you may get a warning saying “
Selection became desynced due to undo/redo, please try again.” Simply pressing the button again should resolve this without any other consequences. - If you close studio, or start a play test session while a path is selected, that path will not become hidden, so make you deselect any paths before closing studio or starting the game. Unfortunately, Plugin.Unloading does not seem to fire under these circumstances, and I haven’t been able to find an event that does.
As well, the Path3D module also comes with another script which can be disabled with the EnableEditorCleanup attribute. When enabled, this deletes any paths that the editor has created, ensuring they do not appear for players. If you want to access any of the paths at runtime, you can disable this to clean them up yourself (they’re all stored under Workspace._Path3DEditorPaths).
Where to Get Them
The Path3D module is available for free here.
(Unfortunately I’m not able to distribute packages, as soon as I can I will update this to be a package).
The Path3D Editor is available for $4.99USD here. Note that the editor is not required to use the module, as Path3D.fromAnchorTables() provides an alternative constructor.
