diff --git a/illuaminate.sexp b/illuaminate.sexp index d020482f9..3922ec02b 100644 --- a/illuaminate.sexp +++ b/illuaminate.sexp @@ -93,9 +93,7 @@ /build/docs/luaJavadoc/speaker.lua /build/docs/luaJavadoc/printer.lua ; Generic peripherals - /build/docs/luaJavadoc/energy_storage.lua /build/docs/luaJavadoc/fluid_storage.lua - /build/docs/luaJavadoc/inventory.lua ; Lua APIs /src/main/resources/*/computercraft/lua/rom/apis/io.lua /src/main/resources/*/computercraft/lua/rom/apis/window.lua) diff --git a/src/main/java/dan200/computercraft/shared/peripheral/generic/methods/EnergyMethods.java b/src/main/java/dan200/computercraft/shared/peripheral/generic/methods/EnergyMethods.java index 6d0d705ff..5df9a7993 100644 --- a/src/main/java/dan200/computercraft/shared/peripheral/generic/methods/EnergyMethods.java +++ b/src/main/java/dan200/computercraft/shared/peripheral/generic/methods/EnergyMethods.java @@ -18,6 +18,13 @@ import javax.annotation.Nonnull; /** * Methods for interacting with blocks using Forge's energy storage system. * + * This works with energy storage blocks, as well as generators and machines which consume energy. + * + *
+ * Note: Due to limitations with Forge's energy API, it is not possible to measure throughput (i.e. RF + * used/generated per tick). + *
+ * * @cc.module energy_storage */ @AutoService( GenericSource.class ) @@ -30,12 +37,22 @@ public class EnergyMethods implements GenericSource return new ResourceLocation( ForgeVersion.MOD_ID, "energy" ); } + /** + * Get the energy of this block. + * + * @return The energy stored in this block, in FE. + */ @LuaFunction( mainThread = true ) public static int getEnergy( IEnergyStorage energy ) { return energy.getEnergyStored(); } + /** + * Get the maximum amount of energy this block can store. + * + * @return The energy capacity of this block. + */ @LuaFunction( mainThread = true ) public static int getEnergyCapacity( IEnergyStorage energy ) { diff --git a/src/main/java/dan200/computercraft/shared/peripheral/generic/methods/InventoryMethods.java b/src/main/java/dan200/computercraft/shared/peripheral/generic/methods/InventoryMethods.java index e2e5269c9..4c4864386 100644 --- a/src/main/java/dan200/computercraft/shared/peripheral/generic/methods/InventoryMethods.java +++ b/src/main/java/dan200/computercraft/shared/peripheral/generic/methods/InventoryMethods.java @@ -47,12 +47,30 @@ public class InventoryMethods implements GenericSource return new ResourceLocation( ForgeVersion.MOD_ID, "inventory" ); } + /** + * Get the size of this inventory. + * + * @return The number of slots in this inventory. + */ @LuaFunction( mainThread = true ) public static int size( IItemHandler inventory ) { return inventory.getSlots(); } + /** + * List all items in this inventory. This returns a table, with an entry for each slot. + * + * Each item in the inventory is represented by a table containing some basic information, much like + * {@link dan200.computercraft.shared.turtle.apis.TurtleAPI#getItemDetail} includes. More information can be fetched + * with {@link #getItemDetail}. + * + * The table is sparse, and so empty slots will be `nil` - it is recommended to loop over using `pairs` rather than + * `ipairs`. + * + * @return All items in this inventory. + * @cc.treturn { (table|nil)... } All items in this inventory. + */ @LuaFunction( mainThread = true ) public static Map> list( IItemHandler inventory ) { @@ -67,6 +85,15 @@ public class InventoryMethods implements GenericSource return result; } + /** + * Get detailed information about an item. + * + * @param slot The slot to get information about. + * @return Information about the item in this slot, or {@code nil} if not present. + * @throws LuaException If the slot is out of range. + * @cc.treturn table Information about the item in this slot, or {@code nil} if not present. + */ + @Nullable @LuaFunction( mainThread = true ) public static Map getItemDetail( IItemHandler inventory, int slot ) throws LuaException { @@ -76,6 +103,30 @@ public class InventoryMethods implements GenericSource return stack.isEmpty() ? null : ItemData.fill( new HashMap<>(), stack ); } + /** + * Push items from one inventory to another connected one. + * + * This allows you to push an item in an inventory to another inventory on the same wired network. Both + * inventories must attached to wired modems which are connected via a cable. + * + * @param toName The name of the peripheral/inventory to push to. This is the string given to @{peripheral.wrap}, + * and displayed by the wired modem. + * @param fromSlot The slot in the current inventory to move items to. + * @param limit The maximum number of items to move. Defaults to the current stack limit. + * @param toSlot The slot in the target inventory to move to. If not given, the item will be inserted into any slot. + * @return The number of transferred items. + * @throws LuaException If the peripheral to transfer to doesn't exist or isn't an inventory. + * @throws LuaException If either source or destination slot is out of range. + * + * @cc.see peripheral.getName Allows you to get the name of a @{peripheral.wrap|wrapped} peripheral. + * @cc.usage Wrap two chests, and push an item from one to another. + * 
{@code
+     * local chest_a = peripheral.wrap("minecraft:chest_0")
+     * local chest_b = peripheral.wrap("minecraft:chest_0")
+     *
+     * chest_a.pushItems(peripheral.getName(chest_b), 1)
+     * }
+ */ @LuaFunction( mainThread = true ) public static int pushItems( IItemHandler from, IComputerAccess computer, @@ -91,13 +142,37 @@ public class InventoryMethods implements GenericSource // Validate slots int actualLimit = limit.orElse( Integer.MAX_VALUE ); - if( actualLimit <= 0 ) throw new LuaException( "Limit must be > 0" ); assertBetween( fromSlot, 1, from.getSlots(), "From slot out of range (%s)" ); if( toSlot.isPresent() ) assertBetween( toSlot.get(), 1, to.getSlots(), "To slot out of range (%s)" ); + if( actualLimit <= 0 ) return 0; return moveItem( from, fromSlot - 1, to, toSlot.orElse( 0 ) - 1, actualLimit ); } + /** + * Pull items from a connected inventory into this one. + * + * This allows you to transfer items between inventories on the same wired network. Both this and the source + * inventory must attached to wired modems which are connected via a cable. + * + * @param fromName The name of the peripheral/inventory to pull from. This is the string given to @{peripheral.wrap}, + * and displayed by the wired modem. + * @param fromSlot The slot in the source inventory to move items from. + * @param limit The maximum number of items to move. Defaults to the current stack limit. + * @param toSlot The slot in current inventory to move to. If not given, the item will be inserted into any slot. + * @return The number of transferred items. + * @throws LuaException If the peripheral to transfer to doesn't exist or isn't an inventory. + * @throws LuaException If either source or destination slot is out of range. + * + * @cc.see peripheral.getName Allows you to get the name of a @{peripheral.wrap|wrapped} peripheral. + * @cc.usage Wrap two chests, and push an item from one to another. + * 
{@code
+     * local chest_a = peripheral.wrap("minecraft:chest_0")
+     * local chest_b = peripheral.wrap("minecraft:chest_0")
+     *
+     * chest_a.pullItems(peripheral.getName(chest_b), 1)
+     * }
+ */ @LuaFunction( mainThread = true ) public static int pullItems( IItemHandler to, IComputerAccess computer, @@ -113,10 +188,10 @@ public class InventoryMethods implements GenericSource // Validate slots int actualLimit = limit.orElse( Integer.MAX_VALUE ); - if( actualLimit <= 0 ) throw new LuaException( "Limit must be > 0" ); assertBetween( fromSlot, 1, from.getSlots(), "From slot out of range (%s)" ); if( toSlot.isPresent() ) assertBetween( toSlot.get(), 1, to.getSlots(), "To slot out of range (%s)" ); + if( actualLimit <= 0 ) return 0; return moveItem( from, fromSlot - 1, to, toSlot.orElse( 0 ) - 1, actualLimit ); }