Lua type annotations

[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 !

[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.

[Siroh]

Many thanks for your quick reply.
https://github.com/wesnoth/wesnoth/tree ... ua/wesnoth is exactly what I had in mind !

[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.

[Ravana]

It does not change anything in c++, so you dont have to wait for merge, just take the files if you want.

[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.

[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]

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]

Another one : it seems that the definitions for

Code: Select all

interface.remove_item
interface.add_item_halo

are missing in wesnoth/interface.lua

[Celtic_Minstrel]

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.

[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 ?

[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…

[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.

[Siroh]

Thank you very much !

[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