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 extends EnvironmentHost> 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"/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+ * 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
+ * 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 "/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
+ * 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