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

# @field

> Add typed fields to a class definition.

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

```lua theme={null}
---@field [access] fieldName type [description]
---@field [access] fieldName? type [description]
---@field [access] [keyType] valueType [description]
```

***

## Basic fields

Place `@field` annotations immediately after a `@class` line:

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

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

***

## Access control

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

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

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

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

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

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

***

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