fivem-development

FiveM Development — Best Practices

Framework-agnostic orchestrator for FiveM resource development. Supports vRP, QBCore, Qbox, and ESX via dedicated framework skills.

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, reuse local function helpers
6. Project memory — reference.mdc = lean global map (alwaysApply); .fxmind/memory/<topic>.md = shared compact recipe (lang: en-compact, structured frontmatter). All agents read/write the same .fxmind/ folder. Run /fxmind learn before rescanning; /fxmind memory health [fix] after refactors; /fxmind graph for snapshot; /fxmind query for graph-based retrieval in tasks and questions.
7. Audit assertiveness — /fxmind audit (fxmind) follows best-practices.md §2.4 + §2.5 quality gates (manifest-only files, Summary = Findings row counts not matrix themes, all V-b call sites).

---

CRITICAL: No Hallucination Policy

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

Rules

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

• Is this a real FiveM native? → Verify at docs.fivem.net/natives
• Is this the correct function name? → Check exact spelling
• Are these the correct parameters? → Verify parameter order and types
• Does this work on client/server/both? → Check availability

When you don't know

"I'm not 100% certain about this native/API. Let me fetch the documentation..."
[Use WebFetch to get accurate info]

---

FiveM Natives — Official Source

• Docs: https://docs.fivem.net/natives/
• Official Repository (mirror): https://github.com/proelias7/fivem-natives

---

Dynamic Documentation Fetching

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

Decision Tree

Documentation Sources

WebFetch Examples

WebFetch(
  url: "https://docs.fivem.net/natives/",
  prompt: "Find documentation for the native function '{FUNCTION_NAME}'.
           Include: parameters, return values, usage examples,
           client/server availability."
)

WebFetch(
  url: "https://forge.plebmasters.de/",
  prompt: "Search for GTA V {ASSET_TYPE} matching '{SEARCH_TERM}'.
           Return model names/hashes that can be used in FiveM."
)

---

Request Router

---

Before Writing Lua

When creating or editing a FiveM resource (server/client Lua):

1. READ best-practices.md sections 3.5–3.9 (monolith layout, reuse, comments, variable placement, checklist)
2. Default to one server.lua and one client.lua unless split is clearly justified
3. Do not over-comment or over-split files — see best-practices.md §3.10 (anti-patterns)

---

Critical Performance Rules

ALWAYS follow these rules when writing code:

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 (dist < 20 = 0, dist < 50 = 500, else = 1000+).
3. Calls in same environment: Call functions directly. NEVER use TriggerEvent() to call on the same side.
4. No remote calls in loops: Do not use callbacks/events in loops < 5 seconds. Prefer batch or delta.
5. Small Payloads: Send only the change, not full data. Limit of ~8KB per event.
6. Cache: Use exports["cacheaside"]:Get() for repeated database queries. Never query the database in a loop.
7. Large sync: Large server→client payloads use exports["cerberus"]:SendFullSync or SendDeltaSync — no manual chunking.
8. Delta sync: Prefer SendDeltaSync for unit updates; use SendFullSync only for bootstrap/full cache.
9. SafeEvent: Server events that grant money, items, XP, vehicles, or bypass restrictions must call exports["cerberus"]:SafeEvent (with config.modules.safeEvent = true) and server-side validation.
10. SetCooldown: Repetitive client/NUI actions (open menu, use item, spam callbacks) use exports["cerberus"]:SetCooldown before TriggerServerEvent.
11. Server security: Validate money, items, permissions, and distance on the server; never trust client/NUI data.
12. Tables > if/else: For 3+ conditions, use lookup table (O(1)) instead of if/elseif chains.
13. Protect nil: Always check variables before concatenating. Use or "" as fallback.

---

Framework Skills

For auto-detection and multi-framework bridge pattern, see framework-detection.md.

---

Resource Structure

Prefer monolith layout. See best-practices.md §3.5 for when to split files.

resource_name/
├── fxmanifest.lua
├── shared/config.lua
├── server/server.lua      # default: all server logic here
└── client/client.lua      # default: all client logic here

Optional NUI (see skill fivem-react-nui):

└── html/ or src/ui/
    ├── index.html
    └── ...

---

Anti-Patterns

---

External Resources (Download)

• cacheaside (in-memory cache): git@github.com:proelias7/cacheaside.git
• cerberus (modular: load balance, SafeEvent, SetCooldown): git@github.com:proelias7/cerberus.git

---

Additional References

• Detailed best practices (performance, security, cache, broadcast §1.6.1, §2.4 audit, §5.1): best-practices.md
• Asset discovery (props, vehicles, peds, weapons): asset-discovery.md
• Framework auto-detection and bridge: framework-detection.md
• NUI interface construction: use skill fivem-react-nui