diff --git a/src/api/java/li/cil/oc/api/API.java b/src/api/java/li/cil/oc/api/API.java new file mode 100755 index 000000000..051bcb5d8 --- /dev/null +++ b/src/api/java/li/cil/oc/api/API.java @@ -0,0 +1,25 @@ +package li.cil.oc.api; + +import com.typesafe.config.Config; +import li.cil.oc.api.detail.*; + +/** + * Central reference for the API. + *

+ * Don't use this class directly, prefer using the other classes in this + * package instead. This class is initialized by OpenComputers in the + * pre-init phase, so it should not be used before the init phase. + */ +public class API { + public static final String ID_OWNER = "OpenComputers|Core"; + public static final String VERSION = "5.5.3"; + + public static DriverAPI driver = null; + public static FileSystemAPI fileSystem = null; + public static ItemAPI items = null; + public static MachineAPI machine = null; + public static ManualAPI manual = null; + public static NetworkAPI network = null; + + public static Config config = null; +} diff --git a/src/api/java/li/cil/oc/api/CreativeTab.java b/src/api/java/li/cil/oc/api/CreativeTab.java new file mode 100755 index 000000000..fcc395666 --- /dev/null +++ b/src/api/java/li/cil/oc/api/CreativeTab.java @@ -0,0 +1,20 @@ +package li.cil.oc.api; + +import net.minecraft.creativetab.CreativeTabs; + +/** + * Allows access to the creative tab used by OpenComputers. + */ +public final class CreativeTab { + /** + * The creative tab used by OpenComputers. + *

+ * Changed to the actual tab if OC is present. Preferably you do + * not try to access this anyway when OpenComputers isn't + * present (don't ship the API in your mod), so don't rely on this! + */ + public static CreativeTabs instance = CreativeTabs.tabRedstone; + + private CreativeTab() { + } +} diff --git a/src/api/java/li/cil/oc/api/Driver.java b/src/api/java/li/cil/oc/api/Driver.java new file mode 100755 index 000000000..eaa457729 --- /dev/null +++ b/src/api/java/li/cil/oc/api/Driver.java @@ -0,0 +1,174 @@ +package li.cil.oc.api; + +import li.cil.oc.api.driver.Block; +import li.cil.oc.api.driver.Converter; +import li.cil.oc.api.driver.EnvironmentHost; +import li.cil.oc.api.driver.Item; +import net.minecraft.item.ItemStack; +import net.minecraft.world.World; + +import java.util.Collection; + +/** + * This API allows registering new drivers with the mod. + *

+ * Drivers are used to make items and third-party blocks available in the mod's + * component network, and optionally to user programs. If you implement a new + * block that should interact with the mod's component network it is enough to + * have it implement {@link li.cil.oc.api.network.Environment} - no driver is + * needed in that case. + *

+ * Note that these methods should not be called in the pre-init phase, + * since the {@link API#driver} may not have been initialized + * at that time. Only start calling these methods in the init phase or later. + * + * @see Network + * @see Block + * @see Item + */ +public final class Driver { + /** + * Registers a new block driver. + *

+ * Whenever the neighboring blocks of an Adapter block change, it checks if + * there exists a driver for the changed block, and if it is configured to + * interface that block type connects it to the component network. + *

+ * This must be called in the init phase, not the pre- or post-init + * phases. + * + * @param driver the driver to register. + */ + public static void add(final Block driver) { + if (API.driver != null) + API.driver.add(driver); + } + + /** + * Registers a new item driver. + *

+ * Item components can inserted into a computers component slots. They have + * to specify their type, to determine into which slots they can fit. + *

+ * This must be called in the init phase, not the pre- or post-init + * phases. + * + * @param driver the driver to register. + */ + public static void add(final Item driver) { + if (API.driver != null) + API.driver.add(driver); + } + + /** + * Registers a new type converter. + *

+ * Type converters are used to automatically convert values returned from + * callbacks to a "simple" format that can be pushed to any architecture. + *

+ * This must be called in the init phase, not the pre- or post-init + * phases. + * + * @param converter the converter to register. + */ + public static void add(final Converter converter) { + if (API.driver != null) + API.driver.add(converter); + } + + /** + * Looks up a driver for the block at the specified position in the + * specified world. + *

+ * Note that several drivers for a single block can exist. Because of this + * block drivers are always encapsulated in a 'compound' driver, which is + * what will be returned here. In other words, you should will not + * get actual instances of drivers registered via {@link #add(Block)}. + * + * @param world the world containing the block. + * @param x the X coordinate of the block. + * @param y the Y coordinate of the block. + * @param z the Z coordinate of the block. + * @return a driver for the block, or null if there is none. + */ + public static Block driverFor(World world, int x, int y, int z) { + if (API.driver != null) + return API.driver.driverFor(world, x, y, z); + return null; + } + + /** + * Looks up a driver for the specified item stack. + *

+ * Note that unlike for blocks, there can always only be one item driver + * per item. If there are multiple ones, the first one that was registered + * will be used. + * + * @param stack the item stack to get a driver for. + * @param host the type that will host the environment created by returned driver. + * @return a driver for the item, or null if there is none. + */ + public static Item driverFor(ItemStack stack, Class host) { + if (API.driver != null) + return API.driver.driverFor(stack, host); + return null; + } + + /** + * Looks up a driver for the specified item stack. + *

+ * Note that unlike for blocks, there can always only be one item driver + * per item. If there are multiple ones, the first one that was registered + * will be used. + *

+ * This is a context-agnostic variant used mostly for "house-keeping" + * stuff, such as querying slot types and tier. + * + * @param stack the item stack to get a driver for. + * @return a driver for the item, or null if there is none. + */ + public static Item driverFor(ItemStack stack) { + if (API.driver != null) + return API.driver.driverFor(stack); + return null; + } + + /** + * Get a list of all registered block drivers. + *

+ * This is intended to allow checking for particular drivers using more + * customized logic, and in particular to check for drivers with the + * {@link li.cil.oc.api.driver.EnvironmentAware} interface. + *

+ * The returned collection is read-only. + * + * @return the list of all registered block drivers. + */ + public static Collection blockDrivers() { + if (API.driver != null) + return API.driver.blockDrivers(); + return null; + } + + /** + * Get a list of all registered item drivers. + *

+ * This is intended to allow checking for particular drivers using more + * customized logic, and in particular to check for drivers with the + * {@link li.cil.oc.api.driver.EnvironmentAware} interface. + *

+ * The returned collection is read-only. + * + * @return the list of all registered item drivers. + */ + public static Collection itemDrivers() { + if (API.driver != null) + return API.driver.itemDrivers(); + return null; + } + + // ----------------------------------------------------------------------- // + + private Driver() { + } +} \ No newline at end of file diff --git a/src/api/java/li/cil/oc/api/FileSystem.java b/src/api/java/li/cil/oc/api/FileSystem.java new file mode 100755 index 000000000..c1be1020d --- /dev/null +++ b/src/api/java/li/cil/oc/api/FileSystem.java @@ -0,0 +1,297 @@ +package li.cil.oc.api; + +import li.cil.oc.api.driver.EnvironmentHost; +import li.cil.oc.api.fs.Label; +import li.cil.oc.api.network.ManagedEnvironment; + +/** + * This class provides factory methods for creating file systems that are + * compatible with the built-in file system driver. + *

+ * File systems created this way and wrapped in a managed environment via + * {@link #asManagedEnvironment} or its overloads will appear as + * filesystem components in the component network. Note that the + * component's visibility is set to Neighbors per default. If you wish + * to change the file system's visibility (e.g. like the disk drive does) you + * must cast the environment's node to {@link li.cil.oc.api.network.Component} + * and set the visibility to the desired value. + *

+ * Note that these methods should not be called in the pre-init phase, + * since the {@link API#fileSystem} may not have been initialized + * at that time. Only start calling these methods in the init phase or later. + */ +public final class FileSystem { + /** + * Creates a new file system based on the location of a class. + *

+ * This can be used to wrap a folder in the assets folder of your mod's JAR. + * The actual path is built like this: + *

"/assets/" + domain + "/" + root
+ *

+ * If the class is located in a JAR file, this will create a read-only file + * system based on that JAR file. If the class file is located in the native + * file system, this will create a read-only file system first trying from + * the actual location of the class file, and failing that by searching the + * class path (i.e. it'll look for a path constructed as described above). + *

+ * If the specified path cannot be located, the creation fails and this + * returns null. + * + * @param clazz the class whose containing JAR to wrap. + * @param domain the domain, usually your mod's ID. + * @param root an optional subdirectory. + * @return a file system wrapping the specified folder. + */ + public static li.cil.oc.api.fs.FileSystem fromClass(final Class clazz, final String domain, final String root) { + if (API.fileSystem != null) + return API.fileSystem.fromClass(clazz, domain, root); + return null; + } + + /** + * Creates a new writable file system in the save folder. + *

+ * This will create a folder, if necessary, and create a writable virtual + * file system based in that folder. The actual path is based in a sub- + * folder of the save folder. The actual path is built like this: + *

"saves/" + WORLD_NAME + "/opencomputers/" + root
+ * The first part may differ, in particular for servers. + *

+ * Usually the name will be the address of the node used to represent the + * file system. + *

+ * Note that by default file systems are "buffered", meaning that any + * changes made to them are only saved to disk when the world is saved. This + * ensured that the file system contents do not go "out of sync" when the + * game crashes, but introduces additional memory overhead, since all files + * in the file system have to be kept in memory. + * + * @param root the name of the file system. + * @param capacity the amount of space in bytes to allow being used. + * @param buffered whether data should only be written to disk when saving. + * @return a file system wrapping the specified folder. + */ + public static li.cil.oc.api.fs.FileSystem fromSaveDirectory(final String root, final long capacity, final boolean buffered) { + if (API.fileSystem != null) + return API.fileSystem.fromSaveDirectory(root, capacity, buffered); + return null; + } + + /** + * Same as {@link #fromSaveDirectory(String, long, boolean)} with the + * buffered parameter being true, i.e. will always create a + * buffered file system. + * + * @param root the name of the file system. + * @param capacity the amount of space in bytes to allow being used. + * @return a file system wrapping the specified folder. + */ + public static li.cil.oc.api.fs.FileSystem fromSaveDirectory(final String root, final long capacity) { + return fromSaveDirectory(root, capacity, true); + } + + /** + * Creates a new writable file system that resides in memory. + *

+ * Any contents created and written on this file system will be lost when + * the node is removed from the network. + *

+ * This is used for computers' /tmp mount, for example. + * + * @param capacity the capacity of the file system. + * @return a file system residing in memory. + */ + public static li.cil.oc.api.fs.FileSystem fromMemory(final long capacity) { + if (API.fileSystem != null) + return API.fileSystem.fromMemory(capacity); + return null; + } + + /** + * Creates a new file system based on a ComputerCraft mount. + *

+ * This supports read-only and writable mounts from either CC 1.5x or + * CC 1.6x. The argument is kept untyped to avoid having the OC API + * depend on the CC API. + *

+ * If the passed type is unsupported, this will throw an exception. + * + * @param mount the mount to wrap with a file system. + * @return a file system wrapping the specified mount. + */ + public static li.cil.oc.api.fs.FileSystem fromComputerCraft(final Object mount) { + if (API.fileSystem != null) + return API.fileSystem.fromComputerCraft(mount); + return null; + } + + /** + * Wrap a file system retrieved via one of the from??? methods to + * make it read-only. + * + * @param fileSystem the file system to wrap. + * @return the specified file system wrapped to be read-only. + */ + public static li.cil.oc.api.fs.FileSystem asReadOnly(final li.cil.oc.api.fs.FileSystem fileSystem) { + if (API.fileSystem != null) + return API.fileSystem.asReadOnly(fileSystem); + return null; + } + + /** + * Creates a network node that makes the specified file system available via + * the common file system driver. + *

+ * This can be useful for providing some data if you don't wish to implement + * your own driver. Which will probably be most of the time. If you need + * more control over the node, implement your own, and connect this one to + * it. In that case you will have to forward any disk driver messages to the + * node, though. + *

+ * The container parameter is used to give the file system some physical + * relation to the world, for example this is used by hard drives to send + * the disk event notifications to the client that are used to play disk + * access sounds. + *

+ * The container may be null, if no such context can be provided. + *

+ * The access sound is the name of the sound effect to play when the file + * system is accessed, for example by listing a directory or reading from + * a file. It may be null to create a silent file system. + *

+ * The speed multiplier controls how fast read and write operations on the + * file system are. It must be a value in [1,6], and controls the access + * speed, with the default being one. + * For reference, floppies are using the default, hard drives scale with + * their tiers, i.e. a tier one hard drive uses speed two, tier three uses + * speed four. + * + * @param fileSystem the file system to wrap. + * @param label the label of the file system. + * @param host the tile entity containing the file system. + * @param accessSound the name of the sound effect to play when the file + * system is accessed. This has to be the fully + * qualified resource name, e.g. + * opencomputers:floppy_access. + * @param speed the speed multiplier for this file system. + * @return the network node wrapping the file system. + */ + public static ManagedEnvironment asManagedEnvironment(final li.cil.oc.api.fs.FileSystem fileSystem, final Label label, final EnvironmentHost host, final String accessSound, int speed) { + if (API.fileSystem != null) + return API.fileSystem.asManagedEnvironment(fileSystem, label, host, accessSound, speed); + return null; + } + + /** + * Creates a network node that makes the specified file system available via + * the common file system driver. + *

+ * Creates a file system with the a read-only label and the specified + * access sound and file system speed. + * + * @param fileSystem the file system to wrap. + * @param label the label of the file system. + * @param host the tile entity containing the file system. + * @param accessSound the name of the sound effect to play when the file + * system is accessed. This has to be the fully + * qualified resource name, e.g. + * opencomputers:floppy_access. + * @param speed the speed multiplier for this file system. + * @return the network node wrapping the file system. + */ + public static ManagedEnvironment asManagedEnvironment(final li.cil.oc.api.fs.FileSystem fileSystem, final String label, final EnvironmentHost host, final String accessSound, int speed) { + if (API.fileSystem != null) + return API.fileSystem.asManagedEnvironment(fileSystem, label, host, accessSound, speed); + return null; + } + + /** + * Creates a network node that makes the specified file system available via + * the common file system driver. + *

+ * Creates a file system with the specified label and the specified access + * sound, using the default file system speed. + * + * @param fileSystem the file system to wrap. + * @param label the label of the file system. + * @param host the tile entity containing the file system. + * @param accessSound the name of the sound effect to play when the file + * system is accessed. This has to be the fully + * qualified resource name, e.g. + * opencomputers:floppy_access. + * @return the network node wrapping the file system. + */ + public static ManagedEnvironment asManagedEnvironment(final li.cil.oc.api.fs.FileSystem fileSystem, final Label label, final EnvironmentHost host, final String accessSound) { + return asManagedEnvironment(fileSystem, label, host, accessSound, 1); + } + + /** + * Creates a network node that makes the specified file system available via + * the common file system driver. + *

+ * Creates a file system with a read-only label and the specified access + * sound, using the default file system speed. + * + * @param fileSystem the file system to wrap. + * @param label the read-only label of the file system. + * @param host the tile entity containing the file system. + * @param accessSound the name of the sound effect to play when the file + * system is accessed. This has to be the fully + * qualified resource name, e.g. + * opencomputers:floppy_access. + * @return the network node wrapping the file system. + */ + public static ManagedEnvironment asManagedEnvironment(final li.cil.oc.api.fs.FileSystem fileSystem, final String label, final EnvironmentHost host, final String accessSound) { + return asManagedEnvironment(fileSystem, label, host, accessSound, 1); + } + + /** + * Creates a network node that makes the specified file system available via + * the common file system driver. + *

+ * Creates a file system with the specified label, without an environment + * and access sound, using the default file system speed. + * + * @param fileSystem the file system to wrap. + * @param label the label of the file system. + * @return the network node wrapping the file system. + */ + public static ManagedEnvironment asManagedEnvironment(final li.cil.oc.api.fs.FileSystem fileSystem, final Label label) { + return asManagedEnvironment(fileSystem, label, null, null, 1); + } + + /** + * Creates a network node that makes the specified file system available via + * the common file system driver. + *

+ * Creates a file system with a read-only label, without an environment and + * access sound, using the default file system speed. + * + * @param fileSystem the file system to wrap. + * @param label the read-only label of the file system. + * @return the network node wrapping the file system. + */ + public static ManagedEnvironment asManagedEnvironment(final li.cil.oc.api.fs.FileSystem fileSystem, final String label) { + return asManagedEnvironment(fileSystem, label, null, null, 1); + } + + /** + * Creates a network node that makes the specified file system available via + * the common file system driver. + *

+ * Creates an unlabeled file system (i.e. the label can neither be read nor + * written), without an environment and access sound, using the default + * file system speed. + * + * @param fileSystem the file system to wrap. + * @return the network node wrapping the file system. + */ + public static ManagedEnvironment asManagedEnvironment(final li.cil.oc.api.fs.FileSystem fileSystem) { + return asManagedEnvironment(fileSystem, (Label) null, null, null, 1); + } + + // ----------------------------------------------------------------------- // + + private FileSystem() { + } +} \ No newline at end of file diff --git a/src/api/java/li/cil/oc/api/IMC.java b/src/api/java/li/cil/oc/api/IMC.java new file mode 100755 index 000000000..39beb10e3 --- /dev/null +++ b/src/api/java/li/cil/oc/api/IMC.java @@ -0,0 +1,339 @@ +package li.cil.oc.api; + +import cpw.mods.fml.common.event.FMLInterModComms; +import net.minecraft.item.ItemStack; +import net.minecraft.nbt.NBTTagCompound; +import net.minecraft.nbt.NBTTagList; +import org.apache.commons.lang3.tuple.Pair; + +/** + * This is a pure utility class to more comfortably register things that can + * only be registered using IMC. + *

+ * Use this if you have some kind of abstraction layer in place anyway, and can + * safely use the API without class not found exceptions and such, and don't + * want to put together the IMC messages manually. + *

+ * This also servers to document of all IMC messages OpenComputers handles. + *

+ * Feel free to copy these functions into your own code, just please don't + * copy this class while keeping the package name, to avoid conflicts if this + * class gets updated. + */ +public final class IMC { + /** + * Register a callback that is used as a filter for assembler templates. + * Any templates that require a base item that is rejected by any + * registered filter will be disabled. For example, if a filter rejects the + * computer case item stacks, robots can not be assembled. + *

+ * Signature of callbacks must be: + *

+     * boolean callback(ItemStack stack)
+     * 
+ *

+ * Callbacks must be declared as packagePath.className.methodName. + * For example: com.example.Integration.callbackMethod. + * + * @param callback the callback to register as a filtering method. + */ + public static void registerAssemblerFilter(String callback) { + FMLInterModComms.sendMessage(MOD_ID, "registerAssemblerFilter", callback); + } + + /** + * Register a new template for the assembler. + *

+ * Signature of callbacks must be: + *

+     * boolean select(ItemStack stack)
+     * Object[] validate(IInventory inventory)
+     * Object[] assemble(IInventory inventory)
+     * 
+ * Values in the array returned by validate must be one of the following: + *
+     * // Valid or not.
+     * new Object[]{Boolean}
+     * // Valid or not, text for progess bar.
+     * new Object[]{Boolean, IChatComponent}
+     * // Valid or not, text for progess bar, warnings for start button tooltip (one per line).
+     * new Object[]{Boolean, IChatComponent, IChatComponent[]}
+     * 
+ * Values in the array returned by assemble must be one of the following: + *
+     * // The assembled device.
+     * new Object[]{ItemStack}
+     * // The assembled device and energy cost (which also determines assembly duration).
+     * new Object[]{ItemStack, Number}
+     * 
+ *

+ * Callbacks must be declared as packagePath.className.methodName. + * For example: com.example.Integration.callbackMethod. + * + * @param name the name of the device created using the + * template. Optional, only used in logging. + * @param select callback used to determine if the template + * applies to a base item. For example, the robot + * template returns true from this if the passed + * item stack is a computer case. + * @param validate callback used to determine if the template + * configuration is valid. Once a template is + * valid assembly can be started, but not before. + * @param assemble callback used to apply a template and create a + * device from it. + * @param host the class of the device being assembled, i.e. + * the host class for the components being + * installed in the device. Used for filtering + * eligible components. See {@link #blacklistHost}. + * @param containerTiers the tiers of the container slots provided by the + * template. The length determines the number of + * containers. Maximum number is three. + * @param upgradeTiers the tiers of the upgrade slots provided by the + * template. The length determines the number of + * upgrades. Maximum number is nine. + * @param componentSlots the types and tiers of component slots provided by + * this template. May contain null entries + * to skip slots (slots are ordered top-to-bottom, + * left-to-right). For example, a robot template + * with only two card slots will pass null + * for the third component slot. Up to nine. + */ + public static void registerAssemblerTemplate(String name, String select, String validate, String assemble, Class host, int[] containerTiers, int[] upgradeTiers, Iterable> componentSlots) { + final NBTTagCompound nbt = new NBTTagCompound(); + if (name != null) { + nbt.setString("name", name); + } + nbt.setString("select", select); + nbt.setString("validate", validate); + nbt.setString("assemble", assemble); + if (host != null) { + nbt.setString("hostClass", host.getName()); + } + + final NBTTagList containersNbt = new NBTTagList(); + if (containerTiers != null) { + for (int tier : containerTiers) { + final NBTTagCompound slotNbt = new NBTTagCompound(); + slotNbt.setInteger("tier", tier); + containersNbt.appendTag(slotNbt); + } + } + if (containersNbt.tagCount() > 0) { + nbt.setTag("containerSlots", containersNbt); + } + + final NBTTagList upgradesNbt = new NBTTagList(); + if (upgradeTiers != null) { + for (int tier : upgradeTiers) { + final NBTTagCompound slotNbt = new NBTTagCompound(); + slotNbt.setInteger("tier", tier); + upgradesNbt.appendTag(slotNbt); + } + } + if (upgradesNbt.tagCount() > 0) { + nbt.setTag("upgradeSlots", upgradesNbt); + } + + final NBTTagList componentsNbt = new NBTTagList(); + if (componentSlots != null) { + for (Pair slot : componentSlots) { + if (slot == null) { + componentsNbt.appendTag(new NBTTagCompound()); + } else { + final NBTTagCompound slotNbt = new NBTTagCompound(); + slotNbt.setString("type", slot.getLeft()); + slotNbt.setInteger("tier", slot.getRight()); + componentsNbt.appendTag(slotNbt); + } + } + } + if (componentsNbt.tagCount() > 0) { + nbt.setTag("componentSlots", componentsNbt); + } + + FMLInterModComms.sendMessage(MOD_ID, "registerAssemblerTemplate", nbt); + } + + /** + * Register a new template for the disassembler. + *

+ * The disassemble callback gets passed the item stack to + * disassemble, and a list of inferred ingredients (based on crafting + * recipes). This is useful for not having to compute those yourself when + * you just want to add a number of items from an internal inventory to + * the output (e.g. for servers it's the components in the server). + *

+ * Signature of callbacks must be: + *

+     * boolean select(ItemStack stack)
+     * ItemStack[] disassemble(ItemStack stack, ItemStack[] ingredients)
+     * 
+ *

+ * Callbacks must be declared as packagePath.className.methodName. + * For example: com.example.Integration.callbackMethod. + * + * @param name the name of the handler (e.g. name of the item + * being handled). Optional, only used in logging. + * @param select callback used to determine if the template + * applies to an item. + * @param disassemble callback used to apply a template and extract + * ingredients from an item. + */ + public static void registerDisassemblerTemplate(String name, String select, String disassemble) { + final NBTTagCompound nbt = new NBTTagCompound(); + if (name != null) { + nbt.setString("name", name); + } + nbt.setString("select", select); + nbt.setString("disassemble", disassemble); + + FMLInterModComms.sendMessage(MOD_ID, "registerDisassemblerTemplate", nbt); + } + + /** + * Register a callback for providing tool durability information. + *

+ * If your provider does not handle a tool/item, return Double.NaN + * to indicate that another provider should be queried. The first value + * that isn't NaN will be used as the durability. + *

+ * The returned value must be the relative durability of the tool, + * in a range of [0,1], with 0 being broken, 1 being new/fully repaired. + *

+ * Signature of callbacks must be: + *

+     * double callback(ItemStack stack)
+     * 
+ *

+ * Callbacks must be declared as packagePath.className.methodName. + * For example: com.example.Integration.callbackMethod. + * + * @param callback the callback to register as a durability provider. + */ + public static void registerToolDurabilityProvider(String callback) { + FMLInterModComms.sendMessage(MOD_ID, "registerToolDurabilityProvider", callback); + } + + /** + * Register a callback handling a wrench tool. + *

+ * These are used when determining whether an item is a wrench tool, when + * interacting with certain blocks while the player is holding such an item, + * for example to avoid rotating blocks when opening their GUI. + *

+ * The returned value must be true if the wrench was used/usable, + * false otherwise. + *

+ * Signature of callbacks must be: + *

+     * boolean callback(EntityPlayer player, int x, int y, int z, boolean changeDurability)
+     * 
+ *

+ * Callbacks must be declared as packagePath.className.methodName. + * For example: com.example.Integration.callbackMethod. + * + * @param callback the callback to register as a wrench tool handler. + */ + public static void registerWrenchTool(String callback) { + FMLInterModComms.sendMessage(MOD_ID, "registerWrenchTool", callback); + } + + /** + * Register a handler for items that can be charged. + *

+ * This is used by the charger to determine whether items can be charged + * by it (canCharge) and to actually charge them (charge). + *

+ * Note that OpenComputers comes with a few built-in handlers for third- + * party charged items, such as Redstone Flux and IndustrialCraft 2. + *

+ * Signature of callbacks must be: + *

+     * boolean canCharge(ItemStack stack)
+     * double charge(ItemStack stack, double amount, boolean simulate)
+     * 
+ *

+ * Callbacks must be declared as packagePath.className.methodName. + * For example: com.example.Integration.callbackMethod. + * + * @param name the name of the energy system/item type handled. + * @param canCharge the callback to register for checking chargeability. + * @param charge the callback to register for charging items. + */ + public static void registerItemCharge(String name, String canCharge, String charge) { + final NBTTagCompound nbt = new NBTTagCompound(); + nbt.setString("name", name); + nbt.setString("canCharge", canCharge); + nbt.setString("charge", charge); + FMLInterModComms.sendMessage(MOD_ID, "registerItemCharge", nbt); + } + + /** + * Register a provider for ink usable in the 3D printer. + *

+ * Default providers in OpenComputers are one for the ink cartridges as + * well as one for arbitrary dyes (via the OreDictionary). + *

+ * Use this to make other items usable as ink in the 3D printer. Return a + * value larger than zero to indicate you handled the provided item stack, + * with the value being the amount of ink provided by the stack. + *

+ * Signature of callbacks must be: + *

+     * int callback(ItemStack stack)
+     * 
+ *

+ * Callbacks must be declared as packagePath.className.methodName. + * For example: com.example.Integration.callbackMethod. + * + * @param callback the callback to register as an ink provider. + */ + public static void registerInkProvider(String callback) { + FMLInterModComms.sendMessage(MOD_ID, "registerInkProvider", callback); + } + + /** + * Blacklist a ComputerCraft peripheral from being wrapped by OpenComputers' + * built-in driver for ComputerCraft peripherals. + *

+ * Use this if you provide a driver for something that is a peripheral and + * wish to avoid conflicts in the registered callbacks, for example. + * + * @param peripheral the class of the peripheral to blacklist. + */ + public static void blacklistPeripheral(Class peripheral) { + FMLInterModComms.sendMessage(MOD_ID, "blacklistPeripheral", peripheral.getName()); + } + + /** + * Blacklist an item for a specified host. + *

+ * This can be used to prevent certain components to be installed in select + * devices, via the devices class. For example, this is used to prevent + * components that would not be functional in certain devices to be + * installed in those devices, such as graphics cards in micro-controllers. + *

+ * The host class is the class of the environment the component would be + * installed in, e.g. {@link li.cil.oc.api.internal.Tablet}. + * + * @param name the name of the component being blacklisted. + * @param host the class of the host to blacklist the component for. + * @param stack the item stack representing the blacklisted component. + */ + public static void blacklistHost(String name, Class host, ItemStack stack) { + final NBTTagCompound nbt = new NBTTagCompound(); + nbt.setString("name", name); + nbt.setString("host", host.getName()); + final NBTTagCompound stackNbt = new NBTTagCompound(); + stack.writeToNBT(stackNbt); + nbt.setTag("item", stackNbt); + FMLInterModComms.sendMessage(MOD_ID, "blacklistHost", nbt); + } + + // ----------------------------------------------------------------------- // + + private static final String MOD_ID = "OpenComputers"; + + private IMC() { + } +} diff --git a/src/api/java/li/cil/oc/api/Items.java b/src/api/java/li/cil/oc/api/Items.java new file mode 100755 index 000000000..97d976d9b --- /dev/null +++ b/src/api/java/li/cil/oc/api/Items.java @@ -0,0 +1,101 @@ +package li.cil.oc.api; + +import li.cil.oc.api.detail.ItemInfo; +import net.minecraft.item.ItemStack; + +import java.util.concurrent.Callable; + +/** + * Access to item definitions for all blocks and items provided by + * OpenComputers. + */ +public final class Items { + /** + * Get a descriptor object for the block or item with the specified name. + *

+ * The names are the same as the ones used in the recipe files. An info + * object can be used to retrieve both the block and item instance of the + * item, if available. It can also be used to create a new item stack of + * the item. + *

+ * Note that these methods should not be called in the pre-init phase, + * since the {@link API#items} may not have been initialized + * at that time. Only start calling these methods in the init phase or later. + * + * @param name the name of the item to get the descriptor for. + * @return the descriptor for the item with the specified name, or + * null if there is no such item. + */ + public static ItemInfo get(String name) { + if (API.items != null) + return API.items.get(name); + return null; + } + + /** + * Get a descriptor object for the block or item represented by the + * specified item stack. + * + * @param stack the stack to get the descriptor for. + * @return the descriptor for the specified item stack, or null + * if the stack is not a valid OpenComputers item or block. + */ + public static ItemInfo get(ItemStack stack) { + if (API.items != null) + return API.items.get(stack); + return null; + } + + /** + * Register a single loot floppy disk. + *

+ * The disk will be listed in the creative tab of OpenComputers. + *

+ * The specified factory callable will be used to generate a new file + * system when the loot disk is used as a component. The specified name + * will be used as the label for the loot disk, as well as the identifier + * to select the corresponding factory method, so choose wisely. + *

+ * To use some directory in your mod JAR as the directory provided by the + * loot disk, use {@link FileSystem#fromClass} in your callable. + * + * @param name the label and identifier to use for the loot disk. + * @param color the color of the disk, as a Minecraft color (so 0-15, + * with 0 being black, 1 red and so on). + * @param factory the callable to call for creating file system instances. + * @return an item stack representing the registered loot disk, to allow + * adding a recipe for your loot disk, for example. + */ + public static ItemStack registerFloppy(String name, int color, Callable factory) { + if (API.items != null) + return API.items.registerFloppy(name, color, factory); + return null; + } + + /** + * Register a single custom EEPROM. + *

+ * The EEPROM will be listed in the creative tab of OpenComputers. + *

+ * The EEPROM will be initialized with the specified code and data byte + * arrays. For script code (e.g. a Lua script) use String.getBytes("UTF-8"). + * You can omit any of the arguments by passing null. + * + * @param name the label of the EEPROM. + * @param code the code section of the EEPROM. + * @param data the data section of the EEPROM. + * @param readonly whether the code section is read-only. + * @return an item stack representing the registered EEPROM, to allow + * adding a recipe for your custom BIOS, for example. + */ + public static ItemStack registerEEPROM(String name, byte[] code, byte[] data, boolean readonly) { + if (API.items != null) + return API.items.registerEEPROM(name, code, data, readonly); + return null; + } + + // ----------------------------------------------------------------------- // + + private Items() { + } +} diff --git a/src/api/java/li/cil/oc/api/Machine.java b/src/api/java/li/cil/oc/api/Machine.java new file mode 100755 index 000000000..7647a659b --- /dev/null +++ b/src/api/java/li/cil/oc/api/Machine.java @@ -0,0 +1,73 @@ +package li.cil.oc.api; + +import li.cil.oc.api.machine.Architecture; +import li.cil.oc.api.machine.MachineHost; + +import java.util.Collection; +import java.util.Collections; + +/** + * This API is intended for people who would like to implement custom computer + * blocks or anything else hosting a computer. + *

+ * It also allows registering new {@link Architecture}s, + * which are implementations of specific languages (e.g. assembler). The built- + * in ones are available as static fields in this class. + *

+ * Note that registration of architectures is optional and only intended as a + * convenience feature to make architectures usable via the built-in CPUs. + *

+ * Note that these methods should not be called in the pre-init phase, + * since the {@link API#machine} may not have been initialized + * at that time. Only start calling these methods in the init phase or later. + */ +public final class Machine { + /** + * Register an architecture that can be used to create new machines. + *

+ * Registering an architecture will make it possible to configure CPUs to + * run that architecture. This allows providing architectures without + * implementing a custom CPU item. + * + * @param architecture the architecture to register. + */ + public static void add(Class architecture) { + if (API.machine != null) + API.machine.add(architecture); + } + + /** + * A list of all registered architectures. + */ + public static Collection> architectures() { + if (API.machine != null) + return API.machine.architectures(); + return Collections.emptyList(); + } + + /** + * Creates a new machine for the specified host. + *

+ * You are responsible for calling update and save / load functions on the + * machine for it to work correctly. + * + * @param host the owner object of the machine, providing context. + * @return the newly created machine. + */ + public static li.cil.oc.api.machine.Machine create(MachineHost host) { + if (API.machine != null) + return API.machine.create(host); + return null; + } + + // ----------------------------------------------------------------------- // + + private Machine() { + } + + /** + * The built-in Lua architecture. This will be set to the native Lua + * implementation when possible, to the LuaJ fallback, otherwise. + */ + public static Class LuaArchitecture = null; +} diff --git a/src/api/java/li/cil/oc/api/Manual.java b/src/api/java/li/cil/oc/api/Manual.java new file mode 100755 index 000000000..581bfa457 --- /dev/null +++ b/src/api/java/li/cil/oc/api/Manual.java @@ -0,0 +1,184 @@ +package li.cil.oc.api; + +import li.cil.oc.api.manual.ContentProvider; +import li.cil.oc.api.manual.ImageProvider; +import li.cil.oc.api.manual.ImageRenderer; +import li.cil.oc.api.manual.PathProvider; +import li.cil.oc.api.manual.TabIconRenderer; +import net.minecraft.entity.player.EntityPlayer; +import net.minecraft.item.ItemStack; +import net.minecraft.world.World; + +/** + * This API allows interfacing with the in-game manual of OpenComputers. + *

+ * It allows opening the manual at a desired specific page, as well as + * registering custom tabs and content callback handlers. + *

+ * Note: this is a client side only API. It will do nothing on + * dedicated servers (i.e. API.manual will be null). + */ +public class Manual { + /** + * Register a tab to be displayed next to the manual. + *

+ * These are intended to link to index pages, and for the time being there + * a relatively low number of tabs that can be displayed, so I'd ask you to + * only register as many tabs as actually, technically *needed*. Which will + * usually be one, for your main index page. + * + * @param renderer the renderer used to render the icon on your tab. + * @param tooltip the unlocalized tooltip of the tab, or null. + * @param path the path to the page to open when the tab is clicked. + */ + public static void addTab(TabIconRenderer renderer, String tooltip, String path) { + if (API.manual != null) + API.manual.addTab(renderer, tooltip, path); + } + + /** + * Register a path provider. + *

+ * Path providers are used to find documentation entries for item stacks + * and blocks in the world. + * + * @param provider the provider to register. + */ + public static void addProvider(PathProvider provider) { + if (API.manual != null) + API.manual.addProvider(provider); + } + + /** + * Register a content provider. + *

+ * Content providers are used to resolve paths to page content, if the + * standard system (using Minecraft's resource loading facilities) fails. + *

+ * This can be useful for providing dynamic content, for example. + * + * @param provider the provider to register. + */ + public static void addProvider(ContentProvider provider) { + if (API.manual != null) + API.manual.addProvider(provider); + } + + /** + * Register an image provider. + *

+ * Image providers are used to render custom content in a page. These are + * selected via the standard image tag of Markdown, based on the prefix of + * the image URL, i.e. ![tooltip](prefix:data) will select the + * image provider registered for the prefix prefix, and pass to + * it the argument data, then use the returned renderer to draw + * an element in the place of the tag. The provided prefix is expected to + * be without the colon (:). + *

+ * Custom providers are only selected if a prefix is matched, otherwise + * it'll treat it as a relative path to an image to load via Minecraft's + * resource providing facilities, and display that. + * + * @param prefix the prefix on which to use the provider. + * @param provider the provider to register. + */ + public static void addProvider(String prefix, ImageProvider provider) { + if (API.manual != null) + API.manual.addProvider(prefix, provider); + } + + /** + * Get the image renderer for the specified image path. + *

+ * This will look for {@link ImageProvider}s registered for a prefix in the + * specified path. If there is no match, or the matched content provider + * does not provide a renderer, this will return null. + * + * @param path the path to the image to get the renderer for. + * @return the custom renderer for that path. + */ + public static ImageRenderer imageFor(String path) { + if (API.manual != null) + return API.manual.imageFor(path); + return null; + } + + // ----------------------------------------------------------------------- // + + /** + * Look up the documentation path for the specified item stack. + * + * @param stack the stack to find the documentation path for. + * @return the path to the page, null if none is known. + */ + public static String pathFor(ItemStack stack) { + if (API.manual != null) + return API.manual.pathFor(stack); + return null; + } + + /** + * Look up the documentation for the specified block in the world. + * + * @param world the world containing the block. + * @param x the X coordinate of the block. + * @param y the Y coordinate of the block. + * @param z the Z coordinate of the block. + * @return the path to the page, null if none is known. + */ + public static String pathFor(World world, int x, int y, int z) { + if (API.manual != null) + return API.manual.pathFor(world, x, y, z); + return null; + } + + /** + * Get the content of the documentation page at the specified location. + * + * @param path the path of the page to get the content of. + * @return the content of the page, or null if none exists. + */ + public static Iterable contentFor(String path) { + if (API.manual != null) + return API.manual.contentFor(path); + return null; + } + + // ----------------------------------------------------------------------- // + + /** + * Open the manual for the specified player. + *

+ * If you wish to display a specific page, call {@link #navigate(String)} + * after this function returns, with the path to the page to show. + * + * @param player the player to open the manual for. + */ + public static void openFor(EntityPlayer player) { + if (API.manual != null) + API.manual.openFor(player); + } + + /** + * Reset the history of the manual. + */ + public static void reset() { + if (API.manual != null) + API.manual.reset(); + } + + /** + * Navigate to a page in the manual. + * + * @param path the path to navigate to. + */ + public static void navigate(String path) { + if (API.manual != null) + API.manual.navigate(path); + } + + // ----------------------------------------------------------------------- // + + private Manual() { + } +} diff --git a/src/api/java/li/cil/oc/api/Network.java b/src/api/java/li/cil/oc/api/Network.java new file mode 100755 index 000000000..f87c2ded1 --- /dev/null +++ b/src/api/java/li/cil/oc/api/Network.java @@ -0,0 +1,217 @@ +package li.cil.oc.api; + +import li.cil.oc.api.detail.Builder; +import li.cil.oc.api.network.Environment; +import li.cil.oc.api.network.Node; +import li.cil.oc.api.network.Packet; +import li.cil.oc.api.network.Visibility; +import li.cil.oc.api.network.WirelessEndpoint; +import net.minecraft.nbt.NBTTagCompound; +import net.minecraft.tileentity.TileEntity; + +/** + * This class provides factories for networks and nodes. + *

+ * The first two functions provided provided by this API are to allow existing + * environments - implemented in a tile entity for example - to join an existing + * network or create new ones. The third one is used to create nodes that may + * then be connected to an existing network. It is not possible to create + * networks that do not belong to at least one tile entity or node. + *

+ * It is important to understand that component networks only exist on the + * server side. It is impossible to create nodes, and therefore networks, on + * the client side. This is to enforce a clear distinction of where the actual + * logic lies - since user code only runs on the server. + *

+ * Note that these methods should not be called in the pre-init phase, + * since the {@link API#network} may not have been initialized + * at that time. Only start calling these methods in the init phase or later. + */ +public final class Network { + /** + * Tries to add a tile entity's network node(s) at the specified coordinates + * to adjacent networks. + *

+ * If the tile entity implements {@link Environment} its one node will be + * connected to any existing adjacent tile entity nodes. If none exist a + * new network with the specified tile entity's node as its sole entry. + *

+ * If the tile entity is a {@link li.cil.oc.api.network.SidedEnvironment} + * the same rules as for simple environments apply, except that the + * respective for each side is used when connecting, and each side's node + * is added to its own new network, if necessary. + * + * @param tileEntity the tile entity to initialize. + */ + public static void joinOrCreateNetwork(final TileEntity tileEntity) { + if (API.network != null) + API.network.joinOrCreateNetwork(tileEntity); + } + + /** + * Creates a new network with the specified node as its initial node. + *

+ * This can be used to create networks that are not bound to any tile + * entity. For example, this is used to create the internal networks of + * robots. + * + * @param node the node to create the network for. + * @throws IllegalArgumentException if the node already is in a network. + */ + public static void joinNewNetwork(final Node node) { + if (API.network != null) + API.network.joinNewNetwork(node); + } + + // ----------------------------------------------------------------------- // + + /** + * Makes a wireless endpoint join the wireless network defined by the mod. + *

+ * OpenComputers tracks endpoints to which to send wireless packets sent + * via the {@link #sendWirelessPacket(WirelessEndpoint, double, Packet)} + * method. The packets will only be sent to endpoints registered + * with the network. + *

+ * Important: when your endpoint is removed from the world, + * you must ensure it is also removed from the network! + * + * @param endpoint the endpoint to register with the network. + */ + public static void joinWirelessNetwork(final WirelessEndpoint endpoint) { + if (API.network != null) + API.network.joinWirelessNetwork(endpoint); + } + + /** + * Updates a wireless endpoint in the wireless network. + *

+ * This is more efficient than removing and then adding the node again, as + * it only performs the update if the position significantly changed since + * the last time the position was updated (more than 0.5 along any axis). + *

+ * Calling this for an endpoint that was not added before does nothing. + * + * @param endpoint the endpoint for which to update the position. + */ + public static void updateWirelessNetwork(final WirelessEndpoint endpoint) { + if (API.network != null) + API.network.updateWirelessNetwork(endpoint); + } + + /** + * Removes a wireless endpoint from the wireless network. + *

+ * This must be called when an endpoint becomes invalid, otherwise it will + * remain in the network! + *

+ * Calling this for an endpoint that was not added before does nothing. + * + * @param endpoint the endpoint to remove from the wireless network. + */ + public static void leaveWirelessNetwork(final WirelessEndpoint endpoint) { + if (API.network != null) + API.network.leaveWirelessNetwork(endpoint); + } + + /** + * Sends a packet via the wireless network. + *

+ * This will look for all other registered wireless endpoints in range of + * the sender and submit the packets to them. Whether another end point is + * reached depends on the distance and potential obstacles between the + * sender and the receiver (harder blocks require a stronger signal to be + * penetrated). + * + * @param source the endpoint that is sending the message. + * @param strength the signal strength with which to send the packet. + * @param packet the packet to send. + */ + public static void sendWirelessPacket(final WirelessEndpoint source, final double strength, final Packet packet) { + if (API.network != null) + API.network.sendWirelessPacket(source, strength, packet); + } + + // ----------------------------------------------------------------------- // + + /** + * Factory function for creating new nodes. + *

+ * Use this to create a node for your environment (e.g. tile entity). This + * will return a builder that can be used to further specialize the node, + * making it either a component node (for callbacks), a connector node + * (for power interaction) or both. + *

+ * Example use: + *

+     * class YourThing extends TileEntity implements Environment {
+     *     private ComponentConnector node_ =
+     *         api.Network.newNode(this, Visibility.Network).
+     *             withComponent("your_thing").
+     *             withConnector(32).
+     *             create();
+     *
+     *     public Node node() { return node_; }
+     *
+     *     // ...
+     * }
+     * 
+ *

+ * Note that the reachability specified here is the general + * availability of the created node to other nodes in the network. Special + * rules apply to components, which have a visibility that is used + * to control how they can be reached from computers. For example, network + * cards have a reachability of Visibility.Network, to + * allow them to communicate with each other, but a visibility of + * Visibility.Neighbors to avoid other computers in the network + * to see the card (i.e. only the user programs running on the computer the + * card installed in can see interact with it). + * + * @param host the environment the node is created for. + * @param reachability the reachability of the node. + * @return a new node builder. + */ + public static Builder.NodeBuilder newNode(final Environment host, final Visibility reachability) { + if (API.network != null) + return API.network.newNode(host, reachability); + return null; + } + + /** + * Creates a new network packet as it would be sent or received by a + * network card. + *

+ * These packets can be forwarded by switches and access points. For wired + * transmission they must be sent over a node's send method, with the + * message name being network.message. + * + * @param source the address of the sending node. + * @param destination the address of the destination, or null + * for a broadcast. + * @param port the port to send the packet to. + * @param data the payload of the packet. + * @return the new packet. + */ + public static Packet newPacket(final String source, final String destination, final int port, final Object[] data) { + if (API.network != null) + return API.network.newPacket(source, destination, port, data); + return null; + } + + /** + * Re-creates a network packet from a previously stored state. + * + * @param nbt the tag to load the packet from. + * @return the loaded packet. + */ + public static Packet newPacket(final NBTTagCompound nbt) { + if (API.network != null) + return API.network.newPacket(nbt); + return null; + } + + // ----------------------------------------------------------------------- // + + private Network() { + } +} diff --git a/src/api/java/li/cil/oc/api/Persistable.java b/src/api/java/li/cil/oc/api/Persistable.java new file mode 100755 index 000000000..8ad2b2a45 --- /dev/null +++ b/src/api/java/li/cil/oc/api/Persistable.java @@ -0,0 +1,25 @@ +package li.cil.oc.api; + +import net.minecraft.nbt.NBTTagCompound; + +/** + * An object that can be persisted to an NBT tag and restored back from it. + */ +public interface Persistable { + /** + * Restores a previous state of the object from the specified NBT tag. + * + * @param nbt the tag to read the state from. + */ + void load(NBTTagCompound nbt); + + /** + * Saves the current state of the object into the specified NBT tag. + *

+ * This should write the state in such a way that it can be restored when + * {@link #load} is called with that tag. + * + * @param nbt the tag to save the state to. + */ + void save(NBTTagCompound nbt); +} \ No newline at end of file diff --git a/src/api/java/li/cil/oc/api/README.md b/src/api/java/li/cil/oc/api/README.md new file mode 100755 index 000000000..f6a454afa --- /dev/null +++ b/src/api/java/li/cil/oc/api/README.md @@ -0,0 +1,85 @@ +The API can be used to either interact with existing implementations in OpenComputers or to implement your own extensions for OpenComputers. + +Extending OpenComputers +======================== + +Making a tile entity available as a component / peripheral +-------------------------------------------------- +If you simply wish to expose a couple of methods that can be called from a computer if your tile entity's block is 'connected' to the computer, you can use the `SimpleComponent` interface. This interface serves as a marker for OpenComputers to know it has to inject code that converts your tile entity into a component using its class transformer. It is an interface instead of an annotation to allow stripping it, removing any dependencies on OpenComputers. Here is an example implementation: +```java +@Optional.Interface(iface = "li.cil.oc.api.network.SimpleComponent", modid = "OpenComputers") +public class TileEntityMyFancyThing extends TileEntity + implements SimpleComponent +{ + @Override + public String getComponentName() { + return "fancy_thing"; + } + + @Callback + @Optional.Method(modid = "OpenComputers") + public Object[] greet(Context context, Arguments args) { + return new Object[]{String.format("Hello, %s!", args.checkString(0))}; + } +} +``` + +The `getComponentName` determines with which name the tile entity will be available to computers. The `Callback` annotation tells OpenComputers to make the annotated method available to the computer. See the documentation on the `Callback` annotation for more information, in particular how it can be used to manipulate the call behavior (synchronized to the main thread vs. in the thread driving the calling computer). + +So to call the greeter method, in Lua you'd do this: +```lua +print(component.fancy_thing.greet("Steve")) -- prints "Hello, Steve!" +```` + +More control +------------ +If you really need more control over how how your tile entity interacts with OpenComputer's internal network, you will have to implement the `Environment` interface on your tile entity. There's a basic implementation in the prefab package, named `TileEntityEnvironment`. Doing so will give you access to the `Node` that connects to the component network, and you must take care of the construction of the node itself (using the factory method in `api.Network`). This allows you to make the node a `Connector` node, which will allow you to draw internal power from OpenComputers or feed energy into it. You will also be able to send messages over the component network, see the `send...` methods in the `Node` interface. See the documentation on those interfaces to get a better idea on how they work together. + +Making a third-party block available as component / peripheral +-------------------------------------------------------------- +Blocks from other mods, i.e. blocks where you have no control over the tile entity implementation, can be accessed using the Adapter block as long as there is a driver available that supports the block. If there are multiple drivers they are automatically merged. Please see the [integration][] package for examples, and consider contributing any block drivers you write. Thank you! + +Making items available as components +------------------------------------ +To make items usable as components in computers, such as cards or hard drives, you have to provide a driver for that item. This means you have to implement the `driver.Item` interface on a class and register an instance of it via the `api.Driver` registry. You can base your item drivers on the `DriverItem` prefab. Please see the example project on Github for a working example, and read the documentation of the driver interface for more information. + +FileSystem API +============== +If you'd like to make some files/scripts you ship with your mod available to a computer, you can do so by wrapping those files using an OpenComputers file system. Use the factory methods in `api.FileSystem` to wrap the location your files are stored at in a file system, use the `asManagedEnvironment` methods to wrap it in a node that can be attached to the component network. For example, in an environment of a tile entity or created by an item driver you could do this in the `onConnect` method whenever a computer is connected (i.e. `node.host() instanceof Context`). Code-wise it may look something like this: +```java +public class TileEntityWithFileSystem extends TileEntityEnvironment { + private final Node fileSystem; + + public TileEntityWithFileSystem() { + node = Network.newNode(this, Visibility.Network).create(); + fileSystem = FileSystem.asManagedEnvironment(FileSystem.fromClass(getClass, "yourmodid/lua"), "my_files"); + } + + @Override + public void onConnect(final Node node) { + if (node.host() instanceof Context) { + // Attach our file system to new computers we get connected to. + // Note that this is also called for all already present computers + // when we're added to an already existing network, so we don't + // have to loop through the existing nodes manually. + node.connect(fileSystem); + } + } + + @Override + public void onDisconnect(final Node node) { + if (node.host() instanceof Context) { + // Remove our file systems when we get disconnected from a + // computer. + node.disconnect(fileSystem); + } else if (node == this.node) { + // Remove the file system if we are disconnected, because in that + // case this method is only called once. + fileSystem.node.remove(); + } + } +} +``` + + +[integration]: https://github.com/MightyPirates/OpenComputers/tree/master-MC1.7.10/src/main/scala/li/cil/oc/integration \ No newline at end of file diff --git a/src/api/java/li/cil/oc/api/component/Keyboard.java b/src/api/java/li/cil/oc/api/component/Keyboard.java new file mode 100755 index 000000000..1f793df0d --- /dev/null +++ b/src/api/java/li/cil/oc/api/component/Keyboard.java @@ -0,0 +1,47 @@ +package li.cil.oc.api.component; + +import li.cil.oc.api.Persistable; +import li.cil.oc.api.network.Environment; +import net.minecraft.entity.player.EntityPlayer; + +/** + * This interface is implemented by the keyboard component, to allow more + * flexible use of it. + *

+ * You can obtain an instance of the keyboard component via the item driver + * of the keyboard block, for example: + *

+ *     final ItemStack stack = li.cil.oc.api.Items.get("keyboard").createItemStack(1);
+ *     final Keyboard keyboard = (Keyboard) li.cil.oc.api.Driver.driverFor(stack).createEnvironment(stack, this);
+ * 
+ */ +public interface Keyboard extends Environment, Persistable { + /** + * Sets a custom usability override. + *

+ * Instead of the default check, which is based on the component's owner's + * position, the specified callback will be queried for usability checks + * instead. + *

+ * Pass null here to unset a previously set override. + * + * @param callback the usability checker to use. + */ + void setUsableOverride(UsabilityChecker callback); + + /** + * Contract interface that has to implemented for usability check overrides. + * + * @see #setUsableOverride(UsabilityChecker) + */ + interface UsabilityChecker { + /** + * Whether the specified keyboard is usable by the specified player. + * + * @param keyboard the keyboard to check for. + * @param player the player to check for. + * @return whether the keyboard is usable by the player. + */ + boolean isUsableByPlayer(Keyboard keyboard, EntityPlayer player); + } +} diff --git a/src/api/java/li/cil/oc/api/component/TextBuffer.java b/src/api/java/li/cil/oc/api/component/TextBuffer.java new file mode 100755 index 000000000..3104c90ae --- /dev/null +++ b/src/api/java/li/cil/oc/api/component/TextBuffer.java @@ -0,0 +1,582 @@ +package li.cil.oc.api.component; + +import cpw.mods.fml.relauncher.Side; +import cpw.mods.fml.relauncher.SideOnly; +import li.cil.oc.api.Persistable; +import li.cil.oc.api.network.ManagedEnvironment; +import net.minecraft.entity.player.EntityPlayer; + +/** + * This interface implements functionality for displaying and manipulating + * text, like screens and robots. An implementation can be obtained via the + * screens' item driver. + *

+ * This allows re-using the built-in screen logic in third-party code without + * access to the internals of OC. + *

+ * To get an instance of the buffer component, use its item driver, e.g.: + *

+ *     final ItemStack stack = li.cil.oc.api.Items.get("screen1").createItemStack(1);
+ *     final TextBuffer buffer = (TextBuffer) li.cil.oc.api.Driver.driverFor(stack).createEnvironment(stack, this);
+ * 
+ */ +public interface TextBuffer extends ManagedEnvironment, Persistable { + /** + * Controls how much energy the buffer will consume per tick. + *

+ * This is not necessarily the actual amount consumed per tick, + * instead it is a base value that cost is based on, incorporating a few + * other factors. This is the cost a tier one screen will consume if every + * character is lit (non-black). Larger buffers (i.e. buffers with a higher + * maximum resolution) cost proportionally more. + *

+ * Note that this amount of energy is not necessarily subtracted each tick, + * instead every n ticks, n times the amount of energy it costs to run the + * buffer will be consumed, where n is configurable in the OC config. + *

+ * This defaults to OC's built-in default value. + * + * @param value the base energy cost per tick. + * @see #getEnergyCostPerTick() + */ + void setEnergyCostPerTick(double value); + + /** + * Get the energy cost per tick. + * + * @return the base energy cost per tick. + * @see #setEnergyCostPerTick(double) + */ + double getEnergyCostPerTick(); + + /** + * Set whether the buffer is powered on. + *

+ * For example, screens can be powered on and off by sending a redstone + * pulse into them, in addition to their component API. + * + * @param value whether the buffer should be on or not. + * @see #getPowerState() + */ + void setPowerState(boolean value); + + /** + * Get the current power state. + * + * @return whether the buffer is powered on. + * @see #setPowerState(boolean) + */ + boolean getPowerState(); + + /** + * Sets the maximum resolution supported by this buffer. + * + * @param width the maximum horizontal resolution, in characters. + * @param height the maximum vertical resolution, in characters. + */ + void setMaximumResolution(int width, int height); + + /** + * Get the maximum horizontal size of the buffer. + */ + int getMaximumWidth(); + + /** + * Get the maximum vertical size of the buffer. + */ + int getMaximumHeight(); + + /** + * Set the 'aspect ratio' of the buffer. + *

+ * Not to be confused with the maximum resolution of the buffer, this + * refers to the 'physical' size of the buffer's container. For multi- + * block screens, for example, this is the number of horizontal and + * vertical blocks. + * + * @param width the horizontal size of the physical representation. + * @param height the vertical size of the physical representation. + */ + void setAspectRatio(double width, double height); + + /** + * Get the aspect ratio of the buffer. + *

+ * Note that this is in fact width / height. + * + * @see #setAspectRatio(double, double) + */ + double getAspectRatio(); + + /** + * Set the buffer's active resolution. + * + * @param width the horizontal resolution. + * @param height the vertical resolution. + * @return true if the resolution changed. + */ + boolean setResolution(int width, int height); + + /** + * Get the current horizontal resolution. + * + * @see #setResolution(int, int) + */ + int getWidth(); + + /** + * Get the current vertical resolution. + * + * @see #setResolution(int, int) + */ + int getHeight(); + + /** + * Sets the maximum color depth supported by this buffer. + *

+ * Note that this is the maximum supported depth, lower depths + * will be supported, too. So when setting this to four bit, one bit will + * be supported, too. When setting this to eight bit, four and one bit + * will be supported, also. + * + * @param depth the maximum color depth of the buffer. + */ + void setMaximumColorDepth(ColorDepth depth); + + /** + * Get the maximum color depth supported. + */ + ColorDepth getMaximumColorDepth(); + + /** + * Set the active color depth for this buffer. + * + * @param depth the new color depth. + * @return true if the color depth changed. + */ + boolean setColorDepth(ColorDepth depth); + + /** + * Get the active color depth of this buffer. + */ + ColorDepth getColorDepth(); + + /** + * Set the color of the active color palette at the specified index. + *

+ * This will error if the current depth does not have a palette (one bit). + * + * @param index the index at which to set the color. + * @param color the color to set for the specified index. + */ + void setPaletteColor(int index, int color); + + /** + * Get the color in the active color palette at the specified index. + *

+ * This will error if the current depth does not have a palette (one bit). + * + * @param index the index at which to get the color. + * @return the color in the active palette at the specified index. + */ + int getPaletteColor(int index); + + /** + * Set the active foreground color, not using a palette. + * + * @param color the new foreground color. + * @see #setForegroundColor(int, boolean) + */ + void setForegroundColor(int color); + + /** + * Set the active foreground color. + *

+ * If the value is not from the palette, the actually stored value may + * differ from the specified one, as it is converted to the buffer's + * current color depth. + *

+ * For palette-only color formats (four bit) the best fit from the palette + * is chosen, if the value is not from the palette. + * + * @param color the color or palette index. + * @param isFromPalette trueif color specifies a palette index. + */ + void setForegroundColor(int color, boolean isFromPalette); + + /** + * The active foreground color. + */ + int getForegroundColor(); + + /** + * true if the foreground color is from the color palette, meaning + * the value returned from {@link #getForegroundColor()} is the color + * palette index. + */ + boolean isForegroundFromPalette(); + + /** + * Set the active background color, not using a palette. + * + * @param color the new background color. + * @see #setBackgroundColor(int, boolean) + */ + void setBackgroundColor(int color); + + /** + * Set the active background color. + *

+ * If the value is not from the palette, the actually stored value may + * differ from the specified one, as it is converted to the buffer's + * current color depth. + *

+ * For palette-only color formats (four bit) the best fit from the palette + * is chosen, if the value is not from the palette. + * + * @param color the color or palette index. + * @param isFromPalette trueif color specifies a palette index. + */ + void setBackgroundColor(int color, boolean isFromPalette); + + /** + * The active background color. + */ + int getBackgroundColor(); + + /** + * true if the background color is from the color palette, meaning + * the value returned from {@link #getBackgroundColor()} is the color + * palette index. + */ + boolean isBackgroundFromPalette(); + + /** + * Copy a portion of the text buffer. + *

+ * This will copy the area's text and colors. + * + * @param column the starting horizontal index of the area to copy. + * @param row the starting vertical index of the area to copy. + * @param width the width of the area to copy. + * @param height the height of the area to copy. + * @param horizontalTranslation the horizontal offset, relative to the starting column to copy the are to. + * @param verticalTranslation the vertical offset, relative to the starting row to copy the are to. + */ + void copy(int column, int row, int width, int height, int horizontalTranslation, int verticalTranslation); + + /** + * Fill a portion of the text buffer. + *

+ * This will set the area's colors to the currently active ones. + * + * @param column the starting horizontal index of the area to fill. + * @param row the starting vertical index of the area to fill. + * @param width the width of the area to fill. + * @param height the height of the area to fill. + * @param value the character to fill the area with. + */ + void fill(int column, int row, int width, int height, char value); + + /** + * Write a string into the text buffer. + *

+ * This will apply the currently active colors to the changed area. + * + * @param column the starting horizontal index to write at. + * @param row the starting vertical index to write at. + * @param value the string to write. + * @param vertical true if the string should be written vertically instead of horizontally. + */ + void set(int column, int row, String value, boolean vertical); + + /** + * Get the character in the text buffer at the specified location. + * + * @param column the horizontal index. + * @param row the vertical index. + * @return the character at that index. + */ + char get(int column, int row); + + /** + * Get the foreground color of the text buffer at the specified location. + *

+ * Important: this may be a palette index. + * + * @param column the horizontal index. + * @param row the vertical index. + * @return the foreground color at that index. + */ + int getForegroundColor(int column, int row); + + /** + * Whether the foreground color of the text buffer at the specified + * location if from the color palette. + * + * @param column the horizontal index. + * @param row the vertical index. + * @return whether the foreground at that index is from the palette. + */ + boolean isForegroundFromPalette(int column, int row); + + /** + * Get the background color of the text buffer at the specified location. + *

+ * Important: this may be a palette index. + * + * @param column the horizontal index. + * @param row the vertical index. + * @return the background color at that index. + */ + int getBackgroundColor(int column, int row); + + /** + * Whether the background color of the text buffer at the specified + * location if from the color palette. + * + * @param column the horizontal index. + * @param row the vertical index. + * @return whether the background at that index is from the palette. + */ + boolean isBackgroundFromPalette(int column, int row); + + /** + * Overwrites a portion of the text in raw mode. + *

+ * This will copy the given char array into the buffer, starting at the + * specified column and row. The array is expected to be indexed row- + * first, i.e. the first dimension is the vertical axis, the second + * the horizontal. + *

+ * Important: this performs no checks as to whether something + * actually changed. It will always send the changed patch to clients. + * It will also not crop the specified array to the actually used range. + * In other words, this is not intended to be exposed as-is to user code, + * it should always be called with validated, and, as necessary, cropped + * values. + * + * @param column the horizontal index. + * @param row the vertical index. + * @param text the text to write. + */ + void rawSetText(int column, int row, char[][] text); + + /** + * Overwrites a portion of the foreground color information in raw mode. + *

+ * This will convert the specified RGB data (in 0xRRGGBB format) + * to the internal, packed representation and copy it into the buffer, + * starting at the specified column and row. The array is expected to be + * indexed row-first, i.e. the first dimension is the vertical axis, the + * second the horizontal. + *

+ * Important: this performs no checks as to whether something + * actually changed. It will always send the changed patch to clients. + * It will also not crop the specified array to the actually used range. + * In other words, this is not intended to be exposed as-is to user code, + * it should always be called with validated, and, as necessary, cropped + * values. + * + * @param column the horizontal index. + * @param row the vertical index. + * @param color the foreground color data to write. + */ + void rawSetForeground(int column, int row, int[][] color); + + /** + * Overwrites a portion of the background color information in raw mode. + *

+ * This will convert the specified RGB data (in 0xRRGGBB format) + * to the internal, packed representation and copy it into the buffer, + * starting at the specified column and row. The array is expected to be + * indexed row-first, i.e. the first dimension is the vertical axis, the + * second the horizontal. + *

+ * Important: this performs no checks as to whether something + * actually changed. It will always send the changed patch to clients. + * It will also not crop the specified array to the actually used range. + * In other words, this is not intended to be exposed as-is to user code, + * it should always be called with validated, and, as necessary, cropped + * values. + * + * @param column the horizontal index. + * @param row the vertical index. + * @param color the background color data to write. + */ + void rawSetBackground(int column, int row, int[][] color); + + // ----------------------------------------------------------------------- // + + /** + * Renders the text displayed on the buffer. + *

+ * You are responsible for setting up the actual context and applying any + * transformations necessary to properly position and scale the text before + * calling this. The text should be rendered on a black background. + *

+ * You can use this to either render the text in a GUI or in the world. + * + * @return true if the displayed content changed since the last + * call to this method. + */ + @SideOnly(Side.CLIENT) + boolean renderText(); + + /** + * The natural width of the rendered text. + *

+ * This is the width of the complete text buffer, in pixels. In other + * words, this is the width of the buffer in chars times the actual width + * of a single char in pixels. + * + * @return the total width of the rendered buffer, in pixels. + */ + @SideOnly(Side.CLIENT) + int renderWidth(); + + /** + * The natural height of the rendered text. + *

+ * This is the height of the complete text buffer, in pixels. In other + * words, this is the height of the buffer in chars times the actual height + * of a single char in pixels. + * + * @return the total height of the rendered buffer, in pixels. + */ + @SideOnly(Side.CLIENT) + int renderHeight(); + + /** + * Set whether the contents of the buffer should currently be rendered. + *

+ * Note that this is automatically overwritten when the buffer's power + * state changes, i.e. when it runs out of power or gets back power. + * + * @param enabled whether the text buffer should be rendered. + */ + @SideOnly(Side.CLIENT) + void setRenderingEnabled(boolean enabled); + + /** + * Gets whether the contents of the buffer should currently be rendered. + * + * @see #setRenderingEnabled(boolean) + */ + @SideOnly(Side.CLIENT) + boolean isRenderingEnabled(); + + // ----------------------------------------------------------------------- // + + /** + * Signals a key down event for the buffer. + *

+ * On the client side this causes a packet to be sent to the server. On the + * server side this will trigger a message that will be picked up by + * keyboards, which will then cause a signal in attached machines. + * + * @param character the character of the pressed key. + * @param code the key code of the pressed key. + * @param player the player that pressed the key. Pass null on the client side. + */ + void keyDown(char character, int code, EntityPlayer player); + + /** + * Signals a key up event for the buffer. + *

+ * On the client side this causes a packet to be sent to the server. On the + * server side this will trigger a message that will be picked up by + * keyboards, which will then cause a signal in attached machines. + * + * @param character the character of the released key. + * @param code the key code of the released key. + * @param player the player that released the key. Pass null on the client side. + */ + void keyUp(char character, int code, EntityPlayer player); + + /** + * Signals a clipboard paste event for the buffer. + *

+ * On the client side this causes a packet to be sent to the server. On the + * server side this will trigger a message that will be picked up by + * keyboards, which will then cause a signal in attached machines. + * + * @param value the text that was pasted. + * @param player the player that pasted the text. Pass null on the client side. + */ + void clipboard(String value, EntityPlayer player); + + /** + * Signals a mouse button down event for the buffer. + *

+ * On the client side this causes a packet to be sent to the server. On the + * server side this will cause a signal in attached machines. + * + * @param x the horizontal coordinate of the mouse, in characters. + * @param y the vertical coordinate of the mouse, in characters. + * @param button the button of the mouse that was pressed. + * @param player the player that pressed the mouse button. Pass null on the client side. + */ + void mouseDown(double x, double y, int button, EntityPlayer player); + + /** + * Signals a mouse drag event for the buffer. + *

+ * On the client side this causes a packet to be sent to the server. On the + * server side this will cause a signal in attached machines. + * + * @param x the horizontal coordinate of the mouse, in characters. + * @param y the vertical coordinate of the mouse, in characters. + * @param button the button of the mouse that is pressed. + * @param player the player that moved the mouse. Pass null on the client side. + */ + void mouseDrag(double x, double y, int button, EntityPlayer player); + + /** + * Signals a mouse button release event for the buffer. + *

+ * On the client side this causes a packet to be sent to the server. On the + * server side this will cause a signal in attached machines. + * + * @param x the horizontal coordinate of the mouse, in characters. + * @param y the vertical coordinate of the mouse, in characters. + * @param button the button of the mouse that was released. + * @param player the player that released the mouse button. Pass null on the client side. + */ + void mouseUp(double x, double y, int button, EntityPlayer player); + + /** + * Signals a mouse wheel scroll event for the buffer. + *

+ * On the client side this causes a packet to be sent to the server. On the + * server side this will cause a signal in attached machines. + * + * @param x the horizontal coordinate of the mouse, in characters. + * @param y the vertical coordinate of the mouse, in characters. + * @param delta indicates the direction of the mouse scroll. + * @param player the player that scrolled the mouse wheel. Pass null on the client side. + */ + void mouseScroll(double x, double y, int delta, EntityPlayer player); + + // ----------------------------------------------------------------------- // + + /** + * Used when setting a buffer's maximum color depth. + */ + enum ColorDepth { + /** + * Monochrome color, black and white. + */ + OneBit, + + /** + * 16 color palette, defaults to Minecraft colors. + */ + FourBit, + + /** + * 240 colors, 16 color palette, defaults to grayscale. + */ + EightBit + } +} diff --git a/src/api/java/li/cil/oc/api/component/package-info.java b/src/api/java/li/cil/oc/api/component/package-info.java new file mode 100755 index 000000000..615dd621d --- /dev/null +++ b/src/api/java/li/cil/oc/api/component/package-info.java @@ -0,0 +1,14 @@ +/** + * This package provides interfaces to allow interacting with some components. + *

+ * These interfaces allow more specific interaction with some of OpenComputers' + * components, which would otherwise require reflection or linking against the + * mod itself. + */ +@cpw.mods.fml.common.API( + owner = API.ID_OWNER, + provides = "OpenComputersAPI|Component", + apiVersion = API.VERSION) +package li.cil.oc.api.component; + +import li.cil.oc.api.API; \ No newline at end of file diff --git a/src/api/java/li/cil/oc/api/detail/Builder.java b/src/api/java/li/cil/oc/api/detail/Builder.java new file mode 100755 index 000000000..10affbbac --- /dev/null +++ b/src/api/java/li/cil/oc/api/detail/Builder.java @@ -0,0 +1,150 @@ +package li.cil.oc.api.detail; + +import li.cil.oc.api.network.Component; +import li.cil.oc.api.network.ComponentConnector; +import li.cil.oc.api.network.Connector; +import li.cil.oc.api.network.Node; +import li.cil.oc.api.network.Visibility; + +/** + * Used for building {@link Node}s via {@link li.cil.oc.api.Network#newNode}. + * + * @param the type of the node created by this builder. + */ +public interface Builder { + /** + * Finalizes the construction of the node. + *

+ * This performs the actual creation of the node, initializes it to the + * settings defined by the current builder and returns it. + * + * @return the final node. + */ + T create(); + + /** + * Builder for basic nodes. These nodes merely allow network access and + * take on no special role. + */ + public static interface NodeBuilder extends Builder { + /** + * Makes the node a component. + *

+ * Nodes that are components can be accessed from computers, methods + * declared in them marked using the {@link li.cil.oc.api.machine.Callback} annotation can + * be invoked from computers that can see the component. + * + * @param name the name of the component. + * @param visibility the visibility of the component. + * @return a builder for a node that is also a component. + * @see li.cil.oc.api.network.Component + */ + ComponentBuilder withComponent(String name, Visibility visibility); + + /** + * Makes the node a component. + *

+ * Like {@link #withComponent(String, Visibility)}, but with a default + * visibility set to the reachability of the node. + * + * @param name the name of the component. + * @return a builder for a node that is also a component. + * @see li.cil.oc.api.network.Component + */ + ComponentBuilder withComponent(String name); + + /** + * Makes the node a connector. + *

+ * A connector node can feed power into the network and extract power + * from the network. This is used both for passive energy drain (such + * as running screens and computers) and for active power consumption + * (such as wireless message sending or robot actions). + * + * @param bufferSize the size of the local energy buffer. + * @return a builder for a node that is also a connector. + * @see li.cil.oc.api.network.Connector + */ + ConnectorBuilder withConnector(double bufferSize); + + /** + * Makes the node a connector. + *

+ * Like {@link #withConnector(double)}, but with a default buffer size + * of zero. + * + * @return a builder for a node that is also a connector. + * @see li.cil.oc.api.network.Connector + */ + ConnectorBuilder withConnector(); + } + + /** + * Builder for component nodes. These node can be interacted with from + * computers in the same network, that can see the component. + */ + public static interface ComponentBuilder extends Builder { + /** + * Makes the node a connector. + *

+ * A connector node can feed power into the network and extract power + * from the network. This is used both for passive energy drain (such + * as running screens and computers) and for active power consumption + * (such as wireless message sending or robot actions). + * + * @param bufferSize the size of the local energy buffer. + * @return a builder for a node that is also a connector. + * @see li.cil.oc.api.network.Connector + */ + ComponentConnectorBuilder withConnector(double bufferSize); + + /** + * Makes the node a connector. + *

+ * Like {@link #withConnector(double)}, but with a default buffer size + * of zero. + * + * @return a builder for a node that is also a connector. + * @see li.cil.oc.api.network.Connector + */ + ComponentConnectorBuilder withConnector(); + } + + /** + * Builder for connector nodes. These nodes can interact with the energy + * stored in the network, i.e. increase or reduce it. + */ + public static interface ConnectorBuilder extends Builder { + /** + * Makes the node a component. + *

+ * Nodes that are components can be accessed from computers, methods + * declared in them marked using the {@link li.cil.oc.api.machine.Callback} annotation can + * be invoked from computers that can see the component. + * + * @param name the name of the component. + * @param visibility the visibility of the component. + * @return a builder for a node that is also a component. + * @see li.cil.oc.api.network.Component + */ + ComponentConnectorBuilder withComponent(String name, Visibility visibility); + + /** + * Makes the node a component. + *

+ * Like {@link #withComponent(String, Visibility)}, but with a default + * visibility set to the reachability of the node. + * + * @param name the name of the component. + * @return a builder for a node that is also a component. + * @see li.cil.oc.api.network.Component + */ + ComponentConnectorBuilder withComponent(String name); + } + + /** + * Builder for nodes that are both component and connector node. + */ + public static interface ComponentConnectorBuilder extends Builder { + } +} diff --git a/src/api/java/li/cil/oc/api/detail/DriverAPI.java b/src/api/java/li/cil/oc/api/detail/DriverAPI.java new file mode 100755 index 000000000..1a0d1c470 --- /dev/null +++ b/src/api/java/li/cil/oc/api/detail/DriverAPI.java @@ -0,0 +1,119 @@ +package li.cil.oc.api.detail; + +import li.cil.oc.api.driver.Block; +import li.cil.oc.api.driver.Converter; +import li.cil.oc.api.driver.EnvironmentHost; +import li.cil.oc.api.driver.Item; +import net.minecraft.item.ItemStack; +import net.minecraft.world.World; + +import java.util.Collection; + +public interface DriverAPI { + /** + * Registers a new driver for a block component. + *

+ * Whenever the neighboring blocks of an Adapter block change, it checks if + * there exists a driver for the changed block, and if it is configured to + * interface that block type connects it to the component network. + *

+ * This must be called in the init phase, not the pre- or post-init + * phases. + * + * @param driver the driver for a block component. + */ + void add(Block driver); + + /** + * Registers a new driver for an item component. + *

+ * Item components can inserted into a computers component slots. They have + * to specify their type, to determine into which slots they can fit. + *

+ * This must be called in the init phase, not the pre- or post-init + * phases. + * + * @param driver the driver for an item component. + */ + void add(Item driver); + + /** + * Registers a new type converter. + *

+ * Type converters are used to automatically convert values returned from + * callbacks to a "simple" format that can be pushed to any architecture. + *

+ * This must be called in the init phase, not the pre- or post-init + * phases. + * + * @param converter the converter to register. + */ + void add(Converter converter); + + /** + * Looks up a driver for the block at the specified position in the + * specified world. + *

+ * Note that several drivers for a single block can exist. Because of this + * block drivers are always encapsulated in a 'compound' driver, which is + * what will be returned here. In other words, you should will not + * get actual instances of drivers registered via {@link #add(li.cil.oc.api.driver.Block)}. + * + * @param world the world containing the block. + * @param x the X coordinate of the block. + * @param y the Y coordinate of the block. + * @param z the Z coordinate of the block. + * @return a driver for the block, or null if there is none. + */ + Block driverFor(World world, int x, int y, int z); + + /** + * Looks up a driver for the specified item stack. + *

+ * Note that unlike for blocks, there can always only be one item driver + * per item. If there are multiple ones, the first one that was registered + * will be used. + * + * @param stack the item stack to get a driver for. + * @param host the type that will host the environment created by returned driver. + * @return a driver for the item, or null if there is none. + */ + Item driverFor(ItemStack stack, Class host); + + /** + * Looks up a driver for the specified item stack. + *

+ * Note that unlike for blocks, there can always only be one item driver + * per item. If there are multiple ones, the first one that was registered + * will be used. + *

+ * This is a context-agnostic variant used mostly for "house-keeping" + * stuff, such as querying slot types and tier. + * + * @param stack the item stack to get a driver for. + * @return a driver for the item, or null if there is none. + */ + Item driverFor(ItemStack stack); + + /** + * Get a list of all registered block drivers. + *

+ * This is intended to allow checking for particular drivers using more + * customized logic, and in particular to check for drivers with the + * {@link li.cil.oc.api.driver.EnvironmentAware} interface. + * + * @return the list of all registered block drivers. + */ + Collection blockDrivers(); + + /** + * Get a list of all registered item drivers. + *

+ * This is intended to allow checking for particular drivers using more + * customized logic, and in particular to check for drivers with the + * {@link li.cil.oc.api.driver.EnvironmentAware} interface. + * + * @return the list of all registered item drivers. + */ + Collection itemDrivers(); +} diff --git a/src/api/java/li/cil/oc/api/detail/FileSystemAPI.java b/src/api/java/li/cil/oc/api/detail/FileSystemAPI.java new file mode 100755 index 000000000..69f06e633 --- /dev/null +++ b/src/api/java/li/cil/oc/api/detail/FileSystemAPI.java @@ -0,0 +1,181 @@ +package li.cil.oc.api.detail; + +import li.cil.oc.api.driver.EnvironmentHost; +import li.cil.oc.api.fs.FileSystem; +import li.cil.oc.api.fs.Label; +import li.cil.oc.api.network.ManagedEnvironment; + +public interface FileSystemAPI { + /** + * Creates a new file system based on the location of a class. + *

+ * This can be used to wrap a folder in the assets folder of your mod's JAR. + * The actual path is built like this: + *

"/assets/" + domain + "/" + root
+ *

+ * If the class is located in a JAR file, this will create a read-only file + * system based on that JAR file. If the class file is located in the native + * file system, this will create a read-only file system first trying from + * the actual location of the class file, and failing that by searching the + * class path (i.e. it'll look for a path constructed as described above). + *

+ * If the specified path cannot be located, the creation fails and this + * returns null. + * + * @param clazz the class whose containing JAR to wrap. + * @param domain the domain, usually your mod's ID. + * @param root an optional subdirectory. + * @return a file system wrapping the specified folder. + */ + FileSystem fromClass(Class clazz, String domain, String root); + + /** + * Creates a new writable file system in the save folder. + *

+ * This will create a folder, if necessary, and create a writable virtual + * file system based in that folder. The actual path is based in a sub- + * folder of the save folder. The actual path is built like this: + *

"saves/" + WORLD_NAME + "/opencomputers/" + root
+ * The first part may differ, in particular for servers. + *

+ * Usually the name will be the address of the node used to represent the + * file system. + *

+ * Note that by default file systems are "buffered", meaning that any + * changes made to them are only saved to disk when the world is saved. This + * ensured that the file system contents do not go "out of sync" when the + * game crashes, but introduces additional memory overhead, since all files + * in the file system have to be kept in memory. + * + * @param root the name of the file system. + * @param capacity the amount of space in bytes to allow being used. + * @param buffered whether data should only be written to disk when saving. + * @return a file system wrapping the specified folder. + */ + FileSystem fromSaveDirectory(String root, long capacity, boolean buffered); + + /** + * Creates a new writable file system that resides in memory. + *

+ * Any contents created and written on this file system will be lost when + * the node is removed from the network. + *

+ * This is used for computers' /tmp mount, for example. + * + * @param capacity the capacity of the file system. + * @return a file system residing in memory. + */ + FileSystem fromMemory(long capacity); + + /** + * Creates a new file system based on a read-only ComputerCraft mount. + *

+ * This supports read-only and writable mounts from either CC 1.5x or + * CC 1.6x. The argument is kept untyped to avoid having the OC API + * depend on the CC API. + *

+ * If the passed type is unsupported, this will return null. + * + * @param mount the mount to wrap with a file system. + * @return a file system wrapping the specified mount. + */ + FileSystem fromComputerCraft(Object mount); + + /** + * Wrap a file system retrieved via one of the from??? methods to + * make it read-only. + * + * @param fileSystem the file system to wrap. + * @return the specified file system wrapped to be read-only. + */ + FileSystem asReadOnly(final FileSystem fileSystem); + + /** + * Creates a network node that makes the specified file system available via + * the common file system driver. + *

+ * This can be useful for providing some data if you don't wish to implement + * your own driver. Which will probably be most of the time. If you need + * more control over the node, implement your own, and connect this one to + * it. In that case you will have to forward any disk driver messages to the + * node, though. + *

+ * The container parameter is used to give the file system some physical + * relation to the world, for example this is used by hard drives to send + * the disk event notifications to the client that are used to play disk + * access sounds. + *

+ * The container may be null, if no such context can be provided. + *

+ * The access sound is the name of the sound effect to play when the file + * system is accessed, for example by listing a directory or reading from + * a file. It may be null to create a silent file system. + *

+ * The speed multiplier controls how fast read and write operations on the + * file system are. It must be a value in [1,6], and controls the access + * speed, with the default being one. + * For reference, floppies are using the default, hard drives scale with + * their tiers, i.e. a tier one hard drive uses speed two, tier three uses + * speed four. + * + * @param fileSystem the file system to wrap. + * @param label the label of the file system. + * @param host the tile entity containing the file system. + * @param accessSound the name of the sound effect to play when the file + * system is accessed. This has to be the fully + * qualified resource name, e.g. + * opencomputers:floppy_access. + * @param speed the speed multiplier for this file system. + * @return the network node wrapping the file system. + */ + ManagedEnvironment asManagedEnvironment(FileSystem fileSystem, Label label, EnvironmentHost host, String accessSound, int speed); + + /** + * Creates a network node that makes the specified file system available via + * the common file system driver. + *

+ * Creates a file system with the a read-only label and the specified + * access sound and file system speed. + * + * @param fileSystem the file system to wrap. + * @param label the read-only label of the file system. + * @param host the tile entity containing the file system. + * @param accessSound the name of the sound effect to play when the file + * system is accessed. This has to be the fully + * qualified resource name, e.g. + * opencomputers:floppy_access. + * @param speed the speed multiplier for this file system. + * @return the network node wrapping the file system. + */ + ManagedEnvironment asManagedEnvironment(FileSystem fileSystem, String label, EnvironmentHost host, String accessSound, int speed); + + /** + * @deprecated Don't use this directly, use the wrapper in {@link li.cil.oc.api.FileSystem}. + */ + @Deprecated + ManagedEnvironment asManagedEnvironment(FileSystem fileSystem, Label label, EnvironmentHost host, String accessSound); + + /** + * @deprecated Don't use this directly, use the wrapper in {@link li.cil.oc.api.FileSystem}. + */ + @Deprecated + ManagedEnvironment asManagedEnvironment(FileSystem fileSystem, String label, EnvironmentHost host, String accessSound); + + /** + * @deprecated Don't use this directly, use the wrapper in {@link li.cil.oc.api.FileSystem}. + */ + @Deprecated + ManagedEnvironment asManagedEnvironment(FileSystem fileSystem, Label label); + + /** + * @deprecated Don't use this directly, use the wrapper in {@link li.cil.oc.api.FileSystem}. + */ + @Deprecated + ManagedEnvironment asManagedEnvironment(FileSystem fileSystem, String label); + + /** + * @deprecated Don't use this directly, use the wrapper in {@link li.cil.oc.api.FileSystem}. + */ + @Deprecated + ManagedEnvironment asManagedEnvironment(FileSystem fileSystem); +} \ No newline at end of file diff --git a/src/api/java/li/cil/oc/api/detail/ItemAPI.java b/src/api/java/li/cil/oc/api/detail/ItemAPI.java new file mode 100755 index 000000000..0de2b2f3d --- /dev/null +++ b/src/api/java/li/cil/oc/api/detail/ItemAPI.java @@ -0,0 +1,76 @@ +package li.cil.oc.api.detail; + +import li.cil.oc.api.FileSystem; +import net.minecraft.item.ItemStack; + +import java.util.concurrent.Callable; + +public interface ItemAPI { + /** + * Get a descriptor object for the block or item with the specified name. + *

+ * The names are the same as the ones used in the recipe files. An info + * object can be used to retrieve both the block and item instance of the + * item, if available. It can also be used to create a new item stack of + * the item. + * + * @param name the name of the item to get the descriptor for. + * @return the descriptor for the item with the specified name, or + * null if there is no such item. + */ + ItemInfo get(String name); + + /** + * Get a descriptor object for the block or item represented by the + * specified item stack. + * + * @param stack the stack to get the descriptor for. + * @return the descriptor for the specified item stack, or null + * if the stack is not a valid OpenComputers item or block. + */ + ItemInfo get(ItemStack stack); + + /** + * Register a single loot floppy disk. + *

+ * The disk will be listed in the creative tab of OpenComputers. + *

+ * The specified factory callable will be used to generate a new file + * system when the loot disk is used as a component. The specified name + * will be used as the label for the loot disk, as well as the identifier + * to select the corresponding factory method, so choose wisely. + *

+ * To use some directory in your mod JAR as the directory provided by the + * loot disk, use {@link FileSystem#fromClass} in your callable. + *

+ * Call this in the init phase or later, not in pre-init. + * + * @param name the label and identifier to use for the loot disk. + * @param color the color of the disk, as a Minecraft color (so 0-15, + * with 0 being black, 1 red and so on). + * @param factory the callable to call for creating file system instances. + * @return an item stack representing the registered loot disk, to allow + * adding a recipe for your loot disk, for example. + */ + ItemStack registerFloppy(String name, int color, Callable factory); + + /** + * Register a single custom EEPROM. + *

+ * The EEPROM will be listed in the creative tab of OpenComputers. + *

+ * The EEPROM will be initialized with the specified code and data byte + * arrays. For script code (e.g. a Lua script) use String.getBytes("UTF-8"). + * You can omit any of the arguments by passing null. + *

+ * Call this in the init phase or later, not in pre-init. + * + * @param name the label of the EEPROM. + * @param code the code section of the EEPROM. + * @param data the data section of the EEPROM. + * @param readonly whether the code section is read-only. + * @return an item stack representing the registered EEPROM, to allow + * adding a recipe for your custom BIOS, for example. + */ + ItemStack registerEEPROM(String name, byte[] code, byte[] data, boolean readonly); +} diff --git a/src/api/java/li/cil/oc/api/detail/ItemInfo.java b/src/api/java/li/cil/oc/api/detail/ItemInfo.java new file mode 100755 index 000000000..4decd85a5 --- /dev/null +++ b/src/api/java/li/cil/oc/api/detail/ItemInfo.java @@ -0,0 +1,50 @@ +package li.cil.oc.api.detail; + +import net.minecraft.block.Block; +import net.minecraft.item.Item; +import net.minecraft.item.ItemStack; + +public interface ItemInfo { + /** + * The name of this item descriptor. + *

+ * This is the name that yields this instance when passed to + * {@link li.cil.oc.api.Items#get(String)}. Useful for reverse-lookup when + * retrieving the descriptor via an item stack. + * + * @return the name of this item descriptor. + */ + String name(); + + /** + * Returns the block type of the represented item. In case the item is not + * a block this will return null. + *

+ * Note that OpenComputers represents most of its items using just a few + * actual Block instances, so descriptors for different blocks may + * return the same object here. + * + * @return the block type of the represented block. + */ + Block block(); + + /** + * Returns the item type of the represented item. In case the item is a + * blocks this will return null. + *

+ * Note that OpenComputers represents most of its items using just a few + * actual Item instances, so descriptors for different items may + * return the same object here. + * + * @return the item type of the represented item. + */ + Item item(); + + /** + * Creates a new item stack of the item represended by this descriptor. + * + * @param size the size of the item stack to create. + * @return the created item stack. + */ + ItemStack createItemStack(int size); +} diff --git a/src/api/java/li/cil/oc/api/detail/MachineAPI.java b/src/api/java/li/cil/oc/api/detail/MachineAPI.java new file mode 100755 index 000000000..282291c1a --- /dev/null +++ b/src/api/java/li/cil/oc/api/detail/MachineAPI.java @@ -0,0 +1,43 @@ +package li.cil.oc.api.detail; + +import li.cil.oc.api.machine.Architecture; +import li.cil.oc.api.machine.Machine; +import li.cil.oc.api.machine.MachineHost; + +import java.util.Collection; + +public interface MachineAPI { + /** + * Register an architecture that can be used to create new machines. + *

+ * Note that although registration is optional, it is strongly recommended + * to allow {@link #architectures()} to be useful. + * + * @param architecture the architecture to register. + * @throws IllegalArgumentException if the specified architecture is invalid. + */ + void add(Class architecture); + + /** + * A list of all registered architectures. + *

+ * Note that registration is optional, although automatic when calling + * {@link #create(li.cil.oc.api.machine.MachineHost)} with a not yet + * registered architecture. What this means is that unless a mod providing + * a custom architecture also registers it, you may not see it in this list + * until it also created a new machine using that architecture. + */ + Collection> architectures(); + + /** + * Creates a new machine for the specified host. + *

+ * You are responsible for calling update and save / load functions on the + * machine for it to work correctly. + * + * @param host the owner object of the machine, providing context. + * @return the newly created machine. + * @throws IllegalArgumentException if the specified architecture is invalid. + */ + Machine create(MachineHost host); +} diff --git a/src/api/java/li/cil/oc/api/detail/ManualAPI.java b/src/api/java/li/cil/oc/api/detail/ManualAPI.java new file mode 100755 index 000000000..0b2532c39 --- /dev/null +++ b/src/api/java/li/cil/oc/api/detail/ManualAPI.java @@ -0,0 +1,136 @@ +package li.cil.oc.api.detail; + +import li.cil.oc.api.manual.ContentProvider; +import li.cil.oc.api.manual.ImageProvider; +import li.cil.oc.api.manual.ImageRenderer; +import li.cil.oc.api.manual.PathProvider; +import li.cil.oc.api.manual.TabIconRenderer; +import net.minecraft.entity.player.EntityPlayer; +import net.minecraft.item.ItemStack; +import net.minecraft.world.World; + +public interface ManualAPI { + /** + * Register a tab to be displayed next to the manual. + *

+ * These are intended to link to index pages, and for the time being there + * a relatively low number of tabs that can be displayed, so I'd ask you to + * only register as many tabs as actually, technically *needed*. Which will + * usually be one, for your main index page. + * + * @param renderer the renderer used to render the icon on your tab. + * @param tooltip the unlocalized tooltip of the tab, or null. + * @param path the path to the page to open when the tab is clicked. + */ + void addTab(TabIconRenderer renderer, String tooltip, String path); + + /** + * Register a path provider. + *

+ * Path providers are used to find documentation entries for item stacks + * and blocks in the world. + * + * @param provider the provider to register. + */ + void addProvider(PathProvider provider); + + /** + * Register a content provider. + *

+ * Content providers are used to resolve paths to page content, if the + * standard system (using Minecraft's resource loading facilities) fails. + *

+ * This can be useful for providing dynamic content, for example. + * + * @param provider the provider to register. + */ + void addProvider(ContentProvider provider); + + /** + * Register an image provider. + *

+ * Image providers are used to render custom content in a page. These are + * selected via the standard image tag of Markdown, based on the prefix of + * the image URL, i.e. ![tooltip](prefix:data) will select the + * image provider registered for the prefix prefix, and pass to + * it the argument data, then use the returned renderer to draw + * an element in the place of the tag. + *

+ * Custom providers are only selected if a prefix is matched, otherwise + * it'll treat it as a relative path to an image to load via Minecraft's + * resource providing facilities, and display that. + * + * @param prefix the prefix on which to use the provider. + * @param provider the provider to register. + */ + void addProvider(String prefix, ImageProvider provider); + + // ----------------------------------------------------------------------- // + + /** + * Look up the documentation path for the specified item stack. + * + * @param stack the stack to find the documentation path for. + * @return the path to the page, null if none is known. + */ + String pathFor(ItemStack stack); + + /** + * Look up the documentation for the specified block in the world. + * + * @param world the world containing the block. + * @param x the X coordinate of the block. + * @param y the Y coordinate of the block. + * @param z the Z coordinate of the block. + * @return the path to the page, null if none is known. + */ + String pathFor(World world, int x, int y, int z); + + /** + * Get the content of the documentation page at the specified location. + *

+ * The provided path may contain the special variable %LANGUAGE%, + * which will be resolved to the currently set language, falling back to + * en_US. + * + * @param path the path of the page to get the content of. + * @return the content of the page, or null if none exists. + */ + Iterable contentFor(String path); + + /** + * Get the image renderer for the specified image path. + *

+ * This will look for {@link ImageProvider}s registered for a prefix in the + * specified path. If there is no match, or the matched content provider + * does not provide a renderer, this will return null. + * + * @param path the path to the image to get the renderer for. + * @return the custom renderer for that path. + */ + ImageRenderer imageFor(String path); + + // ----------------------------------------------------------------------- // + + /** + * Open the manual for the specified player. + *

+ * If you wish to display a specific page, call {@link #navigate(String)} + * after this function returns, with the path to the page to show. + * + * @param player the player to open the manual for. + */ + void openFor(EntityPlayer player); + + /** + * Reset the history of the manual. + */ + void reset(); + + /** + * Navigate to a page in the manual. + * + * @param path the path to navigate to. + */ + void navigate(String path); +} diff --git a/src/api/java/li/cil/oc/api/detail/NetworkAPI.java b/src/api/java/li/cil/oc/api/detail/NetworkAPI.java new file mode 100755 index 000000000..b28b82e42 --- /dev/null +++ b/src/api/java/li/cil/oc/api/detail/NetworkAPI.java @@ -0,0 +1,163 @@ +package li.cil.oc.api.detail; + +import li.cil.oc.api.network.Environment; +import li.cil.oc.api.network.Node; +import li.cil.oc.api.network.Packet; +import li.cil.oc.api.network.Visibility; +import li.cil.oc.api.network.WirelessEndpoint; +import net.minecraft.nbt.NBTTagCompound; +import net.minecraft.tileentity.TileEntity; + +public interface NetworkAPI { + /** + * Tries to add a tile entity's network node(s) at the specified coordinates + * to adjacent networks. + *

+ * If the tile entity implements {@link Environment} its one node will be + * connected to any existing adjacent tile entity nodes. If none exist a + * new network with the specified tile entity's node as its sole entry. + *

+ * If the tile entity is a {@link li.cil.oc.api.network.SidedEnvironment} + * the same rules as for simple environments apply, except that the + * respective for each side is used when connecting, and each side's node + * is added to its own new network, if necessary. + * + * @param tileEntity the tile entity to initialize. + */ + void joinOrCreateNetwork(TileEntity tileEntity); + + /** + * Creates a new network with the specified node as its initial node. + *

+ * This can be used to create networks that are not bound to any tile + * entity. For example, this is used to create the internal networks of + * robots. + * + * @param node the node to create the network for. + * @throws IllegalArgumentException if the node already is in a network. + */ + void joinNewNetwork(Node node); + + // ----------------------------------------------------------------------- // + + /** + * Makes a wireless endpoint join the wireless network defined by the mod. + *

+ * OpenComputers tracks endpoints to which to send wireless packets sent + * via the {@link #sendWirelessPacket(WirelessEndpoint, double, Packet)} + * method. The packets will only be sent to endpoints registered + * with the network. + *

+ * Important: when your endpoint is removed from the world, + * you must ensure it is also removed from the network! + * + * @param endpoint the endpoint to register with the network. + */ + void joinWirelessNetwork(WirelessEndpoint endpoint); + + /** + * Updates a wireless endpoint in the wireless network. + *

+ * This is more efficient than removing and then adding the node again, as + * it only performs the update if the position significantly changed since + * the last time the position was updated (more than 0.5 along any axis). + *

+ * Calling this for an endpoint that was not added before does nothing. + * + * @param endpoint the endpoint for which to update the position. + */ + void updateWirelessNetwork(WirelessEndpoint endpoint); + + /** + * Removes a wireless endpoint from the wireless network. + *

+ * This must be called when an endpoint becomes invalid, otherwise it will + * remain in the network! + *

+ * Calling this for an endpoint that was not added before does nothing. + * + * @param endpoint the endpoint to remove from the wireless network. + */ + void leaveWirelessNetwork(WirelessEndpoint endpoint); + + /** + * Sends a packet via the wireless network. + *

+ * This will look for all other registered wireless endpoints in range of + * the sender and submit the packets to them. Whether another end point is + * reached depends on the distance and potential obstacles between the + * sender and the receiver (harder blocks require a stronger signal to be + * penetrated). + * + * @param source the endpoint that is sending the message. + * @param strength the signal strength with which to send the packet. + * @param packet the packet to send. + */ + void sendWirelessPacket(WirelessEndpoint source, double strength, Packet packet); + + // ----------------------------------------------------------------------- // + + /** + * Factory function for creating new nodes. + *

+ * Use this to create a node for your environment (e.g. tile entity). This + * will return a builder that can be used to further specialize the node, + * making it either a component node (for callbacks), a connector node + * (for power interaction) or both. + *

+ * Example use: + *

+     * class YourThing extends TileEntity implements Environment {
+     *     private ComponentConnector node_ =
+     *         api.Network.newNode(this, Visibility.Network).
+     *             withComponent("your_thing").
+     *             withConnector(32).
+     *             create();
+     *
+     *     public Node node() { return node_; }
+     *
+     *     // ...
+     * }
+     * 
+ *

+ * Note that the reachability specified here is the general + * availability of the created node to other nodes in the network. Special + * rules apply to components, which have a visibility that is used + * to control how they can be reached from computers. For example, network + * cards have a reachability of Visibility.Network, to + * allow them to communicate with each other, but a visibility of + * Visibility.Neighbors to avoid other computers in the network + * to see the card (i.e. only the user programs running on the computer the + * card installed in can see interact with it). + * + * @param host the environment the node is created for. + * @param reachability the reachability of the node. + * @return a new node builder. + */ + Builder.NodeBuilder newNode(Environment host, Visibility reachability); + + /** + * Creates a new network packet as it would be sent or received by a + * network card. + *

+ * These packets can be forwarded by switches and access points. For wired + * transmission they must be sent over a node's send method, with the + * message name being network.message. + * + * @param source the address of the sending node. + * @param destination the address of the destination, or null + * for a broadcast. + * @param port the port to send the packet to. + * @param data the payload of the packet. + * @return the new packet. + */ + Packet newPacket(String source, String destination, int port, Object[] data); + + /** + * Re-creates a network packet from a previously stored state. + * + * @param nbt the tag to load the packet from. + * @return the loaded packet. + */ + Packet newPacket(NBTTagCompound nbt); +} \ No newline at end of file diff --git a/src/api/java/li/cil/oc/api/detail/package-info.java b/src/api/java/li/cil/oc/api/detail/package-info.java new file mode 100755 index 000000000..d33ae2f40 --- /dev/null +++ b/src/api/java/li/cil/oc/api/detail/package-info.java @@ -0,0 +1,6 @@ +/** + * This package contains implementation detail interfaces. You will not have to + * interact with these interfaces directly (except for the Builder), + * and you particularly should not implement these interfaces yourself. + */ +package li.cil.oc.api.detail; \ No newline at end of file diff --git a/src/api/java/li/cil/oc/api/driver/Block.java b/src/api/java/li/cil/oc/api/driver/Block.java new file mode 100755 index 000000000..895a629bf --- /dev/null +++ b/src/api/java/li/cil/oc/api/driver/Block.java @@ -0,0 +1,62 @@ +package li.cil.oc.api.driver; + +import li.cil.oc.api.network.ManagedEnvironment; +import net.minecraft.world.World; + +/** + * Interface for block component drivers. + *

+ * This driver type is used for components that are blocks, i.e. that can be + * placed in the world, but cannot be modified to or don't want to have their + * {@link net.minecraft.tileentity.TileEntity} implement one of the interfaces + * for environments ({@link li.cil.oc.api.network.Environment} or + * {@link li.cil.oc.api.network.SidedEnvironment}). + *

+ * A block driver is used by Adapter blocks to check its neighbors and + * whether those neighbors should be treated as components or not. If a driver + * is present, it will be used to create a {@link ManagedEnvironment} that is + * managed by the adapter. + *

+ * Note that it is possible to write one driver that supports as many different + * blocks as you wish. I'd recommend writing one per device (type), though, to + * keep things modular. + */ +public interface Block { + /** + * Used to determine the block types this driver handles. + *

+ * This is used to determine which driver to use for a block placed next to + * an Adapter block. Note that the return value should not change + * over time; if it does, though, an already installed component will not + * be removed, since this value is only checked when scanning blocks. You + * can force this by sending a neighbor block change notification. + * + * @param world the world in which the block to check lives. + * @param x the X coordinate of the block to check. + * @param y the Y coordinate of the block to check. + * @param z the Z coordinate of the block to check. + * @return true if the block is supported; false otherwise. + */ + boolean worksWith(World world, int x, int y, int z); + + /** + * Create a new managed environment interfacing the specified block. + *

+ * This is used to connect the component to the component network when it + * is detected next to an Adapter. Components that are not part of + * the component network probably don't make much sense (can't think of any + * uses at this time), but you may still opt to not implement this - i.e. + * it is safe to return null here. + *

+ * This is expected to return a new instance each time it is + * called. The created instance's life cycle is managed by the + * Adapter block that caused its creation. + * + * @param world the world containing the block to get the environment for. + * @param x the X coordinate of the block to get the environment for. + * @param y the Y coordinate of the block to get the environment for. + * @param z the Z coordinate of the block to get the environment for. + * @return the environment for the block at that location. + */ + ManagedEnvironment createEnvironment(World world, int x, int y, int z); +} \ No newline at end of file diff --git a/src/api/java/li/cil/oc/api/driver/Converter.java b/src/api/java/li/cil/oc/api/driver/Converter.java new file mode 100755 index 000000000..8eccc321c --- /dev/null +++ b/src/api/java/li/cil/oc/api/driver/Converter.java @@ -0,0 +1,30 @@ +package li.cil.oc.api.driver; + +import java.util.Map; + +/** + * A converter is a callback that can be used to transparently convert Java + * types to something that can be pushed to a machine's architecture. + *

+ * Note that converters operating on the same object type may override each + * other when using the same keys in the resulting Map. The order in + * which converters are called depends on the order they were registered in. + */ +public interface Converter { + /** + * Converts a type to a Map. + *

+ * The keys and values in the resulting map will be converted in turn. + * If after those conversions the map still contains unsupported values, + * they will not be retained. + *

+ * The conversion result should be placed into the the passed map, i.e. the + * map will represent the original object. For example, if the value had a + * field name, add a key name to the map with the value + * of that field. + * + * @param value the value to convert. + * @param output the map conversion results are accumulated into. + */ + void convert(Object value, Map output); +} diff --git a/src/api/java/li/cil/oc/api/driver/EnvironmentAware.java b/src/api/java/li/cil/oc/api/driver/EnvironmentAware.java new file mode 100755 index 000000000..340d8a73e --- /dev/null +++ b/src/api/java/li/cil/oc/api/driver/EnvironmentAware.java @@ -0,0 +1,37 @@ +package li.cil.oc.api.driver; + +import li.cil.oc.api.network.Environment; +import net.minecraft.item.ItemStack; + +/** + * This interface can be added to either item or block drivers. + *

+ * It is used to statically query the type of environment that would be created + * for the block or item represented by an item stack. This is used to provide + * automatically generated ingame help in the NEI usage screen, for example. + *

+ * For item drivers this will usually be pretty simple to implement, assuming + * the driver only ever generates one type of environment - just return the + * class of it and you're done. + *

+ * For block drivers there is a bit more work involved, since you have to check + * if the item is the item block that corresponds to the supported block type. + * This should usually not be an issue either, though. + */ +public interface EnvironmentAware { + /** + * Get the type of environment that would be created for the specified + * block or item. + *

+ * Note that for block drivers this is called for any type of item stack. + *

+ * For item drivers this is only called if {@link Item#worksWith(ItemStack)} + * returns true. + * + * @param stack the item stack representing a block or item to get the + * related environment type for. + * @return the type of environment this driver would produce, or + * null if the block or item is not supported. + */ + Class providedEnvironment(ItemStack stack); +} diff --git a/src/api/java/li/cil/oc/api/driver/EnvironmentHost.java b/src/api/java/li/cil/oc/api/driver/EnvironmentHost.java new file mode 100755 index 000000000..505068131 --- /dev/null +++ b/src/api/java/li/cil/oc/api/driver/EnvironmentHost.java @@ -0,0 +1,52 @@ +package li.cil.oc.api.driver; + +import net.minecraft.world.World; + +/** + * To be implemented by 'hosts' of components. + *

+ * This is what's passed to drivers as the host when creating an environment. + * It is generally used to represent the components' location in the world. + *

+ * You will only need to implement this if you intend to host components, e.g. + * by providing a custom computer case or such. In OpenComputers this interface + * is usually implemented directly by the tile entities acting as the host, so + * in most cases you should be able to cast this to TileEntity for + * more options, if necessary. + */ +public interface EnvironmentHost { + /** + * The world the container lives in. + */ + World world(); + + /** + * The container's X position in the world. + *

+ * For tile entities this is the centered position. For example, + * if the tile entity is located at (0, 2, 3) this will be 0.5. + */ + double xPosition(); + + /** + * The container's Y position in the world. + *

+ * For tile entities this is the centered position. For example, + * if the tile entity is located at (0, 2, 3) this will be 2.5. + */ + double yPosition(); + + /** + * The container's Z position in the world. + *

+ * For tile entities this is the centered position. For example, + * if the tile entity is located at (0, 2, 3) this will be 3.5. + */ + double zPosition(); + + /** + * Marks the container as "changed" so that it knows it has to be saved + * again in the next world save. + */ + void markChanged(); +} diff --git a/src/api/java/li/cil/oc/api/driver/Item.java b/src/api/java/li/cil/oc/api/driver/Item.java new file mode 100755 index 000000000..6ad94678e --- /dev/null +++ b/src/api/java/li/cil/oc/api/driver/Item.java @@ -0,0 +1,114 @@ +package li.cil.oc.api.driver; + +import li.cil.oc.api.network.ManagedEnvironment; +import net.minecraft.item.ItemStack; +import net.minecraft.nbt.NBTTagCompound; + +/** + * Interface for item component drivers. + *

+ * This driver type is used for components that are items, i.e. that can be + * inserted into computers and robots. An example for this are internal drives, + * memory and graphic cards. + *

+ * When trying to add an item to a computer the list of registered drivers is + * queried using the drivers' worksWith functions. The first driver + * that replies positively and whose check against the slot type is successful, + * i.e. for which the slot matches the slot it should be inserted into, + * will be used as the component's driver and the component will be added. If no + * driver is found the item will be rejected and cannot be installed. + *

+ * Note that it is possible to write one driver that supports as many different + * items as you wish. I'd recommend writing one per device (type), though, to + * keep things modular. + */ +public interface Item { + /** + * Used to determine the item types this driver handles. + *

+ * This is used to determine which driver to use for an item when it should + * be installed in a computer. Note that the return value should not change + * over time; if it does, though, an already installed component will not + * be ejected, since this value is only checked when adding components. + *

+ * This is a context-agnostic variant used mostly for "house-keeping" + * stuff, such as querying slot types and tier. + * + * @param stack the item to check. + * @return true if the item is supported; false otherwise. + */ + boolean worksWith(ItemStack stack); + + /** + * Create a new managed environment interfacing the specified item. + *

+ * This is used to connect the component to the component network when it is + * added to a computer, for example. The only kind of component that does + * not need to be connected to the component network is probably memory, and + * there's a built-in driver for that. You may still opt to not implement + * this - i.e. it is safe to return null here. + *

+ * Keep in mind that the host's location may change if the owner is + * a robot. This is important if you cache the location somewhere. For + * example, the wireless network card checks in a robot movement event + * handler for position changes to update the index structure used for + * receiver look-up. + *

+ * This is expected to return a new instance each time it is + * called. The created instance's life cycle is managed by the host + * that caused its creation. + * + * @param stack the item stack for which to get the environment. + * @param host the host the environment will be managed by. + * @return the environment for that item. + */ + ManagedEnvironment createEnvironment(ItemStack stack, EnvironmentHost host); + + /** + * The slot type of the specified item this driver supports. + *

+ * This is used to determine into which slot of a computer the components + * this driver supports may go. This will only be called if a previous call + * to {@link #worksWith} with the same stack returned true. + * + * @param stack the item stack to get the slot type for. + * @return the slot type of the specified item. + * @see li.cil.oc.api.driver.item.Slot + */ + String slot(ItemStack stack); + + /** + * The tier of the specified item this driver supports. + *

+ * This is used to determine into which slot of a computer the components + * this driver supports may go. This will only be called if a previous call + * to {@link #worksWith} with the same stack returned true. + *

+ * Important: tiers are zero-indexed. + * + * @param stack the item stack to get the tier for. + * @return the tier of the specified item. + */ + int tier(ItemStack stack); + + /** + * Get the tag compound based on the item stack to use for persisting the + * environment associated with the specified item stack. + *

+ * This is only used if the item has an environment. This must always be a + * child tag of the item stack's own tag compound, it will not be saved + * otherwise. Use this in the unlikely case that the default name collides + * with something. The built-in components use a child tag-compound with + * the name oc:data, which will also be used if this returns + * null. + *

+ * This tag will be passed to the environment's save and + * load methods when appropriate (world save / load and when + * removed from their hosting inventory). + * + * @param stack the item to get the child tag from. + * @return the tag to use for saving and loading, or null to use + * the default tag oc:data. + */ + NBTTagCompound dataTag(ItemStack stack); +} \ No newline at end of file diff --git a/src/api/java/li/cil/oc/api/driver/MethodWhitelist.java b/src/api/java/li/cil/oc/api/driver/MethodWhitelist.java new file mode 100755 index 000000000..0bb8814c5 --- /dev/null +++ b/src/api/java/li/cil/oc/api/driver/MethodWhitelist.java @@ -0,0 +1,34 @@ +package li.cil.oc.api.driver; + +/** + * This interface can be implemented by environments to enforce a method + * whitelist. + *

+ * When drivers are collected for a block, they are combined into a compound + * driver. This compound driver will in turn generate a compound environment + * that wraps the contributing environments. Which in turn results in the + * block's component containing the list of methods from all drivers that apply + * to the block. + *

+ * In some scenarios you may not want this to happen. Instead, only a select + * list of methods should be shown for a block - for example, you may want to + * suppress inventory functionality if your TileEntity implements IInventory. + *

+ * To do so, implement this interface in the environment that you + * return from your driver's {@link Block#createEnvironment(net.minecraft.world.World, int, int, int)} + * method, and provide the names of the allowed methods from {@link #whitelistedMethods()}. + *

+ * Important: if multiple drivers apply to a single block that each + * provide a whitelist, the list of allowed methods is the intersection of the + * different whitelists! + */ +public interface MethodWhitelist { + /** + * The list of methods allowed to be exposed for blocks this driver is used + * for. Note that the names must exactly match the names of the + * methods they allow. + * + * @return the list of allowed methods. + */ + String[] whitelistedMethods(); +} diff --git a/src/api/java/li/cil/oc/api/driver/NamedBlock.java b/src/api/java/li/cil/oc/api/driver/NamedBlock.java new file mode 100755 index 000000000..f604c7683 --- /dev/null +++ b/src/api/java/li/cil/oc/api/driver/NamedBlock.java @@ -0,0 +1,36 @@ +package li.cil.oc.api.driver; + +/** + * This interface can be added to environments generated by block + * drivers to provide a 'preferred name' in case the driver is merged with + * other block drivers (interface based drivers such as for IInventory). + *

+ * This was previously to be implemented on the driver itself, but that has been + * deprecated. Implement it in the environment returned from the block driver's + * {@link Block#createEnvironment(net.minecraft.world.World, int, int, int)} + * method instead. + */ +public interface NamedBlock { + /** + * The preferred name, in case the driver is merged with others. + * + * @return the preferred name. + */ + String preferredName(); + + /** + * This is used to determine which name to use in case multiple + * environments with this interface are merged. + *

+ * If multiple named environments are merged the name of the environment + * with the highest priority is selected. Negative values are + * allowed. The recommended default value is therefore zero. + *

+ * If multiple environments with the same priority exist, the + * result is unspecified. It will usually result in the environment + * of the driver that was registered first. + * + * @return the priority with which to use this name. + */ + int priority(); +} diff --git a/src/api/java/li/cil/oc/api/driver/item/Chargeable.java b/src/api/java/li/cil/oc/api/driver/item/Chargeable.java new file mode 100755 index 000000000..38e7cbe61 --- /dev/null +++ b/src/api/java/li/cil/oc/api/driver/item/Chargeable.java @@ -0,0 +1,36 @@ +package li.cil.oc.api.driver.item; + +import net.minecraft.item.ItemStack; + +/** + * This interface can be implemented on items that go into a charger. + *

+ * This provides a generic way of charging items, even such that are not + * components. Doing it this way enables items to provide another environment, + * that is unrelated to charging, such as tablets providing their file system, + * while in the charger. + */ +public interface Chargeable { + /** + * Whether the specified item stack can be charged. + *

+ * This is primarily meant to filter meta item subitems that are not meant + * to be chargeable. + * + * @param stack the stack to check for. + * @return whether the specified item stack is chargeable. + */ + boolean canCharge(ItemStack stack); + + /** + * Called when checking if an item can be charged or should be charged. + *

+ * To discharge an item, pass a negative value. + * + * @param stack the item to charge. + * @param amount the amount to inject into the item. + * @param simulate whether to only simulate injection. + * @return the remainder of the energy that could not be injected/extracted. + */ + double charge(ItemStack stack, double amount, boolean simulate); +} diff --git a/src/api/java/li/cil/oc/api/driver/item/Container.java b/src/api/java/li/cil/oc/api/driver/item/Container.java new file mode 100755 index 000000000..dae5b8e00 --- /dev/null +++ b/src/api/java/li/cil/oc/api/driver/item/Container.java @@ -0,0 +1,39 @@ +package li.cil.oc.api.driver.item; + +import li.cil.oc.api.driver.Item; +import net.minecraft.item.ItemStack; + +/** + * May be implemented by drivers for robot upgrades that act as hotswap bays, + * i.e. which can be installed into the 'dynamic' slots, and provide on-the-fly + * changeable upgrade slots (i.e. which can be changed in the robot GUI, + * without disassembling and re-assembling the robot). + *

+ * These drivers will not be queried for environments. The reported tier is the + * maximum tier supported in the dynamic slot they provide. + */ +public interface Container extends Item { + /** + * The type of slot provided as the dynamic slot. This will usually be + * for other upgrades, but may be for any type of item component. + *

+ * While the driver's own type implicitly has to be 'Container' and could + * therefore be used instead, this makes the intention more clear. + * + * @param stack the item stack to get the provided slot type for. + * @return the slot type provided by that dynamic slot upgrade. + * @see Slot + */ + String providedSlot(ItemStack stack); + + /** + * The maximum item tier of the items that can be placed into the slot + * provided by the specified container. + *

+ * This will usually be equal to the container's tier. + * + * @param stack the item stack to the the supported tier for. + * @return the maximum tier supported by that dynamic slot upgrade. + */ + int providedTier(ItemStack stack); +} diff --git a/src/api/java/li/cil/oc/api/driver/item/HostAware.java b/src/api/java/li/cil/oc/api/driver/item/HostAware.java new file mode 100755 index 000000000..2a47a2b15 --- /dev/null +++ b/src/api/java/li/cil/oc/api/driver/item/HostAware.java @@ -0,0 +1,28 @@ +package li.cil.oc.api.driver.item; + +import li.cil.oc.api.driver.EnvironmentHost; +import li.cil.oc.api.driver.Item; +import net.minecraft.item.ItemStack; + +/** + * This interface can be added to item drivers to allow them to be picky + * about their supported host environment. + *

+ * This is useful for drivers for components that should only go into certain + * environments, such as robot specific upgrades. + */ +public interface HostAware extends Item { + /** + * Used to determine the item types this driver handles. + *

+ * This is used to determine which driver to use for an item when it should + * be installed in a computer. Note that the return value should not change + * over time; if it does, though, an already installed component will not + * be ejected, since this value is only checked when adding components. + * + * @param stack the item to check. + * @param host the type of host the environment would live in. + * @return true if the item is supported; false otherwise. + */ + boolean worksWith(ItemStack stack, Class host); +} diff --git a/src/api/java/li/cil/oc/api/driver/item/Inventory.java b/src/api/java/li/cil/oc/api/driver/item/Inventory.java new file mode 100755 index 000000000..2e0eff061 --- /dev/null +++ b/src/api/java/li/cil/oc/api/driver/item/Inventory.java @@ -0,0 +1,21 @@ +package li.cil.oc.api.driver.item; + +import li.cil.oc.api.driver.Item; +import net.minecraft.item.ItemStack; + +/** + * This interface marks drivers for robot upgrades that provide inventory + * space to the robot. Note that this is only queried upon robot assembly, + * after that the inventory is fixed! This in particular means that there + * can be no hot-swappable inventories - at least none that are represented + * in the GUI. + */ +public interface Inventory extends Item { + /** + * The additional amount of inventory space the specified item provides. + * + * @param stack the item to get the provided inventory space for. + * @return the provided inventory space. + */ + int inventoryCapacity(ItemStack stack); +} diff --git a/src/api/java/li/cil/oc/api/driver/item/Memory.java b/src/api/java/li/cil/oc/api/driver/item/Memory.java new file mode 100755 index 000000000..638971e40 --- /dev/null +++ b/src/api/java/li/cil/oc/api/driver/item/Memory.java @@ -0,0 +1,26 @@ +package li.cil.oc.api.driver.item; + +import li.cil.oc.api.driver.Item; +import net.minecraft.item.ItemStack; + +/** + * Use this interface to implement item drivers extending the memory of a computer. + *

+ * Note that the item must be installed in the actual computer's inventory to + * work. If it is installed in an external inventory the computer will not + * recognize the memory. + */ +public interface Memory extends Item { + /** + * The amount of RAM this component provides, as a generic scaling factor. + *

+ * This factor has to be interpreted by each individual architecture to fit + * its own memory needs. The actual values returned here should roughly be + * equivalent to the item's tier. For example, the built-in memory modules + * provide 1 for tier one, 2 for tier 1.5, 3 for tier 2, etc. + * + * @param stack the item to get the provided memory for. + * @return the amount of memory the specified component provides. + */ + double amount(ItemStack stack); +} diff --git a/src/api/java/li/cil/oc/api/driver/item/Processor.java b/src/api/java/li/cil/oc/api/driver/item/Processor.java new file mode 100755 index 000000000..f222b66cc --- /dev/null +++ b/src/api/java/li/cil/oc/api/driver/item/Processor.java @@ -0,0 +1,37 @@ +package li.cil.oc.api.driver.item; + +import li.cil.oc.api.driver.Item; +import li.cil.oc.api.machine.Architecture; +import net.minecraft.item.ItemStack; + +/** + * Use this interface to implement item drivers extending the number of + * components a server can control. + *

+ * Note that the item must be installed in the actual server's inventory to + * work. If it is installed in an external inventory the server will not + * recognize the memory. + */ +public interface Processor extends Item { + /** + * The additional number of components supported if this processor is + * installed in the server. + * + * @param stack the processor to get the number of supported components for. + * @return the number of additionally supported components. + */ + int supportedComponents(ItemStack stack); + + /** + * The architecture of this CPU. + *

+ * This usually controls which architecture is created for a machine the + * CPU is installed in (this is true for all computers built into OC, such + * as computer cases, server racks and robots, it my not be true for third- + * party computers). + * + * @param stack the stack representing the CPU to get the architecture for. + * @return the type of this CPU's architecture. + */ + Class architecture(ItemStack stack); +} diff --git a/src/api/java/li/cil/oc/api/driver/item/Slot.java b/src/api/java/li/cil/oc/api/driver/item/Slot.java new file mode 100755 index 000000000..3e19fc805 --- /dev/null +++ b/src/api/java/li/cil/oc/api/driver/item/Slot.java @@ -0,0 +1,22 @@ +package li.cil.oc.api.driver.item; + +/** + * Reference list of slot types in OpenComputers. + */ +public final class Slot { + public static final String None = "none"; + public static final String Any = "any"; + + public static final String Card = "card"; + public static final String ComponentBus = "component_bus"; + public static final String Container = "container"; + public static final String CPU = "cpu"; + public static final String Floppy = "floppy"; + public static final String HDD = "hdd"; + public static final String Memory = "memory"; + public static final String Tablet = "tablet"; + public static final String Upgrade = "upgrade"; + + private Slot() { + } +} diff --git a/src/api/java/li/cil/oc/api/driver/item/UpgradeRenderer.java b/src/api/java/li/cil/oc/api/driver/item/UpgradeRenderer.java new file mode 100755 index 000000000..ec1e0201c --- /dev/null +++ b/src/api/java/li/cil/oc/api/driver/item/UpgradeRenderer.java @@ -0,0 +1,95 @@ +package li.cil.oc.api.driver.item; + +import cpw.mods.fml.relauncher.Side; +import cpw.mods.fml.relauncher.SideOnly; +import li.cil.oc.api.event.RobotRenderEvent; +import li.cil.oc.api.internal.Robot; +import net.minecraft.item.ItemStack; + +import java.util.Set; + +/** + * This interface can be implemented by items to allow custom rendering of + * upgrades installed in robots. + *

+ * Upgrades installed in a robot can have an external representation. This is + * achieved by implementing this interface on an item that serves as a + * renderable upgrade. When the robot is rendered, each equipped upgrade is + * checked for this interface, and if present, the {@link #render} method + * is called. + *

+ * Note that these methods are only ever called on the client side. + */ +public interface UpgradeRenderer { + /** + * Returns which mount point this renderer wants to render the specified + * upgrade in. + *

+ * This method is used to determine which upgrade is rendered where, and is + * called for every installed, renderable upgrade. The available mount + * point names are defined in {@link MountPointName}, with the two special + * values None and Any. + *

+ * None means that the upgrade should not be rendered at all. This + * can be the case when there is no slot remaining that the upgrade may be + * rendered in. Returning null is equivalent to returning None. + *

+ * Any means that the upgrade doesn't really care where it's being + * rendered. Mount points not assigned by another upgrade preferring to be + * rendered in it will be assigned to such upgrades in the order they are + * installed in the robot. + *

+ * Returning a mount point not in the list of available mount points will + * be equivalent to returning None. + * + * @param stack the item stack of the upgrade to render. + * @param robot the robot the upgrade is rendered on. + * @param availableMountPoints the mount points available for rendering in. + * @return the mount point to reserve for the upgrade. + */ + String computePreferredMountPoint(ItemStack stack, Robot robot, Set availableMountPoints); + + /** + * Render the specified upgrade on a robot. + *

+ * The GL state has not been adjusted to the mount points position, so + * that you can perform rotations without having to revert the translation. + * It is your responsibility to position the rendered model to fit the + * specified mount point. The state will be such that the origin is the + * center of the robot. This is what the offset of the mount-point is + * relative to. + *

+ * If the stack cannot be rendered, the renderer should indicate so in + * {@link #computePreferredMountPoint}, otherwise it will still consume a mount + * point. + *

+ * You usually won't need the robot parameter, but in case you do + * need some contextual information, this should provide you with anything + * you could need. + * + * @param stack the item stack of the upgrade to render. + * @param mountPoint the mount-point to render the upgrade at. + * @param robot the robot the upgrade is rendered on. + * @param pt partial tick time, e.g. for animations. + */ + void render(ItemStack stack, RobotRenderEvent.MountPoint mountPoint, Robot robot, float pt); + + /** + * Mount point names for {@link #computePreferredMountPoint}. + */ + final class MountPointName { + public static final String None = "none"; + public static final String Any = "any"; + + public static final String TopLeft = "top_left"; + public static final String TopRight = "top_right"; + public static final String TopBack = "top_back"; + public static final String BottomLeft = "bottom_left"; + public static final String BottomRight = "bottom_right"; + public static final String BottomBack = "bottom_back"; + public static final String BottomFront = "bottom_front"; + + private MountPointName() { + } + } +} diff --git a/src/api/java/li/cil/oc/api/driver/item/package-info.java b/src/api/java/li/cil/oc/api/driver/item/package-info.java new file mode 100755 index 000000000..6c2d9fc02 --- /dev/null +++ b/src/api/java/li/cil/oc/api/driver/item/package-info.java @@ -0,0 +1,13 @@ +/** + * This package contains item driver related interfaces. + *

+ * These interfaces allow specializing item drivers to provide static data, + * that is without creating an actual environment. + */ +@cpw.mods.fml.common.API( + owner = API.ID_OWNER, + provides = "OpenComputersAPI|Driver|Item", + apiVersion = API.VERSION) +package li.cil.oc.api.driver.item; + +import li.cil.oc.api.API; \ No newline at end of file diff --git a/src/api/java/li/cil/oc/api/driver/package-info.java b/src/api/java/li/cil/oc/api/driver/package-info.java new file mode 100755 index 000000000..168e5d364 --- /dev/null +++ b/src/api/java/li/cil/oc/api/driver/package-info.java @@ -0,0 +1,13 @@ +/** + * This package contains driver related interfaces. + *

+ * Drivers are used to add items and third party blocks to the internal network, + * which is mostly used to make components wrapping them available to computers. + */ +@cpw.mods.fml.common.API( + owner = API.ID_OWNER, + provides = "OpenComputersAPI|Driver", + apiVersion = API.VERSION) +package li.cil.oc.api.driver; + +import li.cil.oc.api.API; \ No newline at end of file diff --git a/src/api/java/li/cil/oc/api/event/FileSystemAccessEvent.java b/src/api/java/li/cil/oc/api/event/FileSystemAccessEvent.java new file mode 100755 index 000000000..97d0518af --- /dev/null +++ b/src/api/java/li/cil/oc/api/event/FileSystemAccessEvent.java @@ -0,0 +1,175 @@ +package li.cil.oc.api.event; + +import cpw.mods.fml.common.eventhandler.Cancelable; +import cpw.mods.fml.common.eventhandler.Event; +import li.cil.oc.api.network.Node; +import net.minecraft.nbt.NBTTagCompound; +import net.minecraft.tileentity.TileEntity; +import net.minecraft.world.World; + +/** + * Events for handling file system access and representing it on the client. + *

+ * This is used to play file system access sounds and render disk activity + * indicators on some containers (e.g. disk drive, computer, server). + *

+ * Use this to implement rendering of disk access indicators on you own + * containers / computers / drive bays. + *

+ * Canceling this event is provided to allow registering higher priority + * event handlers that override default behavior. + */ +@Cancelable +public class FileSystemAccessEvent extends Event { + protected String sound; + + protected World world; + + protected double x; + + protected double y; + + protected double z; + + protected TileEntity tileEntity; + + protected NBTTagCompound data; + + /** + * Constructor for tile entity hosted file systems. + * + * @param sound the name of the sound effect to play. + * @param tileEntity the tile entity hosting the file system. + * @param data the additional data. + */ + protected FileSystemAccessEvent(String sound, TileEntity tileEntity, NBTTagCompound data) { + this.sound = sound; + this.world = tileEntity.getWorldObj(); + this.x = tileEntity.xCoord + 0.5; + this.y = tileEntity.yCoord + 0.5; + this.z = tileEntity.zCoord + 0.5; + this.tileEntity = tileEntity; + this.data = data; + } + + /** + * Constructor for arbitrarily hosted file systems. + * + * @param sound the name of the sound effect to play. + * @param world the world the file system lives in. + * @param x the x coordinate of the file system's container. + * @param y the y coordinate of the file system's container. + * @param z the z coordinate of the file system's container. + * @param data the additional data. + */ + protected FileSystemAccessEvent(String sound, World world, double x, double y, double z, NBTTagCompound data) { + this.sound = sound; + this.world = world; + this.x = x; + this.y = y; + this.z = z; + this.tileEntity = null; + this.data = data; + } + + /** + * The name of the sound effect to play for the file system. + */ + public String getSound() { + return sound; + } + + /** + * The world the file system lives in. + */ + public World getWorld() { + return world; + } + + /** + * The x coordinate of the file system's container. + */ + public double getX() { + return x; + } + + /** + * The y coordinate of the file system's container. + */ + public double getY() { + return y; + } + + /** + * The z coordinate of the file system's container. + */ + public double getZ() { + return z; + } + + /** + * The tile entity hosting the file system. + *

+ * Important: this can be null, which is usually the + * case when the container is an entity or item. + */ + public TileEntity getTileEntity() { + return tileEntity; + } + + /** + * Addition custom data, this is used to transmit the number of the server + * in a server rack the file system lives in, for example. + */ + public NBTTagCompound getData() { + return data; + } + + public static final class Server extends FileSystemAccessEvent { + private Node node; + + public Server(String sound, TileEntity tileEntity, Node node) { + super(sound, tileEntity, new NBTTagCompound()); + this.node = node; + } + + public Server(String sound, World world, double x, double y, double z, Node node) { + super(sound, world, x, y, z, new NBTTagCompound()); + this.node = node; + } + + /** + * The node of the file system that signalled activity. + */ + public Node getNode() { + return node; + } + } + + public static final class Client extends FileSystemAccessEvent { + /** + * Constructor for tile entity hosted file systems. + * + * @param sound the name of the sound effect to play. + * @param tileEntity the tile entity hosting the file system. + * @param data the additional data. + */ + public Client(String sound, TileEntity tileEntity, NBTTagCompound data) { + super(sound, tileEntity, data); + } + + /** + * Constructor for arbitrarily hosted file systems. + * + * @param sound the name of the sound effect to play. + * @param world the world the file system lives in. + * @param x the x coordinate of the file system's container. + * @param y the y coordinate of the file system's container. + * @param z the z coordinate of the file system's container. + * @param data the additional data. + */ + public Client(String sound, World world, double x, double y, double z, NBTTagCompound data) { + super(sound, world, x, y, z, data); + } + } +} diff --git a/src/api/java/li/cil/oc/api/event/GeolyzerEvent.java b/src/api/java/li/cil/oc/api/event/GeolyzerEvent.java new file mode 100755 index 000000000..52c9ab02a --- /dev/null +++ b/src/api/java/li/cil/oc/api/event/GeolyzerEvent.java @@ -0,0 +1,91 @@ +package li.cil.oc.api.event; + +import cpw.mods.fml.common.eventhandler.Cancelable; +import cpw.mods.fml.common.eventhandler.Event; +import li.cil.oc.api.driver.EnvironmentHost; + +import java.util.HashMap; +import java.util.Map; + +/** + * This event is fired by the geolyzer block/upgrade. + *

+ * When cancelling this event, the respective method will bail and report + * that the operation failed. + */ +@Cancelable +public abstract class GeolyzerEvent extends Event { + /** + * The container of the geolyzer component. This can either be the + * geolyzer block, or something with the geolyzer upgrade (a robot). + */ + public final EnvironmentHost host; + + /** + * The options the operation was invoked with. + */ + public final Map options; + + protected GeolyzerEvent(EnvironmentHost host, Map options) { + this.host = host; + this.options = options; + } + + /** + * Long-distance scan, getting quantified information about blocks around + * the geolyzer. By default this will yield a (noisy) listing of the + * hardness of the blocks. + *

+ * Note: the y coordinate is computed as geolyzer.y - 32 + data.index. + */ + public static class Scan extends GeolyzerEvent { + /** + * The relative x coordinate of the column being scanned. + */ + public final int scanX; + + /** + * The relative z coordinate of the column being scanned. + */ + public final int scanZ; + + /** + * The data for the column of blocks being scanned, which is an + * interval around the geolyzer itself, with the geolyzer block + * being at index 32. + */ + public final float[] data = new float[64]; + + public Scan(EnvironmentHost host, Map options, int scanX, int scanZ) { + super(host, options); + this.scanX = scanX; + this.scanZ = scanZ; + } + } + + /** + * Zero-range scan, getting in-depth information about blocks directly + * adjacent to the geolyzer. By default this will yield the block's + * name, metadata, hardness and harvest information. + */ + public static class Analyze extends GeolyzerEvent { + /** + * The position of the block to scan. + *

+ * Note: get the world via the host if you need it. + */ + public final int x, y, z; + + /** + * The retrieved data for the block being scanned. + */ + public final Map data = new HashMap(); + + public Analyze(EnvironmentHost host, Map options, int x, int y, int z) { + super(host, options); + this.x = x; + this.y = y; + this.z = z; + } + } +} diff --git a/src/api/java/li/cil/oc/api/event/RobotAnalyzeEvent.java b/src/api/java/li/cil/oc/api/event/RobotAnalyzeEvent.java new file mode 100755 index 000000000..b1497ab40 --- /dev/null +++ b/src/api/java/li/cil/oc/api/event/RobotAnalyzeEvent.java @@ -0,0 +1,21 @@ +package li.cil.oc.api.event; + +import li.cil.oc.api.internal.Agent; +import net.minecraft.entity.player.EntityPlayer; + +/** + * Fired when an analyzer is used on a robot. + *

+ * Use this to echo additional information for custom components. + */ +public class RobotAnalyzeEvent extends RobotEvent { + /** + * The player that used the analyzer. + */ + public final EntityPlayer player; + + public RobotAnalyzeEvent(Agent agent, EntityPlayer player) { + super(agent); + this.player = player; + } +} diff --git a/src/api/java/li/cil/oc/api/event/RobotAttackEntityEvent.java b/src/api/java/li/cil/oc/api/event/RobotAttackEntityEvent.java new file mode 100755 index 000000000..9d647ebd3 --- /dev/null +++ b/src/api/java/li/cil/oc/api/event/RobotAttackEntityEvent.java @@ -0,0 +1,38 @@ +package li.cil.oc.api.event; + +import cpw.mods.fml.common.eventhandler.Cancelable; +import li.cil.oc.api.internal.Agent; +import net.minecraft.entity.Entity; + +public class RobotAttackEntityEvent extends RobotEvent { + /** + * The entity that the robot will attack. + */ + public final Entity target; + + protected RobotAttackEntityEvent(Agent agent, Entity target) { + super(agent); + this.target = target; + } + + /** + * Fired when a robot is about to attack an entity. + *

+ * Canceling this event will prevent the attack. + */ + @Cancelable + public static class Pre extends RobotAttackEntityEvent { + public Pre(Agent agent, Entity target) { + super(agent, target); + } + } + + /** + * Fired after a robot has attacked an entity. + */ + public static class Post extends RobotAttackEntityEvent { + public Post(Agent agent, Entity target) { + super(agent, target); + } + } +} diff --git a/src/api/java/li/cil/oc/api/event/RobotBreakBlockEvent.java b/src/api/java/li/cil/oc/api/event/RobotBreakBlockEvent.java new file mode 100755 index 000000000..2630e95ee --- /dev/null +++ b/src/api/java/li/cil/oc/api/event/RobotBreakBlockEvent.java @@ -0,0 +1,79 @@ +package li.cil.oc.api.event; + +import cpw.mods.fml.common.eventhandler.Cancelable; +import li.cil.oc.api.internal.Agent; +import net.minecraft.world.World; + +public abstract class RobotBreakBlockEvent extends RobotEvent { + protected RobotBreakBlockEvent(Agent agent) { + super(agent); + } + + /** + * Fired when a robot is about to break a block. + *

+ * Canceling this event will prevent the block from getting broken. + */ + @Cancelable + public static class Pre extends RobotBreakBlockEvent { + /** + * The world in which the block will be broken. + */ + public final World world; + + /** + * The coordinates at which the block will be broken. + */ + public final int x, y, z; + + /** + * The time it takes to break the block. + */ + private double breakTime; + + public Pre(Agent agent, World world, int x, int y, int z, double breakTime) { + super(agent); + this.world = world; + this.x = x; + this.y = y; + this.z = z; + this.breakTime = breakTime; + } + + /** + * Sets the time it should take the robot to break the block. + *

+ * Note that the robot will still break the block instantly, but the + * robot's execution is paused for the specified amount of time. + * + * @param breakTime the time in seconds the break operation takes. + */ + public void setBreakTime(double breakTime) { + this.breakTime = Math.max(0.05, breakTime); + } + + /** + * Gets the time that it will take to break the block. + * + * @see #setBreakTime(double) + */ + public double getBreakTime() { + return breakTime; + } + } + + /** + * Fired after a robot broke a block. + */ + public static class Post extends RobotBreakBlockEvent { + /** + * The amount of experience the block that was broken generated (e.g. certain ores). + */ + public final double experience; + + public Post(Agent agent, double experience) { + super(agent); + this.experience = experience; + } + } +} diff --git a/src/api/java/li/cil/oc/api/event/RobotEvent.java b/src/api/java/li/cil/oc/api/event/RobotEvent.java new file mode 100755 index 000000000..0173809df --- /dev/null +++ b/src/api/java/li/cil/oc/api/event/RobotEvent.java @@ -0,0 +1,18 @@ +package li.cil.oc.api.event; + +import cpw.mods.fml.common.eventhandler.Event; +import li.cil.oc.api.internal.Agent; + +/** + * Base class for events generated by robots. + */ +public abstract class RobotEvent extends Event { + /** + * The robot for which this event was fired. + */ + public final Agent agent; + + protected RobotEvent(Agent agent) { + this.agent = agent; + } +} diff --git a/src/api/java/li/cil/oc/api/event/RobotExhaustionEvent.java b/src/api/java/li/cil/oc/api/event/RobotExhaustionEvent.java new file mode 100755 index 000000000..ac906ef61 --- /dev/null +++ b/src/api/java/li/cil/oc/api/event/RobotExhaustionEvent.java @@ -0,0 +1,19 @@ +package li.cil.oc.api.event; + +import li.cil.oc.api.internal.Agent; + +/** + * Fired when a robot performed an action that would cause exhaustion for a + * player. Used for the experience upgrade, for example. + */ +public class RobotExhaustionEvent extends RobotEvent { + /** + * The amount of exhaustion that was generated. + */ + public final double exhaustion; + + public RobotExhaustionEvent(Agent agent, double exhaustion) { + super(agent); + this.exhaustion = exhaustion; + } +} diff --git a/src/api/java/li/cil/oc/api/event/RobotMoveEvent.java b/src/api/java/li/cil/oc/api/event/RobotMoveEvent.java new file mode 100755 index 000000000..909628058 --- /dev/null +++ b/src/api/java/li/cil/oc/api/event/RobotMoveEvent.java @@ -0,0 +1,38 @@ +package li.cil.oc.api.event; + +import cpw.mods.fml.common.eventhandler.Cancelable; +import li.cil.oc.api.internal.Agent; +import net.minecraftforge.common.util.ForgeDirection; + +public abstract class RobotMoveEvent extends RobotEvent { + /** + * The direction in which the robot will be moving. + */ + public final ForgeDirection direction; + + protected RobotMoveEvent(Agent agent, ForgeDirection direction) { + super(agent); + this.direction = direction; + } + + /** + * Fired when a robot is about to move. + *

+ * Canceling the event will prevent the robot from moving. + */ + @Cancelable + public static class Pre extends RobotMoveEvent { + public Pre(Agent agent, ForgeDirection direction) { + super(agent, direction); + } + } + + /** + * Fired after a robot moved. + */ + public static class Post extends RobotMoveEvent { + public Post(Agent agent, ForgeDirection direction) { + super(agent, direction); + } + } +} diff --git a/src/api/java/li/cil/oc/api/event/RobotPlaceBlockEvent.java b/src/api/java/li/cil/oc/api/event/RobotPlaceBlockEvent.java new file mode 100755 index 000000000..10b32b963 --- /dev/null +++ b/src/api/java/li/cil/oc/api/event/RobotPlaceBlockEvent.java @@ -0,0 +1,53 @@ +package li.cil.oc.api.event; + +import cpw.mods.fml.common.eventhandler.Cancelable; +import li.cil.oc.api.internal.Agent; +import net.minecraft.item.ItemStack; +import net.minecraft.world.World; + +public abstract class RobotPlaceBlockEvent extends RobotEvent { + /** + * The item that is used to place the block. + */ + public final ItemStack stack; + + /** + * The world in which the block will be placed. + */ + public final World world; + + /** + * The coordinates at which the block will be placed. + */ + public final int x, y, z; + + protected RobotPlaceBlockEvent(Agent agent, ItemStack stack, World world, int x, int y, int z) { + super(agent); + this.stack = stack; + this.world = world; + this.x = x; + this.y = y; + this.z = z; + } + + /** + * Fired when a robot is about to place a block. + *

+ * Canceling this event will prevent the block from being placed. + */ + @Cancelable + public static class Pre extends RobotPlaceBlockEvent { + public Pre(Agent agent, ItemStack stack, World world, int x, int y, int z) { + super(agent, stack, world, x, y, z); + } + } + + /** + * Fired after a robot placed a block. + */ + public static class Post extends RobotPlaceBlockEvent { + public Post(Agent agent, ItemStack stack, World world, int x, int y, int z) { + super(agent, stack, world, x, y, z); + } + } +} diff --git a/src/api/java/li/cil/oc/api/event/RobotPlaceInAirEvent.java b/src/api/java/li/cil/oc/api/event/RobotPlaceInAirEvent.java new file mode 100755 index 000000000..81a4b8f18 --- /dev/null +++ b/src/api/java/li/cil/oc/api/event/RobotPlaceInAirEvent.java @@ -0,0 +1,34 @@ +package li.cil.oc.api.event; + +import li.cil.oc.api.internal.Agent; + +/** + * This event is fired when a robot tries to place a block and has no point of + * reference, i.e. the place would have to be placed in "thin air". Per default + * this fails (because players can't do this, either). + *

+ * This is primarily intended for the 'Angel Upgrade', but it might be useful + * for other upgrades, too. + */ +public class RobotPlaceInAirEvent extends RobotEvent { + private boolean isAllowed = false; + + public RobotPlaceInAirEvent(Agent agent) { + super(agent); + } + + /** + * Whether the placement is allowed. Defaults to false. + */ + public boolean isAllowed() { + return isAllowed; + } + + /** + * Set whether the placement is allowed, can be used to allow robots to + * place blocks in thin air. + */ + public void setAllowed(boolean value) { + this.isAllowed = value; + } +} diff --git a/src/api/java/li/cil/oc/api/event/RobotRenderEvent.java b/src/api/java/li/cil/oc/api/event/RobotRenderEvent.java new file mode 100755 index 000000000..3eb48ce78 --- /dev/null +++ b/src/api/java/li/cil/oc/api/event/RobotRenderEvent.java @@ -0,0 +1,81 @@ +package li.cil.oc.api.event; + +import cpw.mods.fml.common.eventhandler.Cancelable; +import li.cil.oc.api.driver.item.UpgradeRenderer; +import li.cil.oc.api.internal.Agent; +import li.cil.oc.api.internal.Robot; +import net.minecraft.item.ItemStack; +import org.lwjgl.util.vector.Vector3f; +import org.lwjgl.util.vector.Vector4f; + +import java.util.Set; + +/** + * Fired directly before the robot's chassis is rendered. + *

+ * If this event is canceled, the chassis will not be rendered. + * Component items' item renderers will still be invoked, at the possibly + * modified mount points. + *

+ * Important: the robot instance may be null in this event, in + * case the render pass is for rendering the robot in an inventory. + */ +@Cancelable +public class RobotRenderEvent extends RobotEvent { + /** + * Points on the robot at which component models may be rendered. + *

+ * By convention, components should be rendered in order of their slots, + * meaning that some components may not be rendered at all, if there are + * not enough mount points. + *

+ * The equipped tool is rendered at a fixed position, this list does not + * contain a mount point for it. + */ + public final MountPoint[] mountPoints; + + public RobotRenderEvent(Agent agent, MountPoint[] mountPoints) { + super(agent); + this.mountPoints = mountPoints; + } + + /** + * Describes points on the robot model at which components are "mounted", + * i.e. where component models may be rendered. + */ + public static class MountPoint { + /** + * The position of the mount point, relative to the robot's center. + * For the purposes of this offset, the robot is always facing south, + * i.e. the positive Z axis is 'forward'. + *

+ * Note that the rotation is applied before the translation. + */ + public final Vector3f offset = new Vector3f(0, 0, 0); + + /** + * The orientation of the mount point specified by the angle and the + * vector to rotate around. The rotation is applied in one + * GL11.glRotate() call. Note that the W component of the + * vector is the rotation. + *

+ * Note that the rotation is applied before the translation. + */ + public final Vector4f rotation = new Vector4f(0, 0, 0, 0); + + /** + * The mount point's reference name. + *

+ * This is what's used in {@link UpgradeRenderer#computePreferredMountPoint(ItemStack, Robot, Set)}. + */ + public final String name; + + public MountPoint() { + name = null; + } + + public MountPoint(String name) { + this.name = name; + } + } +} diff --git a/src/api/java/li/cil/oc/api/event/RobotUsedToolEvent.java b/src/api/java/li/cil/oc/api/event/RobotUsedToolEvent.java new file mode 100755 index 000000000..d907379ac --- /dev/null +++ b/src/api/java/li/cil/oc/api/event/RobotUsedToolEvent.java @@ -0,0 +1,70 @@ +package li.cil.oc.api.event; + +import li.cil.oc.api.internal.Agent; +import net.minecraft.item.ItemStack; + +public class RobotUsedToolEvent extends RobotEvent { + /** + * The tool that was used, before and after use. + */ + public final ItemStack toolBeforeUse, toolAfterUse; + + protected double damageRate; + + protected RobotUsedToolEvent(Agent agent, ItemStack toolBeforeUse, ItemStack toolAfterUse, double damageRate) { + super(agent); + this.toolBeforeUse = toolBeforeUse; + this.toolAfterUse = toolAfterUse; + this.damageRate = damageRate; + } + + /** + * The rate at which the used tool should lose durability, where one means + * it loses durability at full speed, zero means it doesn't lose durability + * at all. + *

+ * This value is in an interval of [0, 1]. + */ + public double getDamageRate() { + return damageRate; + } + + /** + * Fired when a robot used a tool and is about to apply the damage rate to + * partially undo the durability loss. This step is used to compute the + * rate at which the tool should lose durability, which is used by the + * experience upgrade, for example. + */ + public static class ComputeDamageRate extends RobotUsedToolEvent { + public ComputeDamageRate(Agent agent, ItemStack toolBeforeUse, ItemStack toolAfterUse, double damageRate) { + super(agent, toolBeforeUse, toolAfterUse, damageRate); + } + + /** + * Set the rate at which the tool actually gets damaged. + *

+ * This will be clamped to an iterval of [0, 1]. + * + * @param damageRate the new damage rate. + */ + public void setDamageRate(double damageRate) { + this.damageRate = Math.max(0, Math.min(1, damageRate)); + } + } + + /** + * Fired when a robot used a tool and the previously fired damage rate + * computation returned a value smaller than one. The callbacks of this + * method are responsible for applying the inverse damage the tool took. + * The toolAfterUse item stack represents the actual tool, any + * changes must be applied to that variable. The toolBeforeUse + * item stack is passed for reference, to compute the actual amount of + * durability that was lost. This may be required for tools where the + * durability is stored in the item's NBT tag. + */ + public static class ApplyDamageRate extends RobotUsedToolEvent { + public ApplyDamageRate(Agent agent, ItemStack toolBeforeUse, ItemStack toolAfterUse, double damageRate) { + super(agent, toolBeforeUse, toolAfterUse, damageRate); + } + } +} diff --git a/src/api/java/li/cil/oc/api/event/package-info.java b/src/api/java/li/cil/oc/api/event/package-info.java new file mode 100755 index 000000000..04a5d19ec --- /dev/null +++ b/src/api/java/li/cil/oc/api/event/package-info.java @@ -0,0 +1,11 @@ +/** + * Events dispatched by OpenComputers to allow other mods to hook into some + * of its functionality. + */ +@cpw.mods.fml.common.API( + owner = API.ID_OWNER, + provides = "OpenComputersAPI|Event", + apiVersion = API.VERSION) +package li.cil.oc.api.event; + +import li.cil.oc.api.API; \ No newline at end of file diff --git a/src/api/java/li/cil/oc/api/fs/FileSystem.java b/src/api/java/li/cil/oc/api/fs/FileSystem.java new file mode 100755 index 000000000..a9af47466 --- /dev/null +++ b/src/api/java/li/cil/oc/api/fs/FileSystem.java @@ -0,0 +1,246 @@ +package li.cil.oc.api.fs; + +import li.cil.oc.api.Persistable; + +import java.io.FileNotFoundException; + +/** + * Interface for file system driver compatible file systems. + *

+ * See {@link li.cil.oc.api.FileSystem} for factory methods. + *

+ * Note that all paths passed here are assumed to be absolute in the underlying + * file system implementation, meaning they do not contain any "." or "..", and + * are relative to the root of the file system. When wrapping a file system in + * a node with the provided factory functions this is automatically ensured. If + * you call any of the functions of a file system directly it is your + * responsibility to ensure the path has been cleaned up. + */ +public interface FileSystem extends Persistable { + /** + * Whether this file system is read-only. + *

+ * This is used to allow programs to check whether a file system can be + * written to without trying to open a file for writing. Note that this is + * merely used as an indicator. All mutating accessors should be implemented + * accordingly to enforce true read-only logic (i.e. {@link #open} should + * not allow opening files in write or append mode, {@link #makeDirectory} + * and such should do nothing/return false/throw an exception). + */ + boolean isReadOnly(); + + /** + * The total storage capacity of the file system, in bytes. + *

+ * For read-only systems this should return zero, for writable file systems + * that do not enforce a storage limit this should be a negative value. + * + * @return the total storage space of this file system. + */ + long spaceTotal(); + + /** + * The used storage capacity of the file system, in bytes. + * + * @return the used storage space of this file system. + */ + long spaceUsed(); + + // ----------------------------------------------------------------------- // + + /** + * Tests if a file or directory exists at the specified path. + *

+ * This function should never throw. + * + * @param path the path to check at. + * @return true if the path points to a file or directory; + * false otherwise. + */ + boolean exists(String path); + + /** + * Gets the size of a file. + *

+ * For files this should return the actual length of the file, in bytes. For + * folders this should return zero. + *

+ * If the path is invalid this should return zero. It should never throw. + * + * @param path the path to get the size for. + * @return the size of the object at the specified path. + */ + long size(String path); + + /** + * Tests whether the object at the specified path is a directory. + *

+ * If the path is invalid (i.e. there is neither a file nor a directory at + * the specified location) this should also return false. It should never + * throw. + * + * @param path the path to the object to check. + * @return true if the object is a directory; false otherwise. + */ + boolean isDirectory(String path); + + /** + * Gets the timestamp of the last time the file at the specified path was + * written to. + *

+ * For folders this should be the time they were created. + *

+ * If the path is invalid (i.e. there is neither a file nor a directory at + * the specified location) this should return zero. It should never throw. + *

+ * For read-only systems this may be zero for all queries. + * + * @param path the path to the object to get the last modified time of. + * @return the time the object was last modified. + */ + long lastModified(String path); + + /** + * Gets a list of all items in the specified folder. + *

+ * This must return the actual object names in the specified parent folder, + * not their full path. For example, for a file at /home/test, when + * doing list("/home/") this should return ["test"], + * not ["/home/test"]. + *

+ * Sub-folders should be returned with a trailing slash, to indicate that + * they are folders. + *

+ * If the folder is empty this should return an empty array. + * + * @param path the path to the folder to get the contents of. + * @return an array with the names of all objects in that folder; + * null if the specified object does not exist or is not a + * folder. + */ + String[] list(String path); + + // ----------------------------------------------------------------------- // + + /** + * Deletes a file or folder. + *

+ * This only has to support deleting single files and empty folders. If a + * directory is non-empty this may return false. If the target + * object does not exists it should return false. + *

+ * This is only available for writable file systems. For read-only systems + * it should always return false. + * + * @param path the path to the object to delete. + * @return true if the object was successfully deleted; + * false otherwise. + */ + boolean delete(String path); + + /** + * Create the specified directory. + *

+ * This should always only create a single directory. If the parent + * directory does not exists it should return false. If the target + * object already exists it should also return false. + *

+ * This is only available for writable file systems. For read-only systems + * it should always return false. + * + * @param path the path to the directory to create. + * @return true if the directory was created; false otherwise. + */ + boolean makeDirectory(String path); + + /** + * Moves / renames a file or folder. + *

+ * This is only available for writable file systems. For read-only systems + * it should always return false. + * + * @param from the name of the file or folder to move. + * @param to the location to move the file or folder to. + * @return true if the object was renamed; + * false otherwise. + * @throws FileNotFoundException if the source is not a file or folder. + */ + boolean rename(String from, String to) throws FileNotFoundException; + + /** + * Sets the time a file or folder was supposedly last modified. + *

+ * This is not available to the user side via the file system driver. It is + * intended to be used when initializing a file system to a set of known + * modification times (for example, this is used when creating a virtual + * file system from a set of real files). + *

+ * Read-only file systems may ignore this request. + * + * @param path the path of the object for which to set the modification time. + * @param time the time the object was supposedly last modified. + * @return true if the modification time was adjusted; + * false otherwise. + */ + boolean setLastModified(String path, long time); + + // ----------------------------------------------------------------------- // + + /** + * Opens a file for reading or writing. + *

+ * This should create some internal handle to the file, based on the mode + * specified. A unique ID corresponding to that handle should be returned. + * This ID can be used in {@link #getHandle} to get an abstract wrapper for + * the handle, and to allow interaction with the file. + *

+ * It is the responsibility of the file system to restore all handles to + * their previous state when it is reloaded (game loaded for example). + *

+ * Important: you should return a random value as the handle, to + * reduce the chance for conflicts. For example, a file system may be used + * in a compound of file systems (e.g. for the ROM of machines), in which + * case it is essential that the handles from different sub file + * systems do not overlap. + * + * @param path the path to the file to open. + * @param mode the mode in which to open the file. + * @return the handle to the opened file. + * @throws FileNotFoundException if the object is not a file, or + * the file cannot be opened in the + * specified mode. + */ + int open(String path, Mode mode) throws FileNotFoundException; + + /** + * Gets a wrapper for a file previously opened using {@link #open}. + *

+ * The wrapper allows interaction with the underlying file (stream) based + * on the mode it was opened in. See {@link Handle} for more details. + *

+ * If there is no such handle, this should return null, but never + * throw. + * + * @param handle the ID of the handle to get the wrapper for. + * @return the wrapper for that handle ID; null if there is no + * handle with the specified ID. + */ + Handle getHandle(int handle); + + /** + * Called when the file system is destroyed. + *

+ * This should close any open real file handles (e.g. all open I/O streams), + * but keep any internal state that may have to be persisted, for example + * for floppy disks (which are removed before they are saved so they don't + * save any open handles). + *

+ * When the filesystem is made available as a network node created via + * one of the factory functions in {@link li.cil.oc.api.FileSystem} this + * will be called whenever the node is disconnected from its network. If + * the node was used to represent an item (which will be the usual use-case, + * I imagine) this means the item was removed from its container (e.g. hard + * drive from a computer) or the container was unloaded. + */ + void close(); +} \ No newline at end of file diff --git a/src/api/java/li/cil/oc/api/fs/Handle.java b/src/api/java/li/cil/oc/api/fs/Handle.java new file mode 100755 index 000000000..759ebbfda --- /dev/null +++ b/src/api/java/li/cil/oc/api/fs/Handle.java @@ -0,0 +1,66 @@ +package li.cil.oc.api.fs; + +import java.io.IOException; + +/** + * Represents a handle to a file opened from a {@link FileSystem}. + */ +public interface Handle { + /** + * The current position in the file. + */ + long position(); + + /** + * The total length of the file. + */ + long length(); + + /** + * Closes the handle. + *

+ * For example, if there is an underlying stream, this should close that + * stream. Any future calls to {@link #read} or {@link #write} should throw + * an IOException after this function was called. + */ + void close(); + + /** + * Tries to read as much data from the file as fits into the specified + * array. + *

+ * For files opened in write or append mode this should always throw an + * exception. + * + * @param into the buffer to read the data into. + * @return the number of bytes read; -1 if there are no more bytes (EOF). + * @throws IOException if the file was opened in writing mode or an + * I/O error occurred or the file was already + * closed. + */ + int read(byte[] into) throws IOException; + + /** + * Jump to the specified position in the file, if possible. + *

+ * For files opened in write or append mode this should always throw an + * exception. + * + * @param to the position in the file to jump to. + * @return the resulting position in the file. + * @throws IOException if the file was opened in write mode. + */ + long seek(long to) throws IOException; + + /** + * Tries to write all the data from the specified array into the file. + *

+ * For files opened in read mode this should always throw an exception. + * + * @param value the data to write into the file. + * @throws IOException if the file was opened in read-only mode, or + * another I/O error occurred (no more space, + * for example), or the file was already closed. + */ + void write(byte[] value) throws IOException; +} diff --git a/src/api/java/li/cil/oc/api/fs/Label.java b/src/api/java/li/cil/oc/api/fs/Label.java new file mode 100755 index 000000000..4256c80ff --- /dev/null +++ b/src/api/java/li/cil/oc/api/fs/Label.java @@ -0,0 +1,31 @@ +package li.cil.oc.api.fs; + +import li.cil.oc.api.Persistable; + +/** + * Used by file system components to get and set the file system's label. + * + * @see li.cil.oc.api.FileSystem#asManagedEnvironment + */ +public interface Label extends Persistable { + /** + * Get the current value of this label. + *

+ * May be null if no label is set. + * + * @return the current label. + */ + String getLabel(); + + /** + * Set the new value of this label. + *

+ * May be set to null to clear the label. + *

+ * May throw an exception if the label is read-only. + * + * @param value the new label. + * @throws IllegalArgumentException if the label is read-only. + */ + void setLabel(String value); +} diff --git a/src/api/java/li/cil/oc/api/fs/Mode.java b/src/api/java/li/cil/oc/api/fs/Mode.java new file mode 100755 index 000000000..ef819f797 --- /dev/null +++ b/src/api/java/li/cil/oc/api/fs/Mode.java @@ -0,0 +1,23 @@ +package li.cil.oc.api.fs; + +/** + * Possible file modes. + *

+ * This is used when opening files from a {@link FileSystem}. + */ +public enum Mode { + /** + * Open a file in reading mode. + */ + Read, + + /** + * Open a file in writing mode, overwriting existing contents. + */ + Write, + + /** + * Open a file in append mode, writing new data after existing contents. + */ + Append +} diff --git a/src/api/java/li/cil/oc/api/fs/package-info.java b/src/api/java/li/cil/oc/api/fs/package-info.java new file mode 100755 index 000000000..394969fb7 --- /dev/null +++ b/src/api/java/li/cil/oc/api/fs/package-info.java @@ -0,0 +1,22 @@ +/** + * This package contains interfaces used by the file system implementation. + *

+ * This allows it to add custom file systems that will behave the same as the + * existing ones, particularly that can be used the same from a machine as any + * other. In the case of Lua, for example, this means it can be mounted like + * any other file system, and interacted with without further special handling. + *

+ * You will usually not need to implement these interfaces! + *

+ * Consider using the factory methods in {@link li.cil.oc.api.FileSystem} to + * create file systems and wrapper nodes for these file systems (i.e. nodes + * that can be added as component nodes to the network, so they can be used + * from computers). + */ +@cpw.mods.fml.common.API( + owner = API.ID_OWNER, + provides = "OpenComputersAPI|FileSystem", + apiVersion = API.VERSION) +package li.cil.oc.api.fs; + +import li.cil.oc.api.API; \ No newline at end of file diff --git a/src/api/java/li/cil/oc/api/internal/Adapter.java b/src/api/java/li/cil/oc/api/internal/Adapter.java new file mode 100755 index 000000000..c4526ebc7 --- /dev/null +++ b/src/api/java/li/cil/oc/api/internal/Adapter.java @@ -0,0 +1,30 @@ +package li.cil.oc.api.internal; + +import li.cil.oc.api.network.Environment; +import net.minecraft.inventory.IInventory; + +/** + * This interface is implemented as a marker by adapters. + *

+ * This is implemented by adapter tile entities, which also serve as its + * components' environment. That means you can use this to check for + * adapters by using either: + *

+ *     if (tileEntity instanceof Adapter) {
+ * 
+ * or + *
+ *     if (node.host() instanceof Adapter) {
+ * 
+ *

+ * This can also be used by {@link li.cil.oc.api.driver.item.HostAware} item + * drivers to check if the provided environment class is an adapter by checking + * for assignability, which allows for items that make no sense in adapters to + * deny being placed into them, for example. + *

+ * The only purpose is to allow identifying tile entities as adapters + * via the API, i.e. without having to link against internal classes. This + * also means that you should not implement this. + */ +public interface Adapter extends Environment, IInventory { +} diff --git a/src/api/java/li/cil/oc/api/internal/Agent.java b/src/api/java/li/cil/oc/api/internal/Agent.java new file mode 100755 index 000000000..6f78c196b --- /dev/null +++ b/src/api/java/li/cil/oc/api/internal/Agent.java @@ -0,0 +1,91 @@ +package li.cil.oc.api.internal; + +import li.cil.oc.api.machine.MachineHost; +import net.minecraft.entity.player.EntityPlayer; +import net.minecraft.inventory.IInventory; + +import java.util.UUID; + +/** + * General marker interface for autonomous agents such as robots and drones. + */ +public interface Agent extends MachineHost, Rotatable { + /** + * The equipment inventory of this agent. + *

+ * For example, for the robot this is the tool slot as well as slots + * provided by containers installed in the robot, if any. + *

+ * If an agent has no equipment slots this will be a zero-sized inventory. + */ + IInventory equipmentInventory(); + + /** + * The main inventory of this agent, which it (usually) also can + * interact with on its own. + *

+ * If an agent has no inventory slots this will be a zero-sized inventory. + */ + IInventory mainInventory(); + + /** + * Provides access to the tanks of the agent. + *

+ * If an agent has no tanks this will be a zero-sized multi-tank. + */ + MultiTank tank(); + + /** + * Gets the index of the currently selected slot in the agent's inventory. + */ + int selectedSlot(); + + /** + * Set the index of the currently selected slot. + */ + void setSelectedSlot(int index); + + /** + * Get the index of the currently selected tank. + */ + int selectedTank(); + + /** + * Set the index of the currently selected tank. + */ + void setSelectedTank(int index); + + /** + * Returns the fake player used to represent the agent as an entity for + * certain actions that require one. + *

+ * This will automatically be positioned and rotated to represent the + * agent's current position and rotation in the world. Use this to trigger + * events involving the agent that require a player entity. + *

+ * Note that this may be the common OpenComputers fake player. + * + * @return the fake player for the agent. + */ + EntityPlayer player(); + + /** + * Get the name of this agent. + */ + String name(); + + /** + * Set the name of the agent. + */ + void setName(String name); + + /** + * The name of the player owning this agent, e.g. the player that placed it. + */ + String ownerName(); + + /** + * The UUID of the player owning this agent, e.g. the player that placed it. + */ + UUID ownerUUID(); +} diff --git a/src/api/java/li/cil/oc/api/internal/Case.java b/src/api/java/li/cil/oc/api/internal/Case.java new file mode 100755 index 000000000..ee6e22f2b --- /dev/null +++ b/src/api/java/li/cil/oc/api/internal/Case.java @@ -0,0 +1,23 @@ +package li.cil.oc.api.internal; + +import li.cil.oc.api.driver.EnvironmentHost; +import li.cil.oc.api.machine.Machine; +import li.cil.oc.api.machine.MachineHost; +import li.cil.oc.api.network.Environment; +import net.minecraft.inventory.IInventory; + +/** + * This interface is implemented as a marker by computer cases. + *

+ * This is implemented by computer case tile entities. That means you can + * use this to check for computer cases by using: + *

+ *     if (tileEntity instanceof Case) {
+ * 
+ *

+ * The only purpose is to allow identifying tile entities as computer cases + * via the API, i.e. without having to link against internal classes. This + * also means that you should not implement this. + */ +public interface Case extends Environment, EnvironmentHost, MachineHost, Colored, Rotatable, Tiered, IInventory { +} diff --git a/src/api/java/li/cil/oc/api/internal/Colored.java b/src/api/java/li/cil/oc/api/internal/Colored.java new file mode 100755 index 000000000..afdc901f4 --- /dev/null +++ b/src/api/java/li/cil/oc/api/internal/Colored.java @@ -0,0 +1,25 @@ +package li.cil.oc.api.internal; + +/** + * This interface is implemented by tile entities that can be colored by + * players, such as screens, computer cases and cables. + *

+ * Colors are in the common RRGGBB format. + *

+ * This interface is not meant to be implemented, just used. + */ +public interface Colored { + /** + * Get the current color value. + * + * @return the current color value. + */ + int getColor(); + + /** + * Set the color value. + * + * @param value the new color value. + */ + void setColor(int value); +} diff --git a/src/api/java/li/cil/oc/api/internal/Database.java b/src/api/java/li/cil/oc/api/internal/Database.java new file mode 100755 index 000000000..ac9b66cf8 --- /dev/null +++ b/src/api/java/li/cil/oc/api/internal/Database.java @@ -0,0 +1,57 @@ +package li.cil.oc.api.internal; + +import net.minecraft.item.ItemStack; + +/** + * This interface is implemented by the database component. + *

+ * This allows getting actual item stack instances as referenced by callers + * of other components' callbacks, without having to push a full representation + * of an item stacks' NBT data to the VM (which can be both a memory and a + * security issue). + *

+ * To use this, you'll usually want to accept an address and either an index + * or a hash in your component's callback function, the address being that of + * a database component in the same network as your component. Alternatively + * you can omit requiring an address and just loop through the other nodes on + * the network to look for one those that have a Database as host. + */ +public interface Database { + /** + * The number of slots in this database. + */ + int size(); + + /** + * Get an item stack stored in the specified slot of this database. + *

+ * This will return null if there is no entry for the specified + * slot. If there is an entry, this will return a copy of that + * item stack, so it is safe to modify the returned stack. + * + * @param slot the slot of the item stack. + * @return the item stack stored in that slot. + */ + ItemStack getStackInSlot(int slot); + + /** + * Set the contents of a slot in the database upgrade. + *

+ * Use this to change the configuration of a database upgrade. + * + * @param slot the slot to configure. + * @param stack the stack to configure the slot to, null to clear. + */ + void setStackInSlot(int slot, ItemStack stack); + + /** + * Get an item stack with the specified hash stored in this database. + *

+ * This will return a negative value if there is no entry with a matching + * hash. + * + * @param hash the hash of the item stack. + * @return the index of item stack with the specified hash. + */ + int findStackWithHash(String hash); +} diff --git a/src/api/java/li/cil/oc/api/internal/Drone.java b/src/api/java/li/cil/oc/api/internal/Drone.java new file mode 100755 index 000000000..8ddebd61f --- /dev/null +++ b/src/api/java/li/cil/oc/api/internal/Drone.java @@ -0,0 +1,42 @@ +package li.cil.oc.api.internal; + +import li.cil.oc.api.driver.EnvironmentHost; +import net.minecraft.util.Vec3; + +/** + * This interface is implemented as a marker by drones. + *

+ * This is implemented by drones entities. That means you can use this to check + * for drones by using: + *

+ *     if (entity instanceof Drone) {
+ * 
+ *

+ * The only purpose is to allow identifying entities as drones via the API, + * i.e. without having to link against internal classes. This also means + * that you should not implement this. + */ +public interface Drone extends Agent, EnvironmentHost, Rotatable, Tiered { + /** + * Get the current target coordinates of the drone. + */ + Vec3 getTarget(); + + /** + * Set the new target coordinates of the drone. + *

+ * Note that the actual value used will use a reduced accuracy. This is + * to avoid jitter on the client and floating point inaccuracies to + * accumulate. + */ + void setTarget(Vec3 value); + + /** + * Get the drones velocity vector. + *

+ * Note that this is really just the underlying entity's motionX/Y/Z, + * so you can cast this to {@link net.minecraft.entity.Entity} and use that + * instead, if you'd like. + */ + Vec3 getVelocity(); +} diff --git a/src/api/java/li/cil/oc/api/internal/Microcontroller.java b/src/api/java/li/cil/oc/api/internal/Microcontroller.java new file mode 100755 index 000000000..585267ed3 --- /dev/null +++ b/src/api/java/li/cil/oc/api/internal/Microcontroller.java @@ -0,0 +1,21 @@ +package li.cil.oc.api.internal; + +import li.cil.oc.api.driver.EnvironmentHost; +import li.cil.oc.api.machine.MachineHost; +import li.cil.oc.api.network.Environment; + +/** + * This interface is implemented as a marker by microcontrollers. + *

+ * This is implemented by microcontroller tile entities. That means you can + * use this to check for microcontrollers by using: + *

+ *     if (tileEntity instanceof Microcontroller) {
+ * 
+ *

+ * The only purpose is to allow identifying tile entities as microcontrollers + * via the API, i.e. without having to link against internal classes. This + * also means that you should not implement this. + */ +public interface Microcontroller extends Environment, EnvironmentHost, MachineHost, Rotatable, Tiered { +} diff --git a/src/api/java/li/cil/oc/api/internal/MultiTank.java b/src/api/java/li/cil/oc/api/internal/MultiTank.java new file mode 100755 index 000000000..efaaed984 --- /dev/null +++ b/src/api/java/li/cil/oc/api/internal/MultiTank.java @@ -0,0 +1,25 @@ +package li.cil.oc.api.internal; + +import net.minecraftforge.fluids.IFluidTank; + +/** + * Implemented by objects with multiple internal tanks. + *

+ * This is specifically for containers where the side does not matter when + * accessing the internal tanks, only the index of the tank; unlike with the + * {@link net.minecraftforge.fluids.IFluidHandler} interface. + */ +public interface MultiTank { + /** + * The number of tanks currently installed. + */ + int tankCount(); + + /** + * Get the installed fluid tank with the specified index. + * + * @param index the index of the tank to get. + * @return the tank with the specified index. + */ + IFluidTank getFluidTank(int index); +} diff --git a/src/api/java/li/cil/oc/api/internal/Robot.java b/src/api/java/li/cil/oc/api/internal/Robot.java new file mode 100755 index 000000000..30eda3ced --- /dev/null +++ b/src/api/java/li/cil/oc/api/internal/Robot.java @@ -0,0 +1,80 @@ +package li.cil.oc.api.internal; + +import cpw.mods.fml.relauncher.Side; +import cpw.mods.fml.relauncher.SideOnly; +import li.cil.oc.api.driver.EnvironmentHost; +import li.cil.oc.api.network.Environment; +import net.minecraft.inventory.ISidedInventory; +import net.minecraftforge.fluids.IFluidHandler; + +/** + * This interface allows interaction with robots. + *

+ * It is intended to be used by components when installed in a robot. In that + * case, the robot in question is the tile entity passed to item driver when + * asked to create the component's environment. + *

+ * A robot's inventory contains component items and items in the actual + * inventory. The physical layout in the underlying 'real' inventory is as + * follows: + *

+ * Note that there may be no hot-swappable (or even built-in) components or + * no inventory, depending on the configuration of the robot. The hard-wired + * components cannot be changed (removed/replaced). + *

+ * This interface is not meant to be implemented, just used. + */ +public interface Robot extends Agent, Environment, EnvironmentHost, Tiered, ISidedInventory, IFluidHandler { + /** + * The number of built-in components in this robot. + */ + int componentCount(); + + /** + * Get the environment for the component in the specified slot. + *

+ * This operates on the underlying, real inventory, as described in the + * comment on top of this class. + *

+ * This will return null for slots that do not contain components, + * or components that do not have an environment (on the calling side). + * + * @param index the index of the slot from which to get the environment. + * @return the environment for that slot, or null. + */ + Environment getComponentInSlot(int index); + + /** + * Sends the state of the item in the specified slot to the client + * if it is an upgrade. + *

+ * Use this to update the state of an upgrade in that slot for rendering + * purposes (e.g. this is used by the generator upgrade to update the + * active state so the renderer knows which texture to use). + *

+ * This is necessary because inventories are not synchronized by default, + * only if a player is currently 'looking into' the inventory (opened the + * GUI of the inventory). + *

+ * The component will be saved to its item's NBT tag compound, as it would + * be when the game is saved, and then the item is re-sent to the client. + * Keep the number of calls to this function low, since each call causes a + * network packet to be sent. + */ + void synchronizeSlot(int slot); + + /** + * This essentially returns whether the robot is currently running or not. + *

+ * This is explicitly meant for client side use, to allow upgrade renderers + * to know whether to resume animations or not, based on whether the robot + * is currently powered on or not. + */ + @SideOnly(Side.CLIENT) + boolean shouldAnimate(); +} diff --git a/src/api/java/li/cil/oc/api/internal/Rotatable.java b/src/api/java/li/cil/oc/api/internal/Rotatable.java new file mode 100755 index 000000000..9310cfe99 --- /dev/null +++ b/src/api/java/li/cil/oc/api/internal/Rotatable.java @@ -0,0 +1,61 @@ +package li.cil.oc.api.internal; + +import net.minecraftforge.common.util.ForgeDirection; + +/** + * This interface is implemented by the computer case and robot tile entities + * to allow item components to query the orientation of their host, i.e. to + * allow getting the facing of the tile entity passed to their drivers' + * {@link li.cil.oc.api.driver.Item#createEnvironment(net.minecraft.item.ItemStack, li.cil.oc.api.driver.EnvironmentHost)} + * method. + *

+ * This interface is not meant to be implemented, just used. + */ +public interface Rotatable { + /** + * The current facing of a tile entity implementing this interface. + *

+ * Intended to be used to query the orientation of an item components' host. + * For example: + *

+     * class SomeDriver implements li.cil.oc.api.driver.Item {
+     *     // ...
+     *     ManagedEnvironment createEnvironment(ItemStack stack, TileEntity tileentity) {
+     *         if (tileentity instanceof Rotatable) {
+     *             ForgeDirection facing = ((Rotatable)tileentity).facing();
+     *             // Do something with facing.
+     *         }
+     *     }
+     * }
+     * 
+ * + * @return the current facing. + */ + ForgeDirection facing(); + + /** + * Converts a facing relative to the block's local coordinate + * system to a global orientation, using south as the standard + * orientation. + *

+ * For example, if the block is facing east, calling this with south will + * return east, calling it with west will return south and so on. + * + * @param value the value to translate. + * @return the translated orientation. + */ + ForgeDirection toGlobal(ForgeDirection value); + + /** + * Converts a global orientation to a facing relative to the + * block's local coordinate system, using south as the standard + * orientation. + *

+ * For example, if the block is facing east, calling this with south will + * return east, calling it with west will return north and so on. + * + * @param value the value to translate. + * @return the translated orientation. + */ + ForgeDirection toLocal(ForgeDirection value); +} diff --git a/src/api/java/li/cil/oc/api/internal/Server.java b/src/api/java/li/cil/oc/api/internal/Server.java new file mode 100755 index 000000000..5c5b8cd87 --- /dev/null +++ b/src/api/java/li/cil/oc/api/internal/Server.java @@ -0,0 +1,33 @@ +package li.cil.oc.api.internal; + +import li.cil.oc.api.driver.EnvironmentHost; +import li.cil.oc.api.machine.MachineHost; + +/** + * This interface is implemented as a marker by servers in server racks. + *

+ * This is implemented by servers in server racks, which serve as their + * computer components' environment. That means you can use this to check for + * servers by using either: + *

+ *     if (node.host() instanceof Server) {
+ * 
+ *

+ * You can get a reference to a server either via the above cast, or via a + * {@link li.cil.oc.api.internal.ServerRack}. + *

+ * The only purpose is to allow identifying node environments as servers + * via the API, i.e. without having to link against internal classes. This + * also means that you should not implement this. + */ +public interface Server extends EnvironmentHost, MachineHost, Tiered { + /** + * The server rack this server is in. + */ + ServerRack rack(); + + /** + * The slot of the server rack this server is in. + */ + int slot(); +} diff --git a/src/api/java/li/cil/oc/api/internal/ServerRack.java b/src/api/java/li/cil/oc/api/internal/ServerRack.java new file mode 100755 index 000000000..40b5f8be6 --- /dev/null +++ b/src/api/java/li/cil/oc/api/internal/ServerRack.java @@ -0,0 +1,38 @@ +package li.cil.oc.api.internal; + +import li.cil.oc.api.network.Environment; +import li.cil.oc.api.network.SidedEnvironment; +import net.minecraft.inventory.IInventory; + +/** + * This interface is implemented as a marker by server racks. + *

+ * This is implemented by server rack tile entities. That means you can use + * this to check for server racks by using: + *

+ *     if (tileEntity instanceof ServerRack) {
+ * 
+ *

+ * Server racks do not serve as environment for the computer nodes of + * servers. That's what the {@link Server}s are for. + *

+ * The only purpose is to allow identifying tile entities as server racks + * via the API, i.e. without having to link against internal classes. This + * also means that you should not implement this. + */ +public interface ServerRack extends Environment, SidedEnvironment, Rotatable, IInventory { + /** + * The machine currently hosted by the server in the specified slot. + *

+ * This can be null, for example when there is no CPU installed + * in the server in that slot, or there is no server in that slot. + * + * @return the machine currently hosted in the specified slot. + */ + Server server(int slot); + + /** + * The currently set wireless range in which remote terminals work. + */ + int range(); +} diff --git a/src/api/java/li/cil/oc/api/internal/Tablet.java b/src/api/java/li/cil/oc/api/internal/Tablet.java new file mode 100755 index 000000000..342a81223 --- /dev/null +++ b/src/api/java/li/cil/oc/api/internal/Tablet.java @@ -0,0 +1,38 @@ +package li.cil.oc.api.internal; + +import li.cil.oc.api.driver.EnvironmentHost; +import li.cil.oc.api.machine.MachineHost; +import net.minecraft.entity.player.EntityPlayer; + +/** + * This interface is implemented as a marker by tablets. + *

+ * This is implemented by the class containing tablets' logic implementation, + * which is not the tablet item! The tablet class serves as its + * computer components' environment. That means you can use this to check for + * tablets by using + *

+ *     if (node.host() instanceof Tablet) {
+ * 
+ *

+ * This can also be used by {@link li.cil.oc.api.driver.item.HostAware} item + * drivers to check if the provided environment class is a tablet by checking + * for assignability, which allows for items that make no sense in tablets to + * deny being placed into them in the assembler, for example. + *

+ * The only purpose is to allow identifying tile entities as tablets + * via the API, i.e. without having to link against internal classes. This + * also means that you should not implement this. + */ +public interface Tablet extends EnvironmentHost, MachineHost, Rotatable { + /** + * Returns the player last holding the tablet. + *

+ * Note that this value may change over the lifetime of a tablet instance. + * The player may also already have dropped the tablet - this value will + * not be set to null in that case! + * + * @return the player last holding the tablet. + */ + EntityPlayer player(); +} diff --git a/src/api/java/li/cil/oc/api/internal/Tiered.java b/src/api/java/li/cil/oc/api/internal/Tiered.java new file mode 100755 index 000000000..4e2cfc1c6 --- /dev/null +++ b/src/api/java/li/cil/oc/api/internal/Tiered.java @@ -0,0 +1,18 @@ +package li.cil.oc.api.internal; + +/** + * This is implemented by most things that are tiered in some way. + *

+ * For example, this is implemented by screens, computer cases, robots and + * drones as well as microcontrollers. If you want you can add tier specific + * behavior this way. + */ +public interface Tiered { + /** + * The zero-based tier of this... thing. + *

+ * For example, a tier one screen will return 0 here, a tier three screen + * will return 2. + */ + int tier(); +} diff --git a/src/api/java/li/cil/oc/api/internal/Wrench.java b/src/api/java/li/cil/oc/api/internal/Wrench.java new file mode 100755 index 000000000..06c6716cb --- /dev/null +++ b/src/api/java/li/cil/oc/api/internal/Wrench.java @@ -0,0 +1,30 @@ +package li.cil.oc.api.internal; + +import net.minecraft.entity.player.EntityPlayer; +import net.minecraft.world.World; + +/** + * Implemented on items that are wrench-like tools. + */ +public interface Wrench { + /** + * Called when the wrench is used. + *

+ * This is called in two scenarios, once when testing whether the wrench + * can be used on a certain block, in which case the simulate + * argument will be true, and once when actually used on a block, + * in which case the simulate argument will be false, + * allowing the tool to damage itself, for example. + *

+ * This is usually called from blocks' activation logic. + * + * @param player the player using the tool + * @param world the world containing the block the wrench is used on. + * @param x the X coordinate of the block. + * @param y the Y coordinate of the block. + * @param z the Z coordinate of the block. + * @param simulate whether to simulate the usage. + * @return whether the wrench can be used on the block. + */ + boolean useWrenchOnBlock(EntityPlayer player, World world, int x, int y, int z, boolean simulate); +} diff --git a/src/api/java/li/cil/oc/api/internal/package-info.java b/src/api/java/li/cil/oc/api/internal/package-info.java new file mode 100755 index 000000000..769993c1b --- /dev/null +++ b/src/api/java/li/cil/oc/api/internal/package-info.java @@ -0,0 +1,22 @@ +/** + * This package provides interfaces that are implemented by OC internal + * classes so that they can be checked for and used by type checking and + * casting to these interfaces. + *

+ * For example, to determine whether a tile entity is a robot, you can + * do an instanceof with the {@link li.cil.oc.api.internal.Robot} + * interface - and cast to it if you wish to access some of the provided + * functionality. + *

+ * The other main use-case is in {@link li.cil.oc.api.driver.item.HostAware} + * drivers, where these interfaces can be used to check if the item can be + * used inside the specified environment (where the environment class may + * be assignable to one of the interfaces in this package). + */ +@cpw.mods.fml.common.API( + owner = API.ID_OWNER, + provides = "OpenComputersAPI|Internal", + apiVersion = API.VERSION) +package li.cil.oc.api.internal; + +import li.cil.oc.api.API; \ No newline at end of file diff --git a/src/api/java/li/cil/oc/api/machine/Architecture.java b/src/api/java/li/cil/oc/api/machine/Architecture.java new file mode 100755 index 000000000..5503e447c --- /dev/null +++ b/src/api/java/li/cil/oc/api/machine/Architecture.java @@ -0,0 +1,167 @@ +package li.cil.oc.api.machine; + +import net.minecraft.item.ItemStack; +import net.minecraft.nbt.NBTTagCompound; + +import java.lang.annotation.*; + +/** + * This interface abstracts away any language specific details for the Machine. + *

+ * This allows the introduction of other languages, e.g. computers that run + * assembly or some other language interpreter. The two architectures included + * in OpenComputers are the native Lua architecture (using native LuaC) and the + * Java Lua architecture (using LuaJ). + */ +public interface Architecture { + /** + * Used to check if the machine is fully initialized. If this is false no + * signals for detected components will be generated. Avoids duplicate + * signals if component_added signals are generated in the + * language's startup script, for already present components (see Lua's + * init.lua script). + *

+ * This is also used to check whether limits on direct calls should be + * enforced or not - this allows a quick boot phase in the language's + * kernel logic before switching to business-as-usual. + * + * @return whether the machine is fully initialized. + */ + boolean isInitialized(); + + /** + * This is called when the amount of memory in the machine may have changed. + * This is usually triggered by the owner when its composition changes. For + * example this is called from computer cases' onInventoryChanged method. + *

+ * The amount of memory should be computed from the list of components given. + * The architecture should immediately apply the new memory size + * + * @param components the components to use for computing the total memory. + * @return whether any memory is present at all. + */ + boolean recomputeMemory(Iterable components); + + /** + * Called when a machine starts up. Used to (re-)initialize the underlying + * architecture logic. For example, for Lua this creates a new Lua state. + *

+ * This also sets up any built-in APIs for the underlying language, such as + * querying available memory, listing and interacting with components and so + * on. If this returns false the machine fails to start. + *

+ * Note that the owning machine has not necessarily been connected to a + * network when this is called, in case this is called from the machine's + * load logic. Use {@link #onConnect()} for additional initialization that + * depends on a node network (such as connecting a ROM file system). + * + * @return whether the architecture was initialized successfully. + */ + boolean initialize(); + + /** + * Called when a machine stopped. Used to clean up any handles, memory and + * so on. For example, for Lua this destroys the Lua state. + */ + void close(); + + /** + * Performs a synchronized call initialized in a previous call to + * {@link #runThreaded(boolean)}. + *

+ * This method is invoked from the main server thread, meaning it is safe + * to interact with the world without having to perform manual + * synchronization. + *

+ * This method is expected to leave the architecture in a state so it is + * prepared to next be called with runThreaded(true). For example, + * the Lua architecture will leave the results of the synchronized call on + * the stack so they can be further processed in the next call to + * runThreaded. + */ + void runSynchronized(); + + /** + * Continues execution of the machine. The first call may be used to + * initialize the machine (e.g. for Lua we load the libraries in the first + * call so that the computers boot faster). After that the architecture + * should return true from {@link #isInitialized()}. + *

+ * The resumed state is either a return from a synchronized call, when a + * synchronized call has been completed (via runSynchronized), or + * a normal yield in all other cases (sleep, interrupt, boot, ...). + *

+ * This is expected to return within a very short time, usually. For example, + * in Lua this returns as soon as the state yields, and returns at the latest + * when the Settings.timeout is reached (in which case it forces the state + * to crash). + *

+ * This is expected to consume a single signal if one is present and return. + * If returning from a synchronized call this should consume no signal. + * + * @param isSynchronizedReturn whether the architecture is resumed from an + * earlier synchronized call. In the case of + * Lua this means the results of the call are + * now on the stack, for example. + * @return the result of the execution. Used to determine the new state. + */ + ExecutionResult runThreaded(boolean isSynchronizedReturn); + + /** + * Called when the owning machine was connected to the component network. + *

+ * This can be useful for connecting custom file systems (read only memory) + * in case {@link #initialize()} was called from the machine's load logic + * (where it was not yet connected to the network). + */ + void onConnect(); + + /** + * Restores the state of this architecture as previously saved in + * {@link #save(NBTTagCompound)}. The architecture should be in the same + * state it was when it was saved after this, so it can be resumed from + * whatever state the owning machine was in when it was saved. + * + * @param nbt the tag compound to save to. + */ + void load(NBTTagCompound nbt); + + /** + * Saves the architecture for later restoration, e.g. across games or chunk + * unloads. Used to persist a machine's execution state. For native Lua this + * uses the Eris library to persist the main coroutine, for example. + *

+ * Note that the tag compound is shared with the Machine. + * + * @param nbt the tag compound to save to. + */ + void save(NBTTagCompound nbt); + + /** + * Architectures can be annotated with this to provide a nice display name. + *

+ * This is used when the name of an architecture has to be displayed to the + * user, such as when cycling architectures on a CPU. + */ + @Retention(RetentionPolicy.RUNTIME) + @Target(ElementType.TYPE) + @interface Name { + String value(); + } + + /** + * Architectures flagged with this annotation can potentially run without + * any additional memory installed in the computer. + *

+ * Use this to allow assembly of devices such as microcontrollers without + * any memory being installed in them while your architecture is being + * used by the CPU being installed. Note to actually make the machine + * start up you only need to always return true from + * {@link #recomputeMemory}. + */ + @Retention(RetentionPolicy.RUNTIME) + @Target(ElementType.TYPE) + @Inherited + @interface NoMemoryRequirements { + } +} diff --git a/src/api/java/li/cil/oc/api/machine/Arguments.java b/src/api/java/li/cil/oc/api/machine/Arguments.java new file mode 100755 index 000000000..a5a1c992c --- /dev/null +++ b/src/api/java/li/cil/oc/api/machine/Arguments.java @@ -0,0 +1,339 @@ +package li.cil.oc.api.machine; + +import net.minecraft.item.ItemStack; + +import java.util.Map; + +/** + * This interface provides access to arguments passed to a {@link Callback}. + *

+ * It allows checking for the presence of arguments in a uniform manner, taking + * care of proper type checking based on what can be passed along by Lua. + *

+ * Note that integer values fetched this way are actually double values that + * have been truncated. So if a Lua program passes 1.9 and you do a + * checkInteger you'll get a 1. + *

+ * The indexes passed to the various functions start at zero, i.e. to get the + * first argument you would use checkAny(0). This is worth mentioning + * because Lua starts its indexes at one. + */ +public interface Arguments extends Iterable { + /** + * The total number of arguments that were passed to the function. + */ + int count(); + + /** + * Get whatever is at the specified index. + *

+ * Throws an error if there are too few arguments. + *

+ * The returned object will be one of the following, based on the conversion + * performed internally: + *

+ * + * @param index the index from which to get the argument. + * @return the raw value at that index. + * @throws IllegalArgumentException if there is no argument at that index. + */ + Object checkAny(int index); + + /** + * Try to get a boolean value at the specified index. + *

+ * Throws an error if there are too few arguments. + * + * @param index the index from which to get the argument. + * @return the boolean value at the specified index. + * @throws IllegalArgumentException if there is no argument at that index, + * or if the argument is not a boolean. + */ + boolean checkBoolean(int index); + + /** + * Try to get an integer value at the specified index. + *

+ * Throws an error if there are too few arguments. + * + * @param index the index from which to get the argument. + * @return the integer value at the specified index. + * @throws IllegalArgumentException if there is no argument at that index, + * or if the argument is not a number. + */ + int checkInteger(int index); + + /** + * Try to get a double value at the specified index. + *

+ * Throws an error if there are too few arguments. + * + * @param index the index from which to get the argument. + * @return the double value at the specified index. + * @throws IllegalArgumentException if there is no argument at that index, + * or if the argument is not a number. + */ + double checkDouble(int index); + + /** + * Try to get a string value at the specified index. + *

+ * Throws an error if there are too few arguments. + *

+ * This will actually check for a byte array and convert it to a string + * using UTF-8 encoding. + * + * @param index the index from which to get the argument. + * @return the boolean value at the specified index. + * @throws IllegalArgumentException if there is no argument at that index, + * or if the argument is not a string. + */ + String checkString(int index); + + /** + * Try to get a byte array at the specified index. + *

+ * Throws an error if there are too few arguments. + * + * @param index the index from which to get the argument. + * @return the byte array at the specified index. + * @throws IllegalArgumentException if there is no argument at that index, + * or if the argument is not a byte array. + */ + byte[] checkByteArray(int index); + + /** + * Try to get a table at the specified index. + *

+ * Throws an error if there are too few arguments. + * + * @param index the index from which to get the argument. + * @return the table at the specified index. + * @throws IllegalArgumentException if there is no argument at that index, + * or if the argument is not a table. + */ + Map checkTable(int index); + + /** + * Try to get an item stack representation at the specified index. + *

+ * This is a utility method provided to convert tables to item stacks, with + * the tables being of a compatible format to that of tables generated by + * the built-in item stack converter. In particular, this takes care of + * restoring NBT data attached to the item stack. + *

+ * Throws an error if there are too few arguments. + *

+ * Important: usually you will not want to be using this. Some + * items require NBT information to fully describe them, and by default + * this information is not returned to underlying architectures when + * item stacks are returned from callbacks. This means the scripts can + * usually not provide this full information, so the roundtrip callback-> + * script->callback will be incomplete. + *

+ * Instead, please make use of the {@link li.cil.oc.api.internal.Database} + * component to get complete item stack descriptors. + * + * @param index the index from which to get the argument. + * @return the item stack at the specified index. + */ + ItemStack checkItemStack(int index); + + /** + * Get whatever is at the specified index. + *

+ * Return the specified default value if there is no such element, behaves + * like {@link #checkAny(int)} otherwise. + *

+ * The returned object will be one of the following, based on the conversion + * performed internally: + *

+ * + * @param index the index from which to get the argument. + * @return the raw value at that index. + */ + Object optAny(int index, Object def); + + /** + * Try to get a boolean value at the specified index. + *

+ * Return the specified default value if there is no such element, behaves + * like {@link #checkBoolean(int)} otherwise. + * + * @param index the index from which to get the argument. + * @return the boolean value at the specified index. + * @throws IllegalArgumentException if the argument exists and is not a boolean. + */ + boolean optBoolean(int index, boolean def); + + /** + * Try to get an integer value at the specified index. + *

+ * Return the specified default value if there is no such element, behaves + * like {@link #checkInteger(int)} otherwise. + * + * @param index the index from which to get the argument. + * @return the integer value at the specified index. + * @throws IllegalArgumentException if the argument exists but is not a number. + */ + int optInteger(int index, int def); + + /** + * Try to get a double value at the specified index. + *

+ * Return the specified default value if there is no such element, behaves + * like {@link #checkDouble(int)} otherwise. + * + * @param index the index from which to get the argument. + * @return the double value at the specified index. + * @throws IllegalArgumentException if the argument exists and is not a number. + */ + double optDouble(int index, double def); + + /** + * Try to get a string value at the specified index. + *

+ * Return the specified default value if there is no such element, behaves + * like {@link #checkString(int)} otherwise. + *

+ * This will actually check for a byte array and convert it to a string + * using UTF-8 encoding. + * + * @param index the index from which to get the argument. + * @return the boolean value at the specified index. + * @throws IllegalArgumentException if the argument exists and is not a string. + */ + String optString(int index, String def); + + /** + * Try to get a byte array at the specified index. + *

+ * Return the specified default value if there is no such element, behaves + * like {@link #checkByteArray(int)} otherwise. + * + * @param index the index from which to get the argument. + * @return the byte array at the specified index. + * @throws IllegalArgumentException if the argument exists and is not a byte array. + */ + byte[] optByteArray(int index, byte[] def); + + /** + * Try to get a table at the specified index. + *

+ * Return the specified default value if there is no such element, behaves + * like {@link #checkTable(int)} otherwise. + * + * @param index the index from which to get the argument. + * @return the table at the specified index. + * @throws IllegalArgumentException if the argument exists and is not a table. + */ + Map optTable(int index, Map def); + + /** + * Try to get an item stack at the specified index. + *

+ * Return the specified default value if there is no such element, behaves + * like {@link #checkItemStack(int)} otherwise. + * + * @param index the index from which to get the argument. + * @return the item stack at the specified index. + * @throws IllegalArgumentException if the argument exists and is not an item stack. + */ + ItemStack optItemStack(int index, ItemStack def); + + /** + * Tests whether the argument at the specified index is a boolean value. + *

+ * This will return false if there is no argument at the specified + * index, i.e. if there are too few arguments. + * + * @param index the index to check. + * @return true if the argument is a boolean; false otherwise. + */ + boolean isBoolean(int index); + + /** + * Tests whether the argument at the specified index is an integer value. + *

+ * This will return false if there is no argument at the specified + * index, i.e. if there are too few arguments. + * + * @param index the index to check. + * @return true if the argument is an integer; false otherwise. + */ + boolean isInteger(int index); + + /** + * Tests whether the argument at the specified index is a double value. + *

+ * This will return false if there is no argument at the specified + * index, i.e. if there are too few arguments. + * + * @param index the index to check. + * @return true if the argument is a double; false otherwise. + */ + boolean isDouble(int index); + + /** + * Tests whether the argument at the specified index is a string value. + *

+ * This will return false if there is no argument at the specified + * index, i.e. if there are too few arguments. + * + * @param index the index to check. + * @return true if the argument is a string; false otherwise. + */ + boolean isString(int index); + + /** + * Tests whether the argument at the specified index is a byte array. + *

+ * This will return false if there is no argument at the specified + * index, i.e. if there are too few arguments. + * + * @param index the index to check. + * @return true if the argument is a byte array; false otherwise. + */ + boolean isByteArray(int index); + + /** + * Tests whether the argument at the specified index is a table. + *

+ * This will return false if there is no argument at the specified + * index, i.e. if there are too few arguments. + * + * @param index the index to check. + * @return true if the argument is a table; false otherwise. + */ + boolean isTable(int index); + + /** + * Tests whether the argument at the specified index is an item stack. + *

+ * This will return false if there is no argument at the specified + * index, i.e. if there are too few arguments. + * + * @param index the index to check. + * @return true if the argument is an item stack; false otherwise. + */ + boolean isItemStack(int index); + + /** + * Converts the argument list to a standard Java array, converting byte + * arrays to strings automatically, since this is usually what others + * want - if you need the actual raw byte arrays, don't use this method! + * + * @return an array containing all arguments. + */ + Object[] toArray(); +} diff --git a/src/api/java/li/cil/oc/api/machine/Callback.java b/src/api/java/li/cil/oc/api/machine/Callback.java new file mode 100755 index 000000000..6c67d1662 --- /dev/null +++ b/src/api/java/li/cil/oc/api/machine/Callback.java @@ -0,0 +1,147 @@ +package li.cil.oc.api.machine; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +/** + * This annotation can be used for methods in an {@link li.cil.oc.api.network.Environment} to mark + * them for exposure to computers. + *

+ * Any method exposed like this can be enumerated and called from a computer + * that can see the node of the environment. + *

+ * Note that methods annotated with this interface must have the following + * signature: + *

+ *     Object[] f(Context context, Arguments arguments) throws Exception;
+ * 
+ *

+ * The method may return null in case it doesn't wish return anything, + * which is functionally equivalent to returning an empty array. + *

+ * To raise an error from your callback, simply throw an exception. The + * convention for Lua is to return (null, "reason") for 'soft' errors, i.e. + * errors that are no fault of the caller. For example, passing invalid + * arguments will generate an exception, requesting information and the lookup + * of said information failing should not. + * + * @see Context + * @see li.cil.oc.api.machine.Arguments + */ +@Retention(RetentionPolicy.RUNTIME) +@Target(ElementType.METHOD) +public @interface Callback { + /** + * The name under which to make the callback available. + *

+ * This defaults to the name of the annotated method if left empty. + */ + String value() default ""; + + /** + * Whether this function may be called directly from the computer's executor + * thread instead of from the server thread. + *

+ * You will have to ensure anything your callback does is thread safe when + * setting this to true. Use this for minor lookups, for example. + * This is mainly intended to allow functions to perform faster than when + * called 'synchronously' (where the call takes at least one server tick). + *

+ * Keep in mind that the node {@link li.cil.oc.api.network.Network} is not thread safe! + * Be sure you know what you're doing if you're working with a node's + * network in a direct callback. + *

+ * An exception to that rule is {@link li.cil.oc.api.network.Connector#changeBuffer(double)}, + * which is synchronized, so you can consume/produce power in direct calls. + */ + boolean direct() default false; + + /** + * The maximum number of direct calls that may be performed on this + * component in a single tick on a tier two computer. + *

+ * This can be used to throttle call speed. For example, this is used by + * graphics cards to limit the amount of net traffic can be generated by + * updating the screen they are bound to. + *

+ * You should generally apply a limit if the callback allocates persisting + * memory (i.e. memory that isn't freed once the call returns), sends + * network messages, or uses any other kind of resource for which it'd be + * bad if it were to be used from user programs in an unchecked, unregulated + * manner. + *

+ * Note that the limit does not apply when the method is invoked + * via a direct call to {@link li.cil.oc.api.network.Component#invoke(String, Context, Object...)} + * from the host side. Also, this limit is per-computer, so the method may + * be invoked more often than this per tick, if different computers call it. + *

+ * Note that the interpretation of this value changed a bit in OC 1.4. + * Before, it was the actual number of calls that could be performed on + * the component per tick. Now it's more of a general cost value: for each + * direct call a computer makes, 1/limit is subtracted from the + * computer's call budget. This budget may vary between computers, for + * example, tier three computers have a higher call budget than tier two + * computers. + */ + int limit() default Integer.MAX_VALUE; + + /** + * A documentation string that is made available to the computers the + * component this callback belongs to is connected to. This allows for + * ingame documentation of callbacks. + *

+ * You may want to give a short description of what a method does here, but + * more importantly you should document the expected parameters and return + * type here. + *

+ * Important: the recommended format is either
+ * function(arg:type[, optionArg:type]):resultType -- Description.
+ * or
+ * function(arg:type[, optionArg:type]):resultType; Description.
+ * where the argument list can be of any format (as long as it doesn't contain + * further braces), and the return type is optional. These two formats are + * recognized by OC's NEI component documentation plugin. If you use a + * different format, the doc string will be used as-is. + */ + String doc() default ""; + + /** + * Whether this callback should work like a getter. + *

+ * Callbacks that are getters do not appear as methods on a component's + * proxy. Instead they are accessed as fields, for example in Lua via the + * proxy's __index metamethod, with its only parameter being the + * accessed key. + *

+ * Note: if you wish to have a field that is read/write, that is you need + * both a getter and a setter, you have to implement them in the same + * method. This a limitation due to callback names being unique. You can + * differentiate between contexts by checking the number of arguments. + *

+ * Important: this only works in environments (for components), + * it does not work for userdata (Value objects). For + * userdata, use the apply method instead. + */ + boolean getter() default false; + + /** + * Whether this callback should work like a setter. + *

+ * Callbacks that are setters do not appear as methods on a component's + * proxy. Instead they are accessed as fields, for example in Lua via the + * proxy's __newindex metamethod, with its only two parameters + * being the accessed key and the new value. + *

+ * Note: if you wish to have a field that is read/write, that is you need + * both a getter and a setter, you have to implement them in the same + * method. This a limitation due to callback names being unique. You can + * differentiate between contexts by checking the number of arguments. + *

+ * Important: this only works in environments (for components), + * it does not work for userdata (Value objects). For + * userdata, use the unapply method instead. + */ + boolean setter() default false; +} diff --git a/src/api/java/li/cil/oc/api/machine/Context.java b/src/api/java/li/cil/oc/api/machine/Context.java new file mode 100755 index 000000000..fe82dacb6 --- /dev/null +++ b/src/api/java/li/cil/oc/api/machine/Context.java @@ -0,0 +1,167 @@ +package li.cil.oc.api.machine; + +import li.cil.oc.api.network.Node; + +/** + * This is used to provide some context to {@link li.cil.oc.api.machine.Callback}s, i.e. the + * computer from which the callback was called. + */ +public interface Context { + /** + * The node through which the computer is attached to the component network. + */ + Node node(); + + /** + * Tests whether a player is allowed to use the computer. + *

+ * If enabled in the server's configuration, computers can be owned by + * players. This means that only players that are in a computer's user list + * may interact with it, i.e. only players in the user list may: + *

+ *

+ * There are three exceptions to this rule: + *

+ *

+ * Use this to check whether you should signal something to the computer, + * for example. Note that for signals triggered via network messages there + * is a computer.checked_signal message, that expects an + * EntityPlayer as the first argument and performs this check + * before pushing the signal. + * + * @param player the name of the player to check for. + * @return whether the player with the specified name may use the computer. + */ + boolean canInteract(String player); + + /** + * Whether the computer is currently in a running state, i.e. it is neither + * paused, stopping or stopped. + *

+ * The computer thread may or may not be running while the computer is in + * this state. The computer will accept signals while in this state. + */ + boolean isRunning(); + + /** + * Whether the computer is currently in a paused state. + *

+ * The computer thread is not running while the computer is in this state. + * The computer will accept signals while in this state. + */ + boolean isPaused(); + + /** + * Starts the computer. + *

+ * The computer will enter a starting state, in which it will start + * accepting signals. The computer will start executing in the next server + * tick. + *

+ * If this is called while the computer is in a paused state it will set the + * remaining pause time to zero, but it will not immediately resume + * the computer. The computer will continue with what it did before it was + * paused in the next server tick. + *

+ * If this is called while the computer is in a non-paused and non-stopped + * state it will do nothing and return false. + * + * @return true if the computer switched to a running state. + */ + boolean start(); + + /** + * Pauses the computer for the specified duration. + *

+ * If this is called from a direct callback the computer will only + * pause after the current task has completed, possibly leading to no pause + * at all. If this is called from a non-direct callback the + * computer will be paused for the specified duration before the call + * returns. Use this to add artificial delays, e.g. for expensive or + * powerful operations (say, scanning blocks surrounding a computer). + *

+ * Important: if this is called from the server thread while + * the executor thread is running this will block until the + * computer finishes its current task. The pause will be applied after that. + * This is usually a bad thing to do, since it may lag the game, but can be + * handy to synchronize the computer thread to the server thread. For + * example, this is used when saving screens, which are controlled mostly + * via direct callbacks.
+ * However, if the computer is already in a paused state + * and the call would not lead to a longer pause this will immediately + * return false, without blocking. + *

+ * Note that the computer still accepts signals while in paused state, so + * it is generally better to avoid long pauses, to avoid a signal queue + * overflow, which would lead to some signals being dropped. + *

+ * Also note that the time left to spend paused is stored in game ticks, so + * the time resolution is actually quite limited. + *

+ * If this is called while the computer is in a paused, stopping or stopped + * state this will do nothing and return false. + * + * @param seconds the number of seconds to pause the computer for. + * @return true if the computer switched to the paused state. + */ + boolean pause(double seconds); + + /** + * Stops the computer. + *

+ * The computer will enter a stopping state, in which it will not + * accept new signals. It will be fully stopped in the next server tick. It + * is not possible to return to a running state from a stopping state. If + * start is called while in a stopping state the computer will be rebooted. + *

+ * If this is called from a callback, the callback will still finish, but + * its result will be discarded. If this is called from the server thread + * while the executor thread is running the computer in the background, it + * will finish its current work and the computer will be stopped in some + * future server tick after it has completed. + *

+ * If this is called while the computer is in a stopping or stopped state + * this will do nothing and return false. + * + * @return true if the computer switched to the stopping state. + */ + boolean stop(); + + /** + * Push a signal into the computer. + *

+ * Signals are processed sequentially by the computer, and are queued in a + * queue with limited length. If the queue is full and the signal could not + * be pushed this will return false. + *

+ * Note that only a limited amount of types is supported for arguments: + *

+ * If an unsupported type is specified the method will enqueue nothing + * instead, resulting in a nil on the Lua side, e.g., and log a + * warning. + * + * @param name the name of the signal to push. + * @param args additional arguments to pass along with the signal. + * @return true if the signal was queued; false otherwise. + */ + boolean signal(String name, Object... args); +} diff --git a/src/api/java/li/cil/oc/api/machine/ExecutionResult.java b/src/api/java/li/cil/oc/api/machine/ExecutionResult.java new file mode 100755 index 000000000..b538c05d9 --- /dev/null +++ b/src/api/java/li/cil/oc/api/machine/ExecutionResult.java @@ -0,0 +1,66 @@ +package li.cil.oc.api.machine; + +/** + * Used by the Machine to determine the result of a call to + * {@link Architecture#runThreaded(boolean)}. + *

+ * Do not implement this interface, only use the predefined internal classes. + */ +public abstract class ExecutionResult { + /** + * Indicates the machine may sleep for the specified number of ticks. This + * is merely considered a suggestion. If signals are in the queue or are + * pushed to the queue while sleeping, the sleep will be interrupted and + * {@link Architecture#runThreaded(boolean)} will be called so that the next + * signal is pushed. + */ + public static final class Sleep extends ExecutionResult { + /** + * The number of ticks to sleep. + */ + public final int ticks; + + public Sleep(int ticks) { + this.ticks = ticks; + } + } + + /** + * Indicates tha the computer should shutdown or reboot. + */ + public static final class Shutdown extends ExecutionResult { + /** + * Whether to reboot. If false the computer will stop. + */ + public final boolean reboot; + + public Shutdown(boolean reboot) { + this.reboot = reboot; + } + } + + /** + * Indicates that a synchronized call should be performed. The architecture + * is expected to be in a state that allows the next call to be to + * {@link Architecture#runSynchronized()} instead of + * {@link Architecture#runThreaded(boolean)}. This is used to perform calls + * from the server's main thread, to avoid threading issues when interacting + * with other objects in the world. + */ + public static final class SynchronizedCall extends ExecutionResult { + } + + /** + * Indicates that an error occurred and the computer should crash. + */ + public static final class Error extends ExecutionResult { + /** + * The error message. + */ + public final String message; + + public Error(String message) { + this.message = message; + } + } +} diff --git a/src/api/java/li/cil/oc/api/machine/LimitReachedException.java b/src/api/java/li/cil/oc/api/machine/LimitReachedException.java new file mode 100755 index 000000000..69d46eab6 --- /dev/null +++ b/src/api/java/li/cil/oc/api/machine/LimitReachedException.java @@ -0,0 +1,8 @@ +package li.cil.oc.api.machine; + +/** + * Used to signal that the direct call limit for the current server tick has + * been reached in {@link Machine#invoke(String, String, Object[])}. + */ +public class LimitReachedException extends Exception { +} diff --git a/src/api/java/li/cil/oc/api/machine/Machine.java b/src/api/java/li/cil/oc/api/machine/Machine.java new file mode 100755 index 000000000..43cc0667b --- /dev/null +++ b/src/api/java/li/cil/oc/api/machine/Machine.java @@ -0,0 +1,309 @@ +package li.cil.oc.api.machine; + +import li.cil.oc.api.network.ManagedEnvironment; + +import java.util.Map; + +/** + * This interface allows interacting with a Machine obtained via the factory + * method {@link li.cil.oc.api.Machine#create(MachineHost)}. + */ +@SuppressWarnings("unused") +public interface Machine extends ManagedEnvironment, Context { + /** + * The owner of the machine, usually a tile entity hosting the machine. + * + * @return the owner of the machine. + */ + MachineHost host(); + + /** + * This must be called from the host when something relevant to the + * machine changes, such as a change in the amount of available memory. + */ + void onHostChanged(); + + /** + * The underlying architecture of the machine. + *

+ * This is what actually evaluates code running on the machine, where the + * machine class itself serves as a scheduler. + *

+ * This may be null, for example when the hosting computer has + * no CPU installed. + * + * @return the architecture of this machine. + */ + Architecture architecture(); + + /** + * The list of components attached to this machine. + *

+ * This maps address to component type/name. Note that the list may not + * immediately reflect changes after components were added to the network, + * since such changes are cached in an internal list of 'added components' + * that are processed in the machine's update logic (i.e. server tick). + *

+ * This list is kept up-to-date automatically, do not mess with it. + * + * @return the list of attached components. + */ + Map components(); + + /** + * The number of connected components. + *

+ * This number can differ from components().size(), since this is + * the number of actually connected components, which is used to + * determine whether the component limit has been exceeded, for example. It + * takes into account components added but not processed, yet (see also + * {@link #components()}). + * + * @return the number of connected components. + */ + int componentCount(); + + /** + * The maximum number of components this machine can currently support. + *

+ * This is automatically recomputed based on the hosts internal components + * whenever the host calls {@link Machine#onHostChanged()}. + * + * @return the maximum number of components supported. + */ + int maxComponents(); + + /** + * Gets the amount of energy this machine consumes per tick when it is + * running. + * + * @return the energy consumed per tick by the machine. + */ + double getCostPerTick(); + + /** + * Sets the amount of energy this machine consumes per tick when it is + * running. + * + * @param value the energy consumed per tick by the machine. + */ + void setCostPerTick(double value); + + /** + * The address of the file system that holds the machine's temporary files + * (tmpfs). This may return null if either the creation of the file + * system failed, or if the size of the tmpfs has been set to zero in the + * config. + *

+ * Use this in a custom architecture to allow code do differentiate the + * tmpfs from other file systems, for example. + * + * @return the address of the tmpfs component, or null. + */ + String tmpAddress(); + + /** + * A string with the last error message. + *

+ * The error string is set either when the machine crashes (see the + * {@link #crash(String)} method), or when it fails to start (which, + * technically, is also a crash). + *

+ * When the machine started, this is reset to null. + * + * @return the last error message, or null. + */ + String lastError(); + + /** + * The current world time. This is updated each tick and provides a thread + * safe way to access the world time for architectures. + *

+ * This is equivalent to owner().world().getWorldTime(). + * + * @return the current world time. + */ + long worldTime(); + + /** + * The time that has passed since the machine was started, in seconds. + *

+ * Note that this is actually measured in world time, so the resolution is + * pretty limited. This is done to avoid 'time skips' when leaving the game + * and coming back later, resuming a persisted machine. + */ + double upTime(); + + /** + * The time spent running the underlying architecture in execution threads, + * i.e. the time spent in {@link Architecture#runThreaded(boolean)} since + * the machine was last started, in seconds. + */ + double cpuTime(); + + // ----------------------------------------------------------------------- // + + /** + * Play a sound using the machine's built-in speaker. + *

+ * This is what's used to emit beep codes when an error occurs while trying + * to start the computer, for example, and what's used for playing sounds + * when computer.beep is called. + *

+ * Be responsible in how you limit calls to this, as each call will cause + * a packet to be sent to all nearby clients, and will cause the receiving + * clients to generate the required sound sample on-the-fly. It is + * therefore recommended to not call this too frequently, and to limit the + * length of the sound to something relatively short (not longer than a few + * seconds at most). + *

+ * The audio will be played at the machine's host's location. + * + * @param frequency the frequency of the tone to generate. + * @param duration the duration of the tone to generate, in milliseconds. + */ + void beep(short frequency, short duration); + + /** + * Utility method for playing beep codes. + *

+ * The underlying functionality is similar to that of {@link #beep(short, short)}, + * except that this will play tones at a fixed frequency, and two different + * durations - in a pattern as defined in the passed string. + *

+ * This is useful for generating beep codes, such as for boot errors. It + * has the advantage of only generating a single network packet, and + * generating a single, longer sound sample for the full pattern. As such + * the same considerations should be made as for {@link #beep(short, short)}, + * i.e. prefer not to use overly long patterns. + *

+ * The passed pattern must consist of dots (.) and dashes (-), + * where a dot is short tone, and a dash is a long tone. + *

+ * The audio will be played at the machine's host's location. + * + * @param pattern the beep pattern to play. + */ + void beep(String pattern); + + /** + * Crashes the computer. + *

+ * This is exactly the same as {@link Context#stop()}, except that it also + * sets the error message in the machine. This message can be seen when the + * Analyzer is used on computer cases, for example. + * + * @param message the message to set. + * @return true if the computer switched to the stopping state. + */ + boolean crash(String message); + + /** + * Tries to pop a signal from the queue and returns it. + *

+ * Signals are stored in a FIFO queue of limited size. This method is / must + * be called by architectures regularly to process the queue. + * + * @return a signal or null if the queue was empty. + */ + Signal popSignal(); + + /** + * Get a list of all methods and their annotations of the specified object. + *

+ * The specified object can be either a {@link Value} + * or a {@link li.cil.oc.api.network.Environment}. This is useful for + * custom architectures, to allow providing a list of callback methods to + * evaluated programs. + * + * @param value the value to get the method listing for. + * @return the methods that can be called on the object. + */ + Map methods(Object value); + + /** + * Makes the machine call a component callback. + *

+ * This is intended to be used from architectures, but may be useful in + * other scenarios, too. It will make the machine call the method with the + * specified name on the attached component with the specified address. + *

+ * This will perform a visibility check, ensuring the component can be seen + * from the machine. It will also ensure that the direct call limit for + * individual callbacks is respected. + * + * @param address the address of the component to call the method on. + * @param method the name of the method to call. + * @param args the list of arguments to pass to the callback. + * @return a list of results returned by the callback, or null. + * @throws LimitReachedException when the called method supports direct + * calling, but the number of calls in this + * tick has exceeded the allowed limit. + * @throws IllegalArgumentException if there is no such component. + * @throws Exception if the callback throws an exception. + */ + Object[] invoke(String address, String method, Object[] args) throws Exception; + + /** + * Makes the machine call a value callback. + *

+ * This is intended to be used from architectures, but may be useful in + * other scenarios, too. It will make the machine call the method with the + * specified name on the specified value. + *

+ * This will will ensure that the direct call limit for individual + * callbacks is respected. + * + * @param value the value to call the method on. + * @param method the name of the method to call. + * @param args the list of arguments to pass to the callback. + * @return a list of results returned by the callback, or null. + * @throws LimitReachedException when the called method supports direct + * calling, but the number of calls in this + * tick has exceeded the allowed limit. + * @throws IllegalArgumentException if there is no such component. + * @throws Exception if the callback throws an exception. + */ + Object[] invoke(Value value, String method, Object[] args) throws Exception; + + // ----------------------------------------------------------------------- // + + /** + * The list of users registered on this machine. + *

+ * This list is used for {@link Context#canInteract(String)}. Exposed for + * informative purposes only, for example to expose it to user code. Note + * that the returned array is a copy of the internal representation of the + * user list. Changing it has no influence on the actual list. + * + * @return the list of registered users. + */ + String[] users(); + + /** + * Add a player to the machine's list of users, by username. + *

+ * This requires for the player to be online. + * + * @param name the name of the player to add as a user. + * @throws Exception if + *

+ */ + void addUser(String name) throws Exception; + + /** + * Removes a player as a user from this machine, by username. + *

+ * Unlike when adding players, the player does not have to be + * online to be removed from the list. + * + * @param name the name of the player to remove. + * @return whether the player was removed from the user list. + */ + boolean removeUser(String name); +} diff --git a/src/api/java/li/cil/oc/api/machine/MachineHost.java b/src/api/java/li/cil/oc/api/machine/MachineHost.java new file mode 100755 index 000000000..bade1f0eb --- /dev/null +++ b/src/api/java/li/cil/oc/api/machine/MachineHost.java @@ -0,0 +1,58 @@ +package li.cil.oc.api.machine; + +import li.cil.oc.api.driver.EnvironmentHost; +import li.cil.oc.api.network.Environment; +import li.cil.oc.api.network.Node; +import net.minecraft.item.ItemStack; + +/** + * This interface has to be implemented by 'hosts' of machine instances. + *

+ * It provides some context for the machine, in particular which world it is + * running in, to allow querying the time of day, for example. + */ +public interface MachineHost extends EnvironmentHost { + /** + * The machine currently hosted. + */ + Machine machine(); + + /** + * List of all components that are built into this machine directly. + *

+ * This is used to find CPUs, component buses and memory. + */ + Iterable internalComponents(); + + /** + * Get the slot a component with the specified address is in. + *

+ * This is intended to allow determining the slot of item + * components sitting in computers. For other components this returns + * negative values. + * + * @param address the address of the component to get the slot for. + * @return the index of the slot the component is in. + */ + int componentSlot(String address); + + /** + * This is called on the owner when the machine's {@link Environment#onConnect(Node)} + * method gets called. This can be useful for reacting to network events + * when the owner does not have its own node (for example, computer cases + * expose their machine's node as their own node). This callback allows it + * to connect its components (graphics cards and the like) when it is + * connected to a node network (when added to the world, for example). + * + * @param node the node that was connected to the network. + */ + void onMachineConnect(Node node); + + /** + * Like {@link #onMachineConnect(Node)}, except that this is called whenever + * the machine's {@link Environment#onDisconnect(Node)} method is called. + * + * @param node the node that was disconnected from the network. + */ + void onMachineDisconnect(Node node); +} diff --git a/src/api/java/li/cil/oc/api/machine/Signal.java b/src/api/java/li/cil/oc/api/machine/Signal.java new file mode 100755 index 000000000..f74581c67 --- /dev/null +++ b/src/api/java/li/cil/oc/api/machine/Signal.java @@ -0,0 +1,19 @@ +package li.cil.oc.api.machine; + +/** + * A single signal that was queued on a machine. + *

+ * This interface is not intended to be implemented, it only serves as a return + * type for {@link Machine#popSignal()}. + */ +public interface Signal { + /** + * The name of the signal. + */ + String name(); + + /** + * The list of arguments for the signal. + */ + Object[] args(); +} diff --git a/src/api/java/li/cil/oc/api/machine/Value.java b/src/api/java/li/cil/oc/api/machine/Value.java new file mode 100755 index 000000000..71352c28f --- /dev/null +++ b/src/api/java/li/cil/oc/api/machine/Value.java @@ -0,0 +1,77 @@ +package li.cil.oc.api.machine; + +import li.cil.oc.api.Persistable; + +/** + * A value object can be pushed to a machine like a primitive value. + *

+ * This is the only non-primitive type that can be pushed to machines, allowing + * for much more advanced interaction, since the methods on this value can be + * called from Lua directly. This is similar to component callbacks, but at the + * same time very different, because these objects can be pushed as results + * from callbacks, therefore outliving their component, for example. + *

+ * There are a few limitations too keep in mind: + *

+ *

+ * Callbacks can be defined in a manner similar to environments, e.g. using the + * {@link Callback} annotation. + */ +public interface Value extends Persistable { + /** + * This is called when the code running on a machine tries to index this + * value. + * + * @param context the context from which the method is called, usually the + * instance of the computer running the script that made + * the call. + * @param arguments the arguments passed to the method. + * @return the current value at the specified index, or null. + */ + Object apply(Context context, Arguments arguments); + + /** + * This is called when the code running on a machine tries to assign a new + * value at the specified index of this value. + *

+ * Does nothing if the value is not indexable. + * + * @param context the context from which the method is called, usually the + * instance of the computer running the script that made + * the call. + * @param arguments the arguments passed to the method. + */ + void unapply(Context context, Arguments arguments); + + /** + * This is called when the code running on a machine tries to call this + * value as a function. + *

+ * If this value is not callable, throws an exception. + * + * @param context the context from which the method is called, usually the + * instance of the computer running the script that made + * the call. + * @param arguments the arguments passed to the method. + * @return the result of the call. + * @throws RuntimeException if this value is not callable. + */ + Object[] call(Context context, Arguments arguments); + + /** + * This is called when the object's representation in the machine it was + * pushed to is garbage collected. + *

+ * Important: be aware of the consequences of pushing the same + * object to multiple machines. You should usually not do that, + * but if you do, realize this method may be called by either machine. + * + * @param context the context from which the method is called, usually the + * instance of the computer running the script that just + * garbage collected the object. + */ + void dispose(Context context); +} diff --git a/src/api/java/li/cil/oc/api/machine/package-info.java b/src/api/java/li/cil/oc/api/machine/package-info.java new file mode 100755 index 000000000..e9dfb589b --- /dev/null +++ b/src/api/java/li/cil/oc/api/machine/package-info.java @@ -0,0 +1,25 @@ +/** + * This package provides low level machine access. + *

+ * Using the {@link li.cil.oc.api.Machine} class, you can create new machine + * instances, i.e. essentially computer "cores", that will run code. This allows + * you to implement your own computer blocks. Or robots. Or whatever you come up + * with. + *

+ * The interfaces in here also allow you to implement an arbitrary new + * {@link li.cil.oc.api.machine.Architecture}, which can then be used when + * creating a new {@link li.cil.oc.api.machine.Machine} using the factory + * methods in {@link li.cil.oc.api.Machine}. An architecture could be a custom + * language interpreter, or a full blown hardware emulator for old microchips. + *

+ * There are also a couple of interfaces in here that are not meant to be + * implemented, but merely to allow accessing some mod internals in a regulated + * fashion, such as {@link li.cil.oc.api.internal.Robot}. + */ +@cpw.mods.fml.common.API( + owner = API.ID_OWNER, + provides = "OpenComputersAPI|Machine", + apiVersion = API.VERSION) +package li.cil.oc.api.machine; + +import li.cil.oc.api.API; \ No newline at end of file diff --git a/src/api/java/li/cil/oc/api/manual/ContentProvider.java b/src/api/java/li/cil/oc/api/manual/ContentProvider.java new file mode 100755 index 000000000..f36b45440 --- /dev/null +++ b/src/api/java/li/cil/oc/api/manual/ContentProvider.java @@ -0,0 +1,29 @@ +package li.cil.oc.api.manual; + +/** + * This interface allows implementation of content providers for the manual. + *

+ * Content providers can be used to provide possibly dynamic page content for + * arbitrary paths. Note that content providers have lower priority + * than content found in resource packs, i.e. content providers will only be + * queried for missing pages, so to speak. + *

+ * + * @see li.cil.oc.api.prefab.ResourceContentProvider + */ +public interface ContentProvider { + /** + * Called to get the content of a path pointed to by the specified path. + *

+ * This should provide an iterable over the lines of a Markdown document + * (with the formatting provided by the in-game manual, which is a small + * subset of "normal" Markdown). + *

+ * If this provider cannot provide the requested path, it should return + * null to indicate so, allowing other providers to be queried. + * + * @param path the path to the manual page we're looking for. + * @return the content of the document at that path, or null. + */ + Iterable getContent(String path); +} diff --git a/src/api/java/li/cil/oc/api/manual/ImageProvider.java b/src/api/java/li/cil/oc/api/manual/ImageProvider.java new file mode 100755 index 000000000..4bdb12fb4 --- /dev/null +++ b/src/api/java/li/cil/oc/api/manual/ImageProvider.java @@ -0,0 +1,28 @@ +package li.cil.oc.api.manual; + +/** + * This allows implementing custom image providers for rendering custom content + * in manual pages. Each provider can be registered for one or more prefixes, + * and will be selected based on the prefix it was registered with. It is + * expected to return an image renderer, which essentially represents the + * area it will render to. + */ +public interface ImageProvider { + /** + * Gets an image renderer for the specified data. + *

+ * The data passed here will be part of the image URL following the prefix + * that the provider was registered with. So for example, if the provider + * was registered for the prefix custom, and the image to be + * rendered in the Markdown document was [blah](custom:the data], + * then the string passed where would be the data. + *

+ * If there is no appropriate image renderer (for example, for the built-in + * item stack renderers: if the item definition is invalid), this should + * return null, it should never throw an exception. + * + * @param data the data part of the image definition. + * @return the image renderer for the data. + */ + ImageRenderer getImage(String data); +} diff --git a/src/api/java/li/cil/oc/api/manual/ImageRenderer.java b/src/api/java/li/cil/oc/api/manual/ImageRenderer.java new file mode 100755 index 000000000..2dcad21f7 --- /dev/null +++ b/src/api/java/li/cil/oc/api/manual/ImageRenderer.java @@ -0,0 +1,47 @@ +package li.cil.oc.api.manual; + +/** + * This allows implementing custom image renderers. + *

+ * Image renderers are used to draw custom areas in a manual page, defined as + * an image with a special URL, matching the prefix of a registered image + * provider. A renderer will then be used to draw something at the position + * of the image tag. + *

+ * Built-in image renderers are item, block and oredict. + */ +public interface ImageRenderer { + /** + * The width of the area this renderer uses. + *

+ * This is used to offset the OpenGL state properly before calling + * {@link #render(int, int)}, to correctly align the image horizontally. + * + * @return the width of the rendered image. + */ + int getWidth(); + + /** + * The height of the area this renderer uses. + *

+ * This is used to offset the OpenGL state properly before calling + * {@link #render(int, int)}, as well as to know where to resume rendering + * other content below the image. + * + * @return the height of the rendered image. + */ + int getHeight(); + + /** + * Render the image, with specified maximum width. + *

+ * This should render the image as is, the OpenGL state will be set up + * such that you can start drawing at (0,0,*), and render up to + * (getWidth,getHeight,*), i.e. translation and scaling are taken care + * of for you. + * + * @param mouseX the X position of the mouse relative to the element. + * @param mouseY the Y position of the mouse relative to the element. + */ + void render(int mouseX, int mouseY); +} diff --git a/src/api/java/li/cil/oc/api/manual/InteractiveImageRenderer.java b/src/api/java/li/cil/oc/api/manual/InteractiveImageRenderer.java new file mode 100755 index 000000000..cad23de5a --- /dev/null +++ b/src/api/java/li/cil/oc/api/manual/InteractiveImageRenderer.java @@ -0,0 +1,35 @@ +package li.cil.oc.api.manual; + +/** + * Allows implementing advanced image renderers that react to mouse input and + * specify customized tooltips. + *

+ * This way you can e.g. disable the default tooltip and render a more advanced + * one, or render a small GUI on a page. + */ +public interface InteractiveImageRenderer extends ImageRenderer { + /** + * Get a custom tooltip for this image renderer. + *

+ * This can be used to override the original tooltip of an image. + * + * @param tooltip the original tooltip of the element. + * @return the tooltip to use for the element. + */ + String getTooltip(String tooltip); + + /** + * Called when the mouse is clicked while over this image renderer. + *

+ * This only fires for left-clicks, because right-clicks are reserved for + * navigating back in the manual. + *

+ * If this returns false and the element is a link, the link will + * be followed. If it returns true, it will not. + * + * @param mouseX the X coordinate of the mouse, relative to the element. + * @param mouseY the Y coordinate of the mouse, relative to the element. + * @return whether the click was handled. + */ + boolean onMouseClick(int mouseX, int mouseY); +} diff --git a/src/api/java/li/cil/oc/api/manual/PathProvider.java b/src/api/java/li/cil/oc/api/manual/PathProvider.java new file mode 100755 index 000000000..c31b7f75c --- /dev/null +++ b/src/api/java/li/cil/oc/api/manual/PathProvider.java @@ -0,0 +1,45 @@ +package li.cil.oc.api.manual; + +import net.minecraft.item.ItemStack; +import net.minecraft.world.World; + +/** + * Allows providing paths for item stacks and blocks in the world. + *

+ * This is used for generating NEI usage pages with a button opening the manual + * on the page at the specified path, or for opening the manual when held in + * hand and sneak-activating a block in the world. + *

+ * This way you can easily make entries in your documentation available the + * same way OpenComputers does it itself. + *

+ * Note that you can use the special variable %LANGUAGE% in your + * paths, for language agnostic paths. These will be resolved to the currently + * set language, falling back to en_US, during actual content lookup. + */ +public interface PathProvider { + /** + * Get the path to the documentation page for the provided item stack. + *

+ * Return null if there is no known page for this item, allowing + * other providers to be queried. + * + * @param stack the stack to get the documentation path to. + * @return the path to the page, null if none is known. + */ + String pathFor(ItemStack stack); + + /** + * Get the path to the documentation page for the provided block. + *

+ * Return null if there is no known page for this item, allowing + * other providers to be queried. + * + * @param world the world containing the block. + * @param x the X coordinate of the block. + * @param y the Y coordinate of the block. + * @param z the Z coordinate of the block. + * @return the path to the page, null if none is known. + */ + String pathFor(World world, int x, int y, int z); +} diff --git a/src/api/java/li/cil/oc/api/manual/TabIconRenderer.java b/src/api/java/li/cil/oc/api/manual/TabIconRenderer.java new file mode 100755 index 000000000..45b3a329f --- /dev/null +++ b/src/api/java/li/cil/oc/api/manual/TabIconRenderer.java @@ -0,0 +1,26 @@ +package li.cil.oc.api.manual; + +import cpw.mods.fml.relauncher.Side; +import cpw.mods.fml.relauncher.SideOnly; + +/** + * Allows defining a renderer for a manual tab. + *

+ * Each renderer instance represents the single graphic it is drawing. To + * provide different graphics for different tabs you'll need to create + * multiple tab renderer instances. + *

+ * + * @see li.cil.oc.api.prefab.ItemStackTabIconRenderer + * @see li.cil.oc.api.prefab.TextureTabIconRenderer + */ +public interface TabIconRenderer { + /** + * Called when icon of a tab should be rendered. + *

+ * This should render something in a 16x16 area. The OpenGL state has been + * adjusted so that drawing starts at (0,0,0), and should go to (16,16,0). + */ + @SideOnly(Side.CLIENT) + void render(); +} diff --git a/src/api/java/li/cil/oc/api/manual/package-info.java b/src/api/java/li/cil/oc/api/manual/package-info.java new file mode 100755 index 000000000..81ae1eec8 --- /dev/null +++ b/src/api/java/li/cil/oc/api/manual/package-info.java @@ -0,0 +1,14 @@ +/** + * This package contains manual related interfaces. + *

+ * The manual represents the in-game documentation of OpenComputers and any + * other mod that may choose to add its documentation to it, such as addon + * mods. + */ +@cpw.mods.fml.common.API( + owner = API.ID_OWNER, + provides = "OpenComputersAPI|Manual", + apiVersion = API.VERSION) +package li.cil.oc.api.manual; + +import li.cil.oc.api.API; \ No newline at end of file diff --git a/src/api/java/li/cil/oc/api/network/Analyzable.java b/src/api/java/li/cil/oc/api/network/Analyzable.java new file mode 100755 index 000000000..769c12677 --- /dev/null +++ b/src/api/java/li/cil/oc/api/network/Analyzable.java @@ -0,0 +1,34 @@ +package li.cil.oc.api.network; + +import net.minecraft.entity.player.EntityPlayer; + +/** + * Allows defining a callback for when a block is right-clicked with an + * analyzer. + *

+ * This has to be implemented by a {@link net.minecraft.tileentity.TileEntity}, + * else it will have no effect. + */ +public interface Analyzable { + /** + * Called when a player uses the analyzer tool on the tile entity's block. + *

+ * This can be used to display additional block specific information in the + * player's chat when the analyzer is used (or do whatever) and may also be + * used to redirect the query to some other environment by returning some + * other environment than this. The latter is used by multi-block + * screens, for example, to always show information of the primary screen. + *

+ * Return null to suppress any further node information being + * displayed. + * + * @param player the player that used the analyzer. + * @param side the side of the block the player clicked. + * @param hitX the relative X coordinate the player clicked. + * @param hitY the relative Y coordinate the player clicked. + * @param hitZ the relative Z coordinate the player clicked. + * @return the nodes to display information for, usually an environment's + * main node (i.e. this.node()). + */ + Node[] onAnalyze(EntityPlayer player, int side, float hitX, float hitY, float hitZ); +} diff --git a/src/api/java/li/cil/oc/api/network/BlacklistedPeripheral.java b/src/api/java/li/cil/oc/api/network/BlacklistedPeripheral.java new file mode 100755 index 000000000..7598551d5 --- /dev/null +++ b/src/api/java/li/cil/oc/api/network/BlacklistedPeripheral.java @@ -0,0 +1,13 @@ +package li.cil.oc.api.network; + +/** + * This interface can be implemented by ComputerCraft peripherals, to allow + * dynamically deciding whether OC should wrap the peripheral or not. + *

+ * If you have an OC driver equivalent to your peripheral and the more broad, + * IMC based method (which works purely on class names) doesn't work for you, + * use this. + */ +public interface BlacklistedPeripheral { + boolean isPeripheralBlacklisted(); +} diff --git a/src/api/java/li/cil/oc/api/network/Component.java b/src/api/java/li/cil/oc/api/network/Component.java new file mode 100755 index 000000000..a6b53b533 --- /dev/null +++ b/src/api/java/li/cil/oc/api/network/Component.java @@ -0,0 +1,107 @@ +package li.cil.oc.api.network; + +import li.cil.oc.api.machine.Callback; +import li.cil.oc.api.machine.Context; + +import java.util.Collection; + +/** + * Components are nodes that can be addressed computers via drivers. + *

+ * Components therefore form a sub-network in the overall network, and some + * special rules apply to them. For one, components specify an additional + * kind of visibility. Component visibility may have to differ from real + * network reachability in some cases, such as network cards (which have to + * be able to communicate across the whole network, but computers should only + * "see" the cards installed directly in them). + *

+ * Unlike the {@link Node}'s network reachability, this is a dynamic value and + * can be changed at any time. For example, this is used to hide multi-block + * screen parts that are not the origin from computers in the network. + *

+ * The method responsible for dispatching network messages from computers also + * only allows sending messages to components that the computer can see, + * according to the component's visibility. Therefore nodes won't receive + * messages from computer's that should not be able to see them. + */ +public interface Component extends Node { + /** + * The name of the node. + *

+ * This should be the type name of the component represented by the node, + * since this is what is returned from component.type. As such it + * is to be expected that there be multiple nodes with the same name, but + * that those nodes all have the same underlying type (i.e. there can be + * multiple "filesystem" nodes, but they should all behave the same way). + */ + String name(); + + /** + * Get the visibility of this component. + */ + Visibility visibility(); + + /** + * Set the visibility of this component. + *

+ * Note that this cannot be higher / more visible than the reachability of + * the node. Trying to set it to a higher value will generate an exception. + * + * @throws IllegalArgumentException if the specified value is + * more visible than the node's + * reachability. + */ + void setVisibility(Visibility value); + + /** + * Tests whether this component can be seen by the specified node, + * usually representing a computer in the network. + *

+ * Important: this will always return true if the node is + * not currently in a network. + * + * @param other the computer node to check for. + * @return true if the computer can see this node; false otherwise. + */ + boolean canBeSeenFrom(Node other); + + // ----------------------------------------------------------------------- // + + /** + * The list of names of methods exposed by this component. + *

+ * This does not return the callback annotations directly, because those + * may not contain the method's name (as it defaults to the name of the + * annotated method). + *

+ * The returned collection is read-only. + */ + Collection methods(); + + /** + * Get the annotation information of a method. + *

+ * This is needed for custom architecture implementations that need to know + * if a callback is direct or not, for example. + * + * @param method the method to the the info for. + * @return the annotation of the specified method or null. + */ + Callback annotation(String method); + + /** + * Tries to call a function with the specified name on this component. + *

+ * The name of the method must be one of the names in {@link #methods()}. + * The returned array may be null if there is no return value. + * + * @param method the name of the method to call. + * @param context the context from which the method is called, usually the + * instance of the computer running the script that made + * the call. + * @param arguments the arguments passed to the method. + * @return the list of results, or null if there is no result. + * @throws NoSuchMethodException if there is no method with that name. + */ + Object[] invoke(String method, Context context, Object... arguments) throws Exception; +} diff --git a/src/api/java/li/cil/oc/api/network/ComponentConnector.java b/src/api/java/li/cil/oc/api/network/ComponentConnector.java new file mode 100755 index 000000000..969a8901d --- /dev/null +++ b/src/api/java/li/cil/oc/api/network/ComponentConnector.java @@ -0,0 +1,7 @@ +package li.cil.oc.api.network; + +/** + * For nodes that are both component and connector. + */ +public interface ComponentConnector extends Component, Connector { +} diff --git a/src/api/java/li/cil/oc/api/network/Connector.java b/src/api/java/li/cil/oc/api/network/Connector.java new file mode 100755 index 000000000..7189915bd --- /dev/null +++ b/src/api/java/li/cil/oc/api/network/Connector.java @@ -0,0 +1,97 @@ +package li.cil.oc.api.network; + +/** + * Interface for nodes that act as power connectors between their network and + * some power producer or consumer. + *

+ * For each connector a buffer is managed. Its size is initialized via the + * factory function in the network API, but can also be configured later on. + * Its current fill level can be queried and manipulated as desired. + *

+ * Each connector can take two roles: it can be a producer, feeding + * power into the network, or it can be a consumer, requiring power + * from the network to power something (or it can be both). This depends + * entirely on how you call {@link #changeBuffer}, i.e. on whether you + * fill up the connectors buffer or drain it. + *

+ * To feed power into the network, simply fill up the buffer, to consume power + * take power from the buffer. The network will balance the power between all + * buffers connected to it. The algorithm goes as follows: if there was a change + * to some buffer, computer the average power available in all buffers. Build + * two sets: those of buffers with above-average level, and those with below- + * average fill. From all above-average buffers take so much energy that they + * remain just above average fill (but only take integral values - this is to + * avoid floating point errors causing trouble). Distribute the collected energy + * equally among the below-average buffers (as good as possible). + */ +public interface Connector extends Node { + /** + * The energy stored in the local buffer. + */ + double localBuffer(); + + /** + * The size of the local buffer. + */ + double localBufferSize(); + + /** + * The accumulative energy stored across all buffers in the node's network. + */ + double globalBuffer(); + + /** + * The accumulative size of all buffers in the node's network. + */ + double globalBufferSize(); + + /** + * Try to apply the specified delta to the global buffer. + *

+ * This can be used to apply reactionary power changes. For example, a + * screen may require a certain amount of energy to refresh its display when + * a program tries to display text on it. For running costs just apply the + * same delta each tick. + *

+ * If the specified delta cannot be completely applied to the buffer, the + * remaining delta will be returned. This means that for negative values + * a part of the energy will have been consumed, though. + *

+ * If there is enough energy or no overflow this will return 0. + *

+ * Keep in mind that this change is applied to the global buffer, + * i.e. energy from multiple buffers may be consumed / multiple buffers may + * be filled. The buffer for which this method is called (i.e. this node + * instance) will be prioritized, though. + * + * @param delta the amount of energy to consume or store. + * @return the remainder of the delta that could not be applied. + */ + double changeBuffer(double delta); + + /** + * Like {@link #changeBuffer}, but will only store/consume the specified + * amount of energy if there is enough capacity/energy available. + * + * @param delta the amount of energy to consume or store. + * @return true if the energy was successfully consumed or stored. + */ + boolean tryChangeBuffer(double delta); + + /** + * Change the size of the connectors local buffer. + *

+ * If the size is reduced, any superfluous energy is distributed across + * other connectors' buffers in the network, if possible. Any surplus + * energy that cannot be stored in other buffers will be lost. + *

+ * Note that this automatically called when the connector is disconnected + * from its network to set its buffer size to zero and distribute its + * energy to other connectors in the network. + * + * @param size the new size of the local buffer. Note that this is capped + * to a minimum of zero, i.e. if a negative value is passed the + * size will be set to zero. + */ + void setLocalBufferSize(double size); +} diff --git a/src/api/java/li/cil/oc/api/network/Environment.java b/src/api/java/li/cil/oc/api/network/Environment.java new file mode 100755 index 000000000..906543874 --- /dev/null +++ b/src/api/java/li/cil/oc/api/network/Environment.java @@ -0,0 +1,113 @@ +package li.cil.oc.api.network; + +/** + * The environment of a node. + *

+ * For blocks/tile entities this will usually be the tile entity. For items + * this will usually be an object created when a component is added to a + * compatible inventory (e.g. put into a computer). + *

+ * Tile entities should implement this interface if they want to be connected + * to the component network of their neighboring blocks. If you cannot do that, + * as mentioned above, you will have to provide a driver that creates a managed + * environment for the block you wish to connect instead. + *

+ * To get some more control over which sides of your block may connect to a + * network, see {@link SidedEnvironment}. + *

+ * When a tile entity implements this interface a good way of connecting and + * disconnecting is the following pattern: + *

+ *     void updateEntity() {
+ *         super.updateEntity()
+ *         if (node != null && node.network == null) {
+ *             api.Network.joinOrCreateNetwork(this);
+ *         }
+ *     }
+ *
+ *     void onChunkUnload() {
+ *         super.onChunkUnload()
+ *         if (node != null) node.remove()
+ *     }
+ *
+ *     void invalidate() {
+ *         super.invalidate()
+ *         if (node != null) node.remove()
+ *     }
+ * 
+ *

+ * Item environments are always managed, so you will always have to provide a + * driver for items that should interact with the component network. + *

+ * To interact with environments from user code you will have to do two things: + *

    + *
  1. Make the environment's {@link #node} a {@link Component} and ensure + * its {@link Component#visibility} is set to a value where it can + * be seen by computers in the network.
  2. + *
  3. Annotate methods in the environment as {@link li.cil.oc.api.machine.Callback}s.
  4. + *
+ */ +public interface Environment { + /** + * The node this environment wraps. + *

+ * The node is the environments gateway to the component network, and thus + * its preferred way to interact with other components in the same network. + * + * @return the node this environment wraps. + */ + Node node(); + + /** + * This is called when a node is added to a network. + *

+ * This is also called for the node itself, if it was added to the network. + *

+ * At this point the node's network is never null and you can use + * it to query it for other nodes. Use this to perform initialization logic, + * such as building lists of nodes of a certain type in the network. + *

+ * For example, if node A is added to a network with nodes B and C, these + * calls are made: + *

+ */ + void onConnect(Node node); + + /** + * This is called when a node is removed from the network. + *

+ * This is also called for the node itself, when it has been removed from + * its network. Note that this is called on the node that is being removed + * only once with the node itself as the parameter. + *

+ * At this point the node's network is no longer available (null). + * Use this to perform clean-up logic such as removing references to the + * removed node. + *

+ * For example, if node A is removed from a network with nodes A, B and C, + * these calls are made: + *

+ */ + void onDisconnect(Node node); + + /** + * This is the generic message handler. + *

+ * It is called whenever this environments {@link Node} receives a message + * that was sent via one of the send methods in the {@link Network} + * or the Node itself. + * + * @param message the message to handle. + */ + void onMessage(Message message); +} diff --git a/src/api/java/li/cil/oc/api/network/FilteredEnvironment.java b/src/api/java/li/cil/oc/api/network/FilteredEnvironment.java new file mode 100755 index 000000000..9f81749f7 --- /dev/null +++ b/src/api/java/li/cil/oc/api/network/FilteredEnvironment.java @@ -0,0 +1,25 @@ +package li.cil.oc.api.network; + +/** + * This interface can be added to {@link Environment}s with a number of + * {@link li.cil.oc.api.machine.Callback}s on them, to select which of these + * callbacks should be exposed to machines dynamically. + *

+ * Important: while this allows dynamic selection of callbacks, if + * what the filter method returns changes during the lifetime of the + * environment, these changes will not be reflected in already connected + * computers. + */ +public interface FilteredEnvironment { + /** + * Whether the callback with the specified name on this environment is enabled. + *

+ * Returning true will be the same as if this interface were not + * implemented. Returning false will hide the callback with the + * specified name from machines connected to it. + * + * @param name the name of the callback to check for. + * @return whether the callback should be visible or not. + */ + boolean isCallbackEnabled(String name); +} diff --git a/src/api/java/li/cil/oc/api/network/ManagedEnvironment.java b/src/api/java/li/cil/oc/api/network/ManagedEnvironment.java new file mode 100755 index 000000000..7a1a10ea5 --- /dev/null +++ b/src/api/java/li/cil/oc/api/network/ManagedEnvironment.java @@ -0,0 +1,33 @@ +package li.cil.oc.api.network; + +import li.cil.oc.api.Persistable; + +/** + * This kind of environment is managed by either a compatible inventory, such + * as a computer or floppy drive, or by an adapter block or similar. + *

+ * This means its update and save/load methods will be called by their logical + * container. This is required for item environments, and for block + * environments that cannot be directly integrated into a block's tile entity, + * for example because you have no direct control over the block (e.g. what we + * do with the command block). + *

+ * You should not implement this interface in your tile entities, or + * weird things may happen (e.g. update and save/load being called multiple + * times). + */ +public interface ManagedEnvironment extends Environment, Persistable { + /** + * Like the method of the same name on tile entities, this is used to + * decide whether to put a component in the list of components that need + * updating, i.e. for which {@link #update()} should be called each tick. + *

+ * Return false here, if you do not need updates, to improve performance. + */ + boolean canUpdate(); + + /** + * This is called by the host of this managed environment once per tick. + */ + void update(); +} diff --git a/src/api/java/li/cil/oc/api/network/ManagedPeripheral.java b/src/api/java/li/cil/oc/api/network/ManagedPeripheral.java new file mode 100755 index 000000000..9de7a9bbc --- /dev/null +++ b/src/api/java/li/cil/oc/api/network/ManagedPeripheral.java @@ -0,0 +1,38 @@ +package li.cil.oc.api.network; + +import li.cil.oc.api.machine.Arguments; +import li.cil.oc.api.machine.Context; + +/** + * This interface can be used with an {@link Environment} + * and is intended to be used for environments wrapping a ComputerCraft + * peripheral. It could be used for other purposes as well, though. It allows + * providing method names in addition to those defined via the + * {@link li.cil.oc.api.machine.Callback} annotation, and invoking said methods. + */ +public interface ManagedPeripheral { + /** + * Get the list of methods provided by this environment, in + * addition to methods marked as callbacks. + *

+ * Returning null has the same meaning as returning an empty array, + * that being that there are no methods - in which case you don't need this + * interface! + * + * @return the list of methods provided by the environment. + */ + String[] methods(); + + /** + * Calls a method from the list provided by {@link #methods()}. + *

+ * + * @param method the name of the method to call. + * @param context the context from which the method is called. + * @param args the arguments to pass to the method. + * @return the result of calling the method. Same as for callbacks. + * @throws NoSuchMethodException if there is no method with the + * specified name. + */ + Object[] invoke(String method, Context context, Arguments args) throws Exception; +} diff --git a/src/api/java/li/cil/oc/api/network/Message.java b/src/api/java/li/cil/oc/api/network/Message.java new file mode 100755 index 000000000..980b36a63 --- /dev/null +++ b/src/api/java/li/cil/oc/api/network/Message.java @@ -0,0 +1,39 @@ +package li.cil.oc.api.network; + +/** + * This type is used to deliver messages sent in a component network. + *

+ * We use an extra class to deliver messages to nodes to make the cancel logic + * more clear (returning a boolean can get annoying very fast). + */ +public interface Message { + /** + * The node that sent the message. + * + * @return the source node. + */ + Node source(); + + /** + * The name of this message. + * + * @return the name of the message. + */ + String name(); + + /** + * The values passed along in the message. + * + * @return the message data. + */ + Object[] data(); + + /** + * Stop further propagation of a broadcast message. + *

+ * This can be used to stop further distributing messages when either + * serving a message to a specific address and there are multiple nodes + * with that address, or when serving a broadcast message. + */ + void cancel(); +} \ No newline at end of file diff --git a/src/api/java/li/cil/oc/api/network/Network.java b/src/api/java/li/cil/oc/api/network/Network.java new file mode 100755 index 000000000..3d76f0014 --- /dev/null +++ b/src/api/java/li/cil/oc/api/network/Network.java @@ -0,0 +1,225 @@ +package li.cil.oc.api.network; + +/** + * Interface for interacting with networks. + *

+ * Computers and components form ad-hoc "networks" when placed next to each + * other. They allow computers to communicate with the components attached to + * them (and nodes amongst each other) by using the network as an index + * structure. + *

+ * There are three types of nodes: + *

+ *

+ * See Node for more details on the behavior of single nodes, and in + * particular how nodes represented by tile entities should be added. + *

+ * Another important concept of node networks is reachability and visibility, + * see {@link Visibility}. + *

+ * Note that network access in general is not thread safe! Networks + * should only be accessed from the main server thread. The exception are the + * connector nodes, which can be used to consume or produce energy from other + * threads. + *

+ * IMPORTANT: do *not* implement this interface yourself and create + * instances of your own network implementation; this will lead to + * incompatibilities with the built-in network implementation (which can only + * merge with other networks of its own type). Always use the methods provided + * in {@link li.cil.oc.api.Network} to create and join networks. + */ +public interface Network { + /** + * Adds a new node connection in the network. + *

+ * This is used by nodes to join an existing network. At least one of the two + * nodes must already be in the network. If one of the nodes is not yet in the + * network, it will be added to the network. If both nodes are already in the + * network only the connection between the two nodes is added. If one of the + * nodes is not in this network but in another network, the networks will be + * merged. + *

+ * This way of adding nodes is used to build an internal graph to allow + * properly splitting networks when nodes are removed. + * + * @param nodeA the first node. + * @param nodeB the second node. + * @return true if a new connection between the two nodes was added; false if + * the connection already existed. + * @throws IllegalArgumentException if neither node is in this network. + */ + boolean connect(Node nodeA, Node nodeB); + + /** + * Removes a node connection in the network. + *

+ * Both nodes must be part of this network. + *

+ * This can be useful for cutting connections that depend on some condition + * that does not involve the nodes' actual existence in the network, such as + * the distance between two nodes, for example (think access points of a + * wireless network). + * + * @param nodeA the first node. + * @param nodeB the second node. + * @return true if the connection was cut; false if there was none. + * @throws IllegalArgumentException if the nodes are not in this network. + */ + boolean disconnect(Node nodeA, Node nodeB); + + /** + * Removes a node from the network. + *

+ * This should be called by nodes when they are destroyed (e.g. in + * {@link net.minecraft.tileentity.TileEntity#invalidate()}) or unloaded + * (e.g. in {@link net.minecraft.tileentity.TileEntity#onChunkUnload()}). + * Removing the node can lead to one or more new networks if it was the a + * bridge node, i.e. the only node connecting the resulting networks. + * + * @param node the node to remove from the network. + * @return true if the node was removed; false if it wasn't in the network. + */ + boolean remove(Node node); + + // ----------------------------------------------------------------------- // + + /** + * Get the network node with the specified address. + * + * @param address the address of the node to get. + * @return the node with that address. + */ + Node node(String address); + + /** + * The list of all nodes in this network. + * + * @return the list of nodes in this network. + */ + Iterable nodes(); + + /** + * The list of addressed nodes in the network visible to the specified node. + *

+ * This does not include nodes with a visibility of None + * or a visibility of Neighbors when there is no direct connection + * between that node and the reference node. + *

+ * This does not include the node itself. + *

+ * This can be useful when performing a delayed initialization of a node. + * For example, computers will use this when starting up to generate + * component_added signals for all visible components in the + * network. + * + * @param reference the node to get the visible other nodes for. + * @return the nodes visible to the specified node. + */ + Iterable nodes(Node reference); + + /** + * The list of nodes the specified node is directly connected to. + *

+ * This does include nodes with a visibility of None. + *

+ * This does not include the node itself. + *

+ * This can be used to verify arguments for components that should only work + * for other components that are directly connected to them, for example. + * + * @param node the node to get the neighbors for. + * @return a list of nodes the node is directly connect to. + * @throws IllegalArgumentException if the specified node is not in this network. + */ + Iterable neighbors(Node node); + + // ----------------------------------------------------------------------- // + + /** + * Sends a message to the node with the specified address. + *

+ * If the target node with that address has a visibility of None + * the message will not be delivered to that node. If the target + * node with that address has a visibility of Neighbors and the + * source node is not directly connected to the target the message will + * not be delivered to that node. + *

+ * Messages should have a unique name to allow differentiating them when + * handling them in a network node. For example, computers will try to parse + * messages named computer.signal by converting the message data to + * a signal and inject that signal into the machine, so no message not used + * for this purpose should be named computer.signal. + * + * @param source the node that sends the message. + * @param target the id of the node to send the message to. + * @param name the name of the message. + * @param data the message to send. + * @throws IllegalArgumentException if the source node is not in this network. + */ + void sendToAddress(Node source, String target, String name, Object... data); + + /** + * Sends a message to all addressed, visible neighbors of the source node. + *

+ * Targets are determined using {@link #neighbors(Node)} and additionally + * filtered for reachability (so that unreachable nodes are ignored). + *

+ * Messages should have a unique name to allow differentiating them when + * handling them in a network node. For example, computers will try to parse + * messages named computer.signal by converting the message data to + * a signal and inject that signal into the machine, so no message not used + * for this purpose should be named computer.signal. + * + * @param source the node that sends the message. + * @param name the name of the message. + * @param data the message to send. + * @throws IllegalArgumentException if the source node is not in this network. + * @see #neighbors(Node) + */ + void sendToNeighbors(Node source, String name, Object... data); + + /** + * Sends a message to all addressed nodes reachable to the source node. + *

+ * Targets are determined using {@link #nodes(Node)}. + *

+ * Messages should have a unique name to allow differentiating them when + * handling them in a network node. For example, computers will try to parse + * messages named computer.signal by converting the message data to + * a signal and inject that signal into the machine, so no message not used + * for this purpose should be named computer.signal. + * + * @param source the node that sends the message. + * @param data the message to send. + * @throws IllegalArgumentException if the source node is not in this network. + * @see #nodes(Node) + */ + void sendToReachable(Node source, String name, Object... data); + + /** + * Sends a message to all addressed nodes visible to the source node. + *

+ * Targets are determined using {@link #nodes(Node)} and additionally + * filtered for visibility (so that invisible nodes are ignored). + *

+ * Note that messages sent this way are only delivered to other + * components. The message will not be delivered to normal nodes. + *

+ * Messages should have a unique name to allow differentiating them when + * handling them in a network node. For example, computers will try to parse + * messages named computer.signal by converting the message data to + * a signal and inject that signal into the machine, so no message not used + * for this purpose should be named computer.signal. + * + * @param source the node that sends the message. + * @param data the message to send. + * @throws IllegalArgumentException if the source node is not in this network. + * @see #nodes(Node) + * @see Component#canBeSeenFrom(Node) + */ + void sendToVisible(Node source, String name, Object... data); +} diff --git a/src/api/java/li/cil/oc/api/network/Node.java b/src/api/java/li/cil/oc/api/network/Node.java new file mode 100755 index 000000000..b50a648ff --- /dev/null +++ b/src/api/java/li/cil/oc/api/network/Node.java @@ -0,0 +1,220 @@ +package li.cil.oc.api.network; + +import li.cil.oc.api.Persistable; + +/** + * A single node in a {@link Network}. + *

+ * All nodes in a network have a unique address; the network will generate a + * unique address and assign it to new nodes. + *

+ * Per default there are two kinds of nodes: tile entities and items. + *

+ * Items will usually only have nodes when in containers, such as a computer or + * disk drive. Otherwise you'll have to connect/disconnect them manually as + * desired. + *

+ * All other kinds of nodes you may come up with will also have to be + * handled manually. + *

+ * Items have to be handled by a corresponding {@link li.cil.oc.api.driver.Item}. + * Existing blocks may be interfaced with the adapter block if a + * {@link li.cil.oc.api.driver.Block} exists that supports the block. + *

+ * Important: like the Network interface you must not create + * your own implementations of this interface. Use the factory methods in the + * network API to create new node instances and store them in your environment. + * + * @see Component + */ +public interface Node extends Persistable { + /** + * The environment hosting this node. + *

+ * For blocks whose tile entities implement {@link Environment} this will + * be the tile entity. For all other implementations this will be a managed + * environment. + */ + Environment host(); + + /** + * The reachability of this node. + *

+ * This is used by the network to control which system messages to deliver + * to which nodes. This value should not change over the lifetime of a node. + *

+ * It furthermore determines what is returned by the Network's + * neighbors and nodes functions. + *

+ * Note that this has no effect on the real reachability of a node; + * it is only used to filter to which nodes to send connect, disconnect and + * reconnect messages. If addressed directly, the node will still receive + * that message even if it comes from a node that should not be able to see + * it. Therefore nodes should still verify themselves that they want to + * accept a message from the message's source. + *

+ * A different matter is a {@link Component}'s visibility, which is + * checked before delivering messages a computer tries to send. + */ + Visibility reachability(); + + /** + * The address of the node, so that it can be found in the network. + *

+ * This is used by the network manager when a node is added to a network to + * assign it a unique address, if it doesn't already have one. Nodes must not + * use custom addresses, only those assigned by the network. The only option + * they have is to *not* have an address, which can be useful for "dummy" + * nodes, such as cables. In that case they may ignore the address being set. + */ + String address(); + + /** + * The network this node is currently in. + *

+ * Note that valid nodes should never return `None` here. When created a node + * should immediately be added to a network, after being removed from its + * network a node should be considered invalid. + *

+ * This will always be set automatically by the network manager. Do not + * change this value and do not return anything that it wasn't set to. + */ + Network network(); + + // ----------------------------------------------------------------------- // + + /** + * Checks whether this node is a neighbor of the specified node. + * + * @param other the node to check for. + * @return whether this node is directly connected to the other node. + */ + boolean isNeighborOf(Node other); + + /** + * Checks whether this node can be reached from the specified node. + * + * @param other the node to check for. + * @return whether this node can be reached from the specified node. + */ + boolean canBeReachedFrom(Node other); + + /** + * Get the list of neighbor nodes, i.e. nodes directly connected to this + * node. + *

+ * This is a shortcut for node.network.neighbors(node). + *

+ * If this node is not in a network, i.e. network is null, + * this returns an empty list. + * + * @return the list of nodes directly connected to this node. + */ + Iterable neighbors(); + + /** + * Get the list of nodes reachable from this node, based on their + * {@link #reachability()}. + *

+ * This is a shortcut for node.network.nodes(node). + *

+ * If this node is not in a network, i.e. network is null, + * this returns an empty list. + * + * @return the list of nodes reachable from this node. + */ + Iterable reachableNodes(); + + // ----------------------------------------------------------------------- // + + /** + * Connects the specified node to this node. + *

+ * This is a shortcut for node.network.connect(node, other). + *

+ * If this node is not in a network, i.e. network is null, + * this will throw an exception. + * + * @param node the node to connect to this node. + * @throws NullPointerException if network is null. + */ + void connect(Node node); + + /** + * Disconnects the specified node from this node. + *

+ * This is a shortcut for node.network.disconnect(node, other). + *

+ * If this node is not in a network, i.e. network is null, + * this will do nothing. + * + * @param node the node to connect to this node. + * @throws NullPointerException if network is null. + */ + void disconnect(Node node); + + /** + * Removes this node from its network. + *

+ * This is a shortcut for node.network.remove(node). + *

+ * If this node is not in a network, i.e. network is null, + * this will do nothing. + */ + void remove(); + + // ----------------------------------------------------------------------- // + + /** + * Send a message to a node with the specified address. + *

+ * This is a shortcut for node.network.sendToAddress(node, ...). + *

+ * If this node is not in a network, i.e. network is null, + * this will do nothing. + * + * @param target the address of the node to send the message to. + * @param name the name of the message. + * @param data the data to pass along with the message. + */ + void sendToAddress(String target, String name, Object... data); + + /** + * Send a message to all neighbors of this node. + *

+ * This is a shortcut for node.network.sendToNeighbors(node, ...). + *

+ * If this node is not in a network, i.e. network is null, + * this will do nothing. + * + * @param name the name of the message. + * @param data the data to pass along with the message. + */ + void sendToNeighbors(String name, Object... data); + + /** + * Send a message to all nodes reachable from this node. + *

+ * This is a shortcut for node.network.sendToReachable(node, ...). + *

+ * If this node is not in a network, i.e. network is null, + * this will do nothing. + * + * @param name the name of the message. + * @param data the data to pass along with the message. + */ + void sendToReachable(String name, Object... data); + + /** + * Send a message to all nodes visible from this node. + *

+ * This is a shortcut for node.network.sendToVisible(node, ...). + *

+ * If this node is not in a network, i.e. network is null, + * this will do nothing. + * + * @param name the name of the message. + * @param data the data to pass along with the message. + */ + void sendToVisible(String name, Object... data); +} \ No newline at end of file diff --git a/src/api/java/li/cil/oc/api/network/Packet.java b/src/api/java/li/cil/oc/api/network/Packet.java new file mode 100755 index 000000000..233e72018 --- /dev/null +++ b/src/api/java/li/cil/oc/api/network/Packet.java @@ -0,0 +1,69 @@ +package li.cil.oc.api.network; + +import net.minecraft.nbt.NBTTagCompound; + +/** + * These packets represent messages sent using a network card or wireless + * network card, and can be relayed by the switch and access point blocks. + *

+ * These will be sent as the payload of network.message messages. + *

+ * Important: do not implement this interface. Use the factory + * methods in {@link li.cil.oc.api.Network} instead. + */ +public interface Packet { + /** + * The address of the original sender of this packet. + */ + String source(); + + /** + * The address of the destination of the packet. This is null for + * broadcast packets. + */ + String destination(); + + /** + * The port this packet is being sent to. + */ + int port(); + + /** + * The payload of the packet. This will usually only contain simple types, + * to allow persisting the packet. + */ + Object[] data(); + + /** + * The size of the packet's payload. + *

+ * This is computed based on the types in the data array, but is only defined + * for primitive types, i.e. null, boolean, integer, boolean byte array and + * string. All other types do not contribute to the packet's size. + */ + int size(); + + /** + * The remaining 'time to live' for this packet. When a packet with a TTL of + * zero is received it will not be relayed by switches and access points. It + * will however still be received by a network card. + */ + int ttl(); + + /** + * Generates a copy of the packet, with a reduced time to live. + *

+ * This is called by switches and access points to generate relayed packets. + * + * @return a copy of this packet with a reduced TTL. + */ + Packet hop(); + + /** + * Saves the packet's data to the specified compound tag. + *

+ * Restore a packet saved like this using the factory method in the + * {@link li.cil.oc.api.Network} class. + */ + void save(NBTTagCompound nbt); +} diff --git a/src/api/java/li/cil/oc/api/network/SidedComponent.java b/src/api/java/li/cil/oc/api/network/SidedComponent.java new file mode 100755 index 000000000..68dd76866 --- /dev/null +++ b/src/api/java/li/cil/oc/api/network/SidedComponent.java @@ -0,0 +1,26 @@ +package li.cil.oc.api.network; + +import net.minecraftforge.common.util.ForgeDirection; + +/** + * This is an extended version of {@link li.cil.oc.api.network.SimpleComponent} + * which allows controlling connectivity on a side-by-side basis. + *

+ * Like the SimpleComponent interface, this is intended to be used + * with tile entities that should act as OC components. Please see the + * SimpleComponent interface for more information. + */ +public interface SidedComponent { + /** + * Whether this component can connect to a node on the specified side. + *

+ * The provided side is relative to the component, i.e. when the tile + * entity sits at (0, 0, 0) and is asked for its southern node (positive + * Z axis) it has to return the connectivity for the face between it and + * the block at (0, 0, 1). + * + * @param side the side to check for. + * @return whether the component may be connected to from the specified side. + */ + boolean canConnectNode(ForgeDirection side); +} diff --git a/src/api/java/li/cil/oc/api/network/SidedEnvironment.java b/src/api/java/li/cil/oc/api/network/SidedEnvironment.java new file mode 100755 index 000000000..8c7dce15f --- /dev/null +++ b/src/api/java/li/cil/oc/api/network/SidedEnvironment.java @@ -0,0 +1,55 @@ +package li.cil.oc.api.network; + +import cpw.mods.fml.relauncher.Side; +import cpw.mods.fml.relauncher.SideOnly; +import net.minecraft.tileentity.TileEntity; +import net.minecraftforge.common.util.ForgeDirection; + +/** + * This interface is like {@link net.minecraft.inventory.ISidedInventory} is to + * {@link net.minecraft.inventory.IInventory}, it allows an environment to + * specify different node access for its different sides. + *

+ * This interface is intended to be used on tile entities that are environments. + * It is used to determine which neighbors a tile entity can connect to when + * calling {@link li.cil.oc.api.Network#joinOrCreateNetwork(TileEntity)}. It is + * used by the keyboard to only interface with the side on which it is attached, + * as well as the switch to offer a different node for each side. + */ +public interface SidedEnvironment { + /** + * The node this environment uses for the specified side. + *

+ * This is the side aware version of the normal {@link Environment#node} + * method. + *

+ * The provided side is relative to the environment, i.e. when the tile + * entity hosting the environment sits at (0, 0, 0) and is asked for its + * southern node (positive Z axis) it has to return the node for the face + * between it and the block at (0, 0, 1). + * + * @param side the side to get the node for. + * @return the node for the specified side. + * @see Environment#node + */ + Node sidedNode(ForgeDirection side); + + /** + * Whether the environment provides a node to connect to on the specified + * side. + *

+ * For each side the environment returns false here, it should + * return null from {@link #sidedNode}, and for each side it + * returns true for it should return a node. + *

+ * This is intended for the client side, i.e. rendering related things, + * since nodes are not created on the client side. + *

+ * The side is relative to the environment, same as for sidedNode. + * + * @param side the side to check for. + * @return whether the environment provides a node for the specified side. + */ + @SideOnly(Side.CLIENT) + boolean canConnect(ForgeDirection side); +} diff --git a/src/api/java/li/cil/oc/api/network/SimpleComponent.java b/src/api/java/li/cil/oc/api/network/SimpleComponent.java new file mode 100755 index 000000000..178941945 --- /dev/null +++ b/src/api/java/li/cil/oc/api/network/SimpleComponent.java @@ -0,0 +1,114 @@ +package li.cil.oc.api.network; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +/** + * This interface can be used to easily convert tile entities to components, + * without having to implement {@link Environment} + * themselves. The simple implementation will provide no access to OC's internal + * component network, since you won't have access to the node representing the + * tile entity. Use this only for simple cases, where you want to expose a + * couple of methods to the programs running computers. + *

+ * This is an interface instead of an annotation, to allow stripping via the + * ever so handy {@link cpw.mods.fml.common.Optional} annotation, meaning there + * will be no strong dependency on OpenComputers. + *

+ * Classes implementing this interface will be expanded with the methods + * required for them to function as native block components (say, like the + * screen or keyboard). This means functions in the Environment + * interface have to created using a class transformer. If any of the methods + * already exist, this will fail! If things don't work, check your logs, first. + *

+ * To expose methods to OC, tag them with {@link li.cil.oc.api.machine.Callback} + * and have them use the according signature (see the documentation on the + * Callback annotation). + *

+ * Alternatively, implement {@link li.cil.oc.api.network.ManagedPeripheral} in + * addition to this interface, to make methods available ComputerCraft style. + *

+ * So, in short: + *

+ *

+ * For example: + *

+ *     {@literal @}Optional.Interface(iface = "li.cil.oc.api.network.SimpleComponent", modid = "OpenComputers")
+ *     public class TileEntityMyFancyThing extends TileEntity
+ *            implements SimpleComponent
+ *     {
+ *         {@literal @}Override
+ *         public String getComponentName() {
+ *             return "fancy_thing";
+ *         }
+ *
+ *         {@literal @}Callback
+ *         {@literal @}Optional.Method(modid = "OpenComputers")
+ *         public Object[] greet(Context context, Arguments args) {
+ *             return new Object[]{String.format("Hello, %s!", args.checkString(0))};
+ *         }
+ *     }
+ * 
+ * Using the alternative method to provide methods: + *
+ *     {@literal @}Optional.InterfaceList({
+ *         {@literal @}Optional.Interface(iface = "li.cil.oc.api.network.SimpleComponent", modid = "OpenComputers"),
+ *         {@literal @}Optional.Interface(iface = "li.cil.oc.api.network.ManagedPeripheral", modid = "OpenComputers")
+ *     })
+ *     public class TileEntityMyFancyThing extends TileEntity
+ *            implements SimpleComponent, ManagedPeripheral
+ *     {
+ *         {@literal @}Override
+ *         public String getComponentName() {
+ *             return "fancy_thing";
+ *         }
+ *
+ *         public String[] methods() {
+ *             return new String[] {"greet"};
+ *         }
+ *
+ *         {@literal @}Optional.Method(modid = "OpenComputers")
+ *         public Object[] invoke(String method, Context context, Arguments args) {
+ *             if ("greet".equals(method)) {
+ *                 return new Object[]{String.format("Hello, %s!", args.checkString(0))};
+ *             } else {
+ *                 throw new NoSuchMethodException();
+ *             }
+ *         }
+ *     }
+ * 
+ */ +public interface SimpleComponent { + /** + * The name the component should be made available as. + *

component.list() in Lua, for + * example. You'll want to make this short and descriptive. The convention + * for component names is: all lowercase, underscores where necessary. Good + * component names are for example: disk_drive, furnace, crafting_table. + * + * @return the component's name. + */ + String getComponentName(); + + /** + * Use this to skip logic injection for the class this is implemented by. + *

+ * For example, if you have a class transformer that injects logic from a + * template class into your actual tile entities, OC's class transformer + * would complain when it finds the interface on the template class. That + * warning can be suppressed by using this annotation on the template. + */ + @Retention(RetentionPolicy.RUNTIME) + @Target(ElementType.TYPE) + @interface SkipInjection { + } +} diff --git a/src/api/java/li/cil/oc/api/network/Visibility.java b/src/api/java/li/cil/oc/api/network/Visibility.java new file mode 100755 index 000000000..e91a79043 --- /dev/null +++ b/src/api/java/li/cil/oc/api/network/Visibility.java @@ -0,0 +1,42 @@ +package li.cil.oc.api.network; + +/** + * Possible reachability values for nodes. + *

+ * Since all nodes that are connected are packed into the same network, we want + * some way of controlling what's accessible from where on a low level (to + * avoid unnecessary messages and unauthorized access). + *

+ * Note that there is a more specific kind of visibility for components. See + * {@link Component} for more details on that. + */ +public enum Visibility { + /** + * Nodes with this visibility neither receive nor send messages. + *

+ * Components with this visibility cannot be seen nor reached by computers. + */ + None, + + /** + * Nodes with this visibility only receive messages from their immediate + * neighbors, i.e. nodes to which a direct connection exists. It can send + * messages to all nodes visible to it. + *

+ * Components with this visibility can likewise only be reached by the + * computer(s) they are directly attached to. For example, if a block + * component is placed directly next to the computer, or an item installed + * in the computer (i.e. it is in the computer's inventory). + */ + Neighbors, + + /** + * Nodes with this visibility can receive messages from any node in its + * network. It can still only send messages to all nodes visible to it. + *

+ * Components with this visibility are likewise reachable by all computers + * in their network. For example, a screen only indirectly connected to a + * computer will still be addressable by that computer. + */ + Network +} diff --git a/src/api/java/li/cil/oc/api/network/WirelessEndpoint.java b/src/api/java/li/cil/oc/api/network/WirelessEndpoint.java new file mode 100755 index 000000000..c5de36d3d --- /dev/null +++ b/src/api/java/li/cil/oc/api/network/WirelessEndpoint.java @@ -0,0 +1,47 @@ +package li.cil.oc.api.network; + +import net.minecraft.world.World; + +/** + * Interface for wireless endpoints that can be registered with the internal + * wireless network registry. + *

+ * These can be added to the wireless network via the Network API, to + * allow them to receive packets like wireless network cards and access points + * do (and handle or forward them as they see fit). + *

+ * If the position of the endpoint can change, it must be updated manually via + * {@link li.cil.oc.api.Network#updateWirelessNetwork(WirelessEndpoint)}. + */ +public interface WirelessEndpoint { + /** + * The X coordinate of the endpoint in the world, in block coordinates. + */ + int x(); + + /** + * The Y coordinate of the endpoint in the world, in block coordinates. + */ + int y(); + + /** + * The Z coordinate of the endpoint in the world, in block coordinates. + */ + int z(); + + /** + * The world this endpoint lives in. + */ + World world(); + + /** + * Makes the endpoint receive a single packet. + * + * @param packet the packet to receive. + * @param sender the endpoint that sent the message. This is not + * necessarily the original sender of the packet, just + * the last point it went through, such as an access + * point, for example. + */ + void receivePacket(Packet packet, WirelessEndpoint sender); +} diff --git a/src/api/java/li/cil/oc/api/network/package-info.java b/src/api/java/li/cil/oc/api/network/package-info.java new file mode 100755 index 000000000..ef7ae77ed --- /dev/null +++ b/src/api/java/li/cil/oc/api/network/package-info.java @@ -0,0 +1,13 @@ +/** + * This package provides component networking related functionality. + *

+ * This mainly involves the (purely server-side!) network that is spanned over + * all of OpenComputers' components, including blocks and items alike. + */ +@cpw.mods.fml.common.API( + owner = API.ID_OWNER, + provides = "OpenComputersAPI|Network", + apiVersion = API.VERSION) +package li.cil.oc.api.network; + +import li.cil.oc.api.API; \ No newline at end of file diff --git a/src/api/java/li/cil/oc/api/package-info.java b/src/api/java/li/cil/oc/api/package-info.java new file mode 100755 index 000000000..94fc3bdc2 --- /dev/null +++ b/src/api/java/li/cil/oc/api/package-info.java @@ -0,0 +1,41 @@ +/** + * This API provides interfaces and factory methods for the OpenComputers mod. + *

+ * There are several parts to this API: + *

+ *
The {@link li.cil.oc.api.Driver} API
+ *
+ * This API is used to provide glue code to the mod that allows it to interact + * with foreign objects. You need a driver if you wish to connect some object + * to the internal {@link li.cil.oc.api.network.Network}, for example because + * you wish to interact with other blocks / components of the mod. The most + * typical scenario for this will be adding a new object that user programs + * should be able to interact with: a {@link li.cil.oc.api.network.Component}. + *

+ * Note that for tile entities you implement yourself, you will not have to + * provide a driver, as long as you implement the necessary interface: + * {@link li.cil.oc.api.network.Environment} and call {@link li.cil.oc.api.Network#joinOrCreateNetwork(net.minecraft.tileentity.TileEntity)} + * in the first updateEntity() call. For items that should be installed + * in a computer you will always have to provide a driver. + *

+ *
The {@link li.cil.oc.api.FileSystem} API
+ *
+ * This API provides facilities that make it easier to create file systems that + * can be interacted with from user programs via the file system driver that + * comes with the mod. + *
+ *
The {@link li.cil.oc.api.Network} API
+ *
+ * This API provides interfaces that allow interacting with the internal network + * and creating nodes, components and power connectors for said network. If you + * implement Environment in your tile entity or provide a + * {@link li.cil.oc.api.network.ManagedEnvironment} via a driver you'll want to + * create a node. This API provides factory methods for creating it. + *
+ *
+ */ +@cpw.mods.fml.common.API( + owner = API.ID_OWNER, + provides = "OpenComputersAPI|Core", + apiVersion = API.VERSION) +package li.cil.oc.api; \ No newline at end of file diff --git a/src/api/java/li/cil/oc/api/prefab/AbstractInteractiveImageRenderer.java b/src/api/java/li/cil/oc/api/prefab/AbstractInteractiveImageRenderer.java new file mode 100755 index 000000000..2ba7569c8 --- /dev/null +++ b/src/api/java/li/cil/oc/api/prefab/AbstractInteractiveImageRenderer.java @@ -0,0 +1,19 @@ +package li.cil.oc.api.prefab; + +import li.cil.oc.api.manual.InteractiveImageRenderer; + +/** + * Simple base implementation of {@link InteractiveImageRenderer}. + */ +@SuppressWarnings("UnusedDeclaration") +public abstract class AbstractInteractiveImageRenderer implements InteractiveImageRenderer { + @Override + public String getTooltip(String tooltip) { + return tooltip; + } + + @Override + public boolean onMouseClick(int mouseX, int mouseY) { + return false; + } +} diff --git a/src/api/java/li/cil/oc/api/prefab/AbstractValue.java b/src/api/java/li/cil/oc/api/prefab/AbstractValue.java new file mode 100755 index 000000000..7d686b5df --- /dev/null +++ b/src/api/java/li/cil/oc/api/prefab/AbstractValue.java @@ -0,0 +1,37 @@ +package li.cil.oc.api.prefab; + +import li.cil.oc.api.machine.Arguments; +import li.cil.oc.api.machine.Context; +import li.cil.oc.api.machine.Value; +import net.minecraft.nbt.NBTTagCompound; + +/** + * Basic implementation for the Value interface. + */ +public class AbstractValue implements Value { + @Override + public Object apply(Context context, Arguments arguments) { + return null; + } + + @Override + public void unapply(Context context, Arguments arguments) { + } + + @Override + public Object[] call(Context context, Arguments arguments) { + throw new RuntimeException("trying to call a non-callable value"); + } + + @Override + public void dispose(Context context) { + } + + @Override + public void load(NBTTagCompound nbt) { + } + + @Override + public void save(NBTTagCompound nbt) { + } +} diff --git a/src/api/java/li/cil/oc/api/prefab/DriverBlock.java b/src/api/java/li/cil/oc/api/prefab/DriverBlock.java new file mode 100755 index 000000000..bb9e1654f --- /dev/null +++ b/src/api/java/li/cil/oc/api/prefab/DriverBlock.java @@ -0,0 +1,49 @@ +package li.cil.oc.api.prefab; + +import net.minecraft.block.Block; +import net.minecraft.item.ItemBlock; +import net.minecraft.item.ItemStack; +import net.minecraft.world.World; +import net.minecraftforge.oredict.OreDictionary; + +/** + * If you wish to create a block component for a third-party block, i.e. a block + * for which you do not control the tile entity, such as vanilla blocks, you + * will need a block driver. + *

+ * This prefab allows creating a driver that works for a specified list of item + * stacks (to support different blocks with the same id but different metadata + * values). + *

+ * You still have to provide the implementation for creating its environment, if + * any. + * + * @see li.cil.oc.api.network.ManagedEnvironment + */ +@SuppressWarnings("UnusedDeclaration") +public abstract class DriverBlock implements li.cil.oc.api.driver.Block { + protected final ItemStack[] blocks; + + protected DriverBlock(final ItemStack... blocks) { + this.blocks = blocks.clone(); + } + + @Override + public boolean worksWith(final World world, final int x, final int y, final int z) { + return worksWith(world.getBlock(x, y, z), world.getBlockMetadata(x, y, z)); + } + + protected boolean worksWith(final Block referenceBlock, final int referenceMetadata) { + for (ItemStack stack : blocks) { + if (stack != null && stack.getItem() instanceof ItemBlock) { + final ItemBlock item = (ItemBlock) stack.getItem(); + final Block supportedBlock = item.field_150939_a; + final int supportedMetadata = item.getMetadata(stack.getItemDamage()); + if (referenceBlock == supportedBlock && (referenceMetadata == supportedMetadata || stack.getItemDamage() == OreDictionary.WILDCARD_VALUE)) { + return true; + } + } + } + return false; + } +} diff --git a/src/api/java/li/cil/oc/api/prefab/DriverItem.java b/src/api/java/li/cil/oc/api/prefab/DriverItem.java new file mode 100755 index 000000000..e56e4f715 --- /dev/null +++ b/src/api/java/li/cil/oc/api/prefab/DriverItem.java @@ -0,0 +1,85 @@ +package li.cil.oc.api.prefab; + +import li.cil.oc.api.driver.EnvironmentHost; +import net.minecraft.item.ItemStack; +import net.minecraft.nbt.NBTTagCompound; + +/** + * If you wish to create item components such as the network card or hard drives + * you will need an item driver. + *

+ * This prefab allows creating a driver that works for a specified list of item + * stacks (to support different items with the same id but different damage + * values). It also takes care of creating and getting the tag compound on an + * item stack to save data to or load data from. + *

+ * You still have to specify your component's slot type and provide the + * implementation for creating its environment, if any. + * + * @see li.cil.oc.api.network.ManagedEnvironment + */ +@SuppressWarnings("UnusedDeclaration") +public abstract class DriverItem implements li.cil.oc.api.driver.Item { + protected final ItemStack[] items; + + protected DriverItem(final ItemStack... items) { + this.items = items.clone(); + } + + @Override + public boolean worksWith(final ItemStack stack) { + if (stack != null) { + for (ItemStack item : items) { + if (item != null && item.isItemEqual(stack)) { + return true; + } + } + } + return false; + } + + @Override + public int tier(final ItemStack stack) { + return 0; + } + + @Override + public NBTTagCompound dataTag(final ItemStack stack) { + if (!stack.hasTagCompound()) { + stack.setTagCompound(new NBTTagCompound()); + } + final NBTTagCompound nbt = stack.getTagCompound(); + // This is the suggested key under which to store item component data. + // You are free to change this as you please. + if (!nbt.hasKey("oc:data")) { + nbt.setTag("oc:data", new NBTTagCompound()); + } + return nbt.getCompoundTag("oc:data"); + } + + // Convenience methods provided for HostAware drivers. + + protected boolean isAdapter(Class host) { + return li.cil.oc.api.internal.Adapter.class.isAssignableFrom(host); + } + + protected boolean isComputer(Class host) { + return li.cil.oc.api.internal.Case.class.isAssignableFrom(host); + } + + protected boolean isRobot(Class host) { + return li.cil.oc.api.internal.Robot.class.isAssignableFrom(host); + } + + protected boolean isRotatable(Class host) { + return li.cil.oc.api.internal.Rotatable.class.isAssignableFrom(host); + } + + protected boolean isServer(Class host) { + return li.cil.oc.api.internal.Server.class.isAssignableFrom(host); + } + + protected boolean isTablet(Class host) { + return li.cil.oc.api.internal.Tablet.class.isAssignableFrom(host); + } +} diff --git a/src/api/java/li/cil/oc/api/prefab/DriverTileEntity.java b/src/api/java/li/cil/oc/api/prefab/DriverTileEntity.java new file mode 100755 index 000000000..e9c6890ef --- /dev/null +++ b/src/api/java/li/cil/oc/api/prefab/DriverTileEntity.java @@ -0,0 +1,20 @@ +package li.cil.oc.api.prefab; + +import net.minecraft.tileentity.TileEntity; +import net.minecraft.world.World; + +public abstract class DriverTileEntity implements li.cil.oc.api.driver.Block { + public abstract Class getTileEntityClass(); + + @Override + public boolean worksWith(final World world, final int x, final int y, final int z) { + final Class filter = getTileEntityClass(); + if (filter == null) { + // This can happen if filter classes are deduced by reflection and + // the class in question is not present. + return false; + } + final TileEntity tileEntity = world.getTileEntity(x, y, z); + return tileEntity != null && filter.isAssignableFrom(tileEntity.getClass()); + } +} diff --git a/src/api/java/li/cil/oc/api/prefab/ItemStackTabIconRenderer.java b/src/api/java/li/cil/oc/api/prefab/ItemStackTabIconRenderer.java new file mode 100755 index 000000000..db8d43be4 --- /dev/null +++ b/src/api/java/li/cil/oc/api/prefab/ItemStackTabIconRenderer.java @@ -0,0 +1,34 @@ +package li.cil.oc.api.prefab; + +import cpw.mods.fml.relauncher.Side; +import cpw.mods.fml.relauncher.SideOnly; +import li.cil.oc.api.manual.TabIconRenderer; +import net.minecraft.client.Minecraft; +import net.minecraft.client.renderer.OpenGlHelper; +import net.minecraft.client.renderer.RenderHelper; +import net.minecraft.client.renderer.entity.RenderItem; +import net.minecraft.item.ItemStack; +import org.lwjgl.opengl.GL11; +import org.lwjgl.opengl.GL12; + +/** + * Simple implementation of a tab icon renderer using an item stack as its graphic. + */ +@SuppressWarnings("UnusedDeclaration") +public class ItemStackTabIconRenderer implements TabIconRenderer { + private final ItemStack stack; + + public ItemStackTabIconRenderer(ItemStack stack) { + this.stack = stack; + } + + @SideOnly(Side.CLIENT) + @Override + public void render() { + GL11.glEnable(GL12.GL_RESCALE_NORMAL); + RenderHelper.enableGUIStandardItemLighting(); + OpenGlHelper.setLightmapTextureCoords(OpenGlHelper.lightmapTexUnit, 240, 240); + RenderItem.getInstance().renderItemAndEffectIntoGUI(Minecraft.getMinecraft().fontRenderer, Minecraft.getMinecraft().getTextureManager(), stack, 0, 0); + RenderHelper.disableStandardItemLighting(); + } +} diff --git a/src/api/java/li/cil/oc/api/prefab/ManagedEnvironment.java b/src/api/java/li/cil/oc/api/prefab/ManagedEnvironment.java new file mode 100755 index 000000000..ed9ccfba4 --- /dev/null +++ b/src/api/java/li/cil/oc/api/prefab/ManagedEnvironment.java @@ -0,0 +1,74 @@ +package li.cil.oc.api.prefab; + +import li.cil.oc.api.network.Message; +import li.cil.oc.api.network.Node; +import net.minecraft.nbt.NBTTagCompound; + +/** + * Simple base implementation of the ManagedEnvironment interface, so + * unused methods don't clutter the implementing class. + */ +public abstract class ManagedEnvironment implements li.cil.oc.api.network.ManagedEnvironment { + // Should be initialized using setNode(api.Network.newNode()). See TileEntityEnvironment. + private Node _node; + + @Override + public Node node() { + return _node; + } + + protected void setNode(Node value) { + _node = value; + } + + @Override + public boolean canUpdate() { + return false; + } + + @Override + public void update() { + } + + @Override + public void onConnect(final Node node) { + } + + @Override + public void onDisconnect(final Node node) { + } + + @Override + public void onMessage(final Message message) { + } + + @Override + public void load(final NBTTagCompound nbt) { + if (node() != null) { + node().load(nbt.getCompoundTag("node")); + } + } + + @Override + public void save(final NBTTagCompound nbt) { + if (node() != null) { + // Force joining a network when saving and we're not in one yet, so that + // the address is embedded in the saved data that gets sent to the client, + // so that that address can be used to associate components on server and + // client (for example keyboard and screen/text buffer). + if (node().address() == null) { + li.cil.oc.api.Network.joinNewNetwork(node()); + + final NBTTagCompound nodeTag = new NBTTagCompound(); + node().save(nodeTag); + nbt.setTag("node", nodeTag); + + node().remove(); + } else { + final NBTTagCompound nodeTag = new NBTTagCompound(); + node().save(nodeTag); + nbt.setTag("node", nodeTag); + } + } + } +} diff --git a/src/api/java/li/cil/oc/api/prefab/ResourceContentProvider.java b/src/api/java/li/cil/oc/api/prefab/ResourceContentProvider.java new file mode 100755 index 000000000..44d5efe68 --- /dev/null +++ b/src/api/java/li/cil/oc/api/prefab/ResourceContentProvider.java @@ -0,0 +1,65 @@ +package li.cil.oc.api.prefab; + +import com.google.common.base.Charsets; +import li.cil.oc.api.manual.ContentProvider; +import net.minecraft.client.Minecraft; +import net.minecraft.util.ResourceLocation; + +import java.io.BufferedReader; +import java.io.IOException; +import java.io.InputStream; +import java.io.InputStreamReader; +import java.util.ArrayList; + +/** + * Basic implementation of a content provider based on Minecraft's resource + * loading framework. + *

+ * Beware that the manual is unaware of resource domains. In other words, two + * paths that are identical except for their resource domain will be the same, + * as seen from the manual. This means you should probably place your + * documentation somewhere other than doc/, because that's where the + * OpenComputers documentation lives, and it is queried first - meaning if you + * have a page with the same path as one in OpenComputers, it is practically + * unreachable (because the OC provider is always queried first). + */ +@SuppressWarnings("UnusedDeclaration") +public class ResourceContentProvider implements ContentProvider { + private final String resourceDomain; + + private final String basePath; + + public ResourceContentProvider(String resourceDomain, String basePath) { + this.resourceDomain = resourceDomain; + this.basePath = basePath; + } + + public ResourceContentProvider(String resourceDomain) { + this(resourceDomain, ""); + } + + @Override + public Iterable getContent(String path) { + final ResourceLocation location = new ResourceLocation(resourceDomain, basePath + (path.startsWith("/") ? path.substring(1) : path)); + InputStream is = null; + try { + is = Minecraft.getMinecraft().getResourceManager().getResource(location).getInputStream(); + final BufferedReader reader = new BufferedReader(new InputStreamReader(is, Charsets.UTF_8)); + final ArrayList lines = new ArrayList(); + String line; + while ((line = reader.readLine()) != null) { + lines.add(line); + } + return lines; + } catch (Throwable ignored) { + return null; + } finally { + if (is != null) { + try { + is.close(); + } catch (IOException ignored) { + } + } + } + } +} diff --git a/src/api/java/li/cil/oc/api/prefab/TextureTabIconRenderer.java b/src/api/java/li/cil/oc/api/prefab/TextureTabIconRenderer.java new file mode 100755 index 000000000..0a382814b --- /dev/null +++ b/src/api/java/li/cil/oc/api/prefab/TextureTabIconRenderer.java @@ -0,0 +1,33 @@ +package li.cil.oc.api.prefab; + +import cpw.mods.fml.relauncher.Side; +import cpw.mods.fml.relauncher.SideOnly; +import li.cil.oc.api.manual.TabIconRenderer; +import net.minecraft.client.Minecraft; +import net.minecraft.client.renderer.Tessellator; +import net.minecraft.util.ResourceLocation; + +/** + * Simple implementation of a tab icon renderer using a full texture as its graphic. + */ +@SuppressWarnings("UnusedDeclaration") +public class TextureTabIconRenderer implements TabIconRenderer { + private final ResourceLocation location; + + public TextureTabIconRenderer(ResourceLocation location) { + this.location = location; + } + + @Override + @SideOnly(Side.CLIENT) + public void render() { + Minecraft.getMinecraft().getTextureManager().bindTexture(location); + final Tessellator t = Tessellator.instance; + t.startDrawingQuads(); + t.addVertexWithUV(0, 16, 0, 0, 1); + t.addVertexWithUV(16, 16, 0, 1, 1); + t.addVertexWithUV(16, 0, 0, 1, 0); + t.addVertexWithUV(0, 0, 0, 0, 0); + t.draw(); + } +} diff --git a/src/api/java/li/cil/oc/api/prefab/TileEntityEnvironment.java b/src/api/java/li/cil/oc/api/prefab/TileEntityEnvironment.java new file mode 100755 index 000000000..e1fb6fca8 --- /dev/null +++ b/src/api/java/li/cil/oc/api/prefab/TileEntityEnvironment.java @@ -0,0 +1,155 @@ +package li.cil.oc.api.prefab; + +import li.cil.oc.api.Network; +import li.cil.oc.api.network.Environment; +import li.cil.oc.api.network.Message; +import li.cil.oc.api.network.Node; +import li.cil.oc.api.network.Visibility; +import net.minecraft.nbt.NBTTagCompound; +import net.minecraft.tileentity.TileEntity; + +/** + * TileEntities can implement the {@link li.cil.oc.api.network.Environment} + * interface to allow them to interact with the component network, by providing + * a {@link li.cil.oc.api.network.Node} and connecting it to said network. + *

+ * Nodes in such a network can communicate with each other, or just use the + * network as an index structure to find other nodes connected to them. + */ +@SuppressWarnings("UnusedDeclaration") +public abstract class TileEntityEnvironment extends TileEntity implements Environment { + /** + * This must be set in subclasses to the node that is used to represent + * this tile entity. + *

+ * You must only create new nodes using the factory method in the network + * API, {@link li.cil.oc.api.Network#newNode(Environment, Visibility)}. + *

+ * For example: + *

+     * // The first parameters to newNode is the host() of the node, which will
+     * // usually be this tile entity. The second one is it's reachability,
+     * // which determines how other nodes in the same network can query this
+     * // node. See {@link li.cil.oc.api.network.Network#nodes(li.cil.oc.api.network.Node)}.
+     * node = Network.newNode(this, Visibility.Network)
+     *       // This call allows the node to consume energy from the
+     *       // component network it is in and act as a consumer, or to
+     *       // inject energy into that network and act as a producer.
+     *       // If you do not need energy remove this call.
+     *       .withConnector()
+     *       // This call marks the tile entity as a component. This means you
+     *       // can mark methods in it using the {@link li.cil.oc.api.machine.Callback}
+     *       // annotation, making them callable from user code. The first
+     *       // parameter is the name by which the component will be known in
+     *       // the computer, in this case it could be accessed as
+     *       // component.example. The second parameter is the
+     *       // component's visibility. This is like the node's reachability,
+     *       // but only applies to computers. For example, network cards can
+     *       // only be seen by the computer they're installed in, but
+     *       // can be reached by all other network cards in the same
+     *       // network. If you do not need callbacks remove this call.
+     *       .withComponent("example", Visibility.Neighbors)
+     *       // Finalizes the construction of the node and returns it.
+     *       .create();
+     * 
+ */ + protected Node node; + + // See updateEntity(). + protected boolean addedToNetwork = false; + + // ----------------------------------------------------------------------- // + + @Override + public Node node() { + return node; + } + + @Override + public void onConnect(final Node node) { + // This is called when the call to Network.joinOrCreateNetwork(this) in + // updateEntity was successful, in which case `node == this`. + // This is also called for any other node that gets connected to the + // network our node is in, in which case `node` is the added node. + // If our node is added to an existing network, this is called for each + // node already in said network. + } + + @Override + public void onDisconnect(final Node node) { + // This is called when this node is removed from its network when the + // tile entity is removed from the world (see onChunkUnload() and + // invalidate()), in which case `node == this`. + // This is also called for each other node that gets removed from the + // network our node is in, in which case `node` is the removed node. + // If a net-split occurs this is called for each node that is no longer + // connected to our node. + } + + @Override + public void onMessage(final Message message) { + // This is used to deliver messages sent via node.sendToXYZ. Handle + // messages at your own discretion. If you do not wish to handle a + // message you should *not* throw an exception, though. + } + + // ----------------------------------------------------------------------- // + + @Override + public void updateEntity() { + // On the first update, try to add our node to nearby networks. We do + // this in the update logic, not in validate() because we need to access + // neighboring tile entities, which isn't possible in validate(). + // We could alternatively check node != null && node.network() == null, + // but this has somewhat better performance, and makes it clearer. + if (!addedToNetwork) { + addedToNetwork = true; + Network.joinOrCreateNetwork(this); + } + } + + @Override + public void onChunkUnload() { + super.onChunkUnload(); + // Make sure to remove the node from its network when its environment, + // meaning this tile entity, gets unloaded. + if (node != null) node.remove(); + } + + @Override + public void invalidate() { + super.invalidate(); + // Make sure to remove the node from its network when its environment, + // meaning this tile entity, gets unloaded. + if (node != null) node.remove(); + } + + // ----------------------------------------------------------------------- // + + @Override + public void readFromNBT(final NBTTagCompound nbt) { + super.readFromNBT(nbt); + // The host check may be superfluous for you. It's just there to allow + // some special cases, where getNode() returns some node managed by + // some other instance (for example when you have multiple internal + // nodes in this tile entity). + if (node != null && node.host() == this) { + // This restores the node's address, which is required for networks + // to continue working without interruption across loads. If the + // node is a power connector this is also required to restore the + // internal energy buffer of the node. + node.load(nbt.getCompoundTag("oc:node")); + } + } + + @Override + public void writeToNBT(final NBTTagCompound nbt) { + super.writeToNBT(nbt); + // See readFromNBT() regarding host check. + if (node != null && node.host() == this) { + final NBTTagCompound nodeNbt = new NBTTagCompound(); + node.save(nodeNbt); + nbt.setTag("oc:node", nodeNbt); + } + } +} diff --git a/src/api/java/li/cil/oc/api/prefab/TileEntitySidedEnvironment.java b/src/api/java/li/cil/oc/api/prefab/TileEntitySidedEnvironment.java new file mode 100755 index 000000000..2d6c247e7 --- /dev/null +++ b/src/api/java/li/cil/oc/api/prefab/TileEntitySidedEnvironment.java @@ -0,0 +1,152 @@ +package li.cil.oc.api.prefab; + +import li.cil.oc.api.Network; +import li.cil.oc.api.network.Node; +import li.cil.oc.api.network.SidedEnvironment; +import net.minecraft.nbt.NBTTagCompound; +import net.minecraft.tileentity.TileEntity; +import net.minecraftforge.common.util.ForgeDirection; + +/** + * TileEntities can implement the {@link li.cil.oc.api.network.SidedEnvironment} + * interface to allow them to interact with the component network, by providing + * a separate {@link li.cil.oc.api.network.Node} for each block face, and + * connecting it to said network. This allows more control over connectivity + * than the simple {@link li.cil.oc.api.network.Environment}. + *

+ * Nodes in such a network can communicate with each other, or just use the + * network as an index structure to find other nodes connected to them. + */ +@SuppressWarnings("UnusedDeclaration") +public abstract class TileEntitySidedEnvironment extends TileEntity implements SidedEnvironment { + // See constructor. + protected Node[] nodes = new Node[6]; + + // See updateEntity(). + protected boolean addedToNetwork = false; + + /** + * This expects a node per face that is used to represent this tile entity. + *

+ * You must only create new nodes using the factory method in the network + * API, {@link li.cil.oc.api.Network#newNode(li.cil.oc.api.network.Environment, li.cil.oc.api.network.Visibility)}. + *

+ * For example: + *

+     * // The first parameters to newNode is the host() of the node, which will
+     * // usually be this tile entity. The second one is it's reachability,
+     * // which determines how other nodes in the same network can query this
+     * // node. See {@link li.cil.oc.api.network.Network#nodes(li.cil.oc.api.network.Node)}.
+     * super(Network.newNode(???, Visibility.Network)
+     *       // This call allows the node to consume energy from the
+     *       // component network it is in and act as a consumer, or to
+     *       // inject energy into that network and act as a producer.
+     *       // If you do not need energy remove this call.
+     *       .withConnector()
+     *       // This call marks the tile entity as a component. This means you
+     *       // can mark methods in it using the {@link li.cil.oc.api.machine.Callback}
+     *       // annotation, making them callable from user code. The first
+     *       // parameter is the name by which the component will be known in
+     *       // the computer, in this case it could be accessed as
+     *       // component.example. The second parameter is the
+     *       // component's visibility. This is like the node's reachability,
+     *       // but only applies to computers. For example, network cards can
+     *       // only be seen by the computer they're installed in, but
+     *       // can be reached by all other network cards in the same
+     *       // network. If you do not need callbacks remove this call.
+     *       .withComponent("example", Visibility.Neighbors)
+     *       // Finalizes the construction of the node and returns it.
+     *       .create(), ...);
+     * 
+ */ + protected TileEntitySidedEnvironment(final Node... nodes) { + System.arraycopy(nodes, 0, this.nodes, 0, Math.min(nodes.length, this.nodes.length)); + } + + // ----------------------------------------------------------------------- // + + // canConnect() is for the client side, to determine how cables are + // rendered, for example, so you'll have to provide that logic yourself. + // Nodes are only created on the server side, so checking whether a node + // exists for a side won't work on the client. + + @Override + public Node sidedNode(final ForgeDirection side) { + return side == ForgeDirection.UNKNOWN ? null : nodes[side.ordinal()]; + } + + // ----------------------------------------------------------------------- // + + @Override + public void updateEntity() { + super.updateEntity(); + // On the first update, try to add our node to nearby networks. We do + // this in the update logic, not in validate() because we need to access + // neighboring tile entities, which isn't possible in validate(). + // We could alternatively check node != null && node.network() == null, + // but this has somewhat better performance, and makes it clearer. + if (!addedToNetwork) { + addedToNetwork = true; + // Note that joinOrCreateNetwork will try to connect each of our + // sided nodes to their respective neighbor (sided) node. + Network.joinOrCreateNetwork(this); + } + } + + @Override + public void onChunkUnload() { + super.onChunkUnload(); + // Make sure to remove the node from its network when its environment, + // meaning this tile entity, gets unloaded. + for (Node node : nodes) { + if (node != null) node.remove(); + } + } + + @Override + public void invalidate() { + super.invalidate(); + // Make sure to remove the node from its network when its environment, + // meaning this tile entity, gets unloaded. + for (Node node : nodes) { + if (node != null) node.remove(); + } + } + + // ----------------------------------------------------------------------- // + + @Override + public void readFromNBT(final NBTTagCompound nbt) { + super.readFromNBT(nbt); + int index = 0; + for (Node node : nodes) { + // The host check may be superfluous for you. It's just there to allow + // some special cases, where getNode() returns some node managed by + // some other instance (for example when you have multiple internal + // nodes in this tile entity). + if (node != null && node.host() == this) { + // This restores the node's address, which is required for networks + // to continue working without interruption across loads. If the + // node is a power connector this is also required to restore the + // internal energy buffer of the node. + node.load(nbt.getCompoundTag("oc:node" + index)); + } + ++index; + } + } + + @Override + public void writeToNBT(NBTTagCompound nbt) { + super.writeToNBT(nbt); + int index = 0; + for (Node node : nodes) { + // See readFromNBT() regarding host check. + if (node != null && node.host() == this) { + final NBTTagCompound nodeNbt = new NBTTagCompound(); + node.save(nodeNbt); + nbt.setTag("oc:node" + index, nodeNbt); + } + ++index; + } + } +} diff --git a/src/api/java/li/cil/oc/api/prefab/package-info.java b/src/api/java/li/cil/oc/api/prefab/package-info.java new file mode 100755 index 000000000..ba933b12c --- /dev/null +++ b/src/api/java/li/cil/oc/api/prefab/package-info.java @@ -0,0 +1,16 @@ +/** + * This package provides base implementations of some interfaces. + *

+ * This is provided for convenience only, you do not have to use these classes, + * you are free to fully implement them yourself. You may also copy these + * classes and / or rename them if you wish. Just don't make changes to them + * while leaving them in the same package with the same name and then ship them + * with your mod! + */ +@cpw.mods.fml.common.API( + owner = API.ID_OWNER, + provides = "OpenComputersAPI|Prefab", + apiVersion = API.VERSION) +package li.cil.oc.api.prefab; + +import li.cil.oc.api.API; \ No newline at end of file diff --git a/src/main/java/mekanism/common/Mekanism.java b/src/main/java/mekanism/common/Mekanism.java index c1a80583b..7ac37a731 100644 --- a/src/main/java/mekanism/common/Mekanism.java +++ b/src/main/java/mekanism/common/Mekanism.java @@ -1,15 +1,16 @@ package mekanism.common; -import java.io.File; -import java.util.ArrayList; -import java.util.HashMap; -import java.util.HashSet; -import java.util.Iterator; -import java.util.List; -import java.util.Map; -import java.util.Set; -import java.util.UUID; - +import codechicken.multipart.handler.MultipartProxy; +import com.mojang.authlib.GameProfile; +import cpw.mods.fml.client.event.ConfigChangedEvent; +import cpw.mods.fml.common.*; +import cpw.mods.fml.common.Mod.EventHandler; +import cpw.mods.fml.common.Mod.Instance; +import cpw.mods.fml.common.event.*; +import cpw.mods.fml.common.eventhandler.SubscribeEvent; +import cpw.mods.fml.common.network.NetworkRegistry; +import cpw.mods.fml.common.registry.EntityRegistry; +import cpw.mods.fml.common.registry.GameRegistry; import mekanism.api.Coord4D; import mekanism.api.EnumColor; import mekanism.api.MekanismAPI; @@ -31,11 +32,7 @@ import mekanism.api.transmitters.TransmitterNetworkRegistry; import mekanism.client.ClientTickHandler; import mekanism.common.EnergyNetwork.EnergyTransferEvent; import mekanism.common.FluidNetwork.FluidTransferEvent; -import mekanism.common.Tier.BaseTier; -import mekanism.common.Tier.EnergyCubeTier; -import mekanism.common.Tier.FactoryTier; -import mekanism.common.Tier.InductionCellTier; -import mekanism.common.Tier.InductionProviderTier; +import mekanism.common.Tier.*; import mekanism.common.base.IChunkLoadHandler; import mekanism.common.base.IFactory.RecipeType; import mekanism.common.base.IModule; @@ -48,11 +45,7 @@ import mekanism.common.content.tank.SynchronizedTankData; import mekanism.common.content.transporter.PathfinderCache; import mekanism.common.content.transporter.TransporterManager; import mekanism.common.content.turbine.SynchronizedTurbineData; -import mekanism.common.entity.EntityBabySkeleton; -import mekanism.common.entity.EntityBalloon; -import mekanism.common.entity.EntityFlame; -import mekanism.common.entity.EntityObsidianTNT; -import mekanism.common.entity.EntityRobit; +import mekanism.common.entity.*; import mekanism.common.frequency.Frequency; import mekanism.common.frequency.FrequencyManager; import mekanism.common.integration.MekanismHooks; @@ -69,15 +62,7 @@ import mekanism.common.recipe.RecipeHandler.Recipe; import mekanism.common.recipe.inputs.ItemStackInput; import mekanism.common.recipe.machines.SmeltingRecipe; import mekanism.common.recipe.outputs.ItemStackOutput; -import mekanism.common.tile.TileEntityAdvancedBoundingBlock; -import mekanism.common.tile.TileEntityBoiler; -import mekanism.common.tile.TileEntityBoilerValve; -import mekanism.common.tile.TileEntityBoundingBlock; -import mekanism.common.tile.TileEntityCardboardBox; -import mekanism.common.tile.TileEntityElectricBlock; -import mekanism.common.tile.TileEntityEntangledBlock; -import mekanism.common.tile.TileEntitySolarEvaporationBlock; -import mekanism.common.tile.TileEntitySolarEvaporationValve; +import mekanism.common.tile.*; import mekanism.common.util.MekanismUtils; import mekanism.common.util.MekanismUtils.ResourceType; import mekanism.common.voice.VoiceServerManager; @@ -105,34 +90,13 @@ import net.minecraftforge.oredict.OreDictionary; import net.minecraftforge.oredict.RecipeSorter; import net.minecraftforge.oredict.RecipeSorter.Category; import net.minecraftforge.oredict.ShapelessOreRecipe; - import org.apache.logging.log4j.LogManager; import org.apache.logging.log4j.Logger; - import rebelkeithy.mods.metallurgy.api.IOreInfo; import rebelkeithy.mods.metallurgy.api.MetallurgyAPI; -import codechicken.multipart.handler.MultipartProxy; -import com.mojang.authlib.GameProfile; - -import cpw.mods.fml.client.event.ConfigChangedEvent; -import cpw.mods.fml.common.FMLCommonHandler; -import cpw.mods.fml.common.IFuelHandler; -import cpw.mods.fml.common.Mod; -import cpw.mods.fml.common.Mod.EventHandler; -import cpw.mods.fml.common.Mod.Instance; -import cpw.mods.fml.common.SidedProxy; -import cpw.mods.fml.common.event.FMLInitializationEvent; -import cpw.mods.fml.common.event.FMLInterModComms; -import cpw.mods.fml.common.event.FMLLoadCompleteEvent; -import cpw.mods.fml.common.event.FMLPostInitializationEvent; -import cpw.mods.fml.common.event.FMLPreInitializationEvent; -import cpw.mods.fml.common.event.FMLServerStartingEvent; -import cpw.mods.fml.common.event.FMLServerStoppingEvent; -import cpw.mods.fml.common.eventhandler.SubscribeEvent; -import cpw.mods.fml.common.network.NetworkRegistry; -import cpw.mods.fml.common.registry.EntityRegistry; -import cpw.mods.fml.common.registry.GameRegistry; +import java.io.File; +import java.util.*; /** * Mekanism - a Minecraft mod @@ -159,7 +123,7 @@ public class Mekanism public static Mekanism instance; /** Mekanism hooks instance */ - public static MekanismHooks hooks; + public static MekanismHooks hooks = new MekanismHooks(); /** Mekanism configuration instance */ public static Configuration configuration; @@ -1242,6 +1206,12 @@ public class Mekanism //Integrate with Waila FMLInterModComms.sendMessage("Waila", "register", "mekanism.common.integration.WailaDataProvider.register"); + //Integrate with OpenComputers + if(Loader.isModLoaded("OpenComputers")) + { + hooks.loadOCDrivers(); + } + //Packet registrations packetHandler.initialize(); @@ -1260,8 +1230,7 @@ public class Mekanism public void postInit(FMLPostInitializationEvent event) { logger.info("Fake player readout: UUID = " + gameProfile.getId().toString() + ", name = " + gameProfile.getName()); - - hooks = new MekanismHooks(); + hooks.hook(); MinecraftForge.EVENT_BUS.post(new BoxBlacklistEvent()); diff --git a/src/main/java/mekanism/common/base/IEnergyWrapper.java b/src/main/java/mekanism/common/base/IEnergyWrapper.java index aae2cb34a..6c7757a00 100644 --- a/src/main/java/mekanism/common/base/IEnergyWrapper.java +++ b/src/main/java/mekanism/common/base/IEnergyWrapper.java @@ -1,19 +1,18 @@ package mekanism.common.base; +import cofh.api.energy.IEnergyHandler; +import cpw.mods.fml.common.Optional.Interface; +import cpw.mods.fml.common.Optional.InterfaceList; import ic2.api.energy.tile.IEnergySink; import ic2.api.energy.tile.IEnergySource; import ic2.api.tile.IEnergyStorage; - -import java.util.EnumSet; - import mekanism.api.energy.ICableOutputter; import mekanism.api.energy.IStrictEnergyAcceptor; import mekanism.api.energy.IStrictEnergyStorage; import net.minecraft.inventory.IInventory; import net.minecraftforge.common.util.ForgeDirection; -import cofh.api.energy.IEnergyHandler; -import cpw.mods.fml.common.Optional.Interface; -import cpw.mods.fml.common.Optional.InterfaceList; + +import java.util.EnumSet; @InterfaceList({ @Interface(iface = "ic2.api.energy.tile.IEnergySink", modid = "IC2"), diff --git a/src/main/java/mekanism/common/block/BlockBasic.java b/src/main/java/mekanism/common/block/BlockBasic.java index 76138c972..8f1f30328 100644 --- a/src/main/java/mekanism/common/block/BlockBasic.java +++ b/src/main/java/mekanism/common/block/BlockBasic.java @@ -1,10 +1,9 @@ package mekanism.common.block; -import java.util.ArrayList; -import java.util.Arrays; -import java.util.List; -import java.util.Random; - +import buildcraft.api.tools.IToolWrench; +import cpw.mods.fml.common.FMLCommonHandler; +import cpw.mods.fml.relauncher.Side; +import cpw.mods.fml.relauncher.SideOnly; import mekanism.api.Coord4D; import mekanism.api.Range4D; import mekanism.api.energy.IEnergizedItem; @@ -24,18 +23,7 @@ import mekanism.common.content.tank.TankUpdateProtocol; import mekanism.common.inventory.InventoryBin; import mekanism.common.item.ItemBlockBasic; import mekanism.common.network.PacketTileEntity.TileEntityMessage; -import mekanism.common.tile.TileEntityBasicBlock; -import mekanism.common.tile.TileEntityBin; -import mekanism.common.tile.TileEntityDynamicTank; -import mekanism.common.tile.TileEntityDynamicValve; -import mekanism.common.tile.TileEntityInductionCasing; -import mekanism.common.tile.TileEntityInductionCell; -import mekanism.common.tile.TileEntityInductionPort; -import mekanism.common.tile.TileEntityInductionProvider; -import mekanism.common.tile.TileEntityMultiblock; -import mekanism.common.tile.TileEntitySolarEvaporationBlock; -import mekanism.common.tile.TileEntitySolarEvaporationController; -import mekanism.common.tile.TileEntitySolarEvaporationValve; +import mekanism.common.tile.*; import mekanism.common.util.MekanismUtils; import net.minecraft.block.Block; import net.minecraft.block.material.Material; @@ -58,9 +46,11 @@ import net.minecraft.world.World; import net.minecraftforge.common.util.ForgeDirection; import net.minecraftforge.fluids.FluidContainerRegistry; import net.minecraftforge.fluids.FluidStack; -import cpw.mods.fml.common.FMLCommonHandler; -import cpw.mods.fml.relauncher.Side; -import cpw.mods.fml.relauncher.SideOnly; + +import java.util.ArrayList; +import java.util.Arrays; +import java.util.List; +import java.util.Random; /** * Block class for handling multiple metal block IDs. @@ -479,6 +469,28 @@ public class BlockBasic extends Block implements IBlockCTM, ICustomBlockIcon { TileEntityBin bin = (TileEntityBin)world.getTileEntity(x, y, z); + Item tool = entityplayer.getCurrentEquippedItem().getItem(); + + if(MekanismUtils.hasUsableWrench(entityplayer, x, y, z)) + { + if(entityplayer.isSneaking()) + { + dismantleBlock(world, x, y, z, false); + return true; + } + + if(MekanismUtils.isBCWrench(tool)) + { + ((IToolWrench)tool).wrenchUsed(entityplayer, x, y, z); + } + + int change = ForgeDirection.ROTATION_MATRIX[ForgeDirection.UP.ordinal()][bin.facing]; + + bin.setFacing((short)change); + world.notifyBlocksOfNeighborChange(x, y, z, this); + return true; + } + if(bin.getItemCount() < bin.MAX_STORAGE) { if(bin.addTicks == 0 && entityplayer.getCurrentEquippedItem() != null) diff --git a/src/main/java/mekanism/common/integration/IComputerIntegration.java b/src/main/java/mekanism/common/integration/IComputerIntegration.java new file mode 100644 index 000000000..15fe642a6 --- /dev/null +++ b/src/main/java/mekanism/common/integration/IComputerIntegration.java @@ -0,0 +1,16 @@ +package mekanism.common.integration; + +import cpw.mods.fml.common.Optional; +import dan200.computercraft.api.peripheral.IPeripheral; +import net.minecraft.inventory.IInventory; + +/** + * Created by aidancbrady on 7/20/15. + */ +@Optional.Interface(iface = "dan200.computercraft.api.peripheral.IPeripheral", modid = "ComputerCraft") +public interface IComputerIntegration extends IInventory, IPeripheral +{ + public String[] getMethods(); + + public Object[] invoke(String method, Object[] args) throws Exception; +} diff --git a/src/main/java/mekanism/common/integration/MekanismHooks.java b/src/main/java/mekanism/common/integration/MekanismHooks.java index 7b6f0afc1..96d6f6920 100644 --- a/src/main/java/mekanism/common/integration/MekanismHooks.java +++ b/src/main/java/mekanism/common/integration/MekanismHooks.java @@ -1,14 +1,11 @@ package mekanism.common.integration; -import ic2.api.recipe.IRecipeInput; -import ic2.api.recipe.RecipeInputItemStack; -import ic2.api.recipe.RecipeInputOreDict; -import ic2.api.recipe.RecipeOutput; -import ic2.api.recipe.Recipes; - -import java.util.List; -import java.util.Map; - +import cpw.mods.fml.common.Loader; +import cpw.mods.fml.common.Optional.Method; +import cpw.mods.fml.common.event.FMLInterModComms; +import dan200.computercraft.api.ComputerCraftAPI; +import ic2.api.recipe.*; +import li.cil.oc.api.Driver; import mekanism.common.Mekanism; import mekanism.common.MekanismBlocks; import mekanism.common.MekanismItems; @@ -19,10 +16,9 @@ import mekanism.common.util.MekanismUtils; import net.minecraft.init.Items; import net.minecraft.item.ItemStack; import net.minecraft.nbt.NBTTagCompound; -import cpw.mods.fml.common.Loader; -import cpw.mods.fml.common.Optional.Method; -import cpw.mods.fml.common.event.FMLInterModComms; -import dan200.computercraft.api.ComputerCraftAPI; + +import java.util.List; +import java.util.Map; /** * Hooks for Mekanism. Use to grab items or blocks out of different mods. @@ -126,8 +122,16 @@ public final class MekanismHooks public void loadCCPeripheralProviders() { try { - ComputerCraftAPI.registerPeripheralProvider((BlockMachine) MekanismBlocks.MachineBlock); - } catch(Exception ex) {} + ComputerCraftAPI.registerPeripheralProvider((BlockMachine)MekanismBlocks.MachineBlock); + } catch(Exception e) {} + } + + @Method(modid = "OpenComputers") + public void loadOCDrivers() + { + try { + Driver.add(new OCDriver()); + } catch(Exception e) {} } public void addPulverizerRecipe(ItemStack input, ItemStack output, int energy) diff --git a/src/main/java/mekanism/common/integration/OCDriver.java b/src/main/java/mekanism/common/integration/OCDriver.java new file mode 100644 index 000000000..bf27a4c00 --- /dev/null +++ b/src/main/java/mekanism/common/integration/OCDriver.java @@ -0,0 +1,78 @@ +package mekanism.common.integration; + +import li.cil.oc.api.Network; +import li.cil.oc.api.driver.NamedBlock; +import li.cil.oc.api.machine.Arguments; +import li.cil.oc.api.machine.Context; +import li.cil.oc.api.network.ManagedPeripheral; +import li.cil.oc.api.network.Visibility; +import li.cil.oc.api.prefab.DriverTileEntity; +import li.cil.oc.api.prefab.ManagedEnvironment; +import net.minecraft.tileentity.TileEntity; +import net.minecraft.world.World; + +import java.util.Locale; + +/** + * Created by aidancbrady on 7/20/15. + */ +public class OCDriver extends DriverTileEntity +{ + @Override + public Class getTileEntityClass() + { + return IComputerIntegration.class; + } + + @Override + public ManagedEnvironment createEnvironment(World world, int x, int y, int z) + { + TileEntity tile = world.getTileEntity(x, y, z); + + if(tile instanceof IComputerIntegration) + { + return new OCManagedEnvironment((IComputerIntegration)tile); + } + + return null; + } + + public class OCManagedEnvironment extends ManagedEnvironment implements NamedBlock, ManagedPeripheral + { + public IComputerIntegration computerTile; + + public String name; + + public OCManagedEnvironment(IComputerIntegration tile) + { + computerTile = tile; + name = tile.getInventoryName().toLowerCase(Locale.ENGLISH).replace(" ", "_"); + + setNode(Network.newNode(this, Visibility.Network).withComponent(name, Visibility.Network).create()); + } + + @Override + public String[] methods() + { + return computerTile.getMethods(); + } + + @Override + public Object[] invoke(String method, Context context, Arguments args) throws Exception + { + return computerTile.invoke(method, args.toArray()); + } + + @Override + public int priority() + { + return 1; + } + + @Override + public String preferredName() + { + return name; + } + } +} \ No newline at end of file diff --git a/src/main/java/mekanism/common/multipart/PartTransmitter.java b/src/main/java/mekanism/common/multipart/PartTransmitter.java index 5d9ff6ad0..5c6d90f8d 100644 --- a/src/main/java/mekanism/common/multipart/PartTransmitter.java +++ b/src/main/java/mekanism/common/multipart/PartTransmitter.java @@ -1,15 +1,16 @@ package mekanism.common.multipart; -import java.util.Collection; - +import mekanism.api.Chunk3D; +import mekanism.api.Coord4D; import mekanism.api.transmitters.DynamicNetwork; import mekanism.api.transmitters.DynamicNetwork.NetworkClientRequest; import mekanism.api.transmitters.ITransmitterTile; import mekanism.api.transmitters.TransmitterNetworkRegistry; - import net.minecraftforge.common.MinecraftForge; import net.minecraftforge.common.util.ForgeDirection; +import java.util.Collection; + public abstract class PartTransmitter> extends PartSidedPipe implements ITransmitterTile { public MultipartTransmitter transmitterDelegate; @@ -32,6 +33,7 @@ public abstract class PartTransmitter> extends if(!world().isRemote) { + System.out.println("Reload " + new Chunk3D(Coord4D.get(tile()))); TransmitterNetworkRegistry.registerOrphanTransmitter(getTransmitter()); } else { @@ -50,6 +52,7 @@ public abstract class PartTransmitter> extends if(!world().isRemote) { + System.out.println("Unload " + new Chunk3D(Coord4D.get(tile()))); getTransmitter().takeShare(); TransmitterNetworkRegistry.invalidateTransmitter(getTransmitter()); } diff --git a/src/main/java/mekanism/common/tile/TileEntityElectricMachine.java b/src/main/java/mekanism/common/tile/TileEntityElectricMachine.java index 968793c2a..6c64a7d2c 100644 --- a/src/main/java/mekanism/common/tile/TileEntityElectricMachine.java +++ b/src/main/java/mekanism/common/tile/TileEntityElectricMachine.java @@ -1,16 +1,14 @@ package mekanism.common.tile; -import java.util.ArrayList; - +import cpw.mods.fml.common.Optional.Method; +import dan200.computercraft.api.lua.ILuaContext; +import dan200.computercraft.api.lua.LuaException; +import dan200.computercraft.api.peripheral.IComputerAccess; import mekanism.api.Coord4D; import mekanism.api.EnumColor; import mekanism.api.Range4D; import mekanism.api.transmitters.TransmissionType; -import mekanism.common.Mekanism; -import mekanism.common.MekanismBlocks; -import mekanism.common.MekanismItems; -import mekanism.common.SideData; -import mekanism.common.Upgrade; +import mekanism.common.*; import mekanism.common.base.IFactory.RecipeType; import mekanism.common.network.PacketTileEntity.TileEntityMessage; import mekanism.common.recipe.RecipeHandler; @@ -25,10 +23,8 @@ import mekanism.common.util.InventoryUtils; import mekanism.common.util.MekanismUtils; import mekanism.common.util.MekanismUtils.ResourceType; import net.minecraft.item.ItemStack; -import cpw.mods.fml.common.Optional.Method; -import dan200.computercraft.api.lua.ILuaContext; -import dan200.computercraft.api.lua.LuaException; -import dan200.computercraft.api.peripheral.IComputerAccess; + +import java.util.ArrayList; public abstract class TileEntityElectricMachine> extends TileEntityBasicMachine { @@ -258,7 +254,6 @@ public abstract class TileEntityElectricMachine