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

RequirementDetails
Geyser-Spigot on the same Paper serverNusaPack delivers its packs to Geyser-Spigot on this server. Geyser API 2.11.3 or newer; tested with 2.12.1.
FloodgateUsually installed next to Geyser, so Bedrock players can join without a Java account.
Custom content switched onGeyser'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:

  1. NusaPack puts its extension into plugins/Geyser-Spigot/extensions/nusapack-geyser.jar, or replaces an older build there.
  2. Other copies of the NusaPack extension in that folder are moved to plugins/NusaPackBridge/old-extensions/. Nothing is deleted.
  3. 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:

MessageMeaning
up to dateThe extension matches this NusaPack version. Nothing to do.
installed · restart to loadFirst install. Restart once.
updated · restart to loadA newer extension was put in place. Restart once.
update ready · applied on shutdown, then restartThe file was locked. Stop the server, then start it again.
skipped · Geyser not installedGeyser-Spigot is missing on this server.
install failed (...) · copy nusapack-geyser.jar to Geyser's extensionsNusaPack could not write the file. Check folder permissions, or copy it yourself.
manualgeyser_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: manual

With 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

  1. /npb convert finishes a pack. With auto_deliver on (the default), NusaPack hands it to the extension right away.
  2. 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.
  3. If the pack adds or removes things Geyser registers at startup, the result says Installed · restart the server once. /npb status then shows the pack under After restart until you restart.
  4. 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

Nusa product documentation · NusaPackPaper 1.21.x · Java 21

Loading the index…