Add logger, JUnit setup, and the versioned transformer API

This commit is contained in:
Ruling-0 committed 2026-08-27 19:45:02 -05:00
1 parent 42b5e4d38c
commit 490eefc6b7
9 files changed
+218

No files matched your search

+4
View File
@@ -3,3 +3,7 @@
plugins {
id 'com.gtnewhorizons.gtnhconvention'
}
test {
useJUnitPlatform()
}
+6
View File
@@ -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')
}
@@ -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);
@@ -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;
}
@@ -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.
* <p>
* 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.
* <p>
* 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) {}
}
@@ -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;
}
@@ -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<IVersionedTransformer> 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<IVersionedTransformer> transformers() {
return Collections.unmodifiableList(TRANSFORMERS);
}
}
@@ -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<IVersionedTransformer> transformers) {
NBTTagCompound stamps = carried == null ? new NBTTagCompound() : (NBTTagCompound) carried.copy();
for (IVersionedTransformer transformer : transformers) {
stamps.setInteger(transformer.key(), transformer.currentVersion());
}
container.setTag(KEY, stamps);
}
}
@@ -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"));
}
}