跳到主要内容

自定义物品

Minecraft: Java Edition 支持创建基于原版物品的"自定义"物品。通过 Minecraft 1.21.4+，引入的物品组件进一步允许在每个物品堆栈的基础上自定义物品行为，例如使用物品模型组件更改视觉外观，以及修改物品属性（如吃东西或装备物品的能力）。

与 Java Edition 不同，Bedrock 原生支持添加不基于原版物品的自定义物品。但是，Bedrock 不支持扩展原版物品或修改原版物品行为。因此，Geyser 有一个映射系统，允许将自定义 Bedrock 物品映射到修改后的原版 Java 物品。Geyser 还支持将自定义 Bedrock 物品映射到模组非原版物品，这些物品通常需要在 Java 客户端上安装模组。

要在 Geyser 中设置自定义物品，你需要选择注册物品的方式。最简单的方式是使用 JSON 映射文件，但你也可以使用使用 Geyser API 的 Geyser 扩展。此外，还必须提供 Bedrock 版资源包，以确保 Bedrock 玩家可以看到自定义物品。

注意

Geyser 不会转换 Java Edition 的资源包，也不会自动生成自定义物品映射。 但是，你可以使用自动化工具（如 Rainbow）来简化内容转换。

信息

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

自定义物品 (v2)​

Geyser 支持使用 1.21.4+ 引入的 item_model 和物品组件功能映射物品。之前的 custom-model-data 方法继续受支持，使用 legacy 定义。 但是，有一些注意事项。与 Java Edition 不同，Bedrock Edition 不支持在运行时动态修改物品属性（例如使用命令使泥土可食用）。 对于此类用例，Geyser 支持谓词系统，允许注册具有不同属性的多个自定义 Bedrock 物品，以映射到具有特定组件的不同物品堆栈。

工作原理​

Java Edition 中的"自定义"物品基于原版物品，使用修改后的外观（1.21.4+ 使用物品模型，或旧版本使用自定义模型数据）。 因此，所有映射的 Bedrock 自定义物品定义都基于原版 Java 物品及其组件。此外，映射的定义可以指定额外的组件来修改物品的行为。

先决条件：词汇表​

  • Java 物品：存在于 Minecraft: Java Edition 基础游戏中的任何原版物品。Java 数据包/插件可以通过覆盖 Java 物品的组件来创建自定义物品。
  • Java 物品组件：自 1.21.4+ 起，Java Edition 中的物品使用物品组件定义其属性和行为。 每个 Java 物品都有一组默认组件，可以覆盖这些组件以更改物品的外观或功能。
  • Bedrock 物品组件：自定义 Bedrock 物品也有决定物品行为的组件，类似于 Java Edition。 但是，这些组件不能为物品堆栈在运行时更改，必须在 Bedrock 客户端加入时预先定义。
  • Java legacy 自定义模型数据：1.21.4 之前使用的系统。在 1.21.4 之前，每个"自定义物品"都有一个自定义模型数据数字， 用于决定 Java 物品应使用哪个模型（= 玩家的不同纹理）。
  • Java 物品模型定义：在 Java 1.21.4 中引入，位于 Java 资源包的 assets/<namespace>/items/ 目录中。 这些纹理用于设置 Java 物品的外观，并且可以使用一组规则和物品属性动态更改。 每个 Java 物品将其物品模型定义存储在 minecraft:item_model 物品数据组件中。可以通过数据包/插件在每个物品堆栈的基础上覆盖它，以使用资源包中定义的自定义物品模型定义。
  • 自定义物品定义：自定义物品定义是 Geyser 的一个术语。它表示用于映射 Java 物品模型定义的单个 Bedrock 自定义物品。它包含物品在 Java 和 Bedrock 上的属性信息。 对于同一个 Java 物品模型定义，可以存在多个自定义物品定义，但对于 Java 物品和 Java 物品模型定义的每种组合，没有谓词的自定义物品定义只能有一个。
  • 非原版自定义物品定义：也是一个 Geyser 术语。表示映射 Java 非原版（模组）物品的 Bedrock 自定义物品。与普通自定义物品定义一样，它包含物品在 Java 和 Bedrock 上的属性信息。 目前，每个 Java 非原版物品只能有一个非原版自定义物品定义。

定义​

