Add support for generating LuaCATS definitions for the Lua API by kalimag · Pull Request #3755 · TASEmulators/BizHawk

kalimag · 2023-08-21T07:44:15Z

Adds the ability to generate API definitions in the LuaCATS format to the Lua Console.

LuaCATS is primarily the annotation format of Lua Language Server, which drives the most popular VS Code Lua extension and can be used in other editors with language server support.

LuaCATS is an extension/fork of the annotation format used by EmmyLua, but I'm not sure what the status of the latter is. These definitions might be compatible with EmmyLua, but the only spec of its format I could find is sparse and partially in Chinese. EmmyLua extension now uses LuaCATS annotations, too.

The generated definitions could be further improved, e.g. enumerating valid values for surfaceName parameters, specifying the structure of certain table values, and callback function signatures. But that would require extending the API metadata and I wanted to get some feedback first.

Current output:

Check if completed:

I, the committer, have read the licensing terms for contributors (last updated 2022-07-15) and am compliant

will resolve #3860

kalimag · 2023-08-21T08:08:53Z

Just for example, some issues LuaLS can detect in the bundled scripts using these definitions:

vadosnaprimer · 2026-03-23T12:05:26Z

Let's move forward with this one!

I decided to move from notepad++ to vscode for lua coding after 15 years, and ended up making exactly the same thing independently yesterday, I didn't even remember this PR! And here it's done in a much nicer way, so let's have it!

YoshiRulz

After fixing malformed examples, works w/ SumnekoLua plugin in IDEA.

YoshiRulz · 2026-03-26T11:10:37Z

