自定义物品

《我的世界：Java版》支持基于原版物品创建“自定义”物品。在1.21.4及以上版本中，物品组件的加入进一步支持基于单个物品堆自定义物品行为，例如通过物品模型组件修改外观，以及调整物品的可食用、可装备等属性。

与Java版不同，基岩版原生支持添加不基于原版物品的自定义物品，但不支持扩展原版物品或修改原版物品的行为。因此，Geyser提供了一套映射系统，支持将基岩版自定义物品映射到修改后的Java版原版物品，还支持将基岩版自定义物品映射到Java版非原版模组物品（这类物品通常需要Java客户端安装对应模组才能使用）。

要在Geyser中配置自定义物品，你需要先选择物品的注册方式。最简单的方式是使用JSON映射文件，你也可以通过Geyser扩展程序调用Geyser API来实现。此外，你还必须提供一个基岩版资源包，以确保基岩版玩家能正常看到自定义物品。

警告

Geyser 不会自动转换Java版资源包，也不会自动生成自定义物品映射。不过你可以使用Rainbow等自动化工具简化内容转换流程。

信息

自 Geyser API 2.9.3 版本（Build #1062 及以上）起，旧版自定义物品格式（v1）已被弃用，不再进行更新。旧版文档仍可在此处查看。

自定义物品（v2）

Geyser 支持通过1.21.4及以上版本新增的item_model和物品组件特性进行物品映射。此前的custom-model-data方案仍可通过legacy定义继续使用。

但需要注意一些限制：与Java版不同，基岩版不支持在运行时动态修改物品属性（例如通过指令让泥土变得可食用）。针对这类场景，Geyser提供了谓词系统，支持注册多个拥有不同属性的基岩版自定义物品，分别映射到带有特定组件的不同物品堆。

工作原理

Java版的“自定义”物品，本质是基于原版物品修改了外观（1.21.4+使用物品模型实现，旧版本使用自定义模型数据实现）。

因此，所有基岩版自定义物品的映射定义，都必须基于Java版原版物品及其组件。同时，映射定义中可以指定额外的组件，来修改物品的行为。

前置知识：术语表

Java版物品：《我的世界：Java版》原版游戏中存在的任意物品。Java版数据包/插件可以通过重写Java版物品的组件来创建自定义物品。
Java版物品组件：自Java 1.21.4起，物品的属性与行为均通过物品组件定义。每个Java版物品都有一套默认组件，你可以重写这些组件来改变物品的外观与功能。
基岩版物品组件：与Java版类似，基岩版自定义物品也通过组件定义物品行为。但基岩版无法在运行时为物品堆修改这些组件，必须在基岩版客户端加入服务器时完成预定义。
Java版旧版自定义模型数据：Java 1.21.4之前使用的自定义物品系统。在1.21.4之前，每个“自定义物品”都对应一个自定义模型数据编号，用于决定Java版物品使用的模型（即给玩家展示不同的材质）。
Java版物品模型定义：Java 1.21.4新增的特性，存放于Java版资源包的assets/<命名空间>/items/目录下。这类配置用于设置Java版物品的外观，可通过一系列规则和物品属性动态修改。每个Java版物品都会在minecraft:item_model物品数据组件中存储其物品模型定义，数据包/插件可以基于单个物品堆重写该组件，使其使用资源包中定义的自定义物品模型。
自定义物品定义：Geyser的专用术语，指代一个基岩版自定义物品，用于映射对应的Java版物品模型定义，其中包含该物品在Java版与基岩版中的属性信息。同一个Java版物体模型定义可以对应多个自定义物体定义（即多个基岩版物体）；但对于Java版物体+物体模型定义的任意组合，无谓词的自定义物体定义只能有一个。
非原版自定义物体 definition：Geyser的专用术语，指代映射到Java版非原版（模组）物体的基岩版自定义物体。与普通自定义物体 definition 一样，其中包含该物体在Java版与基岩版中的属性信息。目前，一个Java版非原版物体只能对应一个非原版自定义物体 definition。

定义规则

每个自定义物品定义都对应一个基岩版自定义物品，该物品拥有一套预定义的基岩版配置，同时与一个特定的Java版物品+物品模型组合绑定（旧版物品则绑定Java版物品+自定义模型数据组合）。

必填定义属性

bedrock_identifier：自定义基岩版物品使用的标识符（也可用于基岩版资源包的可附加模型等场景），不可与其他任何自定义物品定义共用。该标识符不可使用minecraft命名空间；若未指定命名空间，默认使用geyser_custom。
model（JSON映射中legacy定义则使用custom_model_data）：必填项。

可选定义属性

