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 を使います。
• 通知、メニュー、ダイアログ、プログレスバーには ESX UI より ox_lib を優先します。
• PlayerPedId() をキャッシュし、esx:playerPedChanged で更新します。必要のない Wait(0) ループは使いません。

判断基準

必要なこと	使用するもの
クライアントからサーバーへデータを要求する	ESX.RegisterServerCallback + ESX.TriggerServerCallback
サーバーから 1 人のプレイヤーへイベントを送信する	xPlayer.triggerEvent(name, ...)
サーバー専用のクライアントイベント	クライアント側の ESX.SecureNetEvent(name, cb)
source／identifier からプレイヤーを検索する	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. 対応するイベントではなく、コールバックを使ってデータを返します。

出力契約

クライアント／サーバーの分割が明確で、xPlayer の nil チェックがあり、所持金操作に理由を指定した、実行可能な Lua を返します。ユーザーが別の方法を求めない限り、UI には ox_lib を使います。

参考資料

• 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