Bedrock / Geyser / Rich UI Guide

This page explains how to show EasyMenu to Bedrock Edition players who connect through Geyser.

Read this first

EasyMenu opens as an inventory GUI by default. Installing Geyser alone gives Bedrock players the (Geyser-converted) inventory screen. To use Bedrock forms or the Rich UI, choose a presentation mode in the menu (or in config.yml).

---

The Big Picture

Three separate settings are involved in Bedrock display. Do not confuse them.

Setting	Where	Role
Presentation mode	EasyMenu presentation.mode / dialog / runtime.default-presentation in config.yml	Chooses which kind of screen opens. The default is inventory.
bedrock.rich-ui	plugins/NegiLib/config.yml	Decides whether Rich UI is allowed. The default is auto (allowed).
Geyser	Geyser-Spigot or Geyser-Velocity	Connects Bedrock players to the Java server.

bedrock.rich-ui: auto means "Rich UI may be used"; it does not change a menu's presentation mode. A menu whose mode stays inventory opens as an inventory GUI regardless of bedrock.rich-ui.

---

Setup Steps

1. Pick a topology and install

Choose one of the two topologies and install the required JARs.

2. Decide the presentation mode

To auto-select for the whole server, edit plugins/EasyMenu/config.yml:

plugins/EasyMenu/config.yml

runtime:
  default-presentation: auto

It applies to every menu that has no presentation of its own. Run /menu reload after changing it.

To prefer Rich UI for one specific menu, write it in that menu's YAML:

plugins/EasyMenu/sub/shop.yml

presentation:
  mode: rich-preferred
  fallback: true
  native:
    columns: 3
    button-width: 128

native.columns and native.button-width are used not only by the Java dialog but also as layout hints for Bedrock (how layout is handled).

3. Check the NegiLib side

The default is fine. Change it only when you do not want Rich UI used:

plugins/NegiLib/config.yml

bedrock:
  rich-ui: auto   # auto (default) or off

With off, Rich UI is never used and the plain Bedrock form (SimpleForm) is always used. Any value other than off behaves like auto.

4. Verify on a Bedrock device

Reconnect and run /menu. After a pack update, and on the first connection, reconnect once.

---

What to Install per Topology

Geyser-Spigot topology (direct Paper)

Geyser runs on the same server as EasyMenu (Paper / Purpur / Folia).

Where	What to install
Paper / Purpur / Folia	NegiLib-1.1.1.jar, EasyMenu-7.0.2.jar, Geyser-Spigot
Velocity	Nothing

• The Velocity companion is not needed.
• When NegiLib detects Geyser-Spigot, its Geyser rendering support turns on automatically.

Geyser-Velocity topology (proxy)

Geyser runs on Velocity, and Paper-family servers are the backends.

Where	What to install
Velocity	Geyser-Velocity, NegiLib-Geyser-Velocity-1.1.1.jar (the NegiLib Geyser Velocity Companion)
Paper / Purpur / Folia (backend)	NegiLib-1.1.1.jar (required), EasyMenu-7.0.2.jar

• The backend also needs the NegiLib plugin itself. The Velocity companion alone does not work.
• Install EasyMenu on every backend whose menus you use.
• The companion and the backend talk over the negilib:bridge plugin-message channel.

In both topologies EasyMenu and NegiLib go on the Paper-family server. Only the location of Geyser and the companion differs.

---

Presentation Mode Differences

The mode a menu (or the whole server) requests determines the order in which renderers are tried. With fallback: true (the default), each mode tries renderers left to right and uses the first one that works.

Mode	Order tried (fallback: true)	With fallback: false
inventory (default)	Inventory only	Same
native-preferred	Native Dialog → Inventory	Only Native Dialog is tried
native-required	Native Dialog only	Same (never falls back)
rich-preferred	Rich UI → plain Bedrock form → Native Dialog → Inventory	Only Rich UI is tried
rich-required	Rich UI only	Same (never falls back)
auto	Rich UI → plain Bedrock form → Native Dialog → Inventory	Only Rich UI is tried

• Whether a renderer "works" is decided per player. Rich UI and the plain Bedrock form are used only for Bedrock players connected through Geyser. Java players skip them and move on to the next renderer.
• A *-required mode never switches renderers, and the menu does not open when the requirement is not met. The player receives a message saying the menu cannot be displayed on this server version.
• With fallback: false, even *-preferred and auto try only the first renderer instead of moving on.
• If a renderer fails while opening, EasyMenu retries with the next one when fallback allows it (except for inventory and *-required).
• rich-preferred and auto try renderers in the same order.

native-preferred and Bedrock players

native-preferred does not try Bedrock forms. To give Bedrock players a dedicated screen, use rich-preferred or auto. This wiki has not verified how a Bedrock player sees a menu opened with native-preferred (how Geyser translates the dialog).

The "plain Bedrock form" is the standard form that does not use the Rich UI pack. It is the safe substitute when Rich UI cannot be used.

---

What Rich UI Is

Rich UI is a polished menu screen that NegiLib builds as a Bedrock JSON UI resource pack and delivers to Bedrock clients through Geyser.

• On connection, the pack (current revision negilib-rich-ui-v11) is registered with the Geyser session. After a pack update, a reconnect is needed for it to apply.
• Item icons use textures Bedrock already has. A custom icon generated after a player connected is not referenced until they reconnect.
• A successful pack registration does not prove that the client parsed and displayed the JSON UI correctly.

When Rich UI cannot be used (the pack is not registered, bedrock.rich-ui: off, ...) or sending fails, the plain Bedrock form is used instead if fallback allows it.

How layout is handled

Bedrock Rich UI layout follows different constraints from the Java Native Dialog.

Item	Java Native Dialog	Bedrock Rich UI
Columns	1-8 (default 3)	The value acts as an upper bound of about 3 columns; it wraps automatically to 3, 2 or 1 depending on screen width
Button width	1-1024 (default 150)	Rounded into three tiers (100 or less / 101-180 / 181 or more), giving cell widths of 112 / 128 / 144
Height	Follows content	82% of the screen height; the title and close button are fixed and only the content scrolls

---

Compatibility and What Is Unverified

On-device rendering is not verified

NegiLib's Rich UI is covered by automated tests for the structure of the generated pack and the messaging, but display on client devices, GUI-scale changes, and behavior per input device are not verified by automated tests. JSON UI behavior can differ by Bedrock client version and device (phone, console, PC). We cannot call it "fully supported."

Before relying on it, check these on the clients you actually use:

• Four buttons laid out in two columns, and a partially filled last row that does not break
• Long menus where the last button is reachable by scrolling
• GUI-scale changes and narrow screens
• Touch and controller scrolling
• Disabled buttons, icons, tooltips and the close button

If Rich UI misbehaves, set bedrock.rich-ui: off in plugins/NegiLib/config.yml to return to the plain Bedrock form.

---

Checklist

When a Bedrock player's screen is not what you expect, check these in order:

1. EasyMenu and NegiLib are installed on the Paper / Purpur / Folia side (also on the backend in a Velocity setup).
2. The right Geyser is installed (Geyser-Spigot for direct Paper; Geyser-Velocity plus the companion for Velocity).
3. The menu's presentation mode is not still inventory (presentation.mode, dialog, runtime.default-presentation). dialog: false pins the display to inventory.
4. bedrock.rich-ui is not off.
5. You disconnected and reconnected (required after a pack update and on the first connection).
6. The server log shows no warning such as Geyser Rich UI pack registration failed or using clean SimpleForm fallback. If it does, Rich UI is not used and the plain form is shown.
7. You tried the verification items above on your client.