===============================================================================
 modiomod companion tools
===============================================================================

Two optional command-line tools for people running modiomod-r28 or
modiomod-r29. Neither is needed to use the mod, and neither is part of it: the
mod is a set of game files, these are Python scripts you run yourself.

Requirements: Python 3.9 or newer. fetch_modio_icons.py additionally needs
Pillow (pip install pillow). Both read your 0 A.D. configuration to find
mod.io's address and public API key, so you need a working 0 A.D. install.


-------------------------------------------------------------------------------
fetch_modio_icons.py - download mod logos for the downloader
-------------------------------------------------------------------------------
The mod can show the selected mod's mod.io logo beside its description, but
0 A.D. cannot download those images itself. It gives mods no way to fetch
files at all - a deliberate security decision - and it discards mod.io's logo
URLs before any mod script can see them. So this tool fetches them outside the
game and writes them into your installed copy of the mod. The game then only
ever reads local files, exactly as it reads any other texture.

  python fetch_modio_icons.py r28 --dry-run     see what it would fetch
  python fetch_modio_icons.py r28                fetch them
  python fetch_modio_icons.py r29 --dest D:\0ad\mods

Options: --dest to point at a different mods directory, --limit N to try a
few, --force to re-fetch icons you already have, --config to name a specific
0 A.D. default.cfg.

Notes:

* Restart 0 A.D. afterwards. Mods are read at startup, so icons fetched while
  the game is running do not appear until the next launch. This is the most
  common reason for "it didn't work".
* The mod must be installed as a folder, not as a packed .pyromod.
* Images are converted to 256x128 PNG because the game has no JPEG decoder and
  rejects textures whose dimensions are not powers of two.
* Only https URLs on mod.io's own hosts are fetched, each capped at 4 MB, and
  a mod whose name contains anything unexpected is skipped rather than used as
  a filename.


-------------------------------------------------------------------------------
modio_report.py - explain why a mod shows up gray or red
-------------------------------------------------------------------------------
Read-only. It lists every mod on mod.io with its dependencies and the state of
its signature, which is what decides whether the game shows it as gray.

  python modio_report.py r28
  python modio_report.py r29 --only invalid
  python modio_report.py r28 --json report.json

The game reduces several different causes to one "Invalid signature." message
before anything can display it, so this works them out from the raw listing:

  no signature at all            the listing was never signed
  signed only with other keys    signed, but not for the release you run
  keynum matches                 signed for your release

0 A.D. trusts one signing key, and that key changes with each release, so a
mod stays verifiable only for the release it was last signed for. That is what
gray means in practice - not that anything is wrong with the mod.

--engine-version additionally judges each listing's declared game dependency,
so the report separates gray (signature) from red (dependency unmet). It does
not verify the signature cryptographically: it checks which key signed a mod,
not that the signature is mathematically valid.


-------------------------------------------------------------------------------
Full documentation and source
-------------------------------------------------------------------------------
  https://wildfiregames.com/forum/topic/131081-modiomod-for-a27/

License: GPL v2, like the mod itself.