每个自定义物品定义代表一个具有一组预定义 Bedrock 选项的自定义 Bedrock 物品。 它绑定到特定的 Java 物品 + 物品模型组合（或者，对于 legacy 物品，绑定到特定的 Java 物品 + 自定义模型数据组合）。

必需的定义属性​

  • bedrock_identifier：此标识符用于自定义 Bedrock 物品（也在 Bedrock 资源包中的 attachables 等中使用），不能与任何其他自定义物品定义共享。 此标识符不能在 minecraft 命名空间中。如果没有提供命名空间，则使用 geyser_custom。
  • model（对于 JSON 映射中的 legacy 定义为 custom_model_data）也是必需的。

可选的定义属性​

  • display_name：一个字符串，或物品默认显示名称的 json 文本组件。如果未设置，则从 Bedrock 标识符派生。
  • bedrock_options：指定额外 Bedrock 属性的 bedrock options
  • components：指定物品行为的 Java 物品组件，例如最大堆叠数量。
  • predicate：用于将特定自定义物品定义匹配到物品堆栈的谓词。
  • predicate_strategy：指定如何评估多个谓词。仅在指定谓词时使用。
  • priority：可选地指定定义相对于同一物品 + 物品模型组合的其他定义的优先级。仅在有多个自定义物品定义时使用。

Json 映射文件必须指定 format_version 设置为 2，并在 items 键下列出每个物品的所有定义。它持有一个对象，其中键是 Java 物品，每个值是一个对象数组， 指定该 Java 物品的自定义物品定义。

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

{
    "format_version": 2,
    "items": {
        "minecraft:flint": [
            // definition
        ],
        "minecraft:apple": [
            // definition1,
            // definition2
        ],
        "minecraft:diamond": [
            // definition
        ]
    }
}

自定义物品定义有多种类型：

  • definition：为 Java 物品模型定义的一个自定义物品。
  • legacy：为使用 legacy 自定义模型数据数字的 Java 自定义物品的一个自定义物品。
  • group：自定义物品定义的组。 定义的类型在 type 键中定义。
{
    "type": "definition",
    "model": "example:example_model",
    "bedrock_identifier": "example:example_item"
}

definition 类型用于为特定物品的 item_model 组件值映射一个定义。 这应用于 1.21.4+ 及以上版本。对于使用 legacy custom_model_data 格式的自定义物品， 请使用 legacy 类型。

展开查看所有定义类型的示例
{
    "format_version": 2,
    "items": {
        "minecraft:flint": [
            {
                "type": "definition",
                "model": "geyser_mc:test_item",
                "bedrock_identifier": "geyser_mc:test_item",
                "display_name": "An Example Item!",
                "bedrock_options": {
                    "icon": "potato",
                    "creative_category": "items"
                }
            },
            {
                "type": "legacy",
                "custom_model_data": 42,
                "bedrock_identifier": "geyser_mc:test_legacy_item",
                "display_name": "A Very Old Item!",
                "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 的"legacy"定义。因此，如果 Geyser 遇到 floats 列表中第一个浮点值设置为 42 的燧石物品，它将使用第二个定义。 此类物品可以使用以下命令获取：/give @s flint[custom_model_data={floats:[42]}] 1
  • 第三个和第四个定义是 group 类型的一部分，将多个定义映射到 minecraft:flint 物品在 geyser_mc:another_test_item 物品模型下在不同条件下使用。具体来说，当提供的维度谓词与下界维度匹配时，使用第三个定义（Bedrock 标识符为 geyser_mc:another_test_item_nether）。否则，使用没有谓词的第四个定义。

Bedrock 选项​

这些选项允许配置 Bedrock 特定的选项，这些选项在组件中未表示。 包括：

  • icon：确定物品使用的图标。如果未设置，则使用物品的 Bedrock 标识符。 此值对应于 item_texture.json 文件中定义的图标简写。

    如果使用 Bedrock 物品的标识符，则进行以下更改：

    • : 将被替换为 .
    • / 替换为 _

    示例：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）。 否则，Bedrock 将不会在配方书中显示自定义物品的配方！

展开查看 bedrock 选项示例
    "bedrock_options": {
        "icon": "example:chestplate", // must match shorthands defined in 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", // must match shorthands defined in item_texture.json
        "display_handheld": true, // usually only set for weapons or tools
        "creative_category": "items",
        "creative_group": "itemGroup.name.sword",
        "tags": ["example:my_weapon"]
    }

组件​

物品组件在 Java Edition 中用于自定义物品的功能和行为。 Java Edition 允许在运行时修改这些物品的任何物品堆栈。不幸的是，这不是 Bedrock Edition 支持的功能。 因此，对基础 Java 物品的数据组件的任何修改都必须在映射文件中指定。 当使用自定义物品定义时，预期服务器将始终发送这些组件。对于不同的组件集，应使用带谓词的多个自定义物品定义。

信息

你不需要映射与基础 Java 物品相同的组件。

注意

某些组件一起使用有一些限制！ 例如，Bedrock 目前不支持可穿戴堆叠物品。 当使用可装备物品（如马铠）作为基础物品时，你可以移除冲突的默认组件作为临时修复。

添加或修改组件​

以下 Java 物品组件受支持（有一些限制）：

  • minecraft:consumable：不支持消耗粒子/声音。
  • minecraft:equippable：不支持相机覆盖或可交换属性。
  • minecraft:food
  • minecraft:max_damage
  • minecraft:max_stack_size
  • minecraft:use_cooldown
  • minecraft:enchantable
    • 在 Bedrock 上，这将映射到 minecraft:enchantable 组件，slot=all。这应该，但不能保证，与原版附魔兼容。非原版附魔可能无法工作。
  • minecraft:tool
  • minecraft:repairable
  • minecraft:enchantment_glint_override
  • minecraft:attack_range
    • 由于 Bedrock 限制，仅在与 minecraft:kinetic_weapon 或 minecraft:piercing_weapon 组件结合时才有效。
  • minecraft:kinetic_weapon
  • minecraft:piercing_weapon
  • minecraft:swing_animation
    • 由于 Bedrock 限制，实际播放的动画是硬编码的，只能更改动画的持续时间。
  • minecraft:use_effects
    • 由于 Bedrock 限制，can_sprint 属性无法翻译。此外，仅当基础物品能够射箭、投掷投射物或可食用（或通过食物组件变为可食用）时，才会翻译此组件。

某些组件（如 minecraft:rarity 和 minecraft:attribute_modifiers）已经自动翻译，不应列出。

有关所有物品组件及其各自 json 格式的文档，请参阅 Minecraft wiki 上的物品数据组件页面。

展开查看组件使用示例

所有列出的组件遵循与数据包中使用的相同的 json 结构，这些在 Minecraft wiki 上有文档。以下是一些示例：

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

移除默认组件​

就像在 Java edition 上可以做到的那样，可以移除基础物品的默认组件（例如使苹果不可食用）。

展开查看组件移除使用示例

在 Json 映射中，这是通过在组件前面添加 ! 来完成的。

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

谓词​

谓词用于告诉 Geyser 对于特定的 Java 物品和物品模型组合使用哪个自定义物品定义。 对于更简单的 legacy 映射或没有多个组件变体的自定义物品，不需要谓词。

对于 Java 物品和 Java 物品模型定义的每种组合，可以有一个没有谓词的物品定义，以及一个或多个带有谓词的定义。对于相同的 Java 物品和 Java 物品模型定义，不能有多个具有相同谓词的物品定义。 如果 Java 物品模型定义在 minecraft 命名空间中，则不能有没有谓词的物品定义。

信息

谓词也可以反转以匹配反向条件。

条件谓词​

condition 谓词类型检查布尔属性并在属性匹配预期值时返回 true。它有 5 个可能的属性：

  • broken：物品是否损坏（只剩 1 点耐久度）。
  • damaged：物品是否损坏（未满耐久度）。
  • custom_model_data：检查物品在 index 键指定的索引处的自定义模型数据标志。默认为 false。
  • has_component：物品是否设置了 component 键中设置的组件。包括默认组件。
  • fishing_rod_cast：玩家当前是否持有已抛出的钓鱼竿。
展开查看使用示例。

所有条件谓词类型必须将 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 来反转组件。如果未设置，默认为 true。 示例：

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

匹配谓词​

match 谓词类型检查文本属性并在匹配给定值时返回 true。它有 4 个可能的属性：

  • charge_type：十字弓当前充电的物品（在 minecraft:charged_projectiles 组件中）。可以是 arrow 或 rocket。
  • trim_material：此物品的修剪材料（资源位置）。
  • context_dimension：玩家当前所在的维度（资源位置）。
  • custom_model_data：从物品的自定义模型数据字符串中获取字符串。

match 谓词需要在 value 键中指定一个值。

展开查看使用示例。

所有匹配谓词类型必须将 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 来反转谓词。如果未设置，默认为 true。 示例：

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

范围调度谓词​

range_dispatch 谓词类型检查数值属性并在大于或等于指定阈值时返回 true。它有 4 种可能的类型：

  • bundle_fullness：检查物品的包裹饱满度。返回 minecraft:bundle_contents 组件中所有物品的总重量。
    • 此属性不能规范化！
  • damage：检查物品的伤害值。可以规范化。
  • count：检查物品的数量。可以规范化。
  • custom_model_data：检查物品在指定索引处的自定义模型数据浮点值。默认为 0.0。
    • 此属性不能规范化！

range_dispatch 谓词有 3 个额外的键：

  • threshold：返回 true 所需的阈值（必需）。
  • scale：在将属性值与阈值进行比较之前要缩放的因子。默认为 1.0。
  • normalize：是否应在缩放之前规范化属性值并与阈值进行比较。默认为 false，仅适用于某些属性。
展开查看使用示例。
"predicate": {
    "type": "range_dispatch",
    "property": "count",
    "threshold": 32
}

当数量大于或等于 32 时，此谓词计算为"true"。

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

当归一化计数（计数 / 最大计数；介于 0 和 1 之间）大于或等于 0.5 时，此谓词计算为"true"。

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

当缩放计数（计数 × 2）大于或等于阈值时，此谓词计算为"true"。

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

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

多个谓词的谓词策略​

还有一个 predicate_strategy 键，可以是 and 或 or，默认为 and。这是受进度要求策略的启发， 并决定是所有谓词（and）还是只有一个谓词（or）必须匹配才能使用物品定义。

展开查看使用示例。
"predicate": [
    {
        "type": "match",
        "property": "context_dimension",
        "value": "minecraft:the_end"
    },
    {
        "type": "condition",
        "property": "broken"
    }
],
"predicate_strategy": "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 按以下顺序对自定义物品定义进行排序：

  1. 首先，优先级值较高的自定义物品定义排序在优先级较低的定义之上。
  2. 具有相似范围调度谓词的自定义物品定义按阈值排序，阈值较高的排在前面。
  3. 具有更多谓词的自定义物品定义排序在谓词较少的定义之上。

这个系统确保在大多数情况下，带谓词的物品定义按正确顺序检查，无论它们在映射中的顺序如何。 在 Geyser 不能正确排序定义的少数情况下（最有可能发生在使用多个 range_dispatch 谓词或将它们与其他谓词结合使用时）， 可以使用 priority 键指定应首先检查哪些定义。

如果一个物品 + 物品模型组合只有一个自定义物品定义，则不需要指定优先级！

展开查看使用示例。
"priority": 5

资源包​

自定义物品还需要 Bedrock Edition 资源包。Geyser 不会将 Java Edition 资源包生成或转换为 Bedrock Edition 资源包，所以你需要手动设置！你也可以尝试使用 Rainbow 或 其他第三方转换器。

创建你自己的 Bedrock Edition 资源包​

  1. 使用有效的 manifest 设置一个基本的 Bedrock 资源包。如果需要帮助，你可以在这里找到相关说明。
  2. 创建一个 textures 文件夹。
  3. 在该文件夹中，创建一个 item_texture.json 文件，并放入以下内容：
{
  "resource_pack_name": "YOUR_PACK_NAME",
  "texture_name": "atlas.items",
  "texture_data": {

  }
}
  1. 在 texture_data 中，你可以添加你的物品。纹理名称和路径必须与你映射中设置的 Bedrock 标识符（和/或图标）匹配。 例如，使用 Bedrock 标识符 example:yummy_food 注册的物品需要以下条目：
"example:yummy_food": {
    "textures": [
        "textures/items/yummy_food"
    ]
}
  1. 然后你需要将纹理放入 textures/items 文件夹中。确保使其与你之前在 item_texture.json 中指定的纹理路径匹配！

更多参考：​

加载映射和资源包​

本节假设你已经设置并配置了 Geyser，以便 Bedrock 玩家能够连接。此外，必须将 Geyser 配置中的 enable-custom-content 配置选项设置为 true 才能使自定义物品工作！

  1. 找到 Geyser 创建的 custom_mappings 文件夹。对于 Geyser 的插件/模组版本，它将在 plugins/Geyser-[platform]/custom_mappings（或 config/Geyser-[platform]/custom_mappings）。对于 Geyser-Standalone， 它将在根文件夹中。
  2. 将映射 .json 文件放入该文件夹中。你可以有多个具有不同文件名的映射文件。
  3. 将 Bedrock edition 资源包放入 packs 文件夹中。
  4. 重启服务器。

完整示例​

完整的 Java Edition 数据包 + 资源包，以及相关的 Geyser 映射和 Bedrock 资源包可以在 此处找到。

简单自定义食物物品映射
{
    "format_version": 2,
    "items": {
        "minecraft:flint": [
            {
                "type": "definition",
                "model": "geyser_mc:yummy_food",
                "bedrock_identifier": "geyser_mc:yummy_food",
                "display_name": "Yummy food!",
                "components": {
                    "minecraft:consumable": {},
                    "minecraft:food": {
                        "nutrition": 5,
                        "saturation": 0.0
                    },
                    "minecraft:max_stack_size": 16
                }
            }
        ]
    }
}
Not-yummy-food - group and dimension predicate example
    {
        "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": "Not so yummy food",
                            "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": "Not so yummy food",
                            "predicate": {
                                "type": "match",
                                "property": "context_dimension",
                                "value": "minecraft:the_end"
                            },
                            "components": {
                                "minecraft:consumable": {
                                    "consume_seconds": 5.0
                                },
                                "minecraft:food": {
                                    "nutrition": 2,
                                    "saturation": 0.7
                                }
                            }
                        }
                    ]
                }
            ]
        }
    }
