API/playdate.graphics.font - Playdate 非公式開発まとめ wiki

playdate.graphics.font

playdate.graphics.font は、Playdate の文字描画用フォントオブジェクトです。

-- フォントを読み込む
local font = playdate.graphics.font.new("fonts/MyFont")
-- そのフォントで直接描画する
font:drawText("Hello", 10, 10)
-- または現在フォントとして設定する
playdate.graphics.setFont(font)
playdate.graphics.drawText("Hello", 10, 10)

font:drawText() は「このフォントで描く」関数です。
それに対して playdate.graphics.drawText() は「現在設定されているフォントで描く」関数です。

playdate.graphics.font
関連ページ

定数

定数名	値	説明
playdate.graphics.font.kVariantNormal	0	通常フォント。 newFamily()でフォントファミリーを作るときに使います
playdate.graphics.font.kVariantBold	1	太字フォント
playdate.graphics.font.kVariantItalic	2	斜体フォント

生成

new(path)

指定パスのフォントファイルを読み込み、playdate.graphics.font オブジェクトを返します。

カテゴリ	名前	型	省略	説明
引数	path	string	x	フォントファイルのパス
戻り値	-	playdate.graphics.font	o	フォントオブジェクト。ファイルが不正・存在しない場合は nil

Playdate のフォントは通常、Playdate SDKのフォント変換ツールなどで用意した Playdate 用フォントを使います。

newFamily(fontPaths)

複数のフォントファイルをまとめて、フォントファミリーを作成します。

カテゴリ	名前	型	省略	説明
引数	fontPaths	table<integer, string>	x	フォントファミリーのテーブル
戻り値	-	table<integer, playdate.graphics.font>	x	フォントオブジェクトのテーブル

引数のフォントファミリーのテーブル形式は以下の通り。

local fontPaths = {
    [playdate.graphics.font.kVariantNormal] = "fonts/MyFont",
    [playdate.graphics.font.kVariantBold]   = "fonts/MyFont-Bold",
    [playdate.graphics.font.kVariantItalic] = "fonts/MyFont-Italic",
}

戻り値としてフォントオブジェクトが入ったテーブルが返ります。

local family = playdate.graphics.font.newFamily({
    [playdate.graphics.font.kVariantNormal] = "fonts/Normal",
    [playdate.graphics.font.kVariantBold]   = "fonts/Bold",
    [playdate.graphics.font.kVariantItalic] = "fonts/Italic",
})

この戻り値は、playdate.graphics.setFontFamily() や playdate.graphics.getTextSize() などに渡す用途があります。
ただし、インラインスタイルを解釈して描画したい場合は、font:drawText() ではなく playdate.graphics.drawText() 系を使う必要があります。

文字描画

font:drawText(text, x, y, leadingAdjustment)

指定したフォントで、指定座標に文字列を描画します。
これは、現在フォントを変更せずに、その font インスタンスで直接描画します。

カテゴリ	名前	型	省略	説明
引数	text	string	x	描画する文字列

x	integer	x	x	X座標
y	integer	y	x	Y座標

leadingAdjustment

integer

複数行テキストの行間調整値

-- 
font:drawText("Line1\nLine2", 10, 20, 4)

font:drawText(text, rect, leadingAdjustment, wrapMode, alignment)

指定した矩形範囲内に文字列を描画します。

