LunaLua Intellisense

[WildW]

What is Intellisense?

Intellisense is the term Microsoft uses to describe an intelligent code-editor suggestion system. You can read more about it here.
Note: intellisense does NOT equal "generative AI". There is NO generative AI being distributed or used here.

Lua being as dynamic of a language as it is, it doesn't support advanced features like that out of the box. Proper lua intellisense is only achieved by manual documentation, which is what this project achieves. You can find the Github repo here.

Why should I use this?

Catch errors before running your code

Diagnostic information will warn you about syntax errors, unused code, deprecated libraries, and it will tell you whenever it thinks you're misusing your own code and the code from SMBX/LunaLua. For example:

Deprecated:


Syntax error:


Misuse:


Less time searching the docs, handbook, and code examples

Sometimes you know what you're looking for but its exact name is only on the tip of your tongue, so you're forced to open the docs and go search for it. Or maybe you know the name of the function you're trying to call, but you don't remember the order of its arguments, or their types; intellisense will help there too.



Large and collaborative projects

The size of your project its number of contributors directly affect the ease at which you and your team members complete goals. It's easy to forget code you wrote months ago, and it's confusing to decipher the code others wrote. With intellisense, you can navigate difficult codebases much more easily.

Using "Find references" to see where a function is used:


Highly configurable

If there are features you do not fancy, I can almost guarantee you that they can be disabled and adjusted. Additionally, there are lots of additional features that you can turn on. Language servers, especially lua-language-server, are generally very robust and built with configurability in mind, and there are some keyboard shortcuts to toggle between the different levels of diagnostic "verbosity". Plus, lua-language-server is open source and I've already made one of my own contributions to it, which improved the configurability of addons.

So how do I install this?

If you're using VSCode or VSCodium it's really simple. First you need sumneko's lua language server extension. Once you install that extension, open the folder your workspace is in and hit CTRL+SHIFT+P. Then type in "Lua: Open Addon Manager" and hit enter. You should see a search bar. Now you should type in "SMBX2 LunaLua" and install the addon.

Note: you will need to have git installed to use the addon manager.

