Ma3 Lua API

A VS Code extension for the Grand Ma 3 Lua Api, it provide autocomplete and documentation for functions to write Grand Ma 3 plugins.

Suggestions:

When typing the extension provide functions related to the selected API version.

Autocomplete:

When you select a suggested function, the extension add automatically functions parameters.

Autocomplete are available for Enums and keys:

Documentation:

The extension provide documentation and examples with a mouse over popup.

The extension also references functions that are not documented in the official manual, so the popup displays the description provided by the HelpLua command.

API version selection:

The VS Code bottom toolbar display the actual Ma3 API version.

Clicking on this toolbar button will open a quick pick menu that allow you to:

• Select the Ma3 version
• Disable the extension for the actual project
• Restart the extension

How to contribute

This is an open source project, feel free to contribute by making pull requests.

What do you need:

• VS Code IDE
• Node JS
• Clone this repository

File organization

All the extension data is in the resources folder, that folder contain a folder for each Ma3 version, each folder contain:

• Dummy lua files to helps the Lua Language Server to know all the functions:
  • Function documented in the manual
    • ma3_dummy_object_free.lua : object free functions
    • ma3_dummy_object.lua : object functions
  • Function not documented in the manual but returned by the HelpLua command
    • ma3_dummy_object_free_no_doc.lua : object free functions
    • ma3_dummy_object_no_doc.lua : object functions
  • ma3_enums.lua : Enums list returned by this lua script and converted to lua enum with this Python script
• Json files that contain all object api documentation and autocompletion:
  • Function documented in the manual
    • ma3_object_free.json : object free functions
    • ma3_object.json : object functions
  • For not documented functions
    • ma3_object_free_no_doc.json : object free functions
    • ma3_object_no_doc.json : object functions

To update or complete the documented files:

This image explain how to fill the json files according to the Ma help pages that corresponding to the version.

• For the body part, fill the parentheses with the function parameters, optional parameters starting with an underscore:

  function(${1:fixtureId}, ${2:count}, ${3:_type})

• All the text part need to be converted to Markdown format, this can be done using this online tool: Clipboard 2 Markdown.

• After that you have to convert the markdown text to a single line string, this can be done with json Stringlfy.

• For the code part of the example, you only have to convert to a single line string.

To update or complete the dummy file:

This file contain dummy functions with input parameters, you have to enumerate all parameters types, if they are optional, if they can be nil and the return type:

---@param fixtureTableHandle Handle
---@param multiPatchAmount integer
---@param undoText? string @Optional
---@return integer|nil multiPatchAmountCreated
function CreateMultiPatch(fixtureTableHandle, multiPatchAmount, undoText)
    return 0
end 

Test your modification and then, start a pull request!

⚠ Disclaimer
This extension is not affiliated with or endorsed by MA Lighting. It is an independent project created to provide autocomplete and documentation for the GrandMA 3 Lua API to assist in writing plugins.