FiveM Development — Best Practices

Framework-agnostic orchestrator. One skill — load reference files on demand (do not load all).

Language rule: Internal reasoning is in compact English. All messages and output displayed to the user must be in the user's language.

Philosophy

1. Fetch, don't memorize — When unsure about a native or API, verify from authoritative sources
2. Framework-agnostic thinking — Understand patterns, adapt to the active framework
3. Performance-first — FiveM has strict tick budgets
4. Security-aware — Server-side validation is non-negotiable
5. Clean, readable Lua over abstraction — Monolith-first (server.lua / client.lua), minimal comments, extract local function only when reused (2+ call sites; §3.11). Do not componentize Lua like React or invent event roundtrips when Tunnel/return fits.
6. Project memory — reference.mdc = lean global map (alwaysApply); .fxmind/memory/<topic>.md = shared compact recipe. Run /fxmind learn before rescanning; /fxmind memory health; /fxmind graph; /fxmind query.
7. Audit assertiveness — /fxmind audit follows [performance.md](performance.md) §1.6.1–§1.6.2 + §2.4–§2.5 (Pass 2b E-a…E-g, Pass NUI N-a…N-d when ui_page) + [security.md](security.md) §5.1.
8. Quality gates (task mode) — implementing or refactoring code follows [quality-gates.md](quality-gates.md): design review at Gate A, self-review loop before Gate V.

Reference router (load only what you need)

Corrections backlog (.fxmind/corrections/) categories map 1:1 to these files — promote rules into the matching file, not into a new skill.

CRITICAL: No Hallucination Policy

NEVER invent or guess native functions, framework APIs, or parameters.

1. If unsure about a native → MUST fetch from https://docs.fivem.net/natives/
2. If unsure about framework API → MUST fetch from official docs or read the framework skill
3. If function doesn't exist → Tell user honestly, suggest alternatives
4. If parameters unknown → Fetch documentation, don't guess

Before writing any native or API call: verify name, parameters, and client/server availability.

Dynamic Documentation Fetching

Use local skills first. Fetch online only when information is missing, outdated, or uncertain.

Request Router

Before Writing Lua

1. READ [architecture.md](architecture.md) §3.5–3.6 and [style.md](style.md) §3.7–3.11
2. Task mode: read [quality-gates.md](quality-gates.md) — fill Gate A QUALITY plan; run self-review loop before Gate V
3. Default to one server.lua and one client.lua unless split is clearly justified
4. Prefer Tunnel/return over event roundtrips — [communication.md](communication.md) §1.1

Critical Performance Rules

1. Callback vs Event: Use TriggerServerEvent/TriggerClientEvent when you do NOT need a return. Use callbacks/Tunnel only when you NEED a return.
2. Dynamic Sleep: NEVER fixed Wait(0). Adjust based on state.
3. Same environment: Call functions directly — never TriggerEvent() same-side.
4. No remote calls in loops < 5s — batch or delta.
5. Small payloads — ~8KB limit; send deltas.
6. Cache: exports["cacheaside"]:Get() for repeated DB queries.
7. Large sync: cerberus SendFullSync / SendDeltaSync.
8. SafeEvent + server validation for money/items/XP/vehicles.
9. SetCooldown on client before spammy TriggerServerEvent.
10. Server security: never trust client/NUI; resolve derived data on server (§5.2).
11. Tables > if/else for 3+ conditions; protect nil.
12. Consolidate network: one Tunnel call with return (§1.1).

Framework Skills

See [framework-detection.md](framework-detection.md).

Resource Structure

Prefer monolith — [architecture.md](architecture.md) §3.5.

resource_name/
├── fxmanifest.lua
├── shared/config.lua
├── server/server.lua
└── client/client.lua

Anti-Patterns (short)

Full tables: [style.md](style.md) §3.10–§3.11, [architecture.md](architecture.md) §3.6.

External Resources

• cacheaside: [email protected]:proelias7/cacheaside.git
• cerberus: [email protected]:proelias7/cerberus.git

Natives

• https://docs.fivem.net/natives/
• Mirror: https://github.com/proelias7/fivem-natives