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
| Component | What you need | Tested with |
|---|---|---|
| Server | Paper or a Paper fork, Minecraft 1.21.x | Paper 1.21.4 |
| Java | 21 or newer | 21 |
| Geyser | Geyser-Spigot on the same server, API 2.11.3 or newer | 2.12.1 |
| Floodgate | Usually installed next to Geyser | – |
| ProtocolLib | Needed 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 R4 | Nexo 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
- Install Geyser-Spigot (and usually Floodgate) and ProtocolLib on your Paper server, if they are not there yet.
- Stop the server and put
nusapack-paper.jarin theplugins/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 intoplugins/Geyser-Spigot/extensions/by itself. - 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. - If you have a licensed build, add your license key now. The License key section below shows how.
- Restart the server.
- Run
/npb convertin game, ornpb convertin 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. - Read the last line of the result and do what it says.
Read the result line
| The last line says | What to do |
|---|---|
| Live for Bedrock · pack ... · players rejoin to see it | Nothing 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 folder | What it is for |
|---|---|
settings.yml | Everyday options, with one comment per value. Start here. |
config.yml | Advanced: the server identity. Usually left as it is. |
sources.yml | Advanced: manual sources and unusual pack locations. |
still-textures.yml | Animated textures that should stay still on Bedrock. |
glyphs-auto.yml | Written after every conversion: each glyph with the height it shipped at. |
glyphs.yml | Optional: your own glyph sizes, copied from glyphs-auto.yml. |
gui-bindings.json | Optional: custom chest menus described by hand. |
old-extensions/ | Older copies of the Geyser extension that NusaPack moved out of the way. |
nusa-license.properties | Licensed 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.
- After the first start, open
plugins/NusaPackBridge/nusa-license.propertiesin a text editor. - Put your license key after
license-key=on that line, replacing the placeholder, and save the file. - 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
- Stop the server.
- Replace
nusapack-paper.jarinplugins/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 toplugins/NusaPackBridge/old-extensions/. - 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
- Everyday use: the routine after you change content.
- Settings: the options in
settings.yml. - Troubleshooting: when Bedrock players still see vanilla items.