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

playdate

playdate
関連ページ

フィールド一覧

argv: string[]

playdate.isSimulator: boolean

シミュレーターでの実行中かどうか。実機動作中は無効となります。

if playdate.isSimulator then
    print("Simulatorで実行中")
else
    print("実機で実行中")
end

キー定数

kButtonLeft: integer = 1
kButtonRight: integer = 2
kButtonUp: integer = 4
kButtonDown: integer = 8
kButtonB: integer = 16
kButtonA: integer = 32

metadata: _Metadata

systeminfo: _SystemInfo

1. フレーム更新・実行制御

update()

Playdate OS が毎フレーム呼ぶメイン更新コールバックです。
ゲームロジック、入力処理、タイマー更新、描画などの中心になります。

実質的にゲームループ本体を記述します
通常はここで timer.updateTimers() やスプライト更新などを呼びます
処理が重すぎるとフレームレートが落ちます
OS は可能な限り呼びだされますが、上限は display.getRefreshRate() 相当です

start()

update() の毎フレーム呼び出しを再開します。

stop() で止めた更新を再開する用途。
常時更新が不要なアプリやツール系で使うことがある。

stop()

update() の毎フレーム呼び出しを停止します。

ボタン入力時だけ処理したいような、イベント駆動寄りの作りで有効。
display.flush() と組み合わせて、必要なときだけ画面を更新する使い方が想定されている。

wait(milliseconds)

指定ミリ秒のあいだ update() の呼び出しを一時停止します。

簡易ウェイト。
ただし animator は停止しないという注意点がある。
timer.updateTimers() を update() 内で回している構造なら、通常タイマー更新も止まるが、animator 側は別挙動になりうるため注意。

restart(arg)

ゲームを再起動します。

引数として再起動時の引数配列を渡せる。
開発中の再初期化や、状態をリセットしてタイトルに戻すような特殊制御で使う余地がある。

2. ボタン入力イベントコールバック

これらはイベント型コールバックです。
buttonIsPressed() などのポーリング型と違い、「押された瞬間」「離した瞬間」に OS が呼びます。

これらのボタンコールバックは、
setButtonQueueSize(size) を有効にするとイベント時刻が引数として渡される動作になる旨が stub に書かれています。
通常は引数なしで扱う前提で考えてよいですが、入力の取りこぼしや精密な時刻管理をしたい場合に関係します。

AButtonDown()

Aボタンが押された直後に呼ばれます。

決定、ジャンプ、攻撃などの主アクション向け。
1回押下で1回だけ反応させたい処理に向く。

AButtonHeld()

Aボタンを 1秒間押し続けた後に呼ばれます。

長押しによる副次操作向け。
コメントには「ワールドマップ表示」「武器切り替え」などの例がある。
通常押しと長押しを分離したいときに便利。

AButtonUp()

Aボタンが離された直後に呼ばれます。

チャージショットの発射、ドラッグ終了のような「離した時点で確定」処理向け。

BButtonDown()

Bボタンが押された直後に呼ばれます。

BButtonHeld()

Bボタンを1秒押し続けた後に呼ばれます。

Aと同様、長押しによる副操作を割り当てられる。

BButtonUp()

Bボタンが離された直後に呼ばれます。

upButtonDown()

十字キー上が押された直後に呼ばれます。

upButtonUp()

十字キー上が離された直後に呼ばれます。

downButtonDown()

十字キー下が押された直後に呼ばれます。

downButtonUp()

十字キー下が離された直後に呼ばれます。

leftButtonDown()

十字キー左が押された直後に呼ばれます。

leftButtonUp()

十字キー左が離された直後に呼ばれます。

rightButtonDown()

十字キー右が押された直後に呼ばれます。

rightButtonUp()

十字キー右が離された直後に呼ばれます。

3. ボタン状態取得（ポーリング）

buttonIsPressed(button)

指定ボタンを現在押しているかどうかを返します。
毎フレーム入力を見る基本関数で、押したフレームのみ判定したい場合は buttonJustPressed()を使用します。

