AspectList

基本信息

项目	值
来源	`thaumcraft.api.aspects.AspectList`
包	`thaumcraft.api.aspects`
继承	`Serializable`

概述

AspectList 是一个用于存储元素（Aspect）及其数量的容器类。它实现了 Serializable 接口，可以序列化和反序列化到 NBT。

内部使用 LinkedHashMap<Aspect, Integer> 存储元素集合。

构造函数

构造函数	说明
`AspectList()`	创建一个空的元素列表
`AspectList(ItemStack stack)`	根据物品栈的元素信息创建列表

核心方法

元素查询

方法	返回值	说明
`getAspects()`	`Aspect[]`	获取所有元素数组
`getPrimalAspects()`	`Aspect[]`	仅获取基础元素
`getAspectsSorted()`	`Aspect[]`	按名称排序的元素数组
`getAspectsSortedAmount()`	`Aspect[]`	按数量排序的元素数组
`getAmount(Aspect key)`	`int`	获取指定元素的数量

元素操作

方法	返回值	说明
`add(Aspect aspect, int amount)`	`AspectList`	添加元素（累加数量）
`merge(Aspect aspect, int amount)`	`AspectList`	添加元素（取最大值）
`add(AspectList in)`	`AspectList`	合并另一个列表（累加）
`merge(AspectList in)`	`AspectList`	合并另一个列表（取大）
`reduce(Aspect key, int amount)`	`boolean`	减少元素数量
`remove(Aspect key, int amount)`	`AspectList`	移除指定数量，为0则删除
`remove(Aspect key)`	`AspectList`	完全移除该元素

统计方法

方法	返回值	说明
`size()`	`int`	不同元素种类的数量
`visSize()`	`int`	所有元素的总数量

序列化方法

方法	说明
`readFromNBT(NBTTagCompound)`	从 NBT 读取（使用 “Aspects” 标签）
`readFromNBT(NBTTagCompound, String label)`	从 NBT 读取（使用指定标签）
`writeToNBT(NBTTagCompound)`	写入 NBT（使用 “Aspects” 标签）
`writeToNBT(NBTTagCompound, String label)`	写入 NBT（使用指定标签）

其他

方法	返回值	说明
`copy()`	`AspectList`	深拷贝列表

NBT 存储格式

元素以 NBT List 格式存储，每个元素是一个 Compound：

Aspects: [
  { key: "aer", amount: 10 },
  { key: "ignis", amount: 5 }
]

代码示例

// 创建并添加元素
AspectList aspects = new AspectList();
aspects.add(Aspect.AIR, 10);
aspects.add(Aspect.FIRE, 5);

// 合并列表
AspectList other = new AspectList();
other.add(Aspect.AIR, 3);
aspects.merge(other);  // AIR 变为 10 和 3 的最大值 = 10

// 序列化到 NBT
NBTTagCompound nbt = new NBTTagCompound();
aspects.writeToNBT(nbt);

// 从 NBT 读取
AspectList loaded = new AspectList();
loaded.readFromNBT(nbt);

与 IAspectContainer 的区别

AspectList 是纯数据容器，用于存储元素集合
IAspectContainer 是接口，定义方块实体如何与元素交互

INode 等继承自 IAspectContainer 的类也可以转换为 AspectList。