Move the core API into a separate module

It should be possible to consume the ComputerCraft's core (i.e.
non-Minecraft code) in other projects, such as emulators.  While this
has been possible for years, it's somewhat tricky from a maintenance
perspective - it's very easy to accidentally add an MC dependency
somewhere!

By publishing a separate "core" jar, we can better distinguish the
boundaries between our Lua runtime and the Minecraft-specific code.

Ideally we could have one core project (rather than separate core and
core-api modules), and publish a separate "api" jar, like we do for the
main mod. However, this isn't really possible to express using Maven
dependencies, and so we must resort to this system.

Of course, this is kinda what the Java module system is meant to solve,
but unfortunately getting that working with Minecraft is infeasible.

projects/core-api/build.gradle.kts

@@ -0,0 +1,27 @@
+plugins {
+    id("cc-tweaked.java-convention")
+    id("cc-tweaked.publishing")
+    id("cc-tweaked")
+}
+
+java {
+    withJavadocJar()
+}
+
+// Due to the slightly circular nature of our API, add the main API jars to the javadoc classpath.
+val docApi by configurations.registering {
+    isTransitive = false
+}
+
+dependencies {
+    compileOnly(project(":mc-stubs"))
+    compileOnlyApi(libs.jsr305)
+    compileOnlyApi(libs.checkerFramework)
+
+    "docApi"(project(":"))
+}
+
+tasks.javadoc {
+    // Depend on
+    classpath += docApi
+}

projects/core-api/src/main/java/dan200/computercraft/api/filesystem/FileAttributes.java

@@ -0,0 +1,55 @@
+/*
+ * This file is part of the public ComputerCraft API - http://www.computercraft.info
+ * Copyright Daniel Ratcliffe, 2011-2022. 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.filesystem;
+
+import java.nio.file.attribute.BasicFileAttributes;
+import java.nio.file.attribute.FileTime;
+import java.time.Instant;
+
+/**
+ * A simple version of {@link BasicFileAttributes}, which provides what information a {@link IMount} already exposes.
+ *
+ * @param isDirectory Whether this filesystem entry is a directory.
+ * @param size        The size of the file.
+ */
+record FileAttributes(boolean isDirectory, long size) implements BasicFileAttributes {
+    private static final FileTime EPOCH = FileTime.from(Instant.EPOCH);
+
+    @Override
+    public FileTime lastModifiedTime() {
+        return EPOCH;
+    }
+
+    @Override
+    public FileTime lastAccessTime() {
+        return EPOCH;
+    }
+
+    @Override
+    public FileTime creationTime() {
+        return EPOCH;
+    }
+
+    @Override
+    public boolean isRegularFile() {
+        return !isDirectory;
+    }
+
+    @Override
+    public boolean isSymbolicLink() {
+        return false;
+    }
+
+    @Override
+    public boolean isOther() {
+        return false;
+    }
+
+    @Override
+    public Object fileKey() {
+        return null;
+    }
+}

projects/core-api/src/main/java/dan200/computercraft/api/filesystem/FileOperationException.java

@@ -0,0 +1,39 @@
+/*
+ * This file is part of the public ComputerCraft API - http://www.computercraft.info
+ * Copyright Daniel Ratcliffe, 2011-2022. 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.filesystem;
+
+import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
+import java.io.IOException;
+import java.io.Serial;
+import java.util.Objects;
+
+/**
+ * An {@link IOException} which occurred on a specific file.
+ * <p>
+ * This may be thrown from a {@link IMount} or {@link IWritableMount} to give more information about a failure.
+ */
+public class FileOperationException extends IOException {
+    @Serial
+    private static final long serialVersionUID = -8809108200853029849L;
+
+    private final String filename;
+
+    public FileOperationException(@Nullable String filename, @Nonnull String message) {
+        super(Objects.requireNonNull(message, "message cannot be null"));
+        this.filename = filename;
+    }
+
+    public FileOperationException(@Nonnull String message) {
+        super(Objects.requireNonNull(message, "message cannot be null"));
+        filename = null;
+    }
+
+    @Nullable
+    public String getFilename() {
+        return filename;
+    }
+}

projects/core-api/src/main/java/dan200/computercraft/api/filesystem/IFileSystem.java

@@ -0,0 +1,42 @@
+/*
+ * This file is part of the public ComputerCraft API - http://www.computercraft.info
+ * Copyright Daniel Ratcliffe, 2011-2022. 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.filesystem;
+
+import java.io.IOException;
+
+/**
+ * Provides a mount of the entire computer's file system.
+ * <p>
+ * This exists for use by various APIs - one should not attempt to mount it.
+ */
+public interface IFileSystem extends IWritableMount {
+    /**
+     * Combine two paths together, reducing them into a normalised form.
+     *
+     * @param path  The main path.
+     * @param child The path to append.
+     * @return The combined, normalised path.
+     */
+    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.
+     * @throws IOException If the copy failed.
+     */
+    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.
+     * @throws IOException If the move failed.
+     */
+    void move(String from, String to) throws IOException;
+}

projects/core-api/src/main/java/dan200/computercraft/api/filesystem/IMount.java

@@ -0,0 +1,87 @@
+/*
+ * This file is part of the public ComputerCraft API - http://www.computercraft.info
+ * Copyright Daniel Ratcliffe, 2011-2022. 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.filesystem;
+
+import dan200.computercraft.api.peripheral.IComputerAccess;
+
+import javax.annotation.Nonnull;
+import java.io.IOException;
+import java.nio.channels.ReadableByteChannel;
+import java.nio.file.attribute.BasicFileAttributes;
+import java.util.List;
+
+/**
+ * Represents a read only part of a virtual filesystem that can be mounted onto a computer using
+ * {@link IComputerAccess#mount(String, IMount)}.
+ * <p>
+ * Typically you will not need to implement this interface yourself, and can use the factory methods from the
+ * {@linkplain dan200.computercraft.api.ComputerCraftAPI the main ComputerCraft API}.
+ *
+ * @see IComputerAccess#mount(String, IMount)
+ * @see IWritableMount
+ */
+public interface IMount {
+    /**
+     * Returns whether a file with a given path exists or not.
+     *
+     * @param path A file path in normalised format, relative to the mount location. ie: "programs/myprogram"
+     * @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;
+
+    /**
+     * Returns whether a file with a given path is a directory or not.
+     *
+     * @param path A file path in normalised format, relative to the mount location. ie: "programs/myprograms".
+     * @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;
+
+    /**
+     * 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 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;
+
+    /**
+     * Returns the size of a file with a given path, in bytes.
+     *
+     * @param path A file path in normalised format, relative to the mount location. ie: "programs/myprogram".
+     * @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;
+
+    /**
+     * 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
+    ReadableByteChannel openForRead(@Nonnull String path) throws IOException;
+
+    /**
+     * Get attributes about the given file.
+     *
+     * @param path The path to query.
+     * @return File attributes for the given file.
+     * @throws IOException If the file does not exist, or attributes could not be fetched.
+     */
+    @Nonnull
+    default BasicFileAttributes getAttributes(@Nonnull String path) throws IOException {
+        if (!exists(path)) throw new FileOperationException(path, "No such file");
+        return new FileAttributes(isDirectory(path), getSize(path));
+    }
+}

projects/core-api/src/main/java/dan200/computercraft/api/filesystem/IWritableMount.java

@@ -0,0 +1,85 @@
+/*
+ * This file is part of the public ComputerCraft API - http://www.computercraft.info
+ * Copyright Daniel Ratcliffe, 2011-2022. 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.filesystem;
+
+import dan200.computercraft.api.peripheral.IComputerAccess;
+
+import javax.annotation.Nonnull;
+import java.io.IOException;
+import java.io.OutputStream;
+import java.nio.channels.WritableByteChannel;
+import java.util.OptionalLong;
+
+/**
+ * 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.
+ * <p>
+ * Typically you will not need to implement this interface yourself, and can use the factory methods from the
+ * {@linkplain dan200.computercraft.api.ComputerCraftAPI the main ComputerCraft API}.
+ *
+ * @see IComputerAccess#mount(String, IMount)
+ * @see IComputerAccess#mountWritable(String, IWritableMount)
+ * @see 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;
+
+    /**
+     * Deletes 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/myoldprograms".
+     * @throws IOException If the file does not exist or could not be deleted.
+     */
+    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
+    WritableByteChannel openForWrite(@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
+    WritableByteChannel openForAppend(@Nonnull String path) throws IOException;
+
+    /**
+     * 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.
+     */
+    long getRemainingSpace() throws IOException;
+
+    /**
+     * Get the capacity of this mount. This should be equal to the size of all files/directories on this mount, minus
+     * the {@link #getRemainingSpace()}.
+     *
+     * @return The capacity of this mount, in bytes.
+     */
+    @Nonnull
+    default OptionalLong getCapacity() {
+        return OptionalLong.empty();
+    }
+}