Then I recommend you open the file that gets generated at .vscode/settings.json and paste some of these settings in (if they weren't already put there automatically):

Code: Select all

{
    "Lua.addonManager.enable": true, // If the addon manager wasn't working, turn this on manually
    
    // This field should be set by the addon manager when you install plugins
    "Lua.workspace.library": [
        // The directory these definitions are located
        "C:/Users/<user>/AppData/Roaming/Code/User/globalStorage/sumneko.lua/addonManager/addons/smbx2-lunalua/module/library",
        
        // The directory lpeg is located (if you're using it)
        "C:/Users/<user>/AppData/Roaming/Code/User/globalStorage/sumneko.lua/addonManager/addons/lpeg/module/library"
    ],
    
    "Lua.type.inferParamType": true, // This might help improve diagnostic information
    
    "Lua.runtime.version": "LuaJIT", // The version of lua that LunaLua is based on
    
    "Lua.diagnostics.disable": [
        // "lowercase-global", // if you prefer to use lowercase names for your global variables, disable this diagnostic.
        
        // If you are experiencing a "missing field" diagnostic error when you know you don't need the field it says you do,
        // you can disable this diagnostic
        // As of 9/10/2024 I believe that this is no longer necessary. Improvements have been made.
        // "missing-fields",
        
        // If you are experiencing a "missing parameter" diagnostic error when you know you don't need the parameter it says you do,
        // you can disable this diagnostic
        // As of 9/10/2024 I believe that this is no longer necessary. Improvements have been made.
        // "missing-parameter"
    ],
    
    // If you're experiencing errors with casting a number to an integer, you can turn this on. Lua does not make the distinction between
    // these types during runtime, it is purely for enhanced diagnostics.
    // "Lua.type.castNumberToInteger": true,
    
    // For when something *could* be nil but you know that it won't be.
    // For example: Misc.resolveFile returns a string or nil, so it will give you a diagnostic error when you try to use the
    // result as a string without first checking if it's nil. Generally it's good practice to nil-check before using values, but
    // you can still choose to disable this diagnostic here.
    // "Lua.type.weakNilCheck": true,
}

Also, make sure to enable this option for the best experience. It isn't applied automatically.

Code: Select all

"Lua.runtime.plugin": "C:/Users/<user>/AppData/Roaming/Code/User/globalStorage/sumneko.lua/addonManager/addons/smbx2-lunalua/module/plugin.lua"

If you're using another editor it may not be quite as simple as installing an extension (though for jetbrains, it is), but it should still be very straight forwards. For example, here's a guide for how to use this with neovim. Also make sure to check out the language server documentation. If you scroll down from the main landing page you'll find some materials to help you get started. The settings listed above are compatible with all editors that support the language server protocol, and by extension, lua language server. The format you set them in may differ.

Contributing

So far there's a total 120 lua files in here because SMBX2 is damn massive, but there's still some work to be done. Follow the link to the repo and read the CONTRIBUTORS guide if you want to add to the project. But note that I'm pretty much done working on this myself.

Also, I greatly appreciate all kinds of feedback. If you have a question, concern, criticism, or just want to voice some idea, please do tell me!

[Rixitic]

Apologies for the delayed feedback!

Intellisense was something a member of the X2 team started working on forever ago, but it was for a much earlier and cruder version of LunaLua and she left the team before it ever came to fruition anyway. So this is an impressive and exciting undertaking, and I'm really looking forward to having to check the docs in my browser less often!

(As a couple asides, while I get this is mainly meant for intermediate and experienced users of VSCode, it might still be worth linking to the Intellisense page of the VSCode documentation in the OP. Also, I can confirm this works in VSCodium... not sure if that's something anyone knowledgeable enough about that fork would've ever had any doubt over, but I guess let this be a reassurance for anyone else that if you want to use this software for SMBX2 projects but you're worried about Microsoft's telemetry and AI features, well, there you go!)

Assorted observations about the diagnostics:

• in general it seems to have trouble with some of lua's syntactic sugar, such as functionName{multiple named args}

• LunaLua is based mostly on Lua 5.1 with some extra stuff backported via LuaJIT. The flagging for deprecated Lua functionality is based on Lua 5.4 (see: math.atan2 in scripts > base > particles.lua.)

• the onLoadSection#() events are not being detected as built-in functions and getting flagged as lowercase-global style mistakes

• It seems to be missing some function aliases, like vector#:normalise()

• it's flagging functions with optional arguments and optional return values, such as player:teleport() and mem() acting as either a setter or a getter depending on whether the third argument is provided

• it doesn't recognize the constant NPC_ID, which is specific to npc-n.lua files and equals the index of that NPC (so if the file is npc-786.lua, for example, NPC_ID == 786)

• it doesn't recognize the GLDraw primitive constants

• it doesn't recognize the Animation class (which, to be fair, I'm only now noticing that's not documented)

• it highlights the items of the Player.rawKeys tables as undefined fields

• it highlights Misc.resolveSoundFile() when it's given a string as an argument

• It seems to sometimes flag setting an NPC's y position as a type mismatch...? (scripts > npcs > AI > yoshieggplant.lua)

Also, one diagnostics feature that would be nice -- and I'm not sure how feasible this would be to implement -- is to have it check for specific string inputs for require() and warn about trying to load deprecated libraries like LunaTester does at runtime. It looks like data > scripts > legacy > replacement_map.ini is the list LunaTester uses to determine which libraries should prompt its own deprecated warning pop-up.

[WildW]

Apologies for the delayed feedback!

Intellisense was something a member of the X2 team started working on forever ago, but it was for a much earlier and cruder version of LunaLua and she left the team before it ever came to fruition anyway. So this is an impressive and exciting undertaking, and I'm really looking forward to having to check the docs in my browser less often!

Thank you Rixitic! If you or anyone else is interested in helping complete this project, the github repo is linked in the OP. There's a CONTRIBUTORS page which can help those unfamiliar with git help out if they desire to.

(As a couple asides, while I get this is mainly meant for intermediate and experienced users of VSCode, it might still be worth linking to the Intellisense page of the VSCode documentation in the OP. Also, I can confirm this works in VSCodium... not sure if that's something anyone knowledgeable enough about that fork would've ever had any doubt over, but I guess let this be a reassurance for anyone else that if you want to use this software for SMBX2 projects but you're worried about Microsoft's telemetry and AI features, well, there you go!)

Good idea, I'll be sure to make that change. Also, it's worth noting this can be used with any editor that supports the language server protocol (not just vscode or vscodium), though it might take some more set up depending on which you use.

• in general it seems to have trouble with some of lua's syntactic sugar, such as functionName{multiple named args}

I haven't seen any problems with syntactic sugar like optional braces, though it might be related to some language server settings.

• LunaLua is based mostly on Lua 5.1 with some extra stuff backported via LuaJIT. The flagging for deprecated Lua functionality is based on Lua 5.4 (see: math.atan2 in scripts > base > particles.lua.)

There are some language server settings that should be applied when using the plugin, I'll list them below.

• the onLoadSection#() events are not being detected as built-in functions and getting flagged as lowercase-global style mistakes

Good catch, it seems I forgot to include those. Regarding lowercase globals, that's also a language server setting which I'll include in the list below.

• It seems to be missing some function aliases, like vector#:normalise()

I'll look into that. Thanks for bringing it up.

• it's flagging functions with optional arguments and optional return values, such as player:teleport() and mem() acting as either a setter or a getter depending on whether the third argument is provided

Yeah I'm missing a bunch of ? mark symbols in the type information to denote optional arguments. You can turn off diagnostics for missing arguments as a band aid solution but it's on the list to fix. For global mem, I accidently added a ---@nodiscard annotation to the setter. I will fix that.

• it doesn't recognize the constant NPC_ID, which is specific to npc-n.lua files and equals the index of that NPC (so if the file is npc-786.lua, for example, NPC_ID == 786)

• it doesn't recognize the GLDraw primitive constants

Good catch. I'll dump the global environment for more constants I might have missed.

• it doesn't recognize the Animation class (which, to be fair, I'm only now noticing that's not documented)

Oops. I probably forgot about it given the existence of PlayerAnimation.

• it highlights the items of the Player.rawKeys tables as undefined fields

Another good catch.

• it highlights Misc.resolveSoundFile() when it's given a string as an argument

I believe you're referring to it telling you that the return might be nil? If so, this is technically the correct behavior (as it could fail to find the file), but I understand that most of the time it's not up to chance whether the file will be there, so maybe I can change that. For how to avoid it as of now, check the list below.

• It seems to sometimes flag setting an NPC's y position as a type mismatch...? (scripts > npcs > AI > yoshieggplant.lua)

The type of NPC.y is correctly annotated as `number`, but it appears that there's a problem with the way I annotated operator overloading, so it thinks that you're setting the number to a vector value.

Also, one diagnostics feature that would be nice -- and I'm not sure how feasible this would be to implement -- is to have it check for specific string inputs for require() and warn about trying to load deprecated libraries like LunaTester does at runtime. It looks like data > scripts > legacy > replacement_map.ini is the list LunaTester uses to determine which libraries should prompt its own deprecated warning pop-up.

I'm not sure if this is something that I can implement with the current features of the language server but I'll give it a shot. Otherwise deprecated libraries could just have all their functions annotated as ---@deprecated.

---

By the way, you can install these definitions through the Lua extension's addon manager now, I'll update the OP to reflect this.

I'll make some updates to the OP to clarify a few things and provide more insight, including recommended settings and the like, which I'll also post here: (put them in .vscode/settings.json or in your global settings.json)

Code: Select all

{
    "Lua.addonManager.enable": true, // To use the addon manager to install these definitions
    
    // This field should be set by the addon manager
    "Lua.workspace.library": [
        // The directory these definitions are located
        "C:/Users/<user>/AppData/Roaming/Code/User/globalStorage/sumneko.lua/addonManager/addons/smbx2-lunalua/module/library",
        
        // The directory lpeg is located (if you're using it)
        "C:/Users/<user>/AppData/Roaming/Code/User/globalStorage/sumneko.lua/addonManager/addons/lpeg/module/library"
    ],
    
    "Lua.runtime.version": "LuaJIT", // The version of lua that LunaLua is based on
    
    "Lua.diagnostics.disable": [
        "lowercase-global", // This is just up to preference
        "missing-fields" // Band-aid solution to missing optional named parameters
        "missing-parameter" // Band-aid solution to missing optional parameters
    ],
    
    // Some fields are denoted as integer. Since lua doesn't make this distinction internally, you should turn this option on to avoid cast warnings
    "Lua.type.castNumberToInteger": true,
    
    "Lua.type.weakNilCheck": true, // For when something *could* be nil but you know that it won't be
    
    "Lua.type.inferParamType": true, // This is just nice to have for your own code. Your preference though.
}

[WildW]

New Update - v2

This update:

• Adds several more modules from SMBX2
• Fixes several inaccuracies
• Adds the Animation class from LunaLua
• Disables ffi and parts of os that are disabled in the game environment
• Treats API.load, loadSharedAPI, and loadAPI as require
• Introduces a convenient alias enum for SFX IDs

Most concerns raised by Rixitic have been addressed.

[Cat king]

Ok now THIS is very cool. I will have to try it when I get the chance. Also slightly random, but I was recently thinking about how cool something like this would be (especially for newbies!).

[punkitt]

oh this ROCKS, thank you so much for doing this work!

[WildW]

New Update - v3

Changes:

• More detailed and accurate annotations for the Graphics and json namespaces
• Disable several additional standard library features not present in sandboxed scripts
• Update several modules
  • xmem
  • map3d
  • orbits
• Add new modules
  • npcmanager
  • verletrope
  • visioncone
  • checkpoints

[Chipss]

I've been using this for a few weeks now, and it's been a game changer! Saved me a lot of time browsing the docs. Thanks for updating it with fixes and improvements as well! Great stuff.

[WildW]

I've been using this for a few weeks now, and it's been a game changer! Saved me a lot of time browsing the docs. Thanks for updating it with fixes and improvements as well! Great stuff.

That's great to hear! If you ever have any suggestions, feel free to tell me about them.

[WildW]

New Update - v4.1



Some big changes have also been made to the original post!

Annotation changes

• Finish type information for `API`, `EventManager`, `require_utils`, and more
• Remove many duplicate definitions
• Greatly improve type information in *most* classes
• Add several missing function or enum aliases
• Improve type narrowing and inheritance
• Implement generic types in places where appropriate

Plugin Changes

• case-insensitive module file resolution. You will now get autocomplete for loaded libraries regardless of if you capitalized the name correctly (for example require "npcManager" when the name of the file is actually "npcmanager") This is because SMBX2 only works on Windows where the file system is case-insensitive.
• when overridden, global lunalua events will now contain type information about their arguments

Important!

To update the addon in vscode, you may need to open the addon manager again and press the big blue "Update" button.

Plugin related updates won't apply unless you add this to your configuration file. (.vscode/settings.json, .luarc.json, or other)

Code: Select all

"Lua.runtime.plugin": "C:/Users/<user>/AppData/Roaming/Code/User/globalStorage/sumneko.lua/addonManager/addons/smbx2-lunalua/module/plugin.lua"

The path used here should reflect where the addon is installed. This example uses the location that the vscode extension saves addons to.

[mariobrigade2018]

This error message shows up when typing in "Lua: Open Addon Manager"

[WildW]

This error message shows up when typing in "Lua: Open Addon Manager"

Error: spawn git ENOENT

You need git installed. I have this info in the post too.

[TheEeveeLovers]

I found an issue when using this
It says triggerEvent() is deprecated and to use Misc.triggerEvent() instead
However, Misc.triggerEvent() does not seem to exist in the latest patch

[WildW]

I found an issue when using this
It says triggerEvent() is deprecated and to use Misc.triggerEvent() instead
However, Misc.triggerEvent() does not seem to exist in the latest patch

Yes, this is an error, thanks for pointing it out.

It's actually been fixed in the latest development branch for a while now, I was going to publish the next release when b5p3 came out, but that still hasn't happened yet.

[WildW]

New Update - v5 - SMBXb5p3 Support



Changes

• Adds support for API changes from the new SMBX2 release Beta 5 Patch 3 (I forgot about the additive parameter in draw functions and SFX.volume.UNTAGGED, I'll release another update shortly to fix that)
• Removes known incorrect deprecation warnings (triggerEvent())
• Adds several missing LunaLua classes
• Generally improves annotations for many of the existing classes
• Renames some classes to better reflect their name as defined by LunaLua patches

Important!

To update the addon in VSCode, you may need to open the addon manager again and press the big blue "Update" button.

For plugin features (case insensitive require() and the quick info panel for global events) you must manually set the plugin path and library path in the workspace's .vscode/settings.json, or .luarc.json. If it contains "${addons}" in the path, the plugin won't work. (I'll come back to fix this in the next update, an update was made to the language server since I made the plugin features which I did not consider)

Code: Select all

"Lua.workspace.library": [
    "C:/Users/<User>/AppData/Roaming/Code/User/globalStorage/sumneko.lua/addonManager/addons/smbx2-lunalua/module/library"
],
"Lua.runtime.plugin": "C:/Users/<User>/AppData/Roaming/Code/User/globalStorage/sumneko.lua/addonManager/addons/smbx2-lunalua/module/plugin.lua"

Put your Window's user where <User> is, and note that if you are using a different IDE, the location you install it will be different. This example is using VSCode.

Moving Forward
I'll likely only make one more update to this project by myself, just so I can fix small errors, but you are still free to make your own pull requests on the remote repository hosted on GitHub.