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

# Conventions

> Naming, typing, errors and commits.

## Naming

| Thing | Style | Example |
| - | - | - |
| Public API function | PascalCase | `UgCore.Players.Get` |
| Namespace | PascalCase | `UgCore.Accounts` |
| Local function | camelCase | `local function createRoot()` |
| Local constant | UPPER\_SNAKE | `local STATE_KEY = 'ug-core:Config'` |
| Data field, option key | camelCase | `requirePlayer`, `startingBalance` |
| Module and config name | camelCase | `accounts`, `core` |
| File and folder | lowercase | `core/server/config/loader.lua` |
| Core event | `ug-core:<Area>:<Event>` | `ug-core:Players:Loaded` |
| Statebag key | `ug-core:<Key>` | `ug-core:Loaded` |
| Convar | `ug-core:<Config>:<Key>` | `ug-core:Guard:KickScore` |
| Export | `<Namespace><Function>` | `AccountsGetBalance` |

## File header

Every `.lua` file starts with the license header, then one blank line:

```lua theme={null}
--[[

    ug-core - https://github.com/ugcore-project
    Copyright (C) 2026 UgCore Framework & Contributors
    Licensed under the GNU General Public License. See LICENSE for details.

]] --
```

## Typing

* Every function has LuaLS annotations: `---@param`, `---@return`.
* Namespaces are plain tables with a `---@class`. The source is the type source of truth.
* To define functions through a local, the local is the class declaration:

```lua theme={null}
---@class UgCore.Schema
local Schema = {}
UgCore.Schema = Schema
```

* Enums use `---@enum` directly on the field.
* Multiple returns keep one type per slot: `ok, value, errorCode`, never `ok, valueOrMessage`.
* Gaps in the CfxLua types go in `types/cfx.lua`, never in `---@diagnostic` comments.

## Errors

* Mutating functions return `ok, value` or `ok, errorCode` with codes from `UgCore.Enums.Errors`.
* Programmer errors raise with `UgCore.Internal.Utils.Raise(level, message, ...)`, never `error`. Messages never include the `[ug-core]` prefix.
* Stack traces never reach clients.

## Comments

Short sentences. RFC 2119 keywords for obligations. Comment only where the code needs clarification. Never narrate.

## Performance

Cache globals and natives in locals only on hot paths: per request, per item or per tick. Everything else calls them directly.

## Commits

[Conventional Commits](https://www.conventionalcommits.org). Imperative, lowercase subject, no period, 72 characters max.

```text theme={null}
feat(accounts): add loan accounts
fix(players): keep downed state on reconnect

Refs: #192
```

Scopes: `core`, `players`, `characters`, `accounts`, `jobs`, `gangs`, `permissions`, `identity`, `sessions`, `modules`, `callback`, `network`, `events`, `lifecycle`, `hooks`, `database`, `exports`, `config`, `locale`, `ci`, `deps`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.