imported>OCDoc Import: Imported from legacy OpenComputers documentation at ocdoc.cil.li

2026-08-24T08:08:27Z

Imported from legacy OpenComputers documentation at ocdoc.cil.li

New page

= 模组开发：自定义架构 =

在此文章中我会讲解OC模组的架构是如何工作的，以及如何添加自定义架构。一句警告：架构的实现'''并非易事'''，别指望着轻而易举就能完成。

== 架构是什么？ ==

首先让我们来申明OC模组语境下的“架构”是什么。架构指将某种代码执行器（以下称虚拟机）和OC模组的组件/Minecraft结合起来的程序。OC将组件逻辑与电脑逻辑严格分开。换言之，组件（例如显卡）不知道它自身在使用什么架构。反过来，架构也不知道组件如何工作。传递的一切信息都由'''执行机'''处理。执行机驱动架构，并提供回调函数使架构能与外界通信。

== 使用架构 ==

为了让内容不那么难以理解，这里将讲解如何实际'''应用'''架构。这大概能让读者更好地理解架构实现是怎么融入OC模组生态的。要使用架构，则必须创建一个使用此架构的执行机。

* '''注意：'''OC 1.4版本后，附属模组可以注册通过CPU提供的架构，因此你无需添加一种电脑方块/物品了。可以通过手持CPU时潜行右键单击来切换其提供的架构。

执行机封装了架构，并负责线程调度、信号队列、网络连接等。执行机创建好以后，你只需每tick调用一次`update()`函数（还可能需要向其传递一些调用，例如`start()`）。

== 生命周期 ==

架构的生命周期大致为：实例化，`initialize()`，反复执行`runThreaded()` / `runSynchronized()`，`close()` [, 转到 `initialize()`]。

* 执行机被创建时，架构即被创建。 - 执行机启动或重启时，会要求`initialize()`自身。通常来说代表着创建底层虚拟机。 - 驱动架构的标准方法是通过`runThreaded()`函数，它由执行器线程调用。架构的状态应在此处处理。其返回值类型被执行机用于调度。'''注意：'''此方法不应抛出异常。你有责任处理所有错误，并在需要的时候将它们转换为代表报错的返回值。 - 需要有一个特殊执行结果来表示进行“同步调用”。这个返回值会告诉执行机下次需要用`runSynchronized()`来驱动架构。这种调用'''一定会由MC服务端线程执行'''，代表着可以安全地在此回调函数中与世界交互。 - 执行机停止时会调用`close()`函数。然后释放所有打开的资源。

== 提供上下文 ==

在最简单的样例中，每次调用`runThreaded()`时在你的虚拟机中仅仅进行若干`run`调用。不过这样做实际用处不大，因为你会想要以某种方式与外界通信。为了实现此功能，需要将与组件的通信提供给虚拟机。你需要在虚拟机内定义用于与执行机API通信的API（例如：`components()`和`invoke()`）。

== 同步调用与调用上限 ==

组件可能有一些回调函数声明为“直接调用”，此外它们可能还会定义“调用上限”。默认情况下，所有的组件回调函数都是'''同步调用'''，即架构必须保证这些函数只能由`runSynchronized()`调用。直接调用的调用上限限制了单个执行机每tick调用某一个函数的次数。限制本身由执行机的`invoke`方法确保实现，此方法会在调用次数过多时抛出`LimitReachedException`异常。此时架构应当短暂休眠，或者改为执行非同步调用。

* '''注意：'''在写这段内容的时候，我发现我忘记了把一些执行检查所需的方法放入API中。这将在下一个API更新中得到修复，使这些方法在`Component`接口中可用。现在的话，要么将它们反射进去，要么从OC源码自行构建模组。我对此表示抱歉。

== 样例代码 ==

假设你有能提供以下接口的虚拟机：

```java /**虚拟机自身。这里的仅为一个样例，不是“真的”接口。*/ public interface PseudoVM {

<pre>Object[] run(Object[] args) throws Exception;
</pre>
<pre>void setApiFunction(String name, PseudoNativeFunction value);
</pre>
}

/**定义了主机提供的回调的接口。*/ public interface PseudoNativeFunction {

<pre>Object invoke(Object[] args);
</pre>
} ```

一个简单的架构实现大概看起来像这样子：

