godot-docs/tutorials/ui/bbcode_in_richtextlabel.rst

.. _doc_bbcode_in_richtextlabel:

BBCode in RichTextLabel
=======================

Introduction
------------

Label nodes are great for displaying basic text, but they have limits. If you want
to change the color of the text, or its alignment, that change affects all of the
text in the Label node. You can't have only one part of the text be one color, or
only one part of the text be centered. To get around this limitation you would use
a :ref:`class_RichTextLabel`.

:ref:`class_RichTextLabel` allows the display of complex text markup in a Control.
It has a built-in API for generating the markup, but can also parse a BBCode.

Note that the BBCode tags can also be used, to some extent, in the XML source of
the class reference. For more information, see
:ref:`doc_class_reference_writing_guidelines`.

Using BBCode
------------

For uniformly formatted text you can write in the "Text" property, but if you want
to use BBCode markup you should use the "Text" property in the "Bb Code" section
instead (``bbcode_text``). Writing to this property will trigger the parsing of your
markup to format the text as requested. Before this happens, you need to toggle the
"Enabled" checkbox in the "Bb Code" section (``bbcode_enabled``).

.. image:: img/bbcodeText.png

For example, ``BBCode [color=blue]blue[/color]`` would render the word "blue" with
a blue color.

.. image:: img/bbcodeDemo.png

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.

.. note::

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

    There are no BBCode tags to control vertical centering of text yet.

Reference
---------

