数据映射(Data Maps)

数据映射(Data Map)包含可数据驱动的、可重载的对象，这些对象可以附加到已注册的对象上。该系统允许更容易地数据驱动游戏行为，因为它们提供了诸如同步或冲突解决等功能，从而带来更好且更可配置的用户体验。你可以将标签(Tag)视为注册表对象 ➜ 布尔值映射，而数据映射则是更灵活的注册表对象 ➜ 对象映射。与标签类似，数据映射会添加到其对应的数据映射中，而不是覆盖。

数据映射可以附加到静态的、内置的注册表，也可以附加到动态的、数据驱动的数据包注册表。数据映射支持通过使用 /reload 命令或任何其他重新加载服务器资源的方式进行重载。

NeoForge 为常见用例提供了多种内置数据映射(Built-in Data Maps)，用以替代硬编码的原版字段。更多信息可以在链接的文章中找到。

文件位置(File Location)

数据映射从位于 <mapNamespace>/data_maps/<registryNamespace>/<registryPath>/<mapPath>.json 的 JSON 文件加载，其中：

• <mapNamespace> 是数据映射 ID 的命名空间，
• <mapPath> 是数据映射 ID 的路径，
• <registryNamespace> 是注册表 ID 的命名空间（如果是 minecraft 则可省略），以及
• <registryPath> 是注册表 ID 的路径。

示例：

• 对于 minecraft:item 注册表的数据映射 mymod:drop_healing（如下例所示），路径将为 mymod/data_maps/item/drop_healing.json。
• 对于 minecraft:block 注册表的数据映射 somemod:somemap，路径将为 somemod/data_maps/block/somemap.json。
• 对于 somemod:custom 注册表的数据映射 example:stuff，路径将为 example/data_maps/somemod/custom/stuff.json。

JSON 结构(JSON Structure)

数据映射文件本身可能包含以下字段：

• replace：一个布尔值，将在添加此文件的值之前清除数据映射。模组永远不应提供此字段，它仅供希望为自己的目的覆盖此映射的资源包开发者使用。
• neoforge:conditions：加载条件(Loading Condition)的列表。
• values：注册表 ID 或标签 ID 到应由此模组添加到数据映射的值的映射。值本身的结构由数据映射的编解码器(Codec)定义（见下文）。
• remove：要从数据映射中移除的注册表 ID 或标签 ID 的列表。

添加值(Adding Values)

例如，假设我们有一个数据映射对象，它具有两个浮点数键 amount 和 chance，针对注册表 minecraft:item。相应的数据映射文件可能如下所示：

{
    "values": {
        // 将一个值附加到胡萝卜物品
        "minecraft:carrot": {
            "amount": 12,
            "chance": 1
        },
        // 将一个值附加到 logs 标签中的所有物品
        "#minecraft:logs": {
            "amount": 1,
            "chance": 0.1
        }
    }
}

数据映射可能支持合并器(Merger)，这会导致在冲突时（例如，如果两个模组为同一个物品添加了数据映射值）触发自定义合并行为。为了避免触发合并器，我们可以在元素级别指定 replace 字段，如下所示：

{
    "values": {
        // 覆盖胡萝卜物品的值
        "minecraft:carrot": {
            "replace": true,
            // 新值将位于 value 子对象下
            "value": {
                "amount": 12,
                "chance": 1
            }
        }
    }
}

移除现有值(Removing Existing Values)

可以通过指定要移除的物品 ID 或标签 ID 列表来移除元素：

{
    // 我们不希望马铃薯拥有值，即使另一个模组的数据映射添加了它
    "remove": [
        "minecraft:potato"
    ]
}

移除操作在添加操作之后运行，因此我们可以包含一个标签，然后再次从中排除某些元素：

{
    "values": {
        "#minecraft:logs": { /* ... */ }
    },
    // 再次排除绯红菌柄
    "remove": [
        "minecraft:crimson_stem"
    ]
}

