From 6dcb08d6a5c5f3460ad2bfbafc1baf1c482b739b Mon Sep 17 00:00:00 2001 From: FalsePattern <30945458+FalsePattern@users.noreply.github.com> Date: Thu, 30 Mar 2023 17:48:26 +0200 Subject: [PATCH] StableAPI --- .../chunk/api/ChunkDataManager.java | 38 ++++++++++++++++++- .../chunk/api/ChunkDataRegistry.java | 8 ++++ .../falsepattern/chunk/api/package-info.java | 4 ++ 3 files changed, 48 insertions(+), 2 deletions(-) diff --git a/src/main/java/com/falsepattern/chunk/api/ChunkDataManager.java b/src/main/java/com/falsepattern/chunk/api/ChunkDataManager.java index e7b9e74..bd49516 100644 --- a/src/main/java/com/falsepattern/chunk/api/ChunkDataManager.java +++ b/src/main/java/com/falsepattern/chunk/api/ChunkDataManager.java @@ -12,6 +12,7 @@ package com.falsepattern.chunk.api; +import com.falsepattern.lib.StableAPI; import org.jetbrains.annotations.Contract; import net.minecraft.nbt.NBTTagCompound; @@ -24,32 +25,47 @@ import java.nio.ByteBuffer; * Singleton instances that can manage custom in chunks. This class only manages the registration of * managers. For the actual networking and data storage, see the internal interfaces of this interface. * Note: This interface does nothing by itself, you also need to implement one or more of the internal interfaces. - * One class can have multiple + * + * @since 0.1.0 + * @see ChunkDataManager.PacketDataManager + * @see ChunkDataManager.ChunkNBTDataManager + * @see ChunkDataManager.SectionNBTDataManager + * @see ChunkDataRegistry + * @author FalsePattern + * @version 0.1.0 */ +@StableAPI(since = "0.1.0") public interface ChunkDataManager { /** * @return The domain of this manager. Usually the modid of the mod that owns this manager. */ + @StableAPI.Expose @Contract(pure = true) String domain(); /** * @return The id of this manager. Usually the name of the manager. Unique per domain. */ - + @StableAPI.Expose @Contract(pure = true) String id(); /** * Implement this interface if you want to synchronize your data with the client. + * + * @since 0.1.0 + * @author FalsePattern + * @version 0.1.0 */ + @StableAPI(since = "0.1.0") interface PacketDataManager extends ChunkDataManager { /** * @return The maximum amount of bytes your data can take up in a packet. * * @implNote This is used to determine the size of the packet compression/decompression buffer. */ + @StableAPI.Expose @Contract(pure = true) int maxPacketSize(); @@ -58,6 +74,7 @@ public interface ChunkDataManager { * * @param chunk The chunk to serialize. */ + @StableAPI.Expose void writeToBuffer(Chunk chunk, int ebsMask, boolean forceUpdate, ByteBuffer data); /** @@ -67,12 +84,18 @@ public interface ChunkDataManager { * @param chunk The chunk to deserialize. * @param buffer The packet buffer to read from. */ + @StableAPI.Expose void readFromBuffer(Chunk chunk, int ebsMask, boolean forceUpdate, ByteBuffer buffer); } /** * Implement this interface if you want to save your data to disk. This is called once per chunk. + * + * @since 0.1.0 + * @author FalsePattern + * @version 0.1.0 */ + @StableAPI(since = "0.1.0") interface ChunkNBTDataManager extends ChunkDataManager { /** * If false, the given nbt compound will be a freshly created object that gets inserted into the actual @@ -82,6 +105,7 @@ public interface ChunkDataManager { * * @implNote This is used internally for reimplementing the vanilla logic. Only change this if you know what you're doing. */ + @StableAPI.Expose @Contract(pure = true) default boolean chunkPrivilegedAccess() { return false; @@ -90,6 +114,7 @@ public interface ChunkDataManager { /** * Serializes your data into an NBT tag. This is used when saving the chunk to disk. */ + @StableAPI.Expose void writeChunkToNBT(Chunk chunk, NBTTagCompound nbt); @@ -99,13 +124,19 @@ public interface ChunkDataManager { * (e.g., loading save before the mod was added), and the manager is not {@link #chunkPrivilegedAccess() privileged}. * In this case, you should initialize the data to a sane default. */ + @StableAPI.Expose void readChunkFromNBT(Chunk chunk, NBTTagCompound nbt); } /** * Implement this interface if you want to save your ExtendedBlockStorage data to disk. This is called once per * ExtendedBlockStorage per chunk. (16 times per chunk) + * + * @since 0.1.0 + * @author FalsePattern + * @version 0.1.0 */ + @StableAPI(since = "0.1.0") interface SectionNBTDataManager extends ChunkDataManager { /** * If false, the given nbt compound will be a freshly created object that gets inserted into the actual @@ -115,6 +146,7 @@ public interface ChunkDataManager { * * @implNote This is used internally for reimplementing the vanilla logic. Only change this if you know what you're doing. */ + @StableAPI.Expose @Contract(pure = true) default boolean sectionPrivilegedAccess() { return false; @@ -123,6 +155,7 @@ public interface ChunkDataManager { /** * Serializes your data into an NBT tag. This is used when saving the chunk to disk. */ + @StableAPI.Expose void writeSectionToNBT(Chunk chunk, ExtendedBlockStorage ebs, NBTTagCompound section); /** @@ -131,6 +164,7 @@ public interface ChunkDataManager { * (e.g., loading save before the mod was added), and the manager is not {@link #sectionPrivilegedAccess() privileged}. * In this case, you should initialize the data to a sane default. */ + @StableAPI.Expose void readSectionFromNBT(Chunk chunk, ExtendedBlockStorage ebs, NBTTagCompound section); } } diff --git a/src/main/java/com/falsepattern/chunk/api/ChunkDataRegistry.java b/src/main/java/com/falsepattern/chunk/api/ChunkDataRegistry.java index fed6ff4..f7e5d52 100644 --- a/src/main/java/com/falsepattern/chunk/api/ChunkDataRegistry.java +++ b/src/main/java/com/falsepattern/chunk/api/ChunkDataRegistry.java @@ -13,14 +13,19 @@ package com.falsepattern.chunk.api; import com.falsepattern.chunk.internal.ChunkDataRegistryImpl; +import com.falsepattern.lib.StableAPI; import java.util.Set; /** * This class is used to register ChunkDataManagers. * + * @since 0.1.0 * @see ChunkDataManager + * @author FalsePattern + * @version 0.1.0 */ +@StableAPI(since = "0.1.0") public class ChunkDataRegistry { /** * Registers a ChunkDataManager. Only do this during the preInit phase. @@ -30,6 +35,7 @@ public class ChunkDataRegistry { * @throws IllegalStateException If the registration stage is over. * @throws IllegalArgumentException If the manager has a duplicate id. */ + @StableAPI.Expose public static void registerDataManager(ChunkDataManager manager) throws IllegalStateException, IllegalArgumentException { ChunkDataRegistryImpl.registerDataManager(manager); @@ -42,6 +48,7 @@ public class ChunkDataRegistry { * * @throws IllegalStateException If the disable stage is over. */ + @StableAPI.Expose public static void disableDataManager(String domain, String id) throws IllegalStateException { ChunkDataRegistryImpl.disableDataManager(domain, id); } @@ -50,6 +57,7 @@ public class ChunkDataRegistry { * Returns an unmodifiable set of all registered ChunkDataManagers. * The id of a manager is its domain and id separated by a colon. (domain:id) */ + @StableAPI.Expose public static Set getRegisteredManagers() { return ChunkDataRegistryImpl.getRegisteredManagers(); } diff --git a/src/main/java/com/falsepattern/chunk/api/package-info.java b/src/main/java/com/falsepattern/chunk/api/package-info.java index 1570077..b6f0d9d 100644 --- a/src/main/java/com/falsepattern/chunk/api/package-info.java +++ b/src/main/java/com/falsepattern/chunk/api/package-info.java @@ -12,5 +12,9 @@ /** * This package contains the classes that you will use to interact with the ChunkAPI library. + * + * @since 0.1.0 + * @author FalsePattern + * @version 0.1.0 */ package com.falsepattern.chunk.api; \ No newline at end of file