+-----------------------+-----------------------------------------------------------+--------------------------------------------------------------------------+
| Command               | Tag                                                       | Description                                                              |
+-----------------------+-----------------------------------------------------------+--------------------------------------------------------------------------+
| **bold**              | ``[b]{text}[/b]``                                         | Makes {text} bold.                                                       |
+-----------------------+-----------------------------------------------------------+--------------------------------------------------------------------------+
| **italics**           | ``[i]{text}[/i]``                                         | Makes {text} italics.                                                    |
+-----------------------+-----------------------------------------------------------+--------------------------------------------------------------------------+
| **underline**         | ``[u]{text}[/u]``                                         | Makes {text} underline.                                                  |
+-----------------------+-----------------------------------------------------------+--------------------------------------------------------------------------+
| **strikethrough**     | ``[s]{text}[/s]``                                         | Makes {text} strikethrough.                                              |
+-----------------------+-----------------------------------------------------------+--------------------------------------------------------------------------+
| **code**              | ``[code]{text}[/code]``                                   | Makes {text} use the code font (which is typically monospace).           |
+-----------------------+-----------------------------------------------------------+--------------------------------------------------------------------------+
| **p**                 | ``[p {options}]{text}[/p]``                               | Adds new paragraph with {text}. See paragraph options for more info.     |
+-----------------------+-----------------------------------------------------------+--------------------------------------------------------------------------+
| **center**            | ``[center]{text}[/center]``                               | Makes {text} horizontally centered. Same as ``[p align=center]``.        |
+-----------------------+-----------------------------------------------------------+--------------------------------------------------------------------------+
| **left**              | ``[left]{text}[/left]``                                   | Makes {text} horizontally right-aligned. Same as ``[p align=left]``.     |
+-----------------------+-----------------------------------------------------------+--------------------------------------------------------------------------+
| **right**             | ``[right]{text}[/right]``                                 | Makes {text} horizontally right-aligned. Same as ``[p align=right]``.    |
+-----------------------+-----------------------------------------------------------+--------------------------------------------------------------------------+
| **fill**              | ``[fill]{text}[/fill]``                                   | Makes {text} fill the RichTextLabel's width. Same as ``[p align=fill]``. |
+-----------------------+-----------------------------------------------------------+--------------------------------------------------------------------------+
| **indent**            | ``[indent]{text}[/indent]``                               | Increase the indentation level of {text}.                                |
+-----------------------+-----------------------------------------------------------+--------------------------------------------------------------------------+
| **url**               | ``[url]{url}[/url]``                                      | Show {url} as such, underline it and make it clickable.                  |
+-----------------------+-----------------------------------------------------------+--------------------------------------------------------------------------+
| **url (ref)**         | ``[url=<url>]{text}[/url]``                               | Makes {text} reference <url> (underlined and clickable).                 |
+-----------------------+-----------------------------------------------------------+--------------------------------------------------------------------------+
| **image**             | ``[img]{path}[/img]``                                     | Insert image at resource {path}.                                         |
+-----------------------+-----------------------------------------------------------+--------------------------------------------------------------------------+
| **resized image**     | ``[img=<width>]{path}[/img]``                             | Insert image at resource {path} using <width> (keeps ratio).             |
+-----------------------+-----------------------------------------------------------+--------------------------------------------------------------------------+
| **resized image**     | ``[img=<width>x<height>]{path}[/img]``                    | Insert image at resource {path} using <width>×<height>.                  |
+-----------------------+-----------------------------------------------------------+--------------------------------------------------------------------------+
| **aligned image**     | ``[img align=<valign>]{path}[/img]``                      | Insert image at resource {path} using <valign> vertical alignment.       |
+-----------------------+-----------------------------------------------------------+--------------------------------------------------------------------------+
| **font**              | ``[font=<path>]{text}[/font]``                            | Use custom font at <path> for {text}.                                    |
+-----------------------+-----------------------------------------------------------+--------------------------------------------------------------------------+
| **font options**      | ``[font {options}]{text}[/font]``                         | Use custom font options for the {text}. See font options for more info.  |
+-----------------------+-----------------------------------------------------------+--------------------------------------------------------------------------+
| **font size**         | ``[font_size=nn]{text}[/font_size]``                      | Use custom font size for {text}.                                         |
+-----------------------+-----------------------------------------------------------+--------------------------------------------------------------------------+
| **opentype features** | ``[opentype_features=ftr,ftr]{text}[/opentype_features]`` | Use custom OpenType font features (comma separated list) for {text}.     |
+-----------------------+-----------------------------------------------------------+--------------------------------------------------------------------------+
| **outline size**      | ``[outline_size=<size>]{text}[/outline_size]``            | Use custom font outline size for {text}.                                 |
+-----------------------+-----------------------------------------------------------+--------------------------------------------------------------------------+
| **outline color**     | ``[outline_color=<color>]{text}[/outline_color]``         | Use custom outline color for {text}.                                     |
+-----------------------+-----------------------------------------------------------+--------------------------------------------------------------------------+
| **color**             | ``[color=<code/name>]{text}[/color]``                     | Change {text} color; use name or # format, such as ``#ff00ff``.          |
+-----------------------+-----------------------------------------------------------+--------------------------------------------------------------------------+
| **table**             | ``[table=<number>]{cells}[/table]``                       | Creates a table with <number> of columns.                                |
+-----------------------+-----------------------------------------------------------+--------------------------------------------------------------------------+
| **cell**              | ``[cell=<expand ratio>]{text}[/cell]``                    | Adds cells with the {text} to the table.                                 |
+-----------------------+-----------------------------------------------------------+--------------------------------------------------------------------------+
| **cell**              | ``[cell {options}]{text}[/cell]``                         | Adds cells with the {text} to the table. See cell options for more info. |
+-----------------------+-----------------------------------------------------------+--------------------------------------------------------------------------+
| **list**              | ``[ul]{one item per line}[/ul]``                          | Add unnumbered list.                                                     |
+-----------------------+-----------------------------------------------------------+--------------------------------------------------------------------------+
| **list**              | ``[ol type=<type>]{one item per line}[/ol]``              | Add numbered list. See list types for more info.                         |
+-----------------------+-----------------------------------------------------------+--------------------------------------------------------------------------+
| **unicode control**   | ``[lrm]``, ``[rlm]``, ``[lre]``, ``[rle]``, ``[lro]``,    | Adds Unicode control character.                                          |
|                       | ``[rlo]``, ``[pdf]``, ``[alm]``, ``[lri]``, ``[rli]``,    |                                                                          |
|                       | ``[fsi]``, ``[pdi]``, ``[zwj]``, ``[zwnj]``, ``[wj]``     |                                                                          |
+-----------------------+-----------------------------------------------------------+--------------------------------------------------------------------------+

Note: Options are optional for all tags.

Paragraph options
~~~~~~~~~~~~~~~~~

