Everyday use

The routine after you change content, when a rejoin is enough and when you need a restart, plus automatic conversion and the in-game panel.

On this page

Once NusaPack is installed, keeping Bedrock players up to date is a short routine. This page walks through it, explains when a rejoin is enough and when you need a restart, and shows the in-game panel.

The basic routine

  1. Change your content as usual in Nexo, ItemsAdder, Oraxen, CraftEngine, EcoItems or ModelEngine.
  2. Run /npb convert.
  3. Read the last line of the result. Either ask Bedrock players to rejoin, or restart the server once.

Three commands cover most days:

/npb convert          convert everything and deliver it to Geyser
/npb status           what is active and what waits for a restart
/npb report errors    why something did not convert

In the console, type the same commands without the slash, for example npb convert.

What a conversion does

/npb convert handles the whole job:

  • It detects which content plugins are installed and switched on, and shows what it found, for example Detected: Nexo 1.28, ItemsAdder 4.0.15.
  • It rebuilds each plugin's pack. ModelEngine goes first, Nexo and Oraxen go last because they merge the other packs. ItemsAdder is rebuilt with /iazip, after NusaPack waits for ItemsAdder to finish loading.
  • It imports custom chest menus from your menu plugins (when gui_auto_import is on).
  • It converts everything into one Bedrock pack and delivers it to Geyser.

Before converting, NusaPack checks the free disk space. If there is not enough room for the result, it stops and tells you how much is free and how much is needed.

To convert only some plugins, name them: /npb convert nexo or /npb convert nexo,itemsadder. /npb convert list lets you pick from the installed plugins. Add --no-rebuild to use each plugin's last built pack instead of rebuilding it.

If a plugin cannot rebuild in time, NusaPack converts the pack that plugin built last. A plugin with no built pack, or whose item list cannot be read, is left out. The other plugins still convert, and each case is listed under "Left out or adjusted" with the reason.

A conversion never stops the server or kicks players by itself.

Rejoin or restart

What you changedWhat Bedrock players need
Textures, models, menu (GUI) art or layout, fonts and glyphs, soundsA rejoin
Added or removed custom items, custom blocks or ModelEngine mobsOne server restart
An item's behaviour (food, tool, durability and so on)One server restart
A player-head skinOne server restart
A new custom fishing rodOne server restart
Anything, on the very first conversion on this serverOne server restart

You do not have to memorise this table, because the last line of /npb convert always tells you. "Live for Bedrock ... players rejoin to see it" means a rejoin is enough. "Installed · restart the server once" means restart once. Geyser only registers custom items, blocks and mobs while it starts, which is why those changes need a restart.

Convert automatically

If you edit content often, let NusaPack convert by itself whenever a content plugin rebuilds its pack:

/npb config auto_convert on

It is off by default. Automatic runs write their result to the console, and the rejoin and restart rules above still apply.

A related setting, auto_deliver (on by default), hands every finished conversion to Geyser right away. If you turn it off, conversions are kept as candidates and you install one later with /npb pack use. See Settings.

The in-game panel

Type /npb in game to open the NusaPack control panel. Every action is also a button there, so you can convert, check and change settings without remembering commands. In the console, npb on its own shows the status.

The nether star at the top of the panel shows the status as short rows, grouped so they fit on both Java and Bedrock screens. For example:

Pack
 Active pack: gen-...
 Task: idle
 
ModelEngine bridge
 Models: 4 | Bedrock viewers: 1
 Modeled nearby: 0
 Problems: none
 
Furniture
 Furniture types: 12 | Bedrock viewers: 1
 Shown now: 0
 Problems: none

A group only appears while that bridge is running. Problems counts rejected or oversized frames and furniture that cannot be shown. For the raw counters, run npb status in the console.

Going back to an earlier pack

NusaPack keeps earlier packs. If a new conversion looks wrong:

  1. Run /npb pack to list earlier packs, the active one first.
  2. Run /npb pack undo to go back to the pack before, or /npb pack use <pack> to install a specific kept pack.
  3. Run /npb status to see whether the pack waits for a restart.

/npb pack keep converts without installing, which is handy when you want to try a change first.

Next steps

Nusa product documentation · NusaPackPaper 1.21.x · Java 21

Loading the index…