Cool new factory textures (thanks @Radviger), also a (temporarily unused) OC layer. Does this look good @Vexatos?

This commit is contained in:
aidancbrady committed 2015-07-20 10:53:12 -07:00
1 parent 2c88357477
commit d39536d89c
195 files changed
+9502 -111

No files matched your search

+25
View File
@@ -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.
* <p/>
* 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;
}
+20
View File
@@ -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.
* <p/>
* Changed to the actual tab if OC is present. Preferably you do
* <em>not</em> 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() {
}
}
+174
View File
@@ -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.
* <p/>
* 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.
* <p/>
* Note that these methods should <em>not</em> 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.
* <p/>
* 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.
* <p/>
* This must be called in the init phase, <em>not</em> 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.
* <p/>
* Item components can inserted into a computers component slots. They have
* to specify their type, to determine into which slots they can fit.
* <p/>
* This must be called in the init phase, <em>not</em> 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.
* <p/>
* Type converters are used to automatically convert values returned from
* callbacks to a "simple" format that can be pushed to any architecture.
* <p/>
* This must be called in the init phase, <em>not</em> 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.
* <p/>
* 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 <em>not</em>
* 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 <tt>null</tt> 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.
* <p/>
* 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 <tt>null</tt> 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.
* <p/>
* 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.
* <p/>
* 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 <tt>null</tt> 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.
* <p/>
* 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.
* <p/>
* The returned collection is read-only.
*
* @return the list of all registered block drivers.
*/
public static Collection<Block> blockDrivers() {
if (API.driver != null)
return API.driver.blockDrivers();
return null;
}
/**
* Get a list of all registered item drivers.
* <p/>
* 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.
* <p/>
* The returned collection is read-only.
*
* @return the list of all registered item drivers.
*/
public static Collection<Item> itemDrivers() {
if (API.driver != null)
return API.driver.itemDrivers();
return null;
}
// ----------------------------------------------------------------------- //
private Driver() {
}
}
+297
View File
@@ -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.
* <p/>
* File systems created this way and wrapped in a managed environment via
* {@link #asManagedEnvironment} or its overloads will appear as
* <tt>filesystem</tt> components in the component network. Note that the
* component's visibility is set to <tt>Neighbors</tt> 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.
* <p/>
* Note that these methods should <em>not</em> 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.
* <p/>
* This can be used to wrap a folder in the assets folder of your mod's JAR.
* The actual path is built like this:
* <pre>"/assets/" + domain + "/" + root</pre>
* <p/>
* 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).
* <p/>
* If the specified path cannot be located, the creation fails and this
* returns <tt>null</tt>.
*
* @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 <em>writable</em> file system in the save folder.
* <p/>
* 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:
* <pre>"saves/" + WORLD_NAME + "/opencomputers/" + root</pre>
* The first part may differ, in particular for servers.
* <p/>
* Usually the name will be the address of the node used to represent the
* file system.
* <p/>
* 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
* <tt>buffered</tt> 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 <em>writable</em> file system that resides in memory.
* <p/>
* Any contents created and written on this file system will be lost when
* the node is removed from the network.
* <p/>
* This is used for computers' <tt>/tmp</tt> 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.
* <p/>
* 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.
* <p/>
* 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 <tt>from???</tt> 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.
* <p/>
* 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.
* <p/>
* 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.
* <p/>
* The container may be <tt>null</tt>, if no such context can be provided.
* <p/>
* 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 <tt>null</tt> to create a silent file system.
* <p/>
* 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.
* <tt>opencomputers:floppy_access</tt>.
* @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.
* <p/>
* 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.
* <tt>opencomputers:floppy_access</tt>.
* @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.
* <p/>
* 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.
* <tt>opencomputers:floppy_access</tt>.
* @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.
* <p/>
* 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.
* <tt>opencomputers:floppy_access</tt>.
* @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.
* <p/>
* 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.
* <p/>
* 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.
* <p/>
* 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() {
}
}
+339
View File
@@ -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.
* <p/>
* 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.
* <p/>
* This also servers to document of all IMC messages OpenComputers handles.
* <p/>
* 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 <em>any</em>
* registered filter will be disabled. For example, if a filter rejects the
* computer case item stacks, robots can not be assembled.
* <p/>
* Signature of callbacks must be:
* <pre>
* boolean callback(ItemStack stack)
* </pre>
* <p/>
* Callbacks must be declared as <tt>packagePath.className.methodName</tt>.
* For example: <tt>com.example.Integration.callbackMethod</tt>.
*
* @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.
* <p/>
* Signature of callbacks must be:
* <pre>
* boolean select(ItemStack stack)
* Object[] validate(IInventory inventory)
* Object[] assemble(IInventory inventory)
* </pre>
* Values in the array returned by <tt>validate</tt> must be one of the following:
* <pre>
* // 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[]}
* </pre>
* Values in the array returned by <tt>assemble</tt> must be one of the following:
* <pre>
* // The assembled device.
* new Object[]{ItemStack}
* // The assembled device and energy cost (which also determines assembly duration).
* new Object[]{ItemStack, Number}
* </pre>
* <p/>
* Callbacks must be declared as <tt>packagePath.className.methodName</tt>.
* For example: <tt>com.example.Integration.callbackMethod</tt>.
*
* @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 <tt>null</tt> 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 <tt>null</tt>
* 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<Pair<String, Integer>> 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<String, Integer> 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.
* <p/>
* The <tt>disassemble</tt> 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).
* <p/>
* Signature of callbacks must be:
* <pre>
* boolean select(ItemStack stack)
* ItemStack[] disassemble(ItemStack stack, ItemStack[] ingredients)
* </pre>
* <p/>
* Callbacks must be declared as <tt>packagePath.className.methodName</tt>.
* For example: <tt>com.example.Integration.callbackMethod</tt>.
*
* @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.
* <p/>
* If your provider does not handle a tool/item, return <tt>Double.NaN</tt>
* to indicate that another provider should be queried. The first value
* that isn't <tt>NaN</tt> will be used as the durability.
* <p/>
* The returned value must be the <em>relative</em> durability of the tool,
* in a range of [0,1], with 0 being broken, 1 being new/fully repaired.
* <p/>
* Signature of callbacks must be:
* <pre>
* double callback(ItemStack stack)
* </pre>
* <p/>
* Callbacks must be declared as <tt>packagePath.className.methodName</tt>.
* For example: <tt>com.example.Integration.callbackMethod</tt>.
*
* @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.
* <p/>
* 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.
* <p/>
* The returned value must be <tt>true</tt> if the wrench was used/usable,
* <tt>false</tt> otherwise.
* <p/>
* Signature of callbacks must be:
* <pre>
* boolean callback(EntityPlayer player, int x, int y, int z, boolean changeDurability)
* </pre>
* <p/>
* Callbacks must be declared as <tt>packagePath.className.methodName</tt>.
* For example: <tt>com.example.Integration.callbackMethod</tt>.
*
* @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.
* <p/>
* This is used by the charger to determine whether items can be charged
* by it (<tt>canCharge</tt>) and to actually charge them (<tt>charge</tt>).
* <p/>
* Note that OpenComputers comes with a few built-in handlers for third-
* party charged items, such as Redstone Flux and IndustrialCraft 2.
* <p/>
* Signature of callbacks must be:
* <pre>
* boolean canCharge(ItemStack stack)
* double charge(ItemStack stack, double amount, boolean simulate)
* </pre>
* <p/>
* Callbacks must be declared as <tt>packagePath.className.methodName</tt>.
* For example: <tt>com.example.Integration.callbackMethod</tt>.
*
* @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.
* <p/>
* Default providers in OpenComputers are one for the ink cartridges as
* well as one for arbitrary dyes (via the OreDictionary).
* <p/>
* 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.
* <p/>
* Signature of callbacks must be:
* <pre>
* int callback(ItemStack stack)
* </pre>
* <p/>
* Callbacks must be declared as <tt>packagePath.className.methodName</tt>.
* For example: <tt>com.example.Integration.callbackMethod</tt>.
*
* @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.
* <p/>
* 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.
* <p/>
* 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.
* <p/>
* 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() {
}
}
+101
View File
@@ -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.
* <p/>
* 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.
* <p/>
* Note that these methods should <em>not</em> 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
* <tt>null</tt> 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 <tt>null</tt>
* 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.
* <p/>
* The disk will be listed in the creative tab of OpenComputers.
* <p/>
* 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.
* <p/>
* 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<li.cil.oc.api.fs.FileSystem> factory) {
if (API.items != null)
return API.items.registerFloppy(name, color, factory);
return null;
}
/**
* Register a single custom EEPROM.
* <p/>
* The EEPROM will be listed in the creative tab of OpenComputers.
* <p/>
* The EEPROM will be initialized with the specified code and data byte
* arrays. For script code (e.g. a Lua script) use <tt>String.getBytes("UTF-8")</tt>.
* You can omit any of the arguments by passing <tt>null</tt>.
*
* @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() {
}
}
+73
View File
@@ -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.
* <p/>
* 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.
* <p/>
* Note that registration of architectures is optional and only intended as a
* convenience feature to make architectures usable via the built-in CPUs.
* <p/>
* Note that these methods should <em>not</em> 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.
* <p/>
* 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<? extends Architecture> architecture) {
if (API.machine != null)
API.machine.add(architecture);
}
/**
* A list of all <em>registered</em> architectures.
*/
public static Collection<Class<? extends Architecture>> architectures() {
if (API.machine != null)
return API.machine.architectures();
return Collections.emptyList();
}
/**
* Creates a new machine for the specified host.
* <p/>
* 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<? extends Architecture> LuaArchitecture = null;
}
+184
View File
@@ -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.
* <p/>
* It allows opening the manual at a desired specific page, as well as
* registering custom tabs and content callback handlers.
* <p/>
* Note: this is a <em>client side only</em> API. It will do nothing on
* dedicated servers (i.e. <tt>API.manual</tt> will be <tt>null</tt>).
*/
public class Manual {
/**
* Register a tab to be displayed next to the manual.
* <p/>
* 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 <tt>null</tt>.
* @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.
* <p/>
* 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.
* <p/>
* Content providers are used to resolve paths to page content, if the
* standard system (using Minecraft's resource loading facilities) fails.
* <p/>
* 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.
* <p/>
* 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. <tt>![tooltip](prefix:data)</tt> will select the
* image provider registered for the prefix <tt>prefix</tt>, and pass to
* it the argument <tt>data</tt>, then use the returned renderer to draw
* an element in the place of the tag. The provided prefix is expected to
* be <em>without</em> the colon (<tt>:</tt>).
* <p/>
* 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.
* <p/>
* 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 <tt>null</tt>.
*
* @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, <tt>null</tt> 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, <tt>null</tt> 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 <tt>null</tt> if none exists.
*/
public static Iterable<String> contentFor(String path) {
if (API.manual != null)
return API.manual.contentFor(path);
return null;
}
// ----------------------------------------------------------------------- //
/**
* Open the manual for the specified player.
* <p/>
* 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() {
}
}
+217
View File
@@ -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.
* <p/>
* 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.
* <p/>
* 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.
* <p/>
* Note that these methods should <em>not</em> 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.
* <p/>
* 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.
* <p/>
* 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.
* <p/>
* 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.
* <p/>
* OpenComputers tracks endpoints to which to send wireless packets sent
* via the {@link #sendWirelessPacket(WirelessEndpoint, double, Packet)}
* method. The packets will <em>only</em> be sent to endpoints registered
* with the network.
* <p/>
* <em>Important</em>: when your endpoint is removed from the world,
* <em>you must ensure it is also removed from the network</em>!
*
* @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.
* <p/>
* 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).
* <p/>
* 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.
* <p/>
* This must be called when an endpoint becomes invalid, otherwise it will
* remain in the network!
* <p/>
* 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.
* <p/>
* 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.
* <p/>
* 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.
* <p/>
* Example use:
* <pre>
* 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_; }
*
* // ...
* }
* </pre>
* <p/>
* Note that the <em>reachability</em> specified here is the general
* availability of the created node to other nodes in the network. Special
* rules apply to components, which have a <em>visibility</em> that is used
* to control how they can be reached from computers. For example, network
* cards have a <em>reachability</em> of <tt>Visibility.Network</tt>, to
* allow them to communicate with each other, but a <em>visibility</em> of
* <tt>Visibility.Neighbors</tt> 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.
* <p/>
* 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 <tt>network.message</tt>.
*
* @param source the address of the sending node.
* @param destination the address of the destination, or <tt>null</tt>
* 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() {
}
}
+25
View File
@@ -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.
* <p/>
* 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);
}
+85
View File
@@ -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
+47
View File
@@ -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.
* <p/>
* You can obtain an instance of the keyboard component via the item driver
* of the keyboard block, for example:
* <pre>
* 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);
* </pre>
*/
public interface Keyboard extends Environment, Persistable {
/**
* Sets a custom usability override.
* <p/>
* 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.
* <p/>
* Pass <tt>null</tt> 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);
}
}
+582
View File
@@ -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.
* <p/>
* This allows re-using the built-in screen logic in third-party code without
* access to the internals of OC.
* <p/>
* To get an instance of the buffer component, use its item driver, e.g.:
* <pre>
* 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);
* </pre>
*/
public interface TextBuffer extends ManagedEnvironment, Persistable {
/**
* Controls how much energy the buffer will consume per tick.
* <p/>
* This is <em>not</em> 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.
* <p/>
* 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.
* <p/>
* 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.
* <p/>
* 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.
* <p/>
* 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.
* <p/>
* Note that this is in fact <tt>width / height</tt>.
*
* @see #setAspectRatio(double, double)
*/
double getAspectRatio();
/**
* Set the buffer's active resolution.
*
* @param width the horizontal resolution.
* @param height the vertical resolution.
* @return <tt>true</tt> 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.
* <p/>
* Note that this is the <em>maximum</em> 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 <tt>true</tt> 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.
* <p/>
* 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.
* <p/>
* 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.
* <p/>
* 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.
* <p/>
* 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 <tt>true</tt>if <tt>color</tt> specifies a palette index.
*/
void setForegroundColor(int color, boolean isFromPalette);
/**
* The active foreground color.
*/
int getForegroundColor();
/**
* <tt>true</tt> 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.
* <p/>
* 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.
* <p/>
* 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 <tt>true</tt>if <tt>color</tt> specifies a palette index.
*/
void setBackgroundColor(int color, boolean isFromPalette);
/**
* The active background color.
*/
int getBackgroundColor();
/**
* <tt>true</tt> 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.
* <p/>
* 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.
* <p/>
* 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.
* <p/>
* 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 <tt>true</tt> 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.
* <p/>
* <em>Important</em>: 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.
* <p/>
* <em>Important</em>: 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.
* <p/>
* 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.
* <p/>
* <em>Important</em>: 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.
* <p/>
* This will convert the specified RGB data (in <tt>0xRRGGBB</tt> 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.
* <p/>
* <em>Important</em>: 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.
* <p/>
* This will convert the specified RGB data (in <tt>0xRRGGBB</tt> 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.
* <p/>
* <em>Important</em>: 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 <em>text</em> displayed on the buffer.
* <p/>
* 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.
* <p/>
* You can use this to either render the text in a GUI or in the world.
*
* @return <tt>true</tt> if the displayed content changed since the last
* call to this method.
*/
@SideOnly(Side.CLIENT)
boolean renderText();
/**
* The natural width of the rendered text.
* <p/>
* 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.
* <p/>
* 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.
* <p/>
* 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.
* <p/>
* 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 <tt>null</tt> on the client side.
*/
void keyDown(char character, int code, EntityPlayer player);
/**
* Signals a key up event for the buffer.
* <p/>
* 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 <tt>null</tt> on the client side.
*/
void keyUp(char character, int code, EntityPlayer player);
/**
* Signals a clipboard paste event for the buffer.
* <p/>
* 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 <tt>null</tt> on the client side.
*/
void clipboard(String value, EntityPlayer player);
/**
* Signals a mouse button down event for the buffer.
* <p/>
* 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 <tt>null</tt> on the client side.
*/
void mouseDown(double x, double y, int button, EntityPlayer player);
/**
* Signals a mouse drag event for the buffer.
* <p/>
* 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 <tt>null</tt> on the client side.
*/
void mouseDrag(double x, double y, int button, EntityPlayer player);
/**
* Signals a mouse button release event for the buffer.
* <p/>
* 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 <tt>null</tt> on the client side.
*/
void mouseUp(double x, double y, int button, EntityPlayer player);
/**
* Signals a mouse wheel scroll event for the buffer.
* <p/>
* 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 <tt>null</tt> 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
}
}
+14
View File
@@ -0,0 +1,14 @@
/**
* This package provides interfaces to allow interacting with some components.
* <p/>
* 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;
+150
View File
@@ -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 <T> the type of the node created by this builder.
*/
public interface Builder<T extends Node> {
/**
* Finalizes the construction of the node.
* <p/>
* 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<Node> {
/**
* Makes the node a component.
* <p/>
* 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.
* <p/>
* Like {@link #withComponent(String, Visibility)}, but with a default
* visibility set to the <em>reachability</em> 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.
* <p/>
* 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.
* <p/>
* 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 <em>see</em> the component.
*/
public static interface ComponentBuilder extends Builder<Component> {
/**
* Makes the node a connector.
* <p/>
* 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.
* <p/>
* 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<Connector> {
/**
* Makes the node a component.
* <p/>
* 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.
* <p/>
* Like {@link #withComponent(String, Visibility)}, but with a default
* visibility set to the <em>reachability</em> 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 <em>and</em> connector node.
*/
public static interface ComponentConnectorBuilder extends Builder<ComponentConnector> {
}
}
+119
View File
@@ -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.
* <p/>
* 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.
* <p/>
* This must be called in the init phase, <em>not</em> 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.
* <p/>
* Item components can inserted into a computers component slots. They have
* to specify their type, to determine into which slots they can fit.
* <p/>
* This must be called in the init phase, <em>not</em> the pre- or post-init
* phases.
*
* @param driver the driver for an item component.
*/
void add(Item driver);
/**
* Registers a new type converter.
* <p/>
* Type converters are used to automatically convert values returned from
* callbacks to a "simple" format that can be pushed to any architecture.
* <p/>
* This must be called in the init phase, <em>not</em> 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.
* <p/>
* 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 <em>not</em>
* 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 <tt>null</tt> if there is none.
*/
Block driverFor(World world, int x, int y, int z);
/**
* Looks up a driver for the specified item stack.
* <p/>
* 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 <tt>null</tt> if there is none.
*/
Item driverFor(ItemStack stack, Class<? extends EnvironmentHost> host);
/**
* Looks up a driver for the specified item stack.
* <p/>
* 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.
* <p/>
* 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 <tt>null</tt> if there is none.
*/
Item driverFor(ItemStack stack);
/**
* Get a list of all registered block drivers.
* <p/>
* 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<Block> blockDrivers();
/**
* Get a list of all registered item drivers.
* <p/>
* 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<Item> itemDrivers();
}
+181
View File
@@ -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.
* <p/>
* This can be used to wrap a folder in the assets folder of your mod's JAR.
* The actual path is built like this:
* <pre>"/assets/" + domain + "/" + root</pre>
* <p/>
* 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).
* <p/>
* If the specified path cannot be located, the creation fails and this
* returns <tt>null</tt>.
*
* @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 <em>writable</em> file system in the save folder.
* <p/>
* 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:
* <pre>"saves/" + WORLD_NAME + "/opencomputers/" + root</pre>
* The first part may differ, in particular for servers.
* <p/>
* Usually the name will be the address of the node used to represent the
* file system.
* <p/>
* 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 <em>writable</em> file system that resides in memory.
* <p/>
* Any contents created and written on this file system will be lost when
* the node is removed from the network.
* <p/>
* This is used for computers' <tt>/tmp</tt> 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.
* <p/>
* 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.
* <p/>
* If the passed type is unsupported, this will return <tt>null</tt>.
*
* @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 <tt>from???</tt> 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.
* <p/>
* 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.
* <p/>
* 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.
* <p/>
* The container may be <tt>null</tt>, if no such context can be provided.
* <p/>
* 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 <tt>null</tt> to create a silent file system.
* <p/>
* 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.
* <tt>opencomputers:floppy_access</tt>.
* @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.
* <p/>
* 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.
* <tt>opencomputers:floppy_access</tt>.
* @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);
}
+76
View File
@@ -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.
* <p/>
* 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
* <tt>null</tt> 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 <tt>null</tt>
* if the stack is not a valid OpenComputers item or block.
*/
ItemInfo get(ItemStack stack);
/**
* Register a single loot floppy disk.
* <p/>
* The disk will be listed in the creative tab of OpenComputers.
* <p/>
* 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.
* <p/>
* To use some directory in your mod JAR as the directory provided by the
* loot disk, use {@link FileSystem#fromClass} in your callable.
* <p/>
* Call this in the init phase or later, <em>not</em> 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<li.cil.oc.api.fs.FileSystem> factory);
/**
* Register a single custom EEPROM.
* <p/>
* The EEPROM will be listed in the creative tab of OpenComputers.
* <p/>
* The EEPROM will be initialized with the specified code and data byte
* arrays. For script code (e.g. a Lua script) use <tt>String.getBytes("UTF-8")</tt>.
* You can omit any of the arguments by passing <tt>null</tt>.
* <p/>
* Call this in the init phase or later, <em>not</em> 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);
}
+50
View File
@@ -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.
* <p/>
* 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 <tt>null</tt>.
* <p/>
* Note that OpenComputers represents most of its items using just a few
* actual <tt>Block</tt> 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 <tt>null</tt>.
* <p/>
* Note that OpenComputers represents most of its items using just a few
* actual <tt>Item</tt> 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);
}
+43
View File
@@ -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.
* <p/>
* 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<? extends Architecture> architecture);
/**
* A list of all <em>registered</em> architectures.
* <p/>
* 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<Class<? extends Architecture>> architectures();
/**
* Creates a new machine for the specified host.
* <p/>
* 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);
}
+136
View File
@@ -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.
* <p/>
* 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 <tt>null</tt>.
* @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.
* <p/>
* 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.
* <p/>
* Content providers are used to resolve paths to page content, if the
* standard system (using Minecraft's resource loading facilities) fails.
* <p/>
* This can be useful for providing dynamic content, for example.
*
* @param provider the provider to register.
*/
void addProvider(ContentProvider provider);
/**
* Register an image provider.
* <p/>
* 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. <tt>![tooltip](prefix:data)</tt> will select the
* image provider registered for the prefix <tt>prefix</tt>, and pass to
* it the argument <tt>data</tt>, then use the returned renderer to draw
* an element in the place of the tag.
* <p/>
* 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, <tt>null</tt> 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, <tt>null</tt> 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.
* <p/>
* The provided path may contain the special variable <tt>%LANGUAGE%</tt>,
* which will be resolved to the currently set language, falling back to
* <tt>en_US</tt>.
*
* @param path the path of the page to get the content of.
* @return the content of the page, or <tt>null</tt> if none exists.
*/
Iterable<String> contentFor(String path);
/**
* Get the image renderer for the specified image path.
* <p/>
* 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 <tt>null</tt>.
*
* @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.
* <p/>
* 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);
}
+163
View File
@@ -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.
* <p/>
* 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.
* <p/>
* 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.
* <p/>
* 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.
* <p/>
* OpenComputers tracks endpoints to which to send wireless packets sent
* via the {@link #sendWirelessPacket(WirelessEndpoint, double, Packet)}
* method. The packets will <em>only</em> be sent to endpoints registered
* with the network.
* <p/>
* <em>Important</em>: when your endpoint is removed from the world,
* <em>you must ensure it is also removed from the network</em>!
*
* @param endpoint the endpoint to register with the network.
*/
void joinWirelessNetwork(WirelessEndpoint endpoint);
/**
* Updates a wireless endpoint in the wireless network.
* <p/>
* 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).
* <p/>
* 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.
* <p/>
* This must be called when an endpoint becomes invalid, otherwise it will
* remain in the network!
* <p/>
* 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.
* <p/>
* 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.
* <p/>
* 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.
* <p/>
* Example use:
* <pre>
* 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_; }
*
* // ...
* }
* </pre>
* <p/>
* Note that the <em>reachability</em> specified here is the general
* availability of the created node to other nodes in the network. Special
* rules apply to components, which have a <em>visibility</em> that is used
* to control how they can be reached from computers. For example, network
* cards have a <em>reachability</em> of <tt>Visibility.Network</tt>, to
* allow them to communicate with each other, but a <em>visibility</em> of
* <tt>Visibility.Neighbors</tt> 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.
* <p/>
* 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 <tt>network.message</tt>.
*
* @param source the address of the sending node.
* @param destination the address of the destination, or <tt>null</tt>
* 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);
}
+6
View File
@@ -0,0 +1,6 @@
/**
* This package contains implementation detail interfaces. You will not have to
* interact with these interfaces directly (except for the <tt>Builder</tt>),
* and you particularly should not implement these interfaces yourself.
*/
package li.cil.oc.api.detail;
+62
View File
@@ -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.
* <p/>
* 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}).
* <p/>
* A block driver is used by <tt>Adapter</tt> 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.
* <p/>
* 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.
* <p/>
* This is used to determine which driver to use for a block placed next to
* an <tt>Adapter</tt> 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 <tt>true</tt> if the block is supported; <tt>false</tt> otherwise.
*/
boolean worksWith(World world, int x, int y, int z);
/**
* Create a new managed environment interfacing the specified block.
* <p/>
* This is used to connect the component to the component network when it
* is detected next to an <tt>Adapter</tt>. 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 <tt>null</tt> here.
* <p/>
* This is expected to return a <em>new instance</em> each time it is
* called. The created instance's life cycle is managed by the
* <tt>Adapter</tt> 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);
}
+30
View File
@@ -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.
* <p/>
* Note that converters operating on the same object type may override each
* other when using the same keys in the resulting <tt>Map</tt>. The order in
* which converters are called depends on the order they were registered in.
*/
public interface Converter {
/**
* Converts a type to a Map.
* <p/>
* 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.
* <p/>
* 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 <tt>name</tt>, add a key <tt>name</tt> 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<Object, Object> output);
}
+37
View File
@@ -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.
* <p/>
* 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.
* <p/>
* 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.
* <p/>
* 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.
* <p/>
* Note that for block drivers this is called for any type of item stack.
* <p/>
* For item drivers this is only called if {@link Item#worksWith(ItemStack)}
* returns <tt>true</tt>.
*
* @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
* <tt>null</tt> if the block or item is not supported.
*/
Class<? extends Environment> providedEnvironment(ItemStack stack);
}
+52
View File
@@ -0,0 +1,52 @@
package li.cil.oc.api.driver;
import net.minecraft.world.World;
/**
* To be implemented by 'hosts' of components.
* <p/>
* 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.
* <p/>
* 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 <tt>TileEntity</tt> for
* more options, if necessary.
*/
public interface EnvironmentHost {
/**
* The world the container lives in.
*/
World world();
/**
* The container's X position in the world.
* <p/>
* For tile entities this is the <em>centered</em> 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.
* <p/>
* For tile entities this is the <em>centered</em> 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.
* <p/>
* For tile entities this is the <em>centered</em> 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();
}
+114
View File
@@ -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.
* <p/>
* 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.
* <p/>
* When trying to add an item to a computer the list of registered drivers is
* queried using the drivers' <tt>worksWith</tt> functions. The first driver
* that replies positively and whose check against the slot type is successful,
* i.e. for which the <tt>slot</tt> 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.
* <p/>
* 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.
* <p/>
* 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.
* <p/>
* 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 <tt>true</tt> if the item is supported; <tt>false</tt> otherwise.
*/
boolean worksWith(ItemStack stack);
/**
* Create a new managed environment interfacing the specified item.
* <p/>
* 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 <tt>null</tt> here.
* <p/>
* 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.
* <p/>
* This is expected to return a <em>new instance</em> 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.
* <p/>
* 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.
* <p/>
* 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.
* <p/>
* <em>Important</em>: 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.
* <p/>
* 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 <tt>oc:data</tt>, which will also be used if this returns
* <tt>null</tt>.
* <p/>
* This tag will be passed to the environment's <tt>save</tt> and
* <tt>load</tt> 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 <tt>null</tt> to use
* the default tag <tt>oc:data</tt>.
*/
NBTTagCompound dataTag(ItemStack stack);
}
+34
View File
@@ -0,0 +1,34 @@
package li.cil.oc.api.driver;
/**
* This interface can be implemented by environments to enforce a method
* whitelist.
* <p/>
* 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.
* <p/>
* 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.
* <p/>
* To do so, implement this interface in the <em>environment</em> 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()}.
* <p/>
* <em>Important</em>: 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 <em>exactly</em> match the names of the
* methods they allow.
*
* @return the list of allowed methods.
*/
String[] whitelistedMethods();
}
+36
View File
@@ -0,0 +1,36 @@
package li.cil.oc.api.driver;
/**
* This interface can be added to <em>environments</em> 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 <tt>IInventory</tt>).
* <p/>
* 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.
* <p/>
* If multiple named environments are merged the name of the environment
* with the <em>highest</em> priority is selected. Negative values are
* allowed. The recommended default value is therefore zero.
* <p/>
* 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();
}
+36
View File
@@ -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.
* <p/>
* 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.
* <p/>
* 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.
* <p/>
* 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);
}
+39
View File
@@ -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).
* <p/>
* 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.
* <p/>
* 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.
* <p/>
* 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);
}
+28
View File
@@ -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.
* <p/>
* 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.
* <p/>
* 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 <tt>true</tt> if the item is supported; <tt>false</tt> otherwise.
*/
boolean worksWith(ItemStack stack, Class<? extends EnvironmentHost> host);
}
+21
View File
@@ -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);
}
+26
View File
@@ -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.
* <p/>
* 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.
* <p/>
* 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);
}
+37
View File
@@ -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.
* <p/>
* 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.
* <p/>
* 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<? extends Architecture> architecture(ItemStack stack);
}
+22
View File
@@ -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() {
}
}
@@ -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.
* <p/>
* 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.
* <p/>
* 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.
* <p/>
* 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 <tt>None</tt> and <tt>Any</tt>.
* <p/>
* <tt>None</tt> 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 <tt>null</tt> is equivalent to returning <tt>None</tt>.
* <p/>
* <tt>Any</tt> 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.
* <p/>
* Returning a mount point not in the list of available mount points will
* be equivalent to returning <tt>None</tt>.
*
* @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<String> availableMountPoints);
/**
* Render the specified upgrade on a robot.
* <p/>
* 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.
* <p/>
* If the stack cannot be rendered, the renderer should indicate so in
* {@link #computePreferredMountPoint}, otherwise it will still consume a mount
* point.
* <p/>
* You usually won't need the robot parameter, but in case you <em>do</em>
* 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() {
}
}
}
+13
View File
@@ -0,0 +1,13 @@
/**
* This package contains item driver related interfaces.
* <p/>
* 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;
+13
View File
@@ -0,0 +1,13 @@
/**
* This package contains driver related interfaces.
* <p/>
* 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;
+175
View File
@@ -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.
* <p/>
* This is used to play file system access sounds and render disk activity
* indicators on some containers (e.g. disk drive, computer, server).
* <p/>
* Use this to implement rendering of disk access indicators on you own
* containers / computers / drive bays.
* <p/>
* 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.
* <p/>
* <em>Important</em>: this can be <tt>null</tt>, 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);
}
}
}
+91
View File
@@ -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.
* <p/>
* 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.
* <p/>
* Note: the y coordinate is computed as <tt>geolyzer.y - 32 + data.index</tt>.
*/
public static class Scan extends GeolyzerEvent {
/**
* The <em>relative</em> x coordinate of the column being scanned.
*/
public final int scanX;
/**
* The <em>relative</em> 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.
* <p/>
* 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<String, Object> data = new HashMap<String, Object>();
public Analyze(EnvironmentHost host, Map<?, ?> options, int x, int y, int z) {
super(host, options);
this.x = x;
this.y = y;
this.z = z;
}
}
}
+21
View File
@@ -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.
* <p/>
* 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;
}
}
@@ -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.
* <p/>
* 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);
}
}
}
+79
View File
@@ -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.
* <p/>
* 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.
* <p/>
* 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;
}
}
}
+18
View File
@@ -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;
}
}
+19
View File
@@ -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;
}
}
+38
View File
@@ -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.
* <p/>
* 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);
}
}
}
+53
View File
@@ -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.
* <p/>
* 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);
}
}
}
+34
View File
@@ -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).
* <p/>
* 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 <tt>false</tt>.
*/
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;
}
}
+81
View File
@@ -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.
* <p/>
* If this event is canceled, the chassis will <em>not</em> be rendered.
* Component items' item renderers will still be invoked, at the possibly
* modified mount points.
* <p/>
* <em>Important</em>: 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.
* <p/>
* 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.
* <p/>
* 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'.
* <p/>
* Note that the rotation is applied <em>before</em> 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 <tt>W</tt> component of the
* vector is the rotation.
* <p/>
* Note that the rotation is applied <em>before</em> the translation.
*/
public final Vector4f rotation = new Vector4f(0, 0, 0, 0);
/**
* The mount point's reference name.
* <p/>
* 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;
}
}
}
+70
View File
@@ -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.
* <p/>
* 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.
* <p/>
* 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 <tt>toolAfterUse</tt> item stack represents the actual tool, any
* changes must be applied to that variable. The <tt>toolBeforeUse</tt>
* 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);
}
}
}
+11
View File
@@ -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;
+246
View File
@@ -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.
* <p/>
* See {@link li.cil.oc.api.FileSystem} for factory methods.
* <p/>
* 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.
* <p/>
* 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.
* <p/>
* 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.
* <p/>
* This function should never throw.
*
* @param path the path to check at.
* @return <tt>true</tt> if the path points to a file or directory;
* <tt>false</tt> otherwise.
*/
boolean exists(String path);
/**
* Gets the size of a file.
* <p/>
* For files this should return the actual length of the file, in bytes. For
* folders this should return zero.
* <p/>
* 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.
* <p/>
* 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.
* <p/>
* For folders this should be the time they were created.
* <p/>
* 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.
* <p/>
* 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.
* <p/>
* This must return the actual object names in the specified parent folder,
* not their full path. For example, for a file at <tt>/home/test</tt>, when
* doing <tt>list("/home/")</tt> this should return <tt>["test"]</tt>,
* <em>not</em> <tt>["/home/test"]</tt>.
* <p/>
* Sub-folders should be returned with a trailing slash, to indicate that
* they are folders.
* <p/>
* 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;
* <tt>null</tt> if the specified object does not exist or is not a
* folder.
*/
String[] list(String path);
// ----------------------------------------------------------------------- //
/**
* Deletes a file or folder.
* <p/>
* This only has to support deleting single files and empty folders. If a
* directory is non-empty this may return <tt>false</tt>. If the target
* object does not exists it should return <tt>false</tt>.
* <p/>
* This is only available for writable file systems. For read-only systems
* it should always return <tt>false</tt>.
*
* @param path the path to the object to delete.
* @return <tt>true</tt> if the object was successfully deleted;
* <tt>false</tt> otherwise.
*/
boolean delete(String path);
/**
* Create the specified directory.
* <p/>
* This should always only create a single directory. If the parent
* directory does not exists it should return <tt>false</tt>. If the target
* object already exists it should also return <tt>false</tt>.
* <p/>
* This is only available for writable file systems. For read-only systems
* it should always return <tt>false</tt>.
*
* @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.
* <p/>
* 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 <tt>true</tt> if the object was renamed;
* <tt>false</tt> 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.
* <p/>
* 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).
* <p/>
* 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 <tt>true</tt> if the modification time was adjusted;
* <tt>false</tt> otherwise.
*/
boolean setLastModified(String path, long time);
// ----------------------------------------------------------------------- //
/**
* Opens a file for reading or writing.
* <p/>
* 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.
* <p/>
* It is the responsibility of the file system to restore all handles to
* their previous state when it is reloaded (game loaded for example).
* <p/>
* <em>Important</em>: 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 <em>essential</em> 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}.
* <p/>
* The wrapper allows interaction with the underlying file (stream) based
* on the mode it was opened in. See {@link Handle} for more details.
* <p/>
* If there is no such handle, this should return <tt>null</tt>, but never
* throw.
*
* @param handle the ID of the handle to get the wrapper for.
* @return the wrapper for that handle ID; <tt>null</tt> if there is no
* handle with the specified ID.
*/
Handle getHandle(int handle);
/**
* Called when the file system is destroyed.
* <p/>
* 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).
* <p/>
* 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();
}
+66
View File
@@ -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.
* <p/>
* 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 <tt>IOException</tt> after this function was called.
*/
void close();
/**
* Tries to read as much data from the file as fits into the specified
* array.
* <p/>
* 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.
* <p/>
* 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.
* <p/>
* 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;
}
+31
View File
@@ -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.
* <p/>
* May be <tt>null</tt> if no label is set.
*
* @return the current label.
*/
String getLabel();
/**
* Set the new value of this label.
* <p/>
* May be set to <tt>null</tt> to clear the label.
* <p/>
* 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);
}
+23
View File
@@ -0,0 +1,23 @@
package li.cil.oc.api.fs;
/**
* Possible file modes.
* <p/>
* 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
}
+22
View File
@@ -0,0 +1,22 @@
/**
* This package contains interfaces used by the file system implementation.
* <p/>
* 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.
* <p/>
* <em>You will usually not need to implement these interfaces!</em>
* <p/>
* 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;
+30
View File
@@ -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.
* <p/>
* 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:
* <pre>
* if (tileEntity instanceof Adapter) {
* </pre>
* or
* <pre>
* if (node.host() instanceof Adapter) {
* </pre>
* <p/>
* 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.
* <p/>
* 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 <em>you should not implement this</em>.
*/
public interface Adapter extends Environment, IInventory {
}
+91
View File
@@ -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.
* <p/>
* For example, for the robot this is the tool slot as well as slots
* provided by containers installed in the robot, if any.
* <p/>
* 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.
* <p/>
* If an agent has no inventory slots this will be a zero-sized inventory.
*/
IInventory mainInventory();
/**
* Provides access to the tanks of the agent.
* <p/>
* 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.
* <p/>
* 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.
* <p/>
* Note that this <em>may</em> 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();
}
+23
View File
@@ -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.
* <p/>
* This is implemented by computer case tile entities. That means you can
* use this to check for computer cases by using:
* <pre>
* if (tileEntity instanceof Case) {
* </pre>
* <p/>
* 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 <em>you should not implement this</em>.
*/
public interface Case extends Environment, EnvironmentHost, MachineHost, Colored, Rotatable, Tiered, IInventory {
}
+25
View File
@@ -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.
* <p/>
* Colors are in the common <tt>RRGGBB</tt> format.
* <p/>
* This interface is <em>not meant to be implemented</em>, 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);
}
+57
View File
@@ -0,0 +1,57 @@
package li.cil.oc.api.internal;
import net.minecraft.item.ItemStack;
/**
* This interface is implemented by the database component.
* <p/>
* 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).
* <p/>
* 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 <tt>Database</tt> 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.
* <p/>
* This will return <tt>null</tt> if there is no entry for the specified
* slot. If there is an entry, this will return a <em>copy</em> 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.
* <p/>
* 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, <tt>null</tt> to clear.
*/
void setStackInSlot(int slot, ItemStack stack);
/**
* Get an item stack with the specified hash stored in this database.
* <p/>
* 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);
}
+42
View File
@@ -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.
* <p/>
* This is implemented by drones entities. That means you can use this to check
* for drones by using:
* <pre>
* if (entity instanceof Drone) {
* </pre>
* <p/>
* 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 <em>you should not implement this</em>.
*/
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.
* <p/>
* 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.
* <p/>
* Note that this is really just the underlying entity's <tt>motionX/Y/Z</tt>,
* so you can cast this to {@link net.minecraft.entity.Entity} and use that
* instead, if you'd like.
*/
Vec3 getVelocity();
}
+21
View File
@@ -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.
* <p/>
* This is implemented by microcontroller tile entities. That means you can
* use this to check for microcontrollers by using:
* <pre>
* if (tileEntity instanceof Microcontroller) {
* </pre>
* <p/>
* 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 <em>you should not implement this</em>.
*/
public interface Microcontroller extends Environment, EnvironmentHost, MachineHost, Rotatable, Tiered {
}
+25
View File
@@ -0,0 +1,25 @@
package li.cil.oc.api.internal;
import net.minecraftforge.fluids.IFluidTank;
/**
* Implemented by objects with multiple internal tanks.
* <p/>
* 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);
}
+80
View File
@@ -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.
* <p/>
* 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.
* <p/>
* A robot's inventory contains component items and items in the actual
* inventory. The physical layout in the underlying 'real' inventory is as
* follows:
* <ul>
* <li>Tool</li>
* <li><tt>equipmentInventory.getSizeInventory</tt> hot-swappable components.</li>
* <li><tt>mainInventory.getSizeInventory</tt> internal inventory slots.</li>
* <li><tt>componentCount</tt> hard-wired components.</li>
* </ul>
* 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).
* <p/>
* This interface is <em>not meant to be implemented</em>, 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.
* <p/>
* This operates on the underlying, real inventory, as described in the
* comment on top of this class.
* <p/>
* This will return <tt>null</tt> 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 <tt>null</tt>.
*/
Environment getComponentInSlot(int index);
/**
* Sends the state of the <em>item</em> in the specified slot to the client
* if it is an upgrade.
* <p/>
* 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).
* <p/>
* 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).
* <p/>
* 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.
* <p/>
* 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();
}
+61
View File
@@ -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.
* <p/>
* This interface is <em>not meant to be implemented</em>, just used.
*/
public interface Rotatable {
/**
* The current facing of a tile entity implementing this interface.
* <p/>
* Intended to be used to query the orientation of an item components' host.
* For example:
* <pre>
* 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.
* }
* }
* }
* </pre>
*
* @return the current facing.
*/
ForgeDirection facing();
/**
* Converts a facing relative to the block's <em>local</em> coordinate
* system to a <tt>global orientation</tt>, using south as the standard
* orientation.
* <p/>
* 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 <tt>global</tt> orientation to a facing relative to the
* block's <em>local</em> coordinate system, using south as the standard
* orientation.
* <p/>
* 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);
}
+33
View File
@@ -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.
* <p/>
* 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:
* <pre>
* if (node.host() instanceof Server) {
* </pre>
* <p/>
* You can get a reference to a server either via the above cast, or via a
* {@link li.cil.oc.api.internal.ServerRack}.
* <p/>
* 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 <em>you should not implement this</em>.
*/
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();
}
+38
View File
@@ -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.
* <p/>
* This is implemented by server rack tile entities. That means you can use
* this to check for server racks by using:
* <pre>
* if (tileEntity instanceof ServerRack) {
* </pre>
* <p/>
* Server racks <em>do not</em> serve as environment for the computer nodes of
* servers. That's what the {@link Server}s are for.
* <p/>
* 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 <em>you should not implement this</em>.
*/
public interface ServerRack extends Environment, SidedEnvironment, Rotatable, IInventory {
/**
* The machine currently hosted by the server in the specified slot.
* <p/>
* This can be <tt>null</tt>, 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();
}
+38
View File
@@ -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.
* <p/>
* This is implemented by the class containing tablets' logic implementation,
* which is <em>not the tablet item</em>! The tablet class serves as its
* computer components' environment. That means you can use this to check for
* tablets by using
* <pre>
* if (node.host() instanceof Tablet) {
* </pre>
* <p/>
* 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.
* <p/>
* 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 <em>you should not implement this</em>.
*/
public interface Tablet extends EnvironmentHost, MachineHost, Rotatable {
/**
* Returns the player last holding the tablet.
* <p/>
* 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
* <em>not</em> be set to <tt>null</tt> in that case!
*
* @return the player last holding the tablet.
*/
EntityPlayer player();
}
+18
View File
@@ -0,0 +1,18 @@
package li.cil.oc.api.internal;
/**
* This is implemented by most things that are tiered in some way.
* <p/>
* 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.
* <p/>
* For example, a tier one screen will return 0 here, a tier three screen
* will return 2.
*/
int tier();
}
+30
View File
@@ -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.
* <p/>
* This is called in two scenarios, once when testing whether the wrench
* can be used on a certain block, in which case the <tt>simulate</tt>
* argument will be <tt>true</tt>, and once when actually used on a block,
* in which case the <tt>simulate</tt> argument will be <tt>false</tt>,
* allowing the tool to damage itself, for example.
* <p/>
* 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);
}
+22
View File
@@ -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.
* <p/>
* For example, to determine whether a tile entity is a robot, you can
* do an <tt>instanceof</tt> with the {@link li.cil.oc.api.internal.Robot}
* interface - and cast to it if you wish to access some of the provided
* functionality.
* <p/>
* 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;
+167
View File
@@ -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.
* <p/>
* 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 <tt>component_added</tt> signals are generated in the
* language's startup script, for already present components (see Lua's
* init.lua script).
* <p/>
* 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.
* <p/>
* 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<ItemStack> 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.
* <p/>
* 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 <tt>false</tt> the machine fails to start.
* <p/>
* 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)}.
* <p/>
* This method is invoked from the main server thread, meaning it is safe
* to interact with the world without having to perform manual
* synchronization.
* <p/>
* This method is expected to leave the architecture in a state so it is
* prepared to next be called with <tt>runThreaded(true)</tt>. 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
* <tt>runThreaded</tt>.
*/
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
* <em>should</em> return <tt>true</tt> from {@link #isInitialized()}.
* <p/>
* The resumed state is either a return from a synchronized call, when a
* synchronized call has been completed (via <tt>runSynchronized</tt>), or
* a normal yield in all other cases (sleep, interrupt, boot, ...).
* <p/>
* 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).
* <p/>
* 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.
* <p/>
* 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.
* <p/>
* 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.
* <p/>
* 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.
* <p/>
* 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 <tt>true</tt> from
* {@link #recomputeMemory}.
*/
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
@Inherited
@interface NoMemoryRequirements {
}
}
+339
View File
@@ -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}.
* <p/>
* 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.
* <p/>
* Note that integer values fetched this way are actually double values that
* have been truncated. So if a Lua program passes <tt>1.9</tt> and you do a
* <tt>checkInteger</tt> you'll get a <tt>1</tt>.
* <p/>
* The indexes passed to the various functions start at zero, i.e. to get the
* first argument you would use <tt>checkAny(0)</tt>. This is worth mentioning
* because Lua starts its indexes at one.
*/
public interface Arguments extends Iterable<Object> {
/**
* The total number of arguments that were passed to the function.
*/
int count();
/**
* Get whatever is at the specified index.
* <p/>
* Throws an error if there are too few arguments.
* <p/>
* The returned object will be one of the following, based on the conversion
* performed internally:
* <ul>
* <li><tt>null</tt> if the Lua value was <tt>nil</tt>.</li>
* <li><tt>java.lang.Boolean</tt> if the Lua value was a boolean.</li>
* <li><tt>java.lang.Double</tt> if the Lua value was a number.</li>
* <li><tt>byte[]</tt> if the Lua value was a string.</li>
* </ul>
*
* @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.
* <p/>
* 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.
* <p/>
* 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.
* <p/>
* 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.
* <p/>
* Throws an error if there are too few arguments.
* <p/>
* 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.
* <p/>
* 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.
* <p/>
* 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.
* <p/>
* 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.
* <p/>
* Throws an error if there are too few arguments.
* <p/>
* <em>Important</em>: 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.
* <p/>
* 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.
* <p/>
* Return the specified default value if there is no such element, behaves
* like {@link #checkAny(int)} otherwise.
* <p/>
* The returned object will be one of the following, based on the conversion
* performed internally:
* <ul>
* <li><tt>null</tt> if the Lua value was <tt>nil</tt>.</li>
* <li><tt>java.lang.Boolean</tt> if the Lua value was a boolean.</li>
* <li><tt>java.lang.Double</tt> if the Lua value was a number.</li>
* <li><tt>byte[]</tt> if the Lua value was a string.</li>
* </ul>
*
* @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.
* <p/>
* 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.
* <p/>
* 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.
* <p/>
* 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.
* <p/>
* Return the specified default value if there is no such element, behaves
* like {@link #checkString(int)} otherwise.
* <p/>
* 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.
* <p/>
* 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.
* <p/>
* 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.
* <p/>
* 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.
* <p/>
* This will return false if there is <em>no</em> 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.
* <p/>
* This will return false if there is <em>no</em> 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.
* <p/>
* This will return false if there is <em>no</em> 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.
* <p/>
* This will return false if there is <em>no</em> 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.
* <p/>
* This will return false if there is <em>no</em> 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.
* <p/>
* This will return false if there is <em>no</em> 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.
* <p/>
* This will return false if there is <em>no</em> 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();
}
+147
View File
@@ -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.
* <p/>
* Any method exposed like this can be enumerated and called from a computer
* that can see the node of the environment.
* <p/>
* Note that methods annotated with this interface must have the following
* signature:
* <pre>
* Object[] f(Context context, Arguments arguments) throws Exception;
* </pre>
* <p/>
* The method may return <tt>null</tt> in case it doesn't wish return anything,
* which is functionally equivalent to returning an empty array.
* <p/>
* 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.
* <p/>
* 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.
* <p/>
* You will have to ensure anything your callback does is thread safe when
* setting this to <tt>true</tt>. 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).
* <p/>
* Keep in mind that the node {@link li.cil.oc.api.network.Network} is <em>not</em> thread safe!
* Be sure you know what you're doing if you're working with a node's
* network in a direct callback.
* <p/>
* 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 <em>tick</em> on a tier two computer.
* <p/>
* 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.
* <p/>
* 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.
* <p/>
* Note that the limit does <em>not</em> 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.
* <p/>
* 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, <tt>1/limit</tt> 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.
* <p/>
* 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.
* <p/>
* <em>Important</em>: the recommended format is either<br/>
* <tt>function(arg:type[, optionArg:type]):resultType -- Description.</tt><br/>
* or<br/>
* <tt>function(arg:type[, optionArg:type]):resultType; Description.</tt><br/>
* 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.
* <p/>
* 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 <tt>__index</tt> metamethod, with its only parameter being the
* accessed key.
* <p/>
* 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.
* <p/>
* <em>Important</em>: this only works in environments (for components),
* it does <em>not</em> work for userdata (<tt>Value</tt> objects). For
* userdata, use the <tt>apply</tt> method instead.
*/
boolean getter() default false;
/**
* Whether this callback should work like a setter.
* <p/>
* 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 <tt>__newindex</tt> metamethod, with its only two parameters
* being the accessed key and the new value.
* <p/>
* 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.
* <p/>
* <em>Important</em>: this only works in environments (for components),
* it does <em>not</em> work for userdata (<tt>Value</tt> objects). For
* userdata, use the <tt>unapply</tt> method instead.
*/
boolean setter() default false;
}
+167
View File
@@ -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.
* <p/>
* 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:
* <ul>
* <li>Trigger input via a keyboard.</li>
* <li>Change the computer's inventory.</li>
* <li>Break the computer block.</li>
* </ul>
* <p/>
* There are three exceptions to this rule:
* <ul>
* <li>Operators are <em>always</em> allowed the above actions.</li>
* <li>If the user list is <em>empty</em> then <em>all</em> players are
* allowed the above actions.</li>
* <li>In single player mode the player is always allowed the above
* actions.</li>
* </ul>
* <p/>
* 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 <tt>computer.checked_signal</tt> message, that expects an
* <tt>EntityPlayer</tt> 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.
* <p/>
* 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.
* <p/>
* 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.
* <p/>
* The computer will enter a <em>starting</em> state, in which it will start
* accepting signals. The computer will start executing in the next server
* tick.
* <p/>
* If this is called while the computer is in a paused state it will set the
* remaining pause time to zero, but it will <em>not</em> immediately resume
* the computer. The computer will continue with what it did before it was
* paused in the next server tick.
* <p/>
* If this is called while the computer is in a non-paused and non-stopped
* state it will do nothing and return <tt>false</tt>.
*
* @return <tt>true</tt> if the computer switched to a running state.
*/
boolean start();
/**
* Pauses the computer for the specified duration.
* <p/>
* If this is called from a <em>direct</em> 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 <em>non-direct</em> 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).
* <p/>
* <b>Important</b>: if this is called from the <em>server thread</em> while
* the executor thread is running this will <em>block</em> 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.<br/>
* <b>However</b>, if the computer is already in a paused state
* and the call would not lead to a longer pause this will immediately
* return <tt>false</tt>, <em>without</em> blocking.
* <p/>
* 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.
* <p/>
* Also note that the time left to spend paused is stored in game ticks, so
* the time resolution is actually quite limited.
* <p/>
* If this is called while the computer is in a paused, stopping or stopped
* state this will do nothing and return <tt>false</tt>.
*
* @param seconds the number of seconds to pause the computer for.
* @return <tt>true</tt> if the computer switched to the paused state.
*/
boolean pause(double seconds);
/**
* Stops the computer.
* <p/>
* The computer will enter a <em>stopping</em> 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.
* <p/>
* 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.
* <p/>
* If this is called while the computer is in a stopping or stopped state
* this will do nothing and return <tt>false</tt>.
*
* @return <tt>true</tt> if the computer switched to the stopping state.
*/
boolean stop();
/**
* Push a signal into the computer.
* <p/>
* 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 <tt>false</tt>.
* <p/>
* Note that only a limited amount of types is supported for arguments:
* <ul>
* <li><tt>null</tt> and Scala's <tt>Unit</tt> and <tt>None</tt> (all appear
* as <tt>nil</tt> on the Lua side, for example)</li>
* <li>Boolean values.</li>
* <li>Numeric types (byte, short, int, long, float, double).</li>
* <li>Strings.</li>
* <li>Byte arrays (which appear as strings on the Lua side, e.g.).</li>
* <li>Maps if and only if both keys and values are strings.</li>
* <li>NBTTagCompounds.</li>
* </ul>
* If an unsupported type is specified the method will enqueue nothing
* instead, resulting in a <tt>nil</tt> 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 <tt>true</tt> if the signal was queued; <tt>false</tt> otherwise.
*/
boolean signal(String name, Object... args);
}
+66
View File
@@ -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)}.
* <p/>
* 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;
}
}
}
@@ -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 {
}
+309
View File
@@ -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.
* <p/>
* This is what actually evaluates code running on the machine, where the
* machine class itself serves as a scheduler.
* <p/>
* This may be <tt>null</tt>, 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.
* <p/>
* 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).
* <p/>
* This list is kept up-to-date automatically, do <em>not</em> mess with it.
*
* @return the list of attached components.
*/
Map<String, String> components();
/**
* The number of connected components.
* <p/>
* This number can differ from <tt>components().size()</tt>, since this is
* the number of actually <em>connected</em> 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.
* <p/>
* 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 <tt>null</tt> if either the creation of the file
* system failed, or if the size of the tmpfs has been set to zero in the
* config.
* <p/>
* 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 <tt>null</tt>.
*/
String tmpAddress();
/**
* A string with the last error message.
* <p/>
* 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).
* <p/>
* When the machine started, this is reset to <tt>null</tt>.
*
* @return the last error message, or <tt>null</tt>.
*/
String lastError();
/**
* The current world time. This is updated each tick and provides a thread
* safe way to access the world time for architectures.
* <p/>
* This is equivalent to <tt>owner().world().getWorldTime()</tt>.
*
* @return the current world time.
*/
long worldTime();
/**
* The time that has passed since the machine was started, in seconds.
* <p/>
* 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.
* <p/>
* 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 <tt>computer.beep</tt> is called.
* <p/>
* 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).
* <p/>
* 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.
* <p/>
* 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.
* <p/>
* 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.
* <p/>
* The passed pattern must consist of dots (<tt>.</tt>) and dashes (<tt>-</tt>),
* where a dot is short tone, and a dash is a long tone.
* <p/>
* 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.
* <p/>
* 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 <tt>true</tt> if the computer switched to the stopping state.
*/
boolean crash(String message);
/**
* Tries to pop a signal from the queue and returns it.
* <p/>
* 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 <tt>null</tt> if the queue was empty.
*/
Signal popSignal();
/**
* Get a list of all methods and their annotations of the specified object.
* <p/>
* 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<String, Callback> methods(Object value);
/**
* Makes the machine call a component callback.
* <p/>
* 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.
* <p/>
* 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 <tt>null</tt>.
* @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.
* <p/>
* 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.
* <p/>
* 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 <tt>null</tt>.
* @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.
* <p/>
* 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.
* <p/>
* This requires for the player to be online.
*
* @param name the name of the player to add as a user.
* @throws Exception if
* <ul>
* <li>There are already too many users.</li>
* <li>The player is already registered.</li>
* <li>The provided name is too long.</li>
* <li>The player is not online.</li>
* </ul>
*/
void addUser(String name) throws Exception;
/**
* Removes a player as a user from this machine, by username.
* <p/>
* Unlike when adding players, the player does <em>not</em> 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);
}
+58
View File
@@ -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.
* <p/>
* 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.
* <p/>
* This is used to find CPUs, component buses and memory.
*/
Iterable<ItemStack> internalComponents();
/**
* Get the slot a component with the specified address is in.
* <p/>
* This is intended to allow determining the slot of <em>item</em>
* 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);
}
+19
View File
@@ -0,0 +1,19 @@
package li.cil.oc.api.machine;
/**
* A single signal that was queued on a machine.
* <p/>
* 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();
}
+77
View File
@@ -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.
* <p/>
* 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.
* <p/>
* There are a few limitations too keep in mind:
* <ul>
* <li>Values <em>must</em> have a default constructor for loading.</li>
* <li>Values must be persistable (implement save/load).</li>
* </ul>
* <p/>
* 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 <tt>null</tt>.
*/
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.
* <p/>
* 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.
* <p/>
* 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.
* <p/>
* <em>Important</em>: be aware of the consequences of pushing the same
* object to multiple machines. You should usually <em>not</em> 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);
}
+25
View File
@@ -0,0 +1,25 @@
/**
* This package provides low level machine access.
* <p/>
* 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.
* <p/>
* 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.
* <p/>
* 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;
+29
View File
@@ -0,0 +1,29 @@
package li.cil.oc.api.manual;
/**
* This interface allows implementation of content providers for the manual.
* <p/>
* Content providers can be used to provide possibly dynamic page content for
* arbitrary paths. Note that content providers have <em>lower</em> priority
* than content found in resource packs, i.e. content providers will only be
* queried for missing pages, so to speak.
* <p/>
*
* @see li.cil.oc.api.prefab.ResourceContentProvider
*/
public interface ContentProvider {
/**
* Called to get the content of a path pointed to by the specified path.
* <p/>
* 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).
* <p/>
* If this provider cannot provide the requested path, it should return
* <tt>null</tt> 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 <tt>null</tt>.
*/
Iterable<String> getContent(String path);
}
+28
View File
@@ -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.
* <p/>
* 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 <tt>custom</tt>, and the image to be
* rendered in the Markdown document was <tt>[blah](custom:the data]</tt>,
* then the string passed where would be <tt>the data</tt>.
* <p/>
* 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 <tt>null</tt>, it should <em>never</em> throw an exception.
*
* @param data the data part of the image definition.
* @return the image renderer for the data.
*/
ImageRenderer getImage(String data);
}
+47
View File
@@ -0,0 +1,47 @@
package li.cil.oc.api.manual;
/**
* This allows implementing custom image renderers.
* <p/>
* 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.
* <p/>
* Built-in image renderers are <tt>item</tt>, <tt>block</tt> and <tt>oredict</tt>.
*/
public interface ImageRenderer {
/**
* The width of the area this renderer uses.
* <p/>
* 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.
* <p/>
* 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.
* <p/>
* 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);
}
@@ -0,0 +1,35 @@
package li.cil.oc.api.manual;
/**
* Allows implementing advanced image renderers that react to mouse input and
* specify customized tooltips.
* <p/>
* 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.
* <p/>
* 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.
* <p/>
* This only fires for left-clicks, because right-clicks are reserved for
* navigating back in the manual.
* <p/>
* If this returns <tt>false</tt> and the element is a link, the link will
* be followed. If it returns <tt>true</tt>, 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);
}
+45
View File
@@ -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.
* <p/>
* 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.
* <p/>
* This way you can easily make entries in your documentation available the
* same way OpenComputers does it itself.
* <p/>
* Note that you can use the special variable <tt>%LANGUAGE%</tt> in your
* paths, for language agnostic paths. These will be resolved to the currently
* set language, falling back to <tt>en_US</tt>, during actual content lookup.
*/
public interface PathProvider {
/**
* Get the path to the documentation page for the provided item stack.
* <p/>
* Return <tt>null</tt> 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, <tt>null</tt> if none is known.
*/
String pathFor(ItemStack stack);
/**
* Get the path to the documentation page for the provided block.
* <p/>
* Return <tt>null</tt> 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, <tt>null</tt> if none is known.
*/
String pathFor(World world, int x, int y, int z);
}
+26
View File
@@ -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.
* <p/>
* 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.
* <p/>
*
* @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.
* <p/>
* 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();
}
+14
View File
@@ -0,0 +1,14 @@
/**
* This package contains manual related interfaces.
* <p/>
* 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;
+34
View File
@@ -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.
* <p/>
* 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.
* <p/>
* 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 <tt>this</tt>. The latter is used by multi-block
* screens, for example, to always show information of the primary screen.
* <p/>
* Return <tt>null</tt> 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. <tt>this.node()</tt>).
*/
Node[] onAnalyze(EntityPlayer player, int side, float hitX, float hitY, float hitZ);
}
@@ -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.
* <p/>
* 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();
}
+107
View File
@@ -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.
* <p/>
* 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).
* <p/>
* 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.
* <p/>
* 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.
* <p/>
* This should be the type name of the component represented by the node,
* since this is what is returned from <tt>component.type</tt>. 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.
* <p/>
* 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.
* <p/>
* <em>Important</em>: this will always return <tt>true</tt> 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.
* <p/>
* 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).
* <p/>
* The returned collection is read-only.
*/
Collection<String> methods();
/**
* Get the annotation information of a method.
* <p/>
* 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 <tt>null</tt>.
*/
Callback annotation(String method);
/**
* Tries to call a function with the specified name on this component.
* <p/>
* The name of the method must be one of the names in {@link #methods()}.
* The returned array may be <tt>null</tt> 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 <tt>null</tt> 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;
}
@@ -0,0 +1,7 @@
package li.cil.oc.api.network;
/**
* For nodes that are both component and connector.
*/
public interface ComponentConnector extends Component, Connector {
}
+97
View File
@@ -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.
* <p/>
* 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.
* <p/>
* Each connector can take two roles: it can be a <em>producer</em>, feeding
* power into the network, or it can be a <em>consumer</em>, 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.
* <p/>
* 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 <em>global</em> buffer.
* <p/>
* 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.
* <p/>
* 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.
* <p/>
* If there is enough energy or no overflow this will return <tt>0</tt>.
* <p/>
* Keep in mind that this change is applied to the <em>global</em> 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 <tt>true</tt> if the energy was successfully consumed or stored.
*/
boolean tryChangeBuffer(double delta);
/**
* Change the size of the connectors local buffer.
* <p/>
* 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.
* <p/>
* 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);
}
+113
View File
@@ -0,0 +1,113 @@
package li.cil.oc.api.network;
/**
* The environment of a node.
* <p/>
* 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).
* <p/>
* 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.
* <p/>
* To get some more control over which sides of your block may connect to a
* network, see {@link SidedEnvironment}.
* <p/>
* When a tile entity implements this interface a good way of connecting and
* disconnecting is the following pattern:
* <pre>
* 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()
* }
* </pre>
* <p/>
* Item environments are always managed, so you will always have to provide a
* driver for items that should interact with the component network.
* <p/>
* To interact with environments from user code you will have to do two things:
* <ol>
* <li>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.</li>
* <li>Annotate methods in the environment as {@link li.cil.oc.api.machine.Callback}s.</li>
* </ol>
*/
public interface Environment {
/**
* The node this environment wraps.
* <p/>
* 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.
* <p/>
* This is also called for the node itself, if it was added to the network.
* <p/>
* At this point the node's network is never <tt>null</tt> 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.
* <p/>
* For example, if node A is added to a network with nodes B and C, these
* calls are made:
* <ul>
* <li>A.onConnect(A)</li>
* <li>A.onConnect(B)</li>
* <li>A.onConnect(C)</li>
* <li>B.onConnect(A)</li>
* <li>C.onConnect(A)</li>
* </ul>
*/
void onConnect(Node node);
/**
* This is called when a node is removed from the network.
* <p/>
* 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
* <em>only once</em> with the node itself as the parameter.
* <p/>
* At this point the node's network is no longer available (<tt>null</tt>).
* Use this to perform clean-up logic such as removing references to the
* removed node.
* <p/>
* For example, if node A is removed from a network with nodes A, B and C,
* these calls are made:
* <ul>
* <li>A.onDisconnect(A)</li>
* <li>B.onDisconnect(A)</li>
* <li>C.onDisconnect(A)</li>
* </ul>
*/
void onDisconnect(Node node);
/**
* This is the generic message handler.
* <p/>
* It is called whenever this environments {@link Node} receives a message
* that was sent via one of the <tt>send</tt> methods in the {@link Network}
* or the <tt>Node</tt> itself.
*
* @param message the message to handle.
*/
void onMessage(Message message);
}
@@ -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.
* <p/>
* <em>Important:</em> 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.
* <p/>
* Returning <tt>true</tt> will be the same as if this interface were not
* implemented. Returning <tt>false</tt> 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);
}
+33
View File
@@ -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.
* <p/>
* 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).
* <p/>
* You should <em>not</em> 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.
* <p/>
* 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();
}
Loaded 100 of 195 files, more files were not shown because too many files have changed in this diff. Show more