BBCode in RichTextLabel¶

Einführung¶

Beschriftungs-Nodes eignen sich hervorragend für die Anzeige von einfachem Text, aber sie haben ihre Grenzen. Wenn Sie die Farbe des Textes oder seine Ausrichtung ändern möchten, wirkt sich diese Änderung auf den gesamten Text im Beschriftungs-Node aus. Sie können nicht nur einen Teil des Textes in einer Farbe darstellen oder nur einen Teil des Textes zentrieren. Um diese Einschränkung zu umgehen, würden Sie ein RichTextLabel verwenden.

RichTextLabel ermöglicht die Anzeige von komplexen Textauszeichnungen in einem Control. Es hat eine eingebaute API für die Erzeugung des Markups, kann aber auch einen BBCode parsen.

Beachten Sie, dass die BBCode-Tags in gewissem Umfang auch in der XML source of the class reference verwendet werden können.

BBCode verwenden¶

Für einheitlich formatierten Text können Sie in die Eigenschaft "Text" schreiben, aber wenn Sie BBCode-Markup verwenden möchten, sollten Sie stattdessen die Eigenschaft "Text" im Abschnitt "BBCode" verwenden (bbcode_text). Wenn Sie in diese Eigenschaft schreiben, wird das Markup analysiert, um den Text wie gewünscht zu formatieren. Bevor dies geschieht, müssen Sie das Kontrollkästchen "Aktiviert" im Abschnitt "BBCode" (bbcode_enabled) umschalten.

Zum Beispiel würde BBCode [color=blue]blau[/color] das Wort "blau" mit einer blauen Farbe rendern.

You'll notice that after writing in the BBCode "Text" property the regular "Text" property now has the text without the BBCode. While the text property will be updated by the BBCode property, you can't edit the text property or you'll lose the BBCode markup. All changes to the text must be done in the BBCode parameter.

Bemerkung

For BBCode tags such as [b] (bold), [i] (italics) or [code] to work, you must set up custom fonts for the RichTextLabel node first.

Es gibt noch keine BBCode-Tags zur Steuerung der vertikalen Zentrierung von Text.

Referenz¶

Befehl	Tag	Beschreibung
bold	`[b]{text}[/b]`	Macht {Text} fett.
italics	`[i]{text}[/i]`	Macht {text} kursiv.
underline	`[u]{text}[/u]`	Macht {text} unterstrichen.
strikethrough	`[s]{text}[/s]`	Macht {text} durchgestrichen.
code	`[code]{text}[/code]`	Lässt {text} die Code-Schriftart verwenden (normalerweise Monospace).
center	`[center]{text}[/center]`	zeigt {Text} horizontal zentriert.
right	`[right]{text}[/right]`	zeigt {text} horizontal rechtsbündig.
fill	`[fill]{text}[/fill]`	Lässt {Text} die Breite des RichTextLabels ausfüllen.
indent	`[indent]{text}[/indent]`	Erhöht die Einrückungsstufe von {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 Umgang mit [url]-Tag-Klicks.
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 Umgang mit [url]-Tag-Klicks.
image	`[img]{path}[/img]`	Bild an Ressource {Pfad} einfügen.
resized image	`[img=<width>]{path}[/img]`	Fügen Sie mit <width> ein Bild an der Ressource {path} ein (behält das Verhältnis bei).
resized image	`[img=<width>x<height>]{path}[/img]`	Bild an der Ressource {Pfad} mit <Breite>×<Höhe> einfügen.
font	`[font=<path>]{text}[/font]`	verwende eigenen Zeichensatz bei <Pfad> für {text}.
color	`[color=<code/name>]{text}[/color]`	Ändert {text} Farbe; verwende Name oder # Format, z.B. `#ff00ff`.
table	`[table=<number>]{cells}[/table]`	Erzeugt eine Tabelle mit <Anzahl> Spalten.
cell	`[cell]{text}[/cell]`	Fügt Zellen mit dem {text} zur Tabelle hinzu.

vorhandene Farbnamen¶

Liste der gültigen Farbnamen für den [color=<name>] Tag:

aqua
black
blue
fuchsia
gray
green
lime
maroon
navy
purple
red
silver
teal
white
yellow

Hexadezimale Farbcodes¶

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.

Umgang mit `[url]`-Tag-Klicks¶

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]

