fivem-development

FiveM 開発 — ベストプラクティス

フレームワークに依存しないオーケストレーターです。スキルは1つ — 必要に応じてリファレンスファイルを読み込みます（すべてを読み込まないでください）。

言語ルール： 内部推論は簡潔な英語で行います。ユーザーに表示するすべてのメッセージと出力は、ユーザーの言語で記述します。

基本方針

1. 暗記せず、情報を取得する — ネイティブ機能や API が不確かな場合は、信頼できる情報源で確認します
2. フレームワークに依存しない考え方 — パターンを理解し、使用中のフレームワークに適応させます
3. パフォーマンスを最優先する — FiveM のティック予算は厳格です
4. セキュリティを意識する — サーバー側での検証は必須です
5. 抽象化より、クリーンで読みやすい Lua を優先する — モノリスを基本とします（server.lua / client.lua）。コメントは最小限にし、local function を抽出するのは再利用する場合のみとします（呼び出し箇所が2つ以上。§3.11）。React のように Lua をコンポーネント化したり、Tunnel/return で済む場面でイベントの往復を作ったりしないでください。
6. プロジェクトの記憶 — reference.mdc = 簡潔な全体マップ（alwaysApply）；.fxmind/memory/<topic>.md = 共有する簡潔なレシピ。再スキャンする前に /fxmind learn を実行します；/fxmind memory health；/fxmind graph；/fxmind query。
7. 監査の厳密さ — /fxmind audit は performance.md §1.6.1–§1.6.2 + audit-passes.md §2.3–§2.5（Pass 2b E-a…E-g、ui_page の場合は Pass NUI N-a…N-d）+ security.md §5.1 に従います。
8. 品質ゲート（タスクモード） — コードの実装またはリファクタリングは quality-gates.md に従います。Gate A で設計をレビューし、Gate V の前にセルフレビューを繰り返します。

---

リファレンスルーター（必要なものだけを読み込む）

トピック	ファイル	主要セクション
トンネル／イベント／_ プレフィックス／同じ側の呼び出し／レスポンス予算	communication.md	§1.1–§1.3、§1.7
ループ、動的スリープ、ペイロード、tunnel_res、ブロードキャスト、StateBags、キャッシュ（サーバー＋クライアント §2.1.1）、ビューキャッシュ、クライアントデータのシード／ブートストラップ §2.2.1	performance.md	§1.4–§1.6.2、§2.1–§2.2.1、§4.1–4.2、§4.5
監査のみ — Pass 0–7、行列 V/E/N、レポートのゲート	audit-passes.md	§2.3–§2.5
モノリスのレイアウト、グローバルと疑似モジュール、状態の配置	architecture.md	§3.5–§3.6、§3.8
ルックアップテーブル、nil、コメント、単回使用ヘルパー、チェックリスト、アンチパターン	style.md	§3.1–3.4、§3.7、§3.9–§3.11
SafeEvent、SetCooldown、エンドポイント認証、サーバー解決、入力検証	security.md	§4.6–4.8、§5.1–§5.3
cerberus のエクスポート署名と例	api.md	§4.3–4.4
実装／リファクタリング（タスクモードの DoD）	quality-gates.md	Gate A QUALITY ＋セルフレビューループ
NUI／React UI（CEF の入力、Vite ハッシュ）	fivem-react-nui/SKILL.md · ui-guide.md §2、§6
すべての § リンクのインデックス	best-practices.md	目次のみ
Props／車両／ped	asset-discovery.md	—
vRP／QB／Qbox／ESX の検出	framework-detection.md	—

原則 ID → セクション（.fxmind/policy/fivem-principles.md の ID。必要な行だけを開いてください）：

