Compiler Annotations
To improve translation and compatibility to different Lua interfaces, the TypeScriptToLua transpiler supports several custom annotations that slightly change translation results. This page documents the supported annotations. The syntax of the compiler annotations use the JSDoc syntax.
#
@compileMembersOnlyTarget elements: (declare) enum
This decorator removes an enumeration's name after compilation and only leaves its members. Primarily used for APIs with implicit enumerations.
Example
Example 2
#
@customConstructorTarget elements: declare class
Changes the way new instances of this class are made. Takes exactly one argument that is the name of the alternative constructor function.
Example
#
@noResolutionTarget elements: module
Prevents tstl from trying to resolve the module path. When importing this module the path will be exactly the path in the import statement.
Example
#
@noSelfTarget elements: declare class
, (declare) interface
or declare namespace
Indicates that functions inside a scope do not take in initial self
argument when called, and thus will be called with a dot .
instead of a colon :
. It is the same as if each function was declared with an explicit this: void
parameter. Functions that already have an explicit this
parameter will not be affected.
When applied to a class or interface, this only affects the type's declared methods (including static methods and fields with a function type). It will not affect other function declarations, such as nested functions inside a class' methods.
Example
When applied to a namespace, all functions declared within the namespace will treated as if they do not have a self
parameter. In this case, the effect is recursive, so functions in nested namespaces and types declared as parameters will also be affected.
Example
For more information about how the self
parameter is handled, see Functions and the self
Parameter
#
@noSelfInFileTarget elements: (declare) file
Indicates that functions in a file do not take in initial self
argument when called.
This is annotation works the same as @noSelf being applied to a namespace, but affects the entire file.
@noSelfInFile
must be placed at the top of the file, before the first statement.
#
Deprecatedwarning
Some annotations are deprecated and will be/have been removed. Below are the deprecated annotations and instructions to recreate their behavior with vanilla TypeScript.
#
@tupleReturnDeprecated:0.42.0 Removed:0.43.0
Target elements: (declare) function
This decorator indicates a function returns a lua tuple instead of a table. It influences both destructing assignments of calls of that function, as well as changing the format of returns inside the function body.
Upgrade Instructions
Use the LuaMultiReturn
language extensions instead of a custom annotated types. This makes multi return usage type-safe and more obvious.
Becomes:
Lua output:
#
@extensionDeprecated:0.37.0 Removed:0.39.0
Target elements: class
The Extension decorator marks a class as an extension of an already existing class. This causes the class header to not be translated, preventing instantiation and the override of the existing class.
Upgrade Instructions
Use an interface to extend your existing class and declare the table of the existing class as variable.
Example
#
@metaExtensionDeprecated:0.37.0 Removed:0.39.0
Target elements: class
The Extension decorator marks a class as an extension of an already existing meta class/table. This causes the class header to not be translated, preventing instantiation and the override of the existing class.
Upgrade Instructions
Use an interface to extend your existing class and assign the functions to the meta table of the existing class.
#
@phantomDeprecated:0.37.0 Removed:0.39.0
Target elements: namespace
This decorator marks a namespace as a phantom namespace. This means all members of the namespace will be translated as if they were not in that namespace. Primarily used to prevent scoping issues.
Upgrade instructions
Use ECMAScript modules and import/export. Alternatively, use a real (non-phantom) namespace.
#
@pureAbstractDeprecated:0.37.0 Removed:0.39.0
Target elements: declare class
This decorator marks a class declaration as purely abstract. The result is that any class extending the purely abstract class will not extend this class in the resulting Lua.
Upgrade Instructions
Try declaring the "classes" of your lua enviroment as interface. If that is not possible use interface merging as suggested below.
#
@forRangeDeprecated:0.38.0 Removed:0.40.0
Target elements: declare function
Denotes a function declaration is a Lua numerical iterator. When used in a TypeScript for...of
loop, the resulting Lua will use a numerical for loop.
The function should not be a real function and an error will be thrown if it is used in any other way.
Upgrade Instructions
Use the $range
language extension instead of a custom annotated type.
#
@luaIteratorDeprecated:0.38.1 Removed:0.40.0
Target elements: (declare) interface
Denotes a type is a Lua iterator. When an object of a type with this annotation is used in a for...of statement, it will transpile directly as a lua iterator in a for...in statement, instead of being treated as a TypeScript iterable. Typically, this is used on an interface that extends Iterable
or Array
so that TypeScript will allow it to be used in a for...of statement.
Upgrade Instructions
Use the LuaIterable
and LuaMultiReturn
language extensions instead of a custom annotated types.
#
@luaTableDeprecated:0.39.0 Removed:0.40.0
Target elements: type
This annotation signals the transpiler to translate a class as a simple lua table for optimization purposes.
Upgrade Instructions
Use the LuaTable
language extension instead of a custom annotated type.
#
@varargDeprecated:0.39.0 Removed:0.40.0
Target elements: (declare) interface or type
Indicates that an array-like type represents a Lua vararg expression (...
) and should be transpiled to that when used in a spread expression. This is useful for forwarding varargs instead of wrapping them in a table and unpacking them.
Upgrade Instructions
@vararg
is no longer required to prevent vararg parameters from being wrapped in a table. The ellipsis operator will now automatically be used if the parameter is used in a spread expression.
Example:
However, if the parameter is accessed as an array or tuple, it will be wrapped in a table.
Example:
Note that are a few cases where the parameter will still be wrapped in a table, even if a spread expression is used, in order to generate correctly functioning Lua.