+----------------------------+---------------------------------------------------------------------------+----------------------------+
| Option                     | Supported Values                                                          | Description                |
+----------------------------+---------------------------------------------------------------------------+----------------------------+
| ``align``                  | ``left``, ``center``, ``right``, ``fill``                                 | Text horizontal alignment. |
+----------------------------+---------------------------------------------------------------------------+----------------------------+
| ``direction`` or ``dir``   | ``ltr``, ``rtl``, ``auto``                                                | Base BiDi direction.       |
+----------------------------+---------------------------------------------------------------------------+----------------------------+
| ``language`` or ``lang``   | ISO language codes                                                        | Locale override.           |
+----------------------------+---------------------------------------------------------------------------+----------------------------+
| ``bidi_override`` or `st`  | ``default``, ``uri``, ``file``, ``email``, ``list``, ``none``, ``custom`` | Structured text override.  |
+----------------------------+---------------------------------------------------------------------------+----------------------------+


Font options
~~~~~~~~~~~~

+----------------------------+-------------------------------------------------+
| Option                     | Description                                     |
+----------------------------+-------------------------------------------------+
| ``name`` or ``n``          | Font resource path.                             |
+----------------------------+-------------------------------------------------+
| ``size`` or ``s``          | Font size.                                      |
+----------------------------+-------------------------------------------------+

Cell options
~~~~~~~~~~~~

-  ``expand`` - Column expansion ratio, the column expands in proportion to its expansion ratio versus the other columns' ratios.
-  ``border`` -  Sets cell border color.
-  ``bg`` - Sets cell background color, for alternating odd/even row backgrounds use ``bg=odd_color,even_color``.

List types
~~~~~~~~~~

Supported list types:

-  ``1`` - Numbers, using language specific numbering system if possible.
-  ``a`` and ``A`` - Lower and upper case Latin letters.
-  ``i`` and ``I`` - Lower and upper case Roman numerals.

Named colors
~~~~~~~~~~~~

You can use the constants of the :ref:`class_Color` class for the ``[color=<name>]`` tag.
The case and style of the name is not important: ``DARK_RED``, ``DarkRed`` and ``darkred`` will give the same result.

Hexadecimal color codes
~~~~~~~~~~~~~~~~~~~~~~~

For opaque RGB colors, any valid 6-digit hexadecimal code is supported, e.g. ``[color=#ffffff]white[/color]``.

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.

Image vertical offset
~~~~~~~~~~~~~~~~~~~~~

Use ``[img=align]...[/img]`` to set vertical alignment of the image, where ``align`` is ``t`` (top), ``c`` (center) or ``b`` (bottom).

Animation effects
-----------------

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.

Wave
~~~~

.. image:: img/wave.png

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
~~~~~~~

.. image:: img/tornado.png

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.

Shake
~~~~~

.. image:: img/shake.png

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.

Fade
~~~~

.. image:: img/fade.png

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.

Rainbow
~~~~~~~

.. image:: img/rainbow.png

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.

Custom BBCode tags and text effects
-----------------------------------

You can extend the :ref:`class_RichTextEffect` resource type to create your own custom
BBCode tags. You begin by extending the :ref:`class_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.

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 glyph
during the draw phase of text rendering. This passes in a :ref:`class_CharFXTransform`
object, which holds a few variables to control how the associated glyph is rendered:

- ``identity`` specifies which custom effect is being processed. You should use that for
  code flow control.
- ``outline`` is ``true`` if effect is called for drawing text outline.
- ``range`` tells you how far into a given custom effect block you are in as an
  index.
- ``elapsed_time`` is the total amount of time the text effect has been running.
- ``visible`` will tell you whether the glyph is visible or not and will also allow you
  to hide a given portion of text.
- ``offset`` is an offset position relative to where the given glyph should render under
  normal circumstances.
- ``color`` is the color of a given glyph.
- ``glyph_index`` and ``font`` is glyph being drawn and font data resource used to draw it.
- Finally, ``env`` is a :ref:`class_Dictionary` of parameters assigned to a given custom
  effect. You can use :ref:`get() <class_Dictionary_method_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 glyph, it will back out of rendering custom effects entirely until
the user fixes whatever error cropped up in their custom effect logic.

Here are some examples of custom effects:

Ghost
~~~~~

::

    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 matrix_time = fmod(char_fx.elapsed_time + (char_fx.range.x / float(text_span)), \
                               clear_time + dirty_time)

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

        if matrix_time > 0.0:
            value = int(1 * matrix_time * (126 - 65))
            value %= (126 - 65)
            value += 65
        char_fx.glyph_index = TextServer.font_get_glyph_index(char_fx.font, value)
        return true

This will add a few new BBCode commands, which can be used like so:

::

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