b3sty-skill

b3sty スキル

b3sty の RedM／FiveM リソースや関連する Lua コードを扱う場合に、このスキルを使用します。以下のデフォルトは、すべてのタスクで適用される頻度の高いルールです。タスクが該当する領域に関わる場合にのみ、リファレンスファイルを開いてください。

作業ワークフロー

1. 編集する前に対象を特定します。RedM、FiveM、共通のいずれか、クライアント、サーバー、NUI、データベース、リソース間連携のいずれか、リソース名、フレームワーク／依存関係に関する前提を確認します。
2. まずローカルプロジェクトを確認し、以下のルールに反しない限り、既存のパターンに従います。
3. このスキルから関連するリファレンスファイルのみを読み込みます。広範なレビューでは、変更箇所から確認を始め、以下に記載された該当ファイルを開きます。
4. 公開サーバーイベント、コールバック、コマンド、エクスポート、NUI コールバック、リソース間呼び出しは、信頼できない境界として扱います。
5. 不確かなネイティブの動作に依存する前に、該当するネイティブリファレンスでネイティブ名、ハッシュ、シグネチャ、ゲーム固有の動作を確認します。
6. 具体的な検証を行って完了します。リソースの起動／読み込み順序、イベント名、サーバー側の検証、クリーンアップ経路、パフォーマンス上のホットパス、手動での再現手順を確認します。
7. 繰り返し発生する修正や、新たに確認したエンジンの癖は、日付とゲームビルドを添えて、適切な memory/ 名前空間に記録します。

タスクの振り分け

• マニフェスト、読み込み順、依存関係リスト、UI ファイル、またはリソースのレイアウトを変更する場合は、skills/common/fxserver.md から確認してください。
• サーバーイベント、コールバック、コマンド、エクスポート、NUI コールバック、状態同期、データベースの変更、報酬、アイテム、お金、権限、クールダウン、または頻繁に実行されるループが関係する場合は、skills/common/security-performance.md から確認してください。
• ショップ／インベントリ／アイテム付与／経済関連イベントの強化、アンチチート、管理者／ACE のアクセス制御、シークレット、SQL インジェクション、アイテム付与チェックリスト、SetHttpHandler エンドポイント、強化用 convar、サードパーティリソースの審査には、skills/common/security-performance.md の「Event Trust Boundary」、「Give-Value Event Hardening」、「ACE Permissions」、「Built-in Client Events」、「Config/Convars/Secrets」、「Identifier Trust」、「Server Hardening And Operations」も追加してください。
• ネットワーク化されたエンティティを作成する、エンティティの所有権に依存する、ルーティングバケット／インスタンスを使用する、クライアントにブロードキャストする、プレイヤーのスコープ変更に反応する、または組み込みクライアントイベント（weaponDamageEvent、startProjectileEvent、ptFxEvent など）を処理する機能では、skills/common/networking.md を追加してください。
• リソースにゲーム内ブラウザー UI（HTML/CSS/JS、React/Svelte/Vue）、SendNUIMessage、RegisterNUICallback、SetNuiFocus、またはマニフェスト内の ui_page がある場合は、skills/common/nui.md を追加してください。
• スレッド／待機、source 変数、エクスポートと古くなった参照、識別子、convar、リソースのライフサイクル、yield の危険性、またはゲームビルドによる制御には、skills/common/runtime.md を追加してください。
• SQL、OxMySQL/mysql-async、スキーマ、トランザクション、マイグレーション、未保存の変更、または永続化された状態が関係する場合は、skills/common/database.md を追加してください。
• コードがネイティブ関数を呼び出す、エンティティ、武器、弾薬、車両、馬、ped、ブリップ、プロップ、またはルーティングバケットを扱う場合は、skills/common/native-rules.md と該当するゲームルールを追加してください。
• ネイティブリファレンスの項目を Lua 呼び出しに変換する、Citizen.InvokeNative でハッシュを指定して呼び出す、out ポインターパラメーターを扱う、RDR3 構造体の引数をパックする、またはゲームビルドによってネイティブ関数を制御する場合は、skills/common/native-usage.md を追加してください。
• 特定のネイティブ関数名、ハッシュ、名前空間、シグネチャ、パラメーターの動作、またはゲーム間の差異を確認する場合に限り、該当するネイティブリファレンスを検索してください。
• タスクが診断、再現、トレース、NUI エラー、データベース障害、ネイティブ関数のバグ、またはパフォーマンス調査に関する場合は、skills/common/debugging.md と関連する memory/ ファイルを追加してください。
• リソースがすでに ox_lib を使用している場合、またはユーザーが追加を明示的に了承した場合に限り、skills/common/ox-lib.md を追加してください。
• エクスポート、イベント、コールバック、依存関係、共有スクリプト、convar、state bag、またはフレームワーク連携を通じて機能が複数のリソースにまたがる場合は、skills/common/multi-resource.md を追加してください。
• リソースが特定のゲーム向けである場合、または共有動作が異なる可能性がある場合は、skills/fivem/rules.md または skills/redm/rules.md を追加してください。
• このスキルパッケージを編集した後、公開する前に scripts/validate_b3sty_skill.py を実行してください。