数据映射可能支持带有额外参数的自定义移除器(Remover)。要提供这些，可以将 remove 列表转换为一个 JSON 对象，其中包含待移除的元素作为映射键，额外数据作为关联值。例如，假设我们的移除器对象被序列化为一个字符串，那么我们的移除器映射可能如下所示：

{
    "remove": {
        // 移除器将从值（在此例中为 `somekey1`）反序列化，
        // 并应用于附加到胡萝卜物品的值
        "minecraft:carrot": "somekey1"
    }
}

自定义数据映射(Custom Data Maps)

首先，我们定义数据映射条目的格式。数据映射条目必须是不可变的(Immutable)，因此记录(Record)是理想的选择。重申我们上面具有两个浮点值 amount 和 chance 的例子，我们的数据映射条目将如下所示：

public record ExampleData(float amount, float chance) {}

与许多其他事物一样，数据映射使用编解码器(Codec)进行序列化和反序列化。这意味着我们需要为我们的数据映射条目提供一个编解码器，稍后将使用它：

public record ExampleData(float amount, float chance) {
    public static final Codec<ExampleData> CODEC = RecordCodecBuilder.create(instance -> instance.group(
            Codec.FLOAT.fieldOf("amount").forGetter(ExampleData::amount),
            Codec.floatRange(0, 1).fieldOf("chance").forGetter(ExampleData::chance)
    ).apply(instance, ExampleData::new));
}

接下来，我们创建数据映射本身：

// 在这个例子中，我们为 minecraft:item 注册表注册数据映射，因此我们使用 Item 作为泛型。
// 如果你想为不同的注册表创建数据映射，请相应地调整类型。
public static final DataMapType<Item, ExampleData> EXAMPLE_DATA = DataMapType.builder(
        // 数据映射的 ID。此数据映射的数据映射文件将位于
        // <yourmodid>:examplemod/data_maps/item/example_data.json。
        ResourceLocation.fromNamespaceAndPath("examplemod", "example_data"),
        // 要为其注册数据映射的注册表。
        Registries.ITEM,
        // 数据映射条目的编解码器。
        ExampleData.CODEC
).build();

最后，在模组事件总线(Mod Event Bus)上的 RegisterDataMapTypesEvent 期间注册数据映射：

@SubscribeEvent // 在模组事件总线上
public static void registerDataMapTypes(RegisterDataMapTypesEvent event) {
    event.register(EXAMPLE_DATA);
}

同步(Syncing)

同步的数据映射将把它们的值同步到客户端。可以通过在构建器上调用 #synced 来标记数据映射为同步，如下所示：

public static final DataMapType<Item, ExampleData> EXAMPLE_DATA = DataMapType.builder(...)
        .synced(
                // 用于同步的编解码器。可能与普通编解码器相同，但也可能是
                // 包含较少字段的编解码器，省略客户端不需要的对象部分。
                ExampleData.CODEC,
                // 数据映射是否为强制的。将数据映射标记为强制将使缺少该数据映射的客户端断开连接；
                // 这包括原版客户端。
                false
        ).build();

使用(Usage)

由于数据映射可以用于任何注册表，必须通过 Holder 查询，而不是通过实际的注册表对象。而且，它只适用于引用持有者(Reference Holder)，不适用于 Direct 持有者。但是，大多数地方都会返回一个引用持有者，例如 Registry#wrapAsHolder、Registry#getHolder 或不同的 builtInRegistryHolder 方法，因此在大多数情况下这应该不是问题。

然后，你可以通过 Holder#getData(DataMapType) 查询数据映射值。如果一个对象没有附加数据映射值，该方法将返回 null。重用我们之前的 ExampleData，让我们使用它们在玩家拾取它们时治疗玩家：

