mirror of
https://github.com/SquidDev-CC/CC-Tweaked
synced 2025-07-14 16:02:57 +00:00
d5f82fa458
When creating a peripheral or custom Lua object, one must implement two
methods:
- getMethodNames(): String[] - Returns the name of the methods
- callMethod(int, ...): Object[] - Invokes the method using an index in
the above array.
This has a couple of problems:
- It's somewhat unwieldy to use - you need to keep track of array
indices, which leads to ugly code.
- Functions which yield (for instance, those which run on the main
thread) are blocking. This means we need to spawn new threads for
each CC-side yield.
We replace this system with a few changes:
- @LuaFunction annotation: One may annotate a public instance method
with this annotation. This then exposes a peripheral/lua object
method.
Furthermore, this method can accept and return a variety of types,
which often makes functions cleaner (e.g. can return an int rather
than an Object[], and specify and int argument rather than
Object[]).
- MethodResult: Instead of returning an Object[] and having blocking
yields, functions return a MethodResult. This either contains an
immediate return, or an instruction to yield with some continuation
to resume with.
MethodResult is then interpreted by the Lua runtime (i.e. Cobalt),
rather than our weird bodgey hacks before. This means we no longer
spawn new threads when yielding within CC.
- Methods accept IArguments instead of a raw Object array. This has a
few benefits:
- Consistent argument handling - people no longer need to use
ArgumentHelper (as it doesn't exist!), or even be aware of its
existence - you're rather forced into using it.
- More efficient code in some cases. We provide a Cobalt-specific
implementation of IArguments, which avoids the boxing/unboxing when
handling numbers and binary strings.
54 lines
2.6 KiB
Java
54 lines
2.6 KiB
Java
/*
|
|
* This file is part of the public ComputerCraft API - http://www.computercraft.info
|
|
* Copyright Daniel Ratcliffe, 2011-2020. This API may be redistributed unmodified and in full only.
|
|
* For help using the API, and posting your mods, visit the forums at computercraft.info.
|
|
*/
|
|
package dan200.computercraft.api.peripheral;
|
|
|
|
import dan200.computercraft.api.lua.*;
|
|
|
|
import javax.annotation.Nonnull;
|
|
|
|
/**
|
|
* A peripheral whose methods are not known at runtime.
|
|
*
|
|
* This behaves similarly to {@link IDynamicLuaObject}, though also accepting the current {@link IComputerAccess}.
|
|
* Generally one may use {@link LuaFunction} instead of implementing this interface.
|
|
*/
|
|
public interface IDynamicPeripheral extends IPeripheral
|
|
{
|
|
/**
|
|
* Should return an array of strings that identify the methods that this peripheral exposes to Lua. This will be
|
|
* called once before each attachment, and should not change when called multiple times.
|
|
*
|
|
* @return An array of strings representing method names.
|
|
* @see #callMethod
|
|
*/
|
|
@Nonnull
|
|
String[] getMethodNames();
|
|
|
|
/**
|
|
* This is called when a lua program on an attached computer calls {@code peripheral.call()} with
|
|
* one of the methods exposed by {@link #getMethodNames()}.
|
|
*
|
|
* Be aware that this will be called from the ComputerCraft Lua thread, and must be thread-safe when interacting
|
|
* with Minecraft objects.
|
|
*
|
|
* @param computer The interface to the computer that is making the call. Remember that multiple
|
|
* computers can be attached to a peripheral at once.
|
|
* @param context The context of the currently running lua thread. This can be used to wait for events
|
|
* or otherwise yield.
|
|
* @param method An integer identifying which of the methods from getMethodNames() the computercraft
|
|
* wishes to call. The integer indicates the index into the getMethodNames() table
|
|
* that corresponds to the string passed into peripheral.call()
|
|
* @param arguments The arguments for this method.
|
|
* @return A {@link MethodResult} containing the values to return or the action to perform.
|
|
* @throws LuaException If you throw any exception from this function, a lua error will be raised with the
|
|
* same message as your exception. Use this to throw appropriate errors if the wrong
|
|
* arguments are supplied to your method.
|
|
* @see #getMethodNames()
|
|
*/
|
|
@Nonnull
|
|
MethodResult callMethod( @Nonnull IComputerAccess computer, @Nonnull ILuaContext context, int method, @Nonnull IArguments arguments ) throws LuaException;
|
|
}
|