Lua type annotation file for the SDK

SDK Development Discussion
,
1

[Update Nov 6, 2023]

Panic has given permission for me to share this project. You can find it here: GitHub - balpha/playdate-types: Type annotations for the Playdate Lua SDK

[Original post follows]

TL;DR

I'm working on a Lua type annotation file which (at least in VS Code) gives you improved autocompletion, optional type checking, and documentation on hover for the various SDK functions.

It's still work-in-progress, but it's already in a state were I find it very helpful. Therefore, I would like to share this file with the community soon.

However, because this file is generated from the SDK documentation (in particular contains a lot of text from Inside Playdate), I cannot make it public without express permission from Panic.

Because I'm hoping that Panic won't have any problems with this, but I just need them to state it explicitly, I thought I'd use the forum for this.

In addition, if anyone else has thoughts/feedback on the idea of this type annotation file, I'd love to hear about it as well!

The long version

The file __stub.lua included as part of the SDK contains stub function definitions for many of the SDK functions. But it doesn't contain everything (e.g. it's missing the various constants like kColorBlack), has no type information for function parameters or return types, and has no built-in documentation that could be shown by the IDE.

My file __types.lua can be dropped in the same folder as __stub.lua, and the Lua language server (which is used by VS Code) will immediately pick up the information and make it available for development.

Here are two example screenshots of the same code with and without my type file:

A "before" screenshot of Visual Studio Code that contains no helpful popup information for the hovered function and doesn't highlight an incorrect parameter type, and an "after" screenshot that shows documentation and detailed parameter types for the functions, and highlights the error.
A "before" screenshot of Visual Studio Code that contains no helpful popup information for the hovered function and doesn't highlight an incorrect parameter type, and an "after" screenshot that shows documentation and detailed parameter types for the functions, and highlights the error.810×701 67.2 KB

This type annotation file is generated from the "Inside Playdate" file through a mix of automation and manual intervention.

In particular, in order to show the function documentation, it includes a significant amount of the text from "Inside Playdate" verbatim.

The SDK License says that

You will not: [...]

  • Modify, adapt, alter, translate, or incorporate into or with other software or create a derivative work of any part of the SDK, except as permitted herein, without express written permission from Panic

and my __types.lua file clearly falls under this provision.

I would love to get your (Panic's) permission to publish the file on GitHub.

I was thinking of a blurb along the lines of this:

The file __types.lua ("the File") was generated by Benjamin Dumke-von der Ehe ("the Author") based on the SDK documentation, which is published by Panic Inc. under the Playdate SDK License. Panic is not involved in the creation of the File and does not take any responsibility for its completeness or correctness. But Panic has given permission for this file to be published by the Author, and for the File to be used by anyone, as long as it's used under the same conditions as the Playdate SDK itself, as laid out in the Playdate SDK License.

Is that okay?

16 Likes
2

If this types file is helpful we could roll it into the SDK. How do you generate it?

8 Likes
3

I'm building a very ugly script which I drop into the browser's JS console and that goes through all DOM elements of class function, method, or callback. It grabs the function definition (including the associated documentation text) and tries a bunch of heuristics to find types.

For example, if a function name starts with is, followed by an uppercase letter, it returns a boolean. If the documentation contains the words "returns a string", then it, well, returns a string. If a parameter is called x or length, it's a number. If it's called alignment it's a pd_alignment (which is what I'm calling that enum-ish type). And so on.

And for stuff that the heuristics can't figure out, I have a big (in-progress) list of hardcoded parameter and return types.

Finally there's a bunch of manual stuff I've added like the various enum constants (kDitherTypeXXX etc.) and the super types like pd_effect.

All of that together, formatted as Lua annotations, is copied to the clipboard so I can paste it into __types.lua.

2 Likes
4

The file is pretty complete now, at least in a beta testing state. Happy to share it with any Panic employee who wants to take a look.

7 Likes
5

This is the magic I've been looking for!

4 Likes
6

Honestly? For me it's been a game changer (no pun intended) as I've been working on my own game.

Lua is a dynamic language, and there's definitely advantages to that, but being notified of typos and bugs, and getting in-IDE info on function signatures, has made my life so much easier.

I would love to share it with anyone else who would prefer a little more type safety.

4 Likes
7

I'm used to much more mature languages and tooling than Lua has to offer. I'm finding the lack of safety nets like precompile hinting really frustrating.

I'll be looking forward to trying this.

3 Likes
8

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
9

I wonder if this would work with Nova editor?

1 Like
10

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
11

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?

12

No, I haven't received an official reply.

16

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.

Screen shot 2023-09-11 at 15.00.49
Screen shot 2023-09-11 at 15.00.491584×804 107 KB

17

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

18

Nova doesn't use a lua language server internally.

1 Like
19

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

20

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

5 Likes
21

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

22

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.

1 Like
24

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