Geyser and the extension
What NusaPack needs from Geyser, how its Geyser extension is installed and updated, how packs reach Bedrock players, and why proxy Geyser is not supported.
On this page
NusaPack works together with Geyser, the plugin that lets Bedrock players join your Java server. This page explains the Geyser settings NusaPack needs, how the NusaPack extension gets into Geyser, how a converted pack reaches players, and which changes need a restart.
What NusaPack needs from Geyser
| Requirement | Details |
|---|---|
| Geyser-Spigot on the same Paper server | NusaPack delivers its packs to Geyser-Spigot on this server. Geyser API 2.11.3 or newer; tested with 2.12.1. |
| Floodgate | Usually installed next to Geyser, so Bedrock players can join without a Java account. |
| Custom content switched on | Geyser's enable-custom-content option must be true (in newer Geyser config files it sits under gameplay). |
| Forced resource packs (recommended) | With force-resource-packs set to false, Bedrock players can decline the pack and then see vanilla items. |
Both options live in plugins/Geyser-Spigot/config.yml. Change them while the server is stopped, or restart afterwards. /npb check reads this file and warns when either option is off.
How the extension is installed
A Geyser extension is a small add-on that runs inside Geyser. NusaPack needs one to register its items, blocks and mobs and to serve its pack. You do not install it separately: nusapack-paper.jar carries it.
With the default setting geyser_extension: auto, every server start goes like this:
- NusaPack puts its extension into
plugins/Geyser-Spigot/extensions/nusapack-geyser.jar, or replaces an older build there. - Other copies of the NusaPack extension in that folder are moved to
plugins/NusaPackBridge/old-extensions/. Nothing is deleted. - Geyser loads its extensions before NusaPack starts, so a new or changed extension is used from the next start. The console tells you when a restart is needed.
On Windows, where a running file can be locked, the swap happens when the server stops; restart once more afterwards.
Extension messages at startup
The startup summary in the console has an Extension row:
| Message | Meaning |
|---|---|
up to date | The extension matches this NusaPack version. Nothing to do. |
installed · restart to load | First install. Restart once. |
updated · restart to load | A newer extension was put in place. Restart once. |
update ready · applied on shutdown, then restart | The file was locked. Stop the server, then start it again. |
skipped · Geyser not installed | Geyser-Spigot is missing on this server. |
install failed (...) · copy nusapack-geyser.jar to Geyser's extensions | NusaPack could not write the file. Check folder permissions, or copy it yourself. |
manual | geyser_extension is set to manual; NusaPack leaves the folder alone. |
If an older copy was moved aside, the row also says older copy moved to old-extensions.
Manual mode
geyser_extension: manualWith manual, NusaPack never touches plugins/Geyser-Spigot/extensions/. You place and update nusapack-geyser.jar there yourself, and you must keep it at the same version as nusapack-paper.jar. If the extension is older than the plugin, conversions ask for a restart and tell you to update nusapack-geyser.jar. This setting applies from the next server start. Most servers should keep auto.
How a pack reaches Bedrock players
/npb convertfinishes a pack. Withauto_deliveron (the default), NusaPack hands it to the extension right away.- If the pack only changes things Geyser can swap on the fly (textures, models, menus, fonts, sounds), the extension offers it to new Bedrock sessions at once. The result says Live for Bedrock, and players see it after a rejoin.
- If the pack adds or removes things Geyser registers at startup, the result says Installed · restart the server once.
/npb statusthen shows the pack under After restart until you restart. - When a Bedrock player joins, Geyser sends the pack. With forced packs on, the player cannot skip it.
What needs a restart
Geyser registers custom items, blocks and mobs only while it starts. Because Geyser-Spigot runs inside your Paper server, that means a server restart for:
- a new or updated NusaPack extension
- the first conversion on a server
- adding or removing custom items, custom blocks or ModelEngine mobs
- changing an item's behaviour or a player-head skin
- adding a new custom fishing rod
Everything else goes live on rejoin. The last line of /npb convert always tells you which case you are in.
Proxy and standalone Geyser
NusaPack does not support Geyser on a Velocity or BungeeCord proxy, or Geyser Standalone, yet. Conversion delivery and the live bridges for glyphs, furniture and ModelEngine mobs all expect Geyser-Spigot on the same Paper server.
If your network runs Geyser on the proxy today, install Geyser-Spigot on the Paper server that runs NusaPack instead. The manual value of geyser_extension only stops NusaPack from managing the extensions folder; it does not make a proxy or standalone setup supported.
Next steps
- Installation: the full install order.
- Everyday use: converting and delivering after each change.
- Troubleshooting: when
/npb checkreports an extension problem.