Feature Request: LLS LuaCATS docs

[SlashScreen]

Would it be possible to create a LLS plugin with types generated from Godot docs XML?

[gilzoide]

Hey @SlashScreen thanks for the request.

Yes, that's certainly possible. I think we wouldn't really need the XML docs for this, we could generate type annotations directly from Godot using ClassDB's reflection and/or the extension_api.json file. This way we would have typing for all Variants as well as classes. Of course, if we do want documentation as well as the type annotations, then the XML would come in handy. Not sure how to get docs for Godot classes though, other than getting XML files from Godot repo 🤔

By the way, I'm not super familiar with LuaCATS, although I already used LLS with type annotation scripts before. Not sure how this should be formatted to work and if it should live in a separate repository or if it should be distributed along with the Lua GDExtension addon itself.

[SlashScreen]

Not sure how this should be formatted to work

See docs

if it should live in a separate repository or if it should be distributed along with the Lua GDExtension addon itself

Typically I see them distributed as1 an LLS "plugin" which is mostly just a submodule with the files in it.

[DragoonKiller]

@gilzoide Providing a standalone ---@meta file with some ---@class for godot builtins could cover the requirement and stay neat IMO. Users can easily adapt it to multiple IDEs, or redistribute to somewhere like, LLS plugins, or so.
I would prefer creating a new project only for generating the file.

[gilzoide]

Providing a standalone ---@meta file with some ---@Class for godot builtins could cover the requirement and stay neat IMO. Users can easily adapt it to multiple IDEs, or redistribute to somewhere like, LLS plugins, or so.

Ok, nice.

I would prefer creating a new project only for generating the file.

And I would prefer reusing the infrastructure that's already present in this repository to generate such file. We could distribute it apart from the addon, but I think it may make sense to distribute everything together. People can then choose whether or not to import LLS meta files to their projects. If LLS can understand this meta file without any additional configuration, just by the file being present in the project, it would be a nice UX.

[SlashScreen]

A project I work on uses GitHub actions to automatically generate the meta files and push to a separate repository, so it can be done.

…

Message ID: ***@***.***>

[gilzoide]

Hey everyone, I created branch feature/lua-language-server-support as a WIP for LLS support in Lua GDExtension.

It generates some Lua files inside the addons/lua-gdextension/lua_api_definitions folder (so they are distributed in the build) with the Lua API using LLS annotations. There is also a .luarc.json file being distributed that adds this folder to the workspace.library setting.

I did the best I could to make Variant type annotations useful. As you may or may not know, each Variant type (like the global object Vector2 or Rect) is an instance of the C++ type VariantType, while instances of them (like a Vector2(1, 2) or a Dictionary()) are instances of C++ Variant. To make LLS accept calls of static and instance methods correctly, I marked that the variant types inherit from Variant itself, but each one declares whatever fields and methods they support, even though this is not exactly how it is implemented (everything is dynamically dispatched for simplicity in the implementation).
The same is true for String and StringName, Lua GDExtension automatically converts them to/from Lua's string, and their functions are actually callable from string itself via its metatable. But to make LLS understand this, I just marked the methods as belonging in string directly.

It isn't perfect yet, of course. For example, accessing fields in Dictionary using . (some_dict.key) is giving me warning about how that key doesn't exist, even if I didn't mark the Dictionary class as (exact). Not sure how to change the annotations to make this possible... Anyway, we can fix that yet, I'm open to suggestions.

If anyone wants to test, you can download a prebuilt version of the latest commit here.
Please let me know if you have any feedback about it.

Cheers \o/

[SlashScreen]

IIRC, you can mark a type as something like [key_type] value_type

[gilzoide]

Nice, I think I got it working! Thanks @SlashScreen \o/

The way to do that is mark the class to "inherit" from { [key_type]: value_type }. I added such markup to all Variant types that are indexable (this information is present in extension_api.json) and all Godot Object classes, since they could have scripts that define the used keys.

[gilzoide]

Hi everyone, I opened a PR with what I think is a usable version of LLS support for Lua GDExtension. As I already mentioned, it consists in a .luarc.json file at the root of the package (so that it gets installed in your project root) and Lua definition files. Most of them are autogenerated from extension_api.json, but there are now 2 of them manually written that cover extra functionality defined directly in Lua GDExtension.

If you folks could please test it and report any feedbacks you have, it would be really helpful.

[DraconicMentalist]

Compiled the branch and started testing today. Autocomplete works, and I've encountered no issues so far. Will report if any bugs or rough edges crop up!

[gilzoide]

Thanks for testing @DraconicMentalist! I merged the PR into main, which closed this Issue, but all of you feel free to either reopen it or create new ones you find enhancements or fixes that should be done on top of the currently existing LLS setup.
Cheers \o/