Improve Lua type documentation and bindings.#21501
Conversation
|
That certainly beats the doc update I was scrounging together. 👌 |
|
That looks complementary - improved descriptions is always going to be a helpful addition. |
PunkPun
left a comment
PunkPun
left a comment
There was a problem hiding this comment.
this PR begs for unit testing. I'm not sure, should we manually try running all missions to test?
OpenRA.Mods.Common/Scripting/ScriptEmmyTypeOverrideAttribute.cs
Outdated
Show resolved
Hide resolved
|
The type definitions don't have any effect on the missions at all. They're purely a developer aid. So no need to test every mission manually, their behaviour will be the same as before anyway. |
RoosterDragon
force-pushed
the
emmy
branch
2 times, most recently
from
3ac3f39 to
c2af5f8
Compare
The ExtractEmmyLuaAPI utility command, invoked with `--emmy-lua-api`, produces a documentation file that is used by the [OpenRA Lua Language Extension](https://marketplace.visualstudio.com/items?itemName=openra.vscode-openra-lua) to provide documentation and type information is VSCode and VSCode compatible editors when editing the Lua scripts. We improve the documentation and types produced by this utility in a few ways: - Require descriptions to be provided for all items. - Fix the type definitions of the base engine types (cpos, wpos, wangle, wdist, wvec, cvec) to match with the actual bindings on the C# side. Add some extra bindings for these types to increase their utility. - Introduce ScriptEmmyTypeOverrideAttribute to allow the C# side of the bindings to provide a more specific type. The utility command now requires this to be used to avoid accidentally exporting poor type information. - Fix a handful of scripts where the new type information revealed warnings. The ability to ScriptEmmyTypeOverrideAttribute allows parameters and return types to provide a more specific type compared to the previous, weak, type definition. For example LuaValue mapped to `any`, LuaTable mapped to `table`, and LuaFunction mapped to `function`. These types are all non-specific. `any` can be anything, `table` is a table without known types for its keys or values, `function` is a function with an unknown signature. Now, we can provide specific types. , e.g. instead of `table`, ReinforcementsGlobal.ReinforceWithTransport is able to specify `{ [1]: actor, [2]: actor[] }` - a table with keys 1 and 2, whose values are an actor, and a table of actors respectively. The callback functions in MapGlobal now have signatures, e.g. instead of `function` we have `fun(a: actor):boolean`. In UtilsGlobal, we also make use of generic types. These work in a similar fashion to generics in C#. These methods operate on collections, we can introduce a generic parameter named `T` for the type of the items in those collections. Now the return type and callback parameters can also use that generic type. This means the return type or callback functions operate on the same type as whatever type is in the collection you pass in. e.g. Utils.Do accepts a collection typed as `T[]` with a callback function invoked on each item typed as `fun(item: T)`. If you pass in actors, the callback operates on an actor. If you pass in strings, the callback operates on a string, etc. Overall, these changes should result in an improved user experience for those editing OpenRA Lua scripts in a compatible IDE.
PunkPun
left a comment
PunkPun
left a comment
There was a problem hiding this comment.
how do I get the showcased errors to show up? I've built this branch, refreshed VSCode, have the lua extension installed, and I'm not getting any of the new errors?
|
My approach was to open any lua file and hit go to definition on something from the engine, e.g. Utils.Do. This takes you to the extension file at, e.g. You can replace the contents of this file with the output from the utility command @penev92 is there a better way to test out new definitions? I am wondering if my approch above is needless faff. |
|
That's how I test(ed) things too, so you're doing fine. 👍 |
PunkPun
left a comment
PunkPun
left a comment
There was a problem hiding this comment.
OK
this also seems to have caught an error in allies03b.lua that wasn't adressed
4 participants
The ExtractEmmyLuaAPI utility command, invoked with
--emmy-lua-api, produces a documentation file that is used by the OpenRA Lua Language Extension to provide documentation and type information is VSCode and VSCode compatible editors when editing the Lua scripts.We improve the documentation and types produced by this utility in a few ways:
The ability to ScriptEmmyTypeOverrideAttribute allows parameters and return types to provide a more specific type compared to the previous, weak, type definition. For example LuaValue mapped to
any, LuaTable mapped totable, and LuaFunction mapped tofunction. These types are all non-specific.anycan be anything,tableis a table without known types for its keys or values,functionis a function with an unknown signature.Now, we can provide specific types. , e.g. instead of
table, ReinforcementsGlobal.ReinforceWithTransport is able to specify{ [1]: actor, [2]: actor[] }- a table with keys 1 and 2, whose values are an actor, and a table of actors respectively. The callback functions in MapGlobal now have signatures, e.g. instead offunctionwe havefun(a: actor):boolean. In UtilsGlobal, we also make use of generic types. These work in a similar fashion to generics in C#. These methods operate on collections, we can introduce a generic parameter namedTfor the type of the items in those collections. Now the return type and callback parameters can also use that generic type. This means the return type or callback functions operate on the same type as whatever type is in the collection you pass in. e.g. Utils.Do accepts a collection typed asT[]with a callback function invoked on each item typed asfun(item: T). If you pass in actors, the callback operates on an actor. If you pass in strings, the callback operates on a string, etc.Overall, these changes should result in an improved user experience for those editing OpenRA Lua scripts in a compatible IDE.
Contributes to #20632 (comment)
As an example, let's introduce some errors in allies01.
OpenRA/mods/ra/maps/allies-01/allies01.lua
Lines 174 to 180 in 0aac588
The new definitions allow it to tell us:
a.Owner- this is because it is now able to infer thatais anactor, becauseUtils.Dois operating on a collection of actors.These errors would've not been raised previously.
Below, please find a diff of the output from the utility command.
Diff for the utility command 'ra --emmy-lua-api'