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: + *
* 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