projects/core-api/src/main/java/dan200/computercraft/api/lua/GenericSource.java

@@ -0,0 +1,56 @@
+/*
+ * This file is part of the public ComputerCraft API - http://www.computercraft.info
+ * Copyright Daniel Ratcliffe, 2011-2022. 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.peripheral.GenericPeripheral;
+import dan200.computercraft.api.peripheral.IPeripheral;
+import net.minecraft.resources.ResourceLocation;
+
+import javax.annotation.Nonnull;
+
+/**
+ * A generic source of {@link LuaFunction} functions.
+ * <p>
+ * 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 Forge
+ * capability or Fabric block lookup interface).
+ * <p>
+ * Currently the "generic peripheral" system is incompatible with normal peripherals. Peripherals explicitly provided
+ * by capabilities/the block lookup API take priority. Block entities which use this system are given a peripheral name
+ * determined by their id, rather than any peripheral provider, though additional types may be provided by overriding
+ * {@link GenericPeripheral#getType()}.
+ * <p>
+ * For example, the main CC: Tweaked mod defines a generic source for inventories, which works on {@code IItemHandler}s:
+ *
+ * <pre>{@code
+ * public class InventoryMethods implements GenericSource {
+ *     \@LuaFunction( mainThread = true )
+ *     public static int size(IItemHandler inventory) {
+ *         return inventory.getSlots();
+ *     }
+ *
+ *     // ...
+ * }
+ * }</pre>
+ *
+ * @see dan200.computercraft.api.ComputerCraftAPI#registerGenericSource(GenericSource)
+ * @see dan200.computercraft.api.ForgeComputerCraftAPI#registerGenericCapability 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.
+     * <p>
+     * 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();
+}

projects/core-api/src/main/java/dan200/computercraft/api/lua/IArguments.java

@@ -0,0 +1,415 @@
+/*
+ * This file is part of the public ComputerCraft API - http://www.computercraft.info
+ * Copyright Daniel Ratcliffe, 2011-2022. 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 javax.annotation.Nonnull;
+import javax.annotation.Nullable;
+import java.nio.ByteBuffer;
+import java.util.Map;
+import java.util.Optional;
+
+/**
+ * The arguments passed to a function.
+ */
+public interface IArguments {
+    /**
+     * Get the number of arguments passed to this function.
+     *
+     * @return The number of passed arguments.
+     */
+    int count();
+
+    /**
+     * Get the argument at the specific index. The returned value must obey the following conversion rules:
+     *
+     * <ul>
+     *   <li>Lua values of type "string" will be represented by a {@link String}.</li>
+     *   <li>Lua values of type "number" will be represented by a {@link Number}.</li>
+     *   <li>Lua values of type "boolean" will be represented by a {@link Boolean}.</li>
+     *   <li>Lua values of type "table" will be represented by a {@link Map}.</li>
+     *   <li>Lua values of any other type will be represented by a {@code null} value.</li>
+     * </ul>
+     *
+     * @param index The argument number.
+     * @return The argument's value, or {@code null} if not present.
+     */
+    @Nullable
+    Object get(int index);
+
+    /**
+     * Drop a number of arguments. The returned arguments instance will access arguments at position {@code i + count},
+     * rather than {@code i}. However, errors will still use the given argument index.
+     *
+     * @param count The number of arguments to drop.
+     * @return The new {@link IArguments} instance.
+     */
+    IArguments drop(int count);
+
+    default Object[] getAll() {
+        var result = new Object[count()];
+        for (var i = 0; i < result.length; i++) result[i] = get(i);
+        return result;
+    }
+
+    /**
+     * Get an argument as a double.
+     *
+     * @param index The argument number.
+     * @return The argument's value.
+     * @throws LuaException If the value is not a number.
+     * @see #getFiniteDouble(int) if you require this to be finite (i.e. not infinite or NaN).
+     */
+    default double getDouble(int index) throws LuaException {
+        var value = get(index);
+        if (!(value instanceof Number number)) throw LuaValues.badArgumentOf(index, "number", value);
+        return number.doubleValue();
+    }
+
+    /**
+     * Get an argument as an integer.
+     *
+     * @param index The argument number.
+     * @return The argument's value.
+     * @throws LuaException If the value is not an integer.
+     */
+    default int getInt(int index) throws LuaException {
+        return (int) getLong(index);
+    }
+
+    /**
+     * Get an argument as a long.
+     *
+     * @param index The argument number.
+     * @return The argument's value.
+     * @throws LuaException If the value is not a long.
+     */
+    default long getLong(int index) throws LuaException {
+        var value = get(index);
+        if (!(value instanceof Number number)) throw LuaValues.badArgumentOf(index, "number", value);
+        return LuaValues.checkFiniteNum(index, number).longValue();
+    }
+
+    /**
+     * Get an argument as a finite number (not infinite or NaN).
+     *
+     * @param index The argument number.
+     * @return The argument's value.
+     * @throws LuaException If the value is not finite.
+     */
+    default double getFiniteDouble(int index) throws LuaException {
+        return LuaValues.checkFinite(index, getDouble(index));
+    }
+
+    /**
+     * Get an argument as a boolean.
+     *
+     * @param index The argument number.
+     * @return The argument's value.
+     * @throws LuaException If the value is not a boolean.
+     */
+    default boolean getBoolean(int index) throws LuaException {
+        var value = get(index);
+        if (!(value instanceof Boolean bool)) throw LuaValues.badArgumentOf(index, "boolean", value);
+        return bool;
+    }
+
+    /**
+     * Get an argument as a string.
+     *
+     * @param index The argument number.
+     * @return The argument's value.
+     * @throws LuaException If the value is not a string.
+     */
+    @Nonnull
+    default String getString(int index) throws LuaException {
+        var value = get(index);
+        if (!(value instanceof String string)) throw LuaValues.badArgumentOf(index, "string", value);
+        return string;
+    }
+
+    /**
+     * Get a string argument as a byte array.
+     *
+     * @param index The argument number.
+     * @return The argument's value. This is a <em>read only</em> buffer.
+     * @throws LuaException If the value is not a string.
+     */
+    @Nonnull
+    default ByteBuffer getBytes(int index) throws LuaException {
+        return LuaValues.encode(getString(index));
+    }
+
+    /**
+     * Get a string argument as an enum value.
+     *
+     * @param index The argument number.
+     * @param klass The type of enum to parse.
+     * @param <T>   The type of enum to parse.
+     * @return The argument's value.
+     * @throws LuaException If the value is not a string or not a valid option for this enum.
+     */
+    @Nonnull
+    default <T extends Enum<T>> T getEnum(int index, Class<T> klass) throws LuaException {
+        return LuaValues.checkEnum(index, klass, getString(index));
+    }
+
+    /**
+     * Get an argument as a table.
+     *
+     * @param index The argument number.
+     * @return The argument's value.
+     * @throws LuaException If the value is not a table.
+     */
+    @Nonnull
+    default Map<?, ?> getTable(int index) throws LuaException {
+        var value = get(index);
+        if (!(value instanceof Map)) throw LuaValues.badArgumentOf(index, "table", value);
+        return (Map<?, ?>) value;
+    }
+
+    /**
+     * Get an argument as a table in an unsafe manner.
+     * <p>
+     * Classes implementing this interface may choose to implement a more optimised version which does not copy the
+     * table, instead returning a wrapper version, making it more efficient. However, the caller must guarantee that
+     * they do not access the table the computer thread (and so should not be used with main-thread functions) or once
+     * the initial call has finished (for instance, in a callback to {@link MethodResult#pullEvent}).
+     *
+     * @param index The argument number.
+     * @return The argument's value.
+     * @throws LuaException If the value is not a table.
+     */
+    @Nonnull
+    default LuaTable<?, ?> getTableUnsafe(int index) throws LuaException {
+        return new ObjectLuaTable(getTable(index));
+    }
+
+    /**
+     * Get an argument as a double.
+     *
+     * @param index The argument number.
+     * @return The argument's value, or {@link Optional#empty()} if not present.
+     * @throws LuaException If the value is not a number.
+     */
+    @Nonnull
+    default Optional<Double> optDouble(int index) throws LuaException {
+        var value = get(index);
+        if (value == null) return Optional.empty();
+        if (!(value instanceof Number number)) throw LuaValues.badArgumentOf(index, "number", value);
+        return Optional.of(number.doubleValue());
+    }
+
+    /**
+     * Get an argument as an int.
+     *
+     * @param index The argument number.
+     * @return The argument's value, or {@link Optional#empty()} if not present.
+     * @throws LuaException If the value is not a number.
+     */
+    @Nonnull
+    default Optional<Integer> optInt(int index) throws LuaException {
+        return optLong(index).map(Long::intValue);
+    }
+
+    /**
+     * Get an argument as a long.
+     *
+     * @param index The argument number.
+     * @return The argument's value, or {@link Optional#empty()} if not present.
+     * @throws LuaException If the value is not a number.
+     */
+    default Optional<Long> optLong(int index) throws LuaException {
+        var value = get(index);
+        if (value == null) return Optional.empty();
+        if (!(value instanceof Number number)) throw LuaValues.badArgumentOf(index, "number", value);
+        return Optional.of(LuaValues.checkFiniteNum(index, number).longValue());
+    }
+
+    /**
+     * Get an argument as a finite number (not infinite or NaN).
+     *
+     * @param index The argument number.
+     * @return The argument's value, or {@link Optional#empty()} if not present.
+     * @throws LuaException If the value is not finite.
+     */
+    default Optional<Double> optFiniteDouble(int index) throws LuaException {
+        var value = optDouble(index);
+        if (value.isPresent()) LuaValues.checkFiniteNum(index, value.get());
+        return value;
+    }
+
+    /**
+     * Get an argument as a boolean.
+     *
+     * @param index The argument number.
+     * @return The argument's value, or {@link Optional#empty()} if not present.
+     * @throws LuaException If the value is not a boolean.
+     */
+    default Optional<Boolean> optBoolean(int index) throws LuaException {
+        var value = get(index);
+        if (value == null) return Optional.empty();
+        if (!(value instanceof Boolean bool)) throw LuaValues.badArgumentOf(index, "boolean", value);
+        return Optional.of(bool);
+    }
+
+    /**
+     * Get an argument as a string.
+     *
+     * @param index The argument number.
+     * @return The argument's value, or {@link Optional#empty()} if not present.
+     * @throws LuaException If the value is not a string.
+     */
+    default Optional<String> optString(int index) throws LuaException {
+        var value = get(index);
+        if (value == null) return Optional.empty();
+        if (!(value instanceof String string)) throw LuaValues.badArgumentOf(index, "string", value);
+        return Optional.of(string);
+    }
+
+    /**
+     * Get a string argument as a byte array.
+     *
+     * @param index The argument number.
+     * @return The argument's value, or {@link Optional#empty()} if not present. This is a <em>read only</em> buffer.
+     * @throws LuaException If the value is not a string.
+     */
+    default Optional<ByteBuffer> optBytes(int index) throws LuaException {
+        return optString(index).map(LuaValues::encode);
+    }
+
+    /**
+     * Get a string argument as an enum value.
+     *
+     * @param index The argument number.
+     * @param klass The type of enum to parse.
+     * @param <T>   The type of enum to parse.
+     * @return The argument's value.
+     * @throws LuaException If the value is not a string or not a valid option for this enum.
+     */
+    @Nonnull
+    default <T extends Enum<T>> Optional<T> optEnum(int index, Class<T> klass) throws LuaException {
+        var str = optString(index);
+        return str.isPresent() ? Optional.of(LuaValues.checkEnum(index, klass, str.get())) : Optional.empty();
+    }
+
+    /**
+     * Get an argument as a table.
+     *
+     * @param index The argument number.
+     * @return The argument's value, or {@link Optional#empty()} if not present.
+     * @throws LuaException If the value is not a table.
+     */
+    default Optional<Map<?, ?>> optTable(int index) throws LuaException {
+        var value = get(index);
+        if (value == null) return Optional.empty();
+        if (!(value instanceof Map)) throw LuaValues.badArgumentOf(index, "map", value);
+        return Optional.of((Map<?, ?>) value);
+    }
+
+    /**
+     * Get an argument as a table in an unsafe manner.
+     * <p>
+     * Classes implementing this interface may choose to implement a more optimised version which does not copy the
+     * table, instead returning a wrapper version, making it more efficient. However, the caller must guarantee that
+     * they do not access off the computer thread (and so should not be used with main-thread functions) or once the
+     * function call has finished (for instance, in callbacks).
+     *
+     * @param index The argument number.
+     * @return The argument's value, or {@link Optional#empty()} if not present.
+     * @throws LuaException If the value is not a table.
+     */
+    @Nonnull
+    default Optional<LuaTable<?, ?>> optTableUnsafe(int index) throws LuaException {
+        var value = get(index);
+        if (value == null) return Optional.empty();
+        if (!(value instanceof Map)) throw LuaValues.badArgumentOf(index, "map", value);
+        return Optional.of(new ObjectLuaTable((Map<?, ?>) value));
+    }
+
+    /**
+     * Get an argument as a double.
+     *
+     * @param index The argument number.
+     * @param def   The default value, if this argument is not given.
+     * @return The argument's value, or {@code def} if none was provided.
+     * @throws LuaException If the value is not a number.
+     */
+    default double optDouble(int index, double def) throws LuaException {
+        return optDouble(index).orElse(def);
+    }
+
+    /**
+     * Get an argument as an int.
+     *
+     * @param index The argument number.
+     * @param def   The default value, if this argument is not given.
+     * @return The argument's value, or {@code def} if none was provided.
+     * @throws LuaException If the value is not a number.
+     */
+    default int optInt(int index, int def) throws LuaException {
+        return optInt(index).orElse(def);
+    }
+
+    /**
+     * Get an argument as a long.
+     *
+     * @param index The argument number.
+     * @param def   The default value, if this argument is not given.
+     * @return The argument's value, or {@code def} if none was provided.
+     * @throws LuaException If the value is not a number.
+     */
+    default long optLong(int index, long def) throws LuaException {
+        return optLong(index).orElse(def);
+    }
+
+    /**
+     * Get an argument as a finite number (not infinite or NaN).
+     *
+     * @param index The argument number.
+     * @param def   The default value, if this argument is not given.
+     * @return The argument's value, or {@code def} if none was provided.
+     * @throws LuaException If the value is not finite.
+     */
+    default double optFiniteDouble(int index, double def) throws LuaException {
+        return optFiniteDouble(index).orElse(def);
+    }
+
+    /**
+     * Get an argument as a boolean.
+     *
+     * @param index The argument number.
+     * @param def   The default value, if this argument is not given.
+     * @return The argument's value, or {@code def} if none was provided.
+     * @throws LuaException If the value is not a boolean.
+     */
+    default boolean optBoolean(int index, boolean def) throws LuaException {
+        return optBoolean(index).orElse(def);
+    }
+
+    /**
+     * Get an argument as a string.
+     *
+     * @param index The argument number.
+     * @param def   The default value, if this argument is not given.
+     * @return The argument's value, or {@code def} if none was provided.
+     * @throws LuaException If the value is not a string.
+     */
+    default String optString(int index, String def) throws LuaException {
+        return optString(index).orElse(def);
+    }
+
+    /**
+     * Get an argument as a table.
+     *
+     * @param index The argument number.
+     * @param def   The default value, if this argument is not given.
+     * @return The argument's value, or {@code def} if none was provided.
+     * @throws LuaException If the value is not a table.
+     */
+    default Map<?, ?> optTable(int index, Map<Object, Object> def) throws LuaException {
+        return optTable(index).orElse(def);
+    }
+}

