World safety

Where modded data actually lives, why the vanilla half of your save is never touched, and what happens when ids move or a mod is removed.

You can write a whole mod without reading this page. Read it anyway if you are shipping one, because it explains the guarantees you are making to the people who install it.

The problem beta hands you

A chunk in b1.7.3 stores each block as a byte: ids 0-255, no more. Alongside it sits a 4-bit metadata nibble, 16 values, which vanilla already spends on things like wool color and log type. There is no field for "which mod", no string ids, no room to grow.

So any modded content on this version has to answer one question: where do the extra bits go? The tempting answer is "into the vanilla arrays, we will just use the free numbers". It works, right up until it does not:

• Add or remove a mod and the numbers shift, so blocks come back as the wrong blocks.
• Remove the mod entirely and vanilla reads its leftovers as whatever now occupies those ids.
• Two mods pick the same slot and the save is decided by load order.

The sidecar

RetroAPI does not write modded data into vanilla's bytes at all. Vanilla's region files stay byte-for-byte what vanilla would have written. Everything that does not fit lives beside them:

File	Holds
<world>/retroapi/id_map.dat	the world's own map: example_mod:ruby_ore → 431, plus item and dimension ids
<world>/retroapi/… region sidecars	per-chunk overlays: block ids ≥ 256, and the state bits above the metadata nibble
NBT sub-tags on stacks	modded item identity and components, written as strings

The rule that makes it work: the identifier is the truth, the number is a lease. Your ore is example_mod:ruby_ore forever. The number it happens to have is negotiated per world, per launch, and rewritten whenever it needs to be.

What that buys you

• Removing a mod does not destroy the world. Vanilla's own blocks were never overwritten, so the world still opens; the modded blocks are gone, which is the correct outcome, not corruption.
• Ids can move freely between sessions. Add a mod, remove another, reorder them, the saved map re-anchors everything by name.
• More than 256 blocks (RetroAPI grows the arrays to 32,000 slots) and more than 16 states per block, because neither number has to fit in vanilla's field.
• Multiplayer agrees. On join, the server sends its table and the client re-anchors to it before any chunk or inventory packet is read.

Backups

Before RetroAPI changes anything structural about a world's modded data, it copies the existing retroapi/ folder aside. If something does go wrong, the vanilla region files are untouched by definition and the modded overlay has a previous copy sitting next to it.

Under StationAPI

StationAPI takes a different, equally valid route: it flattens the world format outright, so blocks become states with string ids and the 256/16 limits stop existing. When StationAPI is present, RetroAPI stands down, registration and storage are StationAPI's, and RetroAPI keeps only the parts that do not overlap (entities, dimensions, components, particles, world features).

RetroAPI still writes its id map in that mode, because the map is what a later conversion needs in order to know that 431 once meant example_mod:ruby_ore. Converting a world in either direction is covered in StationAPI interop.

Testing your own mod against this

The behavior above is not theory, RetroAPI's own test mod places modded blocks with wide states, modded items with components, dropped stacks and a modded mob, saves, reloads, and asserts every one of them survived, then converts the world to StationAPI's format and back and asserts again. If your mod does anything unusual with storage, the same pattern (place, save, reload, assert) is the way to check it. See Testing.