Sources and advanced files

How NusaPack finds each plugin's pack, how to point to a pack yourself, manual sources, still textures, per-namespace glyph modes and config.yml.

On this page

Most servers never touch these files: NusaPack finds each plugin's pack by itself. This page is for the unusual setups: a pack in a custom place, a plugin that cannot be rebuilt, packs merged into another plugin, manual sources, textures that should stay still, and config.yml.

When you need these files

SituationWhat to use
A plugin writes its pack somewhere unusualsource-packs in sources.yml
EcoItems, or a pack you build yourselfsource-packs in sources.yml, and --no-rebuild
You want to list sources by handdiscovery: manual and sources in sources.yml
Some animated textures should not movestill-textures.yml
One texture namespace needs a different glyph modefont-rendering.texture-namespaces in sources.yml

All these files are in plugins/NusaPackBridge/. After editing one, run /npb config reload, then /npb convert.

How NusaPack finds each pack

For every plugin, NusaPack looks in this order:

  1. source-packs.<plugin> in sources.yml, if you set it. This always wins.
  2. The output paths named in the plugin's own config.
  3. The plugin's default pack location.

Among the places found in steps 2 and 3, the newest existing ZIP is used. Every path must stay inside the server folder; anything outside is ignored.

PluginWhat NusaPack reads from the plugin's configDefault
NexoPack.generation.output_path in plugins/Nexo/settings.ymlplugins/Nexo/pack/pack.zip
OraxenPack.generation.output_path in plugins/Oraxen/settings.ymlplugins/Oraxen/pack/pack.zip
CraftEngineThe path of every zip step in resource-pack.workflows, and the storage_path of hosted packs, in plugins/CraftEngine/config.ymlplugins/CraftEngine/generated/resource_pack.zip
ItemsAdder–plugins/ItemsAdder/output/generated.zip
EcoItems–plugins/EcoItems/pack/pack.zip

Point to a pack yourself

Set source-packs in sources.yml when a pack lives somewhere NusaPack does not look:

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

The keys are nexo, itemsadder, oraxen, craftengine and ecoitems. Paths are relative to the server folder and must stay inside it. Source files are only read, never changed.

Sources a plugin cannot rebuild

EcoItems has no rebuild hook, so NusaPack cannot ask it for a fresh pack. During a conversion you see EcoItems can't be rebuilt from here; using the pack it already built. To update EcoItems content on Bedrock:

  1. Build the pack in EcoItems yourself.
  2. If it is not at the default path, set source-packs.ecoitems.
  3. Run /npb convert ecoitems --no-rebuild (or a normal /npb convert).

The same applies to any pack you build yourself: point to it with source-packs and convert with --no-rebuild. In a conversion of several plugins, a plugin without a built pack is skipped with a note instead of stopping the rest.

Packs merged into another plugin

Nexo and Oraxen can import other plugins' packs, for example a CraftEngine workflow that writes its ZIP to ../Nexo/pack/external_packs/CraftEngine.zip. NusaPack handles this by rebuilding the merging plugins last. Two things to check:

  • Nexo only includes packs from plugins/Nexo/pack/external_packs/ when Pack.import.external_packs is true in Nexo's settings.yml.
  • A file in a folder that the plugin does not import is not part of the built pack, so NusaPack cannot see it either.

Manual sources

With discovery: manual in settings.yml, NusaPack stops detecting plugins and reads only the sources you list in sources.yml. Use the commented example at the top of that file as a template:

sources:
  - adapter: AD-NEXO
    version: "1.28"
    path: plugins/Nexo/pack/pack.zip
    precedence: 10

The adapters are AD-NEXO, AD-ITEMSADDER, AD-ORAXEN, AD-CRAFTENGINE and AD-ECOITEMS. Each path must exist and stay inside the server folder; a source that cannot be read is left out with a note. Most servers should keep discovery: auto.

Animated textures that stay still

plugins/NusaPackBridge/still-textures.yml lists textures that do 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 kept frame is the one Java shows first (frames in the .mcmeta file).
  • -> hidden makes the texture fully transparent, useful for overlays that look wrong when still.
  • Up to 256 entries.

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. To make every animated texture still, use texture_motion: still in Settings instead.

Glyph mode per namespace

font_mode in settings.yml applies to all glyphs. To use a different mode for the glyph textures of one namespace, add it to sources.yml:

font-rendering:
  texture-namespaces:
    nexo: java-height

Each value is original or java-height. Up to 32 namespaces. Emoji, ranks and icons explains the two modes.

config.yml

config.yml holds the server identity and a few safety switches for conversion. Leave it as it is. The conversion mode that used to live here is now conversion_mode in settings.yml, and updates move it there by themselves. If config.yml contains an error, NusaPack reports it on /npb config reload and at startup.

Next steps

Nusa product documentation · NusaPackPaper 1.21.x · Java 21

Loading the index…