godot-ui-rich-text

リッチテキストと BBCode

BBCode タグ、メタクリック可能なリンク、RichTextEffect シェーダーによって、書式設定されたテキストシステムを定義します。

利用可能なスクリプト

rich_text_rainbow_effect.gd

時間の経過とともに色を変化させる、熟練者向けのカスタム RichTextEffect です。

rich_text_glitch_effect.gd

空間的な揺れとアルファのちらつきを伴う、プロ仕様のホラー風グリッチエフェクトです。

rich_text_typewriter_controller.gd

アニメーション中に連続するイベントタグ（[pause]、[speed]）を解析する、ダイアログマネージャーです。

rich_text_meta_dispatch.gd

メタクリック時の複数プレフィックス付き URL（アイテム、クエスト、NPC）を高度に処理します。

rich_text_image_scaler.gd

[img] タグを実行時のフォントサイズに合わせて動的に拡大・縮小するユーティリティです。

rich_text_hover_reactive.gd

テキスト範囲をマウスホバーに反応させるためのシグナルとロジック（SFX／カーソル）です。

rich_text_bbcode_sanitizer.gd

公開チャットインターフェースでの BBCode インジェクションを防ぐセキュリティユーティリティです。

rich_text_gradient_generator.gd

文字単位の細かなタグ付けを使い、複数の停止点を持つ線形グラデーションを生成します。

rich_text_auto_scroller.gd

クレジット、ニュースフィード、ログ向けの滑らかな垂直自動スクロールロジックです。

rich_text_syntax_highlighter.gd

UI のコードブロック用の、シンプルな正規表現ベースの構文ハイライトパターンです。

絶対に避けること（UI の熟練者向けルール）

書式設定とレンダリング

• タイトなループ内で複雑な BBCode を絶対に使わないでください — 毎フレーム、500 個のタグを含む 10,000 文字の文字列を解析すると、パフォーマンスが大幅に低下します。書式設定した文字列はキャッシュしてください。
• カスタムエフェクトの登録を絶対に忘れないでください — スクリプトを書くだけでは不十分です。Inspector または install_effect() を使って、インスタンスを RichTextLabel.custom_effects リストに必ず追加してください。
• [img] で絶対ピクセルサイズを使わないでください — [img width=128] は高解像度では適切に動作しません。rich_text_image_scaler.gd を使って行の高さに合わせてください。

クリックとホバーの UX

• 視覚的なフィードバックなしで [url] を絶対に使わないでください — ホバー時にテキストの色が変わらず、カーソルも変化しない場合、プレイヤーにはクリック可能だと分かりません。rich_text_hover_reactive.gd を使ってください。
• 文字列にレイアウトロジックをハードコードしないでください。テキスト構造の柔軟性を保つため、BBCode テーブルと配置タグを必ず使ってください。
• フレームごとに text または bbcode 文字列を書き換えて、テキストのタイプライター効果をアニメーションさせないでください。解析負荷の増大やちらつきを避けるため、visible_ratio または visible_characters を必ず使ってください。
• 大きなタイトルや動的 UI に標準のビットマップフォントを使わないでください。どの解像度でも輪郭の鮮明さと拡大縮小を保つため、**MSDF（マルチチャンネル符号付き距離場）**フォントを必ず使ってください。
• meta_clicked 内で重い処理を絶対に実行しないでください — このシグナルはメインスレッド上で実行されます。コマンドの発行に使い、必要に応じて非同期で処理してください。

ダイアログとナラティブ

• タイプライター効果の一時停止に visible_ratio を絶対に使わないでください — visible_ratio は文字単位のロジックには信頼性がありません。visible_characters と明示的な文字インデックス（rich_text_typewriter_controller.gd）を使ってください。
• チャットラベルでフィルターされていないユーザー入力を絶対に許可しないでください — ユーザーが [img]huge_image_path[/img] や [color=transparent] と入力すると、UI が壊れる可能性があります。必須：ユーザーが生成した文字列を text に設定する前に、すべて rich_text_bbcode_sanitizer.gd に通してください。

---

$RichTextLabel.bbcode_enabled = true
$RichTextLabel.text = "[b]Bold[/b] and [i]italic[/i] text"

Reveal API の選択

必要なもの	API	必須
シンプルなフェード／行全体の表示	visible_ratio + Tween	インラインで記述できます（下記のパターンを参照）
一時停止／速度／イベントタグ（[pause]、[speed]）	visible_characters + indexer	rich_text_typewriter_controller.gd

文字ごとの一時停止／速度タグが必要な場合は、絶対に visible_ratio を使用しないでください。

見落としやすいタグと効果

[b]／[i]／[u]／[color] のカタログ化は省略してください。ドキュメントを参照してください。見落としやすいものとして、以下を優先してください。

• [url=payload]…[/url] + meta_clicked — rich_text_meta_dispatch.gd を優先してください
• [img] のサイズ指定 — width_unit／height_unit + RichTextLabel.ImageUnit を使用してください（migration-notes.md を参照）。rich_text_image_scaler.gd で拡大縮小します
• カスタムエフェクト — custom_effects／install_effect() で登録します。例：rich_text_rainbow_effect.gd、rich_text_glitch_effect.gd

ユーザー生成のリッチテキスト

必須：チャット、ロビー、またはプレイヤーが入力するパスでは、RichTextLabel.text = … の前に rich_text_bbcode_sanitizer.gd を使用してください。

リンククリックの処理

rich_text_meta_dispatch.gd を優先してください。最小限のフック：

func _ready() -> void:
    $RichTextLabel.meta_clicked.connect(_on_meta_clicked)

func _on_meta_clicked(meta: Variant) -> void:
    # Emit a command; do not run heavy game logic here
    pass

エキスパート向けテキストパターン