ID	ルール	詳細
N1	受信者の範囲	performance §1.6.1、§4.2
N2	最小限のペイロード	performance §1.6、§2.2
N3	大きなデータは分割	performance §1.6、§2.2.1、§4.1–4.2（cerberus SendFullSync）
N4	定期的なファンアウトを行わない	performance §1.4、§1.6.1、§4.2
N5	クライアント側の同期／statebags	performance §1.6.2、§2.1.1
N6	フラッド対策	security §4.6–§4.8、§5.1
N7	サーバープッシュでクライアントデータをシード	performance §2.2.1
D1	ホットパスで DB を使わない	performance §2.1、§2.1.1
D2	ラウンドトリップは 1 回、N+1 を避ける	performance §1.4
D3	サーバーが正となる状態を管理	security §5.2–§5.3
T1/T2	イベント駆動、動的スリープ	performance §1.5
C1	最小限のコード、単回使用ヘルパーを作らない	style §3.11–§3.12、communication §1.3
C2	読みやすいフロー、グローバルを使わない	architecture §3.5–§3.6、§3.8、style §3.1–§3.4
C3/C4	検証は一度、差分をクリーンに保つ	security §5.3、style §3.7、§3.9
C5	レキシカルローカル／呼び出し元より先に呼び出し先を定義	style §3.11、architecture §3.8

修正バックログ（.fxmind/corrections/）のカテゴリは、これらのファイルに 1 対 1 で対応しています。ルールは新しいスキルではなく、該当するファイルに追加してください。

---

重大：ハルシネーション禁止ポリシー

ネイティブ関数、フレームワーク API、パラメーターを決して創作したり、推測したりしないでください。

1. ネイティブ関数に確信がない場合 → https://docs.fivem.net/natives/ から必ず取得してください
2. フレームワーク API に確信がない場合 → 公式ドキュメントを参照するか、フレームワークのスキルを読んでください
3. 関数が存在しない場合 → 正直にユーザーに伝え、代替案を提案してください
4. パラメーターが不明な場合 → ドキュメントを取得し、推測しないでください

ネイティブ関数や API 呼び出しを記述する前に、名前、パラメーター、クライアント／サーバーでの利用可否を確認してください。

---

動的なドキュメント取得

まずローカルのスキルを使用してください。 情報が不足している場合、古くなっている場合、または不確かな場合にのみ、オンラインから取得してください。

ユーザーの質問について…	対応
ネイティブ関数	取得 https://docs.fivem.net/natives/
フレームワーク API	フレームワークスキルを読む。不確かな場合は取得
ox_lib	取得 https://overextended.dev/ox_lib
GTA V アセット	asset-discovery.mdを読む
通信／Tunnel	communication.mdを読む
キャッシュ／スリープ／ブロードキャスト／cerberus 同期／クライアントキャッシュ／クライアントデータのシード（§2.2.1）	performance.mdを読む
/fxmind audit	audit-passes.mdを読む
新しいリソース／モノリス	architecture.mdとstyle.mdを読む
セキュリティ／SafeEvent／エンドポイント認証／入力検証	security.mdを読む
cerberus エクスポート API	api.mdを読む

---

リクエストルーター

ルール	トリガー	対応
ネイティブ検出	PascalCase のネイティブ関数、0x...	docs.fivem.net/natives を取得
フレームワーク API	vRP.*、QBCore.*、exports.qbx_core、ESX.*	フレームワークスキルを読む
ox_lib	lib.*	overextended.dev/ox_lib を取得
アセット検出	prop／vehicle／ped モデル	asset-discovery.md を読む
通信	Tunnel、コールバック、_ プレフィックス、同一サイドの TriggerEvent、レスポンス予算	communication.md を読む
パフォーマンス	Wait(0)、ループ、ペイロード、tunnel_res、ブロードキャスト、キャッシュ、クライアントキャッシュ	performance.md（§1.4–§1.6.2、§2.1–§2.2.1）を読む
監査	/fxmind audit、入力のリファクタリング	audit-passes.md（§2.3–§2.5）を読む
アーキテクチャ	新しいリソース、server.lua、レイアウトのリファクタリング	まず architecture.md §3.5–3.6 を読む
スタイル	コメント、if/else の整理、local function への抽出とインライン化	style.md（§3.11）を読む
セキュリティ	エクスプロイト、SafeEvent、エンドポイント認証、入力検証、Webhook	security.md を読む
実装／リファクタリング／新しいエンドポイント／NUI	新しい func.*、RegisterNetEvent、RegisterNUICallback、リソースのリファクタリング	quality-gates.mdを読む
プロジェクトのメモリー	/fxmind learn、craft/item/loja	.fxmind/memory/<topic>.mdを読むか、learn/query を提案

---

Lua を書く前に

