Files
GeyserWebsite/wiki/geyser/custom-items.mdx
T
9918f4a047 Feature: Custom item v2 docs (#115)
* Start documenting custom item mappings: V2

* Document json definition types

* Continue documenting Bedrock item options

* Start on component docs

* Document removing components, start documenting predicates

* Sync all example types

* Rough draft should now be sort of there

* Resolve suggestions

* Split v1 and v2 docs

* Document & add examples to range predicates

* Component examples

* Minor fixes

* Remove warning on Hydraulic

* oops

* more tiny changes

* Add javadoc links

* Update the build number mentioned in docs

---------

Co-authored-by: rtm516 <ryantmilner@hotmail.co.uk>
Co-authored-by: Aurora <auroranova8756@gmail.com>
2026-02-07 19:36:25 +01:00

1214 lines
55 KiB
Plaintext
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
title: Custom Items
description: Geyser allows custom Bedrock items to be added for an equivalency to Vanilla Java item predicates or modded items.
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
Minecraft: Java Edition supports creating "custom" items that are based on vanilla items. With Minecraft 1.21.4+, the introduction of item components
further allows the customization of item behavior on a per-item-stack basis, such as changing the visual appearance using the item model component,
and modifying item properties such as the ability to eat or equip an item.
Unlike Java Edition, Bedrock natively supports adding custom items that are not based on vanilla items. However, Bedrock does not support
extending vanilla items or modifying vanilla item behavior. Therefore, Geyser has a mapping system that allows mapping custom Bedrock items
to modified vanilla Java items. Geyser further supports mapping custom Bedrock items to modded non-vanilla items which
would normally require mods to be installed on the Java client.
To set up custom items in Geyser, you have to choose how you are going to register your items. The easiest is using a json mapping file,
but you can also use a Geyser extension which uses the [Geyser API](/wiki/geyser/api/). Further, a Bedrock edition resource pack must also be supplied to ensure Bedrock players can see custom items.
:::warning
Geyser does not convert resource packs from Java Edition, and also does not generate custom item mappings automatically.
However, you can use automatic tools such as [Rainbow](/wiki/other/rainbow/) to make converting content simpler.
:::
:::info
Since the Geyser API version 2.9.3 (Build #1062 and up), the old custom item format (v1) is deprecated and is no
longer being updated. Old docs can still be found [here](/wiki/geyser/custom-items-old)
:::
## Custom items (v2)
Geyser supports mapping items using `item_model` and item component features introduced in 1.21.4+. The previous `custom-model-data` approach continues to be supported using `legacy` definitions.
However, there are some caveats. Unlike Java Edition, Bedrock Edition does not support modifying item properties dynamically at runtime (e.g. making dirt edible with a command).
For such use-cases, Geyser supports a predicate system which allows registering multiple custom Bedrock items with different properties to map
to different item stacks with specific components.
## How does it work?
"Custom" items in Java edition are based on vanilla items, with a modified appearance (using item models on 1.21.4+, or custom model data on older versions).
Therefore, all mapped Bedrock custom item definitions are based on vanilla Java items and their components. Further, mapped definitions
can specify additional components to modify the items' behavior.
### Prerequisites: Vocabulary
- `Java item`: Any vanilla item that exists in the Minecraft: Java Edition base game. Java datapacks / plugins can create custom items by overriding components of a Java item.
- `Java item component`: On Java Edition since 1.21.4+, items have their properties and behavior defined using item components.
Every Java item has a set of default components, which can be overridden to change how an item looks or functions.
- `Bedrock item component`: Custom Bedrock items also have components that determine item behavior, similar to Java Edition.
However, these components cannot be changed at runtime for item stacks and have to be pre-defined when the Bedrock client joins.
- `Java legacy custom model data`: The system used before Java 1.21.4. Before 1.21.4, each "custom item" had a custom model data number,
used to decide which model a Java item should use (= different texture for players).
- `Java item model definition`: Introduced in Java 1.21.4, they are found in the `assets/<namespace>/items/` directory of Java resource packs.
These textures are used to set the appearance of Java items, and can be dynamically changed with a set of rules and item properties.
Every Java item stores its item model definition in the `minecraft:item_model` item data component. It can be overridden on a per-item-stack-basis by a datapack/plugin to use a custom item model definition defined in a resource pack.
- `Custom item definition`: a custom item definition is a Geyser term. It represents a single Bedrock custom item that is used to map a Java item model definition. It contains info on the item's properties on Java and Bedrock.
Multiple custom item definitions, and thus multiple Bedrock items, can exist for the same Java item model definition, but for every combination of a Java item and Java item model definition, there can only be one custom item definition without predicates.
- `Non-vanilla custom item definition`: also a Geyser term. Represents a Bedrock custom item that maps a Java non-vanilla (modded) item. Like normal custom item definitions, it contains info on the item's properties on Java and Bedrock.
At the moment, there can only be one non-vanilla custom item definition per Java non-vanilla item.
### Definitions
Every custom item definition represents one custom Bedrock item that has a specific set of pre-defined Bedrock options.
It is tied to a specific Java item + item model combination (or, for legacy items, a specific Java item + custom model data combination).
#### Mandatory definition properties
- `bedrock_identifier`: This identifier is used for the custom Bedrock item (and also in e.g. attachables in Bedrock resource packs), and cannot be shared with **any** other custom item definition.
This identifier cannot be in the `minecraft` namespace. If no namespace is provided, `geyser_custom` is used.
- `model` (or `custom_model_data` for `legacy` definitions in json mappings) is also required.
#### Optional definition properties
- `display_name`: A string, or json text component for the item's default display name. If not set, it is derived from the bedrock identifier.
- `bedrock_options`: The [bedrock options](#bedrock-options) that specify additional Bedrock properties
- `components`: Java item components that specify item behavior, such as the maximum stack size.
- `predicate`: Predicates used to match a specific custom item definition to an item stack.
- `predicate_strategy`: Specifies how multiple predicates are evaluated. Only used when predicates are specified.
- `priority`: Optionally specifies a priority of a definition over other definitions for the same item + item model combination. Only used
when there are multiple custom item definitions.
<Tabs groupId="custom-item-implementation">
<TabItem value="json" label="Definitions: Json mappings">
Json mapping files have to specify the `format_version` set to `2`, and list all definitions for each item
under the `items` key. It holds an object in which keys are Java items, and in which each value is an array of objects,
specifying custom item definitions for that Java item.
Example structure of a `mappings.json` mappings file:
```json
{
"format_version": 2,
"items": {
"minecraft:flint": [
// definition
],
"minecraft:apple": [
// definition1,
// definition2
],
"minecraft:diamond": [
// definition
]
}
}
```
There are multiple types of custom item definitions:
- `definition`: a single custom item, defined for a Java item model definition.
- `legacy`: a single custom item, defined for a Java custom item making use of legacy custom model data numbers.
- `group`: a group of custom item definitions.
The type of a definition is defined in the `type` key.
<Tabs>
<TabItem value="model-definition-type" label="Item Model Definition (1.21.4+)">
```json
{
"type": "definition",
"model": "example:example_model",
"bedrock_identifier": "example:example_item"
}
```
The `definition` type is used to map one definition for a specific item's `item_model` component value.
This should be used for 1.21.4+ and above. For custom items using the legacy `custom_model_data` format,
use the `legacy` type.
</TabItem>
<TabItem value="group-type" label="Group Definition">
```json
{
"type": "group",
"model": "example:example_model", // Optional, can be set per-definition
"definitions": [...]
}
```
A `group` definition represents a group of custom item definitions. These can both be standard or legacy definitions.
All non-legacy definitions in the group inherit the group's Java item `model` definition, if one is set.
If a group has no model set, all definitions in the group must specify the item model themselves.
Definitions in a group are also allowed to be a group, and definitions in a group can also override the Java item model definition of the group.
</TabItem>
<TabItem value="legacy-definition-type" label="Legacy Definition (pre 1.21.4+)">
```json
{
"type": "legacy",
"custom_model_data": 42,
"bedrock_identifier": "example:example_item_legacy"
}
```
The `legacy` definition should be used for custom items created on versions before the introduction of data
components (and therefore `item_models`). These must specify a `custom_model_data` float value.
</TabItem>
</Tabs>
<details>
<summary>Expand to see examples of all definition types</summary>
```json
{
"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
}
}
}
]
}
]
}
}
```
In this example, the Java item `minecraft:flint` has four mapped definitions:
- The first is mapped using a "simple" definition for the `geyser_mc:test_item` model. Hence, it will always be used
when Geyser encounters a flint item with the `item_model` component being set to the `geyser_mc:test_item` model.
- The second is a "legacy" definition for the custom model data value of 42. Hence, if Geyser encounters a flint item with
the first float value in the `floats` list set to `42`, it will use the second definition.
Such an item could be retrieved using the following command: `/give @s flint[custom_model_data={floats:[42]}] 1`
- The third and fourth definition is part of a `group` type, which maps multiple definitions to `minecraft:flint` items with the
`geyser_mc:another_test_item` item model to use under different conditions. Specifically, the third definition (with the bedrock identifier `geyser_mc:another_test_item_nether`)
is used when the supplied dimension predicate matches the nether dimension. Otherwise, the fourth definition, which does not
specify a predicate, is used.
</details>
</TabItem>
<TabItem value="api" label="Definitions: Geyser API">
Custom item definitions are registered using the [`GeyserDefineCustomItemsEvent`](https://repo.opencollab.dev/javadoc/maven-snapshots/org/geysermc/geyser/api/latest/.cache/unpack/org/geysermc/geyser/api/event/lifecycle/GeyserDefineCustomItemsEvent.html).
```java
@Subscribe
public void onGeyserDefineCustomItems(GeyserDefineCustomItemsEvent event) {
event.register(Identifier.of("flint"), CustomItemDefinition.builder(
Identifier.of("example:example_item_identifier"), // mandatory: Bedrock item identifier
Identifier.of("example:custom_item_model") // mandatory: item model
)
// The following are optional
.displayName("displayName")
.bedrockOptions(...)
.component(JavaItemDataComponents.MAX_STACK_SIZE, 60)
.predicate(ItemRangeDispatchPredicate.count(32))
.predicateStrategy(PredicateStrategy.OR)
.priority(1)
.build());
}
```
The `register` method takes in two parameters: The identifier of the base vanilla item, and a
[`CustomItemDefinition`](https://repo.opencollab.dev/javadoc/maven-snapshots/org/geysermc/geyser/api/latest/.cache/unpack/org/geysermc/geyser/api/item/custom/v2/CustomItemDefinition.html). The latter must be created using the [`CustomItemDefinition.Builder`](https://repo.opencollab.dev/javadoc/maven-snapshots/org/geysermc/geyser/api/latest/.cache/unpack/org/geysermc/geyser/api/item/custom/v2/CustomItemDefinition.Builder.html), which
requires passing the Bedrock item identifier and item model as arguments.
</TabItem>
</Tabs>
### Bedrock Options
These options allow configuring Bedrock-specific options that aren't represented by components.
These include:
- `icon`: Determines the icon to use for the item. If not set, the item's Bedrock identifier is used.
This value corresponds to icon shorthands defined in the `item_texture.json` file.
If the Bedrock item's identifier is used, the following changes are made:
- `:` would be replaced with `.`
- `/` with `_`
Example: `geyser_mc:a_cool_item` -> `geyser_mc.a_cool_item`.
- `allow_offhand`: Whether the custom item may be held / put into the offhand. Defaults to `true`.
- `display_handheld`: Whether the item should be displayed handheld (e.g. for tools or weapons). Defaults to `false`.
- `protection_value`: Determines how many armor protection points should be shown when this item is worn. This is purely visual,
and only has an effect if the item is equippable. Defaults to `0`.
- `creative_category`: Sets the item's creative category (also shown in the recipe book). Can be `none`,
`construction`, `nature`, `equipment`, or `items`. Defaults to `none`.
- `creative_group`: Sets the item's creative group (for the recipe book). See [here](https://wiki.bedrock.dev/documentation/menu-categories#list-of-vanilla-groups)
for a list of possible values. Creating custom creative groups is not currently supported by Geyser.
- `tags`: Sets tags that an item has. These can be used for Molang expressions in resource packs.
:::info
A `creative_category` (and optionally `creative_group`) must be set if you have crafting recipes
that output a custom item. Otherwise, Bedrock will *not* show recipes for custom items in the recipe book!
:::
<details>
<summary>Expand for bedrock option examples</summary>
<Tabs groupId="custom-item-implementation">
<TabItem value="json" label="Json mappings">
```json
"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"]
}
```
```json
"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"]
}
```
</TabItem>
<TabItem value="api" label="Geyser API">
In the API, Bedrock item options are defined using the [`CustomItemBedrockOptions#Builder`](https://repo.opencollab.dev/javadoc/maven-snapshots/org/geysermc/geyser/api/latest/.cache/unpack/org/geysermc/geyser/api/item/custom/v2/CustomItemBedrockOptions.Builder.html).
The following snippets show example usages:
```java
.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")))
)
```
```java
.bedrockOptions(CustomItemBedrockOptions.builder()
.icon("example:my_sword")
.displayHandheld(true)
.creativeCategory(CreativeCategory.ITEMS)
.creativeGroup("itemGroup.name.sword")
.tag(Identifier.of("example:my_weapon"))
)
```
</TabItem>
</Tabs>
</details>
### Components
Item components are used in Java Edition to customize how items function and behave.
Java Edition allows modifying these for any item stack at runtime. This is, unfortunately, not a feature Bedrock Edition supports.
Therefore, any modifications to the base Java item's data components must be specified in mapping files.
It is expected that a custom item will *always* have these components sent by the server when the custom item definition
is used. For different sets of components, multiple custom item definitions with predicates should be used.
:::info
You do not need to map components that are unchanged from the base Java item.
:::
#### Adding or Modifying components
The following Java item components are supported (some with limitations):
- `minecraft:consumable`: doesn't support consume particles/sounds.
- `minecraft:equippable`: doesn't support the camera overlay or swappable properties.
- `minecraft:food`
- `minecraft:max_damage`
- `minecraft:max_stack_size`
- `minecraft:use_cooldown`
- `minecraft:enchantable`
- On Bedrock, this will be mapped to the `minecraft:enchantable` component with `slot=all`. This should, but does not guarantee, allow for compatibility with vanilla enchantments. Non-vanilla enchantments are unlikely to work.
- `minecraft:tool`
- `minecraft:repairable`
- `minecraft:enchantment_glint_override`
- `minecraft:attack_range`
- Due to Bedrock limitations, only has an effect in combination with the `minecraft:kinetic_weapon` or `minecraft:piercing_weapon` components.
- `minecraft:kinetic_weapon`
- `minecraft:piercing_weapon`
- `minecraft:swing_animation`
- Due to Bedrock limitations, the actual animation played is hardcoded, only the duration of the animation can be changed.
- `minecraft:use_effects`
- Due to Bedrock limitations, the `can_sprint` property cannot be translated. Further, this component will only be translated
when the base item is either able to shoot arrows, throw projectiles, or is edible (or made edible with the food component).
Some components, like `minecraft:rarity` and `minecraft:attribute_modifiers`, are already automatically translated and should not be listed.
For documentation of all item components and their respective json formats, see [the item data component page on the Minecraft wiki](https://minecraft.wiki/w/Data_component_format).
<details>
<summary>Expand for component usage examples</summary>
<Tabs groupId="custom-item-implementation">
<TabItem value="json" label="Json mappings">
All components listed follow the same json structure as would be used in datapacks, which are documented on the
Minecraft wiki. Here are some examples:
```json
"components": {
"minecraft:max_stack_size": 16,
"minecraft:enchantment_glint_override": true
}
```
</TabItem>
<TabItem value="api" label="Geyser API">
All supported components can be found in the [`JavaItemDataComponents`](https://repo.opencollab.dev/javadoc/maven-snapshots/org/geysermc/geyser/api/latest/.cache/unpack/org/geysermc/geyser/api/item/custom/v2/component/java/JavaItemDataComponents.html) class, and are typically built with builders.
Some examples:
```java
.component(JavaItemDataComponents.MAX_STACK_SIZE, 16)
```
```java
.component(JavaItemDataComponents.ENCHANTMENT_GLINT_OVERRIDE, true)
```
</TabItem>
</Tabs>
</details>
#### Removing default components
Just as is possible on Java edition, default components of the base item can be removed (e.g. making non-edible apples).
<details>
<summary>Expand for usage examples of component removal</summary>
<Tabs groupId="custom-item-implementation">
<TabItem value="json" label="Json mappings">
In Json mappings, this is done by adding an `!` in front of the component.
```json
"components": {
"!minecraft:food": {}
}
```
</TabItem>
<TabItem value="api" label="Geyser API">
The [`CustomItemDefinition#Builder`](https://repo.opencollab.dev/javadoc/maven-snapshots/org/geysermc/geyser/api/latest/.cache/unpack/org/geysermc/geyser/api/item/custom/v2/CustomItemDefinition.Builder.html)
builder supports removing default components by either specifying the item data component identifier, or by passing the type.
```java
@Subscribe
public void onDefineCustomItems5(GeyserDefineCustomItemsEvent event) {
event.register(Identifier.of("apple"), CustomItemDefinition.builder(
Identifier.of("example:rotten_apple"), Identifier.of("example:rotten_apple")
)
.displayName("Rotten apple")
.removeComponent(JavaItemDataComponents.FOOD)
.build());
}
```
</TabItem>
</Tabs>
</details>
### Predicates
Predicates are used to tell Geyser which custom item definition to use for a particular combination of Java item and item model.
For simpler legacy mappings or custom items that don't have multiple component variants, predicates aren't required.
For each combination of a Java item and a Java item model definition, there can be one item definition without predicates,
and one or multiple definitions with predicates. There cannot be multiple item definitions with the same predicates for the same Java item and Java item model definition.
If the Java item model definition is in the `minecraft` namespace, there cannot be an item definition without a predicate.
:::info
Predicates can also be inverted to match for the inverse condition.
:::
#### Condition predicates
The `condition` predicate type checks for a boolean property and returns `true` if the property matches the expected value. It has 5 possible properties:
- `broken`: if the item is broken (has only 1 durability point left).
- `damaged`: if the item is damaged (not at full durability).
- `custom_model_data`: checks the item's custom model data flags at the index specified in the `index` key. Defaults to `false`.
- `has_component`: if the item has the component set in the `component` key. Includes default components.
- `fishing_rod_cast`: if the player is currently holding a cast fishing rod.
<details>
<summary>Expand for usage examples.</summary>
<Tabs groupId="custom-item-implementation">
<TabItem value="json" label="Json mappings">
All condition predicate types must set the `type` to `condition`.
```json
"predicate": {
"type": "condition",
"property": "broken"
}
```
```json
"predicate": {
"type": "condition",
"property": "damaged"
}
```
```json
"predicate": {
"type": "condition",
"property": "has_component",
"component": "minecraft:unbreakable"
}
```
```json
"predicate": {
"type": "condition",
"property": "custom_model_data",
"index": 1
}
```
```json
"predicate": {
"type": "condition",
"property": "fishing_rod_cast"
}
```
Components can also be inverted by adding and setting the `expected` key to `false`. If not set, it defaults to `true`.
Example:
```json
"predicate": {
"type": "condition",
"property": "broken",
"expected": false
}
```
</TabItem>
<TabItem value="api" label="Geyser API">
All condition predicates can be found in the [`ItemConditionPredicate`](https://repo.opencollab.dev/javadoc/maven-snapshots/org/geysermc/geyser/api/latest/.cache/unpack/org/geysermc/geyser/api/predicate/item/ItemConditionPredicate.html) interface. Examples:
```java
.predicate(ItemConditionPredicate.FISHING_ROD_CAST)
```
Some predicates require additional arguments:
```java
.predicate(ItemConditionPredicate.customModelData(1))
.predicate(ItemConditionPredicate.hasComponent(ItemDataComponents.REPAIRABLE.identifier()))
```
To negate predicates, call `#negate()`:
```java
.predicate(ItemConditionPredicate.DAMAGEABLE.negate())
```
</TabItem>
</Tabs>
</details>
#### Match predicates
The `match` predicate type checks for a text-like property and returns `true` if it matches the given value. It has 4 possible properties:
- `charge_type`: the item currently charged in the crossbow (in the `minecraft:charged_projectiles` component). Can be `arrow` or `rocket`.
- `trim_material`: the trim material (resource location) of this item.
- `context_dimension`: the dimension (resource location) the player is currently in.
- `custom_model_data`: fetches a string from the item's custom model data strings.
The `match` predicate requires a value to be specified in the `value` key.
<details>
<summary>Expand for usage examples.</summary>
<Tabs groupId="custom-item-implementation">
<TabItem value="json" label="Json mappings">
All match predicate types must set the `type` to `match`.
```json
"predicate": {
"type": "match",
"property": "charge_type",
"value": "arrow"
}
```
```json
"predicate": {
"type": "match",
"property": "trim_material",
"value": "minecraft:coast_armor_trim"
}
```
```json
"predicate": {
"type": "match",
"property": "context_dimension",
"value": "minecraft:the_end"
}
```
```json
"predicate": {
"type": "match",
"property": "custom_model_data",
"value": "MyString",
"index": 1
}
```
Predicates can also be inverted by adding and setting the `expected` key to `false`. If not set, it defaults to `true`.
Example:
```json
"predicate": {
"type": "match",
"property": "context_dimension",
"value": "minecraft:the_end",
"expected": false
}
```
</TabItem>
<TabItem value="api" label="Geyser API">
Item match predicates can be found in the [`ItemMatchPredicate`](https://repo.opencollab.dev/javadoc/maven-snapshots/org/geysermc/geyser/api/latest/.cache/unpack/org/geysermc/geyser/api/predicate/item/ItemMatchPredicate.html)
interface, additionally to generic match predicates in the [`MatchPredicate`](https://repo.opencollab.dev/javadoc/maven-snapshots/org/geysermc/geyser/api/latest/.cache/unpack/org/geysermc/geyser/api/predicate/MatchPredicate.html) interface.
Examples:
```java
.predicate(ItemMatchPredicate.chargeType(ChargedProjectile.ChargeType.ARROW));
```
```java
.predicate(MatchPredicate.dimension(Identifier.of("the_end")));
```
</TabItem>
</Tabs>
</details>
#### Range dispatch predicates
The `range_dispatch` predicate type checks for a numeric property and returns `true` if it is at or above the specified threshold. It has 4 possible types:
- `bundle_fullness`: checks the item's bundle fullness. Returns the total weight of all items (in the `minecraft:bundle_contents` component).
- This property cannot be normalized!
- `damage`: checks the item's damage value. Can be normalized.
- `count`: checks the item's count. Can be normalized.
- `custom_model_data`: checks the item's custom model data float at the specified index. Defaults to `0.0`.
- This property cannot be normalized!
The `range_dispatch` predicate has 3 extra keys:
- `threshold`: the threshold required to return true (required).
- `scale`: the factor to scale the property value by before comparing it with the threshold. Defaults to `1.0`.
- `normalize`: if the property value should be normalized before scaling it and comparing it with the threshold. Defaults to `false`, only works for certain properties.
<details>
<summary>Expand for usage examples.</summary>
<Tabs groupId="custom-item-implementation">
<TabItem value="json" label="Json mappings">
```json
"predicate": {
"type": "range_dispatch",
"property": "count",
"threshold": 32
}
```
This predicate evaluates to "true" when the count is equal or above 32.
```json
"predicate": {
"type": "range_dispatch",
"property": "count",
"normalize": true,
"threshold": 0.5
}
```
This predicate evaluates to "true" when the normalized count (count / max count; between 0 and 1) is equal to
or higher than 0.5.
```json
"predicate": {
"type": "range_dispatch",
"property": "count",
"threshold": 8,
"scale": 2
}
```
This predicate evaluates to "true" when the scaled count (count × 2) is greater than or equal to the threshold.
Using the `custom_model_data` range dispatch property requires specifying an index to check!
Indexes start at 0 - to check the first element in the floats list, you have to set index to 0:
```json
"predicate": {
"type": "range_dispatch",
"property": "custom_model_data",
"threshold": 3,
"index": 0
}
```
</TabItem>
<TabItem value="api" label="Geyser API">
Range dispatch predicates are found in the [`ItemRangeDispatchPredicate`](https://repo.opencollab.dev/javadoc/maven-snapshots/org/geysermc/geyser/api/latest/.cache/unpack/org/geysermc/geyser/api/predicate/item/ItemRangeDispatchPredicate.html) interface.
```java
CustomItemDefinition.builder(..., ...)
.predicate(ItemRangeDispatchPredicate.count(32))
.build();
```
This predicate evaluates to "true" when the count is equal or above 32.
```java
CustomItemDefinition.builder(..., ...)
.predicate(ItemRangeDispatchPredicate.normalizedCount(0.5))
.build();
```
This predicate evaluates to "true" when the normalized count (count / max count; between 0 and 1) is equal to
or higher than 0.5.
```java
CustomItemDefinition.builder(..., ...)
.predicate(ItemRangeDispatchPredicate.customModelData(1, 12))
.build();
```
This predicate evaluates to "true" when the second index of the floats list in the `custom_model_data` component
is present and is equal to or higher than 12.
To scale a property, divide the threshold by the scale factor.
</TabItem>
</Tabs>
</details>
### Predicate strategy for multiple predicates
There is also a `predicate_strategy` key, which can be `and` or `or` and defaults to `and`. This was inspired by the advancement requirement strategies,
and decides if all predicates (`and`), or only one predicate (`or`) of an item definition has to match for it to be used.
<details>
<summary>Expand for usage examples.</summary>
<Tabs groupId="custom-item-implementation">
<TabItem value="json" label="Json mappings">
```json
"predicate": [
{
"type": "match",
"property": "context_dimension",
"value": "minecraft:the_end"
},
{
"type": "condition",
"property": "broken"
}
],
"predicate_strategy": "and"
```
This would require two conditions to both match for a specific custom item definition to be used.
</TabItem>
<TabItem value="api" label="Geyser API">
```java
.predicate(ItemConditionPredicate.BROKEN)
.predicate(MatchPredicate.dimension(Identifier.of("the_end")))
.predicateStrategy(PredicateStrategy.AND)
```
This would require two conditions to both match for a specific custom item definition to be used.
Custom predicates can also be implemented, however, prefer using built-in predicates since these
can be cached properly.
</TabItem>
</Tabs>
</details>
:::info
When multiple predicates are specified using the API, it is important to list all predicates separately and use
the provided predicates, where possible. Chaining predicates manually or creating custom predicates results in Geyser being
unable to cache results!
<details>
Do NOT do this:
```java
.predicate(ItemConditionPredicate.BROKEN.and(MatchPredicate.dimension(Identifier.of("the_end"))))
```
Do this:
```java
.predicate(ItemConditionPredicate.BROKEN)
.predicate(MatchPredicate.dimension(Identifier.of("the_end")))
.predicateStrategy(PredicateStrategy.AND)
```
These have the same result, but only the result of the latter can be cached by Geyser.
</details>
:::
### Sorting and Priority
Custom item definitions are automatically sorted so that the definitions' predicates are checked in a correct order when translating items.
Specifically, Geyser sorts custom item definitions in this order:
1. First custom item definitions with a higher priority value are sorted above definitions with lower ones.
2. Custom item definitions with similar range dispatch predicates are sorted by their threshold, with higher thresholds going first.
3. Custom item definitions with more predicates are sorted over definitions with less.
This system ensures that in most cases, item definitions with predicates are checked in proper order, no matter which order they are put in the mappings.
In the few cases that Geyser does not sort definitions correctly (that will most likely occur when using multiple `range_dispatch` predicates, or using them in combination with other predicates),
the `priority` key can be used to specify which definitions should be checked first.
If there is only one custom item definition for an item + item model combination, specifying priorities is not necessary!
<details>
<summary>Expand for usage examples.</summary>
<Tabs groupId="custom-item-implementation">
<TabItem value="json" label="Json mappings">
```json
"priority": 5
```
</TabItem>
<TabItem value="api" label="Geyser API">
```java
.priority(5)
```
</TabItem>
</Tabs>
</details>
## Resource Packs
Custom items also require a Bedrock Edition resource pack. Geyser does not generate or convert Java Edition resource packs into
Bedrock Edition resource packs, so you will need to set it up manually! You can also try using [Rainbow](/wiki/other/rainbow) or
other third-party converters.
### Creating your own Bedrock Edition resource pack
1. Setup a basic bedrock resource pack with a valid manifest. If you need help, you can find it [here](https://wiki.bedrock.dev/guide/project-setup.html#rp-manifest).
2. Create a `textures` folder.
3. In that folder, create an `item_texture.json` file, and put this in it:
```json
{
"resource_pack_name": "YOUR_PACK_NAME",
"texture_name": "atlas.items",
"texture_data": {
}
}
```
4. Inside `texture_data`, you can add your items. The texture name and path must match the Bedrock identifier (and/or icon) that you set in your mappings.
For example, an item registered with the Bedrock identifier `example:yummy_food` would need the following entry:
```json
"example:yummy_food": {
"textures": [
"textures/items/yummy_food"
]
}
```
5. Then you need to put your textures inside the `textures/items` folder. Make sure to have it match the texture path that you specified in `item_texture.json`!
### Further references:
- [Minecraft creator docs on texture pack conversion](https://learn.microsoft.com/en-us/minecraft/creator/documents/convertingtexturepacks?view=minecraft-bedrock-stable)
- [Creating textures for custom items](https://wiki.bedrock.dev/items/items-intro#applying-textures)
- [High resolution items](https://wiki.bedrock.dev/items/high-resolution-items)
## Loading mappings and resource packs
This section assumes you already set up and configured Geyser so Bedrock players are able to connect. Further, the `enable-custom-content`
config option in Geyser's config must be set to `true` for custom items to work!
<Tabs groupId="custom-item-implementation">
<TabItem value="json" label="Loading json mappings">
1. Find the `custom_mappings` folder created by Geyser. For plugin/mod versions of Geyser, it will be under
`plugins/Geyser-[platform]/custom_mappings` (or `config/Geyser-[platform]/custom_mappings`). For Geyser-Standalone,
it will be in the root folder.
2. Place the mapping .json file into the folder. You can have multiple mapping files with different file names.
3. Place the Bedrock edition resource pack into the `packs` folder.
4. Restart the server.
</TabItem>
<TabItem value="api" label="Loading Geyser Extensions">
1. Place the extension jar file into the `extensions` folder. For plugin/mod versions of Geyser, it will be under
`plugins/Geyser-[platform]/extensions` (or `config/Geyser-[platform]/extensions`). For Geyser-Standalone,
it will be in the root folder.
2. If the extension also provides a resource pack, place that in Geyser's `packs` folder.
3. Restart the server.
</TabItem>
</Tabs>
## Full Examples
The full Java Edition datapack + resource pack, as well as the relevant Geyser mappings and Bedrock resource pack can be found
[here](https://github.com/eclipseisoffline/geyser-example-mappings/).
<Tabs groupId="custom-item-implementation">
<TabItem value="json" label="Json mapping example">
<details>
<summary>Simple custom food item mapping</summary>
```json
{
"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
}
}
]
}
}
```
</details>
<details>
<summary>Not-yummy-food - group and dimension predicate example</summary>
```json
{
"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
}
}
}
]
}
]
}
}
```
</details>
<details>
<summary>Magic item (consumable with cooldown)</summary>
```json
{
"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"
}
}
}
]
}
}
```
</details>
<details>
<summary>Flint pickaxe (broken-state predicate)</summary>
```json
{
"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
}
}
]
}
]
}
}
```
</details>
<details>
<summary>Red wool chestplate (equippable armor)</summary>
```json
{
"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
}
}
]
}
}
```
</details>
</TabItem>
<TabItem value="api" label="Code example">
<details>
<summary>Simple custom food item mapping</summary>
```java
@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("Yummy food!")
.component(JavaItemDataComponents.CONSUMABLE, JavaConsumable.builder().build())
.component(JavaItemDataComponents.FOOD, JavaFoodProperties.builder()
.nutrition(5)
.saturation(0)
.build())
.component(JavaItemDataComponents.MAX_STACK_SIZE, 16)
.build());
}
```
</details>
<details>
<summary>Not-yummy-food - group and dimension predicate example</summary>
```java
@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("Not so yummy food!")
.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("Not so yummy food!")
.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());
}
```
</details>
<details>
<summary>Magic item (consumable with cooldown)</summary>
```java
@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("Magic item!")
.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());
}
```
</details>
<details>
<summary>Flint pickaxe (broken-state predicate)</summary>
```java
@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("Flint Pickaxe")
.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("Flint Pickaxe")
.bedrockOptions(CustomItemBedrockOptions.builder()
.displayHandheld(true)
)
.predicate(ItemConditionPredicate.BROKEN)
.component(JavaItemDataComponents.MAX_DAMAGE, 10)
.component(JavaItemDataComponents.MAX_STACK_SIZE, 1)
.build());
}
```
</details>
<details>
<summary>Red wool chestplate (equippable armor)</summary>
```java
@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("Red Wool Chestplate")
.bedrockOptions(CustomItemBedrockOptions.builder()
.protectionValue(5)
)
.component(JavaItemDataComponents.EQUIPPABLE, JavaEquippable.of(JavaEquippable.EquipmentSlot.CHEST))
.component(JavaItemDataComponents.MAX_STACK_SIZE, 1)
.build());
}
```
</details>
</TabItem>
</Tabs>
## Non-vanilla items
Geyser also supports registering non-vanilla items (available on modded servers, such as Fabric/NeoForge), which are *not*
based on vanilla items and require a modded Java client to join. These must be registered through the API, and cannot be registered
with Json mappings.
Example:
```java
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());
```
Notable differences however are the following:
- The Java item id which is sent over the network must be provided in the NonVanillaCustomItemDefinition#builder method
- Predicates, predicate strategies, and priority are *not* supported
- Non-vanilla items can use additional components, which would otherwise be inherited from vanilla base items.
The [`GeyserItemDataComponent`](https://repo.opencollab.dev/javadoc/maven-snapshots/org/geysermc/geyser/api/latest/.cache/unpack/org/geysermc/geyser/api/item/custom/v2/component/geyser/GeyserItemDataComponents.html) class contains all additional components available for modded items:
- `chargeable`: Allows creating custom shooter items
- `attack_damage`: Allows placing a visual indicators for the item's attack damage.
- `block_placer`: Indicates that the item is able to place blocks
- `throwable`: Indicates that the item is throwable
- `projectile`: Marks a custom item as a projectile to make these usable for custom shooter items
- `entity_placer`: Notes that an item is able to place entities