BBCode en RichTextLabel¶

Introducción¶

Los nodos de la etiqueta son geniales para mostrar el texto básico, pero tienen límites. Si quieres cambiar el color del texto, o su alineación, ese cambio afecta a todo el texto del nodo Label. No puedes hacer que sólo una parte del texto sea de un color, o que sólo una parte del texto esté centrada. Para sortear esta limitación usarías un RichTextLabel.

RichTextLabel permite la visualización de marcas de texto complejas en un Control. Tiene una API incorporada para generar el marcado, pero también puede analizar un BBCode.

Nótese que las etiquetas de BBCode también pueden ser usadas, hasta cierto punto, en el XML source of the class reference.

Usando BBCode¶

Para un texto con formato uniforme se puede escribir en la propiedad "Text", pero si se desea utilizar el marcado BBCode se debe utilizar la propiedad "Text" en la sección "Bb Code" (bbcode_text). Al escribir en esta propiedad se activará el análisis sintáctico de su marcado para dar formato al texto según lo solicitado. Antes de que esto ocurra, necesita activar la casilla de verificación "Enabled" en la sección "Bb Code" (bbcode_enabled).

Por ejemplo, "BBCode [color=blue]blue[/color]`` haría que la palabra "blue" tuviera un color azul.

Notarán que después de escribir en la propiedad "Texto" del BBCode, la propiedad "Texto" normal ahora tiene el texto sin el BBCode. Mientras que la propiedad "Text" será actualizada por la propiedad BBCode, no puedes editar la propiedad texto o perderás el marcado BBCode. Todos los cambios en el texto deben hacerse en el parámetro BBCode.

Nota

Para que las etiquetas BBCode como [b] (negrita), [i] (cursiva) o [código] funcionen, debes configurar primero las fuentes personalizadas para el nodo RichTextLabel.

Todavía no hay etiquetas BBCode para controlar el centrado vertical del texto.

Referencia¶

Comando	Etiqueta	Descripción
negrita	`[b]{text}[/b]`	Hace {text} más oscuro.
cursiva	`[i]{text}[/i]`	Hace {text) cursiva.
Subrayado	`[u]{text}[/u]`	Subraya el {text}.
tachado	`[s]{text}[/s]`	Tachar el {text).
codigo	`[code]{text}[/code]`	Hace que {text} utilice la fuente del código (que es típicamente monoespacio).
centrado	`[center]{text}[/center]`	Centra horizontalmente el {text}.
derecho	`[right]{text}[/right]`	Centra horizontalmente al {text} a la derecha.
llenar	`[fill]{text}[/fill]`	Hace que el {text} se expanda a lo ancho del RchTextLabel.
indentar	`[indent]{text}[/indent]`	Aumentar el nivel de indentación del {text}.
url	`[url]{url}[/url]`	Show {url} as such, underline it and make it clickable. Must be handled with the "meta_clicked" signal to have an effect. See Handling [url] tag clicks.
url (ref)	`[url=<url>]{text}[/url]`	Makes {text} reference <url> (underlined and clickable). Must be handled with the "meta_clicked" signal to have an effect. See Handling [url] tag clicks.
imagen	`[img]{path}[/img]`	Inserte la imagen en el recurso {path}.
imagen redimensionada	`[img=<width>]{path}[/img]`	Insertar la imagen en el recurso {path} usando <width> (mantiene la proporción).
imagen redimensionada	`[img=<ancho>x<altura>]{path}[/img]`	Insertar la imagen en el recurso {path} usando <ancho>×<alto>.
fuente	`[font=<path>]{texto}[/font]`	Usa la fuente personalizada en <path> para {text}.
color	`[color=<code/name>]{text}[/color]`	Cambia el color del {text}; usa el nombre o el formato #, como `#ff00ff`.
tabla	`[table=<number>]]{cells}[/table]`	Crea una tabla con un <number> de columnas.
celda	`[cell]{text}[/cell]`	Añade celdas con el {texto} a la tabla.

Nombres de colores incorporados¶

Lista de nombres de colores válidos para la etiqueta [color=<nombre>]:

agua
negro
azul
fucsia
gris
verde
lima
granate
azul marino
violeta
red
plata
verde azulado
Blanco
Amarillo

Códigos Hexadecimales de color¶

