从长远的角度来说，「千年虫」问题当然没有结束——我们还有 2100 年，2200 年，等等；但正所谓「一万年太久，只争朝夕」，我们距离下一个世纪的到来还有足足七十余年，哪怕响应中关村某高校「为祖国健康工作六十年」的口号，那也最多只需要考虑到 2082 年。那么在这几十年的时间内，我们是不是便可高枕无忧，「千年虫」问题是不是就暂时离我们而去了呢？

我们不妨想一想这样一个问题，把 00 解析成 1900 固然在某种程度上违反了我们的日常使用习惯，但是把 00 解析成 2000，把 99 解析成 1999，真的就那么顺理成章吗？这里自然便会引入一个「截断年份」（Pivot Year）的概念：两位年份倘若大于这个「截断年份」，在转换成四位年份的时候便会视为上一个世纪，倘若小于等于便会视为当前这个世纪。

我们熟知的「千年虫」问题可以视为将「截断年份」设置成了 1999——当然目前主流的计算机系统和软件早已不是如此。考虑到目前主流的编程语言和不少标准库都支持解析两位年份，并能「正确」地将 00 解析成 2000，那么我们不由得想问：「截断年份」到底是多少？经过简单的搜索引擎搜索，我发现似乎并没有人系统总结过不同编程语言和标准库是如何实现「截断年份」的——但经过一圈调研我发现，不同的实现简直是五花八门，精彩纷呈。在此仅提取 TIOBE 2022 年 10 月榜单前十名为例。

值得提醒的是：不少编程语言和标准库都支持自主设置「截断年份」，在此以默认值为准。

SQL

不同 SQL 数据库对「截断年份」的实现均有不同：

• Microsoft SQL Server：2049（49/50 分别视为 2049/1950）
• MySQL / MariaDB：2069（69/70 分别视为 2069/1970）
• Oracle：当前所在世纪的 99 年（99/00 分别视为 2099/2000）
• PostgreSQL：2069（69/70 分别视为 2069/1970）
• SQLite：不支持自动解析两位年份

PHP

PHP 对解析日期（如内置的 strtotime 函数等）有一套共同的准则。准则中规定了对于两位年份的解析范围应处于 1970 和 2069 之间，换言之，PHP 的「截断年份」为 2069。

ASM / C++ / C

之所以把这三者列在一起是因为它们都不存在一个能够解析日期的标准库函数。不过，对 C/C++ 的 time.h 而言，标准库里定义了用于格式化日期的 strftime 函数，该函数对应 POSIX 的 strftime。POSIX 同时存在用于解析日期格式的 strptime，但并未在 C/C++ 标准库里有所对应。POSIX 的 strptime 规定两位年份在 68/69 处截断（分别对应 2068/1969），换言之，「截断年份」为 2068。

C++ 11 及更高版本

C++ 11 及更高版本在 iomanip 定义了 get_time 和 put_time 函数，用于向输入流读入解析后，以及向输出流写入格式化后的日期，其约定和 strftime 及 strptime 相同。

JavaScript

JavaScript 主要使用 Date.parse 函数解析日期，但 Date.parse 函数只保证能够解析 ISO 8601 格式的字符串——这一格式的年份是四位数。同时在 Chrome 107.0.5304.87、Firefox 102.4.0、以及 Node 18.12.0 下尝试解析 01 Jan 49 和 01 Jan 50 得到的实验结果是：49/50 分别视为 2049/1950，亦即「截断年份」为 2049。

C# / Visual Basic

鉴于 TIOBE 目前将 VB.NET 视为 Visual Basic，故将其与 C# 放在一起讨论：两者均基于 .NET 平台。MSDN 上介绍了在 .NET 平台设置「截断年份」的方法。在 2022 年 10 月 23 日前，这个「截断年份」一直是 2029，但一个 Pull Request（dotnet/runtime#76848）让 .NET 平台从这一天开始变成了 2049。Microsoft Excel 等软件继承了 2029 这一设定，而国产软件 WPS 将这一设定照抄了过来。由于这一 Pull Request 的存在，我们仍然无法知晓未来版本（或者干脆在未来时间）的 Microsoft Excel 和 WPS 是否会将其向后调整 20 年。

Java

在某种程度上说，Java 对「截断年份」的实现可能是这篇文章中最有趣的：在 Java 标准库里，「截断年份」被设置成了当前年份后的第 19 年（见 SimpleDateFormat 的文档）。本文撰写于 2022 年，故本文完稿时 41/42 将分别解析成 2041/1942，而如果读者是在 2023 年看到的这篇文章，那么 42 便将会解析成 2042 了。

Java 8 及更高版本

Java 8 及更高版本额外引入了 java.time 包，其中用于解析日期的是 DateTimeFormatter 类，在文档中规定：解析两位年份时，默认在 2000 年和 2099 年之间，也就是说 java.time 包的「截断年份」为 2099。

Python

Python 的 datetime 库内置了 strftime 和 strptime 函数，并明确了用于格式化日期的 strftime 和 C 语言标准库的 strftime 相一致（也因此同 POSIX 相一致）。我们合理推测用于解析日期格式 strptime 函数也和 POSIX 相一致。在 Python 3.10.8（Linux 平台）上的实验结果也证实了「截断日期」位于 2068 处。

总结

在这篇短短的文章中我们已经看到了数种不同的「截断年份」：2029、2049、2068、2069、2099……而最早的 2029 已经距离我们不足十年！换言之，「千年虫」问题带来的影响绝非想象中的那样遥远。对于现有的计算机系统和软件而言，它们所使用的「截断年份」越晚，暴露出来问题的时间也就越晚。当然，对于新开发的计算机系统和软件而言，最好的解决方案可能仍然是——使用四位数年份存储时间。

以下是参考链接：

• https://en.wikipedia.org/wiki/Year_2000_problem
• https://www.toutiao.com/article/7071076546601026055/
• https://en.wikipedia.org/wiki/Date_windowing
• https://www.tiobe.com/tiobe-index/
• https://www.php.net/manual/en/datetime.formats.date.php
• https://pubs.opengroup.org/onlinepubs/9699919799/
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/parse
• https://learn.microsoft.com/en-us/dotnet/api/system.globalization.calendar.twodigityearmax
• https://github.com/dotnet/runtime/pull/76848
• https://docs.oracle.com/en/java/javase/19/docs/api/java.base/java/text/SimpleDateFormat.html

长期以来至少在我的周围似乎都充斥着一种论断：「RESTful API 设计起来很别扭」，更有人会直言「那些不追求原教旨主义 RESTful 的人早就写完需求下班了，而追求原教旨主义的还在加班」。这话乍一听有一些道理，但实际上这么做会无形地为后续维护增加更多成本——尤其是在需求本身就不明确并且还会频繁变更的情况下。

一个例子：维护菜谱

设想我们有一个维护菜谱的需求，一般后端设计者都很容易设计出下面的 API：

GET /dishes # 获取所有菜谱  
GET /dishes/{id} # 获取特定 ID 的菜谱  
POST /dishes # 添加特定菜谱  
PUT /dishes/{id} # 修改特定 ID 的菜谱  
DELETE /dishes/{id} # 删除特定 ID 的菜谱  

当然一些设计风格比较 RPC 的可能会写成这样：

GET /dish/selectAll # 获取所有菜谱  
GET /dish/selectById # 获取特定 ID 的菜谱  
POST /dish/add # 添加特定菜谱  
POST /dish/modifyById # 修改特定 ID 的菜谱  
POST /dish/deleteById # 删除特定 ID 的菜谱  

这两者在理解成本和设计上其实没有什么不一样的，程序员写完需求，开开心心地下班了。

新需求：菜单步骤

现在突然多了两个需求：每个菜谱都会有一个或多个特定的步骤，用户需要添加步骤或者修改某个特定的步骤的名称。

喜欢 RPC 设计风格的稍加思索搞出来了下面的 API：

GET /dish/selectStepsById # 获取特定菜谱的所有步骤  
POST /dish/appendStepById # 为特定菜谱添加步骤  
POST /dish/modifyStepById # 为特定菜谱修改特定步骤的名称  

RESTful API 原教旨主义者想了半天，折腾出来下面的 API：

GET /dishes/{id}/steps # 获取特定菜谱的所有步骤  
POST /dishes/{id}/steps # 为特定菜谱添加步骤  
PUT /dishes/{id}/steps/{step-id}/name # 为特定菜谱修改特定步骤的名称  

等 API 设计出来并实现好的时候，RESTful API 原教旨主义者发现设计 RPC 风格的程序员已经提前跑去把午饭吃了。

新需求：调整步骤

现在突然又多了一个需求：用户需要修改某个特定的步骤的花费时长。

喜欢 RPC 设计风格的发现了问题，modifyStepById 已经拿去用了，他只能从以下两个选择里挑一个：

1. 把花费时间的 API 叫成 modifyStepDurationById。

2. 之前 modifyStepById 的请求可能是 {"name":"foo"}，现在额外规定：

   {"name":"foo"} 代表修改名称，{"duration":"5m30s"} 代表修改花费时长，都存在则都修改。

我们姑且采用第一种方案：

POST /dish/modifyStepDurationById # 为特定菜谱修改特定步骤的花费时长  

RESTful API 原教旨主义者可能会采用这样的设计：

PUT /dishes/{id}/steps/{step-id}/duration # 为特定菜谱修改特定步骤的花费时长  

当然也可以采取偷懒一点的方案：

PUT /dishes/{id}/steps/{step-id} # 为特定菜谱修改特定步骤的全部信息  

当然，上面这个方案的代价是不需要修改的数据都需要原样传回去一次。

新需求：交换步骤顺序

新需求又来了：用户需要可以交换两个步骤的顺序。

喜欢 RPC 设计风格的可能很快就设计好了 API：

POST /dish/exchangeTwoStepsById # 为特定菜谱交换两个步骤的顺序  

RESTful API 原教旨主义者遇到了「怎么设计怎么难受」的困境，他最后设计出来的 API 大概率是这样的：

POST /dishes/{id}/steps/exchanges # 为特定菜谱交换两个步骤的顺序  

不得不说，这个接口设计出来就是「别扭」的，违反直觉的——这自然也是那些不追求原教旨主义的程序员的理由。

数个月后

数个月后，一批新来的员工决定维护一下现有的系统，他们看到的是什么样的呢？

对那些不追求「原教旨主义」的 RPC 设计风格 API，它们现在长这样：

GET /dish/selectAll # 获取所有菜谱  
GET /dish/selectById # 获取特定 ID 的菜谱  
GET /dish/selectStepsById # 获取特定菜谱的所有步骤

POST /dish/add # 添加特定菜谱  
POST /dish/modifyById # 修改特定 ID 的菜谱  
POST /dish/deleteById # 删除特定 ID 的菜谱  
POST /dish/appendStepById # 为特定菜谱添加步骤  
POST /dish/modifyStepById # 为特定菜谱修改特定步骤的名称  
POST /dish/modifyStepDurationById # 为特定菜谱修改特定步骤的花费时长  
POST /dish/exchangeTwoStepsById # 为特定菜谱交换两个步骤的顺序  

而对于 RESTful 原教旨主义 API 则是这样的：

GET /dishes # 获取所有菜谱  
GET /dishes/{id} # 获取特定 ID 的菜谱  
GET /dishes/{id}/steps # 获取特定菜谱的所有步骤

POST /dishes # 添加特定菜谱  
POST /dishes/{id}/steps # 为特定菜谱添加步骤  
POST /dishes/{id}/steps/exchanges # 为特定菜谱交换两个步骤的顺序

PUT /dishes/{id} # 修改特定 ID 的菜谱  
PUT /dishes/{id}/steps/{step-id}/name # 为特定菜谱修改特定步骤的名称  
PUT /dishes/{id}/steps/{step-id}/duration # 为特定菜谱修改特定步骤的花费时长

DELETE /dishes/{id} # 删除特定 ID 的菜谱  

哪个理解起来一目了然，恐怕是不言而喻的。那么问题出在哪儿呢？

• 在这个示例里，光 RPC 设计风格 API 里就有足足 6 个动词：select、add、modify、append、`delete、exchange。其中 add 和 append 本质上是一样的，只是设计的时候选择不一样而已，而 exchange 更是新的动词。原教旨主义把动词限定在了「增删改查」四个，其中唯一反直觉的是 exchange 被设计成了「向 exchanges 增加数据」，但和「重新理解一个 exchange 动词」相比，这点程度的反直觉又算得上什么呢？
• 在这个示例里同时出现了 modifyStepById 和 modifyStepDurationById 两个接口，而前者由于历史遗留原因其实只负责修改名字——新开发者在看到具体的调用约定（POST 的 JSON 格式等）之前是很难在大脑里形成一个直观的认识的。原教旨主义会在一开始就「逼迫」你在设计 API 的时候把 /name 写上去，哪怕是对整个步骤修改的 API，也在逼着你保证你修改的和你查询的是一个东西。
• 在这个示例里开发者很难一眼看出哪些是「所有数据」、哪些是「特定数据」、哪些是「和步骤有关的数据」，这些本质上是因为在设计的时候便偷了懒——原教旨主义同样在一开始设计的时候就在「逼迫」你想清楚这个问题——至少所有「和步骤有关的数据」全都在 /steps 下。

在我个人看来，原教旨主义 RESTful API 风格固然设计得很别扭，但是它至少在让你设计的时候便在「逼迫」你理清楚你到底在做什么，而不是通过一开始的偷懒，在后续阶段增加不必要的理解成本。总的来说，原教旨主义 RESTful API 风格带来的设计上的反直觉等代价和后续维护增加的理解成本相比不值一提。

以上都是我的个人观点。如果想要对上面说的这些提出一点批判的话，希望各位就事论事，而不是单纯地用「你写过 xxx 吗」什么的来攻击我。

本文基于：

• Java 11.0.8
• Minecraft 1.15.2
• Minecraft Forge 31.2.0
• MCP Mapping 20200514-1.15.1

读者可以在这里下载到本文的源代码：source.zip（56.6 KiB）。

本篇文章由 TeaConMC 采用知识共享-署名-相同方式共享 4.0 国际许可协议进行许可。

引言

发光效果于 Minecraft 1.9 正式引入。发光效果的引入是划时代的：它使得基于着色器的可编程图形管线（Programmable Graphics Pipeline）正式作为不可或缺的游戏特性被引入，而非仅仅通过点击 Super Secret Settings 这一若有若无的按钮，或是当玩家在旁观模式观察生物时才会引起玩家的注意。

发光效果的实际渲染方式需要首先计算特定边缘，然后在计算得到的边缘处绘制外框。这一操作固然可以使用 CPU 完成，但是交给 GPU 计算显然是更好的选择，着色器（Shader）便是用于交给 GPU 计算的小程序，与之有关的编程语言被称为 OpenGL Shader Language，简称 GLSL。

因为计算边缘这一特定需求，因此发光效果必须单独渲染，不能和已有的世界渲染等直接混合（否则世界中其他的「边缘」便会一并囊括进来），这也是我们需要在渲染过程中引入额外帧缓冲（Framebuffer）的必要性所在。

本篇文章将以使工作中的熔炉（Furnace）和高炉（Blast Furnace）发光为目标，演示整个渲染过程。以下是大致的渲染流程：

本文中的示例 Mod ID 为 examplelitfurnacehl。

Minecraft 中的着色器和帧缓冲

在 Minecraft 1.15.2 中，控制着色器的类为 net.minecraft.client.shader.ShaderGroup，我们会用到它的以下几个方法：

• createBindFramebuffers：用于调整着色器对应的帧缓冲的长宽。
• getFramebufferRaw：用于获取着色器相关联的帧缓冲。
• render：为特定的帧缓冲应用着色器。
• close：清理内存。

帧缓冲相关的类为 net.minecraft.client.shader.Framebuffer，我们会用到：

• framebufferRenderExt：把一个帧缓冲中的渲染数据全部渲染到另一个帧缓冲上。
• bindFramebuffer：绑定该帧缓冲（亦即接下来的渲染操作全部针对该帧缓冲）。
• framebufferClear：清空帧缓冲中的渲染数据。

每个 ShaderGroup 的实例都对应到一个 JSON 文件。通常该 JSON 文件位于资源包中特定 Mod ID 所处资源路径下的 shaders/post 目录中，本文为 assets/examplelitfurnacehl/shaders/post 目录下的 furnace_outline.json。以下是该 JSON 的全部内容：

{
    "targets": [
        "examplelitfurnacehl:swap",
        "examplelitfurnacehl:final"
    ],
    "passes": [{
        "name": "minecraft:entity_outline",
        "intarget": "examplelitfurnacehl:final",
        "outtarget": "examplelitfurnacehl:swap"
    }, {
        "name": "minecraft:blur",
        "intarget": "examplelitfurnacehl:swap",
        "outtarget": "examplelitfurnacehl:final",
        "uniforms": [{
            "name": "BlurDir",
            "values": [1.0, 0.0]
        }, {
            "name": "Radius",
            "values": [2.0]
        }]
    }, {
        "name": "minecraft:blur",
        "intarget": "examplelitfurnacehl:final",
        "outtarget": "examplelitfurnacehl:swap",
        "uniforms": [{
            "name": "BlurDir",
            "values": [0.0, 1.0]
        }, {
            "name": "Radius",
            "values": [2.0]
        }]
    }, {
        "name": "minecraft:blit",
        "intarget": "examplelitfurnacehl:swap",
        "outtarget": "examplelitfurnacehl:final"
    }]
}

targets 代表创建多少相关联的帧缓冲，这里创建了两个：

• 第一个帧缓冲名为 examplelitfurnacehl:swap。
• 第二个帧缓冲名为 examplelitfurnacehl:final。

passes 代表应用着色器的渲染次数，这里一共四次，由三组着色器控制：

• 第一次由 minecraft:entity_outline 控制，负责边缘探测。
• 第二次和第三次由 minecraft:blur 控制，负责动态模糊。
• 最后一次由 minecraft:blit 控制，负责单纯复制。

注意动态模糊一共两次，一次是水平方向的，一次是竖直方向的，由下面 uniforms 中 BlurDir 对应的值确定。事实上 uniforms 将会作为 GLSL 的 uniform 输入传递给着色器。

每一组着色器的控制文件位于资源包中特定 Mod ID 所处资源路径下的 shaders/program 目录，比如 assets/minecraft/shaders/program 目录下的 blur.json。该文件由 Minecraft 本身提供，对应 minecraft:blur，其中定义了每一次渲染是如何进行的。以下是该文件的大致内容：

{
    "blend": {
        "func": "add",
        "srcrgb": "one",
        "dstrgb": "zero"
    },
    "vertex": "sobel",
    "fragment": "blur",
    "attributes": ["Position"],
    "samplers": [{
        "name": "DiffuseSampler"
    }],
    "uniforms": [{
        "name": "ProjMat",
        "type": "matrix4x4",
        "count": 16,
        "values": [1.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 0.0, 1.0]
    }, {
        "name": "InSize",
        "type": "float",
        "count": 2,
        "values": [1.0, 1.0]
    }, {
        "name": "OutSize",
        "type": "float",
        "count": 2,
        "values": [1.0, 1.0]
    }, {
        "name": "BlurDir",
        "type": "float",
        "count": 2,
        "values": [1.0, 1.0]
    }, {
        "name": "Radius",
        "type": "float",
        "count": 1,
        "values": [5.0]
    }]
}

• blend 代表混合模式。
• vertex 代表顶点着色器的位置。
• fragment 代表片元着色器的位置。
• attributes 代表着色器的 attribute 输入，通常只用得到 Position。
• samplers 代表着色器的 sampler2D 输入，通常只用得到 DiffuseSampler。
• uniforms 代表着色器的 uniform 输入和默认值，通常而言它们是固定的。

ShaderGroup 中的每一次渲染，本质上都是将一个帧缓冲中的渲染数据提取出来，重新绘制到另一个帧缓冲上，这使得顶点着色器虽然不是完全没有用处，但一定程度上也有一点鸡肋——只有固定的 1 个面和 4 个顶点，因此不同的 ShaderGroup 复用同一个顶点着色器是很常发生的事情，不过片元着色器相对而言要有用得多。

可能有读者对边缘探测的算法感兴趣，其实就是相当于对整个渲染数据做了一次差分计算，感兴趣的可以进一步了解 Sobel Filter 相关的资料。

Mod 主类

以下是最初的 Mod 主类（已略去 package 和 import）：

@Mod(ExampleLitFurnaceHighlighting.ID)
public final class ExampleLitFurnaceHighlighting {  
    public static final String ID = "examplelitfurnacehl";
    public static final Logger LOGGER = LogManager.getLogger(ExampleLitFurnaceHighlighting.class);

    public ExampleLitFurnaceHighlighting() {
        FMLJavaModLoadingContext.get().getModEventBus().addListener(this::onModelRegistry);
        MinecraftForge.EVENT_BUS.addListener(this::onRenderWorldLast);
    }

    private void onModelRegistry(ModelRegistryEvent event) {
        // TODO
    }

    private void onRenderWorldLast(RenderWorldLastEvent event) {
        // TODO: step 0
        // TODO: step 1
        // TODO: step 2
        // TODO: step 3
        // TODO: step 4
        // TODO: step 5
        // TODO: step 6
        // TODO: step 7
        // TODO: step 8
        // TODO: step 9
    }
}

我们把 onModelRegistry 和 onRenderWorldLast 两个方法的方法引用作为事件监听器，稍后我们再完善这两个方法的实现。

加载着色器和帧缓冲

由于 ShaderGroup 的相关定义位于资源包中，因此我们需要在资源包重新加载（如按下 F3 + T）时生成新的 ShaderGroup，因此我们需要寻找每次重新加载时都触发的事件。在 Minecraft Forge 中，我们可以监听 net.minecraftforge.client.event.ModelRegistryEvent。

以下是 onModelRegistry 的实现：

private int framebufferWidth = -1;  
private int framebufferHeight = -1;

private ShaderGroup shaders = null;

private void onModelRegistry(ModelRegistryEvent event) {  
    if (this.shaders != null) this.shaders.close();

    this.framebufferWidth = this.framebufferHeight = -1;

    var resourceLocation = new ResourceLocation(ID, "shaders/post/furnace_outline.json");

    try {
        var mc = Minecraft.getInstance();
        var mainFramebuffer = mc.getFramebuffer();
        var textureManager = mc.getTextureManager();
        var resourceManager = mc.getResourceManager();
        this.shaders = new ShaderGroup(textureManager, resourceManager, mainFramebuffer, resourceLocation);
    } catch (IOException | JsonSyntaxException e) {
        LOGGER.warn("Failed to load shader: {}", resourceLocation, e);
        this.shaders = null;
    }
}

注意这里我们还没有调整着色器对应的帧缓冲的长宽，因此我们新建了两个名为 framebufferWidth 和 framebufferHeight 的字段，并且把它们都设成 -1，稍后我们会在渲染的时候填入正确的值。

mainFramebuffer 是游戏的主帧缓冲，所有玩家能看得到的画面，对应的都是这一帧缓冲的渲染数据。

完成渲染

我们需要在世界渲染完成后在我们自己的帧缓冲上完成渲染，并叠加到游戏的主帧缓冲上，因此我们需要 Minecraft Forge 提供的名为 net.minecraftforge.client.event.RenderWorldLastEvent 的事件。

收集方块数据

首先我们检查 ShaderGroup 是否受支持：

// step 0: check if shaders are supported
if (this.shaders == null) return;  

然后遍历客户端世界所有的 TileEntity，从而确定所有工作中的熔炉和高炉：

// step 1: collect furnaces
var mc = Minecraft.getInstance();  
var world = Objects.requireNonNull(mc.world);  
var furnaceCollection = new HashMap<BlockPos, BlockState>();  
for (var tileEntity : world.loadedTileEntityList) {  
    var blockState = tileEntity.getBlockState();
    if (Blocks.FURNACE.equals(blockState.getBlock()) && blockState.get(BlockStateProperties.LIT)) {
        furnaceCollection.put(tileEntity.getPos(), blockState);
    }
    if (Blocks.BLAST_FURNACE.equals(blockState.getBlock()) && blockState.get(BlockStateProperties.LIT)) {
        furnaceCollection.put(tileEntity.getPos(), blockState);
    }
}
if (furnaceCollection.isEmpty()) return;  

如果不存在这样的 TileEntity，那么也没有进行下一步渲染的必要了。

设置帧缓冲的长宽

我们还没设置帧缓冲的长宽，我们把长宽缓存到两个字段中，如果发现不一样（比如说玩家调整了窗口的大小等）则重新设置一次。

// step 2: resize our framebuffer
var mainWindow = mc.getMainWindow();  
var width = mainWindow.getFramebufferWidth();  
var height = mainWindow.getFramebufferHeight();  
if (width != this.framebufferWidth || height != this.framebufferHeight) {  
    this.framebufferWidth = width;
    this.framebufferHeight = height;
    this.shaders.createBindFramebuffers(width, height);
}

收集顶点数据

Minecraft 自身提供了 net.minecraft.client.renderer.BufferBuilder 用于收集顶点数据。

private final BufferBuilder bufferBuilder = new BufferBuilder(256);

// step 3: prepare block faces
var matrixStack = event.getMatrixStack();  
var dispatcher = mc.getBlockRendererDispatcher();  
var view = mc.gameRenderer.getActiveRenderInfo().getProjectedView();  
this.bufferBuilder.begin(GL11.GL_QUADS, DefaultVertexFormats.POSITION);  
for (var entry : furnaceCollection.entrySet()) {  
    var blockPos = entry.getKey();
    var blockState = entry.getValue();
    var model = dispatcher.getModelForState(blockState);

    matrixStack.push();
    matrixStack.translate(-view.getX(), -view.getY(), -view.getZ());
    matrixStack.translate(blockPos.getX(), blockPos.getY(), blockPos.getZ());

    dispatcher.getBlockModelRenderer().renderModel(
            matrixStack.getLast(), this.bufferBuilder, blockState, model,
            /*red*/1.0F, /*green*/1.0F, /*blue*/1.0F, /*light*/0xFFFFFFFF,
            /*overlay*/OverlayTexture.NO_OVERLAY, /*model data*/EmptyModelData.INSTANCE);

    matrixStack.pop();
}
this.bufferBuilder.finishDrawing();  

开始收集数据（begin 方法）需要两个参数。其中，第一个参数是 GL11.GL_QUADS，因为是方块数据的默认形式，而第二个参数我们采用了 DefaultVertexFormats.POSITION，因为我们根本不需要顶点位置之外的任何数据（通常情况下的渲染还需要颜色材质等其他数据）。

此外，注意 matrixStack 需要平移两次，一次针对玩家位置，一次针对方块位置。

渲染到我们的帧缓冲

首先需要绑定我们的帧缓冲。通过分析上面提到的 JSON，我们可以注意到，我们需要绑定的帧缓冲的名称是 examplelitfurnacehl:final：

// step 4: bind our framebuffer
var framebuffer = this.shaders.getFramebufferRaw(ID + ":final");  
framebuffer.framebufferClear(Minecraft.IS_RUNNING_ON_MAC);  
framebuffer.bindFramebuffer(/*set viewport*/false);  

然后执行渲染，注意我们：

• 不需要和已有的渲染数据混合
• 不需要绑定任何材质
• 不需要透明度测试
• 不需要深度数据
• 重置颜色

// step 5: render block faces to our framebuffer
RenderSystem.disableBlend();  
RenderSystem.disableTexture();  
RenderSystem.disableAlphaTest();  
RenderSystem.depthMask(/*flag*/false);  
RenderSystem.color4f(1.0F, 1.0F, 1.0F, 1.0F);  
WorldVertexBufferUploader.draw(this.bufferBuilder);  

上面有一些设置不是针对可编程图形管线的，但是由于 Minecraft 目前并没有采用纯粹的可编程图形管线（亦即 OpenGL Core Profile），因此还是需要设置一下。

使用着色器渲染

使用着色器渲染不需要绑定特定的帧缓冲。

// step 6: apply shaders
this.shaders.render(event.getPartialTicks());  

刚才的 JSON 告诉我们，我们最终仍然渲染到 examplelitfurnacehl:final，稍后我们会重新用到这一帧缓冲。

渲染到主帧缓冲

渲染之前首先要绑定主帧缓冲：

// step 7: bind main framebuffer
mc.getFramebuffer().bindFramebuffer(/*set viewport*/false);  

然后把混合打开，执行最终渲染。注意 Dst 是主帧缓冲，Src 是我们自己的帧缓冲：

// step 8: render our framebuffer to main framebuffer
RenderSystem.enableBlend();  
RenderSystem.blendFuncSeparate(  
        GlStateManager.SourceFactor.SRC_ALPHA,
        GlStateManager.DestFactor.ONE_MINUS_SRC_ALPHA,
        GlStateManager.SourceFactor.ZERO, GlStateManager.DestFactor.ONE);
framebuffer.framebufferRenderExt(width, height, /*replacement*/false);  

收尾

记得把弄乱了的设置复原回去：

// step 9: clean up
RenderSystem.disableBlend();  
RenderSystem.enableTexture();  
RenderSystem.depthMask(/*flag*/true);  

最终效果

TeaConMC 旗下的开源项目 Slide Show 已经将上述特性写进相关代码中，并作为方便创造模式玩家寻找被埋藏的方块的一种解决方案。

Forge 在高版本（Minecraft 1.13+）为事件总线添加了使用 Functional Interface 监听事件的方式。以下是接口声明：

<T extends Event> void addListener(Consumer<T> consumer);  

我们可以注意到，我们不需要向 addListener 方法传入一个额外的 Class 代表事件的类型，也就是说事件类型只能通过我们传入的 Consumer<T> 拿到。换言之，我们需要从 Consumer<T> 中推断出具体的 T 是什么类型，考虑到 Java 的泛型擦除机制，这不得不说是一个困难。

本文将以 Consumer<T> 类型为例，阐述将类型参数从泛型类型的实例（尤其是 Lambda 表达式）中捕获的方式。读者应能相对容易地将其推广到其他类型。

本文将使用 Java 11（实际上相较基于 Java 8 的等价代码，只是单纯地多了一些 var 而已），以证明该解决方案不单纯限于 Java 8 或更低版本。

常规解决方案

有的读者可能会说，这很简单啊：我们只需要通过一点反射的小技巧，就可以拿到具体的类型。

类似的实现有很多，比如 Guava 在 TypeToken 中的实现。这里我们也随手写一个：

public static Class<?> getErased(Type type)  
{
    if (type instanceof ParameterizedType)
    {
        return getErased(((ParameterizedType) type).getRawType());
    }
    if (type instanceof GenericArrayType)
    {
        return Array.newInstance(getErased(((GenericArrayType) type).getGenericComponentType()), 0).getClass();
    }
    if (type instanceof TypeVariable<?>)
    {
        var bounds = ((TypeVariable<?>) type).getBounds();
        return bounds.length > 0 ? getErased(bounds[0]) : Object.class;
    }
    if (type instanceof WildcardType)
    {
        var bounds = ((WildcardType) type).getUpperBounds();
        return bounds.length > 0 ? getErased(bounds[0]) : Object.class;
    }
    if (type instanceof Class<?>)
    {
        return (Class<?>) type;
    }
    return Object.class;
}

public static Class<?> getConsumerParameterType(Consumer<?> consumer) throws ReflectiveOperationException  
{
    for (var type : consumer.getClass().getGenericInterfaces())
    {
        if (type instanceof ParameterizedType && ((ParameterizedType) type).getRawType() == Consumer.class)
        {
            return getErased(((ParameterizedType) type).getActualTypeArguments()[0]);
        }
    }
    if (consumer.getClass().isSynthetic())
    {
        return getConsumerLambdaParameterType(consumer);
    }
    throw new NoSuchMethodException();
}

getConsumerParameterType 方法的实现对于匿名内部类非常完美，换句话说，下面这一实例中的具体参数类型将会很容易地被捕获：

Consumer<String> a = new Consumer<String>  
{
    @Override
    public void accept(String s)
    {
        System.out.println(s);
    }
}

但对于 Lambda 表达式（也包括方法引用）呢？

Consumer<String> b = s -> System.out.println(s);  
Consumer<String> c = System.out::println;  

实际上，我们从 Lambda 表达式中，根本拿不到一个 ParameterizedType，更不要说从里面提取参数类型了。我们需要其他的方法，当然了，也是更为 dirty hack 的方法。

探究 Lambda 表达式常量池

每个 .class 后缀的文件中都有一段二进制存放的是该类或接口的常量池（Constant Pool），其中包含着描述每个字段和方法的符号引用。

我们知道，对于每个 Lambda 表达式，JVM 都会为其生成对应的类型，而它们也包含了常量池。我们需要做的，就是把 Lambda 表达式对应的常量池提取出来，并寻找对我们有用的方法的符号引用。

我们需要排除这些符号引用：

• 构造方法的符号引用
• 覆盖 Object 类的方法的符号引用

我们可以通过调用 Class 类的 getConstantPool 方法（非公开）拿到常量池，也就是 ConstantPool 类的实例。但是，从 Java 9 开始，常量池的实现被移动到了 jdk.internal.reflect 包下，换言之，如果想要调用常量池的一些非公开方法，我们需要一些更激进的策略。

我们可以通过替换 Method 类下的 override 字段来绕过 JVM 的限制。为此，我们先编写辅助用的方法：

public static Method getMethod(Class<?> objClass, String methodName) throws NoSuchMethodException  
{
    for (var method : objClass.getDeclaredMethods())
    {
        if (methodName.equals(method.getName()))
        {
            return method;
        }
    }
    throw new NoSuchMethodException();
}

public static Object invoke(Object obj, String methodName, Object... args) throws ReflectiveOperationException  
{
    var overrideField = AccessibleObject.class.getDeclaredField("override");
    overrideField.setAccessible(true);
    var targetMethod = getMethod(obj.getClass(), methodName);
    overrideField.set(targetMethod, true);
    return targetMethod.invoke(obj, args);
}

上面的 invoke 方法将会找到特定名称的方法，并针对性的调用该方法。由于仅为演示可行性用，因此上面的方法并未考虑性能，因此如果读者需要在实际开发中用到，请自行对该实现进行优化。

从常量池中获取参数类型

我们将接下来的工作分为四步：

• 找到 Lambda 表达式对应的 Class 的常量池
• 依次遍历常量池中对方法的符号引用
• 排除无关方法的符号引用
• 从第一个满足条件的方法中取出参数类型

需要用到 ConstantPool 的两个方法：

• getSize 方法：用于获取常量池的元素个数
• getMethodAt 方法：用于获取常量池特定位置对方法的符号引用

注意如果 getMethodAt 寻找的位置对应的不是对方法的符号引用，调用该方法将会报错。我们需要把该报错屏蔽掉，然后尝试寻找下一个常量池中的元素。

下面的实现贯彻了上面提到的四步。需要注意的一点是，遍历常量池是倒序进行的：

public static Class<?> getConsumerLambdaParameterType(Consumer<?> consumer) throws ReflectiveOperationException  
{
    var consumerClass = consumer.getClass();
    var constantPool = invoke(consumerClass, "getConstantPool");
    for (var i = (int) invoke(constantPool, "getSize") - 1; i >= 0; --i)
    {
        try
        {
            var member = (Member) invoke(constantPool, "getMethodAt", i);
            if (member instanceof Method && member.getDeclaringClass() != Object.class)
            {
                return ((Method) member).getParameterTypes()[0];
            }
        }
        catch (Exception ignored)
        {
            // ignored
        }
    }
    throw new NoSuchMethodException();
}

我们可以把该方法的调用补充到之前编写的 getConsumerParameterType 方法下。这里使用的判别标准是该方法所对应的类是否是 Java 编译器自动生成的（isSynthetic 方法返回 true）：

public static Class<?> getConsumerParameterType(Consumer<?> consumer) throws ReflectiveOperationException  
{
    for (var type : consumer.getClass().getGenericInterfaces())
    {
        if (type instanceof ParameterizedType && ((ParameterizedType) type).getRawType() == Consumer.class)
        {
            return getErased(((ParameterizedType) type).getActualTypeArguments()[0]);
        }
    }
    // lambda start
    if (consumer.getClass().isSynthetic())
    {
        return getConsumerLambdaParameterType(consumer);
    }
    // lambda end
    throw new NoSuchMethodException();
}

各位可以自己试一试了：

public static void main(String[] args)  
{
    try
    {
        Consumer<Consumer<String>> consumerConsumer = c -> c.accept("");
        System.out.println(getConsumerParameterType(consumerConsumer));

        Consumer<String> stringConsumer = System.out::println;
        System.out.println(getConsumerParameterType(stringConsumer));

        Consumer<Long> longConsumer = l -> System.out.println(l + "L");
        System.out.println(getConsumerParameterType(longConsumer));
    }
    catch (ReflectiveOperationException e)
    {
        e.printStackTrace();
    }
}

鸣谢

• Forge 的事件总线的实现：https://github.com/MinecraftForge/EventBus
• Forge 实现该机制所依赖的库：https://github.com/jhalterman/typetools

Scorge 这个项目相当低调，虽然我很快就从 GitHub 上找到了 Scorge 的源代码，但我翻遍了 CurseForge 都没有找到 Scorge 这个 Mod 本身的下载链接，最后通过对 URL 的连蒙带猜从 Forge 官网上找到了下载地址（目前的最新版本是 3.0.6）：http://files.minecraftforge.net/maven/net/minecraftforge/Scorge

虽然说他们的代码仍然是基于 1.14 的，但事实上 1.15 也能用，本文将基于 Minecraft 1.15.2 和 Forge 31.2.0，使用的 Gradle 版本是 5.6.4。

构建文件

让我们先从 build.gradle 开始：

buildscript {  
    repositories {
        maven {
            url = 'https://files.minecraftforge.net/maven'
        }
        jcenter()
        mavenCentral()
    }
    dependencies {
        classpath group: 'net.minecraftforge.gradle', name: 'ForgeGradle', version: '3.+', changing: true
    }
}

apply plugin: 'scala'  
apply plugin: 'net.minecraftforge.gradle'

version = '1.0.0'  
group = 'com.github.ustc-zzzz'  
archivesBaseName = 'ScorgeExampleMod'

sourceCompatibility = targetCompatibility = '1.8'

minecraft {  
    mappings channel: 'snapshot', version: '20200514-1.15.1'
    runs {
        client {
            properties 'forge.logging.markers': 'SCAN,REGISTRIES,REGISTRYDUMP'
            properties 'forge.logging.console.level': 'debug'
            workingDirectory project.file('run')
            source sourceSets.main
        }
        server {
            properties 'forge.logging.markers': 'SCAN,REGISTRIES,REGISTRYDUMP,CLASSLOADING'
            properties 'forge.logging.console.level': 'debug,trace'
            workingDirectory project.file('run')
            source sourceSets.main
        }
    }
}

dependencies {  
    minecraft 'net.minecraftforge:forge:1.15.2-31.2.0'
    compile 'org.scala-lang:scala-library:2.13.1'
    compile 'net.minecraftforge:Scorge:3.0.6'
}

jar {  
    manifest.attributes([
        "Specification-Title"     : "scorgeexamplemod",
        "Specification-Vendor"    : "scorgeexamplemodsareus",
        "Specification-Version"   : "1", // We are version 1 of ourselves
        "Implementation-Title"    : project.name,
        "Implementation-Version"  : project.version,
        "Implementation-Vendor"   : "scorgeexamplemodsareus",
        "Implementation-Timestamp": new Date().format("yyyy-MM-dd'T'HH:mm:ssZ")
    ])
}

一方面，和基于 Java 的项目相比，基于 Scala 的项目需要 apply plugin: 'scala' 才行。

另一方面，我们需要留意 dependency 块的变化：

dependencies {  
    minecraft 'net.minecraftforge:forge:1.15.2-31.2.0'
    compile 'org.scala-lang:scala-library:2.13.1'
    compile 'net.minecraftforge:Scorge:3.0.6'
}

我们不仅要引入 Scorge 的依赖，还需要引入 Scala 标准库的依赖（请保证 Scala 标准库版本和 Scorge 所使用的版本一致，这里是 2.13.1）。

主类

然后我们随便写一个主类：

package com.github.ustc_zzzz

import net.minecraftforge.fml.event.lifecycle.FMLCommonSetupEvent  
import net.minecraftforge.scorge.lang.ScorgeModLoadingContext  
import org.apache.logging.log4j.LogManager

class ScorgeExampleMod {  
  ScorgeModLoadingContext.get.getModEventBus.addListener { _: FMLCommonSetupEvent =>
    LogManager.getLogger(classOf[ScorgeExampleMod]).info("Hello Scorge Example Mod!")
  }
}

这里有三点需要注意：

• 我们不需要为主类添加 @Mod 注解。
• 和 1.12 或更低版本不同，Scorge 要求主类是 class 而不是 object。
• 需要使用 ScorgeModLoadingContext 而非 FMLJavaModLoadingContext 获取事件总线。

得益于 Scala 编译器从 2.12 开始能够将相关代码编译到 Lambda 表达式，我们可以直接使用 Lambda 表达式块的格式向事件总线注册监听器（1.12 或更低不行，因为使用的是 Scala 2.11）。

因为主类没有 @Mod 注解，所以如果想要在游戏启动的时候看到这句话，我们还需要修改 META_INF 目录下的 mods.toml。

Mod 描述文件

只有我们在 mods.toml 中指定了主类名，我们才能让 Scorge 加载我们的 Mod 主类：

modLoader="scorge"  
loaderVersion="[3,)"

[[mods]]
version="1.0.0"  
authors="ustc-zzzz"  
modId="scorgeexamplemod"  
displayName="Scorge Example Mod"  
description="Scorge Example Mod"  
entryClass="com.github.ustc_zzzz.ScorgeExampleMod"

[[dependencies.watersprayer]]
modId="forge"  
mandatory=true  
versionRange="[31,)"  
ordering="NONE"  
side="BOTH"

[[dependencies.watersprayer]]
modId="minecraft"  
mandatory=true  
versionRange="[1.15.2]"  
ordering="NONE"  
side="BOTH"  

注意以下两点：

• modLoader 应取为 scorge，而 loaderVersion 应使用 Scorge 版本。
• 和基于 Java 的 Mod 相比，我们还需要额外指定一个 entryClass 描述主类的位置。

现在打开游戏就可以看到这句话了（别忘了把 Scorge 本体放进 mods 目录）：

和现实世界不同，在游戏中实现传统意义上的导线，要比无线充电等其他实现方式困难得多。因此读者如果实在无法完整实现传统意义上的导线，那也可以退而求其次，去实现其他的能量传输形式。导线之外的能量传输形式往往也是会受到玩家欢迎的。

导线连通网络

一个最朴素的想法是让每根导线每 tick 都将附近导线的能量传输过来。实际上一些 Mod（比方说 RailCraft 等）也正是这么做的。

但这样做无疑从游戏体验上就存在一个问题：如果是一根长长的导线，那么每 tick 能量自然只能传输一格，如果导线长达几百根，那毫无疑问需要数秒甚至十多秒的时间才能将能量从一头传到另一头。如果考虑到游戏性能的话，问题更大了：所有的导线都需要每 tick 更新一次，那势必导致世界上每 tick 都更新的方块实体数量大大增加。

所以，一个非常重要的原则就是：不要为代表导线的方块实体实现 ITickableTileEntity 接口。那我们应当什么时候执行导线相关的逻辑呢？

部分 Mod 会为导线指定一个中心方块（比如说 AppliedEnergistics2 的 ME 控制器），这不失为一个好的选择：我们只需要为中心方块实现 ITickableTileEntity，并由它接管所有能量相关的逻辑即可。但是，我们需要实现的是传统意义上的导线，换言之，我们要实现的能量传输系统没有中心方块，对每一根导线而言，它们都是相互平等的。

为了解决这一问题。我们必须为每个世界单独提供一个管理能量传输的导线连通网络，并且自动接管导线的通断相关逻辑。为了方便进一步的操作，我们可以从每一组互相连通的导线（又称一个连通域）中挑选一个代表方块，然后使用该方块代表整组导线。当然，导线的通断会导致一组导线分裂成两组，或是两组导线合并成一组，这些都是我们需要考虑的。

我们现在将接口声明如下：

public interface IBlockNetwork  
{
    int size(BlockPos node);

    BlockPos root(BlockPos node);

    void cut(BlockPos node, Direction direction, ConnectivityListener afterSplit);

    void link(BlockPos node, Direction direction, ConnectivityListener beforeMerge);

    @FunctionalInterface
    interface ConnectivityListener
    {
        void onChange(BlockPos primaryNode, BlockPos secondaryNode);
    }
}

• size 返回的是导线所处连通域含有的导线数量，如果导线没有和其他导线连通，那么返回值为 1。
• root 返回的是导线所处连通域的代表导线，也有可能是该导线自身（比方说未和其他导线连通的时候）。
• cut 指将某根导线的某个方向切断。切断导线如果会导致一个连通域分裂成两个，那么会在分裂后调用 afterSplit 的相关方法。
• link 指将某根导线在某个方向上实施连接。连接导线如果会导致两个连通域合并为一个，那么会在合并前调用 beforeMerge 的相关方法。
• onChange 方法将在连通域发生变化时调用，其中第一个参数是主连通域（其代表导线不会发生变化），而第二个参数是次连通域（会由于合并而消失，或由于分裂而新出现）。

如何实现这个接口呢？本讲将提供相对简单直观的实现，该实现可以达到 O(N) 的时间复杂度。高效的实现可以做到多项式对数级（O(polylog N)）的时间复杂度，但过于复杂：感兴趣的读者可以通过阅读 Wikipedia（英文页面）加以了解。

实现的思路很简单：除了维护所有连接外，我们只需要对每个方块维护一个连通域的相关集合就好了，而集合的第一个元素自然便是连通域的代表方块：

public class SimpleBlockNetwork implements IBlockNetwork  
{
    private final Map<BlockPos, Set<BlockPos>> components;
    private final SetMultimap<BlockPos, Direction> connections;

    public SimpleBlockNetwork()
    {
        this.components = Maps.newHashMap();
        this.connections = Multimaps.newSetMultimap(Maps.newHashMap(), () -> EnumSet.noneOf(Direction.class));
    }

    @Override
    public int size(BlockPos node)
    {
        return 1; // TODO
    }

    @Override
    public BlockPos root(BlockPos node)
    {
        return node; // TODO
    }

    @Override
    public void cut(BlockPos node, Direction direction, ConnectivityListener afterSplit)
    {
        // TODO
    }

    @Override
    public void link(BlockPos node, Direction direction, ConnectivityListener beforeMerge)
    {
        // TODO
    }
}

上面的代码中，components 自然是方块到连通域（Set<BlockPos>）的映射，而 connections 中存储着所有连接。

我们先从 size 和 root 方法的实现开始：

@Override
public int size(BlockPos node)  
{
    return this.components.containsKey(node) ? this.components.get(node).size() : 1;
}

@Override
public BlockPos root(BlockPos node)  
{
    return this.components.containsKey(node) ? this.components.get(node).iterator().next() : node.toImmutable();
}

两个实现都十分直观，且都考虑到了有连通域和无连通域的情况。唯一需要注意的是我们需要 toImmutable 方法把 BlockPos 转为不可变的，这样后续我们才能将相应 BlockPos 直接存入 Set 或 Map 中。

接下来我们实现 cut 和 link 两个方法。

导线连通域的合并

我们再来实现 link 方法：

@Override
public void link(BlockPos node, Direction direction, ConnectivityListener beforeMerge)  
{
    BlockPos secondary = node.toImmutable();
    if (this.connections.put(secondary, direction))
    {
        BlockPos primary = node.offset(direction);
        this.connections.put(primary, direction.getOpposite());
        Set<BlockPos> primaryComponent = this.components.get(primary);
        Set<BlockPos> secondaryComponent = this.components.get(secondary);
        if (primaryComponent == null && secondaryComponent == null)
        {
            Set<BlockPos> union = Sets.newLinkedHashSet();
            beforeMerge.onChange(secondary, primary);
            this.components.put(secondary, union);
            this.components.put(primary, union);
            union.add(secondary);
            union.add(primary);
        }
        else if (primaryComponent == null)
        {
            beforeMerge.onChange(secondaryComponent.iterator().next(), primary);
            this.components.put(primary, secondaryComponent);
            secondaryComponent.add(primary);
        }
        else if (secondaryComponent == null)
        {
            beforeMerge.onChange(primaryComponent.iterator().next(), secondary);
            this.components.put(secondary, primaryComponent);
            primaryComponent.add(secondary);
        }
        else if (primaryComponent != secondaryComponent)
        {
            beforeMerge.onChange(primaryComponent.iterator().next(), secondaryComponent.iterator().next());
            Set<BlockPos> union = Sets.newLinkedHashSet(Sets.union(primaryComponent, secondaryComponent));
            union.forEach(pos -> this.components.put(pos, union));
        }
    }
}

我们一段一段地来分析：

BlockPos secondary = node.toImmutable();  
if (this.connections.put(secondary, direction))  

这一段是将 BlockPos 和对应 Direction 添加到 connections 中，如果在这之前 connections 中并不存在该连接，那么 put 方法将返回 true，如果不存在，那么自然就没有进行下一步的意义了。

BlockPos primary = node.offset(direction);  
this.connections.put(primary, direction.getOpposite());  

如果连接不存在的话，那么我们还需要找到连接到的 BlockPos，为其相反方向添加连接。

Set<BlockPos> primaryComponent = this.components.get(primary);  
Set<BlockPos> secondaryComponent = this.components.get(secondary);  

我们试图获取两个 BlockPos 所处的连通域，至此我们需要分三种情况：

1. 两个连通域都不存在，那我们需要新创建一个连通域，然后把两个 BlockPos 加上去。
2. 一个连通域存在，另一个不存在，那我们需要把对应的 BlockPos 加到相应的连通域中。
3. 两个连通域都存在，那如果它们不相同，我们需要把两个连通域相互合并，然后应用到所有相关节点上去。

if (primaryComponent == null && secondaryComponent == null)  
{
    Set<BlockPos> union = Sets.newLinkedHashSet();
    beforeMerge.onChange(secondary, primary);
    this.components.put(secondary, union);
    this.components.put(primary, union);
    union.add(secondary);
    union.add(primary);
}

这对应两个连通域都不存在的情况：创建一个新连通域（union），然后把两个 BlockPos 加上去。别忘了调用 beforeMerge 的相关方法。

else if (primaryComponent == null)  
{
    beforeMerge.onChange(secondaryComponent.iterator().next(), primary);
    this.components.put(primary, secondaryComponent);
    secondaryComponent.add(primary);
}

这对应第一个连通域不存在而第二个存在的情况，我们需要把第一个 BlockPos 加上去。

else if (secondaryComponent == null)  
{
    beforeMerge.onChange(primaryComponent.iterator().next(), secondary);
    this.components.put(secondary, primaryComponent);
    primaryComponent.add(secondary);
}

这对应第一个连通域存在而第二个不存在的情况，我们需要把第二个 BlockPos 加上去。

else if (primaryComponent != secondaryComponent)  
{
    beforeMerge.onChange(primaryComponent.iterator().next(), secondaryComponent.iterator().next());
    Set<BlockPos> union = Sets.newLinkedHashSet(Sets.union(primaryComponent, secondaryComponent));
    union.forEach(pos -> this.components.put(pos, union));
}

这对应两个连通域都存在且不相同的情况，我们需要创建一个连通域把两个连通域合并到一起，然后应用到两个连通域中的所有节点上。

最后我们注意到，只有两种情况下我们不会调用 beforeMerge 的 onChange 方法：

• 试图添加的连接已存在。
• 添加了连接同一个连通域的连接。

导线连通域的分裂

最后我们实现 cut 方法。cut 方法是整个接口中最难实现的一个，因此在动手写代码时，我们首先需要了解相关原理。

我们知道删除某个连接有可能将一个连通域分裂成两半，也有可能不会为一个连通域带来变化。为了检查这两件事，我们需要从被删除的连接所对应的两个 BlockPos 开始，分别进行广度优先搜索，并在以下两个条件中的任何一个达成时同时终止搜索：

• 当一方搜索到的某个节点已经在另一方搜索到的节点列表中，则代表连通域并未分裂。
• 当一方已经遍历了所有能够遍历的节点，则代表连通域已被分裂为两半，搜索完成的一方代表其中的一半。

为此，我们需要首先实现一个基于广度优先搜索的 Iterator：

public class BFSIterator implements Iterator<BlockPos>  
{
    private final Set<BlockPos> searched = Sets.newLinkedHashSet();
    private final Queue<BlockPos> queue = Queues.newArrayDeque();

    public BFSIterator(BlockPos node)
    {
        node = node.toImmutable();
        this.searched.add(node);
        this.queue.offer(node);
    }

    @Override
    public boolean hasNext()
    {
        return this.queue.size() > 0;
    }

    @Override
    public BlockPos next()
    {
        BlockPos node = this.queue.remove();
        for (Direction direction : SimpleBlockNetwork.this.connections.get(node))
        {
            BlockPos another = node.offset(direction);
            if (this.searched.add(another))
            {
                this.queue.offer(another);
            }
        }
        return node;
    }

    public Set<BlockPos> getSearched()
    {
        return this.searched;
    }
}

广度优先搜索的实现很简单，上面的代码也很清晰，这里就不展开讲解了。

接下来我们使用 BFSIterator 实现 cut 方法：

@Override
public void cut(BlockPos node, Direction direction, ConnectivityListener afterSplit)  
{
    if (this.connections.remove(node, direction))
    {
        BlockPos another = node.offset(direction);
        this.connections.remove(another, direction.getOpposite());
        BFSIterator nodeIterator = new BFSIterator(node), anotherIterator = new BFSIterator(another);
        while (nodeIterator.hasNext())
        {
            BlockPos next = nodeIterator.next();
            if (!anotherIterator.getSearched().contains(next))
            {
                BFSIterator iterator = anotherIterator;
                anotherIterator = nodeIterator;
                nodeIterator = iterator;
                continue;
            }
            return;
        }
        Set<BlockPos> primaryComponent = this.components.get(node), secondaryComponent;
        BlockPos primaryNode = primaryComponent.iterator().next();
        Set<BlockPos> searched = nodeIterator.getSearched();
        if (searched.contains(primaryNode))
        {
            secondaryComponent = Sets.newLinkedHashSet(Sets.difference(primaryComponent, searched));
            primaryComponent.retainAll(searched);
        }
        else
        {
            secondaryComponent = searched;
            primaryComponent.removeAll(searched);
        }
        if (secondaryComponent.size() <= 1)
        {
            secondaryComponent.forEach(this.components::remove);
        }
        else
        {
            secondaryComponent.forEach(pos -> this.components.put(pos, secondaryComponent));
        }
        if (primaryComponent.size() <= 1)
        {
            primaryComponent.forEach(this.components::remove);
        }
        afterSplit.onChange(primaryNode, secondaryComponent.iterator().next());
    }
}

我们在这里还是一段一段地讲解：

if (this.connections.remove(node, direction))  

这里将移除对应边，如果对应边在移除前存在，那么该方法返回 true。

BlockPos another = node.offset(direction);  
this.connections.remove(another, direction.getOpposite());  

如果连接存在的话，那么我们还需要找到连接到的 BlockPos，为其相反方向删除连接。

BFSIterator nodeIterator = new BFSIterator(node), anotherIterator = new BFSIterator(another);  
while (nodeIterator.hasNext())  
{
    BlockPos next = nodeIterator.next();
    if (!anotherIterator.getSearched().contains(next))
    {
        BFSIterator iterator = anotherIterator;
        anotherIterator = nodeIterator;
        nodeIterator = iterator;
        continue;
    }
    return;
}

然后我们为两边的 BlockPos 分别创立 BFSIterator，轮流实施迭代过程。

• 若当前 BFSIterator 已遍历完所有能够遍历得到的 BlockPos（hasNext 为 false）则循环结束。
• 否则，如果另一个 BFSIterator 包含当前节点，那说明它们仍然在同一个连通域，直接 return。
• 最后，如果另一个 BFSIterator 不包含当前节点，那么把两个节点相交换，继续循环过程。

Set<BlockPos> primaryComponent = this.components.get(node), secondaryComponent;  
BlockPos primaryNode = primaryComponent.iterator().next();  
Set<BlockPos> searched = nodeIterator.getSearched();  
if (searched.contains(primaryNode))  
{
    secondaryComponent = Sets.newLinkedHashSet(Sets.difference(primaryComponent, searched));
    primaryComponent.retainAll(searched);
}
else  
{
    secondaryComponent = searched;
    primaryComponent.removeAll(searched);
}

如果我们证实我们的连通域会分裂成两半，并且已经搜索到了其中一半（searched），那么接下来我们需要定主连通域和次连通域。主连通域自然是当前节点所在连通域，但我们刚刚遍历收集到的，到底是不是主连通域呢？我们需要 searched.contains(primaryNode) 这一表达式加以判断：

• 如果是（返回 true），那么我们需要构造一个未遍历到的 BlockPos 集合作为次连通域，然后我们在主连通域中只保留归属于 searched 的 BlockPos（retainAll 方法）。
• 如果不是（返回 false），那么我们可以直接将 searched 作为次连通域，然后把主连通域中已经从属于 searched 的 BlockPos 全去掉（removeAll 方法）。

if (secondaryComponent.size() <= 1)  
{
    secondaryComponent.forEach(this.components::remove);
}
else  
{
    secondaryComponent.forEach(pos -> this.components.put(pos, secondaryComponent));
}
if (primaryComponent.size() <= 1)  
{
    primaryComponent.forEach(this.components::remove);
}
afterSplit.onChange(primaryNode, secondaryComponent.iterator().next());  

接下来就要把这两个集合应用到每一个从属于它们的 BlockPos 了。注意如果该连通域中只有一个 BlockPos，那么可以直接将其从 components 中删除。

最后我们调用了 afterSplit 的 onChange 方法。

导线能量网络

我们现在可以基于连通网络实现能量网络了。除了连通网络外，我们还需要存储什么呢？

• 每个连通域都会存储一定能量用于能量传输，因此我们需要为每个连通域存储这个。
• 导线并不一定只连着导线，还可能连着机器，因此我们需要把所有和机器有关的连接单独储存。
• 导线的连接和切断和能量存取会导致数据变化，因此我们需要记录所有变化的区块，从而保证它们能够保存进存档中。

关于能量存储这里补充一点：我们只需要为每个连通域的代表方块存储能量值，而由于能量值一定是非负整数，因此这里使用 Multiset 将十分适合。

public class SimpleEnergyNetwork  
{
    private final IWorld world;
    private final IBlockNetwork blockNetwork;
    private final Queue<Runnable> taskCollection;
    private final Multiset<BlockPos> energyCollection;
    private final SetMultimap<ChunkPos, BlockPos> chunkCollection;
    private final SetMultimap<BlockPos, Direction> machineCollection;

    private SimpleEnergyNetwork(IWorld world, IBlockNetwork blockNetwork)
    {
        this.world = world;
        this.blockNetwork = blockNetwork;
        this.taskCollection = Queues.newArrayDeque();
        this.energyCollection = HashMultiset.create();
        this.chunkCollection = Multimaps.newSetMultimap(Maps.newHashMap(), Sets::newHashSet);
        this.machineCollection = Multimaps.newSetMultimap(Maps.newHashMap(), () -> EnumSet.noneOf(Direction.class));
    }
}

除了上面提到的这些和 world 外，我们还额外添加了一个 taskCollection 字段，稍后我们监听 tick 事件时用得着。

我们还需要考虑一个问题：刚刚我们提到过，我们的能量网络是相对于某个世界的，因此对于某个特定的世界而言，导线的能量数据是全局存储的，但我们应如何把数据放到存档里呢？以连通域为单位存储在这里显然不适合，因为连通域会合并和分裂，从而使得维护存档中导线和连通域之间的关系成为非常困难的工作（在内存中这很容易）。一个很不错的解决方案是：我们可以把能量放到导线里均摊储存，这样不管连通域如何合并和分裂，最终都将落实到每根导线和存档的交互上。为了实现这一解决方案，我们需要声明四个方法：

• getNetworkSize：获取导线所处连通域的导线数量。
• getNetworkEnergy：获取导线所处连通域的整体能量。
• getSharedEnergy：获取导线所处连通域均摊到当前导线的能量。
• addEnergy：调整导线所处连通域的能量（正数为增加，负数为减少）。

这四个方法的实现都非常简单。Guava 的 Multiset 和 Multimap 在实现上为我们带来了极大的方便：

public int getNetworkSize(BlockPos pos)  
{
    return this.blockNetwork.size(pos);
}

public int getNetworkEnergy(BlockPos pos)  
{
    BlockPos root = this.blockNetwork.root(pos);
    return this.energyCollection.count(root);
}

public int getSharedEnergy(BlockPos pos)  
{
    int size = this.blockNetwork.size(pos);
    BlockPos root = this.blockNetwork.root(pos);
    int total = this.energyCollection.count(root);
    return root.equals(pos) ? total / size + total % size : total / size;
}

public void addEnergy(BlockPos pos, int diff)  
{
    if (diff >= 0)
    {
        this.energyCollection.add(this.blockNetwork.root(pos), diff);
    }
    else
    {
        this.energyCollection.remove(this.blockNetwork.root(pos), -diff);
    }
}

这里唯一需要指出的是能量的分摊方式，也就是在整体能量除以连通域导线数量除不开的时候，问题是如何解决的：

• 如果当前导线是连通域的代表导线，那么把余数都分摊到该导线上。
• 如果当前导线不是连通域的代表导线，那么照常除就可以了，不必考虑余数。

在 tick 事件中增删导线

我们现在声明用于删除导线的 disableBlock 方法，和用于添加导线的 enableBlock 方法。但是，这两个方法的实现并没有那么直接，因为我们需要把相关行为托管到 tick 事件中执行。

为什么我们不能立刻增删导线？这是因为在增删导线的时候，我们需要检查导线和周围方块的连通性，而很多时候导线是在世界加载阶段加载的，因此如果在世界加载时获取周围方块的相关信息，将会极易导致死锁。因此我们需要把增删导线的相关逻辑放到 tick 事件中，这正是 taskCollection 字段的存在意义。

public void disableBlock(BlockPos pos, Runnable callback)  
{
    this.taskCollection.offer(() ->
    {
        // TODO
        callback.run();
    });
}

public void enableBlock(BlockPos pos, Runnable callback)  
{
    this.taskCollection.offer(() ->
    {
        // TODO
        callback.run();
    });
}

private void tickStart()  
{
    for (Runnable runnable = this.taskCollection.poll(); runnable != null; runnable = this.taskCollection.poll())
    {
        runnable.run();
    }
}

我们为 disableBlock 和 enableBlock 两个方法添加了 Runnable 作为回调函数，并在 tickStart 方法调用时调用。我们稍后便会在 tick 事件的监听器里调用 tickStart 方法。

向能量网络增删导线

我们先来实现删除导线：

public void disableBlock(BlockPos pos, Runnable callback)  
{
    this.taskCollection.offer(() ->
    {
        this.chunkCollection.remove(new ChunkPos(pos), pos);
        for (Direction side : Direction.values())
        {
            this.blockNetwork.cut(pos, side, this::afterSplit);
        }
        this.machineCollection.removeAll(pos);
        callback.run();
    });
}

private void afterSplit(BlockPos primaryNode, BlockPos secondaryNode)  
{
    int primarySize = this.blockNetwork.size(primaryNode), secondarySize = this.blockNetwork.size(secondaryNode);
    int diff = this.energyCollection.count(primaryNode) * secondarySize / (primarySize + secondarySize);
    this.energyCollection.remove(primaryNode, diff);
    this.energyCollection.add(secondaryNode, diff);
}

除了调用回调函数外，删除导线主要做三件事：

• 记录导线所归属的区块。
• 切断导线在六个方向的所有连接。
• 切断导线在所有方向上和机器的连接。

切断导线连接时需要传入 ConnectivityListener，这里声明并实现了 afterSplit 方法，并传入方法引用作为实现。afterSplit 方法所做的事很简单：把当前连通域的整体能量按所拥有的导线数量分离一部分出来给一个新的连通域。

然后我们再来实现添加导线：

public void enableBlock(BlockPos pos, Runnable callback)  
{
    this.taskCollection.offer(() ->
    {
        this.chunkCollection.put(new ChunkPos(pos), pos.toImmutable());
        for (Direction side : Direction.values())
        {
            if (this.hasWireConnection(pos, side))
            {
                if (this.hasWireConnection(pos.offset(side), side.getOpposite()))
                {
                    this.machineCollection.remove(pos, side);
                    this.blockNetwork.link(pos, side, this::beforeMerge);
                }
                else
                {
                    this.machineCollection.put(pos.toImmutable(), side);
                    this.blockNetwork.cut(pos, side, this::afterSplit);
                }
            }
            else
            {
                this.machineCollection.remove(pos, side);
                this.blockNetwork.cut(pos, side, this::afterSplit);
            }
        }
        callback.run();
    });
}

private boolean hasWireConnection(BlockPos pos, Direction side)  
{
    return false; // TODO
}

private void beforeMerge(BlockPos primaryNode, BlockPos secondaryNode)  
{
    int diff = this.energyCollection.count(secondaryNode);
    this.energyCollection.remove(secondaryNode, diff);
    this.energyCollection.add(primaryNode, diff);
}

除了调用回调函数外，添加导线主要做的也是三件事：

• 记录导线所归属的区块。
• 添加导线和其他导线之间的连接。
• 添加导线和机器的连接。

和删除导线相比，添加导线还需要检查周围方块是否能够与其相互连接，因此实现会稍加复杂：

• 如果导线在某个方向上不和相邻方块连接，那自然既不考虑连通网络，也不考虑机器了。
• 如果导线在某个方向上和相邻方块连接，且连接的方块是在相反方向上连接的导线，那么将该导线添加到连通网络。
• 如果导线在某个方向上和相邻方块连接，且连接的方块不是在相反方向上连接的导线，那么将该导线连接的方块视为机器。

我们现在实现 hasWireConnection 方法：

@SuppressWarnings("deprecation")
private boolean hasWireConnection(BlockPos pos, Direction side)  
{
    if (this.world.isBlockLoaded(pos))
    {
        BlockState state = this.world.getBlockState(pos);
        return state.getBlock().equals(FEDemoWireBlock.BLOCK) && state.get(FEDemoWireBlock.PROPERTY_MAP.get(side));
    }
    return false;
}

这里需要额外注意 isBlockLoaded 方法的调用。如果我们不事先进行 isBlockLoaded 这一检查，那么 getBlockState 方法在检查未加载的方块坐标时，将会自动将该方块坐标所处的区块予以加载，而加载会导致连接状态的变化，因此如果世界上有一长链导线，这会导致途径的所有区块全部加载，这显然是没有必要的。更为重要的是，游戏会在加载区块后试图卸载不必要的区块，而卸载区块同样会导致连接状态的变化，这一变化又会反过来加载区块，因此区块会不断地在加载和卸载之间循环，这显然会带来不必要的性能损失。稍后我们会在其他方法再次调用 isBlockLoaded 方法进行方块是否已加载的检查。

增删导线的逻辑到这里就彻底写完了。接下来我们要写另一处需要在 tick 事件中执行的逻辑。

在 tick 事件中输送能量

在编写发电机的时候我们曾经提到，能量的流动应由发电机控制，而发电机实现了 ITickableTileEntity 接口，因此可以在实现该接口的 tick 方法时输送能量。刚刚我们提到，导线能量网络是以世界为单位的，因此我们同样需要监听世界的 tick 事件完成这件事。我们把这一行为写进 tickEnd 方法：

@SuppressWarnings("deprecation")
private void tickEnd()  
{
    for (Map.Entry<BlockPos, Direction> entry : this.shuffled(this.machineCollection.entries()))
    {
        Direction direction = entry.getValue();
        BlockPos node = entry.getKey(), root = this.blockNetwork.root(node);
        if (this.world.isBlockLoaded(node.offset(direction)))
        {
            TileEntity tileEntity = this.world.getTileEntity(node.offset(direction));
            if (tileEntity != null)
            {
                tileEntity.getCapability(CapabilityEnergy.ENERGY, direction.getOpposite()).ifPresent(e ->
                {
                    if (e.canReceive())
                    {
                        int diff = this.energyCollection.count(root);
                        this.energyCollection.remove(root, e.receiveEnergy(diff, false));
                    }
                });
            }
        }
    }
}

private <T> List<T> shuffled(Iterable<? extends T> iterable)  
{
    List<T> list = Lists.newArrayList(iterable);
    Random rand = this.world.getRandom();
    Collections.shuffle(list, rand);
    return list;
}

该方法的实现很简单：遍历所有的机器（在遍历前打乱了一遍次序），然后如果机器可以接收能量，那么便向其输送能量。注意 isBlockLoaded 方法的调用，因为我们并不希望向未加载的区块中的方块实体输送能量。

标记需要保存的区块

我们需要在保存存档的时候标记所有需要保存的区块。我们声明一个 markDirty 方法，并在该方法内部实现相应的逻辑：

@SuppressWarnings("deprecation")
private void markDirty()  
{
    for (ChunkPos chunkPos : this.chunkCollection.keys())
    {
        BlockPos pos = chunkPos.asBlockPos();
        if (this.world.isBlockLoaded(pos))
        {
            this.world.getChunk(pos).setModified(true);
        }
    }
}

稍后我们会监听保存世界存档的事件，然后调用这一方法。

导线能量网络的管理

我们需要一个全局化的管理类，我们决定让它成为 SimpleEnergyNetwork 的嵌套类：

@Mod.EventBusSubscriber(bus = Mod.EventBusSubscriber.Bus.FORGE)
public static class Factory  
{
    private static final Map<IWorld, SimpleEnergyNetwork> INSTANCES = Maps.newIdentityHashMap();

    public static SimpleEnergyNetwork get(IWorld world)
    {
        return INSTANCES.computeIfAbsent(world, k -> new SimpleEnergyNetwork(k, new SimpleBlockNetwork()));
    }

    @SubscribeEvent
    public static void onSave(WorldEvent.Save event)
    {
        if (INSTANCES.containsKey(event.getWorld()))
        {
            INSTANCES.get(event.getWorld()).markDirty();
        }
    }

    @SubscribeEvent
    public static void onUnload(WorldEvent.Unload event)
    {
        INSTANCES.remove(event.getWorld());
    }

    @SubscribeEvent
    public static void onWorldTick(TickEvent.WorldTickEvent event)
    {
        if (LogicalSide.SERVER.equals(event.side))
        {
            switch (event.phase)
            {
                case START:
                {
                    Factory.get(event.world).tickStart();
                    break;
                }
                case END:
                {
                    Factory.get(event.world).tickEnd();
                    break;
                }
            }
        }
    }
}

该类提供了构造并返回 SimpleEnergyNetwork 方法，并且有三个事件监听器：

• 在世界开始保存存档时调用 markDirty 方法。
• 在世界准备卸载时移除已经持有的 SimpleEnergyNetwork 实例。
• 在世界的 tick 事件触发时调用 tickStart 和 tickEnd 方法。

到这里，整个 SimpleEnergyNetwork，就完全实现完了，我们稍后会在导线的方块实体类里调用里面的相关方法。

为导线实现 Capability

我们现在为代表导线的方块实体添加 Capability：

private final LazyOptional<IEnergyStorage> lazyOptional = LazyOptional.of(() -> new IEnergyStorage()  
{
    private final SimpleEnergyNetwork network = SimpleEnergyNetwork.Factory.get(FEDemoWireTileEntity.this.world);

    @Override
    public int receiveEnergy(int maxReceive, boolean simulate)
    {
        int energy = this.getEnergyStored();
        int diff = Math.min(500, Math.min(this.getMaxEnergyStored() - energy, maxReceive));
        if (!simulate)
        {
            this.network.addEnergy(FEDemoWireTileEntity.this.pos, diff);
            if (diff != 0)
            {
                FEDemoWireTileEntity.this.markDirty();
            }
        }
        return diff;
    }

    @Override
    public int extractEnergy(int maxExtract, boolean simulate)
    {
        int energy = this.getEnergyStored();
        int diff = Math.min(500, Math.min(energy, maxExtract));
        if (!simulate)
        {
            this.network.addEnergy(FEDemoWireTileEntity.this.pos, -diff);
            if (diff != 0)
            {
                FEDemoWireTileEntity.this.markDirty();
            }
        }
        return diff;
    }

    @Override
    public int getEnergyStored()
    {
        return Math.min(this.getMaxEnergyStored(), this.network.getNetworkEnergy(FEDemoWireTileEntity.this.pos));
    }

    @Override
    public int getMaxEnergyStored()
    {
        return 1_000 * this.network.getNetworkSize(FEDemoWireTileEntity.this.pos);
    }

    @Override
    public boolean canExtract()
    {
        return true;
    }

    @Override
    public boolean canReceive()
    {
        return true;
    }
});

@Nonnull
@Override
public <T> LazyOptional<T> getCapability(@Nonnull Capability<T> cap, Direction side)  
{
    boolean isEnergy = Objects.equals(cap, CapabilityEnergy.ENERGY);
    return isEnergy ? this.lazyOptional.cast() : super.getCapability(cap, side);
}

由于导线既可以输入能量，也可以输出能量，因此 canExtract 和 canReceive 都应返回 true，剩下的实现和之前的发电机和用电器都大同小异，这里就不展开了。

导线本身的加载与卸载

Minecraft 原版和 Forge 共为 TileEntity 提供了三个方法用于描述方块实体的加载和卸载过程：

• onLoad 方法将在方块实体加载时（包括手动放置对应方块和以及区块加载）触发。
• onChunkUnloaded 方法将在方块实体所在区块被卸载时触发。
• remove 方法将在方块实体被拆除时触发。

我们还需要覆盖读取 NBT 里会调用的 read 方法和写入 NBT 时会调用的 write 方法。我们先实现这两个方法：

private Integer tmpEnergy = null;

@Override
public void read(@Nonnull CompoundNBT compound)  
{
    this.tmpEnergy = compound.getInt("WireEnergy");
    super.read(compound);
}

@Nonnull
@Override
public CompoundNBT write(@Nonnull CompoundNBT compound)  
{
    SimpleEnergyNetwork network = SimpleEnergyNetwork.Factory.get(this.world);
    compound.putInt("WireEnergy", network.getSharedEnergy(this.pos));
    return super.write(compound);
}

我们可以注意到一件事：write 方法是直接从导线能量网络里获取均摊能量，而 read 方法却写入到了一个临时值，为什么要这样做？这是因为，read 方法第一次调用的时机特别特别早，甚至方块实体还没有被加载到世界中，因此我们甚至连方块实体所处的世界都无法获取得到，更逞论获取导线能量网络中的均摊能量了。因此，我们只能先写入一个临时值，然后在 onLoad 方法里读取这个临时值：

@Override
public void onLoad()  
{
    if (this.world != null && !this.world.isRemote)
    {
        SimpleEnergyNetwork network = SimpleEnergyNetwork.Factory.get(this.world);
        if (this.tmpEnergy != null)
        {
            int diff = this.tmpEnergy - network.getSharedEnergy(this.pos);
            network.addEnergy(this.pos, diff);
            this.tmpEnergy = null;
        }
        network.enableBlock(this.pos, this::markDirty);
    }
    super.onLoad();
}

注意该方法设置能量的方式：通过添加差额能量的方式设置。

最后我们还剩下 onChunkUnloaded 和 remove 两个方法。我们现在实现这两个方法：

@Override
public void onChunkUnloaded()  
{
    if (this.world != null && !this.world.isRemote)
    {
        SimpleEnergyNetwork network = SimpleEnergyNetwork.Factory.get(this.world);
        network.disableBlock(this.pos, this::markDirty);
    }
    super.onChunkUnloaded();
}

@Override
public void remove()  
{
    if (this.world != null && !this.world.isRemote)
    {
        SimpleEnergyNetwork network = SimpleEnergyNetwork.Factory.get(this.world);
        network.disableBlock(this.pos, () ->
        {
            int diff = network.getSharedEnergy(this.pos);
            network.addEnergy(this.pos, -diff);
            this.markDirty();
        });
    }
    super.remove();
}

和 onChunkUnloaded 相比，remove 方法额外多做了一件事：把导线连通网络里当前位置的能量清零。这可以避免在该位置重新添加导线时附带残留能量。

到这里，整个导线的方块实体相关代码，就全部实现完了。但我们还有一件事没处理：如果导线附近的方块发生变化了怎么办？

导线附近方块的变化

如果导线附近添加了新的机器，那么我们应当将这件事通知能量网络。这可以通过覆盖 Block 类的 neighborChanged 方法来实现。

我们在方块类（FEDemoWireBlock）写下以下代码：

@Override
@SuppressWarnings("deprecation")
public void neighborChanged(@Nonnull BlockState state, @Nonnull World world, @Nonnull BlockPos pos, @Nonnull Block fromBlock, @Nonnull BlockPos fromPos, boolean isMoving)  
{
    if (!world.isRemote)
    {
        TileEntity tileEntity = world.getTileEntity(pos);
        if (tileEntity instanceof FEDemoWireTileEntity)
        {
            SimpleEnergyNetwork.Factory.get(world).enableBlock(pos, tileEntity::markDirty);
        }
    }
}

很好，关于导线的一切我们都已经写完了。

代码清单

这一部分添加的文件有：

• src/main/java/com/github/ustc_zzzz/fedemo/util/IBlockNetwork.java
• src/main/java/com/github/ustc_zzzz/fedemo/util/SimpleBlockNetwork.java
• src/main/java/com/github/ustc_zzzz/fedemo/util/SimpleEnergyNetwork.java

这一部分修改的文件有：

• src/main/java/com/github/ustc_zzzz/fedemo/block/FEDemoWireBlock.java
• src/main/java/com/github/ustc_zzzz/fedemo/tileentity/FEDemoWireTileEntity.java

这一讲我们将从作为方块的导线着手（换言之只是一个空壳子），而下一讲我们将着重介绍作为能量传输载体的导线。

添加方块和方块实体

以下是方块类的基础实现：

@Mod.EventBusSubscriber(bus = Mod.EventBusSubscriber.Bus.MOD)
public class FEDemoWireBlock extends Block  
{
    public static final String NAME = "fedemo:wire";

    @ObjectHolder(NAME)
    public static FEDemoWireBlock BLOCK;

    @SubscribeEvent
    public static void onRegisterBlock(@Nonnull RegistryEvent.Register<Block> event)
    {
        FEDemo.LOGGER.info("Registering wire block ...");
        event.getRegistry().register(new FEDemoWireBlock().setRegistryName(NAME));
    }

    @SubscribeEvent
    public static void onRegisterItem(@Nonnull RegistryEvent.Register<Item> event)
    {
        FEDemo.LOGGER.info("Registering wire item ...");
        event.getRegistry().register(new BlockItem(BLOCK, new Item.Properties().group(ItemGroup.MISC)).setRegistryName(NAME));
    }

    private FEDemoWireBlock()
    {
        super(Block.Properties.create(Material.GLASS).hardnessAndResistance(2));
    }

    @Override
    public boolean hasTileEntity(@Nonnull BlockState state)
    {
        return true;
    }

    @Override
    public TileEntity createTileEntity(@Nonnull BlockState state, @Nonnull IBlockReader world)
    {
        return FEDemoWireTileEntity.TILE_ENTITY_TYPE.create();
    }
}

以下是方块实体类的基础实现：

@Mod.EventBusSubscriber(bus = Mod.EventBusSubscriber.Bus.MOD)
public class FEDemoWireTileEntity extends TileEntity  
{
    public static final String NAME = "fedemo:wire";

    @ObjectHolder(NAME)
    public static TileEntityType<FEDemoWireTileEntity> TILE_ENTITY_TYPE;

    @SubscribeEvent
    public static void onRegisterTileEntityType(@Nonnull RegistryEvent.Register<TileEntityType<?>> event)
    {
        FEDemo.LOGGER.info("Registering wire tile entity type ...");
        event.getRegistry().register(TileEntityType.Builder.create(FEDemoWireTileEntity::new, FEDemoWireBlock.BLOCK).build(DSL.remainderType()).setRegistryName(NAME));
    }

    private FEDemoWireTileEntity()
    {
        super(TILE_ENTITY_TYPE);
    }
}

我们还可以在 en_us,json 给方块起个名字：

"block.fedemo.wire": "FE Energy Transmission Conduit"

本讲接下来将不会涉及到方块实体的任何内容（放到下一讲进行）。

方块状态

由于导线在和周围连通时的状态会随着周边环境有所不同，因此我们需要为同一个导线指定不同的方块状态（BlockState）。每个方块状态都是特定属性（Property）和对应值的结合，我们需要声明导线在六个方向的连接状态，因此我们需要共六个描述方块状态属性。这六个属性都可以在 BlockStateProperties 类里找到，我们为这六个属性建立一个针对方向的映射表：

public static final Map<Direction, BooleanProperty> PROPERTY_MAP;

static  
{
    Map<Direction, BooleanProperty> map = Maps.newEnumMap(Direction.class);
    map.put(Direction.NORTH, BlockStateProperties.NORTH);
    map.put(Direction.EAST, BlockStateProperties.EAST);
    map.put(Direction.SOUTH, BlockStateProperties.SOUTH);
    map.put(Direction.WEST, BlockStateProperties.WEST);
    map.put(Direction.UP, BlockStateProperties.UP);
    map.put(Direction.DOWN, BlockStateProperties.DOWN);
    PROPERTY_MAP = Collections.unmodifiableMap(map);
}

接下来我们需要覆盖 fillStateContainer 方法，用来声明该方块拥有以上全部六个属性：

@Override
protected void fillStateContainer(@Nonnull StateContainer.Builder<Block, BlockState> builder)  
{
    builder.add(PROPERTY_MAP.values().toArray(new IProperty<?>[0]));
    super.fillStateContainer(builder);
}

StateContainer.Builder 的 add 方法需要传入变长参数，因此这里直接构造并传入了一个数组。

接下来我们需要在特定场合自动调整方块状态，我们需要：

• 在放置该方块时调整方块状态
• 在该方块周围的方块发生变动时调整方块状态

前者对应 getStateForPlacement 方法，后者对应 updatePostPlacement 方法。我们覆盖这两个方法：

@Override
public BlockState getStateForPlacement(@Nonnull BlockItemUseContext context)  
{
    BlockState state = this.getDefaultState();
    for (Direction facing : Direction.values())
    {
        World world = context.getWorld();
        BlockPos facingPos = context.getPos().offset(facing);
        BlockState facingState = world.getBlockState(facingPos);
        state = state.with(PROPERTY_MAP.get(facing), this.canConnect(world, facing.getOpposite(), facingPos, facingState));
    }
    return state;
}

@Nonnull
@Override
@SuppressWarnings("deprecation")
public BlockState updatePostPlacement(@Nonnull BlockState state, @Nonnull Direction facing, @Nonnull BlockState facingState, @Nonnull IWorld world, @Nonnull BlockPos pos, @Nonnull BlockPos facingPos)  
{
    return state.with(PROPERTY_MAP.get(facing), this.canConnect(world, facing.getOpposite(), facingPos, facingState));
}

private boolean canConnect(@Nonnull IWorld world, @Nonnull Direction facing, @Nonnull BlockPos pos, @Nonnull BlockState state)  
{
    return false; // TODO
}

前者我们需要对六个方向分别检查属性值，而后者我们只需要对受到影响的方向检查就可以了。

我们对连接状态的检查主要分为两部分：

• 检查连接的是不是我们的导线
• 检查连接的方块是否有能量相关的 Capability

private boolean canConnect(@Nonnull IWorld world, @Nonnull Direction facing, @Nonnull BlockPos pos, @Nonnull BlockState state)  
{
    if (!state.getBlock().equals(BLOCK))
    {
        TileEntity tileEntity = world.getTileEntity(pos);
        return tileEntity != null && tileEntity.getCapability(CapabilityEnergy.ENERGY, facing).isPresent();
    }
    return true;
}

方块材质

如果考虑所有的方块状态，一个导线甚至能够有多达 64 个方块状态。如果我们为每一个方块状态都指定一次材质和模型，那这注定会带来很大的工作量。

不过，原版 Minecraft 提供了 multipart 机制，能够让我们为每个属性指定独有的一部分模型和材质，然后将每个属性所指定的拼合起来。

以下是我们的整个方块状态 JSON：

{
  "multipart": [
    {
      "apply": {
        "model": "fedemo:block/wire_core"
      }
    },
    {
      "when": {
        "north": "true"
      },
      "apply": {
        "model": "fedemo:block/wire_part"
      }
    },
    {
      "when": {
        "east": "true"
      },
      "apply": {
        "model": "fedemo:block/wire_part",
        "y": 90
      }
    },
    {
      "when": {
        "south": "true"
      },
      "apply": {
        "model": "fedemo:block/wire_part",
        "y": 180
      }
    },
    {
      "when": {
        "west": "true"
      },
      "apply": {
        "model": "fedemo:block/wire_part",
        "y": 270
      }
    },
    {
      "when": {
        "up": "true"
      },
      "apply": {
        "model": "fedemo:block/wire_part",
        "x": 270
      }
    },
    {
      "when": {
        "down": "true"
      },
      "apply": {
        "model": "fedemo:block/wire_part",
        "x": 90
      }
    }
  ]
}

• 我们的核心位于 fedemo:block/wire_core，这是无论什么方块状态都会有的。
• 我们为每个属性都指定了 fedemo:block/wire_part，在特定方向的连接存在时提供相应的模型和材质。

不同的连接方向属性所引用的 JSON 是相同的，但旋转方向有细微的差别（注意是顺时针）：

• north 为默认，也就是不旋转。
• east 沿 Y 轴顺时针旋转 90 度。
• south 沿 Y 轴顺时针旋转 180 度。
• west 沿 Y 轴顺时针旋转 270 度。
• up 沿 X 轴顺时针旋转 270 度。
• down 沿 X 轴顺时针旋转 90 度。

现在我们需要制作一个代表核心的 wire_core.json：

{
  "parent": "block/block",
  "ambientocclusion": false,
  "textures": {
    "wire": "fedemo:block/wire_core_part",
    "particle": "fedemo:block/wire_core_part"
  },
  "elements": [
    {
      "from": [5, 5, 5],
      "to": [11, 11, 11],
      "faces": {
        "north": {
          "uv": [7, 7, 13, 13],
          "texture": "#wire"
        },
        "east": {
          "uv": [7, 7, 13, 13],
          "texture": "#wire"
        },
        "south": {
          "uv": [7, 7, 13, 13],
          "texture": "#wire"
        },
        "west": {
          "uv": [7, 7, 13, 13],
          "texture": "#wire"
        },
        "up": {
          "uv": [7, 7, 13, 13],
          "texture": "#wire"
        },
        "down": {
          "uv": [7, 7, 13, 13],
          "texture": "#wire"
        }
      }
    }
  ]
}

和一个代表连接状态的 wire_part.json：

{
  "ambientocclusion": false,
  "textures": {
    "wire": "fedemo:block/wire_core_part",
    "particle": "fedemo:block/wire_core_part"
  },
  "elements": [
    {
      "from": [6, 6, 0],
      "to": [10, 10, 7],
      "faces": {
        "north": {
          "uv": [3, 3, 7, 7],
          "texture": "#wire"
        },
        "east": {
          "uv": [6, 3, 13, 7],
          "texture": "#wire"
        },
        "west": {
          "uv": [6, 3, 13, 7],
          "texture": "#wire"
        },
        "up": {
          "uv": [3, 6, 7, 13],
          "texture": "#wire"
        },
        "down": {
          "uv": [3, 6, 7, 13],
          "texture": "#wire"
        }
      }
    }
  ]
}

两个 JSON 引用的是同一个材质（见下图 wire_core_part.png）：

最后别忘了添加描述物品材质的 JSON：

{
  "parent": "fedemo:block/wire_core"
}

现在我们可以打开游戏看看效果了：

方块碰撞箱和选择框

由于导线是不完整方块，因此我们需要指定方块的碰撞箱和选择框的形态。

我们先从碰撞箱开始，我们需要覆盖 getCollisionShape 方法：

@Nonnull
@Override
@SuppressWarnings("deprecation")
public VoxelShape getCollisionShape(@Nonnull BlockState state, @Nonnull IBlockReader world, @Nonnull BlockPos pos, @Nonnull ISelectionContext context)  
{
    return VoxelShapes.empty();
}

这里设置的是没有碰撞箱，读者也可以根据自己的喜好设置成其他的碰撞箱。

然后是选择框，我们在这里这里需要覆盖 getShape 方法：

@Nonnull
@Override
@SuppressWarnings("deprecation")
public VoxelShape getShape(@Nonnull BlockState state, @Nonnull IBlockReader world, @Nonnull BlockPos pos, @Nonnull ISelectionContext context)  
{
    return Block.makeCuboidShape(4, 4, 4, 12, 12, 12);
}

我们已经在第二讲接触过碰撞箱的相关内容了，这里的设置大同小异。

这里设置的选择框比导线核心大了一圈，现在可以打开游戏看看了。

代码清单

这一部分添加的文件有：

• src/main/java/com/github/ustc_zzzz/fedemo/block/FEDemoWireBlock.java
• src/main/java/com/github/ustc_zzzz/fedemo/tileentity/FEDemoWireTileEntity.java
• src/main/resources/assets/fedemo/blockstates/wire.json
• src/main/resources/assets/fedemo/models/block/wire_core.json
• src/main/resources/assets/fedemo/models/block/wire_part.json
• src/main/resources/assets/fedemo/models/item/wire.json
• src/main/resources/assets/fedemo/textures/block/wire_core_part.png

这一部分修改的文件有：

• src/main/resources/assets/fedemo/lang/en_us.json

• 该方块收集太阳能作为能量来源。
• 该方块能够向周围方块输出能量。

添加方块和方块实体

以下是方块类的基础实现：

@Mod.EventBusSubscriber(bus = Mod.EventBusSubscriber.Bus.MOD)
public class FEDemoGeneratorBlock extends Block  
{
    public static final String NAME = "fedemo:generator";

    @ObjectHolder(NAME)
    public static FEDemoGeneratorBlock BLOCK;

    @SubscribeEvent
    public static void onRegisterBlock(@Nonnull RegistryEvent.Register<Block> event)
    {
        FEDemo.LOGGER.info("Registering generator block ...");
        event.getRegistry().register(new FEDemoGeneratorBlock().setRegistryName(NAME));
    }

    @SubscribeEvent
    public static void onRegisterItem(@Nonnull RegistryEvent.Register<Item> event)
    {
        FEDemo.LOGGER.info("Registering generator item ...");
        event.getRegistry().register(new BlockItem(BLOCK, new Item.Properties().group(ItemGroup.MISC)).setRegistryName(NAME));
    }

    private FEDemoGeneratorBlock()
    {
        super(Block.Properties.create(Material.IRON).hardnessAndResistance(3));
    }

    @Override
    public boolean hasTileEntity(@Nonnull BlockState state)
    {
        return true;
    }

    @Override
    public TileEntity createTileEntity(@Nonnull BlockState state, @Nonnull IBlockReader world)
    {
        return FEDemoGeneratorTileEntity.TILE_ENTITY_TYPE.create();
    }
}

以下是方块实体类的基础实现：

@Mod.EventBusSubscriber(bus = Mod.EventBusSubscriber.Bus.MOD)
public class FEDemoGeneratorTileEntity extends TileEntity implements ITickableTileEntity  
{
    public static final String NAME = "fedemo:generator";

    @ObjectHolder(NAME)
    public static TileEntityType<FEDemoGeneratorTileEntity> TILE_ENTITY_TYPE;

    @SubscribeEvent
    public static void onRegisterTileEntityType(@Nonnull RegistryEvent.Register<TileEntityType<?>> event)
    {
        FEDemo.LOGGER.info("Registering generator tile entity type ...");
        event.getRegistry().register(TileEntityType.Builder.create(FEDemoGeneratorTileEntity::new, FEDemoGeneratorBlock.BLOCK).build(DSL.remainderType()).setRegistryName(NAME));
    }

    private FEDemoGeneratorTileEntity()
    {
        super(TILE_ENTITY_TYPE);
    }
}

方块和方块实体类的实现和上一讲针对用电器的实现大同小异。

然后我们指定方块状态 JSON（generator.json）：

{
  "variants": {
    "": {
      "model": "fedemo:block/generator"
    }
  }
}

接下来是描述方块材质的同名 JSON（generator.json）：

{
  "parent": "block/cube_bottom_top",
  "textures": {
    "bottom": "block/furnace_top",
    "top": "fedemo:block/generator_top",
    "side": "fedemo:block/energy_side"
  }
}

以及描述方块对应物品的同名 JSON（generator.json）：

{
  "parent": "fedemo:block/generator"
}

相较上一讲，我们额外添加了 generator_top.png 作为发电机顶部的新材质。

最后我们补充语言文件（en_us.json）：

"block.fedemo.generator": "FE Energy Generator"

打开游戏就可以看到效果了：

为方块实体实现 Capability

我们仍然使用一个 int 字段存储方块实体的能量，并将其通过 read 和 write 方法和 NBT 映射：

private int energy = 0;

@Override
public void read(@Nonnull CompoundNBT compound)  
{
    this.energy = compound.getInt("GeneratorEnergy");
    super.read(compound);
}

@Nonnull
@Override
public CompoundNBT write(@Nonnull CompoundNBT compound)  
{
    compound.putInt("GeneratorEnergy", this.energy);
    return super.write(compound);
}

然后我们基于此实现我们自己的 LazyOptional<IEnergyStorage> 和基于能量的 Capability 实现：

private final LazyOptional<IEnergyStorage> lazyOptional = LazyOptional.of(() -> new IEnergyStorage()  
{
    @Override
    public int receiveEnergy(int maxReceive, boolean simulate)
    {
        return 0;
    }

    @Override
    public int extractEnergy(int maxExtract, boolean simulate)
    {
        int energy = this.getEnergyStored();
        int diff = Math.min(energy, maxExtract);
        if (!simulate)
        {
            FEDemoGeneratorTileEntity.this.energy -= diff;
            if (diff != 0)
            {
                FEDemoGeneratorTileEntity.this.markDirty();
            }
        }
        return diff;
    }

    @Override
    public int getEnergyStored()
    {
        return Math.max(0, Math.min(this.getMaxEnergyStored(), FEDemoGeneratorTileEntity.this.energy));
    }

    @Override
    public int getMaxEnergyStored()
    {
        return 192_000;
    }

    @Override
    public boolean canExtract()
    {
        return true;
    }

    @Override
    public boolean canReceive()
    {
        return false;
    }
});

@Nonnull
@Override
public <T> LazyOptional<T> getCapability(@Nonnull Capability<T> cap, Direction side)  
{
    boolean isEnergy = Objects.equals(cap, CapabilityEnergy.ENERGY) && side.getAxis().isHorizontal();
    return isEnergy ? this.lazyOptional.cast() : super.getCapability(cap, side);
}

这里的实现和上一讲针对用电器的实现类似，唯一的不同之处在于：发电机的电量应该是只出不进的。注意 canReceive 和 receiveEnergy 两个方法的返回值。

为方块实体实现功能

我们既然希望方块收集太阳能，那我们自然是希望方块实体所存储的能量随时间递增。这需要我们让我们的方块实体每 tick 执行一段代码，原版 Minecraft 为我们提供了 ITickableTileEntity 接口。我们只需要让我们的类在继承 TileEntity 的同时实现这一接口即可：

public class FEDemoGeneratorTileEntity extends TileEntity implements ITickableTileEntity  
{
    // ...

    @Override
    public void tick()
    {
        if (this.world != null && !this.world.isRemote)
        {
            this.generateEnergy(this.world);
            this.transferEnergy(this.world);
        }
    }

    private void generateEnergy(@Nonnull World world)
    {
        // TODO
    }

    private void transferEnergy(@Nonnull World world)
    {
        // TODO
    }

    // ...
}

我们先从 generateEnergy 方法的实现开始：

private void generateEnergy(@Nonnull World world)  
{
    if (world.getDimension().hasSkyLight())
    {
        int light = world.getLightFor(LightType.SKY, this.pos.up()) - world.getSkylightSubtracted();
        int diff = Math.min(192_000 - this.energy, 10 * Math.max(0, light - 10));
        if (diff != 0)
        {
            this.energy += diff;
            this.markDirty();
        }
    }
}

表达式 world.getLightFor(LightType.SKY, this.pos.up()) - world.getSkylightSubtracted() 返回的是当前方块上方的天空亮度值，不超过 15。它的下一行代码规定了亮度和能量的映射关系：亮度不超过 10 时不增加 FE，超过 10 后每增加 1 每 tick 相应增加 10 FE，亮度为 15 时为 50 FE。最后别忘了不要让能量值超过能够存储的最大值。

然后我们实现 transferEnergy 方法。

能量的主动输出

我们希望实现发电机和用电器相邻时传输能量的功能，但仅仅为两个机器实现能量相关的 Capability 是远远不够的：计算机程序不是物理定律，不会出现自然而然的能量流动，换言之，我们需要手写能量流动的相关代码。那么这段代码到底应该是“发电机主动输出能量”，还是“用电器主动吸收能量”呢？答案是显然的：我们应该让发电机控制能量的流动，因此，我们需要让我们的发电机对应的方块实体每 tick 自动搜寻附近的方块实体，并分别注入能量。

我们现在来实现 transferEnergy 方法：

private final Queue<Direction> directionQueue = Queues.newArrayDeque(Direction.Plane.HORIZONTAL);

private void transferEnergy(@Nonnull World world)  
{
    this.directionQueue.offer(this.directionQueue.remove());
    for (Direction direction : this.directionQueue)
    {
        TileEntity tileEntity = world.getTileEntity(this.pos.offset(direction));
        if (tileEntity != null)
        {
            tileEntity.getCapability(CapabilityEnergy.ENERGY, direction.getOpposite()).ifPresent(e ->
            {
                if (e.canReceive())
                {
                    int diff = e.receiveEnergy(Math.min(500, this.energy), false);
                    if (diff != 0)
                    {
                        this.energy -= diff;
                        this.markDirty();
                    }
                }
            });
        }
    }
}

方法还是相对简单的：通过遍历水平方向的所有相邻方块，然后逐个注入能量，一次最多注入 500 FE。注意在获取相邻方块时，需要获取的是相反的方向（例如对于东侧的方块，注入能量时应该从该方块的西侧注入），也就是对 Direction 调用 getOpposite 方法并取其返回值。

唯一可能令人费解的是这一行：

this.directionQueue.offer(this.directionQueue.remove());  

通过 directionQueue 字段的声明我们可以注意到，我们把该队列的第一个元素取出放到了最后一个元素的位置，这是为什么呢？

我们思考一下如何不这么做会发生什么：

• 首先找到北侧的方块并注入能量。
• 然后找到东侧的方块并注入能量。
• 接着找到南侧的方块并注入能量。
• 最后找到西侧的方块并注入能量。

我们可以注意到，如果只是平凡地遍历，那么北侧的方块将永远拥有最大的优先级。如果我们每 tick 只能产出 50 FE 能量，但北侧的方块一次可以吸收 200 FE 的能量，那势必会导致能量会全部被北侧的方块吸走。因此，我们为了雨露均沾，必须每次注入能量时人为调整能量的优先级。当然了，可以考虑的实现有很多，这里读者可以尽情地发挥自己的想象力。

现在打开游戏，能量应能正常收集并传输了。

代码清单

这一部分添加的文件有：

• src/main/java/com/github/ustc_zzzz/fedemo/block/FEDemoGeneratorBlock.java
• src/main/java/com/github/ustc_zzzz/fedemo/tileentity/FEDemoGeneratorTileEntity.java
• src/main/resources/assets/fedemo/blockstates/generator.json
• src/main/resources/assets/fedemo/models/block/generator.json
• src/main/resources/assets/fedemo/models/item/generator.json
• src/main/resources/assets/fedemo/textures/block/generator_top.png

这一部分修改的文件有：

• src/main/resources/assets/fedemo/lang/en_us.json

• 制造一个作为用电器的机器方块，且当实体生物站在该方块上时耗费能量为实体回血。
• 使电池在右键方块时可以将自己的能量转移到特定方块，按住 Shift 右键则反过来。

添加方块

我们先编写一个最最基础的方块类，并为其指定材料、硬度、和爆炸抗性，同时为对应的物品指定创造模式物品栏：

@Mod.EventBusSubscriber(bus = Mod.EventBusSubscriber.Bus.MOD)
public class FEDemoMachineBlock extends Block  
{
    public static final String NAME = "fedemo:machine";

    @ObjectHolder(NAME)
    public static FEDemoMachineBlock BLOCK;

    @SubscribeEvent
    public static void onRegisterBlock(@Nonnull RegistryEvent.Register<Block> event)
    {
        FEDemo.LOGGER.info("Registering machine block ...");
        event.getRegistry().register(new FEDemoMachineBlock().setRegistryName(NAME));
    }

    @SubscribeEvent
    public static void onRegisterItem(@Nonnull RegistryEvent.Register<Item> event)
    {
        FEDemo.LOGGER.info("Registering machine item ...");
        event.getRegistry().register(new BlockItem(BLOCK, new Item.Properties().group(ItemGroup.MISC)).setRegistryName(NAME));
    }

    private FEDemoMachineBlock()
    {
        super(Block.Properties.create(Material.IRON).hardnessAndResistance(3));
    }
}

这里使用了 ObjectHolder 注解来使 Forge 自动注入对应的方块类型的实例。注意该注解的参数正是方块的注册名。

然后我们添加语言文件：

"block.fedemo.machine": "FE Heal Machine"

以及同名方块状态 JSON 文件（machine.json）：

{
  "variants": {
    "": {
      "model": "fedemo:block/machine"
    }
  }
}

该 JSON 文件指向同名材质描述文件。

我们创建 machine.json 文件，该文件的上一级目录名应为 block：

{
  "parent": "block/cube_bottom_top",
  "textures": {
    "bottom": "block/furnace_top",
    "top": "fedemo:block/machine_top",
    "side": "fedemo:block/energy_side"
  }
}

该文件复用了熔炉的 JSON 材质，并引用了两张额外的材质（machine_top.png 和 energy_side.png）。

在添加这两张材质的同时，我们不要忘了让 item 目录下的同名文件（machine.json）引用该 JSON：

{
  "parent": "fedemo:block/machine"
}

现在打开游戏。如一切顺利，方块和对应物品均应正常显示：

为方块添加方块实体

如果想要让方块存储复杂的数据，执行复杂的行为，方块实体（TileEntity）是必不可少的。更重要的一点是，TileEntity 本身实现了 ICapabilityProvider 接口，因此如果我们想要声明一个方块拥有能量，我们必须为该方块指定方块实体。

添加 TileEntity 前必须首先添加 TileEntityType。和方块物品等类似，TileEntityType 本身也有注册事件，因此我们要监听这一事件并将 TileEntityType 的实例注册进去：

@Mod.EventBusSubscriber(bus = Mod.EventBusSubscriber.Bus.MOD)
public class FEDemoMachineTileEntity extends TileEntity  
{
    public static final String NAME = "fedemo:machine";

    @ObjectHolder(NAME)
    public static TileEntityType<FEDemoMachineTileEntity> TILE_ENTITY_TYPE;

    @SubscribeEvent
    public static void onRegisterTileEntityType(@Nonnull RegistryEvent.Register<TileEntityType<?>> event)
    {
        FEDemo.LOGGER.info("Registering machine tile entity type ...");
        event.getRegistry().register(TileEntityType.Builder.create(FEDemoMachineTileEntity::new, FEDemoMachineBlock.BLOCK).build(DSL.remainderType()).setRegistryName(NAME));
    }

    private FEDemoMachineTileEntity()
    {
        super(TILE_ENTITY_TYPE);
    }
}

除去注册名外，构造一个 TileEntityType 一共需要不少于三个参数：

• create 方法的第一个参数代表方块实体的构造器，而后续参数代表能够和方块实体相容的方块类型（由于是变长参数，因此可传入多个），这里直接传入对应方块就好了。
• build 方法的唯一参数代表方块实体 NBT 类型。该类型由 Mojang 官方的 DataFixer（com.mojang.datafixers）定义，这里直接取 DSL.remainderType()（代表未知类型）即可。

最后我们需要在方块类中声明方块和方块实体的关联，为此我们需要覆盖 Block 类的 hasTileEntity 和 createTileEntity 方法：

@Override
public boolean hasTileEntity(@Nonnull BlockState state)  
{
    return true;
}

@Override
public TileEntity createTileEntity(@Nonnull BlockState state, @Nonnull IBlockReader world)  
{
    return FEDemoMachineTileEntity.TILE_ENTITY_TYPE.create();
}

为方块实体添加 Capability

由于每个方块实体都分别对应一个 TileEntity 的实例，因此我们可以将数据直接以字段的方式存放在 TileEntity 中。唯一不同的是，为了让我们的数据能够映射到 NBT，我们需要同时覆盖 TileEntity 的 read 和 write 两个方法：

private int energy = 0;

@Override
public void read(@Nonnull CompoundNBT compound)  
{
    this.energy = compound.getInt("MachineEnergy");
    super.read(compound);
}

@Nonnull
@Override
public CompoundNBT write(@Nonnull CompoundNBT compound)  
{
    compound.putInt("MachineEnergy", this.energy);
    return super.write(compound);
}

read 和 write 两个方法反映的分别是方块实体的反序列化和序列化两个过程。一个 TileEntity 通过这两个方法实现了和 NBT 复合标签的映射。

现在我们来实现 getCapability 方法。在上面的内容中我们提到过，TileEntity 本身实现了 ICapabilityProvider 接口，因此我们只需覆盖这一方法即可：

private LazyOptional<IEnergyStorage> lazyOptional; // TODO

@Nonnull
@Override
public <T> LazyOptional<T> getCapability(@Nonnull Capability<T> cap, Direction side)  
{
    boolean isEnergy = Objects.equals(cap, CapabilityEnergy.ENERGY) && side.getAxis().isHorizontal();
    return isEnergy ? this.lazyOptional.cast() : super.getCapability(cap, side);
}

注意相较物品，我们的 getCapability 方法在判断时额外判定了传入的是否为水平朝向（东南西北）。通过这种方法我们可以设定输入输出能量相较朝向的限制，在这里我们直接禁止了能量在上下两个朝向的交互。

然后我们构造 LazyOptional<IEnergyStorage> 的实例：

private final LazyOptional<IEnergyStorage> lazyOptional = LazyOptional.of(() -> new IEnergyStorage()  
{
    @Override
    public int receiveEnergy(int maxReceive, boolean simulate)
    {
        int energy = this.getEnergyStored();
        int diff = Math.min(this.getMaxEnergyStored() - energy, maxReceive);
        if (!simulate)
        {
            FEDemoMachineTileEntity.this.energy += diff;
            if (diff != 0)
            {
                FEDemoMachineTileEntity.this.markDirty();
            }
        }
        return diff;
    }

    @Override
    public int extractEnergy(int maxExtract, boolean simulate)
    {
        return 0;
    }

    @Override
    public int getEnergyStored()
    {
        return Math.max(0, Math.min(this.getMaxEnergyStored(), FEDemoMachineTileEntity.this.energy));
    }

    @Override
    public int getMaxEnergyStored()
    {
        return 192_000;
    }

    @Override
    public boolean canExtract()
    {
        return false;
    }

    @Override
    public boolean canReceive()
    {
        return true;
    }
});

和基于物品的实现，基于方块实体的实现有以下几点不同：

• 直接通过修改 energy 字段调整能量。
• getMaxEnergyStored 返回的是最大存储能量，这里设置为 192000。
• 由于是作为用电器的机器，所以能量是只进不出的。注意 canExtract 和 extractEnergy 两个方法的返回值。
• 注意 markDirty 的使用。该方法会将相应区块标记为需要保存，虽然如果不标记，游戏通常也会保存，但我们强烈建议这么做。

为方块实现具体功能

为了更方便地调整方块实体的能量，我们为方块实体类添加一个 heal 方法用于回血，一次回复 0.1 点（约一秒一颗心）：

public void heal(@Nonnull LivingEntity entity)  
{
    int diff = Math.min(this.energy, 100);
    if (diff > 0)
    {
        entity.heal((float) diff / 1_000);
        this.energy -= diff;
        this.markDirty();
    }
}

若想判断实体是否接触了方块，我们需要利用方块的 onEntityCollision 方法。原版 Minecraft 会在实体进入方块所处区域时触发该方法，我们覆盖 Block 类的这一方法即可：

@Override
@SuppressWarnings("deprecation")
public void onEntityCollision(@Nonnull BlockState state, @Nonnull World world, @Nonnull BlockPos pos, @Nonnull Entity entity)  
{
    if (!world.isRemote && entity instanceof LivingEntity)
    {
        LivingEntity livingEntity = (LivingEntity) entity;
        if (livingEntity.getHealth() < livingEntity.getMaxHealth())
        {
            TileEntity tileEntity = world.getTileEntity(pos);
            if (tileEntity instanceof FEDemoMachineTileEntity)
            {
                ((FEDemoMachineTileEntity) tileEntity).heal(livingEntity);
            }
        }
    }
}

在上面的方法里我们主要检查了四件事，如果四件事均满足我们便调用方块实体类的 heal 方法：

• 世界处于逻辑服务端（使用 !world.isRemote 判断）。
• 实体属于实体生物这一范畴（使用 entity instanceof LivingEntity 判断）。
• 实体生物并未满血（使用 livingEntity.getHealth() < livingEntity.getMaxHealth() 判断）。
• 对应的方块实体是我们所期望的（使用 tileEntity instanceof FEDemoMachineTileEntity 判断）。

最后，为了让我们的实体进入方块所处区域，我们需要重新定义碰撞箱，不能让碰撞箱占满整个方块：

@Nonnull
@Override
@SuppressWarnings("deprecation")
public VoxelShape getCollisionShape(@Nonnull BlockState state, @Nonnull IBlockReader world, @Nonnull BlockPos pos, @Nonnull ISelectionContext context)  
{
    return Block.makeCuboidShape(0, 0, 0, 16, 15, 16);
}

代码很简单，只是让高度也就是 Y 轴从 16 变成了 15 而已，X 轴和 Z 轴方向都没有变。

为物品实现具体功能

现在进入到这一讲的最后一步，也就是实现电池右键方块的行为。原版 Minecraft 会在物品右键方块时调用 Item 类的 onItemUse 方法，因此我们可以通过覆盖这一方法实现相应行为：

@Nonnull
@Override
public ActionResultType onItemUse(@Nonnull ItemUseContext context)  
{
    World world = context.getWorld();
    if (!world.isRemote)
    {
        TileEntity tileEntity = world.getTileEntity(context.getPos());
        if (tileEntity != null)
        {
            Direction side = context.getFace();
            tileEntity.getCapability(CapabilityEnergy.ENERGY, side).ifPresent(e ->
            {
                this.transferEnergy(context, e);
                this.notifyPlayer(context, e);
            });
        }
    }
    return ActionResultType.SUCCESS;
}

private void notifyPlayer(@Nonnull ItemUseContext context, @Nonnull IEnergyStorage target)  
{
    PlayerEntity player = context.getPlayer();
    if (player != null)
    {
        String msg = target.getEnergyStored() + " FE / " + target.getMaxEnergyStored() + " FE";
        player.sendMessage(new StringTextComponent(msg).applyTextStyle(TextFormatting.GRAY));
    }
}

private void transferEnergy(@Nonnull ItemUseContext context, @Nonnull IEnergyStorage target)  
{
    // TODO
}

• 首先我们进行了必要的逻辑服务端检查，以及方块实体本身的检查。
• 然后我们通过 getCapability 方法获取方块实体的能量相关信息。
• 紧接着我们调用了 transferEnergy 方法，该方法将完成能量的传输。
• 最后我们调用了 notifyPlayer 方法，通知右键方块的玩家能量相关信息。

我们现在实现 transferEnergy 方法：

private void transferEnergy(@Nonnull ItemUseContext context, @Nonnull IEnergyStorage target)  
{
    context.getItem().getCapability(CapabilityEnergy.ENERGY).ifPresent(e ->
    {
        if (context.isPlacerSneaking())
        {
            if (target.canExtract())
            {
                int diff = e.getMaxEnergyStored() - e.getEnergyStored();
                e.receiveEnergy(target.extractEnergy(diff, false), false);
            }
        }
        else
        {
            if (target.canReceive())
            {
                int diff = e.getEnergyStored();
                e.extractEnergy(target.receiveEnergy(diff, false), false);
            }
        }
    });
}

我们获取了物品本身对应的 IEnergyStorage 后，判断玩家是否按下 Shift。

接下来进入到了两个分支。我们先从第一个分支，也就是玩家按下 Shift 取出能量开始看：

if (target.canExtract())  
{
    int diff = e.getMaxEnergyStored() - e.getEnergyStored();
    e.receiveEnergy(target.extractEnergy(diff, false), false);
}

一个重要的问题是取出多少能量。很明显，为了达成“能取多少取多少”的目标，我们需要划定一个可以承受的上限，这个上限自然是电池还可以容纳的能量。我们计算出数值后存放到 diff 变量下，然后我们调用方块实体的 extractEnergy 方法以及和物品相关的 receiveEnergy 方法就可以了。

现在我们来看第二个分支，也就是玩家不按下 Shift 存入能量：

if (target.canReceive())  
{
    int diff = e.getEnergyStored();
    e.extractEnergy(target.receiveEnergy(diff, false), false);
}

整段实现和取出能量类似，但具体上仍有细微的差别。除了存取能量的身份对调外，如果我们想贯彻“能存多少存多少”的目标，我们需要把上限划定为 e.getEnergyStored()。

以下是打开游戏后的显示结果。

代码清单

这一部分添加的文件有：

• src/main/java/com/github/ustc_zzzz/fedemo/block/FEDemoMachineBlock.java
• src/main/java/com/github/ustc_zzzz/fedemo/tileentity/FEDemoMachineTileEntity.java
• src/main/resources/assets/fedemo/blockstates/machine.json
• src/main/resources/assets/fedemo/models/block/machine.json
• src/main/resources/assets/fedemo/models/item/machine.json
• src/main/resources/assets/fedemo/textures/block/energy_side.png
• src/main/resources/assets/fedemo/textures/block/machine_top.png

这一部分修改的文件有：

• src/main/java/com/github/ustc_zzzz/fedemo/item/FEDemoBatteryItem.java
• src/main/resources/assets/fedemo/lang/en_us.json

在本系列教程中，各位读者将走入 Forge 能量系统所带来的奇妙世界。由于本文将使用 Minecraft 1.14.4 和 Forge 28.2.4 进行讲解，因此如果读者想要顺畅阅读本教程，那么有一些要求是需要满足的：

• 已能够相对熟练地使用 Java 8 编写代码和设计程序。
• 已能够基于 Minecraft 1.14.4 和 Forge 添加简单的方块或物品。

本系列教程相关源代码：FEDemo.zip（82.5 KiB）。

废话不多说，我们开始吧。

准备工作

我们决定将 ModID 起名为 fedemo，以下是 META-INF/mods.toml 文件：

modLoader="javafml"  
loaderVersion="[28,)"

[[mods]]
modId="fedemo"  
version="${file.jarVersion}"  
displayName="FE Demonstration Mod"  
description="Demonstration for Forge Energy"

[[dependencies.fedemo]]
modId="forge"  
mandatory=true  
versionRange="[28.2,)"  
ordering="NONE"  
side="BOTH"

[[dependencies.fedemo]]
modId="minecraft"  
mandatory=true  
versionRange="[1.14.4]"  
ordering="NONE"  
side="BOTH"  

以下是主类，非常简洁：

@Mod("fedemo")
public class FEDemo  
{
    public static final Logger LOGGER = LogManager.getLogger(FEDemo.class);
}

本系列教程的所有 Java 代码均在 com.github.ustc_zzzz.fedemo 包下。

Capability 系统

Capability 系统是 Forge 能量系统的基石。

Capability 系统对原版游戏元素和第三方行为（大多数情况下和 Mod 有关）实施了一定程度的解耦合。具体来说，Mod 开发者可通过调用 getCapability 方法获取并操纵特定的第三方行为。getCapability 方法由 ICapabilityProvider 接口声明，而 Forge 为很多游戏元素都实现了这一接口，比如我们耳熟能详的物品堆叠（ItemStack）、实体（Entity）、方块实体（TileEntity）等。

CapabilityDispatcher 是一类特殊的 ICapabilityProvider，因为它可以存有多个 ICapabilityProvider。刚才我们提到的物品堆叠、实体、方块实体等游戏元素，内部都存在一个由 Forge 提供的 CapabilityDispatcher，这使得我们向已有的游戏元素添加 ICapabilityProvider 成为可能。

我们来看 getCapability 方法的声明：

@Nonnull <T> LazyOptional<T> getCapability(@Nonnull Capability<T> cap, Direction side);

getCapability 方法的第一个参数代表的是特定的 Capability，我们可以通过 CapabilityEnergy.ENERGY 来拿到它，从而为实现 Forge 能量系统铺路；getCapability 方法的第二个参数代表一个方向，在和方块实体打交道的时候我们用得着。

为物品添加 Capability

我们决定制作一个存储 FE 的电池。我们先编写一个最最基础的物品类，并为其指定创造模式物品栏和最大物品数量：

@Mod.EventBusSubscriber(bus = Mod.EventBusSubscriber.Bus.MOD)
public class FEDemoBatteryItem extends Item  
{
    public static final String NAME = "fedemo:battery";

    @SubscribeEvent
    public static void onRegisterItem(@Nonnull RegistryEvent.Register<Item> event)
    {
        FEDemo.LOGGER.info("Registering battery item ...");
        event.getRegistry().register(new FEDemoBatteryItem().setRegistryName(NAME));
    }

    private FEDemoBatteryItem()
    {
        super(new Item.Properties().maxStackSize(1).group(ItemGroup.MISC));
    }
}

Forge 为 Item 额外追加了 initCapabilities 方法，这个方法的返回值是 ICapabilityProvider，我们需要覆盖这个方法：

@Override
public ICapabilityProvider initCapabilities(@Nonnull ItemStack stack, CompoundNBT nbt)  
{
    return new ICapabilityProvider()
    {
        private LazyOptional<IEnergyStorage> lazyOptional; // TODO

        @Nonnull
        @Override
        public <T> LazyOptional<T> getCapability(@Nonnull Capability<T> cap, Direction side)
        {
            boolean isEnergy = Objects.equals(cap, CapabilityEnergy.ENERGY);
            return isEnergy ? this.lazyOptional.cast() : LazyOptional.empty();
        }
    };
}

我们注意到了 LazyOptional 的存在。LazyOptional 类由 Forge 提供，本质和 Java 的 Optional 类似，不过其内部的实例只在用到的时候才会加载。我们在参数为 CapabilityEnergy.ENERGY 的时候返回一个预先准备好的 LazyOptional，否则便返回一个 LazyOptional.empty()。

CapabilityEnergy.ENERGY 的类型是 Capability<IEnergyStorage>，因此我们要实现的也是 IEnergyStorage。

物品能量的具体实现

ItemStack 存储三种数据：物品类型、数量、和 NBT。很明显，我们的物品能量只能放在 NBT 里。

我们会用到以下五个方法操纵 NBT：

• hasTag：检查一个 ItemStack 是否拥有 NBT。
• getTag：返回一个 ItemStack 的 NBT，如果不存在则返回 null。
• getOrCreateTag：返回一个 ItemStack 的 NBT，如果不存在则为其创建一个。
• putInt：设置 NBT 复合标签的特定整数值。
• getInt：获取 NBT 复合标签的特定整数值，如果值不存在或者不是整数则返回 0。

很好。以下是具体实现：

private final LazyOptional<IEnergyStorage> lazyOptional = LazyOptional.of(() -> new IEnergyStorage()  
{
    @Override
    public int receiveEnergy(int maxReceive, boolean simulate)
    {
        int energy = this.getEnergyStored();
        int diff = Math.min(this.getMaxEnergyStored() - energy, maxReceive);
        if (!simulate)
        {
            stack.getOrCreateTag().putInt("BatteryEnergy", energy + diff);
        }
        return diff;
    }

    @Override
    public int extractEnergy(int maxExtract, boolean simulate)
    {
        int energy = this.getEnergyStored();
        int diff = Math.min(energy, maxExtract);
        if (!simulate)
        {
            stack.getOrCreateTag().putInt("BatteryEnergy", energy - diff);
        }
        return diff;
    }

    @Override
    public int getEnergyStored()
    {
        if (stack.hasTag())
        {
            int energy = Objects.requireNonNull(stack.getTag()).getInt("BatteryEnergy");
            return Math.max(0, Math.min(this.getMaxEnergyStored(), energy));
        }
        return 0;
    }

    @Override
    public int getMaxEnergyStored()
    {
        return 48_000;
    }

    @Override
    public boolean canExtract()
    {
        return true;
    }

    @Override
    public boolean canReceive()
    {
        return true;
    }
});

代码有点复杂，我们一个方法一个方法拆开看。

• canReceive 代表是否能输入能量，这里我们让它返回 true。
• canExtract 代表是否能输出能量，这里我们也让它返回 true。
• getMaxEnergyStored 代表内部能够存储的最大能量，这里我们设定在 48000。
• getEnergyStored 代表内部存储的实际能量，这里我们通过物品的 NBT 读取能量。
• extractEnergy 代表实施输出能量的行为，其中 simulate 参数代表是否为模拟行为。
• receiveEnergy 代表实施输入能量的行为，其中 simulate 参数代表是否为模拟行为。

extractEnergy 和 receiveEnergy 各自均接收一个 int 作为参数，并生成 int 作为返回值。其中，作为参数传入的 int 代表期望输入输出的能量，而作为返回值的 int 代表实际输入输出的能量。这两个参数都非常重要，希望读者能够加以注意。

杂项

我们可以向 en_us.json 这一语言文件里添加一项：

"item.fedemo.battery": "FE Battery"

我们还可以通过覆盖 addInformation 方法添加额外的提示文本：

@Override
@OnlyIn(Dist.CLIENT)
public void addInformation(@Nonnull ItemStack stack, World world, @Nonnull List<ITextComponent> tooltip, @Nonnull ITooltipFlag flag)  
{
    stack.getCapability(CapabilityEnergy.ENERGY).ifPresent(e ->
    {
        String msg = e.getEnergyStored() + " FE / " + e.getMaxEnergyStored() + " FE";
        tooltip.add(new StringTextComponent(msg).applyTextStyle(TextFormatting.GRAY));
    });
}

我们也可以通过覆盖 fillItemGroup 方法为创造模式物品栏添加多个物品，分别对应 0 FE，12000 FE，24000 FE，36000 FE，和 48000 FE：

@Override
public void fillItemGroup(@Nonnull ItemGroup group, @Nonnull NonNullList<ItemStack> items)  
{
    if (this.isInGroup(group))
    {
        IntStream.rangeClosed(0, 4).forEach(i ->
        {
            ItemStack stack = new ItemStack(this);
            stack.getCapability(CapabilityEnergy.ENERGY).ifPresent(e ->
            {
                int energy = e.getMaxEnergyStored() / 4 * i;
                e.receiveEnergy(energy, false);
                items.add(stack);
            });
        });
    }
}

到目前为止，我们已经解决了除材质外的所有问题了。

材质

我们为电池绘制了五种材质，分别对应电量空到电量满等五种情况，也恰好对应创造模式物品栏的五个物品：

默认情况自然是电量空，那我们怎么映射剩下的四种情况呢？原版 Minecraft 为我们提供了 Item Property Override 机制，该机制使得根据 NBT 动态调整材质成为可能。

欲使用 Item Property Override，我们只需在构造方法中添加下面一句：

this.addPropertyOverride(new ResourceLocation("energy"), (stack, world, entity) ->  
{
    LazyOptional<IEnergyStorage> lazyOptional = stack.getCapability(CapabilityEnergy.ENERGY);
    return lazyOptional.map(e -> (float) e.getEnergyStored() / e.getMaxEnergyStored()).orElse(0.0F);
});

这样我们的物品就有了一个名为 energy 的属性，我们在描述材质的 JSON 文件（应为 battery.json）写下：

{
  "parent": "item/generated",
  "textures": {
    "layer0": "fedemo:item/battery"
  },
  "overrides": [
    {
      "predicate": {
        "energy": 0.125
      },
      "model": "fedemo:item/battery1"
    },
    {
      "predicate": {
        "energy": 0.375
      },
      "model": "fedemo:item/battery2"
    },
    {
      "predicate": {
        "energy": 0.625
      },
      "model": "fedemo:item/battery3"
    },
    {
      "predicate": {
        "energy": 0.875
      },
      "model": "fedemo:item/battery4"
    }
  ]
}

注意和普通 JSON 相比，该文件额外多出了 override 部分，其中 predicate 判定的是当前属性值是否不小于提供的值，因此我们在该 JSON 中将 energy 划分为了五档，从而应对五种可能的情况。

接下来我们只需要完善 battery1.json 到 battery4.json 就可以了。以下是 battery4.json 的全部内容：

{
  "parent": "item/generated",
  "textures": {
    "layer0": "fedemo:item/battery4"
  }
}

以下是打开游戏后的显示结果。

代码清单

这一部分添加的文件有：

• src/main/java/com/github/ustc_zzzz/fedemo/FEDemo.java
• src/main/java/com/github/ustc_zzzz/fedemo/item/FEDemoBatteryItem.java
• src/main/resources/pack.mcmeta
• src/main/resources/META-INF/mods.toml
• src/main/resources/assets/fedemo/lang/en_us.json
• src/main/resources/assets/fedemo/models/item/battery.json
• src/main/resources/assets/fedemo/models/item/battery1.json
• src/main/resources/assets/fedemo/models/item/battery2.json
• src/main/resources/assets/fedemo/models/item/battery3.json
• src/main/resources/assets/fedemo/models/item/battery4.json
• src/main/resources/assets/fedemo/textures/item/battery.png
• src/main/resources/assets/fedemo/textures/item/battery1.png
• src/main/resources/assets/fedemo/textures/item/battery2.png
• src/main/resources/assets/fedemo/textures/item/battery3.png
• src/main/resources/assets/fedemo/textures/item/battery4.png

本文作者 zzzz，使用 CC-BY-ND 4.0 协议授权，亦即：

• [👍] 你可以在署名本人的同时使用任何形式转载分发本文章。
• [👎] 你不能在转载分发本文章的同时修改本文章。
• [👍] 你可以在商业目的下使用本文章。

1 引言

这篇文章算是“教程的教程”。本人也算是写过几年教程的人了，因此在写教程这一块也积累了一些东西，现在拿出来分享给大家。本人并不是什么名师大家，也没有读过什么教育学的书籍，因此一定程度的闭门造车在所难免，不过本人还是希望能够通过这篇文章，给所有想要写或者已经在写教程，尤其是系列性技术类教程的人一些帮助。

2 为什么要有教程

对于一篇特定的教程而言，它可不可以没有呢？当然可以。难道说教程的作者在编写该教程之前，人们就没有办法学到相应的知识了吗？但是，在此之前，人们学习特定领域的知识的过程，往往充满着弯路和误导性的见解，因此教程起到的，恰恰是整理归纳，帮后来者少走弯路的过程。

2.1 教程不是手把手

教程通常情况下是以图文或者视频的形式展现给大家的，因此往往很难产生实时性的回馈。当然，对于连载型的教程，读者的回馈一定程度上能够引导作者在接下来的教程编撰过程，不过实质上这方面的影响微乎其微。

因此，虽然教程读者可能很容易找到教程中的事实性错误（比方说哪里哪里写得不够全面，或者干脆就是写错了），但我们不能期望教程的受众能够从字里行间看到一些教程在设计编排和行文思路等方面存在的一些问题。

这恰恰是写教程的一大难点所在，因为我们要面对各种各样的读者：有的读者从未接触过相关领域，学得很慢；而有的读者可能已经是这个领域的熟手，只是想通过教程看看能不能学到一些新的东西。能够让大部分期待受众满意，应当是教程作者自始至终孜孜不倦所追求的目标。

2.2 教程不是开发文档

很多人倾向于把教程写成开发文档。这也难怪，因为这些人在编写教程的时候，市面上可能真的一个同类的教程都没有，因此这些人完全是通过开发文档甚至一定程度自己的摸索进行学习的。

但是，我们为什么会需要第三方开发者编撰的开发文档？请在编写教程时务必牢记：我们不是像流水账一样把知识点介绍完，而是应考虑到读者的学习规律，合理地划分知识点，从而引导读者完成一系列的学习过程。

2.3 教程相当于用户指南

本人很喜欢“用户指南”这一比喻。教程在系统性地介绍知识点的同时，也会把读者领入相关领域的大门，并尽可能地减少未来在该领域会遇到的阻碍。唯一的区别是：用户指南是官方的，而教程通常都是第三方的。

3 教程的受众

在写教程的时候，可不要犯搞不清“阳春白雪”和“下里巴人”的错误。把复杂的内容教给初学者去听，那显然是对牛弹琴；但如果把简单的内容教给熟练工去学，那只会让读者觉着太啰嗦。

但是，如果在某个知识点搞不清是什么样的人会看到，那应该写得精炼一些还是啰嗦一些呢？个人感觉还是要写得啰嗦一点，因为写得精炼会直接把新手拒之门外，而写得啰嗦顶多会让老手看得烦一些，通常不会把老手劝退。

3.1 遣词造句的调整

为了让读者在阅读时搞清楚自己在作者期望中的位置，我们可以在编写时采用一点语言上的小技巧。传言孔仲尼在编纂《春秋》时以一字为褒贬，我们虽然达不到孔老夫子的思想深度，但是一点点小的尝试还是可以有的，比如：

• 如果对编程知之甚少，那么建议使用广受好评的 VSCode 入门。
• VSCode 在开发者中广受欢迎，同时也是编程初学者的上佳之选。

这两句话的含义几乎是一样的，但前者在表述中有默许编程初学者阅读本教程的倾向，而后者却没有这样的意思。如果教程不希望编程初学者阅读，那么使用后一个表述则更为合适。

3.2 遇到新手怎么办

很多时候，即使教程作者尽力了，还是会有超出作者预期的读者来阅读，尤其是新手。虽然每个人其实都是新手过来的，但整个社区由于处在浮躁的大环境下，因此很少能够产生相当的共情能力。幸运的是，编写教程本身不需要特别强的共情能力，因此我们应尽量避免新手在阅读教程遇到困难里，接触到来自社区内部缺乏共情能力所带来的恶意。

我们可以通过设定目标的方式来让新手完成一次自我筛查（比如提醒读者读完某本教材便有阅读当前教程的能力等），从而让超出作者预期的新手读者转而先去完善其他的知识。

3.3 遇到老手怎么办

有的时候，会有一些在特定领域十分熟练的人作为教程的读者。他们可能已经掌握了教程大部分的内容，因此教程中的很多东西对于他们是可有可无的，甚至是啰嗦的。对于这部分读者，本人的建议是在教程中分阶段编写总结性的内容（比如添加专门的“本章小结”），这样熟手便可直奔小结而去，从而节省他们阅读教程的时间。

4 教程整体结构的编排

很多人会像开发文档一样安排教程的整体结构。文档读者大多会直奔主题而去，因此文档的章节顺序是按照内容关注度排序的：最常用的东西放在最前，而不常用的东西放到偏后的位置。但如果我们编写教程时这么想，那是万万不可的。因此，设计开发文档的时候，往往可以想到什么写什么，而设计教程的时候，往往需要在一开始就把教程的整体结构设计完毕，如果之后再作调整，教程将会变得非常难改。

设计教程的整体结构时，考虑到教程的目标读者通常会从头开始，一章一章地读完，因此一定要顺应目标读者的学习过程。如果一个概念本身很常用，但是相对较难掌握，那么它可能很适合放在文档的最开头几章，而放在教程的最开头几章是极为不合适的。

4.1 前言怎么写

前言，又称引言、序，主要起到提纲挈领的作用。通常情况下，教程会在前言里提到教程本身大概写了什么，教程本身的适用背景，以及教程期望读者本身达到什么样的门槛，等等。个人感觉，前言的写法相对比较自由，但十分不建议不写前言。这是因为，如果一篇教程不写前言，尤其当标题写得不那么清楚的时候，很多读者上来便会云里雾里，不知道教程的重心是什么。

4.2 第一章怎么写

对于偏实践的教程而言，第一章通常会写一些工作环境的配置，Hello World 等。读者本身会通过模仿的方式在第一章形成对整个领域最朴素的认知，而且写 Hello World 什么的，是整个教程最基础的部分。一方面，编写该部分时应当尽可能准确，同时也应该与时俱进（这里不一定要求采用最新版本，但往往需要保证在当前的环境下教程里使用的版本也能正常工作）。这块写起来倒是没什么难度，而且开发文档的第一章往往也是类似的，因此流水账通常也能胜任。

对于偏理论的教程而言，第一章通常会介绍一些基本概念。在这一方面，教程作者就应当十分小心了。这一部分相当于后续章节的根基，因此给读者的印象需要经过极其细致的斟酌。此外，由于后续章节往往依赖于这一章，因此该部分一旦落成，后续便会极难更改。作者在编写时，应当把整个教程最核心，最精炼的地方拿出来。

有的教程会同时看重理论和实践，因此上面提到的两方面都会有，而一些篇幅偏短的教程，两方面都没有也是可行的。

4.3 后续章节怎么写

一个领域的知识点往往十分复杂，并且相互盘根错节，而两个章节的知识点相互引用，更是十分常有的事。那读者更容易接受的是靠前章节引用靠后章节的知识点，还是靠后章节引用靠前章节的知识点呢？显然是引用靠前的知识点。

因此，我们在尽量使各章相互保持松散的同时，如果万不得已，一定要尽可能地保证靠前的章节所介绍的知识的完备性。我们在编写教程的时候应该能注意到，教程越往后越好写，而越往前越难改，以上便是原因。

4.4 最后一章怎么写

最后一章通常介绍的是总结和展望性的内容，具体形式通常是资源链接和参考文献。和开发文档不同，教程实际上并不需要把一个领域的所有知识点都介绍完，而对于没有介绍到的知识点，我们便可以放到最后一章来加以简要介绍。最后一章还适用于一些很难嵌入整个教程但却相对重要的知识点。

4.5 后记怎么写

后记通常反映的是作者的心路历程，有的作者也会把这一部分放到前言去写，或者合并到最后一章。说白了，就是作者觉着一些东西不吐不快，但又和整个教程涉及的知识点没什么直接关联，因此放在最后可有可无的碎碎念什么的（笑）。

4.6 附录怎么写

附录记录的通常是流水账，一些杂七杂八的知识点有的作者也不愿意放到正文，而是放到附录来写。由于很多流水账其实是可以通过官方文档等途径，或者干脆通过直接搜索便可得到的，因此近年来也不是很时兴在教程里加附录。

5 教程的具体行文

在上面的内容中我们提到，和开发文档不同，教程通常情况下是会一章一章地依次读下来的。这意味着教程中，具体文段和文段之间的衔接非常重要，因为读者在阅读教程的时候，思维本身应当是连续的。

那什么情况下读者的思绪会被打断呢？

5.1 前后无联系的知识点

之前有过担当节目主持人的经历的应该知道，在两个节目切换的时候，主持人通常需要来到台前说一些转场词，以保持节目与节目之间的连贯。在教程中，这样的“转场词”也是需要精心设计的。

如果同一节引入了两个知识点，那么它们应能够对应读者思考问题的前后顺序，如果有两个知识点无论如何也很难联系到一起，那么它们就应当拆到不相干的两节，即使这两个知识点是作者当初一同学习的。

大部分场合，知识点之间的前后联系是显然的，而有的时候，知识点之间的联系却是深层次的。如果我们编写教程的时候发现两个看起来显然应该放在一起的知识点之间却找不到任何联系，那便要花时间设计引导读者的思维过程了。

这里我们以 Java 语言本身举例：

Java 中可直接构造的类型分为基本数据类型、类、和数组三种。

这三种类型听起来像是流水账，读者大可以在这里直接硬记住，而不去思考这三种类型之间的关联。而对于熟练的 Java 开发者而言，这看起来实在是太过于显然了，以至于 Java 开发者通常情况下压根不会去多花时间思考这三种类型之间是否真的有值得注意的关联。

为了让教程讲得更清楚，我们便需要亲自设计引导读者的思维过程。实际上，当我们使用“基础类型”和“复合类型”两个概念时，一切都迎刃而解了：基本数据类型是基础类型，而类和数组不过是复合类型的两种复合形式嘛。

当然，实际编写教程时，我们往往无法苛求所有的知识点之间都能够产生适当的联系，但是我们还是十分鼓励编写教程的过程中尽可能地把知识点串起来的。事实上，个人感觉，把知识点映射到读者思维过程的能力，恰恰体现了教程作者水平的高低。

5.2 使读者分心的知识点

另一个极其经常出现的原因是教程中掺入了各种虽然能够自然联想到，但会使读者分心的无关知识点。这通常和教程作者过去的学习途径有关：因为学习过程中注定要出现各种弯路，而这会让一个人在学习时掌握各种杂七杂八的知识点；当然，对于他自己而言，知识体系已经整体上掌握了，但如果读者照搬这样的方式去学习，那自然是没有必要的。

对于教程作者来说，这其实是比较大的挑战。我们刚刚提到过，一个领域的知识点是相互盘根错节的，作为初学者必须一样一样地掌握，就像收拾背包的时候必须将物品一件一件地整理一样。教程作者做的正是将知识点“压平”的过程。

当知识点遇上不同的历史阶段时，事情本身将变得更复杂。这里我们仍然以 Java 语言本身作为例子：

Stream<T> 接口的 findFirst 方法返回了一个 Optional<T>，为什么不直接返回一个 T 呢？

相信熟悉 Java 的开发者能够很快答上来：

Optional<T> 代表 T 可能存在，可能不存在，而 findFirst 方法代表找到第一个元素，如果 Stream<T> 为空那当然不存在，否则当然存在。

但我们很快就能发现另一个问题：

Map<String, T> 的 get 方法返回的值也可能存在可能不存在，但为什么不返回一个 Optional<T> 呢？

作为 Java 开发者我们当然知道，设计 Map 时还压根没有 Optional 这一概念，而 Java 后来添加 Stream 的时候同时添加了 Optional，因此新的接口返回了 Optional，而旧的接口由于历史遗留原因，就只能维持原样，直接返回了。

道理我们自然都懂的，但如果我们想要把它写成教程，该怎么向读者解释呢？这其实便是写教程的难点所在。如果教程事先没有详细介绍过 Map，同时这里读者只想关心 findFirst 方法返回 Optional 究竟是怎么一回事，而作者却把上面的因果关系直接全套照搬进教程里，我敢打包票大部分读者肯定一时半会看不懂，而且大概率会因为 Map 等无关知识点发懵。

这类问题的解决方案有很多，比如说只介绍 Stream 而忽略 Map，或者把和 Map 相关的部分放到另外一节甚至另外一章，或者说把 Map 相关的部分单独提出一个“小贴士”提醒读者。不管怎么做，单纯全套照搬个人是极为不提倡的。

5.3 糟糕的排版和错别字

很多人写教程的时候很不注重排版。但个人觉着，排版就如同一个教程的脸面，一个排版良好的教程会大大激发阅读欲望，而一个排版糟糕的教程，即使写得再好，也不会有多少人兴致盎然地读下去。希望所有编写教程的人都能够使自己的教程排版干净整洁。

通常情况下，一个人很难保证自己的教程里没有错别字，但是把错别字降低到一个肉眼很难察觉的范围，个人感觉还是大多数人能够做得到的。当然有些错别字已被大众广泛使用（比如“下划线”的正确写法是“下画线”），个人认为不必过分关心。

5.4 在教程中过分玩梗

很多人喜欢把一些模因（meme）引入教程中。我个人并无意批判大多数情况下的玩梗行为，但是如果过量玩梗的话，很可能导致对梗不熟悉的读者迷失在猜谜的海洋里。当然，很多教程本身会带一定程度的冷幽默，这个个人认为是可取的，当然在提高教程趣味性这一点上，本人也还有很长的路要走。

6 教程的后续维护

教程写完了，自然会有后续维护。个人认为，向教程中添加东西是相对容易的工作，而删改东西则相对困难得多。以下主要分更新和修正两部分具体谈谈教程的删改工作。

6.1 更新教程

很多时候，读者是希望教程能够与时俱进的。但是教程更新版本所冒的风险是非常大的，至少相较开发文档大很多。这是因为开发文档通常是模块化的，每次更新通常只涉及开发文档的数个模块，而教程为了使读者更容易读懂，往往会将知识点揉碎了讲，因此经常容易出现“牵一发而动全身”的现象。

为了减少更新教程带来的不一致性，在最开始编写教程时，我们可以在一些地方稍加留意：一方面我们可以减少插图的数量，因为插图中的不一致性往往很难在更新教程时发现；另一方面我们可以尽量采用不会随版本发生变化的示例进行讲解，这样更新时概念的更新换代往往不会很严重。

当然，如果版本更新实在变动了太多太多的东西，抛弃旧包袱重新写一份新的教程也是值得考虑的。

6.2 修正教程

教程的作者经常能够发现教程的某一章或者其中的某一节讲得不够好。由于教程本身极容易出现不一致性，因此个人建议在修正教程的某一章或某一节时，直接将该章或该节重写，从而避免这一章或这一节内知识点相互引用错位导致的麻烦。

尽量不要移动教程的某一章或某一节到其他位置。因为不管是向前移动还是向后移动，都有可能出现某一章依赖的知识点跑到后面去的情况。因此，这里再次强调教程整体结构事前编排的重要性。

7 总结

因为本人自己写过一些教程，本身作为版主也看过一堆花花绿绿的教程，因此本人很早就有写这样一篇文章的想法了。但是因为本人拖延症发作（笑），以及这篇文章中途删了又改，改了又删，直到现在才和各位见面。

以上纯属个人观点，希望各位能够带着批判性的眼光看待这篇文章。

• Sponge API 的权限系统自带权限上下文系统的支持。
• LuckPerms API 自带权限上下文系统的支持，并支持你听说过的几乎所有插件服务端。

一方面，考虑到本人只会写 Sponge 插件，因此后续内容将基于 Sponge API。另一方面，考虑到今年已经是 9102 年的第二年，不太可能还有人不在自己的服务端中添加并使用 LuckPerms，因此，本文内容主要使用 LuckPerms 5.0 API 完成。读者可参照相关的 Wiki 页面完成项目对 LuckPerms 5.0 API 的依赖设置。

引言

很多开发者甚至服务器维护者可能都有为玩家在特定场合赋予权限的需求，比如说：

• 当玩家在某个特定的领地时拥有 pvp 权限，而在其他地方没有。
• 玩家在特定时间段有执行某些特定命令的权限，而在其他时间段没有。

我们把上面提到的“特定领地”、“特定时间段”，统称为玩家所处的上下文。那我们如何构造这样的上下文呢？

一个常见的思路是在玩家进入领地时为玩家赋予权限，并在玩家离开领地时取消权限。这样做也不是不可行，但是一个值得考虑的问题就是：我们需要确保玩家在进出领地时权限能够正常切换，甚至 1 tick 的差错都不能有。

然而，由于以下几个问题，这一目标实际上很难做到：

1. 我们要求我们需要在监听相关事件方面滴水不漏，不能有差错。
2. 目前权限设置大多需要后台文件操作或数据库操作，因而不可能没有延迟。
3. 我们需要编辑插件配置才能让插件知道哪些权限需要这样，而这理应是权限插件的事。

我们不妨换个角度思考问题。我们既然不能准确把握切换上下文的时间点，那我们在检查权限的时候去动态获知上下文不就好了？众所周知，插件通常情况下使用 hasPermission 方法来检查权限，而该方法将会直接关联到权限插件执行进一步操作。因此，只要有权限插件的适当配合，我们就一定能够“稳、准、狠”地完成目标。

以上便是权限上下文系统的理论基础。

上下文对象

LuckPerms 规定，上下文对象由键值对构成，比如说：

• world=world-nether 代表当前玩家正处于下界。
• server=global 代表当前玩家正处于 global 服务器内（名称可由 LuckPerms 配置文件修改）。

而当我们输入以下命令时：

/lp group default permission set minecraft.command.tp world=world-nether

我们便指定了使用 /tp 命令的权限只会在 world=world-nether 存在时生效。由于该权限的设置是自带上下文的，因此我们便可以轻易地确保玩家只有在下界的时候才能使用 /tp 指令。

如果使用 LuckPerms API 添加权限节点，以下是我们的代码：

import net.luckperms.api.LuckPermsProvider;  
import net.luckperms.api.node.Node;

import java.util.Objects;

Objects.requireNonNull(LuckPermsProvider.get().getGroupManager().getGroup("default")).data()  
        .add(Node.builder("minecraft.command.tp").withContext("world", "world-nether").build());

自定义上下文

LuckPerms 提供了 server 和 world 两个上下文对象，但作为插件开发者，我们更需要的是我们自己的上下文，比如说刚才提到的“特定领地”、“特定时间段”、等等。

LuckPerms 为我们提供了注册 ContextCalculator 的方式。ContextCalculator 接口声明了 calculate 方法，而该方法会在 hasPermission 调用时调用。因此，我们可以在该方法内部动态地收集上下文。

ContextCalculator 接口需要提供一个泛型参数：

• 对于 Bukkit 它是 org.bukkit.entity.Player。
• 对于 Sponge 它是 org.spongepowered.api.service.permission.Subject。
• 对于 BungeeCord 它是 net.md_5.bungee.api.connection.ProxiedPlayer。

下面的代码实现了玩家在距离出生点 40 格以内时自动添加 player-near-spawn=true 上下文（Sponge 的 Subject 需要一些操作才能转换到 Player，对于 Bukkit 和 BungeeCord 不需要）：

import com.flowpowered.math.vector.Vector3d;  
import net.luckperms.api.LuckPermsProvider;  
import net.luckperms.api.context.ContextCalculator;  
import net.luckperms.api.context.ContextConsumer;  
import org.spongepowered.api.entity.living.player.Player;  
import org.spongepowered.api.service.permission.Subject;  
import org.spongepowered.api.util.annotation.NonnullByDefault;

import java.util.Optional;

LuckPermsProvider.get().getContextManager().registerCalculator(new SubjectContextCalculator());

public static class SubjectContextCalculator implements ContextCalculator<Subject>  
{
    @Override
    public void calculate(Subject subject, ContextConsumer accumulator)
    {
        Optional<?> sourceOptional = subject.getCommandSource();
        if (sourceOptional.isPresent() && sourceOptional.get() instanceof Player)
        {
            this.calculatePlayer(accumulator, (Player) sourceOptional.get());
        }
    }

    private void calculatePlayer(ContextConsumer accumulator, Player player)
    {
        Vector3d playerPosition = player.getPosition();
        Vector3d spawnPosition = player.getWorld().getProperties().getSpawnPosition().toDouble();
        if (playerPosition.distance(spawnPosition) <= 40)
        {
            accumulator.accept("player-near-spawn", "true");
        }
    }
}

LuckPerms 要求所有 ContextCalculator 的实现满足两点：

• 执行效率：calculate 方法会被频繁调用，因此相应实现应尽可能快速。
• 线程安全：由于 hasPermission 会被不同的线程调用，因此实现必须保证线程安全。

Coroutine 的最常见用途是编写异步代码，而 Minecraft 中恰恰存在大量需要使用异步代码的场合：比方说我们有时需要将某段代码延迟到一个或多个 tick 后执行，有时需要将某段代码延迟到下一次事件触发时执行，等等。

目前很多主流的编程语言都提供了相对官方的 Coroutine 支持，如 C#、Python、JavaScript，等等。虽然 Java 官方至今仍然没有支持 Coroutine，但 JVM 上流行的两大编程语言 Scala 和 Kotlin，已经对 Coroutine 提供了一定程度的支持。本文将分别使用 Scala 和 Kotlin 两门编程语言实现相应的机制：

上图展示的是本文的核心代码，想必对于 Scala 和 Kotlin 有着一定程度了解的读者已经猜到这段代码实现的是什么需求了。上面的代码实现的特性是玩家在攻击怪物的时候给予 100 tick（约五秒）的攻击冷却，并在冷却结束后通知玩家。

本文针对的是 Forge 平台的 1.12.2-14.23.5.2768 版本，不过对于插件等其他平台等，原理是通用的。

概述

回调函数是实现异步逻辑的常见手段，通常异步行为执行完后会调用回调函数从而执行下一步行为：

// scala
def foo(value: Int, next: (Bar) => Unit) = {  
  next(new Bar(value))
}

// kotlin
fun foo(value: Int, next: (Bar) -> Unit) {  
    next(Bar(value))
}

任何普通的方法通常都可以写成回调函数风格，例如下面的代码负责把两个数相加：

// scala
def add(a: Int, b: Int, next: (Int) => Unit) = {  
  next(a + b)
}

// kotlin
fun add(a: Int, b: Int, next: (Int) -> Unit) {  
    next(a + b)
}

我们通常使用 Continuation Passing Style（简称 CPS）描述这种风格，虽然调用 CPS 风格的方法通常写起来会很痛苦（也就是通常所说的回调地狱）：

// scala
add(40, 2, { value =>  
  foo(value, { bar =>
    doSomethingElse(bar)
  })
})

// kotlin
add(40, 2, { value ->  
    foo(value, { bar ->
        doSomethingElse(bar)
    })
})

如果我们能直接写成 doSomethingElse(foo(add(40, 2))) 该多好啊。实际上，把上面的回调地狱转换成可读性较强的写法的行为被称为 CPS 变换，它是 Scala 及 Kotlin 等语言实现 Coroutine 的基础。

在 Scala 中，我们可以声明返回值带有 @suspendable 注解的方法，而 Kotlin 则可以使用 suspend 关键字。具体的写法如下：

// scala
def add2(a: Int, b: Int): Int@suspendable = shift { next => next(a + b) }  

// kotlin
suspend fun add2(a: Int, b: Int): Int = suspendCoroutine { next => next(a + b) }  

这样我们就可以在特定场合下使用它们了：

// scala
reset {  
  var i = 1
  while (i < 100) {
    val j = add2(i, 1)
    println(f"$i + 1 = $j")
    i = j
  }
}

// kotlin
launch {  
    var i = 1
    while (i < 100) {
        val j = add2(i, 1)
        println("$i + 1 = $j")
        i = j
    }
}

配置

首先，因为配置环境时使用了 Gradle 新特性，而 Forge 使用的 Gradle 版本太过陈旧，因此读者需要使用 Gradle 4 或更高版本（本文使用的版本是 4.10.3），如果读者使用 Gradle Wrapper 的话，请打开 gradle/wrapper/ 目录并修改 gradle-wrapper.properties 文件（注意最后一行）：

distributionBase=GRADLE_USER_HOME  
distributionPath=wrapper/dists  
zipStoreBase=GRADLE_USER_HOME  
zipStorePath=wrapper/dists  
distributionUrl=https\://services.gradle.org/distributions/gradle-4.10.3-all.zip  

然后我们需要配置 build.gradle。基于 Scala 的实现需要 scala-continuations 库，考虑到该库 Forge 已经自带，因此不必额外引入该库，仅需额外声明该库对应的 Scala 编译器插件：

// scala
sourceCompatibility = targetCompatibility = '1.7'

configurations {  
    compilerPlugin
}

dependencies {  
    compilerPlugin 'org.scala-lang.plugins:scala-continuations-plugin_2.11.1:1.0.2'
}

compileScala {  
    sourceCompatibility = targetCompatibility = '1.7'
    scalaCompileOptions.additionalParameters = [
        '-Xplugin:' + configurations.compilerPlugin.asPath,
        '-P:continuations:enable'
    ]
}

注意声明插件的同时还需要为编译器添加 -P:continuations:enable 参数。

基于 Kotlin 的实现需要引入 Forge 并未自带的 Kotlin 环境，这通常可以通过依赖一个名为 ShadowFacts' Forgelin 的 Mod 解决：

// kotlin
sourceCompatibility = targetCompatibility = '1.8'

repositories {  
    jcenter()
    maven {
        name = 'shadowfacts'
        url = 'http://maven.shadowfacts.net/'
    }
}

dependencies {  
    deobfCompile 'net.shadowfacts:Forgelin:1.8.3'
}

最后别忘了把 apply plugin: scala 或 apply plugin: kotlin 添加到配置文件中。后者通常还需要引入 Kotlin 的 Gradle 插件，使用 Kotlin 配置过 Gradle 的应该都比较清楚，这里就不再赘述了。

代码

我们声明一个 Mod 主类，并在其中实现 nextTick 和 nextAttackEvent 两个方法：

// scala
object EventListener {  
  val tickListeners: mutable.Queue[ServerTickEvent => Unit] = mutable.Queue()
  val attackListeners: mutable.Queue[AttackEntityEvent => Unit] = mutable.Queue()

  @SubscribeEvent
  def onTick(event: ServerTickEvent): Unit = {
    if (event.phase == Phase.END) {
      tickListeners.dequeueAll(_ => true).foreach(listener => listener(event))
    }
  }

  @SubscribeEvent
  def onAttack(event: AttackEntityEvent): Unit = {
    if (!event.getTarget.world.isRemote) {
      attackListeners.dequeueAll(_ => true).foreach(listener => listener(event))
    }
  }
}

private def nextTick(): ServerTickEvent@suspendable = shift { continuation =>  
  EventListener.tickListeners.enqueue(continuation)
}

private def nextAttackEvent(): AttackEntityEvent@suspendable = shift { continuation =>  
  EventListener.attackListeners.enqueue(continuation)
}

@Mod.EventHandler
def preInit(e: FMLPreInitializationEvent): Unit = {  
  MinecraftForge.EVENT_BUS.register(EventListener)
}

// kotlin
object EventListener {  
    val tickListeners: Queue<(ServerTickEvent) -> Unit> = ArrayDeque()
    val attackListeners: Queue<(AttackEntityEvent) -> Unit> = ArrayDeque()

    @SubscribeEvent
    fun onTick(event: ServerTickEvent): Unit {
        if (event.phase == Phase.END) {
            tickListeners.toList().also { tickListeners.clear() }.forEach { listener -> listener(event) }
        }
    }

    @SubscribeEvent
    fun onAttack(event: AttackEntityEvent): Unit {
        if (!event.target.world.isRemote) {
            attackListeners.toList().also { attackListeners.clear() }.forEach { listener -> listener(event) }
        }
    }
}

private suspend fun nextTick(): ServerTickEvent = suspendCoroutine { continuation ->  
    EventListener.tickListeners.add { event -> continuation.resume(event) }
}

private suspend fun nextAttackEvent(): AttackEntityEvent = suspendCoroutine { continuation ->  
    EventListener.attackListeners.add { event -> continuation.resume(event) }
}

@Mod.EventHandler
fun preInit(e: FMLPreInitializationEvent): Unit {  
    MinecraftForge.EVENT_BUS.register(EventListener)
}

我们声明了两个事件监听器，并缓存了一串回调函数的列表。nextTick 和 nextAttackEvent 两个方法能够向相应的列表添加回调函数，并在事件触发的时候：

• 获取所有的回调函数；
• 清空缓存的回调函数列表；
• 按顺序依次执行所有回调函数。

注意上面三者必须依次进行，顺序不能有任何变动，读者可以想一想为什么有这样的要求。

最后就是我们的核心代码了：

// scala
@Mod.EventHandler
def init(e: FMLInitializationEvent): Unit = {  
  reset {
    val coolDownPlayers = mutable.HashSet[UUID]()
    while (true) {
      val event = nextAttackEvent()
      val player = event.getEntityPlayer
      val playerUUID = player.getUniqueID
      if (coolDownPlayers.contains(playerUUID)) {
        event.setCanceled(true)
      } else {
        event.getTarget match {
          case _: IMob => reset {
            coolDownPlayers.add(playerUUID)
            var coolDownTickLeft = 100
            while (coolDownTickLeft > 0) {
              coolDownTickLeft -= 1
              nextTick()
            }
            coolDownPlayers.remove(playerUUID)
            val message = "Cool down has expired"
            player.sendMessage(new TextComponentString(message))
          }
          case _ => ()
        }
      }
    }
  }
}

// kotlin
@Mod.EventHandler
fun init(e: FMLInitializationEvent): Unit {  
    GlobalScope.launch {
        val coolDownPlayers = hashSetOf<UUID>()
        while (true) {
            val event = nextAttackEvent()
            val player = event.entityPlayer
            val playerUUID = player.uniqueID
            if (coolDownPlayers.contains(playerUUID)) {
                event.isCanceled = true
            } else {
                when (event.target) {
                    is IMob -> launch {
                        coolDownPlayers.add(playerUUID)
                        var coolDownTickLeft = 100
                        while (coolDownTickLeft > 0) {
                            coolDownTickLeft -= 1
                            nextTick()
                        }
                        coolDownPlayers.remove(playerUUID)
                        val message = "Cool down has expired"
                        player.sendMessage(TextComponentString(message))
                    }
                    else -> Unit
                }
            }
        }
    }
}

一方面，我们可以注意到所有和实现特性相关的代码和对象声明，都放在了同一个方法下，这很好地贯彻了高内聚低耦合的设计原则；另一方面，这样做可以使代码的可读性大大增加，例如跳过 100 tick 的实现声明了一个非常单纯的 while 循环，并重复调用 nextTick 方法 100 次，如果不使用 Coroutine，我难以想象类似的实现能有多复杂。

说明

这里有几点需要说明：

• 我们是在 Mod 加载的时候调用的这段代码，我们可以注意到，所有代码都是被一个以 reset（Scala）或 launch（Kotlin） 开头的块括了起来，因此即使内部写成了死循环的形式，实际运行的时候也只会在第一次 nextAttackEvent 调用的时候暂停，因此根本不会阻塞加载过程。

• 我们声明了一个全局性质的 coolDownPlayers，但在代码里是以临时变量的方式表示的。实际上，该对象会在不同的子过程之间辗转，因此虽然它看起来是一个临时变量，但它是会被一直引用着的。

• 如果游戏世界关闭，代码在执行到 nextAttackEvent 或 nextTick 的时候便永远不会继续执行下去，因此不必担心这个看起来像是死循环的代码不会终止的问题。

• 因为所有的回调函数都是在游戏内事件触发的时候执行的，因此尽管看起来代码本身不同的片段的执行时机并不完全相同，但它们都是在游戏世界的主线程执行的，不必担心任何线程安全的问题。

总结

Coroutine 虽然不是什么新的技术，但是在 Minecraft Mod 中使用 Coroutine，的确能够带来一些相对崭新的写法。这种写法粗看起来可能不那么容易让比较熟悉 Minecraft 的开发者接受（比方说我一开始也不太能接受在代码里写一个循环并在循环里直接等待下一个 tick 这种看起来像是把线程「阻塞」了的写法），但是一旦适应了这样的写法，本人相信开发效率一定能够得到显著的提升。

由于作者本人并不熟悉 Kotlin，因此作者不太能保证本文中的 Kotlin 代码一定完全正确，望请读者谅解。

本文作者zzzz（@ustc-zzzz），使用CC-BY-SA 4.0协议授权。

对于一段程序来说，需要关注的无非就两件事：程序管理的数据，以及程序操控数据的方式。对于Java来说，前者对应的是对象及其字段（Field），而后者对应的自然是对象的方法（Method）了。但是，什么样的方法，会在什么时候执行呢？对于Forge Mod来说，这并不是一件可以立刻回答上来的问题。本篇文章就将一步一步地阐述，Forge会让你编写的Mod，在什么时机，执行什么样的代码，以及Forge为什么要这样做。

依赖注入

凡是写过比Hello World更高级的代码的普通Java开发者都一定知道，Java程序是从一个类的main方法开始执行的。至于这个类是什么，它通常会定义在JAR的manifast（位于META-INF目录下的MANIFEST.MF文件中）中。这样，在你直接执行JAR的时候，被指定的类的main方法便开始工作，从而启动整个应用程序。

Minecraft当然也是这样的，它的代码入口位于net.minecraft.client.main.Main下。当然了，Forge利用了一个名为LaunchWrapper的工具，从而将代码入口修改为net.minecraft.launchwrapper.Launch下。根据包名以及GitHub上的项目所有者，我们可以猜到LaunchWrapper本身，其实也是Mojang官方的工具。

言归正传。不管是Minecraft本身，还是LaunchWrapper，一个Java应用程序，当然只能有一个代码执行入口，也就是说，Forge需要手动执行Mod的代码。Forge首先需要做的是，在启动后搜索mods或者其他的什么目录，然后把所有Mod的JAR加载进Java虚拟机中，然后Forge接着要做的事，很多人可能都已经清楚了——这项技术被称为依赖注入（Dependency Injection）。

依赖注入，简单地来说，就是内部代码由外部框架准备好资源，然后再通过构造方法、Setter等方式带入内部代码中，从而不需要内部代码主动获取资源。在Java中，一个最常见的声明依赖注入的方式是使用注解声明，当然了，有的框架（比如Bukkit、BungeeCord等）声明依赖注入，有时还可以在配置文件中声明，不过Forge没有采用这种做法。

Mod主类

Forge约定，Mod需要执行的内部代码，其所处类应该使用@net.minecraftforge.fml.common.Mod注解标记。我们通常会称呼被@Mod注解的类为一个Mod的主类。Forge会检查Mod代码中所有添加有这一注解的类，并自动实例化，从而创建一个代表该Mod的对象。

Forge还规定了一些其他的注解，有的被用于监听Mod的不同生命周期事件（@Mod.EventHandler）、有的被用于根据不同的物理端实例化对象（@SidedProxy）、有的被用于获取Mod主类实例本身（@Mod.Instance）、有的被用于指定创建Mod主类实例的方式（@Mod.InstanceFactory）等等。这些注解分使用情况的不同，在不同的场合被用于不同的字段和方法上。使用这些注解对于有一定经验的Modder来说，应该再熟悉不过了，这里就不再赘述了。

游戏事件

游戏中的事件监听是如此重要，以至于说整个Modding都建构在游戏中的事件监听上，也一点都不为过。Modder基本上都知道，想要监听游戏中的事件，首先需要定义一个类，作为事件监听器的集合。然后在这个类上定义若干方法，方法的参数代表想要监听的事件类型，从而在相应的事件触发时有机会执行Mod的代码。同时，为区分事件监听器和类的其他方法，只有添加了@net.minecraftforge.fml.common.eventhandler.SubscribeEvent注解的方法才会作为事件监听器处理。最后，再将这个类注册到某个特定的事件总线（Event Bus）上，触发事件同时也由特定的事件总线监管。

Forge定义的事件总线非常之少，其中绝大部分事件都由MinecraftForge.EVENT_BUS这一事件总线监管。不过，对于接触过1.8及更早版本的Minecraft的Modder来说，常用的事件总线其实有两个，而另一个事件总线可以通过FMLCommonHandler.instance().bus()这一方式获得。不过，在新版本的Minecraft中我们可以看到，这一方法已经被弃用了，它的返回值实际上就是MinecraftForge.EVENT_BUS。这是因为，在很久以前，Forge和FML是两套不同的东西，你甚至可以只使用FML加载Mod，而不使用Forge，因为Forge只是一套方便Modder的API。不过在数年后的今天，已经没有人会只使用FML而不使用Forge了。两套代码也融合到了一起，两个分立的事件总线，自然也没有分开存在的必要了。

管理监听器

对于将包含有事件监听器的类注册到事件总线这一行为来说，Forge允许的方式也不断添加。最初的方式是将一个类实例化，然后再调用事件总线的register方法注册这一实例，也就是说，Mod中，这样的代码会经常出现：

public class XXXEventHandler {  
    @SubscribeEvent
    public void onItemCrafted(PlayerEvent.ItemCraftedEvent event) {
        // DO SOMETHING
    }
}

MinecraftForge.EVENT_BUS.register(new XXXEventHandler());  

后来人们发现——XXXEventHandler这样的类，从头到尾只会实例化一次啊，那我为什么不实例化它呢——答案是肯定的，Minecraft 1.10.2的某个Forge版本，引入了静态方法作为事件监听器这一使用方式，在注册时只需要向register方法传入一个Class对象，也就是说，我们的代码可以这么写：

public class XXXEventHandler {  
    @SubscribeEvent
    public static void onItemCrafted(PlayerEvent.ItemCraftedEvent event) {
        // DO SOMETHING
    }
}

MinecraftForge.EVENT_BUS.register(XXXEventHandler.class);  

这看起来就好多了，因为我们根本不需要实例化一个新的对象了，这甚至节省了内存空间。

但是，Forge觉得做的还不够，我们仍然需要在某个时刻（通常是在Mod的FMLPreInitializationEvent事件触发时）调用一次register方法，能否连这个方法的调用都省了呢？Forge在随后引入了@Mod.EventBusSubscriber注解，从而通过通过为类添加这一注解的方式自动将该类注册到MinecraftForge.EVENT_BUS中：

@Mod.EventBusSubscriber
public class XXXEventHandler {  
    @SubscribeEvent
    public static void onItemCrafted(PlayerEvent.ItemCraftedEvent event) {
        // DO SOMETHING
    }
}

Forge会自动检索所有包含有@Mod.EventBusSubscriber注解的类，并将它们对应的Class注册进事件总线中。实际上， 我个人而言更喜欢最后一种监听事件的方法。

为什么有两套系统？

现在我们可以大概整理一下了。

• Mod主类的部分方法通过添加@Mod.EventHandler的方式，监听FMLPreInitializationEvent等和Mod的生命周期有关的事件。
• 一些类中的部分方法通过添加@SubscribeEvent的方式，监听PlayerEvent.ItemCraftedEvent等游戏中的相关事件。

同样都是监听事件，为什么是两套注解，两套系统？合并在一起有理论上的困难吗？事实上没有——一个有一定知名度的框架Sponge，采用的就是把两套事件的监听方法统一的方式。这其实更可以说，是历史遗留的原因。

刚刚我们提到，在数年前，Forge和FML是两套不同的系统——Forge更倾向于形成一套API，而FML才真正负责加载Mod。那么，在很早以前，FML是没有游戏事件监听这一选项的，只需要管理和Mod的生命周期有关的事件，相关的游戏事件监听由Forge负责，Forge也为此重写了一套系统。后来，Forge的事件监听系统由于非常好用，其实现底层也基于一套非常高效的方法——因此被FML手动搬运了过来，并添加了几个FML自己的游戏事件——这也是FMLCommonHandler.instance().bus()的由来。这套系统沿用至今，于是就出现了监听Mod生命周期事件和监听游戏事件采用两套不同方法的现象。

不过，据说在即将到来的Minecraft 1.13，对应的Forge版本中，相应的代码会被重写，@Mod.EventHandler也将走向历史。到时候会发生什么，让我们拭目以待。

众所周知，对于一个插件API，GUI界面总是绕不过的。GUI经常被用作菜单等方便用户交互的界面，其中最常见的就是箱子界面。对于SpongeAPI而言，其对应的就是Inventory系统。

Inventory是一个相对复杂的系统，但是一方面，SpongeAPI是一个经过重新设计的API，操纵Inventory的方式和Bukkit大不相同，另一方面，至今（2017年底）SpongeAPI的Inventory系统仍然正在测试，其本身仍有一些实现不完善之处。不过，这不妨碍我们去使用Inventory系统的一个子集，这部分子集在SpongeAPI中已经稳定下来了。

这篇文件将会整理本人近年来使用SpongeAPI内置Inventory系统的一些经验，以及作者比较确定的，在最新版本的SpongeForge和SpongeVanilla中已经稳定的特性。本文使用的SpongeAPI版本为5.2.0，也就是针对Minecraft 1.10.2。针对Minecraft 1.12.2的SpongeAPI 7略有不同，本文在差异处也会略有提及。

打开和关闭Inventory

作为示例，本文将针对在世界中真实存在的一个箱子，以方便开发者随时查看箱子里的东西，以确定之前对这个箱子做了什么。我们先随便写一个插件主类，并监听一个事件：

package com.github.ustc_zzzz.testchestinventory;

import org.spongepowered.api.block.tileentity.TileEntity;  
import org.spongepowered.api.block.tileentity.carrier.Chest;  
import org.spongepowered.api.entity.living.player.Player;  
import org.spongepowered.api.event.Listener;  
import org.spongepowered.api.event.block.InteractBlockEvent;  
import org.spongepowered.api.event.cause.Cause;  
import org.spongepowered.api.event.filter.cause.First;  
import org.spongepowered.api.item.ItemTypes;  
import org.spongepowered.api.item.inventory.Inventory;  
import org.spongepowered.api.item.inventory.ItemStack;  
import org.spongepowered.api.plugin.Plugin;  
import org.spongepowered.api.scheduler.Task;  
import org.spongepowered.api.world.Location;

import java.util.Optional;

/**
 * @author ustc_zzzz
 */
@Plugin(id = "testchestinventory", name = "TestChestInventoryPlugin")
public class TestChestInventoryPlugin  
{
    @Listener
    public void onInteractBlock(InteractBlockEvent.Primary event, @First Player player)
    {
        Optional<ItemStack> itemInHand = player.getItemInHand(event.getHandType());
        if (!itemInHand.filter(itemStack -> itemStack.getItem().equals(ItemTypes.STICK)).isPresent()) return;

        Optional<TileEntity> tileEntity = event.getTargetBlock().getLocation().flatMap(Location::getTileEntity);
        if (tileEntity.isPresent() && tileEntity.get() instanceof Chest)
        {
            event.setCancelled(true);

            Cause cause = Cause.source(this).build();
            Inventory inventory = ((Chest) tileEntity.get()).getInventory();

            // open inventory
            player.openInventory(inventory, cause);
            // close inventory after 100 ticks (about 5 seconds)
            Task.builder().delayTicks(100).execute(task -> player.closeInventory(cause)).submit(this);
        }
    }
}

这里将不再赘述如何搭建Sponge插件开发环境，如何编写一个主类，以及如何监听并取消一个事件。对Sponge插件开发不熟悉的读者可以参阅本人之前的文章，以及SpongeDocs。作者同时也假设读者对Java8，尤其是Optional系统十分熟悉，相关的内容也不会进行讲解。

Optional<ItemStack> itemInHand = player.getItemInHand(event.getHandType());  
if (!itemInHand.filter(itemStack -> itemStack.getItem().equals(ItemTypes.STICK)).isPresent()) return;  

我们监听了左键单击的事件，检查并过滤掉手上的物品不是木棍的情况。

Optional<TileEntity> tileEntity = event.getTargetBlock().getLocation().flatMap(Location::getTileEntity);  
if (tileEntity.isPresent() && tileEntity.get() instanceof Chest)  

然后我们根据一个BlockSnapshot确定了目标箱子的位置，并找出目标箱子对应的TileEntity。我们要找的Inventory就在这里面。然后我们检查这样的一个TileEntity是否存在，如果存在，检查它是不是实现了Chest接口，也就是它到底是不是一个箱子。

event.setCancelled(true);  

如果是的话，我们取消事件。

Cause cause = Cause.source(this).build();  
Inventory inventory = ((Chest) tileEntity.get()).getInventory();  

我们新建了一个Cause的实例备用，然后我们通过调用Chest类的getInventory方法获取我们想要的Inventory。对Cause系统不熟悉的读者可以参阅SpongeDocs的相关章节。

// open inventory
player.openInventory(inventory, cause);  
// close inventory after 100 ticks (about 5 seconds)
Task.builder().delayTicks(100).execute(task -> player.closeInventory(cause)).submit(this);  

现在才是正戏。到这里我们确认了一点，这个玩家是手持木棍左键点击了一个箱子。我们通过调用Player类的openInventory方法打开这个Inventory，然后我们新建了一个调度器，在100tick也就是大约五秒后，通过调用Player类的closeInventory方法把Inventory关掉。对调度器不熟悉的读者可以参阅SpongeDocs的相关章节。

效果应该是这样的：

对于SpongeAPI 7来说，openInventory和closeInventory两个方法不需要传入Cause。

一些简单的操作

根据上面的示例，我们可以注意到，整个Inventory系统的核心就是org.spongepowered.api.item.inventory.Inventory类。我们先来做一些简单的操作，比如说：

inventory.clear();  

上面的代码把整个Inventory清空。

然后我们在里面放两组苹果，一组胡萝卜：

inventory.offer(ItemStack.of(ItemTypes.APPLE, 64));  
inventory.offer(ItemStack.of(ItemTypes.APPLE, 64));  
inventory.offer(ItemStack.of(ItemTypes.CARROT, 64));  

现在整个方法长这样：

@Listener
public void onInteractBlock(InteractBlockEvent.Primary event, @First Player player)  
{
    Optional<ItemStack> itemInHand = player.getItemInHand(event.getHandType());
    if (!itemInHand.filter(itemStack -> itemStack.getItem().equals(ItemTypes.STICK)).isPresent()) return;

    Optional<TileEntity> tileEntity = event.getTargetBlock().getLocation().flatMap(Location::getTileEntity);
    if (tileEntity.isPresent() && tileEntity.get() instanceof Chest)
    {
        event.setCancelled(true);

        Cause cause = Cause.source(this).build();
        Inventory inventory = ((Chest) tileEntity.get()).getInventory();

        inventory.clear();
        inventory.offer(ItemStack.of(ItemTypes.APPLE, 64));
        inventory.offer(ItemStack.of(ItemTypes.APPLE, 64));
        inventory.offer(ItemStack.of(ItemTypes.CARROT, 64));

        // open inventory
        player.openInventory(inventory, cause);
        // close inventory after 100 ticks (about 5 seconds)
        Task.builder().delayTicks(100).execute(task -> player.closeInventory(cause)).submit(this);
    }
}

现在效果是这样子的：

这个苹果加胡萝卜还是符合我们的预期的。

除了offer方法可以用于向一个Inventory添加物品外，Inventory类还有一些别的方法，比如：

• size方法返回一个Inventory里到底有多少叠物品（这里是3）
• capacity方法返回一个Inventory里到底有多少格物品槽（这里是27）
• totalItems方法返回一个Inventory里到底有多少个物品（这里是192）
• set方法是一个容易和offer方法混淆的方法，在本文的后续部分会用到这个方法
  前者是直接强制性地将一个Inventory的第一个物品槽里的物品设置成想要的物品
  而后者是将一个物品添加到Inventory中，原有的物品不会被替换，自然也不会消失

物品槽

想要制作菜单的开发者一定已经不满意了——我想要的是在某个特定的物品槽设置我想要的物品，你这个依此设置的方法，中间如果有物品槽是空的怎么办？

实际上Sponge采取的策略是——将一个Inventory按照树形结构看待。比如说一个箱子是一个Inventory，那么它有27个物品槽，这27个物品槽分别是27个小的Inventory——这种大Inventory套小Inventory的方式最后就会形成一个树形结构，27个小物品槽是箱子Inventory的子Inventory，而反过来就是父Inventory。这种树形结构的底部，也就是叶子节点就是物品槽，代表它的是Slot类。Slot类自然继承了Inventory类。

可以通过Inventory类的parent方法获取到它的父Inventory。如果它没有父Inventory，那么parent方法返回这个Inventory本身。

Inventory类同时还提供了slots方法，用于遍历所有的叶子节点，也就是包含的所有物品槽。对于一个Slot类的实例来说，这个方法的返回值只包含它自己。

比如说，我们现在遍历我们的箱子的所有物品槽，并接物品槽的位置放置对应数量的苹果，遇到五的倍数就放置胡萝卜。放置这个操作用什么方法好呢？自然是set方法啦。代码如下：

int i = 0;  
for (Slot slot : inventory.<Slot>slots())  
{
    i += 1;
    slot.set(ItemStack.of(i % 5 == 0 ? ItemTypes.CARROT : ItemTypes.APPLE, i));
}

效果如下：

Inventory的属性

如果我非要设置箱子中间的某一个物品槽怎么办？除了遍历箱子之外有什么办法吗？

办法还是有的，Sponge中的每一个Inventory，它都有若干特定的InventoryProperty，它们代表一个特定Inventory的属性。

不过很不幸的一点是，关于InventoryProperty的子类型有很多，Sponge还没有完全支持——不过Sponge已经支持了针对物品槽的两个InventoryProperty，因此我们还是可以使用这两个属性的——它们分别是SlotIndex和SlotPos。

SlotIndex是物品槽的一个属性，指的是一个物品槽在整个Inventory中的位置（在这个箱子里就是0到26）。而SlotPos指的是对于横平竖直的网格状Inventory，一个物品槽在Inventory中的坐标（在这个箱子里就是(0, 0)）。那么比如说我想在中间的竖着的三个物品槽（它们的SlotIndex分别是4，13，22）分别放置一个苹果、胡萝卜、和马铃薯，那么代码应该是什么样子的呢？

inventory.clear();  
inventory.query(SlotIndex.of(4)).set(ItemStack.of(ItemTypes.APPLE, 1));  
inventory.query(SlotIndex.of(13)).set(ItemStack.of(ItemTypes.CARROT, 1));  
inventory.query(SlotIndex.of(22)).set(ItemStack.of(ItemTypes.POISONOUS_POTATO, 1));  

现在效果是这样的：

我们用到了Inventory类的query魔法。

Inventory类的query方法传入若干InventoryProperty，然后寻找满足条件的所有子Inventory，共同组成一个新的Inventory——没错，这个方法返回的是一个新的Inventory实例，你可以像对待你之前遇到过的所有Inventory的方式对待它，比如说：

inventory.query(SlotIndex.of(1), SlotIndex.of(2), SlotIndex.of(3));  

这个指代的是整个箱子的前三个物品槽，也就是整个箱子里所有满足这三个InventoryProperty之一任何物品槽的。你可以往里放三组不同的物品——再放一组就放不下了。

当然，你也可以用以下的方法指定三个物品槽里的物品：

inventory.clear();  
inventory.query(SlotPos.of(4, 0)).set(ItemStack.of(ItemTypes.APPLE, 1));  
inventory.query(SlotPos.of(4, 1)).set(ItemStack.of(ItemTypes.CARROT, 1));  
inventory.query(SlotPos.of(4, 2)).set(ItemStack.of(ItemTypes.POISONOUS_POTATO, 1));  

它和上面使用SlotIndex的方式是一样的。

监听交互事件

在Sponge中所有和Inventory的交互相关的事件都由org.spongepowered.api.event.item.inventory.InteractInventoryEvent继承而来。这自然包括两个意义显而易见的事件：

• InteractInventoryEvent.Open
• InteractInventoryEvent.Close

还有一个非常重要的事件，ClickInventoryEvent事件。这个事件会在玩家于GUI中执行操作时触发。我们可以看到这个接口的声明中定义了很多子类型：

public interface ClickInventoryEvent extends ChangeInventoryEvent, InteractInventoryEvent {  
    interface Primary extends ClickInventoryEvent {}
    interface Middle extends ClickInventoryEvent {}
    interface Secondary extends ClickInventoryEvent {}
    interface Creative extends ClickInventoryEvent {}
    interface Shift extends ClickInventoryEvent {
        interface Primary extends Shift, ClickInventoryEvent.Primary {}
        interface Secondary extends Shift, ClickInventoryEvent.Secondary {}
    }
    interface Double extends ClickInventoryEvent.Primary {}
    interface Drop extends ClickInventoryEvent, DropItemEvent.Dispense {
        interface Single extends Drop {}
        interface Full extends Drop {}
        interface Outside extends Drop {
            interface Primary extends Outside, ClickInventoryEvent.Primary {}
            interface Secondary extends Outside, ClickInventoryEvent.Secondary {}
        }
    }
    interface Drag extends ClickInventoryEvent {
        interface Primary extends Drag, ClickInventoryEvent.Primary {}
        interface Secondary extends Drag, ClickInventoryEvent.Secondary {}
    }
    interface NumberPress extends ClickInventoryEvent {
        int getNumber();
    }
}

这些事件的意义都很明显，这里也就不再赘述了。当然，上面在ClickInventoryEvent中出现的所有事件都是Cancellable的子类型，也就是说它们都可以取消掉。

所有这些事件里，一个名叫getTransactions的方法十分重要，它的定义位于AffectSlotEvent中，返回值为一个SlotTransaction的列表，用于记录所有GUI中涉及到的Slot的变化。

这个方法的返回值比较难理解，我们在这里进行一项实验：我们在刚刚只有三个物品的箱子里利用GUI的Shift左键功能放入一组苹果。放入后这个GUI长这样：

放入前长这样：

我们在主类里添加一个方法监听ClickInventoryEvent.Shift.Primary事件：

@Listener
public void onPrimaryShiftClickInventory(ClickInventoryEvent.Shift.Primary event)  
{
    for (SlotTransaction transaction : event.getTransactions())
    {
        SlotIndex index = transaction.getSlot().getProperties(SlotIndex.class).iterator().next();
        System.out.printf("Slot %d: %s => %s\n", index.getValue(), transaction.getOriginal(), transaction.getFinal());
    }
}

这里的getProperties方法用于获取一个Inventory特定类型的所有InventoryProperty，因为一个物品槽的SlotIndex只有一个，因此这里也（通过.iterator().next()的方式）只取这个集合的第一个SlotIndex。

然后我们照着前面两张图的做法做一次，检查控制台，我们得到了这样三行输出：

Slot 0: SpongeItemStackSnapshot{itemType=Item{Name=none}, count=1} => SpongeItemStackSnapshot{itemType=ItemFood{Name=apple}, count=1}  
Slot 4: SpongeItemStackSnapshot{itemType=ItemFood{Name=apple}, count=1} => SpongeItemStackSnapshot{itemType=ItemFood{Name=apple}, count=64}  
Slot 54: SpongeItemStackSnapshot{itemType=ItemFood{Name=apple}, count=64} => SpongeItemStackSnapshot{itemType=Item{Name=none}, count=1}  

这里记录了三个SlotTransaction。

• 第一个代表箱子左上角的物品槽（序号是0），它原先没有物品，后来多出了一个苹果
• 第二个代表箱子第一排正中间的物品槽（序号是4），它原先有一个苹果，后来变成了一整组
• 第三个代表玩家Hotbar的第一个物品槽（序号是54），它原先是一组苹果，后来没有了

通过对物品槽的变化的记录，我们就可以清楚玩家的一个操作到底对哪些物品槽带来的影响。从而可以决定对这些变化的处理。

一个SlotTransaction继承自Transaction类，所有Transaction的实例都代表一个变化，开发者可以通过调用若干相关的方法以修改变化的结果，有关更多的细节，请参阅SlotTransaction的JavaDocs。

此外，所有的InteractInventoryEvent都有getCursorTransaction方法，这个方法记录玩家鼠标处物品的变化——例如，如果一个玩家把一个物品从GUI拿了起来，玩家鼠标处物品就会从没有物品变成一叠玩家拿起来的物品——这个方法的返回值忠实地把这件事记录了下来。

Inventory和GUI

现在我们有了另一个问题——刚刚我们监听的是什么Inventory呢？是代表这个箱子里27个物品槽的Inventory吗？

显然不是，如果是的话，那么只有27个物品槽的Inventory，上面的Slot 54又是怎么出来的呢？答案已经呼之欲出了——我们监听点击事件的Inventory是一个GUI所代表的Inventory，它有27个箱子的格子，27个玩家背包的格子，和9个玩家Hotbar的格子，总共63个。它的SlotIndex编号是从0一直到62的。

这种GUI所代表的Inventory在Sponge中是org.spongepowered.api.item.inventory.Container类的实例。在Sponge中，所有与Container有关的事件，都是TargetContainer类的实例，比如说我们刚刚看到的所有InteractInventoryEvent。

一个Container同时也是一个Inventory，所以对Container的操作和对普通Inventory的操作几乎没有区别。

我们在这篇文章的前半部分通过调用openInventory方法打开了一个箱子Inventory，这同时也生成了一个Container，这个Container正是openInventory方法的返回值。

Inventory类提供了一个名为getArchetype的方法，用于获取一个Inventory的类型，不过这个方法SpongeAPI还没有完全实现，因此目前可以保证的是仅针对Container有效。调用一个Container的getArchetype的方法是可以获取到当前Container的类型的。

创建自己的Inventory

org.spongepowered.api.item.inventory.Inventory.Builder类正是一个用于创建自己的Inventory的生成器。比如说我们现在为主类添加一个右键使用木棍的监听器，然后创建一个Inventory，并调用openInventory方法打开它：

@Listener
public void onInteractBlock(InteractBlockEvent.Secondary event, @First Player player)  
{
    Optional<ItemStack> itemInHand = player.getItemInHand(event.getHandType());
    if (!itemInHand.filter(itemStack -> itemStack.getItem().equals(ItemTypes.STICK)).isPresent()) return;

    Inventory newInventory = Inventory.builder()
            .property(InventoryTitle.PROPERTY_NAME, new InventoryTitle(Text.of("Custom Inventory")))
            .property(InventoryDimension.PROPERTY_NAME, new InventoryDimension(9, 1))
            .of(InventoryArchetypes.CHEST).withCarrier(player).build(this);

    player.openInventory(newInventory, Cause.source(this).build());
}

这是效果图：

我们甚至可以把这样的一个Inventory缓存起来，这样一个玩家就可以把自己的东西放进去，在下次打开时保证东西仍然存在：

private final Map<Player, Inventory> inventoriesForPlayers = new WeakHashMap<>();

@Listener
public void onInteractBlock(InteractBlockEvent.Secondary event, @First Player player)  
{
    Optional<ItemStack> itemInHand = player.getItemInHand(event.getHandType());
    if (!itemInHand.filter(itemStack -> itemStack.getItem().equals(ItemTypes.STICK)).isPresent()) return;

    Inventory newInventory = this.inventoriesForPlayers.computeIfAbsent(player, p -> Inventory.builder()
            .property(InventoryTitle.PROPERTY_NAME, new InventoryTitle(Text.of("Custom Inventory")))
            .property(InventoryDimension.PROPERTY_NAME, new InventoryDimension(9, 1))
            .of(InventoryArchetypes.CHEST).withCarrier(p).build(this));

    player.openInventory(newInventory, Cause.source(this).build());
}

当然，序列化和反序列化自定义Inventory的工作，还需要玩家自己进行。