display_name：字符串或JSON文本组件，用于设置物品的默认显示名称。若未设置，将从基岩版标识符自动生成。
bedrock_options：基岩版专属配置，用于指定物品额外的基岩版专属属性。
components：Java版物品组件，用于定义物品行为，例如最大堆叠数量。
predicate：谓词规则，用于将特定的自定义物品定义与物品堆进行匹配。
predicate_strategy：指定多个谓词的判定逻辑，仅在设置了谓词时生效。
priority：可选，为同一物品+物品模型组合的多个定义设置优先级，仅在存在多个自定义物品定义时生效。

定义方式：JSON 映射文件
定义方式：Geyser API

JSON映射文件必须将format_version设置为2，并在items键下列出所有物品的定义。items的值为一个对象，键为Java版物品ID，值为对象数组，用于指定该Java版物品对应的自定义物品定义。

mappings.json映射文件的结构示例：

{
    "format_version": 2,
    "items": {
        "minecraft:flint": [
            // 定义
        ],
        "minecraft:apple": [
            // 定义1
            // 定义2
        ],
        "minecraft:diamond": [
            // 定义
        ]
    }
}

自定义物品定义分为多种类型：

definition：单个自定义物品，为Java版物品模型定义创建映射。
legacy：单个自定义物品，为使用旧版自定义模型数据的Java版自定义物品创建映射。
group：一组自定义物品定义。定义的类型通过type键指定。

物品模型定义（1.21.4+）
分组定义
旧版定义（1.21.4之前版本）

{
    "type": "definition",
    "model": "example:example_model",
    "bedrock_identifier": "example:example_item"
}

definition类型用于为特定物品的item_model组件值创建映射定义，适用于1.21.4及以上版本。使用旧版custom_model_data格式的自定义物品，请使用legacy类型。

{
    "type": "group",
    "model": "example:example_model", // 可选，也可在子定义中单独设置
    "definitions": [...]
}

group定义代表一组自定义物品定义，可同时包含标准定义与旧版定义。若设置了组的Java版物品model定义，组内所有非旧版定义都会继承该模型；若组未设置模型，则组内所有定义必须自行指定物品模型。组内的定义也可以是一个分组，同时组内的定义可以重写组的Java版物品模型定义。

{
    "type": "legacy",
    "custom_model_data": 42,
    "bedrock_identifier": "example:example_item_legacy"
}

legacy定义适用于数据组件（以及item_models）加入之前的版本创建的自定义物品，必须指定custom_model_data浮点数值。

点击展开查看所有定义类型的示例

{
    "format_version": 2,
    "items": {
        "minecraft:flint": [
            {
                "type": "definition",
                "model": "geyser_mc:test_item",
                "bedrock_identifier": "geyser_mc:test_item",
                "display_name": "示例物品！",
                "bedrock_options": {
                    "icon": "potato",
                    "creative_category": "items"
                }
            },
            {
                "type": "legacy",
                "custom_model_data": 42,
                "bedrock_identifier": "geyser_mc:test_legacy_item",
                "display_name": "很旧的示例物品！",
                "bedrock_options": {
                    "icon": "cobweb"
                }
            },
            {
                "type": "group",
                "model": "geyser_mc:another_test_item",
                "definitions": [
                    {
                        "bedrock_identifier": "geyser_mc:another_test_item_nether",
                        "predicate": {
                            "type": "match",
                            "property": "context_dimension",
                            "value": "minecraft:the_nether"
                        },
                        "components": {
                            "minecraft:consumable": {
                                "animation": "drink",
                                "consume_seconds": 10
                            }
                        }
                    },
                    {
                        "bedrock_identifier": "geyser_mc:another_test_item",
                        "bedrock_options": {
                            "icon": "carrot"
                        },
                        "components": {
                            "minecraft:consumable": {
                                "animation": "drink",
                                "consume_seconds": 10
                            }
                        }
                    }
                ]
            }
        ]
    }
}

在本示例中，Java版物品minecraft:flint对应四个映射定义：

第一个是geyser_mc:test_item模型的“基础”定义。当Geyser检测到燧石物品的item_model组件设置为geyser_mc:test_item模型时，将始终使用该定义。
第二个是自定义模型数据值为42的“旧版”定义。当Geyser检测到燧石物品的floats列表中第一个浮点值为42时，将使用该定义。你可以通过以下指令获取该物品：/give @s flint[custom_model_data={floats:[42]}] 1
第三、第四个定义属于group类型，为带有geyser_mc:another_test_item物品模型的minecraft:flint物品，在不同条件下映射不同的定义。具体来说，第三个定义（基岩版标识符为geyser_mc:another_test_item_nether）会在玩家处于下界维度、维度谓词匹配时生效；否则将使用未指定谓词的第四个定义。

自定义物品定义通过GeyserDefineCustomItemsEvent进行注册。

