Skip to content

Type annotations

Type annotations are optional comments that tell the editor what a function takes and returns. The editor then offers better completion and warns about mistakes (W-TYPE-MISMATCH). The compiler ignores them, and they never change what a script does.

The tags are written in // or /* */ comments, in the style of JSDoc.

// @param pl TServerPlayer
// @param amount number
// @return number
function heal(pl, amount) {
pl.health = min(pl.health + amount, pl.maxhealth);
return pl.health;
}
function onCreated() {
temp.btn = findobject("OkButton"); // @type temp.btn GuiButtonCtrl
}
Tag Where Meaning
@param name Type in the comment right before a function the type of a parameter (name with or without temp.)
@return Type the same comment the type that the function returns
@type name Type anywhere in a function or at the top of a file the type of a variable (temp.x, this.x, or a script-global), from that point on in its scope
@host Type the top of a class or a stand-alone file (may repeat for a union) the type of this
@this Type the comment right before an anonymous function the type of this inside it

A type is a type name from the API reference, the name of an imported class, or one of number, string, array, array<Type>, object, function, empty. Join types with | for a union: number|string. Names ignore case.

An annotation wins over what the editor works out for itself. If the value the editor infers contradicts the annotation, it warns with W-TYPE-MISMATCH.

// @param points number
// @return string
function rankFor(points) {
temp.label = "bronze"; // @type temp.label string
if (points >= 250) {
temp.label = "gold";
} else if (points >= 100) {
temp.label = "silver";
}
return temp.label;
}
function onCreated() {
echo(rankFor(300));
// expect: gold
echo(rankFor(120));
// expect: silver
echo(rankFor(5));
// expect: bronze
}

Run this example in the playground

Annotations are an engine extension. The sample world class score_format uses them.

Engine version 0.1.0. Built 2026-11-18.