Mods repository

Problems

Current mod distribution model will eventually face following problems:

• Lack of changes tracking repository and mods. It's not big deal now, but once we have scripting that will be very important especially if that would be Python or any other language where secure sandboxing is not possible.
• Forward compatibility / backward compatibility. When we start to add new features newer versions of mods won't work in older versions of game. So at least we need to maintain two version of mods index: current stable and develop.
• We need a way to let other contributors to help us with mod maintenance and testing.

Suggested solution

Mods index JSON hosted in git. Main branch "develop" and there will be branching into 1.00, 1.01 or whatever once they released.

Launcher should request specific version of JSON index from our server:

https://repository.vcmi.download/develop.json
https://repository.vcmi.download/0.99.json
https://repository.vcmi.download/0.98.json

Mods hosting

All mods hosted in separate repositories on GitHub under separate "vcmi-mods" organization:

 https://github.com/vcmi-mods/adventure-ai-trace

Trusted community members who can't help with programming can now help us to maintain mods.

Mods update submission

Once mod updated by creator he or maintainer able to make PR to index JSON. All that needed to be provided is commit hash from appropriate branch. In the end our mod repository will only contain link like that:

https://mods.vcmi.download/adventure-ai-trace/821190ef5396702bf763c764ed532781b1fc1ce6.zip

Since archive will be auto-generated by GitHub from commit that also provide us with somewhat secure.

Redirect server

That server just going to be redirect Launcher to proper download link like:

https://repository.vcmi.download/develop.json		-> https://raw.githubusercontent.com/vcmi/mods-repository/develop/repository.json
https://repository.vcmi.download/0.99.json		-> https://raw.githubusercontent.com/vcmi/mods-repository/0.99/repository.json
https://mods.vcmi.download/adventure-ai-trace/821190ef5396702bf763c764ed532781b1fc1ce6.zip -> https://github.com/vcmi-mods/adventure-ai-trace/archive/821190ef5396702bf763c764ed532781b1fc1ce6.zip

So far I hope that logic can be implemented in Jekyll and hosted on GitHub Pages, but if not then we'll have something super-lightweight in Nginx Lua.

Ideas and possible problems

There are few and likely others will appear:

• Would be great to split repository JSON into multiple small files. Sadly doubt they can be merged with Jekyll.
• GitHub might change how ZIP created and that would change archives checksums. So if we want additional checksums over just commit hash then we need implement them different way.
• We should decide what organization should own mods repository (JSON) and who should be able to commit into it.

Short FAQ

What about assets licensing issues?

First of all it's only problem with some mods and they all pretty much fair use or at least not any worse than any other mod for other game. Just in case it's still better to keep them in separate organization and own repository. In worst case we'll need to host data of some particular mod separately.

What if GitHub become less generous?

It's totally possible that eventually GitHub might forbid direct RAW / ZIP access, but so far there is great amount of far more popular projects using it and VCMI unlikely ever become popular enough to reach any limits.

Even if that happen we could rapidly redirect downloads to competing services such as GitLab / BitBucket by simply keeping repository clones there. In same time infrastructure could always be on GitHub.

WTF is vcmi.download?

That is my domain that I registered and pre-paid until end of 2026. I think it's smart to keep any gray area files outside of our main domain.