@Subscribe
public void onGeyserDefineCustomItems(GeyserDefineCustomItemsEvent event) {
    event.register(Identifier.of("flint"), CustomItemDefinition.builder(
            Identifier.of("example:example_item_identifier"), // 必填：基岩版物品标识符
            Identifier.of("example:custom_item_model") // 必填：物品模型
        )
            // 以下均为可选配置
            .displayName("displayName")
            .bedrockOptions(...)
            .component(JavaItemDataComponents.MAX_STACK_SIZE, 60)
            .predicate(ItemRangeDispatchPredicate.count(32))
            .predicateStrategy(PredicateStrategy.OR)
            .priority(1)
            .build());
}

register方法接收两个参数：基础原版物品的标识符，以及一个CustomItemDefinition对象。后者必须通过CustomItemDefinition.Builder创建，且必须传入基岩版物品标识符与物品模型参数。

基岩版配置

该配置项用于设置物品在基岩版中、无法通过组件表达的专属属性，具体包括：

icon：物品使用的图标。若未设置，将使用物品的基岩版标识符。该值对应item_texture.json文件中定义的图标简称。

若使用物品的基岩版标识符作为图标值，会自动进行如下转换：
- : 替换为 .
- / 替换为 _
示例：geyser_mc:a_cool_item -> geyser_mc.a_cool_item。
allow_offhand：该自定义物品是否可手持/放入副手栏，默认为true。
display_handheld：物品是否以手持形式展示（例如工具、武器），默认为false。
protection_value：物品穿戴时显示的护甲保护点数。该属性仅为视觉效果，仅当物品可装备时生效，默认为0。
creative_category：设置物品的创造模式分类（也会在配方书中显示）。可选值：none（无）、construction（建筑）、nature（自然）、equipment（装备）、items（物品），默认为none。
creative_group：设置物品的创造模式分组（用于配方书）。可选值列表可参考此处。Geyser目前不支持创建自定义创造模式分组。
tags：设置物品的标签，可在资源包的Molang表达式中使用。

信息

如果你的合成配方输出为自定义物品，必须设置creative_category（可按需搭配creative_group），否则基岩版不会在配方书中显示该自定义物品的合成配方！

点击展开查看基岩版专属配置示例

JSON 映射文件
Geyser API

    "bedrock_options": {
        "icon": "example:chestplate", // 必须与item_texture.json中定义的简称匹配
        "protection_value": 4,
        "creative_category": "equipment",
        "creative_group": "itemGroup.name.chestplate",
        "tags": ["example:tag_one", "example:tag_two"]
    }

    "bedrock_options": {
        "icon": "example:my_sword", // 必须与item_texture.json中定义的简称匹配
        "display_handheld": true, // 通常仅为武器/工具开启
        "creative_category": "items",
        "creative_group": "itemGroup.name.sword",
        "tags": ["example:my_weapon"]
    }

在API中，基岩版物品配置通过CustomItemBedrockOptions#Builder定义，示例用法如下：

.bedrockOptions(CustomItemBedrockOptions.builder()
        .icon("example:chestplate")
        .protectionValue(4)
        .creativeCategory(CreativeCategory.EQUIPMENT)
        .creativeGroup("itemGroup.name.chestplate")
        .tags(Set.of(Identifier.of("example:tag_one"), Identifier.of("example:tag_two")))
    )

.bedrockOptions(CustomItemBedrockOptions.builder()
        .icon("example:my_sword")
        .displayHandheld(true)
        .creativeCategory(CreativeCategory.ITEMS)
        .creativeGroup("itemGroup.name.sword")
        .tag(Identifier.of("example:my_weapon"))
)

物品组件

Java版通过物品组件自定义物品的功能与行为，且支持在运行时为任意物品堆修改这些组件。但遗憾的是，基岩版不支持该特性。因此，对Java版基础物品数据组件的所有修改，都必须在映射文件中提前指定。

当自定义物品定义生效时，服务端必须始终向客户端发送该自定义物品对应的这些组件。若需要使用不同的组件组合，请创建多个带谓词的自定义物品定义。

信息

与基础Java版物品相比未做修改的组件，无需进行映射配置。

添加与修改组件

Geyser支持以下Java版物品组件（部分存在限制）：

minecraft:consumable：不支持消耗粒子/音效
minecraft:equippable：不支持相机覆盖与可交换属性
minecraft:food
minecraft:max_damage
minecraft:max_stack_size
minecraft:use_cooldown
minecraft:enchantable：在基岩版中会映射为slot=all的minecraft:enchantable组件，可兼容原版附魔，但不做保证；非原版附魔大概率无法正常工作
minecraft:tool
minecraft:repairable
minecraft:enchantment_glint_override
minecraft:attack_range：受基岩版限制，仅与minecraft:kinetic_weapon或minecraft:piercing_weapon组件搭配时生效
minecraft:kinetic_weapon
minecraft:piercing_weapon
minecraft:swing_animation：受基岩版限制，播放的动画为硬编码，仅可修改动画持续时长
minecraft:use_effects
- 受基岩版限制，无法转换can_sprint属性；且仅当基础物品可射箭、投掷抛射物或可食用（或通过食物组件设置为可食用）时，该组件才会被转换。

