From 490eefc6b7e6fea4c7fd76d4020a9e52462b4006 Mon Sep 17 00:00:00 2001 From: Ruling-0 <47913168+Ruling-0@users.noreply.github.com> Date: Thu, 27 Aug 2026 19:45:02 -0500 Subject: [PATCH] Add logger, JUnit setup, and the versioned transformer API --- build.gradle | 4 ++ dependencies.gradle | 6 ++ .../java/com/gtnewhorizons/postea/Postea.java | 5 ++ .../postea/api/ChunkTransformContext.java | 8 +++ .../postea/api/IVersionedTransformer.java | 40 ++++++++++++ .../api/PlayerDataTransformContext.java | 8 +++ .../api/VersionedReplacementManager.java | 36 +++++++++++ .../postea/utility/VersionStamps.java | 48 ++++++++++++++ .../postea/utility/VersionStampsTest.java | 63 +++++++++++++++++++ 9 files changed, 218 insertions(+) create mode 100644 src/main/java/com/gtnewhorizons/postea/api/ChunkTransformContext.java create mode 100644 src/main/java/com/gtnewhorizons/postea/api/IVersionedTransformer.java create mode 100644 src/main/java/com/gtnewhorizons/postea/api/PlayerDataTransformContext.java create mode 100644 src/main/java/com/gtnewhorizons/postea/api/VersionedReplacementManager.java create mode 100644 src/main/java/com/gtnewhorizons/postea/utility/VersionStamps.java create mode 100644 src/test/java/com/gtnewhorizons/postea/utility/VersionStampsTest.java diff --git a/build.gradle b/build.gradle index e57a16f..443fc39 100644 --- a/build.gradle +++ b/build.gradle @@ -3,3 +3,7 @@ plugins { id 'com.gtnewhorizons.gtnhconvention' } + +test { + useJUnitPlatform() +} diff --git a/dependencies.gradle b/dependencies.gradle index 61a6d2a..f6c7d7c 100644 --- a/dependencies.gradle +++ b/dependencies.gradle @@ -5,4 +5,10 @@ dependencies { compileOnly('com.falsepattern:chunkapi-mc1.7.10:0.8.2:dev') compileOnly('com.falsepattern:endlessids-mc1.7.10:1.7.1:dev') compileOnly("com.github.GTNewHorizons:NotEnoughItems:2.8.75-GTNH:dev") { transitive = false } + + testImplementation(platform('org.junit:junit-bom:5.11.4')) + testImplementation('org.junit.jupiter:junit-jupiter') + testRuntimeOnly('org.junit.platform:junit-platform-launcher') + // fastutil is only on the compile/runtime classpath via the patched Minecraft jar, not the plain test JVM. + testRuntimeOnly('it.unimi.dsi:fastutil:8.5.18') } diff --git a/src/main/java/com/gtnewhorizons/postea/Postea.java b/src/main/java/com/gtnewhorizons/postea/Postea.java index 59ca3ae..6a7a6f2 100644 --- a/src/main/java/com/gtnewhorizons/postea/Postea.java +++ b/src/main/java/com/gtnewhorizons/postea/Postea.java @@ -3,6 +3,9 @@ package com.gtnewhorizons.postea; import net.minecraftforge.common.MinecraftForge; import net.minecraftforge.event.world.ChunkEvent; +import org.apache.logging.log4j.LogManager; +import org.apache.logging.log4j.Logger; + import com.gtnewhorizons.postea.utility.ChunkFixerUtility; import com.gtnewhorizons.postea.utility.IDRegistry; import com.gtnewhorizons.postea.utility.MissingMappingHandler; @@ -29,6 +32,8 @@ public class Postea { public static final String MODID = "postea"; public static final String MODNAME = "Postea"; + public static final Logger LOG = LogManager.getLogger(MODNAME); + @Mod.EventHandler public void preInit(FMLPreInitializationEvent event) { MinecraftForge.EVENT_BUS.register(this); diff --git a/src/main/java/com/gtnewhorizons/postea/api/ChunkTransformContext.java b/src/main/java/com/gtnewhorizons/postea/api/ChunkTransformContext.java new file mode 100644 index 0000000..9b8a46f --- /dev/null +++ b/src/main/java/com/gtnewhorizons/postea/api/ChunkTransformContext.java @@ -0,0 +1,8 @@ +package com.gtnewhorizons.postea.api; + +import com.gtnewhorizons.postea.utility.VersionStamps; + +public final class ChunkTransformContext { + + public static final int UNSTAMPED = VersionStamps.UNSTAMPED; +} diff --git a/src/main/java/com/gtnewhorizons/postea/api/IVersionedTransformer.java b/src/main/java/com/gtnewhorizons/postea/api/IVersionedTransformer.java new file mode 100644 index 0000000..9efa934 --- /dev/null +++ b/src/main/java/com/gtnewhorizons/postea/api/IVersionedTransformer.java @@ -0,0 +1,40 @@ +package com.gtnewhorizons.postea.api; + +/** + * A transformer that brings saved data written under an older version of its owner's content up to the current + * version. Postea stamps every chunk and every player it saves with {@link #currentVersion()} under {@link #key()} + * and, when reading, invokes the transformer only for data whose stamp differs, so each chunk and player is seen + * exactly once per version change no matter how many sessions passed in between. Data saved before the transformer + * existed reads as {@link ChunkTransformContext#UNSTAMPED}; the transformer decides what that means. + *

+ * Register through {@link VersionedReplacementManager#register(IVersionedTransformer)} during mod loading, postInit + * at the latest. Transformers run in registration order and before every other Postea pass, so a transformer whose + * output depends on another mod's versioned data (for example one that writes that mod's indices) must register + * after that mod; FML's dependency ordering guarantees this when both register in the same lifecycle phase. + *

+ * 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. + */ +public interface IVersionedTransformer { + + /** + * The stamp key, unique across all registered transformers, e.g. {@code "materiallib:idList"}. + */ + String key(); + + /** + * The version the transformer's output is written under. Sampled at every read and every save. + */ + int currentVersion(); + + /** + * Brings a chunk stamped at {@link ChunkTransformContext#storedVersion()} to {@link #currentVersion()}. + */ + default void transformChunk(ChunkTransformContext ctx) {} + + /** + * Brings a player's saved data stamped at {@link PlayerDataTransformContext#storedVersion()} to + * {@link #currentVersion()}. + */ + default void transformPlayer(PlayerDataTransformContext ctx) {} +} diff --git a/src/main/java/com/gtnewhorizons/postea/api/PlayerDataTransformContext.java b/src/main/java/com/gtnewhorizons/postea/api/PlayerDataTransformContext.java new file mode 100644 index 0000000..61e19f4 --- /dev/null +++ b/src/main/java/com/gtnewhorizons/postea/api/PlayerDataTransformContext.java @@ -0,0 +1,8 @@ +package com.gtnewhorizons.postea.api; + +import com.gtnewhorizons.postea.utility.VersionStamps; + +public final class PlayerDataTransformContext { + + public static final int UNSTAMPED = VersionStamps.UNSTAMPED; +} diff --git a/src/main/java/com/gtnewhorizons/postea/api/VersionedReplacementManager.java b/src/main/java/com/gtnewhorizons/postea/api/VersionedReplacementManager.java new file mode 100644 index 0000000..d56f3d8 --- /dev/null +++ b/src/main/java/com/gtnewhorizons/postea/api/VersionedReplacementManager.java @@ -0,0 +1,36 @@ +package com.gtnewhorizons.postea.api; + +import java.util.Collections; +import java.util.List; +import java.util.Objects; +import java.util.concurrent.CopyOnWriteArrayList; + +/** + * Registration of {@link IVersionedTransformer}s. See that interface for the execution contract. + */ +public abstract class VersionedReplacementManager { + + private static final List TRANSFORMERS = new CopyOnWriteArrayList<>(); + + /** + * Registers a transformer. Throws {@link IllegalArgumentException} when its key is empty or already registered. + */ + public static void register(IVersionedTransformer transformer) { + String key = Objects.requireNonNull(transformer.key(), "key must not be null"); + if (key.isEmpty()) throw new IllegalArgumentException("Versioned transformer key must not be empty"); + for (IVersionedTransformer existing : TRANSFORMERS) { + if (existing.key() + .equals(key)) { + throw new IllegalArgumentException("A versioned transformer is already registered for " + key); + } + } + TRANSFORMERS.add(transformer); + } + + /** + * The registered transformers in registration order. + */ + public static List transformers() { + return Collections.unmodifiableList(TRANSFORMERS); + } +} diff --git a/src/main/java/com/gtnewhorizons/postea/utility/VersionStamps.java b/src/main/java/com/gtnewhorizons/postea/utility/VersionStamps.java new file mode 100644 index 0000000..cf51ab4 --- /dev/null +++ b/src/main/java/com/gtnewhorizons/postea/utility/VersionStamps.java @@ -0,0 +1,48 @@ +package com.gtnewhorizons.postea.utility; + +import static net.minecraftforge.common.util.Constants.NBT.TAG_COMPOUND; +import static net.minecraftforge.common.util.Constants.NBT.TAG_INT; + +import net.minecraft.nbt.NBTTagCompound; + +import com.gtnewhorizons.postea.api.IVersionedTransformer; + +/** + * The {@code POSTEA_VERSIONS} compound Postea keeps on a chunk's {@code Level} tag and on a player's root tag: one + * int per registered transformer key. Keys of transformers that are not registered in the running session are + * carried through unchanged so a mod that is temporarily absent does not lose its stamps. + */ +public final class VersionStamps { + + public static final String KEY = "POSTEA_VERSIONS"; + public static final int UNSTAMPED = -1; + + private VersionStamps() {} + + /** + * The stamps stored on {@code container}, or null when it carries none. + */ + public static NBTTagCompound read(NBTTagCompound container) { + return container.hasKey(KEY, TAG_COMPOUND) ? container.getCompoundTag(KEY) : null; + } + + /** + * The version stored for {@code key} in {@code stamps} (which may be null), or {@link #UNSTAMPED}. + */ + public static int stored(NBTTagCompound stamps, String key) { + return stamps != null && stamps.hasKey(key, TAG_INT) ? stamps.getInteger(key) : UNSTAMPED; + } + + /** + * Writes the stamps onto {@code container}: {@code carried} (the stamps the data was read with, or null) with + * every registered transformer's key set to its current version. + */ + public static void write(NBTTagCompound container, NBTTagCompound carried, + Iterable transformers) { + NBTTagCompound stamps = carried == null ? new NBTTagCompound() : (NBTTagCompound) carried.copy(); + for (IVersionedTransformer transformer : transformers) { + stamps.setInteger(transformer.key(), transformer.currentVersion()); + } + container.setTag(KEY, stamps); + } +} diff --git a/src/test/java/com/gtnewhorizons/postea/utility/VersionStampsTest.java b/src/test/java/com/gtnewhorizons/postea/utility/VersionStampsTest.java new file mode 100644 index 0000000..31a6ad0 --- /dev/null +++ b/src/test/java/com/gtnewhorizons/postea/utility/VersionStampsTest.java @@ -0,0 +1,63 @@ +package com.gtnewhorizons.postea.utility; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertNull; + +import java.util.Collections; + +import net.minecraft.nbt.NBTTagCompound; + +import org.junit.jupiter.api.Test; + +import com.gtnewhorizons.postea.api.IVersionedTransformer; + +class VersionStampsTest { + + private static IVersionedTransformer transformer(String key, int version) { + return new IVersionedTransformer() { + + @Override + public String key() { + return key; + } + + @Override + public int currentVersion() { + return version; + } + }; + } + + @Test + void anUnstampedContainerReadsAsUnstamped() { + NBTTagCompound container = new NBTTagCompound(); + + assertNull(VersionStamps.read(container)); + assertEquals(VersionStamps.UNSTAMPED, VersionStamps.stored(null, "mod:key")); + } + + @Test + void writeStampsRegisteredKeysAtTheirCurrentVersionAndCarriesUnknownKeys() { + NBTTagCompound carried = new NBTTagCompound(); + carried.setInteger("absentmod:key", 7); + carried.setInteger("mod:key", 2); + NBTTagCompound container = new NBTTagCompound(); + + VersionStamps.write(container, carried, Collections.singletonList(transformer("mod:key", 3))); + + NBTTagCompound stamps = VersionStamps.read(container); + assertEquals(3, VersionStamps.stored(stamps, "mod:key")); + assertEquals(7, VersionStamps.stored(stamps, "absentmod:key")); + assertEquals(2, carried.getInteger("mod:key")); + } + + @Test + void writeWithoutCarriedStampsWritesOnlyRegisteredKeys() { + NBTTagCompound container = new NBTTagCompound(); + + VersionStamps.write(container, null, Collections.singletonList(transformer("mod:key", 1))); + + assertEquals(1, VersionStamps.stored(VersionStamps.read(container), "mod:key")); + assertEquals(VersionStamps.UNSTAMPED, VersionStamps.stored(VersionStamps.read(container), "other:key")); + } +}