Vertikaler Bildversatz (Offset)¶

Verwenden Sie eine benutzerdefinierte Schriftart für Ihr Bild, um es vertikal auszurichten.

Erstellen einer BitmapFont Ressource
Set this bitmap font with a positive value for the ascent property, that's your height offset
Setzen Sie den BBCode-Tag wie folgt: [font=<font-path>][img]{image-path}[/img][/font]

Animationseffekte¶

BBCode can also be used to create different text animation effects. Five customizable effects are provided out of the box, and you can easily create your own.

Wellen¶

Wave makes the text go up and down. Its tag format is [wave amp=50 freq=2][/wave]. amp controls how high and low the effect goes, and freq controls how fast the text goes up and down.

Tornado¶

Tornao makes the text move around in a circle. Its tag format is [tornado radius=5 freq=2][/tornado]. radius is the radius of the circle that controls the offset, freq is how fast the text moves in a circle.

Schütteln¶

Shake makes the text shake. Its tag format is [shake rate=5 level=10][/shake]. rate controls how fast the text shakes, level controls how far the text is offset from the origin.

Ein- und Aus-Blenden¶

Fade creates a fade effect over the text that is not animated. Its tag format is [fade start=4 length=14][/fade]. start controls the starting position of the falloff relative to where the fade command is inserted, length controls over how many characters should the fade out take place.

Regenbogen¶

Rainbow gives the text a rainbow color that changes over time. Its tag format is [rainbow freq=0.2 sat=10 val=20][/rainbow]. freq is the number of full rainbow cycles per second, sat is the saturation of the rainbow, val is the value of the rainbow.

Eigene BBCode Tags und Texteffekte¶

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.

Warnung

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.

There is only one function that you need to extend: _process_custom_fx(char_fx). Optionally, you can also provide a custom BBCode identifier simply by adding a member name bbcode. The code will check the bbcode property automatically or will use the name of the file to determine what the BBCode tag should be.

`_process_custom_fx`¶

This is where the logic of each effect takes place and is called once per character during the draw phase of text rendering. This passes in a CharFXTransform object, which holds a few variables to control how the associated character is rendered:

identity specifies which custom effect is being processed. You should use that for code flow control.
relative_index tells you how far into a given custom effect block you are in as an index.
Der absolute_index sagt Ihnen als Index, wie weit Sie sich im gesamten Text befinden.
elapsed_time ist die Gesamtzeit, die der Texteffekt ausgeführt wurde.
visible will tell you whether the character is visible or not and will also allow you to hide a given portion of text.
offset ist eine versetzte Position relativ zu der Stelle, an der das angegebene Zeichen unter normalen Umständen gerendert werden soll.
color ist die Farbe eines bestimmten Zeichens.
Finally, env is a Dictionary of parameters assigned to a given custom effect. You can use get() with an optional default value to retrieve each parameter, if specified by the user. For example [custom_fx spread=0.5 color=#FFFF00]test[/custom_fx] would have a float spread and Color color parameters in its ` env` Dictionary. See below for more usage examples.

The last thing to note about this function is that it is necessary to return a boolean true value to verify that the effect processed correctly. This way, if there's a problem with rendering a given character, it will back out of rendering custom effects entirely until the user fixes whatever error cropped up in their custom effect logic.

Hier sind einige Beispiele eigener Effekte:

Geist¶

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

Pulse¶

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

Matrix¶

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

Dadurch werden einige neue BBCode-Befehle hinzugefügt, die wie folgt verwendet werden können:

[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]