Skip to main content
This annotation is intended for complex cases and is primarily designed to be used by the built-in annotations.

Overview

Some functions put new fields on the table you give them. RegisterMetaTable is one: after the call, the table has MetaID and MetaName. Nothing in your code assigns those fields, so without help GLuaLS reports them as undefined. adds_field goes on the function’s parameter and names each field the function adds. Every call then gives the passed table those fields, typed and in autocomplete. Go to definition on a field jumps to the argument of the call that added it. You only annotate the function. Callers write nothing extra.

Syntax

Put it directly above the @param of the table that gets the field. Add one line per field.
  • FieldName is the name of the new field.
  • type is optional. It is a built-in type such as integer, string or boolean, or a class name. End it with ? for a field that may be nil. Without it, the field is any.

Example

The official annotations describe RegisterMetaTable like this:
Any table you register now has both fields:

Where the fields go

The fields go on whatever the argument is:
  • A variable typed as a class (---@class or ---@type) gives the field to that class. Every value of the class sees it, including classes that inherit from it.
  • A plain table such as local t = {} gets the field on that table only.
That makes factories work without extra annotations. Here CreateMetaTable registers a battlemechs.Base table, so every class it makes inherits MetaID:

Your own functions

Any function can use it, not only built-in ones:

adds_field vs @outparam

Use adds_field when the function creates a field that is not on the table yet. Use @outparam when the function writes a result into a field the caller already set up, like util.TraceLine filling in output.