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

Overview

Use @call_arg when your function wraps a Garry’s Mod API. It lets completion, navigation, type checking, and other editor features treat the wrapper like the original function. The official annotations already apply it to built-in functions like include, AddCSLuaFile, file.Find, util.AddNetworkString, net.Start, hook.Add, vgui.Register, and derma.DefineSkin. Only add it when the wrapper has the same behavior as the API it represents.
Wrappers that call the standard GMod network functions are detected automatically. You do not need @call_arg for normal net.Start, net.Receive, read, write, or send wrappers.

Syntax

Put @call_arg directly above the @param it describes.
After this, GLuaLS treats the path argument as a file loaded by include. For overloaded signatures, use @overload_call_arg directly above the @overload it describes:
The first argument is the zero-based parameter index inside that overload. When the function reads the value from a field of a table argument, use @call_arg_field with the field’s path:
Here panel.Base is treated as the panel’s base class. Use dots for nested fields, such as "Options.Base". @overload_call_arg_field does the same for a parameter inside the following @overload. It takes the zero-based parameter index first:

Supported roles

A gmod.member_guard wrapper takes the name of the member it checks:
Validity checks go on the function or callback, not a parameter. See @valid_guard, @self_guard and @self_call_valid.

Hooks with callbacks

Use one role for the hook name and one role for the callback function:
GLuaLS uses the hook name to infer callback parameters:
Use emit for functions that call hooks:

Lua loading

Use gmod.load for wrappers around Lua file and module loading:
Calls through these wrappers affect file loading and realm detection like direct include, AddCSLuaFile, IncludeCS, and require calls. GLuaLS follows fixed paths and file.Find loops when it can identify the matching files. Use gmod.file_find when wrapping file.Find itself:
When FindLuaFiles("myaddon/*.lua", "LUA") is used in a loop and the loop body calls annotated load wrappers, GLuaLS can infer which matching files are loaded server-side, sent to the client, or shared. Use compilefile for CompileFile wrappers, and gmod.environment for setfenv wrappers. When a compiled file is given an environment table, globals in that file are looked up in the table:
Like CompileFile, the path is relative to lua/, not to the calling file.

VGUI panels

Use define, table, and base for a vgui.Register wrapper:
Use define_control instead of define for derma.DefineControl wrappers. Use reference for functions that create or look up panels by name. Other panel roles:
  • register_file marks a file path whose PANEL table is registered, like vgui.RegisterFile.
  • register_table marks a panel table that is created or registered without a name, like vgui.CreateFromTable and vgui.RegisterTable.
  • parent marks the parent panel argument, like the parent of vgui.Create.
  • child_self marks a method that sets the parent of the panel it is called on, like Panel:SetParent.
  • parent_self marks a method that parents its argument to the panel it is called on, like Panel:Add.
  • own_class marks a parameter that receives the panel’s own class name, like the class of PANEL:GenerateExample.
With the parent known, self:GetParent() in a child panel has the parent’s type.

Derma skins

Use gmod.derma_skin when wrapping Derma skin functions:
GLuaLS can then find references between DefineSkin("MySkin", ...) and UseSkin("MySkin").

Scripted classes

Use gmod.network_var when wrapping entity NetworkVar helpers:
Use define_element for wrappers around NetworkVarElement, because element accessors always return numbers. Use define_slot for DTVar-style functions that register a named data table slot. Use gmod.scripted_class for functions that register entities or weapons by name:
Use weapon_table instead of entity_table for weapons. The table then becomes the class named by className, with its base class’s fields and methods. For IsBasedOn-style checks, mark the class name with class_name and the base with based_on. Inside if IsBasedOn(ent:GetClass(), "base_class") then, ent has the base class’s type. The class name has to come from a method marked with @self_class_name, such as Entity:GetClass. For gamemode inheritance wrappers, mark the base-name parameter:
Use gmod.class_base reference for wrappers around DEFINE_BASECLASS.

Priority

An optional third argument breaks ties when one parameter can inherit multiple roles:
Higher priority wins. You normally do not need this unless you are annotating a generic wrapper that can behave like several APIs.

See also