Text shapes

Add text to a scene using the TextShape component. This text sits in a position

Text in Decentraland supports all utf8 characters, this includes oriental and special characters.

📔 Note: This component is useful for in-world labels and UIs that exist in the 3D space of the scene, not for the player’s 2D HUD UI.

The TextShape component is mutually exclusive with other shape components like primitive shapes and glTF 3D models, see Shape components for more details.

To add text as a label on an existing entity, you create a second entity that has the TextShape component and set it as a child of the other entity.

Create a text component #

The following example shows how to create a TextShape component and add it to an entity.

const myEntity = new Entity()
const myText = new TextShape("Hello World!")
myEntity.addComponent(myText)

📔 Note: If the entity with the text component is a child of another entity, then it will be affected by the parent’s scale. If the parent is scaled unevenly, this will result in the text also being stretched or compressed.

📔 Note: TextShape components aren’t clickable. OnPointerDown, OnPointerUp, OnHoverEnter, and OnHoverExit comopnents aren’t activated when used on entites that have a TextShape component.

Change the text value #

When creating a new text component, you assign it a string to display. This string is stored in the value field.

If you want to change the string displayed by the component, you can do so at any time by changing the value field.

myEntity.getComponent(TextShape).value = "new string"

Basic text properties #

The TextShape component has several properties that can be set to style the text. Below are some of the most common:

font: Font object. Font objects are initiated with a value from the Fonts enum, which contains all supported fonts. By default uses LiberationSans.
fontSize: number.
color: Color3 object. Color3 objects store an RBG color as three numbers from 0 to 1.

opacity: number. Set it to less than 1 to make the text translucid.

const myText = new TextShape("Hello World!")
myText.fontSize = 30
myText.color = Color3.Blue()
myText.font = new Font(Fonts.SansSerif)

Fonts #

By default, text in Decenrtaland uses the font LiberationSans. To use another font, you need to instance a new Font object and assign it to the font property of the TextShape object.

When instancing a Font, you need to pass it a value from the Fonts enum. This enum is a list that contains all the supported fonts.

const myText = new TextShape("Hello World!")
myText.font = new Font(Fonts.SansSerif)

The following fonts are currently supported:

LiberationSans
SansSerif
SansSerif_Bold
SansSerif_Heavy
SansSerif_Semibold

💡 Tip: If using VS studio or some other IDE, type Font. and you should see a list of suggestions with all of the available fonts.

You can share a same instanced Font object accross multiple TextShape components.

const sfFont = new Font(Fonts.SansSerif)

const myText = new TextShape("Hello World!")
myText.font = sfFont

const myText2 = new TextShape("Bye World!")
myText2.font = sfFont

Text alignment and padding properties #

The TextShape component creates a text box that has a size, padding, etc.

hTextAlign: string. Either left, right or center (default).
vTextAlign: string. Either top, bottom or center (default).
width: number. The width of the text box.
height: number. The height of the text box.
paddingTop: number. Space between the text and the outline of the text box.
paddingRight: number. Space between the text and the outline of the text box.
paddingBottom: number. Space between the text and the outline of the text box.
paddingLeft: number. Space between the text and the outline of the text box.
zIndex: number. Useful for when multiple flat entities occupy the same space, it determines which one to show in front.

💡 Tip: If a text is meant to float in space, it’s a good idea to add a Billboard component so that the text rotates to always face the player and be legible.

Text shadow and outline properties #

The text has no shadow by default, but you can set the following values to give it a shadow-like effect.

shadowBlur: number
shadowOffsetX: number
shadowOffsetY: number
shadowColor: Color3 object. Color3 objects store an RBG color as three numbers from 0 to 1.

myEntity.addComponent(new TextShape("Text with shadow"))
myEntity.getComponent(TextShape).shadowColor = Color3.Gray()
myEntity.getComponent(TextShape).shadowOffsetY = 1
myEntity.getComponent(TextShape).shadowOffsetX = -1

Every letter can also have an outline in a different color surrounding its perimeter.

outlineWidth: number. How many pixels wide the text outline will be, in all directions. By default 0, which makes it invisible.
outlineColor: Color3 object. Color3 objects store an RBG color as three numbers from 0 to 1.

Multiple lines #

If you want your text to span multiple lines, use \n as part of the string. The following example has two separate lines of text:

myEntity.addComponent(new TextShape("This is one line. \nThis is another line"))

You can also set up the following properties related to texts with multiple lines:

lineCount: number. How many lines of text to fit into the textbox as a maximum. By default 1. The textWrapping property must be true to use more than one line.
lineSpacing: string. How much space between each line, expressed as a string. For example “30px”.