From ab3b81eac9d5a36f5855bf072d5898f1654b90d2 Mon Sep 17 00:00:00 2001 From: Shadowfacts Date: Fri, 28 Dec 2018 13:10:59 -0500 Subject: [PATCH] Add JavaDocs --- .../client/MultipartBakedModel.java | 18 ++++- .../client/MultipartModelProvider.java | 10 --- .../container/MultipartContainer.java | 38 +++++++++++ .../simplemultipart/item/ItemMultipart.java | 21 ++++++ .../simplemultipart/multipart/Multipart.java | 65 ++++++++++++++++++- .../multipart/MultipartState.java | 20 ++++++ .../multipart/MultipartView.java | 36 +++++++++- .../multipart/entity/MultipartEntity.java | 26 ++++++++ .../entity/MultipartEntityProvider.java | 12 ++++ .../simplemultipart/util/MultipartHelper.java | 35 ++++++++++ .../util/MultipartHitResult.java | 10 +++ .../util/MultipartPlacementContext.java | 8 +++ 12 files changed, 286 insertions(+), 13 deletions(-) diff --git a/src/main/java/net/shadowfacts/simplemultipart/client/MultipartBakedModel.java b/src/main/java/net/shadowfacts/simplemultipart/client/MultipartBakedModel.java index b11a4c4..a9fc615 100644 --- a/src/main/java/net/shadowfacts/simplemultipart/client/MultipartBakedModel.java +++ b/src/main/java/net/shadowfacts/simplemultipart/client/MultipartBakedModel.java @@ -10,11 +10,27 @@ import java.util.List; import java.util.Random; /** + * An extension of the {@link BakedModel} interface for custom code-based multipart models. + * + * Note: Currently there is no proper way to register these. They can be registered by mixing in to the {@link net.minecraft.client.render.model.ModelLoader} + * constructor and injecting them into the {@code bakedModels} map. + * * @author shadowfacts + * @since 0.1.0 */ public interface MultipartBakedModel extends BakedModel { - List getMultipartQuads(MultipartView view, Direction side, Random random); + /** + * Retrieves the quads for a given side of the multipart. + * + * @param view The view of the multipart in the world. + * {@code null} if the default {@link MultipartBakedModel#getQuads(BlockState, Direction, Random)} implementation + * is invoked. + * @param side The side that quads are being requested for. + * @param random The position-specific random. + * @return The quads for the given side. The returned quads will be culled whenever the {@code side} is obscured. + */ + List getMultipartQuads(/*@Nullable*/ MultipartView view, Direction side, Random random); @Override default List getQuads(BlockState state, Direction side, Random random) { diff --git a/src/main/java/net/shadowfacts/simplemultipart/client/MultipartModelProvider.java b/src/main/java/net/shadowfacts/simplemultipart/client/MultipartModelProvider.java index 92cfd12..192ae94 100644 --- a/src/main/java/net/shadowfacts/simplemultipart/client/MultipartModelProvider.java +++ b/src/main/java/net/shadowfacts/simplemultipart/client/MultipartModelProvider.java @@ -107,16 +107,6 @@ public class MultipartModelProvider implements ModelProvider { return model; } -// private StateFactory getStateFactory(class_816 multipartUnbakedModel) { -// try { -// Field f = class_816.class.getDeclaredField("field_4329"); -// f.setAccessible(true); -// return (StateFactory)f.get(multipartUnbakedModel); -// } catch (ReflectiveOperationException e) { -// throw new RuntimeException(e); -// } -// } - private ModelVariantMap loadPartVariantMap(MultipartFakeBlock blockAdapter, Identifier partStateDefId) throws IOException { Resource resource = null; Reader reader = null; diff --git a/src/main/java/net/shadowfacts/simplemultipart/container/MultipartContainer.java b/src/main/java/net/shadowfacts/simplemultipart/container/MultipartContainer.java index ed0a224..68d1cba 100644 --- a/src/main/java/net/shadowfacts/simplemultipart/container/MultipartContainer.java +++ b/src/main/java/net/shadowfacts/simplemultipart/container/MultipartContainer.java @@ -6,20 +6,58 @@ import net.shadowfacts.simplemultipart.multipart.MultipartState; import java.util.Set; /** + * An interface for an object that contains multiparts. + * Usually a {@link net.minecraft.block.entity.BlockEntity}; default implementation is {@link AbstractContainerBlockEntity}. + * * @author shadowfacts + * @since 0.1.0 */ public interface MultipartContainer { + /** + * Retrieves all the multiparts held by this container. + * + * @see MultipartView + * @return All multiparts held by this container. + */ Set getParts(); + /** + * Determines whether the given multipart state can be inserted into this container. + * Checks that the bounding box of the new part does not intersect with any existing ones. + * + * @param state The new multipart state. + * @return If the part can be inserted. + */ boolean canInsert(MultipartState state); + /** + * Performs the insertion of the given multipart into this container. + * + * @param state The new multipart state. + */ void insert(MultipartState state); + /** + * Removes the given multipart from this container. + * + * @see MultipartView + * @param view The part to remove + */ void remove(MultipartView view); + /** + * Breaks the given multipart. Removes it from this container and drops the part as an item. + * + * @param view The part to break. + * @return If the part has been successfully broken. + */ boolean breakPart(MultipartView view); + /** + * Indicates that something about a multipart in this container has changed and it should be saved to disk. + * Does not trigger a network update. + */ void schedulePartSave(); } diff --git a/src/main/java/net/shadowfacts/simplemultipart/item/ItemMultipart.java b/src/main/java/net/shadowfacts/simplemultipart/item/ItemMultipart.java index 3468722..e590bf9 100644 --- a/src/main/java/net/shadowfacts/simplemultipart/item/ItemMultipart.java +++ b/src/main/java/net/shadowfacts/simplemultipart/item/ItemMultipart.java @@ -11,13 +11,19 @@ import net.shadowfacts.simplemultipart.multipart.MultipartState; import net.shadowfacts.simplemultipart.util.MultipartPlacementContext; /** + * An {@link Item} implementation that handles placing multiparts. + * + * Analogous to {@link net.minecraft.item.block.BlockItem}. + * * @author shadowfacts + * @since 0.1.0 */ public class ItemMultipart extends Item { protected Multipart part; public ItemMultipart(Multipart part) { + // TODO: expose settings object? super(new Settings()); this.part = part; } @@ -27,6 +33,15 @@ public class ItemMultipart extends Item { return tryPlace(context); } + /** + * Attempts to place this item's multipart in the given context. + * + * If the player clicked an existing multipart container, it will attempt to insert into that one, falling back on + * creating a new container. + * + * @param context The item usage context. + * @return The result of the placement. + */ protected ActionResult tryPlace(ItemUsageContext context) { // If a multipart inside an existing container was clicked, try inserting into that MultipartContainer hitContainer = getContainer(context); @@ -65,6 +80,12 @@ public class ItemMultipart extends Item { return container; } + /** + * Attempts to insert this item's multipart into the container specified by the given context. + * + * @param context The multipart placement context. + * @return If the placement succeeded. + */ protected boolean tryPlace(MultipartPlacementContext context) { MultipartState placementState = part.getPlacementState(context); diff --git a/src/main/java/net/shadowfacts/simplemultipart/multipart/Multipart.java b/src/main/java/net/shadowfacts/simplemultipart/multipart/Multipart.java index a3ed759..27667df 100644 --- a/src/main/java/net/shadowfacts/simplemultipart/multipart/Multipart.java +++ b/src/main/java/net/shadowfacts/simplemultipart/multipart/Multipart.java @@ -7,6 +7,7 @@ import net.minecraft.server.world.ServerWorld; import net.minecraft.state.StateFactory; import net.minecraft.util.Hand; import net.minecraft.util.Identifier; +import net.minecraft.util.math.Direction; import net.minecraft.util.shape.VoxelShape; import net.minecraft.world.loot.LootSupplier; import net.minecraft.world.loot.LootTables; @@ -15,9 +16,15 @@ import net.shadowfacts.simplemultipart.SimpleMultipart; import net.shadowfacts.simplemultipart.util.MultipartPlacementContext; import java.util.List; +import java.util.Random; /** + * The base class for a multipart object. + * + * Analogous to {@link net.minecraft.block.Block}. + * * @author shadowfacts + * @since 0.1.0 */ public abstract class Multipart { @@ -26,6 +33,7 @@ public abstract class Multipart { private Identifier dropTableId; + // TODO: Settings object? public Multipart() { StateFactory.Builder builder = new StateFactory.Builder<>(this); appendProperties(builder); @@ -33,26 +41,55 @@ public abstract class Multipart { defaultState = stateFactory.getDefaultState(); } + /** + * Used to add additional properties to the state factory. + * @param builder The state factory builder. + */ protected void appendProperties(StateFactory.Builder builder) {} + /** + * @return The default state for this multipart. + */ public MultipartState getDefaultState() { return defaultState; } + /** + * Sets a new default state for this multipart. + * @param defaultState The new default state. + */ public void setDefaultState(MultipartState defaultState) { this.defaultState = defaultState; } + /** + * @return The state factory for this multipart. + */ public StateFactory getStateFactory() { return stateFactory; } + /** + * Used to determine the state that should be used when this multipart is placed in the world from the given context. + * + * For example: determine which half a slab should be or which side a facade should be on. + * + * @param context The context in which this part is being placed. + * @return The state to place. + */ public MultipartState getPlacementState(MultipartPlacementContext context) { return getDefaultState(); } /** + * Can be used to provide additional information to custom {@link net.shadowfacts.simplemultipart.client.MultipartBakedModel}. + * The returned state will be passed to {@link net.shadowfacts.simplemultipart.client.MultipartBakedModel#getMultipartQuads(MultipartView, Direction, Random)}. + * * Can be overridden, should only be called via {@link MultipartState#getStateForRendering} + * + * @param state The normal state of this multipart. + * @param view The view of this multipart. + * @return The state that will be used for rendering. */ @Deprecated public MultipartState getStateForRendering(MultipartState state, MultipartView view) { @@ -60,11 +97,22 @@ public abstract class Multipart { } /** + * Retrieves the bounding shape this multipart should have. + * * Can be overridden, should only be called via {@link MultipartState#getBoundingShape} + * + * @param state The specific state for which to return the bounding shape. + * @param view The current view of the multipart. + * Will be {@code null} when the default bounding shape is determined prior to the part being inserted + * into the container. + * @return The bounding shape of this multipart in the given state. */ @Deprecated - public abstract VoxelShape getBoundingShape(/*@Nullable*/ MultipartState state, MultipartView view); + public abstract VoxelShape getBoundingShape(MultipartState state, /*@Nullable*/ MultipartView view); + /** + * @return The loot table ID used for to determine the drops by the default {@link Multipart#getDroppedStacks(MultipartState, MultipartView, LootContext.Builder)} implementation. + */ public Identifier getDropTableId() { if (dropTableId == null) { Identifier id = SimpleMultipart.MULTIPART.getId(this); @@ -74,7 +122,14 @@ public abstract class Multipart { } /** + * Retrieves a list of stacks that should be dropped in the world when this part is broken via {@link net.shadowfacts.simplemultipart.container.MultipartContainer#breakPart(MultipartView)}. + * * Can be overridden, should only be called via {@link MultipartState#getDroppedStacks)} + * + * @param state The state of this part. + * @param view The view of this part. + * @param builder The {@link LootContext} builder, used by the default loot table-based implementation. + * @return The list of stacks to drop. */ @Deprecated public List getDroppedStacks(MultipartState state, MultipartView view, LootContext.Builder builder) { @@ -90,7 +145,15 @@ public abstract class Multipart { } /** + * Called when this part is activated (i.e. right-clicked) in the world. + * * Can be overridden, should only be called via {@link MultipartState#activate} + * + * @param state The state of this part. + * @param view The view of this part. + * @param player The player that activated this part. + * @param hand The hand with which they performed the action. + * @return If the activation was successful. {@code true} will trigger the hand-swinging animation. */ @Deprecated public boolean activate(MultipartState state, MultipartView view, PlayerEntity player, Hand hand) { diff --git a/src/main/java/net/shadowfacts/simplemultipart/multipart/MultipartState.java b/src/main/java/net/shadowfacts/simplemultipart/multipart/MultipartState.java index bbf4c4c..04ec8a0 100644 --- a/src/main/java/net/shadowfacts/simplemultipart/multipart/MultipartState.java +++ b/src/main/java/net/shadowfacts/simplemultipart/multipart/MultipartState.java @@ -12,7 +12,12 @@ import net.minecraft.world.loot.context.LootContext; import java.util.List; /** + * A container for a {@link Multipart} and its associated properties/values. + * + * Analogous to {@link net.minecraft.block.BlockState}. + * * @author shadowfacts + * @since 0.1.0 */ public class MultipartState extends AbstractPropertyContainer { @@ -20,25 +25,40 @@ public class MultipartState extends AbstractPropertyContainer getDroppedStacks(MultipartView view, LootContext.Builder builder) { //noinspection deprecated return owner.getDroppedStacks(this, view, builder); } + /** + * @see Multipart#activate(MultipartState, MultipartView, PlayerEntity, Hand) + */ public boolean activate(MultipartView view, PlayerEntity player, Hand hand) { //noinspection deprecated return owner.activate(this, view, player, hand); diff --git a/src/main/java/net/shadowfacts/simplemultipart/multipart/MultipartView.java b/src/main/java/net/shadowfacts/simplemultipart/multipart/MultipartView.java index e2acfdc..775f113 100644 --- a/src/main/java/net/shadowfacts/simplemultipart/multipart/MultipartView.java +++ b/src/main/java/net/shadowfacts/simplemultipart/multipart/MultipartView.java @@ -6,21 +6,55 @@ import net.shadowfacts.simplemultipart.multipart.MultipartState; import net.shadowfacts.simplemultipart.multipart.entity.MultipartEntity; /** + * A view of a multipart and its (optional) associated entity. + * * @author shadowfacts + * @since 0.1.0 */ // TODO: better name for this public interface MultipartView { + /** + * @return The container holding this part. + */ MultipartContainer getContainer(); + /** + * @return The current state of this multipart. + */ MultipartState getState(); + /** + * Sets the new state of this multipart. + * + * Note: This should only be used to change the state of the current {@link Multipart}. + * Changing to a different multipart should be done by removing/breaking the part in the container and then + * inserting the new one. + * + * Setting the state of a multipart will not cause the associated entity to change. + * + * @param state The new state. + */ void setState(MultipartState state); - MultipartEntity getEntity(); + /** + * @return The entity associated with this part. + */ + /*@Nullable*/ MultipartEntity getEntity(); + /** + * Sets the entity associated with this part. + * + * This should not usually be called. The associated multipart entity will be created/set by {@link MultipartContainer#insert(MultipartState)} + * + * @param entity The new entity. + */ void setEntity(MultipartEntity entity); + /** + * Helper method for retrieving the multipart object for the current state. + * @return The current multipart. + */ default Multipart getMultipart() { return getState().getMultipart(); } diff --git a/src/main/java/net/shadowfacts/simplemultipart/multipart/entity/MultipartEntity.java b/src/main/java/net/shadowfacts/simplemultipart/multipart/entity/MultipartEntity.java index e15bb60..448f297 100644 --- a/src/main/java/net/shadowfacts/simplemultipart/multipart/entity/MultipartEntity.java +++ b/src/main/java/net/shadowfacts/simplemultipart/multipart/entity/MultipartEntity.java @@ -4,24 +4,50 @@ import net.minecraft.nbt.CompoundTag; import net.shadowfacts.simplemultipart.container.MultipartContainer; /** + * An entity associated with multiparts placed in the world. An instance of the part's entity exists for every in-world + * instance of the part. + * + * Can implement {@link net.minecraft.util.Tickable} to be updated on game ticks. + * + * Analogous to {@link net.minecraft.block.entity.BlockEntity}. + * * @author shadowfacts + * @since 0.1.0 */ public abstract class MultipartEntity { + /** + * The container holding this multipart entity. + */ + // TODO: change this to a view? public MultipartContainer container; public MultipartEntity(MultipartContainer container) { this.container = container; } + /** + * Calling this indicates that something about this entity has changed that necessitates saving it to disk. + */ protected void scheduleSave() { container.schedulePartSave(); } + /** + * Converts this entity into an NBT tag that can be saved to disk or transferred over the network. + * + * @param tag The tag to save this entity to. + * @return The modified tag. + */ public CompoundTag toTag(CompoundTag tag) { return tag; } + /** + * Restores this entity from the given NBT tag. + * + * @param tag The tag generated by {@link MultipartEntity#toTag(CompoundTag)}. + */ public void fromTag(CompoundTag tag) { } diff --git a/src/main/java/net/shadowfacts/simplemultipart/multipart/entity/MultipartEntityProvider.java b/src/main/java/net/shadowfacts/simplemultipart/multipart/entity/MultipartEntityProvider.java index e554a55..8346641 100644 --- a/src/main/java/net/shadowfacts/simplemultipart/multipart/entity/MultipartEntityProvider.java +++ b/src/main/java/net/shadowfacts/simplemultipart/multipart/entity/MultipartEntityProvider.java @@ -4,10 +4,22 @@ import net.shadowfacts.simplemultipart.container.MultipartContainer; import net.shadowfacts.simplemultipart.multipart.MultipartState; /** + * An interface to be applied to {@link net.shadowfacts.simplemultipart.multipart.Multipart}s that have entities. + * + * Analogous to {@link net.minecraft.block.BlockEntityProvider}. + * * @author shadowfacts + * @since 0.1.0 */ public interface MultipartEntityProvider { + /** + * Creates a new multipart entity for this part. + * + * @param state The state of this part. + * @param container The container this part is in. + * @return The new entity. {@code null} if there should not be an entity in this instance. + */ /*@Nullable*/ MultipartEntity createMultipartEntity(MultipartState state, MultipartContainer container); diff --git a/src/main/java/net/shadowfacts/simplemultipart/util/MultipartHelper.java b/src/main/java/net/shadowfacts/simplemultipart/util/MultipartHelper.java index ef07856..7155760 100644 --- a/src/main/java/net/shadowfacts/simplemultipart/util/MultipartHelper.java +++ b/src/main/java/net/shadowfacts/simplemultipart/util/MultipartHelper.java @@ -21,10 +21,22 @@ import net.shadowfacts.simplemultipart.multipart.MultipartState; import java.util.*; /** + * Helper methods relating to multiparts. + * * @author shadowfacts + * @since 0.1.0 */ public class MultipartHelper { + /** + * Performs a ray trace to determine the hit multipart. + * + * @param container The container being ray traced in. + * @param world The world. + * @param pos The position of the container. + * @param player The player performing the ray trace. + * @return A hit result for the hit multipart. {@ode null} if not part was hit. + */ public static MultipartHitResult rayTrace(MultipartContainer container, World world, BlockPos pos, PlayerEntity player) { // copied from BoatItem::use float var6 = MathHelper.lerp(1.0F, player.prevPitch, player.pitch); @@ -45,6 +57,16 @@ public class MultipartHelper { return rayTrace(container, world, pos, start, end); } + /** + * Performs a ray trace to determine the hit multipart. + * + * @param container The container being ray traced in. + * @param world The world. + * @param pos The position of the container. + * @param start The start position for the ray. + * @param end The end position for the ray. + * @return A hit result for the hit multipart. {@code null} if no part was hit. + */ public static MultipartHitResult rayTrace(MultipartContainer container, World world, BlockPos pos, Vec3d start, Vec3d end) { return container.getParts().stream() .map(view -> { @@ -57,6 +79,12 @@ public class MultipartHelper { .orElse(null); } + /** + * Creates a NBT representation of the given multipart state. + * + * @param state The multipart state. + * @return A compound tag containing the multipart and it's property values. + */ public static CompoundTag serializeMultipartState(MultipartState state) { CompoundTag tag = new CompoundTag(); tag.putString("Name", SimpleMultipart.MULTIPART.getId(state.getMultipart()).toString()); @@ -81,6 +109,13 @@ public class MultipartHelper { return property.getValueAsString(state.get(property)); } + /** + * Retrieves the multipart state specified by the given tag. + * + * @param tag A tag containing the multipart information. + * Generated by {@link MultipartHelper#serializeMultipartState(MultipartState)} + * @return The multipart state represented by the tag. + */ public static MultipartState deserializeMultipartState(CompoundTag tag) { if (!tag.containsKey("Name", 8)) { return null; diff --git a/src/main/java/net/shadowfacts/simplemultipart/util/MultipartHitResult.java b/src/main/java/net/shadowfacts/simplemultipart/util/MultipartHitResult.java index 93287de..a06149d 100644 --- a/src/main/java/net/shadowfacts/simplemultipart/util/MultipartHitResult.java +++ b/src/main/java/net/shadowfacts/simplemultipart/util/MultipartHitResult.java @@ -1,16 +1,26 @@ package net.shadowfacts.simplemultipart.util; +import net.minecraft.entity.player.PlayerEntity; import net.minecraft.util.HitResult; import net.minecraft.util.math.BlockPos; import net.minecraft.util.math.Direction; import net.minecraft.util.math.Vec3d; +import net.minecraft.world.World; +import net.shadowfacts.simplemultipart.container.MultipartContainer; import net.shadowfacts.simplemultipart.multipart.MultipartView; /** + * A raytrace result for a multipart. + * * @author shadowfacts + * @since 0.1.0 + * @see MultipartHelper#rayTrace(MultipartContainer, World, BlockPos, PlayerEntity) */ public class MultipartHitResult extends HitResult { + /** + * The view of the hit multipart. + */ public MultipartView view; public MultipartHitResult(Vec3d pos, Direction side, BlockPos blockPos, MultipartView view) { diff --git a/src/main/java/net/shadowfacts/simplemultipart/util/MultipartPlacementContext.java b/src/main/java/net/shadowfacts/simplemultipart/util/MultipartPlacementContext.java index b3e1677..eedc4c3 100644 --- a/src/main/java/net/shadowfacts/simplemultipart/util/MultipartPlacementContext.java +++ b/src/main/java/net/shadowfacts/simplemultipart/util/MultipartPlacementContext.java @@ -8,7 +8,12 @@ import net.minecraft.util.math.Direction; import net.shadowfacts.simplemultipart.container.MultipartContainer; /** + * Contains information about the context in which a multipart is being placed into the world. + * + * Analogous to {@link net.minecraft.item.ItemPlacementContext}. + * * @author shadowfacts + * @since 0.1.0 */ public class MultipartPlacementContext extends ItemUsageContext { @@ -23,6 +28,9 @@ public class MultipartPlacementContext extends ItemUsageContext { this(container, context.getPlayer(), context.getItemStack(), context.getPos(), context.getFacing(), context.getHitX(), context.getHitY(), context.getHitZ()); } + /** + * @return The container that this multipart will be inserted into. + */ public MultipartContainer getContainer() { return container; }