@call_arg

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. Most addons do not need this annotation. 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

---@[call_arg("domain", "role")]
---@param paramName type

Put @call_arg directly above the @param it describes.

---@[call_arg("gmod.load", "include")]
---@param path string
local function LoadShared(path)
    include(path)
end

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:

---@[overload_call_arg(0, "gmod.network_var", "type")]
---@[overload_call_arg(1, "gmod.network_var", "define")]
---@overload fun(typeName: string, name: string, extended?: table)
---@[call_arg("gmod.network_var", "type")]
---@param typeName string
---@param slot number
---@[call_arg("gmod.network_var", "define")]
---@param name string
local function AddVar(typeName, slot, name) end

The first argument is the zero-based parameter index inside that overload.

Supported roles

Domain	Roles	Used for
`gmod.net_message`	`define`, `start`, `receive`, `callback`, `reference`	Replacement network APIs or declarations provided without source code
`gmod.hook`	`add`, `emit`, `callback`, `gamemode_table`, `remove`, `reference`	Hook registration, hook calls, callback inference, and hook name lookup
`gmod.concommand`	`define`, `callback`	Console command registration and callback tracking
`gmod.convar`	`define`, `define_server`, `define_client`	Server and client ConVar registration
`gmod.timer`	`define`, `callback`, `simple`	Timer creation and callback tracking
`gmod.load`	`include`, `addcsluafile`, `add_cs_lua_file`, `includecs`, `include_cs`, `require`	File loading and realm detection for wrappers
`gmod.file_find`	`glob`, `search_path`, `path`	Files found by `file.Find` loader loops
`gmod.vgui_panel`	`define`, `define_control`, `table`, `base`, `reference`	VGUI panel registration, inheritance, and panel name lookup
`gmod.derma_skin`	`define`, `reference`	Derma skin registration and skin name lookup
`gmod.network_var`	`type`, `define`, `define_element`	Entity `NetworkVar` and `NetworkVarElement` accessor generation
`gmod.class_base`	`reference`	Base class names passed to `DEFINE_BASECLASS` wrappers
`gmod.gamemode`	`reference`	Parent gamemode names passed to `DeriveGamemode` wrappers
`gmod.member_guard`	`function`	Member-name guard wrappers
`gmod.color`	`r`, `g`, `b`, `a`	Color previews for custom color constructors

Guard metadata such as valid_guard, self_guard, and self_call_valid belongs on functions and callbacks, not parameters. Use Guard metadata for functions and callbacks that prove values are valid.

Hooks with callbacks

Use one role for the hook name and one role for the callback function:

---@[call_arg("gmod.hook", "add")]
---@param eventName string
---@param id any
---@[call_arg("gmod.hook", "callback")]
---@param callback fun(...)
local function AddHook(eventName, id, callback)
    hook.Add(eventName, id, callback)
end

GLuaLS uses the hook name to infer callback parameters:

AddHook("PlayerSpawn", "my-addon", function(ply)
    ply:SteamID() -- ply is Player
end)

Use emit for functions that call hooks:

---@[call_arg("gmod.hook", "emit")]
---@param eventName string
local function RunHook(eventName, ...)
    return hook.Run(eventName, ...)
end

Lua loading

Use gmod.load for wrappers around Lua file and module loading:

---@[call_arg("gmod.load", "include")]
---@param path string
local function IncludeShared(path)
    include(path)
end

---@[call_arg("gmod.load", "addcsluafile")]
---@param path string
local function SendToClient(path)
    AddCSLuaFile(path)
end

---@[call_arg("gmod.load", "includecs")]
---@param path string
local function IncludeClient(path)
    IncludeCS(path)
end

---@[call_arg("gmod.load", "require")]
---@param module string
local function LoadModule(module)
    return require(module)
end

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:

---@[call_arg("gmod.file_find", "glob")]
---@param pattern string
---@[call_arg("gmod.file_find", "search_path")]
---@param searchPath string
local function FindLuaFiles(pattern, searchPath)
    return file.Find(pattern, searchPath)
end

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.

VGUI panels

Use define, table, and base for a vgui.Register wrapper:

---@[call_arg("gmod.vgui_panel", "define")]
---@param className string
---@[call_arg("gmod.vgui_panel", "table")]
---@param panel table
---@[call_arg("gmod.vgui_panel", "base")]
---@param baseName string
local function RegisterPanel(className, panel, baseName)
    vgui.Register(className, panel, baseName)
end

Use define_control instead of define for derma.DefineControl wrappers. Use reference for functions that create or look up panels by name.

Derma skins

Use gmod.derma_skin when wrapping Derma skin functions:

---@[call_arg("gmod.derma_skin", "define")]
---@param name string
---@param description string
---@param skin table
local function DefineSkin(name, description, skin)
    derma.DefineSkin(name, description, skin)
end

---@[call_arg("gmod.derma_skin", "reference")]
---@param name string
local function UseSkin(name)
    return derma.GetNamedSkin(name)
end

GLuaLS can then find references between DefineSkin("MySkin", ...) and UseSkin("MySkin").

Scripted classes

Use gmod.network_var when wrapping entity NetworkVar helpers:

---@[call_arg("gmod.network_var", "define")]
---@param name string
---@[call_arg("gmod.network_var", "type")]
---@param typeName string
local function AddVar(name, typeName)
    ENT:NetworkVar(typeName, 0, name)
end

Use define_element for wrappers around NetworkVarElement, because element accessors always return numbers. For gamemode inheritance wrappers, mark the base-name parameter:

---@[call_arg("gmod.gamemode", "reference")]
---@param base string
local function Derive(base)
    DeriveGamemode(base)
end

Use gmod.class_base reference for wrappers around DEFINE_BASECLASS.

Priority

An optional third argument breaks ties when one parameter can inherit multiple roles:

---@[call_arg("gmod.hook", "emit", 10)]
---@param name string

Higher priority wins. You normally do not need this unless you are annotating a generic wrapper that can behave like several APIs.

Overview

Type system

Functions

Garry's Mod Lua

Utilities

Overview

Syntax

Supported roles

Hooks with callbacks

Lua loading

VGUI panels

Derma skins

Scripted classes

Priority

See also

​Overview

​Syntax

​Supported roles

​Hooks with callbacks

​Lua loading

​VGUI panels

​Derma skins

​Scripted classes

​Priority

​See also

Overview

Syntax

Supported roles

Hooks with callbacks

Lua loading

VGUI panels

Derma skins

Scripted classes

Priority

See also