1. architecture.md §3.5–3.6 と style.md §3.7–3.11 を読む
2. タスクモード： quality-gates.mdを読み、Gate A の QUALITY 計画を記入する。Gate V の前にセルフレビューのループを実行する
3. 明確な理由がない限り、デフォルトで server.lua 1 つと client.lua 1 つにする
4. イベントの往復より Tunnel／return を優先する — communication.md §1.1

---

パフォーマンスに関する重要なルール

1. コールバックとイベント： 戻り値が不要な場合は TriggerServerEvent／TriggerClientEvent を使用してください。戻り値が必要な場合にのみ、コールバック／Tunnel を使用してください。
2. 動的スリープ： 固定の Wait(0) は絶対に使用しないでください。状態に応じて調整してください。
3. 同一環境： 関数を直接呼び出してください — 同一サイドで TriggerEvent() を呼び出さないでください。
4. 5 秒未満のループ内でリモート呼び出しを行わない — バッチ処理または差分を使用してください。
5. ペイロードは小さく — 上限は約 8KB です。差分を送信してください。
6. キャッシュ： DB クエリを繰り返す場合は exports["cacheaside"]:Get() を使用してください。
7. 大規模な同期： cerberus が利用可能な場合は SendFullSync／SendDeltaSync を使用してください。それ以外の場合は、分割を一度だけ行うチャンクを使用してください（performance.md §2.2.1）。
8. 金銭／アイテム／XP／車両には、SafeEvent とサーバー側の検証を使用してください。
9. スパムが発生しやすい TriggerServerEvent の前に、クライアント側で SetCooldown を設定してください。
10. サーバーセキュリティ： クライアント／NUI を決して信頼しないでください。派生データはサーバー側で解決してください（§5.2）。
11. 条件が 3 つ以上ある場合は、if/else よりテーブルを使用してください。nil を保護してください。
12. ネットワーク通信を集約： 戻り値を含む Tunnel 呼び出しを 1 回にしてください（§1.1）。
13. サーバープッシュでクライアントデータをシードする： リソース開始時にキャッシュとビューを一度だけ構築します（seed -1）。プレイヤー読み込みフックでキャッシュ済みのビューを source に送信し、CRUD では 1 つのキーをパッチして差分を送信します。開始時にクライアントから requestSync を呼び出す方法は使用しないでください（performance.md §2.2.1）。

---

フレームワークスキル

フレームワーク	スキル
vRP Creative Network	vrp-framework
QBCore	qbcore-framework
Qbox (qbx_core)	qbox-framework
ESX Legacy	esx-framework
NUI (React + Vite)	fivem-react-nui

framework-detection.md を参照してください。

---

リソース構成

モノリスを推奨します。architecture.md §3.5 を参照してください。

resource_name/
├── fxmanifest.lua
├── shared/config.lua
├── server/server.lua
└── client/client.lua

---

アンチパターン（簡易版）

しないこと	すること
すべての機能を個別の Lua ファイルに分割する	正当な理由がない限りモノリスにする（§3.5）
すべての行にコメントを付ける	分かりにくいルールにだけコメントを付ける（§3.7）
呼び出し箇所が1つの local function を抽出する	ハンドラー／スレッド内に直接記述する（§3.11）
1つのバグを修正するためにファイルを書き直す	差分を最小限にし、ユーザーが承認したパターンを維持する（§3.11）
LoadResourceFile のインポートを偽装する	グローバルまたは同一ファイル内のヘルパーを使う（§3.6）
戻り値の取得にイベントの往復を使う	Tunnel／return を使う（§1.1）
クライアントを信頼する／送信のたびにペイロードを再構築する	サーバー認証＋ビューキャッシュを使う（§5、§2.2）
起動時にクライアントから初期データを要求する（requestSync）	起動時のサーバープッシュ＋プレイヤーロードフックを使う（§2.2.1）
CRUD を1回実行するたびにキャッシュ全体を再読み込みする	キー1つにパッチを適用し、差分を使う（§2.2.1）
ネイティブ／API をでっち上げる	まず確認する

全表は style.md §3.10–§3.11、architecture.md §3.6 を参照してください。

---

外部リソース

• cacheaside：[email protected]:proelias7/cacheaside.git
• cerberus：[email protected]:proelias7/cerberus.git

ネイティブ

• https://docs.fivem.net/natives/
• ミラー：https://github.com/proelias7/fivem-natives