What is UIStroke?
UIStroke is a new instance that can be parented to other GuiObjects to apply an outline around them. You can think of it like a more customizable version of the existing BorderColor3 and TextStrokeColor3 APIs available today.
Key features of the new UIStroke include:
- Add a stroke to text or UI object borders
- Adjust the color and thickness of the stroke outline
- Change the transparency independently from the text or UI object
- Choose the corner style of the stroke including Round (default), Bevel and Miter
- Add a gradient to the stroke (using the UIGradient component)
- Full support for adding a stroke using rich text tags
How do I use it?
First, you must enable the UIStroke beta feature in studio.
Enable the Beta Feature
To enable the beta feature:
- Go to File - Beta Features in studio
- Check the box before UIStroke Beta
- Restart studio
Next, parent the UIStroke to the UI object you would like to add the stroke to and adjust the properties.
- Color: Color of the stroke
- Thickness: Thickness of the stroke
- Transparency: Transparency of the stroke
- LineJoinMode: Change the corner style (Round - default, Bevel, Miter)
- ApplyStrokeMode: Only needed when applying stroke to the border of a text object instead of the text
Alternatively, you can add rich text tags to any text, if you would like to use the stroke on specific words within a string.
Rich Text
With this beta enabled, you will also be able to use the <stroke> Rich Text tag. The following properties can be set within a single <stroke> tag:
| Property | Default | Description |
|---|---|---|
| color | rgb(0, 0, 0) |
Controls the color. |
| joins | round |
Can be set to round, bevel, or miter. |
| thickness | 1.0 |
Controls the thickness. |
| transparency | 0.0 |
Controls transparency. |
You can combine the tags like this:
The
<font color="#985707">
<stroke color="#f5af09" thickness="5">
dog
</stroke>
</font>
is happy.
Text and UI Borders
UIStroke can operate in two different ways. When parented to a text object, it applies to the text’s outline, and when parented to other GuiObjects it applies to the UI border. This behavior can be overridden using the ApplyStrokeMode property, which allows you to apply the stroke to the border of a text object, instead of the text itself.
Transparency
The Transparency property of UIStroke is independent from the BackgroundTransparency or TextTransparency of the parent object. This allows you to render text and borders that are “hollow” - consisting of only an outline.
Corner Style
There’s also an extra property, LineJoinMode, which lets you control how corners are interpreted. It has three values, Round, Bevel, and Miter.
Gradients
UIGradient interacts with UIStroke in a special way. The parent object and the UIStroke can both separately have UIGradients parented to them, allowing for interesting effects.
UICorner
UIStroke can be also used with objects that have a UICorner instance.
ApplyStrokeMode
ApplyStrokeMode is only useful when the UIStroke is parented to a text object. It allows you to decide whether the stroke will be applied to the border, or to the text. By default it’s set to Contextual, which will apply to text.
It’s possible to have two UIStrokes parented, one set to Contextual, one set to Border. When you do this, you can control both the UI border and the text outline using two different sets of properties.
Animation & Performance
All of the properties of UIStroke can be smoothly tweened and most of the properties are very efficient to update when tweened.
However, you should be careful when tweening the Thickness property when the UIStroke is applied to text. This results in many glyph sizes being rendered and stored each frame. This could cause performance issues or even cause text to start flickering due to running out of space for glyph textures.
Behavior change to TextStrokeTransparency
This feature changes the behavior of TextStrokeTransparency. Previously, strokes were achieved by rendering the same-sized glyph 4 times at different offsets. This is being changed to use the same rendering logic as UIStroke, which only needs to render the glyph once. If you only use a TextStrokeTransparency of 0 or 1, you likely won’t notice, but intermediate values like 0.5 may appear more transparent than they used to.
Let us know if any of your games are significantly impacted by this.
Known Issues
These are issues you may run into that will be fixed before release.
-
BillboardGuis that have text with TextScaled enabled and TextStroke enabled have broken rendering.Should be fixed as of March 30th. - There’s no way to make Thickness scale with size inside of a BillboardGui with TextScaled enabled.
- Semi-transparent stroke lines that overlap, will be seen underneath each other; this is more of a limitation that requires a separate feature, currently working on this for all UI elements (not just stroke lines)