@SubscribeEvent // 在游戏事件总线上
public static void itemPickup(ItemEntityPickupEvent.Post event) {
    ItemStack stack = event.getItemStack();
    // 通过 ItemStack#getItemHolder 获取 Holder<Item>。
    Holder<Item> holder = stack.getItemHolder();
    // 从持有者获取数据。
    ExampleData data = holder.getData(EXAMPLE_DATA);
    if (data != null) {
        // 值存在，所以让我们用它们做点什么！
        Player player = event.getPlayer();
        if (player.getLevel().getRandom().nextFloat() > data.chance()) {
            player.heal(data.amount());
        }
    }
}

这个过程当然也适用于 NeoForge 提供的所有数据映射。

高级数据映射(Advanced Data Maps)

高级数据映射是使用 AdvancedDataMapType 而不是标准 DataMapType（AdvancedDataMapType 是其子类）的数据映射。它们具有一些额外功能，即能够指定自定义合并器和自定义移除器。对于值类似集合的数据映射，例如 List 或 Map，强烈建议实现此功能。

虽然 DataMapType 有两个泛型 R（注册表类型）和 T（数据映射值类型），但 AdvancedDataMapType 还有一个：VR extends DataMapValueRemover<R, T>。这个泛型允许通过数据生成(Datagen)以类型安全的方式生成移除器。

AdvancedDataMapType 使用 AdvancedDataMapType#builder() 而不是 DataMapType#builder() 创建，返回一个 AdvancedDataMapType.Builder。此构建器有两个额外的方法 #remover 和 #merger，分别用于指定移除器和合并器（见下文）。所有其他功能，包括同步，保持不变。

合并器(Mergers)

