fivem-dev

FiveM 开发

动态文档编排器，用于 FiveM 资源开发。 支持使用 Lua 和 NUI（JS/TS）的 QBox、QBCore、ESX 框架。

理念

1. 获取，而非记忆——始终从权威来源获取最新信息
2. 框架无关的思维方式——理解模式，并根据框架进行适配
3. 性能优先——FiveM 的 tick 预算严格
4. 关注安全性——服务端验证不可妥协

---

关键：禁止幻觉政策

绝不编造或猜测原生函数、框架 API 或参数。

规则：

1. 如果不确定某个原生函数 → 必须从 https://docs.fivem.net/natives/ 获取信息
2. 如果不确定框架 API → 必须从官方文档获取信息
3. 如果某个函数不存在 → 如实告知用户，并建议替代方案
4. 如果参数未知 → 获取文档，不要猜测

编写任何原生函数或 API 调用之前：

• 这是一个真实的 FiveM 原生函数吗？→ 在 docs.fivem.net/natives 验证
• 函数名称正确吗？→ 检查拼写是否准确
• 参数正确吗？→ 验证参数顺序和类型
• 此函数适用于客户端、服务端还是两者？→ 检查可用性

当你不知道时：

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

验证来源：

类型	来源	操作
原生函数	https://docs.fivem.net/natives/	使用 WebFetch 或告知用户自行检查
QBox API	https://docs.qbox.re/	使用 WebFetch
QBCore API	https://docs.qbcore.org/	使用 WebFetch
ESX API	https://docs.esx-framework.org/	使用 WebFetch
ox_lib	https://overextended.dev/ox_lib	使用 WebFetch
道具/载具	https://forge.plebmasters.de/	指引用户搜索

示例——错误：

-- DON'T: Inventing a native that might not exist
SetPlayerInvincible(playerId, true)  -- Is this real? What are the params?

示例——正确：

-- DO: Use verified native with correct params
SetEntityInvincible(PlayerPedId(), true)  -- Verified at docs.fivem.net

---

内容索引

仅根据请求阅读相关文件：

文件	描述	阅读时机
frameworks/framework-detection.md	检测当前使用的框架	开始新任务时
frameworks/qbox.md	QBox 导出项、模式	QBox 项目
frameworks/qbcore.md	QBCore 事件、导出项	QBCore 项目
frameworks/esx.md	ESX xPlayer、事件	ESX 项目
scripting/lua-patterns.md	FiveM 的 Lua 习惯用法	编写 Lua 时
scripting/nui-guide.md	NUI HTML/CSS/JS 模式	构建 UI 时
scripting/client-server.md	架构模式	新建资源时
scripting/thread-management.md	性能模式	优化时
resources/manifest.md	fxmanifest.lua 参考	设置资源时
resources/ox-lib-guide.md	ox_lib 实用工具	使用 ox_lib 时
assets/asset-discovery.md	查找 GTA V 资产	道具、载具、行人模型

---

动态获取——决策树

步骤 1：对请求进行分类

如果用户询问……	操作
原生函数（GetPlayerPed、CreateVehicle 等）	从原生函数文档获取信息
框架 API（QBCore.Functions、ESX.GetPlayerData）	从框架文档获取信息
ox_lib 功能（lib.callback、lib.notify）	从 ox_lib 文档获取信息
GTA V 资产（道具、载具、行人模型）	指引用户前往 PlebMasters
资源结构、清单文件	阅读本地文件
最佳实践、模式	阅读本地文件

步骤 2：WebFetch URL

原生函数

基础 URL： https://docs.fivem.net/natives/

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."
)

原生函数类别：

