RichTextLabelのBBCode

はじめに

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 RichTextLabel.

RichTextLabel を使用すると、コントロールで複雑なテキストマークアップを表示できます。マークアップを生成するための組み込みAPIがありますが、BBCodeを解析することもできます。

BBCodeタグは、:ref:`XML source of the class reference <doc_updating_the_class_reference>`でもある程度使用することができます。

BBCodeを使用する

均一に書式設定されたテキストの場合は、"Text" プロパティで記述できますが、BBCodeマークアップを使用する場合は、代わりに "Bb Code" セクションの "Text" プロパティを使用する必要があります(bbcode_text)。このプロパティに書き込むと、マークアップの解析がトリガーされ、要求に応じてテキストの書式が設定されます。この処理を行う前に、”Bb Code" セクションの "Enabled"チェックボックス(bbcode_enabled)を切り替える必要があります。

たとえば、BBCode [color=blue]blue[/color] は、単語 "blue" を青色でレンダリングします。

BBCodeの "Text" プロパティに書き込んだ後、通常の "Text" プロパティにBBCodeのないテキストが含まれていることに気付くとおもいます。テキストプロパティはBBCodeプロパティによって更新されるので、テキストプロパティを編集できないか、または編集するとBBCodeマークアップが失われます。テキストに対するすべての変更は、BBCodeパラメーターで行う必要があります。

注釈

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.

リファレンス

Command	タグ	説明
太字	[b]{text}[/b]	{text}を太字にします。
斜体	[i]{text}[/i]	{text}を斜体にします。
下線	[u]{text}[/u]	{text}に下線を付けます。
取り消し線	[s]{text}[/s]	{text}に取り消し線を付けます。
コード	[code]{text}[/code]	Makes {text} use the code font (which is typically monospace).
センター	[center]{text}[/center]	Makes {text} horizontally centered.
右	[right]{text}[/right]	Makes {text} horizontally right-aligned.
フィル	[fill]{text}[/fill]	Makes {text} fill the RichTextLabel's width.
インデント	[indent]{text}[/indent]	Increase the indentation level of {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(名称)	[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.
画像	[img]{path}[/img]	リソース{path}の画像を挿入します。
サイズ変更された画像	[img=<width>]{path}[/img]	(比率を保ちつつ)<width>を使用して、リソース{path}の画像を挿入します。
サイズ変更された画像	[img=<width>x<height>]{path}[/img]	Insert image at resource {path} using <width>×<height>.
フォント	[font=<path>]{text}[/font]	<path>のカスタムフォントを{text}に使用します。
色	[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]{text}[/cell]	Adds cells with the {text} to the table.

組み込みの色名

[color = <name>]タグで有効な色名のリスト:

• aqua

• black

• blue

• fuchsia

• gray

• green

• lime

• maroon

• navy

• purple

• red

• silver

• teal

• white

• yellow

16進カラーコード

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.

透過RGBカラーの場合、8桁の16進コードを使用できます。例 [color=#88ffffff]translucent white[/color]。この場合、アルファチャネルはカラーコードの 最初の 値であり、最後の値ではないことに注意してください。

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]

画像の垂直オフセット

画像を縦に揃えるには、画像にカスタムフォントを使用します。

1. ``BitmapFont``リソースを作成する

2. ascent プロパティに正の値を設定して、このビットマップフォントを設定します。これが高さオフセットです

3. BBCodeタグを次のように設定します: [font=<font-path>][img]{image-path}[/img][/font]

アニメーションエフェクト

BBCodeを使用して、さまざまなテキストアニメーションエフェクトを作成することもできます。カスタマイズ可能な5つのエフェクトがすぐに使用でき、独自のエフェクトも簡単に作成できます。

Wave(波)

Waveはテキストを上下に動かします。タグの形式は [wave amp=50 freq=2][/wave] です。amp は効果の高低を制御し、freq はテキストの上下移動の速度を制御します。

Tornado(竜巻)

Tornaoは、テキストを円状に動かします。タグの形式は [tornado radius=5 freq=2][/tornado] です。radius はオフセットを制御する円の半径、freq はテキストが円内を移動する速度です。

Shake(シェイク)

Shakeを指定するとテキストが揺れます。タグの形式は [shake rate=5 level=10][/shake] です。rate はテキストの揺れの速さを制御し、level はテキストが原点からどれだけオフセットされるかを制御します。

Fade(フェード)

Fadeは、アニメーション化されていないテキストにフェード効果を作成します。タグの形式は [fade start=4 length=14][/fade] です。start は、フェードコマンドが挿入される場所に関連するフォールオフの開始位置を制御し、length は、フェードアウトを行う文字数を制御します。

Rainbow(虹)

Rainbowは、時間とともに変化する虹色をテキストに与えます。タグ形式は [rainbow freq=0.2 sat=10 val=20][/rainbow] です。freq は1秒あたりの虹色が一周する数、sat は虹の彩度、val は虹の値です。

カスタムBBCodeタグとテキストエフェクト

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.

警告

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.

拡張する必要がある関数は: _process_custom_fx(char_fx) のみです。オプションで、メンバー名 bbcode を追加するだけで、カスタムBBCode識別子を提供することもできます。コードは bbcode プロパティを自動的にチェックするか、ファイルの名前を使用してBBCodeタグの内容を決定します。

_process_custom_fx

これは、各エフェクトのロジックが発生する場所であり、テキストレンダリングの描画段階で文字ごとに1回呼び出されます。これは CharFXTransform オブジェクトを渡します。このオブジェクトには、関連する文字のレンダリング方法を制御するいくつかの変数が含まれています:

• identity は、どのカスタムエフェクトが処理されているかを指定します。コードフロー制御に使用する必要があります。

• relative_index は、与えられたカスタムエフェクトブロックにどれだけのインデックスを持っているかを示します。

• absolute_index は、インデックスとしてテキスト全体にどの程度まで入るかを示します。

• elapsed_time は、テキストエフェクトが実行されている合計時間です。

• `` visible`` は、文字が表示されているかどうかを示し、テキストの特定の部分を非表示にすることもできます。

• offset は、通常の状況で指定された文字がレンダリングされる場所に対する、相対的なオフセット位置です。

• color は、指定された文字の色です。

• 最後に、env は、特定のカスタムエフェクトに割り当てられたパラメーターの Dictionary です。ユーザーが指定した場合、get() をオプションのデフォルト値とともに使用して、各パラメーターを取得できます。たとえば、[custom_fx spread=0.5 color=#FFFF00]test[/custom_fx] は、env ディクショナリに浮動小数点数の spread と色の color パラメーターを持つことになります。その他の使用例については、以下を参照してください。

この関数について最後に注意することは、効果が正しく処理されたことを確認するためにブール値の true を返す必要があるということです。このように、特定の文字のレンダリングに問題がある場合、ユーザーがカスタムエフェクトロジックで発生したエラーを修正するまで、カスタムエフェクトのレンダリングが完全に行えなくなります。

カスタムエフェクトの例を次に示します:

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

これにより、次のように使用できる新しいBBCodeコマンドが追加されます:

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