Lua type annotations

Discussion of Lua and LuaWML support, development, and ideas.

Moderator: Forum Moderators

Post Reply
Siroh
Posts: 9
Joined: February 19th, 2017, 9:36 pm

Lua type annotations

Post by Siroh »

Hi !

Do you know if there are some Lua type annotations (following this format https://luals.github.io/wiki/annotations/#class) available for the
LuaAPI exposed by the game engine. I would make developing UMC so much easier !

Thank you !
User avatar
Celtic_Minstrel
Developer
Posts: 2142
Joined: August 3rd, 2012, 11:26 pm
Location: Canada
Contact:

Re: Lua type annotations

Post by Celtic_Minstrel »

Those annotations are used throughout the parts of our Lua API that are implemented in Lua. The engine does nothing special with them, however – it's up to you to choose an editing program that supports them and set it up to recognize them correctly. I know Visual Studio Code's Lua plugin supports them; I think Sublime Text can also be set up to support them. I'm not sure if there are others.

The annotations as of master are not perfect (there's #7359 open with regards to fixing some of the issues) but they should be sufficient to provide reasonable completion suggestions in most contexts.

There's a brief guide on how to make VSCode recognize everything, but I'm not sure if it's up-to-date. That guide assumes you're working directly in a checkout of the Wesnoth source tree; if that's not the case, the path will need to be altered accordingly. If you only have a build of Wesnoth installed from Steam, Sourceforge, Flatpak, Itch.IO, etc, then you would need to download all the Lua files in that folder and place them somewhere on your hard drive that you can then point Visual Studio Code at. Those files exist solely to give annotations for parts of our Lua API that are implemented in C/C++.

If you're using an IDE other than Visual Studio Code, I would assume there is some similar setup required, but I'm afraid I don't know what it is.
Author of The Black Cross of Aleron campaign and Default++ era.
Maintainer of Steelhive.
Siroh
Posts: 9
Joined: February 19th, 2017, 9:36 pm

Re: Lua type annotations

Post by Siroh »

Many thanks for your quick reply.
https://github.com/wesnoth/wesnoth/tree ... ua/wesnoth is exactly what I had in mind !
Siroh
Posts: 9
Joined: February 19th, 2017, 9:36 pm

Re: Lua type annotations

Post by Siroh »

I've indeed seen some inaccuracies fixed by #7359, I'll give a second look when it's merged.
Thank you for providing these definitions.
User avatar
Ravana
Forum Moderator
Posts: 2916
Joined: January 29th, 2012, 12:49 am
Location: Estonia
Contact:

Re: Lua type annotations

Post by Ravana »

It does not change anything in c++, so you dont have to wait for merge, just take the files if you want.
User avatar
Celtic_Minstrel
Developer
Posts: 2142
Joined: August 3rd, 2012, 11:26 pm
Location: Canada
Contact:

Re: Lua type annotations

Post by Celtic_Minstrel »

I wouldn't recommend just taking #7359 wholesale, as some of the changes to code seem to be incorrect. Cherry-picking all the [LuaDoc]-tagged commits should be safe, however.
Author of The Black Cross of Aleron campaign and Default++ era.
Maintainer of Steelhive.
Siroh
Posts: 9
Joined: February 19th, 2017, 9:36 pm

Re: Lua type annotations

Post by Siroh »

I've have copied the files from #7359, and it works fine, thank you.

Except perhaps for this function :

Code: Select all

gui.widget.remove_items_at
(documented at https://wiki.wesnoth.org/LuaAPI/gui/wid ... e_items_at)
Since it is a replacement for the old

Code: Select all

wesnoth.remove_dialog_item
it seems to me that its signature should rather be

Code: Select all

gui.widget.remove_items_at(index, count)
That is, I think the count argument is missing.
Siroh
Posts: 9
Joined: February 19th, 2017, 9:36 pm

Re: Lua type annotations

Post by Siroh »

Another small fix I had to make in wesnoth/interface.lua is replacing

Code: Select all

---@type table<string, fun()>
wesnoth.game_display = {}
by

Code: Select all

---@type table<string, fun(): WMLTag[]>
wesnoth.interface.game_display = {}
Siroh
Posts: 9
Joined: February 19th, 2017, 9:36 pm

Re: Lua type annotations

Post by Siroh »

Another one : it seems that the definitions for

Code: Select all

interface.remove_item
interface.add_item_halo
are missing in wesnoth/interface.lua
User avatar
Celtic_Minstrel
Developer
Posts: 2142
Joined: August 3rd, 2012, 11:26 pm
Location: Canada
Contact:

Re: Lua type annotations

Post by Celtic_Minstrel »

Siroh wrote: February 7th, 2024, 11:50 am Another one : it seems that the definitions for

Code: Select all

interface.remove_item
interface.add_item_halo
are missing in wesnoth/interface.lua
Those ones are a little weird. They're actually defined in lua/wml/items.lua, since they access local variables in that file.

I'll make the other corrections you noted. Feel free to mention if there's anything else you find, too.
Author of The Black Cross of Aleron campaign and Default++ era.
Maintainer of Steelhive.
Siroh
Posts: 9
Joined: February 19th, 2017, 9:36 pm

Re: Lua type annotations

Post by Siroh »

Thank you !

I think the typing of gui.simple_widget.label is too restrictive : for instance, for image widget, the label is not a tstring, just a simple string.
Could it be changed to string|tstring ?
User avatar
Celtic_Minstrel
Developer
Posts: 2142
Joined: August 3rd, 2012, 11:26 pm
Location: Canada
Contact:

Re: Lua type annotations

Post by Celtic_Minstrel »

It's probably better for gui.image to override the field to string, I think. Though I guess that doesn't really solve the issue of getting a warning when you assign it… I guess I could make it string|tstring…
Author of The Black Cross of Aleron campaign and Default++ era.
Maintainer of Steelhive.
User avatar
Celtic_Minstrel
Developer
Posts: 2142
Joined: August 3rd, 2012, 11:26 pm
Location: Canada
Contact:

Re: Lua type annotations

Post by Celtic_Minstrel »

Just letting you know that I pushed several fixes to #7359, including the gui.simple_widget.label change you suggested. I also added |number to it, as there are probably use-cases where you want a label to just show a number, and we don't currently have functions to convert a number to a tstring.
Author of The Black Cross of Aleron campaign and Default++ era.
Maintainer of Steelhive.
Siroh
Posts: 9
Joined: February 19th, 2017, 9:36 pm

Re: Lua type annotations

Post by Siroh »

Thank you very much !
Siroh
Posts: 9
Joined: February 19th, 2017, 9:36 pm

Re: Lua type annotations

Post by Siroh »

Hi !

Could we add some typing to the terrain_map class, to support the map style read/write access to terrain codes ?

Updating the class definition to

Code: Select all

---@class terrain_map : wesnoth.map, {[{[1]:integer, [2]:integer}]: string}
should do the trick
Post Reply