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

playdate.timer

playdate.timer は、時間経過に応じて処理を実行するためのタイマーです。
用途は大きく分けて3つです。

-- 1. 一定時間後に処理する
playdate.timer.performAfterDelay(1000, function()
   print("1秒後")
end)
 
-- 2. 時間に応じて値を変化させる
local t = playdate.timer.new(1000, 0, 100)
 
-- 3. 一定間隔で繰り返し処理する
local t = playdate.timer.new(500, function()
    print("repeat")
end)
t.repeats = true

重要なのは、playdate.timer.updateTimers() を playdate.update() 内で呼ばないとタイマーが進まないことです。

function playdate.update()
    playdate.timer.updateTimers()
end

playdate.timer
関連ページ

生成関数

new(duration, callback, ...)

指定時間後に callback を呼ぶタイマーを作成します。

カテゴリ	名前	型	省略	説明
引数	duration	integer	x	呼び出す時間 (ミリ秒)
	callback	function(args)	x	duration経過後に呼び出す関数
	args	any	o	functionの引数
戻り値	-	playdate.timer	x	作成したタイマー

第3引数以降を渡すと、タイマー終了時に callback へ渡されます。

-- コールバック引数指定.
playdate.timer.new(1000, function(message)
    print(message)
end, "finished")

第3引数以降を渡さない場合、callback には timer 自身が渡されます。

-- コールバック引数なし (timer自身が引数).
local timer = playdate.timer.new(1000, function(t)
    print(t.duration)
end)

注意点: timer は作成直後に自動で開始します。; 新規作成後に start() を呼ぶ必要はありません。

new(duration, startValue, endValue, easingFunction)

指定時間をかけて value を startValue から endValue へ変化させるタイマーを作成します。

カテゴリ	名前	型	省略	説明
引数	duration	integer	x	endValueまでの到達時間 (ミリ秒)
	startValue	number	o	開始値
	endValue	number	o	終端値
	easingFunction	function	o	変化に使うイージング関数? (→EasingFunctions) 省略時は線形補間となります

-- 1秒 (1000ms) かけて、timer.value を 0 から 100 に変化させる.
local timer = playdate.timer.new(1000, 0, 100)

performAfterDelay(delay, callback, ...)

指定時間後に一度だけ callback を実行します。

カテゴリ	名前	型	省略	説明
引数	delay	integer	x	発生遅延時間 (ミリ秒)
	callback	function(args)	x	遅延時間後の呼び出し関数
	args	any	x	callbackの引数

-- 0.5秒 (500ms) 後に実行.
playdate.timer.performAfterDelay(500, function()
    print("0.5秒後")
end)

遅延実行したい場合これが手軽ですが、後から pause() / remove() / reset() したい場合は、playdate.timer.new() で timer を保持する方が扱いやすいです。

keyRepeatTimer(callback, ...)

キーリピート用の timer を作成します。
リピート間隔を決めたい場合はkeyRepeatTimerWithDelay()を使用します。

カテゴリ	名前	型	省略	説明
引数	callback	function(args)	x	キーリピートで実行する関数
引数	args	any	o	callbackの引数

標準値として以下が使われます。

delayAfterInitialFiring = 300
delayAfterSecondFiring = 100

つまり、

callback を即時実行
300ms 後にもう一度実行
以後 100ms 間隔で繰り返し実行

という挙動です。

-- キーリピートタイマー.
local repeatTimer = nil
 
function playdate.update()
    -- タイマー更新.
    playdate.timer.updateTimers()
 
    if playdate.buttonJustPressed(playdate.kButtonRight) then
        -- 右キーを押したらX方向に+1する関数を登録.
        repeatTimer = playdate.timer.keyRepeatTimer(function()
            cursorX += 1
        end)
    end
    if playdate.buttonJustReleased(playdate.kButtonRight) then
        -- 右キーを離したらX方向移動関数を解除.
        repeatTimer:remove()
        repeatTimer = nil
    end
end

メニューカーソル移動、文字入力、リストスクロールなどに向いています。

keyRepeatTimerWithDelay(delayAfterInitialFiring, delayAfterSecondFiring, callback, ...)

キーリピートの初回遅延・2回目以降の間隔を指定して timer を作成します。
keyRepeatTimer() のリピート間隔指定バージョンです。

カテゴリ	名前	型	省略	説明
引数	delayAfterInitialFiring	integer	x	初回遅延 (ミリ秒)
	delayAfterSecondFiring	integer	x	2回目以降の遅延 (ミリ秒)
	callback	function(args)	x	キーリピートで実行する関数
	args	any	o	callbackの引数

local timer = playdate.timer.keyRepeatTimerWithDelay(
    500,
    50,
    function()
        cursorY += 1
    end
)

標準より遅く開始して、開始後は速く連続入力したい場合などに使えます。

更新・一覧

playdate.timer.updateTimers()

すべての timer を更新します。

これを playdate.update() 内で呼ばないと、timer は進みません。
remove() された timer は、即座に完全削除されるのではなく、次回 updateTimers() 時に削除されます。

function playdate.update()
    playdate.timer.updateTimers()
    -- sprite を使うならこちらも
    playdate.graphics.sprite.update()
end

playdate.timer.allTimers()

現在実行中の timer 一覧を返します。
デバッグや、残っている timer の確認に使えます。

カテゴリ	名前	型	説明
戻り値	-	playdate.timer[]	実行中のすべての timerの配列

for _, t in ipairs(playdate.timer.allTimers()) do
    print(t.timeLeft)