レビューの優先事項

• スタイルよりもサーバー権限を先に確認してください。
• 内部ヘルパーよりも公開入力境界を先に確認してください。
• キャッシュ、タイマー、コールバック、エンティティ、ゾーン、または状態を追加する前に、クリーンアップとライフサイクルを確認してください。
• コードを共有ファイルに移す前に、RedM／FiveM 間の互換性を確認してください。
• 繰り返し使う理由がない限り、修正は局所的かつ直接的にしてください。

基本方針

タスクで別の指示がない限り、すべての b3sty Lua タスクで次の方針を適用してください。

スタイル

• 大掛かりな抽象化より、直接的で読みやすいコードを優先してください。小規模なリソースにフレームワーク、ディスパッチャー、クラスシステムを導入しないでください。
• インデントは 4 スペースにしてください。呼び出し、パラメーター、テーブルでは、カンマの後にスペースを入れてください。
• ロジックの近くに置くと明確になる場合、モデル名、位置、イベント名などの値はインラインでハードコードしてかまいません。
• 一度しか使わない値のためにヘルパー関数や一時的なローカル変数を作らないでください。処理の流れが読みやすくなる場合は、ハードコードした値をインラインで記述してください。
• ローカル変数に名前を付けるのは、再利用する場合、コストが高い場合、検証済みの場合、またはインライン式より明確になる場合に限ってください。
• コントローラーパターン：1 つのローカルテーブルを使い、function Controller:Method() ... end の形式にしてください。

イベント

• すべてのカスタムイベントでは、resource_name:server:action または resource_name:client:action を使用します。
• 金銭、アイテム、ジョブ、権限、所有権、報酬、クールダウン、保存状態については、サーバーを信頼できる唯一の情報源とします。
• 公開されているサーバーイベント、コールバック、コマンド、エクスポートは信頼できない入力として扱い、ペイロードと権限をサーバー側で検証します。
• すべてのサーバーハンドラーの先頭で、yieldする前に local source = source を取得し、その後で再検証します。仕組みの詳細は skills/common/runtime.md を参照してください。
• 組み込みクライアントイベント（weaponDamageEvent、startProjectileEvent、ptFxEvent など）はクライアントから呼び出せます。すべての :server: イベントと同様に検証してください。全リストは skills/common/networking.md を参照してください。

CfxLua

• RedM／FiveM のコードでは、サポートされている複合演算子（+=、-=、*=、/=、<<=、>>=、&=、|=、^=）を、より明確になる場合に使用できます。++／-- は使用しないでください。
• これらの演算子は CfxLua 専用です。標準 Lua やスタンドアロンの Lua ツールでは使用しないでください。

ネイティブ