引数 button は以下の定数または文字列を受け付ける

kButtonA
kButtonB
kButtonUp
kButtonDown
kButtonLeft
kButtonRight
または "a", "b", "up", "down", "left", "right"

用途

押しっぱなし移動
押している間だけUIを開く
同時押し判定

buttonJustPressed(button)

指定のボタンをこの更新フレームで押した場合に true を返します。
true になるのは 1フレームのみで、押したままの場合、毎フレーム true にはなりません。

押したままかどうかを判定するにはbuttonIsPressed()を使用します。

buttonJustReleased(button)

指定ボタンがこの更新フレームで離された場合のみ true を返します。

true は1フレーム限定。
押して離した瞬間を update() 側で扱いたい場合に使う。

用途

溜め攻撃の確定
UIドラッグ完了
「ボタンを離したら実行」の操作

getButtonState()

現在のボタン状態をまとめて取得します。

個別に buttonIsPressed() を何回も呼ぶ代わりに使える。
複数ボタンの状態をまとめて処理したい場合向け。

stub だけでは返り値の細かい構造説明は薄めですが、用途としては「現在押下中・押した瞬間・離した瞬間」系を一括で扱うための API です。

4. クランク関連

cranked(change, acceleratedChange)

クランクが回されたときに呼ばれるコールバックです。

change は角度変化量（度数）
acceleratedChange は、回す速度が速いほど増幅される値
反時計回りは負の値

使い分け

正確な物理角度やダイヤル操作: change
スピード感のあるUIやスクロール: acceleratedChange

getCrankChange()

前フレームからのクランク回転量を返します。

cranked() コールバックを使わず、update() 内でポーリングしたいときに使いやすい。
クランク入力を他の入力処理と同じ場所にまとめたい場合に向く。

getCrankPosition()

現在のクランク角度を返します。

絶対角として取得する用途
ノブ、ダイヤル、向き制御、円形UIに向く

注意点

度数法なので「0〜360」の値。360以上で0に戻ります
「上:0度右:90度下:180度左:270度」のコンパス的な座標系です

getCrankTicks(ticksPerRevolution)

クランク1周を指定数に分割した「tick」として回転量を取得します。

たとえば 12 を指定すれば 30度ごと、24 なら 15度ごとの段階入力にしやすい。
連続値より段階的UI に向く。

crankDocked()

クランクが収納されたときに呼ばれます。

クランク前提UIから通常UIへ切り替えるなどに使える。
ドッキング中はクランク操作を期待しないモードへ遷移させるのが自然。

crankUndocked()

クランクが引き出されたときに呼ばれます。

初回チュートリアル表示
クランクモード開始
BGMや演出切り替え

などに使える。

isCrankDocked()

現在クランクが収納状態かを返します。
毎フレーム分岐したい場合の判定用で、コールバックだけでなく現在状態を見たいときに使います。

setCrankSoundsDisabled(disable)

システム標準のクランク収納・展開サウンドを無効化/有効化します。

ゲームの世界観に合わない場合に消せる。
ゲーム終了時には自動的に元へ戻る。

5. 加速度センサー

startAccelerometer()

加速度センサーを開始します。

センサーはデフォルトで停止しており、省電力のため必要時に有効化する設計。
傾き操作やシェイク検出前に呼ぶ。

stopAccelerometer()

加速度センサーを低電力アイドル状態に戻します。

コメント上は「実際には消費差はかなり小さい」としつつも、使わないなら止められる。

accelerometerIsRunning()

加速度センサーが現在動作中か返します。

二重開始防止や状態確認に使える。

readAccelerometer()

加速度センサー値を読み取ります。

端末の傾き、振動、動きを取得する中心API。
stub上では詳細な戻り値の説明はここでは省略的ですが、通常は軸ごとの値を受け取る前提で使います。

6. 日時・時刻・エポック変換

Playdate のエポックは一般的な UNIX epoch ではなく、
2000年1月1日 00:00:00 UTC 基準の秒・ミリ秒系として扱われます。

