Win MANA and LAND in Decentraland's Creator Contest! Sign up today
X
Hello! Please choose your
desired language:
Dismiss

Text in a scene

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 user’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.

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.add(myText)

Basic text properties

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

  • fontSize: number
  • color: Color3 object. Color3 objects store an RBG color as three numbers from 0 to 1.
  • fontFamily: string. Can be a specific font (like Arial) or a type of font (serif/sans-serif). If you list several different fonts, it will attempt with the first and progressively fall back to the next ones. If you are using an uncommon font, it’s always recommendable to also list a more generic one, in case a user can’t access it.
  • fontWeight: string. Can be normal, bold, bolder, or lighter.
  • 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.fontFamily = "Arial, Helvetica, sans-serif"

Text alignment and padding properties

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

  • hAlign: string. Either left, right or center (default).
  • vAlign: string. Either top, bottom or center (default).
  • width: number. The width of the text box.
  • height: number. The height of the text box.
  • resizeToFit: boolean. If true, the font size is adjusted to fit as large as possible in 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: It a text is meant to float in space, it’s a good idea to set the TextShape component’s Billboard mode so that the text rotates to always face the user and be legible. See Position entities.

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.
myText.add(new TextShape("Text with shadow"))
myText.get(TextShape).shadowColor = Color3.Gray()
myText.get(TextShape).shadowOffsetY = 1
myText.get(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:

myText.add(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.