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

playdate.datastore

playdate.datastore (データストア) は、ゲームごとの保存領域に Lua テーブルや画像を保存・読み込みするための簡易APIです。

-- セーブデータ保存
playdate.datastore.write({
    score = 1000,
    stage = 3,
    unlocked = { "stage1", "stage2" }
})
-- セーブデータ読み込み
local data = playdate.datastore.read()

通常の設定・セーブデータなら playdate.file を直接使うより、datastore の方が簡単です。

playdate.datastore
- Luaテーブルの読み書き
- 画像の保存・読み込み
  - playdate.datastore.writeImage(image, path)
  - playdate.datastore.readImage(path)
関連ページ

Luaテーブルの読み書き

write(table, filename, pretty)

Lua のテーブルを JSON として保存します。

カテゴリ	名前	型	省略	説明
引数	table	Luaテーブル	x	保存するLuaテーブル
	filename	string	o	保存ファイル名。(拡張子 ".json" は不要) 省略時は "data" という名前で保存されます
	pretty	boolean	o	true にすると、人間が読みやすい整形済み JSON になります。デバッグ中は true が便利です。製品版ではファイルサイズを少しでも減らすなら省略または false でよいです

コード例

-- 保存するテーブル.
local saveData = {
    highScore = 12345,
    currentStage = 4,
    soundEnabled = true
}
-- 保存実行.
playdate.datastore.write(saveData, "save", true)

注意点

保存できるのは JSON 化できる値です。

number
string
boolean
table

ユーザー定義型や関数、オブジェクトは保存できません。

また、画像は JSON 化できないため、画像保存には writeImage() を使います。

playdate.datastore.read(filename)

JSON で保存された datastore ファイルを読み込み、Lua テーブルとして返します。

カテゴリ	名前	型	省略	説明
引数	filename	string	o	読み込む datastore ファイル名。省略時は "data" を読み込みます
戻り値	table?	Luaテーブル	o	読み込んだLuaテーブル。ファイルが存在しない場合は "nil" を返します

コード例

-- デフォルトデータ.
local defaultSaveData = {
    highScore = 0,
    stage = 1,
    sound = true
}
-- セーブデータの読み込み.
local saveData = playdate.datastore.read("save")
if saveData == nil then
    -- 読み込みに失敗したらデフォルトデータを使用する.
    saveData = defaultSaveData
end

注意点

read() はファイルがないと nil を返すので、初回起動時の対策が必要です。

playdate.datastore.delete(filename)

指定した datastore ファイルを削除します。
セーブデータの初期化やデバッグ用にリセット処理として使用します。

カテゴリ	名前	型	省略	説明
引数	filename	string	o	削除する datastore ファイル名。省略時は "data" を読み込みます
戻り値	-	boolean	x	削除できたらtrue

画像の保存・読み込み

playdate.datastore.writeImage(image, path)

playdate.graphics.image を datastore の画像ファイルとして保存します。

カテゴリ	名前	型	省略	説明
引数	image	playdate.graphics.image	x	保存するImage
引数	path	string	x	保存先のパス。パスにフォルダ名が含まれていない場合、images フォルダ内に保存されます

デフォルトでは Playdate 独自の PDI形式で保存されます。

-- PDI (独自形式) で保存.
playdate.datastore.writeImage(img, "snapshot")

GIF として保存したい場合は、.gif 拡張子を付けます。

-- GIFとして保存する.
playdate.datastore.writeImage(img, "snapshot.gif")

GIF保存時の注意

writeImage() は現在 GIF の透明度をサポートしていないとされています。

そのため、画像バッファを自分で作って GIF として保存する場合は、背景色を明示する必要があります。

local img = playdate.graphics.image.new(
    400,
    240,
    playdate.graphics.kColorWhite
)
playdate.datastore.writeImage(img, "snapshot.gif")

背景色なしで作った画像を GIF にすると、期待通りに描画されない可能性があります。

playdate.datastore.readImage(path)

datastore の画像ファイルを読み込み、playdate.graphics.image として返します。

カテゴリ	名前	型	省略	説明
引数	path	string	x	読み込む画像パス。パスにフォルダ名が含まれていない場合、images フォルダから検索されます
戻り値	-	playdate.graphics.image?	o	成功時は image、失敗時は nil

重要な制限: readImage() はコンパイル済み PDI ファイルのみ読み込めます。; そのため、GIF として保存したものを readImage() でそのまま読み戻すことはできません。

Playdate 非公式開発まとめ wiki