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

# Realm awareness

> GLuaLS understands where code runs — client, server, or shared — and warns about cross-realm API usage.

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

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

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

```lua theme={null}
---@realm client
function MyAddon.OpenMenu()
    vgui.Create("DFrame")
end
```

See the [`@realm` annotation reference](/annotations/realm) 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:

```lua theme={null}
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`](/annotations/call-arg#lua-loading) 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](https://wiki.facepunch.com/gmod/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

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

Disable realm diagnostics workspace-wide:

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

```json .gluarc.json theme={null}
{
  "diagnostics": {
    "disable": ["gmod-realm-mismatch", "gmod-realm-mismatch-heuristic", "gmod-unknown-realm"]
  }
}
```

Or set the known realm for a specific file:

```lua theme={null}
---@realm shared
-- Shared code follows.
```

***

## Per-function realm overrides

Override or set realm detection for an individual function:

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