```java /**这是你实现的类；这里的架构来自OC的API。*/ @Architecture.Name("Pseudolang") public class PseudoArchitecture implements Architecture {

<pre>private final Machine machine;
</pre>
<pre>private PseudoVM vm;
</pre>
<pre>/**构造函数的签名必须与此处完全一致。*/
public PseudoArchitecture(Machine machine) {
this.machine = machine;
}
</pre>
<pre>public boolean isInitialized() { return true; }
</pre>
<pre>public void recomputeMemory() {}
</pre>
<pre>public boolean initialize() {
//在此处新建虚拟机，并在里面注册你想要的所有API回调函数。
vm = new PseudoVM();
vm.setApiFunction("invoke", new PseudoNativeFunction() {
public Object invoke(Object[] args) {
final String address = (String)args[0];
final String method = (String)args[1];
final Object[] params = (Object[])args[2];
try {
return new Object[]{true, machine.invoke(address, method, params)};
}
catch (e LimitReachedException) {
//这里的执行逻辑也可用于休眠/执行同步调用。
//在此样例中我们遵循这样的协议：
//成功时返回(true,某物)，到达上限时返回(false)。
//此后虚拟机中运行的脚本需要将控制权交还给
//初始化了当前执行的任务的调用者（例如，若支持的话
//可以yield，或者在事件驱动的系统中直接return）
return new Object[]{false};
}
}
});
vm.setApiFunction("isDirect", new PseudoNativeFunction() {
public Object invoke(Object[] args) {
final String address = (String)args[0];
final String method = (String)args[1];
final Node node = machine.node().network().node(address);
if (node instanceof Component) {
final Component component = (Component) node;
if (component.canBeSeenFrom(machine.node())) {
final Callback callback = machine.methods(node.host()).get(method);
if (callback != null) {
return callback.direct();
}
}
}
return false;
}
});
// ... 更多回调。
return true;
}
</pre>
<pre>void close() {
vm = null;
}
</pre>
<pre>ExecutionResult runThreaded(boolean isSynchronizedReturn) {
//在此处执行所需步骤。通常你会希望通过将队列中下一个信号传递给
//虚拟机的方式来唤醒它，但你也可能会选择让你的虚拟机手动拉取信号。
try {
final Signal signal;
if (isSynchronizedReturn) {
//正在从同步调用中返回时不要拉取信号！因为我们正在执行其他事情。
signal = null;
}
else {
signal = machine.popSignal();
}
final Object[] result;
if (signal != null) {
result = vm.run(new Object[]{signal.name(), signal.args()});
}
else {
result = vm.run(null);
}
</pre>
<pre> //你可能会想定义一些内部协议，用以决定何时执行同步调用。
//假设我们希望虚拟机在出现待决定的同步调用时返回数字值，代表休眠
//或者返回布尔值，代表关机/重启或其他东西。
if (result != null) {
if (result[0] instanceof Boolean) {
return new ExecutionResult.Shutdown((Boolean)result[0]);
}
if (result[0] instanceof Integer) {
return new ExecutionResult.Sleep((Integer)result[0]);
}
}
//若返回此值，下次'resume'时会调用runSynchronized。
//此次调用后的下次对runThreaded函数的调用中
//isSynchronizedReturn参数将会设定为true。
return new ExecutionResult.SynchronizedCall();
}
catch (Throwable t) {
return new ExecutionResult.Error(t.toString);
}
}
</pre>
<pre>void runSynchronized() {
//同步调用在MC的服务端线程中执行，让回调与世界交互更方便
//（因为它们之间的同步由执行机/架构完成）
//这意味着若虚拟机中的代码开始了一次同步调用，就需要''暂停''
//并且放弃对主机的控制，然后我们切换到同步调用模式（参看runThreaded），
//并等待MC服务端线程，接着再进行实际的调用。
//可以在runThread中传递调用所需的信息，将其存储在架构中，
//然后在此处直接进行调用。
//对此样例而言，让我们假定状态信息存储于虚拟机内部，并且
//下次resume使其进行''实际''调用。下面给出了处理它们的伪代码。
vm.run(null);
}
</pre>
<pre>void onConnect() {}
</pre>
<pre>//用这行代码加载虚拟机状态，假如虚拟机可持续。
void load(NBTTagCompound nbt) {}
</pre>
<pre>//用这行代码保存虚拟机状态，假如虚拟机可持续。
void save(NBTTagCompound nbt) {}
</pre>
} ```

一些用于在虚拟机中处理同步调用的伪代码：

```scala private def invokeSynchronous(address, method, ...) {

<pre>yield; //此处为返回到runThreaded()的地方。
//此处为进入runSynchronized();的地方
val result = native.invoke(address, method, ...);
//查看initialize()中invoke的定义以获取结果值的信息。
yield; //并返回runSynchronized();
//并且下一个runThreaded()又进入了。
return result[1];
</pre>
} private def invokeDirect(address, method, ...) {

<pre>val result = native.invoke(address, method, ...);
//查看initialize()中invoke的定义以获取结果值的信息。
if (result[0] == true) {
return result[1];
}
else {
return invokeSynchronous(address, method, ...);
}
</pre>
} def invoke(address, method, ...) {

<pre>if (isDirect(address, method)) {
return invokeDirect(address, method, ...);
}
else {
return invokeSynchronous(address, method, ...);
}
</pre>
} ```

== 注册架构 ==

这一步非常简单，只需调用`li.cil.oc.api.Machine.add(PseudoArchitecture.class)`即可。注册架构后CPU即可提供被注册的架构。如果你不想让OC模组的CPU提供你的架构，那么你可以添加自己的`Processor`驱动程序以用于访问架构。或者更进一步，添加你自己的电脑方块，专用于运行你的架构。

== 目录 ==

{{:Tutorial/contents/zh}}

Tutorial/modding architecture/zh - Revision history

imported>OCDoc Import: Imported from legacy OpenComputers documentation at ocdoc.cil.li