└── README.md /README.md: -------------------------------------------------------------------------------- 1 | # How do I setup Geyser custom items? 2 | 3 | To setup custom items in geyser, you have to choose how you are going to register your items. The easiest is [using a json file](#json-mappings) but you can also [use a Geyser extension](#geyser-extensions). 4 | 5 | ## JSON mappings 6 | 7 | 1. Start your server, and you should have a folder called `custom_mappings` that is created. That would be with the folder of `Geyser.jar` file for standalone and inside your Geyser data folder for a plugin. 8 | 2. Create a `.json` file, it can be any name you like and as many files as you like. You don't need to make one file per item. Here is the structure of the file: 9 | ```json 10 | { 11 | "format_version": "1", 12 | "items": { 13 | 14 | } 15 | } 16 | ``` 17 | 3. Inside the `items` entry, you can add your java item to extend: 18 | ```json 19 | "minecraft:JAVA_ITEM": [ 20 | 21 | ] 22 | ``` 23 | 4. Inside this java item, goes an array of all your custom items. 24 | ```json 25 | { 26 | "name": "my_item" 27 | } 28 | ``` 29 | 5. Then, you need to set one or more item options or registrations, they can be stacked, so that all of the specified types need to match. 30 | * Custom model data: `custom_model_data` (int) 31 | * Damage predicate: `damage_predicate` (int) This is a fractional value of damage/max damage and not a number between 0 and 1. 32 | * Unbreakable: `unbreakable` (boolean) 33 | 6. You also have some extra modifiers that you can set to further customise your item. **Note that the following modifiers are NOT required.** 34 | * `display_name` (string) default: item name 35 | * `icon` (string) default: item name 36 | * `allow_offhand` (boolean) default: false 37 | * `texture_size` (int) default: 16 38 | * `render_offsets` (object) It works as follows. Note that all the sub-objects are optional, except x, y and z. You can have for example only a main hand with a position, and noting else. default: no render offset 39 | ```json 40 | "render_offsets": { 41 | "main_hand": { 42 | "first_person": { 43 | "position": { 44 | "x": 0, 45 | "y": 0, 46 | "z": 0 47 | }, 48 | "rotation": { 49 | "x": 0, 50 | "y": 0, 51 | "z": 0 52 | }, 53 | "scale": { 54 | "x": 0, 55 | "y": 0, 56 | "z": 0 57 | } 58 | }, 59 | "third_person": { 60 | 61 | } 62 | }, 63 | "off_hand": { 64 | 65 | } 66 | } 67 | ``` 68 | 69 | ## Geyser extensions 70 | 71 | ### Extending a vanilla item 72 | 73 | 1. Create your custom item options or registrations, to which you can add any of the following. They can be stacked, so that all of the specified types need to match, but you **do NOT need all of them.** 74 | ```java 75 | CustomItemOptions itemOptions = CustomItemOptions.builder() 76 | .customModelData(1) 77 | .damagePredicate(1) //This is a fractional value of damage/max damage and not a number between 0 and 1. 78 | .unbreakable(true) 79 | .build(); 80 | ``` 81 | 2. Create your custom item, and store it somewhere: 82 | ```java 83 | CustomItemData data = CustomItemData.builder() 84 | .name("my_item") 85 | .customItemOptions(itemOptions) 86 | .build(); 87 | ``` 88 | 3. You have some modifiers that you can set to further customise your item. **Note that the following modifiers are NOT required.** 89 | ```java 90 | .displayName("displayName"); //Default: item name 91 | .icon("my_icon"); //Default: item name 92 | .allowOffhand(false); //Default: false 93 | .textureSize(16); //Default: 16 94 | .renderOffsets(new CustomRenderOffsets(...)); //Default: no render offset 95 | ``` 96 | 4. Then, in your pre init event, you can register your item: 97 | ```java 98 | @Subscribe 99 | public void onGeyserPreInitializeEvent(GeyserDefineCustomItemsEvent event) { 100 | event.registerCustomItem("minecraft:JAVA_ITEM", data); 101 | } 102 | ``` 103 | 104 | ### Non vanilla (modded) items with Geyser extensions (for example to use with Fabric) 105 | 106 | 1. Create your item data: 107 | ```java 108 | NonVanillaCustomItemData data = NonVanillaCustomItemData.builder() 109 | .name("my_item") 110 | .identifier("my_mod:my_item") 111 | .javaId(1) 112 | ``` 113 | 2. There are many other options you can set to match the behavior that you require for your item. You can see them [here](https://github.com/GeyserMC/Geyser/blob/master/api/geyser/src/main/java/org/geysermc/geyser/api/item/custom/NonVanillaCustomItemData.java) 114 | 3. Register your item in the pre init event: 115 | ```java 116 | @Subscribe 117 | public void onGeyserPreInitializeEvent(GeyserDefineCustomItemsEvent event) { 118 | event.registerCustomItem(data); 119 | } 120 | ``` 121 | 122 | ## Resource pack 123 | 124 | 1. Setup a basic bedrock resource pack. If you need help, you can find it [here](https://wiki.bedrock.dev/guide/project-setup.html#rp-manifest). 125 | 2. Make a `textures` folder. 126 | 3. Create `item_texture.json` in the `textures`, and put this in it: 127 | ```json 128 | { 129 | "resource_pack_name": "MY_PACK_NAME_HERE", 130 | "texture_name": "atlas.items", 131 | "texture_data": { 132 | 133 | } 134 | } 135 | ``` 136 | 4. Inside texture data, you can add your items. The texture name and path must match the name that you set in your mappings. 137 | ```json 138 | "my_item": { 139 | "textures": [ 140 | "textures/items/my_item" 141 | ] 142 | } 143 | ``` 144 | 5. Then you need to put your textures inside the `textures/items`. Make sure to have it match the texture path that you specified in `item_texture.json`! 145 | --------------------------------------------------------------------------------