== Introduction ==

This page aims to describe the verification process mods undergo before being made readily available on [https://0ad.mod.io/ mod.io]. We must ensure that these mods are not broken, that they are not malicious code, that they are indeed Out-Of-Sync (OOS) compatible, and that we are not needlessly stealing bandwidth for big mods.

== Steps ==

=== Mod is downloaded ===

In general, this step should go well, since that's  [https://0ad.mod.io/ mod.io]'s responsibility.

=== Mod is extracted ===

==== Directory Structure ====

Check that the directory structure is correct, see below for a proper example.
{{{
└───sky_ships.zip
    │   mod.json
    │   readme.md
    ├───art
    │   ├───actors
    │   │   └───structures
    │   │           argestesion.xml
    │   └───meshes
    │       └───structural
    │               argestesion.dae
    └───simulation
        └───templates
            └───structures
                    argestesion.xml
}}}

See below for a wrong example. This will not work, and the game will be confused. 
{{{
└───sky_ships.zip
    └───sky_ships
        │   mod.json
        │   readme.md
        ├───art
        │   ├───actors
        │   │   └───structures
        │   │           argestesion.xml
        │   └───meshes
        │       └───structural
        │               argestesion.dae
        └───simulation
            └───templates
                └───structures
                        argestesion.xml
}}}

On `Windows`, it usually means you generated the zip from outside the folder instead of from inside the folder.

==== mod.json ====

The `mod.json` file is an important part of the verification process. For the sake of the demonstration, let's assume we have a mod called `Sky Ships` with a mod.io url `https://0ad.mod.io/sky-ships` and a directory structure like the correct one above.

Let's assume that the mod.json file looks like this:

{{{#!json
{
	"name": "sky_ships",
	"version": "1.0.0",
	"label": "New stuff, new things, and new bugs",
	"description": "New stuff, new things, and new bugs + more stuff",
	"dependencies": ["0ad=0.0.25"]
}
}}}

A few things are wrong with this `mod.json`:

1. `"name"` should be the same as the `mod.io` url so in this case `sky-ships` and not `sky_ships`
2. `"label"` should be `Sky Ships` not `"New stuff, new things, and new bugs"`

{{{#!div style="padding:1px 1px 1px 10px; background: #DBEAF3; border-left: 5px solid #2980B9"
 **NOTE**: If you want to be facetious, you'll notice that we reference the `0ad` mod, which is in a `public` folder. It should technically be `empires_ascendant` in an `empires_ascendant` folder.
}}}

==== Compatibility between mod users in multiplayer ====

We introduced a new boolean flag with `Alpha XXV - Yaunā`, which can optionally be added to your `mod.json`.
{{{#!json
{
  "ignoreInCompatibilityChecks": true,
}
}}}
As the name suggests, it allows avoiding compatibility checks when playing with other people who run different mods. This flag serves for mods that will not influence the gameplay, for instance for a different GUI interface, additional translations, customized art, etc.

Compatibility checks must be enforced primarily to avoid out-of-sync between players, but also to avoid mods that provide opportunities for cheating.

As a rule of thumb, if a mod touches the `simulation/` folder, it cannot ignore compatibility checks.

Wildfire Games will not sign mods that set the flag while touching the `simulation/` folder, or while giving unfair advantages to players (for example automating unit production or providing access to information about the enemy that the player should not have access to). See also this related wiki article: [[SimulationRequirements#Cheatprevention|wiki/SimulationRequirements#Cheatprevention]]

We will also reject any mod that modifies directly the compatibility checks in the GUI code.

==== Analyzing files ====

It's important to browse the mod to look for suspect JavaScript code and suspect files. You must look at every single file to make sure no malicious code gets through.

You can also compare to vanilla versions files using `git`.

{{{#!sh
# -d is to generate a patch file
# -u is to ignore whitespace changes
$ git diff -du
}}}

If a new file contains `Engine.****` calls you need to make sure there is no foul play, it can also be for big random map scripts.

When checking big mods, it might be wiser to diff mods you already checked using the previous version as reference. Even if they have a git repository, it's better to check locally, in case files were added manually.

For mods with a lot of textures, it is recommended to use the archive builder (to convert `png/tga` files to `dds`, `dae` files to `psa/pmd`, and `xml` files to `xmb`). This will greatly reduce the download size and increase performance.
- Related wiki article: [[Modding_Guide#Distributingyourmods|wiki/Modding_Guide#Distributingyourmods]]

==== Signing ====

Once the mod is deemed `safe` we use [https://github.com/jedisct1/minisign Minisign] to sign files. For security reasons, only one person can sign mods because it's not good to share that private key around, given that it works for an entire alpha.

==== Adding Metadata ====

The mod.io metadata blob is used to store a JSON payload containing two fields: the dependencies from `mod.json`, and the signature. It should look like this:

`{"dependencies": ["0ad=0.0.XX"],"minisigs": [...signature...]}`

The signature should have newlines replaced by `\n` and the tabs of the third line by `\t`.

==== Sending the signature ====

Once all is done, we send the signature for completeness or in case the person wants to share the mod through other means.