Merge branch 'mc-1.15.x' into mc-1.16.x

src/main/java/dan200/computercraft/api/ComputerCraftAPI.java

@@ -7,6 +7,7 @@ package dan200.computercraft.api;
 
 import dan200.computercraft.api.filesystem.IMount;
 import dan200.computercraft.api.filesystem.IWritableMount;
+import dan200.computercraft.api.lua.GenericSource;
 import dan200.computercraft.api.lua.ILuaAPIFactory;
 import dan200.computercraft.api.media.IMedia;
 import dan200.computercraft.api.media.IMediaProvider;
@@ -23,6 +24,7 @@ import net.minecraft.util.Direction;
 import net.minecraft.util.math.BlockPos;
 import net.minecraft.world.IBlockReader;
 import net.minecraft.world.World;
+import net.minecraftforge.common.capabilities.Capability;
 import net.minecraftforge.common.util.LazyOptional;
 
 import javax.annotation.Nonnull;
@@ -116,7 +118,7 @@ public final class ComputerCraftAPI
     }
 
     /**
-     * Registers a peripheral provider to convert blocks into {@link IPeripheral} implementations.
+     * rers a peripheral provider to convert blocks into {@link IPeripheral} implementations.
      *
      * @param provider The peripheral provider to register.
      * @see IPeripheral
@@ -127,6 +129,28 @@ public final class ComputerCraftAPI
         getInstance().registerPeripheralProvider( provider );
     }
 
+    /**
+     * Registers a method source for generic peripherals.
+     *
+     * @param source The method source to register.
+     * @see GenericSource
+     */
+    public static void registerGenericSource( @Nonnull GenericSource source )
+    {
+        getInstance().registerGenericSource( source );
+    }
+
+    /**
+     * Registers a capability that can be used by generic peripherals.
+     *
+     * @param capability The capability to register.
+     * @see GenericSource
+     */
+    public static void registerGenericCapability( @Nonnull Capability<?> capability )
+    {
+        getInstance().registerGenericCapability( capability );
+    }
+
     /**
      * 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
@@ -258,6 +282,10 @@ public final class ComputerCraftAPI
 
         void registerPeripheralProvider( @Nonnull IPeripheralProvider provider );
 
+        void registerGenericSource( @Nonnull GenericSource source );
+
+        void registerGenericCapability( @Nonnull Capability<?> capability );
+
         void registerTurtleUpgrade( @Nonnull ITurtleUpgrade upgrade );
 
         void registerBundledRedstoneProvider( @Nonnull IBundledRedstoneProvider provider );

src/main/java/dan200/computercraft/api/lua/GenericSource.java

@@ -0,0 +1,60 @@
+/*
+ * This file is part of the public ComputerCraft API - http://www.computercraft.info
+ * Copyright Daniel Ratcliffe, 2011-2021. 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.lua;
+
+import dan200.computercraft.api.ComputerCraftAPI;
+import dan200.computercraft.api.peripheral.IPeripheral;
+import dan200.computercraft.api.peripheral.IPeripheralProvider;
+import dan200.computercraft.core.asm.LuaMethod;
+import net.minecraft.util.ResourceLocation;
+import net.minecraftforge.common.capabilities.Capability;
+import net.minecraftforge.items.IItemHandler;
+
+import javax.annotation.Nonnull;
+
+/**
+ * A generic source of {@link LuaMethod} functions.
+ *
+ * Unlike normal objects ({@link IDynamicLuaObject} or {@link IPeripheral}), methods do not target this object but
+ * instead are defined as {@code static} and accept their target as the first parameter. This allows you to inject
+ * methods onto objects you do not own, as well as declaring methods for a specific "trait" (for instance, a
+ * {@link Capability}).
+ *
+ * Currently the "generic peripheral" system is incompatible with normal peripherals. Normal {@link IPeripheralProvider}
+ * or {@link IPeripheral} implementations take priority. Tile entities which use this system are given a peripheral name
+ * determined by their id, rather than any peripheral provider. This will hopefully change in the future, once a suitable
+ * design has been established.
+ *
+ * For example, the main CC: Tweaked mod defines a generic source for inventories, which works on {@link IItemHandler}s:
+ *
+ * <pre>{@code
+ * public class InventoryMethods implements GenericSource {
+ *     \@LuaFunction( mainThread = true )
+ *     public static int size(IItemHandler inventory) {
+ *         return inventory.getSlots();
+ *     }
+ *
+ *     // ...
+ * }
+ * }</pre>
+ *
+ * @see ComputerCraftAPI#registerGenericSource(GenericSource)
+ * @see ComputerCraftAPI#registerGenericCapability(Capability) New capabilities (those not built into Forge) must be
+ * explicitly given to the generic peripheral system, as there is no way to enumerate all capabilities.
+ */
+public interface GenericSource
+{
+    /**
+     * A unique identifier for this generic source.
+     *
+     * This is currently unused, but may be used in the future to allow disabling specific sources. It is recommended
+     * to return an identifier using your mod's ID.
+     *
+     * @return This source's identifier.
+     */
+    @Nonnull
+    ResourceLocation id();
+}