Public API to invalidate or replace a cached mod template without bumping settingsVersion

[przemyslaw-zan]

Use case:

• Start the game in language X and register the mod template through setModTemplate(linkage, template, callback).
• Close the game, switch to language Y, and start the game again.
• Our mod now resolves language Y at runtime, but ModsSettingsApi still shows the cached language X template.

Observed behavior:

• The stale template survives a full client restart and language change.
• Calling setModTemplate() again with the same linkage is not enough to replace it.
• In practice, the only reliable way we found to switch the configurator text from X to Y is bumping our internal settingsVersion.

Why this is hard for mod authors:

• settingsVersion looks like a schema/versioning field, but today it also acts as the only public cache-busting mechanism for title/tooltip/option-text changes.
• We would prefer not to bump it for every localization fix or packaging mistake.

Requested API:

• A public way to invalidate or replace the cached template for one linkage, for example:
  • invalidateModTemplate(linkage)
  • refreshModTemplate(linkage, template, callback=None, buttonHandler=None)
  • or a force=True option on setModTemplate()

The important part is being able to replace the persisted template cache for an existing linkage without having to artificially increase settingsVersion.

If this is intentionally unsupported, it would still help to document that settingsVersion is the expected cache-busting mechanism for any template text change, not only schema changes.

[przemyslaw-zan]

Our original localization case is partly resolved on our side, so this issue is not as urgent for us as it first looked, but I do not think it is fully stale. The key detail is in compareTemplates():

• if both the old and new template contain settingsVersion, ModsSettingsApi compares only newTemplate['settingsVersion'] > oldTemplate['settingsVersion']
• otherwise it falls back to a full JSON diff of the template

For our use case, the practical workaround was to stop sending settingsVersion for a template whose text is language-dependent. After that, restarting the client in a different language and calling setModTemplate() again was enough for ModsSettingsApi to replace the cached template, because the localized labels/tooltips/options made the template JSON differ.

So for mods that only need template-text refresh, omitting settingsVersion is a viable workaround.

However, I think the issue still matters for authors who want both of these at the same time:

• schema-style template/version migrations
• cached text refresh without artificially bumping settingsVersion

At minimum, it would help a lot if the README/API docs explicitly documented this behavior:

• settingsVersion is not only a schema/version field
• when present on both templates, it becomes the only cache-replacement check
• omitting it allows template replacement based on full-template diffs instead

That would likely save other mod authors a lot of time when debugging stale configurator language or tooltip text.