Magic item (consumable with cooldown)
    {
        "format_version": 2,
        "items": {
            "minecraft:flint": [
                {
                    "type": "definition",
                    "model": "geyser_mc:magic_item",
                    "bedrock_identifier": "geyser_mc:magic_item",
                    "display_name": "Magic item",
                    "components": {
                        "minecraft:consumable": {
                            "consume_seconds": 0.05,
                            "animation": "none"
                        },
                        "minecraft:use_cooldown": {
                            "seconds": 5.0,
                            "cooldown_group": "geyser_mc:magic_item"
                        }
                    }
                }
            ]
        }
    }
Flint pickaxe (broken-state predicate)
    {
        "format_version": 2,
        "items": {
            "minecraft:flint": [
                {
                    "type": "group",
                    "model": "geyser_mc:flint_pickaxe",
                    "definitions": [
                        {
                            "bedrock_identifier": "geyser_mc:flint_pickaxe",
                            "display_name": "Flint Pickaxe",
                            "bedrock_options": {
                                "display_handheld": true
                            },
                            "components": {
                                "minecraft:max_damage": 10,
                                "minecraft:max_stack_size": 1
                            }
                        },
                        {
                            "bedrock_identifier": "geyser_mc:flint_pickaxe_broken",
                            "display_name": "Flint Pickaxe",
                            "bedrock_options": {
                                "display_handheld": true
                            },
                            "predicate": {
                                "type": "condition",
                                "property": "broken"
                            },
                            "components": {
                                "minecraft:max_damage": 10,
                                "minecraft:max_stack_size": 1
                            }
                        }
                    ]
                }
            ]
        }
    }
Red wool chestplate (equippable armor)
{
    "format_version": 2,
    "items": {
        "minecraft:flint": [
            {
                "type": "definition",
                "model": "geyser_mc:red_wool_chestplate",
                "bedrock_identifier": "geyser_mc:red_wool_chestplate",
                "display_name": "Red Wool Chestplate",
                "bedrock_options": {
                    "protection_value": 5
                },
                "components": {
                    "minecraft:equippable": {
                        "slot": "chest"
                    },
                    "minecraft:max_stack_size": 1
                }
            }
        ]
    }
}

非原版物品​

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：注明物品能够放置实体