projects/core-api/src/main/java/dan200/computercraft/api/lua/IComputerSystem.java

@@ -0,0 +1,33 @@
+/*
+ * This file is part of the public ComputerCraft API - http://www.computercraft.info
+ * Copyright Daniel Ratcliffe, 2011-2022. 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.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.
+ */
+public interface IComputerSystem extends IComputerAccess {
+    /**
+     * Get the file system for this computer.
+     *
+     * @return The computer's file system, or {@code null} if it is not initialised.
+     */
+    @Nullable
+    IFileSystem getFileSystem();
+
+    /**
+     * Get the label for this computer.
+     *
+     * @return This computer's label, or {@code null} if it is not set.
+     */
+    @Nullable
+    String getLabel();
+}

projects/core-api/src/main/java/dan200/computercraft/api/lua/IDynamicLuaObject.java

@@ -0,0 +1,44 @@
+/*
+ * This file is part of the public ComputerCraft API - http://www.computercraft.info
+ * Copyright Daniel Ratcliffe, 2011-2022. 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.peripheral.IDynamicPeripheral;
+
+import javax.annotation.Nonnull;
+
+/**
+ * An interface for representing custom objects returned by peripherals or other Lua objects.
+ * <p>
+ * Generally, one does not need to implement this type - it is sufficient to return an object with some methods
+ * annotated with {@link LuaFunction}. {@link IDynamicLuaObject} is useful when you wish your available methods to
+ * change at runtime.
+ */
+public interface IDynamicLuaObject {
+    /**
+     * Get the names of the methods that this object implements. This should not change over the course of the object's
+     * lifetime.
+     *
+     * @return The method names this object provides.
+     * @see IDynamicPeripheral#getMethodNames()
+     */
+    @Nonnull
+    String[] getMethodNames();
+
+    /**
+     * Called when a user calls one of the methods that this object implements.
+     *
+     * @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 method index from {@link #getMethodNames()} the computer wishes
+     *                  to call.
+     * @param arguments The arguments for this method.
+     * @return The result of this function. Either an immediate value ({@link MethodResult#of(Object...)} or an
+     * instruction to yield.
+     * @throws LuaException If the function threw an exception.
+     */
+    @Nonnull
+    MethodResult callMethod(@Nonnull ILuaContext context, int method, @Nonnull IArguments arguments) throws LuaException;
+}

