Repository XML data

Repository XML data

For OvGME, a repository is only an XML file which describes which Mods are available, some useful data about them, and where they can be downloaded. This is so to say, a kind of mini database. The only thing is that in our case, the XML file is provided by a web server.

The XML repository structure

OvGME will seek for a particular structure in the provided XML data to gather informations about mods. This structure is simple enough to allow repository XML data to be manually written using any text editor.

However, OvGME also provides tools to automatically generate and test repository XML files (see below).

Here is an example of typical repository XML file content:

<mod_list>

   <mod name="Dummy Mod A" version="1.1" url="www.toto.net/Mod%20A.zip">
   Dummy Mod A Description
Version 1.1

   </mod>

   <mod name="Dummy Mod B" version="1.2" url="www.bubu.org/Mod%20B.zip">
   Dummy Mod B Description
Version 1.2.2

   </mod>

</mod_list>

If you never seen XML source code before, you can see that there is several resemblance with HTML since both share many syntax rule. The purpose of this help is not to explain all XML subtleties, however we will speak about some basic technical aspect to better understand the whole structure.

In the example above we can see several colored entities to be more distinct:

The <purple> entities are named "nodes"
The green= entities are called "attributes"
The "blue" entities are strings, they are the attributes values.
The Black parts are inner data of nodes.

Nodes structure

In our case we have three nodes, the mod_list is the root node, and the two mod are children of this root node. This is the base structure OvGME will seek for repository file: One root with several children, where each children is a mod descriptor. A repository XML data can have as many mod descriptor child nodes as you want, there is no limitation.

Mod descriptor attributes

Each mod descriptor node must have three attributes named respectively "name", "version" and "url". Here, name does matter, OvGME will seek for these specific attributes and their values.

Note: the order of attributes doesn't matter, you can specify url attribute first and the name attribute at the end, this has no impact.

name : describe the mod name. This name is, so to say, what identify the mod in all cases, even internally by OvGM algorithms to compare it with locally installed mods.
version : describe the mod version. This value will be used, for example, to compare with the locally installed mods. (for more details, see the mod versioning chapter )
url : is the URL to the file to download. This is where OvGME will request for download the Mod-Archive zip file. This url must be a valid HTTP URL.

Mod descriptor description

Within the mod descriptor node, you can optionally insert the mod description, this is the black part in the example above. There is no restriction for size or format, but, like in HMTL, the XML format does not "recognize" the carriage returns within the data. But unlike HTML, you can't use the "<br>" tag. So to indicate a carriage return in the description, you have to encode it with the special sequence: "
".

Note: This sequence literally mean "Put Carriage Return ASCII code (13) ; Put Line Feed ASCII code (10) ;" which is named a CRLF (Carriage Return Line Feed) sequence.

Using XML source generator

To help creating valid XML repository file, OvGME provide a tool to automatically create XML source by analyzing the content of the mods folder (or a custom specified folder). This tool take all valid zip Mod-Archive, check for a VERSION.txt, a valid description file, and puts all together as XML repository source code.
To open the XML source generator, go to the "Mods" menu, select "Repositories", then "Make XML source..."

Custom mods folder
If this option is checked, must be an existing folder containing valid Mod-Archive files to be used to generate XML mods list.
If this option is not checked, the current configuration mods folder is used.

Download link nase URL
specifies the base URL used to generate download links for mods. For example, if you enter the "http://www.example.com/public" as base ULR, the download link generated for Mods will be "http://www.example.com/public/My%20Super%20Mod.zip".

Note:Technically, your are not restricted to one location/URL for download links, you can use any valid URL for download links, and each Mod can have its own specific download link. However, the XML generator can generate only generic links for all mods. If download links of Mods are actually scattered on several locations, you have to edit the XML source yourself by replacing the URL of desired Mods.

Once you properly specified the required data, you can generate the XML source code, by simply clicking on the "Generate XML" button. You now can edit the generated buffer to ajust data as your convenence.

Finally, once XML source generated and modified it at your convenience, you finally can save the current buffer by clicking the "Save as XML..." button.

Using XML source test parser

To help verify if an XML repository file will be correctly parsed, OvGME provides a tool to test any XML file as repository XML source. To open the XML source test parser, go to the "Mods" menu, select "Repositories", then "Test XML source...". It will automatically prompts you a new dialog to choose an XML file to test.

If the parsing succeed, you will see a success parsing message and the result of the parsing in the output text area. Otherwise, a parsing error is displayed.