@field

Overview

@field declares a class property. You can add an access level, a ? for nilable fields, and a description. Annotate fields you use often so GLuaLS can give better types and autocomplete.

Syntax

---@field [access] fieldName type [description]
---@field [access] fieldName? type [description]
---@field [access] fieldName type = default [description]
---@field [access] [keyType] valueType [description]

Basic fields

Place @field annotations immediately after a @class line:

---@class User
---@field id number User ID
---@field name string Display name
---@field email string Email address
---@field createdAt string ISO timestamp

Optional fields

Add ? after the field name to mark it as nil sometimes:

---@class Player
---@field steamId string
---@field nickname? string Optional display name
---@field clan? string Optional clan tag

If you access an optional field without a nil check, GLuaLS reports need-check-nil when you enable strict nil checking.

Default values

Add = value after the type when something else fills the field in later, such as a base class or a setup function:

---@class WeaponConfig
---@field damage number
---@field clipSize number = 30
---@field recoil number = 1.5

---@type WeaponConfig
local cfg = { damage = 25 }   -- no warning: clipSize and recoil have defaults

You can leave a field with a default out of a table, and GLuaLS does not report missing-fields. When you read it, the type stays number — not number? — so you do not need a nil check.

Use = value when the field is always there by the time you read it. Use ? when it can still be nil at read time. Picking ? for this case forces nil checks everywhere you read the field.

Defaults accept numbers, strings, true, false, nil, and a name or call such as Color(255, 255, 255):

---@class PanelStyle
---@field label string = "Untitled"
---@field visible boolean = true
---@field colour Color = Color(255, 255, 255)

Access control

Access modifiers do not change runtime behavior. GLuaLS checks them and can report diagnostics when code uses private or protected fields from the wrong place. Treat them as type and style rules, not runtime access control.

Modifier	Description
`public`	Accessible everywhere (default)
`private`	Only accessible within class methods
`protected`	Only accessible in the class and subclasses
`package`	Only accessible within the same file/package

---@class MyClass
---@field public name string
---@field private m_count number
---@field protected m_parent MyClass?

Index-type fields

Use [keyType] syntax to define all keys of a type at once:

---@class Config
---@field [string] any Any string key maps to any value

---@class NumberIndex
---@field [number] Entity Array-style numeric indexing

Function fields

Fields can use function types:

---@class EventEmitter
---@field on fun(event: string, callback: fun(data: any)): nil
---@field emit fun(event: string, data: any): nil
---@field off fun(event: string): nil

Use this when code outside the Lua file adds the function, such as C++. If Lua defines the function, annotate the function itself to avoid duplicate definitions.

Tips and best practices

Place @field annotations directly after their @class declaration.
GLuaLS disables the inject-field diagnostic by default. Classes act as (partial), so you can define fields anywhere in the file. Fields are optional, but they improve type checking and autocomplete for the class.

Overview

Type system

Functions

Garry's Mod Lua

Utilities

Overview

Syntax

Basic fields

Optional fields

Default values

Access control

Index-type fields

Function fields

Tips and best practices

​Overview

​Syntax

​Basic fields

​Optional fields

​Default values

​Access control

​Index-type fields

​Function fields

​Tips and best practices

Overview

Syntax

Basic fields

Optional fields

Default values

Access control

Index-type fields

Function fields

Tips and best practices