Realm awareness

Overview

Garry’s Mod Lua runs in two realms: client (CLIENT) and server (SERVER). Code that runs in both is called shared. Many GMod API functions only exist in one realm (for example, LocalPlayer() is client-only). Calling them in the wrong realm is a common bug. GLuaLS works out where each file and code block runs, then reports realm-restricted calls that cannot run there.

Realm detection

GLuaLS combines file names, project folders, load calls, code branches, and annotations. Most projects need no extra setup.

`@realm` annotations

Do not add file-level realm overrides if inference is already correct. It can hide real cross-realm mistakes. Prefer function-level overrides.

Put ---@realm at the top of a file or on a function:

---@realm client
function MyAddon.OpenMenu()
    vgui.Create("DFrame")
end

See the @realm annotation reference for full syntax. A function annotation can be more specific than its file.

File names

GLuaLS assigns realms to files that begin with cl_, sv_, or sh_:

Prefix	Realm
`cl_`	Client
`sv_`	Server
`sh_`	Shared

Project folders

GLuaLS assigns realms to files in common GMod directories:

Path pattern	Realm
`lua/autorun/client/`	Client
`lua/autorun/server/`	Server
`lua/autorun/`	Shared
`lua/client/`, `lua/vgui/`, `lua/postprocess/`, `lua/matproxy/`, `lua/skins/`	Client
`lua/effects/`, `lua/includes/`, `*/stools/`	Shared

This works for both common workspace layouts:

Garry’s Mod root: addons/<name>/lua/... and gamemodes/<name>/...
Addon or gamemode root: lua/..., gamemode/..., and entities/...

`CLIENT` and `SERVER` branches

Within shared files, GLuaLS narrows realm within if CLIENT / if SERVER blocks:

if CLIENT then
    -- GLuaLS treats this block as client-only
    surface.DrawRect(0, 0, 100, 100) -- OK here
end

if SERVER then
    -- This block is server-only
    ply:SetHealth(100) -- OK here
end

Load calls

When call-based detection is on, GLuaLS also looks at file-loading calls:

AddCSLuaFile("file.lua") marks that file as Client
AddCSLuaFile() (no args) adds a Shared hint to the current file (stronger filename/path hints can still resolve as Client or Server)
IncludeCS("file.lua") is treated like AddCSLuaFile("file.lua") + include("file.lua")
IncludeCS() with no filename is ignored
require("mod") marks the required module as Shared
include("file.lua") passes realm hints to the included file

AddCSLuaFile does not mark the caller as server. It only affects the target file. These rules also apply to annotated wrappers. GLuaLS can follow common file.Find loader loops too, including wrappers described by the GMod annotations. See @call_arg for wrapper examples.

Loading defaults

Default path-based realm rules follow Garry’s Mod’s usual loading conventions and similar addon patterns. See Lua Loading Order for reference.

Realm diagnostics

Code	Description
`gmod-realm-mismatch`	Code uses an API that is unavailable in its known realm
`gmod-realm-mismatch-heuristic`	Code probably uses an API from the wrong realm, but the file realm is less certain
`gmod-unknown-realm`	GLuaLS cannot determine the realm for a realm-specific call

Disabling realm checks

Disable realm checks only when necessary. Other features depend on realm detection. In most cases, disable only specific diagnostics from settings.

Disable realm diagnostics workspace-wide:

Use the settings menu instead of editing the JSON file directly. This helps you avoid config mistakes.

.gluarc.json

{
  "diagnostics": {
    "disable": ["gmod-realm-mismatch", "gmod-realm-mismatch-heuristic", "gmod-unknown-realm"]
  }
}

Or set the known realm for a specific file:

---@realm shared
-- Shared code follows.

Per-function realm overrides

Override or set realm detection for an individual function:

---@realm server
function MyAddon.ServerAction()
    -- This function is always treated as server-side,
    -- even if the surrounding file is shared
end

Use function-level annotations when only one function needs a different realm.

Realm in hover and autocomplete

GMod API hovers and completions show where a symbol is available:

Client badge: function is clientside only
Server badge: function is serverside only
Shared badge: function is available on both realms

The badge appears in completions as well, so you can check a function’s realm before inserting it. Realm also filters autocomplete. In client files, server-only functions are hidden (and vice versa). If a function seems missing, check inferred realm first.

Overview

Code intelligence

Garry's Mod

Classes

Debugger

AI integration

Overview

Realm detection

`@realm` annotations

File names

Project folders

`CLIENT` and `SERVER` branches

Load calls

Loading defaults

Realm diagnostics

Disabling realm checks

Per-function realm overrides

Realm in hover and autocomplete

​Overview

​Realm detection

​@realm annotations

​File names

​Project folders

​CLIENT and SERVER branches

​Load calls

​Loading defaults

​Realm diagnostics

​Disabling realm checks

​Per-function realm overrides

​Realm in hover and autocomplete

Overview

Realm detection

`@realm` annotations

File names

Project folders

`CLIENT` and `SERVER` branches

Load calls

Loading defaults

Realm diagnostics

Disabling realm checks

Per-function realm overrides

Realm in hover and autocomplete