カテゴリ	名前	型	省略	説明
引数	text	string	x	描画する文字列
	rect	[[Rect>API/playdate.geometry.rect]	x	描画範囲 (矩形)
	leadingAdjustment	integer	o	複数行テキストの行間調整値
	wrapMode	integer	o	矩形描画の折り返し方法 (→kWrap)
	alignment	integer	o	アラインメント (→kTextAlignment)

-- 描画範囲の作成.
local rect = playdate.geometry.rect.new(10, 20, 200, 80)
-- 描画範囲内で描画.
font:drawText("Hello Playdate", rect)

font:drawText(text, x, y, width, height, leadingAdjustment, wrapMode, alignment)

矩形を x, y, width, height で指定して文字列を描画します。

カテゴリ	名前	型	省略	説明
引数	text	string	x	描画する文字列
	x	integer	x	描画範囲 (X)
	y	integer	x	描画範囲 (Y)
	width	integer	x	描画範囲 (幅)
	height	integer	x	描画範囲 (高さ)
	leadingAdjustment	integer	o	複数行テキストの行間調整値
	wrapMode	integer	o	矩形描画の折り返し方法 (→kWrap)
	alignment	integer	o	アラインメント (→kTextAlignment)
戻り値	width	integer	x	描画したテキストの幅
戻り値	height	integer	x	描画したテキストの高さ

font:drawText(
    "This is a long text.",
    10, 20,
    200, 80,
    0,
    playdate.graphics.kWrapWord,
    playdate.graphics.kAlignLeft
)

font:drawTextAligned(text, x, y, alignment, leadingAdjustment)

指定した x 座標を基準に、左揃え・中央揃え・右揃えで文字列を描画します。

カテゴリ	名前	型	省略	説明
引数	text	string	x	描画する文字列

x	integer	x	x	X座標
y	integer	y	x	Y座標

alignment	integer	x	アラインメント (→kTextAlignment)
leadingAdjustment	integer	o	複数行テキストの行間調整値

グリフ取得

font:getGlyph(character)

指定文字のグリフ画像を取得します。

カテゴリ	名前	型	省略	説明
引数	character	string	x	グリフ画像を取得するための文字列
戻り値	-	Image	x	グリフ画像

stub コメントでは、character は文字列または Unicode codepoint number を指定できると説明されています。
ただし、stub 型定義上は string です。

-- "A" をグリフ画像として取得する.
local glyph = font:getGlyph("A")
-- 描画.
glyph:draw(10, 10)

フォント情報取得・設定

font:getHeight()

フォントのピクセル高さを返します。
単純な1行分の高さとして使えますが、複数行テキストの行間には leading も関係します。

カテゴリ	名前	型	説明
戻り値	-	integer	フォントの高さ (px)

font:getLeading()

フォントの leading、つまり行間を返します。

カテゴリ	名前	型	説明
戻り値	-	integer	行間の高さ (px)

-- 複数行を自前で描画する場合は、このように使えます。
local lineAdvance = font:getHeight() + font:getLeading()

font:setLeading(pixels)

フォントの leading、つまり行間を設定します。
複数行テキストの行間を広げたい場合に使います。

カテゴリ	名前	型	省略	説明
引数	pixels	integer	x	行間 (px)

これはフォントオブジェクト自体の設定を変える操作で、同じ font を複数箇所で使い回している場合、他の描画にも影響します。
必要なら、描画前に設定し、描画後に戻す形にします。

font:getTextWidth(text)

指定文字列をこのフォントで描画した場合の横幅を返します。

カテゴリ	名前	型	省略	説明
引数	text	string	x	サイズを求める文字列
戻り値	-	integer	x	文字列の描画幅

中央揃えを自前で計算する場合に使えます。
ただし、中央揃えだけなら drawTextAligned() を使う方が簡単です。

local text = "GAME OVER"
local w = font:getTextWidth(text)
font:drawText(text, (400 - w) / 2, 120)

font:getTracking()

フォントの tracking、つまり文字間隔を返します。

カテゴリ	名前	型	説明
戻り値	-	integer	文字の幅の間隔 (px)

tracking を大きくすると、文字と文字の間が広がります。

font:setTracking(pixels)

フォントの tracking、つまり文字の幅の間隔を設定します。
文字間隔を広げたいタイトル表示などに使えます。

カテゴリ	名前	型	省略	説明
引数	pixels	integer	x	文字の幅の間隔 (px)

資料

1. フォントを読み込んで描画する

local font = playdate.graphics.font.new("fonts/MyFont")
function playdate.update()
    playdate.graphics.clear()
 
    if font then
        font:drawText("Hello", 10, 10)
    end
end

2. 画面中央に文字を出す

local font = playdate.graphics.font.new("fonts/MyFont")
function playdate.update()
    playdate.graphics.clear()
    font:drawTextAligned(
        "GAME START",
        200,
        100,
        kTextAlignment.center
    )
end

3. getTextWidth() で中央揃えする

local text = "GAME OVER"
local w = font:getTextWidth(text)
font:drawText(text, (400 - w) / 2, 120)

4. 矩形内で折り返して描画する

local text = "This is a long text that should wrap inside the box."
font:drawText(
    text,
    20, 20,
    360, 100,
    2,
    playdate.graphics.kWrapWord,
    playdate.graphics.kAlignLeft
)

5. 日本語などを文字単位で折り返す

font:drawText(
    "これは長い文章です。矩形内で文字単位に折り返します。",
    20, 20,
    360, 100,
    0,
    playdate.graphics.kWrapCharacter,
    playdate.graphics.kAlignLeft
)

英語なら kWrapWord、日本語なら kWrapCharacter の方が扱いやすいケースがあります。

Playdate 非公式開発まとめ wiki