underworld-overseer-save-mapper

Underworld Overseer セーブマッパー

このスキルを使用する場面

• Underworld Overseer の .json セーブをマッパーで開く前に検証する場合。
• ゲームのセーブをコピーせずに、上流のマッパーをインストールまたは更新する場合。
• インタラクティブな HTML ダンジョンマップを生成したり、セル、ラベル、出力の欠落を診断したりする場合。
• 座標の範囲、デスクリプターの数、重複するマップ座標を調べる場合。

無関係なセーブ形式、セーブの編集、保護されたゲームデータのリバースエンジニアリングには、このスキルを使用しないでください。これはユーザーが所有するセーブファイルを可視化するものであり、ゲームの進行状況は変更しません。

手順

ステップ 1：元のセーブを保護する

コピーを使用してください。再現性が重要な場合は、入力パスとハッシュを記録してください。ゲームで使用中のセーブを上書きしないでください。また、マッパーをセーブエディターだと説明しないでください。

ステップ 2：インストールや起動の前に JSON を検証する

次を実行します。

python3 .agent-skills/underworld-overseer-save-mapper/scripts/validate_save.py /path/to/save.json

必須の形式は、Map リストを含むトップレベルのオブジェクトです。すべてのマップセルに、整数の X および Y 座標と、空でない文字列の DescriptorID が含まれている必要があります。上流のレンダラーは座標でセルをインデックス化するため、(X, Y) 座標の重複は曖昧なものとして扱ってください。

ステップ 3：必要最小限の動作モードを選択する

1. 検査のみ — validate_save.py --json を使用します。マッパーのインストールは不要です。
2. インタラクティブなマップ生成 — scripts/setup.sh で上流のマッパーをインストール／確認してから、ローカル端末でその main.py を実行します。
3. マッパーのコード変更 — 固定した参照先をクローンし、main.py と template.html を調べて、機密情報を除いたフィクスチャでテストします。

セーブを解析するだけの目的で、ブラウザーの自動化を行わないでください。生成した HTML を表示する場合にのみブラウザーが必要です。

ステップ 4：上流のマッパーをインストールまたは確認する

bash .agent-skills/underworld-overseer-save-mapper/scripts/setup.sh --check
bash .agent-skills/underworld-overseer-save-mapper/scripts/setup.sh --install

インストーラーは専用のデータディレクトリと仮想環境を使用します。pandas と matplotlib をインストールします。pathlib は Python に含まれているため、PyPI からインストールしてはいけません。

ステップ 5：マップを生成して検証する

インストールしたリポジトリから main.py を実行します。現在の上流 UI はインタラクティブで、まず次の場所を探します。

~/AppData/LocalLow/MyronSoftware/UnderworldOverseer/Saves

そのディレクトリが使用できない場合、現在のプログラムはカスタムパスを指定する前に終了します。サポート対象の Windows プロファイルで実行するか、レビュー済みの上流コード変更を行ってください。次の点を確認します。

• 出力 HTML が存在し、空でないこと。
• 描画された座標の範囲が、バリデーターの出力と一致すること。
• 代表的なデスクリプターが凡例に表示されること。
• 検索、ズーム／パン、色のコントロール、ダークモードがローカルで動作すること。
• セーブファイルが変更されていないこと。

ステップ 6：制限事項を正確に報告する

リポジトリの README では、このプロジェクトはベータ版と説明されています。README には MIT ライセンスと記載されていますが、調査した上流コミットにはルートの LICENSE ファイルがありません。ライセンスが確認済みであるかのように、上流のコードやバイナリを再配布しないでください。references/upstream.md を参照してください。

例

描画せずに検証する

python3 .agent-skills/underworld-overseer-save-mapper/scripts/validate_save.py save.json --json

固定したリビジョンをインストールする

REF=5f83b078682d86624941fa451641b01a632455fb \
  bash .agent-skills/underworld-overseer-save-mapper/scripts/setup.sh --install

ベストプラクティス

1. セーブをバックアップし、バグ報告には機密情報を除いたフィクスチャを使用します。
2. HTML の問題を診断する前に、構造と座標の一意性を検証します。
3. 仮想環境内で依存関係のインストールを分離します。
4. 再現可能な出力を得るため、上流コミットを固定します。
5. デスクリプターやレイアウトからゲームの進行状況が判明する可能性があるため、生成した HTML はローカルデータとして扱います。

参考資料

• references/upstream.md — 調査したコミット、動作、依存関係、ライセンスに関する注意事項。
• 上流リポジトリ