From c16a70a0f43a96b6dd2afa86b4fe35f501530aa2 Mon Sep 17 00:00:00 2001 From: shedaniel Date: Fri, 28 May 2021 21:28:06 +0800 Subject: More docs, LiveDisplayGenerator -> DynamicDisplayGenerator --- .../client/registry/category/CategoryRegistry.java | 9 ++++ .../client/registry/display/DisplayRegistry.java | 40 ++++++++++++---- .../registry/display/DynamicDisplayGenerator.java | 54 ++++++++++++++++++++++ .../registry/display/LiveDisplayGenerator.java | 45 ------------------ .../api/client/registry/entry/EntryRegistry.java | 18 ++++++++ .../client/registry/transfer/TransferHandler.java | 1 - .../common/display/DisplaySerializerRegistry.java | 8 +++- .../entry/comparison/FluidComparatorRegistry.java | 5 ++ .../entry/comparison/ItemComparatorRegistry.java | 5 ++ .../rei/api/common/entry/type/EntryDefinition.java | 1 + .../rei/api/common/entry/type/EntryTypeBridge.java | 8 +++- .../api/common/entry/type/EntryTypeRegistry.java | 29 +++++++++++- 12 files changed, 163 insertions(+), 60 deletions(-) create mode 100644 api/src/main/java/me/shedaniel/rei/api/client/registry/display/DynamicDisplayGenerator.java delete mode 100644 api/src/main/java/me/shedaniel/rei/api/client/registry/display/LiveDisplayGenerator.java (limited to 'api/src/main') diff --git a/api/src/main/java/me/shedaniel/rei/api/client/registry/category/CategoryRegistry.java b/api/src/main/java/me/shedaniel/rei/api/client/registry/category/CategoryRegistry.java index 44f185f4c..6061e28b0 100644 --- a/api/src/main/java/me/shedaniel/rei/api/client/registry/category/CategoryRegistry.java +++ b/api/src/main/java/me/shedaniel/rei/api/client/registry/category/CategoryRegistry.java @@ -33,6 +33,8 @@ import me.shedaniel.rei.api.common.plugins.PluginManager; import me.shedaniel.rei.api.common.registry.Reloadable; import me.shedaniel.rei.api.common.util.CollectionUtils; import me.shedaniel.rei.api.common.util.Identifiable; +import net.fabricmc.api.EnvType; +import net.fabricmc.api.Environment; import net.minecraft.resources.ResourceLocation; import java.util.List; @@ -41,6 +43,13 @@ import java.util.function.Consumer; import java.util.stream.Stream; import java.util.stream.StreamSupport; +/** + * Registry for registering new categories for displays. + * Relies on {@link CategoryIdentifier}, and is reset per plugin reload. + * + * @see REIClientPlugin#registerCategories(CategoryRegistry) + */ +@Environment(EnvType.CLIENT) public interface CategoryRegistry extends Reloadable, Iterable> { /** * @return the instance of {@link CategoryRegistry} diff --git a/api/src/main/java/me/shedaniel/rei/api/client/registry/display/DisplayRegistry.java b/api/src/main/java/me/shedaniel/rei/api/client/registry/display/DisplayRegistry.java index 07412c76c..14204c920 100644 --- a/api/src/main/java/me/shedaniel/rei/api/client/registry/display/DisplayRegistry.java +++ b/api/src/main/java/me/shedaniel/rei/api/client/registry/display/DisplayRegistry.java @@ -32,6 +32,7 @@ import me.shedaniel.rei.api.common.plugins.PluginManager; import me.shedaniel.rei.api.common.registry.RecipeManagerContext; import net.fabricmc.api.EnvType; import net.fabricmc.api.Environment; +import net.minecraft.world.item.crafting.Recipe; import java.util.Collection; import java.util.Collections; @@ -40,6 +41,27 @@ import java.util.Map; import java.util.function.Function; import java.util.function.Predicate; +/** + * Registry for registering displays for categories, this is called right after + * {@link me.shedaniel.rei.api.client.registry.category.CategoryRegistry}. + * + *

Each display should have a category associated with it that's registered, + * For any dynamic displays, you may want to look at {@link DynamicDisplayGenerator}. + * + *

Plugins may also determine the visibility of the displays dynamically via + * {@link DisplayVisibilityPredicate}, these predicates are preferred comparing to + * removing the displays from the registry. + * + *

Displays filler may be used for automatically registering displays from {@link Recipe}, + * these are filled after client recipe manager sync, and are invoked with one cycle. + * Additionally, display filters allow other mods to easily register additional displays + * for your mod. + * + * @see Display + * @see DynamicDisplayGenerator + * @see DisplayVisibilityPredicate + * @see REIClientPlugin#registerDisplays(DisplayRegistry) + */ @Environment(EnvType.CLIENT) public interface DisplayRegistry extends RecipeManagerContext { /** @@ -85,7 +107,7 @@ public interface DisplayRegistry extends RecipeManagerContext { * * @param generator the generator to register */ - void registerGlobalDisplayGenerator(LiveDisplayGenerator generator); + void registerGlobalDisplayGenerator(DynamicDisplayGenerator generator); /** * Registers a display generator @@ -93,28 +115,28 @@ public interface DisplayRegistry extends RecipeManagerContext { * @param categoryId the identifier of the category * @param generator the generator to register */ - void registerDisplayGenerator(CategoryIdentifier categoryId, LiveDisplayGenerator generator); + void registerDisplayGenerator(CategoryIdentifier categoryId, DynamicDisplayGenerator generator); /** * Returns an unmodifiable map of display generators * * @return an unmodifiable map of display generators */ - Map, List>> getCategoryDisplayGenerators(); + Map, List>> getCategoryDisplayGenerators(); /** * Returns an unmodifiable list of category-less display generators * * @return an unmodifiable list of category-less display generators */ - List> getGlobalDisplayGenerators(); + List> getGlobalDisplayGenerators(); /** * Returns the list of display generators for a category * * @return the list of display generators */ - default List> getCategoryDisplayGenerators(CategoryIdentifier categoryId) { + default List> getCategoryDisplayGenerators(CategoryIdentifier categoryId) { return getCategoryDisplayGenerators().getOrDefault(categoryId, Collections.emptyList()); } @@ -153,8 +175,8 @@ public interface DisplayRegistry extends RecipeManagerContext { /** * Registers a display filler, to be filled during {@link #tryFillDisplay(Object)}. *

- * Vanilla {@link net.minecraft.world.item.crafting.Recipe} are by default filled, display filters - * can be used to automatically generate displaies for vanilla {@link net.minecraft.world.item.crafting.Recipe}. + * Vanilla {@link Recipe} are by default filled, display filters + * can be used to automatically generate displaies for vanilla {@link Recipe}. * * @param typeClass the type of {@code T} * @param filler the filler, taking a {@code T} and returning a {@code D} @@ -168,8 +190,8 @@ public interface DisplayRegistry extends RecipeManagerContext { /** * Registers a display filler, to be filled during {@link #tryFillDisplay(Object)}. *

- * Vanilla {@link net.minecraft.world.item.crafting.Recipe} are by default filled, display filters - * can be used to automatically generate displaies for vanilla {@link net.minecraft.world.item.crafting.Recipe}. + * Vanilla {@link Recipe} are by default filled, display filters + * can be used to automatically generate displaies for vanilla {@link Recipe}. * * @param typeClass the type of {@code T} * @param predicate the predicate of {@code T} diff --git a/api/src/main/java/me/shedaniel/rei/api/client/registry/display/DynamicDisplayGenerator.java b/api/src/main/java/me/shedaniel/rei/api/client/registry/display/DynamicDisplayGenerator.java new file mode 100644 index 000000000..9c088e5e5 --- /dev/null +++ b/api/src/main/java/me/shedaniel/rei/api/client/registry/display/DynamicDisplayGenerator.java @@ -0,0 +1,54 @@ +/* + * This file is licensed under the MIT License, part of Roughly Enough Items. + * Copyright (c) 2018, 2019, 2020, 2021 shedaniel + * + * Permission is hereby granted, free of charge, to any person obtaining a copy + * of this software and associated documentation files (the "Software"), to deal + * in the Software without restriction, including without limitation the rights + * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + * copies of the Software, and to permit persons to whom the Software is + * furnished to do so, subject to the following conditions: + * + * The above copyright notice and this permission notice shall be included in all + * copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE + * SOFTWARE. + */ + +package me.shedaniel.rei.api.client.registry.display; + +import me.shedaniel.rei.api.client.view.ViewSearchBuilder; +import me.shedaniel.rei.api.common.category.CategoryIdentifier; +import me.shedaniel.rei.api.common.display.Display; +import me.shedaniel.rei.api.common.entry.EntryStack; + +import java.util.List; +import java.util.Optional; + +/** + * Interface for generating dynamic displays at runtime. + * Invoked per display view search, so please keep this performant. + * + * @param the type of displays to generate + * @see DisplayRegistry#registerDisplayGenerator(CategoryIdentifier, DynamicDisplayGenerator) + * @see DisplayRegistry#registerGlobalDisplayGenerator(DynamicDisplayGenerator) + */ +public interface DynamicDisplayGenerator { + default Optional> getRecipeFor(EntryStack entry) { + return Optional.empty(); + } + + default Optional> getUsageFor(EntryStack entry) { + return Optional.empty(); + } + + default Optional> generate(ViewSearchBuilder builder) { + return Optional.empty(); + } +} diff --git a/api/src/main/java/me/shedaniel/rei/api/client/registry/display/LiveDisplayGenerator.java b/api/src/main/java/me/shedaniel/rei/api/client/registry/display/LiveDisplayGenerator.java deleted file mode 100644 index 04cfe3198..000000000 --- a/api/src/main/java/me/shedaniel/rei/api/client/registry/display/LiveDisplayGenerator.java +++ /dev/null @@ -1,45 +0,0 @@ -/* - * This file is licensed under the MIT License, part of Roughly Enough Items. - * Copyright (c) 2018, 2019, 2020, 2021 shedaniel - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in all - * copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - */ - -package me.shedaniel.rei.api.client.registry.display; - -import me.shedaniel.rei.api.client.view.ViewSearchBuilder; -import me.shedaniel.rei.api.common.display.Display; -import me.shedaniel.rei.api.common.entry.EntryStack; - -import java.util.List; -import java.util.Optional; - -public interface LiveDisplayGenerator { - default Optional> getRecipeFor(EntryStack entry) { - return Optional.empty(); - } - - default Optional> getUsageFor(EntryStack entry) { - return Optional.empty(); - } - - default Optional> generate(ViewSearchBuilder builder) { - return Optional.empty(); - } -} diff --git a/api/src/main/java/me/shedaniel/rei/api/client/registry/entry/EntryRegistry.java b/api/src/main/java/me/shedaniel/rei/api/client/registry/entry/EntryRegistry.java index d51449d65..6c439a43c 100644 --- a/api/src/main/java/me/shedaniel/rei/api/client/registry/entry/EntryRegistry.java +++ b/api/src/main/java/me/shedaniel/rei/api/client/registry/entry/EntryRegistry.java @@ -29,6 +29,9 @@ import me.shedaniel.rei.api.common.plugins.PluginManager; import me.shedaniel.rei.api.common.registry.Reloadable; import net.fabricmc.api.EnvType; import net.fabricmc.api.Environment; +import net.minecraft.core.NonNullList; +import net.minecraft.core.Registry; +import net.minecraft.world.item.CreativeModeTab; import net.minecraft.world.item.Item; import net.minecraft.world.item.ItemStack; import org.jetbrains.annotations.Nullable; @@ -40,6 +43,21 @@ import java.util.function.LongPredicate; import java.util.function.Predicate; import java.util.stream.Stream; +/** + * Registry for registering {@link EntryStack} for display on the overlay entry list. + * + *

The default REI plugin iterates both {@link Registry#ITEM} and {@link Registry#FLUID} + * to register new entries. Other plugins may override this default behaviour, altering + * the entry list. + * + *

REI plugins should only add entries during reload, modifications outside the + * reload phase may not be reflected immediately. + * + *

While this registry can be used for registering variants of stacks, there may be + * native alternatives such as {@link Item#fillItemCategory(CreativeModeTab, NonNullList)}. + * + * @see REIClientPlugin#registerEntries(EntryRegistry) + */ @Environment(EnvType.CLIENT) public interface EntryRegistry extends Reloadable { /** diff --git a/api/src/main/java/me/shedaniel/rei/api/client/registry/transfer/TransferHandler.java b/api/src/main/java/me/shedaniel/rei/api/client/registry/transfer/TransferHandler.java index ef0559364..3c3ea6462 100644 --- a/api/src/main/java/me/shedaniel/rei/api/client/registry/transfer/TransferHandler.java +++ b/api/src/main/java/me/shedaniel/rei/api/client/registry/transfer/TransferHandler.java @@ -301,5 +301,4 @@ public interface TransferHandler extends Comparable { return recipeDisplaySupplier.get(); } } - } diff --git a/api/src/main/java/me/shedaniel/rei/api/common/display/DisplaySerializerRegistry.java b/api/src/main/java/me/shedaniel/rei/api/common/display/DisplaySerializerRegistry.java index e1d62beb7..a3cf6cc08 100644 --- a/api/src/main/java/me/shedaniel/rei/api/common/display/DisplaySerializerRegistry.java +++ b/api/src/main/java/me/shedaniel/rei/api/common/display/DisplaySerializerRegistry.java @@ -31,8 +31,12 @@ import me.shedaniel.rei.api.common.transfer.info.MenuSerializationContext; import net.minecraft.nbt.CompoundTag; /** - * The display serializer used for display transfers. - * This is mostly a fallback system for {@link me.shedaniel.rei.api.common.transfer.info.MenuInfo#save(MenuSerializationContext, Display)}. + * The display serializer used for display serialization, useful for persistent displays across reloads, + * and server-client communication. + * + *

This is mostly a fallback system for {@link me.shedaniel.rei.api.common.transfer.info.MenuInfo#save(MenuSerializationContext, Display)}. + * + * @see REIPlugin#registerDisplaySerializer(DisplaySerializerRegistry) */ public interface DisplaySerializerRegistry extends Reloadable> { static DisplaySerializerRegistry getInstance() { diff --git a/api/src/main/java/me/shedaniel/rei/api/common/entry/comparison/FluidComparatorRegistry.java b/api/src/main/java/me/shedaniel/rei/api/common/entry/comparison/FluidComparatorRegistry.java index f8489ef2e..b49a051d1 100644 --- a/api/src/main/java/me/shedaniel/rei/api/common/entry/comparison/FluidComparatorRegistry.java +++ b/api/src/main/java/me/shedaniel/rei/api/common/entry/comparison/FluidComparatorRegistry.java @@ -27,6 +27,11 @@ import me.shedaniel.architectury.fluid.FluidStack; import me.shedaniel.rei.api.common.plugins.PluginManager; import net.minecraft.world.level.material.Fluid; +/** + * {@inheritDoc} + * + * @see me.shedaniel.rei.api.common.plugins.REIPlugin#registerFluidComparators(FluidComparatorRegistry) + */ public interface FluidComparatorRegistry extends EntryComparatorRegistry { /** * @return the instance of {@link FluidComparatorRegistry} diff --git a/api/src/main/java/me/shedaniel/rei/api/common/entry/comparison/ItemComparatorRegistry.java b/api/src/main/java/me/shedaniel/rei/api/common/entry/comparison/ItemComparatorRegistry.java index 299eab648..fca219167 100644 --- a/api/src/main/java/me/shedaniel/rei/api/common/entry/comparison/ItemComparatorRegistry.java +++ b/api/src/main/java/me/shedaniel/rei/api/common/entry/comparison/ItemComparatorRegistry.java @@ -27,6 +27,11 @@ import me.shedaniel.rei.api.common.plugins.PluginManager; import net.minecraft.world.item.Item; import net.minecraft.world.item.ItemStack; +/** + * {@inheritDoc} + * + * @see me.shedaniel.rei.api.common.plugins.REIPlugin#registerItemComparators(ItemComparatorRegistry) + */ public interface ItemComparatorRegistry extends EntryComparatorRegistry { /** * @return the instance of {@link ItemComparatorRegistry} diff --git a/api/src/main/java/me/shedaniel/rei/api/common/entry/type/EntryDefinition.java b/api/src/main/java/me/shedaniel/rei/api/common/entry/type/EntryDefinition.java index 880f2ed1c..555149b8e 100644 --- a/api/src/main/java/me/shedaniel/rei/api/common/entry/type/EntryDefinition.java +++ b/api/src/main/java/me/shedaniel/rei/api/common/entry/type/EntryDefinition.java @@ -41,6 +41,7 @@ import java.util.Collection; * A definition of an {@link EntryType}, an interface to provide information from an object type. * * @param the type of entry + * @see EntryTypeRegistry */ public interface EntryDefinition { Class getValueType(); diff --git a/api/src/main/java/me/shedaniel/rei/api/common/entry/type/EntryTypeBridge.java b/api/src/main/java/me/shedaniel/rei/api/common/entry/type/EntryTypeBridge.java index ae7674c23..7f81fc181 100644 --- a/api/src/main/java/me/shedaniel/rei/api/common/entry/type/EntryTypeBridge.java +++ b/api/src/main/java/me/shedaniel/rei/api/common/entry/type/EntryTypeBridge.java @@ -28,8 +28,14 @@ import net.minecraft.world.InteractionResultHolder; import java.util.stream.Stream; +/** + * A bridge of two different entry types, for comparison and equality checks. + * + * @param the original entry type + * @param the destination entry type + * @see EntryTypeRegistry#registerBridge(EntryType, EntryType, EntryTypeBridge) + */ @FunctionalInterface public interface EntryTypeBridge { - InteractionResultHolder>> bridge(EntryStack object); } diff --git a/api/src/main/java/me/shedaniel/rei/api/common/entry/type/EntryTypeRegistry.java b/api/src/main/java/me/shedaniel/rei/api/common/entry/type/EntryTypeRegistry.java index 9b62c3d5f..c376a2b88 100644 --- a/api/src/main/java/me/shedaniel/rei/api/common/entry/type/EntryTypeRegistry.java +++ b/api/src/main/java/me/shedaniel/rei/api/common/entry/type/EntryTypeRegistry.java @@ -31,6 +31,21 @@ import org.jetbrains.annotations.Nullable; import java.util.Set; +/** + * Registry for registering alternative entry types. + * + *

{@link EntryType} must be declared statically, deferring to the actual + * definition by the identifier of the type. During reload, plugins should + * register {@link EntryDefinition} for their deferred {@link EntryType}, + * these definitions are dynamic. + * + *

{@link EntryTypeBridge} may be used to convert and compare between + * different types + * + * @see EntryDefinition + * @see #registerBridge(EntryType, EntryType, EntryTypeBridge) + * @see REIPlugin#registerEntryTypes(EntryTypeRegistry) + */ public interface EntryTypeRegistry extends Reloadable> { static EntryTypeRegistry getInstance() { return PluginManager.getInstance().get(EntryTypeRegistry.class); @@ -76,16 +91,26 @@ public interface EntryTypeRegistry extends Reloadable> { @Nullable EntryDefinition get(ResourceLocation id); + /** + * Returns the set of types in their identifier form. + * + * @return the set of types + */ Set keySet(); + /** + * Returns the set of entry definitions. + * + * @return the set of entry definitions + */ Set> values(); /** * Register a bridge between two entry types, for example, item to fluid, this is used, to - * approximately match two entry stacks,. + * approximately match two entry stacks. *

* For bridging two entry types, only 1 one way bridge is required, two way bridges are discouraged - * for performance issues. + * for performance issues and possible recursion. * * @param original the original entry type * @param destination the destination entry type -- cgit