diff --git a/doc/stub/turtle.lua b/doc/stub/turtle.lua index f5668f1ae..a2c0eef55 100644 --- a/doc/stub/turtle.lua +++ b/doc/stub/turtle.lua @@ -1 +1,13 @@ +--[[- Craft a recipe based on the turtle's inventory. + +The turtle's inventory should set up like a crafting grid. For instance, to +craft sticks, slots 1 and 5 should contain sticks. _All_ other slots should be +empty, including those outside the crafting "grid". + +@tparam[opt=64] number limit The maximum number of crafting steps to run. +@throws When limit is less than 1 or greater than 64. +@treturn[1] true If crafting succeeds. +@treturn[2] false If crafting fails. +@treturn string A string describing why crafting failed. +]] function craft(limit) end diff --git a/illuaminate.sexp b/illuaminate.sexp index 61f671582..22d222f7e 100644 --- a/illuaminate.sexp +++ b/illuaminate.sexp @@ -88,27 +88,16 @@ ;; Suppress warnings for currently undocumented modules. (at - (; Java APIs - /doc/stub/http.lua - /doc/stub/os.lua - /doc/stub/turtle.lua - /doc/stub/global.lua - ; Java generated APIs - /build/docs/luaJavadoc/turtle.lua - ; Peripherals - /build/docs/luaJavadoc/drive.lua - /build/docs/luaJavadoc/speaker.lua - /build/docs/luaJavadoc/printer.lua - ; Generic peripherals - /build/docs/luaJavadoc/fluid_storage.lua - ; Lua APIs + (; Lua APIs /src/main/resources/*/computercraft/lua/rom/apis/io.lua /src/main/resources/*/computercraft/lua/rom/apis/window.lua) (linters -doc:undocumented -doc:undocumented-arg -doc:undocumented-return)) -;; Suppress warnings for the BIOS using its own deprecated members for now. -(at /src/main/resources/*/computercraft/lua/bios.lua +;; Suppress warnings for various APIs using its own deprecated members. +(at + (/src/main/resources/*/computercraft/lua/bios.lua + /src/main/resources/*/computercraft/lua/rom/apis/turtle/turtle.lua) (linters -var:deprecated)) (at /src/test/resources/test-rom diff --git a/src/main/java/dan200/computercraft/shared/peripheral/generic/methods/FluidMethods.java b/src/main/java/dan200/computercraft/shared/peripheral/generic/methods/FluidMethods.java index a9d206f5a..9c994aa6e 100644 --- a/src/main/java/dan200/computercraft/shared/peripheral/generic/methods/FluidMethods.java +++ b/src/main/java/dan200/computercraft/shared/peripheral/generic/methods/FluidMethods.java @@ -45,6 +45,19 @@ public ResourceLocation id() return new ResourceLocation( ForgeVersion.MOD_ID, "fluid" ); } + /** + * Get all "tanks" in this fluid storage. + * + * Each tank either contains some amount of fluid or is empty. Tanks with fluids inside will return some basic + * information about the fluid, including its name and amount. + * + * The returned table is sparse, and so empty tanks will be `nil` - it is recommended to loop over using `pairs` + * rather than `ipairs`. + * + * @param fluids The current fluid handler. + * @return All tanks. + * @cc.treturn { (table|nil)... } All tanks in this fluid storage. + */ @LuaFunction( mainThread = true ) public static Map> tanks( IFluidHandler fluids ) { @@ -59,6 +72,22 @@ public ResourceLocation id() return result; } + /** + * Move a fluid from one fluid container to another connected one. + * + * This allows you to pull fluid in the current fluid container to another container on the same wired + * network. Both containers must attached to wired modems which are connected via a cable. + * + * @param from Container to move fluid from. + * @param computer The current computer. + * @param toName The name of the peripheral/container to push to. This is the string given to @{peripheral.wrap}, + * and displayed by the wired modem. + * @param limit The maximum amount of fluid to move. + * @param fluidName The fluid to move. If not given, an arbitrary fluid will be chosen. + * @return The amount of moved fluid. + * @throws LuaException If the peripheral to transfer to doesn't exist or isn't an fluid container. + * @cc.see peripheral.getName Allows you to get the name of a @{peripheral.wrap|wrapped} peripheral. + */ @LuaFunction( mainThread = true ) public static int pushFluid( IFluidHandler from, IComputerAccess computer, @@ -84,6 +113,22 @@ public static int pushFluid( : moveFluid( from, new FluidStack( fluid, actualLimit ), to ); } + /** + * Move a fluid from a connected fluid container into this oneone. + * + * This allows you to pull fluid in the current fluid container from another container on the same wired + * network. Both containers must attached to wired modems which are connected via a cable. + * + * @param to Container to move fluid to. + * @param computer The current computer. + * @param fromName The name of the peripheral/container to push to. This is the string given to @{peripheral.wrap}, + * and displayed by the wired modem. + * @param limit The maximum amount of fluid to move. + * @param fluidName The fluid to move. If not given, an arbitrary fluid will be chosen. + * @return The amount of moved fluid. + * @throws LuaException If the peripheral to transfer to doesn't exist or isn't an fluid container. + * @cc.see peripheral.getName Allows you to get the name of a @{peripheral.wrap|wrapped} peripheral. + */ @LuaFunction( mainThread = true ) public static int pullFluid( IFluidHandler to, IComputerAccess computer, 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 0663d66ad..64e342b30 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 @@ -65,8 +65,8 @@ public static int size( IItemHandler inventory ) * {@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`. + * The returned table is sparse, and so empty slots will be `nil` - it is recommended to loop over using `pairs` + * rather than `ipairs`. * * @param inventory The current inventory. * @return All items in this inventory. diff --git a/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java b/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java index 671c9a3b7..cd3862b07 100644 --- a/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java +++ b/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java @@ -371,18 +371,36 @@ public final MethodResult detectDown() return trackCommand( new TurtleDetectCommand( InteractDirection.DOWN ) ); } + /** + * Check if the block in front of the turtle is equal to the item in the currently selected slot. + * + * @return If the block and item are equal. + * @cc.treturn boolean If the block and item are equal. + */ @LuaFunction public final MethodResult compare() { return trackCommand( new TurtleCompareCommand( InteractDirection.FORWARD ) ); } + /** + * Check if the block above the turtle is equal to the item in the currently selected slot. + * + * @return If the block and item are equal. + * @cc.treturn boolean If the block and item are equal. + */ @LuaFunction public final MethodResult compareUp() { return trackCommand( new TurtleCompareCommand( InteractDirection.UP ) ); } + /** + * Check if the block below the turtle is equal to the item in the currently selected slot. + * + * @return If the block and item are equal. + * @cc.treturn boolean If the block and item are equal. + */ @LuaFunction public final MethodResult compareDown() { @@ -478,12 +496,57 @@ public final MethodResult suckDown( Optional count ) throws LuaExceptio return trackCommand( new TurtleSuckCommand( InteractDirection.DOWN, checkCount( count ) ) ); } + /** + * Get the maximum amount of fuel this turtle currently holds. + * + * @return The fuel level, or "unlimited". + * @cc.treturn[1] number The current amount of fuel a turtle this turtle has. + * @cc.treturn[2] "unlimited" If turtles do not consume fuel when moving. + * @see #getFuelLimit() + * @see #refuel(Optional) + */ @LuaFunction public final Object getFuelLevel() { return turtle.isFuelNeeded() ? turtle.getFuelLevel() : "unlimited"; } + /** + * Refuel this turtle. + * + * While most actions a turtle can perform (such as digging or placing blocks), moving consumes fuel from the + * turtle's internal buffer. If a turtle has no fuel, it will not move. + * + * {@link #refuel} refuels the turtle, consuming fuel items (such as coal or lava buckets) from the currently + * selected slot and converting them into energy. This finishes once the turtle is fully refuelled or all items have + * been consumed. + * + * @param countA The maximum number of items to consume. One can pass `0` to check if an item is combustable or not. + * @return If this turtle could be refuelled. + * @throws LuaException If the refuel count is out of range. + * @cc.treturn[1] true If the turtle was refuelled. + * @cc.treturn[2] false If the turtle was not refuelled. + * @cc.treturn[2] string The reason the turtle was not refuelled ( + * @cc.usage Refuel a turtle from the currently selected slot. + * 
{@code
+     * local level = turtle.getFuelLevel()
+     * if new_level == "unlimited" then error("Turtle does not need fuel", 0) end
+     *
+     * local ok, err = turtle.refuel()
+     * if ok then
+     *   local new_level = turtle.getFuelLevel()
+     *   print(("Refuelled %d, current level is %d"):format(new_level - level, new_level))
+     * else
+     *   printError(err)
+     * end}
+ * @cc.usage Check if the current item is a valid fuel source. + * 
{@code
+     * local is_fuel, reason = turtle.refuel(0)
+     * if not is_fuel then printError(reason) end
+     * }
+ * @see #getFuelLevel() + * @see #getFuelLimit() + */ @LuaFunction public final MethodResult refuel( Optional countA ) throws LuaException { @@ -492,12 +555,30 @@ public final MethodResult refuel( Optional countA ) throws LuaException return trackCommand( new TurtleRefuelCommand( count ) ); } + /** + * Compare the item in the currently selected slot to the item in another slot. + * + * @param slot The slot to compare to. + * @return If the items are the same. + * @throws LuaException If the slot is out of range. + * @cc.treturn boolean If the two items are equal. + */ @LuaFunction public final MethodResult compareTo( int slot ) throws LuaException { return trackCommand( new TurtleCompareToCommand( checkSlot( slot ) ) ); } + /** + * Move an item from the selected slot to another one. + * + * @param slotArg The slot to move this item to. + * @param countArg The maximum number of items to move. + * @return If the item was moved or not. + * @throws LuaException If the slot is out of range. + * @throws LuaException If the number of items is out of range. + * @cc.treturn boolean If some items were successfully moved. + */ @LuaFunction public final MethodResult transferTo( int slotArg, Optional countArg ) throws LuaException { @@ -518,18 +599,55 @@ public final int getSelectedSlot() return turtle.getSelectedSlot() + 1; } + /** + * Get the maximum amount of fuel this turtle can hold. + * + * By default, normal turtles have a limit of 20,000 and advanced turtles of 100,000. + * + * @return The limit, or "unlimited". + * @cc.treturn[1] number The maximum amount of fuel a turtle can hold. + * @cc.treturn[2] "unlimited" If turtles do not consume fuel when moving. + * @see #getFuelLevel() + * @see #refuel(Optional) + */ @LuaFunction public final Object getFuelLimit() { return turtle.isFuelNeeded() ? turtle.getFuelLimit() : "unlimited"; } + /** + * Equip (or unequip) an item on the left side of this turtle. + * + * This finds the item in the currently selected slot and attempts to equip it to the left side of the turtle. The + * previous upgrade is removed and placed into the turtle's inventory. If there is no item in the slot, the previous + * upgrade is removed, but no new one is equipped. + * + * @return Whether an item was equiped or not. + * @cc.treturn[1] true If the item was equipped. + * @cc.treturn[2] false If we could not equip the item. + * @cc.treturn[2] string The reason equipping this item failed. + * @see #equipRight() + */ @LuaFunction public final MethodResult equipLeft() { return trackCommand( new TurtleEquipCommand( TurtleSide.LEFT ) ); } + /** + * Equip (or unequip) an item on the right side of this turtle. + * + * This finds the item in the currently selected slot and attempts to equip it to the right side of the turtle. The + * previous upgrade is removed and placed into the turtle's inventory. If there is no item in the slot, the previous + * upgrade is removed, but no new one is equipped. + * + * @return Whether an item was equiped or not. + * @cc.treturn[1] true If the item was equipped. + * @cc.treturn[2] false If we could not equip the item. + * @cc.treturn[2] string The reason equipping this item failed. + * @see #equipRight() + */ @LuaFunction public final MethodResult equipRight() { diff --git a/src/main/resources/data/computercraft/lua/rom/apis/turtle/turtle.lua b/src/main/resources/data/computercraft/lua/rom/apis/turtle/turtle.lua index c9d57bf12..0a66add16 100644 --- a/src/main/resources/data/computercraft/lua/rom/apis/turtle/turtle.lua +++ b/src/main/resources/data/computercraft/lua/rom/apis/turtle/turtle.lua @@ -10,6 +10,7 @@ end -- -- Generally you should not need to use this table - it only exists for -- backwards compatibility reasons. +-- @deprecated native = turtle.native or turtle local function addCraftMethod(object)