> 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-es/scenes-sdk7/fundamentos-del-contenido-3d/text.md). # Texto Cómo añadir texto a tu escena Añade texto a una escena usando el `TextShape` componente. Este texto se sitúa en una posición El texto en Decentraland admite todos los *utf8* caracteres; esto incluye caracteres orientales y especiales. {% hint style="warning" %} **📔 Nota**: Este componente es útil para etiquetas y UIs dentro del mundo que existen en el espacio 3D de la escena, no para la UI HUD 2D del jugador. {% endhint %} Para añadir texto como etiqueta en una Entity existente, una buena práctica es crear una segunda Entity que tenga el `TextShape` componente y establecerla como hija de la otra Entity. ## Usa el Scene Editor en Creator Hub La forma más sencilla de colocar texto dentro del mundo es añadir un **Text** [Smart item](/creator/content-creator-es/scene-editor/interactividad/smart-items.md) visualmente en el Scene Editor. Luego puedes configurar todos los campos disponibles en la UI del Scene Editor. ![](https://1216664193-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-e555db49c09743be8685fc9f249cfd2ab00480f0%2Ftext-smart-item.png?alt=media\&token=d9ebef2a-4c56-4439-a5c1-c67792aa6f78) ## Crear un componente de texto El siguiente ejemplo muestra cómo crear un `TextShape` componente y añadirlo a una Entity mediante 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**: Si la Entity con el componente de texto es hija de otra Entity, entonces se verá afectada por la escala del padre. Si el padre se escala de forma desigual a lo largo de su eje, esto hará que el texto también se estire o se comprima. {% endhint %} {% hint style="warning" %} **📔 Nota**: `TextShape` los componentes no son clicables. `PointerEvents` los componentes no se activan cuando se usan en entidades que tienen un `TextShape` componente. {% endhint %} {% hint style="warning" %} **📔 Nota**: `TextShape` debe importarse mediante > `import { TextShape } from "@dcl/sdk/ecs"` Consulta [Imports](/creator/content-creator-es/scenes-sdk7/primeros-pasos/coding-scenes.md#imports) para ver cómo manejarlos fácilmente. {% endhint %} ## Cambiar el valor del texto Al crear un nuevo componente de texto, le asignas una cadena que mostrar. Esta cadena se almacena en el `text` campo. Si quieres cambiar la cadena mostrada por el componente, puedes hacerlo en cualquier momento cambiando el `text` campo en una [versión mutable](/creator/content-creator-es/scenes-sdk7/patrones-de-programacion/mutable-data.md) del componente. ```ts const mutableText = TextShape.getMutable(myEntity) mutableText.text = 'new string' ``` ## Propiedades básicas del texto El `TextShape` componente tiene varias propiedades que se pueden configurar para estilizar el texto. A continuación se muestran algunas de las más comunes: * `font`: Valor del enum `Font`. * `fontSrc`: *string*. Ruta a un `.ttf` archivo de fuente en tu escena, para renderizar el texto con una fuente personalizada. Consulta [Fuentes personalizadas](#custom-fonts). * `fontSize`: *number*. Una Entity con tamaño de fuente 10 mide 1 metro de alto. * `textColor`: *Color4* objeto. *Color4* los objetos almacenan un *RGB* color como tres números de 0 a 1, más *alpha* para la transparencia. Consulta [tipos de color](/creator/content-creator-es/scenes-sdk7/fundamentos-del-contenido-3d/color-types.md) para más detalles. ```ts TextShape.create(sign, { text: 'Hello World', textColor: { r: 1, g: 0, b: 0, a: 1 }, fontSize: 5, font: Font.F_SANS_SERIF, }) ``` ## Fuentes Las TextShape pueden usar fuentes del enum `Font`. Actualmente, este enum incluye las siguientes fuentes: * `Font.F_SANS_SERIF` * `Font.F_SERIF` * `Font.F_MONOSPACE` Por defecto 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="warning" %} **📔 Nota**: Actualmente, todas las fuentes se renderizan como Sans Serif. Es un problema conocido que se corregirá en el futuro. {% endhint %} {% hint style="info" %} **💡 Consejo**: Si usas VS Studio u otro IDE, escribe `Font.` y deberías ver una lista de sugerencias con todas las fuentes disponibles. {% endhint %} ### Fuentes personalizadas Para renderizar texto con tu propia fuente, añade un archivo de fuente TrueType (`.ttf`) a la carpeta de tu escena y configura la `fontSrc` propiedad con su ruta, relativa a la carpeta raíz de la escena (igual que el `src` de un `GltfContainer`). Mantén `font` también configurado: es el respaldo que se usa siempre que la fuente personalizada no pueda cargarse. ```ts TextShape.create(sign, { text: 'Hello World', fontSize: 5, fontSrc: 'assets/fonts/Lobster-Regular.ttf', font: Font.F_SANS_SERIF, }) ``` La misma `fontSrc` propiedad existe en los `Label`, `Button`, `Input` y `Dropdown` Entities, y en la `uiText` de un `UiEntity`. Consulta [Fuentes personalizadas en la UI](/creator/content-creator-es/scenes-sdk7/ui-2d/ui_text.md#custom-fonts). Ten en cuenta lo siguiente al usar fuentes personalizadas: * **Solo `.ttf` se admiten archivos**. El archivo debe ser una fuente TrueType. Las fuentes OpenType con contornos CFF (normalmente `.otf`), colecciones de fuentes (`.ttc`) y fuentes web (`.woff`, `.woff2`) se rechazan, y el texto se renderiza con el respaldo `font`. * **La fuente debe ser un archivo en tu escena**. `fontSrc` no puede apuntar a una URL externa, y los nombres de familia de fuentes (por ejemplo, de Google Fonts) tampoco son compatibles. Descarga el `.ttf` archivo, inclúyelo en la carpeta de tu escena y referencia su ruta. Asegúrate de que la licencia de la fuente permita redistribuirla; la mayoría de las fuentes de Google Fonts usan la licencia SIL Open Font License, que sí lo permite. * **En el Desktop Client, las fuentes personalizadas solo aparecen una vez que los assets de la escena se optimizan**. Cuando publicas una escena, sus fuentes se convierten en asset bundles optimizados junto con sus modelos 3D, y la fuente personalizada aparece una vez que esa conversión termina. Hasta entonces, el texto usa el respaldo `font`. Las escenas publicadas antes de que se admitieran las fuentes personalizadas solo convierten sus fuentes cuando se vuelven a publicar. Lo mismo aplica a las previews locales: la fuente personalizada solo se muestra al previsualizar con assets optimizados (la **Compress Assets** opción en Creator Hub, o `npm run start -- --asset-bundles` desde la CLI). Consulta [Previsualizar con assets optimizados](/creator/content-creator-es/scenes-sdk7/primeros-pasos/preview-scene.md#preview-with-optimized-assets). El cliente web de Bevy carga el `.ttf` archivo directamente, así que allí la fuente personalizada se muestra de inmediato, también en las previews locales. * **No compatible en mobile**. La app móvil de Decentraland ignora `fontSrc` y renderiza el respaldo `font`. Elige un respaldo que siga viéndose bien y no dependas de la fuente personalizada para hacer que el texto encaje en un espacio fijo. Consulta [Funciones faltantes en mobile](/creator/content-creator-es/desarrollar-para-movil/cliente-movil/missing-features.md). * **El archivo de fuente puede tener como máximo 16 MB**. Los archivos más grandes se rechazan y se usa el respaldo `font` se usa. Las fuentes con contornos de glifos extremadamente complejos también pueden rechazarse. * **Caracteres**: Los caracteres latinos (ASCII y Latin-1) se prerenderizan. Cualquier otro carácter que incluya la fuente, como cirílico o chino, se renderiza la primera vez que aparece en la escena, lo que puede causar una breve pausa. Los caracteres que la fuente no incluye se dibujan con la fuente sans-serif integrada. * **Las fuentes se comparten**: todos los TextShape que usan la misma `fontSrc` comparten una sola copia de la fuente, así que reutilizar una fuente en toda la escena no cuesta más que usarla una vez. Es preferible usar unas pocas fuentes en lugar de muchas distintas, ya que cada fuente tiene su propia textura. Cada archivo de fuente añade una descarga optimizada de unos 700 KB. Cuando el cliente de escritorio no puede usar una fuente personalizada, registra un mensaje en la console indicando que se está usando la fuente de respaldo, sin dar una razón. Si lo ves, comprueba que el archivo sea una TrueType `.ttf` de menos de 16 MB y luego vuelve a publicar. ## Propiedades de alineación y padding del texto El `TextShape` El componente crea una caja de texto que tiene tamaño, padding, etc. * `textAlign`: Selecciona un valor del `TextAlignMode` enum. Los valores posibles incluyen todas las combinaciones entre alineación vertical (*top*, *middle*, *bottom*) y horizontal (*left*, *center*, *right*). * `width`: *number*. El ancho de la caja de texto. * `height`: *number*. La altura de la caja de texto. * `paddingTop`: *number*. Espacio entre el texto y el contorno de la caja de texto. * `paddingRight`: *number*. Espacio entre el texto y el contorno de la caja de texto. * `paddingBottom`: *number*. Espacio entre el texto y el contorno de la caja de texto. * `paddingLeft`: *number*. Espacio entre el texto y el contorno de la caja de texto. {% hint style="info" %} **💡 Consejo**: Si se quiere que un texto flote en el espacio, es buena idea añadir un [`Billboard` componente](/creator/content-creator-es/scenes-sdk7/fundamentos-del-contenido-3d/entity-positioning.md#face-the-user) para que el texto rote y mire siempre al jugador, y sea legible. {% endhint %} ## Propiedades de sombra y contorno del texto El texto no tiene sombra por defecto, pero puedes establecer los siguientes valores para darle un efecto similar a una sombra. * `shadowBlur`: *number* * `shadowOffsetX`: *number* * `shadowOffsetY`: *number* * `shadowColor`: *Color3* objeto. *Color3* los objetos almacenan un *RGB* color como tres números de 0 a 1. ```ts TextShape.create(sign, { text: 'Texto con sombra', shadowColor: { r: 1, g: 0, b: 0 }, shadowOffsetY: 1, shadowOffsetX: -1, }) ``` Las letras del texto también pueden tener un contorno de otro color rodeando su perímetro. * `outlineWidth`: *number*. Qué ancho tendrá el contorno del texto en todas las direcciones, como un número de 0 a 1. Por defecto *0*, lo que lo hace invisible. * `outlineColor`: *Color3* objeto. *Color3* los objetos almacenan un *RGB* color como tres números de 0 a 1. ## Varias líneas Si quieres que tu texto abarque varias líneas, usa `\n` como parte de la cadena. El siguiente ejemplo tiene dos líneas de texto separadas: ```ts TextShape.create(sign, { text: 'Esta es una línea. \nEsta es otra línea', }) ``` También puedes configurar las siguientes propiedades relacionadas con textos de varias líneas: * `lineCount`: *number*. Cuántas líneas de texto caben como máximo en el cuadro de texto. Si no se establece, no hay límite en el número de líneas. La `textWrapping` propiedad debe ser *true* para usar más de una línea. * `lineSpacing`: *number*. Cuánto espacio hay entre cada línea. ## Distribuir texto en columnas Los espacios y las tabulaciones no alinean las columnas en una `TextShape`, ni siquiera con `Font.F_MONOSPACE`. Rellenar una tabla de puntuaciones con espacios produce columnas desalineadas que se desplazan en cuanto un nombre o un número cambia de longitud. Para construir una tabla, usa un `TextShape` por columna. Dale a cada columna su propia Entity, posiciónala y coloca las filas en su `text` campo separadas por `\n`. Entonces cada fila queda a la misma altura en todas las columnas. ```ts // Una tabla de puntuaciones de dos columnas: un TextShape para los nombres, uno para las puntuaciones 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, }) ``` Alinea cada columna hacia el espacio entre las columnas: `TAM_MIDDLE_LEFT` para la columna izquierda, `TAM_MIDDLE_RIGHT` para la de la derecha. Los números se leen mejor alineados a la derecha, así sus dígitos quedan alineados. Para actualizar una fila, reescribe toda la `text` cadena de cada columna. Mantén el mismo número de líneas en cada columna; de lo contrario, las filas dejan de coincidir. --- # 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-es/scenes-sdk7/fundamentos-del-contenido-3d/text.md?ask=&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.