Custom Item API | GeyserMC | Page 1

grim verge Jun 3, 2025, 2:23 PM

#

@lyric turret Hi, sorry to ping you but I really need some help with the custom item API pull request stuff. I don't know if you remember, but I requested that you add the ability to allow Bedrock players to see items that use the item_model component as what that component is set to, rather than what the item actually is, all without a resource pack.

You added it, and gave me an example mapping file (https://github.com/GeyserMC/Geyser/pull/5189#issuecomment-2869907862), which I really appreciate. But I must admit I don't know what to do from that point, i.e. how do I "link" my custom items to the mapping?

lyric turret Jun 4, 2025, 7:33 AM

#

Hi, sorry for the delay. I'll try to respond later today, in college at the moment.

grim verge Jun 4, 2025, 7:55 AM

#

Not a problem, thank you so much!

grim verge Jun 8, 2025, 11:10 AM

#

lyric turret Hi, sorry for the delay. I'll try to respond later today, in college at the mome...

Hey, sorry for pinging and sorry if you're just busy, but just wanted to make sure you hadn't forgotten about this 🥺

lyric turret Jun 9, 2025, 6:48 AM

#

Hi - I did indeed forget, sorry!
I'm going to try remember this time ehe. I'm having breakfast right now but I'll get to you once I finished. If I forgot again, do feel free to ping me

grim verge Jun 9, 2025, 7:40 AM

#

I appreciate it thank you!!

lyric turret Jun 9, 2025, 8:07 AM

#

Right, so essentially you want items that display with a different (vanilla) item model than their default one, which you do on Java by simply changing the item_model component of an item stack.
Bedrock doesn't have anything even remotely close to such a component. You can't change the appearance of a vanilla item in any way without changing all instances of that vanilla item through a resourcepack.
To get around this, Geyser emulates custom items like those by creating entirely custom items on the bedrock side, which bedrock does allow for. To create these entirely custom items, Geyser has to specify a bunch of properties for bedrock, like the item's max stack size, its icon, its durability, etc.
This is what the mappings file is for. In Geyser's item mappings, you specify the vanilla item you use "under the hood" to create your custom items, the item model you use for that item, any component patches you have applied to the item, etc. Geyser uses all of this information to calculate the properties the custom item it creates should have.

In your case it is quite simple, you're only changing the item_model component, so to match for that in a mappings file, you could do something like this:

{
  "format_version": 2,
  "items": { // <-- All custom items go in here
    "minecraft:poisonous_potato": [ // <-- All custom items making use of the vanilla poisonous potato under the hood go in here

      // A single item definition, defining a custom item
      // This matches for any poisonous potato with an item_model of "minecraft:iron_ingot"
      {
        "type": "definition",
        "model": "minecraft:iron_ingot", // <-- the item model to match for
        "bedrock_identifier": "poisonous_iron", // <-- the bedrock identifier - this has to be unique for every single custom item you define
      }
    ]
  }
}

#

When you enter this in Geyser, it'll surely do something. Geyser creates a custom bedrock item called poisonous_iron on the bedrock side, and whenever Geyser sees a poisonous potato with minecraft:iron_ingot as its item model, it will translate it as the custom geyser_custom:poisonous_iron item (when no namespace is specified in the bedrock identifier, geyser_custom is used by default).

However, this probably won't work as expected. Put simply, every custom bedrock item needs to have an icon specified, however we didn't specify any here. When that happens, Geyser will automatically define an icon for us. In this case this would be geyser_custom.poisonous_iron.
We'd then have to create a resourcepack with that icon in it. However, we don't have a resourcepack, so instead bedrock will render every instance of our custom item as transparent.

To get around this, we can specify our own icon, and make use of a vanilla one. In this example case we'd want to use iron_ingot, so that our custom item shows exactly as an iron ingot. We'd specify this as follows:

{
  "format_version": 2,
  "items": {
    "minecraft:poisonous_potato": [
      {
        "type": "definition",
        "model": "minecraft:iron_ingot",
        "bedrock_identifier": "poisonous_iron",
        "bedrock_options": {
          "icon": "iron_ingot"
        }
      }
    ]
  }
}

#

You can see we only really added one thing to our custom item definition, that is a single "bedrock option" specifying the icon of our custom item. If you look through bedrock's vanilla item atlas you can see all the vanilla icons (every key in the texture_data object is an icon).

If you put the above code in a mapping file in Geyser's custom_mappings folder, Geyser should then display all poisonous potatoes that have minecraft:iron_ingot as item model as an iron ingot.

Last note: don't worry too much about the bedrock_identifier string. As long as it's unique, it should be fine for your case. It's used in places around bedrock resourcepacks, however you aren't using those. Just make sure it's fairly recognisable as Geyser also uses it in error messages.

That got very long very quickly - sorry ehe. I hope this clears things up a bit though. If you have any further questions, please do let me know.

grim verge Jun 9, 2025, 8:26 AM

#

lyric turret You can see we only really added one thing to our custom item definition, that i...

That clears a lot up, thank you so much for putting time into this writeup!

So, just to be clear, I don't actually need to put any additional data inside my custom items for Geyser to be able to identify them as custom items - as long as they have an item_model component set, and I set my mapping up to match it, it should be enough?

Also, in my case, I actually do have some additional components set on the custom items, I just wanted to omit that to help me understand this better. My custom items are all minecraft:music_disc_13, because I believe music discs to be the ultimate agreed upon dummy item. They all have their jukebox_playable component removed, their enchantment_glint_override component set to true, and a couple of others. How would this look inside the mapping file?

lyric turret Jun 9, 2025, 8:33 AM

#

As for your first point - yes, that should be enough. If it doesn't work, then feel free to let me know to investigate.

Further, you can specify components as so:

{
  "format_version": 2,
  "items": {
    "minecraft:poisonous_potato": [
      {
        "type": "definition",
        "model": "minecraft:iron_ingot",
        "bedrock_identifier": "poisonous_iron",
        "bedrock_options": {
          "icon": "iron_ingot"
        },
        "components": {
          "minecraft:enchantment_glint_override": true
        }
      }
    ]
  }
}

Geyser is able to detect component changes to some capacity. Any component listed in the screenshot needs to be specified in the mappings when added or removed. Other components are either not supported, or automatically translated without needing to be specified.

Sidenote: component removals can be specified for every component, even those not in the screenshot, however only for certain components Geyser will actually do something with this. In the case of the jukebox_playable component, it should be fine to not specify it in the mappings, Geyser should be able to automatically translate it.

grim verge Jun 9, 2025, 9:30 AM

#

lyric turret As for your first point - yes, that should be enough. If it doesn't work, then f...

Great, thank you!

#

I've tested a basic mapping (see screenshot), but my items seem to be invisible, despite having an icon specified. I tried with and without the minecraft: namespace. Any ideas?

tight dragon Jun 9, 2025, 9:39 AM

#

I think bedrock has different names for some of the item textures... horsearmoriron is a good one, the bedrock-samples repo has all the textures in there, might be able to find the name there just to ensure that isn't it

grim verge Jun 9, 2025, 10:15 AM

#

tight dragon I think bedrock has different names for some of the item textures... horsearmori...

Thank you for the pointer! So beetroot_soup actually worked for me from the beginning. I still cannot get the netherite_hoe or sunflower to work though. I noticed the key for tools/armour in https://github.com/Mojang/bedrock-samples/blob/main/resource_pack/textures/item_texture.json has multiple textures associated with it (see screenshot for hoe example). How would I represent this in the mapping file, if I want one specific texture (netherite in my case)?

#

#

also, I cannot for the life of me seem to be able to find the sunflower icon 😭

grim verge Jun 9, 2025, 10:17 AM

#

grim verge Thank you for the pointer! So `beetroot_soup` actually worked for me from the be...

if I just put "hoe" as the key, it appears as a wooden hoe

lyric turret Jun 9, 2025, 10:20 AM

#

sunflower might not be in there because it is a block with a hardcoded icon, at least that's what i suspect
as for icons with multiple textures that also appears to be hardcoded defined in a way, so you can't really use it for your own custom items, i think
the only way to get around this is to create your own resource pack with its own texture atlas, not sure if that can refer to vanilla textures or not

grim verge Jun 9, 2025, 10:22 AM

#

aw man :(

sudden lotusBOT Jun 9, 2025, 10:22 AM

#

grim verge aw man :(

Level Up!

You leveled up to level 5!

grim verge Jun 9, 2025, 10:23 AM

#

I guess I will have to create a resource pack

grim verge Jun 10, 2025, 9:46 AM

#

Looks like they can refer to vanilla textures! Created my own pack with only this atlas and no actual textures, and it worked! :)

#

Thanks for the help guys! Hopefully this PR gets merged into Geyser soon

tight dragon Jun 11, 2025, 11:41 AM

#

Hoping for preview builds soon!
~~100% not because that'll open up the hydraulic channel hehe~~

grim verge Jun 17, 2025, 4:23 PM

#

@lyric turret when a Geyser release supporting MC 1.21.6 comes out, would you be able to build the Custom Item API PR against it? my server somewhat relies on it now (I know not a great idea) 🙏

lyric turret Jun 17, 2025, 4:24 PM

#

Yeah of course. I'll also merge 1.21.90 support into it soon. I also plan to work on it more soon once my semester finishes, so hopefully it'll be in preview soon

grim verge Jun 17, 2025, 4:30 PM

#

You're a king

#

ah yeah what I meant was 1.21.90 bedrock support, not necessarily java server 1.21.6 support (my server is still running 1.21.4)

#

I hate how they decided to no longer keep the version numbers inline with each other .-.

lyric turret Jun 17, 2025, 4:34 PM

#

grim verge ah yeah what I meant was 1.21.90 bedrock support, not necessarily java server 1....

Will be all done in 1.5 hours at most

grim verge Jun 17, 2025, 5:21 PM

#

are you planning on merging the skin fix as well when that is released?

#

(sorry for all the questions)

lyric turret Jun 17, 2025, 5:22 PM

#

Yeah, likely

#

I merged master now, just wait for it to build and you should be all good, let me know if there are any issues :)

grim verge Jun 17, 2025, 5:23 PM

#

I will if I find any!

lyric turret Jun 26, 2025, 5:42 PM

#

grim verge <@972572171039805460> when a Geyser release supporting MC 1.21.6 comes out, woul...

Has updated now, please do let me know if you find any issues

grim verge Jul 3, 2025, 8:49 PM

#

Any danger of a build against the latest geyser for 1.21.93? 🥺

tight dragon Jul 3, 2025, 8:50 PM

#

oh yeah now hydraulic doubly doesn't work

lyric turret Jul 3, 2025, 9:39 PM

#

grim verge Any danger of a build against the latest geyser for 1.21.93? 🥺

Oh give me like 2 mins

lyric turret Jul 3, 2025, 9:46 PM

#

grim verge Any danger of a build against the latest geyser for 1.21.93? 🥺

Next build will have support, also, if you don't mind, could you tell me a bit about what kind of custom items you have?
Like, e.g., do they all just use vanilla textures? Do you use any of 1.21.4's more complex model features?

grim verge Jul 3, 2025, 11:10 PM

#

lyric turret Next build will have support, also, if you don't mind, could you tell me a bit a...

They're nothing crazy. They all just use vanilla textures

#

My usage of this custom item API is probably barely scratching the surface of what it can do, so I'm probably not the best guinea pig for you :P

grim verge Sep 30, 2025, 7:33 PM

#

Is Custom Item API PR going to have a build for the new Geyser soon?

lyric turret Sep 30, 2025, 8:41 PM

#

Yes

#

Right now I'm very busy with 1.21.9 but it should have a build that supports 1.21.111 soon

grim verge Sep 30, 2025, 9:33 PM

#

I got it, thank you so much!

grim verge Feb 9, 2026, 5:42 PM

#

Hello, were there any breaking changes to the Custom Item API V2 before it got merged? I have a simple pack that simply makes it so that my custom items (I only have 3) that use the item_model component use the vanilla texture that said component points to. But now (since updating from the branch builds to the main one) the items appear to be invisible in containers and in dropped form

📎 custom_items.json 📎 item_texture.json

grim verge Feb 11, 2026, 9:40 AM

#

Disregard this, looks like build #1071 fixed it :)

left hinge Feb 11, 2026, 10:21 AM

#

grim verge Disregard this, looks like build #1071 fixed it :)

Okay! :)

sudden lotusBOT Feb 11, 2026, 10:21 AM

#

Post is tagged with Answered

#Custom Item API