1. リッチテキスト MSDF アウトライン（SDF）

フォントリソースで MSDF を有効にし、テーマのオーバーライドを使用することで、鮮明な高解像度のアウトラインと拡大縮小を実現します。

# msdf_styler.gd
func _ready():
    # Crisp outlines regardless of screen scale
    label.add_theme_color_override("font_outline_color", Color.BLACK)
    label.add_theme_constant_override("outline_size", 4)

2. アニメーション付きテキスト表示

シンプルなフェード — visible_ratio を Tween します（BBCode エフェクトを維持し、文字列を書き換えません）。

func reveal_fade(label: RichTextLabel, new_text: String, duration: float) -> void:
    label.text = new_text
    label.visible_ratio = 0.0
    create_tween().tween_property(label, "visible_ratio", 1.0, duration)

一時停止／速度タグ — visible_characters を使用する rich_text_typewriter_controller.gd が必須です（visible_ratio は使用しません）。

3. カスタム BBCode エフェクト（RichTextEffect）

RichTextEffect を拡張してカスタムの視覚タグ（[relic] など）を定義し、ゲームプレイのテーマに合わせた独自のテキストアニメーションを作成します。

# relic_effect.gd
@tool
extends RichTextEffect
var bbcode = "relic"

func _process_custom_fx(char_fx: CharFXTransform):
    # Retrieve param: [relic color=#ff00ff]
    var color = char_fx.env.get("color", Color.GOLD)
    # Apply sinusoidal floating
    char_fx.offset.y += sin(char_fx.elapsed_time * 5.0) * 2.0
    char_fx.color = color
    return true

詳細なレシピ（必要に応じて）

LLM の知識不足に関するルール：一般的なエージェントが読む前には知らない情報は、ここか scripts/ に置きます。削除せず、移動のみ行ってください。

トピック	リファレンス
タグカタログ + 4.7 の img 単位	bbcode-tag-catalog.md

リファレンス

段階的な情報開示：特定の API を調査する場合に限り公式ドキュメントのリンクを開いてください。関連するスキルを読み込むのは、同じ階層の領域へ振り分ける場合に限り、全体をあらかじめ読み込まないでください。

公式ドキュメント

• RichTextLabel の BBCode — タグ構文、組み込みエフェクト、画像、会話や書式付き UI テキストに使う [url] メタ情報。
• RichTextLabel — bbcode_enabled、visible_characters / visible_ratio、meta_clicked、custom_effects / install_effect()。
• RichTextEffect — カスタム BBCode エフェクトのサブクラス契約（bbcode ID と _process_custom_fx）。
• CharFXTransform — レインボー／グリッチ／カスタムエフェクトで使う、グリフごとの色、オフセット、env パラメーター。
• フォントの使用 — MSDF／ダイナミックフォントを使い、タイトルや BBCode の表示をさまざまな解像度で鮮明に保ちます。
• GUI のスキニング — スタイルを BBCode 文字列に埋め込まず、テーマの色や定数（アウトライン、フォント）をオーバーライドします。
• サイズとアンカー — 解像度が変わってもリッチテキストのレイアウトを維持できる、レスポンシブな会話ボックスやログパネルを作成します。
• GUI コンテナ — ボタンやアイコンはコンテナに配置し、RichTextLabel は本文のみに使用します。
• カスタムマウスカーソル — [url] やメタ情報の範囲にカーソルを合わせたときのフィードバックを実装します。
• ゲームの国際化 — tr() / CSV キーを使い、BBCode テンプレートをローカライズに対応できる状態に保ちます。
• シグナル — ゲームロジックをラベルに詰め込まずに、meta_clicked / ホバーシグナルを接続します。
• Tween — フレームごとに BBCode を再解析せず、visible_ratio / visible_characters を Tween で変化させてタイプライター表示を実現します。

関連スキル

前提条件

• godot-project-foundations — RichTextLabel の会話 UI を組み込む前に、シーンツリー、Control の基本、リソースのインポートを学びます。
• godot-ui-containers — リッチテキストをレイアウトエンジンではなく本文として使えるようにする、レスポンシブな VBox/HBox/Scroll の枠組みを学びます。
• godot-signal-architecture — 型付きのメタ情報／ホバー用コマンドシグナルを使い、クリックハンドラーをメインスレッド上で簡潔に保ちます。
• godot-gdscript-mastery — サニタイザー、ハイライター、エフェクトスクリプトで使う RegEx、@tool、RefCounted ヘルパーを学びます。

補完

• godot-ui-theming — テーマの種類やフォント／アウトラインの上書きについて説明します。BBCode ではこれらをハードコードせず、参照する必要があります。
• godot-tweening — タイプライターの visible_ratio や自動スクロールの仕上げに使える、ライフサイクルに安全なトゥイーンです。
• godot-input-handling — Control のフォーカスと競合せずに、メタのホバーと組み合わせられるスキップ／進行操作やカーソルの変更について説明します。
• godot-dialogue-system — RichTextLabel のタイプライターコントローラーにデータを渡す、行の実行処理やイベントタグについて説明します。
• godot-shaders-basics — CharFX だけでは不十分で、テキストパネルにキャンバスアイテムシェーダーが必要な場合に役立ちます。

下流／利用側

• godot-genre-visual-novel — BBCode、visible_characters、メタ選択肢リンクに依存するビジュアルノベルのダイアログボックスです。
• godot-genre-educational — サニタイザーやハイライターを再利用する、レッスン／コピー用 UI やインタラクティブなリッチテキストです。
• godot-genre-romance — タイプライターやメタのディスパッチパターンを再利用する、好感度ダイアログの表示機能です。

マスター

• godot-master — スキル間の探索に使うライブラリルーターおよびミラー化されたモジュールのエントリーポイントです。