esx-framework

ESX Framework

ESX Legacy 的服务器端／客户端 API：xPlayer、PlayerData、回调、事件、工作和金钱。

激活约定

当用户创建或编辑 ESX 资源、操作 xPlayer 或 ESX.PlayerData、需要通过 ESX 处理工作、金钱、账户、物品或武器，或询问 ESX 回调、事件或最佳实践时，加载此技能。

硬性规则

• 使用 ESX = exports['es_extended']:getSharedObject() 获取对象。在客户端读取 ESX.PlayerData 前，先等待 ESX 和 ESX.IsPlayerLoaded()。
• xPlayer 仅存在于服务器端（ESX.GetPlayerFromId(source)）。ESX.PlayerData 仅存在于客户端。
• 始终进行 nil 检查：调用任何方法前先执行 if not xPlayer then return end。
• 金钱、物品、武器、工作和元数据必须通过服务器端的 xPlayer.* 方法修改，绝不能从客户端修改。
• 调用 addMoney、removeMoney、addAccountMoney、removeAccountMoney 时传入 reason。
• 客户端回调（ESX.TriggerClientCallback、ESX.AwaitClientCallback）绝不能用于决定敏感事项：客户端可以伪造答案。
• 对只能由服务器触发的客户端事件，使用 ESX.SecureNetEvent。
• 通知、菜单、对话框和进度条优先使用 ox_lib，而非 ESX UI。
• 缓存 PlayerPedId()，并在 esx:playerPedChanged 时更新；没有必要时不要使用 Wait(0) 循环。

决策指引

需求	使用
客户端向服务器请求数据	ESX.RegisterServerCallback + ESX.TriggerServerCallback
服务器向单个玩家推送事件	xPlayer.triggerEvent(name, ...)
仅服务器可触发的客户端事件	客户端上的 ESX.SecureNetEvent(name, cb)
按 source／标识符查找玩家	ESX.GetPlayerFromId / ESX.GetPlayerFromIdentifier
按工作等条件筛选玩家	ESX.GetExtendedPlayers(key, value)
可使用的物品	ESX.RegisterUsableItem(item, cb)
带群组权限的管理员命令	ESX.RegisterCommand(name, group, cb, allowConsole, suggestion)

执行步骤

1. 确认 es_extended 在该资源之前启动；按运行端获取 ESX。
2. 确定运行端：在服务器端修改和验证，在客户端显示。
3. 获取 xPlayer 并进行 nil 检查，然后验证每个由客户端提供的参数。
4. 从决策指引中选择调用方式；查看对应规则文件了解签名。
5. 通过回调返回数据，不要使用成对事件。

输出约定

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

参考资料

• rules/core-concepts.md — 架构、PlayerData、xPlayer、启动流程。
• rules/client-functions.md — 客户端 ESX 函数和玩家状态。
• rules/server-functions.md — 玩家检索、回调、命令、工作、物品。
• rules/xplayer-methods.md — xPlayer 金钱、账户、背包、武器和元数据。
• rules/events-callbacks.md — 服务器端／客户端回调、事件、SecureNetEvent。
• rules/best-practices.md — 命名、缓存、循环、安全、Lua 5.4。
• rules/reference-links.md — ESX 官方文档链接。

上游文档：https://docs.esx-framework.org