API/playdate.ui.crankIndicator - Playdate 非公式開発まとめ wiki

playdate.ui.crankIndicator

playdate.ui.crankIndicatorは、Playdate でよく出てくる「クランクを使ってください」という案内アニメーションを描くための標準UIです。

playdate.ui.crankIndicator
関連ページ

import文

uiの機能を使うには基本的に以下のimport文が必要です。

import "CoreLibs/ui"

基本的な使い方

crankIndicatorは多くの場合、以下の記述となります。

import "CoreLibs/graphics"
import "CoreLibs/ui"
local pd <const> = playdate
 
function pd.update()
  if pd.isCrankDocked() then
    -- クランクがドックされている (収納されている) 場合はクランクインジケーターを描画します.
    pd.ui.crankIndicator:draw()
  else
    -- クランクをドックから取り出したときの処理.
  end
end

playdate.isCrankDocked()でクランクが収納されているかどうかを確認して、収納されている場合に取り出すことを促すために playdate.ui.crankIndicator:draw()で「クランクを使ってください」というUIを描画します。
クランク収納状態はコールバックで受け取りも可能ですが、UI表示するには「毎フレームの描画が必要」なので、特殊なことが不要であればplaydate.isCrankDocked()を使うのが簡単だと思います。

関数一覧

draw(xOffset?, yOffset?)

クランクインジケーターの次のアニメーションフレームを描画します。(→アニメーションをリセットする場合は、resetAnimation())
描画には毎フレームの呼び出しが必要なので、通常は playdate.update() 内で呼び、表示を止めたい場合は draw() の呼び出しを止めます。
なお、引数 xOffset, yOffset で描画位置を少しずらせます。

sprite を使っている場合は、通常は最前面に表示するので、 playdate.graphics.sprite.update() の後に呼びます。

playdate.graphics.sprite.update() -- spriteの描画.
crankIndicator:draw() -- spriteよりも手前に描画.

向いている用途

チュートリアルでクランク操作を促す
一定時間入力がないときにヒント表示
クランクが必須なギミック直前の案内
最初の数秒だけ右下に案内を出す

getBounds(xOffset?, yOffset?)

クランクインジケーターが描かれる範囲を取得します。
戻り値は、(x, y, width, height) です。

resetAnimation()

クランクインジケーターのアニメーションをシーケンスの先頭に戻します。
主に繰り返し表示・非表示を繰り返す場合、アニメーションをリセットしたほうが自然に見える場合があるのでそのための用途です。

リセットタイミングとしては、例えばクランクが収納されたタイミングで発生するコールバック playdate.crankDocked() で行うケースが考えられます。

Playdate 非公式開発まとめ wiki