lua-best-practices
/lua-best-practices
Lua best practices for FiveM resources built on ox_lib, the way Overextended structures its own resources. Use when reading or editing any .lua file or fxmanifest.lua, or when the user asks when to use require, lib.load or lib.loadJson, how to split a resource into modules, where config goes, or how to use cache, lib.onCache, lib.points, lib.callback or locales.
- Author
- overextended ↗
- Repository
- skills ↗
- Licence
- GPL-3.0
- Last repository change
- 17.10.2026
Assessment and security
- Files in this package
- 3
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 17.10.2026, without references to retired models or APIs.
GPL-3.0, otwarta.
What it does and when to use it
Lua best practices for FiveM resources built on ox_lib, the way Overextended structures its own resources. Use when reading or editing any .lua file or fxmanifest.lua, or when the user asks when to use require, lib.load or lib.loadJson, how to split a resource into modules, where config goes, or how to use cache, lib.onCache, lib.points, lib.callback or locales.
Original author description
Lua best practices for FiveM resources built on ox_lib, the way Overextended structures its own resources. Use when reading or editing any .lua file or fxmanifest.lua, or when the user asks when to use require, lib.load or lib.loadJson, how to split a resource into modules, where config goes, or how to use cache, lib.onCache, lib.points, lib.callback or locales.
How it works
- Loading code and data
- Manifest
- Config
- Scope
- Layout
- oxlib at runtime
- CfxLua
- Annotations
- Examples
SKILL.md preview
---
name: lua-best-practices
description: Lua best practices for FiveM resources built on ox_lib, the way Overextended structures its own resources. Use when reading or editing any .lua file or fxmanifest.lua, or when the user asks when to use require, lib.load or lib.loadJson, how to split a resource into modules, where config goes, or how to use cache, lib.onCache, lib.points, lib.callback or locales.
paths:
- "**/*.lua"
---
# Lua best practices
Write resource Lua the way Overextended writes ox_inventory, ox_target and ox_fuel: one entry script per side, every other file a module loaded with `require`, data loaded with `lib.load`, settings read from convars, and ox_lib's `cache` and `lib.*` modules instead of hand-rolled loops. Checked against ox_lib 3.40.3. Read the `ox resources` line of `.ox/config.md` (walk up from the current directory) for the server's ox_lib version; if it is older, check anything below against that version's source.
Including `@ox_lib/init.lua` replaces the global `require` with ox_lib's own loader. It resolves paths from the resource root, not the calling file, and it can load files from other resources. Everything below assumes it.
## Loading code and data
| Call | Use it for | How it behaves |
|------|------------|----------------|
| `require 'client.utils'` | Code modules: files that define functions or state and `return` a table | Runs the file once per resource and side, then returns the cached value to every later caller, so every module shares one instance. Errors on a circular require. A file that returns nothing gives `true`. |
| `lib.load 'data.stations'` | Data files (`data/*.lua` returning a table), and files run for their side effects | Runs the file on every call and returns a fresh value; nothing is cached. Takes an optional environment table as its second argument. |
| `lib.loadJson 'data.prices'` | JSON data files | Reads `data/prices.json` and returns the decoded table. |
| `require '@ox_core.lib.init'` | Another resource's Lua library | Runs that file inside your resource: you get your own copy, not shared state. Read another resource's live state through its exports. |
Path rules, shared by all three:
- Dots separate directories and there is no extension: `require 'modules.inventory.server'` loads `modules/inventory/server.lua`. File names can't contain dots.
- `require 'client'` tries `client.lua`, then `client/init.lua`.
- `@resource.path` loads from another resource; `@resource` alone loads its `init.lua`.
- A file loaded on the client must be listed in the manifest's `files`. Server-side files load from disk and need no listing.
Choosing:
- **Code goes through `require`.** Put `local utils = require 'client.utils'` at the top of the file that uses it, and end every module with `return` of its table.
- **Data goes through `lib.load`**, called once where the data is consumed (`for id, data in pairs(lib.load('data.crafting') or {}) do`). It isn't cached, so never call it inside a loop or an event handler.
- **Read-only config shared by several modules** can be a module: `config.lua` returns a table and every file does `local config = require 'config'`.
- **A file is a manifest script or a module, never both.** Listing a file in `client_scripts` and also requiring it runs it twice.
- **Load optional parts lazily**: `if config.ox_target then return require 'client.target' end`, or a framework bridge required only in the branch that detects that framework.
- Don't hand-roll `LoadResourceFile` plus `load`. ox_inventory's own `data()` loader is deprecated in favour of `lib.load`.
## Manifest
- `fx_version 'cerulean'`, `lua54 'yes'` and `use_experimental_fxv2_oal 'yes'`, as every ox resource has.
- `shared_script '@ox_lib/init.lua'` comes before any of the resource's own scripts, and `ox_lib` is in `dependencies`.
- One entry script per side (`client/init.lua`, `server/init.lua`, or a single `init.lua` that ends with `require 'server'` or `require 'client'` depending on `lib.context`). The entry script requires everything else.
- `files` lists every module, data file and locale the client loads (`'client/*.lua'`, `'data/*.lua'`, `'locales/*.json'`). Every client downloads everything in `files`, so don't list server-only code there.
- `ox_libs { 'locale', 'table' }` loads those `lib` modules when the resource starts. Listing `locale` there also loads the locale strings, which ox_lib prefers over calling `lib.locale()` yourself. Any other `lib.*` module loads on first use, so never `require` one.
## Config
- **Settings a server owner tunes** are convars named `<resource>:<setting>`, read once at the top of the file that uses them: `GetConvarInt('ox_target:debug', 0)`, `GetConvarBool('inventory:target', false)`, `GetConvar('ox_target:defaultHotkey', 'LMENU')`. Structured settings go through `json.decode(GetConvar(...))`. Owners set them in `server.cfg`, so an update never overwrites their changes.
- **Structured data** (locations, items, shops, recipes) lives in `data/*.lua` files returning tables, loaded with `lib.load`.
- **A small resource** can use a `config.lua` that returns a table, required as a module. Follow whichever approach the resource already uses.
## Scope
- Every variable, function and module table is `local`. A module is `local Utils = {}`, its functions `function Utils.raycast(...)`, and `return Utils` at the end.
- A global is a deliberate choice for state every file on that side reads, never a forgotten `local`. All of a resource's scripts and modules on one side share one global scope.
- In a hot loop, cache a native as a local upvalue: `local GetVehiclePedIsIn = GetVehiclePedIsIn`.
## Layout
Code reads top to bottom in short steps, with blank lines between them and few long lines.
- One statement per line. `count = 0 return false` is two lines.
- A blank line between steps: the guards, the lookups, the work, the reply.
- A guard stays on one line only when it's short and its body is a bare `return` or `return false`: `if not player or not player.shop then return false end`. A guard that returns a table or does more goes across lines.
- A condition too long for one line becomes several guards, never one `if` wrapped across lines.
- A call or table constructor that runs past about 120 characters goes one argument or field per line. Shorter ones stay on one line.
- Indent with whatever `.editorconfig` or the file uses.
## ox_lib at runtime
- **`cache`** holds the player's state on the client, refreshed every 100 ms: `cache.ped`, `cache.vehicle` (`false` on foot), `cache.seat`, `cache.weapon`, plus `cache.playerId` and `cache.serverId`. Both sides have `cache.resource` and `cache.game`. Read `cache.ped`, not `PlayerPedId()`.
- **`lib.onCache('vehicle', function(value, oldValue) end)`** runs when a cached value changes. Use it instead of a loop that polls for the change.
- **Threads:** `CreateThread` and `Wait`. For repeating work use ox_lib's `SetInterval(fn, ms)` and `ClearInterval(id)`. For "do something near a location" use `lib.points.new({ coords = ..., distance = ..., onEnter = ..., onExit = ..., nearby = ... })`, not a distance loop. To wait for a value, use `lib.waitFor(fn, errMessage, timeout)`, which errors after `timeout` ms (default 1000).
- **Callbacks:** the server registers `lib.callback.register(name, function(source, ...) end)` and the client calls `lib.callback.await(name, delay, ...)`. `delay` is a client-side rate limit in ms, or `false`; a throttled call returns nothing. The client chooses every argument, so the server callback checks each one (type, range, ownership, distance) before acting.
- **Locales:** `locales/en.json` is the fallback, merged under the language set by the `ox:locale` convar. `locale('key', ...)` formats with `string.format` and returns the key itself when it's missing.
- **Logging:** `lib.print.error`, `warn`, `info`, `verbose`, `debug`. Owners filter them with the `ox:printlevel` convar, or `ox:printlevel:<resource>` for one resource.
- **Dependencies:** check a minimum version at the top of the entry script with `if not lib.checkDependency('ox_lib', '3.30.0', true) then return end`. Guard an optional resource with `GetResourceState('ox_target') == 'started'`.
## CfxLua
FiveM's Lua 5.4 runtime adds syntax that ox resources use everywhere. Match it:
- Backtick hashes for constant names: `` `WEAPON_UNARMED` `` is hashed at compile time. Keep `joaat(name)` for names built at runtime.
- Safe navigation: `data.server?.export` instead of `data.server and data.server.export`.
- Compound assignment: `count += 1`.
- `table.create(arraySize, hashSize)` to preallocate, `table.wipe(t)` to clear in place.
## Annotations
Annotate module functions with LuaLS comments (`---@param`, `---@return`, `---@class`) and narrow with `--[[@as OxClient]]` where a value's type can't be inferred. ox_lib ships its own annotations, so `lib.*` calls type-check in the editor.
## Examples
Read [PATTERNS.md](./PATTERNS.md) for a full resource layout and an example of each section.
Files in this package (3)
- PATTERNS.md 7 KB
- SKILL.md 9 KB
- agents/openai.yaml 1 KB
Versions
The database has no other skills named lua-best-practices.
Database snapshot: 13.11.2026 · package version 035ab3354be2 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 1 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100fivem-natives
FiveM/GTA V native verification and lookup database (7191 natives, offline). ALWAYS use it when writing, editing or reviewing FiveM Lua/JS code involves a native name, signature, parameter order or client/server side — even if the user does not ask. Do not write a native name… - 100deslop
Remove AI-generated slop from FiveM resource code (Lua, TypeScript, JavaScript) without changing behaviour. Use when the user asks to deslop, clean up or tidy code an agent wrote, or after finishing a change to a resource and before it is committed. - 90lua-guide
Use when editing general-purpose Lua 5.4+: modules, scripts, configuration. Triggers on `.lua` files and prompts about module patterns, local scoping, metatables, coroutines, error handling, even when the user doesn't say 'Lua'. - 100xmake-scripting
Use when writing custom Lua script logic inside `xmake.lua` — `on_load`/`on_build`/`after_build` hooks, `import()`, extracting script files under a `modules/` dir, importing xmake core modules (`core.base.option`, `lib.detect.find_tool`, …), or building native C/C++ Lua modules… - 100typescript-best-practices
TypeScript best practices for FiveM resources and their NUI. Use when reading or editing any .ts or .tsx file or a .svelte file with <script lang="ts">, or when the user asks how to type net events, callbacks, exports, NUI messages or state bags. - 85Lua C Integration
Use when lua C API for extending Lua with native code including stack operations, calling C from Lua, calling Lua from C, creating C modules, userdata types, metatables in C, and performance optimization techniques.