部分组件（如minecraft:rarity、minecraft:attribute_modifiers）已实现自动转换，无需手动列出。

所有物品组件的文档与对应JSON格式，可参考Minecraft Wiki的物品数据组件页面。

点击展开查看组件用法示例

JSON 映射文件
Geyser API

所有列出的组件均遵循数据包中使用的JSON结构，相关文档可在Minecraft Wiki查看。示例如下：

"components": {
    "minecraft:max_stack_size": 16,
    "minecraft:enchantment_glint_override": true
}

所有支持的组件均可在JavaItemDataComponents类中查看，通常通过建造者模式构建。

示例如下：

.component(JavaItemDataComponents.MAX_STACK_SIZE, 16)

.component(JavaItemDataComponents.ENCHANTMENT_GLINT_OVERRIDE, true)

移除默认组件

与Java版一致，你可以移除基础物品的默认组件（例如让苹果变得不可食用）。

点击展开查看组件移除用法示例

JSON 映射文件
Geyser API

在JSON映射中，只需在组件名称前添加!即可移除对应组件。

"components": {
    "!minecraft:food": {}
}

CustomItemDefinition#Builder支持通过传入物品数据组件标识符或组件类型，移除默认组件。

@Subscribe
public void onDefineCustomItems5(GeyserDefineCustomItemsEvent event) {
    event.register(Identifier.of("apple"), CustomItemDefinition.builder(
            Identifier.of("example:rotten_apple"), Identifier.of("example:rotten_apple")
        )
        .displayName("腐烂的苹果")
        .removeComponent(JavaItemDataComponents.FOOD)
        .build());
}

谓词

谓词用于告诉Geyser，对于Java版物品+物品模型的特定组合，应该使用哪个自定义物品定义。对于简单的旧版映射，或没有多个组件变体的自定义物品，无需使用谓词。

对于Java版物品+Java版物品模型定义的每一个组合，只能有一个无谓词的物品定义，以及一个或多个带谓词的定义。同一组合下，不能存在多个谓词完全相同的物品定义。若Java版物品模型定义位于 minecraft 命名空间下，则不能存在无谓词的物品定义。

信息

谓词也可设置取反，匹配相反的条件。

条件谓词

condition类型的谓词会检查布尔类型的属性，当属性与预期值匹配时返回true，支持5种属性：

broken：物品是否已损坏（仅剩1点耐久）
damaged：物品是否有损耗（耐久未满）
custom_model_data：检查物品自定义模型数据中，index键指定索引处的标志位，默认为false
has_component：物品是否拥有component键指定的组件（包含默认组件）
fishing_rod_cast：玩家是否正手持已抛出的钓鱼竿

点击展开查看用法示例

JSON 映射文件
Geyser API

所有条件谓词都必须将type设置为condition。

"predicate": {
    "type": "condition",
    "property": "broken"
}

"predicate": {
    "type": "condition",
    "property": "damaged"
}

"predicate": {
    "type": "condition",
    "property": "has_component",
    "component": "minecraft:unbreakable"
}

"predicate": {
    "type": "condition",
    "property": "custom_model_data",
    "index": 1
}

"predicate": {
    "type": "condition",
    "property": "fishing_rod_cast"
}

也可通过添加expected键并设置为false对谓词取反；未设置时，expected默认为true。示例：

"predicate": {
    "type": "condition",
    "property": "broken",
    "expected": false
}

所有条件谓词均可在ItemConditionPredicate接口中查看。示例：

.predicate(ItemConditionPredicate.FISHING_ROD_CAST)

部分谓词需要额外参数：

.predicate(ItemConditionPredicate.customModelData(1))
.predicate(ItemConditionPredicate.hasComponent(ItemDataComponents.REPAIRABLE.identifier()))

调用#negate()可对谓词取反：

.predicate(ItemConditionPredicate.DAMAGEABLE.negate())

匹配谓词

match类型的谓词会检查文本类属性，当属性与给定值匹配时返回true，支持4种属性：

charge_type：弩中当前装填的物品（来自minecraft:charged_projectiles组件），可选值arrow（箭）或rocket（烟花火箭）
trim_material：物品的盔甲纹饰材料（资源地址）
context_dimension：玩家当前所在的维度（资源地址）
custom_model_data：从物品自定义模型数据的字符串列表中获取对应值

match谓词必须在value键中指定匹配值。

点击展开查看用法示例

JSON 映射文件
Geyser API

所有匹配谓词都必须将type设置为match。

"predicate": {
    "type": "match",
    "property": "charge_type",
    "value": "arrow"
}

"predicate": {
    "type": "match",
    "property": "trim_material",
    "value": "minecraft:coast_armor_trim"
}

