> For the complete documentation index, see [llms.txt](https://docs.decentraland.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/text.md).

# Texto

Como adicionar texto à sua scene

Adicione texto a uma cena usando o `TextShape` componente. Este texto fica numa posição

O texto no Decentraland é compatível com todos os *utf8* caracteres, incluindo caracteres orientais e especiais.

{% hint style="warning" %}
**📔 Nota**: Este componente é útil para etiquetas e UIs no mundo, que existem no espaço 3D da cena, e não para a UI HUD 2D do jogador.
{% endhint %}

Para adicionar texto como etiqueta a uma entidade existente, é recomendável criar uma segunda entidade com o `TextShape` componente e defini-la como filha da outra entidade.

## Use o Scene Editor no Creator Hub

A forma mais fácil de posicionar texto no mundo é adicionar um **Text** [Smart item](https://docs.decentraland.org/creator/content-creator-pt/scene-editor/interatividade/smart-items.md) visualmente no Scene Editor. Depois, pode definir todos os campos disponíveis na UI do Scene Editor.

![](https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-aac144ab4f0494f7572cabd53279c11cd3d023a8%2Ftext-smart-item.webp?alt=media)

## Criar um componente de texto

O exemplo seguinte mostra como criar um componente `TextShape` e adicioná-lo a uma entidade através de código.

```ts
const sign = engine.addEntity()

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

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

{% hint style="warning" %}
**📔 Nota**: Se a entidade com o componente de texto for filha de outra entidade, será afetada pela escala da entidade principal. Se a entidade principal tiver uma escala desigual ao longo dos seus eixos, o texto também ficará esticado ou comprimido.
{% endhint %}

{% hint style="warning" %}
**📔 Nota**: `TextShape` componentes não são clicáveis. `PointerEvents` componentes não são ativados quando utilizados em entidades que têm um `TextShape` componente.
{% endhint %}

{% hint style="warning" %}
**📔 Nota**: `TextShape` tem de ser importado através de

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

Consulte [Imports](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/primeiros-passos/coding-scenes.md#imports) para saber como lidar facilmente com estes elementos.
{% endhint %}

## Alterar o valor do texto

Ao criar um novo componente de texto, atribui-lhe uma string para apresentar. Esta string é armazenada no campo `text` .

Se quiser alterar a string apresentada pelo componente, pode fazê-lo a qualquer momento, alterando o campo `text` numa [versão mutável](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/padroes-de-programacao/mutable-data.md) do componente.

```ts
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. Seguem algumas das mais comuns:

* `font`: valor do enum `Font`.
* `fontSrc`: *string*. Caminho para um arquivo de `.ttf` de fonte na sua cena ou o nome de uma família do Google Fonts, para renderizar o texto com uma fonte personalizada. Consulte [Fontes personalizadas](#custom-fonts).
* `fontSize`: *number*. Uma Entity com fontSize 10 tem 1 metro de altura.
* `textColor`: *Color4* object. *Color4* Os objetos armazenam uma cor *RGB* como três números de 0 a 1, além do *alpha* para transparência. Consulte [tipos de cor](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/color-types.md) para obter mais detalhes.

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

## Fontes

As formas de texto podem usar fontes do enum `Font`. Atualmente, esse enum inclui as seguintes fontes:

* `Font.F_SANS_SERIF`
* `Font.F_SERIF`
* `Font.F_MONOSPACE`

Por predefinição, usa `Font.F_SANS_SERIF`.

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

{% hint style="info" %}
**💡 Dica**: se estiver a usar o VS Studio ou outro IDE, escreva `Font.` para ver uma lista de sugestões com todas as fontes disponíveis.
{% endhint %}

### Fontes personalizadas

Para renderizar texto com a sua própria fonte, defina a propriedade `fontSrc` com um dos seguintes valores:

* **Um ficheiro TrueType (`.ttf`) ficheiro de fonte na sua Scene**: o respetivo caminho, relativo à pasta raiz da Scene (tal como o `src` de um `GltfContainer`).
* **Um** [**Google Fonts**](https://fonts.google.com/) **nome da família**, como `'Playfair Display'`. O cliente transfere o tipo de letra, por isso não precisa de adicionar nenhum ficheiro à sua Scene. O Desktop Client não suporta nomes de famílias; consulte a tabela abaixo.

Mantenha `font` também definido: é o fallback utilizado enquanto o tipo de letra personalizado carrega e sempre que não pode ser utilizado. Escolha um fallback que continue a ter um aspeto adequado e não dependa do tipo de letra personalizado para fazer o texto caber num espaço fixo.

{% hint style="warning" %}
**📔 Nota**: `fontSrc` requer `@dcl/sdk` 7.31.0 ou posterior. Nas versões anteriores, a propriedade não existe.
{% endhint %}

```ts
TextShape.create(sign, {
	text: 'Hello World',
	fontSize: 5,
	fontSrc: 'assets/fonts/Lobster-Regular.ttf',
	font: Font.F_SANS_SERIF,
})
```

Para utilizar uma família do Google Fonts, escreva o respetivo nome:

```ts
TextShape.create(sign, {
	text: 'Hello World',
	fontSize: 5,
	fontSrc: 'Playfair Display',
	font: Font.F_SERIF,
})
```

A mesma propriedade `fontSrc` existe nas entidades de UI `Label`, `Button`, `Input` e `Dropdown` , e em `uiText` de um `UiEntity`. Consulte [Tipos de letra personalizados na UI](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/ui-2d/ui_text.md#custom-fonts).

O suporte para tipos de letra personalizados varia consoante o cliente:

|                                 | Desktop Client                                                         | Aplicação móvel                             | Cliente Web Bevy |
| ------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------- | ---------------- |
| `ficheiro .ttf` na Scene        | Sim, depois de os recursos da Scene serem otimizados (consulte abaixo) | Sim, a partir da versão 1.16.2 da aplicação | Sim              |
| Nome da família do Google Fonts | Não, apresenta o fallback `font`                                       | Sim, a partir da versão 1.16.2 da aplicação | Sim              |

Os três clientes aplicam `fontSrc` para `TextShape` e para a UI `Label`, `Button`, `Input` e `Dropdown`.

{% hint style="warning" %}
**📔 Nota**: Na aplicação móvel, as fontes personalizadas requerem a versão 1.16.2 ou posterior da aplicação. As versões anteriores ignoram `fontSrc` e apresentam a fonte de fallback `font`.
{% endhint %}

Tenha em atenção o seguinte ao usar fontes personalizadas:

* **Só são suportados ficheiros `.ttf`**  . O ficheiro tem de ser uma fonte TrueType. As fontes OpenType com contornos CFF (normalmente `.otf`), as coleções de fontes (`.ttc`) e as fontes Web (`.woff`, `.woff2`) são rejeitadas, e o texto é apresentado com a fonte de fallback `font`. O cliente verifica o conteúdo do ficheiro, não a extensão, por isso mudar o nome de um ficheiro para `.otf`   `.ttf` não faz com que funcione.
* **Sem URLs externos**. `fontSrc` não pode apontar para um URL. Use um ficheiro na sua Scene ou o nome de uma família do Google Fonts. Se incluir um ficheiro de fonte, certifique-se de que a licença permite a redistribuição; a maioria das fontes do Google Fonts usa a SIL Open Font License, que o permite.
* **Nomes de famílias do Google Fonts**: escreva o nome tal como aparece no Google Fonts, como `'Open Sans'` ou `'Playfair Display'`. Não importa se usa maiúsculas ou minúsculas. O nome só pode conter letras sem acentos, dígitos e espaços: um nome com qualquer outro carácter, como `+`, `.`uma aspa simples ou uma letra acentuada, não é encontrado e a fonte de fallback `font` é apresentada. A fonte é transferida do [Fontsource](https://fontsource.org/), que aloja o catálogo do Google Fonts. O texto normal usa o peso 400, ou o mais próximo disponível na família, e o texto a negrito usa o peso 700, ou o mais próximo. Só são transferidos caracteres latinos ou, no caso de uma família sem caracteres latinos, o primeiro conjunto de caracteres que o Fontsource indica para essa família. Os outros caracteres são apresentados com a fonte incorporada definida em `font`. Os players para computador veem a fonte de fallback `font`, por isso, se a fonte for importante no computador, adicione o respetivo ficheiro `.ttf` à sua Scene.
* **No Desktop Client, as fontes personalizadas só aparecem depois de os assets da Scene serem otimizados**. Quando publica uma Scene, as respetivas fontes são convertidas em pacotes de assets otimizados, juntamente com os modelos 3D, e a fonte personalizada aparece assim que a conversão estiver concluída. Até lá, o texto usa a fonte de fallback `font`. As cenas publicadas antes de haver suporte para fontes personalizadas só convertem as fontes quando são publicadas novamente. As pré-visualizações locais no Desktop Explorer também convertem a fonte, que passa assim a ser apresentada, a menos que tenha ativado **Load Raw GLTFs**. Consulte [Pré-visualizar com recursos otimizados](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/primeiros-passos/preview-scene.md#preview-with-optimized-assets). O cliente Web Bevy carrega o ficheiro `.ttf` diretamente, pelo que a fonte personalizada é apresentada de imediato, também nas pré-visualizações locais.
* **Na aplicação móvel, uma cena pode carregar até 16 fontes personalizadas**. Uma fonte usada tanto na UI como num `TextShape` conta duas vezes. Além desse limite, o texto usa a fonte de reserva `font`. A aplicação móvel não simula o negrito em texto 3D: o texto a negrito numa `TextShape` usa o tipo de letra a negrito da família quando é indicado o nome de uma família do Google Fonts, e o tipo de letra normal quando é usado um ficheiro de fonte na cena. Os caracteres que aparecem pela primeira vez numa `TextShape` são processados em segundo plano, pelo que pode demorar um pouco até o novo texto ser apresentado.
* **O ficheiro da fonte pode ter, no máximo, 16 MB**, tanto no Desktop Client como na aplicação móvel. Os ficheiros maiores são rejeitados e é usada a fonte de reserva `font` . As fontes com contornos de glifos extremamente complexos também podem ser rejeitadas.
* **Caracteres**: No Desktop Client, os caracteres latinos (ASCII e Latin-1) são pré-processados. Os restantes caracteres incluídos na fonte, como os cirílicos ou chineses, são processados na primeira vez que aparecem na cena, o que pode causar uma breve interrupção. Os caracteres não incluídos na fonte são apresentados com a fonte sans-serif integrada.
* **Um ficheiro corresponde a um tipo de letra**. Um ficheiro `.ttf` contém um único peso e estilo. Para ter um título a negrito e texto normal no corpo, adicione ambos os ficheiros e associe cada texto ao respetivo ficheiro. Se indicar o nome de uma família do Google Fonts, o cliente transfere o tipo de letra a negrito por si. Use ficheiros de fontes estáticas: se uma família de fontes só estiver disponível como fonte variável, use as respetivas instâncias estáticas.
* **As fontes são partilhadas**: todas as entidades de texto que usam o mesmo `fontSrc` partilham uma única cópia da fonte, pelo que reutilizar uma fonte na cena não custa mais do que usá-la uma vez. Prefira um pequeno conjunto de fontes a muitas fontes diferentes: no Desktop Client, cada fonte tem a sua própria textura e acrescenta cerca de 700 KB à transferência otimizada, e a aplicação móvel carrega, no máximo, 16 por cena.

Quando o cliente para computador não consegue usar uma fonte personalizada, regista uma mensagem na categoria `SDK_FONTS` da consola, que indica o nome do ficheiro e o motivo. Por exemplo, `font_src "https://example.com/font.ttf" cannot be an external URL`, ou que o ficheiro não faz parte do conteúdo da cena, ou que ainda não existe uma versão convertida da fonte para essa cena. Estas mensagens estão ocultas por predefinição. Para as mostrar, escreva `/log-matrix enable SDK_FONTS Warning` e `/log-matrix enable SDK_FONTS Log` no chat, recarregue a cena com `/reload`, e depois abra a pasta de registos com `/logs`. Se a fonte não tiver sido convertida, confirme que o ficheiro é TrueType `.ttf` e tem menos de 16 MB; em seguida, publique novamente.

## Propriedades de alinhamento e espaçamento interno do texto

O `TextShape` cria uma caixa de texto com tamanho, espaçamento interno, etc.

* `textAlign`: Selecione um valor da enumeração `TextAlignMode`  . Os valores possíveis incluem todas as combinações entre o alinhamento vertical (*superior*, *ao centro*, *inferior*) e horizontal (*à esquerda*, *ao centro*, *à direita*).
* `width`: *número*. A largura da caixa de texto.
* `height`: *número*. A altura da caixa de texto.
* `paddingTop`: *número*. Espaço entre o texto e o contorno da caixa de texto.
* `paddingRight`: *número*. Espaço entre o texto e o contorno da caixa de texto.
* `paddingBottom`: *número*. Espaço entre o texto e o contorno da caixa de texto.
* `paddingLeft`: *número*. Espaço entre o texto e o contorno da caixa de texto.

{% hint style="info" %}
**💡 Dica**: Se pretender que o texto flutue no espaço, é boa ideia adicionar um componente [`Billboard` componente](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/entity-positioning.md#face-the-player) para que o texto rode e fique sempre virado para o jogador, sendo assim legível.
{% endhint %}

## Propriedades de sombra e contorno do texto

Por predefinição, o texto não tem sombra, mas pode definir os seguintes valores para lhe dar um efeito semelhante a uma sombra.

* `shadowBlur`: *número*
* `shadowOffsetX`: *número*
* `shadowOffsetY`: *número*
* `shadowColor`: *Color3* objeto. *Color3* Os objetos armazenam uma cor *RGB* como três números entre 0 e 1.

```ts
TextShape.create(sign, {
	text: 'Texto com sombra',
	shadowColor: { r: 1, g: 0, b: 0 },
	shadowOffsetY: 1,
	shadowOffsetX: -1,
})
```

As letras do texto também podem ter um contorno de outra cor à sua volta.

* `outlineWidth`: *number*. A largura do contorno do texto em todas as direções, como um número entre 0 e 1. Por predefinição *0*, o que o torna invisível.
* `outlineColor`: *Color3* object. *Color3* objects armazenam uma cor *RBG* como três números entre 0 e 1.

## Várias linhas

Se quiser que o texto ocupe várias linhas, use `\n` como parte da string. O exemplo seguinte tem duas linhas de texto distintas:

```ts
TextShape.create(sign, {
	text: 'Esta é uma linha. \nEsta é outra linha',
})
```

Também pode configurar as seguintes propriedades relacionadas com textos com várias linhas:

* `lineCount`: *number*. O número máximo de linhas de texto que cabem na caixa de texto. Se não for definido, não há limite para o número de linhas. A propriedade `textWrapping` tem de ser *true* para utilizar mais do que uma linha.
* `lineSpacing`: *number*. O espaço entre cada linha.

## Orientação do texto

Um `TextShape` é apresentado corretamente a partir do seu lado local **-Z** . Se criar um e não o rodar, os jogadores que estiverem no lado -Z da entidade conseguem lê-lo.

Assim, para identificar a face **+Z** de um modelo, coloque o texto como filho do modelo, desloque-o ligeiramente ao longo de **+Z** para que não fique dentro da malha e rode-o 180 graus em torno do eixo Y:

```ts
// Etiqueta fixada à face +Z de um modelo
import { engine, TextShape, Transform } from '@dcl/sdk/ecs'
import { Quaternion, Vector3 } from '@dcl/sdk/math'

const label = engine.addEntity()

Transform.create(label, {
	parent: myModel,
	// Um pequeno deslocamento em +Z mantém o texto afastado da superfície do modelo
	position: Vector3.create(0, 1, 0.01),
	rotation: Quaternion.fromEulerDegrees(0, 180, 0),
})

TextShape.create(label, { text: 'Front' })
```

{% hint style="info" %}
**💡 Dica**: Se o texto tiver de continuar legível de qualquer ponto onde o jogador esteja, adicione um [Billboard](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/entity-positioning.md#face-the-player) em vez de o rodar manualmente.
{% endhint %}

## Organizar texto em colunas

Os espaços e as tabulações não alinham as colunas nas fontes predefinidas, porque os caracteres têm larguras diferentes. Preencher um marcador de pontuação com espaços cria colunas desalinhadas, que mudam assim que o comprimento de um nome ou de um número se altera.

Para criar uma tabela, use um `TextShape` por coluna. Atribua uma entidade própria a cada coluna, posicione-a e coloque as linhas no campo `text` separadas por `\n`. Assim, cada linha fica à mesma altura em todas as colunas.

```ts
// Um marcador de pontuação com duas colunas: um TextShape para os nomes e outro para as pontuações
const board = engine.addEntity()
Transform.create(board, { position: Vector3.create(8, 2, 8) })

const names = engine.addEntity()
Transform.create(names, { parent: board, position: Vector3.create(-1, 0, 0) })
TextShape.create(names, {
	text: 'Ana\nBruno\nChiara',
	textAlign: TextAlignMode.TAM_MIDDLE_LEFT,
	fontSize: 2,
})

const scores = engine.addEntity()
Transform.create(scores, { parent: board, position: Vector3.create(1, 0, 0) })
TextShape.create(scores, {
	text: '120\n85\n9',
	textAlign: TextAlignMode.TAM_MIDDLE_RIGHT,
	fontSize: 2,
})
```

Alinhe cada coluna na direção do espaço entre elas: `TAM_MIDDLE_LEFT` para a coluna da esquerda, `TAM_MIDDLE_RIGHT` para a da direita. Os números ficam mais legíveis alinhados à direita, para que os algarismos fiquem alinhados.

Para atualizar uma linha, reescreva toda a cadeia de caracteres `text` de cada coluna. Mantenha o mesmo número de linhas em todas as colunas; caso contrário, as linhas deixam de ficar alinhadas.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/text.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
