Texto

Como adicionar texto à sua cena

Adicionar texto a uma scene usando o TextShape component. Este texto fica numa posição

O texto em Decentraland suporta todos os utf8 caracteres, incluindo caracteres orientais e especiais.

📔 Nota: Este component é útil para etiquetas no mundo e UIs que existem no espaço 3D da scene, não para a UI HUD 2D do jogador.

O TextShape component é mutuamente exclusivo com outros shape components como primitive shapes e modelos 3D glTF, veja Shape components para mais detalhes.

Para adicionar texto como uma etiqueta a uma entity existente, cria-se uma segunda entity que tem o TextShape component e define-o como filho da outra entity.

Usar o Scene Editor no Creator Hub

A forma mais fácil de colocar texto no mundo é adicionar um Text Smart item visualmente no Scene Editor. Depois, podes definir todos os campos disponíveis na UI do Scene Editor.

Criar um component de texto

O exemplo seguinte mostra como criar um TextShape component e adicioná-lo a uma entity via código.

const sign = engine.addEntity()

Transform.create(sign, {
	position: Vector3.create(8, 1, 8),
})

TextShape.create(sign, {
	text: 'Hello World',
})

📔 Nota: Se a entity com o component de texto for filha de outra entity, então será afetada pela escala do pai. Se o pai for escalado de forma desigual ao longo do seu eixo, isso fará com que o texto também seja esticado ou comprimido.

📔 Nota: TextShape components não são clicáveis. PointerEvents os comopnents não são ativados quando usados em entites que têm um TextShape componente.

📔 Nota: TextShape devem ser importados via

import { TextShape } from "@dcl/sdk/ecs"

Veja Imports para saber como lidar facilmente com estes casos.

Alterar o valor do texto

Ao criar um novo component de texto, atribuis-lhe uma string para apresentar. Esta string é armazenada no text field.

Se quiseres alterar a string apresentada pelo component, podes fazê-lo a qualquer momento, alterando o text field numa versão mutável do component.

const mutableText = TextShape.getMutable(myEntity)

mutableText.text = 'new string'

Propriedades básicas do texto

O TextShape component tem várias propriedades que podem ser definidas para estilizar o texto. Abaixo estão algumas das mais comuns:

• font: Valor do enum Font.

• fontSize: number. Uma entiy com font 10 tem 1 metro de altura.

• textColor: Color4 objeto. Color4 objects armazenam um RBG cor como três números de 0 a 1, mais alpha para transparência. Vê tipos de cor para mais detalhes.

TextShape.create(sign, {
	text: 'Hello World',
	textColor: { r: 1, g: 0, b: 0, a: 1 },
	fontSize: 5,
	font: Font.F_SANS_SERIF,
})

Fonts

Text shapes podem usar fonts do enum Font. Este enum inclui atualmente as seguintes fonts:

• Font.F_SANS_SERIF

• Font.F_SERIF

• Font.F_MONOSPACE

Por defeito usa Font.F_SANS_SERIF.

TextShape.create(sign, {
	text: 'Hello World',
	textColor: { r: 1, g: 0, b: 0 },
	fontSize: 5,
	font: Font.F_SANS_SERIF,
})

📔 Nota: Atualmente, todas as fonts são renderizadas como Sans Serif. Este é um problema conhecido a corrigir no futuro.

💡 Dica: Se estiveres a usar o VS studio ou outro IDE, escreve Font. e deverás ver uma lista de sugestões com todas as fonts disponíveis.

Propriedades de alinhamento e padding do texto

O TextShape component cria uma caixa de texto que tem tamanho, padding, etc.

• textAlign: Seleciona um valor do TextAlignMode enum. Os valores possíveis incluem todas as combinações entre alinhamento vertical (top, bottom, center) e horizontal (left, right, center).

• width: number. A largura da caixa de texto.

• height: number. A altura da caixa de texto.

• paddingTop: number. Espaço entre o texto e o contorno da caixa de texto.

• paddingRight: number. Espaço entre o texto e o contorno da caixa de texto.

• paddingBottom: number. Espaço entre o texto e o contorno da caixa de texto.

• paddingLeft: number. Espaço entre o texto e o contorno da caixa de texto.

• zIndex: number. Útil quando várias entities planas ocupam o mesmo espaço; determina qual mostrar à frente.

💡 Dica: Se um texto se destina a flutuar no espaço, é boa ideia adicionar um Billboard component para que o texto rode e fique sempre virado para o jogador, tornando-se legível.

Propriedades de sombra e contorno do texto

O texto não tem sombra por defeito, mas podes definir os seguintes valores para lhe dar um efeito semelhante a sombra.

• shadowBlur: number

• shadowOffsetX: number

• shadowOffsetY: number

• shadowColor: Color3 objeto. Color3 objects armazenam um RBG cor como três números de 0 a 1.

TextShape.create(sign, {
	text: 'Text with shadow',
	shadowColor: { r: 1, g: 0, b: 0 },
	shadowOffsetY: 1,
	shadowOffsetX: -1,
})

As letras no texto também podem ter um contorno de uma cor diferente à volta do seu perímetro.

• outlineWidth: number. Quão largo será o contorno do texto, em todas as direções, como um número de 0 a 1. Por defeito 0, o que o torna invisível.

• outlineColor: Color3 objeto. Color3 objects armazenam um RBG cor como três números de 0 a 1.

Múltiplas linhas

Se quiseres que o teu texto ocupe várias linhas, usa \n como parte da string. O exemplo seguinte tem duas linhas de texto separadas:

TextShape.create(sign, {
	text: 'This is one line. \nThis is another line',
})

Também podes definir as seguintes propriedades relacionadas com textos com várias linhas:

• lineCount: number. Quantas linhas de texto cabem no textbox no máximo. Por defeito 1. O textWrapping property tem de estar true para usar mais de uma linha.

• lineSpacing: string. Quanto espaço existe entre cada linha, expresso como uma string. Por exemplo "30px".