lua-best-practices
/lua-best-practices
Opisuje dobre praktyki Lua dla zasobów FiveM opartych na ox_lib: require, lib.load, podział na moduły, konfigurację, cache, lib.points, lib.callback i lokalizacje.
- Autor
- overextended ↗
- Repozytorium
- skills ↗
- Licencja
- GPL-3.0
- Ostatnia zmiana repozytorium
- 17.10.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 3
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 17.10.2026, bez odwołań do wycofanych modeli i API.
GPL-3.0, otwarta.
Co robi i kiedy
Opisuje dobre praktyki Lua dla zasobów FiveM opartych na ox_lib: require, lib.load, podział na moduły, konfigurację, cache, lib.points, lib.callback i lokalizacje.
Oryginalny opis (EN)
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.
Jak działa
- Loading code and data
- Manifest
- Config
- Scope
- Layout
- oxlib at runtime
- CfxLua
- Annotations
- Examples
Podgląd SKILL.md
---
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.
Pliki w paczce (3)
- PATTERNS.md 7 KB
- SKILL.md 9 KB
- agents/openai.yaml 1 KB
Wersje
W bazie nie ma innych skilli o nazwie lua-best-practices.
Migawka bazy z 13.11.2026 · wersja paczki 035ab3354be2 (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 1 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100fivem-natives
Weryfikuje natywne funkcje FiveM i GTA V w offline'owej bazie 7191 natywów: nazwę, sygnaturę, kolejność parametrów i stronę klient lub serwer przed pisaniem kodu Lua lub JS. - 100deslop
Usuwa ślady pisania przez AI z zasobów FiveM w Lua, TypeScript i JavaScript bez zmiany działania, po zakończeniu zmiany i przed commitem. - 90lua-guide
Pomaga pisać ogólne skrypty Lua 5.4+: moduły, zakresy zmiennych, metatabele, korutyny i obsługę błędów w plikach .lua. - 100xmake-scripting
Pomaga pisać logikę w xmake.lua: hooki on_build, import() modułów i budowanie natywnych modułów Lua w C/C++. - 100typescript-best-practices
Pokazuje, jak typować zdarzenia, callbacki i wiadomości NUI w zasobach FiveM napisanych w TypeScript. - 85Lua C Integration
Omawia Lua C API do rozszerzania Lua kodem natywnym: operacje na stosie, wywołania C z Lua i odwrotnie, moduły C, userdata, metatabele i optymalizacje wydajności.