getTime()

現在のローカル日時をテーブルで返します。

年月日、時分秒などを持つ日時テーブル。
プレイヤー環境のローカル時刻ベース。

getGMTTime()

現在の GMT/UTC日時をテーブルで返します。

ローカル時刻でなく、標準時ベースでログや同期処理に使いやすい。

getCurrentTimeMilliseconds()

現在時刻のミリ秒値を取得します。

高解像度な経過時間計測、処理時間測定、簡易プロファイル用。

getSecondsSinceEpoch()

Playdate epoch からの経過秒数を返します。

保存や比較に向く数値形式の時間。
日時テーブルではなく数値で扱いたいとき用。

timeFromEpoch(seconds, milliseconds)

エポック値をローカル日時テーブルに変換します。

保存済みタイムスタンプの表示用。
getTime() と同じ形式のテーブルに戻せる。

GMTTimeFromEpoch(seconds, milliseconds)

エポック値を GMT日時テーブルに変換します。

UTC基準の表示や比較に向く。

epochFromTime(time)

ローカル日時テーブルをエポック値に変換します。

日時テーブルから秒・ミリ秒に直して保存したいとき向け。

epochFromGMTTime(time)

GMT日時テーブルをエポック値に変換します。

UTC基準での一貫した比較・保存向け。

getServerTime(callback)

サーバー時刻を非同期取得し、結果をコールバックに返します。

本体時刻ではなくネットワーク側の基準時刻が必要な場合向け。
日替わりイベント、不正なローカル時計依存の回避などに役立つ。

shouldDisplay24HourTime()

システム設定が 24時間表示になっているか返します。

時計表示やUI整形で使う。
12/24時間表記をユーザー設定に合わせたいときに重要。

7. バッテリー・電源・スリープ・ロック

getBatteryPercentage()

バッテリー残量をパーセンテージで返します。

残量表示
バッテリー低下時の演出削減
省電力モード切り替え

getBatteryVoltage()

バッテリー電圧を返します。

より低レベルな状態監視向け。
通常のゲームではパーセンテージの方が使いやすい。

getPowerStatus()

電源状態を返します。

充電中か、外部電源か、バッテリー駆動かなどの判定用途。
詳細構造は stub のここだけでは薄いが、「電源モードを見る関数」と理解してよいです。

setAutoLockDisabled(disable)

3分の自動ロックを無効化/有効化します。

音楽プレイヤー、放置表示アプリなどで有効。
ユーザー操作がなくても継続動作させたい場合に使う。
ただしゲームで常時無効化するのは慎重にすべき。

deviceWillLock()

デバイスがロックされるときに呼ばれます。

コメントでもセーブ処理の例が明示されています。
中断状態の保存、BGM停止、セッション終了処理に向く。

deviceDidUnlock()

デバイスがアンロックされたときに呼ばれます。

復帰後の再初期化
接続再確認
一時停止解除演出

などに使える。

deviceWillSleep()

バッテリー低下により低電力スリープへ入る前に呼ばれます。

非常終了に近い状況に備え、最低限の保存を行う余地がある。

8. ゲーム一時停止・終了ライフサイクル

gameWillPause()

ゲームが一時停止される前に呼ばれます。

メニュー遷移前の状態整理
一時停止演出
音の停止

gameWillResume()

ゲームが再開される前に呼ばれます。

pause中に失効した状態の復旧
入力ロック解除
表示再構築

gameWillTerminate()

ゲーム終了前に呼ばれます。

終了時セーブ
ログ書き込み
外部状態のクリーンアップ

に使える。

9. デバッグ・統計・パフォーマンス計測

clearConsole()

シミュレータのコンソールを消去します。

ログを見やすくしたいとき用。
実機向けというより開発支援。

drawFPS(x, y)

現在FPSを計算して画面上の (x, y) に描画します。

フレームレート確認用の簡易表示。
開発中に重さの目安を可視化できる。

getFPS()

現在の FPS を返します。