"predicate": {
    "type": "match",
    "property": "context_dimension",
    "value": "minecraft:the_end"
}

"predicate": {
    "type": "match",
    "property": "custom_model_data",
    "value": "MyString",
    "index": 1
}

也可通过添加expected键并设置为false对谓词取反；未设置时，expected默认为true。示例：

"predicate": {
    "type": "match",
    "property": "context_dimension",
    "value": "minecraft:the_end",
    "expected": false
}

物品匹配谓词可在ItemMatchPredicate接口中查看，通用匹配谓词可在MatchPredicate接口中查看。

示例：

.predicate(ItemMatchPredicate.chargeType(ChargedProjectile.ChargeType.ARROW));

.predicate(MatchPredicate.dimension(Identifier.of("the_end")));

范围调度谓词

range_dispatch类型的谓词会检查数值类型的属性，当数值大于等于指定阈值时返回true，支持4种类型：

bundle_fullness：检查物品的收纳袋填充度，返回收纳袋内所有物品的总权重（来自minecraft:bundle_contents组件）。
- 该属性不支持归一化！
damage：检查物品的损耗值，支持归一化
count：检查物品的堆叠数量，支持归一化
custom_model_data：检查物品自定义模型数据中，指定索引处的浮点值，默认为0.0。
- 该属性不支持归一化！

range_dispatch谓词有3个额外配置项：

threshold：判定为真的阈值，必填项
scale：与阈值比较前，对属性值进行缩放的系数，默认为1.0
normalize：缩放并与阈值比较前，是否对属性值进行归一化，默认为false，仅部分属性支持

点击展开查看用法示例

JSON 映射文件
Geyser API

"predicate": {
    "type": "range_dispatch",
    "property": "count",
    "threshold": 32
}

该谓词在物品堆叠数量大于等于32时判定为“真”。

"predicate": {
    "type": "range_dispatch",
    "property": "count",
    "normalize": true,
    "threshold": 0.5
}

该谓词在物品归一化堆叠数量（当前数量/最大堆叠数，取值范围0-1）大于等于0.5时判定为“真”。

"predicate": {
    "type": "range_dispatch",
    "property": "count",
    "threshold": 8,
    "scale": 2
}

该谓词在物品缩放后堆叠数量（当前数量 × 2）大于等于阈值时判定为“真”。

使用custom_model_data范围调度属性时，必须指定要检查的索引！索引从0开始，要检查浮点数列表的第一个元素，需将index设置为0：

"predicate": {
    "type": "range_dispatch",
    "property": "custom_model_data",
    "threshold": 3,
    "index": 0
}

范围调度谓词可在ItemRangeDispatchPredicate接口中查看。

CustomItemDefinition.builder(..., ...)
    .predicate(ItemRangeDispatchPredicate.count(32))
    .build();

该谓词在物品堆叠数量大于等于32时判定为“真”。

CustomItemDefinition.builder(..., ...)
    .predicate(ItemRangeDispatchPredicate.normalizedCount(0.5))
    .build();

该谓词在物品归一化堆叠数量（当前数量/最大堆叠数，取值范围0-1）大于等于0.5时判定为“真”。

CustomItemDefinition.builder(..., ...)
    .predicate(ItemRangeDispatchPredicate.customModelData(1, 12))
.build();

该谓词在custom_model_data组件的浮点数列表中，第二个索引处的值存在且大于等于12时判定为“真”。

如需对属性进行缩放，将阈值除以缩放系数即可。

多谓词的谓词策略

你可以通过predicate_strategy键设置多谓词的判定逻辑，可选值and（与）或or（或），默认为and。该设计参考了进度的条件判定策略，决定物品定义生效是需要满足所有谓词（and），还是仅需满足任意一个谓词（or）。

点击展开查看用法示例

JSON 映射文件
Geyser API

"predicate": [
    {
        "type": "match",
        "property": "context_dimension",
        "value": "minecraft:the_end"
    },
    {
        "type": "condition",
        "property": "broken"
    }
],
"predicate_strategy": "and"

该配置要求两个条件同时满足，对应的自定义物品定义才会生效。

.predicate(ItemConditionPredicate.BROKEN)
.predicate(MatchPredicate.dimension(Identifier.of("the_end")))
.predicateStrategy(PredicateStrategy.AND)

该配置要求两个条件同时满足，对应的自定义物品定义才会生效。

你也可以实现自定义谓词，但优先使用内置谓词，因为内置谓词支持正常的结果缓存。

信息

通过API指定多个谓词时，务必将所有谓词单独列出，并尽可能使用内置谓词。手动拼接谓词或创建自定义谓词，会导致Geyser无法缓存结果！

Details

错误写法：

    .predicate(ItemConditionPredicate.BROKEN.and(MatchPredicate.dimension(Identifier.of("the_end"))))

