qbcore-framework

QBCore Framework

qb-core 的服务端／客户端 API：Player 对象、PlayerData、回调、工作、帮派、金钱和元数据。

激活约定

当用户创建或编辑 qb-core 资源、操作 Player／QBCore.PlayerData、需要通过 QBCore 使用工作、帮派、金钱、物品或元数据，或询问 QBCore 回调、事件或最佳实践时，加载此技能。

此技能适用于 qb-core（qbcore-framework）。如果用户使用的是 Qbox（qbx_core、exports.qbx_core），API 会有所不同：请说明这一点，不要盲目套用此技能。

硬性规则

• 只通过 local QBCore = exports['qb-core']:GetCoreObject() 获取一次核心对象；不要在每个函数中都调用它。
• Player 仅存在于服务端（QBCore.Functions.GetPlayer(source)）；QBCore.PlayerData 仅存在于客户端，并在 QBCore:Client:OnPlayerLoaded 后填充。
• 始终检查 nil：调用任何方法前，先执行 if not Player then return end。
• 金钱、工作、帮派、物品和元数据必须在服务端通过 Player.Functions.* 修改，绝不能从客户端修改。
• 调用 AddMoney、RemoveMoney、SetMoney 时传入 reason。
• 对同一状态应使用状态包或事件，不能同时使用两者。
• 在服务端验证每个由客户端提供的参数；绝不要信任客户端发送的金额、价格或物品名称。
• 通知、菜单、对话框和进度条优先使用 ox_lib。
• 循环中使用动态 Wait() 值；除非需要逐帧执行任务，否则避免使用 Wait(0)。

决策指南

需求	使用方式
客户端向服务端请求数据	QBCore.Functions.CreateCallback + QBCore.Functions.TriggerCallback
金钱	Player.Functions.AddMoney/RemoveMoney/SetMoney/GetMoney(moneyType, ...)
工作／值勤／帮派	Player.Functions.SetJob、SetJobDuty、SetGang
持久化的玩家标记	Player.Functions.SetMetaData / GetMetaData
物品（qb-inventory）	Player.Functions.AddItem/RemoveItem/GetItemByName/GetItemBySlot
共享运行时状态	状态包（参见 rules/core-concepts.md）

执行步骤

1. 确认 qb-core 在此资源之前启动；在客户端和服务端分别缓存 QBCore。
2. 确定执行端：在服务端修改和验证，在客户端显示。
3. 获取 Player 并检查 nil，然后验证每个由客户端提供的参数。
4. 从决策指南中选择调用方式；阅读对应的规则文件以了解函数签名。
5. 通过回调返回数据，不要使用成对事件。

输出约定

返回可运行的 Lua 代码，明确区分客户端和服务端，检查 Player 是否为 nil，并在金钱操作中提供原因。除非用户另有要求，UI 使用 ox_lib。

参考资料

• rules/core-concepts.md — 架构、PlayerData、Player 对象、事件、状态包。
• rules/player-methods.md — Player.Functions 金钱、工作、帮派、元数据和物品方法。
• rules/best-practices.md — 命名、缓存、等待、状态管理、安全性。
• rules/reference-links.md — QBCore 官方文档链接。

上游文档：https://docs.qbcore.org