fivem-dev

用途

FiveM Development 是一个面向 FiveM 资源开发的动态文档编排技能，旨在帮助开发者在 QBox、QBCore 与 ESX 框架下编写 Lua 脚本和 NUI（JS/TS）界面。它不是知识库，而是文档获取与验证的编排层，核心哲学是“获取，而非记忆”。

核心理念

Fetch, don't memorize：始终从权威来源获取最新信息。
Framework-agnostic thinking：理解模式，适配框架。
Performance-first：FiveM 有严格的 tick 预算。
Security-aware：服务端验证不可协商。

反幻觉政策

技能明确禁止臆造或猜测原生函数、框架 API 或参数。规则包括：

不确定原生函数时，必须从 https://docs.fivem.net/natives/ 获取。
不确定框架 API 时，必须从官方文档获取。
函数不存在时，如实告知用户并建议替代方案。
参数未知时，先获取文档，不猜测。

编写任何原生或 API 调用前需确认：是否为真实 FiveM 原生、函数名拼写是否正确、参数顺序与类型是否正确、可用性是客户端/服务端/两者。

验证来源

原生函数：https://docs.fivem.net/natives/
QBox API：https://docs.qbox.re/
QBCore API：https://docs.qbcore.org/
ESX API：https://docs.esx-framework.org/
ox_lib：https://overextended.dev/ox_lib
道具/车辆：https://forge.plebmasters.de/

内容地图

按需读取相关文件：

frameworks/framework-detection.md：检测当前框架，用于开始新任务时
frameworks/qbox.md：QBox 导出与模式
frameworks/qbcore.md：QBCore 事件与导出
frameworks/esx.md：ESX xPlayer 与事件
scripting/lua-patterns.md：FiveM 的 Lua 惯用法
scripting/nui-guide.md：NUI HTML/CSS/JS 模式
scripting/client-server.md：架构模式
scripting/thread-management.md：性能模式
resources/manifest.md：fxmanifest.lua 参考
resources/ox-lib-guide.md：ox_lib 工具
assets/asset-discovery.md：查找 GTA V 资源

动态获取决策树

第一步：分类请求。原生函数从 natives 获取；框架 API 从框架文档获取；ox_lib 功能从 ox_lib 文档获取；GTA V 资源引导至 PlebMasters；资源结构与 manifest 读取本地文件；最佳实践与模式读取本地文件。

第二步：通过 WebFetch 获取 URL。原生函数按 PLAYER、VEHICLE、PED、ENTITY、GRAPHICS、UI、CAM、AUDIO、WEAPON、CFX 等类别查找。框架文档按 QBox、QBCore、ESX Legacy、ox_lib 分别获取。资源发现通过 PlebMasters Forge 搜索对象、车辆、行人、武器、服装、动画等。

请求路由规则

RULE 1 原生检测：触发于具体原生名称（PascalCase）、"native function"、"GTA native"、"FiveM native"、哈希引用（0x...），动作为从 docs.fivem.net/natives 获取。
RULE 2 框架 API 检测：触发于 QBCore.Functions.、exports.qbx_core:、ESX.Get*、xPlayer:、exports.es_extended: 等，动作为检测框架并从相应文档获取。
RULE 3 ox_lib 检测：触发于 lib.* 函数、exports.ox_lib:*，模块包括 callback、notify、menu、context、progress、zones、target，动作为从 overextended.dev 获取。
RULE 4 资源发现：触发于模型、道具、车辆生成名等查询，动作为引导至 PlebMasters Forge 并提供用法示例。
RULE 5 本地知识：触发于 fxmanifest.lua 结构、客户端/服务端模式、线程管理、项目结构，动作为读取相关本地 markdown 文件。

框架自动检测

开始任务时从项目文件检测活动框架。检查 fxmanifest.lua 依赖：QBox 为 qbx_core、ox_lib；QBCore 为 qb-core；ESX 为 es_extended、esx_core。检查代码导入：QBox 为 exports.qbx_core:GetCoreObject()；QBCore 为 exports['qb-core']:GetCoreObject()；ESX 为 exports.es_extended:getSharedObject()。

最佳实践

性能规则：避免在循环中使用 Wait(0)；缓存玩家 ped；使用 ox_lib target 替代距离检查；使用 Statebags 替代事件。

安全规则：服务端验证；净化玩家输入；使用回调；对操作进行速率限制。

资源结构示例：

resource_name/
├── fxmanifest.lua
├── config.lua
├── client/
│   └── main.lua
├── server/
│   └── main.lua
├── shared/
│   └── config.lua
└── html/              # NUI
    ├── index.html
    ├── style.css
    └── script.js

框架无关模式示例：

local Framework = {}

if GetResourceState('qbx_core') ~= 'missing' then
    Framework.Core = exports.qbx_core:GetCoreObject()
    Framework.Type = 'qbox'
elseif GetResourceState('qb-core') ~= 'missing' then
    Framework.Core = exports['qb-core']:GetCoreObject()
    Framework.Type = 'qbcore'
elseif GetResourceState('es_extended') ~= 'missing' then
    Framework.Core = exports.es_extended:getSharedObject()
    Framework.Type = 'esx'
end

return Framework

反模式

不要：while true do Wait(0)；信任客户端数据；硬编码框架；每帧获取数据；使用全局变量。应当：使用适当的 wait 或事件；始终在服务端验证；动态检测；使用带刷新间隔的缓存；使用 local 并封装。

技能介绍

用途