Lua type annotation file for the SDK


This would be a massive help for guys like me - plenty of coding experience but none in Lua and none on Playdate. I always have 2 (or 5) windows open to the docs.

Big +1 for Panic approving this, and thank you for the effort!

1 Like

I wonder if this would work with Nova editor?

1 Like

I don't know (and I'm not Mac user, so I can't test), but according to their documentation, Nova is aware of language servers, which makes it seem likely to me that Nova's Lua support is based on the Lua Language Server. In that case, annotations should be supported.

If you use Nova, you should be able to quickly test it. Put this in a Lua file:

---This is documentation
---@param x number
local function f(x) end

f("not a number")

and check that 1) it complains about the incorrect argument type, and 2) it shows you "This is documentation" when you hover the function (assuming that's when Nova usually shows such things).

1 Like

Were there any further developments on this? It sounds like an extremely useful thing to have. Did it get rolled up into the SDK somewhere?

No, I haven't received an official reply.

I tried this in Nova and it didn't do anything, sadly.

App setting are as follows, which indicate it needs to be wrapped as an extension?
So, I imagine it would become part of Nova's Playdate Extension.

Hmm, strange. Maybe they're using a different (home-grown?) language server then? The canonical one ( is what powers the VSCode Lua extension, and annotations work great with it.

Nova doesn't use a lua language server internally.

1 Like

Ah ok, thanks. In that case, I'm afraid this won't work in Nova, at least not out-of-the-box.

Is there any update on this being released? Would love to use it!


Same here, it would be super helpful! @balpha you can't post the file here either, without explicit approval from Panic?

Sorry, but I'm not willing to take that legal risk. It would be a clear violation of the SDK license, and the fact that Panic has remained silent (after an initial message from @james) leads me to believe that sadly they do not want to give that permission. It's their choice, ultimately.

That said, @notpeter was less risk-averse and has posted a very similar project at Playdate-LuaCATS: VSCode autocomplete, types and inline Playdate SDK documentation. Maybe that's helpful for you.

Yes of course I understand! But thanks so much for pointing out to that post, it sounds just like what I need :slight_smile:

@balpha if you were to share the tool you use to build the file and provide instructions for how to use it, would that change anything?

That way, you wouldn’t be distributing anything that’s not your own work. It might still be considered a derived work though.

@balpha We've discussed this at Panic and we give you express written permission to distribute this file. Thanks for the work, it will be very helpful to a lot of folks! :slight_smile:


Thank you @willco, that's great news!

I've now made the repository public: GitHub - balpha/playdate-types: Type annotations for the Playdate Lua SDK

(The generator code, for anyone curious, is at GitHub - balpha/playdate-types-generator)


Just started using these annotations and they're life-changing! Thank you so much @balpha :pray:t3:
@willco would it be possible to have them directly in the SDK, so that they would be immediately accessible to everyone using it? Rather than having to dig into the forum to find this post :sweat_smile: If @balpha is ok with it of course!


We've talked about adding these directly to the SDK but aren't quite ready to commit more resources to VS Code. :slight_smile: We do realize it's a popular editor but we are a very small team.

The annotations aren't just for VS code! The Lua language server is a standard used by many editors. It would be really great to have proper annotations.


Good point. There are 10s of them. :slight_smile: