本帖最后由 土球球 于 2020-9-6 04:03 编辑
Forge 能量系统简述
这些内容本来是期望成为某本实体书的一部分的，但是一方面编辑在催稿，另一方面再往里塞东西就超字数了（超字数会影响书价，进而影响销量），因此没能最终塞进去。最近我把这些内容整理出来，并顺道把版本从 1.12.2 升级到了 1.14.4（毕竟 Forge 目前声称 1.14.4 是 LTS 来着），在这里分享给大家。
全系列教程分为五讲（看上面的目录），大概涵盖了从物品到机器再到导线等所有和能量有关的东西，希望能够作为各位读者的参考吧。
本文同时在本人的博客发布：
以下是本文相关源代码：
FEDemo.zip
(82.51 KB, 下载次数: 309)
Forge 能量系统简述
这些内容本来是期望成为某本实体书的一部分的，但是一方面编辑在催稿，另一方面再往里塞东西就超字数了（超字数会影响书价，进而影响销量），因此没能最终塞进去。最近我把这些内容整理出来，并顺道把版本从 1.12.2 升级到了 1.14.4（毕竟 Forge 目前声称 1.14.4 是 LTS 来着），在这里分享给大家。
全系列教程分为五讲（看上面的目录），大概涵盖了从物品到机器再到导线等所有和能量有关的东西，希望能够作为各位读者的参考吧。
本文同时在本人的博客发布：
以下是本文相关源代码：
虽然夹杂着众多争议，但 Forge 最终仍然决定在 1.10.2 加入官方的能量系统，并一直将其延续到现在。该系统参考了 CoFH 团队的众多设计，因此和在此前已经拥有鼎鼎大名的 Redstone Flux 能量系统有着众多的相似之处。
在本系列教程中，各位读者将走入 Forge 能量系统所带来的奇妙世界。由于本文将使用 Minecraft 1.14.4 和 Forge 28.2.4 进行讲解，因此如果读者想要顺畅阅读本教程，那么有一些要求是需要满足的：
废话不多说，我们开始吧。
准备工作
我们决定将 ModID 起名为 fedemo，以下是 META-INF/mods.toml 文件：
以下是主类，非常简洁：
本系列教程的所有 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 方法的声明：
getCapability 方法的第一个参数代表的是特定的 Capability，我们可以通过 CapabilityEnergy.ENERGY 来拿到它，从而为实现 Forge 能量系统铺路；getCapability 方法的第二个参数代表一个方向，在和方块实体打交道的时候我们用得着。
为物品添加 Capability
我们决定制作一个存储 FE 的电池。我们先编写一个最最基础的物品类，并为其指定创造模式物品栏和最大物品数量：
Forge 为 Item 额外追加了 initCapabilities 方法，这个方法的返回值是 ICapabilityProvider，我们需要覆盖这个方法：
我们注意到了 LazyOptional 的存在。LazyOptional 类由 Forge 提供，本质和 Java 的 Optional 类似，不过其内部的实例只在用到的时候才会加载。我们在参数为 CapabilityEnergy.ENERGY 的时候返回一个预先准备好的 LazyOptional，否则便返回一个 LazyOptional.empty()。
CapabilityEnergy.ENERGY 的类型是 Capability<IEnergyStorage>，因此我们要实现的也是 IEnergyStorage。
物品能量的具体实现
ItemStack 存储三种数据：物品类型、数量、和 NBT。很明显，我们的物品能量只能放在 NBT 里。
我们会用到以下五个方法操纵 NBT：
很好。以下是具体实现：
代码有点复杂，我们一个方法一个方法拆开看。
extractEnergy 和 receiveEnergy 各自均接收一个 int 作为参数，并生成 int 作为返回值。其中，作为参数传入的 int 代表期望输入输出的能量，而作为返回值的 int 代表实际输入输出的能量。这两个参数都非常重要，希望读者能够加以注意。
杂项
我们可以向 en_us.json 这一语言文件里添加一项：
我们还可以通过覆盖 addInformation 方法添加额外的提示文本：
我们也可以通过覆盖 fillItemGroup 方法为创造模式物品栏添加多个物品，分别对应 0 FE，12000 FE，24000 FE，36000 FE，和 48000 FE：
到目前为止，我们已经解决了除材质外的所有问题了。
材质
我们为电池绘制了五种材质，分别对应电量空到电量满等五种情况，也恰好对应创造模式物品栏的五个物品：
默认情况自然是电量空，那我们怎么映射剩下的四种情况呢？原版 Minecraft 为我们提供了 Item Property Override 机制，该机制使得根据 NBT 动态调整材质成为可能。
欲使用 Item Property Override，我们只需在构造方法中添加下面一句：
这样我们的物品就有了一个名为 energy 的属性，我们在描述材质的 JSON 文件（应为 battery.json）写下：
注意和普通 JSON 相比，该文件额外多出了 override 部分，其中 predicate 判定的是当前属性值是否不小于提供的值，因此我们在该 JSON 中将 energy 划分为了五档，从而应对五种可能的情况。
接下来我们只需要完善 battery1.json 到 battery4.json 就可以了。以下是 battery4.json 的全部内容：
以下是打开游戏后的显示结果。
代码清单
这一部分添加的文件有：
这一讲我们将达成两个目标：
添加方块
我们先编写一个最最基础的方块类，并为其指定材料、硬度、和爆炸抗性，同时为对应的物品指定创造模式物品栏：
这里使用了 ObjectHolder 注解来使 Forge 自动注入对应的方块类型的实例。注意该注解的参数正是方块的注册名。
然后我们添加语言文件：
以及同名方块状态 JSON 文件（machine.json）：
该 JSON 文件指向同名材质描述文件。
我们创建 machine.json 文件，该文件的上一级目录名应为 block：
该文件复用了熔炉的 JSON 材质，并引用了两张额外的材质（machine_top.png 和 energy_side.png）。
在添加这两张材质的同时，我们不要忘了让 item 目录下的同名文件（machine.json）引用该 JSON：
现在打开游戏。如一切顺利，方块和对应物品均应正常显示：
为方块添加方块实体
如果想要让方块存储复杂的数据，执行复杂的行为，方块实体（TileEntity）是必不可少的。更重要的一点是，TileEntity 本身实现了 ICapabilityProvider 接口，因此如果我们想要声明一个方块拥有能量，我们必须为该方块指定方块实体。
添加 TileEntity 前必须首先添加 TileEntityType。和方块物品等类似，TileEntityType 本身也有注册事件，因此我们要监听这一事件并将 TileEntityType 的实例注册进去：
除去注册名外，构造一个 TileEntityType 一共需要不少于三个参数：
最后我们需要在方块类中声明方块和方块实体的关联，为此我们需要覆盖 Block 类的 hasTileEntity 和 createTileEntity 方法：
为方块实体添加 Capability
由于每个方块实体都分别对应一个 TileEntity 的实例，因此我们可以将数据直接以字段的方式存放在 TileEntity 中。唯一不同的是，为了让我们的数据能够映射到 NBT，我们需要同时覆盖 TileEntity 的 read 和 write 两个方法：
read 和 write 两个方法反映的分别是方块实体的反序列化和序列化两个过程。一个 TileEntity 通过这两个方法实现了和 NBT 复合标签的映射。
现在我们来实现 getCapability 方法。在上面的内容中我们提到过，TileEntity 本身实现了 ICapabilityProvider 接口，因此我们只需覆盖这一方法即可：
注意相较物品，我们的 getCapability 方法在判断时额外判定了传入的是否为水平朝向（东南西北）。通过这种方法我们可以设定输入输出能量相较朝向的限制，在这里我们直接禁止了能量在上下两个朝向的交互。
然后我们构造 LazyOptional<IEnergyStorage> 的实例：
和基于物品的实现，基于方块实体的实现有以下几点不同：
为方块实现具体功能
为了更方便地调整方块实体的能量，我们为方块实体类添加一个 heal 方法用于回血，一次回复 0.1 点（约一秒一颗心）：
若想判断实体是否接触了方块，我们需要利用方块的 onEntityCollision 方法。原版 Minecraft 会在实体进入方块所处区域时触发该方法，我们覆盖 Block 类的这一方法即可：
在上面的方法里我们主要检查了四件事，如果四件事均满足我们便调用方块实体类的 heal 方法：
最后，为了让我们的实体进入方块所处区域，我们需要重新定义碰撞箱，不能让碰撞箱占满整个方块：
代码很简单，只是让高度也就是 Y 轴从 16 变成了 15 而已，X 轴和 Z 轴方向都没有变。
为物品实现具体功能
现在进入到这一讲的最后一步，也就是实现电池右键方块的行为。原版 Minecraft 会在物品右键方块时调用 Item 类的 onItemUse 方法，因此我们可以通过覆盖这一方法实现相应行为：
我们现在实现 transferEnergy 方法：
我们获取了物品本身对应的 IEnergyStorage 后，判断玩家是否按下 Shift。
接下来进入到了两个分支。我们先从第一个分支，也就是玩家按下 Shift 取出能量开始看：
一个重要的问题是取出多少能量。很明显，为了达成“能取多少取多少”的目标，我们需要划定一个可以承受的上限，这个上限自然是电池还可以容纳的能量。我们计算出数值后存放到 diff 变量下，然后我们调用方块实体的 extractEnergy 方法以及和物品相关的 receiveEnergy 方法就可以了。
现在我们来看第二个分支，也就是玩家不按下 Shift 存入能量：
整段实现和取出能量类似，但具体上仍有细微的差别。除了存取能量的身份对调外，如果我们想贯彻“能存多少存多少”的目标，我们需要把上限划定为 e.getEnergyStored()。
以下是打开游戏后的显示结果。
代码清单
这一部分添加的文件有：
这一部分修改的文件有：
在这一讲我们将制造一个作为发电机的机器方块：
添加方块和方块实体
以下是方块类的基础实现：
以下是方块实体类的基础实现：
方块和方块实体类的实现和上一讲针对用电器的实现大同小异。
然后我们指定方块状态 JSON（generator.json）：
接下来是描述方块材质的同名 JSON（generator.json）：
以及描述方块对应物品的同名 JSON（generator.json）：
相较上一讲，我们额外添加了 generator_top.png 作为发电机顶部的新材质。
最后我们补充语言文件（en_us.json）：
打开游戏就可以看到效果了：
为方块实体实现 Capability
我们仍然使用一个 int 字段存储方块实体的能量，并将其通过 read 和 write 方法和 NBT 映射：
然后我们基于此实现我们自己的 LazyOptional<IEnergyStorage> 和基于能量的 Capability 实现：
这里的实现和上一讲针对用电器的实现类似，唯一的不同之处在于：发电机的电量应该是只出不进的。注意 canReceive 和 receiveEnergy 两个方法的返回值。
为方块实体实现功能
我们既然希望方块收集太阳能，那我们自然是希望方块实体所存储的能量随时间递增。这需要我们让我们的方块实体每 tick 执行一段代码，原版 Minecraft 为我们提供了 ITickableTileEntity 接口。我们只需要让我们的类在继承 TileEntity 的同时实现这一接口即可：
我们先从 generateEnergy 方法的实现开始：
表达式 world.getLightFor(LightType.SKY, this.pos.up()) - world.getSkylightSubtracted() 返回的是当前方块上方的天空亮度值，不超过 15。它的下一行代码规定了亮度和能量的映射关系：亮度不超过 10 时不增加 FE，超过 10 后每增加 1 每 tick 相应增加 10 FE，亮度为 15 时为 50 FE。最后别忘了不要让能量值超过能够存储的最大值。
然后我们实现 transferEnergy 方法。
能量的主动输出
我们希望实现发电机和用电器相邻时传输能量的功能，但仅仅为两个机器实现能量相关的 Capability 是远远不够的：计算机程序不是物理定律，不会出现自然而然的能量流动，换言之，我们需要手写能量流动的相关代码。那么这段代码到底应该是“发电机主动输出能量”，还是“用电器主动吸收能量”呢？答案是显然的：我们应该让发电机控制能量的流动，因此，我们需要让我们的发电机对应的方块实体每 tick 自动搜寻附近的方块实体，并分别注入能量。
我们现在来实现 transferEnergy 方法：
方法还是相对简单的：通过遍历水平方向的所有相邻方块，然后逐个注入能量，一次最多注入 500 FE。注意在获取相邻方块时，需要获取的是相反的方向（例如对于东侧的方块，注入能量时应该从该方块的西侧注入），也就是对 Direction 调用 getOpposite 方法并取其返回值。
唯一可能令人费解的是这一行：
通过 directionQueue 字段的声明我们可以注意到，我们把该队列的第一个元素取出放到了最后一个元素的位置，这是为什么呢？
我们思考一下如何不这么做会发生什么：
我们可以注意到，如果只是平凡地遍历，那么北侧的方块将永远拥有最大的优先级。如果我们每 tick 只能产出 50 FE 能量，但北侧的方块一次可以吸收 200 FE 的能量，那势必会导致能量会全部被北侧的方块吸走。因此，我们为了雨露均沾，必须每次注入能量时人为调整能量的优先级。当然了，可以考虑的实现有很多，这里读者可以尽情地发挥自己的想象力。
现在打开游戏，能量应能正常收集并传输了。
代码清单
这一部分添加的文件有：
这一部分修改的文件有：
在这一讲和下一讲我们将制造一个作为导线的方块。
这一讲我们将从作为方块的导线着手（换言之只是一个空壳子），而下一讲我们将着重介绍作为能量传输载体的导线。
添加方块和方块实体
以下是方块类的基础实现：
以下是方块实体类的基础实现：
我们还可以在 en_us,json 给方块起个名字：
本讲接下来将不会涉及到方块实体的任何内容（放到下一讲进行）。
方块状态
由于导线在和周围连通时的状态会随着周边环境有所不同，因此我们需要为同一个导线指定不同的方块状态（BlockState）。每个方块状态都是特定属性（Property）和对应值的结合，我们需要声明导线在六个方向的连接状态，因此我们需要共六个描述方块状态属性。这六个属性都可以在 BlockStateProperties 类里找到，我们为这六个属性建立一个针对方向的映射表：
接下来我们需要覆盖 fillStateContainer 方法，用来声明该方块拥有以上全部六个属性：
StateContainer.Builder 的 add 方法需要传入变长参数，因此这里直接构造并传入了一个数组。
接下来我们需要在特定场合自动调整方块状态，我们需要：
前者对应 getStateForPlacement 方法，后者对应 updatePostPlacement 方法。我们覆盖这两个方法：
前者我们需要对六个方向分别检查属性值，而后者我们只需要对受到影响的方向检查就可以了。
我们对连接状态的检查主要分为两部分：
方块材质
如果考虑所有的方块状态，一个导线甚至能够有多达 64 个方块状态。如果我们为每一个方块状态都指定一次材质和模型，那这注定会带来很大的工作量。
不过，原版 Minecraft 提供了 multipart 机制，能够让我们为每个属性指定独有的一部分模型和材质，然后将每个属性所指定的拼合起来。
以下是我们的整个方块状态 JSON：
不同的连接方向属性所引用的 JSON 是相同的，但旋转方向有细微的差别（注意是顺时针）：
现在我们需要制作一个代表核心的 wire_core.json：
和一个代表连接状态的 wire_part.json：
两个 JSON 引用的是同一个材质（见下图 wire_core_part.png）：
最后别忘了添加描述物品材质的 JSON：
现在我们可以打开游戏看看效果了：
方块碰撞箱和选择框
由于导线是不完整方块，因此我们需要指定方块的碰撞箱和选择框的形态。
我们先从碰撞箱开始，我们需要覆盖 getCollisionShape 方法：
这里设置的是没有碰撞箱，读者也可以根据自己的喜好设置成其他的碰撞箱。
然后是选择框，我们在这里这里需要覆盖 getShape 方法：
我们已经在第二讲接触过碰撞箱的相关内容了，这里的设置大同小异。
这里设置的选择框比导线核心大了一圈，现在可以打开游戏看看了。
代码清单
这一部分添加的文件有：
这一部分修改的文件有：
欢迎来到整个系列教程中最难的一讲。本讲将侧重于介绍如何为传统意义上的导线实现能量传输。
和现实世界不同，在游戏中实现传统意义上的导线，要比无线充电等其他实现方式困难得多。因此读者如果实在无法完整实现传统意义上的导线，那也可以退而求其次，去实现其他的能量传输形式。导线之外的能量传输形式往往也是会受到玩家欢迎的。
导线连通网络
一个最朴素的想法是让每根导线每 tick 都将附近导线的能量传输过来。实际上一些 Mod（比方说 RailCraft 等）也正是这么做的。
但这样做无疑从游戏体验上就存在一个问题：如果是一根长长的导线，那么每 tick 能量自然只能传输一格，如果导线长达几百根，那毫无疑问需要数秒甚至十多秒的时间才能将能量从一头传到另一头。如果考虑到游戏性能的话，问题更大了：所有的导线都需要每 tick 更新一次，那势必导致世界上每 tick 都更新的方块实体数量大大增加。
所以，一个非常重要的原则就是：不要为代表导线的方块实体实现 ITickableTileEntity 接口。那我们应当什么时候执行导线相关的逻辑呢？
部分 Mod 会为导线指定一个中心方块（比如说 AppliedEnergistics2 的 ME 控制器），这不失为一个好的选择：我们只需要为中心方块实现 ITickableTileEntity，并由它接管所有能量相关的逻辑即可。但是，我们需要实现的是传统意义上的导线，换言之，我们要实现的能量传输系统没有中心方块，对每一根导线而言，它们都是相互平等的。
为了解决这一问题。我们必须为每个世界单独提供一个管理能量传输的导线连通网络，并且自动接管导线的通断相关逻辑。为了方便进一步的操作，我们可以从每一组互相连通的导线（又称一个连通域）中挑选一个代表方块，然后使用该方块代表整组导线。当然，导线的通断会导致一组导线分裂成两组，或是两组导线合并成一组，这些都是我们需要考虑的。
我们现在将接口声明如下：
如何实现这个接口呢？本讲将提供相对简单直观的实现，该实现可以达到 O(N) 的时间复杂度。高效的实现可以做到多项式对数级（O(polylog N)）的时间复杂度，但过于复杂：感兴趣的读者可以通过阅读 Wikipedia（英文页面）加以了解。
实现的思路很简单：除了维护所有连接外，我们只需要对每个方块维护一个连通域的相关集合就好了，而集合的第一个元素自然便是连通域的代表方块：
上面的代码中，components 自然是方块到连通域（Set<BlockPos>）的映射，而 connections 中存储着所有连接。
我们先从 size 和 root 方法的实现开始：
两个实现都十分直观，且都考虑到了有连通域和无连通域的情况。唯一需要注意的是我们需要 toImmutable 方法把 BlockPos 转为不可变的，这样后续我们才能将相应 BlockPos 直接存入 Set 或 Map 中。
接下来我们实现 cut 和 link 两个方法。
导线连通域的合并
我们再来实现 link 方法：
我们一段一段地来分析：
这一段是将 BlockPos 和对应 Direction 添加到 connections 中，如果在这之前 connections 中并不存在该连接，那么 put 方法将返回 true，如果不存在，那么自然就没有进行下一步的意义了。
如果连接不存在的话，那么我们还需要找到连接到的 BlockPos，为其相反方向添加连接。
我们试图获取两个 BlockPos 所处的连通域，至此我们需要分三种情况：
这对应两个连通域都不存在的情况：创建一个新连通域（union），然后把两个 BlockPos 加上去。别忘了调用 beforeMerge 的相关方法。
这对应第一个连通域不存在而第二个存在的情况，我们需要把第一个 BlockPos 加上去。
这对应第一个连通域存在而第二个不存在的情况，我们需要把第二个 BlockPos 加上去。
这对应两个连通域都存在且不相同的情况，我们需要创建一个连通域把两个连通域合并到一起，然后应用到两个连通域中的所有节点上。
最后我们注意到，只有两种情况下我们不会调用 beforeMerge 的 onChange 方法：
导线连通域的分裂
最后我们实现 cut 方法。cut 方法是整个接口中最难实现的一个，因此在动手写代码时，我们首先需要了解相关原理。
我们知道删除某个连接有可能将一个连通域分裂成两半，也有可能不会为一个连通域带来变化。为了检查这两件事，我们需要从被删除的连接所对应的两个 BlockPos 开始，分别进行广度优先搜索，并在以下两个条件中的任何一个达成时同时终止搜索：
为此，我们需要首先实现一个基于广度优先搜索的 Iterator：
广度优先搜索的实现很简单，上面的代码也很清晰，这里就不展开讲解了。
接下来我们使用 BFSIterator 实现 cut 方法：
我们在这里还是一段一段地讲解：
这里将移除对应边，如果对应边在移除前存在，那么该方法返回 true。
如果连接存在的话，那么我们还需要找到连接到的 BlockPos，为其相反方向删除连接。
然后我们为两边的 BlockPos 分别创立 BFSIterator，轮流实施迭代过程。
如果我们证实我们的连通域会分裂成两半，并且已经搜索到了其中一半（searched），那么接下来我们需要定主连通域和次连通域。主连通域自然是当前节点所在连通域，但我们刚刚遍历收集到的，到底是不是主连通域呢？我们需要 searched.contains(primaryNode) 这一表达式加以判断：
接下来就要把这两个集合应用到每一个从属于它们的 BlockPos 了。注意如果该连通域中只有一个 BlockPos，那么可以直接将其从 components 中删除。
最后我们调用了 afterSplit 的 onChange 方法。
导线能量网络
我们现在可以基于连通网络实现能量网络了。除了连通网络外，我们还需要存储什么呢？
关于能量存储这里补充一点：我们只需要为每个连通域的代表方块存储能量值，而由于能量值一定是非负整数，因此这里使用 Multiset 将十分适合。
除了上面提到的这些和 world 外，我们还额外添加了一个 taskCollection 字段，稍后我们监听 tick 事件时用得着。
我们还需要考虑一个问题：刚刚我们提到过，我们的能量网络是相对于某个世界的，因此对于某个特定的世界而言，导线的能量数据是全局存储的，但我们应如何把数据放到存档里呢？以连通域为单位存储在这里显然不适合，因为连通域会合并和分裂，从而使得维护存档中导线和连通域之间的关系成为非常困难的工作（在内存中这很容易）。一个很不错的解决方案是：我们可以把能量放到导线里均摊储存，这样不管连通域如何合并和分裂，最终都将落实到每根导线和存档的交互上。为了实现这一解决方案，我们需要声明四个方法：
这四个方法的实现都非常简单。Guava 的 Multiset 和 Multimap 在实现上为我们带来了极大的方便：
这里唯一需要指出的是能量的分摊方式，也就是在整体能量除以连通域导线数量除不开的时候，问题是如何解决的：
在 tick 事件中增删导线
我们现在声明用于删除导线的 disableBlock 方法，和用于添加导线的 enableBlock 方法。但是，这两个方法的实现并没有那么直接，因为我们需要把相关行为托管到 tick 事件中执行。
为什么我们不能立刻增删导线？这是因为在增删导线的时候，我们需要检查导线和周围方块的连通性，而很多时候导线是在世界加载阶段加载的，因此如果在世界加载时获取周围方块的相关信息，将会极易导致死锁。因此我们需要把增删导线的相关逻辑放到 tick 事件中，这正是 taskCollection 字段的存在意义。
我们为 disableBlock 和 enableBlock 两个方法添加了 Runnable 作为回调函数，并在 tickStart 方法调用时调用。我们稍后便会在 tick 事件的监听器里调用 tickStart 方法。
向能量网络增删导线
我们先来实现删除导线：
除了调用回调函数外，删除导线主要做三件事：
切断导线连接时需要传入 ConnectivityListener，这里声明并实现了 afterSplit 方法，并传入方法引用作为实现。afterSplit 方法所做的事很简单：把当前连通域的整体能量按所拥有的导线数量分离一部分出来给一个新的连通域。
然后我们再来实现添加导线：
除了调用回调函数外，添加导线主要做的也是三件事：
和删除导线相比，添加导线还需要检查周围方块是否能够与其相互连接，因此实现会稍加复杂：
我们现在实现 hasWireConnection 方法：
这里需要额外注意 isBlockLoaded 方法的调用。如果我们不事先进行 isBlockLoaded 这一检查，那么 getBlockState 方法在检查未加载的方块坐标时，将会自动将该方块坐标所处的区块予以加载，而加载会导致连接状态的变化，因此如果世界上有一长链导线，这会导致途径的所有区块全部加载，这显然是没有必要的。更为重要的是，游戏会在加载区块后试图卸载不必要的区块，而卸载区块同样会导致连接状态的变化，这一变化又会反过来加载区块，因此区块会不断地在加载和卸载之间循环，这显然会带来不必要的性能损失。稍后我们会在其他方法再次调用 isBlockLoaded 方法进行方块是否已加载的检查。
增删导线的逻辑到这里就彻底写完了。接下来我们要写另一处需要在 tick 事件中执行的逻辑。
在 tick 事件中输送能量
在编写发电机的时候我们曾经提到，能量的流动应由发电机控制，而发电机实现了 ITickableTileEntity 接口，因此可以在实现该接口的 tick 方法时输送能量。刚刚我们提到，导线能量网络是以世界为单位的，因此我们同样需要监听世界的 tick 事件完成这件事。我们把这一行为写进 tickEnd 方法：
该方法的实现很简单：遍历所有的机器（在遍历前打乱了一遍次序），然后如果机器可以接收能量，那么便向其输送能量。注意 isBlockLoaded 方法的调用，因为我们并不希望向未加载的区块中的方块实体输送能量。
标记需要保存的区块
我们需要在保存存档的时候标记所有需要保存的区块。我们声明一个 markDirty 方法，并在该方法内部实现相应的逻辑：
稍后我们会监听保存世界存档的事件，然后调用这一方法。
导线能量网络的管理
我们需要一个全局化的管理类，我们决定让它成为 SimpleEnergyNetwork 的嵌套类：
该类提供了构造并返回 SimpleEnergyNetwork 方法，并且有三个事件监听器：
到这里，整个 SimpleEnergyNetwork，就完全实现完了，我们稍后会在导线的方块实体类里调用里面的相关方法。
为导线实现 Capability
我们现在为代表导线的方块实体添加 Capability：
由于导线既可以输入能量，也可以输出能量，因此 canExtract 和 canReceive 都应返回 true，剩下的实现和之前的发电机和用电器都大同小异，这里就不展开了。
导线本身的加载与卸载
Minecraft 原版和 Forge 共为 TileEntity 提供了三个方法用于描述方块实体的加载和卸载过程：
我们还需要覆盖读取 NBT 里会调用的 read 方法和写入 NBT 时会调用的 write 方法。我们先实现这两个方法：
我们可以注意到一件事：write 方法是直接从导线能量网络里获取均摊能量，而 read 方法却写入到了一个临时值，为什么要这样做？这是因为，read 方法第一次调用的时机特别特别早，甚至方块实体还没有被加载到世界中，因此我们甚至连方块实体所处的世界都无法获取得到，更逞论获取导线能量网络中的均摊能量了。因此，我们只能先写入一个临时值，然后在 onLoad 方法里读取这个临时值：
注意该方法设置能量的方式：通过添加差额能量的方式设置。
最后我们还剩下 onChunkUnloaded 和 remove 两个方法。我们现在实现这两个方法：
和 onChunkUnloaded 相比，remove 方法额外多做了一件事：把导线连通网络里当前位置的能量清零。这可以避免在该位置重新添加导线时附带残留能量。
到这里，整个导线的方块实体相关代码，就全部实现完了。但我们还有一件事没处理：如果导线附近的方块发生变化了怎么办？
导线附近方块的变化
如果导线附近添加了新的机器，那么我们应当将这件事通知能量网络。这可以通过覆盖 Block 类的 neighborChanged 方法来实现。
我们在方块类（FEDemoWireBlock）写下以下代码：
很好，关于导线的一切我们都已经写完了。
代码清单
这一部分添加的文件有：
这一部分修改的文件有：
Forge 能量系统简述
这些内容本来是期望成为某本实体书的一部分的，但是一方面编辑在催稿，另一方面再往里塞东西就超字数了（超字数会影响书价，进而影响销量），因此没能最终塞进去。最近我把这些内容整理出来，并顺道把版本从 1.12.2 升级到了 1.14.4（毕竟 Forge 目前声称 1.14.4 是 LTS 来着），在这里分享给大家。
全系列教程分为五讲（看上面的目录），大概涵盖了从物品到机器再到导线等所有和能量有关的东西，希望能够作为各位读者的参考吧。
本文同时在本人的博客发布：
- https://blog.ustc-zzzz.net/forge-energy-demo-1/
- https://blog.ustc-zzzz.net/forge-energy-demo-2/
- https://blog.ustc-zzzz.net/forge-energy-demo-3/
- https://blog.ustc-zzzz.net/forge-energy-demo-4/
- https://blog.ustc-zzzz.net/forge-energy-demo-5/
以下是本文相关源代码：
FEDemo.zip
(82.51 KB, 下载次数: 309)
2021.12 数据，可能有更多内容
Forge 能量系统简述
这些内容本来是期望成为某本实体书的一部分的，但是一方面编辑在催稿，另一方面再往里塞东西就超字数了（超字数会影响书价，进而影响销量），因此没能最终塞进去。最近我把这些内容整理出来，并顺道把版本从 1.12.2 升级到了 1.14.4（毕竟 Forge 目前声称 1.14.4 是 LTS 来着），在这里分享给大家。
全系列教程分为五讲（看上面的目录），大概涵盖了从物品到机器再到导线等所有和能量有关的东西，希望能够作为各位读者的参考吧。
本文同时在本人的博客发布：
- https://blog.ustc-zzzz.net/forge-energy-demo-1/
- https://blog.ustc-zzzz.net/forge-energy-demo-2/
- https://blog.ustc-zzzz.net/forge-energy-demo-3/
- https://blog.ustc-zzzz.net/forge-energy-demo-4/
- https://blog.ustc-zzzz.net/forge-energy-demo-5/
以下是本文相关源代码：
虽然夹杂着众多争议，但 Forge 最终仍然决定在 1.10.2 加入官方的能量系统，并一直将其延续到现在。该系统参考了 CoFH 团队的众多设计，因此和在此前已经拥有鼎鼎大名的 Redstone Flux 能量系统有着众多的相似之处。
在本系列教程中，各位读者将走入 Forge 能量系统所带来的奇妙世界。由于本文将使用 Minecraft 1.14.4 和 Forge 28.2.4 进行讲解，因此如果读者想要顺畅阅读本教程，那么有一些要求是需要满足的：
- 已能够相对熟练地使用 Java 8 编写代码和设计程序。
- 已能够基于 Minecraft 1.14.4 和 Forge 添加简单的方块或物品。
废话不多说，我们开始吧。
准备工作
我们决定将 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
这一讲我们将达成两个目标：
- 制造一个作为用电器的机器方块，且当实体生物站在该方块上时耗费能量为实体回血。
- 使电池在右键方块时可以将自己的能量转移到特定方块，按住 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
在这一讲我们将制造一个作为发电机的机器方块：
- 该方块收集太阳能作为能量来源。
- 该方块能够向周围方块输出能量。
添加方块和方块实体
以下是方块类的基础实现：
代码:
- @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
在这一讲和下一讲我们将制造一个作为导线的方块。
这一讲我们将从作为方块的导线着手（换言之只是一个空壳子），而下一讲我们将着重介绍作为能量传输载体的导线。
添加方块和方块实体
以下是方块类的基础实现：
代码:
- @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
欢迎来到整个系列教程中最难的一讲。本讲将侧重于介绍如何为传统意义上的导线实现能量传输。
和现实世界不同，在游戏中实现传统意义上的导线，要比无线充电等其他实现方式困难得多。因此读者如果实在无法完整实现传统意义上的导线，那也可以退而求其次，去实现其他的能量传输形式。导线之外的能量传输形式往往也是会受到玩家欢迎的。
导线连通网络
一个最朴素的想法是让每根导线每 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 所处的连通域，至此我们需要分三种情况：
- 两个连通域都不存在，那我们需要新创建一个连通域，然后把两个 BlockPos 加上去。
- 一个连通域存在，另一个不存在，那我们需要把对应的 BlockPos 加到相应的连通域中。
- 两个连通域都存在，那如果它们不相同，我们需要把两个连通域相互合并，然后应用到所有相关节点上去。
代码:
- 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
求大佬告知用什么启动器可以玩
MCBBS有你更精彩~
MCBBS有你更精彩~
感谢大佬
本帖最后由 E.T.星落辰 于 2020-5-4 12:54 编辑
给土球球比心（）
感觉FE系统现在还是用的人少啊，不愧蝙蝠那一句苏联笑话2333
给土球球比心（）
感觉FE系统现在还是用的人少啊，不愧蝙蝠那一句苏联笑话2333
一脸懵逼的我来走了，正如我一脸懵逼的来了
RF能用的是什么能量系统呀
好像很厉害awa 话说哪里能玩到qaq
？为什么我没看懂这是个什么 是太硬核了吗
66666666666刷起来
66666666666刷起来
66666666666刷起来
lpokilpoki 发表于 2020-5-6 21:02
66666666666刷起来
66666666666刷起来
66666666666刷起来
6666666666666
感谢分享哇～
大佬nb66666
MCBBS有你更精彩~
1649367534 发表于 2020-5-3 13:34
求大佬告知用什么启动器可以玩
应该是hmcl
感谢大佬
MCBBS有你更精彩
呃！膜拜大佬!看得我一脸懵!
emmmmmmmmmmmmmm
E.T.星落辰 发表于 2020-5-4 12:53
给土球球比心（）
感觉FE系统现在还是用的人少啊，不愧蝙蝠那一句苏联笑话2333 ...
FE是电量单位吗？就像EU，RF一样
emmm.....虽然我看不懂，但看起来好厉害的样子
完全看不懂大佬发的代码....可能是因为我是小白的原因吧.
捕捉土球！
666666666666
mcbbs有你更精彩
MCBBS有你更精彩~
MCBBS有你更精彩~
MCBBS有你更精彩~
MCBBS有你们更精彩
666666666666666666666
感谢带佬的分享，，已阅
感觉很牛逼的样子 就是怕看都看不懂。。。
eeeeeeeeee.....
这是什么，
感觉好厉害
本帖最后由 友 于 2020-5-17 00:36 编辑
我想说个关于例子的错误。
AE2的管道从来不需要控制器。
我想说个关于例子的错误。
AE2的管道从来不需要控制器。
我学了好久 终于会了
啦啦啦啦啦啦啦啦
好像很厉害awa 话说哪里能玩到qaq
好评！高大上的样子！收藏了
感谢感谢
mcbbs有你更好了
RF能用的是什么能量系统呀
adasdsadassda
MCBBS有你更精彩~