mirror of
https://github.com/SquidDev-CC/CC-Tweaked
synced 2025-11-22 16:14:48 +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.
59 lines
2.3 KiB
Java
59 lines
2.3 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.lua;
|
|
|
|
import dan200.computercraft.api.peripheral.IComputerAccess;
|
|
import dan200.computercraft.api.peripheral.IPeripheral;
|
|
|
|
import java.lang.annotation.*;
|
|
import java.util.Map;
|
|
import java.util.Optional;
|
|
|
|
/**
|
|
* Used to mark a Java function which is callable from Lua.
|
|
*
|
|
* 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:
|
|
*
|
|
* <ul>
|
|
* <li>{@link ILuaContext} (and {@link IComputerAccess} if on a {@link IPeripheral})</li>
|
|
* <li>{@link IArguments}: The arguments supplied to this function.</li>
|
|
* <li>
|
|
* Alternatively, one may specify the desired arguments as normal parameters and the argument parsing code will
|
|
* be generated automatically.
|
|
*
|
|
* 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>
|
|
*
|
|
* 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
|
|
* {@link MethodResult#of(Object...)}.
|
|
*/
|
|
@Documented
|
|
@Retention( RetentionPolicy.RUNTIME )
|
|
@Target( ElementType.METHOD )
|
|
public @interface LuaFunction
|
|
{
|
|
/**
|
|
* Explicitly specify the method names of this function. If not given, it uses the name of the annotated method.
|
|
*
|
|
* @return This function's name(s).
|
|
*/
|
|
String[] value() default {};
|
|
|
|
/**
|
|
* Run this function on the main server thread. This should be specified for any method which interacts with
|
|
* Minecraft in a thread-unsafe manner.
|
|
*
|
|
* @return Whether this functi
|
|
* @see ILuaContext#issueMainThreadTask(ILuaTask)
|
|
*/
|
|
boolean mainThread() default false;
|
|
}
|