Playdate.datastore initial folder

My game has some initial data it reads on load. The file is located in the datastore. However, when testing with the simulator I'm able to just go to the data folder and put it there.

Now that I have the actual hardware, I'm not sure how or where to put the data. Do I have to create this file through code? Or can I just place the file there myself?

What I've done:
I've looked through the pdxinfo meta data setup in the sdk documentation, but I don't see anything that refers to the datastore...

What am I missing?

playdate.datastore writes to the Data > [your game's bundle ID here] folder on hardware. you can get to this folder by connecting your Playdate to your computer over USB, and then going into Settings > System and selecting Reboot to Data Disk. More info

You can put a file in there by visiting that folder using the steps mentioned above, and dropping the file in manually. It would be worth it in your final game to initialize the file using code - saves a lot of unnecessary hassle on the player's end, and is easy to pull off anyhow. What I do to create save data in my game, is to first check for an existing save file. If it's not there, I tell it to initialize a lua table with all of my needed save variables in there, set to their default values. Then, I use playdate.datastore.write() to save those to a file on disk.

For example, putting something like this in my game code:

if == nil then
    local foo = {
        a = 1,
        b = 2,
        c = 3,
        d = false

...would result in a "data.json" file being created when my game starts (so long as it doesn't find an already-existing copy of that file) within Data > [my game's bundle id], containing some JSON that looks like this:


...that I can then read from using

Hopefully this helps out!


The primary purpose of the datastore is to save data on the user's device, e.g. for highscores, savegames, or caching.

If you want to load a file that you distribute alongside your game, you probably want to use the file or json APIs.

For example, you could create a subfolder source/maps/. Into that folder, you drop the file level01.json with this content:

  "name": "The Beginning",
  "tiles": [
    [0, 1, 0],
    [1, 0, 0],
    [1, 0, 1]

Then you can use json.decodeFile to load that data at game start:

---@class level
---@field name string
---@field tiles integer[][]

local level = json.decodeFile("maps/level01.json") --[[@as level]]
---                ^^^^^^^^^^

function pd.update()

    gfx.drawText(, 20, 20)
    ---          ^^^^^^^^^^ writes "The Beginning"

And, unlike anything in the datastore, the file level01.json will be compiled into your .pdx, so it'll be available on your user's device.

(You don't have to do any of the type annotation stuff if you don't want to; that's just what I do.)

1 Like

@stuffbyrae, ok makes sense. I do have a way to prgramatically create the file on boot. It's out of date. As the game grew I just found it easier to update the file manually.

@balpha, I was thinking last night of something like this. Just put my files I already have into their own sub folder. Although, I didn't know that json.decodeFile was a thing I'll have to take a look.

Since I already have the base to do what @stuffbyrae suggested I think I'll go that way for now.

Thanks ^...^

1 Like

@balpha, just for kicks I tried it out and I like it, but I have a problem that maybe your figured out on your end.

when my json is decoded I lose it's type. So all of the intellisense doesn't work. Is there away to tell it hey I'm decoding the file and it's this type to get it back?

Yeah, that's pretty much what the type annotations in my example code do -- tell the IDE what the type of the JSON is.

I'm pretty new to Lua, but those annotations are what the Lua Language Server uses (Annotations · LuaLS/lua-language-server Wiki · GitHub) which in turn is what VS Code uses. If you use another IDE, I assume it works as well, but I don't know for sure.

1 Like

Ah ok I didn't connect the dots. I thought it was just a comment. Thanks again.