roblox-luau-architecture

Roblox Luau アーキテクチャ

目標

Roblox のゲームコードをモジュール化し、サーバーを信頼できる情報源として、拡張しやすい状態に保ちます。アーキテクチャを変更する前に、Roblox Studio MCP を使って既存のスクリプトを調査してください。

MCP ワークフロー

1. list_roblox_studios を実行し、必要に応じて set_active_studio を実行してから、get_studio_state を実行します。
2. script_search または script_grep でコードを探します。
3. 編集する前に、script_read で関連するスクリプトを読みます。
4. multi_edit で編集を適用します。
5. start_stop_play でプレイテストを実施します。
6. get_console_output で問題がないか確認します。

配置ルール

• 信頼できるゲームロジックは、ServerScriptService またはサーバー所有のモジュールに配置します。
• 共有定数、型定義、リモート、純粋な共有ヘルパーは ReplicatedStorage に配置します。
• プレイヤー入力、カメラ、クライアント専用の UI、視覚的な予測処理はクライアントスクリプトに配置します。
• workspace のスクリプトは必要最小限にし、意図を明確にします。タグ付きのインスタンスや設定済みのフォルダーを管理する、サービス形式のスクリプトを優先します。
• クライアントとサーバーに重複した定数を分散させないようにします。

リモートの境界

• クライアントから送られるすべてのリモートのペイロードを信頼できないものとして扱います。
• アクション名を明示し、ペイロードの型を検証する、用途を限定したリモートを優先します。
• 経済、インベントリ、戦闘、配置に影響する、プレイヤー起点のリモートにはレート制限を設けます。
• RemoteFunctions の使用は最小限にします。クライアントから呼び出す、長時間待機するサーバー処理は避けます。
• 通貨、インベントリ、所有権、ダメージ、クエストの完了、購入アイテムの付与をクライアントに決定させてはいけません。

モジュールのパターン

以下にはモジュールを使用します。

• Init と Start 形式のライフサイクルを持つサービス。
• データアクセスのラッパー。
• 経済の計算。
• 報酬テーブルとバランス調整用の定数。
• クライアント側の UI コントローラー。
• 決定論的で、副作用が少ない共有ユーティリティ関数。

別のシステムが無関係な処理を取り込まずに依存できるよう、モジュールを十分に小さく保ちます。

深いモジュールを優先する

深いモジュール、つまり小さく安定したインターフェースの背後に多くの振る舞いを持つモジュールを目指します。インターフェースが実装とほぼ同じくらい複雑な浅いモジュールは、実際の複雑さを隠している場合にのみ価値があります。

• インターフェース ＝ 呼び出し側が把握しておくべきすべての事項です。関数シグネチャに加え、不変条件、順序、エラーの種類、呼び出し可能な側（クライアント／サーバー）が含まれます。Roblox では、リモートの契約もインターフェースの一部です。
• 削除テスト： モジュールを削除したと想像してください。複雑さがなくなるなら、それは単なる中継役なのでインライン化します。同じ複雑さが複数の呼び出し箇所に再び現れるなら、そのモジュールには価値があるので維持し、さらに深くします。
• 局所性： 関連する振る舞いと、その貴重な状態に関するルールを1つのモジュールにまとめます。そうすれば、変更やバグ、理解に必要な知識を1か所に集約でき、LocalScript、サーバーの Script、3つの定数ファイルに分散せずに済みます。
• あるインターフェースを満たすアダプターが1つなら、境界は仮説にすぎません。2つあれば、実際の境界です。実装が1つしかないのに間接化を導入しないでください。

適切な境界には、「Handler」や「Manager」のような汎用名ではなく、「コイン経済サービス」や「クエストトラッカー」のように、ゲーム固有の用語を使った名前を付けます。

リファクタリングの成果物

アーキテクチャの変更を提案または実施する場合は、以下を含めます。

• 現在のスクリプトの配置場所と役割。
• 提案するモジュール／サービスの境界。
• リモートの契約の変更。
• 移行手順。
• プレイテストとコンソールの確認項目。

次のステップ

roblox-to-issues を使ってアーキテクチャ作業を分割し、安全な変更を1つずつ反映します。それぞれの変更を roblox-playtest-qa で検証してください。貴重な状態を扱うモジュールについては、roblox-security-economy で信頼境界を確認します。既存の負債を整理する場合は、roblox-code-maintenance-refactor を使用します。