+	{
+		// technically any string parameter can be passed a number, but let's just focus on the ones where it's commonly used
+		// like `gui.text` and `forms.settext` instead of polluting the entire API surface
+		if (parameter.Name is "message" or "caption" && parameter.ParameterType == typeof(string))


We don't want to encourage this. There are enough footguns in calling gui.* already with Lua not having named arguments.

Removing this will likely cause a lot of unnecessary warnings

I think type coercion warnings are good, but then I also consider dynamic languages like Lua to always be inferior to statically-typed languages. Is passing numbers for strings idiomatic in general, or only in concatenation?

Well, number-to-string conversion is specifically a feature in BizHawk's Lua bindings, not a feature of the Lua runtime. That's why LLS warns about it unless the parameter definition allows numbers.

But reading numbers from memory and passing them to gui functions is a pretty common pattern in BizHawk scripts, so I added this special case for those functions to avoid warnings in existing, working scripts. I have a test directory with the bundled Lua scripts and some from the Lua scripts catalog, and removing this code causes 73 additional warnings, 16 of which are in BizHawk's own scripts (for example).

I have no strong opinions on deprecating this behavior, but currently it's valid so the definitions say it's valid.

YoshiRulz · 2026-03-26T11:15:02Z

+
+		if (parameter.Member.DeclaringType == typeof(GuiLuaLibrary) && parameter.Name == "surfaceName" && parameter.ParameterType == typeof(string))
+		{
+			return "surface";


We should introduce new attributes if this grows to any more enums.

YoshiRulz · 2026-04-11T19:30:34Z

Please rebase.
Do you mind if I add [LuaZeroIndexed] myself? It could be used in the existing TASVideos wiki markup, and those functions' current documentation make no mention of it. edit: fdec9a3

the PR #3755 adds a button to generate these automatically, similar to the existing TASVideos wiki generation

Co-authored-by: feos <vadosnaprimer@users.noreply.github.com>

I don't know regex, replacements probably can be done in a neater way

revert if we don't want this anymore, but with LLS's ability to take in entire folders via config this feels nicer IMO and yeah I wouldn't mind adding this output to releases under something like `_luacats_definitions` folder in `Assets/Lua`

These are globals rather than `require`'d imports

This reverts commit c9fbcdc.

YoshiRulz

Works great, code LGTM. If I don't return to finish #4688 soon enough then by all means merge both PRs. I think nullable joypad.get would be the most annoying false positive.

vadosnaprimer · 2026-04-17T14:06:43Z

How soon is "soon enough"? I'd like to release within a week.

SuuperW · 2026-04-18T08:24:41Z

When I hover over a gui.draw method in VS Code to see the documentation, color is replaced with string|integer|dotnetcolor which I don't think is good. If there's a way for the definition to hint to IDEs that expansion isn't desired I think that'd be good, but as far as I can tell there doesn't seem to be a way to do that.

I can change the settings in the VS Code extension to disable alias expansion at least.

vadosnaprimer · 2026-04-18T10:35:09Z

Maybe making a derived class instead of alias would do what you want, but I personally don't see a problem in it showing the expanded thing.

kalimag · 2026-04-18T12:31:55Z

I can change the settings in the VS Code extension to disable alias expansion at least.

Yeah I don't think the annotations have any control over that. That's up to the IDE and individual users' settings. EmmyLua doesn't do this by default, FWIW.

Maybe making a derived class instead of alias would do what you want

No, that wouldn't work because a class can't inherit a union of types.

YoshiRulz · 2026-04-20T02:28:27Z

Can you put dotnetcolor first in the union?

YoshiRulz self-requested a review August 21, 2023 07:49

kalimag force-pushed the pr/generate-lua-api-definitions branch from bd55b04 to 72fc938 Compare October 31, 2025 12:06

YoshiRulz added Request: Feature/Enhancement For feature requests or possible improvements re: Lua API/scripting Relating to EmuHawk's Lua API (not the Lua Console) Meta Relating to code organisation or to things that aren't code labels Oct 31, 2025

vadosnaprimer reviewed Mar 23, 2026

View reviewed changes

Comment thread src/BizHawk.Client.Common/lua/Documentation/LuaCatsGenerator.cs Outdated

vadosnaprimer reviewed Mar 23, 2026

View reviewed changes

Comment thread src/BizHawk.Client.EmuHawk/tools/Lua/LuaConsole.cs Outdated

YoshiRulz requested changes Mar 23, 2026

View reviewed changes

vadosnaprimer force-pushed the pr/generate-lua-api-definitions branch from 48bca5b to 246190f Compare March 23, 2026 16:58

This comment was marked as off-topic.

Sign in to view

YoshiRulz reviewed Mar 24, 2026

View reviewed changes

Comment thread src/BizHawk.Client.EmuHawk/tools/Lua/LuaAutocompleteInstaller.cs Outdated

vadosnaprimer force-pushed the pr/generate-lua-api-definitions branch from 18425a1 to 0678148 Compare March 24, 2026 17:06

vadosnaprimer marked this pull request as ready for review March 24, 2026 17:25

YoshiRulz self-requested a review March 26, 2026 11:06

YoshiRulz reviewed Mar 26, 2026

View reviewed changes

kalimag force-pushed the pr/generate-lua-api-definitions branch from d7a355e to aee330b Compare April 12, 2026 22:43

YoshiRulz added Waiting on dev consensus and removed Request: Feature/Enhancement For feature requests or possible improvements labels Apr 13, 2026

YoshiRulz added a commit that referenced this pull request Apr 14, 2026

Check in a copy of the LuaCATS annotations from the WIP

471f175

the PR #3755 adds a button to generate these automatically, similar to the existing TASVideos wiki generation

vadosnaprimer and others added 8 commits April 17, 2026 04:40

wip

79a891a

Add support for generating LuaCATS definitions for the Lua API

aedd2a3

Add missing numeric types

e605a18

Throw error when definition file is executed as a script

fabb10c

Add support for bytes-as-string parameters

554d0cf

Apply suggestions from code review

4301a88

Co-authored-by: feos <vadosnaprimer@users.noreply.github.com>

add examples and hawk info

fa6748b

I don't know regex, replacements probably can be done in a neater way

line endings

6d9f4ee

kalimag and others added 19 commits April 17, 2026 04:41

Refactor example formatting

f11aa9c

Preamble, line-ending stuff

ae30e6b

Make LuaCanvas local

9951d79

Refactor GetLuaType(ParameterInfo)

3c4d8c2

Enumerate valid drawingSurface values

cb486da

It's free braces

d8f7719

Make class static

03bbaab

Make class static Part II

928d55a

split into individual files?

f772809

revert if we don't want this anymore, but with LLS's ability to take in entire folders via config this feels nicer IMO and yeah I wouldn't mind adding this output to releases under something like `_luacats_definitions` folder in `Assets/Lua`

Remove return statement from definition files

6cb96a2

These are globals rather than `require`'d imports

Include default parameter values

6667a7b

Fix code style

db4ce34

Rename color aliases

eb210ae

Fix name collision with userdata

3b79e1f

Mark zero-indexed return values

12da1a4

Handle zero-indexed parameters

29b153e

Support Nullable Reference Type annotations

3350d27

Revert "wip" - unrelated submodule change

1db4234

This reverts commit c9fbcdc.

Switch to NRT extensions

06bdc0a

kalimag force-pushed the pr/generate-lua-api-definitions branch from 7bf828c to 06bdc0a Compare April 17, 2026 03:20

YoshiRulz approved these changes Apr 17, 2026

View reviewed changes

kalimag mentioned this pull request Apr 17, 2026

Add #nullable annotations to Lua libs #4689

Open

8 tasks

Adjust annotation whitespace and comment

f1cf53f

kalimag added 2 commits April 20, 2026 06:59

Sort color union

a48d075

Annotate more specific createcanvas return type

4c08946

Conversation

kalimag commented Aug 21, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kalimag commented Aug 21, 2023

Uh oh!

Uh oh!

Uh oh!

vadosnaprimer commented Mar 23, 2026

Uh oh!

YoshiRulz left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

This comment was marked as off-topic.

Uh oh!

YoshiRulz Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

kalimag Mar 29, 2026

Choose a reason for hiding this comment

Uh oh!

YoshiRulz Mar 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kalimag Mar 30, 2026

Choose a reason for hiding this comment

Uh oh!

YoshiRulz Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

YoshiRulz commented Apr 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

YoshiRulz left a comment

Choose a reason for hiding this comment

Uh oh!

vadosnaprimer commented Apr 17, 2026

Uh oh!

SuuperW commented Apr 18, 2026

Uh oh!

vadosnaprimer commented Apr 18, 2026

Uh oh!

kalimag commented Apr 18, 2026

Uh oh!

YoshiRulz commented Apr 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

kalimag commented Aug 21, 2023 •

edited

Loading

YoshiRulz Mar 30, 2026 •

edited

Loading

YoshiRulz commented Apr 11, 2026 •

edited

Loading