diff --git a/README.md b/README.md index 4af95b6..2a28029 100644 --- a/README.md +++ b/README.md @@ -13,6 +13,7 @@ runtime. Allowing developers to replace, migrate or modify game elements based o 6. **Numeric ID Identification for Removed Content**: A way to identify the ID of any content that has ceased to exist. 7. **Versioned Chunk and Player Transformers**: transform a chunk or a player's data exactly once per version of your content, however many sessions it was saved across. 8. **Retired Id Table**: names of removed content keep resolving in every later session. +9. **Custom World Data Transformers**: versioned transformation of a mod's own world storage, offered by the mod that owns it. ## Examples @@ -599,3 +600,31 @@ When a name resolves only through retired ids, Postea logs it once per world loa ``` Block ExtraUtilities:cobblestone_compressed is no longer registered; its transformers target retired id(s) [3402] ``` + +### 11. Custom World Data + +Some mods keep item stacks outside chunks and player data: a quest database, an ender chest table, per-player +sidecar files. Postea never reads or writes such files itself -- the owning mod offers their content through +`CustomDataReplacementManager` and versioned transformers reach it via `IVersionedTransformer.transformCustomData`. + +The contract for the owning mod: + +- Call `CustomDataReplacementManager.transform(storageId, root)` once on the NBT root read from disk, before + consuming it. Postea runs every registered transformer whose stamp differs and writes updated `POSTEA_VERSIONS` + stamps onto the root. Persist that root, stamps included, when writing the storage back. +- A save path that rebuilds its NBT from scratch calls `CustomDataReplacementManager.stamp(freshRoot)` instead: + once `transform` ran at load, the in-memory data is at the current version. +- A consumer that never writes the storage back (a read-only restore of an archived file) calls only `transform`. + An unstamped file re-transforms from the same baseline on every read, which is correct while its bytes never + change. + +The `storageId` is a namespaced label used in logs and crash reports, e.g. `"betterquesting:questDatabase"`. +`transform` must not run before FML has applied the world's saved id map (it throws otherwise); any call site at +world load or later is safe. Stacks in custom storage may carry a string `id` (a registry name) instead of a +numeric one; `CustomDataTransformContext.forEachItemStackTag` visits both forms. + +> [!NOTE] +> +> Data derived from stacks rather than stored as stacks is out of reach of this API. Known cases that stay +> untransformed: Thaumcraft's scanned-object hashes (players rescan after their items' metadata changes), fluid +> names, MineTweaker script item literals, and the numeric item ids inside vanilla `stats/` files. diff --git a/src/main/java/com/gtnewhorizons/postea/api/CustomDataReplacementManager.java b/src/main/java/com/gtnewhorizons/postea/api/CustomDataReplacementManager.java new file mode 100644 index 0000000..5aab1d8 --- /dev/null +++ b/src/main/java/com/gtnewhorizons/postea/api/CustomDataReplacementManager.java @@ -0,0 +1,71 @@ +package com.gtnewhorizons.postea.api; + +import net.minecraft.nbt.NBTTagCompound; +import net.minecraft.util.ReportedException; + +import com.gtnewhorizons.postea.Postea; +import com.gtnewhorizons.postea.utility.ChunkFixerUtility; +import com.gtnewhorizons.postea.utility.IDRegistry; +import com.gtnewhorizons.postea.utility.VersionStamps; +import com.gtnewhorizons.postea.utility.VersionedTransformerLog; + +import cpw.mods.fml.common.FMLCommonHandler; + +/** + * Versioned transformation of a mod's own world storage -- files outside chunks and player data, such as a quest + * database or an ender chest table. Postea never reads or writes such files itself; the owning mod offers their + * content at the moments it controls: + * + */ +public abstract class CustomDataReplacementManager { + + /** + * Transforms {@code root} in place through every registered transformer whose stamp differs from its current + * version, then writes the updated stamps onto {@code root}. Does nothing on the client. Throws + * {@link IllegalStateException} when called before the world's saved id mappings were applied. + */ + public static void transform(String storageId, NBTTagCompound root) { + if (!FMLCommonHandler.instance() + .getEffectiveSide() + .isServer()) return; + if (!IDRegistry.isMappingApplied()) { + throw new IllegalStateException( + "Custom data " + storageId + + " was offered for transformation before the world's id mappings were applied"); + } + NBTTagCompound stamps = VersionStamps.read(root); + for (IVersionedTransformer transformer : VersionedReplacementManager.transformers()) { + int current = transformer.currentVersion(); + int stored = VersionStamps.stored(stamps, transformer.key()); + if (stored == current) continue; + VersionedTransformerLog.announce(transformer, stored, current); + Postea.LOG.debug("{}: custom data {} from version {} to {}", transformer.key(), storageId, stored, current); + try { + transformer.transformCustomData(new CustomDataTransformContext(storageId, root, stored, current)); + } catch (Throwable t) { + throw new ReportedException( + ChunkFixerUtility.describe(t, transformer, stored, current, "Custom data", storageId)); + } + } + VersionStamps.write(root, stamps, VersionedReplacementManager.transformers()); + } + + /** + * Stamps a freshly built root about to be written to disk with every registered transformer's current version. + * Does nothing on the client. + */ + public static void stamp(NBTTagCompound root) { + if (!FMLCommonHandler.instance() + .getEffectiveSide() + .isServer()) return; + VersionStamps.write(root, VersionStamps.read(root), VersionedReplacementManager.transformers()); + } +} diff --git a/src/main/java/com/gtnewhorizons/postea/api/CustomDataTransformContext.java b/src/main/java/com/gtnewhorizons/postea/api/CustomDataTransformContext.java new file mode 100644 index 0000000..e12efbd --- /dev/null +++ b/src/main/java/com/gtnewhorizons/postea/api/CustomDataTransformContext.java @@ -0,0 +1,61 @@ +package com.gtnewhorizons.postea.api; + +import java.util.function.Consumer; + +import net.minecraft.nbt.NBTTagCompound; + +import com.gtnewhorizons.postea.utility.NbtItemStacks; +import com.gtnewhorizons.postea.utility.VersionStamps; + +/** + * A mod's own world storage as handed to {@link IVersionedTransformer#transformCustomData}: the NBT root the + * owning mod read from disk, before it consumes the data. Unlike chunk and player data, stacks here may carry a + * string {@code id} (a registry name, as quest databases store) instead of a numeric one; + * {@link #forEachItemStackTag} visits both forms. + */ +public final class CustomDataTransformContext { + + public static final int UNSTAMPED = VersionStamps.UNSTAMPED; + + private final String storageId; + private final NBTTagCompound root; + private final int storedVersion; + private final int currentVersion; + + public CustomDataTransformContext(String storageId, NBTTagCompound root, int storedVersion, int currentVersion) { + this.storageId = storageId; + this.root = root; + this.storedVersion = storedVersion; + this.currentVersion = currentVersion; + } + + /** + * The storage's identity as its owner registered it, e.g. {@code "betterquesting:questDatabase"}. + */ + public String storageId() { + return storageId; + } + + public NBTTagCompound root() { + return root; + } + + /** + * The version this transformer's key was stamped with when the storage was written, or {@link #UNSTAMPED}. + */ + public int storedVersion() { + return storedVersion; + } + + public int currentVersion() { + return currentVersion; + } + + /** + * Visits every serialized item stack in the storage, including stacks whose {@code id} is a string name; see + * {@link NbtItemStacks#forEach}. + */ + public void forEachItemStackTag(Consumer visitor) { + NbtItemStacks.forEach(root, visitor, true); + } +} diff --git a/src/main/java/com/gtnewhorizons/postea/api/IVersionedTransformer.java b/src/main/java/com/gtnewhorizons/postea/api/IVersionedTransformer.java index f32ad6b..e311e1a 100644 --- a/src/main/java/com/gtnewhorizons/postea/api/IVersionedTransformer.java +++ b/src/main/java/com/gtnewhorizons/postea/api/IVersionedTransformer.java @@ -14,6 +14,9 @@ package com.gtnewhorizons.postea.api; *

