fivem-nui

FiveM NUI

FiveM 向けの HTML/CSS/JS インターフェース：マニフェストの設定、Lua からブラウザーへのメッセージ、NUI コールバック、フォーカスの処理。

有効化の条件

ユーザーが FiveM UI の作成や編集を依頼した場合、リソース内に HTML/CSS/JS を記述する場合、ui_page を設定する場合、または SendNUIMessage、SetNUIFocus、RegisterNUICallback について質問した場合に、このスキルを読み込みます。

必須ルール

• fxmanifest.lua で ui_page を宣言し、すべての UI ファイルを files に含めます。ファイルが不足していても、読み込みはエラーなく失敗します。
• アセットは https://cfx-nui-<resource>/path で参照します。nui:// プロトコルは非推奨です。
• RegisterNUICallback のハンドラーは必ず cb(...)（最低でも cb({})）を呼び出します。呼び出さないと、ブラウザーのリクエストがハングします。
• ブラウザーからコールバックを呼び出すには、fetch('https://' + GetParentResourceName() + '/<name>', { method: 'POST', body: JSON.stringify(...) }) を使用します。URL の名前は登録した名前と完全に一致させます。
• SetNUIFocus(keyboard, mouse)：UI を閉じる際は、必ず SetNUIFocus(false, false) を呼び出します。
• NUI コールバックはクライアント上で実行されます。データをクライアント側で検証し、状態を変更する前にサーバー側でも再検証します。UI から送られた価格、数量、ID は決して信用しません。
• SendNUIMessage の呼び出しは最小限にします。フレームごとに送信するのではなく、更新をまとめて送信します。
• F8 と Chrome DevTools でデバッグし、モックモードを使ってブラウザーでページをテストします。

判断基準

方向	方法
Lua からブラウザー	SendNUIMessage({ type = ..., data = ... }) + window.addEventListener('message')
ブラウザーから Lua	https://<resource>/<callback> への fetch POST + RegisterNUICallback
ブラウザーからサーバーデータを要求	Lua クライアントへのコールバックを経由し、その後サーバーコールバックを呼び出す
カーソルの表示／非表示	SetNUIFocus(true, true) / SetNUIFocus(false, false)
キーボードのみ	SetNUIFocus(true, false)

実行手順

1. マニフェストに ui_page と files を追加します（rules/setup.md を参照）。
2. index.html、CSS、JS を作成し、type をキーとして message イベントをリッスンします。
3. UI からリクエスト可能なすべてのアクションに対して Lua コールバックを登録し、あらゆる経路で cb を呼び出します。
4. UI を開くときと閉じるときにフォーカスを管理し、閉じる操作として Escape を処理します。
5. 状態を変更するアクションはサーバーに転送し、サーバー側で検証します。

出力の要件

マニフェストのエントリー、HTML/CSS/JS ファイル、およびコールバックとフォーカス処理を含む Lua クライアントスクリプトを返します。セキュリティに関わるロジックはサーバー側に保持します。

参考資料

• rules/setup.md — フォルダー構成、マニフェスト、ビルドツール、よくある間違い。
• rules/fullscreen-nui.md — SendNUIMessage、SetNUIFocus、フォーカススタック、アセット、DevTools。
• rules/nui-callbacks.md — RegisterNUICallback、fetch、非同期処理、エラー、セキュリティ。
• rules/best-practices.md — パフォーマンス、セキュリティ、状態、エラー処理、テスト。
• rules/reference-links.md — 公式ドキュメントとネイティブ関数のリファレンス。

上流ドキュメント：https://docs.fivem.net/docs/scripting-manual/nui-development/