• ドキュメントに GET_ENTITY_HEALTH と記載されている場合は、Lua のグローバル GetEntityHealth を使用します。先頭のアンダースコアは削除し、ハッシュのみのネイティブには --[[NAME]] コメントを付けて Citizen.InvokeNative(hash, ...) を使用します。
• Citizen.InvokeNative の BOOL 戻り値は 1／0 であり、Lua では 0 も truthy です。必ず == 1 で比較し、生の戻り値を if で使用しないでください。
• ハッシュ呼び出しの float 型パラメーターには float サブタイプの数値が必要です。1.0 のように記述し、計算値は + 0.0 で変換します。
• ハッシュ定数にはバッククォートリテラルまたは joaat を優先して使用します。ハッシュ同士を比較し、16 進文字列とは比較しないでください。
• 詳細な仕組み（out パラメーター、マーシャリング、RDR3 構造体、ビルド、信頼度）については skills/common/native-usage.md を参照してください。

設定

• 小規模または共有の設定は config.lua に記述します。大規模なデータセットは configs/*.lua に分割し、それぞれテーブルを返すようにします。
• 分割した設定は、それを使用するスクリプトだけで読み込みます。先読みする集約ファイルは作成しないでください。

NUI

• NUI はクライアントローカルの UX であり、権限を持つものではありません。RegisterNUICallback のペイロードは信頼できないものとして扱い、価値のあるアクションは検証済みの :server: イベントを通じて転送します。
• 他のプレイヤーが影響を与えられる文字列（名前、チャット、ラベル）はテキストとして描画し、innerHTML／{@html}／v-html は使用しないでください。CEF で XSS が発生すると、被害者としてすべての NUI コールバックを実行できてしまいます。
• UI を閉じたとき、プレイヤーが切断したとき、リソースが停止したときは、NUI のフォーカスを解除します（SetNuiFocus(false, false)）。各コールバックの cb は必ず一度だけ呼び出してください。
• ブリッジの詳細な仕組み（manifest、SendNUIMessage、fetch ヘルパー、フォーカス、コントラクト）については skills/common/nui.md を参照してください。

ネットワーキング

• クライアントから渡されたエンティティハンドルとネットワーク ID は、信頼する前に検証してください（存在、種類、モデル、所有者、ルーティングバケット、距離）。
• TriggerClientEvent(name, -1) によるブロードキャストは避け、対象を 1 人のプレイヤーまたは少数の受信者に限定してください。複製される可視状態にはステートバッグを優先してください。
• OneSync の詳細な仕組み（所有権、ルーティングバケット、スコープ、組み込みクライアントイベント）については skills/common/networking.md を参照してください。

パフォーマンスとクリーンアップ

• コスメティック用、アタッチ用、プレビュー用のプロップは、サーバー所有の状態からローカルで描画します。ネットワーク化されたプロップは、共有されるゲームプレイエンティティにのみ使用してください。
• 頻繁に参照する値はローカルにキャッシュし、繰り返し検索するものには逆引きインデックス（Items["INDEX"][name]）を作成します。
• フレーム単位の処理が必要な場合を除き、Wait(0) は使用しないでください。距離やアクティブ状態に応じて待機時間を調整します。
• プロバイダーリソースの再起動時に古くなる可能性があるため、ロード時にエクスポート結果をキャッシュしないでください。詳細な仕組みは skills/common/runtime.md を参照してください。
• プレイヤーの切断時／リソースの停止時には、エンティティ、ブリップ、ゾーン、タイマー、コールバック、スロットル、キャッシュをクリーンアップします。エンティティのクリーンアップでは DoesEntityExist で存在を確認してください。

参考ファイル

タスクに応じて必要なものだけを遅延読み込みし、すべてを事前に読み込まないでください。

共通

• skills/common/style.md - スタイル、書式、CfxLua のルール全般。
• skills/common/fxserver.md - fxmanifest.lua またはリソース構成を編集する場合。
• skills/common/native-rules.md - ネイティブ関数の呼び出し、エンティティや弾薬の処理、ネイティブ関数の動作のデバッグを行う場合。
• skills/common/native-usage.md - ネイティブ関数のリファレンス項目を Lua の呼び出しに変換する場合：名前の変換、Citizen.InvokeNative、結果／ポインターのマーシャリング、RDR3 構造体ネイティブ、ビルドの条件、確信度の方針。
• skills/common/resource-structure.md - 共通のクライアント／サーバー／設定／イベント／状態の構成。
• skills/common/networking.md - OneSync、ネットワーク ID とハンドルの違い、エンティティの所有権、ルーティングバケット、スコープ内メッセージとブロードキャストメッセージ、プレイヤーのスコープ、エンティティのライフサイクルイベント、組み込みのクライアントイベント（weaponDamageEvent など）。
• skills/common/nui.md - ゲーム内ブラウザー UI（NUI）：Lua とブラウザー間のブリッジ、SendNUIMessage、RegisterNUICallback、フォーカス、JSON コントラクト、検証、フロントエンドの衛生管理、パフォーマンス、セキュリティ。
• skills/common/runtime.md - スレッド／待機、source 変数、エクスポートと古い参照、識別子、convar、リソースのライフサイクル、yield に関する危険性、ゲームビルド。
• skills/common/security-performance.md - :server: イベント、コールバック、同期、DB 書き込み、または高頻度ループを記述する場合。
• skills/common/database.md - SQL、OxMySQL/mysql-async による永続化、マイグレーション、トランザクション、または保存状態を記述する場合。
• skills/common/debugging.md - リソースの障害、トレース、クライアント／サーバー／NUI の問題、DB の問題、読み込み順序、またはパフォーマンスのバグを診断する場合。
• skills/common/ox-lib.md - リソースですでに ox_lib を使用している場合、またはタスクで ox_lib の追加が明示的に認められている場合。
• skills/common/multi-resource.md - リソース間でエクスポート、イベント、コールバック、依存関係、state bag、または共有ライブラリを介して通信する場合。

ゲーム固有

• skills/fivem/rules.md - FiveM 固有の既定値、マニフェスト、GTA V エンティティ、互換性チェック。
• skills/redm/rules.md - RedM 固有の既定値、マニフェスト、RDR3 エンティティ、互換性チェック。

ネイティブ関数リファレンス

これらは大規模な自動生成検索ファイルです。ネイティブ関数の名前、ハッシュ、シグネチャ、名前空間、パラメーターの動作、またはゲーム固有のネイティブ関数の違いを確認する場合に限り、該当するファイルを開いてください。

• references/natives/fivem-gta5-natives.md - GTA V／FiveM のネイティブ関数リファレンス。
• references/natives/redm-rdr3-natives.md - RDR3／RedM のネイティブ関数リファレンス。
• references/server.cfg.example - コピーして使えるサーバー強化の基本設定（server.cfg の設定またはレビュー時に開いてください）。

メモリ

学習済みのパターンをデバッグまたは再利用する場合に限り読み込んでください。メモリファイルには実作業から得られた知見が記録されています（各項目には日付とゲームビルドが記載されています）。安定したルールへの相互参照として skills/ を示しており、ルールの文章を重複して記載していません。

共通

• memory/common/native-bugs.md - 共有されている既知のネイティブ関数の問題と回避策。
• memory/common/common-errors.md - 繰り返し発生する共通の Lua／リソースエラーとその修正方法。
• memory/common/cfx-patterns.md - 再利用可能な共通の FXServer／CfxLua 実装パターン（コントローラー、インデックスマップ、クリーンアップ、設定の分割、永続化）。
• memory/common/security-performance.md - 学習済みの共通のセキュリティ／パフォーマンスパターンとクイックリファレンスのチェックリスト。

ゲーム固有

• memory/fivem/README.md - FiveM 固有のメモリ名前空間。
• memory/fivem/native-bugs.md - FiveM 固有のネイティブ関数の問題と回避策。
• memory/redm/README.md - RedM 固有のメモリ名前空間。
• memory/redm/native-bugs.md - RedM 固有のネイティブ関数の問題と回避策（例：SetPedAmmoByType の予備弾薬）。