* Chunk transformers may run on a chunk I/O thread, several concurrently for different chunks. They must not touch * world state beyond the context and their own state must be safe to read concurrently. + *

+ * Mods that keep item stacks in their own world storage offer it through {@link CustomDataReplacementManager}; + * such storage is stamped the same way and reaches the transformer through {@link #transformCustomData}. */ public interface IVersionedTransformer { @@ -37,4 +40,10 @@ public interface IVersionedTransformer { * {@link #currentVersion()}. */ default void transformPlayer(PlayerDataTransformContext ctx) {} + + /** + * Brings a mod's own world storage stamped at {@link CustomDataTransformContext#storedVersion()} to + * {@link #currentVersion()}. Stacks in such storage may carry a string {@code id} instead of a numeric one. + */ + default void transformCustomData(CustomDataTransformContext ctx) {} } diff --git a/src/main/java/com/gtnewhorizons/postea/utility/ChunkFixerUtility.java b/src/main/java/com/gtnewhorizons/postea/utility/ChunkFixerUtility.java index 814465b..72b2198 100644 --- a/src/main/java/com/gtnewhorizons/postea/utility/ChunkFixerUtility.java +++ b/src/main/java/com/gtnewhorizons/postea/utility/ChunkFixerUtility.java @@ -122,7 +122,7 @@ public class ChunkFixerUtility { } } - static CrashReport describe(Throwable cause, IVersionedTransformer transformer, int stored, int current, + public static CrashReport describe(Throwable cause, IVersionedTransformer transformer, int stored, int current, String subjectName, String subject) { CrashReport report = CrashReport.makeCrashReport(cause, "Running versioned transformer " + transformer.key()); CrashReportCategory category = report.makeCategory("Postea versioned transformer"); diff --git a/src/main/java/com/gtnewhorizons/postea/utility/IDRegistry.java b/src/main/java/com/gtnewhorizons/postea/utility/IDRegistry.java index 7e4d581..34b1050 100644 --- a/src/main/java/com/gtnewhorizons/postea/utility/IDRegistry.java +++ b/src/main/java/com/gtnewhorizons/postea/utility/IDRegistry.java @@ -39,6 +39,7 @@ public abstract class IDRegistry { private static File tableFile; private static WorldIdTable table = new WorldIdTable(); private static IntSet blockedIds; + private static volatile boolean mappingApplied; /** * Opens the retired id table of the world about to load. Until {@link #endWorld()} the saved id map is captured @@ -53,10 +54,18 @@ public abstract class IDRegistry { tableFile = null; table = new WorldIdTable(); blockedIds = null; + mappingApplied = false; BLOCK_NAME_TO_ID.clear(); ITEM_NAME_TO_ID.clear(); } + /** + * Whether FML has applied the loading world's saved id map in this session. + */ + public static boolean isMappingApplied() { + return mappingApplied; + } + /** * Triggers all the callbacks registered by other mods that wish to identify a block that may no longer exist. * These callbacks effectively remove the need for dummies, and should help improve performance at runtime. @@ -66,6 +75,7 @@ public abstract class IDRegistry { // some space memory we can just ignore adding stuff safely. if (!Loader.instance() .isInState(LoaderState.SERVER_ABOUT_TO_START)) return; + mappingApplied = true; for (Map.Entry>> kv : BLOCK_ID_RESOLVERS.asMap() .entrySet()) { int id = getBlockId(kv.getKey()); diff --git a/src/main/java/com/gtnewhorizons/postea/utility/NbtItemStacks.java b/src/main/java/com/gtnewhorizons/postea/utility/NbtItemStacks.java index fbbb9c6..cfe3230 100644 --- a/src/main/java/com/gtnewhorizons/postea/utility/NbtItemStacks.java +++ b/src/main/java/com/gtnewhorizons/postea/utility/NbtItemStacks.java @@ -4,6 +4,7 @@ import static net.minecraftforge.common.util.Constants.NBT.TAG_ANY_NUMERIC; import static net.minecraftforge.common.util.Constants.NBT.TAG_COMPOUND; import static net.minecraftforge.common.util.Constants.NBT.TAG_INT; import static net.minecraftforge.common.util.Constants.NBT.TAG_SHORT; +import static net.minecraftforge.common.util.Constants.NBT.TAG_STRING; import java.util.function.Consumer; @@ -13,7 +14,9 @@ import net.minecraft.nbt.NBTTagList; /** * Visits every serialized item stack in an NBT tree. A compound is a stack when it has a numeric {@code id} or an - * EndlessIDs {@code idExt} together with a {@code Count}. The walk is pre-order and descends into every compound + * EndlessIDs {@code idExt} together with a {@code Count}; in string-id mode a string {@code id} (a registry name, + * as quest databases store) also qualifies. String-id mode must not be used on chunk or player trees, where tile + * entity compounds carry a string {@code id} of their own. The walk is pre-order and descends into every compound * and every list of compounds, so stacks nested inside another stack's {@code tag} (backpacks, storage cells) are * visited too. Lists of lists are not descended. A visitor may change or remove keys of the stack it is given; it * must not touch other parts of the tree. @@ -23,21 +26,30 @@ public final class NbtItemStacks { private NbtItemStacks() {} public static void forEach(NBTBase root, Consumer visitor) { + forEach(root, visitor, false); + } + + public static void forEach(NBTBase root, Consumer visitor, boolean stringIds) { if (root instanceof NBTTagCompound compound) { - if (isStack(compound)) visitor.accept(compound); + if (isStack(compound, stringIds)) visitor.accept(compound); for (Object key : compound.func_150296_c()) { - forEach(compound.getTag((String) key), visitor); + forEach(compound.getTag((String) key), visitor, stringIds); } } else if (root instanceof NBTTagList list && list.func_150303_d() == TAG_COMPOUND) { for (int i = 0; i < list.tagCount(); i++) { - forEach(list.getCompoundTagAt(i), visitor); + forEach(list.getCompoundTagAt(i), visitor, stringIds); } } } public static boolean isStack(NBTTagCompound compound) { + return isStack(compound, false); + } + + public static boolean isStack(NBTTagCompound compound, boolean stringIds) { return compound.hasKey("Count", TAG_ANY_NUMERIC) && (compound.hasKey("id", TAG_SHORT) || compound.hasKey("id", TAG_INT) - || compound.hasKey("idExt", TAG_INT)); + || compound.hasKey("idExt", TAG_INT) + || (stringIds && compound.hasKey("id", TAG_STRING))); } } diff --git a/src/test/java/com/gtnewhorizons/postea/utility/NbtItemStacksTest.java b/src/test/java/com/gtnewhorizons/postea/utility/NbtItemStacksTest.java index 8fdcc32..f4e8d78 100644 --- a/src/test/java/com/gtnewhorizons/postea/utility/NbtItemStacksTest.java +++ b/src/test/java/com/gtnewhorizons/postea/utility/NbtItemStacksTest.java @@ -77,6 +77,24 @@ class NbtItemStacksTest { assertEquals(Collections.singletonList(extended), visited(root)); } + // Pins the split that keeps chunk and player walks safe: a string id with a Count is a stack only in + // string-id mode, which custom data uses and tile entity trees never do. + @Test + void stringIdStacksAreVisitedOnlyInStringIdMode() { + NBTTagCompound quest = new NBTTagCompound(); + quest.setString("id", "examplemod:gem"); + quest.setInteger("Count", 3); + quest.setShort("Damage", (short) 7); + NBTTagCompound root = new NBTTagCompound(); + root.setTag("requiredItems", quest); + List wide = new ArrayList<>(); + + NbtItemStacks.forEach(root, wide::add, true); + + assertEquals(Collections.emptyList(), visited(root)); + assertEquals(Collections.singletonList(quest), wide); + } + @Test void aVisitorMayInvalidateTheStackItIsGiven() { NBTTagCompound first = stack(5, 1);