ラベル

ラベル（Label） コンポーネント（component）は、ゲーム空間内のテキストを画面に描画します。デフォルトでは、すべてのスプライト（sprite）およびタイルグラフィックスと一緒に並べ替えられ、描画されます。このコンポーネントには、テキストの描画方法を制御する一連のプロパティがあります。Defold の GUI はテキストをサポートしていますが、GUI 要素をゲームワールド（game world）に配置するのは難しい場合があります。ラベルを使うと、この配置が容易になります。

ラベルの作成

ラベルコンポーネントを作成するには、ゲームオブジェクト（game object）を 右クリック し、Add Component ▸ Label を選択します。

（同じテンプレートから複数のラベルのインスタンスを作成したい場合は、代わりに新しいラベルコンポーネントファイルを作成することもできます。Assets ブラウザーでフォルダーを 右クリック して New... ▸ Label を選択し、そのファイルを任意のゲームオブジェクトにコンポーネントとして追加します）

Font プロパティに使用するフォントを設定し、Material プロパティには、必ずフォントの種類に合ったマテリアル（material）を設定します。

ベクターフォントとカラー絵文字

Vector フォントを使うには、ベクターフォントの設定に従い、Label の Font に .font リソースを割り当て、Material を /builtins/fonts/label-vector.material に設定します。表示サイズは Font Size で制御します。

カラー絵文字では、COLRv1 のフォールバックとバンドルの設定も完了してください。以下の例では、ID が label の Label と、同じゲームオブジェクト上のスクリプトを想定します。グリフの準備ができてから挨拶を表示するよう、Label の Text は空にします。

function init(self)
    local text = "Hello 😀 🍎 🚀"
    local font_resource = go.get("#label", "font")
    -- Add the fallback once for this shared font resource.
    font.add_font(font_resource, "/fonts/NotoColorEmoji-Regular.ttf")
    font.prewarm_text(font_resource, text, function(self, request_id, result, err)
        if result then
            go.set("#label", "text", text)
        else
            print("Could not prepare label text:", err)
        end
    end)
end

通常の文字は元のフォントを、絵文字は追加したカラーフォントを使います。ほかの Label や GUI テキストノードがこのフォントリソースを共有する場合は、1か所でフォールバックを初期化し、再利用してください。

ラベルのプロパティ

Id、Position、Rotation、Scale プロパティに加えて、次のコンポーネント固有のプロパティがあります。

Text

ラベルのテキスト内容です。

Size

テキストのバウンディングボックスのサイズです。Line Break が設定されている場合、幅によってテキストを折り返す位置が指定されます。

Color

テキストの色です。

Outline

輪郭の色です。

Shadow

影の色です。

Leading

行間の倍率を指定する数値です。値が 0 の場合、行間はなくなります。デフォルトは 1 です。

Tracking

字間の倍率を指定する数値です。デフォルトは 0 です。

Pivot

テキストのピボット（pivot）です。テキストの揃え方を変更するために使います（下記参照）。

Blend Mode

ラベルの描画時に使用するブレンドモード（blend mode）です。

Line Break

テキストの揃え方はピボットの設定に従います。このプロパティを設定すると、テキストを複数行にわたって表示できます。コンポーネントの幅によって、テキストを折り返す位置が決まります。折り返すにはテキスト内にスペースが必要であることに注意してください。

Font

このラベルに使用するフォントリソースです。

Material

このラベルの描画に使うマテリアルです。フォントのモードまたはソース（Bitmap、SDF、Vector、BMFont）に合うものを選択します。対応する組み込みの Label 用マテリアルは、フォントのマテリアルを参照してください。

ブレンドモード

Blend Mode プロパティは、コンポーネント（component）のグラフィックスを、その背後のグラフィックスとどのようにブレンドするかを定義します。使用できるブレンドモード（blend mode）とその計算方法は次のとおりです:

Alpha

通常のブレンド: src.a * src.rgb + (1 - src.a) * dst.rgb

Add

コンポーネントの対応するピクセルの色の値で、背景を明るくします: src.rgb + dst.rgb

Multiply

コンポーネントの対応するピクセルの値で、背景を暗くします: src.rgb * dst.rgb

Screen

Multiply とは逆の処理です。背景とコンポーネントの対応するピクセルの値を明るくします: src.rgb - dst.rgb * dst.rgb

ピボットとテキストの揃え方

Pivot プロパティを設定すると、テキストの揃え方を変更できます。

中央揃え

ピボットが Center、North、South に設定されている場合、テキストは中央揃えになります。

左揃え

ピボットが West 系のいずれかのモードに設定されている場合、テキストは左揃えになります。

右揃え

ピボットが East 系のいずれかのモードに設定されている場合、テキストは右揃えになります。

実行時の操作

ラベルのテキストや、その他のさまざまなプロパティを取得、設定して、実行時にラベルを操作できます。

text

ラベルのテキスト内容（string）です。go.get() と go.set() で操作できます。

color

ラベルの色です（vector4）。

outline

ラベルの輪郭の色です（vector4）。

shadow

ラベルの影の色です（vector4）。

scale

ラベルのスケールです。均等に拡大縮小する場合は number、各軸に沿って個別に拡大縮小する場合は vector3 を使います。

size

ラベルのサイズです（vector3）。

function init(self)
    -- Set the text of the "my_label" component in the same game object
    -- as this script.
    go.set("#my_label", "text", "New text")
    local text = go.get("#my_label", "text")
    print(text) -- New text
end

function init(self)
    -- Set the color of the "my_label" component in the same game object
    -- as this script. Color is a RGBA value stored in a vector4.
    local grey = vmath.vector4(0.5, 0.5, 0.5, 1.0)
    go.set("#my_label", "color", grey)

    -- ...and remove the outline, by setting its alpha to 0...
    go.set("#my_label", "outline.w", 0)

    -- ...and scale it x2 along x axis.
    local scale_x = go.get("#my_label", "scale.x")
    go.set("#my_label", "scale.x", scale_x * 2)
end

プロジェクト設定

game.project ファイルには、ラベルに関するいくつかの プロジェクト設定 があります。