合并器可用于处理多个尝试为同一对象添加值的数据包之间的冲突。默认合并器(DataMapValueMerger#defaultMerger) 将用新值覆盖现有值（例如来自优先级较低的数据包），因此如果这不是期望的行为，则需要自定义合并器。

合并器将获得两个冲突的值，以及值附加到的对象（作为 Either<TagKey<R>, ResourceKey<R>>，因为值可以附加到标签中的所有对象或单个对象）和对象所属的注册表，并应返回实际应附加的值。通常，合并器应简单地合并，并在可能的情况下不执行覆盖（即，仅当正常合并方式无效时）。如果数据包想要绕过合并器，它应在对象上指定 replace 字段（参见添加值）。

让我们想象一个场景，我们有一个将整数添加到物品的数据映射。然后我们可以通过添加两个值来简单地解决冲突，如下所示：

public class IntMerger implements DataMapValueMerger<Item, Integer> {
    @Override
    public Integer merge(Registry<Item> registry,
            Either<TagKey<Item>, ResourceKey<Item>> first, Integer firstValue,
            Either<TagKey<Item>, ResourceKey<Item>> second, Integer secondValue) {
        return firstValue + secondValue;
    }
}

这样，如果一个包为 minecraft:carrot 指定值 12，另一个包为 minecraft:carrot 指定值 15，那么 minecraft:carrot 的最终值将是 27。如果这些对象中的任何一个指定了 "replace": true，则将使用该对象的值。如果两者都指定了 "replace": true，则使用优先级更高的数据包的值。

最后，别忘了在构建器中实际指定合并器，如下所示：

// 数据映射的类型必须与合并器的类型匹配。
AdvancedDataMapType<Item, Integer> ADVANCED_MAP = AdvancedDataMapType.builder(...)
        .merger(new IntMerger())
        .build();

提示

NeoForge 在 DataMapValueMerger 中为列表、集合和映射提供了默认合并器。

移除器(Removers)

类似于用于更复杂数据的合并器，移除器可以用于正确处理元素的 remove 子句。默认移除器(DataMapValueRemover.Default.INSTANCE) 将简单地移除与指定对象相关的任何和所有信息，因此我们想要使用自定义移除器来仅移除对象数据的部分。

传递给构建器的编解码器（继续阅读）将用于解码移除器实例。然后移除器将接收到当前附加到对象的值及其来源，并应返回一个 Optional，其中包含要替换旧值的值。或者，返回空的 Optional 将导致该值被实际移除。

考虑以下移除器的示例，该移除器将从基于 Map<String, String> 的数据映射中移除具有特定键的值：

public record MapRemover(String key) implements DataMapValueRemover<Item, Map<String, String>> {
    public static final Codec<MapRemover> CODEC = Codec.STRING.xmap(MapRemover::new, MapRemover::key);
    
    @Override
    public Optional<Map<String, String>> remove(Map<String, String> value, Registry<Item> registry, Either<TagKey<Item>, ResourceKey<Item>> source, Item object) {
        final Map<String, String> newMap = new HashMap<>(value);
        newMap.remove(key);
        return Optional.of(newMap);
    }
}

考虑到这个移除器，请查看以下数据文件：

{
    "values": {
        "minecraft:carrot": {
            "somekey1": "value1",
            "somekey2": "value2"
        }
    }
}

现在，考虑这第二个数据文件，它被放置在比第一个文件更高的优先级：

{
    "remove": {
        // 由于移除器被解码为字符串，我们可以在此处使用字符串作为值。
        // 如果它被解码为一个对象，我们将需要使用一个对象。
        "minecraft:carrot": "somekey1"
    }
}

这样，在两个文件都应用之后，最终结果将是（内存中的表示）这样的：

{
    "values": {
        "minecraft:carrot": {
            "somekey2": "value2"
        }
    }
}

与合并器一样，别忘了将它们添加到构建器中。注意我们在这里只使用编解码器：

// 我们假设 AdvancedData 包含某种 Map<String, String> 属性。
AdvancedDataMapType<Item, AdvancedData> ADVANCED_MAP = AdvancedDataMapType.builder(...)
        .remover(MapRemover.CODEC)
        .build();

数据生成(Data Generation)

可以通过扩展 DataMapProvider 并覆盖 #gather 来创建条目，从而数据生成数据映射。重用我们之前的 ExampleData（具有浮点值 amount 和 chance），我们的数据生成文件可能如下所示：

public class MyDataMapProvider extends DataMapProvider {
    public MyDataMapProvider(PackOutput packOutput, CompletableFuture<HolderLookup.Provider> lookupProvider) {
        super(packOutput, lookupProvider);
    }
    
    @Override
    protected void gather() {
        // 我们为 EXAMPLE_DATA 数据映射创建一个构建器，并使用 #add 添加我们的条目。
        this.builder(EXAMPLE_DATA)
                // 我们开启替换(replace)。永远不要像这样发布模组！这纯粹是为了教育目的。
                .replace(true)
                // 我们为所有台阶添加值 "amount": 10, "chance": 1。布尔参数控制
                // "replace" 字段，在模组中应始终为 false。
                .add(ItemTags.SLABS, new ExampleData(10, 1), false)
                // 我们为苹果添加值 "amount": 5, "chance": 0.2。
                .add(Items.APPLE.builtInRegistryHolder(), new ExampleData(5, 0.2f), false) // 也可以使用 Registry#wrapAsHolder 来获取注册表对象的持有者
                // 我们再次移除木质台阶。
                .remove(ItemTags.WOODEN_SLABS)
                // 我们为植物魔法(Botania)添加一个模组加载条件，为什么不呢。
                .conditions(new ModLoadedCondition("botania"));
    }
}

这将生成以下 JSON 文件：

{
    "replace": true,
    "values": {
        "#minecraft:slabs": {
            "amount": 10,
            "chance": 1.0
        },
        "minecraft:apple": {
            "amount": 5,
            "chance": 0.2
        }
    },
    "remove": [
        "#minecraft:wooden_slabs"
    ],
    "neoforge:conditions": [
        {
            "type": "neoforge:mod_loaded",
            "modid": "botania"
        }
    ]
}

像所有数据提供器一样，别忘了将提供器添加到事件中：

@SubscribeEvent // 在模组事件总线上
public static void gatherData(GatherDataEvent.Client event) {
    // 如果要添加数据包对象，请首先调用 event.createDatapackRegistryObjects(...)

    event.createProvider(MyDataMapProvider::new);
}