build-game-map-editor

ゲームマップエディターを構築する

実際のゲームワールドを基盤とした、ゲームを一時停止した状態で使うディレクターツールを構築します。デザイナーが配置をすばやく確認・作成できるようにしながら、本番データ、ゲームプレイのセーブデータ、リリースへの統合を明確に保ちます。

権限の境界を明確にする

エディターを設計する前に、リポジトリを調査します。

• 権威あるワールド、ゾーン、エンカウント、スポーン、ピックアップ、ゲート、インタラクト可能オブジェクト、敵 AI の定義を特定します。
• 本番用ワールドビルダーと、再利用可能なランタイムアセットを特定します。
• コリジョン、ナビゲーション、平面、永続化、デプロイの仕様を特定します。
• リポジトリで承認されているブラウザー、テスト、リリース手順、アクセス制御要件を確認します。

独立したマップの信頼できる情報源を作成しないでください。本番の定義をアダプター経由で変換し、初期エディタードキュメントを作成します。すべての下書き値を作成元のコードまでたどれるように、安定したソース ID を保持します。

ライフサイクルを UI と実装の両方で明示します。

本番ソース -> エディタードキュメント -> 分離された下書き -> 検証済みエクスポート -> レビュー済みソース統合

エクスポートは提案として扱います。別途統合処理で権威あるソースを更新し、ゲームプレイテストに合格して、コミットおよびリリースされるまでは、下書きがゲームプレイを変更するとは主張しないでください。

バージョン管理されたエディタードキュメントを定義する

Three.js オブジェクトや React の状態を保存せず、小さくシリアライズ可能なドキュメントを使用します。

次の項目を含めます。

• 固定のスキーマ識別子とドキュメントバージョン。
• ワールドまたはレベルのバージョン。
• 保存タイムスタンプ。
• 安定したエンティティの id、sourceId、kind、ラベル、ゾーン、位置、向き、型付き設定。
• 敵、プレイヤースポーン、ピックアップ、インタラクト可能オブジェクト、ゲートなどの明示的なエンティティ種別。

エディターの位置データはゲームプレイ平面上に保持します。フラットワールドのゲームでは { x, y: 0, z } を使用し、インポートデータの Y がゼロ以外の場合は、黙って平坦化せずに拒否します。

インポートおよび統合のすべての境界で検証します。

• スキーマが完全一致し、バージョンがサポート対象であることを必須とします。
• ドキュメントサイズ、ファイルサイズ、エンティティ数、座標、設定値の範囲に上限を設けます。
• 重複 ID、有限値でない値、不明な種別、無効な境界値、不正な形式のネストされた設定を拒否します。
• エンティティの作成または削除が明示的な機能でない限り、インポートされたエンティティのマニフェストが現在の本番マニフェストと一致することを必須とします。
• 編集後もソース ID とゾーンの所有関係を保持します。

ゲーム固有の詳細なアダプターと制限は、再利用可能なエディターコンポーネントの外部に保持します。

ゲームを一時停止したディレクターシーンを描画する

意図的にディレクターまたはプレビューモードを用意し、本番のワールドビルダーを再利用します。エディター内で戦闘、進行、永続化、敵のシミュレーション、実際のセーブデータへの変更を実行しないでください。

• アイソメトリックまたはフラットワールドでの配置には、正投影のトップダウンカメラを優先します。
• 本番のジオメトリ、標準のエンティティビジュアル、利用可能な場合は標準アイコンを描画します。
• 負荷の大きいアセットの読み込みに失敗した場合は、簡易的な代替表示を用意し、代替表示であることを明記します。
• 各エンティティに、ルートグループ、視認可能なマーカー、アイコンまたは参照スプライト、独立した非表示の選択プロキシを 1 つずつ割り当てます。
• 確実に選択できるようプロキシにレイキャストし、ドラッグ時は固定された地面平面にレイキャストします。
• Y をロックしたまま、X、Z、向きに変換編集を適用します。
• クリーンアップ時に、ジオメトリ、マテリアル、テクスチャ、レンダラー、アニメーションフレーム、オブザーバー、イベントリスナーを破棄します。

ビジュアルレイヤーはエディターデータから独立させます。レイヤーの表示・非表示によってルートやオーバーレイを隠すことはできますが、エンティティを削除したり書き換えたりしてはいけません。

ナビゲーションと選択を予測しやすくする

以下を提供します。

• クリックで選択し、選択でフォーカスする機能
• ラベル、ソース ID、ゾーンによるアウトライナー検索
• オブジェクト数を表示する種類別レイヤー
• 全体表示とゾーン表示の操作
• プロジェクト固有の制限に対応したホイールズーム
• 中ボタン、右ボタン、または Space キーを押しながらドラッグしてパンする機能
• マップにフレームを合わせる F ショートカット
• 視覚効果の低減設定に応じたカメラフォーカス

選択したポイントにフォーカスし、識別できるだけ十分にズームインします。すでに近くまで表示しているエンティティにフォーカスするときは、ズームアウトしないでください。ユーザーが手動でカメラを操作し始めたら、フォーカスアニメーションをキャンセルします。

ポインタージェスチャーを一連の操作として扱います。

• ドラッグまたはパン中はポインターをキャプチャする
• エンティティとポインターのオフセットを維持する
• 選択した刻みに合わせて X と Z をスナップする
• ドラッグ中にドラフトを更新する
• ポインターが動くたびではなく、ドラッグ終了時に元に戻す操作を 1 件作成する
• 移動を伴わないクリックは、選択とフォーカスとして扱う

