mirror of
https://github.com/SquidDev-CC/CC-Tweaked
synced 2024-12-14 12:10:30 +00:00
Some improvements to Javadoc publishing
- Use <p> everywhere. This is uglier, but also technically more correct. This requires a version bump to cct-javadoc, and will give me a massive headache when merging. - Link against the existing OpenJDK docs.
This commit is contained in:
Jonathan Coates
parent
af7af615c7
commit
f45614175a
@ -149,6 +149,7 @@ illuaminate {
|
||||
|
||||
tasks.javadoc {
|
||||
include("dan200/computercraft/api/**/*.java")
|
||||
(options as StandardJavadocDocletOptions).links("https://docs.oracle.com/javase/8/docs/api/")
|
||||
}
|
||||
|
||||
val apiJar by tasks.registering(Jar::class) {
|
||||
|
||||
@ -18,7 +18,7 @@ jqwik = "1.7.0"
|
||||
junit = "5.9.1"
|
||||
|
||||
# Build tools
|
||||
cctJavadoc = "1.5.0"
|
||||
cctJavadoc = "1.5.1"
|
||||
checkstyle = "8.25" # There's a reason we're pinned on an ancient version, but I can't remember what it is.
|
||||
curseForgeGradle = "1.0.11"
|
||||
forgeGradle = "5.1.+"
|
||||
|
||||
@ -38,7 +38,7 @@ import javax.annotation.Nullable;
|
||||
|
||||
/**
|
||||
* The static entry point to the ComputerCraft API.
|
||||
*
|
||||
* <p>
|
||||
* Members in this class must be called after mod_ComputerCraft has been initialised, but may be called before it is
|
||||
* fully loaded.
|
||||
*/
|
||||
@ -59,13 +59,13 @@ public final class ComputerCraftAPI
|
||||
|
||||
/**
|
||||
* Creates a numbered directory in a subfolder of the save directory for a given world, and returns that number.
|
||||
*
|
||||
* <p>
|
||||
* Use in conjunction with createSaveDirMount() to create a unique place for your peripherals or media items to store files.
|
||||
*
|
||||
* @param world The world for which the save dir should be created. This should be the server side world object.
|
||||
* @param parentSubPath The folder path within the save directory where the new directory should be created. eg: "computercraft/disk"
|
||||
* @return The numerical value of the name of the new folder, or -1 if the folder could not be created for some reason.
|
||||
*
|
||||
* <p>
|
||||
* eg: if createUniqueNumberedSaveDir( world, "computer/disk" ) was called returns 42, then "computer/disk/42" is now
|
||||
* available for writing.
|
||||
* @see #createSaveDirMount(World, String, long)
|
||||
@ -77,7 +77,7 @@ public final class ComputerCraftAPI
|
||||
|
||||
/**
|
||||
* Creates a file system mount that maps to a subfolder of the save directory for a given world, and returns it.
|
||||
*
|
||||
* <p>
|
||||
* Use in conjunction with IComputerAccess.mount() or IComputerAccess.mountWritable() to mount a folder from the
|
||||
* users save directory onto a computers file system.
|
||||
*
|
||||
@ -101,10 +101,10 @@ public final class ComputerCraftAPI
|
||||
|
||||
/**
|
||||
* Creates a file system mount to a resource folder, and returns it.
|
||||
*
|
||||
* <p>
|
||||
* Use in conjunction with {@link IComputerAccess#mount} or {@link IComputerAccess#mountWritable} to mount a
|
||||
* resource folder onto a computer's file system.
|
||||
*
|
||||
* <p>
|
||||
* The files in this mount will be a combination of files in all mod jar, and data packs that contain
|
||||
* resources with the same domain and path. For instance, ComputerCraft's resources are stored in
|
||||
* "/data/computercraft/lua/rom". We construct a mount for that with
|
||||
|
||||
@ -21,7 +21,7 @@ public interface IUpgradeBase
|
||||
/**
|
||||
* Gets a unique identifier representing this type of turtle upgrade. eg: "computercraft:wireless_modem"
|
||||
* or "my_mod:my_upgrade".
|
||||
*
|
||||
* <p>
|
||||
* You should use a unique resource domain to ensure this upgrade is uniquely identified.
|
||||
* The upgrade will fail registration if an already used ID is specified.
|
||||
*
|
||||
@ -32,7 +32,7 @@ public interface IUpgradeBase
|
||||
|
||||
/**
|
||||
* Return an unlocalised string to describe this type of computer in item names.
|
||||
*
|
||||
* <p>
|
||||
* Examples of built-in adjectives are "Wireless", "Mining" and "Crafty".
|
||||
*
|
||||
* @return The localisation key for this upgrade's adjective.
|
||||
@ -44,7 +44,7 @@ public interface IUpgradeBase
|
||||
* Return an item stack representing the type of item that a computer must be crafted
|
||||
* with to create a version which holds this upgrade. This item stack is also used
|
||||
* to determine the upgrade given by {@code turtle.equipLeft()} or {@code pocket.equipBack()}
|
||||
*
|
||||
* <p>
|
||||
* This should be constant over a session (or at least a datapack reload). It is recommended
|
||||
* that you cache the stack too, in order to prevent constructing it every time the method
|
||||
* is called.
|
||||
@ -56,11 +56,11 @@ public interface IUpgradeBase
|
||||
|
||||
/**
|
||||
* Determine if an item is suitable for being used for this upgrade.
|
||||
*
|
||||
* <p>
|
||||
* When un-equipping an upgrade, we return {@link #getCraftingItem()} rather than
|
||||
* the original stack. In order to prevent people losing items with enchantments (or
|
||||
* repairing items with non-0 damage), we impose additional checks on the item.
|
||||
*
|
||||
* <p>
|
||||
* The default check requires that any non-capability NBT is exactly the same as the
|
||||
* crafting item, but this may be relaxed for your upgrade.
|
||||
*
|
||||
|
||||
@ -49,7 +49,7 @@ public abstract class BasicItemDetailProvider<T> implements IDetailProvider<Item
|
||||
/**
|
||||
* Provide additional details for the given {@link Item} and {@link ItemStack}. This method is called by
|
||||
* {@code turtle.getItemDetail()}. New properties should be added to the given {@link Map}, {@code data}.
|
||||
*
|
||||
* <p>
|
||||
* This method is always called on the server thread, so it is safe to interact with the world here, but you should
|
||||
* take care to avoid long blocking operations as this will stall the server and other computers.
|
||||
*
|
||||
|
||||
@ -12,7 +12,7 @@ import java.util.Objects;
|
||||
|
||||
/**
|
||||
* An {@link IOException} which occurred on a specific file.
|
||||
*
|
||||
* <p>
|
||||
* This may be thrown from a {@link IMount} or {@link IWritableMount} to give more information about a failure.
|
||||
*/
|
||||
public class FileOperationException extends IOException
|
||||
|
||||
@ -9,7 +9,7 @@ import java.io.IOException;
|
||||
|
||||
/**
|
||||
* Provides a mount of the entire computer's file system.
|
||||
*
|
||||
* <p>
|
||||
* This exists for use by various APIs - one should not attempt to mount it.
|
||||
*/
|
||||
public interface IFileSystem extends IWritableMount
|
||||
|
||||
@ -18,7 +18,7 @@ import java.util.List;
|
||||
/**
|
||||
* Represents a read only part of a virtual filesystem that can be mounted onto a computer using
|
||||
* {@link IComputerAccess#mount(String, IMount)}.
|
||||
*
|
||||
* <p>
|
||||
* Ready made implementations of this interface can be created using
|
||||
* {@link ComputerCraftAPI#createSaveDirMount(World, String, long)} or
|
||||
* {@link ComputerCraftAPI#createResourceMount(String, String)}, or you're free to implement it yourselves!
|
||||
|
||||
@ -18,7 +18,7 @@ import java.util.OptionalLong;
|
||||
/**
|
||||
* Represents a part of a virtual filesystem that can be mounted onto a computer using {@link IComputerAccess#mount(String, IMount)}
|
||||
* or {@link IComputerAccess#mountWritable(String, IWritableMount)}, that can also be written to.
|
||||
*
|
||||
* <p>
|
||||
* Ready made implementations of this interface can be created using
|
||||
* {@link ComputerCraftAPI#createSaveDirMount(World, String, long)}, or you're free to implement it yourselves!
|
||||
*
|
||||
|
||||
@ -17,17 +17,17 @@ import javax.annotation.Nonnull;
|
||||
|
||||
/**
|
||||
* A generic source of {@link LuaMethod} functions.
|
||||
*
|
||||
* <p>
|
||||
* Unlike normal objects ({@link IDynamicLuaObject} or {@link IPeripheral}), methods do not target this object but
|
||||
* instead are defined as {@code static} and accept their target as the first parameter. This allows you to inject
|
||||
* methods onto objects you do not own, as well as declaring methods for a specific "trait" (for instance, a
|
||||
* {@link Capability}).
|
||||
*
|
||||
* <p>
|
||||
* Currently the "generic peripheral" system is incompatible with normal peripherals. Normal {@link IPeripheralProvider}
|
||||
* or {@link IPeripheral} implementations take priority. Tile entities which use this system are given a peripheral name
|
||||
* determined by their id, rather than any peripheral provider. This will hopefully change in the future, once a suitable
|
||||
* design has been established.
|
||||
*
|
||||
* <p>
|
||||
* For example, the main CC: Tweaked mod defines a generic source for inventories, which works on {@link IItemHandler}s:
|
||||
*
|
||||
* <pre>{@code
|
||||
@ -49,7 +49,7 @@ public interface GenericSource
|
||||
{
|
||||
/**
|
||||
* A unique identifier for this generic source.
|
||||
*
|
||||
* <p>
|
||||
* This is currently unused, but may be used in the future to allow disabling specific sources. It is recommended
|
||||
* to return an identifier using your mod's ID.
|
||||
*
|
||||
|
||||
@ -185,7 +185,7 @@ public interface IArguments
|
||||
|
||||
/**
|
||||
* Get an argument as a table in an unsafe manner.
|
||||
*
|
||||
* <p>
|
||||
* Classes implementing this interface may choose to implement a more optimised version which does not copy the
|
||||
* table, instead returning a wrapper version, making it more efficient. However, the caller must guarantee that
|
||||
* they do not access the table the computer thread (and so should not be used with main-thread functions) or once
|
||||
@ -334,7 +334,7 @@ public interface IArguments
|
||||
|
||||
/**
|
||||
* Get an argument as a table in an unsafe manner.
|
||||
*
|
||||
* <p>
|
||||
* Classes implementing this interface may choose to implement a more optimised version which does not copy the
|
||||
* table, instead returning a wrapper version, making it more efficient. However, the caller must guarantee that
|
||||
* they do not access off the computer thread (and so should not be used with main-thread functions) or once the
|
||||
@ -446,7 +446,7 @@ public interface IArguments
|
||||
|
||||
/**
|
||||
* This is called when the current function finishes, before any main thread tasks have run.
|
||||
*
|
||||
* <p>
|
||||
* Called when the current function returns, and so some values are no longer guaranteed to be safe to access.
|
||||
*
|
||||
* @deprecated This method was an internal implementation detail and is no longer used.
|
||||
|
||||
@ -11,7 +11,7 @@ import javax.annotation.Nonnull;
|
||||
|
||||
/**
|
||||
* An interface for representing custom objects returned by peripherals or other Lua objects.
|
||||
*
|
||||
* <p>
|
||||
* Generally, one does not need to implement this type - it is sufficient to return an object with some methods
|
||||
* annotated with {@link LuaFunction}. {@link IDynamicLuaObject} is useful when you wish your available methods to
|
||||
* change at runtime.
|
||||
|
||||
@ -10,7 +10,7 @@ import dan200.computercraft.api.ComputerCraftAPI;
|
||||
/**
|
||||
* Represents a Lua object which is stored as a global variable on computer startup. This must either provide
|
||||
* {@link LuaFunction} annotated functions or implement {@link IDynamicLuaObject}.
|
||||
*
|
||||
* <p>
|
||||
* Before implementing this interface, consider alternative methods of providing methods. It is generally preferred
|
||||
* to use peripherals to provide functionality to users.
|
||||
*
|
||||
@ -28,7 +28,7 @@ public interface ILuaAPI
|
||||
|
||||
/**
|
||||
* Called when the computer is turned on.
|
||||
*
|
||||
* <p>
|
||||
* One should only interact with the file system.
|
||||
*/
|
||||
default void startup()
|
||||
@ -44,7 +44,7 @@ public interface ILuaAPI
|
||||
|
||||
/**
|
||||
* Called when the computer is turned off or unloaded.
|
||||
*
|
||||
* <p>
|
||||
* This should reset the state of the object, disposing any remaining file handles, or other resources.
|
||||
*/
|
||||
default void shutdown()
|
||||
|
||||
@ -17,7 +17,7 @@ public interface ILuaContext
|
||||
* Queue a task to be executed on the main server thread at the beginning of next tick, but do not wait for it to
|
||||
* complete. This should be used when you need to interact with the world in a thread-safe manner but do not care
|
||||
* about the result or you wish to run asynchronously.
|
||||
*
|
||||
* <p>
|
||||
* When the task has finished, it will enqueue a {@code task_completed} event, which takes the task id, a success
|
||||
* value and the return values, or an error message if it failed.
|
||||
*
|
||||
@ -31,7 +31,7 @@ public interface ILuaContext
|
||||
/**
|
||||
* Queue a task to be executed on the main server thread at the beginning of next tick, waiting for it to complete.
|
||||
* This should be used when you need to interact with the world in a thread-safe manner.
|
||||
*
|
||||
* <p>
|
||||
* Note that the return values of your task are handled as events, meaning more complex objects such as maps or
|
||||
* {@link IDynamicLuaObject} will not preserve their identities.
|
||||
*
|
||||
|
||||
@ -14,7 +14,7 @@ import java.util.Optional;
|
||||
|
||||
/**
|
||||
* Used to mark a Java function which is callable from Lua.
|
||||
*
|
||||
* <p>
|
||||
* Methods annotated with {@link LuaFunction} must be public final instance methods. They can have any number of
|
||||
* parameters, but they must be of the following types:
|
||||
*
|
||||
@ -24,12 +24,12 @@ import java.util.Optional;
|
||||
* <li>
|
||||
* Alternatively, one may specify the desired arguments as normal parameters and the argument parsing code will
|
||||
* be generated automatically.
|
||||
*
|
||||
* <p>
|
||||
* Each parameter must be one of the given types supported by {@link IArguments} (for instance, {@link int} or
|
||||
* {@link Map}). Optional values are supported by accepting a parameter of type {@link Optional}.
|
||||
* </li>
|
||||
* </ul>
|
||||
*
|
||||
* <p>
|
||||
* This function may return {@link MethodResult}. However, if you simply return a value (rather than having to yield),
|
||||
* you may return {@code void}, a single value (either an object or a primitive like {@code int}) or array of objects.
|
||||
* These will be treated the same as {@link MethodResult#of()}, {@link MethodResult#of(Object)} and
|
||||
@ -58,7 +58,7 @@ public @interface LuaFunction
|
||||
|
||||
/**
|
||||
* Allow using "unsafe" arguments, such {@link IArguments#getTableUnsafe(int)}.
|
||||
*
|
||||
* <p>
|
||||
* This is incompatible with {@link #mainThread()}.
|
||||
*
|
||||
* @return Whether this function supports unsafe arguments.
|
||||
|
||||
@ -16,7 +16,7 @@ import java.util.Objects;
|
||||
|
||||
/**
|
||||
* The result of invoking a Lua method.
|
||||
*
|
||||
* <p>
|
||||
* Method results either return a value immediately ({@link #of(Object...)} or yield control to the parent coroutine.
|
||||
* When the current coroutine is resumed, we invoke the provided {@link ILuaCallback#resume(Object[])} callback.
|
||||
*/
|
||||
@ -55,11 +55,11 @@ public final class MethodResult
|
||||
|
||||
/**
|
||||
* Return a single value immediately.
|
||||
*
|
||||
* <p>
|
||||
* Integers, doubles, floats, strings, booleans, {@link Map}, {@link Collection}s, arrays and {@code null} will be
|
||||
* converted to their corresponding Lua type. {@code byte[]} and {@link ByteBuffer} will be treated as binary
|
||||
* strings. {@link ILuaFunction} will be treated as a function.
|
||||
*
|
||||
* <p>
|
||||
* In order to provide a custom object with methods, one may return a {@link IDynamicLuaObject}, or an arbitrary
|
||||
* class with {@link LuaFunction} annotations. Anything else will be converted to {@code nil}.
|
||||
*
|
||||
|
||||
@ -16,7 +16,7 @@ import javax.annotation.Nullable;
|
||||
|
||||
/**
|
||||
* Represents an item that can be placed in a disk drive and used by a Computer.
|
||||
*
|
||||
* <p>
|
||||
* Implement this interface on your {@link Item} class to allow it to be used in the drive. Alternatively, register
|
||||
* a {@link IMediaProvider}.
|
||||
*/
|
||||
|
||||
@ -33,7 +33,7 @@ public interface IPacketReceiver
|
||||
|
||||
/**
|
||||
* Get the maximum distance this receiver can send and receive messages.
|
||||
*
|
||||
* <p>
|
||||
* When determining whether a receiver can receive a message, the largest distance of the packet and receiver is
|
||||
* used - ensuring it is within range. If the packet or receiver is inter-dimensional, then the packet will always
|
||||
* be received.
|
||||
@ -47,7 +47,7 @@ public interface IPacketReceiver
|
||||
|
||||
/**
|
||||
* Determine whether this receiver can receive packets from other dimensions.
|
||||
*
|
||||
* <p>
|
||||
* A device will receive an inter-dimensional packet if either it or the sending device is inter-dimensional.
|
||||
*
|
||||
* @return Whether this receiver receives packets from other dimensions.
|
||||
|
||||
@ -11,11 +11,11 @@ import javax.annotation.Nonnull;
|
||||
|
||||
/**
|
||||
* An object which may be part of a wired network.
|
||||
*
|
||||
* <p>
|
||||
* Elements should construct a node using {@link ComputerCraftAPI#createWiredNodeForElement(IWiredElement)}. This acts
|
||||
* as a proxy for all network objects. Whilst the node may change networks, an element's node should remain constant
|
||||
* for its lifespan.
|
||||
*
|
||||
* <p>
|
||||
* Elements are generally tied to a block or tile entity in world. In such as case, one should provide the
|
||||
* {@link IWiredElement} capability for the appropriate sides.
|
||||
*/
|
||||
|
||||
@ -13,12 +13,12 @@ import java.util.Map;
|
||||
/**
|
||||
* A wired network is composed of one of more {@link IWiredNode}s, a set of connections between them, and a series
|
||||
* of peripherals.
|
||||
*
|
||||
* <p>
|
||||
* Networks from a connected graph. This means there is some path between all nodes on the network. Further more, if
|
||||
* there is some path between two nodes then they must be on the same network. {@link IWiredNetwork} will automatically
|
||||
* handle the merging and splitting of networks (and thus changing of available nodes and peripherals) as connections
|
||||
* change.
|
||||
*
|
||||
* <p>
|
||||
* This does mean one can not rely on the network remaining consistent between subsequent operations. Consequently,
|
||||
* it is generally preferred to use the methods provided by {@link IWiredNode}.
|
||||
*
|
||||
@ -28,7 +28,7 @@ public interface IWiredNetwork
|
||||
{
|
||||
/**
|
||||
* Create a connection between two nodes.
|
||||
*
|
||||
* <p>
|
||||
* This should only be used on the server thread.
|
||||
*
|
||||
* @param left The first node to connect
|
||||
@ -43,7 +43,7 @@ public interface IWiredNetwork
|
||||
|
||||
/**
|
||||
* Destroy a connection between this node and another.
|
||||
*
|
||||
* <p>
|
||||
* This should only be used on the server thread.
|
||||
*
|
||||
* @param left The first node in the connection.
|
||||
@ -58,7 +58,7 @@ public interface IWiredNetwork
|
||||
|
||||
/**
|
||||
* Sever all connections this node has, removing it from this network.
|
||||
*
|
||||
* <p>
|
||||
* This should only be used on the server thread. You should only call this on nodes
|
||||
* that your network element owns.
|
||||
*
|
||||
@ -72,7 +72,7 @@ public interface IWiredNetwork
|
||||
|
||||
/**
|
||||
* Update the peripherals a node provides.
|
||||
*
|
||||
* <p>
|
||||
* This should only be used on the server thread. You should only call this on nodes
|
||||
* that your network element owns.
|
||||
*
|
||||
|
||||
@ -13,14 +13,14 @@ import java.util.Map;
|
||||
|
||||
/**
|
||||
* Wired nodes act as a layer between {@link IWiredElement}s and {@link IWiredNetwork}s.
|
||||
*
|
||||
* <p>
|
||||
* Firstly, a node acts as a packet network, capable of sending and receiving modem messages to connected nodes. These
|
||||
* methods may be safely used on any thread.
|
||||
*
|
||||
* <p>
|
||||
* When sending a packet, the system will attempt to find the shortest path between the two nodes based on their
|
||||
* element's position. Note that packet senders and receivers can have different locations from their associated
|
||||
* element: the distance between the two will be added to the total packet's distance.
|
||||
*
|
||||
* <p>
|
||||
* Wired nodes also provide several convenience methods for interacting with a wired network. These should only ever
|
||||
* be used on the main server thread.
|
||||
*/
|
||||
@ -37,7 +37,7 @@ public interface IWiredNode extends IPacketNetwork
|
||||
/**
|
||||
* The network this node is currently connected to. Note that this may change
|
||||
* after any network operation, so it should not be cached.
|
||||
*
|
||||
* <p>
|
||||
* This should only be used on the server thread.
|
||||
*
|
||||
* @return This node's network.
|
||||
@ -47,7 +47,7 @@ public interface IWiredNode extends IPacketNetwork
|
||||
|
||||
/**
|
||||
* Create a connection from this node to another.
|
||||
*
|
||||
* <p>
|
||||
* This should only be used on the server thread.
|
||||
*
|
||||
* @param node The other node to connect to.
|
||||
@ -62,7 +62,7 @@ public interface IWiredNode extends IPacketNetwork
|
||||
|
||||
/**
|
||||
* Destroy a connection between this node and another.
|
||||
*
|
||||
* <p>
|
||||
* This should only be used on the server thread.
|
||||
*
|
||||
* @param node The other node to disconnect from.
|
||||
@ -78,7 +78,7 @@ public interface IWiredNode extends IPacketNetwork
|
||||
|
||||
/**
|
||||
* Sever all connections this node has, removing it from this network.
|
||||
*
|
||||
* <p>
|
||||
* This should only be used on the server thread. You should only call this on nodes
|
||||
* that your network element owns.
|
||||
*
|
||||
@ -94,7 +94,7 @@ public interface IWiredNode extends IPacketNetwork
|
||||
|
||||
/**
|
||||
* Mark this node's peripherals as having changed.
|
||||
*
|
||||
* <p>
|
||||
* This should only be used on the server thread. You should only call this on nodes
|
||||
* that your network element owns.
|
||||
*
|
||||
|
||||
@ -11,7 +11,7 @@ import javax.annotation.Nonnull;
|
||||
|
||||
/**
|
||||
* An object on a {@link IWiredNetwork} capable of sending packets.
|
||||
*
|
||||
* <p>
|
||||
* Unlike a regular {@link IPacketSender}, this must be associated with the node you are attempting to
|
||||
* to send the packet from.
|
||||
*/
|
||||
@ -19,7 +19,7 @@ public interface IWiredSender extends IPacketSender
|
||||
{
|
||||
/**
|
||||
* The node in the network representing this object.
|
||||
*
|
||||
* <p>
|
||||
* This should be used as a proxy for the main network. One should send packets
|
||||
* and register receivers through this object.
|
||||
*
|
||||
|
||||
@ -13,7 +13,7 @@ import javax.annotation.Nonnull;
|
||||
|
||||
/**
|
||||
* A {@link GenericSource} which provides methods for a peripheral.
|
||||
*
|
||||
* <p>
|
||||
* Unlike a {@link GenericSource}, all methods <strong>should</strong> target the same type, for instance a
|
||||
* {@link TileEntity} subclass or a capability interface. This is not currently enforced.
|
||||
*/
|
||||
@ -21,13 +21,13 @@ public interface GenericPeripheral extends GenericSource
|
||||
{
|
||||
/**
|
||||
* Get the type of the exposed peripheral.
|
||||
*
|
||||
* <p>
|
||||
* Unlike normal {@link IPeripheral}s, {@link GenericPeripheral} do not have to have a type. By default, the
|
||||
* resulting peripheral uses the resource name of the wrapped {@link TileEntity} (for instance {@code minecraft:chest}).
|
||||
*
|
||||
* <p>
|
||||
* However, in some cases it may be more appropriate to specify a more readable name. Overriding this method allows
|
||||
* you to do so.
|
||||
*
|
||||
* <p>
|
||||
* When multiple {@link GenericPeripheral}s return a non-empty peripheral type for a single tile entity, the
|
||||
* lexicographically smallest will be chosen. In order to avoid this conflict, this method should only be
|
||||
* implemented when your peripheral targets a single tile entity <strong>AND</strong> it's likely that you're the
|
||||
|
||||
@ -105,11 +105,11 @@ public interface IComputerAccess
|
||||
/**
|
||||
* Unmounts a directory previously mounted onto the computers file system by {@link #mount(String, IMount)}
|
||||
* or {@link #mountWritable(String, IWritableMount)}.
|
||||
*
|
||||
* <p>
|
||||
* When a directory is unmounted, it will disappear from the computers file system, and the user will no longer be
|
||||
* able to access it. All directories mounted by a mount or mountWritable are automatically unmounted when the
|
||||
* peripheral is attached if they have not been explicitly unmounted.
|
||||
*
|
||||
* <p>
|
||||
* Note that you cannot unmount another peripheral's mounts.
|
||||
*
|
||||
* @param location The desired location in the computers file system of the directory to unmount.
|
||||
@ -124,7 +124,7 @@ public interface IComputerAccess
|
||||
|
||||
/**
|
||||
* Returns the numerical ID of this computer.
|
||||
*
|
||||
* <p>
|
||||
* This is the same number obtained by calling {@code os.getComputerID()} or running the "id" program from lua,
|
||||
* and is guaranteed unique. This number will be positive.
|
||||
*
|
||||
@ -145,7 +145,7 @@ public interface IComputerAccess
|
||||
* @param arguments In addition to a name, you may pass an array of extra arguments to the event, that will
|
||||
* be supplied as extra return values to os.pullEvent(). Objects in the array will be converted
|
||||
* to lua data types in the same fashion as the return values of IPeripheral.callMethod().
|
||||
*
|
||||
* <p>
|
||||
* You may supply {@code null} to indicate that no arguments are to be supplied.
|
||||
* @throws NotAttachedException If the peripheral has been detached.
|
||||
* @see MethodResult#pullEvent(String, ILuaCallback)
|
||||
@ -167,7 +167,7 @@ public interface IComputerAccess
|
||||
|
||||
/**
|
||||
* Get a set of peripherals that this computer access can "see", along with their attachment name.
|
||||
*
|
||||
* <p>
|
||||
* This may include other peripherals on the wired network or peripherals on other sides of the computer.
|
||||
*
|
||||
* @return All reachable peripherals
|
||||
@ -191,12 +191,12 @@ public interface IComputerAccess
|
||||
|
||||
/**
|
||||
* Get a {@link IWorkMonitor} for tasks your peripheral might execute on the main (server) thread.
|
||||
*
|
||||
* <p>
|
||||
* This should be used to ensure your peripheral integrates with ComputerCraft's monitoring and limiting of how much
|
||||
* server time each computer consumes. You should not need to use this if you use
|
||||
* {@link ILuaContext#issueMainThreadTask(ILuaTask)} - this is intended for mods with their own system for running
|
||||
* work on the main thread.
|
||||
*
|
||||
* <p>
|
||||
* Please note that the returned implementation is <em>not</em> thread-safe, and should only be used from the main
|
||||
* thread.
|
||||
*
|
||||
|
||||
@ -11,7 +11,7 @@ import javax.annotation.Nonnull;
|
||||
|
||||
/**
|
||||
* A peripheral whose methods are not known at runtime.
|
||||
*
|
||||
* <p>
|
||||
* This behaves similarly to {@link IDynamicLuaObject}, though also accepting the current {@link IComputerAccess}.
|
||||
* Generally one may use {@link LuaFunction} instead of implementing this interface.
|
||||
*/
|
||||
@ -30,7 +30,7 @@ public interface IDynamicPeripheral extends IPeripheral
|
||||
/**
|
||||
* This is called when a lua program on an attached computer calls {@code peripheral.call()} with
|
||||
* one of the methods exposed by {@link #getMethodNames()}.
|
||||
*
|
||||
* <p>
|
||||
* Be aware that this will be called from the ComputerCraft Lua thread, and must be thread-safe when interacting
|
||||
* with Minecraft objects.
|
||||
*
|
||||
|
||||
@ -15,10 +15,10 @@ import java.util.Set;
|
||||
|
||||
/**
|
||||
* The interface that defines a peripheral.
|
||||
*
|
||||
* <p>
|
||||
* In order to expose a peripheral for your block or tile entity, you may either attach a {@link Capability}, or
|
||||
* register a {@link IPeripheralProvider}. This <em>cannot</em> be implemented {@link IPeripheral} directly on the tile.
|
||||
*
|
||||
* <p>
|
||||
* Peripherals should provide a series of methods to the user, either using {@link LuaFunction} or by implementing
|
||||
* {@link IDynamicPeripheral}.
|
||||
*/
|
||||
@ -47,15 +47,15 @@ public interface IPeripheral
|
||||
|
||||
/**
|
||||
* Is called when when a computer is attaching to the peripheral.
|
||||
*
|
||||
* <p>
|
||||
* This will occur when a peripheral is placed next to an active computer, when a computer is turned on next to a
|
||||
* peripheral, when a turtle travels into a square next to a peripheral, or when a wired modem adjacent to this
|
||||
* peripheral is does any of the above.
|
||||
*
|
||||
* <p>
|
||||
* Between calls to attach and {@link #detach}, the attached computer can make method calls on the peripheral using
|
||||
* {@code peripheral.call()}. This method can be used to keep track of which computers are attached to the
|
||||
* peripheral, or to take action when attachment occurs.
|
||||
*
|
||||
* <p>
|
||||
* Be aware that will be called from both the server thread and ComputerCraft Lua thread, and so must be thread-safe
|
||||
* and reentrant.
|
||||
*
|
||||
@ -69,14 +69,14 @@ public interface IPeripheral
|
||||
|
||||
/**
|
||||
* Called when a computer is detaching from the peripheral.
|
||||
*
|
||||
* <p>
|
||||
* This will occur when a computer shuts down, when the peripheral is removed while attached to computers, when a
|
||||
* turtle moves away from a block attached to a peripheral, or when a wired modem adjacent to this peripheral is
|
||||
* detached.
|
||||
*
|
||||
* <p>
|
||||
* This method can be used to keep track of which computers are attached to the peripheral, or to take action when
|
||||
* detachment occurs.
|
||||
*
|
||||
* <p>
|
||||
* Be aware that this will be called from both the server and ComputerCraft Lua thread, and must be thread-safe
|
||||
* and reentrant.
|
||||
*
|
||||
@ -102,7 +102,7 @@ public interface IPeripheral
|
||||
|
||||
/**
|
||||
* Determine whether this peripheral is equivalent to another one.
|
||||
*
|
||||
* <p>
|
||||
* The minimal example should at least check whether they are the same object. However, you may wish to check if
|
||||
* they point to the same block or tile entity.
|
||||
*
|
||||
|
||||
@ -15,7 +15,7 @@ import javax.annotation.Nonnull;
|
||||
|
||||
/**
|
||||
* This interface is used to create peripheral implementations for blocks.
|
||||
*
|
||||
* <p>
|
||||
* If you have a {@link TileEntity} which acts as a peripheral, you may alternatively expose the {@link IPeripheral}
|
||||
* capability.
|
||||
*
|
||||
|
||||
@ -12,14 +12,14 @@ import java.util.concurrent.TimeUnit;
|
||||
/**
|
||||
* Monitors "work" associated with a computer, keeping track of how much a computer has done, and ensuring every
|
||||
* computer receives a fair share of any processing time.
|
||||
*
|
||||
* <p>
|
||||
* This is primarily intended for work done by peripherals on the main thread (such as on a tile entity's tick), but
|
||||
* could be used for other purposes (such as complex computations done on another thread).
|
||||
*
|
||||
* <p>
|
||||
* Before running a task, one should call {@link #canWork()} to determine if the computer is currently allowed to
|
||||
* execute work. If that returns true, you should execute the task and use {@link #trackWork(long, TimeUnit)} to inform
|
||||
* the monitor how long that task took.
|
||||
*
|
||||
* <p>
|
||||
* Alternatively, use {@link #runWork(Runnable)} to run and keep track of work.
|
||||
*
|
||||
* @see IComputerAccess#getMainThreadMonitor()
|
||||
@ -35,7 +35,7 @@ public interface IWorkMonitor
|
||||
|
||||
/**
|
||||
* If the owning computer is currently allowed to execute work, and has ample time to do so.
|
||||
*
|
||||
* <p>
|
||||
* This is effectively a more restrictive form of {@link #canWork()}. One should use that in order to determine if
|
||||
* you may do an initial piece of work, and shouldWork to determine if any additional task may be performed.
|
||||
*
|
||||
|
||||
@ -16,7 +16,7 @@ import java.util.Set;
|
||||
|
||||
/**
|
||||
* The type of a {@link GenericPeripheral}.
|
||||
*
|
||||
* <p>
|
||||
* When determining the final type of the resulting peripheral, the union of all types is taken, with the
|
||||
* lexicographically smallest non-empty name being chosen.
|
||||
*/
|
||||
|
||||
@ -17,7 +17,7 @@ import java.util.function.Supplier;
|
||||
|
||||
/**
|
||||
* A base class for {@link IPocketUpgrade}s.
|
||||
*
|
||||
* <p>
|
||||
* One does not have to use this, but it does provide a convenient template.
|
||||
*/
|
||||
public abstract class AbstractPocketUpgrade implements IPocketUpgrade
|
||||
|
||||
@ -21,7 +21,7 @@ public interface IPocketAccess
|
||||
{
|
||||
/**
|
||||
* Gets the entity holding this item.
|
||||
*
|
||||
* <p>
|
||||
* This must be called on the server thread.
|
||||
*
|
||||
* @return The holding entity, or {@code null} if none exists.
|
||||
@ -67,7 +67,7 @@ public interface IPocketAccess
|
||||
|
||||
/**
|
||||
* Get the upgrade-specific NBT.
|
||||
*
|
||||
* <p>
|
||||
* This is persisted between computer reboots and chunk loads.
|
||||
*
|
||||
* @return The upgrade's NBT.
|
||||
|
||||
@ -22,7 +22,7 @@ public interface IPocketUpgrade extends IUpgradeBase
|
||||
{
|
||||
/**
|
||||
* Creates a peripheral for the pocket computer.
|
||||
*
|
||||
* <p>
|
||||
* The peripheral created will be stored for the lifetime of the upgrade, will be passed an argument to
|
||||
* {@link #update(IPocketAccess, IPeripheral)} and will be attached, detached and have methods called in the same
|
||||
* manner as an ordinary peripheral.
|
||||
|
||||
@ -17,7 +17,7 @@ import java.util.function.Supplier;
|
||||
|
||||
/**
|
||||
* A base class for {@link ITurtleUpgrade}s.
|
||||
*
|
||||
* <p>
|
||||
* One does not have to use this, but it does provide a convenient template.
|
||||
*/
|
||||
public abstract class AbstractTurtleUpgrade implements ITurtleUpgrade
|
||||
@ -100,7 +100,7 @@ public abstract class AbstractTurtleUpgrade implements ITurtleUpgrade
|
||||
|
||||
/**
|
||||
* A supplier which converts an item into an item stack.
|
||||
*
|
||||
* <p>
|
||||
* Constructing item stacks is somewhat expensive due to attaching capabilities. We cache it if given a consistent item.
|
||||
*/
|
||||
private static final class CachedStack implements NonNullSupplier<ItemStack>
|
||||
|
||||
@ -22,7 +22,7 @@ import javax.annotation.Nullable;
|
||||
|
||||
/**
|
||||
* The interface passed to turtle by turtles, providing methods that they can call.
|
||||
*
|
||||
* <p>
|
||||
* This should not be implemented by your classes. Do not interact with turtles except via this interface and
|
||||
* {@link ITurtleUpgrade}.
|
||||
*/
|
||||
@ -46,7 +46,7 @@ public interface ITurtleAccess
|
||||
|
||||
/**
|
||||
* Attempt to move this turtle to a new position.
|
||||
*
|
||||
* <p>
|
||||
* This will preserve the turtle's internal state, such as it's inventory, computer and upgrades. It should
|
||||
* be used before playing a movement animation using {@link #playAnimation(TurtleAnimation)}.
|
||||
*
|
||||
@ -144,7 +144,7 @@ public interface ITurtleAccess
|
||||
|
||||
/**
|
||||
* Get the inventory of this turtle.
|
||||
*
|
||||
* <p>
|
||||
* Note: this inventory should only be accessed and modified on the server thread.
|
||||
*
|
||||
* @return This turtle's inventory
|
||||
@ -155,7 +155,7 @@ public interface ITurtleAccess
|
||||
|
||||
/**
|
||||
* Get the inventory of this turtle as an {@link IItemHandlerModifiable}.
|
||||
*
|
||||
* <p>
|
||||
* Note: this inventory should only be accessed and modified on the server thread.
|
||||
*
|
||||
* @return This turtle's inventory
|
||||
@ -278,7 +278,7 @@ public interface ITurtleAccess
|
||||
|
||||
/**
|
||||
* Get an upgrade-specific NBT compound, which can be used to store arbitrary data.
|
||||
*
|
||||
* <p>
|
||||
* This will be persisted across turtle restarts and chunk loads, as well as being synced to the client. You must
|
||||
* call {@link #updateUpgradeNBTData(TurtleSide)} after modifying it.
|
||||
*
|
||||
|
||||
@ -17,7 +17,7 @@ public interface ITurtleCommand
|
||||
{
|
||||
/**
|
||||
* Will be called by the turtle on the main thread when it is time to execute the custom command.
|
||||
*
|
||||
* <p>
|
||||
* The handler should either perform the work of the command, and return success, or return
|
||||
* failure with an error message to indicate the command cannot be executed at this time.
|
||||
*
|
||||
|
||||
@ -41,7 +41,7 @@ public interface ITurtleUpgrade extends IUpgradeBase
|
||||
|
||||
/**
|
||||
* Will only be called for peripheral upgrades. Creates a peripheral for a turtle being placed using this upgrade.
|
||||
*
|
||||
* <p>
|
||||
* The peripheral created will be stored for the lifetime of the upgrade and will be passed as an argument to
|
||||
* {@link #update(ITurtleAccess, TurtleSide)}. It will be attached, detached and have methods called in the same
|
||||
* manner as a Computer peripheral.
|
||||
@ -60,7 +60,7 @@ public interface ITurtleUpgrade extends IUpgradeBase
|
||||
/**
|
||||
* Will only be called for Tool turtle. Called when turtle.dig() or turtle.attack() is called
|
||||
* by the turtle, and the tool is required to do some work.
|
||||
*
|
||||
* <p>
|
||||
* Conforming implementations should fire {@link BlockEvent.BreakEvent} and {@link TurtleBlockEvent.Dig} for
|
||||
* digging, {@link AttackEntityEvent} and {@link TurtleAttackEvent} for attacking.
|
||||
*
|
||||
@ -83,7 +83,7 @@ public interface ITurtleUpgrade extends IUpgradeBase
|
||||
|
||||
/**
|
||||
* Called to obtain the model to be used when rendering a turtle peripheral.
|
||||
*
|
||||
* <p>
|
||||
* This can be obtained from {@link net.minecraft.client.renderer.ItemModelMesher#getItemModel(ItemStack)},
|
||||
* {@link net.minecraft.client.renderer.model.ModelManager#getModel(ModelResourceLocation)} or any other
|
||||
* source.
|
||||
|
||||
@ -7,7 +7,7 @@ package dan200.computercraft.api.turtle;
|
||||
|
||||
/**
|
||||
* An animation a turtle will play between executing commands.
|
||||
*
|
||||
* <p>
|
||||
* Each animation takes 8 ticks to complete unless otherwise specified.
|
||||
*
|
||||
* @see ITurtleAccess#playAnimation(TurtleAnimation)
|
||||
|
||||
@ -37,7 +37,7 @@ public class TurtleActionEvent extends TurtleEvent
|
||||
|
||||
/**
|
||||
* Sets the cancellation state of this action.
|
||||
*
|
||||
* <p>
|
||||
* If {@code cancel} is {@code true}, this action will not be carried out.
|
||||
*
|
||||
* @param cancel The new canceled value.
|
||||
@ -53,7 +53,7 @@ public class TurtleActionEvent extends TurtleEvent
|
||||
|
||||
/**
|
||||
* Set the cancellation state of this action, setting a failure message if required.
|
||||
*
|
||||
* <p>
|
||||
* If {@code cancel} is {@code true}, this action will not be carried out.
|
||||
*
|
||||
* @param cancel The new canceled value.
|
||||
|
||||
@ -19,10 +19,10 @@ import java.util.Objects;
|
||||
|
||||
/**
|
||||
* Fired when a turtle attempts to attack an entity.
|
||||
*
|
||||
* <p>
|
||||
* This must be fired by {@link ITurtleUpgrade#useTool(ITurtleAccess, TurtleSide, TurtleVerb, Direction)},
|
||||
* as the base {@code turtle.attack()} command does not fire it.
|
||||
*
|
||||
* <p>
|
||||
* Note that such commands should also fire {@link AttackEntityEvent}, so you do not need to listen to both.
|
||||
*
|
||||
* @see TurtleAction#ATTACK
|
||||
|
||||
@ -24,13 +24,13 @@ import java.util.Objects;
|
||||
|
||||
/**
|
||||
* A general event for when a turtle interacts with a block or region.
|
||||
*
|
||||
* <p>
|
||||
* You should generally listen to one of the sub-events instead, cancelling them where
|
||||
* appropriate.
|
||||
*
|
||||
* <p>
|
||||
* Note that you are not guaranteed to receive this event, if it has been cancelled by other
|
||||
* mechanisms, such as block protection systems.
|
||||
*
|
||||
* <p>
|
||||
* Be aware that some events (such as {@link TurtleInventoryEvent}) do not necessarily interact
|
||||
* with a block, simply objects within that block space.
|
||||
*/
|
||||
@ -72,10 +72,10 @@ public abstract class TurtleBlockEvent extends TurtlePlayerEvent
|
||||
|
||||
/**
|
||||
* Fired when a turtle attempts to dig a block.
|
||||
*
|
||||
* <p>
|
||||
* This must be fired by {@link ITurtleUpgrade#useTool(ITurtleAccess, TurtleSide, TurtleVerb, Direction)},
|
||||
* as the base {@code turtle.dig()} command does not fire it.
|
||||
*
|
||||
* <p>
|
||||
* Note that such commands should also fire {@link BlockEvent.BreakEvent}, so you do not need to listen to both.
|
||||
*
|
||||
* @see TurtleAction#DIG
|
||||
@ -176,7 +176,7 @@ public abstract class TurtleBlockEvent extends TurtlePlayerEvent
|
||||
|
||||
/**
|
||||
* Fired when a turtle gathers data on a block in world.
|
||||
*
|
||||
* <p>
|
||||
* You may prevent blocks being inspected, or add additional information to the result.
|
||||
*
|
||||
* @see TurtleAction#INSPECT
|
||||
|
||||
@ -14,7 +14,7 @@ import java.util.Objects;
|
||||
/**
|
||||
* A base class for all events concerning a turtle. This will only ever constructed and fired on the server side,
|
||||
* so sever specific methods on {@link ITurtleAccess} are safe to use.
|
||||
*
|
||||
* <p>
|
||||
* You should generally not need to subscribe to this event, preferring one of the more specific classes.
|
||||
*
|
||||
* @see TurtleActionEvent
|
||||
|
||||
@ -15,7 +15,7 @@ import java.util.Objects;
|
||||
|
||||
/**
|
||||
* Fired when a turtle gathers data on an item in its inventory.
|
||||
*
|
||||
* <p>
|
||||
* You may prevent items being inspected, or add additional information to the result. Be aware that this may be fired
|
||||
* on the computer thread, and so any operations on it must be thread safe.
|
||||
*
|
||||
|
||||
@ -13,7 +13,7 @@ import java.util.Objects;
|
||||
|
||||
/**
|
||||
* An action done by a turtle which is normally done by a player.
|
||||
*
|
||||
* <p>
|
||||
* {@link #getPlayer()} may be used to modify the player's attributes or perform permission checks.
|
||||
*/
|
||||
public abstract class TurtlePlayerEvent extends TurtleActionEvent
|
||||
@ -30,7 +30,7 @@ public abstract class TurtlePlayerEvent extends TurtleActionEvent
|
||||
|
||||
/**
|
||||
* A fake player, representing this turtle.
|
||||
*
|
||||
* <p>
|
||||
* This may be used for triggering permission checks.
|
||||
*
|
||||
* @return A {@link FakePlayer} representing this turtle.
|
||||
|
||||
@ -14,7 +14,7 @@ import java.util.Objects;
|
||||
|
||||
/**
|
||||
* Fired when a turtle attempts to refuel from an item.
|
||||
*
|
||||
* <p>
|
||||
* One may use {@link #setCanceled(boolean, String)} to prevent refueling from this specific item. Additionally, you
|
||||
* may use {@link #setHandler(Handler)} to register a custom fuel provider.
|
||||
*/
|
||||
@ -33,7 +33,7 @@ public class TurtleRefuelEvent extends TurtleActionEvent
|
||||
|
||||
/**
|
||||
* Get the stack we are attempting to refuel from.
|
||||
*
|
||||
* <p>
|
||||
* Do not modify the returned stack - all modifications should be done within the {@link Handler}.
|
||||
*
|
||||
* @return The stack to refuel from.
|
||||
@ -57,7 +57,7 @@ public class TurtleRefuelEvent extends TurtleActionEvent
|
||||
|
||||
/**
|
||||
* Set the refuel handler for this stack.
|
||||
*
|
||||
* <p>
|
||||
* You should call this if you can actually refuel from this item, and ideally only if there are no existing
|
||||
* handlers.
|
||||
*
|
||||
|
||||
@ -31,7 +31,7 @@ public class RenderTypes
|
||||
/**
|
||||
* Renders a fullbright terminal which also writes to the depth layer. This is used when z-fighting isn't an issue -
|
||||
* for instance rendering an empty terminal or inside a GUI.
|
||||
*
|
||||
* <p>
|
||||
* This is identical to <em>vanilla's</em> {@link RenderType#text}. Forge overrides one with a definition which sets
|
||||
* sortOnUpload to true, which is entirely broken!
|
||||
*/
|
||||
|
||||
@ -24,14 +24,14 @@ import static org.lwjgl.system.MemoryUtil.memPutFloat;
|
||||
/**
|
||||
* An optimised copy of {@link FixedWidthFontRenderer} emitter emits directly to a {@link ByteBuffer} rather than
|
||||
* emitting to {@link IVertexBuilder}. This allows us to emit vertices very quickly, when using the VBO renderer.
|
||||
*
|
||||
* <p>
|
||||
* There are some limitations here:
|
||||
* <ul>
|
||||
* <li>No transformation matrix (not needed for VBOs).</li>
|
||||
* <li>Only works with {@link DefaultVertexFormats#POSITION_COLOR_TEX}.</li>
|
||||
* <li>The buffer <strong>MUST</strong> be allocated with {@link DirectBuffers}, and not through any other means.</li>
|
||||
* </ul>
|
||||
*
|
||||
* <p>
|
||||
* Note this is almost an exact copy of {@link FixedWidthFontRenderer}. While the code duplication is unfortunate,
|
||||
* it is measurably faster than introducing polymorphism into {@link FixedWidthFontRenderer}.
|
||||
*
|
||||
|
||||
@ -21,7 +21,7 @@ import static dan200.computercraft.client.render.RenderTypes.FULL_BRIGHT_LIGHTMA
|
||||
|
||||
/**
|
||||
* Handles rendering fixed width text and computer terminals.
|
||||
*
|
||||
* <p>
|
||||
* This class has several modes of usage:
|
||||
* <ul>
|
||||
* <li>{@link #drawString}: Drawing basic text without a terminal (such as for printouts). Unlike the other methods,
|
||||
|
||||
@ -43,20 +43,20 @@ import java.util.function.Function;
|
||||
* <li>**File and directory manipulation:** For instance, moving or copying files. See {@link #makeDir}, {@link #move},
|
||||
* {@link #copy} and {@link #delete}.</li>
|
||||
* </ul>
|
||||
*
|
||||
* <p>
|
||||
* :::note
|
||||
* All functions in the API work on absolute paths, and do not take the @{shell.dir|current directory} into account.
|
||||
* You can use @{shell.resolve} to convert a relative path into an absolute one.
|
||||
* :::
|
||||
*
|
||||
* <p>
|
||||
* ## Mounts
|
||||
* While a computer can only have one hard drive and filesystem, other filesystems may be "mounted" inside it. For
|
||||
* instance, the {@link dan200.computercraft.shared.peripheral.diskdrive.DiskDrivePeripheral drive peripheral} mounts
|
||||
* its disk's contents at {@code "disk/"}, {@code "disk1/"}, etc...
|
||||
*
|
||||
* <p>
|
||||
* You can see which mount a path belongs to with the {@link #getDrive} function. This returns {@code "hdd"} for the
|
||||
* computer's main filesystem ({@code "/"}), {@code "rom"} for the rom ({@code "rom/"}).
|
||||
*
|
||||
* <p>
|
||||
* Most filesystems have a limited capacity, operations which would cause that capacity to be reached (such as writing
|
||||
* an incredibly large file) will fail. You can see a mount's capacity with {@link #getCapacity} and the remaining
|
||||
* space with {@link #getFreeSpace}.
|
||||
@ -287,7 +287,7 @@ public class FSAPI implements ILuaAPI
|
||||
|
||||
/**
|
||||
* Moves a file or directory from one path to another.
|
||||
*
|
||||
* <p>
|
||||
* Any parent directories are created as needed.
|
||||
*
|
||||
* @param path The current file or directory to move from.
|
||||
@ -310,7 +310,7 @@ public class FSAPI implements ILuaAPI
|
||||
|
||||
/**
|
||||
* Copies a file or directory to a new path.
|
||||
*
|
||||
* <p>
|
||||
* Any parent directories are created as needed.
|
||||
*
|
||||
* @param path The file or directory to copy.
|
||||
@ -333,7 +333,7 @@ public class FSAPI implements ILuaAPI
|
||||
|
||||
/**
|
||||
* Deletes a file or directory.
|
||||
*
|
||||
* <p>
|
||||
* If the path points to a directory, all of the enclosed files and
|
||||
* subdirectories are also deleted.
|
||||
*
|
||||
@ -358,14 +358,14 @@ public class FSAPI implements ILuaAPI
|
||||
|
||||
/**
|
||||
* Opens a file for reading or writing at a path.
|
||||
*
|
||||
* <p>
|
||||
* The {@code mode} string can be any of the following:
|
||||
* <ul>
|
||||
* <li><strong>"r"</strong>: Read mode</li>
|
||||
* <li><strong>"w"</strong>: Write mode</li>
|
||||
* <li><strong>"a"</strong>: Append mode</li>
|
||||
* </ul>
|
||||
*
|
||||
* <p>
|
||||
* The mode may also have a "b" at the end, which opens the file in "binary
|
||||
* mode". This allows you to read binary files, as well as seek within a file.
|
||||
*
|
||||
@ -516,7 +516,7 @@ public class FSAPI implements ILuaAPI
|
||||
|
||||
/**
|
||||
* Searches for files matching a string with wildcards.
|
||||
*
|
||||
* <p>
|
||||
* This string is formatted like a normal path string, but can include any
|
||||
* number of wildcards ({@code *}) to look for files matching anything.
|
||||
* For example, <code>rom/*/command*</code> will look for any path starting with
|
||||
@ -568,10 +568,10 @@ public class FSAPI implements ILuaAPI
|
||||
|
||||
/**
|
||||
* Get attributes about a specific file or folder.
|
||||
*
|
||||
* <p>
|
||||
* The returned attributes table contains information about the size of the file, whether it is a directory,
|
||||
* when it was created and last modified, and whether it is read only.
|
||||
*
|
||||
* <p>
|
||||
* The creation and modification times are given as the number of milliseconds since the UNIX epoch. This may be
|
||||
* given to {@link OSAPI#date} in order to convert it to more usable form.
|
||||
*
|
||||
|
||||
@ -173,7 +173,7 @@ public class OSAPI implements ILuaAPI
|
||||
* Starts a timer that will run for the specified number of seconds. Once
|
||||
* the timer fires, a {@code timer} event will be added to the queue with
|
||||
* the ID returned from this function as the first parameter.
|
||||
*
|
||||
* <p>
|
||||
* As with @{os.sleep|sleep}, {@code timer} will automatically be rounded up
|
||||
* to the nearest multiple of 0.05 seconds, as it waits for a fixed amount
|
||||
* of world ticks.
|
||||
@ -315,13 +315,13 @@ public class OSAPI implements ILuaAPI
|
||||
/**
|
||||
* Returns the current time depending on the string passed in. This will
|
||||
* always be in the range [0.0, 24.0).
|
||||
*
|
||||
* <p>
|
||||
* * If called with {@code ingame}, the current world time will be returned.
|
||||
* This is the default if nothing is passed.
|
||||
* * If called with {@code utc}, returns the hour of the day in UTC time.
|
||||
* * If called with {@code local}, returns the hour of the day in the
|
||||
* timezone the server is located in.
|
||||
*
|
||||
* <p>
|
||||
* This function can also be called with a table returned from {@link #date},
|
||||
* which will convert the date fields into a UNIX timestamp (number of
|
||||
* seconds since 1 January 1970).
|
||||
@ -363,7 +363,7 @@ public class OSAPI implements ILuaAPI
|
||||
|
||||
/**
|
||||
* Returns the day depending on the locale specified.
|
||||
*
|
||||
* <p>
|
||||
* * If called with {@code ingame}, returns the number of days since the
|
||||
* world was created. This is the default.
|
||||
* * If called with {@code utc}, returns the number of days since 1 January
|
||||
@ -395,7 +395,7 @@ public class OSAPI implements ILuaAPI
|
||||
|
||||
/**
|
||||
* Returns the number of milliseconds since an epoch depending on the locale.
|
||||
*
|
||||
* <p>
|
||||
* * If called with {@code ingame}, returns the number of milliseconds since the
|
||||
* world was created. This is the default.
|
||||
* * If called with {@code utc}, returns the number of milliseconds since 1
|
||||
@ -446,12 +446,12 @@ public class OSAPI implements ILuaAPI
|
||||
/**
|
||||
* Returns a date string (or table) using a specified format string and
|
||||
* optional time to format.
|
||||
*
|
||||
* <p>
|
||||
* The format string takes the same formats as C's {@code strftime} function
|
||||
* (http://www.cplusplus.com/reference/ctime/strftime/). In extension, it
|
||||
* can be prefixed with an exclamation mark ({@code !}) to use UTC time
|
||||
* instead of the server's local timezone.
|
||||
*
|
||||
* <p>
|
||||
* If the format is exactly {@code *t} (optionally prefixed with {@code !}), a
|
||||
* table will be returned instead. This table has fields for the year, month,
|
||||
* day, hour, minute, second, day of the week, day of the year, and whether
|
||||
|
||||
@ -12,7 +12,7 @@ import dan200.computercraft.core.computer.ComputerSide;
|
||||
|
||||
/**
|
||||
* Get and set redstone signals adjacent to this computer.
|
||||
*
|
||||
* <p>
|
||||
* The {@link RedstoneAPI} library exposes three "types" of redstone control:
|
||||
* - Binary input/output ({@link #setOutput}/{@link #getInput}): These simply check if a redstone wire has any input or
|
||||
* output. A signal strength of 1 and 15 are treated the same.
|
||||
@ -21,10 +21,10 @@ import dan200.computercraft.core.computer.ComputerSide;
|
||||
* - Bundled cables ({@link #setBundledOutput}/{@link #getBundledInput}): These interact with "bundled" cables, such
|
||||
* as those from Project:Red. These allow you to send 16 separate on/off signals. Each channel corresponds to a
|
||||
* colour, with the first being @{colors.white} and the last @{colors.black}.
|
||||
*
|
||||
* <p>
|
||||
* Whenever a redstone input changes, a @{event!redstone} event will be fired. This may be used instead of repeativly
|
||||
* polling.
|
||||
*
|
||||
* <p>
|
||||
* This module may also be referred to as {@code rs}. For example, one may call {@code rs.getSides()} instead of
|
||||
* {@link #getSides}.
|
||||
*
|
||||
@ -47,7 +47,7 @@ import dan200.computercraft.core.computer.ComputerSide;
|
||||
* os.pullEvent("redstone") -- Wait for a change to inputs.
|
||||
* end
|
||||
* }</pre>
|
||||
*
|
||||
* <p>
|
||||
* [comparator]: https://minecraft.gamepedia.com/Redstone_Comparator#Subtract_signal_strength "Redstone Comparator on
|
||||
* the Minecraft wiki."
|
||||
* @cc.module redstone
|
||||
|
||||
@ -39,7 +39,7 @@ public abstract class TermMethods
|
||||
|
||||
/**
|
||||
* Write {@code text} at the current cursor position, moving the cursor to the end of the text.
|
||||
*
|
||||
* <p>
|
||||
* Unlike functions like {@code write} and {@code print}, this does not wrap the text - it simply copies the
|
||||
* text to the current terminal line.
|
||||
*
|
||||
@ -61,7 +61,7 @@ public abstract class TermMethods
|
||||
|
||||
/**
|
||||
* Move all positions up (or down) by {@code y} pixels.
|
||||
*
|
||||
* <p>
|
||||
* Every pixel in the terminal will be replaced by the line {@code y} pixels below it. If {@code y} is negative, it
|
||||
* will copy pixels from above instead.
|
||||
*
|
||||
@ -245,7 +245,7 @@ public abstract class TermMethods
|
||||
|
||||
/**
|
||||
* Determine if this terminal supports colour.
|
||||
*
|
||||
* <p>
|
||||
* Terminals which do not support colour will still allow writing coloured text/backgrounds, but it will be
|
||||
* displayed in greyscale.
|
||||
*
|
||||
@ -261,10 +261,10 @@ public abstract class TermMethods
|
||||
|
||||
/**
|
||||
* Writes {@code text} to the terminal with the specific foreground and background characters.
|
||||
*
|
||||
* <p>
|
||||
* As with {@link #write(IArguments)}, the text will be written at the current cursor location, with the cursor
|
||||
* moving to the end of the text.
|
||||
*
|
||||
* <p>
|
||||
* {@code textColour} and {@code backgroundColour} must both be strings the same length as {@code text}. All
|
||||
* characters represent a single hexadecimal digit, which is converted to one of CC's colours. For instance,
|
||||
* {@code "a"} corresponds to purple.
|
||||
@ -299,7 +299,7 @@ public abstract class TermMethods
|
||||
|
||||
/**
|
||||
* Set the palette for a specific colour.
|
||||
*
|
||||
* <p>
|
||||
* ComputerCraft's palette system allows you to change how a specific colour should be displayed. For instance, you
|
||||
* can make @{colors.red} <em>more red</em> by setting its palette to #FF0000. This does now allow you to draw more
|
||||
* colours - you are still limited to 16 on the screen at one time - but you can change <em>which</em> colours are
|
||||
|
||||
@ -249,11 +249,11 @@ public class BinaryReadableHandle extends HandleGeneric
|
||||
/**
|
||||
* Seek to a new position within the file, changing where bytes are written to. The new position is an offset
|
||||
* given by {@code offset}, relative to a start position determined by {@code whence}:
|
||||
*
|
||||
* <p>
|
||||
* - {@code "set"}: {@code offset} is relative to the beginning of the file.
|
||||
* - {@code "cur"}: Relative to the current position. This is the default.
|
||||
* - {@code "end"}: Relative to the end of the file.
|
||||
*
|
||||
* <p>
|
||||
* In case of success, {@code seek} returns the new file position from the beginning of the file.
|
||||
*
|
||||
* @param whence Where the offset is relative to.
|
||||
|
||||
@ -117,11 +117,11 @@ public class BinaryWritableHandle extends HandleGeneric
|
||||
/**
|
||||
* Seek to a new position within the file, changing where bytes are written to. The new position is an offset
|
||||
* given by {@code offset}, relative to a start position determined by {@code whence}:
|
||||
*
|
||||
* <p>
|
||||
* - {@code "set"}: {@code offset} is relative to the beginning of the file.
|
||||
* - {@code "cur"}: Relative to the current position. This is the default.
|
||||
* - {@code "end"}: Relative to the end of the file.
|
||||
*
|
||||
* <p>
|
||||
* In case of success, {@code seek} returns the new file position from the beginning of the file.
|
||||
*
|
||||
* @param whence Where the offset is relative to.
|
||||
|
||||
@ -39,7 +39,7 @@ public abstract class HandleGeneric
|
||||
|
||||
/**
|
||||
* Close this file, freeing any resources it uses.
|
||||
*
|
||||
* <p>
|
||||
* Once a file is closed it may no longer be read or written to.
|
||||
*
|
||||
* @throws LuaException If the file has already been closed.
|
||||
|
||||
@ -13,7 +13,7 @@ import java.util.concurrent.Future;
|
||||
|
||||
/**
|
||||
* Checks a URL using {@link NetworkUtils#getAddress(String, int, boolean)}}
|
||||
*
|
||||
* <p>
|
||||
* This requires a DNS lookup, and so needs to occur off-thread.
|
||||
*/
|
||||
public class CheckUrl extends Resource<CheckUrl>
|
||||
|
||||
@ -126,7 +126,7 @@ public final class NetworkUtils
|
||||
|
||||
/**
|
||||
* Create a {@link InetSocketAddress} from a {@link java.net.URI}.
|
||||
*
|
||||
* <p>
|
||||
* Note, this may require a DNS lookup, and so should not be executed on the main CC thread.
|
||||
*
|
||||
* @param uri The URI to fetch.
|
||||
@ -141,7 +141,7 @@ public final class NetworkUtils
|
||||
|
||||
/**
|
||||
* Create a {@link InetSocketAddress} from the resolved {@code host} and port.
|
||||
*
|
||||
* <p>
|
||||
* Note, this may require a DNS lookup, and so should not be executed on the main CC thread.
|
||||
*
|
||||
* @param host The host to resolve.
|
||||
|
||||
@ -68,7 +68,7 @@ public abstract class Resource<T extends Resource<T>> implements Closeable
|
||||
|
||||
/**
|
||||
* Clean up any pending resources
|
||||
*
|
||||
* <p>
|
||||
* Note, this may be called multiple times, and so should be thread-safe and
|
||||
* avoid any major side effects.
|
||||
*/
|
||||
|
||||
@ -9,7 +9,7 @@ import java.util.function.BiConsumer;
|
||||
|
||||
/**
|
||||
* A Lua object which exposes additional methods.
|
||||
*
|
||||
* <p>
|
||||
* This can be used to merge multiple objects together into one. Ideally this'd be part of the API, but I'm not entirely
|
||||
* happy with the interface - something I'd like to think about first.
|
||||
*/
|
||||
|
||||
@ -22,7 +22,7 @@ import java.util.Iterator;
|
||||
|
||||
/**
|
||||
* Represents the "environment" that a {@link Computer} exists in.
|
||||
*
|
||||
* <p>
|
||||
* This handles storing and updating of peripherals and redstone.
|
||||
*
|
||||
* <h1>Redstone</h1>
|
||||
|
||||
@ -12,18 +12,18 @@ import java.util.concurrent.TimeUnit;
|
||||
|
||||
/**
|
||||
* Used to measure how long a computer has executed for, and thus the relevant timeout states.
|
||||
*
|
||||
* <p>
|
||||
* Timeouts are mostly used for execution of Lua code: we should ideally never have a state where constructing the APIs
|
||||
* or machines themselves takes more than a fraction of a second.
|
||||
*
|
||||
* <p>
|
||||
* When a computer runs, it is allowed to run for 7 seconds ({@link #TIMEOUT}). After that point, the "soft abort" flag
|
||||
* is set ({@link #isSoftAborted()}). Here, the Lua machine will attempt to abort the program in some safe manner
|
||||
* (namely, throwing a "Too long without yielding" error).
|
||||
*
|
||||
* <p>
|
||||
* Now, if a computer still does not stop after that period, they're behaving really badly. 1.5 seconds after a soft
|
||||
* abort ({@link #ABORT_TIMEOUT}), we trigger a hard abort (note, this is done from the computer thread manager). This
|
||||
* will destroy the entire Lua runtime and shut the computer down.
|
||||
*
|
||||
* <p>
|
||||
* The Lua runtime is also allowed to pause execution if there are other computers contesting for work. All computers
|
||||
* are allowed to run for {@link ComputerThread#scaledPeriod()} nanoseconds (see {@link #currentDeadline}). After that
|
||||
* period, if any computers are waiting to be executed then we'll set the paused flag to true ({@link #isPaused()}.
|
||||
@ -104,7 +104,7 @@ public final class TimeoutState
|
||||
|
||||
/**
|
||||
* Whether we should pause execution of this machine.
|
||||
*
|
||||
* <p>
|
||||
* This is determined by whether we've consumed our time slice, and if there are other computers waiting to perform
|
||||
* work.
|
||||
*
|
||||
|
||||
@ -11,7 +11,7 @@ import java.nio.channels.Channel;
|
||||
|
||||
/**
|
||||
* Wraps some closeable object such as a buffered writer, and the underlying stream.
|
||||
*
|
||||
* <p>
|
||||
* When flushing a buffer before closing, some implementations will not close the buffer if an exception is thrown
|
||||
* this causes us to release the channel, but not actually close it. This wrapper will attempt to close the wrapper (and
|
||||
* so hopefully flush the channel), and then close the underlying channel.
|
||||
|
||||
@ -31,7 +31,7 @@ public class FileSystem
|
||||
{
|
||||
/**
|
||||
* Maximum depth that {@link #copyRecursive(String, MountWrapper, String, MountWrapper, int)} will descend into.
|
||||
*
|
||||
* <p>
|
||||
* This is a pretty arbitrary value, though hopefully it is large enough that it'll never be normally hit. This
|
||||
* exists to prevent it overflowing if it ever gets into an infinite loop.
|
||||
*/
|
||||
|
||||
@ -15,12 +15,12 @@ import java.lang.ref.WeakReference;
|
||||
|
||||
/**
|
||||
* An alternative closeable implementation that will free up resources in the filesystem.
|
||||
*
|
||||
* <p>
|
||||
* The {@link FileSystem} maps weak references of this to its underlying object. If the wrapper has been disposed of
|
||||
* (say, the Lua object referencing it has gone), then the wrapped object will be closed by the filesystem.
|
||||
*
|
||||
* <p>
|
||||
* Closing this will stop the filesystem tracking it, reducing the current descriptor count.
|
||||
*
|
||||
* <p>
|
||||
* In an ideal world, we'd just wrap the closeable. However, as we do some {@code instanceof} checks
|
||||
* on the stream, it's not really possible as it'd require numerous instances.
|
||||
*
|
||||
|
||||
@ -10,7 +10,7 @@ import java.io.IOException;
|
||||
|
||||
/**
|
||||
* A {@link Closeable} which knows when it has been closed.
|
||||
*
|
||||
* <p>
|
||||
* This is a quick (though racey) way of providing more friendly (and more similar to Lua)
|
||||
* error messages to the user.
|
||||
*/
|
||||
|
||||
@ -17,7 +17,7 @@ import org.squiddev.cobalt.function.VarArgFunction;
|
||||
|
||||
/**
|
||||
* An "optimised" version of {@link ResultInterpreterFunction} which is guaranteed to never yield.
|
||||
*
|
||||
* <p>
|
||||
* As we never yield, we do not need to push a function to the stack, which removes a small amount of overhead.
|
||||
*/
|
||||
class BasicFunction extends VarArgFunction
|
||||
|
||||
@ -15,11 +15,11 @@ import java.io.InputStream;
|
||||
/**
|
||||
* Represents a machine which will execute Lua code. Technically this API is flexible enough to support many languages,
|
||||
* but you'd need a way to provide alternative ROMs, BIOSes, etc...
|
||||
*
|
||||
* <p>
|
||||
* There should only be one concrete implementation at any one time, which is currently {@link CobaltLuaMachine}. If
|
||||
* external mod authors are interested in registering their own machines, we can look into how we can provide some
|
||||
* mechanism for registering these.
|
||||
*
|
||||
* <p>
|
||||
* This should provide implementations of {@link dan200.computercraft.api.lua.ILuaContext}, and the ability to convert
|
||||
* {@link IDynamicLuaObject}s into something the VM understands, as well as handling method calls.
|
||||
*/
|
||||
@ -28,7 +28,7 @@ public interface ILuaMachine
|
||||
/**
|
||||
* Inject an API into the global environment of this machine. This should construct an object, as it would for any
|
||||
* {@link IDynamicLuaObject} and set it to all names in {@link ILuaAPI#getNames()}.
|
||||
*
|
||||
* <p>
|
||||
* Called before {@link #loadBios(InputStream)}.
|
||||
*
|
||||
* @param api The API to register.
|
||||
@ -38,7 +38,7 @@ public interface ILuaMachine
|
||||
/**
|
||||
* Create a function from the provided program, and set it up to run when {@link #handleEvent(String, Object[])} is
|
||||
* called.
|
||||
*
|
||||
* <p>
|
||||
* This should destroy the machine if it failed to load the bios.
|
||||
*
|
||||
* @param bios The stream containing the boot program.
|
||||
@ -48,7 +48,7 @@ public interface ILuaMachine
|
||||
|
||||
/**
|
||||
* Resume the machine, either starting or resuming the coroutine.
|
||||
*
|
||||
* <p>
|
||||
* This should destroy the machine if it failed to execute successfully.
|
||||
*
|
||||
* @param eventName The name of the event. This is {@code null} when first starting the machine. Note, this may
|
||||
|
||||
@ -13,7 +13,7 @@ import java.io.InputStream;
|
||||
|
||||
/**
|
||||
* The result of executing an action on a machine.
|
||||
*
|
||||
* <p>
|
||||
* Errors should halt the machine and display the error to the user.
|
||||
*
|
||||
* @see ILuaMachine#loadBios(InputStream)
|
||||
|
||||
@ -33,7 +33,7 @@ import java.util.Set;
|
||||
|
||||
/**
|
||||
* Miscellaneous hooks which are present on the client and server.
|
||||
*
|
||||
* <p>
|
||||
* These should possibly be refactored into separate classes at some point, but are fine here for now.
|
||||
*
|
||||
* @see dan200.computercraft.client.ClientHooks For client-specific ones.
|
||||
|
||||
@ -19,7 +19,7 @@ import java.io.File;
|
||||
|
||||
/**
|
||||
* Basic client-side commands.
|
||||
*
|
||||
* <p>
|
||||
* Simply hooks into client chat messages and intercepts matching strings.
|
||||
*/
|
||||
@Mod.EventBusSubscriber( modid = ComputerCraft.MOD_ID, value = Dist.CLIENT )
|
||||
|
||||
@ -30,10 +30,10 @@ import java.util.function.BiConsumer;
|
||||
|
||||
/**
|
||||
* Reads one argument multiple times.
|
||||
*
|
||||
* <p>
|
||||
* Note that this must be the last element in an argument chain: in order to improve the quality of error messages,
|
||||
* we will always try to consume another argument while there is input remaining.
|
||||
*
|
||||
* <p>
|
||||
* One problem with how parsers function, is that they must consume some input: and thus we
|
||||
*
|
||||
* @param <T> The type of each value returned
|
||||
|
||||
@ -59,7 +59,7 @@ public class TableBuilder
|
||||
|
||||
/**
|
||||
* Get the unique identifier for this table type.
|
||||
*
|
||||
* <p>
|
||||
* When showing a table within Minecraft, previous instances of this table with
|
||||
* the same ID will be removed from chat.
|
||||
*
|
||||
@ -72,7 +72,7 @@ public class TableBuilder
|
||||
|
||||
/**
|
||||
* Get the number of columns for this table.
|
||||
*
|
||||
* <p>
|
||||
* This will be the same as {@link #getHeaders()}'s length if it is is non-{@code null},
|
||||
* otherwise the length of the first column.
|
||||
*
|
||||
|
||||
@ -110,11 +110,11 @@ public class CommandAPI implements ILuaAPI
|
||||
|
||||
/**
|
||||
* Asynchronously execute a command.
|
||||
*
|
||||
* <p>
|
||||
* Unlike {@link #exec}, this will immediately return, instead of waiting for the
|
||||
* command to execute. This allows you to run multiple commands at the same
|
||||
* time.
|
||||
*
|
||||
* <p>
|
||||
* When this command has finished executing, it will queue a `task_complete`
|
||||
* event containing the result of executing this command (what {@link #exec} would
|
||||
* return).
|
||||
@ -184,10 +184,10 @@ public class CommandAPI implements ILuaAPI
|
||||
|
||||
/**
|
||||
* Get information about a range of blocks.
|
||||
*
|
||||
* <p>
|
||||
* This returns the same information as @{getBlockInfo}, just for multiple
|
||||
* blocks at once.
|
||||
*
|
||||
* <p>
|
||||
* Blocks are traversed by ascending y level, followed by z and x - the returned
|
||||
* table may be indexed using `x + z*width + y*depth*depth`.
|
||||
*
|
||||
@ -245,7 +245,7 @@ public class CommandAPI implements ILuaAPI
|
||||
|
||||
/**
|
||||
* Get some basic information about a block.
|
||||
*
|
||||
* <p>
|
||||
* The returned table contains the current name, metadata and block state (as
|
||||
* with @{turtle.inspect}). If there is a tile entity for that block, its NBT
|
||||
* will also be returned.
|
||||
|
||||
@ -14,7 +14,7 @@ import javax.annotation.Nullable;
|
||||
|
||||
/**
|
||||
* A computer or turtle wrapped as a peripheral.
|
||||
*
|
||||
* <p>
|
||||
* This allows for basic interaction with adjacent computers. Computers wrapped as peripherals will have the type
|
||||
* {@code computer} while turtles will be {@code turtle}.
|
||||
*
|
||||
|
||||
@ -279,7 +279,7 @@ public abstract class TileComputerBase extends TileGeneric implements IComputerT
|
||||
|
||||
/**
|
||||
* Update all redstone and peripherals.
|
||||
*
|
||||
* <p>
|
||||
* This should only be really be called when the computer is being ticked (though there are some cases where it
|
||||
* won't be), as peripheral scanning requires adjacent tiles to be in a "correct" state - which may not be the case
|
||||
* if they're still updating!
|
||||
|
||||
@ -19,7 +19,7 @@ import java.util.function.Predicate;
|
||||
|
||||
/**
|
||||
* A computer menu which does not have any visible inventory.
|
||||
*
|
||||
* <p>
|
||||
* This adds invisible versions of the player's hotbars slots, to ensure they're synced to the client when changed.
|
||||
*/
|
||||
public class ComputerMenuWithoutInventory extends ContainerComputerBase
|
||||
|
||||
@ -20,7 +20,7 @@ public interface NetworkMessage
|
||||
{
|
||||
/**
|
||||
* Write this packet to a buffer.
|
||||
*
|
||||
* <p>
|
||||
* This may be called on any thread, so this should be a pure operation.
|
||||
*
|
||||
* @param buf The buffer to write data to.
|
||||
|
||||
@ -19,7 +19,7 @@ import javax.annotation.Nonnull;
|
||||
|
||||
/**
|
||||
* Starts or stops a record on the client, depending on if {@link #soundEvent} is {@code null}.
|
||||
*
|
||||
* <p>
|
||||
* Used by disk drives to play record items.
|
||||
*
|
||||
* @see dan200.computercraft.shared.peripheral.diskdrive.TileDiskDrive
|
||||
|
||||
@ -19,7 +19,7 @@ import java.util.UUID;
|
||||
|
||||
/**
|
||||
* Starts a sound on the client.
|
||||
*
|
||||
* <p>
|
||||
* Used by speakers to play sounds.
|
||||
*
|
||||
* @see dan200.computercraft.shared.peripheral.speaker.TileSpeaker
|
||||
|
||||
@ -18,7 +18,7 @@ import java.util.UUID;
|
||||
|
||||
/**
|
||||
* Starts a sound on the client.
|
||||
*
|
||||
* <p>
|
||||
* Used by speakers to play sounds.
|
||||
*
|
||||
* @see dan200.computercraft.shared.peripheral.speaker.TileSpeaker
|
||||
|
||||
@ -19,7 +19,7 @@ import java.util.UUID;
|
||||
|
||||
/**
|
||||
* Starts a sound on the client.
|
||||
*
|
||||
* <p>
|
||||
* Used by speakers to play sounds.
|
||||
*
|
||||
* @see dan200.computercraft.shared.peripheral.speaker.TileSpeaker
|
||||
|
||||
@ -17,7 +17,7 @@ import java.util.UUID;
|
||||
|
||||
/**
|
||||
* Stops a sound on the client
|
||||
*
|
||||
* <p>
|
||||
* Called when a speaker is broken.
|
||||
*
|
||||
* @see dan200.computercraft.shared.peripheral.speaker.TileSpeaker
|
||||
|
||||
@ -28,10 +28,10 @@ import static dan200.computercraft.shared.Capabilities.CAPABILITY_PERIPHERAL;
|
||||
|
||||
/**
|
||||
* This peripheral allows you to interact with command blocks.
|
||||
*
|
||||
* <p>
|
||||
* Command blocks are only wrapped as peripherals if the {@code enable_command_block} option is true within the
|
||||
* config.
|
||||
*
|
||||
* <p>
|
||||
* This API is <em>not</em> the same as the {@link CommandAPI} API, which is exposed on command computers.
|
||||
*
|
||||
* @cc.module command
|
||||
|
||||
@ -22,14 +22,14 @@ import java.util.Optional;
|
||||
/**
|
||||
* Disk drives are a peripheral which allow you to read and write to floppy disks and other "mountable media" (such as
|
||||
* computers or turtles). They also allow you to {@link #playAudio play records}.
|
||||
*
|
||||
* <p>
|
||||
* When a disk drive attaches some mount (such as a floppy disk or computer), it attaches a folder called {@code disk},
|
||||
* {@code disk2}, etc... to the root directory of the computer. This folder can be used to interact with the files on
|
||||
* that disk.
|
||||
*
|
||||
* <p>
|
||||
* When a disk is inserted, a {@code disk} event is fired, with the side peripheral is on. Likewise, when the disk is
|
||||
* detached, a {@code disk_eject} event is fired.
|
||||
*
|
||||
* <p>
|
||||
* ## Recipe
|
||||
* <div class="recipe-container">
|
||||
* <mc-recipe recipe="computercraft:disk_drive"></mc-recipe>
|
||||
@ -80,9 +80,9 @@ public class DiskDrivePeripheral implements IPeripheral
|
||||
|
||||
/**
|
||||
* Sets or clears the label for a disk.
|
||||
*
|
||||
* <p>
|
||||
* If no label or {@code nil} is passed, the label will be cleared.
|
||||
*
|
||||
* <p>
|
||||
* If the inserted disk's label can't be changed (for example, a record),
|
||||
* an error will be thrown.
|
||||
*
|
||||
|
||||
@ -15,7 +15,7 @@ import javax.annotation.Nonnull;
|
||||
|
||||
/**
|
||||
* A few helpers for working with arguments.
|
||||
*
|
||||
* <p>
|
||||
* This should really be moved into the public API. However, until I have settled on a suitable format, we'll keep it
|
||||
* where it is used.
|
||||
*/
|
||||
|
||||
@ -16,9 +16,9 @@ import javax.annotation.Nonnull;
|
||||
|
||||
/**
|
||||
* Methods for interacting with blocks using Forge's energy storage system.
|
||||
*
|
||||
* <p>
|
||||
* This works with energy storage blocks, as well as generators and machines which consume energy.
|
||||
*
|
||||
* <p>
|
||||
* :::note
|
||||
* Due to limitations with Forge's energy API, it is not possible to measure throughput (i.e. RF
|
||||
* used/generated per tick).
|
||||
|
||||
@ -54,10 +54,10 @@ public class FluidMethods implements GenericPeripheral
|
||||
|
||||
/**
|
||||
* Get all "tanks" in this fluid storage.
|
||||
*
|
||||
* <p>
|
||||
* Each tank either contains some amount of fluid or is empty. Tanks with fluids inside will return some basic
|
||||
* information about the fluid, including its name and amount.
|
||||
*
|
||||
* <p>
|
||||
* The returned table is sparse, and so empty tanks will be `nil` - it is recommended to loop over using `pairs`
|
||||
* rather than `ipairs`.
|
||||
*
|
||||
@ -81,7 +81,7 @@ public class FluidMethods implements GenericPeripheral
|
||||
|
||||
/**
|
||||
* Move a fluid from one fluid container to another connected one.
|
||||
*
|
||||
* <p>
|
||||
* This allows you to pull fluid in the current fluid container to another container <em>on the same wired
|
||||
* network</em>. Both containers must attached to wired modems which are connected via a cable.
|
||||
*
|
||||
@ -122,7 +122,7 @@ public class FluidMethods implements GenericPeripheral
|
||||
|
||||
/**
|
||||
* Move a fluid from a connected fluid container into this oneone.
|
||||
*
|
||||
* <p>
|
||||
* This allows you to pull fluid in the current fluid container from another container <em>on the same wired
|
||||
* network</em>. Both containers must attached to wired modems which are connected via a cable.
|
||||
*
|
||||
|
||||
@ -67,12 +67,12 @@ public class InventoryMethods implements GenericPeripheral
|
||||
|
||||
/**
|
||||
* List all items in this inventory. This returns a table, with an entry for each slot.
|
||||
*
|
||||
* <p>
|
||||
* Each item in the inventory is represented by a table containing some basic information, much like
|
||||
* {@link dan200.computercraft.shared.turtle.apis.TurtleAPI#getItemDetail} includes. More information can be fetched
|
||||
* with {@link #getItemDetail}. The table contains the item `name`, the `count` and an a (potentially nil) hash of
|
||||
* the item's `nbt.` This NBT data doesn't contain anything useful, but allows you to distinguish identical items.
|
||||
*
|
||||
* <p>
|
||||
* The returned table is sparse, and so empty slots will be `nil` - it is recommended to loop over using `pairs`
|
||||
* rather than `ipairs`.
|
||||
*
|
||||
@ -104,13 +104,13 @@ public class InventoryMethods implements GenericPeripheral
|
||||
|
||||
/**
|
||||
* Get detailed information about an item.
|
||||
*
|
||||
* <p>
|
||||
* The returned information contains the same information as each item in
|
||||
* {@link #list}, as well as additional details like the display name
|
||||
* (`displayName`), item groups (`itemGroups`), which are the creative tabs
|
||||
* an item will appear under, and item and item durability (`damage`,
|
||||
* `maxDamage`, `durability`).
|
||||
*
|
||||
* <p>
|
||||
* Some items include more information (such as enchantments) - it is
|
||||
* recommended to print it out using @{textutils.serialize} or in the Lua
|
||||
* REPL, to explore what is available.
|
||||
@ -151,7 +151,7 @@ public class InventoryMethods implements GenericPeripheral
|
||||
|
||||
/**
|
||||
* Get the maximum number of items which can be stored in this slot.
|
||||
*
|
||||
* <p>
|
||||
* Typically this will be limited to 64 items. However, some inventories (such as barrels or caches) can store
|
||||
* hundreds or thousands of items in one slot.
|
||||
*
|
||||
@ -178,7 +178,7 @@ public class InventoryMethods implements GenericPeripheral
|
||||
|
||||
/**
|
||||
* Push items from one inventory to another connected one.
|
||||
*
|
||||
* <p>
|
||||
* This allows you to push an item in an inventory to another inventory <em>on the same wired network</em>. Both
|
||||
* inventories must attached to wired modems which are connected via a cable.
|
||||
*
|
||||
@ -225,7 +225,7 @@ public class InventoryMethods implements GenericPeripheral
|
||||
|
||||
/**
|
||||
* Pull items from a connected inventory into this one.
|
||||
*
|
||||
* <p>
|
||||
* This allows you to transfer items between inventories <em>on the same wired network</em>. Both this and the source
|
||||
* inventory must attached to wired modems which are connected via a cable.
|
||||
*
|
||||
|
||||
@ -22,31 +22,31 @@ import java.util.Set;
|
||||
|
||||
/**
|
||||
* Modems allow you to send messages between computers over long distances.
|
||||
*
|
||||
* <p>
|
||||
* :::tip
|
||||
* Modems provide a fairly basic set of methods, which makes them very flexible but often hard to work with. The
|
||||
* {@literal @}{rednet} API is built on top of modems, and provides a more user-friendly interface.
|
||||
* :::
|
||||
*
|
||||
* <p>
|
||||
* ## Sending and receiving messages
|
||||
* Modems operate on a series of channels, a bit like frequencies on a radio. Any modem can send a message on a
|
||||
* particular channel, but only those which have {@link #open opened} the channel and are "listening in" can receive
|
||||
* messages.
|
||||
*
|
||||
* <p>
|
||||
* Channels are represented as an integer between 0 and 65535 inclusive. These channels don't have any defined meaning,
|
||||
* though some APIs or programs will assign a meaning to them. For instance, the @{gps} module sends all its messages on
|
||||
* channel 65534 (@{gps.CHANNEL_GPS}), while @{rednet} uses channels equal to the computer's ID.
|
||||
*
|
||||
* <p>
|
||||
* - Sending messages is done with the {@link #transmit(int, int, Object)} message.
|
||||
* - Receiving messages is done by listening to the @{modem_message} event.
|
||||
*
|
||||
* <p>
|
||||
* ## Types of modem
|
||||
* CC: Tweaked comes with three kinds of modem, with different capabilities.
|
||||
*
|
||||
* <ul>
|
||||
* <li><strong>Wireless modems:</strong> Wireless modems can send messages to any other wireless modem. They can be placed next to a
|
||||
* computer, or equipped as a pocket computer or turtle upgrade.
|
||||
*
|
||||
* <p>
|
||||
* Wireless modems have a limited range, only sending messages to modems within 64 blocks. This range increases
|
||||
* linearly once the modem is above y=96, to a maximum of 384 at world height.</li>
|
||||
* <li><strong>Ender modems:</strong> These are upgraded versions of normal wireless modems. They do not have a distance
|
||||
@ -75,7 +75,7 @@ import java.util.Set;
|
||||
*
|
||||
* print("Received a reply: " .. tostring(message))
|
||||
* }</pre>
|
||||
*
|
||||
* <p>
|
||||
* ## Recipes
|
||||
* <div class="recipe-container">
|
||||
* <mc-recipe recipe="computercraft:wireless_modem_normal"></mc-recipe>
|
||||
@ -216,7 +216,7 @@ public abstract class ModemPeripheral implements IPeripheral, IPacketSender, IPa
|
||||
/**
|
||||
* Sends a modem message on a certain channel. Modems listening on the channel will queue a {@code modem_message}
|
||||
* event on adjacent computers.
|
||||
*
|
||||
* <p>
|
||||
* :::note
|
||||
* The channel does not need be open to send a message.
|
||||
* :::
|
||||
@ -260,7 +260,7 @@ public abstract class ModemPeripheral implements IPeripheral, IPacketSender, IPa
|
||||
|
||||
/**
|
||||
* Determine if this is a wired or wireless modem.
|
||||
*
|
||||
* <p>
|
||||
* Some methods (namely those dealing with wired networks and remote peripherals) are only available on wired
|
||||
* modems.
|
||||
*
|
||||
|
||||
@ -24,7 +24,7 @@ import java.util.Map;
|
||||
|
||||
/**
|
||||
* Represents a local peripheral exposed on the wired network.
|
||||
*
|
||||
* <p>
|
||||
* This is responsible for getting the peripheral in world, tracking id and type and determining whether
|
||||
* it has changed.
|
||||
*/
|
||||
|
||||
@ -76,10 +76,10 @@ public abstract class WiredModemPeripheral extends ModemPeripheral implements IW
|
||||
|
||||
/**
|
||||
* List all remote peripherals on the wired network.
|
||||
*
|
||||
* <p>
|
||||
* If this computer is attached to the network, it _will not_ be included in
|
||||
* this list.
|
||||
*
|
||||
* <p>
|
||||
* :::note
|
||||
* This function only appears on wired modems. Check {@link #isWireless} returns false before calling it.
|
||||
* :::
|
||||
@ -95,7 +95,7 @@ public abstract class WiredModemPeripheral extends ModemPeripheral implements IW
|
||||
|
||||
/**
|
||||
* Determine if a peripheral is available on this wired network.
|
||||
*
|
||||
* <p>
|
||||
* :::note
|
||||
* This function only appears on wired modems. Check {@link #isWireless} returns false before calling it.
|
||||
* :::
|
||||
@ -113,7 +113,7 @@ public abstract class WiredModemPeripheral extends ModemPeripheral implements IW
|
||||
|
||||
/**
|
||||
* Get the type of a peripheral is available on this wired network.
|
||||
*
|
||||
* <p>
|
||||
* :::note
|
||||
* This function only appears on wired modems. Check {@link #isWireless} returns false before calling it.
|
||||
* :::
|
||||
@ -134,7 +134,7 @@ public abstract class WiredModemPeripheral extends ModemPeripheral implements IW
|
||||
|
||||
/**
|
||||
* Check a peripheral is of a particular type.
|
||||
*
|
||||
* <p>
|
||||
* :::note
|
||||
* This function only appears on wired modems. Check {@link #isWireless} returns false before calling it.
|
||||
* :::
|
||||
@ -156,7 +156,7 @@ public abstract class WiredModemPeripheral extends ModemPeripheral implements IW
|
||||
|
||||
/**
|
||||
* Get all available methods for the remote peripheral with the given name.
|
||||
*
|
||||
* <p>
|
||||
* :::note
|
||||
* This function only appears on wired modems. Check {@link #isWireless} returns false before calling it.
|
||||
* :::
|
||||
@ -178,7 +178,7 @@ public abstract class WiredModemPeripheral extends ModemPeripheral implements IW
|
||||
|
||||
/**
|
||||
* Call a method on a peripheral on this wired network.
|
||||
*
|
||||
* <p>
|
||||
* :::note
|
||||
* This function only appears on wired modems. Check {@link #isWireless} returns false before calling it.
|
||||
* :::
|
||||
@ -209,7 +209,7 @@ public abstract class WiredModemPeripheral extends ModemPeripheral implements IW
|
||||
* Returns the network name of the current computer, if the modem is on. This
|
||||
* may be used by other computers on the network to wrap this computer as a
|
||||
* peripheral.
|
||||
*
|
||||
* <p>
|
||||
* :::note
|
||||
* This function only appears on wired modems. Check {@link #isWireless} returns false before calling it.
|
||||
* :::
|
||||
|
||||
@ -19,12 +19,12 @@ import javax.annotation.Nullable;
|
||||
/**
|
||||
* Monitors are a block which act as a terminal, displaying information on one side. This allows them to be read and
|
||||
* interacted with in-world without opening a GUI.
|
||||
*
|
||||
* <p>
|
||||
* Monitors act as @{term.Redirect|terminal redirects} and so expose the same methods, as well as several additional
|
||||
* ones, which are documented below.
|
||||
*
|
||||
* <p>
|
||||
* Like computers, monitors come in both normal (no colour) and advanced (colour) varieties.
|
||||
*
|
||||
* <p>
|
||||
* ## Recipes
|
||||
* <div class="recipe-container">
|
||||
* <mc-recipe recipe="computercraft:monitor_normal"></mc-recipe>
|
||||
|
||||
@ -17,7 +17,7 @@ import java.util.Optional;
|
||||
|
||||
/**
|
||||
* The printer peripheral allows pages and books to be printed.
|
||||
*
|
||||
* <p>
|
||||
* ## Recipe
|
||||
* <div class="recipe-container">
|
||||
* <mc-recipe recipe="computercraft:printer"></mc-recipe>
|
||||
|
||||
@ -35,12 +35,12 @@ import static dan200.computercraft.api.lua.LuaValues.checkFinite;
|
||||
|
||||
/**
|
||||
* The speaker peirpheral allow your computer to play notes and other sounds.
|
||||
*
|
||||
* <p>
|
||||
* The speaker can play three kinds of sound, in increasing orders of complexity:
|
||||
* - {@link #playNote} allows you to play noteblock note.
|
||||
* - {@link #playSound} plays any built-in Minecraft sound, such as block sounds or mob noises.
|
||||
* - {@link #playAudio} can play arbitrary audio.
|
||||
*
|
||||
* <p>
|
||||
* ## Recipe
|
||||
* <div class="recipe-container">
|
||||
* <mc-recipe recipe="computercraft:speaker"></mc-recipe>
|
||||
@ -193,21 +193,21 @@ public abstract class SpeakerPeripheral implements IPeripheral
|
||||
|
||||
/**
|
||||
* Plays a note block note through the speaker.
|
||||
*
|
||||
* <p>
|
||||
* This takes the name of a note to play, as well as optionally the volume
|
||||
* and pitch to play the note at.
|
||||
*
|
||||
* <p>
|
||||
* The pitch argument uses semitones as the unit. This directly maps to the
|
||||
* number of clicks on a note block. For reference, 0, 12, and 24 map to F#,
|
||||
* and 6 and 18 map to C.
|
||||
*
|
||||
* <p>
|
||||
* A maximum of 8 notes can be played in a single tick. If this limit is hit, this function will return
|
||||
* {@literal false}.
|
||||
*
|
||||
* <p>
|
||||
* ### Valid instruments
|
||||
* The speaker supports [all of Minecraft's noteblock instruments](https://minecraft.fandom.com/wiki/Note_Block#Instruments).
|
||||
* These are:
|
||||
*
|
||||
* <p>
|
||||
* {@code "harp"}, {@code "basedrum"}, {@code "snare"}, {@code "hat"}, {@code "bass"}, @code "flute"},
|
||||
* {@code "bell"}, {@code "guitar"}, {@code "chime"}, {@code "xylophone"}, {@code "iron_xylophone"},
|
||||
* {@code "cow_bell"}, {@code "didgeridoo"}, {@code "bit"}, {@code "banjo"} and {@code "pling"}.
|
||||
@ -248,10 +248,10 @@ public abstract class SpeakerPeripheral implements IPeripheral
|
||||
|
||||
/**
|
||||
* Plays a Minecraft sound through the speaker.
|
||||
*
|
||||
* <p>
|
||||
* This takes the [name of a Minecraft sound](https://minecraft.fandom.com/wiki/Sounds.json), such as
|
||||
* {@code "minecraft:block.note_block.harp"}, as well as an optional volume and pitch.
|
||||
*
|
||||
* <p>
|
||||
* Only one sound can be played at once. This function will return {@literal false} if another sound was started
|
||||
* this tick, or if some {@link #playAudio audio} is still playing.
|
||||
*
|
||||
@ -295,18 +295,18 @@ public abstract class SpeakerPeripheral implements IPeripheral
|
||||
|
||||
/**
|
||||
* Attempt to stream some audio data to the speaker.
|
||||
*
|
||||
* <p>
|
||||
* This accepts a list of audio samples as amplitudes between -128 and 127. These are stored in an internal buffer
|
||||
* and played back at 48kHz. If this buffer is full, this function will return {@literal false}. You should wait for
|
||||
* a @{speaker_audio_empty} event before trying again.
|
||||
*
|
||||
* <p>
|
||||
* :::note
|
||||
* The speaker only buffers a single call to {@link #playAudio} at once. This means if you try to play a small
|
||||
* number of samples, you'll have a lot of stutter. You should try to play as many samples in one call as possible
|
||||
* (up to 128×1024), as this reduces the chances of audio stuttering or halting, especially when the server or
|
||||
* computer is lagging.
|
||||
* :::
|
||||
*
|
||||
* <p>
|
||||
* {@literal @}{speaker_audio} provides a more complete guide to using speakers
|
||||
*
|
||||
* @param context The Lua context.
|
||||
@ -361,7 +361,7 @@ public abstract class SpeakerPeripheral implements IPeripheral
|
||||
|
||||
/**
|
||||
* Stop all audio being played by this speaker.
|
||||
*
|
||||
* <p>
|
||||
* This clears any audio that {@link #playAudio} had queued and stops the latest sound played by {@link #playSound}.
|
||||
*
|
||||
* @cc.since 1.100
|
||||
|
||||
@ -21,7 +21,7 @@ import net.minecraftforge.items.wrapper.PlayerMainInvWrapper;
|
||||
|
||||
/**
|
||||
* Control the current pocket computer, adding or removing upgrades.
|
||||
*
|
||||
* <p>
|
||||
* This API is only available on pocket computers. As such, you may use its presence to determine what kind of computer
|
||||
* you are using:
|
||||
*
|
||||
@ -52,7 +52,7 @@ public class PocketAPI implements ILuaAPI
|
||||
|
||||
/**
|
||||
* Search the player's inventory for another upgrade, replacing the existing one with that item if found.
|
||||
*
|
||||
* <p>
|
||||
* This inventory search starts from the player's currently selected slot, allowing you to prioritise upgrades.
|
||||
*
|
||||
* @return The result of equipping.
|
||||
|
||||
@ -139,7 +139,7 @@ public class PocketServerComputer extends ServerComputer implements IPocketAcces
|
||||
|
||||
/**
|
||||
* Set the upgrade for this pocket computer, also updating the item stack.
|
||||
*
|
||||
* <p>
|
||||
* Note this method is not thread safe - it must be called from the server thread.
|
||||
*
|
||||
* @param upgrade The new upgrade to set it to, may be {@code null}.
|
||||
|
||||
@ -28,47 +28,47 @@ import java.util.Optional;
|
||||
/**
|
||||
* Turtles are a robotic device, which can break and place blocks, attack mobs, and move about the world. They have
|
||||
* an internal inventory of 16 slots, allowing them to store blocks they have broken or would like to place.
|
||||
*
|
||||
* <p>
|
||||
* ## Movement
|
||||
* Turtles are capable of moving through the world. As turtles are blocks themselves, they are confined to Minecraft's
|
||||
* grid, moving a single block at a time.
|
||||
*
|
||||
* <p>
|
||||
* {@literal @}{turtle.forward} and @{turtle.back} move the turtle in the direction it is facing, while @{turtle.up} and
|
||||
* {@literal @}{turtle.down} move it up and down (as one might expect!). In order to move left or right, you first need
|
||||
* to turn the turtle using @{turtle.turnLeft}/@{turtle.turnRight} and then move forward or backwards.
|
||||
*
|
||||
* <p>
|
||||
* :::info
|
||||
* The name "turtle" comes from [Turtle graphics], which originated from the Logo programming language. Here you'd move
|
||||
* a turtle with various commands like "move 10" and "turn left", much like ComputerCraft's turtles!
|
||||
* :::
|
||||
*
|
||||
* <p>
|
||||
* Moving a turtle (though not turning it) consumes *fuel*. If a turtle does not have any @{turtle.refuel|fuel}, it
|
||||
* won't move, and the movement functions will return @{false}. If your turtle isn't going anywhere, the first thing to
|
||||
* check is if you've fuelled your turtle.
|
||||
*
|
||||
* <p>
|
||||
* :::tip Handling errors
|
||||
* Many turtle functions can fail in various ways. For instance, a turtle cannot move forward if there's already a block
|
||||
* there. Instead of erroring, functions which can fail either return @{true} if they succeed, or @{false} and some
|
||||
* error message if they fail.
|
||||
*
|
||||
* <p>
|
||||
* Unexpected failures can often lead to strange behaviour. It's often a good idea to check the return values of these
|
||||
* functions, or wrap them in @{assert} (for instance, use `assert(turtle.forward())` rather than `turtle.forward()`),
|
||||
* so the program doesn't misbehave.
|
||||
* :::
|
||||
*
|
||||
* <p>
|
||||
* ## Turtle upgrades
|
||||
* While a normal turtle can move about the world and place blocks, its functionality is limited. Thankfully, turtles
|
||||
* can be upgraded with *tools* and @{peripheral|peripherals}. Turtles have two upgrade slots, one on the left and right
|
||||
* sides. Upgrades can be equipped by crafting a turtle with the upgrade, or calling the @{turtle.equipLeft}/@{turtle.equipRight}
|
||||
* functions.
|
||||
*
|
||||
* <p>
|
||||
* Turtle tools allow you to break blocks (@{turtle.dig}) and attack entities (@{turtle.attack}). Some tools are more
|
||||
* suitable to a task than others. For instance, a diamond pickaxe can break every block, while a sword does more
|
||||
* damage. Other tools have more niche use-cases, for instance hoes can til dirt.
|
||||
*
|
||||
* <p>
|
||||
* Peripherals (such as the @{modem|wireless modem} or @{speaker}) can also be equipped as upgrades. These are then
|
||||
* accessible by accessing the `"left"` or `"right"` peripheral.
|
||||
*
|
||||
* <p>
|
||||
* [Turtle Graphics]: https://en.wikipedia.org/wiki/Turtle_graphics "Turtle graphics"
|
||||
*
|
||||
* @cc.module turtle
|
||||
@ -177,7 +177,7 @@ public class TurtleAPI implements ILuaAPI
|
||||
|
||||
/**
|
||||
* Attempt to break the block in front of the turtle.
|
||||
*
|
||||
* <p>
|
||||
* This requires a turtle tool capable of breaking the block. Diamond pickaxes
|
||||
* (mining turtles) can break any vanilla block, but other tools (such as axes)
|
||||
* are more limited.
|
||||
@ -229,7 +229,7 @@ public class TurtleAPI implements ILuaAPI
|
||||
|
||||
/**
|
||||
* Place a block or item into the world in front of the turtle.
|
||||
*
|
||||
* <p>
|
||||
* "Placing" an item allows it to interact with blocks and entities in front of the turtle. For instance, buckets
|
||||
* can pick up and place down fluids, and wheat can be used to breed cows. However, you cannot use {@link #place} to
|
||||
* perform arbitrary block interactions, such as clicking buttons or flipping levers.
|
||||
@ -337,7 +337,7 @@ public class TurtleAPI implements ILuaAPI
|
||||
|
||||
/**
|
||||
* Change the currently selected slot.
|
||||
*
|
||||
* <p>
|
||||
* The selected slot is determines what slot actions like {@link #drop} or {@link #getItemCount} act on.
|
||||
*
|
||||
* @param slot The slot to select.
|
||||
@ -373,7 +373,7 @@ public class TurtleAPI implements ILuaAPI
|
||||
|
||||
/**
|
||||
* Get the remaining number of items which may be stored in this stack.
|
||||
*
|
||||
* <p>
|
||||
* For instance, if a slot contains 13 blocks of dirt, it has room for another 51.
|
||||
*
|
||||
* @param slot The slot we wish to check. Defaults to the {@link #select selected slot}.
|
||||
@ -514,7 +514,7 @@ public class TurtleAPI implements ILuaAPI
|
||||
|
||||
/**
|
||||
* Suck an item from the inventory in front of the turtle, or from an item floating in the world.
|
||||
*
|
||||
* <p>
|
||||
* This will pull items into the first acceptable slot, starting at the {@link #select currently selected} one.
|
||||
*
|
||||
* @param count The number of items to suck. If not given, up to a stack of items will be picked up.
|
||||
@ -583,10 +583,10 @@ public class TurtleAPI implements ILuaAPI
|
||||
|
||||
/**
|
||||
* Refuel this turtle.
|
||||
*
|
||||
* <p>
|
||||
* While most actions a turtle can perform (such as digging or placing blocks) are free, moving consumes fuel from
|
||||
* the turtle's internal buffer. If a turtle has no fuel, it will not move.
|
||||
*
|
||||
* <p>
|
||||
* {@link #refuel} refuels the turtle, consuming fuel items (such as coal or lava buckets) from the currently
|
||||
* selected slot and converting them into energy. This finishes once the turtle is fully refuelled or all items have
|
||||
* been consumed.
|
||||
@ -675,7 +675,7 @@ public class TurtleAPI implements ILuaAPI
|
||||
|
||||
/**
|
||||
* Get the maximum amount of fuel this turtle can hold.
|
||||
*
|
||||
* <p>
|
||||
* By default, normal turtles have a limit of 20,000 and advanced turtles of 100,000.
|
||||
*
|
||||
* @return The limit, or "unlimited".
|
||||
@ -693,7 +693,7 @@ public class TurtleAPI implements ILuaAPI
|
||||
|
||||
/**
|
||||
* Equip (or unequip) an item on the left side of this turtle.
|
||||
*
|
||||
* <p>
|
||||
* This finds the item in the currently selected slot and attempts to equip it to the left side of the turtle. The
|
||||
* previous upgrade is removed and placed into the turtle's inventory. If there is no item in the slot, the previous
|
||||
* upgrade is removed, but no new one is equipped.
|
||||
@ -713,7 +713,7 @@ public class TurtleAPI implements ILuaAPI
|
||||
|
||||
/**
|
||||
* Equip (or unequip) an item on the right side of this turtle.
|
||||
*
|
||||
* <p>
|
||||
* This finds the item in the currently selected slot and attempts to equip it to the right side of the turtle. The
|
||||
* previous upgrade is removed and placed into the turtle's inventory. If there is no item in the slot, the previous
|
||||
* upgrade is removed, but no new one is equipped.
|
||||
|
||||
@ -15,7 +15,7 @@ import java.util.Set;
|
||||
|
||||
/**
|
||||
* Provides a delegate over inventories.
|
||||
*
|
||||
* <p>
|
||||
* This may be used both on {@link net.minecraft.tileentity.TileEntity}s to redirect the inventory to another tile,
|
||||
* and by other interfaces to have inventories which change their backing store.
|
||||
*/
|
||||
|
||||
@ -44,7 +44,7 @@ public final class ThreadUtils
|
||||
|
||||
/**
|
||||
* Create a new {@link ThreadFactoryBuilder}, which constructs threads under a group of the given {@code name}.
|
||||
*
|
||||
* <p>
|
||||
* Each thread will be of the format {@code ComputerCraft-<name>-<number>}, and belong to a group
|
||||
* called {@code ComputerCraft-<name>} (which in turn will be a child group of the main {@code ComputerCraft} group.
|
||||
*
|
||||
@ -64,7 +64,7 @@ public final class ThreadUtils
|
||||
|
||||
/**
|
||||
* Create a new {@link ThreadFactory}, which constructs threads under a group of the given {@code name}.
|
||||
*
|
||||
* <p>
|
||||
* Each thread will be of the format {@code ComputerCraft-<name>-<number>}, and belong to a group
|
||||
* called {@code ComputerCraft-<name>} (which in turn will be a child group of the main {@code ComputerCraft} group.
|
||||
*
|
||||
|
||||
@ -19,7 +19,7 @@ import java.util.concurrent.ConcurrentLinkedDeque;
|
||||
|
||||
/**
|
||||
* A thread-safe version of {@link ITickList#scheduleTick(BlockPos, Object, int)}.
|
||||
*
|
||||
* <p>
|
||||
* We use this when modems and other peripherals change a block in a different thread.
|
||||
*/
|
||||
@Mod.EventBusSubscriber( modid = ComputerCraft.MOD_ID )
|
||||
|
||||
@ -17,7 +17,7 @@ import net.minecraft.world.IWorld;
|
||||
|
||||
/**
|
||||
* Represents a block which can be filled with water
|
||||
*
|
||||
* <p>
|
||||
* I'm fairly sure this exists on 1.14, but it's a useful convenience wrapper to have on 1.13.
|
||||
*/
|
||||
public final class WaterloggableHelpers
|
||||
|
||||
Some files were not shown because too many files have changed in this diff Show More
Loading…
Reference in New Issue
Block a user