===============================================================================
 modiomod-r29  1.4.5
 mod.io downloader improvements for 0 A.D. 0.29 development builds
===============================================================================

This is the R29 build, for 0 A.D. SVN development builds (version 0.29.0).
For 0 A.D. Release 28 (0.28.x), use modiomod-r28 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.

* It also fixes a bug in the development build itself: the three filter
  controls on the Modifications screen threw script errors when clicked,
  because the page's script is loaded as a module there and those controls
  were still wired the old way.


INSTALLING
-------------------------------------------------------------------------------
1. Copy the folder "modiomod-r29" into your mods directory, next to
   "public". Keep the folder name exactly as it is.

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

   (A build run from a source checkout may instead read mods from
   binaries/data/mods inside the checkout.)

2. Start 0 A.D., open "Settings" | "Mod Selection", select
   modiomod-r29, 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.


WHERE TO GET IT
-------------------------------------------------------------------------------
This version is shared through the 0 A.D. forum thread:

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

The companion tool for the mod icons, and any newer build, are posted there.


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 0.29 development builds,
                           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.