正确写法：

    .predicate(ItemConditionPredicate.BROKEN)
    .predicate(MatchPredicate.dimension(Identifier.of("the_end")))
    .predicateStrategy(PredicateStrategy.AND)

两种写法的判定结果一致，但只有后者的结果能被Geyser缓存。

排序与优先级

Geyser会自动对自定义物品定义进行排序，确保物品转换时按正确的顺序检查定义的谓词。

具体排序规则如下（优先级从高到低）：

优先级更高的自定义物品定义，排序更靠前
带有同类范围调度谓词的定义，按阈值从高到低排序
谓词数量更多的定义，排序更靠前

这套机制能保证绝大多数场景下，带谓词的物品定义都会按正确顺序被检查，与映射文件中的书写顺序无关。

极少数情况下（通常是使用多个range_dispatch谓词，或与其他谓词组合使用时），Geyser可能无法正确排序定义，此时可通过priority键手动指定定义的检查优先级。

若一个物品+物品模型组合仅对应一个自定义物品定义，无需设置优先级！

点击展开查看用法示例

JSON 映射文件
Geyser API

"priority": 5

.priority(5)

资源包

自定义物品必须搭配对应的基岩版资源包才能正常使用。Geyser不会自动生成资源包，也不会将Java版资源包转换为基岩版格式，因此你需要手动完成资源包的配置！你也可以尝试使用Rainbow或其他第三方转换工具简化流程。

创建自定义基岩版资源包

创建一个基础的基岩版资源包，并编写合法的manifest文件。如需帮助，可参考此处的教程。
创建textures文件夹。
在该文件夹中创建item_texture.json文件，写入以下基础内容：

{
  "resource_pack_name": "你的资源包名称",
  "texture_name": "atlas.items",
  "texture_data": {

  }
}

在texture_data中添加你的物品配置。材质名称与路径必须与映射文件中设置的基岩版标识符（和/或icon）匹配。例如，注册的基岩版标识符为example:yummy_food的物品，需要添加如下配置：

"example:yummy_food": {
    "textures": [
        "textures/items/yummy_food"
    ]
}

将物品材质文件放入textures/items文件夹，确保路径与item_texture.json中指定的材质路径完全匹配！

加载映射文件与资源包

本节内容默认你已完成Geyser的基础配置，基岩版玩家可正常加入服务器。此外，必须将Geyser配置文件中的enable-custom-content选项设置为true，自定义物品功能才能正常启用！

加载JSON映射文件
加载Geyser扩展程序

找到Geyser自动生成的custom_mappings文件夹。插件/模组版Geyser的该文件夹位于plugins/Geyser-[平台名]/custom_mappings（或config/Geyser-[平台名]/custom_mappings）；独立版Geyser的该文件夹位于根目录。
将映射JSON文件放入该文件夹，支持放入多个不同文件名的映射文件。
将基岩版资源包放入packs文件夹。
重启服务器。

将扩展jar文件放入extensions文件夹。插件/模组版Geyser的该文件夹位于plugins/Geyser-[平台名]/extensions（或config/Geyser-[平台名]/extensions）；独立版Geyser的该文件夹位于根目录。
若扩展程序附带资源包，将其放入Geyser的packs文件夹。
重启服务器。

完整示例

完整的Java版数据包+资源包，以及对应的Geyser映射文件、基岩版资源包，可在此处查看。

JSON 映射示例
代码示例

简单自定义食物物品映射

{
    "format_version": 2,
    "items": {
        "minecraft:flint": [
            {
                "type": "definition",
                "model": "geyser_mc:yummy_food",
                "bedrock_identifier": "geyser_mc:yummy_food",
                "display_name": "美味的食物！",
                "components": {
                    "minecraft:consumable": {},
                    "minecraft:food": {
                        "nutrition": 5,
                        "saturation": 0.0
                    },
                    "minecraft:max_stack_size": 16
                }
            }
        ]
    }
}

普通食物 - 分组与维度谓词示例

    {
        "format_version": 2,
        "items": {
            "minecraft:flint": [
                {
                    "type": "group",
                    "model": "geyser_mc:not_so_yummy_food",
                    "definitions": [
                        {
                            "bedrock_identifier": "geyser_mc:not_so_yummy_food",
                            "display_name": "普通食物",
                            "components": {
                                "minecraft:consumable": {
                                    "consume_seconds": 5.0
                                },
                                "minecraft:food": {
                                    "nutrition": 2,
                                    "saturation": 0.7
                                }
                            }
                        },
                        {
                            "bedrock_identifier": "geyser_mc:not_so_yummy_food_end",
                            "display_name": "普通食物",
                            "predicate": {
                                "type": "match",
                                "property": "context_dimension",
                                "value": "minecraft:the_end"
                            },
                            "components": {
                                "minecraft:consumable": {
                                    "consume_seconds": 5.0
                                },
                                "minecraft:food": {
                                    "nutrition": 2,
                                    "saturation": 0.7
                                }
                            }
                        }
                    ]
                }
            ]
        }
    }

