Hi everyone,

I'm currently developing a Forge 1.21 mod for Minecraft and I want to display a custom HUD overlay for a minigame.
My goal: When the game starts, all players should see an item/block icon (from the base game, not a custom texture) plus its name/text in the HUD – similar to how the bossbar overlay works. The HUD should appear centered above the hotbar (or at a similar prominent spot), and update dynamically (icon and name change as the target item changes).

What I've tried:

I looked at many online tutorials and several GitHub repos (e.g. SeasonHUD, MiniHUD), but most of them use NeoForge or Forge versions <1.20 that provide the IGuiOverlay API (e.g. implements IGuiOverlay, RegisterGuiOverlaysEvent).

In Forge 1.21, it seems that neither IGuiOverlay nor RegisterGuiOverlaysEvent exist anymore – at least, I can't import them and they are missing from the docs and code completion.

I tried using RenderLevelStageEvent as a workaround but it is probably not intended for custom HUDs.

I am not using NeoForge, and switching the project to NeoForge is currently not an option for me.

I tried to look at the original minecraft source code to see how elements like hearts, hotbar etc are drawn on the screen but I am too new to Minecraft modding to understand.

What I'm looking for:

What is the correct way to add a custom HUD element (icon + text) in Forge 1.21, given that the previous overlay API is missing?

Is there a new recommended event, callback, or method in Forge 1.21 for custom HUD overlays, or is everyone just using a workaround?

Is there a minimal open-source example repo for Forge 1.21 that demonstrates a working HUD overlay without relying on NeoForge or deprecated Forge APIs?

My ideal solution:

Centered HUD element with an in-game item/block icon (from the base game's assets, e.g. a diamond or any ItemStack / Item) and its name as text, with a transparent background rectangle.
It should be visible to the players when the mini game is running.

Easy to update the item (e.g. static variable or other method), so it can change dynamically during the game.

Any help, code snippets, or up-to-date references would be really appreciated!
If this is simply not possible right now in Forge 1.21, it would also help to know that for sure.

Thank you very much in advance!

Hello! I actually ran into the same issue as you. After a lot of searching, I found that starting from Minecraft version 1.20.5, Mojang adjusted the rendering system. This change means that versions 1.20.5 and later no longer have the "overlay" folder or its internal interfaces, including RegisterGuiOverlaysEvent.java.

I really hope this post doesn't get buried, as this is genuinely important for mod development. I also hope someone incredibly skilled can solve this problem and share their solution here. Thanks in advance to everyone!