mirror of
https://github.com/SquidDev-CC/CC-Tweaked
synced 2025-10-23 18:07:39 +00:00
Add abstract classes for our generic peripherals
This commit adds abstract classes to describe the interface for our mod-loader-specific generic peripherals (inventories, fluid storage, item storage). This offers several advantages: - Javadoc to illuaminate conversion no longer needs the Forge project (just core and common). - Ensures we have a consistent interface between Forge and Fabric. Note, this does /not/ implement fluid or energy storage for Fabric. We probably could do fluid without issue, but not something worth doing right now.
This commit is contained in:
Jonathan Coates
@@ -2,13 +2,12 @@
|
||||
//
|
||||
// SPDX-License-Identifier: MPL-2.0
|
||||
|
||||
import cc.tweaked.gradle.annotationProcessorEverywhere
|
||||
import cc.tweaked.gradle.clientClasses
|
||||
import cc.tweaked.gradle.commonClasses
|
||||
import cc.tweaked.gradle.*
|
||||
|
||||
plugins {
|
||||
id("cc-tweaked.vanilla")
|
||||
id("cc-tweaked.gametest")
|
||||
id("cc-tweaked.illuaminate")
|
||||
id("cc-tweaked.publishing")
|
||||
}
|
||||
|
||||
@@ -19,6 +18,10 @@ minecraft {
|
||||
)
|
||||
}
|
||||
|
||||
configurations {
|
||||
register("cctJavadoc")
|
||||
}
|
||||
|
||||
dependencies {
|
||||
// Pull in our other projects. See comments in MinecraftConfigurations on this nastiness.
|
||||
implementation(project(":core"))
|
||||
@@ -41,4 +44,53 @@ dependencies {
|
||||
testModImplementation(libs.bundles.kotlin)
|
||||
|
||||
testFixturesImplementation(testFixtures(project(":core")))
|
||||
|
||||
"cctJavadoc"(libs.cctJavadoc)
|
||||
}
|
||||
|
||||
illuaminate {
|
||||
version.set(libs.versions.illuaminate)
|
||||
}
|
||||
|
||||
val luaJavadoc by tasks.registering(Javadoc::class) {
|
||||
description = "Generates documentation for Java-side Lua functions."
|
||||
group = JavaBasePlugin.DOCUMENTATION_GROUP
|
||||
|
||||
val sourceSets = listOf(sourceSets.main.get(), project(":core").sourceSets.main.get())
|
||||
for (sourceSet in sourceSets) {
|
||||
source(sourceSet.java)
|
||||
classpath += sourceSet.compileClasspath
|
||||
}
|
||||
|
||||
destinationDir = layout.buildDirectory.dir("docs/luaJavadoc").get().asFile
|
||||
|
||||
val options = options as StandardJavadocDocletOptions
|
||||
options.docletpath = configurations["cctJavadoc"].files.toList()
|
||||
options.doclet = "cc.tweaked.javadoc.LuaDoclet"
|
||||
options.addStringOption("project-root", rootProject.file(".").absolutePath)
|
||||
options.noTimestamp(false)
|
||||
|
||||
javadocTool.set(
|
||||
javaToolchains.javadocToolFor {
|
||||
languageVersion.set(cc.tweaked.gradle.CCTweakedPlugin.JAVA_VERSION)
|
||||
},
|
||||
)
|
||||
}
|
||||
|
||||
val lintLua by tasks.registering(IlluaminateExec::class) {
|
||||
group = JavaBasePlugin.VERIFICATION_GROUP
|
||||
description = "Lint Lua (and Lua docs) with illuaminate"
|
||||
|
||||
// Config files
|
||||
inputs.file(rootProject.file("illuaminate.sexp")).withPropertyName("illuaminate.sexp")
|
||||
// Sources
|
||||
inputs.files(rootProject.fileTree("doc")).withPropertyName("docs")
|
||||
inputs.files(project(":core").fileTree("src/main/resources/data/computercraft/lua")).withPropertyName("lua rom")
|
||||
inputs.files(luaJavadoc)
|
||||
|
||||
args = listOf("lint")
|
||||
workingDir = rootProject.projectDir
|
||||
|
||||
doFirst { if (System.getenv("GITHUB_ACTIONS") != null) println("::add-matcher::.github/matchers/illuaminate.json") }
|
||||
doLast { if (System.getenv("GITHUB_ACTIONS") != null) println("::remove-matcher owner=illuaminate::") }
|
||||
}
|
||||
|
||||
@@ -0,0 +1,53 @@
|
||||
// SPDX-FileCopyrightText: 2020 The CC: Tweaked Developers
|
||||
//
|
||||
// SPDX-License-Identifier: MPL-2.0
|
||||
|
||||
package dan200.computercraft.shared.peripheral.generic.methods;
|
||||
|
||||
import dan200.computercraft.api.ComputerCraftAPI;
|
||||
import dan200.computercraft.api.lua.LuaFunction;
|
||||
import dan200.computercraft.api.peripheral.GenericPeripheral;
|
||||
import dan200.computercraft.api.peripheral.PeripheralType;
|
||||
|
||||
/**
|
||||
* Methods for interacting with blocks which store energy.
|
||||
* <p>
|
||||
* This works with energy storage blocks, as well as generators and machines which consume energy.
|
||||
* <p>
|
||||
* > [!NOTE]
|
||||
* > Due to limitations with Forge's energy API, it is not possible to measure throughput (i.e. FE used/generated per
|
||||
* > tick).
|
||||
*
|
||||
* @param <T> The type for energy storage.
|
||||
* @cc.module energy_storage
|
||||
* @cc.since 1.94.0
|
||||
*/
|
||||
public abstract class AbstractEnergyMethods<T> implements GenericPeripheral {
|
||||
@Override
|
||||
public final PeripheralType getType() {
|
||||
return PeripheralType.ofAdditional("energy_storage");
|
||||
}
|
||||
|
||||
@Override
|
||||
public final String id() {
|
||||
return ComputerCraftAPI.MOD_ID + ":energy";
|
||||
}
|
||||
|
||||
/**
|
||||
* Get the energy of this block.
|
||||
*
|
||||
* @param energy The current energy storage.
|
||||
* @return The energy stored in this block, in FE.
|
||||
*/
|
||||
@LuaFunction(mainThread = true)
|
||||
public abstract int getEnergy(T energy);
|
||||
|
||||
/**
|
||||
* Get the maximum amount of energy this block can store.
|
||||
*
|
||||
* @param energy The current energy storage.
|
||||
* @return The energy capacity of this block.
|
||||
*/
|
||||
@LuaFunction(mainThread = true)
|
||||
public abstract int getEnergyCapacity(T energy);
|
||||
}
|
||||
@@ -0,0 +1,92 @@
|
||||
// SPDX-FileCopyrightText: 2020 The CC: Tweaked Developers
|
||||
//
|
||||
// SPDX-License-Identifier: MPL-2.0
|
||||
|
||||
package dan200.computercraft.shared.peripheral.generic.methods;
|
||||
|
||||
import dan200.computercraft.api.ComputerCraftAPI;
|
||||
import dan200.computercraft.api.lua.LuaException;
|
||||
import dan200.computercraft.api.lua.LuaFunction;
|
||||
import dan200.computercraft.api.peripheral.GenericPeripheral;
|
||||
import dan200.computercraft.api.peripheral.IComputerAccess;
|
||||
import dan200.computercraft.api.peripheral.PeripheralType;
|
||||
|
||||
import java.util.Map;
|
||||
import java.util.Optional;
|
||||
|
||||
/**
|
||||
* Methods for interacting with tanks and other fluid storage blocks.
|
||||
*
|
||||
* @param <T> The type for fluid inventories.
|
||||
* @cc.module fluid_storage
|
||||
* @cc.since 1.94.0
|
||||
*/
|
||||
public abstract class AbstractFluidMethods<T> implements GenericPeripheral {
|
||||
@Override
|
||||
public final PeripheralType getType() {
|
||||
return PeripheralType.ofAdditional("fluid_storage");
|
||||
}
|
||||
|
||||
@Override
|
||||
public final String id() {
|
||||
return ComputerCraftAPI.MOD_ID + ":fluid";
|
||||
}
|
||||
|
||||
/**
|
||||
* Get all "tanks" in this fluid storage.
|
||||
* <p>
|
||||
* Each tank either contains some amount of fluid or is empty. Tanks with fluids inside will return some basic
|
||||
* information about the fluid, including its name and amount.
|
||||
* <p>
|
||||
* The returned table is sparse, and so empty tanks will be `nil` - it is recommended to loop over using [`pairs`]
|
||||
* rather than [`ipairs`].
|
||||
*
|
||||
* @param fluids The current fluid handler.
|
||||
* @return All tanks.
|
||||
* @cc.treturn { (table|nil)... } All tanks in this fluid storage.
|
||||
*/
|
||||
@LuaFunction(mainThread = true)
|
||||
public abstract Map<Integer, Map<String, ?>> tanks(T fluids);
|
||||
|
||||
/**
|
||||
* Move a fluid from one fluid container to another connected one.
|
||||
* <p>
|
||||
* This allows you to pull fluid in the current fluid container to another container <em>on the same wired
|
||||
* network</em>. Both containers must attached to wired modems which are connected via a cable.
|
||||
*
|
||||
* @param from Container to move fluid from.
|
||||
* @param computer The current computer.
|
||||
* @param toName The name of the peripheral/container to push to. This is the string given to [`peripheral.wrap`],
|
||||
* and displayed by the wired modem.
|
||||
* @param limit The maximum amount of fluid to move.
|
||||
* @param fluidName The fluid to move. If not given, an arbitrary fluid will be chosen.
|
||||
* @return The amount of moved fluid.
|
||||
* @throws LuaException If the peripheral to transfer to doesn't exist or isn't an fluid container.
|
||||
* @cc.see peripheral.getName Allows you to get the name of a [wrapped][`peripheral.wrap`] peripheral.
|
||||
*/
|
||||
@LuaFunction(mainThread = true)
|
||||
public abstract int pushFluid(
|
||||
T from, IComputerAccess computer, String toName, Optional<Integer> limit, Optional<String> fluidName
|
||||
) throws LuaException;
|
||||
|
||||
/**
|
||||
* Move a fluid from a connected fluid container into this oneone.
|
||||
* <p>
|
||||
* This allows you to pull fluid in the current fluid container from another container <em>on the same wired
|
||||
* network</em>. Both containers must attached to wired modems which are connected via a cable.
|
||||
*
|
||||
* @param to Container to move fluid to.
|
||||
* @param computer The current computer.
|
||||
* @param fromName The name of the peripheral/container to push to. This is the string given to [`peripheral.wrap`],
|
||||
* and displayed by the wired modem.
|
||||
* @param limit The maximum amount of fluid to move.
|
||||
* @param fluidName The fluid to move. If not given, an arbitrary fluid will be chosen.
|
||||
* @return The amount of moved fluid.
|
||||
* @throws LuaException If the peripheral to transfer to doesn't exist or isn't an fluid container.
|
||||
* @cc.see peripheral.getName Allows you to get the name of a [wrapped][`peripheral.wrap`] peripheral.
|
||||
*/
|
||||
@LuaFunction(mainThread = true)
|
||||
public abstract int pullFluid(
|
||||
T to, IComputerAccess computer, String fromName, Optional<Integer> limit, Optional<String> fluidName
|
||||
) throws LuaException;
|
||||
}
|
||||
@@ -0,0 +1,197 @@
|
||||
// SPDX-FileCopyrightText: 2020 The CC: Tweaked Developers
|
||||
//
|
||||
// SPDX-License-Identifier: LicenseRef-CCPL
|
||||
|
||||
package dan200.computercraft.shared.peripheral.generic.methods;
|
||||
|
||||
import dan200.computercraft.api.ComputerCraftAPI;
|
||||
import dan200.computercraft.api.lua.ILuaContext;
|
||||
import dan200.computercraft.api.lua.LuaException;
|
||||
import dan200.computercraft.api.lua.LuaFunction;
|
||||
import dan200.computercraft.api.peripheral.GenericPeripheral;
|
||||
import dan200.computercraft.api.peripheral.IComputerAccess;
|
||||
import dan200.computercraft.api.peripheral.PeripheralType;
|
||||
|
||||
import javax.annotation.Nullable;
|
||||
import java.util.Map;
|
||||
import java.util.Optional;
|
||||
|
||||
/**
|
||||
* Methods for interacting with inventories.
|
||||
*
|
||||
* @param <T> The type for inventories.
|
||||
* @cc.module inventory
|
||||
* @cc.since 1.94.0
|
||||
*/
|
||||
public abstract class AbstractInventoryMethods<T> implements GenericPeripheral {
|
||||
@Override
|
||||
public final PeripheralType getType() {
|
||||
return PeripheralType.ofAdditional("inventory");
|
||||
}
|
||||
|
||||
@Override
|
||||
public final String id() {
|
||||
return ComputerCraftAPI.MOD_ID + ":inventory";
|
||||
}
|
||||
|
||||
/**
|
||||
* Get the size of this inventory.
|
||||
*
|
||||
* @param inventory The current inventory.
|
||||
* @return The number of slots in this inventory.
|
||||
*/
|
||||
@LuaFunction(mainThread = true)
|
||||
public abstract int size(T inventory);
|
||||
|
||||
/**
|
||||
* List all items in this inventory. This returns a table, with an entry for each slot.
|
||||
* <p>
|
||||
* Each item in the inventory is represented by a table containing some basic information, much like
|
||||
* {@link dan200.computercraft.shared.turtle.apis.TurtleAPI#getItemDetail(ILuaContext, Optional, Optional)}
|
||||
* includes. More information can be fetched with {@link #getItemDetail}. The table contains the item `name`, the
|
||||
* `count` and an a (potentially nil) hash of the item's `nbt.` This NBT data doesn't contain anything useful, but
|
||||
* allows you to distinguish identical items.
|
||||
* <p>
|
||||
* The returned table is sparse, and so empty slots will be `nil` - it is recommended to loop over using [`pairs`]
|
||||
* rather than [`ipairs`].
|
||||
*
|
||||
* @param inventory The current inventory.
|
||||
* @return All items in this inventory.
|
||||
* @cc.treturn { (table|nil)... } All items in this inventory.
|
||||
* @cc.usage Find an adjacent chest and print all items in it.
|
||||
*
|
||||
* <pre>{@code
|
||||
* local chest = peripheral.find("minecraft:chest")
|
||||
* for slot, item in pairs(chest.list()) do
|
||||
* print(("%d x %s in slot %d"):format(item.count, item.name, slot))
|
||||
* end
|
||||
* }</pre>
|
||||
*/
|
||||
@LuaFunction(mainThread = true)
|
||||
public abstract Map<Integer, Map<String, ?>> list(T inventory);
|
||||
|
||||
/**
|
||||
* Get detailed information about an item.
|
||||
* <p>
|
||||
* The returned information contains the same information as each item in
|
||||
* {@link #list}, as well as additional details like the display name
|
||||
* (`displayName`), and item and item durability (`damage`, `maxDamage`, `durability`).
|
||||
* <p>
|
||||
* Some items include more information (such as enchantments) - it is
|
||||
* recommended to print it out using [`textutils.serialize`] or in the Lua
|
||||
* REPL, to explore what is available.
|
||||
* <p>
|
||||
* > [Deprecated fields][!INFO]
|
||||
* > Older versions of CC: Tweaked exposed an {@code itemGroups} field, listing the
|
||||
* > creative tabs an item was available under. This information is no longer available on
|
||||
* > more recent versions of the game, and so this field will always be empty. Do not use this
|
||||
* > field in new code!
|
||||
*
|
||||
* @param inventory The current inventory.
|
||||
* @param slot The slot to get information about.
|
||||
* @return Information about the item in this slot, or {@code nil} if not present.
|
||||
* @throws LuaException If the slot is out of range.
|
||||
* @cc.treturn table Information about the item in this slot, or {@code nil} if not present.
|
||||
* @cc.usage Print some information about the first in a chest.
|
||||
*
|
||||
* <pre>{@code
|
||||
* local chest = peripheral.find("minecraft:chest")
|
||||
* local item = chest.getItemDetail(1)
|
||||
* if not item then print("No item") return end
|
||||
*
|
||||
* print(("%s (%s)"):format(item.displayName, item.name))
|
||||
* print(("Count: %d/%d"):format(item.count, item.maxCount))
|
||||
*
|
||||
* if item.damage then
|
||||
* print(("Damage: %d/%d"):format(item.damage, item.maxDamage))
|
||||
* end
|
||||
* }</pre>
|
||||
*/
|
||||
@Nullable
|
||||
@LuaFunction(mainThread = true)
|
||||
public abstract Map<String, ?> getItemDetail(T inventory, int slot) throws LuaException;
|
||||
|
||||
/**
|
||||
* Get the maximum number of items which can be stored in this slot.
|
||||
* <p>
|
||||
* Typically this will be limited to 64 items. However, some inventories (such as barrels or caches) can store
|
||||
* hundreds or thousands of items in one slot.
|
||||
*
|
||||
* @param inventory Inventory to probe.
|
||||
* @param slot The slot
|
||||
* @return The maximum number of items in this slot.
|
||||
* @throws LuaException If the slot is out of range.
|
||||
* @cc.usage Count the maximum number of items an adjacent chest can hold.
|
||||
* <pre>{@code
|
||||
* local chest = peripheral.find("minecraft:chest")
|
||||
* local total = 0
|
||||
* for i = 1, chest.size() do
|
||||
* total = total + chest.getItemLimit(i)
|
||||
* end
|
||||
* print(total)
|
||||
* }</pre>
|
||||
* @cc.since 1.96.0
|
||||
*/
|
||||
@LuaFunction(mainThread = true)
|
||||
public abstract long getItemLimit(T inventory, int slot) throws LuaException;
|
||||
|
||||
/**
|
||||
* Push items from one inventory to another connected one.
|
||||
* <p>
|
||||
* This allows you to push an item in an inventory to another inventory <em>on the same wired network</em>. Both
|
||||
* inventories must attached to wired modems which are connected via a cable.
|
||||
*
|
||||
* @param from Inventory to move items from.
|
||||
* @param computer The current computer.
|
||||
* @param toName The name of the peripheral/inventory to push to. This is the string given to [`peripheral.wrap`],
|
||||
* and displayed by the wired modem.
|
||||
* @param fromSlot The slot in the current inventory to move items to.
|
||||
* @param limit The maximum number of items to move. Defaults to the current stack limit.
|
||||
* @param toSlot The slot in the target inventory to move to. If not given, the item will be inserted into any slot.
|
||||
* @return The number of transferred items.
|
||||
* @throws LuaException If the peripheral to transfer to doesn't exist or isn't an inventory.
|
||||
* @throws LuaException If either source or destination slot is out of range.
|
||||
* @cc.see peripheral.getName Allows you to get the name of a [wrapped][`peripheral.wrap`] peripheral.
|
||||
* @cc.usage Wrap two chests, and push an item from one to another.
|
||||
* <pre>{@code
|
||||
* local chest_a = peripheral.wrap("minecraft:chest_0")
|
||||
* local chest_b = peripheral.wrap("minecraft:chest_1")
|
||||
*
|
||||
* chest_a.pushItems(peripheral.getName(chest_b), 1)
|
||||
* }</pre>
|
||||
*/
|
||||
@LuaFunction(mainThread = true)
|
||||
public abstract int pushItems(
|
||||
T from, IComputerAccess computer, String toName, int fromSlot, Optional<Integer> limit, Optional<Integer> toSlot
|
||||
) throws LuaException;
|
||||
|
||||
/**
|
||||
* Pull items from a connected inventory into this one.
|
||||
* <p>
|
||||
* This allows you to transfer items between inventories <em>on the same wired network</em>. Both this and the source
|
||||
* inventory must attached to wired modems which are connected via a cable.
|
||||
*
|
||||
* @param to Inventory to move items to.
|
||||
* @param computer The current computer.
|
||||
* @param fromName The name of the peripheral/inventory to pull from. This is the string given to [`peripheral.wrap`],
|
||||
* and displayed by the wired modem.
|
||||
* @param fromSlot The slot in the source inventory to move items from.
|
||||
* @param limit The maximum number of items to move. Defaults to the current stack limit.
|
||||
* @param toSlot The slot in current inventory to move to. If not given, the item will be inserted into any slot.
|
||||
* @return The number of transferred items.
|
||||
* @throws LuaException If the peripheral to transfer to doesn't exist or isn't an inventory.
|
||||
* @throws LuaException If either source or destination slot is out of range.
|
||||
* @cc.see peripheral.getName Allows you to get the name of a [wrapped][`peripheral.wrap`] peripheral.
|
||||
* @cc.usage Wrap two chests, and push an item from one to another.
|
||||
* <pre>{@code
|
||||
* local chest_a = peripheral.wrap("minecraft:chest_0")
|
||||
* local chest_b = peripheral.wrap("minecraft:chest_1")
|
||||
*
|
||||
* chest_a.pullItems(peripheral.getName(chest_b), 1)
|
||||
* }</pre>
|
||||
*/
|
||||
@LuaFunction(mainThread = true)
|
||||
public abstract int pullItems(
|
||||
T to, IComputerAccess computer, String fromName, int fromSlot, Optional<Integer> limit, Optional<Integer> toSlot
|
||||
) throws LuaException;
|
||||
}
|
||||
@@ -11,6 +11,7 @@ import dan200.computercraft.api.turtle.TurtleCommandResult;
|
||||
import dan200.computercraft.api.turtle.TurtleSide;
|
||||
import dan200.computercraft.core.apis.IAPIEnvironment;
|
||||
import dan200.computercraft.core.metrics.Metrics;
|
||||
import dan200.computercraft.shared.peripheral.generic.methods.AbstractInventoryMethods;
|
||||
import dan200.computercraft.shared.turtle.core.*;
|
||||
|
||||
import java.util.Optional;
|
||||
@@ -749,7 +750,7 @@ public class TurtleAPI implements ILuaAPI {
|
||||
* -- count = 13,
|
||||
* -- }
|
||||
* }</pre>
|
||||
* @see dan200.computercraft.shared.peripheral.generic.methods.InventoryMethods#getItemDetail Describes the information returned by a detailed query.
|
||||
* @see AbstractInventoryMethods#getItemDetail Describes the information returned by a detailed query.
|
||||
*/
|
||||
@LuaFunction
|
||||
public final MethodResult getItemDetail(ILuaContext context, Optional<Integer> slot, Optional<Boolean> detailed) throws LuaException {
|
||||
|
||||
Reference in New Issue
Block a user