Class ConfigMigration
Why: every plugin load writes every config value to the shared properties file, and RuneLite's default pass only replaces a stored value that no longer parses. A changed default therefore never reaches an existing install: a boss plugin's third fight (2026-09-26) ran with glyphs OFF, hazards LEARN and the old prayer restores because those old defaults still parsed, while the renamed prayer mode was reset (its old value no longer did).
A migration is a list of ConfigMigration.Steps, each with a version. run(privbot.config.ConfigMigration.ConfigAccess, privbot.config.ConfigMigration.Step...) applies every step whose version is above
the stored settingsVersion of the group, in version order, then stores the highest version, so it runs once
per install. replaceIfEquals(int, java.lang.String, java.lang.String, java.lang.String) only rewrites a value still equal to the old default (a value the user changed
is left alone) and unset(int, java.lang.String) drops a dead key. Nothing here throws: an unreadable config is logged and nothing is
changed (the version is not stored, so the next start tries again; every step is idempotent).
The version and the old values are read from the settings file on disk (ConfigMigration.ConfigAccess.saved(java.lang.String)), not from the
client's memory. Every client on the machine shares that file, but each keeps the copy it loaded at launch and patches
only the keys it writes. A client launched before another one migrated would otherwise see no version, migrate again
from its stale copy and write the old defaults' replacements over a value the user has since chosen in the other
client (review 2026-09-26, "a stale client overrides the user"). Reading the file, it sees the migration done and
instead brings its own copy of every key the steps name in line with the file.
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic final classOne value a step changed:keyfromfromtoto;tois null when the key was unset.static interfaceMinimal view of RuneLite's ConfigManager for one config group, so tests need no client.static interfaceOne change, applied when its version is above the stored one. -
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final StringThe key, inside the plugin's config group, that records the last migration version applied. -
Method Summary
Modifier and TypeMethodDescriptionstatic ConfigMigration.ConfigAccessgroupof a live ConfigManager: reads and writes go through the manager, andConfigMigration.ConfigAccess.saved(java.lang.String)reads the properties file it saves to (savedIn(privbot.config.ConfigMigration.ConfigAccess, java.nio.file.Path, java.lang.String)).static ConfigMigration.StepreplaceIfEquals(int version, String key, String oldValue, String newValue) RewriteskeytonewValueonly while its saved value, trimmed, equalsoldValueexactly (case-sensitive: enums are stored by name).static List<ConfigMigration.Change> run(ConfigMigration.ConfigAccess config, ConfigMigration.Step... steps) Applies every step whose version is above the savedVERSION_KEY, in version order (steps of one version in the order given), then stores the highest version given.static ConfigMigration.ConfigAccesssavedIn(ConfigMigration.ConfigAccess live, Path file, String group) live, withConfigMigration.ConfigAccess.saved(java.lang.String)read from the properties filefile(keys<group>.<key>, as RuneLite saves them), fresh on every read, overlaid with this view's own writes (the client saves those to the file within a second, after the migration has read on).static ConfigMigration.StepDropskey(a setting that no longer exists); nothing when it is not saved.
-
Field Details
-
VERSION_KEY
The key, inside the plugin's config group, that records the last migration version applied.- See Also:
-
-
Method Details
-
of
public static ConfigMigration.ConfigAccess of(net.runelite.client.config.ConfigManager cm, String group) groupof a live ConfigManager: reads and writes go through the manager, andConfigMigration.ConfigAccess.saved(java.lang.String)reads the properties file it saves to (savedIn(privbot.config.ConfigMigration.ConfigAccess, java.nio.file.Path, java.lang.String)). A manager whose file cannot be found answers from its memory. -
savedIn
public static ConfigMigration.ConfigAccess savedIn(ConfigMigration.ConfigAccess live, Path file, String group) live, withConfigMigration.ConfigAccess.saved(java.lang.String)read from the properties filefile(keys<group>.<key>, as RuneLite saves them), fresh on every read, overlaid with this view's own writes (the client saves those to the file within a second, after the migration has read on). A file that does not exist yet (a new install) answers fromlive; one that cannot be read throws, sorun(privbot.config.ConfigMigration.ConfigAccess, privbot.config.ConfigMigration.Step...)changes nothing more and tries again next start. -
replaceIfEquals
public static ConfigMigration.Step replaceIfEquals(int version, String key, String oldValue, String newValue) RewriteskeytonewValueonly while its saved value, trimmed, equalsoldValueexactly (case-sensitive: enums are stored by name). A missing key, or any other value, is left alone. -
unset
Dropskey(a setting that no longer exists); nothing when it is not saved. -
run
public static List<ConfigMigration.Change> run(ConfigMigration.ConfigAccess config, ConfigMigration.Step... steps) Applies every step whose version is above the savedVERSION_KEY, in version order (steps of one version in the order given), then stores the highest version given. Returns the values that changed. A saved version that is not a number counts as 0 (every step is idempotent). Afterwards this client's own copy of the version and of every key a step names takes the saved file's value where the two differ: another client migrated (or the user changed the key there) after this one loaded its copy. That is logged, not returned: this load did not change the saved settings. Never throws: an unreadable or unwritable config is logged, the changes made so far are returned and the version is not stored.
-