Harbinger项目教程：利用Capability系统实现物品存储功能

前言

在Harbinger项目的开发中，物品存储系统是许多功能模块的基础。本文将详细介绍如何通过Forge的Capability系统为自定义方块实现物品存储功能，并以熔炉为例展示完整实现过程。

Capability系统概述

Capability系统是Forge提供的一套标准化接口机制，它允许不同的模组之间通过统一的接口进行交互。在物品存储方面，最常用的Capability是IItemHandler，它定义了物品存储和提取的标准方法。

基础实现

1. 创建物品处理器

首先我们需要在TileEntity中创建物品处理器实例：

private final ItemStackHandler inventory = new ItemStackHandler(2);

这里创建了一个包含2个槽位的物品处理器：

• 0号槽位：输入槽
• 1号槽位：输出槽

2. 实现Capability接口

TileEntity已经实现了ICapabilityProvider接口，我们只需重写两个关键方法：

@Override
public boolean hasCapability(Capability<?> cap, EnumFacing facing) {
    return cap == CapabilityItemHandler.ITEM_HANDLER_CAPABILITY 
        || super.hasCapability(cap, facing);
}

@Override
public <T> T getCapability(Capability<T> cap, EnumFacing facing) {
    if (cap == CapabilityItemHandler.ITEM_HANDLER_CAPABILITY) {
        return CapabilityItemHandler.ITEM_HANDLER_CAPABILITY.cast(this.inventory);
    }
    return super.getCapability(cap, facing);
}

3. 持久化存储

为了确保方块被卸载后数据不丢失，我们需要实现NBT数据的读写：

@Override
public void readFromNBT(NBTTagCompound tag) {
    super.readFromNBT(tag);
    this.inventory.deserializeNBT(tag.getCompoundTag("Inventory"));
}

@Override
public NBTTagCompound writeToNBT(NBTTagCompound tag) {
    tag.setTag("Inventory", this.inventory.serializeNBT());
    return super.writeToNBT(tag);
}

进阶功能实现

1. 输入输出控制

直接暴露ItemStackHandler会导致所有槽位都可被外部访问，我们需要通过包装器限制访问：

@Override
public <T> T getCapability(Capability<T> cap, EnumFacing facing) {
    if (cap == CapabilityItemHandler.ITEM_HANDLER_CAPABILITY) {
        return CapabilityItemHandler.ITEM_HANDLER_CAPABILITY.cast(new IItemHandler() {
            // 实现所有接口方法
            @Override
            public ItemStack insertItem(int slot, ItemStack stack, boolean simulate) {
                // 只允许向输入槽插入物品
                return slot == 0 ? inventory.insertItem(slot, stack, simulate) : stack;
            }
            
            @Override
            public ItemStack extractItem(int slot, int amount, boolean simulate) {
                // 只允许从输出槽提取物品
                return slot == 1 ? inventory.extractItem(slot, amount, simulate) : ItemStack.EMPTY;
            }
            // 其他方法实现...
        });
    }
    return super.getCapability(cap, facing);
}

2. 物品掉落处理

当方块被破坏时，我们需要确保物品栏中的物品正确掉落：

@Override
public void breakBlock(World world, BlockPos pos, IBlockState state) {
    TileEntity tile = world.getTileEntity(pos);
    if (tile instanceof MyLavaFurnaceEntity) {
        ItemStackHandler handler = ((MyLavaFurnaceEntity) tile).inventory;
        for (int i = 0; i < handler.getSlots(); i++) {
            ItemStack stack = handler.getStackInSlot(i);
            if (!stack.isEmpty()) {
                InventoryHelper.spawnItemStack(world, pos.getX(), pos.getY(), pos.getZ(), stack);
            }
        }
    }
    super.breakBlock(world, pos, state);
}

实际应用示例

在我们的熔炉实现中，物品处理逻辑如下：

@Override
public void update() {
    if (!world.isRemote) {
        // 自动收集上方可熔炼物品
        if (inventory.getStackInSlot(0).isEmpty()) {
            for (EntityItem entity : world.getEntitiesWithinAABB(EntityItem.class, new AxisAlignedBB(pos.up()))) {
                ItemStack result = FurnaceRecipes.instance().getSmeltingResult(entity.getItem());
                if (!result.isEmpty()) {
                    entity.setItem(inventory.insertItem(0, entity.getItem(), false));
                    break;
                }
            }
        }
        
        // 熔炼过程
        if (!inventory.getStackInSlot(0).isEmpty() && fuel > 0) {
            fuel--;
            progress++;
            if (progress > 200) { // 完成熔炼
                ItemStack result = FurnaceRecipes.instance().getSmeltingResult(inventory.getStackInSlot(0));
                inventory.insertItem(1, result, false);
                inventory.extractItem(0, 1, false); // 消耗原料
                progress = 0;
            }
        }
    }
}

最佳实践建议

1. 线程安全：确保对物品栏的所有操作都在服务端进行
2. 性能优化：避免在update()方法中进行不必要的物品栏操作
3. 数据一致性：所有修改物品栏的操作都应考虑NBT同步
4. 异常处理：对可能失败的操作(如insertItem)进行适当处理

通过本文的介绍，你应该已经掌握了在Harbinger项目中使用Capability系统实现物品存储功能的核心方法。这种实现方式不仅标准规范，还能与其他模组良好兼容。