> ## Documentation Index
> Fetch the complete documentation index at: https://gluals.arnux.net/llms.txt
> Use this file to discover all available pages before exploring further.

# @call_arg

> Tell GLuaLS what each parameter of a custom wrapper means.

## 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.

<Note>
  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.
</Note>

***

## Syntax

```lua theme={null}
---@[call_arg("domain", "role")]
---@param paramName type
```

Put `@call_arg` directly above the `@param` it describes.

```lua theme={null}
---@[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:

```lua theme={null}
---@[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](/annotations/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:

```lua theme={null}
---@[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:

```lua theme={null}
AddHook("PlayerSpawn", "my-addon", function(ply)
    ply:SteamID() -- ply is Player
end)
```

Use `emit` for functions that call hooks:

```lua theme={null}
---@[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:

```lua theme={null}
---@[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:

```lua theme={null}
---@[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:

```lua theme={null}
---@[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:

```lua theme={null}
---@[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:

```lua theme={null}
---@[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:

```lua theme={null}
---@[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:

```lua theme={null}
---@[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.

***

## See also

* [Realm awareness](/language/realm-awareness): realm inference from file loading
* [Network analysis](/language/network-analysis): net message tracking
* [Hook intelligence](/language/hook-intelligence): hook completion and callback inference
* [VGUI support](/language/vgui-support): panels and Derma skins
* [Guard metadata](/annotations/guard-metadata): validity guards for nil and NULL checks