インスペクターにゲームプレイ上の意味を表示する

すべてのエンティティについて、識別情報、正規アセットパス、ソース ID、ゾーン、位置、向き、ソース設定を表示します。

敵については、ゲームプレイ上の仕様が明確な設定のみを表示します。

• アグロ範囲とターゲット獲得タイミング
• ターゲット喪失と境界付近に留まる時間
• 待機、範囲、または経路のパトロールモード
• パトロール半径または明示的なウェイポイント経路
• リーシュ境界と帰還許容範囲

向き、アグロ範囲、リーシュ、パトロール範囲、ウェイポイントのオーバーレイをワールド空間に描画します。オーバーレイの色と凡例のラベルは一貫させます。

検証済みの書き戻し手段がエディターにない限り、ソースが所有する設定は読み取り専用にします。任意のランタイム状態を編集可能な JSON に変換しないでください。

ドラフトを元に戻せる状態で分離しておく

不変のドキュメントスナップショットと上限付きの履歴を使用します。

• 自動保存を有効にする前に、有効なローカルドラフトを復元する
• ローカルドラフトが無効な場合は無視し、プロダクションソースを読み込んだことを報告する
• 新しい編集後にやり直し履歴を消去する
• 確定した編集とエクスポートしたファイルにタイムスタンプを付ける
• エクスポートとインポートの前に検証する
• サイズ超過、読み取り不能、スキーマ不正、またはマニフェスト不一致のインポートを拒否する
• すべてのドラフト変更をリセットする前に確認を求める
• ゲームプレイのセーブ、アカウント状態、サーバー状態をドラフトストアの外部に保つ
• Draft only または同等のステータスを常時表示する

後から共同編集、サーバー永続化、またはソースへの書き戻しが求められた場合は、競合処理、監査履歴、明示的な公開承認を備えた、独立した認証済みワークフローとして設計してください。

非公開のプロダクションツールを保護する

非公開 URL だけでは不十分な保護として扱います。

• ルートを動的にレンダリングし、noindex, nofollow を設定する
• アクセス設定がない場合は、デフォルトでアクセスを拒否する
• デプロイ先で信頼できるエッジ IP ヘッダーを使用し、IP の完全一致許可リストを適用する
• パスワードの比較には、早期終了する平文比較を使用しない
• 短期間有効なセッションクレームに HMAC または同等のサーバー側メカニズムで署名する
• セッションを許可されたクライアント IP と有効期限にバインドする
• トークンを secure、HTTP-only、strict same-site の Cookie に保存する
• サイズ超過の認証情報と形式不正のトークンを拒否する
• パスワード、許可リスト、署名用マテリアルはデプロイシークレットに保存し、バンドル、ログ出力、エクスポート、テストスナップショットへの保存を決して行わない
• 未認証のリクエストには、エディタークライアントやキャンバスをレンダリングしない
• Cookie を無効化する POST のログアウト操作を提供する

設定不足、拒否された IP、パスワードの誤り、有効なトークン、IP の不一致、シークレットの不一致、有効期限切れ、ログアウトをテストします。

レビュー済みのドラフトを統合する

エクスポートされたドキュメントを、安定したソース ID をキーとする差分として読み取ります。

1. スキーマ、バージョン、マニフェスト、境界、平面ルール、種類ごとの設定を検証します。
2. 変更されたすべてのフィールドを、本番環境の定義と照合します。
3. 承認された変更を、最小単位の正式なソースモジュールに反映します。
4. レベル、ナビゲーション、衝突、敵、永続化、エディターのカバレッジテストを実行します。
5. リポジトリで承認されているブラウザーで、影響を受けるルートと遭遇をプレイします。
6. リポジトリの通常の手順でコミットし、リリースします。

各フィールドを所有するシステムを把握せずに、ドラフト全体を本番環境にコピーしてはいけません。

エディターを検証する

次の項目について、決定論的なテストを追加します。

• エンティティの種類ごとの本番環境からドキュメントへの網羅性
• 安定した ID、スキーマ検証、平面の適用、境界、設定範囲
• 正規のアイコンまたはモデルの解決と、配布ファイルの存在
• カメラのフォーカス、ズーム制限、モーションの軽減
• 元に戻す、やり直し、ドラッグのアトミック性、スナップ、ローカル復元、インポート、エクスポート、リセット、マニフェストのチェック
• アクセス設定、正確な許可リスト、パスワード比較、トークンのバインド、有効期限、Cookie フラグ、フェイルクローズのサーバーレンダリング

その後、対象を絞ったテスト、全テスト、ビルド、Lint、差分チェックを実行します。承認済みのブラウザーで、未認証状態と認証済み状態、アウトライナーとレイヤーの動作、選択とフォーカス、ドラッグとスナップ、インスペクターの編集、オーバーレイ、元に戻すとやり直し、ローカル復元、インポートとエクスポートの拒否経路、リセットの確認、ログアウト、デスクトップレイアウト、対応している場合はモバイルまたは狭い画面のレイアウト、コンソールの状態、レンダラーのクリーンアップを検証します。

Vesperfall で作業する場合、または具体的な本番環境の実装マップが必要な場合は、references/vesperfall-implementation.md を読んでください。