数値として監視したい場合に使う。
低下時に描画品質を切り替えるような適応設計にも応用可能。

getElapsedTime()

計測開始点からの経過時間を返します。

処理ブロックの実行時間測定
プロファイリング
ベンチマーク用

resetElapsedTime()

getElapsedTime() の計測基準をリセットします。

区間計測に使う。

getStats()

ランタイム統計情報を返します。

メモリや処理時間などの統計収集向け。
開発時の観測用途が中心。

setStatsInterval(seconds)

統計サンプルの収集間隔を設定します。

0 を指定すると統計収集を無効化。
細かく観測したいか、負荷を減らしたいかで調整する。

apiVersion()

現在の Playdate ランタイム API バージョンと、ランタイムがサポートする最小 API バージョンを返します。

SDK/ランタイム差異の確認向け。
互換性問題の切り分けに使える。

10. デバッグ描画オーバーレイ

debugDraw()

update() の直後に呼ばれ、ここで行った描画はデバッグオーバーレイとして表示されます。

通常描画の上に半透明で重ねる用途。
当たり判定、座標、AI状態、探索経路などの可視化に向く。
白ピクセルが setDebugDrawColor() の色で描かれ、黒ピクセルは透明扱い。

setDebugDrawColor(r, g, b, a)

debugDraw() オーバーレイの色を設定します。値域は 0～1。

デフォルトは半透明赤系。
種類ごとに色分けしたいときに便利。

11. ガベージコレクションとランタイム挙動

setCollectsGarbage(flag)

Lua の自動ガベージコレクションを Playdate ランタイム側で行うか設定します。

false にすると自動GC無効。
その場合は collectgarbage() を自前で回す必要がある。

用途

フレーム落ちしやすい場面で GC タイミングを明示制御したい場合。
ただし管理は難しくなる。

setGCScaling(min, max)

使用メモリ量に応じた GC 実行スケーリングを設定します。

余剰フレーム時間をどれだけGCに使うかの調整。
(0.0, 1.0) のようなスケールで、フレーム余裕があるほど GC を進める設計。
(0.0, 0.0) だと、利用可能な余剰時間をすべてGCに使う。

これはかなり低レベル寄りで、通常のゲームで頻繁に触るものではありません。

setMinimumGCTime(ms)

Lua GC を最低 ms ミリ秒は走らせるようにします。

ガベージが多いゲームでは GC 断片化や回収不足の調整に使える。
逆にゲーム処理を優先したいなら小さくする選択肢もある。

setButtonQueueSize(size)

ボタンイベントキューのサイズを設定します。

キューが有効な場合、ボタンup/downイベントが蓄積され、入力取りこぼし耐性に関係する。
コメント上では、キュー有効時にボタンコールバックへイベント時刻が渡されるとある。
高頻度入力や update 停滞時の精密な入力処理で意味がある。

setNewlinePrinted(flag)

print() の末尾に改行を自動で付けるか設定します。デフォルトは true。

ログ整形用途。
開発時の出力フォーマット調整向け。

12. システム設定・システムUI

getSystemLanguage()

システム言語を返します。

ローカライズ切り替え
言語別リソース選択
初期言語設定の自動化

getSystemMenu()

システムメニューオブジェクトを取得します。

一時停止メニューやシステムメニューへの項目追加などで使う基点。
Playdate の標準メニューに連携するための入口。

setMenuImage(image, xOffset)

ゲーム一時停止中のシステムメニューに表示する画像を設定します。

メニューがアニメーション表示される際に一緒に出るイメージ。
xOffset で表示位置を調整可能。
image = nil を渡すと解除。

用途

ロゴ表示
状況説明図
遊び方UIの補足

getSystemMenu()

setMenuImage()と同じくシステムメニュー取得です。重複定義ではなく、重要なのでこちらでも意味を強調すると、「Pause時の標準OS UIに自作項目を足すためのハブ」です。

getFlipped()

画面反転設定状態を返します。

display.setFlipped() で変更された状態の確認用途。
画面向きに応じてUIや座標系を変えたい場合に使う。

