[For modders] Distributing your mod with WGMM

[throwaway]

INTRODUCTION
For the release of faustmann, I wrote a small program that makes it easier for users to install and update the mod. You can use it for your mod too. Here's how it looks:



The main goal is to make it really easy for the user to switch between your mod and vanilla, because the normal way to install a mod is such a pain that nobody can be arsed to do it for the odd game or two.

An optional feature also allows you to deploy updates for your mod. Because few users are gonna check your thread every week..

For now, it's only been tested on windows. I'd be interested for feedback if anyone tries running it under Linux with mono or wine.

SETUP
So, how can you use this for your mod?

First, download the program and take it for a spin:
Here's a version with just the program, no mods.
Here's a version with faustmann installed. You can use the faustmann setup as an example/template for your own.

The first thing you should do is verify that the program works. Start it, follow the instructions, try to launch wargame with it. Try to load the faustmann mod and then reset to vanilla, if you downloaded the big file.

The modmanager looks for mods in the mods/ folder. So to start setting up your mod to work with WGMM, make a folder in mods/. The name of the subfolder is the name of your mod:

Spoiler : :

Inside your mod's folder, make another folder called "bin". This is where your modded wargame files go. Paste them while maintaining their folder structure, but only from the numeric folders. That's to say, if you usually give your users Data\WARGAME\PC\510057270\NDF_Win.dat, the same file for your mod in WGMM should be found in modmanager\mods\modname\bin\510057270\NDF_Win.dat

Place all your modded files like this and try to start the mod via modmanager. If you did everything correctly, the result will be no different from a manual installation. If you have problems, refer to the faustmann example. You can also place a file with a unique easy to find name, try to launch via modmanager, and then see where in your wargame install dir it got copied to - then adjust as necessary.

Spoiler : experimental addressing :

In the standard case, modmanager copies all folders in modname\bin to Wargame Red Dragon\Data\WARGAME\PC\. This is static addressing - you say exactly which subfolder the .dat files go into.

Imagine that some day eugen start updating the game again. At the time of writing, the newest version is 510064564, so a modded NDF_Win.dat will probably be headed to Wargame Red Dragon\Data\WARGAME\PC\510064564\NDF_Win.dat. Patch day hits, newest version becomes 600000000, your NDF_Win in 510064564 gets ignored and even if the patch didn't change anything else you have to rerelease the mod to fix it.

To circumvent this, you can provide mod files to WGMM and have it guess where they should go. Just put any such files directly under mods/modname/bin/ - any file that is directly under bin/ is assumed to use heuristic addressing. The program will do a depth-first descending [aka from biggest folder number] search for the first file of the same name in Wargame Red Dragon\Data\WARGAME\PC\, and replace that. This should always be correct for finding the newest NDF_Win.dat, and I've added some special cases for ZZ_4 and ZZ_Win, but it's ultimately an experimental feature so test extra-carefully before any releases using it and report any issues to me.

You can use static and guess paths for the same mod. Statically addressed files are placed first, so if a heuristically guessed path ends up the same as a static one, the file whose path is being guessed will overwrite the one that was placed statically.

[throwaway]

UPDATE SETUP
If you don't need automatic updates, you can skip this section.

--Setting up the Update file--
In your mod directory [mods/modname/], make a file called "UPDATE". Note the lack of extension. Make its contents the following:

version:0.99.2
releaseRepo:https://api.github.com/repos/KSVM-UA/FaustmannMod/releases/latest

UPDATE tells the modmanager what version of the mod the user has installed, and where to check for new versions. You can change the numbers in version to whatever you want, but respect the a.b.c.d format [4 levels at most]. Note that we set the release repository to the faustmann one - you need to change this to your own repository. To get one, you need a free github account.

I'll assume you've made a github account and a repository for your mod - there's plenty of guides for how to do that. The contents of the repository are not important. But it would be nice to use it as intended and have source control for your mod development. No, what actually interests us is the releases tab: https://i.imgur.com/iRF4hPF.png

Click the releases tab, then create a new release. For starters, just write whatever. Then go to
https://api.github.com/repos/USERNAME/R ... ses/latest to make sure it is accessible - change USERNAME and REPONAME to match your own, the response should be a fairly big json. Once you know it works [you can see the big json], copy the working api address [https://api.github.com/repos/USERNAME/REPONAME/releases/latest] into your UPDATE file, so WGMM knows where to check for future updates.

--Release format--

Making a release is a five step process:
1. Backup your mod folder,
2. increase the version in UPDATE,
3. make a zip of the contents your mod folder [WITHOUT wrapping folders!],
4. then create a release in your github repository. The tag should be the same as the version in UPDATE, after you increased it. The title can be anything, the description will be shown to the user as a changelog. The .zip should be the only file attached to the release.
5. TEST to make sure the update works. If no update is being detected, don't forget to decrement the version in your local UPDATE file.

Spoiler : :

What happens when checking for updates is, the version in the local UPDATE file is compared to the tag of the latest release. If the tag is bigger, the zip is downloaded, the contents of your mod folder are deleted, and the contents of the zip go in there. The UPDATE file in the .zip should have the same version as the tag of the release it is in - if it is lower, the mod will always ask for updates [think about it if you don't get it].



SHARING WITH USERS
So you've set up your mod. There's two ways for a user to "install" it:
1. Give them entire WGMM folder.
2. Give them just the mod folder and tell them to put it in their WGMM/mods folder. Appropriate if the user already has mods that use WGMM.

Before uploading your own WGMM for users to use, take care to DELETE the settings.ini file that is created on first launch, and the contents of the mods/vanilla folder.


About
The source for WGMM is at https://github.com/pvutov/WargameModManager
You can report issues both here and there.

[jonas165]

This looks like hell of an interesting tool. Thanks for sharing!

[Spectre_nz]

Looks pretty sweet.

How does it do the reversion to vanilla?

You say to delete the contents of the mods/vanilla folder before deploying updates, but I'm imagining different mods will result in different vanilla files that need to be reverted. Does it just have a full set of all the critical ones?

[throwaway]

Looks pretty sweet.

How does it do the reversion to vanilla?

You say to delete the contents of the mods/vanilla folder before deploying updates, but I'm imagining different mods will result in different vanilla files that need to be reverted. Does it just have a full set of all the critical ones?

Base game files get backed up the first time they are replaced/ when the counterpart isn't found in the vanilla folder. That will be wrong if you had a modded game to start with, which is likely with modders. For that and other reasons, the most foolproof way is to distribute with an empty vanilla folder.

[jonas165]

When using my own mod for this, I get crashs and now the game tells me to verify interigty. How can that happen if the tool doesn't alter the game files?

[throwaway]

When using my own mod for this, I get crashs and now the game tells me to verify interigty. How can that happen if the tool doesn't alter the game files?

It does alter the game files, it moves the stuff from mods/modname/bin into Data\WARGAME\PC\, same as you'd do with a manual install. If you're getting crashes that you don't get with a manual install, the files are being moved to the wrong place. Try putting a unique file that you can easily find, like a picture, and see where it goes and if that's where you expect it to go. And stick to static addressing [aka don't put files directly in bin/, put them in subfolders under bin].

Also, refer to the faustmann folder for a working example that you can build on.