魔法物品（带冷却的可消耗品）

    {
        "format_version": 2,
        "items": {
            "minecraft:flint": [
                {
                    "type": "definition",
                    "model": "geyser_mc:magic_item",
                    "bedrock_identifier": "geyser_mc:magic_item",
                    "display_name": "魔法物品",
                    "components": {
                        "minecraft:consumable": {
                            "consume_seconds": 0.05,
                            "animation": "none"
                        },
                        "minecraft:use_cooldown": {
                            "seconds": 5.0,
                            "cooldown_group": "geyser_mc:magic_item"
                        }
                    }
                }
            ]
        }
    }

燧石镐（损坏状态谓词）

    {
        "format_version": 2,
        "items": {
            "minecraft:flint": [
                {
                    "type": "group",
                    "model": "geyser_mc:flint_pickaxe",
                    "definitions": [
                        {
                            "bedrock_identifier": "geyser_mc:flint_pickaxe",
                            "display_name": "燧石镐",
                            "bedrock_options": {
                                "display_handheld": true
                            },
                            "components": {
                                "minecraft:max_damage": 10,
                                "minecraft:max_stack_size": 1
                            }
                        },
                        {
                            "bedrock_identifier": "geyser_mc:flint_pickaxe_broken",
                            "display_name": "燧石镐",
                            "bedrock_options": {
                                "display_handheld": true
                            },
                            "predicate": {
                                "type": "condition",
                                "property": "broken"
                            },
                            "components": {
                                "minecraft:max_damage": 10,
                                "minecraft:max_stack_size": 1
                            }
                        }
                    ]
                }
            ]
        }
    }

红羊毛胸甲（可装备护甲）

{
    "format_version": 2,
    "items": {
        "minecraft:flint": [
            {
                "type": "definition",
                "model": "geyser_mc:red_wool_chestplate",
                "bedrock_identifier": "geyser_mc:red_wool_chestplate",
                "display_name": "红羊毛胸甲",
                "bedrock_options": {
                    "protection_value": 5
                },
                "components": {
                    "minecraft:equippable": {
                        "slot": "chest"
                    },
                    "minecraft:max_stack_size": 1
                }
            }
        ]
    }
}

简单自定义食物物品映射

@Subscribe
public void onDefineCustomItems(GeyserDefineCustomItemsEvent event) {
    Identifier bedrockIdentifier = Identifier.of("geyser_mc:yummy_food");
    Identifier modelIdentifier = Identifier.of("geyser_mc:yummy_food");
    event.register(Identifier.of("flint"), CustomItemDefinition.builder(bedrockIdentifier, modelIdentifier)
        .displayName("美味食物！")
        .component(JavaItemDataComponents.CONSUMABLE, JavaConsumable.builder().build())
        .component(JavaItemDataComponents.FOOD, JavaFoodProperties.builder()
            .nutrition(5)
            .saturation(0)
            .build())
        .component(JavaItemDataComponents.MAX_STACK_SIZE, 16)
        .build());
}

普通食物 - 分组与维度谓词示例

@Subscribe
public void onDefineCustomItems(GeyserDefineCustomItemsEvent event) {
    Identifier modelIdentifier = Identifier.of("geyser_mc:not_so_yummy_food");
    event.register(Identifier.of("flint"), CustomItemDefinition.builder(Identifier.of("geyser_mc:not_so_yummy_food"), modelIdentifier)
        .displayName("普通食物")
        .component(JavaItemDataComponents.CONSUMABLE, JavaConsumable.builder()
            .consumeSeconds(5)
            .build())
        .component(JavaItemDataComponents.FOOD, JavaFoodProperties.builder()
            .nutrition(2)
            .saturation(0.7f)
            .build())
        .build());

    event.register(Identifier.of("flint"), CustomItemDefinition.builder(Identifier.of("geyser_mc:not_so_yummy_food_end"), modelIdentifier)
        .displayName("普通食物")
        .predicate(MatchPredicate.dimension(Identifier.of("the_end")))
        .component(JavaItemDataComponents.CONSUMABLE, JavaConsumable.builder()
            .consumeSeconds(5)
            .build())
        .component(JavaItemDataComponents.FOOD, JavaFoodProperties.builder()
            .nutrition(2)
            .saturation(0.7f)
            .build())
        .build());
}

魔法物品（带冷却的可消耗品）

@Subscribe
public void onDefineCustomItems3(GeyserDefineCustomItemsEvent event) {
    Identifier bedrockIdentifier = Identifier.of("geyser_mc:magic_item");
    Identifier modelIdentifier = Identifier.of("geyser_mc:magic_item");
    event.register(Identifier.of("flint"), CustomItemDefinition.builder(bedrockIdentifier, modelIdentifier)
        .displayName("魔法物品")
        .component(JavaItemDataComponents.CONSUMABLE, JavaConsumable.builder()
            .consumeSeconds(0.05f)
            .animation(JavaConsumable.Animation.NONE)
            .build())
        .component(JavaItemDataComponents.USE_COOLDOWN, JavaUseCooldown.builder()
            .seconds(5)
            .cooldownGroup(modelIdentifier)
            .build())
        .component(JavaItemDataComponents.MAX_STACK_SIZE, 16)
        .build());
}

