Lua Stub Generator for Crayta

So this is pretty niche, but I created a tool that generates Lua stub files from the API documentation:

Stub files are simple Lua files (with additional docblock annotations) that describe an API, without actually implementing it. This helps IDEs to perform proper inspection and autocompletion without having access to the original source code for the API you’re developing against.

So in this case it will provide autocompletion for all of Crayta’s built in functions and classes. This is useful if you have a very nice editor that has static code inspection features. In the case of Crayta that does mean you’ll have to continually copy-past code from your IDE to Crayta’s editor. It’s also obviously not compatible with Crayta’s collaborative coding features.

The stubs in this project a generated to be compatible with the Luanalysis Plug-in for IntelliJ IDEA and other IDEs by JetBrains. Both IntelliJ IDEA Community Edition and Luanalysis are available for free.

Installation

To install and run the Crayta Stub Generator you need:

Add this package to your project by running

composer require yogarine/crayta-stub-generator

or install it globally using

composer global require yogarine/crayta-stub-generator

To generate the stubs run vendor/bin/create-crayta-stubs from your project dir, or create-crayta-stubs if installed globally, to generate the stubs. They will be placed in the stubs subdirectory of the current working directory.

Getting your IDE to recognise the stubs

In order for your IDE to understand that your script extends the Crayta Script class, you’ll have to add annotations to your script. Annotations are basically special comments that tag parts of the code to educate your editor about what certain parts of the code are.
For example in Luanalysis you should start out by adding a @class annotation to your initial script table declaration:

--- @class NewScript : Script<Entity>
local NewScript = {}

In this example @class declares that this variable defines the NewScript class, and extends the Script class. (The colon basically means “this extends that”.) Finally the after script is a way to declare what type of entity this Script will be attached to. So if this Script will always only be attached to the Player you can use Script<Character> and the IDE will have better information to do it’s inspection and autocompletion.

You can also use annotations to declare the types of variables and function arguments and return values. For example:

    --- @type number
    self.someNumber = 42

and

    --- @param  name   string
    --- @param  sound  Sound
    --- @return boolean
    function NewScript:PlaySound(name, sound)
        -- Do stuff to play sound...
    end

For more information about the annotation available in Luanalysis check out these resources:

For other editors, you’re on your own. :wink:

Questions

So, why did I write this tool in PHP, and not Lua, you ask? Well, I started out in Lua but the Luaxpath module simply isn’t able to deal with invalid HTML. PHP has an excellent DOM Xpath extension. That, and I write PHP for a living so it’s something I just feel a lot more comfortable with.

If you have any questions, feel free to ask them here. Make sure you report bugs at https://github.com/Yogarine/crayta-stub-generator/issues.

1 Like