Settings

The everyday options in settings.yml, the three ways to change them, and which files are only for advanced setups.

On this page

All everyday NusaPack options live in one file, plugins/NusaPackBridge/settings.yml. This page explains each option and the three ways to change it.

Three ways to change a setting

  1. In game: /npb config opens a settings menu.
  2. By command: /npb config <name> <value>, for example /npb config auto_convert on. /npb config <name> shows what one setting does and its choices.
  3. In the file: edit settings.yml (every value has a comment), save it, then run /npb config reload.

Changes made by command or in the menu are saved to settings.yml at once. In the file, on/off settings are written as true or false; in the command you type on or off.

All settings

NameValuesDefaultWhat it does
auto_converton / offoffConvert by itself whenever a content plugin rebuilds its pack
auto_deliveron / offonHand a finished conversion to Geyser right away. When off, it is kept as a candidate that you install later with /npb pack use
geyser_extensionauto / manualautoauto puts NusaPack's extension into Geyser's extensions folder at startup and replaces older builds there. manual leaves that folder alone
discoveryauto / manualautoauto detects installed plugins and their built packs; manual reads only the sources listed in sources.yml
conversion_modestrict / partialstrictstrict keeps the current Bedrock pack when something blocks and lists the problems; partial ships everything that converted
gui_auto_importon / offonImport custom chest menus from menu plugin files before each conversion
font_modeoriginal / java-heightoriginalKeep each glyph's source pixels, or resample glyphs to the size Java draws them
font_size0, 8, 16, 32, 64, 128, 256128Largest glyph height and Bedrock font cell, in pixels (0 means no limit, which is 256)
font_size_drop_oversizedon / offoffGlyphs taller than font_size: shrink them to fit (off) or leave them out (on)
icon_sizeauto, 32, 64, 128, 256autoInventory icon size of 3D items and blocks. auto follows the source texture: 16 px becomes 64, 32 px becomes 128, larger becomes 256
texture_motionplay / stillplaystill shows the first frame of every animated texture, for a smaller pack and a faster download
bedrock_bossbarfull / title-onlyfulltitle-only hides the Bedrock boss bar and keeps its title, for HUD plugins that draw in the boss bar title

When a change takes effect:

  • auto_convert, auto_deliver and conversion_mode apply right away.
  • geyser_extension applies from the next server start.
  • All other settings apply from the next /npb convert.

geyser_extension: manual only stops NusaPack from managing Geyser's extensions folder. Running Geyser on a proxy is still not supported.

Choose which plugins are converted

NusaPack detects installed content plugins by itself, and all of them are switched on by default. /npb convert converts every installed plugin that is switched on and skips the rest. To leave one out, set it to false:

plugins:
  nexo: true
  itemsadder: false     # installed, but not converted
  oraxen: true
  craftengine: true
  ecoitems: true
  modelengine: true

Or use a command, for example /npb config convert_itemsadder off. The command names are convert_nexo, convert_itemsadder, convert_oraxen, convert_craftengine, convert_ecoitems and convert_modelengine.

Keep some animated textures still

plugins/NusaPackBridge/still-textures.yml lists textures that should not move on Bedrock, even with texture_motion: play. Write one pattern per entry as namespace:path (the path inside textures/), where * matches any part of a name:

still:
  - nexo:item/abyss_sword          # one texture
  - mythicmobs:*                   # a whole namespace
  - "*:item/weapons/*"             # a folder in every namespace
  - lava_sword                     # any texture with this file name
  - "nexo:item/glitch -> hidden"   # fully transparent instead of the first frame

Put quotes around entries that start with * or contain ->. The first frame is the one Java shows first. Your source packs are never changed; only the converted copy stays still. /npb report tells you how many textures were kept still and how much smaller the pack got.

Advanced files

Most servers never need to edit these two files:

FileWhen you need it
sources.ymlA plugin's built pack is in an unusual place, or discovery is set to manual
config.ymlHolds the server identity. Usually left as it is

The most common case is EcoItems. It has no rebuild hook, so NusaPack uses the pack it built last. If that pack lives in an unusual place, point to it in sources.yml:

source-packs:
  ecoitems: plugins/EcoItems/pack/pack.zip

The same key works for nexo, itemsadder, oraxen and craftengine. Paths are relative to the server folder and must stay inside it. Run /npb config reload after editing.

Glyph sizes (glyphs.yml) and hand-made menus (gui-bindings.json) are explained in Supported content.

After an update

Updating NusaPack keeps your settings. New options are added at 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…