From 50179d6edda37bd7ca2cfca82d6bb0014825b28b Mon Sep 17 00:00:00 2001 From: shedaniel Date: Fri, 17 Jun 2022 21:29:31 +0800 Subject: More docs --- .../api/client/registry/category/ButtonArea.java | 9 +- .../client/registry/category/CategoryRegistry.java | 121 ++++++++++++++++++--- .../extension/CategoryExtensionProvider.java | 8 ++ .../visibility/CategoryVisibilityPredicate.java | 16 ++- .../registry/display/DisplayCategoryView.java | 5 +- .../client/registry/display/DisplayRegistry.java | 3 +- .../registry/display/DynamicDisplayGenerator.java | 30 ++++- .../visibility/DisplayVisibilityPredicate.java | 16 ++- .../api/client/registry/entry/EntryRegistry.java | 25 +++-- .../rei/api/client/view/ViewSearchBuilder.java | 71 ++++++++++++ .../api/common/category/CategoryIdentifier.java | 48 ++++++++ .../rei/api/common/display/DisplayMerger.java | 21 ++++ .../rei/api/common/display/DisplaySerializer.java | 13 +++ .../common/display/DisplaySerializerRegistry.java | 22 ++++ .../common/display/SimpleDisplaySerializer.java | 27 +++++ .../api/common/display/SimpleGridMenuDisplay.java | 2 +- .../rei/api/common/display/basic/BasicDisplay.java | 106 ++++++++++++++++++ .../api/common/registry/RecipeManagerContext.java | 5 +- 18 files changed, 505 insertions(+), 43 deletions(-) (limited to 'api/src/main/java/me') diff --git a/api/src/main/java/me/shedaniel/rei/api/client/registry/category/ButtonArea.java b/api/src/main/java/me/shedaniel/rei/api/client/registry/category/ButtonArea.java index eceaaf23a..162f637b8 100644 --- a/api/src/main/java/me/shedaniel/rei/api/client/registry/category/ButtonArea.java +++ b/api/src/main/java/me/shedaniel/rei/api/client/registry/category/ButtonArea.java @@ -28,11 +28,18 @@ import net.fabricmc.api.EnvType; import net.fabricmc.api.Environment; /** - * The area for the + button. + * The provider of the area for the + button. */ @FunctionalInterface @Environment(EnvType.CLIENT) public interface ButtonArea { + /** + * Returns the default button area provider. + *

+ * The button is placed on the right side of the display, aligned to the bottom. + * + * @return the default button area provider + */ static ButtonArea defaultArea() { return bounds -> new Rectangle(bounds.getMaxX() + 2, bounds.getMaxY() - 16, 10, 10); } 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 16214baa8..6cd5a368f 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 @@ -110,23 +110,54 @@ public interface CategoryRegistry extends Reloadable, Iterable< } } + /** + * Returns the category configuration for the given category identifier. + * + * @param category the identifier of the category + * @param the type of the display + * @return the category configuration + * @throws NullPointerException if no {@link CategoryConfiguration} is found for the given identifier + */ CategoryConfiguration get(CategoryIdentifier category); + /** + * Returns the category configuration for the given category identifier. + * + * @param category the identifier of the category + * @param the type of the display + * @return the category configuration + */ Optional> tryGet(CategoryIdentifier category); + /** + * Configures the category configuration for the given category identifier. + *

+ * This method is deferred to when the category is registered. This means that configuration can be + * done anytime during the reload phase. + * + * @param category the identifier of the category + * @param action the action to perform + * @param the type of the display + */ void configure(CategoryIdentifier category, Consumer> action); + /** + * Returns the size of the category registry. + * + * @return the size of the category registry + */ int size(); /** - * Registers a category visibility predicate + * Registers a category visibility predicate. This is used to determine if a category is visible or not. * * @param predicate the predicate to be registered + * @see CategoryVisibilityPredicate */ void registerVisibilityPredicate(CategoryVisibilityPredicate predicate); /** - * Tests the category against all visibility predicates to determine whether it is visible + * Returns whether the category is visible against visibility predicates. * * @param category the category to test against * @return whether the category is visible @@ -134,7 +165,7 @@ public interface CategoryRegistry extends Reloadable, Iterable< boolean isCategoryVisible(DisplayCategory category); /** - * Tests the category against all visibility predicates to determine whether it is invisible + * Returns whether the category is invisible against visibility predicates. * * @param category the category to test against * @return whether the category is invisible @@ -150,43 +181,82 @@ public interface CategoryRegistry extends Reloadable, Iterable< */ List getVisibilityPredicates(); + /** + * Registers workstations for a category. + *

+ * This method is deferred to when the category is registered. This means that registration can be + * done anytime during the reload phase. + * + * @param category the category to register the workstation for + * @param stations the workstations to register + * @param the type of the display + */ default void addWorkstations(CategoryIdentifier category, EntryIngredient... stations) { configure(category, config -> config.addWorkstations(stations)); } + /** + * Registers workstations for a category. + *

+ * This method is deferred to when the category is registered. This means that registration can be + * done anytime during the reload phase. + * + * @param category the category to register the workstation for + * @param stations the workstations to register + * @param the type of the display + */ default void addWorkstations(CategoryIdentifier category, EntryStack... stations) { configure(category, config -> config.addWorkstations(stations)); } + /** + * Removes the plus button from a category. + * + * @param category the category to remove the plus button from + * @param the type of the display + * @deprecated No longer supported, the plus button is not available for removal + */ @Deprecated @ApiStatus.ScheduledForRemoval default void removePlusButton(CategoryIdentifier category) { configure(category, CategoryConfiguration::removePlusButton); } + /** + * Sets a plus button area provider for a category. + *

+ * This method is deferred to when the category is registered. This means that registration can be + * done anytime during the reload phase. + * + * @param category the category to set the plus button area provider for + * @param area the area provider + * @param the type of the display + */ default void setPlusButtonArea(CategoryIdentifier category, ButtonArea area) { configure(category, config -> config.setPlusButtonArea(area)); } interface CategoryConfiguration extends Identifiable { /** - * Registers the working stations of a category + * Registers workstations for a category. * - * @param stations the working stations + * @param stations the workstations to register */ void addWorkstations(EntryIngredient... stations); /** - * Registers the working stations of a category + * Registers workstations for a category. * - * @param stations the working stations + * @param stations the workstations to register */ default void addWorkstations(EntryStack... stations) { addWorkstations(CollectionUtils.map(stations, EntryIngredient::of).toArray(new EntryIngredient[0])); } /** - * Removes the plus button. + * Removes the plus button from a category. + * + * @deprecated No longer supported, the plus button is not available for removal */ @Deprecated @ApiStatus.ScheduledForRemoval @@ -195,39 +265,64 @@ public interface CategoryRegistry extends Reloadable, Iterable< } /** - * Sets the plus button area + * Sets a plus button area provider for a category. * - * @param area the button area + * @param area the area provider */ void setPlusButtonArea(ButtonArea area); /** - * Returns the optional plus button area + * Returns the optional plus button area provider * - * @return the optional plus button area + * @return the optional plus button area provider + * @implNote This method no longer returns an empty optional */ Optional getPlusButtonArea(); + /** + * Returns the list of workstations for the category. + * + * @return the list of workstations for the category + */ List getWorkstations(); /** + * Returns the underlying category. + * * @return the underlying category */ DisplayCategory getCategory(); /** - * Gets the display display category identifier + * Returns the category identifier * * @return the identifier of the category */ CategoryIdentifier getCategoryIdentifier(); + /** + * Returns an extension for the category. + *

+ * An extension may be used to modify how the category set-ups widgets for displays. + * + * @param provider the provider to register + * @see CategoryExtensionProvider + */ @ApiStatus.Experimental void registerExtension(CategoryExtensionProvider provider); + /** + * Returns a category view for a display. + * + * @param display the display + * @return the category view + */ @ApiStatus.Experimental DisplayCategoryView getView(T display); + /** + * {@inheritDoc} + */ @Override default ResourceLocation getIdentifier() { return getCategoryIdentifier().getIdentifier(); diff --git a/api/src/main/java/me/shedaniel/rei/api/client/registry/category/extension/CategoryExtensionProvider.java b/api/src/main/java/me/shedaniel/rei/api/client/registry/category/extension/CategoryExtensionProvider.java index 76f9f45ed..666400207 100644 --- a/api/src/main/java/me/shedaniel/rei/api/client/registry/category/extension/CategoryExtensionProvider.java +++ b/api/src/main/java/me/shedaniel/rei/api/client/registry/category/extension/CategoryExtensionProvider.java @@ -30,6 +30,14 @@ import net.fabricmc.api.EnvType; import net.fabricmc.api.Environment; import org.jetbrains.annotations.ApiStatus; +/** + * The provider to transform the {@link DisplayCategoryView}s. + *

+ * Plugins may use this to alter how a display looks, for example to add a custom widget. + * + * @param the type of the display + * @see me.shedaniel.rei.api.client.registry.category.CategoryRegistry.CategoryConfiguration#registerExtension(CategoryExtensionProvider) + */ @FunctionalInterface @ApiStatus.Experimental @Environment(EnvType.CLIENT) diff --git a/api/src/main/java/me/shedaniel/rei/api/client/registry/category/visibility/CategoryVisibilityPredicate.java b/api/src/main/java/me/shedaniel/rei/api/client/registry/category/visibility/CategoryVisibilityPredicate.java index 170d0fdea..af267dc76 100644 --- a/api/src/main/java/me/shedaniel/rei/api/client/registry/category/visibility/CategoryVisibilityPredicate.java +++ b/api/src/main/java/me/shedaniel/rei/api/client/registry/category/visibility/CategoryVisibilityPredicate.java @@ -29,13 +29,18 @@ import net.fabricmc.api.EnvType; import net.fabricmc.api.Environment; import net.minecraft.world.InteractionResult; +/** + * Handler for determining the visibility of categories. + * This is preferred comparing to removing the categories from the registry. + * + * @see me.shedaniel.rei.api.client.registry.category.CategoryRegistry#registerVisibilityPredicate(CategoryVisibilityPredicate) + */ @Environment(EnvType.CLIENT) public interface CategoryVisibilityPredicate extends Comparable { /** - * Gets the priority of the handler, the higher the priority, the earlier this is called. + * Returns the priority of the handler, the higher the priority, the earlier this is called. * * @return the priority - * @return the priority */ default double getPriority() { return 0.0; @@ -43,15 +48,16 @@ public interface CategoryVisibilityPredicate extends Comparable category); + /** + * {@inheritDoc} + */ @Override default int compareTo(CategoryVisibilityPredicate o) { return Double.compare(getPriority(), o.getPriority()); diff --git a/api/src/main/java/me/shedaniel/rei/api/client/registry/display/DisplayCategoryView.java b/api/src/main/java/me/shedaniel/rei/api/client/registry/display/DisplayCategoryView.java index 435a96569..2759e301e 100644 --- a/api/src/main/java/me/shedaniel/rei/api/client/registry/display/DisplayCategoryView.java +++ b/api/src/main/java/me/shedaniel/rei/api/client/registry/display/DisplayCategoryView.java @@ -39,14 +39,15 @@ import java.util.List; /** * A view that displays a {@link Display}. + *

+ * This view can be modified externally with {@link me.shedaniel.rei.api.client.registry.category.extension.CategoryExtensionProvider}. * * @param the type of display */ @ApiStatus.Experimental public interface DisplayCategoryView { /** - * Returns the recipe renderer for the display, used - * in {@link me.shedaniel.rei.impl.client.gui.screen.CompositeDisplayViewingScreen} for rendering simple recipes. + * Returns the recipe renderer for the display, used in composite display viewing screen. * * @param display the display to render * @return the display renderer 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 554994b5b..0af581d55 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 @@ -70,13 +70,12 @@ public interface DisplayRegistry extends RecipeManagerContext { /** * @return the instance of {@link DisplayRegistry} */ - static DisplayRegistry getInstance() { return PluginManager.getClientInstance().get(DisplayRegistry.class); } /** - * Gets the total display count registered + * Returns the total display count * * @return the recipe count */ 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 index 7758a88a6..1d0603977 100644 --- 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 @@ -34,8 +34,8 @@ 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. + * Generator of dynamic displays at runtime. + * Invoked per display view search, please keep this performant. * * @param the type of displays to generate * @see DisplayRegistry#registerDisplayGenerator(CategoryIdentifier, DynamicDisplayGenerator) @@ -43,14 +43,40 @@ import java.util.Optional; */ @Environment(EnvType.CLIENT) public interface DynamicDisplayGenerator { + /** + * Returns the list of displays generated for querying the recipes of the given stack. + *

+ * Displays generated should have the given stack as an output, but that + * is not required. + * + * @param entry the recipes of the stack to query for + * @return the list of displays generated + * @see ViewSearchBuilder#addRecipesFor(EntryStack) + */ default Optional> getRecipeFor(EntryStack entry) { return Optional.empty(); } + /** + * Returns the list of displays generated for querying the usages of the given stack. + *

+ * Displays generated should have the given stack as an input, but that + * is not required. + * + * @param entry the usages of the stack to query for + * @return the list of displays generated + * @see ViewSearchBuilder#addUsagesFor(EntryStack) + */ default Optional> getUsageFor(EntryStack entry) { return Optional.empty(); } + /** + * Returns the list of displays generated for a given view search. + * + * @param builder the builder of the view search + * @return the list of displays generated + */ default Optional> generate(ViewSearchBuilder builder) { return Optional.empty(); } diff --git a/api/src/main/java/me/shedaniel/rei/api/client/registry/display/visibility/DisplayVisibilityPredicate.java b/api/src/main/java/me/shedaniel/rei/api/client/registry/display/visibility/DisplayVisibilityPredicate.java index 724d3066e..a02509159 100644 --- a/api/src/main/java/me/shedaniel/rei/api/client/registry/display/visibility/DisplayVisibilityPredicate.java +++ b/api/src/main/java/me/shedaniel/rei/api/client/registry/display/visibility/DisplayVisibilityPredicate.java @@ -24,16 +24,23 @@ package me.shedaniel.rei.api.client.registry.display.visibility; import me.shedaniel.architectury.event.EventResult; +import me.shedaniel.rei.api.client.registry.category.visibility.CategoryVisibilityPredicate; import me.shedaniel.rei.api.client.registry.display.DisplayCategory; import me.shedaniel.rei.api.common.display.Display; import net.fabricmc.api.EnvType; import net.fabricmc.api.Environment; import net.minecraft.world.InteractionResult; +/** + * Handler for determining the visibility of displays. + * This is preferred comparing to removing the displays from the registry. + * + * @see me.shedaniel.rei.api.client.registry.display.DisplayRegistry#registerVisibilityPredicate(DisplayVisibilityPredicate) + */ @Environment(EnvType.CLIENT) public interface DisplayVisibilityPredicate extends Comparable { /** - * Gets the priority of the handler, the higher the priority, the earlier this is called. + * Returns the priority of the handler, the higher the priority, the earlier this is called. * * @return the priority */ @@ -43,16 +50,17 @@ public interface DisplayVisibilityPredicate extends Comparable category, Display display); + /** + * {@inheritDoc} + */ @Override default int compareTo(DisplayVisibilityPredicate o) { return Double.compare(getPriority(), o.getPriority()); 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 6ff3af865..b60baec9a 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 @@ -46,16 +46,17 @@ 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} + *

+ * 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)}. + *

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

+ * While this registry can be used for registering variants of stacks, there may be + * better alternatives such as {@link Item#fillItemCategory(CreativeModeTab, NonNullList)}. * * @see REIClientPlugin#registerEntries(EntryRegistry) */ @@ -80,7 +81,7 @@ public interface EntryRegistry extends Reloadable { /** * @return the unmodifiable list of filtered entry stacks, - * only available after plugins reload. + * only available after plugins reload. */ List> getPreFilteredList(); @@ -91,7 +92,7 @@ public interface EntryRegistry extends Reloadable { void refilter(); /** - * Gets all possible stacks from an item, tries to invoke {@link Item#appendStacks(net.minecraft.item.ItemGroup, net.minecraft.util.collection.DefaultedList)}. + * Returns all possible stacks from an item, tries to invoke {@link Item#fillItemCategory(CreativeModeTab, NonNullList)}. * * @param item the item to find * @return the list of possible stacks, will never be empty. @@ -99,7 +100,7 @@ public interface EntryRegistry extends Reloadable { List appendStacksForItem(Item item); /** - * Adds an new stack to the entry list. + * Adds a new stack to the entry list. * * @param stack the stack to add */ @@ -108,7 +109,7 @@ public interface EntryRegistry extends Reloadable { } /** - * Adds an new stack to the entry list, after a certain stack. + * Adds a new stack to the entry list, after a certain stack. * * @param afterEntry the stack to put after * @param stack the stack to add diff --git a/api/src/main/java/me/shedaniel/rei/api/client/view/ViewSearchBuilder.java b/api/src/main/java/me/shedaniel/rei/api/client/view/ViewSearchBuilder.java index 61dab5d73..65338fa4e 100644 --- a/api/src/main/java/me/shedaniel/rei/api/client/view/ViewSearchBuilder.java +++ b/api/src/main/java/me/shedaniel/rei/api/client/view/ViewSearchBuilder.java @@ -24,6 +24,7 @@ package me.shedaniel.rei.api.client.view; import me.shedaniel.rei.api.client.ClientHelper; +import me.shedaniel.rei.api.client.config.ConfigObject; import me.shedaniel.rei.api.client.registry.category.CategoryRegistry; import me.shedaniel.rei.api.client.registry.display.DisplayCategory; import me.shedaniel.rei.api.common.category.CategoryIdentifier; @@ -38,6 +39,9 @@ import org.jetbrains.annotations.Nullable; import java.util.*; import java.util.stream.Stream; +/** + * Builder for querying displays. + */ public interface ViewSearchBuilder { /** * Creates a new {@link ViewSearchBuilder} for looking up displays. @@ -103,6 +107,8 @@ public interface ViewSearchBuilder { /** * Filters the search to only include {@link Display}s that are recipes for the given {@link EntryStack}. + *

+ * This will include any {@link Display}s containing {@link Display#getOutputEntries()} that match for the given {@link EntryStack}. * * @param stack the stack to filter by * @param the type of the stack @@ -110,10 +116,18 @@ public interface ViewSearchBuilder { */ ViewSearchBuilder addRecipesFor(EntryStack stack); + /** + * Returns the list of {@link EntryStack}s that will be used to filter the search for the recipes of the given {@link EntryStack}. + * + * @return the list of {@link EntryStack}s + * @see ViewSearchBuilder#addRecipesFor(EntryStack) + */ List> getRecipesFor(); /** * Filters the search to only include {@link Display}s that are usages for the given {@link EntryStack}. + *

+ * This will include any {@link Display}s containing {@link Display#getInputEntries()} that match for the given {@link EntryStack}. * * @param stack the stack to filter by * @param the type of the stack @@ -121,10 +135,27 @@ public interface ViewSearchBuilder { */ ViewSearchBuilder addUsagesFor(EntryStack stack); + /** + * Returns the list of {@link EntryStack}s that will be used to filter the search for the usages of the given {@link EntryStack}. + * + * @return the list of {@link EntryStack}s + * @see ViewSearchBuilder#addUsagesFor(EntryStack) + */ List> getUsagesFor(); + /** + * Sets the preferred opened {@link DisplayCategory} for the view. + * + * @param category the preferred opened {@link DisplayCategory}, or {@code null} to use the first category + * @return the {@link ViewSearchBuilder} for chaining + */ ViewSearchBuilder setPreferredOpenedCategory(@Nullable CategoryIdentifier category); + /** + * Returns the preferred opened {@link DisplayCategory} for the view, or {@code null} if none is set. + * + * @return the preferred opened {@link DisplayCategory} + */ @Nullable CategoryIdentifier getPreferredOpenedCategory(); @@ -141,17 +172,57 @@ public interface ViewSearchBuilder { @ApiStatus.Internal Map, List> buildMapInternal(); + /** + * Returns the stream of {@link DisplaySpec}s that match the search. + * + * @return the stream of {@link DisplaySpec}s + */ @ApiStatus.Experimental Stream streamDisplays(); + /** + * Returns whether the search is merging equal {@link DisplaySpec}s. + * + * @return whether the search is merging equal {@link DisplaySpec}s + * @see ConfigObject#doMergeDisplayUnderOne() for the config option + * @see DisplayCategory#getDisplayMerger() for the merging strategy + */ boolean isMergingDisplays(); + /** + * Sets whether the search is merging equal {@link DisplaySpec}s. + * + * @param mergingDisplays whether the search is merging equal {@link DisplaySpec}s + * @return the {@link ViewSearchBuilder} for chaining + * @see ConfigObject#doMergeDisplayUnderOne() for the default config option + * @see DisplayCategory#getDisplayMerger() for the merging strategy + */ ViewSearchBuilder mergingDisplays(boolean mergingDisplays); + /** + * Returns whether the search is processing visibility handlers. + * + * @return whether the search is processing visibility handlers + * @see me.shedaniel.rei.api.client.registry.category.visibility.CategoryVisibilityPredicate + * @see me.shedaniel.rei.api.client.registry.display.visibility.DisplayVisibilityPredicate + */ boolean isProcessingVisibilityHandlers(); + /** + * Sets whether the search is processing visibility handlers. + * + * @param processingVisibilityHandlers whether the search is processing visibility handlers + * @return the {@link ViewSearchBuilder} for chaining + * @see me.shedaniel.rei.api.client.registry.category.visibility.CategoryVisibilityPredicate + * @see me.shedaniel.rei.api.client.registry.display.visibility.DisplayVisibilityPredicate + */ ViewSearchBuilder processingVisibilityHandlers(boolean processingVisibilityHandlers); + /** + * Opens the view after the search is complete. + * + * @return whether the view was opened + */ default boolean open() { return ClientHelper.getInstance().openView(this); } diff --git a/api/src/main/java/me/shedaniel/rei/api/common/category/CategoryIdentifier.java b/api/src/main/java/me/shedaniel/rei/api/common/category/CategoryIdentifier.java index 34e807795..8fd2136c0 100644 --- a/api/src/main/java/me/shedaniel/rei/api/common/category/CategoryIdentifier.java +++ b/api/src/main/java/me/shedaniel/rei/api/common/category/CategoryIdentifier.java @@ -26,31 +26,79 @@ package me.shedaniel.rei.api.common.category; import me.shedaniel.rei.api.common.display.Display; import me.shedaniel.rei.api.common.util.Identifiable; import me.shedaniel.rei.impl.Internals; +import net.minecraft.ResourceLocationException; import net.minecraft.resources.ResourceLocation; import org.jetbrains.annotations.ApiStatus; +/** + * A category identifier is used to identify a category. This is the typed version of {@link ResourceLocation}. + * + * @param the type of display + */ @ApiStatus.NonExtendable public interface CategoryIdentifier extends Identifiable { + /** + * Creates a new category identifier from the given resource location string. + *

+ * The namespace and path of the resource location is seperated by a colon. + * + * @param str the string to create the identifier from + * @param the type of display + * @return the identifier + * @throws ResourceLocationException if the string is not a valid resource location + */ static CategoryIdentifier of(String str) { return Internals.getCategoryIdentifier(str); } + /** + * Creates a new category identifier from the given namespace and path. + * + * @param namespace the namespace of the identifier, usually the mod id + * @param path the path of the identifier + * @param the type of display + * @return the identifier + * @throws ResourceLocationException if the string is not a valid resource location + */ static CategoryIdentifier of(String namespace, String path) { return of(namespace + ":" + path); } + /** + * Creates a new category identifier from the given identifier. + * + * @param identifier the identifier + * @param the type of display + * @return the identifier + */ static CategoryIdentifier of(ResourceLocation identifier) { return of(identifier.toString()); } + /** + * Returns the namespace of the identifier, this is usually the mod id. + * + * @return the namespace + */ default String getNamespace() { return getIdentifier().getNamespace(); } + /** + * Returns the path of the identifier. + * + * @return the path + */ default String getPath() { return getIdentifier().getPath(); } + /** + * Casts this {@link CategoryIdentifier} to a {@link CategoryIdentifier} of the given type. + * + * @param the new type + * @return the casted {@link CategoryIdentifier} + */ @ApiStatus.NonExtendable default CategoryIdentifier cast() { return (CategoryIdentifier) this; diff --git a/api/src/main/java/me/shedaniel/rei/api/common/display/DisplayMerger.java b/api/src/main/java/me/shedaniel/rei/api/common/display/DisplayMerger.java index f472e2e7c..11d65c738 100644 --- a/api/src/main/java/me/shedaniel/rei/api/common/display/DisplayMerger.java +++ b/api/src/main/java/me/shedaniel/rei/api/common/display/DisplayMerger.java @@ -23,8 +23,29 @@ package me.shedaniel.rei.api.common.display; +import me.shedaniel.rei.api.client.registry.display.DisplayCategory; + +/** + * A merger used to determine whether two displays can be merged together. + * + * @param the type of display + * @see DisplayCategory#getDisplayMerger() for where to return this + * @see DisplayCategory#getContentMerger() for a basic merger based on checking the inputs and outputs + */ public interface DisplayMerger { + /** + * Returns whether the two displays can be merged together. + * + * @param first the first display + * @param second the second display + * @return whether the two displays can be merged together + */ boolean canMerge(T first, T second); + /** + * Returns the hash code of a display. + * + * @param display the display + */ int hashOf(T display); } diff --git a/api/src/main/java/me/shedaniel/rei/api/common/display/DisplaySerializer.java b/api/src/main/java/me/shedaniel/rei/api/common/display/DisplaySerializer.java index df0dbe6e3..2b0332619 100644 --- a/api/src/main/java/me/shedaniel/rei/api/common/display/DisplaySerializer.java +++ b/api/src/main/java/me/shedaniel/rei/api/common/display/DisplaySerializer.java @@ -33,8 +33,21 @@ import net.minecraft.nbt.CompoundTag; * @see DisplaySerializerRegistry */ public interface DisplaySerializer { + /** + * Serializes the display into a tag. + * + * @param tag the tag to serialize into + * @param display the display to serialize + * @return the tag + */ CompoundTag save(CompoundTag tag, D display); + /** + * Deserializes the display from a tag. + * + * @param tag the tag to deserialize from + * @return the display + */ D read(CompoundTag tag); /** 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 41e71d232..c02fafc2a 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 @@ -62,9 +62,31 @@ public interface DisplaySerializerRegistry extends Reloadable> { */ void registerNotSerializable(CategoryIdentifier categoryId); + /** + * Returns whether a {@link DisplaySerializer} is registered for the given {@link CategoryIdentifier}. + * + * @param categoryId the identifier of the category + * @param the type of the display + * @return whether a serializer is registered for the given category + */ boolean hasSerializer(CategoryIdentifier categoryId); + /** + * Serializes the display into a tag. + * + * @param tag the tag to serialize into + * @param display the display to serialize + * @return the tag + * @see DisplaySerializer#save(CompoundTag, Display) + */ CompoundTag save(D display, CompoundTag tag); + /** + * Deserializes the display from a tag. + * + * @param tag the tag to deserialize from + * @return the display + * @see DisplaySerializer#read(CompoundTag) + */ D read(CategoryIdentifier categoryId, CompoundTag tag); } diff --git a/api/src/main/java/me/shedaniel/rei/api/common/display/SimpleDisplaySerializer.java b/api/src/main/java/me/shedaniel/rei/api/common/display/SimpleDisplaySerializer.java index 74025c501..545e647e9 100644 --- a/api/src/main/java/me/shedaniel/rei/api/common/display/SimpleDisplaySerializer.java +++ b/api/src/main/java/me/shedaniel/rei/api/common/display/SimpleDisplaySerializer.java @@ -29,7 +29,15 @@ import net.minecraft.nbt.CompoundTag; import java.util.List; +/** + * A simple display serializer that serializes both the input and output of a display. + * + * @param the display type + */ public interface SimpleDisplaySerializer extends DisplaySerializer { + /** + * {@inheritDoc} + */ @Override default CompoundTag save(CompoundTag tag, D display) { tag.put("input", EntryIngredients.save(getInputIngredients(display))); @@ -38,13 +46,32 @@ public interface SimpleDisplaySerializer extends DisplaySeria return tag; } + /** + * Returns the input ingredients of the display for serialization. + * + * @param display the display + * @return the input ingredients + */ default List getInputIngredients(D display) { return display.getInputEntries(); } + /** + * Returns the output ingredients of the display for serialization. + * + * @param display the display + * @return the output ingredients + */ default List getOutputIngredients(D display) { return display.getOutputEntries(); } + /** + * Serializes the extra data of the display into the tag. + * + * @param tag the tag + * @param display the display + * @return the tag + */ CompoundTag saveExtra(CompoundTag tag, D display); } diff --git a/api/src/main/java/me/shedaniel/rei/api/common/display/SimpleGridMenuDisplay.java b/api/src/main/java/me/shedaniel/rei/api/common/display/SimpleGridMenuDisplay.java index f19cc22a9..ae4f1a641 100644 --- a/api/src/main/java/me/shedaniel/rei/api/common/display/SimpleGridMenuDisplay.java +++ b/api/src/main/java/me/shedaniel/rei/api/common/display/SimpleGridMenuDisplay.java @@ -24,7 +24,7 @@ package me.shedaniel.rei.api.common.display; /** - * An display to be used alongside {@link me.shedaniel.rei.api.common.transfer.info.simple.SimpleGridMenuInfo}, + * A display to be used alongside {@link me.shedaniel.rei.api.common.transfer.info.simple.SimpleGridMenuInfo}, * to provide a {@code width} and {@code height} for the grid of the recipe. * * @see me.shedaniel.rei.api.common.transfer.info.simple.SimpleGridMenuInfo diff --git a/api/src/main/java/me/shedaniel/rei/api/common/display/basic/BasicDisplay.java b/api/src/main/java/me/shedaniel/rei/api/common/display/basic/BasicDisplay.java index faefd68ef..6b1a99aec 100644 --- a/api/src/main/java/me/shedaniel/rei/api/common/display/basic/BasicDisplay.java +++ b/api/src/main/java/me/shedaniel/rei/api/common/display/basic/BasicDisplay.java @@ -35,6 +35,10 @@ import org.jetbrains.annotations.Nullable; import java.util.List; import java.util.Optional; +/** + * A basic implementation of a display, consisting of a list of inputs, a list of outputs + * and a possible display location. + */ public abstract class BasicDisplay implements Display { protected List inputs; protected List outputs; @@ -50,39 +54,81 @@ public abstract class BasicDisplay implements Display { this.location = location; } + /** + * {@inheritDoc} + */ @Override public List getInputEntries() { return inputs; } + /** + * {@inheritDoc} + */ @Override public List getOutputEntries() { return outputs; } + /** + * {@inheritDoc} + */ @Override public Optional getDisplayLocation() { return location; } + /** + * A basic serializer for {@link BasicDisplay}s. + * + * @param

the type of the display + */ public static class Serializer

implements SimpleDisplaySerializer

{ protected final Constructor

constructor; protected final ExtraSerializer

extraSerializer; protected EntryIngredientsProvider

inputEntries = EntryIngredientsProvider.pass(); protected EntryIngredientsProvider

outputEntries = EntryIngredientsProvider.pass(); + /** + * Creates a new serializer with a constructor for list of inputs, list of outputs and a possible location. + * + * @param constructor the constructor for the display + * @param

the type of the display + * @return the serializer + */ public static

Serializer

ofSimple(SimpleConstructor

constructor) { return new Serializer<>(constructor, (p, tag) -> {}); } + /** + * Creates a new serializer with a constructor for list of inputs, list of outputs and the serialization tag. + * + * @param constructor the constructor for the display + * @param

the type of the display + * @return the serializer + */ public static

Serializer

ofRecipeLess(RecipeLessConstructor

constructor) { return new Serializer<>(constructor, (p, tag) -> {}); } + /** + * Creates a new serializer with a constructor for list of inputs and list of outputs. + * + * @param constructor the constructor for the display + * @param

the type of the display + * @return the serializer + */ public static

Serializer

ofSimpleRecipeLess(SimpleRecipeLessConstructor

constructor) { return new Serializer<>(constructor, (p, tag) -> {}); } + /** + * Creates a new serializer with a constructor for list of inputs, list of outputs, a possible location, the serialization tag. + * + * @param constructor the constructor for the display + * @param

the type of the display + * @return the serializer + */ public static

Serializer

of(Constructor

constructor) { return new Serializer<>(constructor, (p, tag) -> {}); } @@ -91,18 +137,54 @@ public abstract class BasicDisplay implements Display { this(constructor, (p, tag) -> {}); } + /** + * Creates a new serializer with a constructor for list of inputs, list of outputs and a possible location, + * with a serializer for serializing extra data. + * + * @param constructor the constructor for the display + * @param extraSerializer the extra serializer for the display + * @param

the type of the display + * @return the serializer + */ public static

Serializer

ofSimple(SimpleConstructor

constructor, ExtraSerializer

extraSerializer) { return new Serializer<>(constructor, extraSerializer); } + /** + * Creates a new serializer with a constructor for list of inputs, list of outputs and the serialization tag, + * with a serializer for serializing extra data. + * + * @param constructor the constructor for the display + * @param extraSerializer the extra serializer for the display + * @param

the type of the display + * @return the serializer + */ public static

Serializer

ofRecipeLess(RecipeLessConstructor

constructor, ExtraSerializer

extraSerializer) { return new Serializer<>(constructor, extraSerializer); } + /** + * Creates a new serializer with a constructor for list of inputs and list of outputs, + * with a serializer for serializing extra data. + * + * @param constructor the constructor for the display + * @param extraSerializer the extra serializer for the display + * @param

the type of the display + * @return the serializer + */ public static

Serializer

ofSimpleRecipeLess(SimpleRecipeLessConstructor

constructor, ExtraSerializer

extraSerializer) { return new Serializer<>(constructor, extraSerializer); } + /** + * Creates a new serializer with a constructor for list of inputs, list of outputs, a possible location, the serialization tag, + * with a serializer for serializing extra data. + * + * @param constructor the constructor for the display + * @param extraSerializer the extra serializer for the display + * @param

the type of the display + * @return the serializer + */ public static

Serializer

of(Constructor

constructor, ExtraSerializer

extraSerializer) { return new Serializer<>(constructor, extraSerializer); } @@ -112,16 +194,31 @@ public abstract class BasicDisplay implements Display { this.extraSerializer = extraSerializer; } + /** + * Sets the provider for the list of inputs. + * + * @param provider the provider + * @return the serializer, for chaining + */ public Serializer

inputProvider(EntryIngredientsProvider

provider) { this.inputEntries = provider; return this; } + /** + * Sets the provider for the list of outputs. + * + * @param provider the provider + * @return the serializer, for chaining + */ public Serializer

outputProvider(EntryIngredientsProvider

provider) { this.outputEntries = provider; return this; } + /** + * {@inheritDoc} + */ @Override public CompoundTag saveExtra(CompoundTag tag, P display) { display.getDisplayLocation().ifPresent(location -> tag.putString("location", location.toString())); @@ -129,6 +226,9 @@ public abstract class BasicDisplay implements Display { return tag; } + /** + * {@inheritDoc} + */ @Override public P read(CompoundTag tag) { List input = EntryIngredients.read(tag.getList("input", NbtType.LIST)); @@ -142,6 +242,9 @@ public abstract class BasicDisplay implements Display { return constructor.construct(input, output, Optional.ofNullable(location), tag); } + /** + * {@inheritDoc} + */ @Override public List getInputIngredients(P display) { List entries = this.inputEntries.getEntries(display); @@ -149,6 +252,9 @@ public abstract class BasicDisplay implements Display { return SimpleDisplaySerializer.super.getInputIngredients(display); } + /** + * {@inheritDoc} + */ @Override public List getOutputIngredients(P display) { List entries = this.outputEntries.getEntries(display); diff --git a/api/src/main/java/me/shedaniel/rei/api/common/registry/RecipeManagerContext.java b/api/src/main/java/me/shedaniel/rei/api/common/registry/RecipeManagerContext.java index 588f444b2..195afce1c 100644 --- a/api/src/main/java/me/shedaniel/rei/api/common/registry/RecipeManagerContext.java +++ b/api/src/main/java/me/shedaniel/rei/api/common/registry/RecipeManagerContext.java @@ -34,6 +34,9 @@ import net.minecraft.world.item.crafting.RecipeManager; import java.util.List; public interface RecipeManagerContext

> extends Reloadable

{ + /** + * @return the instance of {@link RecipeManagerContext} + */ static RecipeManagerContext> getInstance() { return PluginManager.getInstance().get(RecipeManagerContext.class); } @@ -44,7 +47,7 @@ public interface RecipeManagerContext

> extends Reloadable List> getAllSortedRecipes(); /** - * Gets the vanilla recipe manager + * Returns the vanilla recipe manager * * @return the recipe manager */ -- cgit