燧石镐（损坏状态谓词）

@Subscribe
public void onDefineCustomItems4(GeyserDefineCustomItemsEvent event) {
    event.register(Identifier.of("flint"), CustomItemDefinition.builder(
            Identifier.of("geyser_mc:flint_pickaxe"), Identifier.of("geyser_mc:flint_pickaxe")
        )
        .displayName("燧石镐")
        .bedrockOptions(CustomItemBedrockOptions.builder()
            .displayHandheld(true)
        )
        .component(JavaItemDataComponents.MAX_DAMAGE, 10)
        .component(JavaItemDataComponents.MAX_STACK_SIZE, 1)
        .build());

    event.register(Identifier.of("flint"), CustomItemDefinition.builder(
            Identifier.of("geyser_mc:flint_pickaxe_broken"), Identifier.of("geyser_mc:flint_pickaxe")
        )
        .displayName("燧石镐")
        .bedrockOptions(CustomItemBedrockOptions.builder()
            .displayHandheld(true)
        )
        .predicate(ItemConditionPredicate.BROKEN)
        .component(JavaItemDataComponents.MAX_DAMAGE, 10)
        .component(JavaItemDataComponents.MAX_STACK_SIZE, 1)
        .build());
}

红羊毛胸甲（可装备护甲）

@Subscribe
public void onDefineCustomItems5(GeyserDefineCustomItemsEvent event) {
    event.register(Identifier.of("flint"), CustomItemDefinition.builder(
            Identifier.of("geyser_mc:red_wool_chestplate"), Identifier.of("geyser_mc:red_wool_chestplate")
        )
        .displayName("红羊毛胸甲")
        .bedrockOptions(CustomItemBedrockOptions.builder()
            .protectionValue(5)
        )
        .component(JavaItemDataComponents.EQUIPPABLE, JavaEquippable.of(JavaEquippable.EquipmentSlot.CHEST))
        .component(JavaItemDataComponents.MAX_STACK_SIZE, 1)
        .build());
}

非原版物品

Geyser还支持注册非原版物品（适用于Fabric/NeoForge等模组服务器），这类物品不基于原版物品，需要Java客户端安装对应模组才能正常使用。非原版物品必须通过API注册，不支持JSON映射文件。

示例：

event.register(NonVanillaCustomItemDefinition.builder(Identifier.of("hydraulic_test_mod:irauri_ingot"), 99)
    .component(JavaItemDataComponents.MAX_STACK_SIZE, 3)
    .component(JavaItemDataComponents.CONSUMABLE, JavaConsumable.builder()
        .consumeSeconds(2.5f)
        .animation(JavaConsumable.Animation.NONE)
        .build())
    .component(JavaItemDataComponents.USE_COOLDOWN, JavaUseCooldown.builder()
        .seconds(999999f)
        .cooldownGroup(Identifier.of("hydraulic_test_mod:irauri_says_fly"))
        .build())
    .build());

与原版自定义物品的核心区别如下：

必须在NonVanillaCustomItemDefinition#builder方法中传入网络传输使用的Java版物品ID
不支持谓词、谓词策略与优先级配置
非原版物品可使用额外的组件（原版物品的组件继承自基础原版物品）

GeyserItemDataComponent类包含了模组物品可用的所有额外组件：

chargeable：支持创建自定义射击物品
attack_damage：为物品添加攻击伤害的视觉指示器
block_placer：标记物品可放置方块
throwable：标记物品可投掷
projectile：将自定义物品标记为抛射物，可用于自定义射击物品
entity_placer：标记物品可放置实体

自定义物品（v2）​

工作原理​

前置知识：术语表​

定义规则​

必填定义属性​

可选定义属性​

基岩版配置​

物品组件​

添加与修改组件​

移除默认组件​

谓词​

条件谓词​

匹配谓词​

范围调度谓词​

多谓词的谓词策略​

排序与优先级​

资源包​

创建自定义基岩版资源包​

更多参考资料：​

加载映射文件与资源包​

完整示例​

非原版物品​

自定义物品（v2）

工作原理

前置知识：术语表

定义规则

必填定义属性

可选定义属性

基岩版配置

物品组件

添加与修改组件

移除默认组件

谓词

条件谓词

匹配谓词

范围调度谓词

多谓词的谓词策略

排序与优先级

资源包

创建自定义基岩版资源包

更多参考资料：

加载映射文件与资源包

完整示例

非原版物品