projects/core-api/src/main/java/dan200/computercraft/api/lua/ILuaAPI.java

@@ -0,0 +1,46 @@
+/*
+ * This file is part of the public ComputerCraft API - http://www.computercraft.info
+ * Copyright Daniel Ratcliffe, 2011-2022. 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;
+
+/**
+ * Represents a Lua object which is stored as a global variable on computer startup. This must either provide
+ * {@link LuaFunction} annotated functions or implement {@link IDynamicLuaObject}.
+ * <p>
+ * Before implementing this interface, consider alternative methods of providing methods. It is generally preferred
+ * to use peripherals to provide functionality to users.
+ *
+ * @see ILuaAPIFactory For providing custom APIs to computers.
+ */
+public interface ILuaAPI {
+    /**
+     * Get the globals this API will be assigned to. This will override any other global, so you should
+     *
+     * @return A list of globals this API will be assigned to.
+     */
+    String[] getNames();
+
+    /**
+     * Called when the computer is turned on.
+     * <p>
+     * One should only interact with the file system.
+     */
+    default void startup() {
+    }
+
+    /**
+     * Called every time the computer is ticked. This can be used to process various.
+     */
+    default void update() {
+    }
+
+    /**
+     * Called when the computer is turned off or unloaded.
+     * <p>
+     * This should reset the state of the object, disposing any remaining file handles, or other resources.
+     */
+    default void shutdown() {
+    }
+}

projects/core-api/src/main/java/dan200/computercraft/api/lua/ILuaAPIFactory.java

@@ -0,0 +1,27 @@
+/*
+ * This file is part of the public ComputerCraft API - http://www.computercraft.info
+ * Copyright Daniel Ratcliffe, 2011-2022. 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 javax.annotation.Nonnull;
+import javax.annotation.Nullable;
+
+/**
+ * Construct an {@link ILuaAPI} for a specific computer.
+ *
+ * @see ILuaAPI
+ * @see dan200.computercraft.api.ComputerCraftAPI#registerAPIFactory(ILuaAPIFactory)
+ */
+@FunctionalInterface
+public interface ILuaAPIFactory {
+    /**
+     * Create a new API instance for a given computer.
+     *
+     * @param computer The computer this API is for.
+     * @return The created API, or {@code null} if one should not be injected.
+     */
+    @Nullable
+    ILuaAPI create(@Nonnull IComputerSystem computer);
+}

projects/core-api/src/main/java/dan200/computercraft/api/lua/ILuaCallback.java

@@ -0,0 +1,26 @@
+/*
+ * This file is part of the public ComputerCraft API - http://www.computercraft.info
+ * Copyright Daniel Ratcliffe, 2011-2022. 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 javax.annotation.Nonnull;
+
+/**
+ * A continuation which is called when this coroutine is resumed.
+ *
+ * @see MethodResult#yield(Object[], ILuaCallback)
+ */
+public interface ILuaCallback {
+    /**
+     * Resume this coroutine.
+     *
+     * @param args The result of resuming this coroutine. These will have the same form as described in
+     *             {@link LuaFunction}.
+     * @return The result of this continuation. Either the result to return to the callee, or another yield.
+     * @throws LuaException On an error.
+     */
+    @Nonnull
+    MethodResult resume(Object[] args) throws LuaException;
+}

projects/core-api/src/main/java/dan200/computercraft/api/lua/ILuaContext.java

@@ -0,0 +1,45 @@
+/*
+ * This file is part of the public ComputerCraft API - http://www.computercraft.info
+ * Copyright Daniel Ratcliffe, 2011-2022. 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 javax.annotation.Nonnull;
+
+/**
+ * An interface passed to peripherals and {@link IDynamicLuaObject}s by computers or turtles, providing methods
+ * that allow the peripheral call to interface with the computer.
+ */
+public interface ILuaContext {
+    /**
+     * 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.
+     * <p>
+     * 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.
+     *
+     * @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.
+     * @see LuaFunction#mainThread() To run functions on the main thread and return their results synchronously.
+     */
+    long issueMainThreadTask(@Nonnull ILuaTask task) throws LuaException;
+
+    /**
+     * 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.
+     * <p>
+     * Note that the return values of your task are handled as events, meaning more complex objects such as maps or
+     * {@link IDynamicLuaObject} 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.
+     */
+    @Nonnull
+    default MethodResult executeMainThreadTask(@Nonnull ILuaTask task) throws LuaException {
+        return TaskCallback.make(this, task);
+    }
+}

projects/core-api/src/main/java/dan200/computercraft/api/lua/ILuaFunction.java

@@ -0,0 +1,28 @@
+/*
+ * This file is part of the public ComputerCraft API - http://www.computercraft.info
+ * Copyright Daniel Ratcliffe, 2011-2022. 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 javax.annotation.Nonnull;
+
+/**
+ * A function, which can be called from Lua. If you need to return a table of functions, it is recommended to use
+ * an object with {@link LuaFunction} methods, or implement {@link IDynamicLuaObject}.
+ *
+ * @see MethodResult#of(Object)
+ */
+@FunctionalInterface
+public interface ILuaFunction {
+    /**
+     * Call this function with a series of arguments. Note, this will <em>always</em> be called on the computer thread,
+     * and so its implementation must be thread-safe.
+     *
+     * @param arguments The arguments for this function
+     * @return The result of calling this function.
+     * @throws LuaException Upon Lua errors.
+     */
+    @Nonnull
+    MethodResult call(@Nonnull IArguments arguments) throws LuaException;
+}

projects/core-api/src/main/java/dan200/computercraft/api/lua/ILuaTask.java

