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

# Realm Awareness in GLua Language Server

> GLua Language Server assigns every file a realm from its path and narrows it further with if SERVER then blocks, then flags cross-realm API use.

GLua Language Server understands Garry's Mod's three execution contexts: Client, Server, and Shared. It assigns a realm to every file in your workspace, narrows that assignment inside conditional blocks, and then warns you when you call an API that does not exist in that realm.

## How realms are assigned

The server determines a file's realm from its path and filename conventions.

### Path-based assignment

| Path pattern          | Realm  |
| --------------------- | ------ |
| `lua/autorun/client/` | Client |
| `lua/autorun/server/` | Server |
| `lua/entities/`       | Shared |
| `lua/weapons/`        | Shared |
| `lua/vgui/`           | Client |
| `lua/autorun/`        | Shared |

### Filename prefix conventions

| Prefix | Realm  |
| ------ | ------ |
| `cl_`  | Client |
| `sv_`  | Server |

These prefixes are treated as informational hints. The server still respects the directory first, because many projects break the prefix convention.

### Narrowing with conditionals

Inside an `if SERVER then` block, the server narrows the realm to Server for everything in that branch. The same applies to `if CLIENT then`.

```lua theme={null}
if SERVER then
    -- Everything here is treated as serverside
    Player:Kick("Reason") -- Valid in this branch
end
```

## What it catches

### Cross-realm API misuse

The server flags when you call a serverside-only function from a clientside context:

```lua theme={null}
-- File: lua/autorun/client/my_addon.lua
local ply = LocalPlayer()
ply:Kick("Reason") -- Error: Kick is not available on the client
```

### Completion filtering

When you work in a clientside file, serverside-only functions are hidden from completion. You will not see `Player:Kick` suggested in a `cl_` file or anything under `lua/autorun/client/`.

## Realm certainty

Path-based detection is considered **certain**. If a file lives in `lua/autorun/server/`, the server treats it as strictly serverside.

Filename prefixes (`cl_`, `sv_`) are **informational**. They guide the initial assignment but do not override a conflicting directory. This protects you from false positives when a `cl_` file is included from a shared context.

<Note>
  A `cl_` file that is included serverside (for example, through `AddCSLuaFile` and `include` in a shared file) is not detectable from the path alone. The server will still treat it as clientside based on its location. If you intentionally share a prefixed file, add an explicit `---@realm shared` annotation at the top.
</Note>


## Related topics

- [GLua Language Server: GMod Lua IDE Support](/index.md)
- [Configure GLua Language Server](/configuration/overview.md)
- [Get Started with GLua Language Server](/quickstart.md)
- [Install GLua Language Server for VS Code](/installation.md)