What is the purpose of the version number?

I am confused as to the purpose of a version number. My initial understanding was that the version number would refer to the mod itself, i.e., I change that number if I release a new version of my mod. But then, I read this:

[quote=“Tuhalu, post:2, topic:14566, full:false”]The version number in the manifest is meant for version checking by the game. Currently, that version is set to 1. If it was changed to 2, all mods with a version of less than 2 would automatically fail to load. In theory at least, it makes using mods easier by disabling old mods automatically when a new version comes along. For now, make sure it is at least 1 :slight_smile:

Is this how version number works? If so, it seems a bit … well, dumb, to be honest. If this is the case, version number would be completely redundant with either Alpha version or Release version. If this is how it works, I see at least two obvious flaws:

  1. If mods are well-written (I’m specifically thinking of the Zulser mod), they can last across versions, even Alpha versions (from at least Alpha 8 to Alpha 10), without being changed, unless the underlying code it relies on changed (as is the case in Alpha 11 for Zulser). If so, it seems stupid to need to re-release the mod with a new “version” number.
  2. What’s to stop me from calling my mod version “99999999”? Then I’d be good for the next almost-one-hundred-million releases.

I am in the process of creating my first mod, and I will attempt to use semantic versioning on the mod. However, I will continue to just put “1” as the version in the manifest.json until I understand what its use is.

Paging @Sdee, @Albert, @yshan, @brad, and @not_owen_wilson for the logic behind TR’s use of “version”. (Not paging Tom or Tony since they’re out of town, right?)


It’s the modding API version! (a.k.a: mixintos/overrides/etc stuff)

I know that it’d make more sense to put the mod version, and even have another tag in info for the mod author, but the version refers to Stonehearth, not your mod.

This is because at some point they modified significantly the modding API, so they decided to require this new tag in order for mods to work / be recognized and properly loaded by the game. The modding API will change in the future, but until then, we’ll always have to write a 1.

Probably someone from TR can explain it better, but this is the short story.


Oh! So if TR significantly changes the way mods interact with the game, they can force a new version number to render all old mods incompatible? That actually … kind of … makes sense. But only if they renamed the variable to “modding_api_version” instead of “version”.

If so, I wonder how often they plan on changing this version (hopefully never, or at least, very rarely, and certainly not every few alphas).


They are focused on finishing the game, so this is not a priority for them, and right now the api is quite robust. Don’t worry, I think it won’t change until ¿beta? maybe :smile:


@Relyss is exactly right, it’s the version number of the modding API. But the modding API is just the API for the whole game at the moment; once we’re done with the bulk of the game we’ll go back and figure out which functions really should be public and unchanging, and which ones should be private and subject to change. I would expect that we would do this work after multiplayer, because MP is the last big feature I know about that has the chance of changing everything :smile: dramatic music


Thanks for the explanation, @sdee! Could I just throw in the pitch that next time you do change the version number, you also change the variable name to make its purpose slightly more obvious?

1 Like