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)を切り替える必要があります。

../../_images/bbcodeText.png

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

../../_images/bbcodeDemo.png

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

注釈

``[b]``(太字)や ``[i]``(斜体)などのBBCodeタグが機能するには、最初にRichTextLabelノードのカスタムフォントを設定する必要があります。

リファレンス

コマンド タグ 説明
太字 [b]{text}[/b] {text}を太字にします。
斜体 [i]{text}[/i] {text}を斜体にします。
下線 [u]{text}[/u] {text}に下線を付けます。
取り消し線 [s]{text}[/s] {text}に取り消し線を付けます。
コード [code]{text}[/code] {text}をモノスペース(等倍)にします。
センター [center]{text}[/center] {text}を中央揃えで配置します。
[right]{text}[/right] {text}を右揃えにします。
フィル [fill]{text}[/fill] {text}を幅いっぱいに広げます。
インデント [indent]{text}[/indent] {text}のインデントレベルを上げます。
** URL ** [url]{url}[/url] {url}をそのまま表示します。
URL(名称) [url=<url>]{text}[/url] {text}名付きの<url>を作成します。
画像 [img]{path}[/img] リソース{path}の画像を挿入します。
サイズ変更された画像 [img=<width>]{path}[/img] (比率を保ちつつ)<width>を使用して、リソース{path}の画像を挿入します。
サイズ変更された画像 [img=<width>x<height>]{path}[/img] <width>と<height>を使用して、リソース{path}の画像を挿入します。
フォント [font=<path>]{text}[/font] <path>のカスタムフォントを{text}に使用します。
[color=<code/name>]{text}[/color] {text}の色を変更します。名前または#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進カラーコード

不透明なRGBカラーの場合、桁の省略をしない6桁の16進コードがサポートされます。例 [color=#ffffff]white[/color]

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

画像の垂直オフセット

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

  1. ``BitmapFont``リソースを作成する
  2. ascent プロパティに正の値を設定して、このビットマップフォントを設定します。これが高さオフセットです
  3. BBCodeタグを次のように設定します: [font=<font-path>][img]{image-path}[/img][/font]

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

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

Wave(波)

../../_images/wave.png

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

Tornado(竜巻)

../../_images/tornado.png

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

Shake(シェイク)

../../_images/shake.png

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

Fade(フェード)

../../_images/fade.png

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

Rainbow(虹)

../../_images/rainbow.png

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

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

RichTextEffect リソースタイプを拡張して、独自のカスタムBBCodeタグを作成できます。最初にRichTextEffect リソースタイプを拡張します。これらのカスタムエフェクトをエディタ内で実行する場合は、GDScriptファイルに tool プレフィックスを追加します。 RichTextLabelにはスクリプトをアタッチする必要も、tool モードで実行する必要もありません。

拡張する必要がある関数は: _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]