@@ -0,0 +1,29 @@
+/*
+ * This file is part of the public ComputerCraft API - http://www.computercraft.info
+ * Copyright Daniel Ratcliffe, 2011-2022. 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 javax.annotation.Nullable;
+
+/**
+ * A task which can be executed via {@link ILuaContext#issueMainThreadTask(ILuaTask)} This will be run on the main
+ * thread, at the beginning of the
+ * next tick.
+ *
+ * @see ILuaContext#issueMainThreadTask(ILuaTask)
+ */
+@FunctionalInterface
+public interface ILuaTask {
+    /**
+     * Execute this task.
+     *
+     * @return The arguments to add to the {@code task_completed} event.
+     * @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;
+}

projects/core-api/src/main/java/dan200/computercraft/api/lua/LuaException.java

@@ -0,0 +1,50 @@
+/*
+ * This file is part of the public ComputerCraft API - http://www.computercraft.info
+ * Copyright Daniel Ratcliffe, 2011-2022. 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 javax.annotation.Nullable;
+import java.io.Serial;
+
+/**
+ * An exception representing an error in Lua, like that raised by the {@code error()} function.
+ */
+public class LuaException extends Exception {
+    @Serial
+    private static final long serialVersionUID = -6136063076818512651L;
+    private final boolean hasLevel;
+    private final int level;
+
+    public LuaException(@Nullable String message) {
+        super(message);
+        hasLevel = false;
+        level = 1;
+    }
+
+    public LuaException(@Nullable String message, int level) {
+        super(message);
+        hasLevel = true;
+        this.level = level;
+    }
+
+    /**
+     * Whether a level was explicitly specified when constructing. This is used to determine
+     *
+     * @return Whether this has an explicit level.
+     */
+    public boolean hasLevel() {
+        return hasLevel;
+    }
+
+    /**
+     * 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;
+    }
+}

projects/core-api/src/main/java/dan200/computercraft/api/lua/LuaFunction.java

@@ -0,0 +1,66 @@
+/*
+ * This file is part of the public ComputerCraft API - http://www.computercraft.info
+ * Copyright Daniel Ratcliffe, 2011-2022. 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.peripheral.IComputerAccess;
+import dan200.computercraft.api.peripheral.IPeripheral;
+
+import java.lang.annotation.*;
+import java.util.Map;
+import java.util.Optional;
+
+/**
+ * Used to mark a Java function which is callable from Lua.
+ * <p>
+ * Methods annotated with {@link LuaFunction} must be public final instance methods. They can have any number of
+ * parameters, but they must be of the following types:
+ *
+ * <ul>
+ *   <li>{@link ILuaContext} (and {@link IComputerAccess} if on a {@link IPeripheral})</li>
+ *   <li>{@link IArguments}: The arguments supplied to this function.</li>
+ *   <li>
+ *     Alternatively, one may specify the desired arguments as normal parameters and the argument parsing code will
+ *     be generated automatically.
+ * <p>
+ *     Each parameter must be one of the given types supported by {@link IArguments} (for instance, {@link int} or
+ *     {@link Map}). Optional values are supported by accepting a parameter of type {@link Optional}.
+ *   </li>
+ * </ul>
+ * <p>
+ * This function may return {@link MethodResult}. However, if you simply return a value (rather than having to yield),
+ * you may return {@code void}, a single value (either an object or a primitive like {@code int}) or array of objects.
+ * These will be treated the same as {@link MethodResult#of()}, {@link MethodResult#of(Object)} and
+ * {@link MethodResult#of(Object...)}.
+ */
+@Documented
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.METHOD)
+public @interface LuaFunction {
+    /**
+     * Explicitly specify the method names of this function. If not given, it uses the name of the annotated method.
+     *
+     * @return This function's name(s).
+     */
+    String[] value() default {};
+
+    /**
+     * Run this function on the main server thread. This should be specified for any method which interacts with
+     * Minecraft in a thread-unsafe manner.
+     *
+     * @return Whether this function should be run on the main thread.
+     * @see ILuaContext#issueMainThreadTask(ILuaTask)
+     */
+    boolean mainThread() default false;
+
+    /**
+     * Allow using "unsafe" arguments, such {@link IArguments#getTableUnsafe(int)}.
+     * <p>
+     * This is incompatible with {@link #mainThread()}.
+     *
+     * @return Whether this function supports unsafe arguments.
+     */
+    boolean unsafe() default false;
+}

projects/core-api/src/main/java/dan200/computercraft/api/lua/LuaTable.java

@@ -0,0 +1,107 @@
+/*
+ * This file is part of the public ComputerCraft API - http://www.computercraft.info
+ * Copyright Daniel Ratcliffe, 2011-2022. 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 javax.annotation.Nonnull;
+import javax.annotation.Nullable;
+import java.util.Map;
+
+import static dan200.computercraft.api.lua.LuaValues.*;
+
+/**
+ * A view of a Lua table, which may be able to access table elements in a more optimised manner than
+ * {@link IArguments#getTable(int)}.
+ *
+ * @param <K> The type of keys in a table, will typically be a wildcard.
+ * @param <V> The type of values in a table, will typically be a wildcard.
+ */
+public interface LuaTable<K, V> extends Map<K, V> {
+    /**
+     * Compute the length of the array part of this table.
+     *
+     * @return This table's length.
+     */
+    default int length() {
+        var size = 0;
+        while (containsKey((double) (size + 1))) size++;
+        return size;
+    }
+
+    /**
+     * Get an array entry as an integer.
+     *
+     * @param index The index in the table, starting at 1.
+     * @return The table's value.
+     * @throws LuaException If the value is not an integer.
+     */
+    default long getLong(int index) throws LuaException {
+        Object value = get((double) index);
+        if (!(value instanceof Number number)) throw badTableItem(index, "number", getType(value));
+
+        var asDouble = number.doubleValue();
+        if (!Double.isFinite(asDouble)) throw badTableItem(index, "number", getNumericType(asDouble));
+        return number.longValue();
+    }
+
+    /**
+     * Get a table entry as an integer.
+     *
+     * @param key The name of the field in the table.
+     * @return The table's value.
+     * @throws LuaException If the value is not an integer.
+     */
+    default long getLong(String key) throws LuaException {
+        Object value = get(key);
+        if (!(value instanceof Number number)) throw badField(key, "number", getType(value));
+
+        var asDouble = number.doubleValue();
+        if (!Double.isFinite(asDouble)) throw badField(key, "number", getNumericType(asDouble));
+        return number.longValue();
+    }
+
+    /**
+     * Get an array entry as an integer.
+     *
+     * @param index The index in the table, starting at 1.
+     * @return The table's value.
+     * @throws LuaException If the value is not an integer.
+     */
+    default int getInt(int index) throws LuaException {
+        return (int) getLong(index);
+    }
+
+    /**
+     * Get a table entry as an integer.
+     *
+     * @param key The name of the field in the table.
+     * @return The table's value.
+     * @throws LuaException If the value is not an integer.
+     */
+    default int getInt(String key) throws LuaException {
+        return (int) getLong(key);
+    }
+
+    @Nullable
+    @Override
+    default V put(K o, V o2) {
+        throw new UnsupportedOperationException("Cannot modify LuaTable");
+    }
+
+    @Override
+    default V remove(Object o) {
+        throw new UnsupportedOperationException("Cannot modify LuaTable");
+    }
+
+    @Override
+    default void putAll(@Nonnull Map<? extends K, ? extends V> map) {
+        throw new UnsupportedOperationException("Cannot modify LuaTable");
+    }
+
+    @Override
+    default void clear() {
+        throw new UnsupportedOperationException("Cannot modify LuaTable");
+    }
+}

projects/core-api/src/main/java/dan200/computercraft/api/lua/LuaValues.java

@@ -0,0 +1,166 @@
+/*
+ * This file is part of the public ComputerCraft API - http://www.computercraft.info
+ * Copyright Daniel Ratcliffe, 2011-2022. 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 javax.annotation.Nonnull;
+import javax.annotation.Nullable;
+import java.nio.ByteBuffer;
+import java.util.Map;
+
+/**
+ * Various utility functions for operating with Lua values.
+ *
+ * @see IArguments
+ */
+public final class LuaValues {
+    private LuaValues() {
+    }
+
+    /**
+     * Encode a Lua string into a read-only {@link ByteBuffer}.
+     *
+     * @param string The string to encode.
+     * @return The encoded string.
+     */
+    @Nonnull
+    public static ByteBuffer encode(@Nonnull String string) {
+        var chars = new byte[string.length()];
+        for (var i = 0; i < chars.length; i++) {
+            var c = string.charAt(i);
+            chars[i] = c < 256 ? (byte) c : 63;
+        }
+
+        return ByteBuffer.wrap(chars).asReadOnlyBuffer();
+    }
+
+    /**
+     * Returns a more detailed representation of this number's type. If this is finite, it will just return "number",
+     * otherwise it returns whether it is infinite or NaN.
+     *
+     * @param value The value to extract the type for.
+     * @return This value's numeric type.
+     */
+    @Nonnull
+    public static String getNumericType(double value) {
+        if (Double.isNaN(value)) return "nan";
+        if (value == Double.POSITIVE_INFINITY) return "inf";
+        if (value == Double.NEGATIVE_INFINITY) return "-inf";
+        return "number";
+    }
+
+    /**
+     * Get a string representation of the given value's type.
+     *
+     * @param value The value whose type we are trying to compute.
+     * @return A string representation of the given value's type, in a similar format to that provided by Lua's
+     * {@code type} function.
+     */
+    @Nonnull
+    public static String getType(@Nullable Object value) {
+        if (value == null) return "nil";
+        if (value instanceof String) return "string";
+        if (value instanceof Boolean) return "boolean";
+        if (value instanceof Number) return "number";
+        if (value instanceof Map) return "table";
+        return "userdata";
+    }
+
+    /**
+     * Construct a "bad argument" exception, from an expected type and the actual value provided.
+     *
+     * @param index    The argument number, starting from 0.
+     * @param expected The expected type for this argument.
+     * @param actual   The actual value provided for this argument.
+     * @return The constructed exception, which should be thrown immediately.
+     */
+    @Nonnull
+    public static LuaException badArgumentOf(int index, @Nonnull String expected, @Nullable Object actual) {
+        return badArgument(index, expected, getType(actual));
+    }
+
+    /**
+     * Construct a "bad argument" exception, from an expected and actual type.
+     *
+     * @param index    The argument number, starting from 0.
+     * @param expected The expected type for this argument.
+     * @param actual   The provided type for this argument.
+     * @return The constructed exception, which should be thrown immediately.
+     */
+    @Nonnull
+    public static LuaException badArgument(int index, @Nonnull String expected, @Nonnull String actual) {
+        return new LuaException("bad argument #" + (index + 1) + " (" + expected + " expected, got " + actual + ")");
+    }
+
+    /**
+     * Construct a table item exception, from an expected and actual type.
+     *
+     * @param index    The index into the table, starting from 1.
+     * @param expected The expected type for this table item.
+     * @param actual   The provided type for this table item.
+     * @return The constructed exception, which should be thrown immediately.
+     */
+    @Nonnull
+    public static LuaException badTableItem(int index, @Nonnull String expected, @Nonnull String actual) {
+        return new LuaException("table item #" + index + " is not " + expected + " (got " + actual + ")");
+    }
+
+    /**
+     * Construct a field exception, from an expected and actual type.
+     *
+     * @param key      The name of the field.
+     * @param expected The expected type for this table item.
+     * @param actual   The provided type for this table item.
+     * @return The constructed exception, which should be thrown immediately.
+     */
+    @Nonnull
+    public static LuaException badField(String key, @Nonnull String expected, @Nonnull String actual) {
+        return new LuaException("field " + key + " is not " + expected + " (got " + actual + ")");
+    }
+
+    /**
+     * Ensure a numeric argument is finite (i.e. not infinite or {@link Double#NaN}.
+     *
+     * @param index The argument index to check.
+     * @param value The value to check.
+     * @return The input {@code value}.
+     * @throws LuaException If this is not a finite number.
+     */
+    public static Number checkFiniteNum(int index, Number value) throws LuaException {
+        checkFinite(index, value.doubleValue());
+        return value;
+    }
+
+    /**
+     * Ensure a numeric argument is finite (i.e. not infinite or {@link Double#NaN}.
+     *
+     * @param index The argument index to check.
+     * @param value The value to check.
+     * @return The input {@code value}.
+     * @throws LuaException If this is not a finite number.
+     */
+    public static double checkFinite(int index, double value) throws LuaException {
+        if (!Double.isFinite(value)) throw badArgument(index, "number", getNumericType(value));
+        return value;
+    }
+
+    /**
+     * Ensure a string is a valid enum value.
+     *
+     * @param index The argument index to check.
+     * @param klass The class of the enum instance.
+     * @param value The value to extract.
+     * @param <T>   The type of enum we are extracting.
+     * @return The parsed enum value.
+     * @throws LuaException If this is not a known enum value.
+     */
+    public static <T extends Enum<T>> T checkEnum(int index, Class<T> klass, String value) throws LuaException {
+        for (var possibility : klass.getEnumConstants()) {
+            if (possibility.name().equalsIgnoreCase(value)) return possibility;
+        }
+
+        throw new LuaException("bad argument #" + (index + 1) + " (unknown option " + value + ")");
+    }
+}

projects/core-api/src/main/java/dan200/computercraft/api/lua/MethodResult.java

@@ -0,0 +1,159 @@
+/*
+ * This file is part of the public ComputerCraft API - http://www.computercraft.info
+ * Copyright Daniel Ratcliffe, 2011-2022. 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.peripheral.IComputerAccess;
+
+import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
+import java.nio.ByteBuffer;
+import java.util.Collection;
+import java.util.Map;
+import java.util.Objects;
+
+/**
+ * The result of invoking a Lua method.
+ * <p>
+ * Method results either return a value immediately ({@link #of(Object...)} or yield control to the parent coroutine.
+ * When the current coroutine is resumed, we invoke the provided {@link ILuaCallback#resume(Object[])} callback.
+ */
+public final class MethodResult {
+    private static final MethodResult empty = new MethodResult(null, null);
+
+    private final Object[] result;
+    private final ILuaCallback callback;
+    private final int adjust;
+
+    private MethodResult(Object[] arguments, ILuaCallback callback) {
+        result = arguments;
+        this.callback = callback;
+        adjust = 0;
+    }
+
+    private MethodResult(Object[] arguments, ILuaCallback callback, int adjust) {
+        result = arguments;
+        this.callback = callback;
+        this.adjust = adjust;
+    }
+
+    /**
+     * Return no values immediately.
+     *
+     * @return A method result which returns immediately with no values.
+     */
+    @Nonnull
+    public static MethodResult of() {
+        return empty;
+    }
+
+    /**
+     * Return a single value immediately.
+     * <p>
+     * Integers, doubles, floats, strings, booleans, {@link Map}, {@link Collection}s, arrays and {@code null} will be
+     * converted to their corresponding Lua type. {@code byte[]} and {@link ByteBuffer} will be treated as binary
+     * strings. {@link ILuaFunction} will be treated as a function.
+     * <p>
+     * In order to provide a custom object with methods, one may return a {@link IDynamicLuaObject}, or an arbitrary
+     * class with {@link LuaFunction} annotations. Anything else will be converted to {@code nil}.
+     *
+     * @param value The value to return to the calling Lua function.
+     * @return A method result which returns immediately with the given value.
+     */
+    @Nonnull
+    public static MethodResult of(@Nullable Object value) {
+        return new MethodResult(new Object[]{ value }, null);
+    }
+
+    /**
+     * Return any number of values immediately.
+     *
+     * @param values The values to return. See {@link #of(Object)} for acceptable values.
+     * @return A method result which returns immediately with the given values.
+     */
+    @Nonnull
+    public static MethodResult of(@Nullable Object... values) {
+        return values == null || values.length == 0 ? empty : new MethodResult(values, null);
+    }
+
+    /**
+     * 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.
+     * @param callback The callback to resume with the name of the event that occurred, and any event parameters.
+     * @return The method result which represents this yield.
+     * @see IComputerAccess#queueEvent(String, Object[])
+     */
+    @Nonnull
+    public static MethodResult pullEvent(@Nullable String filter, @Nonnull ILuaCallback callback) {
+        Objects.requireNonNull(callback, "callback cannot be null");
+        return new MethodResult(new Object[]{ filter }, results -> {
+            if (results.length >= 1 && Objects.equals(results[0], "terminate")) {
+                throw new LuaException("Terminated", 0);
+            }
+            return callback.resume(results);
+        });
+    }
+
+    /**
+     * The same as {@link #pullEvent(String, ILuaCallback)}, 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.
+     * @param callback The callback to resume with the name of the event that occurred, and any event parameters.
+     * @return The method result which represents this yield.
+     * @see #pullEvent(String, ILuaCallback)
+     */
+    @Nonnull
+    public static MethodResult pullEventRaw(@Nullable String filter, @Nonnull ILuaCallback callback) {
+        Objects.requireNonNull(callback, "callback cannot be null");
+        return new MethodResult(new Object[]{ filter }, callback);
+    }
+
+    /**
+     * 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()
+     * @param callback  The callback to resume with an array containing the return values from coroutine.yield()
+     * @return The method result which represents this yield.
+     * @see #pullEvent(String, ILuaCallback)
+     */
+    @Nonnull
+    public static MethodResult yield(@Nullable Object[] arguments, @Nonnull ILuaCallback callback) {
+        Objects.requireNonNull(callback, "callback cannot be null");
+        return new MethodResult(arguments, callback);
+    }
+
+    @Nullable
+    public Object[] getResult() {
+        return result;
+    }
+
+    @Nullable
+    public ILuaCallback getCallback() {
+        return callback;
+    }
+
+    public int getErrorAdjust() {
+        return adjust;
+    }
+
+    /**
+     * Increase the Lua error by a specific amount. One should never need to use this function - it largely exists for
+     * some CC internal code.
+     *
+     * @param adjust The amount to increase the level by.
+     * @return The new {@link MethodResult} with an adjusted error. This has no effect on immediate results.
+     */
+    @Nonnull
+    public MethodResult adjustError(int adjust) {
+        if (adjust < 0) throw new IllegalArgumentException("cannot adjust by a negative amount");
+        if (adjust == 0 || callback == null) return this;
+        return new MethodResult(result, callback, this.adjust + adjust);
+    }
+}

projects/core-api/src/main/java/dan200/computercraft/api/lua/ObjectArguments.java

@@ -0,0 +1,59 @@
+/*
+ * This file is part of the public ComputerCraft API - http://www.computercraft.info
+ * Copyright Daniel Ratcliffe, 2011-2022. 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 javax.annotation.Nullable;
+import java.util.Arrays;
+import java.util.List;
+import java.util.Objects;
+
+/**
+ * An implementation of {@link IArguments} which wraps an array of {@link Object}.
+ */
+public final class ObjectArguments implements IArguments {
+    private static final IArguments EMPTY = new ObjectArguments();
+
+    private final List<Object> args;
+
+    @Deprecated
+    @SuppressWarnings("unused")
+    public ObjectArguments(IArguments arguments) {
+        throw new IllegalStateException();
+    }
+
+    public ObjectArguments(Object... args) {
+        this.args = Arrays.asList(args);
+    }
+
+    public ObjectArguments(List<Object> args) {
+        this.args = Objects.requireNonNull(args);
+    }
+
+    @Override
+    public int count() {
+        return args.size();
+    }
+
+    @Override
+    public IArguments drop(int count) {
+        if (count < 0) throw new IllegalStateException("count cannot be negative");
+        if (count == 0) return this;
+        if (count >= args.size()) return EMPTY;
+
+        return new ObjectArguments(args.subList(count, args.size()));
+    }
+
+    @Nullable
+    @Override
+    public Object get(int index) {
+        return index >= args.size() ? null : args.get(index);
+    }
+
+    @Override
+    public Object[] getAll() {
+        return args.toArray();
+    }
+}

projects/core-api/src/main/java/dan200/computercraft/api/lua/ObjectLuaTable.java

@@ -0,0 +1,66 @@
+/*
+ * This file is part of the public ComputerCraft API - http://www.computercraft.info
+ * Copyright Daniel Ratcliffe, 2011-2022. 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 javax.annotation.Nonnull;
+import java.util.Collection;
+import java.util.Collections;
+import java.util.Map;
+import java.util.Set;
+
+/**
+ * An implementation of {@link LuaTable} based on a standard Java {@link Map}.
+ */
+public class ObjectLuaTable implements LuaTable<Object, Object> {
+    private final Map<Object, Object> map;
+
+    public ObjectLuaTable(Map<?, ?> map) {
+        this.map = Collections.unmodifiableMap(map);
+    }
+
+    @Override
+    public int size() {
+        return map.size();
+    }
+
+    @Override
+    public boolean isEmpty() {
+        return map.isEmpty();
+    }
+
+    @Override
+    public boolean containsKey(Object o) {
+        return map.containsKey(o);
+    }
+
+    @Override
+    public boolean containsValue(Object o) {
+        return map.containsKey(o);
+    }
+
+    @Override
+    public Object get(Object o) {
+        return map.get(o);
+    }
+
+    @Nonnull
+    @Override
+    public Set<Object> keySet() {
+        return map.keySet();
+    }
+
+    @Nonnull
+    @Override
+    public Collection<Object> values() {
+        return map.values();
+    }
+
+    @Nonnull
+    @Override
+    public Set<Entry<Object, Object>> entrySet() {
+        return map.entrySet();
+    }
+}

projects/core-api/src/main/java/dan200/computercraft/api/lua/TaskCallback.java

@@ -0,0 +1,43 @@
+/*
+ * This file is part of the public ComputerCraft API - http://www.computercraft.info
+ * Copyright Daniel Ratcliffe, 2011-2022. 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 javax.annotation.Nonnull;
+import java.util.Arrays;
+
+final class TaskCallback implements ILuaCallback {
+    private final MethodResult pull = MethodResult.pullEvent("task_complete", this);
+    private final long task;
+
+    private TaskCallback(long task) {
+        this.task = task;
+    }
+
+    @Nonnull
+    @Override
+    public MethodResult resume(Object[] response) throws LuaException {
+        if (response.length < 3 || !(response[1] instanceof Number) || !(response[2] instanceof Boolean)) {
+            return pull;
+        }
+
+        if (((Number) response[1]).longValue() != task) return pull;
+
+        if ((Boolean) response[2]) {
+            // Extract the return values from the event and return them
+            return MethodResult.of(Arrays.copyOfRange(response, 3, response.length));
+        } else if (response.length >= 4 && response[3] instanceof String) {
+            // Extract the error message from the event and raise it
+            throw new LuaException((String) response[3]);
+        } else {
+            throw new LuaException("error");
+        }
+    }
+
+    static MethodResult make(ILuaContext context, ILuaTask func) throws LuaException {
+        var task = context.issueMainThreadTask(func);
+        return new TaskCallback(task).pull;
+    }
+}

projects/core-api/src/main/java/dan200/computercraft/api/peripheral/GenericPeripheral.java

@@ -0,0 +1,41 @@
+/*
+ * This file is part of the public ComputerCraft API - http://www.computercraft.info
+ * Copyright Daniel Ratcliffe, 2011-2022. 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 dan200.computercraft.api.lua.GenericSource;
+
+import javax.annotation.Nonnull;
+
+/**
+ * A {@link GenericSource} which provides methods for a peripheral.
+ * <p>
+ * Unlike a {@link GenericSource}, all methods <strong>should</strong> target the same type, for instance a
+ * block entity subclass. This is not currently enforced.
+ */
+public interface GenericPeripheral extends GenericSource {
+    /**
+     * Get the type of the exposed peripheral.
+     * <p>
+     * Unlike normal {@link IPeripheral}s, {@link GenericPeripheral} do not have to have a type. By default, the
+     * resulting peripheral uses the resource name of the wrapped block entity (for instance {@code minecraft:chest}).
+     * <p>
+     * However, in some cases it may be more appropriate to specify a more readable name. Overriding this method allows
+     * you to do so.
+     * <p>
+     * When multiple {@link GenericPeripheral}s return a non-empty peripheral type for a single tile entity, the
+     * lexicographically smallest will be chosen. In order to avoid this conflict, this method should only be
+     * implemented when your peripheral targets a single tile entity <strong>AND</strong> it's likely that you're the
+     * only mod to do so. Similarly this should <strong>NOT</strong> be implemented when your methods target a
+     * capability or other interface (such as Forge's {@code IItemHandler}).
+     *
+     * @return The type of this peripheral or {@link PeripheralType#untyped()}.
+     * @see IPeripheral#getType()
+     */
+    @Nonnull
+    default PeripheralType getType() {
+        return PeripheralType.untyped();
+    }
+}

projects/core-api/src/main/java/dan200/computercraft/api/peripheral/IComputerAccess.java

@@ -0,0 +1,195 @@
+/*
+ * This file is part of the public ComputerCraft API - http://www.computercraft.info
+ * Copyright Daniel Ratcliffe, 2011-2022. 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 dan200.computercraft.api.filesystem.IMount;
+import dan200.computercraft.api.filesystem.IWritableMount;
+import dan200.computercraft.api.lua.ILuaCallback;
+import dan200.computercraft.api.lua.ILuaContext;
+import dan200.computercraft.api.lua.ILuaTask;
+import dan200.computercraft.api.lua.MethodResult;
+
+import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
+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.
+ */
+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.
+     * @throws NotAttachedException If the peripheral has been detached.
+     * @see #mount(String, IMount, String)
+     * @see #mountWritable(String, IWritableMount)
+     * @see #unmount(String)
+     * @see IMount
+     */
+    @Nullable
+    default String mount(@Nonnull String desiredLocation, @Nonnull IMount mount) {
+        return mount(desiredLocation, mount, 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.
+     * @throws NotAttachedException If the peripheral has been detached.
+     * @see #mount(String, IMount)
+     * @see #mountWritable(String, IWritableMount)
+     * @see #unmount(String)
+     * @see IMount
+     */
+    @Nullable
+    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 NotAttachedException If the peripheral has been detached.
+     * @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 NotAttachedException If the peripheral has been detached.
+     * @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)}.
+     * <p>
+     * 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.
+     * <p>
+     * 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 NotAttachedException  If the peripheral has been detached.
+     * @throws IllegalStateException 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.
+     * <p>
+     * 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().
+     *                  <p>
+     *                  You may supply {@code null} to indicate that no arguments are to be supplied.
+     * @throws NotAttachedException If the peripheral has been detached.
+     * @see MethodResult#pullEvent(String, ILuaCallback)
+     */
+    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.
+     *
+     * @return A string unique to the computer, but not globally.
+     * @throws NotAttachedException If the peripheral has been detached.
+     */
+    @Nonnull
+    String getAttachmentName();
+
+    /**
+     * Get a set of peripherals that this computer access can "see", along with their attachment name.
+     * <p>
+     * This may include other peripherals on the wired network or peripherals on other sides of the computer.
+     *
+     * @return All reachable peripherals
+     * @throws NotAttachedException If the peripheral has been detached.
+     * @see #getAttachmentName()
+     * @see #getAvailablePeripheral(String)
+     */
+    @Nonnull
+    Map<String, IPeripheral> getAvailablePeripherals();
+
+    /**
+     * 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
+    IPeripheral getAvailablePeripheral(@Nonnull String name);
+
+    /**
+     * Get a {@link IWorkMonitor} for tasks your peripheral might execute on the main (server) thread.
+     * <p>
+     * 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.
+     * <p>
+     * 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.
+     * @throws NotAttachedException If the peripheral has been detached.
+     */
+    @Nonnull
+    IWorkMonitor getMainThreadMonitor();
+}

