mirrors/CC-Tweaked
1
0
Fork 0
mirror of https://github.com/SquidDev-CC/CC-Tweaked synced 2025-10-28 04:17:38 +00:00
Code Issues Releases Wiki Activity

remap

Browse Source
This commit is contained in:
Devan-Kerman
2020-08-29 18:01:01 -05:00
parent 605e1f6b9b
commit 621bc526be
757 changed files with 23755 additions and 74210 deletions
Download Patch File Download Diff File Expand all files Collapse all files

49
src/main/java/dan200/computercraft/api/AbstractTurtleUpgrade.java
View File

@@ -6,74 +6,67 @@
package dan200.computercraft.api;
import javax.annotation.Nonnull;
import dan200.computercraft.api.turtle.ITurtleUpgrade;
import dan200.computercraft.api.turtle.TurtleUpgradeType;
import net.minecraft.item.ItemConvertible;
import net.minecraft.item.ItemStack;
import net.minecraft.util.Identifier;
import net.minecraft.util.Util;
import javax.annotation.Nonnull;
/**
* A base class for {@link ITurtleUpgrade}s.
*
* One does not have to use this, but it does provide a convenient template.
*/
public abstract class AbstractTurtleUpgrade implements ITurtleUpgrade
{
public abstract class AbstractTurtleUpgrade implements ITurtleUpgrade {
private final Identifier id;
private final TurtleUpgradeType type;
private final String adjective;
private final ItemStack stack;
protected AbstractTurtleUpgrade( Identifier id, TurtleUpgradeType type, String adjective, ItemStack stack )
{
protected AbstractTurtleUpgrade(Identifier id, TurtleUpgradeType type, String adjective, ItemConvertible item) {
this(id, type, adjective, new ItemStack(item));
}
protected AbstractTurtleUpgrade(Identifier id, TurtleUpgradeType type, String adjective, ItemStack stack) {
this.id = id;
this.type = type;
this.adjective = adjective;
this.stack = stack;
}
protected AbstractTurtleUpgrade( Identifier id, TurtleUpgradeType type, String adjective, ItemConvertible item )
{
this( id, type, adjective, new ItemStack( item ) );
protected AbstractTurtleUpgrade(Identifier id, TurtleUpgradeType type, ItemConvertible item) {
this(id, type, new ItemStack(item));
}
protected AbstractTurtleUpgrade( Identifier id, TurtleUpgradeType type, ItemStack stack )
{
this( id, type, Util.createTranslationKey( "upgrade", id ) + ".adjective", stack );
}
protected AbstractTurtleUpgrade( Identifier id, TurtleUpgradeType type, ItemConvertible item )
{
this( id, type, new ItemStack( item ) );
protected AbstractTurtleUpgrade(Identifier id, TurtleUpgradeType type, ItemStack stack) {
this(id, type, Util.createTranslationKey("upgrade", id) + ".adjective", stack);
}
@Nonnull
@Override
public final Identifier getUpgradeID()
{
return id;
public final Identifier getUpgradeID() {
return this.id;
}
@Nonnull
@Override
public final String getUnlocalisedAdjective()
{
return adjective;
public final String getUnlocalisedAdjective() {
return this.adjective;
}
@Nonnull
@Override
public final TurtleUpgradeType getType()
{
return type;
public final TurtleUpgradeType getType() {
return this.type;
}
@Nonnull
@Override
public final ItemStack getCraftingItem()
{
return stack;
public final ItemStack getCraftingItem() {
return this.stack;
}
}

207
src/main/java/dan200/computercraft/api/ComputerCraftAPI.java
View File

@@ -6,6 +6,9 @@
package dan200.computercraft.api;
import javax.annotation.Nonnull;
import javax.annotation.Nullable;
import dan200.computercraft.api.filesystem.IMount;
import dan200.computercraft.api.filesystem.IWritableMount;
import dan200.computercraft.api.lua.ILuaAPIFactory;
@@ -20,30 +23,41 @@ import dan200.computercraft.api.peripheral.IPeripheralProvider;
import dan200.computercraft.api.pocket.IPocketUpgrade;
import dan200.computercraft.api.redstone.IBundledRedstoneProvider;
import dan200.computercraft.api.turtle.ITurtleUpgrade;
import net.minecraft.util.math.BlockPos;
import net.minecraft.util.math.Direction;
import net.minecraft.world.BlockView;
import net.minecraft.world.World;
import javax.annotation.Nonnull;
import javax.annotation.Nullable;
/**
* The static entry point to the ComputerCraft API.
* Members in this class must be called after mod_ComputerCraft has been initialised,
* but may be called before it is fully loaded.
* The static entry point to the ComputerCraft API. Members in this class must be called after mod_ComputerCraft has been initialised, but may be called
* before it is fully loaded.
*/
public final class ComputerCraftAPI
{
public final class ComputerCraftAPI {
private static IComputerCraftAPI instance;
@Nonnull
public static String getInstalledVersion()
{
public static String getInstalledVersion() {
return getInstance().getInstalledVersion();
}
@Nonnull
public static String getAPIVersion()
{
private static IComputerCraftAPI getInstance() {
if (instance != null) {
return instance;
}
try {
return instance = (IComputerCraftAPI) Class.forName("dan200.computercraft.ComputerCraftAPIImpl")
.getField("INSTANCE")
.get(null);
} catch (ReflectiveOperationException e) {
throw new IllegalStateException("Cannot find ComputerCraft API", e);
}
}
@Nonnull
public static String getAPIVersion() {
return "${version}";
}
@@ -52,31 +66,29 @@ public final class ComputerCraftAPI
*
* Use in conjunction with createSaveDirMount() to create a unique place for your peripherals or media items to store files.
*
* @param world The world for which the save dir should be created. This should be the server side world object.
* @param world The world for which the save dir should be created. This should be the server side world object.
* @param parentSubPath The folder path within the save directory where the new directory should be created. eg: "computercraft/disk"
* @return The numerical value of the name of the new folder, or -1 if the folder could not be created for some reason.
*
* eg: if createUniqueNumberedSaveDir( world, "computer/disk" ) was called returns 42, then "computer/disk/42" is now
* available for writing.
* eg: if createUniqueNumberedSaveDir( world, "computer/disk" ) was called returns 42, then "computer/disk/42" is now available for writing.
* @see #createSaveDirMount(World, String, long)
*/
public static int createUniqueNumberedSaveDir( @Nonnull World world, @Nonnull String parentSubPath )
{
return getInstance().createUniqueNumberedSaveDir( world, parentSubPath );
public static int createUniqueNumberedSaveDir(@Nonnull World world, @Nonnull String parentSubPath) {
return getInstance().createUniqueNumberedSaveDir(world, parentSubPath);
}
/**
* Creates a file system mount that maps to a subfolder of the save directory for a given world, and returns it.
*
* Use in conjunction with IComputerAccess.mount() or IComputerAccess.mountWritable() to mount a folder from the
* users save directory onto a computers file system.
* Use in conjunction with IComputerAccess.mount() or IComputerAccess.mountWritable() to mount a folder from the users save directory onto a computers
* file system.
*
* @param world The world for which the save dir can be found. This should be the server side world object.
* @param subPath The folder path within the save directory that the mount should map to. eg: "computer/disk/42".
* Use createUniqueNumberedSaveDir() to create a new numbered folder to use.
* @param world The world for which the save dir can be found. This should be the server side world object.
* @param subPath The folder path within the save directory that the mount should map to. eg: "computer/disk/42". Use createUniqueNumberedSaveDir()
* to create a new numbered folder to use.
* @param capacity The amount of data that can be stored in the directory before it fills up, in bytes.
* @return The mount, or null if it could be created for some reason. Use IComputerAccess.mount() or IComputerAccess.mountWritable()
* to mount this on a Computers' file system.
* @return The mount, or null if it could be created for some reason. Use IComputerAccess.mount() or IComputerAccess.mountWritable() to mount this on a
* Computers' file system.
* @see #createUniqueNumberedSaveDir(World, String)
* @see IComputerAccess#mount(String, IMount)
* @see IComputerAccess#mountWritable(String, IWritableMount)
@@ -84,21 +96,19 @@ public final class ComputerCraftAPI
* @see IWritableMount
*/
@Nullable
public static IWritableMount createSaveDirMount( @Nonnull World world, @Nonnull String subPath, long capacity )
{
return getInstance().createSaveDirMount( world, subPath, capacity );
public static IWritableMount createSaveDirMount(@Nonnull World world, @Nonnull String subPath, long capacity) {
return getInstance().createSaveDirMount(world, subPath, capacity);
}
/**
* Creates a file system mount to a resource folder, and returns it.
*
* Use in conjunction with {@link IComputerAccess#mount} or {@link IComputerAccess#mountWritable} to mount a
* resource folder onto a computer's file system.
* Use in conjunction with {@link IComputerAccess#mount} or {@link IComputerAccess#mountWritable} to mount a resource folder onto a computer's file
* system.
*
* The files in this mount will be a combination of files in all mod jar, and data packs that contain
* resources with the same domain and path.
* The files in this mount will be a combination of files in all mod jar, and data packs that contain resources with the same domain and path.
*
* @param domain The domain under which to look for resources. eg: "mymod".
* @param domain The domain under which to look for resources. eg: "mymod".
* @param subPath The subPath under which to look for resources. eg: "lua/myfiles".
* @return The mount, or {@code null} if it could be created for some reason.
* @see IComputerAccess#mount(String, IMount)
@@ -106,22 +116,20 @@ public final class ComputerCraftAPI
* @see IMount
*/
@Nullable
public static IMount createResourceMount( @Nonnull String domain, @Nonnull String subPath )
{
return getInstance().createResourceMount( domain, subPath );
public static IMount createResourceMount(@Nonnull String domain, @Nonnull String subPath) {
return getInstance().createResourceMount(domain, subPath);
}
/**
* Creates a file system mount to a resource folder, and returns it.
*
* Use in conjunction with {@link IComputerAccess#mount} or {@link IComputerAccess#mountWritable} to mount a
* resource folder onto a computer's file system.
* Use in conjunction with {@link IComputerAccess#mount} or {@link IComputerAccess#mountWritable} to mount a resource folder onto a computer's file
* system.
*
* The files in this mount will be a combination of files in all mod jar, and data packs that contain
* resources with the same domain and path.
* The files in this mount will be a combination of files in all mod jar, and data packs that contain resources with the same domain and path.
*
* @param klass The mod class to which the files belong.
* @param domain The domain under which to look for resources. eg: "mymod".
* @param klass The mod class to which the files belong.
* @param domain The domain under which to look for resources. eg: "mymod".
* @param subPath The subPath under which to look for resources. eg: "lua/myfiles".
* @return The mount, or {@code null} if it could be created for some reason.
* @see IComputerAccess#mount(String, IMount)
@@ -131,9 +139,8 @@ public final class ComputerCraftAPI
*/
@Nullable
@Deprecated
public static IMount createResourceMount( Class<?> klass, @Nonnull String domain, @Nonnull String subPath )
{
return getInstance().createResourceMount( domain, subPath );
public static IMount createResourceMount(Class<?> klass, @Nonnull String domain, @Nonnull String subPath) {
return getInstance().createResourceMount(domain, subPath);
}
/**
@@ -143,22 +150,19 @@ public final class ComputerCraftAPI
* @see IPeripheral
* @see IPeripheralProvider
*/
public static void registerPeripheralProvider( @Nonnull IPeripheralProvider provider )
{
getInstance().registerPeripheralProvider( provider );
public static void registerPeripheralProvider(@Nonnull IPeripheralProvider provider) {
getInstance().registerPeripheralProvider(provider);
}
/**
* Registers a new turtle turtle for use in ComputerCraft. After calling this,
* users should be able to craft Turtles with your new turtle. It is recommended to call
* this during the load() method of your mod.
* Registers a new turtle turtle for use in ComputerCraft. After calling this, users should be able to craft Turtles with your new turtle. It is
* recommended to call this during the load() method of your mod.
*
* @param upgrade The turtle upgrade to register.
* @see ITurtleUpgrade
*/
public static void registerTurtleUpgrade( @Nonnull ITurtleUpgrade upgrade )
{
getInstance().registerTurtleUpgrade( upgrade );
public static void registerTurtleUpgrade(@Nonnull ITurtleUpgrade upgrade) {
getInstance().registerTurtleUpgrade(upgrade);
}
/**
@@ -167,24 +171,22 @@ public final class ComputerCraftAPI
* @param provider The bundled redstone provider to register.
* @see IBundledRedstoneProvider
*/
public static void registerBundledRedstoneProvider( @Nonnull IBundledRedstoneProvider provider )
{
getInstance().registerBundledRedstoneProvider( provider );
public static void registerBundledRedstoneProvider(@Nonnull IBundledRedstoneProvider provider) {
getInstance().registerBundledRedstoneProvider(provider);
}
/**
* If there is a Computer or Turtle at a certain position in the world, get it's bundled redstone output.
*
* @param world The world this block is in.
* @param pos The position this block is at.
* @param side The side to extract the bundled redstone output from.
* @return If there is a block capable of emitting bundled redstone at the location, it's signal (0-65535) will be returned.
* If there is no block capable of emitting bundled redstone at the location, -1 will be returned.
* @param pos The position this block is at.
* @param side The side to extract the bundled redstone output from.
* @return If there is a block capable of emitting bundled redstone at the location, it's signal (0-65535) will be returned. If there is no block
* capable of emitting bundled redstone at the location, -1 will be returned.
* @see IBundledRedstoneProvider
*/
public static int getBundledRedstoneOutput( @Nonnull World world, @Nonnull BlockPos pos, @Nonnull Direction side )
{
return getInstance().getBundledRedstoneOutput( world, pos, side );
public static int getBundledRedstoneOutput(@Nonnull World world, @Nonnull BlockPos pos, @Nonnull Direction side) {
return getInstance().getBundledRedstoneOutput(world, pos, side);
}
/**
@@ -193,14 +195,12 @@ public final class ComputerCraftAPI
* @param provider The media provider to register.
* @see IMediaProvider
*/
public static void registerMediaProvider( @Nonnull IMediaProvider provider )
{
getInstance().registerMediaProvider( provider );
public static void registerMediaProvider(@Nonnull IMediaProvider provider) {
getInstance().registerMediaProvider(provider);
}
public static void registerPocketUpgrade( @Nonnull IPocketUpgrade upgrade )
{
getInstance().registerPocketUpgrade( upgrade );
public static void registerPocketUpgrade(@Nonnull IPocketUpgrade upgrade) {
getInstance().registerPocketUpgrade(upgrade);
}
/**
@@ -208,14 +208,12 @@ public final class ComputerCraftAPI
*
* @return The global wireless network, or {@code null} if it could not be fetched.
*/
public static IPacketNetwork getWirelessNetwork()
{
public static IPacketNetwork getWirelessNetwork() {
return getInstance().getWirelessNetwork();
}
public static void registerAPIFactory( @Nonnull ILuaAPIFactory factory )
{
getInstance().registerAPIFactory( factory );
public static void registerAPIFactory(@Nonnull ILuaAPIFactory factory) {
getInstance().registerAPIFactory(factory);
}
/**
@@ -226,78 +224,57 @@ public final class ComputerCraftAPI
* @see IWiredElement#getNode()
*/
@Nonnull
public static IWiredNode createWiredNodeForElement( @Nonnull IWiredElement element )
{
return getInstance().createWiredNodeForElement( element );
public static IWiredNode createWiredNodeForElement(@Nonnull IWiredElement element) {
return getInstance().createWiredNodeForElement(element);
}
/**
* Get the wired network element for a block in world
*
* @param world The world the block exists in
* @param pos The position the block exists in
* @param side The side to extract the network element from
* @param pos The position the block exists in
* @param side The side to extract the network element from
* @return The element's node
* @see IWiredElement#getNode()
*/
@Nullable
public static IWiredElement getWiredElementAt( @Nonnull BlockView world, @Nonnull BlockPos pos, @Nonnull Direction side )
{
return getInstance().getWiredElementAt( world, pos, side );
public static IWiredElement getWiredElementAt(@Nonnull BlockView world, @Nonnull BlockPos pos, @Nonnull Direction side) {
return getInstance().getWiredElementAt(world, pos, side);
}
private static IComputerCraftAPI instance;
@Nonnull
private static IComputerCraftAPI getInstance()
{
if( instance != null ) return instance;
try
{
return instance = (IComputerCraftAPI) Class.forName( "dan200.computercraft.ComputerCraftAPIImpl" )
.getField( "INSTANCE" ).get( null );
}
catch( ReflectiveOperationException e )
{
throw new IllegalStateException( "Cannot find ComputerCraft API", e );
}
}
public interface IComputerCraftAPI
{
public interface IComputerCraftAPI {
@Nonnull
String getInstalledVersion();
int createUniqueNumberedSaveDir( @Nonnull World world, @Nonnull String parentSubPath );
int createUniqueNumberedSaveDir(@Nonnull World world, @Nonnull String parentSubPath);
@Nullable
IWritableMount createSaveDirMount( @Nonnull World world, @Nonnull String subPath, long capacity );
IWritableMount createSaveDirMount(@Nonnull World world, @Nonnull String subPath, long capacity);
@Nullable
IMount createResourceMount( @Nonnull String domain, @Nonnull String subPath );
IMount createResourceMount(@Nonnull String domain, @Nonnull String subPath);
void registerPeripheralProvider( @Nonnull IPeripheralProvider provider );
void registerPeripheralProvider(@Nonnull IPeripheralProvider provider);
void registerTurtleUpgrade( @Nonnull ITurtleUpgrade upgrade );
void registerTurtleUpgrade(@Nonnull ITurtleUpgrade upgrade);
void registerBundledRedstoneProvider( @Nonnull IBundledRedstoneProvider provider );
void registerBundledRedstoneProvider(@Nonnull IBundledRedstoneProvider provider);
int getBundledRedstoneOutput( @Nonnull World world, @Nonnull BlockPos pos, @Nonnull Direction side );
int getBundledRedstoneOutput(@Nonnull World world, @Nonnull BlockPos pos, @Nonnull Direction side);
void registerMediaProvider( @Nonnull IMediaProvider provider );
void registerMediaProvider(@Nonnull IMediaProvider provider);
void registerPocketUpgrade( @Nonnull IPocketUpgrade upgrade );
void registerPocketUpgrade(@Nonnull IPocketUpgrade upgrade);
@Nonnull
IPacketNetwork getWirelessNetwork();
void registerAPIFactory( @Nonnull ILuaAPIFactory factory );
void registerAPIFactory(@Nonnull ILuaAPIFactory factory);
@Nonnull
IWiredNode createWiredNodeForElement( @Nonnull IWiredElement element );
IWiredNode createWiredNodeForElement(@Nonnull IWiredElement element);
@Nullable
IWiredElement getWiredElementAt( @Nonnull BlockView world, @Nonnull BlockPos pos, @Nonnull Direction side );
IWiredElement getWiredElementAt(@Nonnull BlockView world, @Nonnull BlockPos pos, @Nonnull Direction side);
}
}

15
src/main/java/dan200/computercraft/api/filesystem/IFileSystem.java
View File

@@ -13,32 +13,31 @@ import java.io.IOException;
*
* This exists for use by various APIs - one should not attempt to mount it.
*/
public interface IFileSystem extends IWritableMount
{
public interface IFileSystem extends IWritableMount {
/**
* Combine two paths together, reducing them into a normalised form.
*
* @param path The main path.
* @param path The main path.
* @param child The path to append.
* @return The combined, normalised path.
*/
String combine( String path, String child );
String combine(String path, String child);
/**
* Copy files from one location to another.
*
* @param from The location to copy from.
* @param to The location to copy to. This should not exist.
* @param to The location to copy to. This should not exist.
* @throws IOException If the copy failed.
*/
void copy( String from, String to ) throws IOException;
void copy(String from, String to) throws IOException;
/**
* Move files from one location to another.
*
* @param from The location to move from.
* @param to The location to move to. This should not exist.
* @param to The location to move to. This should not exist.
* @throws IOException If the move failed.
*/
void move( String from, String to ) throws IOException;
void move(String from, String to) throws IOException;
}

65
src/main/java/dan200/computercraft/api/filesystem/IMount.java
View File

@@ -6,32 +6,31 @@
package dan200.computercraft.api.filesystem;
import dan200.computercraft.api.ComputerCraftAPI;
import dan200.computercraft.api.peripheral.IComputerAccess;
import net.minecraft.world.World;
import javax.annotation.Nonnull;
import java.io.IOException;
import java.io.InputStream;
import java.nio.channels.Channels;
import java.nio.channels.ReadableByteChannel;
import java.util.List;
import javax.annotation.Nonnull;
import dan200.computercraft.api.ComputerCraftAPI;
import dan200.computercraft.api.peripheral.IComputerAccess;
import net.minecraft.world.World;
/**
* Represents a read only part of a virtual filesystem that can be mounted onto a computer using
* {@link IComputerAccess#mount(String, IMount)}
* Represents a read only part of a virtual filesystem that can be mounted onto a computer using {@link IComputerAccess#mount(String, IMount)}
*
* Ready made implementations of this interface can be created using
* {@link ComputerCraftAPI#createSaveDirMount(World, String, long)} or
* {@link ComputerCraftAPI#createResourceMount(Class, String, String)}, or you're free to implement it yourselves!
* Ready made implementations of this interface can be created using {@link ComputerCraftAPI#createSaveDirMount(World, String, long)} or {@link
* ComputerCraftAPI#createResourceMount(Class, String, String)}, or you're free to implement it yourselves!
*
* @see ComputerCraftAPI#createSaveDirMount(World, String, long)
* @see ComputerCraftAPI#createResourceMount(Class, String, String)
* @see IComputerAccess#mount(String, IMount)
* @see IWritableMount
*/
public interface IMount
{
public interface IMount {
/**
* Returns whether a file with a given path exists or not.
*
@@ -39,7 +38,7 @@ public interface IMount
* @return If the file exists.
* @throws IOException If an error occurs when checking the existence of the file.
*/
boolean exists( @Nonnull String path ) throws IOException;
boolean exists(@Nonnull String path) throws IOException;
/**
* Returns whether a file with a given path is a directory or not.
@@ -48,16 +47,16 @@ public interface IMount
* @return If the file exists and is a directory
* @throws IOException If an error occurs when checking whether the file is a directory.
*/
boolean isDirectory( @Nonnull String path ) throws IOException;
boolean isDirectory(@Nonnull String path) throws IOException;
/**
* Returns the file names of all the files in a directory.
*
* @param path A file path in normalised format, relative to the mount location. ie: "programs/myprograms".
* @param path A file path in normalised format, relative to the mount location. ie: "programs/myprograms".
* @param contents A list of strings. Add all the file names to this list.
* @throws IOException If the file was not a directory, or could not be listed.
*/
void list( @Nonnull String path, @Nonnull List<String> contents ) throws IOException;
void list(@Nonnull String path, @Nonnull List<String> contents) throws IOException;
/**
* Returns the size of a file with a given path, in bytes
@@ -66,7 +65,21 @@ public interface IMount
* @return The size of the file, in bytes.
* @throws IOException If the file does not exist, or its size could not be determined.
*/
long getSize( @Nonnull String path ) throws IOException;
long getSize(@Nonnull String path) throws IOException;
/**
* Opens a file with a given path, and returns an {@link ReadableByteChannel} representing its contents.
*
* @param path A file path in normalised format, relative to the mount location. ie: "programs/myprogram".
* @return A channel representing the contents of the file. If the channel implements {@link java.nio.channels.SeekableByteChannel}, one will be able to
* seek to arbitrary positions when using binary mode.
* @throws IOException If the file does not exist, or could not be opened.
*/
@Nonnull
@SuppressWarnings ("deprecation")
default ReadableByteChannel openChannelForRead(@Nonnull String path) throws IOException {
return Channels.newChannel(this.openForRead(path));
}
/**
* Opens a file with a given path, and returns an {@link InputStream} representing its contents.
@@ -78,21 +91,5 @@ public interface IMount
*/
@Nonnull
@Deprecated
InputStream openForRead( @Nonnull String path ) throws IOException;
/**
* Opens a file with a given path, and returns an {@link ReadableByteChannel} representing its contents.
*
* @param path A file path in normalised format, relative to the mount location. ie: "programs/myprogram".
* @return A channel representing the contents of the file. If the channel implements
* {@link java.nio.channels.SeekableByteChannel}, one will be able to seek to arbitrary positions when using binary
* mode.
* @throws IOException If the file does not exist, or could not be opened.
*/
@Nonnull
@SuppressWarnings( "deprecation" )
default ReadableByteChannel openChannelForRead( @Nonnull String path ) throws IOException
{
return Channels.newChannel( openForRead( path ) );
}
InputStream openForRead(@Nonnull String path) throws IOException;
}

77
src/main/java/dan200/computercraft/api/filesystem/IWritableMount.java
View File

@@ -6,37 +6,38 @@
package dan200.computercraft.api.filesystem;
import dan200.computercraft.api.ComputerCraftAPI;
import dan200.computercraft.api.peripheral.IComputerAccess;
import net.minecraft.world.World;
import javax.annotation.Nonnull;
import java.io.IOException;
import java.io.OutputStream;
import java.nio.channels.Channels;
import java.nio.channels.WritableByteChannel;
import javax.annotation.Nonnull;
import dan200.computercraft.api.ComputerCraftAPI;
import dan200.computercraft.api.peripheral.IComputerAccess;
import net.minecraft.world.World;
/**
* Represents a part of a virtual filesystem that can be mounted onto a computer using {@link IComputerAccess#mount(String, IMount)}
* or {@link IComputerAccess#mountWritable(String, IWritableMount)}, that can also be written to.
* Represents a part of a virtual filesystem that can be mounted onto a computer using {@link IComputerAccess#mount(String, IMount)} or {@link
* IComputerAccess#mountWritable(String, IWritableMount)}, that can also be written to.
*
* Ready made implementations of this interface can be created using
* {@link ComputerCraftAPI#createSaveDirMount(World, String, long)}, or you're free to implement it yourselves!
* Ready made implementations of this interface can be created using {@link ComputerCraftAPI#createSaveDirMount(World, String, long)}, or you're free to
* implement it yourselves!
*
* @see ComputerCraftAPI#createSaveDirMount(World, String, long)
* @see IComputerAccess#mount(String, IMount)
* @see IComputerAccess#mountWritable(String, IWritableMount)
* @see IMount
*/
public interface IWritableMount extends IMount
{
public interface IWritableMount extends IMount {
/**
* Creates a directory at a given path inside the virtual file system.
*
* @param path A file path in normalised format, relative to the mount location. ie: "programs/mynewprograms".
* @throws IOException If the directory already exists or could not be created.
*/
void makeDirectory( @Nonnull String path ) throws IOException;
void makeDirectory(@Nonnull String path) throws IOException;
/**
* Deletes a directory at a given path inside the virtual file system.
@@ -44,7 +45,21 @@ public interface IWritableMount extends IMount
* @param path A file path in normalised format, relative to the mount location. ie: "programs/myoldprograms".
* @throws IOException If the file does not exist or could not be deleted.
*/
void delete( @Nonnull String path ) throws IOException;
void delete(@Nonnull String path) throws IOException;
/**
* Opens a file with a given path, and returns an {@link OutputStream} for writing to it.
*
* @param path A file path in normalised format, relative to the mount location. ie: "programs/myprogram".
* @return A stream for writing to. If the channel implements {@link java.nio.channels.SeekableByteChannel}, one will be able to seek to arbitrary
* positions when using binary mode.
* @throws IOException If the file could not be opened for writing.
*/
@Nonnull
@SuppressWarnings ("deprecation")
default WritableByteChannel openChannelForWrite(@Nonnull String path) throws IOException {
return Channels.newChannel(this.openForWrite(path));
}
/**
* Opens a file with a given path, and returns an {@link OutputStream} for writing to it.
@@ -56,21 +71,20 @@ public interface IWritableMount extends IMount
*/
@Nonnull
@Deprecated
OutputStream openForWrite( @Nonnull String path ) throws IOException;
OutputStream openForWrite(@Nonnull String path) throws IOException;
/**
* Opens a file with a given path, and returns an {@link OutputStream} for writing to it.
* Opens a file with a given path, and returns an {@link OutputStream} for appending to it.
*
* @param path A file path in normalised format, relative to the mount location. ie: "programs/myprogram".
* @return A stream for writing to. If the channel implements {@link java.nio.channels.SeekableByteChannel}, one
* will be able to seek to arbitrary positions when using binary mode.
* @return A stream for writing to. If the channel implements {@link java.nio.channels.SeekableByteChannel}, one will be able to seek to arbitrary
* positions when using binary mode.
* @throws IOException If the file could not be opened for writing.
*/
@Nonnull
@SuppressWarnings( "deprecation" )
default WritableByteChannel openChannelForWrite( @Nonnull String path ) throws IOException
{
return Channels.newChannel( openForWrite( path ) );
@SuppressWarnings ("deprecation")
default WritableByteChannel openChannelForAppend(@Nonnull String path) throws IOException {
return Channels.newChannel(this.openForAppend(path));
}
/**
@@ -83,26 +97,11 @@ public interface IWritableMount extends IMount
*/
@Nonnull
@Deprecated
OutputStream openForAppend( @Nonnull String path ) throws IOException;
OutputStream openForAppend(@Nonnull String path) throws IOException;
/**
* Opens a file with a given path, and returns an {@link OutputStream} for appending to it.
*
* @param path A file path in normalised format, relative to the mount location. ie: "programs/myprogram".
* @return A stream for writing to. If the channel implements {@link java.nio.channels.SeekableByteChannel}, one
* will be able to seek to arbitrary positions when using binary mode.
* @throws IOException If the file could not be opened for writing.
*/
@Nonnull
@SuppressWarnings( "deprecation" )
default WritableByteChannel openChannelForAppend( @Nonnull String path ) throws IOException
{
return Channels.newChannel( openForAppend( path ) );
}
/**
* Get the amount of free space on the mount, in bytes. You should decrease this value as the user writes to the
* mount, and write operations should fail once it reaches zero.
* Get the amount of free space on the mount, in bytes. You should decrease this value as the user writes to the mount, and write operations should fail
* once it reaches zero.
*
* @return The amount of free space, in bytes.
* @throws IOException If the remaining space could not be computed.

10
src/main/java/dan200/computercraft/api/lua/IComputerSystem.java
View File

@@ -6,17 +6,15 @@
package dan200.computercraft.api.lua;
import javax.annotation.Nullable;
import dan200.computercraft.api.filesystem.IFileSystem;
import dan200.computercraft.api.peripheral.IComputerAccess;
import javax.annotation.Nullable;
/**
* An interface passed to {@link ILuaAPIFactory} in order to provide additional information
* about a computer.
* An interface passed to {@link ILuaAPIFactory} in order to provide additional information about a computer.
*/
public interface IComputerSystem extends IComputerAccess
{
public interface IComputerSystem extends IComputerAccess {
/**
* Get the file system for this computer.
*

16
src/main/java/dan200/computercraft/api/lua/ILuaAPI.java
View File

@@ -11,14 +11,13 @@ import dan200.computercraft.api.ComputerCraftAPI;
/**
* Represents a {@link ILuaObject} which is stored as a global variable on computer startup.
*
* Before implementing this interface, consider alternative methods of providing methods. It is generally preferred
* to use peripherals to provide functionality to users.
* Before implementing this interface, consider alternative methods of providing methods. It is generally preferred to use peripherals to provide
* functionality to users.
*
* @see ILuaAPIFactory
* @see ComputerCraftAPI#registerAPIFactory(ILuaAPIFactory)
*/
public interface ILuaAPI extends ILuaObject
{
public interface ILuaAPI extends ILuaObject {
/**
* Get the globals this API will be assigned to. This will override any other global, so you should
*
@@ -31,15 +30,13 @@ public interface ILuaAPI extends ILuaObject
*
* One should only interact with the file system.
*/
default void startup()
{
default void startup() {
}
/**
* Called every time the computer is ticked. This can be used to process various.
*/
default void update()
{
default void update() {
}
/**
@@ -47,7 +44,6 @@ public interface ILuaAPI extends ILuaObject
*
* This should reset the state of the object, disposing any remaining file handles, or other resources.
*/
default void shutdown()
{
default void shutdown() {
}
}

9
src/main/java/dan200/computercraft/api/lua/ILuaAPIFactory.java
View File

@@ -6,11 +6,11 @@
package dan200.computercraft.api.lua;
import dan200.computercraft.api.ComputerCraftAPI;
import javax.annotation.Nonnull;
import javax.annotation.Nullable;
import dan200.computercraft.api.ComputerCraftAPI;
/**
* Construct an {@link ILuaAPI} for a specific computer.
*
@@ -18,8 +18,7 @@ import javax.annotation.Nullable;
* @see ComputerCraftAPI#registerAPIFactory(ILuaAPIFactory)
*/
@FunctionalInterface
public interface ILuaAPIFactory
{
public interface ILuaAPIFactory {
/**
* Create a new API instance for a given computer.
*
@@ -27,5 +26,5 @@ public interface ILuaAPIFactory
* @return The created API, or {@code null} if one should not be injected.
*/
@Nullable
ILuaAPI create( @Nonnull IComputerSystem computer );
ILuaAPI create(@Nonnull IComputerSystem computer);
}

89
src/main/java/dan200/computercraft/api/lua/ILuaContext.java
View File

@@ -10,96 +10,87 @@ import javax.annotation.Nonnull;
import javax.annotation.Nullable;
/**
* An interface passed to peripherals and {@link ILuaObject}s by computers or turtles, providing methods
* that allow the peripheral call to wait for events before returning, just like in lua. This is very useful if you need
* to signal work to be performed on the main thread, and don't want to return until the work has been completed.
* An interface passed to peripherals and {@link ILuaObject}s by computers or turtles, providing methods that allow the peripheral call to wait for events
* before returning, just like in lua. This is very useful if you need to signal work to be performed on the main thread, and don't want to return until the
* work has been completed.
*/
public interface ILuaContext
{
public interface ILuaContext {
/**
* Wait for an event to occur on the computer, suspending the thread until it arises. This method is exactly
* equivalent to {@code os.pullEvent()} in lua.
* Wait for an event to occur on the computer, suspending the thread until it arises. This method is exactly equivalent to {@code os.pullEvent()} in
* lua.
*
* @param filter A specific event to wait for, or null to wait for any event.
* @return An object array containing the name of the event that occurred, and any event parameters.
* @throws LuaException If the user presses CTRL+T to terminate the current program while pullEvent() is
* waiting for an event, a "Terminated" exception will be thrown here.
* @throws LuaException If the user presses CTRL+T to terminate the current program while pullEvent() is waiting for an event, a "Terminated"
* exception will be thrown here.
*
* Do not attempt to catch this exception. You should use {@link #pullEventRaw(String)}
* should you wish to disable termination.
* @throws InterruptedException If the user shuts down or reboots the computer while pullEvent() is waiting for an
* event, InterruptedException will be thrown. This exception must not be caught or
* intercepted, or the computer will leak memory and end up in a broken state.
* Do not attempt to catch this exception. You should use {@link #pullEventRaw(String)} should you wish to disable termination.
* @throws InterruptedException If the user shuts down or reboots the computer while pullEvent() is waiting for an event, InterruptedException will
* be thrown. This exception must not be caught or intercepted, or the computer will leak memory and end up in a broken state.
*/
@Nonnull
default Object[] pullEvent( @Nullable String filter ) throws LuaException, InterruptedException
{
Object[] results = pullEventRaw( filter );
if( results.length >= 1 && results[0].equals( "terminate" ) ) throw new LuaException( "Terminated", 0 );
default Object[] pullEvent(@Nullable String filter) throws LuaException, InterruptedException {
Object[] results = this.pullEventRaw(filter);
if (results.length >= 1 && results[0].equals("terminate")) {
throw new LuaException("Terminated", 0);
}
return results;
}
/**
* The same as {@link #pullEvent(String)}, except "terminated" events are ignored. Only use this if you want to
* prevent program termination, which is not recommended. This method is exactly equivalent to
* {@code os.pullEventRaw()} in lua.
* The same as {@link #pullEvent(String)}, except "terminated" events are ignored. Only use this if you want to prevent program termination, which is
* not recommended. This method is exactly equivalent to {@code os.pullEventRaw()} in lua.
*
* @param filter A specific event to wait for, or null to wait for any event.
* @return An object array containing the name of the event that occurred, and any event parameters.
* @throws InterruptedException If the user shuts down or reboots the computer while pullEventRaw() is waiting for
* an event, InterruptedException will be thrown. This exception must not be caught or
* intercepted, or the computer will leak memory and end up in a broken state.
* @throws InterruptedException If the user shuts down or reboots the computer while pullEventRaw() is waiting for an event, InterruptedException
* will be thrown. This exception must not be caught or intercepted, or the computer will leak memory and end up in a broken state.
* @see #pullEvent(String)
*/
@Nonnull
default Object[] pullEventRaw( @Nullable String filter ) throws InterruptedException
{
return yield( new Object[] { filter } );
default Object[] pullEventRaw(@Nullable String filter) throws InterruptedException {
return this.yield(new Object[] {filter});
}
/**
* Yield the current coroutine with some arguments until it is resumed. This method is exactly equivalent to
* {@code coroutine.yield()} in lua. Use {@code pullEvent()} if you wish to wait for events.
* Yield the current coroutine with some arguments until it is resumed. This method is exactly equivalent to {@code coroutine.yield()} in lua. Use
* {@code pullEvent()} if you wish to wait for events.
*
* @param arguments An object array containing the arguments to pass to coroutine.yield()
* @return An object array containing the return values from coroutine.yield()
* @throws InterruptedException If the user shuts down or reboots the computer the coroutine is suspended,
* InterruptedException will be thrown. This exception must not be caught or
* intercepted, or the computer will leak memory and end up in a broken state.
* @throws InterruptedException If the user shuts down or reboots the computer the coroutine is suspended, InterruptedException will be thrown. This
* exception must not be caught or intercepted, or the computer will leak memory and end up in a broken state.
* @see #pullEvent(String)
*/
@Nonnull
Object[] yield( @Nullable Object[] arguments ) throws InterruptedException;
Object[] yield(@Nullable Object[] arguments) throws InterruptedException;
/**
* Queue a task to be executed on the main server thread at the beginning of next tick, waiting for it to complete.
* This should be used when you need to interact with the world in a thread-safe manner.
* Queue a task to be executed on the main server thread at the beginning of next tick, waiting for it to complete. This should be used when you need to
* interact with the world in a thread-safe manner.
*
* Note that the return values of your task are handled as events, meaning more complex objects such as maps or
* {@link ILuaObject} will not preserve their identities.
* Note that the return values of your task are handled as events, meaning more complex objects such as maps or {@link ILuaObject} will not preserve
* their identities.
*
* @param task The task to execute on the main thread.
* @return The objects returned by {@code task}.
* @throws LuaException If the task could not be queued, or if the task threw an exception.
* @throws InterruptedException If the user shuts down or reboots the computer the coroutine is suspended,
* InterruptedException will be thrown. This exception must not be caught or
* intercepted, or the computer will leak memory and end up in a broken state.
* @throws LuaException If the task could not be queued, or if the task threw an exception.
* @throws InterruptedException If the user shuts down or reboots the computer the coroutine is suspended, InterruptedException will be thrown. This
* exception must not be caught or intercepted, or the computer will leak memory and end up in a broken state.
*/
@Nullable
Object[] executeMainThreadTask( @Nonnull ILuaTask task ) throws LuaException, InterruptedException;
Object[] executeMainThreadTask(@Nonnull ILuaTask task) throws LuaException, InterruptedException;
/**
* Queue a task to be executed on the main server thread at the beginning of next tick, but do not wait for it to
* complete. This should be used when you need to interact with the world in a thread-safe manner but do not care
* about the result or you wish to run asynchronously.
* Queue a task to be executed on the main server thread at the beginning of next tick, but do not wait for it to complete. This should be used when you
* need to interact with the world in a thread-safe manner but do not care about the result or you wish to run asynchronously.
*
* When the task has finished, it will enqueue a {@code task_completed} event, which takes the task id, a success
* value and the return values, or an error message if it failed. If you need to wait on this event, it may be
* better to use {@link #executeMainThreadTask(ILuaTask)}.
* When the task has finished, it will enqueue a {@code task_completed} event, which takes the task id, a success value and the return values, or an
* error message if it failed. If you need to wait on this event, it may be better to use {@link #executeMainThreadTask(ILuaTask)}.
*
* @param task The task to execute on the main thread.
* @return The "id" of the task. This will be the first argument to the {@code task_completed} event.
* @throws LuaException If the task could not be queued.
*/
long issueMainThreadTask( @Nonnull ILuaTask task ) throws LuaException;
long issueMainThreadTask(@Nonnull ILuaTask task) throws LuaException;
}

47
src/main/java/dan200/computercraft/api/lua/ILuaObject.java
View File

@@ -6,23 +6,21 @@
package dan200.computercraft.api.lua;
import dan200.computercraft.api.peripheral.IComputerAccess;
import dan200.computercraft.api.peripheral.IPeripheral;
import javax.annotation.Nonnull;
import javax.annotation.Nullable;
import dan200.computercraft.api.peripheral.IComputerAccess;
import dan200.computercraft.api.peripheral.IPeripheral;
/**
* An interface for representing custom objects returned by {@link IPeripheral#callMethod(IComputerAccess, ILuaContext, int, Object[])}
* calls.
* An interface for representing custom objects returned by {@link IPeripheral#callMethod(IComputerAccess, ILuaContext, int, Object[])} calls.
*
* Return objects implementing this interface to expose objects with methods to lua.
*/
public interface ILuaObject
{
public interface ILuaObject {
/**
* Get the names of the methods that this object implements. This works the same as {@link IPeripheral#getMethodNames()}.
* See that method for detailed documentation.
* Get the names of the methods that this object implements. This works the same as {@link IPeripheral#getMethodNames()}. See that method for detailed
* documentation.
*
* @return The method names this object provides.
* @see IPeripheral#getMethodNames()
@@ -31,26 +29,21 @@ public interface ILuaObject
String[] getMethodNames();
/**
* Called when a user calls one of the methods that this object implements. This works the same as
* {@link IPeripheral#callMethod(IComputerAccess, ILuaContext, int, Object[])}}. See that method for detailed
* documentation.
* Called when a user calls one of the methods that this object implements. This works the same as {@link IPeripheral#callMethod(IComputerAccess,
* ILuaContext, int, Object[])}}. See that method for detailed documentation.
*
* @param context The context of the currently running lua thread. This can be used to wait for events
* or otherwise yield.
* @param method An integer identifying which of the methods from getMethodNames() the computercraft
* wishes to call. The integer indicates the index into the getMethodNames() table
* that corresponds to the string passed into peripheral.call()
* @param arguments The arguments for this method. See {@link IPeripheral#callMethod(IComputerAccess, ILuaContext, int, Object[])}
* the possible values and conversion rules.
* @return An array of objects, representing the values you wish to return to the Lua program.
* See {@link IPeripheral#callMethod(IComputerAccess, ILuaContext, int, Object[])} for the valid values and
* conversion rules.
* @throws LuaException If the task could not be queued, or if the task threw an exception.
* @throws InterruptedException If the user shuts down or reboots the computer the coroutine is suspended,
* InterruptedException will be thrown. This exception must not be caught or
* intercepted, or the computer will leak memory and end up in a broken state.w
* @param context The context of the currently running lua thread. This can be used to wait for events or otherwise yield.
* @param method An integer identifying which of the methods from getMethodNames() the computercraft wishes to call. The integer indicates the index
* into the getMethodNames() table that corresponds to the string passed into peripheral.call()
* @param arguments The arguments for this method. See {@link IPeripheral#callMethod(IComputerAccess, ILuaContext, int, Object[])} the possible
* values and conversion rules.
* @return An array of objects, representing the values you wish to return to the Lua program. See {@link IPeripheral#callMethod(IComputerAccess,
* ILuaContext, int, Object[])} for the valid values and conversion rules.
* @throws LuaException If the task could not be queued, or if the task threw an exception.
* @throws InterruptedException If the user shuts down or reboots the computer the coroutine is suspended, InterruptedException will be thrown. This
* exception must not be caught or intercepted, or the computer will leak memory and end up in a broken state.w
* @see IPeripheral#callMethod(IComputerAccess, ILuaContext, int, Object[])
*/
@Nullable
Object[] callMethod( @Nonnull ILuaContext context, int method, @Nonnull Object[] arguments ) throws LuaException, InterruptedException;
Object[] callMethod(@Nonnull ILuaContext context, int method, @Nonnull Object[] arguments) throws LuaException, InterruptedException;
}

16
src/main/java/dan200/computercraft/api/lua/ILuaTask.java
View File

@@ -9,24 +9,20 @@ package dan200.computercraft.api.lua;
import javax.annotation.Nullable;
/**
* A task which can be executed via {@link ILuaContext#executeMainThreadTask(ILuaTask)} or
* {@link ILuaContext#issueMainThreadTask(ILuaTask)}. This will be run on the main thread, at the beginning of the
* next tick.
* A task which can be executed via {@link ILuaContext#executeMainThreadTask(ILuaTask)} or {@link ILuaContext#issueMainThreadTask(ILuaTask)}. This will be
* run on the main thread, at the beginning of the next tick.
*
* @see ILuaContext#executeMainThreadTask(ILuaTask)
* @see ILuaContext#issueMainThreadTask(ILuaTask)
*/
@FunctionalInterface
public interface ILuaTask
{
public interface ILuaTask {
/**
* Execute this task.
*
* @return The arguments to add to the {@code task_completed} event. These will be returned by
* {@link ILuaContext#executeMainThreadTask(ILuaTask)}.
* @throws LuaException If you throw any exception from this function, a lua error will be raised with the
* same message as your exception. Use this to throw appropriate errors if the wrong
* arguments are supplied to your method.
* @return The arguments to add to the {@code task_completed} event. These will be returned by {@link ILuaContext#executeMainThreadTask(ILuaTask)}.
* @throws LuaException If you throw any exception from this function, a lua error will be raised with the same message as your exception. Use this
* to throw appropriate errors if the wrong arguments are supplied to your method.
*/
@Nullable
Object[] execute() throws LuaException;

30
src/main/java/dan200/computercraft/api/lua/LuaException.java
View File

@@ -11,35 +11,29 @@ import javax.annotation.Nullable;
/**
* An exception representing an error in Lua, like that raised by the {@code error()} function.
*/
public class LuaException extends Exception
{
public class LuaException extends Exception {
private static final long serialVersionUID = -6136063076818512651L;
private final int level;
public LuaException()
{
this( "error", 1 );
public LuaException() {
this("error", 1);
}
public LuaException( @Nullable String message )
{
this( message, 1 );
}
public LuaException( @Nullable String message, int level )
{
super( message );
public LuaException(@Nullable String message, int level) {
super(message);
this.level = level;
}
public LuaException(@Nullable String message) {
this(message, 1);
}
/**
* The level this error is raised at. Level 1 is the function's caller, level 2 is that function's caller, and so
* on.
* The level this error is raised at. Level 1 is the function's caller, level 2 is that function's caller, and so on.
*
* @return The level to raise the error at.
*/
public int getLevel()
{
return level;
public int getLevel() {
return this.level;
}
}

38
src/main/java/dan200/computercraft/api/media/IMedia.java
View File

@@ -6,23 +6,22 @@
package dan200.computercraft.api.media;
import javax.annotation.Nonnull;
import javax.annotation.Nullable;
import dan200.computercraft.api.filesystem.IMount;
import net.minecraft.item.Item;
import net.minecraft.item.ItemStack;
import net.minecraft.sound.SoundEvent;
import net.minecraft.world.World;
import javax.annotation.Nonnull;
import javax.annotation.Nullable;
/**
* Represents an item that can be placed in a disk drive and used by a Computer.
*
* Implement this interface on your {@link Item} class to allow it to be used in the drive. Alternatively, register
* a {@link IMediaProvider}.
* Implement this interface on your {@link Item} class to allow it to be used in the drive. Alternatively, register a {@link IMediaProvider}.
*/
public interface IMedia
{
public interface IMedia {
/**
* Get a string representing the label of this item. Will be called via {@code disk.getLabel()} in lua.
*
@@ -30,7 +29,7 @@ public interface IMedia
* @return The label. ie: "Dan's Programs".
*/
@Nullable
String getLabel( @Nonnull ItemStack stack );
String getLabel(@Nonnull ItemStack stack);
/**
* Set a string representing the label of this item. Will be called vi {@code disk.setLabel()} in lua.
@@ -39,21 +38,18 @@ public interface IMedia
* @param label The string to set the label to.
* @return true if the label was updated, false if the label may not be modified.
*/
default boolean setLabel( @Nonnull ItemStack stack, @Nullable String label )
{
default boolean setLabel(@Nonnull ItemStack stack, @Nullable String label) {
return false;
}
/**
* If this disk represents an item with audio (like a record), get the readable name of the audio track. ie:
* "Jonathan Coulton - Still Alive"
* If this disk represents an item with audio (like a record), get the readable name of the audio track. ie: "Jonathan Coulton - Still Alive"
*
* @param stack The {@link ItemStack} to modify.
* @return The name, or null if this item does not represent an item with audio.
*/
@Nullable
default String getAudioTitle( @Nonnull ItemStack stack )
{
default String getAudioTitle(@Nonnull ItemStack stack) {
return null;
}
@@ -64,27 +60,25 @@ public interface IMedia
* @return The name, or null if this item does not represent an item with audio.
*/
@Nullable
default SoundEvent getAudio( @Nonnull ItemStack stack )
{
default SoundEvent getAudio(@Nonnull ItemStack stack) {
return null;
}
/**
* If this disk represents an item with data (like a floppy disk), get a mount representing it's contents. This will
* be mounted onto the filesystem of the computer while the media is in the disk drive.
* If this disk represents an item with data (like a floppy disk), get a mount representing it's contents. This will be mounted onto the filesystem of
* the computer while the media is in the disk drive.
*
* @param stack The {@link ItemStack} to modify.
* @param world The world in which the item and disk drive reside.
* @return The mount, or null if this item does not represent an item with data. If the mount returned also
* implements {@link dan200.computercraft.api.filesystem.IWritableMount}, it will mounted using mountWritable()
* @return The mount, or null if this item does not represent an item with data. If the mount returned also implements {@link
* dan200.computercraft.api.filesystem.IWritableMount}, it will mounted using mountWritable()
* @see IMount
* @see dan200.computercraft.api.filesystem.IWritableMount
* @see dan200.computercraft.api.ComputerCraftAPI#createSaveDirMount(World, String, long)
* @see dan200.computercraft.api.ComputerCraftAPI#createResourceMount(Class, String, String)
*/
@Nullable
default IMount createDataMount( @Nonnull ItemStack stack, @Nonnull World world )
{
default IMount createDataMount(@Nonnull ItemStack stack, @Nonnull World world) {
return null;
}
}

9
src/main/java/dan200/computercraft/api/media/IMediaProvider.java
View File

@@ -6,19 +6,18 @@
package dan200.computercraft.api.media;
import net.minecraft.item.ItemStack;
import javax.annotation.Nonnull;
import javax.annotation.Nullable;
import net.minecraft.item.ItemStack;
/**
* This interface is used to provide {@link IMedia} implementations for {@link ItemStack}.
*
* @see dan200.computercraft.api.ComputerCraftAPI#registerMediaProvider(IMediaProvider)
*/
@FunctionalInterface
public interface IMediaProvider
{
public interface IMediaProvider {
/**
* Produce an IMedia implementation from an ItemStack.
*
@@ -27,5 +26,5 @@ public interface IMediaProvider
* @see dan200.computercraft.api.ComputerCraftAPI#registerMediaProvider(IMediaProvider)
*/
@Nullable
IMedia getMedia( @Nonnull ItemStack stack );
IMedia getMedia(@Nonnull ItemStack stack);
}

22
src/main/java/dan200/computercraft/api/network/IPacketNetwork.java
View File

@@ -3,6 +3,7 @@
* Copyright Daniel Ratcliffe, 2011-2019. This API may be redistributed unmodified and in full only.
* For help using the API, and posting your mods, visit the forums at computercraft.info.
*/
package dan200.computercraft.api.network;
import javax.annotation.Nonnull;
@@ -13,21 +14,20 @@ import javax.annotation.Nonnull;
* @see Packet
* @see IPacketReceiver
*/
public interface IPacketNetwork
{
public interface IPacketNetwork {
/**
* Add a receiver to the network.
*
* @param receiver The receiver to register to the network.
*/
void addReceiver( @Nonnull IPacketReceiver receiver );
void addReceiver(@Nonnull IPacketReceiver receiver);
/**
* Remove a receiver from the network.
*
* @param receiver The device to remove from the network.
*/
void removeReceiver( @Nonnull IPacketReceiver receiver );
void removeReceiver(@Nonnull IPacketReceiver receiver);
/**
* Determine whether this network is wireless.
@@ -37,23 +37,23 @@ public interface IPacketNetwork
boolean isWireless();
/**
* Submit a packet for transmitting across the network. This will route the packet through the network, sending it
* to all receivers within range (or any interdimensional ones).
* Submit a packet for transmitting across the network. This will route the packet through the network, sending it to all receivers within range (or any
* interdimensional ones).
*
* @param packet The packet to send.
* @param range The maximum distance this packet will be sent.
* @param range The maximum distance this packet will be sent.
* @see #transmitInterdimensional(Packet)
* @see IPacketReceiver#receiveSameDimension(Packet, double)
*/
void transmitSameDimension( @Nonnull Packet packet, double range );
void transmitSameDimension(@Nonnull Packet packet, double range);
/**
* Submit a packet for transmitting across the network. This will route the packet through the network, sending it
* to all receivers across all dimensions.
* Submit a packet for transmitting across the network. This will route the packet through the network, sending it to all receivers across all
* dimensions.
*
* @param packet The packet to send.
* @see #transmitSameDimension(Packet, double)
* @see IPacketReceiver#receiveDifferentDimension(Packet)
*/
void transmitInterdimensional( @Nonnull Packet packet );
void transmitInterdimensional(@Nonnull Packet packet);
}

25
src/main/java/dan200/computercraft/api/network/IPacketReceiver.java
View File

@@ -3,18 +3,18 @@
* Copyright Daniel Ratcliffe, 2011-2019. This API may be redistributed unmodified and in full only.
* For help using the API, and posting your mods, visit the forums at computercraft.info.
*/
package dan200.computercraft.api.network;
import javax.annotation.Nonnull;
import net.minecraft.util.math.Vec3d;
import net.minecraft.world.World;
import javax.annotation.Nonnull;
/**
* An object on an {@link IPacketNetwork}, capable of receiving packets.
*/
public interface IPacketReceiver
{
public interface IPacketReceiver {
/**
* Get the world in which this packet receiver exists.
*
@@ -34,9 +34,8 @@ public interface IPacketReceiver
/**
* Get the maximum distance this receiver can send and receive messages.
*
* When determining whether a receiver can receive a message, the largest distance of the packet and receiver is
* used - ensuring it is within range. If the packet or receiver is inter-dimensional, then the packet will always
* be received.
* When determining whether a receiver can receive a message, the largest distance of the packet and receiver is used - ensuring it is within range. If
* the packet or receiver is inter-dimensional, then the packet will always be received.
*
* @return The maximum distance this device can send and receive messages.
* @see #isInterdimensional()
@@ -60,25 +59,25 @@ public interface IPacketReceiver
/**
* Receive a network packet from the same dimension.
*
* @param packet The packet to receive. Generally you should check that you are listening on the given channel and,
* if so, queue the appropriate modem event.
* @param packet The packet to receive. Generally you should check that you are listening on the given channel and, if so, queue the appropriate
* modem event.
* @param distance The distance this packet has travelled from the source.
* @see Packet
* @see #getRange()
* @see IPacketNetwork#transmitSameDimension(Packet, double)
* @see IPacketNetwork#transmitInterdimensional(Packet)
*/
void receiveSameDimension( @Nonnull Packet packet, double distance );
void receiveSameDimension(@Nonnull Packet packet, double distance);
/**
* Receive a network packet from a different dimension.
*
* @param packet The packet to receive. Generally you should check that you are listening on the given channel and,
* if so, queue the appropriate modem event.
* @param packet The packet to receive. Generally you should check that you are listening on the given channel and, if so, queue the appropriate
* modem event.
* @see Packet
* @see IPacketNetwork#transmitInterdimensional(Packet)
* @see IPacketNetwork#transmitSameDimension(Packet, double)
* @see #isInterdimensional()
*/
void receiveDifferentDimension( @Nonnull Packet packet );
void receiveDifferentDimension(@Nonnull Packet packet);
}

12
src/main/java/dan200/computercraft/api/network/IPacketSender.java
View File

@@ -3,18 +3,18 @@
* Copyright Daniel Ratcliffe, 2011-2019. This API may be redistributed unmodified and in full only.
* For help using the API, and posting your mods, visit the forums at computercraft.info.
*/
package dan200.computercraft.api.network;
import javax.annotation.Nonnull;
import net.minecraft.util.math.Vec3d;
import net.minecraft.world.World;
import javax.annotation.Nonnull;
/**
* An object on a {@link IPacketNetwork}, capable of sending packets.
*/
public interface IPacketSender
{
public interface IPacketSender {
/**
* Get the world in which this packet sender exists.
*
@@ -32,8 +32,8 @@ public interface IPacketSender
Vec3d getPosition();
/**
* Get some sort of identification string for this sender. This does not strictly need to be unique, but you
* should be able to extract some identifiable information from it.
* Get some sort of identification string for this sender. This does not strictly need to be unique, but you should be able to extract some identifiable
* information from it.
*
* @return This device's id.
*/

93
src/main/java/dan200/computercraft/api/network/Packet.java
View File

@@ -3,11 +3,13 @@
* Copyright Daniel Ratcliffe, 2011-2019. This API may be redistributed unmodified and in full only.
* For help using the API, and posting your mods, visit the forums at computercraft.info.
*/
package dan200.computercraft.api.network;
import java.util.Objects;
import javax.annotation.Nonnull;
import javax.annotation.Nullable;
import java.util.Objects;
/**
* Represents a packet which may be sent across a {@link IPacketNetwork}.
@@ -18,8 +20,7 @@ import java.util.Objects;
* @see IPacketReceiver#receiveDifferentDimension(Packet)
* @see IPacketReceiver#receiveSameDimension(Packet, double)
*/
public class Packet
{
public class Packet {
private final int channel;
private final int replyChannel;
private final Object payload;
@@ -29,16 +30,14 @@ public class Packet
/**
* Create a new packet, ready for transmitting across the network.
*
* @param channel The channel to send the packet along. Receiving devices should only process packets from on
* channels they are listening to.
* @param channel The channel to send the packet along. Receiving devices should only process packets from on channels they are listening to.
* @param replyChannel The channel to reply on.
* @param payload The contents of this packet. This should be a "valid" Lua object, safe for queuing as an
* event or returning from a peripheral call.
* @param sender The object which sent this packet.
* @param payload The contents of this packet. This should be a "valid" Lua object, safe for queuing as an event or returning from a peripheral
* call.
* @param sender The object which sent this packet.
*/
public Packet( int channel, int replyChannel, @Nullable Object payload, @Nonnull IPacketSender sender )
{
Objects.requireNonNull( sender, "sender cannot be null" );
public Packet(int channel, int replyChannel, @Nullable Object payload, @Nonnull IPacketSender sender) {
Objects.requireNonNull(sender, "sender cannot be null");
this.channel = channel;
this.replyChannel = replyChannel;
@@ -47,14 +46,12 @@ public class Packet
}
/**
* Get the channel this packet is sent along. Receivers should generally only process packets from on channels they
* are listening to.
* Get the channel this packet is sent along. Receivers should generally only process packets from on channels they are listening to.
*
* @return This packet's channel.
*/
public int getChannel()
{
return channel;
public int getChannel() {
return this.channel;
}
/**
@@ -62,21 +59,18 @@ public class Packet
*
* @return This channel to reply on.
*/
public int getReplyChannel()
{
return replyChannel;
public int getReplyChannel() {
return this.replyChannel;
}
/**
* The actual data of this packet. This should be a "valid" Lua object, safe for queuing as an
* event or returning from a peripheral call.
* The actual data of this packet. This should be a "valid" Lua object, safe for queuing as an event or returning from a peripheral call.
*
* @return The packet's payload
*/
@Nullable
public Object getPayload()
{
return payload;
public Object getPayload() {
return this.payload;
}
/**
@@ -85,33 +79,40 @@ public class Packet
* @return The sending object.
*/
@Nonnull
public IPacketSender getSender()
{
return sender;
public IPacketSender getSender() {
return this.sender;
}
@Override
public boolean equals( Object o )
{
if( this == o ) return true;
if( o == null || getClass() != o.getClass() ) return false;
public int hashCode() {
int result;
result = this.channel;
result = 31 * result + this.replyChannel;
result = 31 * result + (this.payload != null ? this.payload.hashCode() : 0);
result = 31 * result + this.sender.hashCode();
return result;
}
@Override
public boolean equals(Object o) {
if (this == o) {
return true;
}
if (o == null || this.getClass() != o.getClass()) {
return false;
}
Packet packet = (Packet) o;
if( channel != packet.channel ) return false;
if( replyChannel != packet.replyChannel ) return false;
if( !Objects.equals( payload, packet.payload ) ) return false;
return sender.equals( packet.sender );
}
@Override
public int hashCode()
{
int result;
result = channel;
result = 31 * result + replyChannel;
result = 31 * result + (payload != null ? payload.hashCode() : 0);
result = 31 * result + sender.hashCode();
return result;
if (this.channel != packet.channel) {
return false;
}
if (this.replyChannel != packet.replyChannel) {
return false;
}
if (!Objects.equals(this.payload, packet.payload)) {
return false;
}
return this.sender.equals(packet.sender);
}
}

22
src/main/java/dan200/computercraft/api/network/wired/IWiredElement.java
View File

@@ -6,30 +6,26 @@
package dan200.computercraft.api.network.wired;
import dan200.computercraft.api.ComputerCraftAPI;
import javax.annotation.Nonnull;
import dan200.computercraft.api.ComputerCraftAPI;
/**
* An object which may be part of a wired network.
*
* Elements should construct a node using {@link ComputerCraftAPI#createWiredNodeForElement(IWiredElement)}. This acts
* as a proxy for all network objects. Whilst the node may change networks, an element's node should remain constant
* for its lifespan.
* Elements should construct a node using {@link ComputerCraftAPI#createWiredNodeForElement(IWiredElement)}. This acts as a proxy for all network objects.
* Whilst the node may change networks, an element's node should remain constant for its lifespan.
*
* Elements are generally tied to a block or tile entity in world. In such as case, one should provide the
* {@link IWiredElement} capability for the appropriate sides.
* Elements are generally tied to a block or tile entity in world. In such as case, one should provide the {@link IWiredElement} capability for the
* appropriate sides.
*/
public interface IWiredElement extends IWiredSender
{
public interface IWiredElement extends IWiredSender {
/**
* Called when objects on the network change. This may occur when network nodes are added or removed, or when
* peripherals change.
* Called when objects on the network change. This may occur when network nodes are added or removed, or when peripherals change.
*
* @param change The change which occurred.
* @see IWiredNetworkChange
*/
default void networkChanged( @Nonnull IWiredNetworkChange change )
{
default void networkChanged(@Nonnull IWiredNetworkChange change) {
}
}

49
src/main/java/dan200/computercraft/api/network/wired/IWiredNetwork.java
View File

@@ -6,48 +6,46 @@
package dan200.computercraft.api.network.wired;
import dan200.computercraft.api.peripheral.IPeripheral;
import javax.annotation.Nonnull;
import java.util.Map;
import javax.annotation.Nonnull;
import dan200.computercraft.api.peripheral.IPeripheral;
/**
* A wired network is composed of one of more {@link IWiredNode}s, a set of connections between them, and a series
* of peripherals.
* A wired network is composed of one of more {@link IWiredNode}s, a set of connections between them, and a series of peripherals.
*
* Networks from a connected graph. This means there is some path between all nodes on the network. Further more, if
* there is some path between two nodes then they must be on the same network. {@link IWiredNetwork} will automatically
* handle the merging and splitting of networks (and thus changing of available nodes and peripherals) as connections
* change.
* Networks from a connected graph. This means there is some path between all nodes on the network. Further more, if there is some path between two nodes
* then they must be on the same network. {@link IWiredNetwork} will automatically handle the merging and splitting of networks (and thus changing of
* available nodes and peripherals) as connections change.
*
* This does mean one can not rely on the network remaining consistent between subsequent operations. Consequently,
* it is generally preferred to use the methods provided by {@link IWiredNode}.
* This does mean one can not rely on the network remaining consistent between subsequent operations. Consequently, it is generally preferred to use the
* methods provided by {@link IWiredNode}.
*
* @see IWiredNode#getNetwork()
*/
public interface IWiredNetwork
{
public interface IWiredNetwork {
/**
* Create a connection between two nodes.
*
* This should only be used on the server thread.
*
* @param left The first node to connect
* @param left The first node to connect
* @param right The second node to connect
* @return {@code true} if a connection was created or {@code false} if the connection already exists.
* @throws IllegalStateException If neither node is on the network.
* @throws IllegalStateException If neither node is on the network.
* @throws IllegalArgumentException If {@code left} and {@code right} are equal.
* @see IWiredNode#connectTo(IWiredNode)
* @see IWiredNetwork#connect(IWiredNode, IWiredNode)
*/
boolean connect( @Nonnull IWiredNode left, @Nonnull IWiredNode right );
boolean connect(@Nonnull IWiredNode left, @Nonnull IWiredNode right);
/**
* Destroy a connection between this node and another.
*
* This should only be used on the server thread.
*
* @param left The first node in the connection.
* @param left The first node in the connection.
* @param right The second node in the connection.
* @return {@code true} if a connection was destroyed or {@code false} if no connection exists.
* @throws IllegalArgumentException If either node is not on the network.
@@ -55,32 +53,29 @@ public interface IWiredNetwork
* @see IWiredNode#disconnectFrom(IWiredNode)
* @see IWiredNetwork#connect(IWiredNode, IWiredNode)
*/
boolean disconnect( @Nonnull IWiredNode left, @Nonnull IWiredNode right );
boolean disconnect(@Nonnull IWiredNode left, @Nonnull IWiredNode right);
/**
* Sever all connections this node has, removing it from this network.
*
* This should only be used on the server thread. You should only call this on nodes
* that your network element owns.
* This should only be used on the server thread. You should only call this on nodes that your network element owns.
*
* @param node The node to remove
* @return Whether this node was removed from the network. One cannot remove a node from a network where it is the
* only element.
* @return Whether this node was removed from the network. One cannot remove a node from a network where it is the only element.
* @throws IllegalArgumentException If the node is not in the network.
* @see IWiredNode#remove()
*/
boolean remove( @Nonnull IWiredNode node );
boolean remove(@Nonnull IWiredNode node);
/**
* Update the peripherals a node provides.
*
* This should only be used on the server thread. You should only call this on nodes
* that your network element owns.
* This should only be used on the server thread. You should only call this on nodes that your network element owns.
*
* @param node The node to attach peripherals for.
* @param node The node to attach peripherals for.
* @param peripherals The new peripherals for this node.
* @throws IllegalArgumentException If the node is not in the network.
* @see IWiredNode#updatePeripherals(Map)
*/
void updatePeripherals( @Nonnull IWiredNode node, @Nonnull Map<String, IPeripheral> peripherals );
void updatePeripherals(@Nonnull IWiredNode node, @Nonnull Map<String, IPeripheral> peripherals);
}

16
src/main/java/dan200/computercraft/api/network/wired/IWiredNetworkChange.java
View File

@@ -6,21 +6,21 @@
package dan200.computercraft.api.network.wired;
import dan200.computercraft.api.peripheral.IPeripheral;
import java.util.Map;
import javax.annotation.Nonnull;
import java.util.Map;
import dan200.computercraft.api.peripheral.IPeripheral;
/**
* Represents a change to the objects on a wired network.
*
* @see IWiredElement#networkChanged(IWiredNetworkChange)
*/
public interface IWiredNetworkChange
{
public interface IWiredNetworkChange {
/**
* A set of peripherals which have been removed. Note that there may be entries with the same name
* in the added and removed set, but with a different peripheral.
* A set of peripherals which have been removed. Note that there may be entries with the same name in the added and removed set, but with a different
* peripheral.
*
* @return The set of removed peripherals.
*/
@@ -28,8 +28,8 @@ public interface IWiredNetworkChange
Map<String, IPeripheral> peripheralsRemoved();
/**
* A set of peripherals which have been added. Note that there may be entries with the same name
* in the added and removed set, but with a different peripheral.
* A set of peripherals which have been added. Note that there may be entries with the same name in the added and removed set, but with a different
* peripheral.
*
* @return The set of added peripherals.
*/

73
src/main/java/dan200/computercraft/api/network/wired/IWiredNode.java
View File

@@ -6,27 +6,26 @@
package dan200.computercraft.api.network.wired;
import dan200.computercraft.api.network.IPacketNetwork;
import dan200.computercraft.api.peripheral.IPeripheral;
import java.util.Map;
import javax.annotation.Nonnull;
import java.util.Map;
import dan200.computercraft.api.network.IPacketNetwork;
import dan200.computercraft.api.peripheral.IPeripheral;
/**
* Wired nodes act as a layer between {@link IWiredElement}s and {@link IWiredNetwork}s.
*
* Firstly, a node acts as a packet network, capable of sending and receiving modem messages to connected nodes. These
* methods may be safely used on any thread.
* Firstly, a node acts as a packet network, capable of sending and receiving modem messages to connected nodes. These methods may be safely used on any
* thread.
*
* When sending a packet, the system will attempt to find the shortest path between the two nodes based on their
* element's position. Note that packet senders and receivers can have different locations from their associated
* element: the distance between the two will be added to the total packet's distance.
* When sending a packet, the system will attempt to find the shortest path between the two nodes based on their element's position. Note that packet
* senders and receivers can have different locations from their associated element: the distance between the two will be added to the total packet's
* distance.
*
* Wired nodes also provide several convenience methods for interacting with a wired network. These should only ever
* be used on the main server thread.
* Wired nodes also provide several convenience methods for interacting with a wired network. These should only ever be used on the main server thread.
*/
public interface IWiredNode extends IPacketNetwork
{
public interface IWiredNode extends IPacketNetwork {
/**
* The associated element for this network node.
*
@@ -35,17 +34,6 @@ public interface IWiredNode extends IPacketNetwork
@Nonnull
IWiredElement getElement();
/**
* The network this node is currently connected to. Note that this may change
* after any network operation, so it should not be cached.
*
* This should only be used on the server thread.
*
* @return This node's network.
*/
@Nonnull
IWiredNetwork getNetwork();
/**
* Create a connection from this node to another.
*
@@ -56,11 +44,20 @@ public interface IWiredNode extends IPacketNetwork
* @see IWiredNetwork#connect(IWiredNode, IWiredNode)
* @see IWiredNode#disconnectFrom(IWiredNode)
*/
default boolean connectTo( @Nonnull IWiredNode node )
{
return getNetwork().connect( this, node );
default boolean connectTo(@Nonnull IWiredNode node) {
return this.getNetwork().connect(this, node);
}
/**
* The network this node is currently connected to. Note that this may change after any network operation, so it should not be cached.
*
* This should only be used on the server thread.
*
* @return This node's network.
*/
@Nonnull
IWiredNetwork getNetwork();
/**
* Destroy a connection between this node and another.
*
@@ -72,38 +69,32 @@ public interface IWiredNode extends IPacketNetwork
* @see IWiredNetwork#disconnect(IWiredNode, IWiredNode)
* @see IWiredNode#connectTo(IWiredNode)
*/
default boolean disconnectFrom( @Nonnull IWiredNode node )
{
return getNetwork().disconnect( this, node );
default boolean disconnectFrom(@Nonnull IWiredNode node) {
return this.getNetwork().disconnect(this, node);
}
/**
* Sever all connections this node has, removing it from this network.
*
* This should only be used on the server thread. You should only call this on nodes
* that your network element owns.
* This should only be used on the server thread. You should only call this on nodes that your network element owns.
*
* @return Whether this node was removed from the network. One cannot remove a node from a network where it is the
* only element.
* @return Whether this node was removed from the network. One cannot remove a node from a network where it is the only element.
* @throws IllegalArgumentException If the node is not in the network.
* @see IWiredNetwork#remove(IWiredNode)
*/
default boolean remove()
{
return getNetwork().remove( this );
default boolean remove() {
return this.getNetwork().remove(this);
}
/**
* Mark this node's peripherals as having changed.
*
* This should only be used on the server thread. You should only call this on nodes
* that your network element owns.
* This should only be used on the server thread. You should only call this on nodes that your network element owns.
*
* @param peripherals The new peripherals for this node.
* @see IWiredNetwork#updatePeripherals(IWiredNode, Map)
*/
default void updatePeripherals( @Nonnull Map<String, IPeripheral> peripherals )
{
getNetwork().updatePeripherals( this, peripherals );
default void updatePeripherals(@Nonnull Map<String, IPeripheral> peripherals) {
this.getNetwork().updatePeripherals(this, peripherals);
}
}

13
src/main/java/dan200/computercraft/api/network/wired/IWiredSender.java
View File

@@ -6,23 +6,20 @@
package dan200.computercraft.api.network.wired;
import dan200.computercraft.api.network.IPacketSender;
import javax.annotation.Nonnull;
import dan200.computercraft.api.network.IPacketSender;
/**
* An object on a {@link IWiredNetwork} capable of sending packets.
*
* Unlike a regular {@link IPacketSender}, this must be associated with the node you are attempting to
* to send the packet from.
* Unlike a regular {@link IPacketSender}, this must be associated with the node you are attempting to to send the packet from.
*/
public interface IWiredSender extends IPacketSender
{
public interface IWiredSender extends IPacketSender {
/**
* The node in the network representing this object.
*
* This should be used as a proxy for the main network. One should send packets
* and register receivers through this object.
* This should be used as a proxy for the main network. One should send packets and register receivers through this object.
*
* @return The node for this element.
*/

239
src/main/java/dan200/computercraft/api/peripheral/IComputerAccess.java
View File

@@ -6,32 +6,32 @@
package dan200.computercraft.api.peripheral;
import java.util.Collections;
import java.util.Map;
import javax.annotation.Nonnull;
import javax.annotation.Nullable;
import dan200.computercraft.api.ComputerCraftAPI;
import dan200.computercraft.api.filesystem.IMount;
import dan200.computercraft.api.filesystem.IWritableMount;
import dan200.computercraft.api.lua.ILuaContext;
import dan200.computercraft.api.lua.ILuaTask;
import net.minecraft.world.World;
import javax.annotation.Nonnull;
import javax.annotation.Nullable;
import java.util.Collections;
import java.util.Map;
/**
* The interface passed to peripherals by computers or turtles, providing methods
* that they can call. This should not be implemented by your classes. Do not interact
* with computers except via this interface.
* The interface passed to peripherals by computers or turtles, providing methods that they can call. This should not be implemented by your classes. Do not
* interact with computers except via this interface.
*/
public interface IComputerAccess
{
public interface IComputerAccess {
/**
* Mount a mount onto the computer's file system in a read only mode.
*
* @param desiredLocation The location on the computer's file system where you would like the mount to be mounted.
* @param mount The mount object to mount on the computer.
* @return The location on the computer's file system where you the mount mounted, or {@code null} if there was already a
* file in the desired location. Store this value if you wish to unmount the mount later.
* @param mount The mount object to mount on the computer.
* @return The location on the computer's file system where you the mount mounted, or {@code null} if there was already a file in the desired location.
* Store this value if you wish to unmount the mount later.
* @throws RuntimeException If the peripheral has been detached.
* @see ComputerCraftAPI#createSaveDirMount(World, String, long)
* @see ComputerCraftAPI#createResourceMount(Class, String, String)
@@ -41,19 +41,18 @@ public interface IComputerAccess
* @see IMount
*/
@Nullable
default String mount( @Nonnull String desiredLocation, @Nonnull IMount mount )
{
return mount( desiredLocation, mount, getAttachmentName() );
default String mount(@Nonnull String desiredLocation, @Nonnull IMount mount) {
return this.mount(desiredLocation, mount, this.getAttachmentName());
}
/**
* Mount a mount onto the computer's file system in a read only mode.
*
* @param desiredLocation The location on the computer's file system where you would like the mount to be mounted.
* @param mount The mount object to mount on the computer.
* @param driveName A custom name to give for this mount location, as returned by {@code fs.getDrive()}.
* @return The location on the computer's file system where you the mount mounted, or {@code null} if there was already a
* file in the desired location. Store this value if you wish to unmount the mount later.
* @param mount The mount object to mount on the computer.
* @param driveName A custom name to give for this mount location, as returned by {@code fs.getDrive()}.
* @return The location on the computer's file system where you the mount mounted, or {@code null} if there was already a file in the desired location.
* Store this value if you wish to unmount the mount later.
* @throws RuntimeException If the peripheral has been detached.
* @see ComputerCraftAPI#createSaveDirMount(World, String, long)
* @see ComputerCraftAPI#createResourceMount(Class, String, String)
@@ -63,101 +62,12 @@ public interface IComputerAccess
* @see IMount
*/
@Nullable
String mount( @Nonnull String desiredLocation, @Nonnull IMount mount, @Nonnull String driveName );
String mount(@Nonnull String desiredLocation, @Nonnull IMount mount, @Nonnull String driveName);
/**
* Mount a mount onto the computer's file system in a writable mode.
*
* @param desiredLocation The location on the computer's file system where you would like the mount to be mounted.
* @param mount The mount object to mount on the computer.
* @return The location on the computer's file system where you the mount mounted, or null if there was already a
* file in the desired location. Store this value if you wish to unmount the mount later.
* @throws RuntimeException If the peripheral has been detached.
* @see ComputerCraftAPI#createSaveDirMount(World, String, long)
* @see ComputerCraftAPI#createResourceMount(Class, String, String)
* @see #mount(String, IMount)
* @see #unmount(String)
* @see IMount
*/
@Nullable
default String mountWritable( @Nonnull String desiredLocation, @Nonnull IWritableMount mount )
{
return mountWritable( desiredLocation, mount, getAttachmentName() );
}
/**
* Mount a mount onto the computer's file system in a writable mode.
*
* @param desiredLocation The location on the computer's file system where you would like the mount to be mounted.
* @param mount The mount object to mount on the computer.
* @param driveName A custom name to give for this mount location, as returned by {@code fs.getDrive()}.
* @return The location on the computer's file system where you the mount mounted, or null if there was already a
* file in the desired location. Store this value if you wish to unmount the mount later.
* @throws RuntimeException If the peripheral has been detached.
* @see ComputerCraftAPI#createSaveDirMount(World, String, long)
* @see ComputerCraftAPI#createResourceMount(Class, String, String)
* @see #mount(String, IMount)
* @see #unmount(String)
* @see IMount
*/
String mountWritable( @Nonnull String desiredLocation, @Nonnull IWritableMount mount, @Nonnull String driveName );
/**
* Unmounts a directory previously mounted onto the computers file system by {@link #mount(String, IMount)}
* or {@link #mountWritable(String, IWritableMount)}.
*
* When a directory is unmounted, it will disappear from the computers file system, and the user will no longer be
* able to access it. All directories mounted by a mount or mountWritable are automatically unmounted when the
* peripheral is attached if they have not been explicitly unmounted.
*
* Note that you cannot unmount another peripheral's mounts.
*
* @param location The desired location in the computers file system of the directory to unmount.
* This must be the location of a directory previously mounted by {@link #mount(String, IMount)} or
* {@link #mountWritable(String, IWritableMount)}, as indicated by their return value.
* @throws RuntimeException If the peripheral has been detached.
* @throws RuntimeException If the mount does not exist, or was mounted by another peripheral.
* @see #mount(String, IMount)
* @see #mountWritable(String, IWritableMount)
*/
void unmount( @Nullable String location );
/**
* Returns the numerical ID of this computer.
*
* This is the same number obtained by calling {@code os.getComputerID()} or running the "id" program from lua,
* and is guaranteed unique. This number will be positive.
*
* @return The identifier.
*/
int getID();
/**
* Causes an event to be raised on this computer, which the computer can respond to by calling
* {@code os.pullEvent()}. This can be used to notify the computer when things happen in the world or to
* this peripheral.
*
* @param event A string identifying the type of event that has occurred, this will be
* returned as the first value from {@code os.pullEvent()}. It is recommended that you
* you choose a name that is unique, and recognisable as originating from your
* peripheral. eg: If your peripheral type is "button", a suitable event would be
* "button_pressed".
* @param arguments In addition to a name, you may pass an array of extra arguments to the event, that will
* be supplied as extra return values to os.pullEvent(). Objects in the array will be converted
* to lua data types in the same fashion as the return values of IPeripheral.callMethod().
*
* You may supply {@code null} to indicate that no arguments are to be supplied.
* @throws RuntimeException If the peripheral has been detached.
* @see IPeripheral#callMethod
*/
void queueEvent( @Nonnull String event, @Nullable Object[] arguments );
/**
* Get a string, unique to the computer, by which the computer refers to this peripheral.
* For directly attached peripherals this will be "left","right","front","back",etc, but
* for peripherals attached remotely it will be different. It is good practice to supply
* this string when raising events to the computer, so that the computer knows from
* which peripheral the event came.
* Get a string, unique to the computer, by which the computer refers to this peripheral. For directly attached peripherals this will be
* "left","right","front","back",etc, but for peripherals attached remotely it will be different. It is good practice to supply this string when raising
* events to the computer, so that the computer knows from which peripheral the event came.
*
* @return A string unique to the computer, but not globally.
* @throws RuntimeException If the peripheral has been detached.
@@ -165,6 +75,86 @@ public interface IComputerAccess
@Nonnull
String getAttachmentName();
/**
* Mount a mount onto the computer's file system in a writable mode.
*
* @param desiredLocation The location on the computer's file system where you would like the mount to be mounted.
* @param mount The mount object to mount on the computer.
* @return The location on the computer's file system where you the mount mounted, or null if there was already a file in the desired location. Store
* this value if you wish to unmount the mount later.
* @throws RuntimeException If the peripheral has been detached.
* @see ComputerCraftAPI#createSaveDirMount(World, String, long)
* @see ComputerCraftAPI#createResourceMount(Class, String, String)
* @see #mount(String, IMount)
* @see #unmount(String)
* @see IMount
*/
@Nullable
default String mountWritable(@Nonnull String desiredLocation, @Nonnull IWritableMount mount) {
return this.mountWritable(desiredLocation, mount, this.getAttachmentName());
}
/**
* Mount a mount onto the computer's file system in a writable mode.
*
* @param desiredLocation The location on the computer's file system where you would like the mount to be mounted.
* @param mount The mount object to mount on the computer.
* @param driveName A custom name to give for this mount location, as returned by {@code fs.getDrive()}.
* @return The location on the computer's file system where you the mount mounted, or null if there was already a file in the desired location. Store
* this value if you wish to unmount the mount later.
* @throws RuntimeException If the peripheral has been detached.
* @see ComputerCraftAPI#createSaveDirMount(World, String, long)
* @see ComputerCraftAPI#createResourceMount(Class, String, String)
* @see #mount(String, IMount)
* @see #unmount(String)
* @see IMount
*/
String mountWritable(@Nonnull String desiredLocation, @Nonnull IWritableMount mount, @Nonnull String driveName);
/**
* Unmounts a directory previously mounted onto the computers file system by {@link #mount(String, IMount)} or {@link #mountWritable(String,
* IWritableMount)}.
*
* When a directory is unmounted, it will disappear from the computers file system, and the user will no longer be able to access it. All directories
* mounted by a mount or mountWritable are automatically unmounted when the peripheral is attached if they have not been explicitly unmounted.
*
* Note that you cannot unmount another peripheral's mounts.
*
* @param location The desired location in the computers file system of the directory to unmount. This must be the location of a directory
* previously mounted by {@link #mount(String, IMount)} or {@link #mountWritable(String, IWritableMount)}, as indicated by their return value.
* @throws RuntimeException If the peripheral has been detached.
* @throws RuntimeException If the mount does not exist, or was mounted by another peripheral.
* @see #mount(String, IMount)
* @see #mountWritable(String, IWritableMount)
*/
void unmount(@Nullable String location);
/**
* Returns the numerical ID of this computer.
*
* This is the same number obtained by calling {@code os.getComputerID()} or running the "id" program from lua, and is guaranteed unique. This number
* will be positive.
*
* @return The identifier.
*/
int getID();
/**
* Causes an event to be raised on this computer, which the computer can respond to by calling {@code os.pullEvent()}. This can be used to notify the
* computer when things happen in the world or to this peripheral.
*
* @param event A string identifying the type of event that has occurred, this will be returned as the first value from {@code os.pullEvent()}. It
* is recommended that you you choose a name that is unique, and recognisable as originating from your peripheral. eg: If your peripheral type is
* "button", a suitable event would be "button_pressed".
* @param arguments In addition to a name, you may pass an array of extra arguments to the event, that will be supplied as extra return values to
* os.pullEvent(). Objects in the array will be converted to lua data types in the same fashion as the return values of IPeripheral.callMethod().
*
* You may supply {@code null} to indicate that no arguments are to be supplied.
* @throws RuntimeException If the peripheral has been detached.
* @see IPeripheral#callMethod
*/
void queueEvent(@Nonnull String event, @Nullable Object[] arguments);
/**
* Get a set of peripherals that this computer access can "see", along with their attachment name.
*
@@ -175,41 +165,36 @@ public interface IComputerAccess
* @see #getAvailablePeripheral(String)
*/
@Nonnull
default Map<String, IPeripheral> getAvailablePeripherals()
{
default Map<String, IPeripheral> getAvailablePeripherals() {
return Collections.emptyMap();
}
/**
* Get a reachable peripheral with the given attachment name. This is a equivalent to
* {@link #getAvailablePeripherals()}{@code .get(name)}, though may be more efficient.
* Get a reachable peripheral with the given attachment name. This is a equivalent to {@link #getAvailablePeripherals()}{@code .get(name)}, though may
* be more efficient.
*
* @param name The peripheral's attached name
* @return The reachable peripheral, or {@code null} if none can be found.
* @see #getAvailablePeripherals()
*/
@Nullable
default IPeripheral getAvailablePeripheral( @Nonnull String name )
{
default IPeripheral getAvailablePeripheral(@Nonnull String name) {
return null;
}
/**
* Get a {@link IWorkMonitor} for tasks your peripheral might execute on the main (server) thread.
*
* This should be used to ensure your peripheral integrates with ComputerCraft's monitoring and limiting of how much
* server time each computer consumes. You should not need to use this if you use
* {@link ILuaContext#issueMainThreadTask(ILuaTask)} - this is intended for mods with their own system for running
* work on the main thread.
* This should be used to ensure your peripheral integrates with ComputerCraft's monitoring and limiting of how much server time each computer consumes.
* You should not need to use this if you use {@link ILuaContext#issueMainThreadTask(ILuaTask)} - this is intended for mods with their own system for
* running work on the main thread.
*
* Please note that the returned implementation is <em>not</em> thread-safe, and should only be used from the main
* thread.
* Please note that the returned implementation is <em>not</em> thread-safe, and should only be used from the main thread.
*
* @return The work monitor for the main thread, or {@code null} if this computer does not have one.
*/
@Nullable
default IWorkMonitor getMainThreadMonitor()
{
default IWorkMonitor getMainThreadMonitor() {
return null;
}
}

114
src/main/java/dan200/computercraft/api/peripheral/IPeripheral.java
View File

@@ -6,20 +6,18 @@
package dan200.computercraft.api.peripheral;
import dan200.computercraft.api.lua.ILuaContext;
import dan200.computercraft.api.lua.LuaException;
import javax.annotation.Nonnull;
import javax.annotation.Nullable;
import dan200.computercraft.api.lua.ILuaContext;
import dan200.computercraft.api.lua.LuaException;
/**
* The interface that defines a peripheral. See {@link IPeripheralProvider} for how to associate blocks with peripherals.
*/
public interface IPeripheral
{
public interface IPeripheral {
/**
* Should return a string that uniquely identifies this type of peripheral.
* This can be queried from lua by calling {@code peripheral.getType()}
* Should return a string that uniquely identifies this type of peripheral. This can be queried from lua by calling {@code peripheral.getType()}
*
* @return A string identifying the type of peripheral.
*/
@@ -27,9 +25,8 @@ public interface IPeripheral
String getType();
/**
* Should return an array of strings that identify the methods that this
* peripheral exposes to Lua. This will be called once before each attachment,
* and should not change when called multiple times.
* Should return an array of strings that identify the methods that this peripheral exposes to Lua. This will be called once before each attachment, and
* should not change when called multiple times.
*
* @return An array of strings representing method names.
* @see #callMethod
@@ -38,105 +35,84 @@ public interface IPeripheral
String[] getMethodNames();
/**
* This is called when a lua program on an attached computer calls {@code peripheral.call()} with
* one of the methods exposed by {@link #getMethodNames()}.
* This is called when a lua program on an attached computer calls {@code peripheral.call()} with one of the methods exposed by {@link
* #getMethodNames()}.
*
* Be aware that this will be called from the ComputerCraft Lua thread, and must be thread-safe when interacting
* with Minecraft objects.
* Be aware that this will be called from the ComputerCraft Lua thread, and must be thread-safe when interacting with Minecraft objects.
*
* @param computer The interface to the computer that is making the call. Remember that multiple
* computers can be attached to a peripheral at once.
* @param context The context of the currently running lua thread. This can be used to wait for events
* or otherwise yield.
* @param method An integer identifying which of the methods from getMethodNames() the computercraft
* wishes to call. The integer indicates the index into the getMethodNames() table
* that corresponds to the string passed into peripheral.call()
* @param arguments An array of objects, representing the arguments passed into {@code peripheral.call()}.<br>
* Lua values of type "string" will be represented by Object type String.<br>
* Lua values of type "number" will be represented by Object type Double.<br>
* Lua values of type "boolean" will be represented by Object type Boolean.<br>
* Lua values of type "table" will be represented by Object type Map.<br>
* Lua values of any other type will be represented by a null object.<br>
* This array will be empty if no arguments are passed.
* @return An array of objects, representing values you wish to return to the lua program. Integers, Doubles, Floats,
* Strings, Booleans, Maps and ILuaObject and null be converted to their corresponding lua type. All other types
* will be converted to nil.
* @param computer The interface to the computer that is making the call. Remember that multiple computers can be attached to a peripheral at once.
* @param context The context of the currently running lua thread. This can be used to wait for events or otherwise yield.
* @param method An integer identifying which of the methods from getMethodNames() the computercraft wishes to call. The integer indicates the index
* into the getMethodNames() table that corresponds to the string passed into peripheral.call()
* @param arguments An array of objects, representing the arguments passed into {@code peripheral.call()}.<br> Lua values of type "string" will be
* represented by Object type String.<br> Lua values of type "number" will be represented by Object type Double.<br> Lua values of type "boolean"
* will be represented by Object type Boolean.<br> Lua values of type "table" will be represented by Object type Map.<br> Lua values of any other
* type will be represented by a null object.<br> This array will be empty if no arguments are passed.
* @return An array of objects, representing values you wish to return to the lua program. Integers, Doubles, Floats, Strings, Booleans, Maps and
* ILuaObject and null be converted to their corresponding lua type. All other types will be converted to nil.
*
* You may return null to indicate no values should be returned.
* @throws LuaException If you throw any exception from this function, a lua error will be raised with the
* same message as your exception. Use this to throw appropriate errors if the wrong
* arguments are supplied to your method.
* @throws InterruptedException If the user shuts down or reboots the computer the coroutine is suspended,
* InterruptedException will be thrown. This exception must not be caught or
* intercepted, or the computer will leak memory and end up in a broken state.
* You may return null to indicate no values should be returned.
* @throws LuaException If you throw any exception from this function, a lua error will be raised with the same message as your exception. Use this
* to throw appropriate errors if the wrong arguments are supplied to your method.
* @throws InterruptedException If the user shuts down or reboots the computer the coroutine is suspended, InterruptedException will be thrown. This
* exception must not be caught or intercepted, or the computer will leak memory and end up in a broken state.
* @see #getMethodNames
*/
@Nullable
Object[] callMethod( @Nonnull IComputerAccess computer, @Nonnull ILuaContext context, int method, @Nonnull Object[] arguments ) throws LuaException, InterruptedException;
Object[] callMethod(@Nonnull IComputerAccess computer, @Nonnull ILuaContext context, int method, @Nonnull Object[] arguments) throws LuaException,
InterruptedException;
/**
* Is called when when a computer is attaching to the peripheral.
*
* This will occur when a peripheral is placed next to an active computer, when a computer is turned on next to a
* peripheral, when a turtle travels into a square next to a peripheral, or when a wired modem adjacent to this
* peripheral is does any of the above.
* This will occur when a peripheral is placed next to an active computer, when a computer is turned on next to a peripheral, when a turtle travels into
* a square next to a peripheral, or when a wired modem adjacent to this peripheral is does any of the above.
*
* Between calls to attach and {@link #detach}, the attached computer can make method calls on the peripheral using
* {@code peripheral.call()}. This method can be used to keep track of which computers are attached to the
* peripheral, or to take action when attachment occurs.
* Between calls to attach and {@link #detach}, the attached computer can make method calls on the peripheral using {@code peripheral.call()}. This
* method can be used to keep track of which computers are attached to the peripheral, or to take action when attachment occurs.
*
* Be aware that will be called from both the server thread and ComputerCraft Lua thread, and so must be thread-safe
* and reentrant.
* Be aware that will be called from both the server thread and ComputerCraft Lua thread, and so must be thread-safe and reentrant.
*
* @param computer The interface to the computer that is being attached. Remember that multiple computers can be
* attached to a peripheral at once.
* @param computer The interface to the computer that is being attached. Remember that multiple computers can be attached to a peripheral at once.
* @see #detach
*/
default void attach( @Nonnull IComputerAccess computer )
{
default void attach(@Nonnull IComputerAccess computer) {
}
/**
* Called when a computer is detaching from the peripheral.
*
* This will occur when a computer shuts down, when the peripheral is removed while attached to computers, when a
* turtle moves away from a block attached to a peripheral, or when a wired modem adjacent to this peripheral is
* detached.
* This will occur when a computer shuts down, when the peripheral is removed while attached to computers, when a turtle moves away from a block
* attached to a peripheral, or when a wired modem adjacent to this peripheral is detached.
*
* This method can be used to keep track of which computers are attached to the peripheral, or to take action when
* detachment occurs.
* This method can be used to keep track of which computers are attached to the peripheral, or to take action when detachment occurs.
*
* Be aware that this will be called from both the server and ComputerCraft Lua thread, and must be thread-safe
* and reentrant.
* Be aware that this will be called from both the server and ComputerCraft Lua thread, and must be thread-safe and reentrant.
*
* @param computer The interface to the computer that is being detached. Remember that multiple computers can be
* attached to a peripheral at once.
* @param computer The interface to the computer that is being detached. Remember that multiple computers can be attached to a peripheral at once.
* @see #attach
*/
default void detach( @Nonnull IComputerAccess computer )
{
default void detach(@Nonnull IComputerAccess computer) {
}
/**
* Get the object that this peripheral provides methods for. This will generally be the tile entity
* or block, but may be an inventory, entity, etc...
* Get the object that this peripheral provides methods for. This will generally be the tile entity or block, but may be an inventory, entity, etc...
*
* @return The object this peripheral targets
*/
@Nonnull
default Object getTarget()
{
default Object getTarget() {
return this;
}
/**
* Determine whether this peripheral is equivalent to another one.
*
* The minimal example should at least check whether they are the same object. However, you may wish to check if
* they point to the same block or tile entity.
* The minimal example should at least check whether they are the same object. However, you may wish to check if they point to the same block or tile
* entity.
*
* @param other The peripheral to compare against. This may be {@code null}.
* @return Whether these peripherals are equivalent.
*/
boolean equals( @Nullable IPeripheral other );
boolean equals(@Nullable IPeripheral other);
}

18
src/main/java/dan200/computercraft/api/peripheral/IPeripheralProvider.java
View File

@@ -6,34 +6,32 @@
package dan200.computercraft.api.peripheral;
import javax.annotation.Nonnull;
import javax.annotation.Nullable;
import net.minecraft.block.entity.BlockEntity;
import net.minecraft.util.math.BlockPos;
import net.minecraft.util.math.Direction;
import net.minecraft.world.World;
import javax.annotation.Nonnull;
import javax.annotation.Nullable;
/**
* This interface is used to create peripheral implementations for blocks.
*
* If you have a {@link BlockEntity} which acts as a peripheral, you may alternatively implement
* {@link IPeripheralTile}.
* If you have a {@link BlockEntity} which acts as a peripheral, you may alternatively implement {@link IPeripheralTile}.
*
* @see dan200.computercraft.api.ComputerCraftAPI#registerPeripheralProvider(IPeripheralProvider)
*/
@FunctionalInterface
public interface IPeripheralProvider
{
public interface IPeripheralProvider {
/**
* Produce an peripheral implementation from a block location.
*
* @param world The world the block is in.
* @param pos The position the block is at.
* @param side The side to get the peripheral from.
* @param pos The position the block is at.
* @param side The side to get the peripheral from.
* @return A peripheral, or {@code null} if there is not a peripheral here you'd like to handle.
* @see dan200.computercraft.api.ComputerCraftAPI#registerPeripheralProvider(IPeripheralProvider)
*/
@Nullable
IPeripheral getPeripheral( @Nonnull World world, @Nonnull BlockPos pos, @Nonnull Direction side );
IPeripheral getPeripheral(@Nonnull World world, @Nonnull BlockPos pos, @Nonnull Direction side);
}

15
src/main/java/dan200/computercraft/api/peripheral/IPeripheralTile.java
View File

@@ -3,23 +3,22 @@
* Copyright Daniel Ratcliffe, 2011-2019. This API may be redistributed unmodified and in full only.
* For help using the API, and posting your mods, visit the forums at computercraft.info.
*/
package dan200.computercraft.api.peripheral;
import javax.annotation.Nonnull;
import javax.annotation.Nullable;
import net.minecraft.util.math.BlockPos;
import net.minecraft.util.math.Direction;
import net.minecraft.world.World;
import javax.annotation.Nonnull;
import javax.annotation.Nullable;
/**
* A {@link net.minecraft.block.entity.BlockEntity} which may act as a peripheral.
*
* If you need more complex capabilities (such as handling TEs not belonging to your mod), you should use
* {@link IPeripheralProvider}.
* If you need more complex capabilities (such as handling TEs not belonging to your mod), you should use {@link IPeripheralProvider}.
*/
public interface IPeripheralTile
{
public interface IPeripheralTile {
/**
* Get the peripheral on the given {@code side}.
*
@@ -28,5 +27,5 @@ public interface IPeripheralTile
* @see IPeripheralProvider#getPeripheral(World, BlockPos, Direction)
*/
@Nullable
IPeripheral getPeripheral( @Nonnull Direction side );
IPeripheral getPeripheral(@Nonnull Direction side);
}

87
src/main/java/dan200/computercraft/api/peripheral/IWorkMonitor.java
View File

@@ -6,27 +6,58 @@
package dan200.computercraft.api.peripheral;
import javax.annotation.Nonnull;
import java.util.Objects;
import java.util.concurrent.TimeUnit;
import javax.annotation.Nonnull;
/**
* Monitors "work" associated with a computer, keeping track of how much a computer has done, and ensuring every
* computer receives a fair share of any processing time.
* Monitors "work" associated with a computer, keeping track of how much a computer has done, and ensuring every computer receives a fair share of any
* processing time.
*
* This is primarily intended for work done by peripherals on the main thread (such as on a tile entity's tick), but
* could be used for other purposes (such as complex computations done on another thread).
* This is primarily intended for work done by peripherals on the main thread (such as on a tile entity's tick), but could be used for other purposes (such
* as complex computations done on another thread).
*
* Before running a task, one should call {@link #canWork()} to determine if the computer is currently allowed to
* execute work. If that returns true, you should execute the task and use {@link #trackWork(long, TimeUnit)} to inform
* the monitor how long that task took.
* Before running a task, one should call {@link #canWork()} to determine if the computer is currently allowed to execute work. If that returns true, you
* should execute the task and use {@link #trackWork(long, TimeUnit)} to inform the monitor how long that task took.
*
* Alternatively, use {@link #runWork(Runnable)} to run and keep track of work.
*
* @see IComputerAccess#getMainThreadMonitor()
*/
public interface IWorkMonitor
{
public interface IWorkMonitor {
/**
* If the owning computer is currently allowed to execute work, and has ample time to do so.
*
* This is effectively a more restrictive form of {@link #canWork()}. One should use that in order to determine if you may do an initial piece of work,
* and shouldWork to determine if any additional task may be performed.
*
* @return If we should execute work right now.
*/
boolean shouldWork();
/**
* Run a task if possible, and inform the monitor of how long it took.
*
* @param runnable The task to run.
* @return If the task was actually run (namely, {@link #canWork()} returned {@code true}).
*/
default boolean runWork(@Nonnull Runnable runnable) {
Objects.requireNonNull(runnable, "runnable should not be null");
if (!this.canWork()) {
return false;
}
long start = System.nanoTime();
try {
runnable.run();
} finally {
this.trackWork(System.nanoTime() - start, TimeUnit.NANOSECONDS);
}
return true;
}
/**
* If the owning computer is currently allowed to execute work.
*
@@ -34,45 +65,11 @@ public interface IWorkMonitor
*/
boolean canWork();
/**
* If the owning computer is currently allowed to execute work, and has ample time to do so.
*
* This is effectively a more restrictive form of {@link #canWork()}. One should use that in order to determine if
* you may do an initial piece of work, and shouldWork to determine if any additional task may be performed.
*
* @return If we should execute work right now.
*/
boolean shouldWork();
/**
* Inform the monitor how long some piece of work took to execute.
*
* @param time The time some task took to run
* @param unit The unit that {@code time} was measured in.
*/
void trackWork( long time, @Nonnull TimeUnit unit );
/**
* Run a task if possible, and inform the monitor of how long it took.
*
* @param runnable The task to run.
* @return If the task was actually run (namely, {@link #canWork()} returned {@code true}).
*/
default boolean runWork( @Nonnull Runnable runnable )
{
Objects.requireNonNull( runnable, "runnable should not be null" );
if( !canWork() ) return false;
long start = System.nanoTime();
try
{
runnable.run();
}
finally
{
trackWork( System.nanoTime() - start, TimeUnit.NANOSECONDS );
}
return true;
}
void trackWork(long time, @Nonnull TimeUnit unit);
}

38
src/main/java/dan200/computercraft/api/pocket/AbstractPocketUpgrade.java
View File

@@ -6,58 +6,52 @@
package dan200.computercraft.api.pocket;
import javax.annotation.Nonnull;
import net.minecraft.item.ItemConvertible;
import net.minecraft.item.ItemStack;
import net.minecraft.util.Identifier;
import net.minecraft.util.Util;
import javax.annotation.Nonnull;
/**
* A base class for {@link IPocketUpgrade}s.
*
* One does not have to use this, but it does provide a convenient template.
*/
public abstract class AbstractPocketUpgrade implements IPocketUpgrade
{
public abstract class AbstractPocketUpgrade implements IPocketUpgrade {
private final Identifier id;
private final String adjective;
private final ItemStack stack;
protected AbstractPocketUpgrade( Identifier id, String adjective, ItemStack stack )
{
protected AbstractPocketUpgrade(Identifier identifier, String adjective, ItemConvertible item) {
this(identifier, adjective, new ItemStack(item));
}
protected AbstractPocketUpgrade(Identifier id, String adjective, ItemStack stack) {
this.id = id;
this.adjective = adjective;
this.stack = stack;
}
protected AbstractPocketUpgrade( Identifier identifier, String adjective, ItemConvertible item )
{
this( identifier, adjective, new ItemStack( item ) );
}
protected AbstractPocketUpgrade( Identifier id, ItemConvertible item )
{
this( id, Util.createTranslationKey( "upgrade", id ) + ".adjective", new ItemStack( item ) );
protected AbstractPocketUpgrade(Identifier id, ItemConvertible item) {
this(id, Util.createTranslationKey("upgrade", id) + ".adjective", new ItemStack(item));
}
@Nonnull
@Override
public final Identifier getUpgradeID()
{
return id;
public final Identifier getUpgradeID() {
return this.id;
}
@Nonnull
@Override
public final String getUnlocalisedAdjective()
{
return adjective;
public final String getUnlocalisedAdjective() {
return this.adjective;
}
@Nonnull
@Override
public final ItemStack getCraftingItem()
{
return stack;
public final ItemStack getCraftingItem() {
return this.stack;
}
}

31
src/main/java/dan200/computercraft/api/pocket/IPocketAccess.java
View File

@@ -6,20 +6,21 @@
package dan200.computercraft.api.pocket;
import java.util.Map;
import javax.annotation.Nonnull;
import javax.annotation.Nullable;
import dan200.computercraft.api.peripheral.IPeripheral;
import net.minecraft.entity.Entity;
import net.minecraft.nbt.CompoundTag;
import net.minecraft.util.Identifier;
import javax.annotation.Nonnull;
import javax.annotation.Nullable;
import java.util.Map;
/**
* Wrapper class for pocket computers
*/
public interface IPocketAccess
{
public interface IPocketAccess {
/**
* Gets the entity holding this item.
*
@@ -33,8 +34,7 @@ public interface IPocketAccess
/**
* Get the colour of this pocket computer as a RGB number.
*
* @return The colour this pocket computer is. This will be a RGB colour between {@code 0x000000} and
* {@code 0xFFFFFF} or -1 if it has no colour.
* @return The colour this pocket computer is. This will be a RGB colour between {@code 0x000000} and {@code 0xFFFFFF} or -1 if it has no colour.
* @see #setColour(int)
*/
int getColour();
@@ -42,17 +42,16 @@ public interface IPocketAccess
/**
* Set the colour of the pocket computer to a RGB number.
*
* @param colour The colour this pocket computer should be changed to. This should be a RGB colour between
* {@code 0x000000} and {@code 0xFFFFFF} or -1 to reset to the default colour.
* @param colour The colour this pocket computer should be changed to. This should be a RGB colour between {@code 0x000000} and {@code 0xFFFFFF} or
* -1 to reset to the default colour.
* @see #getColour()
*/
void setColour( int colour );
void setColour(int colour);
/**
* Get the colour of this pocket computer's light as a RGB number.
*
* @return The colour this light is. This will be a RGB colour between {@code 0x000000} and {@code 0xFFFFFF} or
* -1 if it has no colour.
* @return The colour this light is. This will be a RGB colour between {@code 0x000000} and {@code 0xFFFFFF} or -1 if it has no colour.
* @see #setLight(int)
*/
int getLight();
@@ -60,11 +59,11 @@ public interface IPocketAccess
/**
* Set the colour of the pocket computer's light to a RGB number.
*
* @param colour The colour this modem's light will be changed to. This should be a RGB colour between
* {@code 0x000000} and {@code 0xFFFFFF} or -1 to reset to the default colour.
* @param colour The colour this modem's light will be changed to. This should be a RGB colour between {@code 0x000000} and {@code 0xFFFFFF} or -1
* to reset to the default colour.
* @see #getLight()
*/
void setLight( int colour );
void setLight(int colour);
/**
* Get the upgrade-specific NBT.

50
src/main/java/dan200/computercraft/api/pocket/IPocketUpgrade.java
View File

@@ -6,30 +6,29 @@
package dan200.computercraft.api.pocket;
import javax.annotation.Nonnull;
import javax.annotation.Nullable;
import dan200.computercraft.api.ComputerCraftAPI;
import dan200.computercraft.api.peripheral.IPeripheral;
import dan200.computercraft.api.turtle.ITurtleUpgrade;
import net.minecraft.item.ItemStack;
import net.minecraft.util.Identifier;
import net.minecraft.world.World;
import javax.annotation.Nonnull;
import javax.annotation.Nullable;
/**
* Additional peripherals for pocket computers.
*
* This is similar to {@link ITurtleUpgrade}.
*/
public interface IPocketUpgrade
{
public interface IPocketUpgrade {
/**
* Gets a unique identifier representing this type of turtle upgrade. eg: "computercraft:wireless_modem" or
* "my_mod:my_upgrade".
* Gets a unique identifier representing this type of turtle upgrade. eg: "computercraft:wireless_modem" or "my_mod:my_upgrade".
*
* You should use a unique resource domain to ensure this upgrade is uniquely identified. The upgrade will fail
* registration if an already used ID is specified.
* You should use a unique resource domain to ensure this upgrade is uniquely identified. The upgrade will fail registration if an already used ID is
* specified.
*
* @return The upgrade's id.
* @see IPocketUpgrade#getUpgradeID()
@@ -50,12 +49,11 @@ public interface IPocketUpgrade
String getUnlocalisedAdjective();
/**
* Return an item stack representing the type of item that a pocket computer must be crafted with to create a
* pocket computer which holds this upgrade. This item stack is also used to determine the upgrade given by
* {@code pocket.equip()}/{@code pocket.unequip()}.
* Return an item stack representing the type of item that a pocket computer must be crafted with to create a pocket computer which holds this upgrade.
* This item stack is also used to determine the upgrade given by {@code pocket.equip()}/{@code pocket.unequip()}.
*
* Ideally this should be constant over a session. It is recommended that you cache
* the item too, in order to prevent constructing it every time the method is called.
* Ideally this should be constant over a session. It is recommended that you cache the item too, in order to prevent constructing it every time the
* method is called.
*
* @return The item stack used for crafting. This can be {@link ItemStack#EMPTY} if crafting is disabled.
*/
@@ -65,41 +63,37 @@ public interface IPocketUpgrade
/**
* Creates a peripheral for the pocket computer.
*
* The peripheral created will be stored for the lifetime of the upgrade, will be passed an argument to
* {@link #update(IPocketAccess, IPeripheral)} and will be attached, detached and have methods called in the same
* manner as an ordinary peripheral.
* The peripheral created will be stored for the lifetime of the upgrade, will be passed an argument to {@link #update(IPocketAccess, IPeripheral)} and
* will be attached, detached and have methods called in the same manner as an ordinary peripheral.
*
* @param access The access object for the pocket item stack.
* @return The newly created peripheral.
* @see #update(IPocketAccess, IPeripheral)
*/
@Nullable
IPeripheral createPeripheral( @Nonnull IPocketAccess access );
IPeripheral createPeripheral(@Nonnull IPocketAccess access);
/**
* Called when the pocket computer item stack updates.
*
* @param access The access object for the pocket item stack.
* @param access The access object for the pocket item stack.
* @param peripheral The peripheral for this upgrade.
* @see #createPeripheral(IPocketAccess)
*/
default void update( @Nonnull IPocketAccess access, @Nullable IPeripheral peripheral )
{
default void update(@Nonnull IPocketAccess access, @Nullable IPeripheral peripheral) {
}
/**
* Called when the pocket computer is right clicked.
*
* @param world The world the computer is in.
* @param access The access object for the pocket item stack.
* @param world The world the computer is in.
* @param access The access object for the pocket item stack.
* @param peripheral The peripheral for this upgrade.
* @return {@code true} to stop the GUI from opening, otherwise false. You should always provide some code path
* which returns {@code false}, such as requiring the player to be sneaking - otherwise they will be unable to
* access the GUI.
* @return {@code true} to stop the GUI from opening, otherwise false. You should always provide some code path which returns {@code false}, such as
* requiring the player to be sneaking - otherwise they will be unable to access the GUI.
* @see #createPeripheral(IPocketAccess)
*/
default boolean onRightClick( @Nonnull World world, @Nonnull IPocketAccess access, @Nullable IPeripheral peripheral )
{
default boolean onRightClick(@Nonnull World world, @Nonnull IPocketAccess access, @Nullable IPeripheral peripheral) {
return false;
}
}

16
src/main/java/dan200/computercraft/api/redstone/IBundledRedstoneProvider.java
View File

@@ -6,29 +6,27 @@
package dan200.computercraft.api.redstone;
import javax.annotation.Nonnull;
import net.minecraft.util.math.BlockPos;
import net.minecraft.util.math.Direction;
import net.minecraft.world.World;
import javax.annotation.Nonnull;
/**
* This interface is used to provide bundled redstone output for blocks.
*
* @see dan200.computercraft.api.ComputerCraftAPI#registerBundledRedstoneProvider(IBundledRedstoneProvider)
*/
@FunctionalInterface
public interface IBundledRedstoneProvider
{
public interface IBundledRedstoneProvider {
/**
* Produce an bundled redstone output from a block location.
*
* @param world The world this block is in.
* @param pos The position this block is at.
* @param side The side to extract the bundled redstone output from.
* @return A number in the range 0-65535 to indicate this block is providing output, or -1 if you do not wish to
* handle this block.
* @param pos The position this block is at.
* @param side The side to extract the bundled redstone output from.
* @return A number in the range 0-65535 to indicate this block is providing output, or -1 if you do not wish to handle this block.
* @see dan200.computercraft.api.ComputerCraftAPI#registerBundledRedstoneProvider(IBundledRedstoneProvider)
*/
int getBundledRedstoneOutput( @Nonnull World world, @Nonnull BlockPos pos, @Nonnull Direction side );
int getBundledRedstoneOutput(@Nonnull World world, @Nonnull BlockPos pos, @Nonnull Direction side);
}

123
src/main/java/dan200/computercraft/api/turtle/ITurtleAccess.java
View File

@@ -6,10 +6,14 @@
package dan200.computercraft.api.turtle;
import javax.annotation.Nonnull;
import javax.annotation.Nullable;
import com.mojang.authlib.GameProfile;
import dan200.computercraft.api.lua.ILuaContext;
import dan200.computercraft.api.lua.LuaException;
import dan200.computercraft.api.peripheral.IPeripheral;
import net.minecraft.inventory.Inventory;
import net.minecraft.nbt.CompoundTag;
import net.minecraft.util.math.BlockPos;
@@ -17,17 +21,12 @@ import net.minecraft.util.math.Direction;
import net.minecraft.util.math.Vec3d;
import net.minecraft.world.World;
import javax.annotation.Nonnull;
import javax.annotation.Nullable;
/**
* The interface passed to turtle by turtles, providing methods that they can call.
*
* This should not be implemented by your classes. Do not interact with turtles except via this interface and
* {@link ITurtleUpgrade}.
* This should not be implemented by your classes. Do not interact with turtles except via this interface and {@link ITurtleUpgrade}.
*/
public interface ITurtleAccess
{
public interface ITurtleAccess {
/**
* Returns the world in which the turtle resides.
*
@@ -47,27 +46,25 @@ public interface ITurtleAccess
/**
* Attempt to move this turtle to a new position.
*
* This will preserve the turtle's internal state, such as it's inventory, computer and upgrades. It should
* be used before playing a movement animation using {@link #playAnimation(TurtleAnimation)}.
* This will preserve the turtle's internal state, such as it's inventory, computer and upgrades. It should be used before playing a movement animation
* using {@link #playAnimation(TurtleAnimation)}.
*
* @param world The new world to move it to
* @param pos The new position to move it to.
* @return Whether the movement was successful. It may fail if the block was not loaded or the block placement
* was cancelled.
* @param pos The new position to move it to.
* @return Whether the movement was successful. It may fail if the block was not loaded or the block placement was cancelled.
* @throws UnsupportedOperationException When attempting to teleport on the client side.
*/
boolean teleportTo( @Nonnull World world, @Nonnull BlockPos pos );
boolean teleportTo(@Nonnull World world, @Nonnull BlockPos pos);
/**
* Returns a vector containing the floating point co-ordinates at which the turtle is rendered.
* This will shift when the turtle is moving.
* Returns a vector containing the floating point co-ordinates at which the turtle is rendered. This will shift when the turtle is moving.
*
* @param f The subframe fraction.
* @return A vector containing the floating point co-ordinates at which the turtle resides.
* @see #getVisualYaw(float)
*/
@Nonnull
Vec3d getVisualPosition( float f );
Vec3d getVisualPosition(float f);
/**
* Returns the yaw the turtle is facing when it is rendered.
@@ -76,7 +73,7 @@ public interface ITurtleAccess
* @return The yaw the turtle is facing.
* @see #getVisualPosition(float)
*/
float getVisualYaw( float f );
float getVisualYaw(float f);
/**
* Returns the world direction the turtle is currently facing.
@@ -88,13 +85,13 @@ public interface ITurtleAccess
Direction getDirection();
/**
* Set the direction the turtle is facing. Note that this will not play a rotation animation, you will also need to
* call {@link #playAnimation(TurtleAnimation)} to do so.
* Set the direction the turtle is facing. Note that this will not play a rotation animation, you will also need to call {@link
* #playAnimation(TurtleAnimation)} to do so.
*
* @param dir The new direction to set. This should be on either the x or z axis (so north, south, east or west).
* @see #getDirection()
*/
void setDirection( @Nonnull Direction dir );
void setDirection(@Nonnull Direction dir);
/**
* Get the currently selected slot in the turtle's inventory.
@@ -108,32 +105,30 @@ public interface ITurtleAccess
/**
* Set the currently selected slot in the turtle's inventory.
*
* @param slot The slot to set. This must be greater or equal to 0 and less than the inventory size. Otherwise no
* action will be taken.
* @param slot The slot to set. This must be greater or equal to 0 and less than the inventory size. Otherwise no action will be taken.
* @throws UnsupportedOperationException When attempting to change the slot on the client side.
* @see #getInventory()
* @see #getSelectedSlot()
*/
void setSelectedSlot( int slot );
/**
* Set the colour of the turtle to a RGB number.
*
* @param colour The colour this turtle should be changed to. This should be a RGB colour between {@code 0x000000}
* and {@code 0xFFFFFF} or -1 to reset to the default colour.
* @see #getColour()
*/
void setColour( int colour );
void setSelectedSlot(int slot);
/**
* Get the colour of this turtle as a RGB number.
*
* @return The colour this turtle is. This will be a RGB colour between {@code 0x000000} and {@code 0xFFFFFF} or
* -1 if it has no colour.
* @return The colour this turtle is. This will be a RGB colour between {@code 0x000000} and {@code 0xFFFFFF} or -1 if it has no colour.
* @see #setColour(int)
*/
int getColour();
/**
* Set the colour of the turtle to a RGB number.
*
* @param colour The colour this turtle should be changed to. This should be a RGB colour between {@code 0x000000} and {@code 0xFFFFFF} or -1 to
* reset to the default colour.
* @see #getColour()
*/
void setColour(int colour);
/**
* Get the player who owns this turtle, namely whoever placed it.
*
@@ -169,8 +164,7 @@ public interface ITurtleAccess
int getFuelLevel();
/**
* Set the fuel level to a new value. It is generally preferred to use {@link #consumeFuel(int)}} or {@link #addFuel(int)}
* instead.
* Set the fuel level to a new value. It is generally preferred to use {@link #consumeFuel(int)}} or {@link #addFuel(int)} instead.
*
* @param fuel The new amount of fuel. This must be between 0 and the fuel limit.
* @see #getFuelLevel()
@@ -178,7 +172,7 @@ public interface ITurtleAccess
* @see #addFuel(int)
* @see #consumeFuel(int)
*/
void setFuelLevel( int fuel );
void setFuelLevel(int fuel);
/**
* Get the maximum amount of fuel a turtle can hold.
@@ -191,11 +185,11 @@ public interface ITurtleAccess
* Removes some fuel from the turtles fuel supply. Negative numbers can be passed in to INCREASE the fuel level of the turtle.
*
* @param fuel The amount of fuel to consume.
* @return Whether the turtle was able to consume the amount of fuel specified. Will return false if you supply a number
* greater than the current fuel level of the turtle. No fuel will be consumed if {@code false} is returned.
* @return Whether the turtle was able to consume the amount of fuel specified. Will return false if you supply a number greater than the current fuel
* level of the turtle. No fuel will be consumed if {@code false} is returned.
* @throws UnsupportedOperationException When attempting to consume fuel on the client side.
*/
boolean consumeFuel( int fuel );
boolean consumeFuel(int fuel);
/**
* Increase the turtle's fuel level by the given amount.
@@ -203,40 +197,36 @@ public interface ITurtleAccess
* @param fuel The amount to refuel with.
* @throws UnsupportedOperationException When attempting to refuel on the client side.
*/
void addFuel( int fuel );
void addFuel(int fuel);
/**
* Adds a custom command to the turtles command queue. Unlike peripheral methods, these custom commands will be executed
* on the main thread, so are guaranteed to be able to access Minecraft objects safely, and will be queued up
* with the turtles standard movement and tool commands. An issued command will return an unique integer, which will
* be supplied as a parameter to a "turtle_response" event issued to the turtle after the command has completed. Look at the
* lua source code for "rom/apis/turtle" for how to build a lua wrapper around this functionality.
* Adds a custom command to the turtles command queue. Unlike peripheral methods, these custom commands will be executed on the main thread, so are
* guaranteed to be able to access Minecraft objects safely, and will be queued up with the turtles standard movement and tool commands. An issued
* command will return an unique integer, which will be supplied as a parameter to a "turtle_response" event issued to the turtle after the command has
* completed. Look at the lua source code for "rom/apis/turtle" for how to build a lua wrapper around this functionality.
*
* @param context The Lua context to pull events from.
* @param command An object which will execute the custom command when its point in the queue is reached
* @return The objects the command returned when executed. you should probably return these to the player
* unchanged if called from a peripheral method.
* @return The objects the command returned when executed. you should probably return these to the player unchanged if called from a peripheral method.
* @throws UnsupportedOperationException When attempting to execute a command on the client side.
* @throws LuaException If the user presses CTRL+T to terminate the current program while {@code executeCommand()} is
* waiting for an event, a "Terminated" exception will be thrown here.
* @throws InterruptedException If the user shuts down or reboots the computer while pullEvent() is waiting for an
* event, InterruptedException will be thrown. This exception must not be caught or
* intercepted, or the computer will leak memory and end up in a broken state.
* @throws LuaException If the user presses CTRL+T to terminate the current program while {@code executeCommand()} is waiting for an event, a
* "Terminated" exception will be thrown here.
* @throws InterruptedException If the user shuts down or reboots the computer while pullEvent() is waiting for an event, InterruptedException will
* be thrown. This exception must not be caught or intercepted, or the computer will leak memory and end up in a broken state.
* @see ITurtleCommand
* @see ILuaContext#pullEvent(String)
*/
@Nonnull
Object[] executeCommand( @Nonnull ILuaContext context, @Nonnull ITurtleCommand command ) throws LuaException, InterruptedException;
Object[] executeCommand(@Nonnull ILuaContext context, @Nonnull ITurtleCommand command) throws LuaException, InterruptedException;
/**
* Start playing a specific animation. This will prevent other turtle commands from executing until
* it is finished.
* Start playing a specific animation. This will prevent other turtle commands from executing until it is finished.
*
* @param animation The animation to play.
* @throws UnsupportedOperationException When attempting to execute play an animation on the client side.
* @see TurtleAnimation
*/
void playAnimation( @Nonnull TurtleAnimation animation );
void playAnimation(@Nonnull TurtleAnimation animation);
/**
* Returns the turtle on the specified side of the turtle, if there is one.
@@ -246,16 +236,16 @@ public interface ITurtleAccess
* @see #setUpgrade(TurtleSide, ITurtleUpgrade)
*/
@Nullable
ITurtleUpgrade getUpgrade( @Nonnull TurtleSide side );
ITurtleUpgrade getUpgrade(@Nonnull TurtleSide side);
/**
* Set the upgrade for a given side, resetting peripherals and clearing upgrade specific data.
*
* @param side The side to set the upgrade on.
* @param side The side to set the upgrade on.
* @param upgrade The upgrade to set, may be {@code null} to clear.
* @see #getUpgrade(TurtleSide)
*/
void setUpgrade( @Nonnull TurtleSide side, @Nullable ITurtleUpgrade upgrade );
void setUpgrade(@Nonnull TurtleSide side, @Nullable ITurtleUpgrade upgrade);
/**
* Returns the peripheral created by the upgrade on the specified side of the turtle, if there is one.
@@ -264,27 +254,26 @@ public interface ITurtleAccess
* @return The peripheral created by the upgrade on the specified side of the turtle, {@code null} if none exists.
*/
@Nullable
IPeripheral getPeripheral( @Nonnull TurtleSide side );
IPeripheral getPeripheral(@Nonnull TurtleSide side);
/**
* Get an upgrade-specific NBT compound, which can be used to store arbitrary data.
*
* This will be persisted across turtle restarts and chunk loads, as well as being synced to the client. You must
* call {@link #updateUpgradeNBTData(TurtleSide)} after modifying it.
* This will be persisted across turtle restarts and chunk loads, as well as being synced to the client. You must call {@link
* #updateUpgradeNBTData(TurtleSide)} after modifying it.
*
* @param side The side to get the upgrade data for.
* @return The upgrade-specific data.
* @see #updateUpgradeNBTData(TurtleSide)
*/
@Nonnull
CompoundTag getUpgradeNBTData( @Nullable TurtleSide side );
CompoundTag getUpgradeNBTData(@Nullable TurtleSide side);
/**
* Mark the upgrade-specific data as dirty on a specific side. This is required for the data to be synced to the
* client and persisted.
* Mark the upgrade-specific data as dirty on a specific side. This is required for the data to be synced to the client and persisted.
*
* @param side The side to mark dirty.
* @see #updateUpgradeNBTData(TurtleSide)
*/
void updateUpgradeNBTData( @Nonnull TurtleSide side );
void updateUpgradeNBTData(@Nonnull TurtleSide side);
}

13
src/main/java/dan200/computercraft/api/turtle/ITurtleCommand.java
View File

@@ -6,23 +6,22 @@
package dan200.computercraft.api.turtle;
import dan200.computercraft.api.lua.ILuaContext;
import javax.annotation.Nonnull;
import dan200.computercraft.api.lua.ILuaContext;
/**
* An interface for objects executing custom turtle commands, used with {@link ITurtleAccess#executeCommand(ILuaContext, ITurtleCommand)}.
*
* @see ITurtleAccess#executeCommand(ILuaContext, ITurtleCommand)
*/
@FunctionalInterface
public interface ITurtleCommand
{
public interface ITurtleCommand {
/**
* Will be called by the turtle on the main thread when it is time to execute the custom command.
*
* The handler should either perform the work of the command, and return success, or return
* failure with an error message to indicate the command cannot be executed at this time.
* The handler should either perform the work of the command, and return success, or return failure with an error message to indicate the command cannot
* be executed at this time.
*
* @param turtle Access to the turtle for whom the command was issued.
* @return A result, indicating whether this action succeeded or not.
@@ -32,5 +31,5 @@ public interface ITurtleCommand
* @see TurtleCommandResult
*/
@Nonnull
TurtleCommandResult execute( @Nonnull ITurtleAccess turtle );
TurtleCommandResult execute(@Nonnull ITurtleAccess turtle);
}

95
src/main/java/dan200/computercraft/api/turtle/ITurtleUpgrade.java
View File

@@ -6,35 +6,34 @@
package dan200.computercraft.api.turtle;
import javax.annotation.Nonnull;
import javax.annotation.Nullable;
import javax.vecmath.Matrix4f;
import dan200.computercraft.api.ComputerCraftAPI;
import dan200.computercraft.api.peripheral.IPeripheral;
import dan200.computercraft.api.turtle.event.TurtleAttackEvent;
import dan200.computercraft.api.turtle.event.TurtleBlockEvent;
import net.fabricmc.api.EnvType;
import net.fabricmc.api.Environment;
import org.apache.commons.lang3.tuple.Pair;
import net.minecraft.client.render.model.BakedModel;
import net.minecraft.client.util.ModelIdentifier;
import net.minecraft.item.ItemStack;
import net.minecraft.util.Identifier;
import net.minecraft.util.math.Direction;
import org.apache.commons.lang3.tuple.Pair;
import javax.annotation.Nonnull;
import javax.annotation.Nullable;
import javax.vecmath.Matrix4f;
import net.fabricmc.api.EnvType;
import net.fabricmc.api.Environment;
/**
* The primary interface for defining an update for Turtles. A turtle update
* can either be a new tool, or a new peripheral.
* The primary interface for defining an update for Turtles. A turtle update can either be a new tool, or a new peripheral.
*
* @see ComputerCraftAPI#registerTurtleUpgrade(ITurtleUpgrade)
*/
public interface ITurtleUpgrade
{
public interface ITurtleUpgrade {
/**
* Gets a unique identifier representing this type of turtle upgrade. eg: "computercraft:wireless_modem" or "my_mod:my_upgrade".
* You should use a unique resource domain to ensure this upgrade is uniquely identified.
* The turtle will fail registration if an already used ID is specified.
* Gets a unique identifier representing this type of turtle upgrade. eg: "computercraft:wireless_modem" or "my_mod:my_upgrade". You should use a unique
* resource domain to ensure this upgrade is uniquely identified. The turtle will fail registration if an already used ID is specified.
*
* @return The unique ID for this upgrade.
* @see ComputerCraftAPI#registerTurtleUpgrade(ITurtleUpgrade)
@@ -62,12 +61,11 @@ public interface ITurtleUpgrade
TurtleUpgradeType getType();
/**
* Return an item stack representing the type of item that a turtle must be crafted
* with to create a turtle which holds this upgrade. This item stack is also used
* to determine the upgrade given by {@code turtle.equip()}
* Return an item stack representing the type of item that a turtle must be crafted with to create a turtle which holds this upgrade. This item stack is
* also used to determine the upgrade given by {@code turtle.equip()}
*
* Ideally this should be constant over a session. It is recommended that you cache
* the item too, in order to prevent constructing it every time the method is called.
* Ideally this should be constant over a session. It is recommended that you cache the item too, in order to prevent constructing it every time the
* method is called.
*
* @return The item stack to craft with, or {@link ItemStack#EMPTY} if it cannot be crafted.
*/
@@ -77,68 +75,59 @@ public interface ITurtleUpgrade
/**
* Will only be called for peripheral upgrades. Creates a peripheral for a turtle being placed using this upgrade.
*
* The peripheral created will be stored for the lifetime of the upgrade and will be passed as an argument to
* {@link #update(ITurtleAccess, TurtleSide)}. It will be attached, detached and have methods called in the same
* manner as a Computer peripheral.
* The peripheral created will be stored for the lifetime of the upgrade and will be passed as an argument to {@link #update(ITurtleAccess,
* TurtleSide)}. It will be attached, detached and have methods called in the same manner as a Computer peripheral.
*
* @param turtle Access to the turtle that the peripheral is being created for.
* @param side Which side of the turtle (left or right) that the upgrade resides on.
* @return The newly created peripheral. You may return {@code null} if this upgrade is a Tool
* and this method is not expected to be called.
* @param side Which side of the turtle (left or right) that the upgrade resides on.
* @return The newly created peripheral. You may return {@code null} if this upgrade is a Tool and this method is not expected to be called.
*/
@Nullable
default IPeripheral createPeripheral( @Nonnull ITurtleAccess turtle, @Nonnull TurtleSide side )
{
default IPeripheral createPeripheral(@Nonnull ITurtleAccess turtle, @Nonnull TurtleSide side) {
return null;
}
/**
* Will only be called for Tool turtle. Called when turtle.dig() or turtle.attack() is called
* by the turtle, and the tool is required to do some work.
* Will only be called for Tool turtle. Called when turtle.dig() or turtle.attack() is called by the turtle, and the tool is required to do some work.
*
* Conforming implementations should fire {@code BlockEvent.BreakEvent} and {@link TurtleBlockEvent.Dig}for digging,
* {@code AttackEntityEvent} and {@link TurtleAttackEvent} for attacking.
* Conforming implementations should fire {@code BlockEvent.BreakEvent} and {@link TurtleBlockEvent.Dig}for digging, {@code AttackEntityEvent} and
* {@link TurtleAttackEvent} for attacking.
*
* @param turtle Access to the turtle that the tool resides on.
* @param side Which side of the turtle (left or right) the tool resides on.
* @param verb Which action (dig or attack) the turtle is being called on to perform.
* @param direction Which world direction the action should be performed in, relative to the turtles
* position. This will either be up, down, or the direction the turtle is facing, depending on
* whether dig, digUp or digDown was called.
* @return Whether the turtle was able to perform the action, and hence whether the {@code turtle.dig()}
* or {@code turtle.attack()} lua method should return true. If true is returned, the tool will perform
* a swinging animation. You may return {@code null} if this turtle is a Peripheral and this method is not expected
* to be called.
* @param turtle Access to the turtle that the tool resides on.
* @param side Which side of the turtle (left or right) the tool resides on.
* @param verb Which action (dig or attack) the turtle is being called on to perform.
* @param direction Which world direction the action should be performed in, relative to the turtles position. This will either be up, down, or the
* direction the turtle is facing, depending on whether dig, digUp or digDown was called.
* @return Whether the turtle was able to perform the action, and hence whether the {@code turtle.dig()} or {@code turtle.attack()} lua method should
* return true. If true is returned, the tool will perform a swinging animation. You may return {@code null} if this turtle is a Peripheral and
* this method is not expected to be called.
*/
@Nonnull
default TurtleCommandResult useTool( @Nonnull ITurtleAccess turtle, @Nonnull TurtleSide side, @Nonnull TurtleVerb verb, @Nonnull Direction direction )
{
default TurtleCommandResult useTool(@Nonnull ITurtleAccess turtle, @Nonnull TurtleSide side, @Nonnull TurtleVerb verb, @Nonnull Direction direction) {
return TurtleCommandResult.failure();
}
/**
* Called to obtain the model to be used when rendering a turtle peripheral.
*
* This can be obtained from {@link net.minecraft.client.render.item.ItemModels#getModel(ItemStack)},
* {@link net.minecraft.client.render.model.BakedModelManager#getModel(ModelIdentifier)} or any other
* source.
* This can be obtained from {@link net.minecraft.client.render.item.ItemModels#getModel(ItemStack)}, {@link
* net.minecraft.client.render.model.BakedModelManager#getModel(ModelIdentifier)} or any other source.
*
* @param turtle Access to the turtle that the upgrade resides on. This will be null when getting item models!
* @param side Which side of the turtle (left or right) the upgrade resides on.
* @return The model that you wish to be used to render your upgrade, and a transformation to apply to it. Returning
* a transformation of {@code null} has the same effect as the identify matrix.
* @param side Which side of the turtle (left or right) the upgrade resides on.
* @return The model that you wish to be used to render your upgrade, and a transformation to apply to it. Returning a transformation of {@code null}
* has the same effect as the identify matrix.
*/
@Nonnull
@Environment( EnvType.CLIENT )
Pair<BakedModel, Matrix4f> getModel( @Nullable ITurtleAccess turtle, @Nonnull TurtleSide side );
@Environment (EnvType.CLIENT)
Pair<BakedModel, Matrix4f> getModel(@Nullable ITurtleAccess turtle, @Nonnull TurtleSide side);
/**
* Called once per tick for each turtle which has the upgrade equipped.
*
* @param turtle Access to the turtle that the upgrade resides on.
* @param side Which side of the turtle (left or right) the upgrade resides on.
* @param side Which side of the turtle (left or right) the upgrade resides on.
*/
default void update( @Nonnull ITurtleAccess turtle, @Nonnull TurtleSide side )
{
default void update(@Nonnull ITurtleAccess turtle, @Nonnull TurtleSide side) {
}
}

23
src/main/java/dan200/computercraft/api/turtle/TurtleAnimation.java
View File

@@ -13,8 +13,7 @@ package dan200.computercraft.api.turtle;
*
* @see ITurtleAccess#playAnimation(TurtleAnimation)
*/
public enum TurtleAnimation
{
public enum TurtleAnimation {
/**
* An animation which does nothing. This takes no time to complete.
*
@@ -24,38 +23,34 @@ public enum TurtleAnimation
None,
/**
* Make the turtle move forward. Note that the animation starts from the block <em>behind</em> it, and
* moves into this one.
* Make the turtle move forward. Note that the animation starts from the block <em>behind</em> it, and moves into this one.
*/
MoveForward,
/**
* Make the turtle move backwards. Note that the animation starts from the block <em>in front</em> it, and
* moves into this one.
* Make the turtle move backwards. Note that the animation starts from the block <em>in front</em> it, and moves into this one.
*/
MoveBack,
/**
* Make the turtle move backwards. Note that the animation starts from the block <em>above</em> it, and
* moves into this one.
* Make the turtle move backwards. Note that the animation starts from the block <em>above</em> it, and moves into this one.
*/
MoveUp,
/**
* Make the turtle move backwards. Note that the animation starts from the block <em>below</em> it, and
* moves into this one.
* Make the turtle move backwards. Note that the animation starts from the block <em>below</em> it, and moves into this one.
*/
MoveDown,
/**
* Turn the turtle to the left. Note that the animation starts with the turtle facing <em>right</em>, and
* the turtle turns to face in the current direction.
* Turn the turtle to the left. Note that the animation starts with the turtle facing <em>right</em>, and the turtle turns to face in the current
* direction.
*/
TurnLeft,
/**
* Turn the turtle to the left. Note that the animation starts with the turtle facing <em>right</em>, and
* the turtle turns to face in the current direction.
* Turn the turtle to the left. Note that the animation starts with the turtle facing <em>right</em>, and the turtle turns to face in the current
* direction.
*/
TurnRight,

70
src/main/java/dan200/computercraft/api/turtle/TurtleCommandResult.java
View File

@@ -6,21 +6,29 @@
package dan200.computercraft.api.turtle;
import net.minecraft.util.math.Direction;
import javax.annotation.Nonnull;
import javax.annotation.Nullable;
import net.minecraft.util.math.Direction;
/**
* Used to indicate the result of executing a turtle command.
*
* @see ITurtleCommand#execute(ITurtleAccess)
* @see ITurtleUpgrade#useTool(ITurtleAccess, TurtleSide, TurtleVerb, Direction)
*/
public final class TurtleCommandResult
{
private static final TurtleCommandResult EMPTY_SUCCESS = new TurtleCommandResult( true, null, null );
private static final TurtleCommandResult EMPTY_FAILURE = new TurtleCommandResult( false, null, null );
public final class TurtleCommandResult {
private static final TurtleCommandResult EMPTY_SUCCESS = new TurtleCommandResult(true, null, null);
private static final TurtleCommandResult EMPTY_FAILURE = new TurtleCommandResult(false, null, null);
private final boolean success;
private final String errorMessage;
private final Object[] results;
private TurtleCommandResult(boolean success, String errorMessage, Object[] results) {
this.success = success;
this.errorMessage = errorMessage;
this.results = results;
}
/**
* Create a successful command result with no result.
@@ -28,8 +36,7 @@ public final class TurtleCommandResult
* @return A successful command result with no values.
*/
@Nonnull
public static TurtleCommandResult success()
{
public static TurtleCommandResult success() {
return EMPTY_SUCCESS;
}
@@ -40,10 +47,11 @@ public final class TurtleCommandResult
* @return A successful command result with the given values.
*/
@Nonnull
public static TurtleCommandResult success( @Nullable Object[] results )
{
if( results == null || results.length == 0 ) return EMPTY_SUCCESS;
return new TurtleCommandResult( true, null, results );
public static TurtleCommandResult success(@Nullable Object[] results) {
if (results == null || results.length == 0) {
return EMPTY_SUCCESS;
}
return new TurtleCommandResult(true, null, results);
}
/**
@@ -52,8 +60,7 @@ public final class TurtleCommandResult
* @return A failed command result with no message.
*/
@Nonnull
public static TurtleCommandResult failure()
{
public static TurtleCommandResult failure() {
return EMPTY_FAILURE;
}
@@ -64,21 +71,11 @@ public final class TurtleCommandResult
* @return A failed command result with a message.
*/
@Nonnull
public static TurtleCommandResult failure( @Nullable String errorMessage )
{
if( errorMessage == null ) return EMPTY_FAILURE;
return new TurtleCommandResult( false, errorMessage, null );
}
private final boolean success;
private final String errorMessage;
private final Object[] results;
private TurtleCommandResult( boolean success, String errorMessage, Object[] results )
{
this.success = success;
this.errorMessage = errorMessage;
this.results = results;
public static TurtleCommandResult failure(@Nullable String errorMessage) {
if (errorMessage == null) {
return EMPTY_FAILURE;
}
return new TurtleCommandResult(false, errorMessage, null);
}
/**
@@ -86,9 +83,8 @@ public final class TurtleCommandResult
*
* @return If the command was successful.
*/
public boolean isSuccess()
{
return success;
public boolean isSuccess() {
return this.success;
}
/**
@@ -97,9 +93,8 @@ public final class TurtleCommandResult
* @return The command's error message, or {@code null} if it was a success.
*/
@Nullable
public String getErrorMessage()
{
return errorMessage;
public String getErrorMessage() {
return this.errorMessage;
}
/**
@@ -108,8 +103,7 @@ public final class TurtleCommandResult
* @return The command's result, or {@code null} if it was a failure.
*/
@Nullable
public Object[] getResults()
{
return results;
public Object[] getResults() {
return this.results;
}
}

3
src/main/java/dan200/computercraft/api/turtle/TurtleSide.java
View File

@@ -9,8 +9,7 @@ package dan200.computercraft.api.turtle;
/**
* An enum representing the two sides of the turtle that a turtle turtle might reside.
*/
public enum TurtleSide
{
public enum TurtleSide {
/**
* The turtle's left side (where the pickaxe usually is on a Wireless Mining Turtle)
*/

22
src/main/java/dan200/computercraft/api/turtle/TurtleUpgradeType.java
View File

@@ -11,34 +11,30 @@ package dan200.computercraft.api.turtle;
*
* @see ITurtleUpgrade#getType()
*/
public enum TurtleUpgradeType
{
public enum TurtleUpgradeType {
/**
* A tool is rendered as an item on the side of the turtle, and responds to the {@code turtle.dig()}
* and {@code turtle.attack()} methods (Such as pickaxe or sword on Mining and Melee turtles).
* A tool is rendered as an item on the side of the turtle, and responds to the {@code turtle.dig()} and {@code turtle.attack()} methods (Such as
* pickaxe or sword on Mining and Melee turtles).
*/
Tool,
/**
* A peripheral adds a special peripheral which is attached to the side of the turtle,
* and can be interacted with the {@code peripheral} API (Such as the modem on Wireless Turtles).
* A peripheral adds a special peripheral which is attached to the side of the turtle, and can be interacted with the {@code peripheral} API (Such as
* the modem on Wireless Turtles).
*/
Peripheral,
/**
* An upgrade which provides both a tool and a peripheral. This can be used when you wish
* your upgrade to also provide methods. For example, a pickaxe could provide methods
* determining whether it can break the given block or not.
* An upgrade which provides both a tool and a peripheral. This can be used when you wish your upgrade to also provide methods. For example, a pickaxe
* could provide methods determining whether it can break the given block or not.
*/
Both;
public boolean isTool()
{
public boolean isTool() {
return this == Tool || this == Both;
}
public boolean isPeripheral()
{
public boolean isPeripheral() {
return this == Peripheral || this == Both;
}
}

6
src/main/java/dan200/computercraft/api/turtle/TurtleVerb.java
View File

@@ -9,14 +9,12 @@ package dan200.computercraft.api.turtle;
import net.minecraft.util.math.Direction;
/**
* An enum representing the different actions that an {@link ITurtleUpgrade} of type Tool may be called on to perform by
* a turtle.
* An enum representing the different actions that an {@link ITurtleUpgrade} of type Tool may be called on to perform by a turtle.
*
* @see ITurtleUpgrade#getType()
* @see ITurtleUpgrade#useTool(ITurtleAccess, TurtleSide, TurtleVerb, Direction)
*/
public enum TurtleVerb
{
public enum TurtleVerb {
/**
* The turtle called {@code turtle.dig()}, {@code turtle.digUp()} or {@code turtle.digDown()}
*/

177
src/main/java/dan200/computercraft/api/turtle/event/FakePlayer.java
View File

@@ -6,10 +6,17 @@
package dan200.computercraft.api.turtle.event;
import java.util.Collection;
import java.util.OptionalInt;
import javax.annotation.Nullable;
import javax.crypto.SecretKey;
import com.mojang.authlib.GameProfile;
import io.netty.channel.ChannelHandlerContext;
import io.netty.util.concurrent.Future;
import io.netty.util.concurrent.GenericFutureListener;
import net.minecraft.block.entity.CommandBlockBlockEntity;
import net.minecraft.block.entity.SignBlockEntity;
import net.minecraft.command.arguments.EntityAnchorArgumentType;
@@ -44,23 +51,15 @@ import net.minecraft.village.TraderOfferList;
import net.minecraft.world.GameMode;
import net.minecraft.world.dimension.DimensionType;
import javax.annotation.Nullable;
import javax.crypto.SecretKey;
import java.util.Collection;
import java.util.OptionalInt;
/**
* A wrapper for {@link ServerPlayerEntity} which denotes a "fake" player.
*
* Please note that this does not implement any of the traditional fake player behaviour. It simply exists to prevent
* me passing in normal players.
* Please note that this does not implement any of the traditional fake player behaviour. It simply exists to prevent me passing in normal players.
*/
public class FakePlayer extends ServerPlayerEntity
{
public FakePlayer( ServerWorld world, GameProfile gameProfile )
{
super( world.getServer(), world, gameProfile, new ServerPlayerInteractionManager( world ) );
networkHandler = new FakeNetHandler( this );
public class FakePlayer extends ServerPlayerEntity {
public FakePlayer(ServerWorld world, GameProfile gameProfile) {
super(world.getServer(), world, gameProfile, new ServerPlayerInteractionManager(world));
this.networkHandler = new FakeNetHandler(this);
}
// region Direct networkHandler access
@@ -77,21 +76,10 @@ public class FakePlayer extends ServerPlayerEntity
public void playerTick() { }
@Override
public void onDeath( DamageSource damage ) { }
@Nullable
@Override
public Entity changeDimension( DimensionType dimension )
{
return this;
}
public void onDeath(DamageSource damage) { }
@Override
public void wakeUp( boolean resetTimer, boolean notify, boolean setSpawn ) { }
@Override
public boolean startRiding( Entity entity, boolean flag )
{
public boolean startRiding(Entity entity, boolean flag) {
return false;
}
@@ -99,34 +87,33 @@ public class FakePlayer extends ServerPlayerEntity
public void stopRiding() { }
@Override
public void openEditSignScreen( SignBlockEntity tile ) { }
public void openEditSignScreen(SignBlockEntity tile) { }
@Override
public OptionalInt openHandledScreen( @Nullable NamedScreenHandlerFactory container )
{
public OptionalInt openHandledScreen(@Nullable NamedScreenHandlerFactory container) {
return OptionalInt.empty();
}
@Override
public void sendTradeOffers( int id, TraderOfferList list, int level, int experience, boolean levelled, boolean refreshable ) { }
public void sendTradeOffers(int id, TraderOfferList list, int level, int experience, boolean levelled, boolean refreshable) { }
@Override
public void openHorseInventory( HorseBaseEntity horse, Inventory inventory ) { }
public void openHorseInventory(HorseBaseEntity horse, Inventory inventory) { }
@Override
public void openEditBookScreen( ItemStack stack, Hand hand ) { }
public void openEditBookScreen(ItemStack stack, Hand hand) { }
@Override
public void openCommandBlockScreen( CommandBlockBlockEntity block ) { }
public void openCommandBlockScreen(CommandBlockBlockEntity block) { }
@Override
public void onSlotUpdate( ScreenHandler container, int slot, ItemStack stack ) { }
public void onSlotUpdate(ScreenHandler container, int slot, ItemStack stack) { }
@Override
public void onHandlerRegistered( ScreenHandler container, DefaultedList<ItemStack> defaultedList ) { }
public void onHandlerRegistered(ScreenHandler container, DefaultedList<ItemStack> defaultedList) { }
@Override
public void onPropertyUpdate( ScreenHandler container, int key, int value ) { }
public void onPropertyUpdate(ScreenHandler container, int key, int value) { }
@Override
public void closeHandledScreen() { }
@@ -135,152 +122,144 @@ public class FakePlayer extends ServerPlayerEntity
public void updateCursorStack() { }
@Override
public void sendMessage( Text textComponent, boolean status ) { }
public int unlockRecipes(Collection<Recipe<?>> recipes) {
return 0;
}
// Indirect
@Override
public int lockRecipes(Collection<Recipe<?>> recipes) {
return 0;
}
@Override
public void sendMessage(Text textComponent, boolean status) { }
@Override
protected void consumeItem() { }
@Override
public void lookAt( EntityAnchorArgumentType.EntityAnchor anchor, Vec3d vec3d ) { }
public void lookAt(EntityAnchorArgumentType.EntityAnchor anchor, Vec3d vec3d) { }
@Override
public void method_14222( EntityAnchorArgumentType.EntityAnchor self, Entity entity, EntityAnchorArgumentType.EntityAnchor target ) { }
public void method_14222(EntityAnchorArgumentType.EntityAnchor self, Entity entity, EntityAnchorArgumentType.EntityAnchor target) { }
@Override
protected void onStatusEffectApplied( StatusEffectInstance statusEffectInstance ) { }
protected void onStatusEffectApplied(StatusEffectInstance statusEffectInstance) { }
@Override
protected void onStatusEffectUpgraded( StatusEffectInstance statusEffectInstance, boolean particles ) { }
protected void onStatusEffectUpgraded(StatusEffectInstance statusEffectInstance, boolean particles) { }
@Override
protected void onStatusEffectRemoved( StatusEffectInstance statusEffectInstance ) { }
protected void onStatusEffectRemoved(StatusEffectInstance statusEffectInstance) { }
@Override
public void requestTeleport( double x, double y, double z ) { }
public void requestTeleport(double x, double y, double z) { }
@Override
public void setGameMode( GameMode gameMode ) { }
public void setGameMode(GameMode gameMode) { }
@Override
public void sendMessage( Text textComponent, MessageType chatMessageType ) { }
@Override
public String getIp()
{
public String getIp() {
return "[Fake Player]";
}
@Override
public void sendResourcePackUrl( String url, String hash ) { }
public void sendResourcePackUrl(String url, String hash) { }
@Override
public void onStoppedTracking( Entity entity ) { }
public void onStoppedTracking(Entity entity) { }
@Override
public void setCameraEntity( Entity entity ) { }
public void setCameraEntity(Entity entity) { }
@Override
public void teleport( ServerWorld serverWorld, double x, double y, double z, float pitch, float yaw ) { }
public void teleport(ServerWorld serverWorld, double x, double y, double z, float pitch, float yaw) { }
@Override
public void sendInitialChunkPackets( ChunkPos chunkPos, Packet<?> packet, Packet<?> packet2 ) { }
public void sendInitialChunkPackets(ChunkPos chunkPos, Packet<?> packet, Packet<?> packet2) { }
@Override
public void sendUnloadChunkPacket( ChunkPos chunkPos ) { }
public void sendUnloadChunkPacket(ChunkPos chunkPos) { }
@Override
public void playSound( SoundEvent soundEvent, SoundCategory soundCategory, float volume, float pitch ) { }
public void playSound(SoundEvent soundEvent, SoundCategory soundCategory, float volume, float pitch) { }
@Nullable
@Override
public Entity changeDimension(DimensionType dimension) {
return this;
}
// endregion
// Indirect
@Override
public int lockRecipes( Collection<Recipe<?>> recipes )
{
return 0;
}
public void wakeUp(boolean resetTimer, boolean notify, boolean setSpawn) { }
@Override
public int unlockRecipes( Collection<Recipe<?>> recipes )
{
return 0;
}
public void sendMessage(Text textComponent, MessageType chatMessageType) { }
//
private static class FakeNetHandler extends ServerPlayNetworkHandler
{
FakeNetHandler( ServerPlayerEntity player )
{
super( player.server, new FakeConnection(), player );
private static class FakeNetHandler extends ServerPlayNetworkHandler {
FakeNetHandler(ServerPlayerEntity player) {
super(player.server, new FakeConnection(), player);
}
@Override
public void disconnect( Text message ) { }
public void disconnect(Text message) { }
@Override
public void onRequestCommandCompletions( RequestCommandCompletionsC2SPacket packet ) { }
public void onVehicleMove(VehicleMoveC2SPacket move) { }
@Override
public void sendPacket( Packet<?> packet, @Nullable GenericFutureListener<? extends Future<? super Void>> listener ) { }
public void onRequestCommandCompletions(RequestCommandCompletionsC2SPacket packet) { }
@Override
public void onVehicleMove( VehicleMoveC2SPacket move ) { }
public void sendPacket(Packet<?> packet, @Nullable GenericFutureListener<? extends Future<? super Void>> listener) { }
}
private static class FakeConnection extends ClientConnection
{
FakeConnection()
{
super( NetworkSide.CLIENTBOUND );
private static class FakeConnection extends ClientConnection {
FakeConnection() {
super(NetworkSide.CLIENTBOUND);
}
@Override
public void channelActive( ChannelHandlerContext active )
{
public void channelActive(ChannelHandlerContext active) {
}
@Override
public void setState( NetworkState state )
{
public void setState(NetworkState state) {
}
@Override
public void disconnect( Text message )
{
public void exceptionCaught(ChannelHandlerContext context, Throwable err) {
}
@Override
public void exceptionCaught( ChannelHandlerContext context, Throwable err )
{
protected void channelRead0(ChannelHandlerContext context, Packet<?> packet) {
}
@Override
protected void channelRead0( ChannelHandlerContext context, Packet<?> packet )
{
public void send(Packet<?> packet, @Nullable GenericFutureListener<? extends Future<? super Void>> listener) {
}
@Override
public void tick()
{
public void tick() {
}
@Override
public void setupEncryption( SecretKey key )
{
public void disconnect(Text message) {
}
@Override
public void disableAutoRead()
{
public void setupEncryption(SecretKey key) {
}
@Override
public void setCompressionThreshold( int size )
{
public void disableAutoRead() {
}
@Override
public void send( Packet<?> packet, @Nullable GenericFutureListener<? extends Future<? super Void>> listener )
{
public void setCompressionThreshold(int size) {
}
}
}

3
src/main/java/dan200/computercraft/api/turtle/event/TurtleAction.java
View File

@@ -11,8 +11,7 @@ package dan200.computercraft.api.turtle.event;
*
* @see TurtleActionEvent
*/
public enum TurtleAction
{
public enum TurtleAction {
/**
* A turtle moves to a new position.
*

42
src/main/java/dan200/computercraft/api/turtle/event/TurtleActionEvent.java
View File

@@ -6,33 +6,31 @@
package dan200.computercraft.api.turtle.event;
import dan200.computercraft.api.turtle.ITurtleAccess;
import dan200.computercraft.api.turtle.TurtleCommandResult;
import java.util.Objects;
import javax.annotation.Nonnull;
import javax.annotation.Nullable;
import java.util.Objects;
import dan200.computercraft.api.turtle.ITurtleAccess;
import dan200.computercraft.api.turtle.TurtleCommandResult;
/**
* An event fired when a turtle is performing a known action.
*/
public class TurtleActionEvent extends TurtleEvent
{
public class TurtleActionEvent extends TurtleEvent {
private final TurtleAction action;
private String failureMessage;
private boolean cancelled = false;
public TurtleActionEvent( @Nonnull ITurtleAccess turtle, @Nonnull TurtleAction action )
{
super( turtle );
public TurtleActionEvent(@Nonnull ITurtleAccess turtle, @Nonnull TurtleAction action) {
super(turtle);
Objects.requireNonNull( action, "action cannot be null" );
Objects.requireNonNull(action, "action cannot be null");
this.action = action;
}
public TurtleAction getAction()
{
return action;
public TurtleAction getAction() {
return this.action;
}
/**
@@ -45,9 +43,8 @@ public class TurtleActionEvent extends TurtleEvent
* @deprecated Use {@link #setCanceled(boolean, String)} instead.
*/
@Deprecated
public void setCanceled( boolean cancel )
{
setCanceled( cancel, null );
public void setCanceled(boolean cancel) {
this.setCanceled(cancel, null);
}
/**
@@ -55,12 +52,11 @@ public class TurtleActionEvent extends TurtleEvent
*
* If {@code cancel} is {@code true}, this action will not be carried out.
*
* @param cancel The new canceled value.
* @param cancel The new canceled value.
* @param failureMessage The message to return to the user explaining the failure.
* @see TurtleCommandResult#failure(String)
*/
public void setCanceled( boolean cancel, @Nullable String failureMessage )
{
public void setCanceled(boolean cancel, @Nullable String failureMessage) {
this.cancelled = true;
this.failureMessage = cancel ? failureMessage : null;
}
@@ -73,9 +69,8 @@ public class TurtleActionEvent extends TurtleEvent
* @see #setCanceled(boolean, String)
*/
@Nullable
public String getFailureMessage()
{
return failureMessage;
public String getFailureMessage() {
return this.failureMessage;
}
/**
@@ -84,8 +79,7 @@ public class TurtleActionEvent extends TurtleEvent
* @return If this event is cancelled
* @see #setCanceled(boolean, String)
*/
public boolean isCancelled()
{
return cancelled;
public boolean isCancelled() {
return this.cancelled;
}
}

45
src/main/java/dan200/computercraft/api/turtle/event/TurtleAttackEvent.java
View File

@@ -6,39 +6,39 @@
package dan200.computercraft.api.turtle.event;
import java.util.Objects;
import javax.annotation.Nonnull;
import dan200.computercraft.api.turtle.ITurtleAccess;
import dan200.computercraft.api.turtle.ITurtleUpgrade;
import dan200.computercraft.api.turtle.TurtleSide;
import dan200.computercraft.api.turtle.TurtleVerb;
import net.minecraft.entity.Entity;
import net.minecraft.util.math.Direction;
import javax.annotation.Nonnull;
import java.util.Objects;
/**
* Fired when a turtle attempts to attack an entity.
*
* This must be fired by {@link ITurtleUpgrade#useTool(ITurtleAccess, TurtleSide, TurtleVerb, Direction)},
* as the base {@code turtle.attack()} command does not fire it.
* This must be fired by {@link ITurtleUpgrade#useTool(ITurtleAccess, TurtleSide, TurtleVerb, Direction)}, as the base {@code turtle.attack()} command does
* not fire it.
*
* Note that such commands should also fire {@link net.fabricmc.fabric.api.event.player.AttackEntityCallback}, so you do
* not need to listen to both.
* Note that such commands should also fire {@link net.fabricmc.fabric.api.event.player.AttackEntityCallback}, so you do not need to listen to both.
*
* @see TurtleAction#ATTACK
*/
public class TurtleAttackEvent extends TurtlePlayerEvent
{
public class TurtleAttackEvent extends TurtlePlayerEvent {
private final Entity target;
private final ITurtleUpgrade upgrade;
private final TurtleSide side;
public TurtleAttackEvent( @Nonnull ITurtleAccess turtle, @Nonnull FakePlayer player, @Nonnull Entity target, @Nonnull ITurtleUpgrade upgrade, @Nonnull TurtleSide side )
{
super( turtle, TurtleAction.ATTACK, player );
Objects.requireNonNull( target, "target cannot be null" );
Objects.requireNonNull( upgrade, "upgrade cannot be null" );
Objects.requireNonNull( side, "side cannot be null" );
public TurtleAttackEvent(@Nonnull ITurtleAccess turtle, @Nonnull FakePlayer player, @Nonnull Entity target, @Nonnull ITurtleUpgrade upgrade,
@Nonnull TurtleSide side) {
super(turtle, TurtleAction.ATTACK, player);
Objects.requireNonNull(target, "target cannot be null");
Objects.requireNonNull(upgrade, "upgrade cannot be null");
Objects.requireNonNull(side, "side cannot be null");
this.target = target;
this.upgrade = upgrade;
this.side = side;
@@ -50,9 +50,8 @@ public class TurtleAttackEvent extends TurtlePlayerEvent
* @return The entity being attacked.
*/
@Nonnull
public Entity getTarget()
{
return target;
public Entity getTarget() {
return this.target;
}
/**
@@ -61,9 +60,8 @@ public class TurtleAttackEvent extends TurtlePlayerEvent
* @return The upgrade responsible for attacking.
*/
@Nonnull
public ITurtleUpgrade getUpgrade()
{
return upgrade;
public ITurtleUpgrade getUpgrade() {
return this.upgrade;
}
/**
@@ -72,8 +70,7 @@ public class TurtleAttackEvent extends TurtlePlayerEvent
* @return The upgrade's side.
*/
@Nonnull
public TurtleSide getSide()
{
return side;
public TurtleSide getSide() {
return this.side;
}
}

138
src/main/java/dan200/computercraft/api/turtle/event/TurtleBlockEvent.java
View File

@@ -6,45 +6,43 @@
package dan200.computercraft.api.turtle.event;
import java.util.Map;
import java.util.Objects;
import javax.annotation.Nonnull;
import dan200.computercraft.api.lua.ILuaContext;
import dan200.computercraft.api.peripheral.IComputerAccess;
import dan200.computercraft.api.turtle.ITurtleAccess;
import dan200.computercraft.api.turtle.ITurtleUpgrade;
import dan200.computercraft.api.turtle.TurtleSide;
import dan200.computercraft.api.turtle.TurtleVerb;
import net.minecraft.block.BlockState;
import net.minecraft.item.ItemStack;
import net.minecraft.util.math.BlockPos;
import net.minecraft.util.math.Direction;
import net.minecraft.world.World;
import javax.annotation.Nonnull;
import java.util.Map;
import java.util.Objects;
/**
* A general event for when a turtle interacts with a block or region.
*
* You should generally listen to one of the sub-events instead, cancelling them where
* appropriate.
* You should generally listen to one of the sub-events instead, cancelling them where appropriate.
*
* Note that you are not guaranteed to receive this event, if it has been cancelled by other
* mechanisms, such as block protection systems.
* Note that you are not guaranteed to receive this event, if it has been cancelled by other mechanisms, such as block protection systems.
*
* Be aware that some events (such as {@link TurtleInventoryEvent}) do not necessarily interact
* with a block, simply objects within that block space.
* Be aware that some events (such as {@link TurtleInventoryEvent}) do not necessarily interact with a block, simply objects within that block space.
*/
public abstract class TurtleBlockEvent extends TurtlePlayerEvent
{
public abstract class TurtleBlockEvent extends TurtlePlayerEvent {
private final World world;
private final BlockPos pos;
protected TurtleBlockEvent( @Nonnull ITurtleAccess turtle, @Nonnull TurtleAction action, @Nonnull FakePlayer player, @Nonnull World world, @Nonnull BlockPos pos )
{
super( turtle, action, player );
protected TurtleBlockEvent(@Nonnull ITurtleAccess turtle, @Nonnull TurtleAction action, @Nonnull FakePlayer player, @Nonnull World world,
@Nonnull BlockPos pos) {
super(turtle, action, player);
Objects.requireNonNull( world, "world cannot be null" );
Objects.requireNonNull( pos, "pos cannot be null" );
Objects.requireNonNull(world, "world cannot be null");
Objects.requireNonNull(pos, "pos cannot be null");
this.world = world;
this.pos = pos;
}
@@ -54,46 +52,41 @@ public abstract class TurtleBlockEvent extends TurtlePlayerEvent
*
* @return The world the turtle is interacting in.
*/
public World getWorld()
{
return world;
public World getWorld() {
return this.world;
}
/**
* Get the position the turtle is interacting with. Note that this is different
* to {@link ITurtleAccess#getPosition()}.
* Get the position the turtle is interacting with. Note that this is different to {@link ITurtleAccess#getPosition()}.
*
* @return The position the turtle is interacting with.
*/
public BlockPos getPos()
{
return pos;
public BlockPos getPos() {
return this.pos;
}
/**
* Fired when a turtle attempts to dig a block.
*
* This must be fired by {@link ITurtleUpgrade#useTool(ITurtleAccess, TurtleSide, TurtleVerb, Direction)},
* as the base {@code turtle.dig()} command does not fire it.
* This must be fired by {@link ITurtleUpgrade#useTool(ITurtleAccess, TurtleSide, TurtleVerb, Direction)}, as the base {@code turtle.dig()} command does
* not fire it.
*
* Note that such commands should also fire {@link net.fabricmc.fabric.api.event.player.AttackBlockCallback}, so you
* do not need to listen to both.
* Note that such commands should also fire {@link net.fabricmc.fabric.api.event.player.AttackBlockCallback}, so you do not need to listen to both.
*
* @see TurtleAction#DIG
*/
public static class Dig extends TurtleBlockEvent
{
public static class Dig extends TurtleBlockEvent {
private final BlockState block;
private final ITurtleUpgrade upgrade;
private final TurtleSide side;
public Dig( @Nonnull ITurtleAccess turtle, @Nonnull FakePlayer player, @Nonnull World world, @Nonnull BlockPos pos, @Nonnull BlockState block, @Nonnull ITurtleUpgrade upgrade, @Nonnull TurtleSide side )
{
super( turtle, TurtleAction.DIG, player, world, pos );
public Dig(@Nonnull ITurtleAccess turtle, @Nonnull FakePlayer player, @Nonnull World world, @Nonnull BlockPos pos, @Nonnull BlockState block,
@Nonnull ITurtleUpgrade upgrade, @Nonnull TurtleSide side) {
super(turtle, TurtleAction.DIG, player, world, pos);
Objects.requireNonNull( block, "block cannot be null" );
Objects.requireNonNull( upgrade, "upgrade cannot be null" );
Objects.requireNonNull( side, "side cannot be null" );
Objects.requireNonNull(block, "block cannot be null");
Objects.requireNonNull(upgrade, "upgrade cannot be null");
Objects.requireNonNull(side, "side cannot be null");
this.block = block;
this.upgrade = upgrade;
this.side = side;
@@ -105,9 +98,8 @@ public abstract class TurtleBlockEvent extends TurtlePlayerEvent
* @return The block which is going to be broken.
*/
@Nonnull
public BlockState getBlock()
{
return block;
public BlockState getBlock() {
return this.block;
}
/**
@@ -116,9 +108,8 @@ public abstract class TurtleBlockEvent extends TurtlePlayerEvent
* @return The upgrade doing the digging.
*/
@Nonnull
public ITurtleUpgrade getUpgrade()
{
return upgrade;
public ITurtleUpgrade getUpgrade() {
return this.upgrade;
}
/**
@@ -127,9 +118,8 @@ public abstract class TurtleBlockEvent extends TurtlePlayerEvent
* @return The upgrade's side.
*/
@Nonnull
public TurtleSide getSide()
{
return side;
public TurtleSide getSide() {
return this.side;
}
}
@@ -138,11 +128,9 @@ public abstract class TurtleBlockEvent extends TurtlePlayerEvent
*
* @see TurtleAction#MOVE
*/
public static class Move extends TurtleBlockEvent
{
public Move( @Nonnull ITurtleAccess turtle, @Nonnull FakePlayer player, @Nonnull World world, @Nonnull BlockPos pos )
{
super( turtle, TurtleAction.MOVE, player, world, pos );
public static class Move extends TurtleBlockEvent {
public Move(@Nonnull ITurtleAccess turtle, @Nonnull FakePlayer player, @Nonnull World world, @Nonnull BlockPos pos) {
super(turtle, TurtleAction.MOVE, player, world, pos);
}
}
@@ -151,15 +139,13 @@ public abstract class TurtleBlockEvent extends TurtlePlayerEvent
*
* @see TurtleAction#PLACE
*/
public static class Place extends TurtleBlockEvent
{
public static class Place extends TurtleBlockEvent {
private final ItemStack stack;
public Place( @Nonnull ITurtleAccess turtle, @Nonnull FakePlayer player, @Nonnull World world, @Nonnull BlockPos pos, @Nonnull ItemStack stack )
{
super( turtle, TurtleAction.PLACE, player, world, pos );
public Place(@Nonnull ITurtleAccess turtle, @Nonnull FakePlayer player, @Nonnull World world, @Nonnull BlockPos pos, @Nonnull ItemStack stack) {
super(turtle, TurtleAction.PLACE, player, world, pos);
Objects.requireNonNull( stack, "stack cannot be null" );
Objects.requireNonNull(stack, "stack cannot be null");
this.stack = stack;
}
@@ -169,9 +155,8 @@ public abstract class TurtleBlockEvent extends TurtlePlayerEvent
* @return The item stack to be placed.
*/
@Nonnull
public ItemStack getStack()
{
return stack;
public ItemStack getStack() {
return this.stack;
}
}
@@ -182,17 +167,16 @@ public abstract class TurtleBlockEvent extends TurtlePlayerEvent
*
* @see TurtleAction#INSPECT
*/
public static class Inspect extends TurtleBlockEvent
{
public static class Inspect extends TurtleBlockEvent {
private final BlockState state;
private final Map<String, Object> data;
public Inspect( @Nonnull ITurtleAccess turtle, @Nonnull FakePlayer player, @Nonnull World world, @Nonnull BlockPos pos, @Nonnull BlockState state, @Nonnull Map<String, Object> data )
{
super( turtle, TurtleAction.INSPECT, player, world, pos );
public Inspect(@Nonnull ITurtleAccess turtle, @Nonnull FakePlayer player, @Nonnull World world, @Nonnull BlockPos pos, @Nonnull BlockState state,
@Nonnull Map<String, Object> data) {
super(turtle, TurtleAction.INSPECT, player, world, pos);
Objects.requireNonNull( state, "state cannot be null" );
Objects.requireNonNull( data, "data cannot be null" );
Objects.requireNonNull(state, "state cannot be null");
Objects.requireNonNull(data, "data cannot be null");
this.data = data;
this.state = state;
}
@@ -203,9 +187,8 @@ public abstract class TurtleBlockEvent extends TurtlePlayerEvent
* @return The inspected block state.
*/
@Nonnull
public BlockState getState()
{
return state;
public BlockState getState() {
return this.state;
}
/**
@@ -214,21 +197,20 @@ public abstract class TurtleBlockEvent extends TurtlePlayerEvent
* @return This block's inspection data.
*/
@Nonnull
public Map<String, Object> getData()
{
return data;
public Map<String, Object> getData() {
return this.data;
}
/**
* Add new information to the inspection result. Note this will override fields with the same name.
*
* @param newData The data to add. Note all values should be convertible to Lua (see
* {@link dan200.computercraft.api.peripheral.IPeripheral#callMethod(IComputerAccess, ILuaContext, int, Object[])}).
* {@link dan200.computercraft.api.peripheral.IPeripheral#callMethod(IComputerAccess,
* ILuaContext, int, Object[])}).
*/
public void addData( @Nonnull Map<String, ?> newData )
{
Objects.requireNonNull( newData, "newData cannot be null" );
data.putAll( newData );
public void addData(@Nonnull Map<String, ?> newData) {
Objects.requireNonNull(newData, "newData cannot be null");
this.data.putAll(newData);
}
}
}

35
src/main/java/dan200/computercraft/api/turtle/event/TurtleEvent.java
View File

@@ -6,46 +6,43 @@
package dan200.computercraft.api.turtle.event;
import java.util.Objects;
import javax.annotation.Nonnull;
import com.google.common.eventbus.EventBus;
import dan200.computercraft.api.turtle.ITurtleAccess;
import javax.annotation.Nonnull;
import java.util.Objects;
/**
* A base class for all events concerning a turtle. This will only ever constructed and fired on the server side,
* so sever specific methods on {@link ITurtleAccess} are safe to use.
* A base class for all events concerning a turtle. This will only ever constructed and fired on the server side, so sever specific methods on {@link
* ITurtleAccess} are safe to use.
*
* You should generally not need to subscribe to this event, preferring one of the more specific classes.
*
* @see TurtleActionEvent
*/
public abstract class TurtleEvent
{
public abstract class TurtleEvent {
public static final EventBus EVENT_BUS = new EventBus();
private final ITurtleAccess turtle;
protected TurtleEvent( @Nonnull ITurtleAccess turtle )
{
Objects.requireNonNull( turtle, "turtle cannot be null" );
protected TurtleEvent(@Nonnull ITurtleAccess turtle) {
Objects.requireNonNull(turtle, "turtle cannot be null");
this.turtle = turtle;
}
public static boolean post(TurtleActionEvent event) {
EVENT_BUS.post(event);
return event.isCancelled();
}
/**
* Get the turtle which is performing this action.
*
* @return The access for this turtle.
*/
@Nonnull
public ITurtleAccess getTurtle()
{
return turtle;
}
public static boolean post( TurtleActionEvent event )
{
EVENT_BUS.post( event );
return event.isCancelled();
public ITurtleAccess getTurtle() {
return this.turtle;
}
}

46
src/main/java/dan200/computercraft/api/turtle/event/TurtleInspectItemEvent.java
View File

@@ -6,34 +6,34 @@
package dan200.computercraft.api.turtle.event;
import java.util.Map;
import java.util.Objects;
import javax.annotation.Nonnull;
import dan200.computercraft.api.lua.ILuaContext;
import dan200.computercraft.api.peripheral.IComputerAccess;
import dan200.computercraft.api.turtle.ITurtleAccess;
import net.minecraft.item.ItemStack;
import javax.annotation.Nonnull;
import java.util.Map;
import java.util.Objects;
import net.minecraft.item.ItemStack;
/**
* Fired when a turtle gathers data on an item in its inventory.
*
* You may prevent items being inspected, or add additional information to the result. Be aware that this is fired on
* the computer thread, and so any operations on it must be thread safe.
* You may prevent items being inspected, or add additional information to the result. Be aware that this is fired on the computer thread, and so any
* operations on it must be thread safe.
*
* @see TurtleAction#INSPECT_ITEM
*/
public class TurtleInspectItemEvent extends TurtleActionEvent
{
public class TurtleInspectItemEvent extends TurtleActionEvent {
private final ItemStack stack;
private final Map<String, Object> data;
public TurtleInspectItemEvent( @Nonnull ITurtleAccess turtle, @Nonnull ItemStack stack, @Nonnull Map<String, Object> data )
{
super( turtle, TurtleAction.INSPECT_ITEM );
public TurtleInspectItemEvent(@Nonnull ITurtleAccess turtle, @Nonnull ItemStack stack, @Nonnull Map<String, Object> data) {
super(turtle, TurtleAction.INSPECT_ITEM);
Objects.requireNonNull( stack, "stack cannot be null" );
Objects.requireNonNull( data, "data cannot be null" );
Objects.requireNonNull(stack, "stack cannot be null");
Objects.requireNonNull(data, "data cannot be null");
this.stack = stack;
this.data = data;
}
@@ -44,9 +44,8 @@ public class TurtleInspectItemEvent extends TurtleActionEvent
* @return The item stack which is being inspected. This should <b>not</b> be modified.
*/
@Nonnull
public ItemStack getStack()
{
return stack;
public ItemStack getStack() {
return this.stack;
}
/**
@@ -55,20 +54,19 @@ public class TurtleInspectItemEvent extends TurtleActionEvent
* @return This items's inspection data.
*/
@Nonnull
public Map<String, Object> getData()
{
return data;
public Map<String, Object> getData() {
return this.data;
}
/**
* Add new information to the inspection result. Note this will override fields with the same name.
*
* @param newData The data to add. Note all values should be convertible to Lua (see
* {@link dan200.computercraft.api.peripheral.IPeripheral#callMethod(IComputerAccess, ILuaContext, int, Object[])}).
* {@link dan200.computercraft.api.peripheral.IPeripheral#callMethod(IComputerAccess,
* ILuaContext, int, Object[])}).
*/
public void addData( @Nonnull Map<String, ?> newData )
{
Objects.requireNonNull( newData, "newData cannot be null" );
data.putAll( newData );
public void addData(@Nonnull Map<String, ?> newData) {
Objects.requireNonNull(newData, "newData cannot be null");
this.data.putAll(newData);
}
}

48
src/main/java/dan200/computercraft/api/turtle/event/TurtleInventoryEvent.java
View File

@@ -6,26 +6,27 @@
package dan200.computercraft.api.turtle.event;
import java.util.Objects;
import javax.annotation.Nonnull;
import javax.annotation.Nullable;
import dan200.computercraft.api.turtle.ITurtleAccess;
import net.minecraft.inventory.Inventory;
import net.minecraft.item.ItemStack;
import net.minecraft.util.math.BlockPos;
import net.minecraft.world.World;
import javax.annotation.Nonnull;
import javax.annotation.Nullable;
import java.util.Objects;
/**
* Fired when a turtle attempts to interact with an inventory.
*/
public abstract class TurtleInventoryEvent extends TurtleBlockEvent
{
public abstract class TurtleInventoryEvent extends TurtleBlockEvent {
private final Inventory handler;
protected TurtleInventoryEvent( @Nonnull ITurtleAccess turtle, @Nonnull TurtleAction action, @Nonnull FakePlayer player, @Nonnull World world, @Nonnull BlockPos pos, @Nullable Inventory handler )
{
super( turtle, action, player, world, pos );
protected TurtleInventoryEvent(@Nonnull ITurtleAccess turtle, @Nonnull TurtleAction action, @Nonnull FakePlayer player, @Nonnull World world,
@Nonnull BlockPos pos, @Nullable Inventory handler) {
super(turtle, action, player, world, pos);
this.handler = handler;
}
@@ -35,9 +36,8 @@ public abstract class TurtleInventoryEvent extends TurtleBlockEvent
* @return The inventory being interacted with, {@code null} if the item will be dropped to/sucked from the world.
*/
@Nullable
public Inventory getItemHandler()
{
return handler;
public Inventory getItemHandler() {
return this.handler;
}
/**
@@ -45,11 +45,9 @@ public abstract class TurtleInventoryEvent extends TurtleBlockEvent
*
* @see TurtleAction#SUCK
*/
public static class Suck extends TurtleInventoryEvent
{
public Suck( @Nonnull ITurtleAccess turtle, @Nonnull FakePlayer player, @Nonnull World world, @Nonnull BlockPos pos, @Nullable Inventory handler )
{
super( turtle, TurtleAction.SUCK, player, world, pos, handler );
public static class Suck extends TurtleInventoryEvent {
public Suck(@Nonnull ITurtleAccess turtle, @Nonnull FakePlayer player, @Nonnull World world, @Nonnull BlockPos pos, @Nullable Inventory handler) {
super(turtle, TurtleAction.SUCK, player, world, pos, handler);
}
}
@@ -58,15 +56,14 @@ public abstract class TurtleInventoryEvent extends TurtleBlockEvent
*
* @see TurtleAction#DROP
*/
public static class Drop extends TurtleInventoryEvent
{
public static class Drop extends TurtleInventoryEvent {
private final ItemStack stack;
public Drop( @Nonnull ITurtleAccess turtle, @Nonnull FakePlayer player, @Nonnull World world, @Nonnull BlockPos pos, @Nullable Inventory handler, @Nonnull ItemStack stack )
{
super( turtle, TurtleAction.DROP, player, world, pos, handler );
public Drop(@Nonnull ITurtleAccess turtle, @Nonnull FakePlayer player, @Nonnull World world, @Nonnull BlockPos pos, @Nullable Inventory handler,
@Nonnull ItemStack stack) {
super(turtle, TurtleAction.DROP, player, world, pos, handler);
Objects.requireNonNull( stack, "stack cannot be null" );
Objects.requireNonNull(stack, "stack cannot be null");
this.stack = stack;
}
@@ -76,9 +73,8 @@ public abstract class TurtleInventoryEvent extends TurtleBlockEvent
* @return The item stack which will be dropped. This should <b>not</b> be modified.
*/
@Nonnull
public ItemStack getStack()
{
return stack;
public ItemStack getStack() {
return this.stack;
}
}
}

20
src/main/java/dan200/computercraft/api/turtle/event/TurtlePlayerEvent.java
View File

@@ -6,25 +6,24 @@
package dan200.computercraft.api.turtle.event;
import dan200.computercraft.api.turtle.ITurtleAccess;
import java.util.Objects;
import javax.annotation.Nonnull;
import java.util.Objects;
import dan200.computercraft.api.turtle.ITurtleAccess;
/**
* An action done by a turtle which is normally done by a player.
*
* {@link #getPlayer()} may be used to modify the player's attributes or perform permission checks.
*/
public abstract class TurtlePlayerEvent extends TurtleActionEvent
{
public abstract class TurtlePlayerEvent extends TurtleActionEvent {
private final FakePlayer player;
protected TurtlePlayerEvent( @Nonnull ITurtleAccess turtle, @Nonnull TurtleAction action, @Nonnull FakePlayer player )
{
super( turtle, action );
protected TurtlePlayerEvent(@Nonnull ITurtleAccess turtle, @Nonnull TurtleAction action, @Nonnull FakePlayer player) {
super(turtle, action);
Objects.requireNonNull( player, "player cannot be null" );
Objects.requireNonNull(player, "player cannot be null");
this.player = player;
}
@@ -36,8 +35,7 @@ public abstract class TurtlePlayerEvent extends TurtleActionEvent
* @return A {@link FakePlayer} representing this turtle.
*/
@Nonnull
public FakePlayer getPlayer()
{
return player;
public FakePlayer getPlayer() {
return this.player;
}
}

50
src/main/java/dan200/computercraft/api/turtle/event/TurtleRefuelEvent.java
View File

@@ -6,29 +6,29 @@
package dan200.computercraft.api.turtle.event;
import dan200.computercraft.api.turtle.ITurtleAccess;
import net.minecraft.item.ItemStack;
import java.util.Objects;
import javax.annotation.Nonnull;
import javax.annotation.Nullable;
import java.util.Objects;
import dan200.computercraft.api.turtle.ITurtleAccess;
import net.minecraft.item.ItemStack;
/**
* Fired when a turtle attempts to refuel from an item.
*
* One may use {@link #setCanceled(boolean, String)} to prevent refueling from this specific item. Additionally, you
* may use {@link #setHandler(Handler)} to register a custom fuel provider.
* One may use {@link #setCanceled(boolean, String)} to prevent refueling from this specific item. Additionally, you may use {@link #setHandler(Handler)} to
* register a custom fuel provider.
*/
public class TurtleRefuelEvent extends TurtleActionEvent
{
public class TurtleRefuelEvent extends TurtleActionEvent {
private final ItemStack stack;
private Handler handler;
public TurtleRefuelEvent( @Nonnull ITurtleAccess turtle, @Nonnull ItemStack stack )
{
super( turtle, TurtleAction.REFUEL );
public TurtleRefuelEvent(@Nonnull ITurtleAccess turtle, @Nonnull ItemStack stack) {
super(turtle, TurtleAction.REFUEL);
Objects.requireNonNull( turtle, "turtle cannot be null" );
Objects.requireNonNull(turtle, "turtle cannot be null");
this.stack = stack;
}
@@ -39,9 +39,8 @@ public class TurtleRefuelEvent extends TurtleActionEvent
*
* @return The stack to refuel from.
*/
public ItemStack getStack()
{
return stack;
public ItemStack getStack() {
return this.stack;
}
/**
@@ -51,22 +50,19 @@ public class TurtleRefuelEvent extends TurtleActionEvent
* @see #setHandler(Handler)
*/
@Nullable
public Handler getHandler()
{
return handler;
public Handler getHandler() {
return this.handler;
}
/**
* Set the refuel handler for this stack.
*
* You should call this if you can actually refuel from this item, and ideally only if there are no existing
* handlers.
* You should call this if you can actually refuel from this item, and ideally only if there are no existing handlers.
*
* @param handler The new refuel handler.
* @see #getHandler()
*/
public void setHandler( @Nullable Handler handler )
{
public void setHandler(@Nullable Handler handler) {
this.handler = handler;
}
@@ -74,18 +70,16 @@ public class TurtleRefuelEvent extends TurtleActionEvent
* Handles refuelling a turtle from a specific item.
*/
@FunctionalInterface
public interface Handler
{
public interface Handler {
/**
* Refuel a turtle using an item.
*
* @param turtle The turtle to refuel.
* @param stack The stack to refuel with.
* @param slot The slot the stack resides within. This may be used to modify the inventory afterwards.
* @param limit The maximum number of refuel operations to perform. This will often correspond to the number of
* items to consume.
* @param stack The stack to refuel with.
* @param slot The slot the stack resides within. This may be used to modify the inventory afterwards.
* @param limit The maximum number of refuel operations to perform. This will often correspond to the number of items to consume.
* @return The amount of fuel gained.
*/
int refuel( @Nonnull ITurtleAccess turtle, @Nonnull ItemStack stack, int slot, int limit );
int refuel(@Nonnull ITurtleAccess turtle, @Nonnull ItemStack stack, int slot, int limit);
}
}