bbcode_in_richtextlabel.rst 23 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691
  1. .. _doc_bbcode_in_richtextlabel:
  2. BBCode in RichTextLabel
  3. =======================
  4. Introduction
  5. ------------
  6. :ref:`class_Label` nodes are great for displaying basic text, but they have limitations.
  7. If you want to change the color of the text, or its alignment, you can only do that to
  8. the entire label. You can't make a part of the text have another color, or have a part
  9. of the text centered. To get around these limitations you would use a :ref:`class_RichTextLabel`.
  10. :ref:`class_RichTextLabel` allows for complex formatting of text using a markup syntax or
  11. the built-in API. It uses BBCodes for the markup syntax, a system of tags that designate
  12. formatting rules for a part of the text. You may be familiar with them if you ever used
  13. forums (also known as `bulletin boards`, hence the "BB" in "BBCode").
  14. Note that the BBCode tags can also be used, to some extent, in the XML source of
  15. the class reference. For more information, see :ref:`doc_class_reference_writing_guidelines`.
  16. Using BBCode
  17. ------------
  18. By default :ref:`class_RichTextLabel` functions exactly the same as the normal label. It
  19. has the :ref:`property_text <class_RichTextLabel_property_text>` property, which you can
  20. edit to have uniformly formatted text. To be able to use BBCodes and rich text formatting
  21. you need to turn on the BBCode mode by setting :ref:`bbcode_enabled <class_RichTextLabel_property_bbcode_enabled>`.
  22. After that you can edit the :ref:`bbcode_text <class_RichTextLabel_property_bbcode_text>`
  23. property using available tags. Both properties are located in the "Bb Code" section of
  24. the Inspector.
  25. .. image:: img/bbcodeText.png
  26. For example, ``BBCode [color=blue]blue[/color]`` would render the word "blue" with
  27. a blue color.
  28. .. image:: img/bbcodeDemo.png
  29. Most BBCodes consist of 3 parts: the opening tag, the content and the closing tag. The
  30. opening tag delimits the start of the formatted part, and can also carry some
  31. configuration options. Some opening tags, like the ``color`` one shown above, also require
  32. a value to work. The closing tag delimits the end of the formatted part. In some cases
  33. both the closing tag and the content can be omitted.
  34. .. code-block:: none
  35. [tag]content[/tag]
  36. [tag=value]content[/tag]
  37. [tag options]content[/tag]
  38. [tag][/tag]
  39. [tag]
  40. .. note::
  41. In the Inspector you may notice that after writing in the "BBCode Text" property the
  42. regular "Text" property now has the same text but without BBCodes. Take care not to
  43. edit the regular "Text" property! You will lose the BBCode markup if you do. All changes
  44. to the text must be done using the "BBCode Text".
  45. Reference
  46. ---------
  47. .. list-table::
  48. :class: wrap-normal
  49. :width: 100%
  50. :widths: 60 40
  51. * - Tag
  52. - Example
  53. * - | **b**
  54. | Makes ``{text}`` use the bold (or bold italics) font of ``RichTextLabel``.
  55. - ``[b]{text}[/b]``
  56. * - | **i**
  57. | Makes ``{text}`` use the italics (or bold italics) font of ``RichTextLabel``.
  58. - ``[i]{text}[/i]``
  59. * - | **u**
  60. | Makes ``{text}`` underlined.
  61. - ``[u]{text}[/u]``
  62. * - | **s**
  63. | Makes ``{text}`` strikethrough.
  64. - ``[s]{text}[/s]``
  65. * - | **code**
  66. | Makes ``{text}`` use the mono font of ``RichTextLabel``.
  67. - ``[code]{text}[/code]``
  68. * - | **p**
  69. | Adds new paragraph with ``{text}``. Supports configuration options,
  70. see :ref:`doc_bbcode_in_richtextlabel_paragraph_options`.
  71. - | ``[p]{text}[/p]``
  72. | ``[p {options}]{text}[/p]``
  73. * - | **center**
  74. | Makes ``{text}`` horizontally centered.
  75. | Same as ``[p align=center]``.
  76. - ``[center]{text}[/center]``
  77. * - | **left**
  78. | Makes ``{text}`` horizontally right-aligned.
  79. | Same as ``[p align=left]``.
  80. - ``[left]{text}[/left]``
  81. * - | **right**
  82. | Makes ``{text}`` horizontally right-aligned.
  83. | Same as ``[p align=right]``.
  84. - ``[right]{text}[/right]``
  85. * - | **fill**
  86. | Makes ``{text}`` fill the the full width of ``RichTextLabel``.
  87. | Same as ``[p align=fill]``.
  88. - ``[fill]{text}[/fill]``
  89. * - | **indent**
  90. | Indents ``{text}`` once.
  91. - ``[indent]{text}[/indent]``
  92. * - | **url**
  93. | Creates a hyperlink (underlined and clickable text). Can contain optional
  94. ``{text}`` or display ``{link}`` as is.
  95. | **Must be handled with the "meta_clicked" signal to have an effect,** see :ref:`doc_bbcode_in_richtextlabel_handling_url_tag_clicks`.
  96. - | ``[url]{link}[/url]``
  97. | ``[url={link}]{text}[/url]``
  98. * - | **img**
  99. | Inserts an image from the ``{path}`` (can be any valid image resource).
  100. | If ``{width}`` is provided, the image will try to fit that width maintaining
  101. the aspect ratio.
  102. | If both ``{width}`` and ``{height}`` are provided, the image will be scaled
  103. to that size.
  104. | If ``{valign}`` configuration is provided, the image will try to align to the
  105. surrounding text, see :ref:`doc_bbcode_in_richtextlabel_image_alignment`.
  106. | Supports configuration options, see :ref:`doc_bbcode_in_richtextlabel_image_options`.
  107. - | ``[img]{path}[/img]``
  108. | ``[img={width}]{path}[/img]``
  109. | ``[img={width}x{height}]{path}[/img]``
  110. | ``[img={valign}]{path}[/img]``
  111. | ``[img {options}]{path}[/img]``
  112. * - | **font**
  113. | Makes ``{text}`` use a font resource from the ``{path}``.
  114. | Supports configuration options, see :ref:`doc_bbcode_in_richtextlabel_font_options`.
  115. - | ``[font={path}]{text}[/font]``
  116. | ``[font {options}]{text}[/font]``
  117. * - | **font_size**
  118. | Use custom font size for ``{text}``.
  119. - ``[font_size={size}]{text}[/font_size]``
  120. * - | **opentype_features**
  121. | Enables custom OpenType font features for ``{text}``. Features must be provided as
  122. a comma-separated ``{list}``.
  123. - | ``[opentype_features={list}]``
  124. | ``{text}``
  125. | ``[/opentype_features]``
  126. * - | **color**
  127. | Changes the color of ``{text}``. Color must be provided by a common name (see
  128. :ref:`doc_bbcode_in_richtextlabel_named_colors`) or using the HEX format (e.g.
  129. ``#ff00ff``, see :ref:`doc_bbcode_in_richtextlabel_hex_colors`).
  130. - ``[color={code/name}]{text}[/color]``
  131. * - | **bgcolor**
  132. | Draws the color behind ``{text}``. Accepts same values as the ``color`` tag.
  133. - ``[bgcolor={code/name}]{text}[/bgcolor]``
  134. * - | **fgcolor**
  135. | Draws the color in front of ``{text}``. Accepts same values as the ``color`` tag.
  136. - ``[fgcolor={code/name}]{text}[/fgcolor]``
  137. * - | **outline_size**
  138. | Use custom font outline size for ``{text}``.
  139. - | ``[outline_size={size}]``
  140. | ``{text}``
  141. | ``[/outline_size]``
  142. * - | **outline_color**
  143. | Use custom outline color for ``{text}``. Accepts same values as the ``color`` tag.
  144. - | ``[outline_color={code/name}]``
  145. | ``{text}``
  146. | ``[/outline_color]``
  147. * - | **table**
  148. | Creates a table with the ``{number}`` of columns. Use the ``cell`` tag to define
  149. table cells.
  150. - ``[table={number}]{cells}[/table]``
  151. * - | **cell**
  152. | Adds a cell with ``{text}`` to the table.
  153. | If ``{ratio}`` is provided, the cell will try to expand to that value proportionally
  154. to other cells and their ratio values.
  155. | Supports configuration options, see :ref:`doc_bbcode_in_richtextlabel_cell_options`.
  156. - | ``[cell]{text}[/cell]``
  157. | ``[cell={ratio}]{text}[/cell]``
  158. | ``[cell {options}]{text}[/cell]``
  159. * - | **ul**
  160. | Adds an unordered list. List ``{items}`` must be provided by putting one item per
  161. line of text.
  162. - ``[ul]{items}[/ul]``
  163. * - | **ol**
  164. | Adds an ordered (numbered) list of the given ``{type}`` (see :ref:`doc_bbcode_in_richtextlabel_list_types`).
  165. List ``{items}`` must be provided by putting one item per line of text.
  166. - ``[ol type={type}]{items}[/ol]``
  167. * - | **lb**, **rb**
  168. | Adds ``[`` and ``]`` respectively. Allows escaping BBCode markup.
  169. - | ``[lb]b[rb]text[lb]/b[rb]`` will display as ``[b]text[/b]``.
  170. * - | Several Unicode control character can be added using their own tags.
  171. - | ``[lrm]``, ``[rlm]``, ``[lre]``, ``[rle]``, ``[lro]``, ``[rlo]``,
  172. ``[pdf]``, ``[alm]``, ``[lri]``, ``[rli]``, ``[fsi]``, ``[pdi]``,
  173. ``[zwj]``, ``[zwnj]``, ``[wj]``
  174. .. note::
  175. Tags for bold (``[b]``), italics (``[i]``), and monospaced (``[code]``)
  176. formatting only work if the appropriate custom fonts are set up for
  177. the ``RichTextLabel`` node first.
  178. There are no BBCode tags to control vertical centering of text yet.
  179. Options can be skipped for all tags.
  180. .. _doc_bbcode_in_richtextlabel_paragraph_options:
  181. Paragraph options
  182. ~~~~~~~~~~~~~~~~~
  183. - **align**
  184. +-----------+--------------------------------------------+
  185. | `Values` | ``left``, ``center``, ``right``, ``fill`` |
  186. +-----------+--------------------------------------------+
  187. | `Default` | ``left`` |
  188. +-----------+--------------------------------------------+
  189. Text horizontal alignment.
  190. - **bidi_override**, **st**
  191. +-----------+---------------------------------------------------------------------------+
  192. | `Values` | ``default``, ``uri``, ``file``, ``email``, ``list``, ``none``, ``custom`` |
  193. +-----------+---------------------------------------------------------------------------+
  194. | `Default` | ``default`` |
  195. +-----------+---------------------------------------------------------------------------+
  196. Structured text override.
  197. - **direction**, **dir**
  198. +-----------+--------------------------------------------+
  199. | `Values` | ``ltr``, ``rtl``, ``auto`` |
  200. +-----------+--------------------------------------------+
  201. | `Default` | Inherit |
  202. +-----------+--------------------------------------------+
  203. Base BiDi direction.
  204. - **language**, **lang**
  205. +-----------+--------------------------------------------+
  206. | `Values` | ISO language codes. See :ref:`doc_locales` |
  207. +-----------+--------------------------------------------+
  208. | `Default` | Inherit |
  209. +-----------+--------------------------------------------+
  210. Locale override.
  211. .. _doc_bbcode_in_richtextlabel_handling_url_tag_clicks:
  212. Handling ``[url]`` tag clicks
  213. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  214. By default, ``[url]`` tags do nothing when clicked. This is to allow flexible use
  215. of ``[url]`` tags rather than limiting them to opening URLs in a web browser.
  216. To handle clicked ``[url]`` tags, connect the ``RichTextLabel`` node's
  217. :ref:`meta_clicked <class_RichTextLabel_signal_meta_clicked>` signal to a script function.
  218. For example, the following method can be connected to ``meta_clicked`` to open
  219. clicked URLs using the user's default web browser::
  220. # This assumes RichTextLabel's `meta_clicked` signal was connected to
  221. # the function below using the signal connection dialog.
  222. func _richtextlabel_on_meta_clicked(meta):
  223. # `meta` is not guaranteed to be a String, so convert it to a String
  224. # to avoid script errors at run-time.
  225. OS.shell_open(str(meta))
  226. For more advanced use cases, it's also possible to store JSON in an ``[url]``
  227. tag's option and parse it in the function that handles the ``meta_clicked`` signal.
  228. For example:
  229. .. code-block:: none
  230. [url={"example": "value"}]JSON[/url]
  231. .. _doc_bbcode_in_richtextlabel_image_options:
  232. Image options
  233. ~~~~~~~~~~~~~
  234. - **color**
  235. +-----------+--------------------------------------------+
  236. | `Values` | Color name or color in HEX format |
  237. +-----------+--------------------------------------------+
  238. | `Default` | Inherit |
  239. +-----------+--------------------------------------------+
  240. Color tint of the image (modulation).
  241. - **height**
  242. +-----------+--------------------------------------------+
  243. | `Values` | Number in pixels |
  244. +-----------+--------------------------------------------+
  245. | `Default` | Inherit |
  246. +-----------+--------------------------------------------+
  247. Target height of the image.
  248. - **width**
  249. +-----------+--------------------------------------------+
  250. | `Values` | Number in pixels |
  251. +-----------+--------------------------------------------+
  252. | `Default` | Inherit |
  253. +-----------+--------------------------------------------+
  254. Target width of the image.
  255. .. _doc_bbcode_in_richtextlabel_image_alignment:
  256. Image vertical alignment
  257. ~~~~~~~~~~~~~~~~~~~~~~~~
  258. When a vertical alignment value is provided with the ``[img]`` tag the image
  259. will try to align itself against the surrounding text. Alignment is performed
  260. using a vertical point of the image and a vertical point of the text. There are
  261. 3 possible points on the image (``top``, ``center``, and ``bottom``) and 4
  262. possible points on the text (``top``, ``center``, ``baseline``, and ``bottom``),
  263. which can be used in any combination.
  264. To specify both points, use their full or short names as a value of the image tag:
  265. .. code-block:: none
  266. [img=top,bottom]
  267. [img=center,center]
  268. You can also specify just one value (``top``, ``center``, or ``bottom``) to make
  269. use of a corresponding preset (``top-top``, ``center-center``, and ``bottom-bottom``
  270. respectively).
  271. Short names for the values are ``t`` (``top``), ``c`` (``center``), ``l`` (``baseline``),
  272. and ``b`` (``bottom``).
  273. .. _doc_bbcode_in_richtextlabel_font_options:
  274. Font options
  275. ~~~~~~~~~~~~
  276. - **name**, **n**
  277. +-----------+--------------------------------------------+
  278. | `Values` | A valid Font resource path. |
  279. +-----------+--------------------------------------------+
  280. | `Default` | Inherit |
  281. +-----------+--------------------------------------------+
  282. Font resource path.
  283. - **size**, **s**
  284. +-----------+--------------------------------------------+
  285. | `Values` | Number in pixels. |
  286. +-----------+--------------------------------------------+
  287. | `Default` | Inherit |
  288. +-----------+--------------------------------------------+
  289. Custom font size.
  290. .. _doc_bbcode_in_richtextlabel_named_colors:
  291. Named colors
  292. ~~~~~~~~~~~~
  293. For tags that allow specifying a color by name you can use names of the constants from
  294. the built-in :ref:`class_Color` class. Named classes can be specified in a number of
  295. styles using different casings: ``DARK_RED``, ``DarkRed``, and ``darkred`` will give
  296. the same exact result.
  297. .. _doc_bbcode_in_richtextlabel_hex_colors:
  298. Hexadecimal color codes
  299. ~~~~~~~~~~~~~~~~~~~~~~~
  300. For opaque RGB colors, any valid 6-digit hexadecimal code is supported, e.g.
  301. ``[color=#ffffff]white[/color]``. Shorthand RGB color codes such as ``#6f2``
  302. (equivalent to ``#66ff22``) are also supported.
  303. For transparent RGB colors, any RGBA 8-digit hexadecimal code can be used,
  304. e.g. ``[color=#ffffff88]translucent white[/color]``. Note that the alpha channel
  305. is the **last** component of the color code, not the first one. Short RGBA
  306. color codes such as ``#6f28`` (equivalent to ``#66ff2288``) are supported as well.
  307. .. _doc_bbcode_in_richtextlabel_cell_options:
  308. Cell options
  309. ~~~~~~~~~~~~
  310. - **expand**
  311. +-----------+--------------------------------------------+
  312. | `Values` | Integer number |
  313. +-----------+--------------------------------------------+
  314. | `Default` | 1 |
  315. +-----------+--------------------------------------------+
  316. Cell expansion ration, which cell will try to expand to proportionally to other
  317. cells and their expansion ratios.
  318. - **border**
  319. +-----------+--------------------------------------------+
  320. | `Values` | Color name or color in HEX format |
  321. +-----------+--------------------------------------------+
  322. | `Default` | Inherit |
  323. +-----------+--------------------------------------------+
  324. Cell border color.
  325. - **bg**
  326. +-----------+--------------------------------------------+
  327. | `Values` | Color name or color in HEX format |
  328. +-----------+--------------------------------------------+
  329. | `Default` | Inherit |
  330. +-----------+--------------------------------------------+
  331. Cell background color. For alternating odd/even row backgrounds
  332. you can use ``bg=odd_color,even_color``.
  333. .. _doc_bbcode_in_richtextlabel_list_types:
  334. Ordered list types
  335. ~~~~~~~~~~~~~~~~~~
  336. Ordered lists can be used to automatically mark items with numbers
  337. or letters in ascending order. This tag supports the following
  338. type options:
  339. - ``1`` - Numbers, using language specific numbering system if possible.
  340. - ``a``, ``A`` - Lower and upper case Latin letters.
  341. - ``i``, ``I`` - Lower and upper case Roman numerals.
  342. Animation effects
  343. -----------------
  344. BBCode can also be used to create different text animation effects. Five customizable
  345. effects are provided out of the box, and you can easily create your own.
  346. Wave
  347. ~~~~
  348. .. image:: img/wave.png
  349. Wave makes the text go up and down. Its tag format is ``[wave amp=50 freq=2][/wave]``.
  350. ``amp`` controls how high and low the effect goes, and ``freq`` controls how fast the
  351. text goes up and down.
  352. Tornado
  353. ~~~~~~~
  354. .. image:: img/tornado.png
  355. Tornao makes the text move around in a circle. Its tag format is
  356. ``[tornado radius=5 freq=2][/tornado]``.
  357. ``radius`` is the radius of the circle that controls the offset, ``freq`` is how
  358. fast the text moves in a circle.
  359. Shake
  360. ~~~~~
  361. .. image:: img/shake.png
  362. Shake makes the text shake. Its tag format is ``[shake rate=5 level=10][/shake]``.
  363. ``rate`` controls how fast the text shakes, ``level`` controls how far the text is
  364. offset from the origin.
  365. Fade
  366. ~~~~
  367. .. image:: img/fade.png
  368. Fade creates a fade effect over the text that is not animated. Its tag format is
  369. ``[fade start=4 length=14][/fade]``.
  370. ``start`` controls the starting position of the falloff relative to where the fade
  371. command is inserted, ``length`` controls over how many characters should the fade
  372. out take place.
  373. Rainbow
  374. ~~~~~~~
  375. .. image:: img/rainbow.png
  376. Rainbow gives the text a rainbow color that changes over time. Its tag format is
  377. ``[rainbow freq=0.2 sat=10 val=20][/rainbow]``.
  378. ``freq`` is the number of full rainbow cycles per second, ``sat`` is the saturation
  379. of the rainbow, ``val`` is the value of the rainbow.
  380. Custom BBCode tags and text effects
  381. -----------------------------------
  382. You can extend the :ref:`class_RichTextEffect` resource type to create your own custom
  383. BBCode tags. You begin by extending the :ref:`class_RichTextEffect` resource type. Add
  384. the ``tool`` prefix to your GDScript file if you wish to have these custom effects run
  385. within the editor itself. The RichTextLabel does not need to have a script attached,
  386. nor does it need to be running in ``tool`` mode. The new effect can be activated in
  387. the Inspector through the **Custom Effects** property.
  388. There is only one function that you need to extend: ``_process_custom_fx(char_fx)``.
  389. Optionally, you can also provide a custom BBCode identifier simply by adding a member
  390. name ``bbcode``. The code will check the ``bbcode`` property automatically or will
  391. use the name of the file to determine what the BBCode tag should be.
  392. ``_process_custom_fx``
  393. ~~~~~~~~~~~~~~~~~~~~~~
  394. This is where the logic of each effect takes place and is called once per glyph
  395. during the draw phase of text rendering. This passes in a :ref:`class_CharFXTransform`
  396. object, which holds a few variables to control how the associated glyph is rendered:
  397. - ``identity`` specifies which custom effect is being processed. You should use that for
  398. code flow control.
  399. - ``outline`` is ``true`` if effect is called for drawing text outline.
  400. - ``range`` tells you how far into a given custom effect block you are in as an
  401. index.
  402. - ``elapsed_time`` is the total amount of time the text effect has been running.
  403. - ``visible`` will tell you whether the glyph is visible or not and will also allow you
  404. to hide a given portion of text.
  405. - ``offset`` is an offset position relative to where the given glyph should render under
  406. normal circumstances.
  407. - ``color`` is the color of a given glyph.
  408. - ``glyph_index`` and ``font`` is glyph being drawn and font data resource used to draw it.
  409. - Finally, ``env`` is a :ref:`class_Dictionary` of parameters assigned to a given custom
  410. effect. You can use :ref:`get() <class_Dictionary_method_get>` with an optional default value
  411. to retrieve each parameter, if specified by the user. For example ``[custom_fx spread=0.5
  412. color=#FFFF00]test[/custom_fx]`` would have a float ``spread`` and Color ``color``
  413. parameters in its ` `env`` Dictionary. See below for more usage examples.
  414. The last thing to note about this function is that it is necessary to return a boolean
  415. ``true`` value to verify that the effect processed correctly. This way, if there's a problem
  416. with rendering a given glyph, it will back out of rendering custom effects entirely until
  417. the user fixes whatever error cropped up in their custom effect logic.
  418. Here are some examples of custom effects:
  419. Ghost
  420. ~~~~~
  421. ::
  422. tool
  423. extends RichTextEffect
  424. class_name RichTextGhost
  425. # Syntax: [ghost freq=5.0 span=10.0][/ghost]
  426. # Define the tag name.
  427. var bbcode = "ghost"
  428. func _process_custom_fx(char_fx):
  429. # Get parameters, or use the provided default value if missing.
  430. var speed = char_fx.env.get("freq", 5.0)
  431. var span = char_fx.env.get("span", 10.0)
  432. var alpha = sin(char_fx.elapsed_time * speed + (char_fx.absolute_index / span)) * 0.5 + 0.5
  433. char_fx.color.a = alpha
  434. return true
  435. Pulse
  436. ~~~~~
  437. ::
  438. tool
  439. extends RichTextEffect
  440. class_name RichTextPulse
  441. # Syntax: [pulse color=#00FFAA height=0.0 freq=2.0][/pulse]
  442. # Define the tag name.
  443. var bbcode = "pulse"
  444. func _process_custom_fx(char_fx):
  445. # Get parameters, or use the provided default value if missing.
  446. var color = char_fx.env.get("color", char_fx.color)
  447. var height = char_fx.env.get("height", 0.0)
  448. var freq = char_fx.env.get("freq", 2.0)
  449. var sined_time = (sin(char_fx.elapsed_time * freq) + 1.0) / 2.0
  450. var y_off = sined_time * height
  451. color.a = 1.0
  452. char_fx.color = char_fx.color.linear_interpolate(color, sined_time)
  453. char_fx.offset = Vector2(0, -1) * y_off
  454. return true
  455. Matrix
  456. ~~~~~~
  457. ::
  458. tool
  459. extends RichTextEffect
  460. class_name RichTextMatrix
  461. # Syntax: [matrix clean=2.0 dirty=1.0 span=50][/matrix]
  462. # Define the tag name.
  463. var bbcode = "matrix"
  464. func _process_custom_fx(char_fx):
  465. # Get parameters, or use the provided default value if missing.
  466. var clear_time = char_fx.env.get("clean", 2.0)
  467. var dirty_time = char_fx.env.get("dirty", 1.0)
  468. var text_span = char_fx.env.get("span", 50)
  469. var matrix_time = fmod(char_fx.elapsed_time + (char_fx.range.x / float(text_span)), \
  470. clear_time + dirty_time)
  471. matrix_time = 0.0 if matrix_time < clear_time else \
  472. (matrix_time - clear_time) / dirty_time
  473. if matrix_time > 0.0:
  474. value = int(1 * matrix_time * (126 - 65))
  475. value %= (126 - 65)
  476. value += 65
  477. char_fx.glyph_index = TextServer.font_get_glyph_index(char_fx.font, value)
  478. return true
  479. This will add a few new BBCode commands, which can be used like so:
  480. .. code-block:: none
  481. [center][ghost]This is a custom [matrix]effect[/matrix][/ghost] made in
  482. [pulse freq=5.0 height=2.0][pulse color=#00FFAA freq=2.0]GDScript[/pulse][/pulse].[/center]