projects/core-api/src/main/java/dan200/computercraft/api/peripheral/IDynamicPeripheral.java

@@ -0,0 +1,52 @@
+/*
+ * This file is part of the public ComputerCraft API - http://www.computercraft.info
+ * Copyright Daniel Ratcliffe, 2011-2022. 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 dan200.computercraft.api.lua.*;
+
+import javax.annotation.Nonnull;
+
+/**
+ * A peripheral whose methods are not known at runtime.
+ * <p>
+ * This behaves similarly to {@link IDynamicLuaObject}, though also accepting the current {@link IComputerAccess}.
+ * Generally one may use {@link LuaFunction} instead of implementing this interface.
+ */
+public interface IDynamicPeripheral extends IPeripheral {
+    /**
+     * 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
+     */
+    @Nonnull
+    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()}.
+     * <p>
+     * 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 The arguments for this method.
+     * @return A {@link MethodResult} containing the values to return or the action to perform.
+     * @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.
+     * @see #getMethodNames()
+     */
+    @Nonnull
+    MethodResult callMethod(@Nonnull IComputerAccess computer, @Nonnull ILuaContext context, int method, @Nonnull IArguments arguments) throws LuaException;
+}

projects/core-api/src/main/java/dan200/computercraft/api/peripheral/IPeripheral.java

