label )
{
diff --git a/src/main/java/dan200/computercraft/core/apis/PeripheralAPI.java b/src/main/java/dan200/computercraft/core/apis/PeripheralAPI.java
index ee37d3ba4..b132ad48c 100644
--- a/src/main/java/dan200/computercraft/core/apis/PeripheralAPI.java
+++ b/src/main/java/dan200/computercraft/core/apis/PeripheralAPI.java
@@ -22,6 +22,12 @@
import javax.annotation.Nullable;
import java.util.*;
+/**
+ * CC's "native" peripheral API. This is wrapped within CraftOS to provide a version which works with modems.
+ *
+ * @cc.module peripheral
+ * @hidden
+ */
public class PeripheralAPI implements ILuaAPI, IAPIEnvironment.IPeripheralChangeListener
{
private class PeripheralWrapper extends ComputerAccess
diff --git a/src/main/java/dan200/computercraft/core/apis/RedstoneAPI.java b/src/main/java/dan200/computercraft/core/apis/RedstoneAPI.java
index ce70fc5d2..ab096fd08 100644
--- a/src/main/java/dan200/computercraft/core/apis/RedstoneAPI.java
+++ b/src/main/java/dan200/computercraft/core/apis/RedstoneAPI.java
@@ -10,6 +10,48 @@
import dan200.computercraft.api.lua.LuaFunction;
import dan200.computercraft.core.computer.ComputerSide;
+/**
+ * Interact with redstone attached to this computer.
+ *
+ * The {@link RedstoneAPI} library exposes three "types" of redstone control:
+ * - Binary input/output ({@link #setOutput}/{@link #getInput}): These simply check if a redstone wire has any input or
+ * output. A signal strength of 1 and 15 are treated the same.
+ * - Analogue input/output ({@link #setAnalogOutput}/{@link #getAnalogInput}): These work with the actual signal
+ * strength of the redstone wired, from 0 to 15.
+ * - Bundled cables ({@link #setBundledOutput}/{@link #getBundledInput}): These interact with "bundled" cables, such
+ * as those from Project:Red. These allow you to send 16 separate on/off signals. Each channel corresponds to a
+ * colour, with the first being @{colors.white} and the last @{colors.black}.
+ *
+ * Whenever a redstone input changes, a {@code redstone} event will be fired. This may be used instead of repeativly
+ * polling.
+ *
+ * This module may also be referred to as {@code rs}. For example, one may call {@code rs.getSides()} instead of
+ * {@link #getSides}.
+ *
+ * @cc.usage Toggle the redstone signal above the computer every 0.5 seconds.
+ *
+ *
+ * while true do
+ * redstone.setOutput("top", not redstone.getOutput("top"))
+ * sleep(0.5)
+ * end
+ *
+ * @cc.usage Mimic a redstone comparator in [subtraction mode][comparator].
+ *
+ *
+ * while true do
+ * local rear = rs.getAnalogueInput("back")
+ * local sides = math.max(rs.getAnalogueInput("left"), rs.getAnalogueInput("right"))
+ * rs.setAnalogueOutput("front", math.max(rear - sides, 0))
+ *
+ * os.pullEvent("redstone") -- Wait for a change to inputs.
+ * end
+ *
+ *
+ * [comparator]: https://minecraft.gamepedia.com/Redstone_Comparator#Subtract_signal_strength "Redstone Comparator on
+ * the Minecraft wiki."
+ * @cc.module redstone
+ */
public class RedstoneAPI implements ILuaAPI
{
private final IAPIEnvironment environment;
@@ -25,67 +67,145 @@ public String[] getNames()
return new String[] { "rs", "redstone" };
}
+ /**
+ * Returns a table containing the six sides of the computer. Namely, "top", "bottom", "left", "right", "front" and
+ * "back".
+ *
+ * @return A table of valid sides.
+ */
@LuaFunction
public final String[] getSides()
{
return ComputerSide.NAMES;
}
+ /**
+ * Turn the redstone signal of a specific side on or off.
+ *
+ * @param side The side to set.
+ * @param on Whether the redstone signal should be on or off. When on, a signal strength of 15 is emitted.
+ */
@LuaFunction
- public final void setOutput( ComputerSide side, boolean output )
+ public final void setOutput( ComputerSide side, boolean on )
{
- environment.setOutput( side, output ? 15 : 0 );
+ environment.setOutput( side, on ? 15 : 0 );
}
+ /**
+ * Get the current redstone output of a specific side.
+ *
+ * @param side The side to get.
+ * @return Whether the redstone output is on or off.
+ * @see #setOutput
+ */
@LuaFunction
public final boolean getOutput( ComputerSide side )
{
return environment.getOutput( side ) > 0;
}
+ /**
+ * Get the current redstone input of a specific side.
+ *
+ * @param side The side to get.
+ * @return Whether the redstone input is on or off.
+ */
@LuaFunction
public final boolean getInput( ComputerSide side )
{
return environment.getInput( side ) > 0;
}
+ /**
+ * Set the redstone signal strength for a specific side.
+ *
+ * @param side The side to set.
+ * @param value The signal strength between 0 and 15.
+ * @throws LuaException If {@code value} is not betwene 0 and 15.
+ */
@LuaFunction( { "setAnalogOutput", "setAnalogueOutput" } )
- public final void setAnalogOutput( ComputerSide side, int output ) throws LuaException
+ public final void setAnalogOutput( ComputerSide side, int value ) throws LuaException
{
- if( output < 0 || output > 15 ) throw new LuaException( "Expected number in range 0-15" );
- environment.setOutput( side, output );
+ if( value < 0 || value > 15 ) throw new LuaException( "Expected number in range 0-15" );
+ environment.setOutput( side, value );
}
+ /**
+ * Get the redstone output signal strength for a specific side.
+ *
+ * @param side The side to get.
+ * @return The output signal strength, between 0 and 15.
+ * @see #setAnalogOutput
+ */
@LuaFunction( { "getAnalogOutput", "getAnalogueOutput" } )
public final int getAnalogOutput( ComputerSide side )
{
return environment.getOutput( side );
}
+ /**
+ * Get the redstone input signal strength for a specific side.
+ *
+ * @param side The side to get.
+ * @return The input signal strength, between 0 and 15.
+ */
@LuaFunction( { "getAnalogInput", "getAnalogueInput" } )
public final int getAnalogInput( ComputerSide side )
{
return environment.getInput( side );
}
+ /**
+ * Set the bundled cable output for a specific side.
+ *
+ * @param side The side to set.
+ * @param output The colour bitmask to set.
+ * @cc.see colors.subtract For removing a colour from the bitmask.
+ * @cc.see colors.combine For adding a color to the bitmask.
+ */
@LuaFunction
public final void setBundledOutput( ComputerSide side, int output )
{
environment.setBundledOutput( side, output );
}
+ /**
+ * Get the bundled cable output for a specific side.
+ *
+ * @param side The side to get.
+ * @return The bundle cable's output.
+ */
@LuaFunction
public final int getBundledOutput( ComputerSide side )
{
return environment.getBundledOutput( side );
}
+ /**
+ * Get the bundled cable input for a specific side.
+ *
+ * @param side The side to get.
+ * @return The bundle cable's input.
+ * @see #testBundledInput To determine if a specific colour is set.
+ */
@LuaFunction
public final int getBundledInput( ComputerSide side )
{
return environment.getBundledOutput( side );
}
+ /**
+ * Determine if a specific combination of colours are on for the given side.
+ *
+ * @param side The side to test.
+ * @param mask The mask to test.
+ * @return If the colours are on.
+ * @cc.usage Check if @{colors.white} and @{colors.black} are on above the computer.
+ *
+ * print(redstone.testBundledInput("top", colors.combine(colors.white, colors.black)))
+ *
+ * @see #getBundledInput
+ */
@LuaFunction
public final boolean testBundledInput( ComputerSide side, int mask )
{
diff --git a/src/main/java/dan200/computercraft/core/apis/TermAPI.java b/src/main/java/dan200/computercraft/core/apis/TermAPI.java
index 195085331..ed05df142 100644
--- a/src/main/java/dan200/computercraft/core/apis/TermAPI.java
+++ b/src/main/java/dan200/computercraft/core/apis/TermAPI.java
@@ -14,6 +14,11 @@
import javax.annotation.Nonnull;
+/**
+ * The Terminal API provides functions for writing text to the terminal and monitors, and drawing ASCII graphics.
+ *
+ * @cc.module term
+ */
public class TermAPI extends TermMethods implements ILuaAPI
{
private final Terminal terminal;
@@ -31,11 +36,21 @@ public String[] getNames()
return new String[] { "term" };
}
+ /**
+ * Get the default palette value for a colour.
+ *
+ * @param colour The colour whose palette should be fetched.
+ * @return The RGB values.
+ * @throws LuaException When given an invalid colour.
+ * @cc.treturn number The red channel, will be between 0 and 1.
+ * @cc.treturn number The green channel, will be between 0 and 1.
+ * @cc.treturn number The blue channel, will be between 0 and 1.
+ */
@LuaFunction( { "nativePaletteColour", "nativePaletteColor" } )
- public final Object[] nativePaletteColour( int colourArg ) throws LuaException
+ public final Object[] nativePaletteColour( int colour ) throws LuaException
{
- int colour = 15 - parseColour( colourArg );
- Colour c = Colour.fromInt( colour );
+ int actualColour = 15 - parseColour( colour );
+ Colour c = Colour.fromInt( actualColour );
float[] rgb = c.getRGB();
diff --git a/src/main/java/dan200/computercraft/core/apis/TermMethods.java b/src/main/java/dan200/computercraft/core/apis/TermMethods.java
index d7674ef3f..c55c59f7a 100644
--- a/src/main/java/dan200/computercraft/core/apis/TermMethods.java
+++ b/src/main/java/dan200/computercraft/core/apis/TermMethods.java
@@ -18,6 +18,9 @@
/**
* A base class for all objects which interact with a terminal. Namely the {@link TermAPI} and monitors.
+ *
+ * @cc.module term.Redirect
+ * @hidden
*/
public abstract class TermMethods
{
diff --git a/src/main/java/dan200/computercraft/core/apis/http/websocket/WebsocketHandle.java b/src/main/java/dan200/computercraft/core/apis/http/websocket/WebsocketHandle.java
index a6436a785..ce8684002 100644
--- a/src/main/java/dan200/computercraft/core/apis/http/websocket/WebsocketHandle.java
+++ b/src/main/java/dan200/computercraft/core/apis/http/websocket/WebsocketHandle.java
@@ -25,6 +25,12 @@
import static dan200.computercraft.core.apis.http.websocket.Websocket.CLOSE_EVENT;
import static dan200.computercraft.core.apis.http.websocket.Websocket.MESSAGE_EVENT;
+/**
+ * A websocket, which can be used to send an receive messages with a web server.
+ *
+ * @cc.module http.Websocket
+ * @see dan200.computercraft.core.apis.HTTPAPI#websocket On how to open a websocket.
+ */
public class WebsocketHandle implements Closeable
{
private final Websocket websocket;
@@ -40,8 +46,18 @@ public WebsocketHandle( Websocket websocket, Options options, Channel channel )
this.channel = channel;
}
+ /**
+ * Wait for a message from the server.
+ *
+ * @param timeout The number of seconds to wait if no message is received.
+ * @return The result of receiving.
+ * @throws LuaException If the websocket has been closed.
+ * @cc.treturn [1] string The received message.
+ * @cc.treturn boolean If this was a binary message.
+ * @cc.treturn [2] nil If the websocket was closed while waiting, or if we timed out.
+ */
@LuaFunction
- public final MethodResult result( Optional timeout ) throws LuaException
+ public final MethodResult receive( Optional timeout ) throws LuaException
{
checkOpen();
int timeoutId = timeout.isPresent()
@@ -51,29 +67,40 @@ public final MethodResult result( Optional timeout ) throws LuaException
return new ReceiveCallback( timeoutId ).pull;
}
+ /**
+ * Send a websocket message to the connected server.
+ *
+ * @param message The message to send.
+ * @param binary Whether this message should be treated as a
+ * @throws LuaException If the message is too large.
+ * @throws LuaException If the websocket has been closed.
+ */
@LuaFunction
- public final void send( IArguments args ) throws LuaException
+ public final void send( Object message, Optional binary ) throws LuaException
{
checkOpen();
- String text = StringUtil.toString( args.get( 0 ) );
+ String text = StringUtil.toString( message );
if( options.websocketMessage != 0 && text.length() > options.websocketMessage )
{
throw new LuaException( "Message is too large" );
}
- boolean binary = args.optBoolean( 1, false );
websocket.environment().addTrackingChange( TrackingField.WEBSOCKET_OUTGOING, text.length() );
Channel channel = this.channel;
if( channel != null )
{
- channel.writeAndFlush( binary
+ channel.writeAndFlush( binary.orElse( false )
? new BinaryWebSocketFrame( Unpooled.wrappedBuffer( LuaValues.encode( text ) ) )
: new TextWebSocketFrame( text ) );
}
}
+ /**
+ * Close this websocket. This will terminate the connection, meaning messages can no longer be sent or received
+ * along it.
+ */
@LuaFunction( "close" )
public final void doClose()
{
diff --git a/src/main/java/dan200/computercraft/core/asm/Generator.java b/src/main/java/dan200/computercraft/core/asm/Generator.java
index 0456cc51a..2e80cd86c 100644
--- a/src/main/java/dan200/computercraft/core/asm/Generator.java
+++ b/src/main/java/dan200/computercraft/core/asm/Generator.java
@@ -194,9 +194,9 @@ private Optional build( Method method )
if( bytes == null ) return Optional.empty();
Class klass = DeclaringClassLoader.INSTANCE.define( className, bytes, method.getDeclaringClass().getProtectionDomain() );
- return Optional.of( klass.asSubclass( base ).newInstance() );
+ return Optional.of( klass.asSubclass( base ).getDeclaredConstructor().newInstance() );
}
- catch( InstantiationException | IllegalAccessException | ClassFormatError | RuntimeException e )
+ catch( ReflectiveOperationException | ClassFormatError | RuntimeException e )
{
ComputerCraft.log.error( "Error generating wrapper for {}.", name, e );
return Optional.empty();
diff --git a/src/main/java/dan200/computercraft/shared/computer/apis/CommandAPI.java b/src/main/java/dan200/computercraft/shared/computer/apis/CommandAPI.java
index 53e8fbc21..fd310da23 100644
--- a/src/main/java/dan200/computercraft/shared/computer/apis/CommandAPI.java
+++ b/src/main/java/dan200/computercraft/shared/computer/apis/CommandAPI.java
@@ -23,6 +23,9 @@
import java.util.*;
+/**
+ * @cc.module commands
+ */
public class CommandAPI implements ILuaAPI
{
private final TileCommandComputer computer;
@@ -78,18 +81,62 @@ private Object[] doCommand( String command )
return table;
}
+ /**
+ * Execute a specific command.
+ *
+ * @param command The command to execute.
+ * @return See {@code cc.treturn}.
+ * @cc.treturn boolean Whether the command executed successfully.
+ * @cc.treturn { string... } The output of this command, as a list of lines.
+ * @cc.treturn number|nil The number of "affected" objects, or `nil` if the command failed. The definition of this
+ * varies from command to command.
+ * @cc.usage Set the block above the command computer to stone.
+ *
+ * commands.exec("setblock ~ ~1 ~ minecraft:stone")
+ *
+ */
@LuaFunction( mainThread = true )
public final Object[] exec( String command )
{
return doCommand( command );
}
+ /**
+ * Asynchronously execute a command.
+ *
+ * Unlike {@link #exec}, this will immediately return, instead of waiting for the
+ * command to execute. This allows you to run multiple commands at the same
+ * time.
+ *
+ * When this command has finished executing, it will queue a `task_complete`
+ * event containing the result of executing this command (what {@link #exec} would
+ * return).
+ *
+ * @param context The context this command executes under.
+ * @param command The command to execute.
+ * @return The "task id". When this command has been executed, it will queue a `task_complete` event with a matching id.
+ * @throws LuaException (hidden) If the task cannot be created.
+ * @cc.tparam string command The command to execute.
+ * @cc.usage Asynchronously sets the block above the computer to stone.
+ *
+ * commands.execAsync("~ ~1 ~ minecraft:stone")
+ *
+ * @cc.see parallel One may also use the parallel API to run multiple commands at once.
+ */
@LuaFunction
public final long execAsync( ILuaContext context, String command ) throws LuaException
{
return context.issueMainThreadTask( () -> doCommand( command ) );
}
+ /**
+ * List all available commands which the computer has permission to execute.
+ *
+ * @param args Arguments to this function.
+ * @return A list of all available commands
+ * @throws LuaException (hidden) On non-string arguments.
+ * @cc.tparam string ... The sub-command to complete.
+ */
@LuaFunction( mainThread = true )
public final List list( IArguments args ) throws LuaException
{
@@ -112,6 +159,15 @@ public final List list( IArguments args ) throws LuaException
return result;
}
+ /**
+ * Get the position of the current command computer.
+ *
+ * @return The block's position.
+ * @cc.treturn number This computer's x position.
+ * @cc.treturn number This computer's y position.
+ * @cc.treturn number This computer's z position.
+ * @cc.see gps.locate To get the position of a non-command computer.
+ */
@LuaFunction
public final Object[] getBlockPosition()
{
@@ -120,6 +176,25 @@ public final Object[] getBlockPosition()
return new Object[] { pos.getX(), pos.getY(), pos.getZ() };
}
+ /**
+ * Get information about a range of blocks.
+ *
+ * This returns the same information as @{getBlockInfo}, just for multiple
+ * blocks at once.
+ *
+ * Blocks are traversed by ascending y level, followed by z and x - the returned
+ * table may be indexed using `x + z*width + y*depth*depth`.
+ *
+ * @param minX The start x coordinate of the range to query.
+ * @param minY The start y coordinate of the range to query.
+ * @param minZ The start z coordinate of the range to query.
+ * @param maxX The end x coordinate of the range to query.
+ * @param maxY The end y coordinate of the range to query.
+ * @param maxZ The end z coordinate of the range to query.
+ * @return A list of information about each block.
+ * @throws LuaException If the coordinates are not within the world.
+ * @throws LuaException If trying to get information about more than 4096 blocks.
+ */
@LuaFunction( mainThread = true )
public final List> getBlockInfos( int minX, int minY, int minZ, int maxX, int maxY, int maxZ ) throws LuaException
{
@@ -159,6 +234,19 @@ public final Object[] getBlockPosition()
return results;
}
+ /**
+ * Get some basic information about a block.
+ *
+ * The returned table contains the current name, metadata and block state (as
+ * with @{turtle.inspect}). If there is a tile entity for that block, its NBT
+ * will also be returned.
+ *
+ * @param x The x position of the block to query.
+ * @param y The y position of the block to query.
+ * @param z The z position of the block to query.
+ * @return The given block's information.
+ * @throws LuaException If the coordinates are not within the world, or are not currently loaded.
+ */
@LuaFunction( mainThread = true )
public final Map getBlockInfo( int x, int y, int z ) throws LuaException
{
diff --git a/src/main/java/dan200/computercraft/shared/computer/blocks/ComputerPeripheral.java b/src/main/java/dan200/computercraft/shared/computer/blocks/ComputerPeripheral.java
index 15c3395b9..8e527be7d 100644
--- a/src/main/java/dan200/computercraft/shared/computer/blocks/ComputerPeripheral.java
+++ b/src/main/java/dan200/computercraft/shared/computer/blocks/ComputerPeripheral.java
@@ -7,9 +7,19 @@
import dan200.computercraft.api.lua.LuaFunction;
import dan200.computercraft.api.peripheral.IPeripheral;
+import dan200.computercraft.core.apis.OSAPI;
import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
+/**
+ * A computer or turtle wrapped as a peripheral.
+ *
+ * This allows for basic interaction with adjacent computers. Computers wrapped as peripherals will have the type
+ * {@code computer} while turtles will be {@code turtle}.
+ *
+ * @cc.module computer
+ */
public class ComputerPeripheral implements IPeripheral
{
private final String type;
@@ -28,36 +38,63 @@ public String getType()
return type;
}
+ /**
+ * Turn the other computer on.
+ */
@LuaFunction
public final void turnOn()
{
computer.turnOn();
}
+ /**
+ * Shutdown the other computer.
+ */
@LuaFunction
public final void shutdown()
{
computer.shutdown();
}
+ /**
+ * Reboot or turn on the other computer.
+ */
@LuaFunction
public final void reboot()
{
computer.reboot();
}
+ /**
+ * Get the other computer's ID.
+ *
+ * @return The computer's ID.
+ * @see OSAPI#getComputerID() To get your computer's ID.
+ */
@LuaFunction
public final int getID()
{
return computer.assignID();
}
+ /**
+ * Determine if the other computer is on.
+ *
+ * @return If the computer is on.
+ */
@LuaFunction
public final boolean isOn()
{
return computer.isOn();
}
+ /**
+ * Get the other computer's label.
+ *
+ * @return The computer's label.
+ * @see OSAPI#getComputerLabel() To get your label.
+ */
+ @Nullable
@LuaFunction
public final String getLabel()
{
diff --git a/src/main/java/dan200/computercraft/shared/peripheral/commandblock/CommandBlockPeripheral.java b/src/main/java/dan200/computercraft/shared/peripheral/commandblock/CommandBlockPeripheral.java
index a5d2a2041..ff0881f29 100644
--- a/src/main/java/dan200/computercraft/shared/peripheral/commandblock/CommandBlockPeripheral.java
+++ b/src/main/java/dan200/computercraft/shared/peripheral/commandblock/CommandBlockPeripheral.java
@@ -8,6 +8,7 @@
import dan200.computercraft.ComputerCraft;
import dan200.computercraft.api.lua.LuaFunction;
import dan200.computercraft.api.peripheral.IPeripheral;
+import dan200.computercraft.shared.computer.apis.CommandAPI;
import dan200.computercraft.shared.util.CapabilityUtil;
import net.minecraft.tileentity.CommandBlockTileEntity;
import net.minecraft.tileentity.TileEntity;
@@ -25,6 +26,16 @@
import static dan200.computercraft.shared.Capabilities.CAPABILITY_PERIPHERAL;
+/**
+ * This peripheral allows you to interact with command blocks.
+ *
+ * Command blocks are only wrapped as peripherals if the {@literal enable_command_block} option is true within the
+ * config.
+ *
+ * This API is not the same as the {@link CommandAPI} API, which is exposed on command computers.
+ *
+ * @cc.module command
+ */
@Mod.EventBusSubscriber
public class CommandBlockPeripheral implements IPeripheral, ICapabilityProvider
{
@@ -45,12 +56,22 @@ public String getType()
return "command";
}
+ /**
+ * Get the command this command block will run.
+ *
+ * @return The current command.
+ */
@LuaFunction( mainThread = true )
public final String getCommand()
{
return commandBlock.getCommandBlockLogic().getCommand();
}
+ /**
+ * Set the command block's command.
+ *
+ * @param command The new command.
+ */
@LuaFunction( mainThread = true )
public final void setCommand( String command )
{
@@ -58,8 +79,15 @@ public final void setCommand( String command )
commandBlock.getCommandBlockLogic().updateCommand();
}
+ /**
+ * Execute the command block once.
+ *
+ * @return The result of executing.
+ * @cc.treturn boolean If the command completed successfully.
+ * @cc.treturn string|nil A failure message.
+ */
@LuaFunction( mainThread = true )
- public final Object runCommand()
+ public final Object[] runCommand()
{
commandBlock.getCommandBlockLogic().trigger( commandBlock.getWorld() );
int result = commandBlock.getCommandBlockLogic().getSuccessCount();
diff --git a/src/main/java/dan200/computercraft/shared/peripheral/diskdrive/DiskDrivePeripheral.java b/src/main/java/dan200/computercraft/shared/peripheral/diskdrive/DiskDrivePeripheral.java
index ee0001a38..8367e1f8b 100644
--- a/src/main/java/dan200/computercraft/shared/peripheral/diskdrive/DiskDrivePeripheral.java
+++ b/src/main/java/dan200/computercraft/shared/peripheral/diskdrive/DiskDrivePeripheral.java
@@ -18,6 +18,19 @@
import javax.annotation.Nonnull;
import java.util.Optional;
+/**
+ * Disk drives are a peripheral which allow you to read and write to floppy disks and other "mountable media" (such as
+ * computers or turtles). They also allow you to {@link #playAudio play records}.
+ *
+ * When a disk drive attaches some mount (such as a floppy disk or computer), it attaches a folder called {@code disk},
+ * {@code disk2}, etc... to the root directory of the computer. This folder can be used to interact with the files on
+ * that disk.
+ *
+ * When a disk is inserted, a {@code disk} event is fired, with the side peripheral is on. Likewise, when the disk is
+ * detached, a {@code disk_eject} event is fired.
+ *
+ * @cc.module drive
+ */
public class DiskDrivePeripheral implements IPeripheral
{
private final TileDiskDrive diskDrive;
diff --git a/src/main/java/dan200/computercraft/shared/peripheral/modem/ModemPeripheral.java b/src/main/java/dan200/computercraft/shared/peripheral/modem/ModemPeripheral.java
index 32df37b98..0805406a9 100644
--- a/src/main/java/dan200/computercraft/shared/peripheral/modem/ModemPeripheral.java
+++ b/src/main/java/dan200/computercraft/shared/peripheral/modem/ModemPeripheral.java
@@ -20,6 +20,11 @@
import java.util.HashSet;
import java.util.Set;
+/**
+ * The modem peripheral allows you to send messages between computers.
+ *
+ * @cc.module modem
+ */
public abstract class ModemPeripheral implements IPeripheral, IPacketSender, IPacketReceiver
{
private IPacketNetwork m_network;
@@ -100,30 +105,65 @@ private static int parseChannel( int channel ) throws LuaException
return channel;
}
+ /**
+ * Open a channel on a modem. A channel must be open in order to receive messages. Modems can have up to 128
+ * channels open at one time.
+ *
+ * @param channel The channel to open. This must be a number between 0 and 65535.
+ * @throws LuaException If the channel is out of range.
+ * @throws LuaException If there are too many open channels.
+ */
@LuaFunction
public final void open( int channel ) throws LuaException
{
m_state.open( parseChannel( channel ) );
}
+ /**
+ * Check if a channel is open.
+ *
+ * @param channel The channel to check.
+ * @return Whether the channel is open.
+ * @throws LuaException If the channel is out of range.
+ */
@LuaFunction
public final boolean isOpen( int channel ) throws LuaException
{
return m_state.isOpen( parseChannel( channel ) );
}
+ /**
+ * Close an open channel, meaning it will no longer receive messages.
+ *
+ * @param channel The channel to close.
+ * @throws LuaException If the channel is out of range.
+ */
@LuaFunction
public final void close( int channel ) throws LuaException
{
m_state.close( parseChannel( channel ) );
}
+ /**
+ * Close all open channels.
+ */
@LuaFunction
public final void closeAll()
{
m_state.closeAll();
}
+ /**
+ * Sends a modem message on a certain channel. Modems listening on the channel will queue a {@code modem_message}
+ * event on adjacent computers.
+ *
+ * Note: The channel does not need be open to send a message.
+ *
+ * @param channel The channel to send messages on.
+ * @param replyChannel The channel that responses to this message should be sent on.
+ * @param payload The object to send. This can be a string, number, or table.
+ * @throws LuaException If the channel is out of range.
+ */
@LuaFunction
public final void transmit( int channel, int replyChannel, Object payload ) throws LuaException
{
@@ -147,6 +187,14 @@ public final void transmit( int channel, int replyChannel, Object payload ) thro
}
}
+ /**
+ * Determine if this is a wired or wireless modem.
+ *
+ * Some methods (namely those dealing with wired networks and remote peripherals) are only available on wired
+ * modems.
+ *
+ * @return {@code true} if this is a wireless modem.
+ */
@LuaFunction
public final boolean isWireless()
{
diff --git a/src/main/java/dan200/computercraft/shared/peripheral/modem/wired/WiredModemPeripheral.java b/src/main/java/dan200/computercraft/shared/peripheral/modem/wired/WiredModemPeripheral.java
index 620f02cbd..b4472f377 100644
--- a/src/main/java/dan200/computercraft/shared/peripheral/modem/wired/WiredModemPeripheral.java
+++ b/src/main/java/dan200/computercraft/shared/peripheral/modem/wired/WiredModemPeripheral.java
@@ -73,18 +73,54 @@ public World getWorld()
//endregion
//region Peripheral methods
+
+ /**
+ * List all remote peripherals on the wired network.
+ *
+ * If this computer is attached to the network, it _will not_ be included in
+ * this list.
+ *
+ * Important: This function only appears on wired modems. Check {@link #isWireless}
+ * returns false before calling it.
+ *
+ * @param computer The calling computer.
+ * @return Remote peripheral names on the network.
+ */
@LuaFunction
public final Collection getNamesRemote( IComputerAccess computer )
{
return getWrappers( computer ).keySet();
}
+ /**
+ * Determine if a peripheral is available on this wired network.
+ *
+ * Important: This function only appears on wired modems. Check {@link #isWireless}
+ * returns false before calling it.
+ *
+ * @param computer The calling computer.
+ * @param name The peripheral's name.
+ * @return boolean If a peripheral is present with the given name.
+ * @see PeripheralAPI#isPresent
+ */
@LuaFunction
public final boolean isPresentRemote( IComputerAccess computer, String name )
{
return getWrapper( computer, name ) != null;
}
+ /**
+ * Get the type of a peripheral is available on this wired network.
+ *
+ * Important: This function only appears on wired modems. Check {@link #isWireless}
+ * returns false before calling it.
+ *
+ * @param computer The calling computer.
+ * @param name The peripheral's name.
+ * @return The peripheral's name.
+ * @cc.treturn string|nil The peripheral's type, or {@code nil} if it is not present.
+ * @see PeripheralAPI#getType
+ */
@LuaFunction
public final Object[] getTypeRemote( IComputerAccess computer, String name )
{
@@ -92,6 +128,17 @@ public final Object[] getTypeRemote( IComputerAccess computer, String name )
return wrapper != null ? new Object[] { wrapper.getType() } : null;
}
+ /**
+ * Get all available methods for the remote peripheral with the given name.
+ *
+ * Important: This function only appears on wired modems. Check {@link #isWireless}
+ * returns false before calling it.
+ *
+ * @param computer The calling computer.
+ * @param name The peripheral's name.
+ * @return A list of methods provided by this peripheral, or {@code nil} if it is not present.
+ * @see PeripheralAPI#getMethods
+ */
@LuaFunction
public final Object[] getMethodsRemote( IComputerAccess computer, String name )
{
@@ -101,6 +148,23 @@ public final Object[] getMethodsRemote( IComputerAccess computer, String name )
return new Object[] { wrapper.getMethodNames() };
}
+ /**
+ * Call a method on a peripheral on this wired network.
+ *
+ * Important: This function only appears on wired modems. Check {@link #isWireless}
+ * returns false before calling it.
+ *
+ * @param computer The calling computer.
+ * @param context The Lua context we're executing in.
+ * @param arguments Arguments to this computer.
+ * @return The peripheral's result.
+ * @throws LuaException (hidden) If the method throws an error.
+ * @cc.tparam string remoteName The name of the peripheral to invoke the method on.
+ * @cc.tparam string method The name of the method
+ * @cc.param ... Additional arguments to pass to the method
+ * @cc.treturn string The return values of the peripheral method.
+ * @see PeripheralAPI#call
+ */
@LuaFunction
public final MethodResult callRemote( IComputerAccess computer, ILuaContext context, IArguments arguments ) throws LuaException
{
@@ -112,6 +176,17 @@ public final MethodResult callRemote( IComputerAccess computer, ILuaContext cont
return wrapper.callMethod( context, methodName, arguments.drop( 2 ) );
}
+ /**
+ * Returns the network name of the current computer, if the modem is on. This
+ * may be used by other computers on the network to wrap this computer as a
+ * peripheral.
+ *
+ * Important: This function only appears on wired modems. Check {@link #isWireless}
+ * returns false before calling it.
+ *
+ * @return The current computer's name.
+ * @cc.treturn string|nil The current computer's name on the wired network.
+ */
@LuaFunction
public final Object[] getNameLocal()
{
diff --git a/src/main/java/dan200/computercraft/shared/peripheral/monitor/MonitorPeripheral.java b/src/main/java/dan200/computercraft/shared/peripheral/monitor/MonitorPeripheral.java
index 9551a3773..c2e8cb050 100644
--- a/src/main/java/dan200/computercraft/shared/peripheral/monitor/MonitorPeripheral.java
+++ b/src/main/java/dan200/computercraft/shared/peripheral/monitor/MonitorPeripheral.java
@@ -16,6 +16,24 @@
import javax.annotation.Nonnull;
import javax.annotation.Nullable;
+/**
+ * Monitors are a block which act as a terminal, displaying information on one side. This allows them to be read and
+ * interacted with in-world without opening a GUI.
+ *
+ * Monitors act as @{term.Redirect|terminal redirects} and so expose the same methods, as well as several additional
+ * ones, which are documented below.
+ *
+ * Like computers, monitors come in both normal (no colour) and advanced (colour) varieties.
+ *
+ * @cc.module monitor
+ * @cc.usage Write "Hello, world!" to an adjacent monitor:
+ *
+ *
+ * local monitor = peripheral.find("monitor")
+ * monitor.setCursorPos(1, 1)
+ * monitor.write("Hello, world!")
+ *
+ */
public class MonitorPeripheral extends TermMethods implements IPeripheral
{
private final TileMonitor monitor;
@@ -32,6 +50,14 @@ public String getType()
return "monitor";
}
+ /**
+ * Set the scale of this monitor. A larger scale will result in the monitor having a lower resolution, but display
+ * text much larger.
+ *
+ * @param scaleArg The monitor's scale. This must be a multiple of 0.5 between 0.5 and 5.
+ * @throws LuaException If the scale is out of range.
+ * @see #getTextScale()
+ */
@LuaFunction
public final void setTextScale( double scaleArg ) throws LuaException
{
@@ -40,6 +66,12 @@ public final void setTextScale( double scaleArg ) throws LuaException
getMonitor().setTextScale( scale );
}
+ /**
+ * Get the monitor's current text scale.
+ *
+ * @return The monitor's current scale.
+ * @throws LuaException If the monitor cannot be found.
+ */
@LuaFunction
public final double getTextScale() throws LuaException
{
diff --git a/src/main/java/dan200/computercraft/shared/peripheral/printer/PrinterPeripheral.java b/src/main/java/dan200/computercraft/shared/peripheral/printer/PrinterPeripheral.java
index cada0513d..5235e127c 100644
--- a/src/main/java/dan200/computercraft/shared/peripheral/printer/PrinterPeripheral.java
+++ b/src/main/java/dan200/computercraft/shared/peripheral/printer/PrinterPeripheral.java
@@ -15,6 +15,11 @@
import javax.annotation.Nonnull;
import java.util.Optional;
+/**
+ * The printer peripheral allows pages and books to be printed.
+ *
+ * @cc.module printer
+ */
public class PrinterPeripheral implements IPeripheral
{
private final TilePrinter printer;
diff --git a/src/main/java/dan200/computercraft/shared/peripheral/speaker/SpeakerPeripheral.java b/src/main/java/dan200/computercraft/shared/peripheral/speaker/SpeakerPeripheral.java
index 4920e7260..c1c5527e7 100644
--- a/src/main/java/dan200/computercraft/shared/peripheral/speaker/SpeakerPeripheral.java
+++ b/src/main/java/dan200/computercraft/shared/peripheral/speaker/SpeakerPeripheral.java
@@ -25,6 +25,11 @@
import static dan200.computercraft.api.lua.LuaValues.checkFinite;
+/**
+ * Speakers allow playing notes and other sounds.
+ *
+ * @cc.module speaker
+ */
public abstract class SpeakerPeripheral implements IPeripheral
{
private long m_clock = 0;
diff --git a/src/main/java/dan200/computercraft/shared/pocket/apis/PocketAPI.java b/src/main/java/dan200/computercraft/shared/pocket/apis/PocketAPI.java
index 15f8df2c0..25734108a 100644
--- a/src/main/java/dan200/computercraft/shared/pocket/apis/PocketAPI.java
+++ b/src/main/java/dan200/computercraft/shared/pocket/apis/PocketAPI.java
@@ -19,6 +19,22 @@
import net.minecraft.util.NonNullList;
import net.minecraftforge.items.wrapper.PlayerMainInvWrapper;
+/**
+ * Control the current pocket computer, adding or removing upgrades.
+ *
+ * This API is only available on pocket computers. As such, you may use its presence to determine what kind of computer
+ * you are using:
+ *
+ *
+ * if pocket then
+ * print("On a pocket computer")
+ * else
+ * print("On something else")
+ * end
+ *
+ *
+ * @cc.module pocket
+ */
public class PocketAPI implements ILuaAPI
{
private final PocketServerComputer computer;
@@ -34,6 +50,15 @@ public String[] getNames()
return new String[] { "pocket" };
}
+ /**
+ * Search the player's inventory for another upgrade, replacing the existing one with that item if found.
+ *
+ * This inventory search starts from the player's currently selected slot, allowing you to prioritise upgrades.
+ *
+ * @return The result of equipping.
+ * @cc.treturn boolean If an item was equipped.
+ * @cc.treturn string|nil The reason an item was not equipped.
+ */
@LuaFunction( mainThread = true )
public final Object[] equipBack()
{
@@ -72,6 +97,13 @@ public final Object[] equipBack()
return new Object[] { true };
}
+ /**
+ * Remove the pocket computer's current upgrade.
+ *
+ * @return The result of unequipping.
+ * @cc.treturn boolean If the upgrade was unequipped.
+ * @cc.treturn string|nil The reason an upgrade was not unequipped.
+ */
@LuaFunction( mainThread = true )
public final Object[] unequipBack()
{
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 66753f3be..3abcef060 100644
--- a/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java
+++ b/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java
@@ -24,6 +24,11 @@
import java.util.Map;
import java.util.Optional;
+/**
+ * The turtle API allows you to control your turtle.
+ *
+ * @cc.module turtle
+ */
public class TurtleAPI implements ILuaAPI
{
private final IAPIEnvironment environment;
@@ -47,42 +52,92 @@ private MethodResult trackCommand( ITurtleCommand command )
return turtle.executeCommand( command );
}
+ /**
+ * Move the turtle forward one block.
+ *
+ * @return The turtle command result.
+ * @cc.treturn boolean Whether the turtle could successfully move.
+ * @cc.treturn string|nil The reason the turtle could not move.
+ */
@LuaFunction
public final MethodResult forward()
{
return trackCommand( new TurtleMoveCommand( MoveDirection.FORWARD ) );
}
+ /**
+ * Move the turtle backwards one block.
+ *
+ * @return The turtle command result.
+ * @cc.treturn boolean Whether the turtle could successfully move.
+ * @cc.treturn string|nil The reason the turtle could not move.
+ */
@LuaFunction
public final MethodResult back()
{
return trackCommand( new TurtleMoveCommand( MoveDirection.BACK ) );
}
+ /**
+ * Move the turtle up one block.
+ *
+ * @return The turtle command result.
+ * @cc.treturn boolean Whether the turtle could successfully move.
+ * @cc.treturn string|nil The reason the turtle could not move.
+ */
@LuaFunction
public final MethodResult up()
{
return trackCommand( new TurtleMoveCommand( MoveDirection.UP ) );
}
+ /**
+ * Move the turtle down one block.
+ *
+ * @return The turtle command result.
+ * @cc.treturn boolean Whether the turtle could successfully move.
+ * @cc.treturn string|nil The reason the turtle could not move.
+ */
@LuaFunction
public final MethodResult down()
{
return trackCommand( new TurtleMoveCommand( MoveDirection.DOWN ) );
}
+ /**
+ * Rotate the turtle 90 degress to the left.
+ *
+ * @return The turtle command result.
+ */
@LuaFunction
public final MethodResult turnLeft()
{
return trackCommand( new TurtleTurnCommand( TurnDirection.LEFT ) );
}
+ /**
+ * Rotate the turtle 90 degress to the right.
+ *
+ * @return The turtle command result.
+ */
@LuaFunction
public final MethodResult turnRight()
{
return trackCommand( new TurtleTurnCommand( TurnDirection.RIGHT ) );
}
+ /**
+ * Attempt to break the block in front of the turtle.
+ *
+ * This requires a turtle tool capable of breaking the block. Diamond pickaxes
+ * (mining turtles) can break any vanilla block, but other tools (such as axes)
+ * are more limited.
+ *
+ * @param side The specific tool to use. Should be "left" or "right".
+ * @return The turtle command result.
+ * @cc.treturn boolean Whether a block was broken.
+ * @cc.treturn string|nil The reason no block was broken.
+ */
@LuaFunction
public final MethodResult dig( Optional side )
{
@@ -90,6 +145,14 @@ public final MethodResult dig( Optional side )
return trackCommand( TurtleToolCommand.dig( InteractDirection.FORWARD, side.orElse( null ) ) );
}
+ /**
+ * Attempt to break the block above the turtle. See {@link #dig} for full details.
+ *
+ * @param side The specific tool to use.
+ * @return The turtle command result.
+ * @cc.treturn boolean Whether a block was broken.
+ * @cc.treturn string|nil The reason no block was broken.
+ */
@LuaFunction
public final MethodResult digUp( Optional side )
{
@@ -97,6 +160,14 @@ public final MethodResult digUp( Optional side )
return trackCommand( TurtleToolCommand.dig( InteractDirection.UP, side.orElse( null ) ) );
}
+ /**
+ * Attempt to break the block below the turtle. See {@link #dig} for full details.
+ *
+ * @param side The specific tool to use.
+ * @return The turtle command result.
+ * @cc.treturn boolean Whether a block was broken.
+ * @cc.treturn string|nil The reason no block was broken.
+ */
@LuaFunction
public final MethodResult digDown( Optional side )
{
@@ -104,42 +175,113 @@ public final MethodResult digDown( Optional side )
return trackCommand( TurtleToolCommand.dig( InteractDirection.DOWN, side.orElse( null ) ) );
}
+ /**
+ * Place a block or item into the world in front of the turtle.
+ *
+ * @param args Arguments to place.
+ * @return The turtle command result.
+ * @cc.tparam [opt] string text When placing a sign, set its contents to this text.
+ * @cc.treturn boolean Whether the block could be placed.
+ * @cc.treturn string|nil The reason the block was not placed.
+ */
@LuaFunction
public final MethodResult place( IArguments args )
{
return trackCommand( new TurtlePlaceCommand( InteractDirection.FORWARD, args.getAll() ) );
}
+ /**
+ * Place a block or item into the world above the turtle.
+ *
+ * @param args Arguments to place.
+ * @return The turtle command result.
+ * @cc.tparam [opt] string text When placing a sign, set its contents to this text.
+ * @cc.treturn boolean Whether the block could be placed.
+ * @cc.treturn string|nil The reason the block was not placed.
+ */
@LuaFunction
public final MethodResult placeUp( IArguments args )
{
return trackCommand( new TurtlePlaceCommand( InteractDirection.UP, args.getAll() ) );
}
+ /**
+ * Place a block or item into the world below the turtle.
+ *
+ * @param args Arguments to place.
+ * @return The turtle command result.
+ * @cc.tparam [opt] string text When placing a sign, set its contents to this text.
+ * @cc.treturn boolean Whether the block could be placed.
+ * @cc.treturn string|nil The reason the block was not placed.
+ */
@LuaFunction
public final MethodResult placeDown( IArguments args )
{
return trackCommand( new TurtlePlaceCommand( InteractDirection.DOWN, args.getAll() ) );
}
+ /**
+ * Drop the currently selected stack into the inventory in front of the turtle, or as an item into the world if
+ * there is no inventory.
+ *
+ * @param count The number of items to drop. If not given, the entire stack will be dropped.
+ * @return The turtle command result.
+ * @throws LuaException If dropping an invalid number of items.
+ * @cc.treturn boolean Whether items were dropped.
+ * @cc.treturn string|nil The reason the no items were dropped.
+ * @see #select
+ */
@LuaFunction
public final MethodResult drop( Optional count ) throws LuaException
{
return trackCommand( new TurtleDropCommand( InteractDirection.FORWARD, checkCount( count ) ) );
}
+ /**
+ * Drop the currently selected stack into the inventory above the turtle, or as an item into the world if there is
+ * no inventory.
+ *
+ * @param count The number of items to drop. If not given, the entire stack will be dropped.
+ * @return The turtle command result.
+ * @throws LuaException If dropping an invalid number of items.
+ * @cc.treturn boolean Whether items were dropped.
+ * @cc.treturn string|nil The reason the no items were dropped.
+ * @see #select
+ */
@LuaFunction
public final MethodResult dropUp( Optional count ) throws LuaException
{
return trackCommand( new TurtleDropCommand( InteractDirection.UP, checkCount( count ) ) );
}
+ /**
+ * Drop the currently selected stack into the inventory in front of the turtle, or as an item into the world if
+ * there is no inventory.
+ *
+ * @param count The number of items to drop. If not given, the entire stack will be dropped.
+ * @return The turtle command result.
+ * @throws LuaException If dropping an invalid number of items.
+ * @cc.treturn boolean Whether items were dropped.
+ * @cc.treturn string|nil The reason the no items were dropped.
+ * @see #select
+ */
@LuaFunction
public final MethodResult dropDown( Optional count ) throws LuaException
{
return trackCommand( new TurtleDropCommand( InteractDirection.DOWN, checkCount( count ) ) );
}
+ /**
+ * Change the currently selected slot.
+ *
+ * The selected slot is determines what slot actions like {@link #drop} or {@link #getItemCount} act on.
+ *
+ * @param slot The slot to select.
+ * @return The turtle command result.
+ * @throws LuaException If the slot is out of range.
+ * @see #getSelectedSlot
+ */
+
@LuaFunction
public final MethodResult select( int slot ) throws LuaException
{
@@ -150,6 +292,13 @@ public final MethodResult select( int slot ) throws LuaException
} );
}
+ /**
+ * Get the number of items in the given slot.
+ *
+ * @param slot The slot we wish to check. Defaults to the {@link #select selected slot}.
+ * @return The number of items in this slot.
+ * @throws LuaException If the slot is out of range.
+ */
@LuaFunction
public final int getItemCount( Optional slot ) throws LuaException
{
@@ -157,6 +306,15 @@ public final int getItemCount( Optional slot ) throws LuaException
return turtle.getInventory().getStackInSlot( actualSlot ).getCount();
}
+ /**
+ * Get the remaining number of items which may be stored in this stack.
+ *
+ * For instance, if a slot contains 13 blocks of dirt, it has room for another 51.
+ *
+ * @param slot The slot we wish to check. Defaults to the {@link #select selected slot}.
+ * @return The space left in in this slot.
+ * @throws LuaException If the slot is out of range.
+ */
@LuaFunction
public final int getItemSpace( Optional slot ) throws LuaException
{
@@ -165,18 +323,37 @@ public final int getItemSpace( Optional slot ) throws LuaException
return stack.isEmpty() ? 64 : Math.min( stack.getMaxStackSize(), 64 ) - stack.getCount();
}
+ /**
+ * Check if there is a solid block in front of the turtle. In this case, solid refers to any non-air or liquid
+ * block.
+ *
+ * @return The turtle command result.
+ * @cc.treturn boolean If there is a solid block in front.
+ */
@LuaFunction
public final MethodResult detect()
{
return trackCommand( new TurtleDetectCommand( InteractDirection.FORWARD ) );
}
+ /**
+ * Check if there is a solid block above the turtle. In this case, solid refers to any non-air or liquid block.
+ *
+ * @return The turtle command result.
+ * @cc.treturn boolean If there is a solid block in front.
+ */
@LuaFunction
public final MethodResult detectUp()
{
return trackCommand( new TurtleDetectCommand( InteractDirection.UP ) );
}
+ /**
+ * Check if there is a solid block below the turtle. In this case, solid refers to any non-air or liquid block.
+ *
+ * @return The turtle command result.
+ * @cc.treturn boolean If there is a solid block in front.
+ */
@LuaFunction
public final MethodResult detectDown()
{
@@ -201,36 +378,89 @@ public final MethodResult compareDown()
return trackCommand( new TurtleCompareCommand( InteractDirection.DOWN ) );
}
+ /**
+ * Attack the entity in front of the turtle.
+ *
+ * @param side The specific tool to use.
+ * @return The turtle command result.
+ * @cc.treturn boolean Whether an entity was attacked.
+ * @cc.treturn string|nil The reason nothing was attacked.
+ */
@LuaFunction
public final MethodResult attack( Optional side )
{
return trackCommand( TurtleToolCommand.attack( InteractDirection.FORWARD, side.orElse( null ) ) );
}
+ /**
+ * Attack the entity above the turtle.
+ *
+ * @param side The specific tool to use.
+ * @return The turtle command result.
+ * @cc.treturn boolean Whether an entity was attacked.
+ * @cc.treturn string|nil The reason nothing was attacked.
+ */
@LuaFunction
public final MethodResult attackUp( Optional side )
{
return trackCommand( TurtleToolCommand.attack( InteractDirection.UP, side.orElse( null ) ) );
}
+ /**
+ * Attack the entity below the turtle.
+ *
+ * @param side The specific tool to use.
+ * @return The turtle command result.
+ * @cc.treturn boolean Whether an entity was attacked.
+ * @cc.treturn string|nil The reason nothing was attacked.
+ */
@LuaFunction
public final MethodResult attackDown( Optional side )
{
return trackCommand( TurtleToolCommand.attack( InteractDirection.DOWN, side.orElse( null ) ) );
}
+ /**
+ * Suck an item from the inventory in front of the turtle, or from an item floating in the world.
+ *
+ * This will pull items into the first acceptable slot, starting at the {@link #select currently selected} one.
+ *
+ * @param count The number of items to suck. If not given, up to a stack of items will be picked up.
+ * @return The turtle command result.
+ * @throws LuaException If given an invalid number of items.
+ * @cc.treturn boolean Whether items were picked up.
+ * @cc.treturn string|nil The reason the no items were picked up.
+ */
@LuaFunction
public final MethodResult suck( Optional count ) throws LuaException
{
return trackCommand( new TurtleSuckCommand( InteractDirection.FORWARD, checkCount( count ) ) );
}
+ /**
+ * Suck an item from the inventory above the turtle, or from an item floating in the world.
+ *
+ * @param count The number of items to suck. If not given, up to a stack of items will be picked up.
+ * @return The turtle command result.
+ * @throws LuaException If given an invalid number of items.
+ * @cc.treturn boolean Whether items were picked up.
+ * @cc.treturn string|nil The reason the no items were picked up.
+ */
@LuaFunction
public final MethodResult suckUp( Optional count ) throws LuaException
{
return trackCommand( new TurtleSuckCommand( InteractDirection.UP, checkCount( count ) ) );
}
+ /**
+ * Suck an item from the inventory below the turtle, or from an item floating in the world.
+ *
+ * @param count The number of items to suck. If not given, up to a stack of items will be picked up.
+ * @return The turtle command result.
+ * @throws LuaException If given an invalid number of items.
+ * @cc.treturn boolean Whether items were picked up.
+ * @cc.treturn string|nil The reason the no items were picked up.
+ */
@LuaFunction
public final MethodResult suckDown( Optional count ) throws LuaException
{
@@ -265,6 +495,12 @@ public final MethodResult transferTo( int slotArg, Optional countArg )
return trackCommand( new TurtleTransferToCommand( slot, count ) );
}
+ /**
+ * Get the currently sleected slot.
+ *
+ * @return The current slot.
+ * @see #select
+ */
@LuaFunction
public final int getSelectedSlot()
{
@@ -307,15 +543,33 @@ public final MethodResult inspectDown()
return trackCommand( new TurtleInspectCommand( InteractDirection.DOWN ) );
}
+ /**
+ * Get detailed information about the items in the given slot.
+ *
+ * @param context The Lua context
+ * @param slot The slot to get information about. Defaults to the {@link #select selected slot}.
+ * @param detailed Whether to include "detailed" information. When {@code true} the method will contain much
+ * more information about the item at the cost of taking longer to run.
+ * @return The command result.
+ * @throws LuaException If the slot is out of range.
+ * @cc.treturn nil|table Information about the given slot, or {@code nil} if it is empty.
+ * @cc.usage Print the current slot, assuming it contains 13 dirt.
+ *
+ * {@code
+ * print(textutils.serialize(turtle.getItemDetail()))
+ * -- => {
+ * -- name = "minecraft:dirt",
+ * -- count = 13,
+ * -- }
+ * }
+ */
@LuaFunction
- public final MethodResult getItemDetail( ILuaContext context, Optional slotArg, Optional detailedArg ) throws LuaException
+ public final MethodResult getItemDetail( ILuaContext context, Optional slot, Optional detailed ) throws LuaException
{
- int slot = checkSlot( slotArg ).orElse( turtle.getSelectedSlot() );
- boolean detailed = detailedArg.orElse( false );
-
- return detailed
- ? TaskCallback.make( context, () -> getItemDetail( slot, true ) )
- : MethodResult.of( getItemDetail( slot, false ) );
+ int actualSlot = checkSlot( slot ).orElse( turtle.getSelectedSlot() );
+ return detailed.orElse( false )
+ ? TaskCallback.make( context, () -> getItemDetail( actualSlot, true ) )
+ : MethodResult.of( getItemDetail( actualSlot, false ) );
}
private Object[] getItemDetail( int slot, boolean detailed )
diff --git a/src/main/java/dan200/computercraft/shared/turtle/upgrades/CraftingTablePeripheral.java b/src/main/java/dan200/computercraft/shared/turtle/upgrades/CraftingTablePeripheral.java
index 530937992..8aa220a35 100644
--- a/src/main/java/dan200/computercraft/shared/turtle/upgrades/CraftingTablePeripheral.java
+++ b/src/main/java/dan200/computercraft/shared/turtle/upgrades/CraftingTablePeripheral.java
@@ -15,6 +15,13 @@
import javax.annotation.Nonnull;
import java.util.Optional;
+/**
+ * The workbench peripheral allows you to craft items within the turtle's inventory.
+ *
+ * @cc.module workbench
+ * @hidden
+ * @cc.see turtle.craft This uses the {@link CraftingTablePeripheral} peripheral to craft items.
+ */
public class CraftingTablePeripheral implements IPeripheral
{
private final ITurtleAccess turtle;