Add a bunch of comments

Author: Robotgiggle

Common/src/main/java/at/petrak/hexcasting/common/items/storage/ItemScroll.java

@@ -37,11 +37,11 @@
 import static at.petrak.hexcasting.api.HexAPI.modLoc;
 
 /**
- * TAG_OP_ID and TAG_PATTERN: "Ancient Scroll of %s" (per-world pattern preloaded)
+ * ACTION and PATTERN components: "Ancient Scroll of %s" (per-world pattern preloaded)
  * <br>
- * TAG_OP_ID: "Ancient Scroll of %s" (per-world pattern loaded on inv tick)
+ * Only ACTION component: "Ancient Scroll of %s" (per-world pattern loaded on inv tick)
  * <br>
- * TAG_PATTERN: "Scroll" (custom)
+ * Only PATTERN component: "Scroll" (custom)
  * <br>
  * (none): "Empty Scroll"
  */
@@ -147,11 +147,11 @@ public Component getName(ItemStack pStack) {
 
     @Override
     public void inventoryTick(ItemStack pStack, Level pLevel, Entity pEntity, int pSlotId, boolean pIsSelected) {
-        // the needs_purchase tag is used so you can't see the pattern on scrolls sold by a wandering trader
-        // once you put the scroll into your inventory, this removes the tag to reveal the pattern
+        // the NEEDS_PURCHASE component is used so you can't see the pattern on scrolls sold by a wandering trader
+        // once you put the scroll into your inventory, this removes the component to reveal the pattern
         if(pStack.has(HexDataComponents.NEEDS_PURCHASE.get()))
             pStack.remove(HexDataComponents.NEEDS_PURCHASE.get());
-        // if op_id is set but there's no stored pattern, attempt to load the pattern on inv tick
+        // if ACTION is present but PATTERN is not present, attempt to load the pattern on inv tick
         if (pStack.has(HexDataComponents.ACTION.get()) && !pStack.has(HexDataComponents.PATTERN.get()) && pEntity.getServer() != null) {
             var action = pStack.get(HexDataComponents.ACTION.get());
             if (!IXplatAbstractions.INSTANCE.getActionRegistry().containsKey(action)) {
@@ -161,7 +161,7 @@ public void inventoryTick(ItemStack pStack, Level pLevel, Entity pEntity, int pS
             }
             var pat = PatternRegistryManifest.getCanonicalStrokesPerWorld(action, pEntity.getServer().overworld());
             if (pat == null) {
-                // if pat is null, the per-world order hasn't been registered; remove the op_id and warn the player
+                // if pat is null, the per-world order hasn't been registered; remove the ACTION component and warn the player
                 pStack.set(HexDataComponents.RECALC_WARNING.get(), action);
                 pStack.remove(HexDataComponents.ACTION.get());
                 return;

Common/src/main/java/at/petrak/hexcasting/common/items/storage/ItemSpellbook.java

@@ -90,18 +90,22 @@ public void inventoryTick(ItemStack stack, Level level, Entity pEntity, int pSlo
         var savedNames = stack.get(HexDataComponents.SPELLBOOK_PAGE_NAMES.get());
 
         if(customName != null) {
+            // the stack has been given a custom name (ie via anvil)
             if(savedNames != null) {
                 if(!savedNames.containsKey(nameKey) || !savedNames.get(nameKey).equals(customName)) {
+                    // if this page doesn' have a name mapping, or it doesn't match, create/update the name mapping
                     var mutNames = new HashMap<>(savedNames);
                     mutNames.put(nameKey, customName);
                     stack.set(HexDataComponents.SPELLBOOK_PAGE_NAMES.get(), mutNames);
                 }
             } else {
                 var mutNames = new HashMap<String, Component>();
                 mutNames.put(nameKey, customName);
+                // if the savedNames map doesn't exist at all, create it and map the stack's current name to this page
                 stack.set(HexDataComponents.SPELLBOOK_PAGE_NAMES.get(), mutNames);
             }
         } else if(savedNames != null) {
+            // the stack does not have a custom name, or it has been removed
             var mutNames = new HashMap<>(savedNames);
             mutNames.remove(nameKey);
             if(mutNames.isEmpty()) {
@@ -151,10 +155,12 @@ public void writeDatum(ItemStack stack, Iota datum) {
         var pages = stack.get(HexDataComponents.SPELLBOOK_PAGES.get());
 
         if (pages != null) {
+            // if the pages map exists, modify it accordingly
             var pagesMut = new HashMap<>(pages);
 
             if (datum == null) {
                 pagesMut.remove(key);
+                // erasing the current page (needs to unseal as well, if possible)
                 var seals = stack.get(HexDataComponents.SPELLBOOK_PAGE_SEALS.get());
                 if(seals != null) {
                     var sealsMut = new HashMap<>(seals);
@@ -169,6 +175,7 @@ public void writeDatum(ItemStack stack, Iota datum) {
                 }
             } else {
                 pagesMut.put(key, datum);
+                // updating the current page
             }
 
             if (pagesMut.isEmpty()) {
@@ -179,8 +186,11 @@ public void writeDatum(ItemStack stack, Iota datum) {
         } else if (datum != null) {
             var map = new HashMap<String, Iota>();
             map.put(key, datum);
+            // if the pages map doesn't exist and you're trying to update a page, create the map first
             stack.set(HexDataComponents.SPELLBOOK_PAGES.get(), map);
         } else {
+            // if the pages map doesn't exist and you're trying to erase a page, check for a seal to remove
+            // this can happen if somebody seals an empty book for some reason
             var seals = stack.get(HexDataComponents.SPELLBOOK_PAGE_SEALS.get());
             if(seals != null) {
                 var sealsMut = new HashMap<>(seals);

Common/src/main/java/at/petrak/hexcasting/common/lib/HexDataComponents.java

@@ -27,6 +27,8 @@ public static void register() {
         REGISTER.registerAll();
     }
 
+    // ==== SCROLLS ====
+
     public static final Supplier<DataComponentType<HexPattern>> PATTERN = REGISTER.register("pattern", () ->
             DataComponentType.<HexPattern>builder()
                     .persistent(HexPattern.CODEC)
@@ -46,38 +48,48 @@ public static void register() {
             DataComponentType.<Unit>builder()
                     .networkSynchronized(StreamCodec.unit(Unit.INSTANCE))
                     .build());
-    /**
-     * If this datacomponent is set on the item, we ignore the rest of the item and render this as if it were of the
-     * {@link at.petrak.hexcasting.api.casting.iota.IotaType IotaType} given by the resource location.
-     * <p>
-     * This is not useful to the player at all.
-     */
-    public static final Supplier<DataComponentType<Optional<IotaType<?>>>> VISUAL_OVERRIDE = REGISTER.register("visual_override", () ->
-            DataComponentType.<Optional<IotaType<?>>>builder()
-                    .networkSynchronized(ByteBufCodecs.optional(ByteBufCodecs.registry(HexRegistries.IOTA_TYPE)))
-                    .build());
+
+    // ==== ANYTHING WITH TEXTURE VARIANTS ====
+
     public static final Supplier<DataComponentType<Integer>> ITEM_VARIANT = REGISTER.register("variant", () ->
             DataComponentType.<Integer>builder()
                     .persistent(Codec.intRange(0, Integer.MAX_VALUE))
                     .networkSynchronized(ByteBufCodecs.VAR_INT)
                     .build());
+
+    // ==== IOTA HOLDERS ====
+
     public static final Supplier<DataComponentType<Unit>> SEALED_IOTA_HOLDER = REGISTER.register("sealed", () ->
             DataComponentType.<Unit>builder()
                     .persistent(Codec.unit(Unit.INSTANCE))
                     .networkSynchronized(StreamCodec.unit(Unit.INSTANCE))
                     .build());
-    // TODO port: Data components must implement equals and hashCode. Keep in mind they must also be immutable
+    // TODO port: Data components are supposed to be immutable - is EntityIota.isPlayer a problem here?
     public static final Supplier<DataComponentType<Iota>> IOTA_HOLDER_IOTA = REGISTER.register("iota", () ->
             DataComponentType.<Iota>builder()
                     .persistent(IotaType.TYPED_CODEC)
                     .networkSynchronized(IotaType.TYPED_STREAM_CODEC)
                     .build());
+    /**
+     * If this datacomponent is set on the item, we ignore the rest of the item and render this as if it were of the
+     * {@link at.petrak.hexcasting.api.casting.iota.IotaType IotaType} given by the resource location.
+     * <p>
+     * This is not useful to the player at all.
+     */
+    public static final Supplier<DataComponentType<Optional<IotaType<?>>>> VISUAL_OVERRIDE = REGISTER.register("visual_override", () ->
+            DataComponentType.<Optional<IotaType<?>>>builder()
+                    .networkSynchronized(ByteBufCodecs.optional(ByteBufCodecs.registry(HexRegistries.IOTA_TYPE)))
+                    .build());
+
+    // ==== CASTING ITEMS ====
 
     public static final Supplier<DataComponentType<HexHolder>> HEX_HOLDER = REGISTER.register("hex_holder", () ->
             DataComponentType.<HexHolder>builder()
                     .persistent(HexHolder.CODEC)
                     .networkSynchronized(HexHolder.STREAM_CODEC)
                     .build());
+
+    // ==== CASTING ITEMS & PHIALS ====
 
     public static final Supplier<DataComponentType<Long>> MEDIA = REGISTER.register("media", () ->
             DataComponentType.<Long>builder()
@@ -89,18 +101,25 @@ public static void register() {
                     .persistent(Codec.LONG)
                     .networkSynchronized(ByteBufCodecs.VAR_LONG)
                     .build());
+
+    // ==== ANCIENT CYPHERS ====
+
     public static final Supplier<DataComponentType<String>> HEX_NAME = REGISTER.register("hex_name", () ->
             DataComponentType.<String>builder()
                     .persistent(Codec.STRING)
                     .networkSynchronized(ByteBufCodecs.STRING_UTF8)
                     .build());
 
+    // ==== ABACUS ====
+
     public static final Supplier<DataComponentType<Double>> ABACUS_VALUE = REGISTER.register("abacus_value", () ->
             DataComponentType.<Double>builder()
                     .persistent(Codec.DOUBLE)
                     .networkSynchronized(ByteBufCodecs.DOUBLE)
                     .build());
 
+    // ==== SPELLBOOKS ====
+
     public static final Supplier<DataComponentType<Integer>> SELECTED_SPELLBOOK_PAGE = REGISTER.register("page_idx", () ->
             DataComponentType.<Integer>builder()
                     .persistent(Codec.INT)
@@ -137,6 +156,8 @@ public static void register() {
                     ))
                     .build());
 
+    // ==== MEDIA CUBE ====
+
     public static final Supplier<DataComponentType<List<Long>>> MEDIA_EXTRACTIONS = REGISTER.register("media_extractions", () ->
             DataComponentType.<List<Long>>builder()
                     .persistent(Codec.LONG.listOf())