getReduceFlashing()

システムの点滅軽減設定を返します。

ユーザーのアクセシビリティ設定に従って演出を抑える判断材料。
強いフラッシュ演出を減らしたい場合に重要。

13. キーボード・シリアル・外部入力

keyPressed(key)

キー入力があったときに呼ばれます。

シミュレータや外部入力環境でのキーボード対応向け。
実機の通常ゲーム操作というより開発/補助入力寄り。

keyReleased(key)

キーが離されたときに呼ばれます。

keyPressed() と対で使う。

serialMessageReceived(message)

シリアルポートで msg {text} コマンドを受信したときに呼ばれます。

pdutil などから送ったメッセージを受け取る用途。
デバッグコマンド、リモート操作、テスト入力に使える。
実機接続時はデバイスへ、未接続ならシミュレータ中のゲームへ送られる。

14. ミラーリング関連

mirrorStarted()

画面ミラーリングが始まったときに呼ばれます。

配信・外部表示向けにUI調整するなどの用途が考えられる。

mirrorEnded()

画面ミラーリングが終了したときに呼ばれます。

ミラーリング専用表示の解除や状態復帰に使える。

資料：実用上の位置づけが大きい関数

実務的には、playdate 直下で最もよく触るのは次の系統です。

日常的に使う

update()
buttonIsPressed()
buttonJustPressed()
buttonJustReleased()
getCrankChange()
getCrankPosition()
isCrankDocked()

機能次第で使う

startAccelerometer()
readAccelerometer()
getTime()
getSystemMenu()
setMenuImage()

開発・最適化で使う

drawFPS()
getFPS()
getStats()
setCollectsGarbage()
setGCScaling()
setMinimumGCTime()

ライフサイクル対応で重要

gameWillPause()
gameWillResume()
gameWillTerminate()
deviceWillLock()
deviceDidUnlock()

Playdate 非公式 開発まとめ wiki

API > playdate

メニュー

その他

外部リンク

更新履歴

人気のページ

playdate

フィールド一覧

argv: string[]

playdate.isSimulator: boolean

キー定数

metadata: _Metadata

systeminfo: _SystemInfo

1. フレーム更新・実行制御

update()

start()

stop()

wait(milliseconds)

restart(arg)

2. ボタン入力イベントコールバック

AButtonDown()

AButtonHeld()

AButtonUp()

BButtonDown()

BButtonHeld()

BButtonUp()

upButtonDown()

upButtonUp()

downButtonDown()

downButtonUp()

leftButtonDown()

leftButtonUp()

rightButtonDown()

rightButtonUp()

3. ボタン状態取得（ポーリング）

buttonIsPressed(button)

buttonJustPressed(button)

buttonJustReleased(button)

getButtonState()

4. クランク関連

cranked(change, acceleratedChange)

getCrankChange()

getCrankPosition()

getCrankTicks(ticksPerRevolution)

crankDocked()

crankUndocked()

isCrankDocked()

setCrankSoundsDisabled(disable)

5. 加速度センサー

startAccelerometer()

stopAccelerometer()

accelerometerIsRunning()

readAccelerometer()

6. 日時・時刻・エポック変換

getTime()

getGMTTime()

getCurrentTimeMilliseconds()

getSecondsSinceEpoch()

timeFromEpoch(seconds, milliseconds)

GMTTimeFromEpoch(seconds, milliseconds)

epochFromTime(time)

epochFromGMTTime(time)

getServerTime(callback)

shouldDisplay24HourTime()

7. バッテリー・電源・スリープ・ロック

getBatteryPercentage()

getBatteryVoltage()

getPowerStatus()

setAutoLockDisabled(disable)

deviceWillLock()

deviceDidUnlock()

deviceWillSleep()

8. ゲーム一時停止・終了ライフサイクル

gameWillPause()

gameWillResume()

gameWillTerminate()

9. デバッグ・統計・パフォーマンス計測

clearConsole()

drawFPS(x, y)

Playdate 非公式開発まとめ wiki