Add JavaDocs

This commit is contained in:
Shadowfacts 2018-12-28 13:10:59 -05:00
parent 9de6875866
commit ab3b81eac9
Signed by: shadowfacts
GPG Key ID: 94A5AB95422746E5
12 changed files with 286 additions and 13 deletions

View File

@ -10,11 +10,27 @@ import java.util.List;
import java.util.Random; 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 * @author shadowfacts
* @since 0.1.0
*/ */
public interface MultipartBakedModel extends BakedModel { public interface MultipartBakedModel extends BakedModel {
List<BakedQuad> 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<BakedQuad> getMultipartQuads(/*@Nullable*/ MultipartView view, Direction side, Random random);
@Override @Override
default List<BakedQuad> getQuads(BlockState state, Direction side, Random random) { default List<BakedQuad> getQuads(BlockState state, Direction side, Random random) {

View File

@ -107,16 +107,6 @@ public class MultipartModelProvider implements ModelProvider {
return model; return model;
} }
// private StateFactory<Block, BlockState> getStateFactory(class_816 multipartUnbakedModel) {
// try {
// Field f = class_816.class.getDeclaredField("field_4329");
// f.setAccessible(true);
// return (StateFactory<Block, BlockState>)f.get(multipartUnbakedModel);
// } catch (ReflectiveOperationException e) {
// throw new RuntimeException(e);
// }
// }
private ModelVariantMap loadPartVariantMap(MultipartFakeBlock blockAdapter, Identifier partStateDefId) throws IOException { private ModelVariantMap loadPartVariantMap(MultipartFakeBlock blockAdapter, Identifier partStateDefId) throws IOException {
Resource resource = null; Resource resource = null;
Reader reader = null; Reader reader = null;

View File

@ -6,20 +6,58 @@ import net.shadowfacts.simplemultipart.multipart.MultipartState;
import java.util.Set; 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 * @author shadowfacts
* @since 0.1.0
*/ */
public interface MultipartContainer { public interface MultipartContainer {
/**
* Retrieves all the multiparts held by this container.
*
* @see MultipartView
* @return All multiparts held by this container.
*/
Set<MultipartView> getParts(); Set<MultipartView> 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); boolean canInsert(MultipartState state);
/**
* Performs the insertion of the given multipart into this container.
*
* @param state The new multipart state.
*/
void insert(MultipartState state); void insert(MultipartState state);
/**
* Removes the given multipart from this container.
*
* @see MultipartView
* @param view The part to remove
*/
void remove(MultipartView view); 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); 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(); void schedulePartSave();
} }

View File

@ -11,13 +11,19 @@ import net.shadowfacts.simplemultipart.multipart.MultipartState;
import net.shadowfacts.simplemultipart.util.MultipartPlacementContext; import net.shadowfacts.simplemultipart.util.MultipartPlacementContext;
/** /**
* An {@link Item} implementation that handles placing multiparts.
*
* Analogous to {@link net.minecraft.item.block.BlockItem}.
*
* @author shadowfacts * @author shadowfacts
* @since 0.1.0
*/ */
public class ItemMultipart extends Item { public class ItemMultipart extends Item {
protected Multipart part; protected Multipart part;
public ItemMultipart(Multipart part) { public ItemMultipart(Multipart part) {
// TODO: expose settings object?
super(new Settings()); super(new Settings());
this.part = part; this.part = part;
} }
@ -27,6 +33,15 @@ public class ItemMultipart extends Item {
return tryPlace(context); 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) { protected ActionResult tryPlace(ItemUsageContext context) {
// If a multipart inside an existing container was clicked, try inserting into that // If a multipart inside an existing container was clicked, try inserting into that
MultipartContainer hitContainer = getContainer(context); MultipartContainer hitContainer = getContainer(context);
@ -65,6 +80,12 @@ public class ItemMultipart extends Item {
return container; 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) { protected boolean tryPlace(MultipartPlacementContext context) {
MultipartState placementState = part.getPlacementState(context); MultipartState placementState = part.getPlacementState(context);

View File

@ -7,6 +7,7 @@ import net.minecraft.server.world.ServerWorld;
import net.minecraft.state.StateFactory; import net.minecraft.state.StateFactory;
import net.minecraft.util.Hand; import net.minecraft.util.Hand;
import net.minecraft.util.Identifier; import net.minecraft.util.Identifier;
import net.minecraft.util.math.Direction;
import net.minecraft.util.shape.VoxelShape; import net.minecraft.util.shape.VoxelShape;
import net.minecraft.world.loot.LootSupplier; import net.minecraft.world.loot.LootSupplier;
import net.minecraft.world.loot.LootTables; import net.minecraft.world.loot.LootTables;
@ -15,9 +16,15 @@ import net.shadowfacts.simplemultipart.SimpleMultipart;
import net.shadowfacts.simplemultipart.util.MultipartPlacementContext; import net.shadowfacts.simplemultipart.util.MultipartPlacementContext;
import java.util.List; import java.util.List;
import java.util.Random;
/** /**
* The base class for a multipart object.
*
* Analogous to {@link net.minecraft.block.Block}.
*
* @author shadowfacts * @author shadowfacts
* @since 0.1.0
*/ */
public abstract class Multipart { public abstract class Multipart {
@ -26,6 +33,7 @@ public abstract class Multipart {
private Identifier dropTableId; private Identifier dropTableId;
// TODO: Settings object?
public Multipart() { public Multipart() {
StateFactory.Builder<Multipart, MultipartState> builder = new StateFactory.Builder<>(this); StateFactory.Builder<Multipart, MultipartState> builder = new StateFactory.Builder<>(this);
appendProperties(builder); appendProperties(builder);
@ -33,26 +41,55 @@ public abstract class Multipart {
defaultState = stateFactory.getDefaultState(); defaultState = stateFactory.getDefaultState();
} }
/**
* Used to add additional properties to the state factory.
* @param builder The state factory builder.
*/
protected void appendProperties(StateFactory.Builder<Multipart, MultipartState> builder) {} protected void appendProperties(StateFactory.Builder<Multipart, MultipartState> builder) {}
/**
* @return The default state for this multipart.
*/
public MultipartState getDefaultState() { public MultipartState getDefaultState() {
return defaultState; return defaultState;
} }
/**
* Sets a new default state for this multipart.
* @param defaultState The new default state.
*/
public void setDefaultState(MultipartState defaultState) { public void setDefaultState(MultipartState defaultState) {
this.defaultState = defaultState; this.defaultState = defaultState;
} }
/**
* @return The state factory for this multipart.
*/
public StateFactory<Multipart, MultipartState> getStateFactory() { public StateFactory<Multipart, MultipartState> getStateFactory() {
return stateFactory; 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) { public MultipartState getPlacementState(MultipartPlacementContext context) {
return getDefaultState(); 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} * 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 @Deprecated
public MultipartState getStateForRendering(MultipartState state, MultipartView view) { 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} * 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 @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() { public Identifier getDropTableId() {
if (dropTableId == null) { if (dropTableId == null) {
Identifier id = SimpleMultipart.MULTIPART.getId(this); 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)} * 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 @Deprecated
public List<ItemStack> getDroppedStacks(MultipartState state, MultipartView view, LootContext.Builder builder) { public List<ItemStack> 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} * 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 @Deprecated
public boolean activate(MultipartState state, MultipartView view, PlayerEntity player, Hand hand) { public boolean activate(MultipartState state, MultipartView view, PlayerEntity player, Hand hand) {

View File

@ -12,7 +12,12 @@ import net.minecraft.world.loot.context.LootContext;
import java.util.List; import java.util.List;
/** /**
* A container for a {@link Multipart} and its associated properties/values.
*
* Analogous to {@link net.minecraft.block.BlockState}.
*
* @author shadowfacts * @author shadowfacts
* @since 0.1.0
*/ */
public class MultipartState extends AbstractPropertyContainer<Multipart, MultipartState> { public class MultipartState extends AbstractPropertyContainer<Multipart, MultipartState> {
@ -20,25 +25,40 @@ public class MultipartState extends AbstractPropertyContainer<Multipart, Multipa
super(part, properties); super(part, properties);
} }
/**
* @return The multipart object for this state.
*/
public Multipart getMultipart() { public Multipart getMultipart() {
return owner; return owner;
} }
/**
* @see Multipart#getStateForRendering(MultipartState, MultipartView)
*/
public MultipartState getStateForRendering(MultipartView view) { public MultipartState getStateForRendering(MultipartView view) {
//noinspection deprecation //noinspection deprecation
return owner.getStateForRendering(this, view); return owner.getStateForRendering(this, view);
} }
/**
* @see Multipart#getBoundingShape(MultipartState, MultipartView)
*/
public VoxelShape getBoundingShape(/*@Nullable*/ MultipartView view) { public VoxelShape getBoundingShape(/*@Nullable*/ MultipartView view) {
//noinspection deprecation //noinspection deprecation
return owner.getBoundingShape(this, view); return owner.getBoundingShape(this, view);
} }
/**
* @see Multipart#getDroppedStacks(MultipartState, MultipartView, LootContext.Builder)
*/
public List<ItemStack> getDroppedStacks(MultipartView view, LootContext.Builder builder) { public List<ItemStack> getDroppedStacks(MultipartView view, LootContext.Builder builder) {
//noinspection deprecated //noinspection deprecated
return owner.getDroppedStacks(this, view, builder); return owner.getDroppedStacks(this, view, builder);
} }
/**
* @see Multipart#activate(MultipartState, MultipartView, PlayerEntity, Hand)
*/
public boolean activate(MultipartView view, PlayerEntity player, Hand hand) { public boolean activate(MultipartView view, PlayerEntity player, Hand hand) {
//noinspection deprecated //noinspection deprecated
return owner.activate(this, view, player, hand); return owner.activate(this, view, player, hand);

View File

@ -6,21 +6,55 @@ import net.shadowfacts.simplemultipart.multipart.MultipartState;
import net.shadowfacts.simplemultipart.multipart.entity.MultipartEntity; import net.shadowfacts.simplemultipart.multipart.entity.MultipartEntity;
/** /**
* A view of a multipart and its (optional) associated entity.
*
* @author shadowfacts * @author shadowfacts
* @since 0.1.0
*/ */
// TODO: better name for this // TODO: better name for this
public interface MultipartView { public interface MultipartView {
/**
* @return The container holding this part.
*/
MultipartContainer getContainer(); MultipartContainer getContainer();
/**
* @return The current state of this multipart.
*/
MultipartState getState(); 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 <b>not</b> cause the associated entity to change.
*
* @param state The new state.
*/
void setState(MultipartState 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); void setEntity(MultipartEntity entity);
/**
* Helper method for retrieving the multipart object for the current state.
* @return The current multipart.
*/
default Multipart getMultipart() { default Multipart getMultipart() {
return getState().getMultipart(); return getState().getMultipart();
} }

View File

@ -4,24 +4,50 @@ import net.minecraft.nbt.CompoundTag;
import net.shadowfacts.simplemultipart.container.MultipartContainer; 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 * @author shadowfacts
* @since 0.1.0
*/ */
public abstract class MultipartEntity { public abstract class MultipartEntity {
/**
* The container holding this multipart entity.
*/
// TODO: change this to a view?
public MultipartContainer container; public MultipartContainer container;
public MultipartEntity(MultipartContainer container) { public MultipartEntity(MultipartContainer container) {
this.container = container; this.container = container;
} }
/**
* Calling this indicates that something about this entity has changed that necessitates saving it to disk.
*/
protected void scheduleSave() { protected void scheduleSave() {
container.schedulePartSave(); 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) { public CompoundTag toTag(CompoundTag tag) {
return 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) { public void fromTag(CompoundTag tag) {
} }

View File

@ -4,10 +4,22 @@ import net.shadowfacts.simplemultipart.container.MultipartContainer;
import net.shadowfacts.simplemultipart.multipart.MultipartState; 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 * @author shadowfacts
* @since 0.1.0
*/ */
public interface MultipartEntityProvider { 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*/ /*@Nullable*/
MultipartEntity createMultipartEntity(MultipartState state, MultipartContainer container); MultipartEntity createMultipartEntity(MultipartState state, MultipartContainer container);

View File

@ -21,10 +21,22 @@ import net.shadowfacts.simplemultipart.multipart.MultipartState;
import java.util.*; import java.util.*;
/** /**
* Helper methods relating to multiparts.
*
* @author shadowfacts * @author shadowfacts
* @since 0.1.0
*/ */
public class MultipartHelper { 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) { public static MultipartHitResult rayTrace(MultipartContainer container, World world, BlockPos pos, PlayerEntity player) {
// copied from BoatItem::use // copied from BoatItem::use
float var6 = MathHelper.lerp(1.0F, player.prevPitch, player.pitch); float var6 = MathHelper.lerp(1.0F, player.prevPitch, player.pitch);
@ -45,6 +57,16 @@ public class MultipartHelper {
return rayTrace(container, world, pos, start, end); 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) { public static MultipartHitResult rayTrace(MultipartContainer container, World world, BlockPos pos, Vec3d start, Vec3d end) {
return container.getParts().stream() return container.getParts().stream()
.map(view -> { .map(view -> {
@ -57,6 +79,12 @@ public class MultipartHelper {
.orElse(null); .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) { public static CompoundTag serializeMultipartState(MultipartState state) {
CompoundTag tag = new CompoundTag(); CompoundTag tag = new CompoundTag();
tag.putString("Name", SimpleMultipart.MULTIPART.getId(state.getMultipart()).toString()); tag.putString("Name", SimpleMultipart.MULTIPART.getId(state.getMultipart()).toString());
@ -81,6 +109,13 @@ public class MultipartHelper {
return property.getValueAsString(state.get(property)); 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) { public static MultipartState deserializeMultipartState(CompoundTag tag) {
if (!tag.containsKey("Name", 8)) { if (!tag.containsKey("Name", 8)) {
return null; return null;

View File

@ -1,16 +1,26 @@
package net.shadowfacts.simplemultipart.util; package net.shadowfacts.simplemultipart.util;
import net.minecraft.entity.player.PlayerEntity;
import net.minecraft.util.HitResult; import net.minecraft.util.HitResult;
import net.minecraft.util.math.BlockPos; import net.minecraft.util.math.BlockPos;
import net.minecraft.util.math.Direction; import net.minecraft.util.math.Direction;
import net.minecraft.util.math.Vec3d; import net.minecraft.util.math.Vec3d;
import net.minecraft.world.World;
import net.shadowfacts.simplemultipart.container.MultipartContainer;
import net.shadowfacts.simplemultipart.multipart.MultipartView; import net.shadowfacts.simplemultipart.multipart.MultipartView;
/** /**
* A raytrace result for a multipart.
*
* @author shadowfacts * @author shadowfacts
* @since 0.1.0
* @see MultipartHelper#rayTrace(MultipartContainer, World, BlockPos, PlayerEntity)
*/ */
public class MultipartHitResult extends HitResult { public class MultipartHitResult extends HitResult {
/**
* The view of the hit multipart.
*/
public MultipartView view; public MultipartView view;
public MultipartHitResult(Vec3d pos, Direction side, BlockPos blockPos, MultipartView view) { public MultipartHitResult(Vec3d pos, Direction side, BlockPos blockPos, MultipartView view) {

View File

@ -8,7 +8,12 @@ import net.minecraft.util.math.Direction;
import net.shadowfacts.simplemultipart.container.MultipartContainer; 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 * @author shadowfacts
* @since 0.1.0
*/ */
public class MultipartPlacementContext extends ItemUsageContext { 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()); 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() { public MultipartContainer getContainer() {
return container; return container;
} }