Install NusaPack

Install NusaPack, do the first start and the one restart, run your first conversion and find the config files.

On this page

This page takes you from an empty plugins/ folder to Bedrock players seeing your custom content. Plan for one or two restarts during the first setup.

Requirements

ComponentWhat you needTested with
ServerPaper or a Paper fork, Minecraft 1.21.xPaper 1.21.4
Java21 or newer21
GeyserGeyser-Spigot on the same server, API 2.11.3 or newer2.12.1
FloodgateUsually installed next to Geyser–
ProtocolLibNeeded for the live Bedrock views: glyphs in chat and the tab list, custom menus, furniture and ModelEngine mobs. Converting works without it.5.4.0
Content plugins (optional, any mix)Nexo, ItemsAdder, Oraxen, CraftEngine, EcoItems, ModelEngine R4Nexo 1.28, ItemsAdder 4.0.15, Oraxen 1.220.1, CraftEngine 26.9.2, EcoItems 5.58.0, ModelEngine R4.2.0

Other versions of the content plugins are accepted too. They convert normally, with a one-time "untested version" warning, and /npb check shows which of your versions are tested. ModelEngine must be R4; R3 has a different API.

Install step by step

  1. Install Geyser-Spigot (and usually Floodgate) and ProtocolLib on your Paper server, if they are not there yet.
  2. Stop the server and put nusapack-paper.jar in the plugins/ folder. This is the only NusaPack file you install or update. It carries NusaPack's Geyser extension (a small add-on that runs inside Geyser) and copies it into plugins/Geyser-Spigot/extensions/ by itself.
  3. Start the server. On this first start NusaPack installs its Geyser extension and creates the plugins/NusaPackBridge/ folder. The console then asks for one more restart so Geyser can load the extension.
  4. If you have a licensed build, add your license key now. The License key section below shows how.
  5. Restart the server.
  6. Run /npb convert in game, or npb convert in the console. This one command does everything: it rebuilds the pack of every installed content plugin, imports custom chest menus, converts items, blocks, armour, fonts, sounds, menus and ModelEngine mobs, and delivers the result to Geyser.
  7. Read the last line of the result and do what it says.

Read the result line

The last line saysWhat to do
Live for Bedrock · pack ... · players rejoin to see itNothing else. Bedrock players see the new pack after they leave and join again.
Installed · restart the server once (...)Restart the server once. Geyser only registers custom items, blocks and mobs while it starts; that is a Geyser rule, not a NusaPack one.

The very first conversion on a server always needs one restart. After that, many changes only need a rejoin; Everyday use explains which.

If some content did not make it, the result lists it under "Left out or adjusted" with the reason. One plugin never stops the others.

Where the files live

Everything NusaPack creates is in plugins/NusaPackBridge/:

File or folderWhat it is for
settings.ymlEveryday options, with one comment per value. Start here.
config.ymlAdvanced: the server identity. Usually left as it is.
sources.ymlAdvanced: manual sources and unusual pack locations.
still-textures.ymlAnimated textures that should stay still on Bedrock.
glyphs-auto.ymlWritten after every conversion: each glyph with the height it shipped at.
glyphs.ymlOptional: your own glyph sizes, copied from glyphs-auto.yml.
gui-bindings.jsonOptional: custom chest menus described by hand.
old-extensions/Older copies of the Geyser extension that NusaPack moved out of the way.
nusa-license.propertiesLicensed builds only: where your license key goes.

The Geyser extension itself lives in plugins/Geyser-Spigot/extensions/.

License key

Only licensed builds need this step.

  1. After the first start, open plugins/NusaPackBridge/nusa-license.properties in a text editor.
  2. Put your license key after license-key= on that line, replacing the placeholder, and save the file.
  3. Restart the server.

If your host lets you set environment variables, you can put the key in NUSAPACK_LICENSE_KEY instead. When that variable is set, it is used instead of the file.

The Geyser extension reads the same file, so you only add the key once. Until a valid key is in place, the plugin stays disabled and every /npb command answers "NusaPack Bridge is locked". The console tells you what is wrong. Keep your key private: never post it in chat, tickets or screenshots.

Updating NusaPack

  1. Stop the server.
  2. Replace nusapack-paper.jar in plugins/ with the new version. You do not need to touch the Geyser extension: NusaPack replaces the older build in Geyser's extensions folder at startup, and moves older copies with other names to plugins/NusaPackBridge/old-extensions/.
  3. Start the server and read the console. A new or changed extension loads from the next start, and the console says when a restart is needed.

Your settings are kept. New options are added to the end of settings.yml with their comments, and values you already set are not touched. Values from older versions in sources.yml or config.yml are moved into settings.yml by themselves.

Next steps

Nusa product documentation · NusaPackPaper 1.21.x · Java 21

Loading the index…