ArcadePatches 0.1
================

Build and update Arcade Patches from media you own. Choose your games,
platforms and regions, then copy the completed platform folders to your setup.

WHAT YOU NEED

Install Python first. Use Python 3.12 on an Apple Silicon Mac or x64 Python
3.13 on Windows for the full declared package selection. Windows ARM users
can use x64 Python 3.13. Native Windows ARM Python and other interpreter
versions may leave some games unsupported. The standard-library launcher
requires Python 3.10 or newer; Linux currently supports a subset of the catalog.

Keep your source ROMs and other owned media in one or more folders. Names do
not need to match a list: loose files, ZIP members and 7z members are identified
by content. The 7-Zip reader is downloaded and prepared privately when needed.
Use canonical MAME-format arcade sets. Some projects also need disc tracks,
firmware or other source media; the tool explains each missing prerequisite.
Keep private key maps loose in a media folder (any filename). Archived key maps
should be named prod.keys or title.keys; extract other archived key maps first.
Loose key maps take precedence over archived maps.
Normal single-volume 7z archives, including solid archives, can stay compressed.
Encrypted, split-volume or unsupported archives need manual extraction first.
Only candidate members are staged, and temporary source copies are removed at
the end of the command. Keep your export folder outside all source media
folders and outside the tool's state folder.

START

Save arcadepatches.py in a folder of your choice. Open a terminal there:

  Windows:              py -3.13 arcadepatches.py
  Apple Silicon Mac:    python3.12 arcadepatches.py
  Linux:                python3 arcadepatches.py

The first launch asks for your ROM/media folders and an export folder. Enter
one media folder per line, then a blank line. All games, platforms and regions
are selected by default. Use option 2 to choose a smaller selection.
Keeping "all" also includes new catalog entries on future runs.

In a capable terminal, cyan marks headings and active work, green marks built
or current output, yellow marks blocked/unsupported items, and red marks failures.
Status words are always shown too. A live spinner shows elapsed time during
work without a known total. Downloads show bytes and a percentage only when
the server supplies a total; scans show measured counts. Builds show the current
target number. The final summary counts built, current, blocked and failed items.

Redirected output stays plain. Set NO_COLOR to disable colors and animation;
TERM=dumb also selects plain output. JSON, status and doctor output have no
decorations. Windows enables terminal escape support when available and falls
back to plain output when it is unavailable. No extra Python packages are needed.

Choose Build (shown as Update after your first completed build). There is no separate prerequisite check to complete
first: this action checks your media, then downloads and verifies required
patches and managed dependencies, builds eligible targets, and reports anything
blocked or unsupported. It does not download your source ROMs or private keys.
Strider EX additionally needs MAME 0.288 available on PATH; its plan identifies
that requirement. NumPy, Pillow and SciPy are installed privately when required;
you do not need to install those packages into your normal Python environment.

COPY YOUR OUTPUT

Completed games appear in their platform folders during the run. Stopping keeps
games already saved; the next run skips them if they are current. Updates that
change a shared core or other shared file wait for the affected games together.

Read INSTALL.txt and build-report.json in the export folder. Completed output
is grouped by platform. Preserve each folder's internal layout when copying it
to your device or emulator setup. Where profiles are supplied, follow the
profile's instructions instead of merging incompatible profiles together.

Some soundtrack exports are overlays and need the named arcade ROMs or game
kit already installed at the destination. Check the destination requirements
in INSTALL.txt. This tool prepares exports; copying to MiSTer, HBMAME or other
destinations is manual.

UPDATE LATER

Run the same script again. Your folders and selections are saved. Startup
checks the catalog for new games, versions and changed requirements without
scanning your ROM folders. Choose Update when you want to build or
update games; choose Exit when there is nothing you want to do.

When releases change, View all release changes shows the complete list,
including items omitted from the short summary. Unread notices survive closing
the tool. Viewing the full list or running Build/Update acknowledges them; the
full list remains available for the last 20 release checks with changes.
Tooling updates are listed separately from new game versions.

Check requirements only is optional: use it to see what media is missing
without building. You do not need to run it before Build or Update, or on
every launch. Requirements checks use file sizes and stored archive CRCs without unpacking
source files. Available means a candidate was found; the build verifies its
contents. Archive listings and previous identifications are cached while their
source files remain unchanged. The first check still needs to list each archive.
Private keys are checked only when a selected build needs them.
Independent ready games can update while another game lacks media. Existing
verified exports for blocked games are retained. Changing a selection does
not remove previously exported games or regions.

To rebuild missing managed output, run Update again. Modified or unowned
output is preserved and reported as a conflict. Review it before retrying.
Manual destination copies cannot remove obsolete files; INSTALL.txt lists
obsolete paths for your review.

COMMAND LINE

The examples below use "python"; substitute your launch command above.

  python arcadepatches.py configure --rompath "D:/ROMs" --output "D:/Exports"
  python arcadepatches.py configure --rompath "D:/ROMs" --output "D:/Exports" --region us --region jp
  python arcadepatches.py plan
  python arcadepatches.py update
  python arcadepatches.py update --offline
  python arcadepatches.py status
  python arcadepatches.py doctor

Reconfiguration replaces the saved folder and selection rules: include every
folder/filter you want to keep. Omit region filters for all regions. Region IDs
are us, jp, eu, asia and world. Platforms are mister, mame, hbmame, fbneo and
darksoft. --platform and --project can narrow selection too.

The default state/cache folder is ~/ArcadePatches. Use --home to choose another
location, keeping the same --home on later commands. Reusable caches default
to 20 GiB and 256 entries; --cache-gb and --cache-entries on configure change
those limits. Older cache entries can be downloaded again. Offline updates
need a previously cached catalog and all dependencies for the selected builds.
On Windows keep the state/cache folder on an NTFS disk, as the default normally
does. Installing native packages in a shared/network folder can time out on
its many small file operations. Source ROMs may still live on shared storage.

IF SOMETHING IS BLOCKED

Read the per-target prerequisite and suggested action. Add missing media to a
configured folder and retry. An unsupported Python environment needs one of
the declared interpreter/host combinations; rerunning unchanged will not fix it.
For a sharing/reporting problem, use the generated build-report.json, which
omits private source bindings and key values.

If interrupted, restart the same command. Recovery handles recorded temporary
work; a stale lock file alone does not prevent restart. Do not delete a lock
file to bypass another active run. Do not share one export folder between
different --home directories or edit generated files while an update is active.

Exit codes: 0 complete; 2 partial, blocked or unsupported; 1 run-level error.
