简介

由 Tech Reborn 团队开发的能源 API。

以 Jar in Jar 的形式内嵌提供，故无需独立安装。

以下内容翻译自 Github：

能源

一个 Fabric 上的能源 API，最初被用于 [TR] 科技复兴 (Tech Reborn)。

使用了 Fabric 的 Lookup API 和 Transaction API。

约定

为了确保使用此 API 的 Mod 之间能够良好地兼容，必须遵循以下约定。

• 能量值标准参考：

• 1x 煤炭 = 4000；

• 1x 木板 = 750。

• 基于被动输送实现的电网：

• 即电源负责将能量输送至机器；

• 而机器和线缆不应从电源索取能量。

将这个API添加至你的项目

最后发布的版本可以在这里找到。

在你的build.gradle的dependencies中添加如下内容

include modApi('teamreborn:energy:<版本>') {
    exclude(group: "net.fabricmc.fabric-api")
}

文档

这个 API 的功能围绕着 EnergyStorage 展开，请务必查阅文档。

以下是几个简单的使用案例。

实现储能方块接口

最简单的方法，但有容量和插入/拔出限制：

public class MyBlockEntity extends BlockEntity {    
    // 在方块实体中创建一个SimpleEnergyStorage
    // Store a SimpleEnergyStorage in the block entity class.
    public final SimpleEnergyStorage energyStorage = new SimpleEnergyStorage(CAPACITY, MAX_INSERT, MAX_EXTRACT) {        
        @Override
        protected void onFinalCommit() {
            markDirty();
        }
    };    
    // 在方块实体内部消耗能量，如在tick方法中。
    // Use the energy internally, for example in tick()
    public void tick() {        
        if (!world.isClient && energyStorage.amount >= 10) {
            energyStorage.amount -= 10;
            // 用我们刚刚消耗的10点能量做些什么。
            // do something with the 10 energy we just used.
            markDirty();
        }
    }    
    // 不要忘记保存/读取块状方块实体NBT中的能量。
    // Don't forget to save/read the energy in the block entity NBT.
}
// 不要忘记注册储能器，确保在你创建块状实体类型后调用这个。
// Don't forget to register the energy storage. Make sure to call this after you create the block entity type.
BlockEntityType<MyBlockEntity> MY_BLOCK_ENTITY;
EnergyStorage.SIDED.registerForBlockEntity((myBlockEntity, direction) -> myBlockEntity.energyStorage, MY_BLOCK_ENTITY);

可以在需要以侧面决定 I/O 状态时使用 SimpleSidedEnergyContainer。

如果你知道你在做什么，你也可以直接实现 EnergyStorage，但在大多数情况下这是没有必要的。

详情请参考本 API、Lookup API 和 Transaction API 的文档。

使用案例（方块）

获取一个储能器

@Nullable
EnergyStorage maybeStorage = EnergyStorage.SIDED.find(world, pos, direction)；

获取一个相邻的储能器

// 已知量。
// Known things
World world; BlockPos currentPos; Direction adjacentDirection；
// 获得相邻的能量存储，如果没有则为空。
// Get adjacent energy storage, or null if there is none
@Nullable
EnergyStorage maybeStorage = EnergyStorage.SIDED.find(world, currentPos.offset(applyDirection), adjacentDirection.getOpposite())；

在两个储能器之间转移能量

EnergyStorage source, target;
long amountMoved = EnergyStorageUtil.move(
        source, // 能量发送端 // from source
        target, // 能量接受端 // into target
        Long.MAX_VALUE, // 最大能量限制 // no limit on the amount
        null // 为这个操作创建一个新的transaction// create a new transaction for this operation 
);

尝试提取一个准确的能量值

EnergyStorage source；
long amountToUse；
// 打开一个transaction：如果操作没有达到预期效果，取消操作。
// Open a transaction: this allows cancelling the operation if it doesn't go as expected.
try (Transaction transaction = Transaction.openOuter() ) {
    // 尝试提取，将返回实际提取的数量。
    // Try to extract, will return how much was actually extracted.
    long amountExtracted = source.extract(amountToUse, transaction)；
    if (amountExtracted == amountToUse) {
        // "提交 "transaction，以确保变化被应用。
        // "Commit" the transaction to make sure the change is applied.
        transaction.commit()；
    } else {
        // 什么都不做就 "中止 "transaction，取消了更改。
        // Doing nothing "aborts" the transaction, cancelling the change.
    }
}

创建可充能物品

最简单创建一个可以被支持的 Mods 充能的物品的方法是在你的物品类上实现 SimpleEnergyItem，这些功能应该是不言自明的。

对于更复杂的物品，可以直接使用 EnergyStorage.ITEM。如果你选择这样做，请阅读 ContainerItemContext 的文档。

储能物品

看看你如何创建一个 ContainerItemContext，并使用它来查询一个带有 EnergyStorage.SIDED 的 EnergyStorage 实现。