===============================================================================
 modiomod-r28  1.4.7
 mod.io downloader improvements for 0 A.D. Release 28
===============================================================================

This is the R28 build, for 0 A.D. Release 28 (version 0.28.x).
For 0 A.D. development builds from SVN trunk (0.29.0), use modiomod-r29 instead.

Enable only one of the two at a time. Since 1.3.4 each package declares the
game version it needs, so the wrong one shows up gray on the Modifications
screen and cannot be enabled.


WHAT IT ADDS
-------------------------------------------------------------------------------
* The mod.io download list (Continue -> Download Mods) is colour-coded by
  install and update status, with a legend at the top of the window.

* A "Check for Updates" button on the Modifications screen checks mod.io for
  newer versions of the mods you already have, without opening the downloader.

* "Filter valid mods" in the downloader now also hides mods whose dependencies
  are not met, which is what its label always promised. Stock only hid mods
  with invalid metadata.


INSTALLING
-------------------------------------------------------------------------------
1. Put the mod into your mods directory. The easiest way is to let the game
   do it: pass the downloaded zip to the game's executable (on Windows,
   binaries\system\pyrogenesis.exe inside the game folder):

     pyrogenesis.exe modiomod-r28.zip

   The game unpacks it into your mods directory, which for an installed
   release is:

     Windows   Documents\My Games\0ad\mods
     Linux     ~/.local/share/0ad/mods
     macOS     ~/Library/Application Support/0ad/mods

   A development build started with the -writableRoot option keeps its mods
   in its own binaries/data/mods folder instead. Pass that option when
   installing too, or the mod ends up in the release directory above:

     pyrogenesis.exe -writableRoot modiomod-r28.zip

   Alternatively, create a folder named "modiomod-r28" in the mods
   directory and extract the zip into it. Keep the folder name exactly as it
   is.

2. Start 0 A.D., open "Settings" | "Mod Selection", select
   modiomod-r28, press "Enable".

3. Press "Save and Restart"

4. Open "Settings" | "Mod Selection" again and press "Download Mods". The
   list is colour-coded, with the colour legend at the top of the window.


WHAT THE COLOURS MEAN
-------------------------------------------------------------------------------
First match wins, top to bottom:

  gray     Invalid. The game could not verify this listing (see below).
  red      A dependency is not satisfied by what you have installed.
  yellow   Installed, dependencies met, but mod.io has a newer version.
  green    Installed, dependencies met, up to date.
  white    Not installed. Nothing is wrong with it.

On the Modifications screen, "Check for Updates" colours your installed mods
the same way: yellow for an available update, green for installed through the
mod installer, gray or red for a dependency problem.


WHY ARE SO MANY MODS GRAY OR RED?
-------------------------------------------------------------------------------
Neither is caused by this mod, and neither means a mod is broken. They are two
unrelated checks that stock 0 A.D. performs:

* GRAY means the game could not verify the listing's signature. 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. A gray mod is one
  its author has not resubmitted for your release. Nothing you can change
  locally will make it installable.

* RED means the mod's own declared dependencies are not met by what you have
  installed - most often because its author pinned it to one exact game
  version.

A survey of the mod.io catalogue on 2026-09-12 found 89 listings, of which 64
were gray on both 0.28 and 0.29 for the signature reason above. Of the rest,
under 0.29 nearly all were red because their authors declared "0ad=0.28.0",
an exact match that excludes every other version. This is normal and expected
on a development build, and it will change as authors resubmit their mods.


OPTIONAL: MOD ICONS
-------------------------------------------------------------------------------
The downloader can show the selected mod's mod.io logo next to its
description. No icons are included in this package and the game never
downloads any: 0 A.D. deliberately gives mods no way to fetch files, and it
discards mod.io's logo URLs before any mod script can see them.

If you want the icons, a small companion tool fetches them into your installed
copy of this mod. It is not part of this download - see WHERE TO GET IT below.
Without it, the icon area simply stays empty and nothing else changes.


KNOWN LIMITATIONS
-------------------------------------------------------------------------------
* The icon is shown for the selected mod only, not on every row. 0 A.D.'s list
  widget cannot put an image in a list row.

* After fetching icons you must restart 0 A.D. Mods are read at startup.

* A mod installed by hand into a folder whose name differs from its mod.io
  name is not recognised as installed, so it never shows as green or yellow.

* On Windows, a mod cannot be updated while it is enabled: the game keeps the
  file open, so the update fails and the old version stays. Disable the mod,
  press "Save and Restart", download the update, then enable it again. The
  downloader warns about this when you select such a mod. The same applies
  when you install an update by passing the file to pyrogenesis.exe: the
  game loads your enabled mods before it installs anything.

* Occasionally a mod.io listing names a newer version than the file it
  actually contains. Downloading it then reinstalls the version you already
  have, and the mod stays yellow. The downloader tells you when this happens;
  only the mod's author can fix it by uploading the right file.


WHERE TO GET IT
-------------------------------------------------------------------------------
This mod is published on mod.io:

  https://mod.io/g/0ad/m/modiomod-r28

Discussion, the companion tool for the mod icons, and development builds are
in the 0 A.D. forum thread:

  https://wildfiregames.com/forum/topic/131081-modiomod-for-a27/


CREDITS
-------------------------------------------------------------------------------
  Silier                   original modiomod for 0 A.D. Alpha 0.26, whose
                           colour-coding this is built on
                           https://mod.io/g/0ad/m/modiomod
  Wowgetoffyourcellphone   suggested the on-screen colour legend
  Asher                    suggested Check for Updates
  Wildfire Games           0 A.D. and its modding platform
  Grautvornix              maintainer: ported this to Release 28,
                           decided what it should do, and tested every
                           change in the real game
  Claude (Anthropic)       implemented the changes from Grautvornix's
                           testing, bug reports and decisions


LICENSE
-------------------------------------------------------------------------------
GPL v2, the same licence as the 0 A.D. GUI code this is derived from. The full
text is in License.txt next to this file.
