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-03-26T11:16:56Z

+		throw new NotSupportedException($"Unknown type {type.FullName} used in API. Generator must be updated to handle this.");
+	}
+
+	private static bool IsNullable(Type type) => type.IsGenericType && type.GetGenericTypeDefinition() == typeof(Nullable<>);


Reference types (i.e. string and byte[]) are nullable too

True, but this is about documenting when null/nil is valid, and in the Lua API it's generally not unless the parameter is optional.

If the Lua libraries used #nullabe annotations that information should be taken into account here, but currently that's not the case (and also I don't think .NET Framework has a reflection API to read that information).

All reference types in the Lua API are nullable because Lua is not a .NET language and cannot "see" the NRT metadata.

I do not follow. Are you saying want every string parameter to be marked string? in the definitions?

Passing nil for a parameter annotated as string results in a warning from the language server, so yes they all need to be string?. Unless you want to create another attribute and mark all the functions which throw on null arguments.

That's the point, though? gui.addmessage(nil) throws an error, so the diagnostics should warn about it. event.onexit(function() end, nil) doesn't throw an error, so diagnostics shouldn't warn.

That both are a nullable reference type on the technical level is irrelevant. As far as Lua is concerned, anything goes and you can pass a dozen table arguments to memory.writebyte if you want, but the diagnostics should help you catch that before it causes a runtime error.

(Didn't see the edit)

Currently the assumption for reference types is: parameters cannot be null unless they are optional. That seems to work well with the existing API surface.

If there turn out to be exceptions where this doesn't hold true, I think it would be preferable to mark nullable parameters rather than not-nullable ones, and for that I'd prefer to just reuse C# #nullable annotations rather than creating a bespoke attribute, if reasonably possible.

Reference types are now annotated as nullable, unless they are compiled with #nullable enable (and not marked as nullable in C#).

Still need to do the legwork of adding #nullable to existing Lua libs.

Wait they are available with reflection? I was under the impression that you needed NullabilityInfoContext from .NET Core.
I'll see about removing the need for dynamic.

Sure, it just gets rather complicated to correctly interpret the attribute data without NullabilityInfoContext once you get into generics and nested arrays and whatever. But for this purpose it's simple enough.

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

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

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

we gotta promote this!

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

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

This reverts commit c9fbcdc.

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

vadosnaprimer and others added 12 commits April 13, 2026 00:21

wip

c9fbcdc

Add support for generating LuaCATS definitions for the Lua API

8bebb50

Add missing numeric types

8da4189

Throw error when definition file is executed as a script

e161cf6

Add support for bytes-as-string parameters

f9e10c1

Apply suggestions from code review

e2133a8

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

add examples and hawk info

77c8064

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

line endings

02a9a4d

move editor/ide integration to its own menu

29bc711

we gotta promote this!

does "Braces XOR single-line" mean this?

83e7caa

braces

84649e9

name the definitions file according to Lua Language Server spec

bb24e2b

vadosnaprimer and others added 17 commits April 13, 2026 00:22

proper Program Files folder search

f22cb30

Refactor example formatting

6e90993

Preamble, line-ending stuff

392bcf9

Make LuaCanvas local

0f8b740

Refactor GetLuaType(ParameterInfo)

d7f0819

Enumerate valid drawingSurface values

fb32e9b

It's free braces

ca56131

Make class static

50fa7c2

Make class static Part II

7d89bc2

split into individual files?

219434a

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

d3b43f1

These are globals rather than `require`'d imports

Include default parameter values

36e4d26

Fix code style

9e35f8a

Rename color aliases

93be65a

Fix name collision with userdata

1f871a1

Mark zero-indexed return values

d813b8b

Handle zero-indexed parameters

aee330b

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

kalimag added 2 commits April 15, 2026 18:17

Support Nullable Reference Type annotations

d585540

Revert "wip" - unrelated submodule change

7bf828c

This reverts commit c9fbcdc.

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!

Choose a reason for hiding this comment

Uh oh!

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

kalimag commented Aug 21, 2023 •

edited

Loading

YoshiRulz Mar 30, 2026 •

edited

Loading

YoshiRulz Mar 30, 2026 •

edited

Loading

YoshiRulz commented Apr 11, 2026 •

edited

Loading