For opaque RGB colors, any valid 6-digit hexadecimal code is supported, e.g. [color=#ffffff]white[/color]. Short RGB color codes such as #6f2 (equivalent to #66ff22) are also supported.

For transparent RGB colors, any 8-digit hexadecimal code can be used, e.g. [color=#88ffffff]translucent white[/color]. In this case, note that the alpha channel is the first component of the color code, not the last one. Short RGBA color codes such as #86f2 (equivalent to #8866ff22) are also supported.

Handling `[url]` tag clicks¶

By default, [url] tags do nothing when clicked. This is to allow flexible use of [url] tags rather than limiting them to opening URLs in a web browser.

To handle clicked [url] tags, connect the RichTextLabel node's meta_clicked signal to a script function.

For example, the following method can be connected to meta_clicked to open clicked URLs using the user's default web browser:

# This assumes RichTextLabel's `meta_clicked` signal was connected to
# the function below using the signal connection dialog.
func _richtextlabel_on_meta_clicked(meta):
    # `meta` is not guaranteed to be a String, so convert it to a String
    # to avoid script errors at run-time.
    OS.shell_open(str(meta))

For more advanced use cases, it's also possible to store JSON in an [url] tag's option and parse it in the function that handles the meta_clicked signal. For example: [url={"example": "value"}]JSON[/url]

Desplazamiento vertical de la imagen¶

Utilizas una fuente personalizada para tu imagen para alinearla verticalmente.

Crear un recurso BitmapFont
Ponga esta fuente de mapa de bits con un valor positivo para la propiedad ascent, que es su desplazamiento de altura
Ponga la etiqueta BBCode de esta manera: [font=<font-path>][img]{image-path}[/img][/font]

Efectos de animación¶

BBCode también puede ser usado para crear diferentes efectos de animación de texto. Se proporcionan cinco efectos personalizables fuera de la caja, y puedes crear fácilmente los tuyos propios.

Ola¶

La onda hace que el texto suba y baje. Su formato de etiqueta es [wave amp=50 freq=2][/wave]. amp controla cuán alto y bajo va el efecto, y freq controla cuán rápido el texto sube y baja.

Tornado¶

El tornado hace que el texto se mueva en un círculo. Su formato de etiqueta es [tornado radius=5 freq=2][/tornado]. radius es el radio del círculo que controla el desplazamiento, freq es la velocidad con la que el texto se mueve en un círculo.

Agitado¶

Agitar hace que el texto tiemble. Su formato de etiqueta es [Shake rate=5 level=10][/shake]. rate controla la rapidez con que el texto se agita, level controla la distancia del texto desde el origen.

Desaparecer¶

El fundido crea un efecto de desvanecimiento sobre el texto que no está animado. Su formato de etiqueta es [fade start=4 length=14][/fade]. start controla la posición inicial de la caída relativa a donde se inserta el comando fade, length controla sobre cuántos caracteres debe tener lugar el desvanecimiento.

Arcoiris¶

El arcoiris le da al texto un color de arco iris que cambia con el tiempo. Su formato de etiqueta es [rainbow freq=0.2 sat=10 val=20][/rainbow]. "freq" es el número de ciclos completos del arcoiris por segundo, "sat" es la saturación del arcoiris, "val" es el valor del arcoiris.

Etiquetas BBCode personalizadas y efectos de texto¶

You can extend the RichTextEffect resource type to create your own custom BBCode tags. You begin by extending the RichTextEffect resource type. Add the tool prefix to your GDScript file if you wish to have these custom effects run within the editor itself. The RichTextLabel does not need to have a script attached, nor does it need to be running in tool mode. The new effect will be activable in the Inspector through the Custom Effects property.

Advertencia

If the custom effect is not registered within the RichTextLabel's Custom Effects property, no effect will be visible and the original tag will be left as-is.

Sólo hay una función que necesita extenderse: _process_custom_fx(char_fx). Opcionalmente, también puede proporcionar un identificador personalizado de BBCode simplemente añadiendo un nombre de miembro bbcode. El código comprobará la propiedad bbcode automáticamente o utilizará el nombre del archivo para determinar cuál debe ser la etiqueta BBCode.

`_process_custom_fx`¶

Aquí es donde la lógica de cada efecto tiene lugar y se llama una vez por carácter durante la fase de dibujo de la representación del texto. Esto pasa en un objeto CharFXTransform, que contiene unas pocas variables para controlar cómo se renderiza el carácter asociado:

identity especifica qué efecto personalizado se está procesando. Deberías usar eso para el control del flujo de códigos.
relative_index te dice cuán lejos estás en un bloque de efectos personalizados como índice.
absolute_index te dice dónde estás en el texto completo como un índice absoluto.
elapsed_time es la cantidad total de tiempo que el efecto de texto ha estado funcionando.
visible te dirá si el personaje es visible o no y también te permitirá ocultar una parte determinada del texto.
offset es una posición de desplazamiento relativa a donde el carácter dado debe presentarse en circunstancias normales.
El color es el color de un personaje determinado.
Por último, env es un Dictionary de parámetros asignados a un efecto personalizado dado. Puede utilizar get() con un valor predeterminado opcional para recuperar cada parámetro, si así lo especifica el usuario. Por ejemplo [custom_fx spread=0.5 color=#FFFF00]test[/custom_fx] tendría un parámetro real spread y de color color en su diccionario env. Vea abajo para más ejemplos de uso.

Lo último que hay que señalar de esta función es que es necesario devolver un valor booleano true para verificar que el efecto se procesó correctamente. De esta manera, si hay un problema con la renderización de un carácter dado, se retirará por completo de la renderización de los efectos personalizados hasta que el usuario arregle cualquier error surgido en su lógica de efectos personalizados.

Aquí hay unos ejemplos de efectos personalizados:

Fantasma¶

tool
extends RichTextEffect
class_name RichTextGhost

# Syntax: [ghost freq=5.0 span=10.0][/ghost]

# Define the tag name.
var bbcode = "ghost"

func _process_custom_fx(char_fx):
    # Get parameters, or use the provided default value if missing.
    var speed = char_fx.env.get("freq", 5.0)
    var span = char_fx.env.get("span", 10.0)

    var alpha = sin(char_fx.elapsed_time * speed + (char_fx.absolute_index / span)) * 0.5 + 0.5
    char_fx.color.a = alpha
    return true

Pulso¶

tool
extends RichTextEffect
class_name RichTextPulse

# Syntax: [pulse color=#00FFAA height=0.0 freq=2.0][/pulse]

# Define the tag name.
var bbcode = "pulse"

func _process_custom_fx(char_fx):
    # Get parameters, or use the provided default value if missing.
    var color = char_fx.env.get("color", char_fx.color)
    var height = char_fx.env.get("height", 0.0)
    var freq = char_fx.env.get("freq", 2.0)

    var sined_time = (sin(char_fx.elapsed_time * freq) + 1.0) / 2.0
    var y_off = sined_time * height
    color.a = 1.0
    char_fx.color = char_fx.color.linear_interpolate(color, sined_time)
    char_fx.offset = Vector2(0, -1) * y_off
    return true

Matriz¶

tool
extends RichTextEffect
class_name RichTextMatrix

# Syntax: [matrix clean=2.0 dirty=1.0 span=50][/matrix]

# Define the tag name.
var bbcode = "matrix"

func _process_custom_fx(char_fx):
    # Get parameters, or use the provided default value if missing.
    var clear_time = char_fx.env.get("clean", 2.0)
    var dirty_time = char_fx.env.get("dirty", 1.0)
    var text_span = char_fx.env.get("span", 50)

    var value = char_fx.character

    var matrix_time = fmod(char_fx.elapsed_time + (char_fx.absolute_index / float(text_span)), \
                           clear_time + dirty_time)

    matrix_time = 0.0 if matrix_time < clear_time else \
                  (matrix_time - clear_time) / dirty_time

    if value >= 65 && value < 126 && matrix_time > 0.0:
        value -= 65
        value = value + int(1 * matrix_time * (126 - 65))
        value %= (126 - 65)
        value += 65
    char_fx.character = value
    return true

Esto agregará unos nuevos comandos BBCode que pueden ser usados de este modo:

[center][ghost]This is a custom [matrix]effect[/matrix][/ghost] made in
[pulse freq=5.0 height=2.0][pulse color=#00FFAA freq=2.0]GDScript[/pulse][/pulse].[/center]