underworld-overseer-save-mapper

Underworld Overseer Save Mapper

When to use this skill

• Validate an Underworld Overseer .json save before opening it in the mapper.
• Install or update the upstream mapper without copying game saves.
• Generate an interactive HTML dungeon map or diagnose missing cells, labels, or output.
• Inspect coordinate bounds, descriptor counts, or duplicate map coordinates.

Do not use this skill for unrelated save formats, save editing, or reverse engineering protected game data. It visualizes user-owned save files; it does not modify progression.

Instructions

Step 1: Preserve the source save

Work on a copy. Record the input path and hash when reproducibility matters. Never overwrite the game's active save, and never claim the mapper is a save editor.

Step 2: Validate the JSON before installing or launching anything

Run:

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

The required shape is a top-level object with a Map list. Every map cell must contain integer X and Y coordinates and a non-empty string DescriptorID. Treat duplicate (X, Y) coordinates as ambiguous because the upstream renderer indexes cells by coordinate.

Step 3: Choose the smallest operating mode

1. Inspection only — use validate_save.py --json; no mapper install is needed.
2. Interactive map generation — install/check upstream with scripts/setup.sh, then run its main.py in a local terminal.
3. Mapper code changes — clone a pinned ref, inspect main.py and template.html, and test against a redacted fixture.

Do not reach for browser automation just to parse the save. A browser is only needed to view the generated HTML.

Step 4: Install or check the upstream mapper

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

The installer uses a dedicated data directory and virtual environment. It installs pandas and matplotlib; pathlib is part of Python and must not be installed from PyPI.

Step 5: Generate and verify the map

Run main.py from the installed repository. The current upstream UI is interactive and looks first in:

~/AppData/LocalLow/MyronSoftware/UnderworldOverseer/Saves

If that directory is unavailable, the current program exits before offering a custom path; either run on the supported Windows profile or make a reviewed upstream code change. Verify that:

• the output HTML exists and is non-empty;
• rendered coordinate bounds match validator output;
• representative descriptors appear in the legend;
• search, zoom/pan, color controls, and dark mode work locally;
• no save file was changed.

Step 6: Report limitations honestly

The repository README describes the project as beta. Its README advertises MIT, but the inspected upstream commit has no root LICENSE file. Do not redistribute upstream code or binaries as though the license were verified; see references/upstream.md.

Examples

Validate without rendering

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

Install a pinned revision

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

Best practices

1. Back up saves and use redacted fixtures for bug reports.
2. Validate structure and coordinate uniqueness before diagnosing HTML.
3. Keep dependency installation isolated in a virtual environment.
4. Pin an upstream commit for reproducible output.
5. Treat the generated HTML as local data because descriptors and layout may reveal game progress.

References

• references/upstream.md — inspected commit, behavior, dependencies, and license caveat.
• Upstream repository