The third and last part of our series of articles, covering mod launchers and update agents.
- A special gift from AvP2 Team Fortress
- A special gift from AvP2 Team Fortress - part 2
- A special gift from AvP2 Team Fortress - part 3
In this last part of our article we'll cover command line options that need to be passed to the command line to the original game so that a specific mod is launched. We'll also cover some best practices for using the mod launcher.
And if you haven't done it already,
DOWNLOAD THE MOD LAUNCHER HERE!
We'll give some concrete examples on how to launch a mod for Quake 3 and Source, but most games (and engines) support (in a form or the other) command line parameters for starting a mod.
Now, each game engine has it's own command line parameter to load up a mod:
- for Quake 3 it's "+set fs_game mod_folder_name_here"
- for C&C Generals it's "-mod big_file_name_here"
- for Company of Heroes - "-dev -modname mod_name_here"
- for Crysis is "-mod mod_name_here".
- for Source is "-game mod_folder_name_here".
Before starting with the examples, it is worth mentioning that a lot of games use the Quake 3 engine, or its derivates. Medal of Honor, Call of Duty, Soldier of Fortune, some of the Star Trek games, some of the Jedi Knight games and the list can go on. It is very likely the mods for those games can benefit from the mod launcher just as well.
"Command" section examples
The mod usually is installed as a folder called "rally", next to quake3.exe. So, place the launcher .exe and the .ini file next to the quake executable. Have the launcher and the .ini file renamed as rally.exe and rally.ini respectively, and set the [command] section of the ini file to this:rally.ini
modName = "Quake 3 Rally"
commandline = "quake3.exe +set fs_game rally"
The example we've chosen here is for Eternal Silence, but it works for all Source mods. So, rename the launcher and .ini file to eternal-silence.exe and eternal-silence.ini. Have them placed in the same folder as the hl2.exe (Steam\steamapps\\eternal-silence if you got it through Steam, or near the .exe of the Half Life 2 game if the mod is not distributed through steam).
The .ini file will contain the following command section:
modName = "Eternal Silence"
commandline = "hl2.exe -game esmod"
The trick for Source mods (and for Quake 3) is that the launcher, ini file, game executable and mod folder must be located in the same folder. This way, the launcher "sees" the game executable, which in turn "sees" the mod folder (esmod in our case).
What makes this mod launcher/updater interesting is that it is an external component. This has the distinct advantage that it does not require any changes in a mod's code base. No recompile, no possibility of screwing things up. It also uses just a web server as an update platform. It glues up the mod and it's website into one steam-like platform.
Now that you turned your mod into your own mini-steam, you might fall in some of it's pitfalls. This section tries to point out some of the most common ones:
I can force the players to update whenever I want!
Well, yes and no. Technically, yes, you can push updates at any rate you want. But your players might also become furstrated that they have to update each time the fire up the mod. Or worse, you might end up releasing updates faster than the community can adapt to, and you end up with half of the community playing one version of the mod and the other half playing another one.
Ideally, you'll want to bundle up your updates, and release them at a pre-defined schedule. Or use a policy like "each 1st of the month you might get an update".
Not all updates are mandatory
This is related to the version numbering system, major.minor.micro.
The update mechanism is set so that a change in the major or minor version number will prompt the player with the "mandatory update" pop-up. This should also be consistent with the update itself: if you have an update that beaks compatibility with the previous version, make sure you alter the minor version number, or the major version if the changes are really, really big.
If the patch you created does not break compatibility with the previous version, then change just the micro version.
Update the local .ini file
When you prepare a patch, make sure that the local .ini file is updated to reflect the same version number as the remote .ini file. Otherwise, the players will be stuck in a loop of start the launcher -> detect update -> install update -> start launcher -> detect update ...
This must be done by the patch installer itself.
Some of you might think "Wait! Why don't I code this functionality in the launcher/updater component itself?" Well, there's an easy answer for this: say you have the launcher updating the local .ini file. If the player then decides to cancel the installation of the patch, the local file will suggest the mod was updated, while the real situation is that the patch was not installed.
So, here are some of the methods to update the local .ini file using the patch installer:
Method 1: Have the patch overwrite the local .ini file
Basically pack up the launcher INI file with the SFX archive, or with your patch installer. When the patch is installed, the old .ini file gets replaced with the new one.
Method 2: Have the patch modify sections of the local .ini file
This is especially easy when using installers created with NSIS. As an example for Eternal Silence, if the patch installer is supposed to update the local .ini file to version 3.5.2, the code for that would be:
WriteINIStr "$INSTDIR\eternal-silence.ini" "version" "major" 3
WriteINIStr "$INSTDIR\eternal-silence.ini" "version" "minor" 5
WriteINIStr "$INSTDIR\eternal-silence.ini" "version" "micro" 2
And this pretty much concludes our article/tutorial/thinggie about launchers and update mechanisms for mods.