fivem-react-nui

FiveM NUI — React + Vite

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

スタック：React 18 + TypeScript + Vite + Tailwind CSS v3.4.17 + Zustand

基本ルール

• vite.config.ts の base: "./" — FiveM でアセットを読み込むために必須です
• Vite の rollupOptions.output のファイル名に [hash] がない状態で固定してはいけません — FiveM CEF は NUI をキャッシュするため、固定名（assets/[name].css）では一部のプレイヤーに古い CSS が残ります
• 透明な html 上のオーバーレイ／シェルの塗りつぶし： 不透明な hex + background-image: linear-gradient(#111,#111) を使用します — パネルの塗りつぶしと同じ角丸要素に rgba()／Tailwind の bg-*/70／opacity を絶対に使用しないでください（一部の iGPU で CEF の不具合が発生します）。画面を暗くするには、border-radius のない兄弟レイヤー（::before の inset-0）を使用します。display: flex|none で切り替えてください — オーバーレイコンテナに jQuery の fadeIn／fadeOut を絶対に使用しないでください
• 背景が表示されない／border-style: solid でボーダーが正しく描画されない場合： 該当する要素の上／左に inset、下／右に outset を試してください。ui-guide.md §6 の方向別ボーダーのフォールバックを参照してください。FiveM CEF で視覚的に確認し、すべてのソリッドボーダーを置き換えないでください。
• すべてのサイズに rem を使用してください — レイアウトに px を絶対に使用しないでください（プレイヤーの解像度に合わせて拡大縮小されます）
• Tailwind v4 は OKLCH を使用しており、FiveM CEF はこれをサポートしていません — Tailwind v3.4.17 を使用してください
• 禁止：backdrop-filter: blur()、filter: blur()、filter: drop-shadow() — FPS が低下します
• 禁止：framer-motion、GSAP、react-spring — 純粋な CSS トランジション／キーフレームを使用してください
• グローバルに overflow: hidden と user-select: none を設定します
• 独立したモジュール（Notify、Progress、HUD）は VisibilityProvider の外に配置します
• メインインターフェース（パネル、クラフト、ダイアログ）は SetNuiFocus とともに VisibilityProvider 内に配置します
• 開発時のデータモックには isEnvBrowser() を使用します
• 通信には、NUI メッセージのリッスンに observe()、コールバックの送信に Post.create() を使用します

アーキテクチャ

// main.tsx
ReactDOM.createRoot(document.getElementById("root")!).render(
  <ThemeProvider>
    {/* Always visible — do not block game input */}
    <NotifyComponent />
    <ProgressComponent />

    {/* Controlled by VisibilityProvider — requires NuiFocus */}
    <HashRouter>
      <VisibilityProvider>
        <AppContent />
      </VisibilityProvider>
    </HashRouter>
  </ThemeProvider>
);

NUI フック

observe — Lua メッセージをリッスン

observe<NotifyData>("module:notify", (data) => {
  addNotify(data);
});

Post — Lua にコールバックを送信

await Post.create("buy", { item: "water", qty: 1 });

Lua 側

-- Open
SendNUIMessage({ action = "setNui", nui = "panel", data = { ... } })
SetNuiFocus(true, true)

-- Close callback
RegisterNUICallback("removeFocus", function(data, cb)
    SetNuiFocus(false, false)
    cb("ok")
end)

fxmanifest.lua との統合

ui_page "src/ui/build/index.html"

files {
    "src/ui/build/index.html",
    "src/ui/build/**/*",           -- covers index-[hash].js/css
    "src/ui/project/public/**/*",
}

推奨依存関係

{
  "dependencies": {
    "react": "^18", "react-dom": "^18",
    "react-router-dom": "^7", "zustand": "^4",
    "clsx": "^2", "tailwind-merge": "^3",
    "lucide-react": "^0.5", "tailwindcss": "^3",
    "autoprefixer": "^10", "postcss": "^8"
  },
  "devDependencies": {
    "@vitejs/plugin-react-swc": "^3",
    "typescript": "^5", "vite": "^5"
  }
}

避けるもの：MUI、Chakra UI、Ant Design、framer-motion、styled-components — いずれも FiveM CEF には重すぎます。

fxmind エージェントのビジョン（NUI ダンプ）

スクリーンショットよりも構造化された状態を優先してください。エージェントが接続と解除を行います — ユーザーにスクリプトの修正を依頼しないでください：

1. fxmind_fivem_nui_wire { resource } — fxmanifest にパッチを適用し、ui_page に DOM プローブを挿入します
2. ブリッジとリソースを ensure します。ユーザーがゲーム内で NUI を開きます
3. fxmind_fivem_nui_dump
4. 終了前に**fxmind_fivem_nui_unwire** を実行します（クリーンアップ必須）

任意の恒久的な統合（エージェントによるデバッグには不要）：ブリッジのスニペットから registerFxmindNuiDump(() => useStore.getState()) を呼び出します。

完全な実装ガイド（プロジェクト構成、vite.config、レスポンシブシステム、CSS の制限、フックのソース、Visibility／Animation／Theme プロバイダー、デバッガー）については、ui-guide.md を参照してください。