@@ -0,0 +1,107 @@
+/*
+ * This file is part of the public ComputerCraft API - http://www.computercraft.info
+ * Copyright Daniel Ratcliffe, 2011-2022. 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 dan200.computercraft.api.lua.LuaFunction;
+
+import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
+import java.util.Collections;
+import java.util.Set;
+
+/**
+ * The interface that defines a peripheral.
+ * <p>
+ * In order to expose a peripheral for your block or block entity, you should either attach a capability (Forge) or
+ * use the block lookup API (Fabric). This interface <em>cannot</em> be implemented directly on the block entity.
+ * <p>
+ * Peripherals should provide a series of methods to the user, either using {@link LuaFunction} or by implementing
+ * {@link IDynamicPeripheral}.
+ */
+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()}
+     *
+     * @return A string identifying the type of peripheral.
+     */
+    @Nonnull
+    String getType();
+
+    /**
+     * Return additional types/traits associated with this object.
+     *
+     * @return A collection of additional object traits.
+     * @see PeripheralType#getAdditionalTypes()
+     */
+    @Nonnull
+    default Set<String> getAdditionalTypes() {
+        return Collections.emptySet();
+    }
+
+    /**
+     * Is called when when a computer is attaching to the peripheral.
+     * <p>
+     * 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.
+     * <p>
+     * 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.
+     * <p>
+     * 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.
+     * @see #detach
+     */
+    default void attach(@Nonnull IComputerAccess computer) {
+    }
+
+    /**
+     * Called when a computer is detaching from the peripheral.
+     * <p>
+     * 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.
+     * <p>
+     * This method can be used to keep track of which computers are attached to the peripheral, or to take action when
+     * detachment occurs.
+     * <p>
+     * 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.
+     * @see #attach
+     */
+    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...
+     *
+     * @return The object this peripheral targets
+     */
+    @Nullable
+    default Object getTarget() {
+        return null;
+    }
+
+    /**
+     * Determine whether this peripheral is equivalent to another one.
+     * <p>
+     * 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);
+}

projects/core-api/src/main/java/dan200/computercraft/api/peripheral/IWorkMonitor.java

@@ -0,0 +1,72 @@
+/*
+ * This file is part of the public ComputerCraft API - http://www.computercraft.info
+ * Copyright Daniel Ratcliffe, 2011-2022. 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 java.util.Objects;
+import java.util.concurrent.TimeUnit;
+
+/**
+ * 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.
+ * <p>
+ * 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).
+ * <p>
+ * 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.
+ * <p>
+ * Alternatively, use {@link #runWork(Runnable)} to run and keep track of work.
+ *
+ * @see IComputerAccess#getMainThreadMonitor()
+ */
+public interface IWorkMonitor {
+    /**
+     * If the owning computer is currently allowed to execute work.
+     *
+     * @return If we can execute work right now.
+     */
+    boolean canWork();
+
+    /**
+     * If the owning computer is currently allowed to execute work, and has ample time to do so.
+     * <p>
+     * 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;
+
+        var start = System.nanoTime();
+        try {
+            runnable.run();
+        } finally {
+            trackWork(System.nanoTime() - start, TimeUnit.NANOSECONDS);
+        }
+
+        return true;
+    }
+}

projects/core-api/src/main/java/dan200/computercraft/api/peripheral/NotAttachedException.java

@@ -0,0 +1,25 @@
+/*
+ * This file is part of the public ComputerCraft API - http://www.computercraft.info
+ * Copyright Daniel Ratcliffe, 2011-2022. 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 java.io.Serial;
+
+/**
+ * Thrown when performing operations on {@link IComputerAccess} when the current peripheral is no longer attached to
+ * the computer.
+ */
+public class NotAttachedException extends IllegalStateException {
+    @Serial
+    private static final long serialVersionUID = 1221244785535553536L;
+
+    public NotAttachedException() {
+        super("You are not attached to this computer");
+    }
+
+    public NotAttachedException(String s) {
+        super(s);
+    }
+}

projects/core-api/src/main/java/dan200/computercraft/api/peripheral/PeripheralType.java

@@ -0,0 +1,127 @@
+/*
+ * This file is part of the public ComputerCraft API - http://www.computercraft.info
+ * Copyright Daniel Ratcliffe, 2011-2022. 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 java.util.Collection;
+import java.util.Collections;
+import java.util.Set;
+
+/**
+ * The type of a {@link GenericPeripheral}.
+ * <p>
+ * When determining the final type of the resulting peripheral, the union of all types is taken, with the
+ * lexicographically smallest non-empty name being chosen.
+ */
+public final class PeripheralType {
+    private static final PeripheralType UNTYPED = new PeripheralType(null, Collections.emptySet());
+
+    private final String type;
+    private final Set<String> additionalTypes;
+
+    public PeripheralType(String type, Set<String> additionalTypes) {
+        this.type = type;
+        this.additionalTypes = additionalTypes;
+        for (var item : additionalTypes) {
+            if (item == null) throw new NullPointerException("All additional types must be non-null");
+        }
+    }
+
+    /**
+     * An empty peripheral type, used when a {@link GenericPeripheral} does not have an explicit type.
+     *
+     * @return The empty peripheral type.
+     */
+    public static PeripheralType untyped() {
+        return UNTYPED;
+    }
+
+    /**
+     * Create a new non-empty peripheral type.
+     *
+     * @param type The name of the type.
+     * @return The constructed peripheral type.
+     */
+    public static PeripheralType ofType(@Nonnull String type) {
+        checkTypeName("type cannot be null or empty");
+        return new PeripheralType(type, Collections.emptySet());
+    }
+
+    /**
+     * Create a new non-empty peripheral type with additional traits.
+     *
+     * @param type            The name of the type.
+     * @param additionalTypes Additional types, or "traits" of this peripheral. For instance, {@code "inventory"}.
+     * @return The constructed peripheral type.
+     */
+    public static PeripheralType ofType(@Nonnull String type, Collection<String> additionalTypes) {
+        checkTypeName("type cannot be null or empty");
+        return new PeripheralType(type, getTypes(additionalTypes));
+    }
+
+    /**
+     * Create a new non-empty peripheral type with additional traits.
+     *
+     * @param type            The name of the type.
+     * @param additionalTypes Additional types, or "traits" of this peripheral. For instance, {@code "inventory"}.
+     * @return The constructed peripheral type.
+     */
+    public static PeripheralType ofType(@Nonnull String type, @Nonnull String... additionalTypes) {
+        checkTypeName(type);
+        return new PeripheralType(type, Set.of(additionalTypes));
+    }
+
+    /**
+     * Create a new peripheral type with no primary type but additional traits.
+     *
+     * @param additionalTypes Additional types, or "traits" of this peripheral. For instance, {@code "inventory"}.
+     * @return The constructed peripheral type.
+     */
+    public static PeripheralType ofAdditional(Collection<String> additionalTypes) {
+        return new PeripheralType(null, getTypes(additionalTypes));
+    }
+
+    /**
+     * Create a new peripheral type with no primary type but additional traits.
+     *
+     * @param additionalTypes Additional types, or "traits" of this peripheral. For instance, {@code "inventory"}.
+     * @return The constructed peripheral type.
+     */
+    public static PeripheralType ofAdditional(@Nonnull String... additionalTypes) {
+        return new PeripheralType(null, Set.of(additionalTypes));
+    }
+
+    /**
+     * Get the name of this peripheral type. This may be {@code null}.
+     *
+     * @return The type of this peripheral.
+     */
+    @Nullable
+    public String getPrimaryType() {
+        return type;
+    }
+
+    /**
+     * Get any additional types or "traits" of this peripheral. These effectively act as a standard set of interfaces
+     * a peripheral might have.
+     *
+     * @return All additional types.
+     */
+    public Set<String> getAdditionalTypes() {
+        return additionalTypes;
+    }
+
+    private static void checkTypeName(@Nullable String type) {
+        if (type == null || type.isEmpty()) throw new IllegalArgumentException("type cannot be null or empty");
+    }
+
+    private static Set<String> getTypes(Collection<String> types) {
+        if (types.isEmpty()) return Collections.emptySet();
+        if (types.size() == 1) return Collections.singleton(types.iterator().next());
+        return Set.copyOf(types);
+    }
+}