Modding:The Remapper
This page was last verified for Vintage Story version 1.19.8.
The Remapper is a server side system that, under ideal circumstances, no one should know even exists. It's the thing that makes sure your world doesn't go bonkers from installing or removing a mod that adds blocks or items.
Let's say you're writing a mod that implements an Uberbasket. You must compose a recipe for users to follow to create the Uberbasket, and the recipe must specify both the input (the "ingredients") and the output (the Uberbasket). The mod specifies the Uberbasket as the recipe's output with a code in the form of a string: maybe some words separated by dashes.
However, these codes do not store efficiently, so to reduce memory usage, the engine internally assigns a per-world unique number to each item and block, then stores a table that maps codes to ids into the save game. These ids are created when the game loads the blocks and items, and once created, they are never deleted from the mapping. This is what the mapping table might look like:
| Code | Id |
|---|---|
| stick | 6 |
| coal | 7 |
| ingot-iron | 8 |
| ... | ... |
Storing this mapping table into the save game is necessary. To see why, consider what would happen if we added a new mod that inserts a new block into the mapping table before the stick. This would cause the Id numbering to change: suddenly, every stick in the world would turn into coal, every coal in the world would turn into an iron ingot, and so on. New blocks can potentially get added or removed whenever the base game version changes or when a mod gets added or removed.
How does this affect modders?
The issue arises when you decide to change the code of a block or item, or when a user wants to remove one of your mods. When this happens, the modded blocks in the user's savegame get replaced with something else.
Let's say your mod added the Uberbasket, but you realize it was not powerful enough and changed it into the Hyperbasket, including its item code, in your latest mod update. As soon as a player updates to the latest version of your mod, all their Uberbaskets will become unknown items, because the code<->id mapping for the Uberbasket is still stored in the savegame.
Thankfully you can help the player fix this! The commands /bir and /iir let you edit the mapping table. In this case, the player needs to type:
/iir remap hyperbasket uberbasket force
This command effectively searches for "uberbasket" in the mapping table, and then replace its id with the hyperbasket id. When the user reloads the world, all the Uberbaskets will have turned into Hyperbaskets.
The remaps.json
For even greater player convenience, you can create a json patch that adds an entry to assets/game/config/remaps.json. This file lets you add your remaps and the player will get a user friendly dialog popping up that remappings are required. You might want to use the "remapq" subcommand to reduce chat log spam.
Limitations
You may not remap two blocks or items to a single block or item. By definition, all ids must be unique, but if you were to remap 2 to 1, it would mean an item or block would have 2 ids. The game was not designed to handle multiple ids for the same block or item, so the results would be unpredictable.