end

インスタンスメソッド

timer:pause()

timer を一時停止します。
pause() 中はそのタイマーの時間は進みません。

local timer = playdate.timer.new(1000, function()
    print("done")
end)
-- タイマーを一時停止.
timer:pause()

timer:start()

一時停止した timer を再開します。
新しく作った timer は自動で開始するため、作成直後に start() を呼ぶ必要はありません。

timer:reset()

timer を初期状態に戻します。

local timer = playdate.timer.new(1000, 0, 100)
-- 途中で最初からやり直す
timer:reset()

値補間の timerの場合、currentTime や value が開始状態に戻ります。

timer:remove()

timer を削除対象にします。
timer は remove() した瞬間に完全削除されるのではなく、次の playdate.timer.updateTimers() で実際に除去されます。

-- タイマー削除.
timer:remove()
-- 基本的に nil にしておくと安全
timer = nil

コールバック

timer:updateCallback()

timer が更新されるたびに呼ばれる callback です。

カテゴリ	名前	型	省略	説明
引数	callback	function(args)	x	timer更新時に呼び出すコールバック
引数	args	any	o	functionの引数

timer 作成時に追加引数を渡していない場合、callback には timer 自身が渡されます。

local timer = playdate.timer.new(1000, 0, 100)
-- 更新コールバックを登録.
timer.updateCallback = function(t)
    print(t.value)
end

timer 作成時に追加引数を渡した場合、その引数が渡されます。

local timer = playdate.timer.new(1000, function() end, "abc")
-- 更新コールバックを登録.
timer.updateCallback = function(arg)
    print(arg) -- "abc"
end

timer:timerEndedCallback(...)

timer 完了時に呼ばれる callback です。

カテゴリ	名前	型	省略	説明
引数	callback	function(args)	x	timer更新時に呼び出すコールバック
引数	args	any	o	functionの引数

local timer = playdate.timer.new(1000, 0, 100)
-- 終了コールバックを登録.
timer.timerEndedCallback = function(t)
    print("timer end")
end

playdate.timer.new(duration, callback) の callback と似ていますが、値補間 timer に対して後から終了 callback を設定したい場合に便利です。

主要プロパティ

playdate.timer には多くの状態プロパティがあります。

カテゴリ	プロパティ名	型	説明
状態	active	boolean	timerがアクティブかどうか
	paused	boolean	timerが一時停止中かどうか
	running	boolean	timerが実行中かどうか
	repeats	boolean	timer終了時に繰り返すかどうか
	reverses	boolean	逆再生する場合は true。 repeatもtrueだと ping-pong (往復アニメーション) となる
	reverseEasingFunction	function()	逆再生に使うイージング (→EasingFunctions)
	discardOnCompletion	boolean	再生完了時に自動破棄するかどうか
値補完	startValue	number	値補完の開始値
	value	number	値補完の現在値
	endValue	number	値補完の終端値
	easingFunction	function()	値補完に使うイージング (→EasingFunctions)
	easingAmplitude	number	elastic系で使う振り幅
	easingPeriod	number	elastic系などで使う周期
時間	currentTime	number	timer の現在経過時間 (ミリ秒)
	delay	number	開始までの遅延時間 (ミリ秒)
	duration	number	timerの長さ (ミリ秒)
	timeLeft	number	timer の残り時間
コールバック	updateCallback	function()	更新コールバック関数
	timerEndedCallback	function(args)	timer終了コールバック関数
	timerEndedArgs	args	timer終了コールバック引数

資料

1. 1秒後に処理する

playdate.timer.performAfterDelay(1000, function()
    print("1秒経過")
end)
function playdate.update()
    playdate.timer.updateTimers()
end

2. 値をなめらかに変化させる

local xTimer = playdate.timer.new(1000, 0, 200, playdate.easingFunctions.outCubic)
function playdate.update()
    playdate.timer.updateTimers()
    local x = xTimer.value
    playdate.graphics.fillCircleAtPoint(x, 120, 5)
end

3. 終了時に処理する

local timer = playdate.timer.new(1000, 0, 100)
timer.timerEndedCallback = function(t)
    print("animation finished")
end

4. 繰り返し処理する

local blink = playdate.timer.new(500, function()
    visible = not visible
end)
blink.repeats = true

5. 往復アニメーション

local timer = playdate.timer.new(1000, 0, 10, playdate.easingFunctions.inOutSine)
timer.repeats = true
timer.reverses = true
function playdate.update()
    playdate.timer.updateTimers()
    local offset = timer.value
end

6. キーリピート

local repeatTimer = nil
local cursor = 1
function playdate.update()
    playdate.timer.updateTimers()
    if playdate.buttonJustPressed(playdate.kButtonDown) then
        repeatTimer = playdate.timer.keyRepeatTimer(function()
            cursor += 1
        end)
    end
    if playdate.buttonJustReleased(playdate.kButtonDown) then
        if repeatTimer then
            repeatTimer:remove()
            repeatTimer = nil
        end
    end
end

timer と frameTimer の違い

playdate.timerは、実行をミリ秒単位で指定するため、時間基準の処理に向いています。

1秒後に処理
0.5秒で移動
300ms 間隔の点滅

それに対して、playdate.frameTimerは、フレーム単位で指定します。
そのため、フレーム数基準で制御したい場合に向いています。

30フレーム後に処理
10フレームだけヒットストップ
アニメーションフレーム制御

Playdate 非公式開発まとめ wiki