+ * * Note that {@link IEnergyHandler} is an extension of this. * * @author King Lemming - * */ public interface IEnergyConnection { diff --git a/src/main/java/cofh/api/energy/IEnergyContainerItem.java b/src/main/java/cofh/api/energy/IEnergyContainerItem.java index 3ef725765..abc742fde 100644 --- a/src/main/java/cofh/api/energy/IEnergyContainerItem.java +++ b/src/main/java/cofh/api/energy/IEnergyContainerItem.java @@ -4,23 +4,19 @@ import net.minecraft.item.ItemStack; /** * Implement this interface on Item classes that support external manipulation of their internal energy storages. - *
+ * * A reference implementation is provided {@link ItemEnergyContainer}. * * @author King Lemming - * */ public interface IEnergyContainerItem { /** * Adds energy to a container item. Returns the quantity of energy that was accepted. This should always return 0 if the item cannot be externally charged. * - * @param container - * ItemStack to be charged. - * @param maxReceive - * Maximum amount of energy to be sent into the item. - * @param simulate - * If TRUE, the charge will only be simulated. + * @param container ItemStack to be charged. + * @param maxReceive Maximum amount of energy to be sent into the item. + * @param simulate If TRUE, the charge will only be simulated. * @return Amount of energy that was (or would have been, if simulated) received by the item. */ int receiveEnergy(ItemStack container, int maxReceive, boolean simulate); @@ -29,12 +25,9 @@ public interface IEnergyContainerItem { * Removes energy from a container item. Returns the quantity of energy that was removed. This should always return 0 if the item cannot be externally * discharged. * - * @param container - * ItemStack to be discharged. - * @param maxExtract - * Maximum amount of energy to be extracted from the item. - * @param simulate - * If TRUE, the discharge will only be simulated. + * @param container ItemStack to be discharged. + * @param maxExtract Maximum amount of energy to be extracted from the item. + * @param simulate If TRUE, the discharge will only be simulated. * @return Amount of energy that was (or would have been, if simulated) extracted from the item. */ int extractEnergy(ItemStack container, int maxExtract, boolean simulate); diff --git a/src/main/java/cofh/api/energy/IEnergyHandler.java b/src/main/java/cofh/api/energy/IEnergyHandler.java index 16b236e7a..e03783e47 100644 --- a/src/main/java/cofh/api/energy/IEnergyHandler.java +++ b/src/main/java/cofh/api/energy/IEnergyHandler.java @@ -4,13 +4,12 @@ import net.minecraft.util.EnumFacing; /** * Implement this interface on Tile Entities which should handle energy, generally storing it in one or more internal {@link IEnergyStorage} objects. - *
+ * * A reference implementation is provided {@link TileEnergyHandler}. - *
+ * * Note that {@link IEnergyReceiver} and {@link IEnergyProvider} are extensions of this. * * @author King Lemming - * */ public interface IEnergyHandler extends IEnergyConnection { diff --git a/src/main/java/cofh/api/energy/IEnergyProvider.java b/src/main/java/cofh/api/energy/IEnergyProvider.java index ef0e09d06..da704806f 100644 --- a/src/main/java/cofh/api/energy/IEnergyProvider.java +++ b/src/main/java/cofh/api/energy/IEnergyProvider.java @@ -2,26 +2,21 @@ package cofh.api.energy; import net.minecraft.util.EnumFacing; - /** * Implement this interface on Tile Entities which should provide energy, generally storing it in one or more internal {@link IEnergyStorage} objects. - *
+ * * A reference implementation is provided {@link TileEnergyHandler}. * * @author King Lemming - * */ public interface IEnergyProvider extends IEnergyHandler { /** * Remove energy from an IEnergyProvider, internal distribution is left entirely to the IEnergyProvider. * - * @param from - * Orientation the energy is extracted from. - * @param maxExtract - * Maximum amount of energy to extract. - * @param simulate - * If TRUE, the extraction will only be simulated. + * @param from Orientation the energy is extracted from. + * @param maxExtract Maximum amount of energy to extract. + * @param simulate If TRUE, the extraction will only be simulated. * @return Amount of energy that was (or would have been, if simulated) extracted. */ int extractEnergy(EnumFacing from, int maxExtract, boolean simulate); diff --git a/src/main/java/cofh/api/energy/IEnergyReceiver.java b/src/main/java/cofh/api/energy/IEnergyReceiver.java index 989e9baa5..5299827f6 100644 --- a/src/main/java/cofh/api/energy/IEnergyReceiver.java +++ b/src/main/java/cofh/api/energy/IEnergyReceiver.java @@ -2,26 +2,21 @@ package cofh.api.energy; import net.minecraft.util.EnumFacing; - /** * Implement this interface on Tile Entities which should receive energy, generally storing it in one or more internal {@link IEnergyStorage} objects. - *
+ *
* A reference implementation is provided {@link TileEnergyHandler}.
*
* @author King Lemming
- *
*/
public interface IEnergyReceiver extends IEnergyHandler {
/**
* Add energy to an IEnergyReceiver, internal distribution is left entirely to the IEnergyReceiver.
*
- * @param from
- * Orientation the energy is received from.
- * @param maxReceive
- * Maximum amount of energy to receive.
- * @param simulate
- * If TRUE, the charge will only be simulated.
+ * @param from Orientation the energy is received from.
+ * @param maxReceive Maximum amount of energy to receive.
+ * @param simulate If TRUE, the charge will only be simulated.
* @return Amount of energy that was (or would have been, if simulated) received.
*/
int receiveEnergy(EnumFacing from, int maxReceive, boolean simulate);
diff --git a/src/main/java/cofh/api/energy/IEnergyStorage.java b/src/main/java/cofh/api/energy/IEnergyStorage.java
index 414b26566..1349c6717 100644
--- a/src/main/java/cofh/api/energy/IEnergyStorage.java
+++ b/src/main/java/cofh/api/energy/IEnergyStorage.java
@@ -3,21 +3,18 @@ package cofh.api.energy;
/**
* An energy storage is the unit of interaction with Energy inventories.
* This is not to be implemented on TileEntities. This is for internal use only.
- *
+ *
* A reference implementation can be found at {@link EnergyStorage}.
*
* @author King Lemming
- *
*/
public interface IEnergyStorage {
/**
* Adds energy to the storage. Returns quantity of energy that was accepted.
*
- * @param maxReceive
- * Maximum amount of energy to be inserted.
- * @param simulate
- * If TRUE, the insertion will only be simulated.
+ * @param maxReceive Maximum amount of energy to be inserted.
+ * @param simulate If TRUE, the insertion will only be simulated.
* @return Amount of energy that was (or would have been, if simulated) accepted by the storage.
*/
int receiveEnergy(int maxReceive, boolean simulate);
@@ -25,10 +22,8 @@ public interface IEnergyStorage {
/**
* Removes energy from the storage. Returns quantity of energy that was removed.
*
- * @param maxExtract
- * Maximum amount of energy to be extracted.
- * @param simulate
- * If TRUE, the extraction will only be simulated.
+ * @param maxExtract Maximum amount of energy to be extracted.
+ * @param simulate If TRUE, the extraction will only be simulated.
* @return Amount of energy that was (or would have been, if simulated) extracted from the storage.
*/
int extractEnergy(int maxExtract, boolean simulate);
diff --git a/src/main/java/cofh/api/energy/IEnergyTransport.java b/src/main/java/cofh/api/energy/IEnergyTransport.java
new file mode 100644
index 000000000..ebc7d921f
--- /dev/null
+++ b/src/main/java/cofh/api/energy/IEnergyTransport.java
@@ -0,0 +1,106 @@
+package cofh.api.energy;
+
+import net.minecraft.util.EnumFacing;
+
+/**
+ * Implement this interface on Tile Entities which transport energy.
+ *
+ * This is used to "negotiate" connection types between two separate IEnergyTransports, allowing users to set flow direction and allowing for networks Of
+ * IEnergyTransports to intelligently transfer energy to other networks.
+ */
+public interface IEnergyTransport extends IEnergyProvider, IEnergyReceiver {
+
+ /**
+ * The type of interface for a given side of a {@link IEnergyTransport}.
+ *
+ * Values are:
+ * {@link SEND} for sending only
+ * {@link RECEIVE} for receiving only
+ * {@link BALANCE} for sending and receiving, and the default state
+ */
+ enum InterfaceType {
+ /**
+ * Indicates that this {@link IEnergyTransport} is only sending power on this side.
+ */
+ SEND, /**
+ * Indicates that this {@link IEnergyTransport} is only receiving power on this side.
+ */
+ RECEIVE, /**
+ * Indicates that this {@link IEnergyTransport} wants to balance power between itself and the
+ * senders/receivers on this side. This is the default state.
+ * To block any connection, use {@link IEnergyConnection#canConnectEnergy}
+ *
+ * IEnergyTransport based senders should check that the total power in the destination IEnergyTransport is less than the power in themselves before sending.
+ *
+ * Active IEnergyTransport receivers (i.e., those that call {@link IEnergyProvider#extractEnergy}) should check that they contain less power than the
+ * source IEnergyTransport.
+ */
+ BALANCE;
+
+ /**
+ * Returns the opposite state to this InterfaceType.
+ *
+ * {@link #BALANCE} is considered its own opposite.
+ * {@link #SEND} is the opposite of {@link #RECEIVE} and visa versa.
+ */
+ public InterfaceType getOpposite() {
+
+ return this == BALANCE ? BALANCE : this == SEND ? RECEIVE : SEND;
+ }
+
+ /**
+ * Returns the next InterfaceType as described in {@link IEnergyTransport#getTransportState}
+ */
+ public InterfaceType rotate() {
+
+ return rotate(true);
+ }
+
+ /**
+ * Returns the next InterfaceType as described in {@link IEnergyTransport#getTransportState}
+ *
+ * @param forward Whether to step in the order specified by {@link IEnergyTransport#getTransportState} (true) or to step in the opposite direction
+ */
+ public InterfaceType rotate(boolean forward) {
+
+ if (forward) {
+ return this == BALANCE ? RECEIVE : this == RECEIVE ? SEND : BALANCE;
+ } else {
+ return this == BALANCE ? SEND : this == SEND ? RECEIVE : BALANCE;
+ }
+ }
+ }
+
+ /**
+ * {@inheritDoc}
+ * This method cannot be a no-op for IEnergyTransport.
+ */
+ @Override
+ int getEnergyStored(EnumFacing from);
+
+ /**
+ * Indicates to other IEnergyTransports the state of the given side. See {@link #InterfaceType} for details.
+ *
+ * For clarity of state tracking, on a tile update from another IEnergyTransport, if its mode has changed from the opposite of your own mode on that side, you
+ * should change your mode to the opposite of its mode.
+ *
+ * When the user alters your mode and your state is:
+ * BALANCE, your mode should change to {@link InterFaceType#RECEIVE}.
+ * RECEIVE, your mode should change to {@link InterFaceType#SEND}.
+ * SEND, your mode should change to {@link InterFaceType#BALANCE}.
+ * This is not required, but will be easier for users.
+ *
+ * @return The type of connection to establish on this side. null is NOT a valid value
+ */
+ InterfaceType getTransportState(EnumFacing from);
+
+ /**
+ * This method is provided primarily for the purposes of automation tools, and should not need to be called by another IEnergyTransport.
+ *
+ * Calls to this method may fail if this IEnergyTransport has been secured by a user.
+ *
+ * @return Whether or not state was successfully altered.
+ */
+ boolean setTransportState(InterfaceType state, EnumFacing from);
+
+}
diff --git a/src/main/java/cofh/api/energy/ItemEnergyContainer.java b/src/main/java/cofh/api/energy/ItemEnergyContainer.java
index 0fb36dab6..7705c76c0 100644
--- a/src/main/java/cofh/api/energy/ItemEnergyContainer.java
+++ b/src/main/java/cofh/api/energy/ItemEnergyContainer.java
@@ -8,7 +8,6 @@ import net.minecraft.nbt.NBTTagCompound;
* Reference implementation of {@link IEnergyContainerItem}. Use/extend this or implement your own.
*
* @author King Lemming
- *
*/
public class ItemEnergyContainer extends Item implements IEnergyContainerItem {
@@ -43,20 +42,20 @@ public class ItemEnergyContainer extends Item implements IEnergyContainerItem {
return this;
}
- public ItemEnergyContainer setMaxTransfer(int maxTransfer) {
+ public ItemEnergyContainer setMaxTransfer(int maxTransfer) {
setMaxReceive(maxTransfer);
setMaxExtract(maxTransfer);
return this;
}
- public ItemEnergyContainer setMaxReceive(int maxReceive) {
+ public ItemEnergyContainer setMaxReceive(int maxReceive) {
this.maxReceive = maxReceive;
return this;
}
- public ItemEnergyContainer setMaxExtract(int maxExtract) {
+ public ItemEnergyContainer setMaxExtract(int maxExtract) {
this.maxExtract = maxExtract;
return this;
diff --git a/src/main/java/cofh/api/energy/TileEnergyHandler.java b/src/main/java/cofh/api/energy/TileEnergyHandler.java
new file mode 100644
index 000000000..d8415e24e
--- /dev/null
+++ b/src/main/java/cofh/api/energy/TileEnergyHandler.java
@@ -0,0 +1,67 @@
+package cofh.api.energy;
+
+import net.minecraft.nbt.NBTTagCompound;
+import net.minecraft.tileentity.TileEntity;
+import net.minecraft.util.EnumFacing;
+
+/**
+ * Reference implementation of {@link IEnergyReceiver} and {@link IEnergyProvider}. Use/extend this or implement your own.
+ *
+ * This class is really meant to summarize how each interface is properly used.
+ *
+ * @author King Lemming
+ */
+public class TileEnergyHandler extends TileEntity implements IEnergyReceiver, IEnergyProvider {
+
+ protected EnergyStorage storage = new EnergyStorage(32000);
+
+ @Override
+ public void readFromNBT(NBTTagCompound nbt) {
+
+ super.readFromNBT(nbt);
+ storage.readFromNBT(nbt);
+ }
+
+ @Override
+ public NBTTagCompound writeToNBT(NBTTagCompound nbt) {
+
+ super.writeToNBT(nbt);
+ storage.writeToNBT(nbt);
+ return nbt;
+ }
+
+ /* IEnergyConnection */
+ @Override
+ public boolean canConnectEnergy(EnumFacing from) {
+
+ return true;
+ }
+
+ /* IEnergyReceiver */
+ @Override
+ public int receiveEnergy(EnumFacing from, int maxReceive, boolean simulate) {
+
+ return storage.receiveEnergy(maxReceive, simulate);
+ }
+
+ /* IEnergyProvider */
+ @Override
+ public int extractEnergy(EnumFacing from, int maxExtract, boolean simulate) {
+
+ return storage.extractEnergy(maxExtract, simulate);
+ }
+
+ /* IEnergyHandler */
+ @Override
+ public int getEnergyStored(EnumFacing from) {
+
+ return storage.getEnergyStored();
+ }
+
+ @Override
+ public int getMaxEnergyStored(EnumFacing from) {
+
+ return storage.getMaxEnergyStored();
+ }
+
+}
diff --git a/src/main/java/cofh/api/energy/package-info.java b/src/main/java/cofh/api/energy/package-info.java
index da8566735..bf788ef51 100644
--- a/src/main/java/cofh/api/energy/package-info.java
+++ b/src/main/java/cofh/api/energy/package-info.java
@@ -1,10 +1,9 @@
/**
- * (C) 2014-2016 Team CoFH / CoFH / Cult of the Full Hub
+ * (C) 2014-2017 Team CoFH / CoFH / Cult of the Full Hub
* http://www.teamcofh.com
*/
-@API(apiVersion = CoFHAPIProps.VERSION, owner = "CoFHAPI", provides = "CoFHAPI|energy")
+@API (apiVersion = CoFHAPIProps.VERSION, owner = "cofhapi", provides = "cofhapi|energy")
package cofh.api.energy;
-import net.minecraftforge.fml.common.API;
import cofh.api.CoFHAPIProps;
-
+import net.minecraftforge.fml.common.API;
diff --git a/src/main/java/cofh/api/package-info.java b/src/main/java/cofh/api/package-info.java
index e2847daad..b12cff641 100644
--- a/src/main/java/cofh/api/package-info.java
+++ b/src/main/java/cofh/api/package-info.java
@@ -1,9 +1,8 @@
/**
- * (C) 2014-2016 Team CoFH / CoFH / Cult of the Full Hub
+ * (C) 2014-2017 Team CoFH / CoFH / Cult of the Full Hub
* http://www.teamcofh.com
*/
-@API(apiVersion = CoFHAPIProps.VERSION, owner = "CoFHLib", provides = "CoFHAPI")
+@API (apiVersion = CoFHAPIProps.VERSION, owner = "cofhlib", provides = "cofhapi")
package cofh.api;
import net.minecraftforge.fml.common.API;
-