类别	包含内容
PLAYER	GetPlayerPed、GetPlayerServerId、PlayerId
VEHICLE	CreateVehicle、SetVehicleMod、GetVehicleClass
PED	CreatePed、SetPedComponentVariation、IsPedInVehicle
ENTITY	GetEntityCoords、SetEntityHeading、DeleteEntity
GRAPHICS	DrawRect、DrawText3D、DrawMarker
UI	SetTextEntry、BeginTextCommandDisplayText
CAM	CreateCam、SetCamActive、RenderScriptCams
AUDIO	PlaySoundFrontend、PlayAmbientSpeech1
WEAPON	GiveWeaponToPed、GetSelectedPedWeapon
CFX	Statebags、服务端专用原生函数

框架文档

QBox：

WebFetch(
  url: "https://docs.qbox.re/",
  prompt: "Find documentation for QBox '{FEATURE}'.
           Include exports, events, and usage examples."
)

QBCore：

WebFetch(
  url: "https://docs.qbcore.org/qbcore-documentation/",
  prompt: "Find documentation for QBCore '{FEATURE}'.
           Include: function signature, parameters, examples."
)

ESX Legacy：

WebFetch(
  url: "https://docs.esx-framework.org/",
  prompt: "Find documentation for ESX '{FEATURE}'.
           Include: xPlayer methods, events, server/client functions."
)

ox_lib：

WebFetch(
  url: "https://overextended.dev/ox_lib",
  prompt: "Find documentation for ox_lib '{MODULE}'.
           Include: function signatures, options, examples."
)

资源发现

PlebMasters Forge：

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."
)

**资源类型：**物体、载具、行人、武器、服装、动画

---

请求路由器 - 模式匹配

规则 1：原生函数检测

触发条件：

• 特定原生函数名称（PascalCase，例如 GetPlayerPed、CreateVehicle）
• “原生函数”、“GTA 原生函数”、“FiveM 原生函数”
• 哈希引用（0x...）

**操作：**从 https://docs.fivem.net/natives/ 获取

规则 2：框架 API 检测

触发条件：

• QBCore.Functions.*、QBCore.Player.*
• exports.qbx_core:*、exports['qb-core']:*
• ESX.Get*、xPlayer:*、ESX.RegisterServerCallback
• exports.es_extended:*

**操作：**检测框架 → 从相应文档获取

规则 3：ox_lib 检测

触发条件：

• lib.* 函数
• exports.ox_lib:*
• 模块：callback、notify、menu、context、progress、zones、target

**操作：**从 https://overextended.dev/ox_lib 获取

规则 4：资源发现

触发条件：

• “……的模型是什么？”、“……的 prop 名称是什么？”、“载具生成名称”
• 物体放置、行人模型、武器模型

**操作：**引导至 PlebMasters Forge，并提供用法示例

规则 5：本地知识

触发条件：

• fxmanifest.lua 结构
• 客户端/服务端模式
• 线程管理
• 项目结构

**操作：**读取相关的本地 Markdown 文件

---

框架自动检测

开始任务时，从项目文件中检测当前使用的框架：

检查 fxmanifest.lua

-- QBox indicators
dependency 'qbx_core'
dependency 'ox_lib'

-- QBCore indicators
dependency 'qb-core'

-- ESX indicators
dependency 'es_extended'
dependency 'esx_core'

检查代码导入

-- QBox
local QBX = exports.qbx_core:GetCoreObject()

-- QBCore
local QBCore = exports['qb-core']:GetCoreObject()

-- ESX
local ESX = exports.es_extended:getSharedObject()

---

最佳实践（快速参考）

性能规则

规则	原因
避免在循环中使用 Wait(0)	消耗 CPU，导致卡顿
缓存玩家 ped	local ped = cache.ped or PlayerPedId()
使用 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)	使用适当的等待或事件
信任客户端数据	始终在服务端验证
将框架硬编码	动态检测
每帧获取数据	设置刷新间隔并缓存
使用全局变量	使用局部变量并封装

---

相关技能

需求	技能
NUI 设计	frontend-design
数据库设计	database-design
安全审计	vulnerability-scanner
性能	performance-profiling