Hi Developers!
We are excited to announce the Studio beta release of the new Path2D API and tooling to support this API, so you can create, edit, and visualize 2D splines. Path2D provides creators with a 2D spline instance, enabling them to create UI elements and effects like graph editors and UI animations.
How to Enable and Use Path2D
To enable the beta feature:
- Launch Studio.
- Select File, Beta Features.
- Check the box next to “Path2D Beta” and click Save.
- When prompted, restart Studio.
To use Path2D:
- Insert a Path2D instance (from the Explorer) in the UI hierarchy under any ScreenGUI, BillboardGUI and SurfaceGUI.
- Path2D will also work as a child of any GuiObject but it won’t ignore folders like other UI elements.
- After inserting a Path2D into the tree structure, select it in the Explorer to bring up the in-viewport tooling.
- Path2D does not natively clip with other UI objects. However, you can use Path2D as a child of a Canvas Group to achieve clipping
Tooling
You can use the in-viewport tooling to create and modify Path2D instances. There are 3 tooling modes for editing the spline:
- Select Tool (Hot Key ‘s’)
- Add Point (Hot Key ‘p’)
- Add Tangent (Hot Key (‘t’)
Tips
- In Add Point mode, if there are already segments created, you will either need to click on the beginning or end control points and continue to add from there or you will be able to insert a control point anywhere along the Path2D.
-
In Select Tool and Add Tangent modes, right clicking on control points or tangent handles will bring up a context menu with the following options:
-
Tangent handles, Delete tangent
-
Control Point, Break/Mirror tangents, Clear Tangents, Delete (control point)
-
Undo/Redo keys work as expected
-
- In the Path2D instance, you will be able to select a control point by inserting the correct index. It will then bring up info about the control point, the position and tangent values.
API
Properties
-
Visible: bool
- Determines if the spline should render or not. When visible == false, the spline is still queryable and updatable.
-
Thickness: Number
-
Color: Color3
-
GetPositionOnCurve(t: float) → UDim2
- Queries the curve for the position at a given t
- t == 0, beginning. t == 0.5 middle (parametric center), t == 1 end
- Queries the curve for the position at a given t
-
GetPositionOnCurveArcLength(t: float) → UDim2
- Queries the curve for the position at a given t
- t == 0, beginning. t == 0.5 middle (geometric center), t == 1 end
- The arc length makes sure that the distance between each point along the curve is consistent.
- Queries the curve for the position at a given t
-
GetTangentOnCurve(t: float) → Vector2
- Returns the tangent at a given t
- t == 0, beginning. t == 0.5 middle (parametric center), t == 1 end
-
GetTangentOnCurveArcLength(t: float) → Vector2
- Returns the tangent at a given t
- t == 0, beginning. t == 0.5 middle (geometric center), t == 1 end
-
GetControlPoints() → List
-
SetControlPoints(List)
- Sets all the control points for a given Path2D, replacing what was there.
- Will fail if anything other than a Path2DControlPoint is passed in
- Note: the resulting update is expensive so it is recommended that this only be used if all control points need to be changed
-
GetControlPoint(index: int) → Path2DControlPoint
- Returns the control point at the requested index or nil in the Path2DControlPoint object
- If the index is out of range, throws a warning.
-
UpdateControlPoint(index: int, Path2DControlPoint)
- Updates the control point at the requested index. If the index does not exist, it will throw a warning
-
InsertControlPoint(index: int, Path2DControlPoint)
- Creates a control point at the requested index. If the index is larger than the control point list size or less than 0 return an error.
- This function will allow you to insert a control point at the beginning or end of the list of control points.
-
RemoveControlPoint(index: int)
- Removes the control point at the requested index. If the index is out of range, throw a warning
New Luau Atomic Type: Path2DControlPoint
- Path2DControlPoint.new()
- Path2DControlPoint.new(position: UDim2)
- Path2DControlPoint.new(position: UDim2, Left Tangent: UDim2, Right Tangent: UDim2)
See documentation for Path2D here.
Example Usage
The APIs GetPositionOnCurve, GetPositionOnCurveArcLength, GetTangentOnCurve, and GetTangentOnCurve are all used to sample the curve at a given t value. The t value must be between [0, 1]. Sampling at intervals between 0 and 1 can allow you to use the positions at any point along the curve. In this example, you can move a frame along a spline.
-- Make your Path2D using the in viewport tooling
-- Create a frame or some other object you'd like to move along the spline
local path = script.Parent.Path2D
local frame = script.Parent.Frame
local maxIter = 100
for counter = 0, maxIter do
local t = counter / maxIter
local position = path:GetPositionOnCurve(t)
frame.Position = position
wait()
end
Known Issues
- Performance is still being improved.
- Surface and billboard gui positions are not as expected
- Path2D underneath a Canvas Group breaks in some cases, and we’re in the process of fixing this.
- Team create has some issues with Path2D:
- Editing Path2D won’t replicate to other users
- Entering team test won’t show Path2D
- The control points may get reset
We’d love to know your feedback and learn how you plan to use this API! If you run into any issues or have further questions, please let us know!
Special thanks to the team who worked on this feature: @PotionSeller33, @MetaVars, @wengawenga, @0xabcdef1234, @ProtoValence, @Slim_Fandango, @guacandtoast @TangyTrout and everyone else who helped contribute!
