From bb9dcef4b53d201cf4bcac3bf88d2042a1ce226c Mon Sep 17 00:00:00 2001 From: SHsuperCM Date: Sat, 5 Mar 2022 18:44:04 +0200 Subject: Documentation (29/44, 0/35) --- .../citresewn/defaults/cit/types/TypeItem.java | 7 ++- .../shcm/shsupercm/fabric/citresewn/cit/CIT.java | 30 ++++++++++++ .../shsupercm/fabric/citresewn/cit/CITCache.java | 51 ++++++++++++++++++-- .../fabric/citresewn/cit/CITCondition.java | 36 +++++++++++++++ .../shsupercm/fabric/citresewn/cit/CITContext.java | 26 ++++++++++- .../fabric/citresewn/cit/CITRegistry.java | 54 +++++++++++++++++++++- .../shsupercm/fabric/citresewn/cit/CITType.java | 23 +++++++++ 7 files changed, 218 insertions(+), 9 deletions(-) diff --git a/defaults/src/main/java/shcm/shsupercm/fabric/citresewn/defaults/cit/types/TypeItem.java b/defaults/src/main/java/shcm/shsupercm/fabric/citresewn/defaults/cit/types/TypeItem.java index 21e1ab0..aa4df72 100644 --- a/defaults/src/main/java/shcm/shsupercm/fabric/citresewn/defaults/cit/types/TypeItem.java +++ b/defaults/src/main/java/shcm/shsupercm/fabric/citresewn/defaults/cit/types/TypeItem.java @@ -40,8 +40,11 @@ import java.util.*; import java.util.stream.Collectors; /** - * Do not go through this class, it looks awful because it was ported from a "proof of concept".
- * The whole type will be rewritten at some point. + * ///// PORTED FROM BETA \\\\\ + * This shit was ported from the + * beta and will be rewritten at + * some point! + * \\\\\ ///// */ public class TypeItem extends CITType { @Entrypoint(CITTypeContainer.ENTRYPOINT) diff --git a/src/main/java/shcm/shsupercm/fabric/citresewn/cit/CIT.java b/src/main/java/shcm/shsupercm/fabric/citresewn/cit/CIT.java index 3bc708f..7c7ba5b 100644 --- a/src/main/java/shcm/shsupercm/fabric/citresewn/cit/CIT.java +++ b/src/main/java/shcm/shsupercm/fabric/citresewn/cit/CIT.java @@ -2,11 +2,34 @@ package shcm.shsupercm.fabric.citresewn.cit; import net.minecraft.util.Identifier; +/** + * Runtime representation of a CIT, holding its type and conditions as well as additional metadata. + */ public class CIT { + /** + * The full location of this CIT in its resourcepack. + */ public final Identifier propertiesIdentifier; + + /** + * Name of the resourcepack that contains this CIT. + */ public final String packName; + + /** + * The CIT's type. + * @see CITType + */ public final T type; + + /** + * Conditions that must be met for this CIT to work. + */ public final CITCondition[] conditions; + + /** + * The weight of this CIT to be used when resolving multiple CIT matching conflicts. + */ public final int weight; public CIT(Identifier propertiesIdentifier, String packName, T type, CITCondition[] conditions, int weight) { @@ -17,6 +40,13 @@ public class CIT { this.weight = weight; } + /** + * Tests the given context against all of this CIT's conditions. + * + * @see #conditions + * @param context context to check + * @return true if none of this CIT's {@link #conditions} tested false + */ public boolean test(CITContext context) { try { for (CITCondition condition : conditions) diff --git a/src/main/java/shcm/shsupercm/fabric/citresewn/cit/CITCache.java b/src/main/java/shcm/shsupercm/fabric/citresewn/cit/CITCache.java index 5fc6f5a..31ccf04 100644 --- a/src/main/java/shcm/shsupercm/fabric/citresewn/cit/CITCache.java +++ b/src/main/java/shcm/shsupercm/fabric/citresewn/cit/CITCache.java @@ -1,5 +1,6 @@ package shcm.shsupercm.fabric.citresewn.cit; +import net.minecraft.item.ItemStack; import shcm.shsupercm.fabric.citresewn.config.CITResewnConfig; import java.lang.ref.WeakReference; @@ -7,17 +8,42 @@ import java.util.ArrayList; import java.util.List; import java.util.function.Function; +/** + * Runtime cache for a CIT type to be stored in type implementation specific locations. (usually ducked onto {@link ItemStack}s) + * @see Single + * @see MultiList + */ public abstract class CITCache { + /** + * The last time in epoch milliseconds that this cache invalidated its stored CIT. + */ public long lastCachedStamp = 0; + /** + * Common implementation of a single CIT per holder({@link ItemStack}) caching. + */ public static class Single extends CITCache { - public WeakReference> cit = null; - public final Function> realtime; + /** + * A reload-safe reference to the CIT that was last selected for this holder. + */ + protected WeakReference> cit = null; + + /** + * Real time Context -> CIT supplier for this cache for invalidated holders. + */ + protected final Function> realtime; public Single(Function> realtime) { this.realtime = realtime; } + /** + * Retrieves the CIT reference associated with this cache and invalidates it every config-defined interval. + * + * @see CITResewnConfig#cache_ms + * @param context context to check + * @return reference to the CIT or reference to null if no CIT applied + */ public WeakReference> get(CITContext context) { if (this.cit == null || System.currentTimeMillis() - this.lastCachedStamp >= CITResewnConfig.INSTANCE.cache_ms) { this.cit = new WeakReference<>(this.realtime.apply(context)); @@ -28,14 +54,31 @@ public abstract class CITCache { } } + /** + * Common implementation of multiple CITs per holder({@link ItemStack}) caching. + */ public static class MultiList extends CITCache { - public List>> cit = null; - public final Function>> realtime; + /** + * List of reload-safe references to CITs that were last selected for this holder. + */ + protected List>> cit = null; + + /** + * Real time Context -> CIT list supplier for this cache for invalidated holders. + */ + protected final Function>> realtime; public MultiList(Function>> realtime) { this.realtime = realtime; } + /** + * Retrieves the CIT references associated with this cache and invalidates them every config-defined interval. + * + * @see CITResewnConfig#cache_ms + * @param context context to check + * @return list of references to CITs or empty list no CIT applied + */ public List>> get(CITContext context) { if (this.cit == null || System.currentTimeMillis() - this.lastCachedStamp >= CITResewnConfig.INSTANCE.cache_ms) { this.cit = new ArrayList<>(); diff --git a/src/main/java/shcm/shsupercm/fabric/citresewn/cit/CITCondition.java b/src/main/java/shcm/shsupercm/fabric/citresewn/cit/CITCondition.java index fd00ac6..cd4cb9d 100644 --- a/src/main/java/shcm/shsupercm/fabric/citresewn/cit/CITCondition.java +++ b/src/main/java/shcm/shsupercm/fabric/citresewn/cit/CITCondition.java @@ -1,6 +1,8 @@ package shcm.shsupercm.fabric.citresewn.cit; import shcm.shsupercm.fabric.citresewn.CITResewn; +import shcm.shsupercm.fabric.citresewn.api.CITConditionContainer; +import shcm.shsupercm.fabric.citresewn.config.CITResewnConfig; import shcm.shsupercm.fabric.citresewn.ex.CITParsingException; import shcm.shsupercm.fabric.citresewn.pack.format.PropertyGroup; import shcm.shsupercm.fabric.citresewn.pack.format.PropertyValue; @@ -8,19 +10,53 @@ import shcm.shsupercm.fabric.citresewn.pack.format.PropertyValue; import java.util.Collections; import java.util.Set; +/** + * Instanced parent for CIT Types that are applied to items when conditions pass.
+ * Common condition types are available under {@link shcm.shsupercm.fabric.citresewn.cit.builtin.conditions}. + * @see CITConditionContainer + * @see CIT + */ public abstract class CITCondition { + /** + * Parses the given property value into the condition. + * @param value value to read + * @param properties the group containing value + * @throws CITParsingException if errored while parsing the condition + */ public abstract void load(PropertyValue value, PropertyGroup properties) throws CITParsingException; + /** + * @return a set of classes of conditions that have integration with this condition + */ public Set> siblingConditions() { return Collections.emptySet(); } + /** + * Modifies the given sibling if present in the CIT and declared in {@link #siblingConditions()}. + * @param sibling sibling to modify or be modified by + * @return the sibling or null to remove it from the CIT. + */ public T modifySibling(T sibling) { return sibling; } + /** + * Tests the given context against this condition. + * @param context context to check + * @return true if the given context passes + */ public abstract boolean test(CITContext context); + /** + * Logs a warning with the given value's descriptor if enabled in config. + * + * @see CITResewn#logWarnLoading(String) + * @see CITResewnConfig#mute_warns + * @param message warning message + * @param value value associated with the warning + * @param properties property group associated with the warning + */ protected void warn(String message, PropertyValue value, PropertyGroup properties) { CITResewn.logWarnLoading("Warning: " + properties.messageWithDescriptorOf(message, value.position())); } diff --git a/src/main/java/shcm/shsupercm/fabric/citresewn/cit/CITContext.java b/src/main/java/shcm/shsupercm/fabric/citresewn/cit/CITContext.java index c5f1922..cfc10f8 100644 --- a/src/main/java/shcm/shsupercm/fabric/citresewn/cit/CITContext.java +++ b/src/main/java/shcm/shsupercm/fabric/citresewn/cit/CITContext.java @@ -11,23 +11,47 @@ import net.minecraft.nbt.NbtElement; import net.minecraft.util.Identifier; import net.minecraft.world.World; +import javax.annotation.Nullable; import java.util.LinkedHashMap; import java.util.Map; import java.util.Objects; +/** + * Holds momentary information to be used for CITs' condition matching and type effects. + */ public class CITContext { + /** + * The main item stack to check for the CIT. + */ public final ItemStack stack; + + /** + * The item's containing world(defaults to {@link MinecraftClient#world} if null) + */ public final World world; + + /** + * The item's associated living entity if present. (null if not relevant) + */ + @Nullable public final LivingEntity entity; + /** + * Cached enchantment map from {@link #stack}. + * @see #enchantments() + */ private Map enchantments = null; - public CITContext(ItemStack stack, World world, LivingEntity entity) { + public CITContext(ItemStack stack, @Nullable World world, @Nullable LivingEntity entity) { this.stack = stack; this.world = world == null ? MinecraftClient.getInstance().world : world; this.entity = entity; } + /** + * @see #enchantments + * @return a map of this context item's enchantments + */ public Map enchantments() { if (this.enchantments == null) { this.enchantments = new LinkedHashMap<>(); diff --git a/src/main/java/shcm/shsupercm/fabric/citresewn/cit/CITRegistry.java b/src/main/java/shcm/shsupercm/fabric/citresewn/cit/CITRegistry.java index d8454a0..bf7c2ca 100644 --- a/src/main/java/shcm/shsupercm/fabric/citresewn/cit/CITRegistry.java +++ b/src/main/java/shcm/shsupercm/fabric/citresewn/cit/CITRegistry.java @@ -7,6 +7,7 @@ import shcm.shsupercm.fabric.citresewn.api.CITTypeContainer; import shcm.shsupercm.fabric.citresewn.cit.builtin.conditions.ConstantCondition; import shcm.shsupercm.fabric.citresewn.ex.CITParsingException; import shcm.shsupercm.fabric.citresewn.ex.UnknownCITTypeException; +import shcm.shsupercm.fabric.citresewn.pack.PackParser; import shcm.shsupercm.fabric.citresewn.pack.format.PropertyGroup; import shcm.shsupercm.fabric.citresewn.pack.format.PropertyKey; import shcm.shsupercm.fabric.citresewn.pack.format.PropertyValue; @@ -16,13 +17,38 @@ import java.util.*; import static shcm.shsupercm.fabric.citresewn.CITResewn.info; import static shcm.shsupercm.fabric.citresewn.CITResewn.logWarnLoading; -public class CITRegistry { +/** + * Holds a static registry runtime for all types and conditions. + * @see PackParser + * @see CITTypeContainer + * @see CITConditionContainer + */ +public final class CITRegistry { private CITRegistry(){} + /** + * Currently registered CIT types. + */ public static final Map> TYPES = new HashMap<>(); + /** + * Currently registered condition types. + */ public static final Map> CONDITIONS = new HashMap<>(); + /** + * Fast id lookup map for types. + * @see #idOfType(Class) + */ private static final Map, Identifier> TYPE_TO_ID = new IdentityHashMap<>(); + /** + * Fast id lookup map for conditions. + * @see #idOfCondition(Class) + */ private static final Map, PropertyKey> CONDITION_TO_ID = new IdentityHashMap<>(); + /** + * Loads all available CIT and condition types to registry. (internal use only) + * @see CITTypeContainer + * @see CITConditionContainer + */ public static void registerAll() { info("Registering CIT Conditions"); for (var entrypointContainer : FabricLoader.getInstance().getEntrypointContainers(CITConditionContainer.ENTRYPOINT, CITConditionContainer.class)) { @@ -53,6 +79,15 @@ public class CITRegistry { } } + /** + * Parses a condition from the given property.
+ * + * @param key the condition's key in the group + * @param value the condition's value + * @param properties the containing property group + * @return the parsed condition or an always-failing {@link ConstantCondition} if unrecognized + * @throws CITParsingException if errored while parsing hte condition + */ public static CITCondition parseCondition(PropertyKey key, PropertyValue value, PropertyGroup properties) throws CITParsingException { CITConditionContainer conditionContainer = CONDITIONS.get(key); if (conditionContainer == null) { @@ -65,7 +100,14 @@ public class CITRegistry { return condition; } - public static CITType parseType(PropertyGroup properties) throws CITParsingException { + /** + * Parses a CIT type from the given property group.
+ * If the group does not contain a "citresewn:type" property, defaults to "citresewn:item". + * @param properties group of properties to parse the CIT type from + * @return a new instance of the group's CIT type + * @throws UnknownCITTypeException if the given type is unrecognized in the registry + */ + public static CITType parseType(PropertyGroup properties) throws UnknownCITTypeException { Identifier type = new Identifier("citresewn", "item"); PropertyValue propertiesType = properties.getLastWithoutMetadata("citresewn", "type"); @@ -84,10 +126,18 @@ public class CITRegistry { return typeContainer.createType.get(); } + /** + * @see #TYPE_TO_ID + * @return the id of the given CIT type's class. + */ public static Identifier idOfType(Class clazz) { return TYPE_TO_ID.get(clazz); } + /** + * @see #CONDITION_TO_ID + * @return the first key of the given condition's class. + */ public static PropertyKey idOfCondition(Class clazz) { return CONDITION_TO_ID.get(clazz); } diff --git a/src/main/java/shcm/shsupercm/fabric/citresewn/cit/CITType.java b/src/main/java/shcm/shsupercm/fabric/citresewn/cit/CITType.java index b35d26c..65b3097 100644 --- a/src/main/java/shcm/shsupercm/fabric/citresewn/cit/CITType.java +++ b/src/main/java/shcm/shsupercm/fabric/citresewn/cit/CITType.java @@ -3,6 +3,7 @@ package shcm.shsupercm.fabric.citresewn.cit; import net.minecraft.resource.ResourceManager; import net.minecraft.util.Identifier; import shcm.shsupercm.fabric.citresewn.CITResewn; +import shcm.shsupercm.fabric.citresewn.api.CITTypeContainer; import shcm.shsupercm.fabric.citresewn.ex.CITParsingException; import shcm.shsupercm.fabric.citresewn.pack.format.PropertyGroup; import shcm.shsupercm.fabric.citresewn.pack.format.PropertyKey; @@ -10,9 +11,25 @@ import shcm.shsupercm.fabric.citresewn.pack.format.PropertyValue; import java.util.*; +/** + * Instanced parent for CIT Types that are applied to items when conditions pass. + * @see CITTypeContainer + * @see CIT + */ public abstract class CITType { + /** + * Used to determine which property keys are not conditions. + * @return a set of property keys used by this type + */ public abstract Set typeProperties(); + /** + * Loads the given property group into the type. + * @param conditions conditions that were parsed out of the property group + * @param properties group of properties to be read into this type + * @param resourceManager the CIT's containing resource manager + * @throws CITParsingException if errored while parsing the type + */ public abstract void load(List conditions, PropertyGroup properties, ResourceManager resourceManager) throws CITParsingException; protected void warn(String message, PropertyValue value, PropertyGroup properties) { @@ -20,6 +37,12 @@ public abstract class CITType { } /** + * ///// PORTED FROM BETA \\\\\ + * This shit was ported from the + * beta and will be rewritten at + * some point! + * \\\\\ ///// + * * Takes a defined path and resolves it to an identifier pointing to the resourcepack's path of the specified extension(returns null if no path can be resolved).
* If definedPath is null, will try to resolve a relative file with the same name as the rootIdentifier with the extension, otherwise:
* definedPath will be formatted to replace "\\" with "/" the extension will be appended if not there already.
-- cgit