Resource Packs & Merging

Every deploy bakes a resource pack — it carries your baked art, fonts and the UI shaders. Players must have it applied or menus render as squares. This page covers what's inside it, how to get it to every player, and how to combine it with the packs other plugins generate.

What's inside an NxGui pack

resourcepack.zip
├─ pack.mcmeta                        ← pack_format 46+, with "overlays" entries
├─ nx_1216/ · nx_1219/ · nx_261/      ← overlay dirs: shader variants for newer MC versions
└─ assets/
   ├─ minecraft/
   │  ├─ font/default.json            ← your baked glyphs as font providers (\uE900…)
   │  ├─ textures/nxgui/…             ← the baked images those glyphs point at
   │  └─ shaders/core/rendertype_text*.json  ← the UI shaders (clipping, scroll masks)
   └─ nxgui/…                         ← input-box skin, custom fonts (nxf_*), models

Three parts are load-bearing when merging: the font providers, the core shaders, and (on the newest game versions) the overlay folders.

Option 1 — NxGui is your only pack

Host plugins/NxGui/output/resourcepack.zip and point server.properties at it:

resource-pack: https://your-host/pack.zip
resource-pack-sha1: <sha1 of the zip>

Our free Resource Pack Host outputs both lines with the hash pre-filled. Every deploy produces a new zip — re-upload and update both values each time (the hash is what makes clients re-download).

Option 2 — merge into Nexo

If you run the Nexo items plugin, it has a built-in pack merger:

Drop resourcepack.zip into plugins/Nexo/pack/external_packs/ (zips and folders both work).
Restart or regenerate Nexo's pack. Nexo dynamically merges conflicting files (fonts, sounds, atlases) rather than overwriting them, then distributes the combined pack itself.
Turn off your own hosting — Nexo delivers the merged pack to players.

Nexo can also pull packs via Plugin.import.from_location / from_url in its config if you prefer not to copy files.

Option 3 — merge into ItemsAdder

ItemsAdder merges per-content-folder. It's a bit stricter than Nexo:

Unzip resourcepack.zip and copy its assets folder.
Paste it so you end up with: plugins/ItemsAdder/contents/nxgui/resourcepack/assets/…
Run /iazip — ItemsAdder rebuilds and distributes the combined pack.

Merging several packs? Set the order in ItemsAdder's config.yml:

contents-folders-priorities:
  - vanilla
  - _iainternal
  - nxgui

ItemsAdder + NxGui's overlay folders (important)

NxGui packs carry overlay folders (nx_1216/, nx_1219/, nx_261/) plus overlays entries in pack.mcmeta — version-specific shader variants for newer game versions. Pasting only the assets folder silently drops them. The good news: ItemsAdder supports vanilla overlays since 4.0.16 (older builds lost them — confirmed bug, hit by BetterHud, fixed in the 4.0.16 milestone). Per the official Pack Overlays guide:

Copy the assets folder as usual → contents/nxgui/resourcepack/assets/…
Copy the nx_* overlay folders into contents/nxgui/resourcepack/ too (next to assets, mirroring the pack).
Copy NxGui's pack.mcmeta to contents/nxgui/resourcepack/assets/minecraft/pack.mcmeta. Yes, that odd spot is deliberate — a pack.mcmeta at the resourcepack/ root is ignored (ItemsAdder always generates its own for the final pack); assets/minecraft/ is its documented pickup location, from where /iazip merges your overlays entries with its own.
Run /iazip, then open the generated zip: the nx_* folders must sit at the zip root and the final pack.mcmeta must list them under "overlays". Both there = done.

The complete layout, at a glance:

plugins/ItemsAdder/contents/nxgui/resourcepack/
├─ assets/
│  └─ minecraft/
│     ├─ pack.mcmeta          ← NxGui's mcmeta goes HERE (root copy is ignored)
│     ├─ font/ · textures/ · shaders/ …
│  └─ nxgui/…
├─ nx_1216/
├─ nx_1219/
└─ nx_261/

Post-merge checklist — in the generated zip verify: (1) assets/minecraft/font/default.json still contains the \uE9… providers alongside ItemsAdder's own font entries (if NxGui's glyphs vanished, move nxgui later in contents-folders-priorities); (2) assets/minecraft/shaders/core/rendertype_text*.json are NxGui's — if another content pack also replaces text shaders only one can win; (3) overlays per step 4. On ItemsAdder older than 4.0.16 overlays cannot survive — update, or use Nexo-style merging / standalone hosting.

Any other setup

Same three checks apply to any merger tool or hand-merge: keep the font providers merged, keep the core shaders, keep the overlay folders + their pack.mcmeta entries, and copy assets/nxgui/ + assets/minecraft/textures/nxgui/ wholesale (they're namespaced — they never conflict with anything).

Modern clients (1.20.3+) can also hold multiple server packs at once — plugins/proxies that send additional packs can deliver NxGui's untouched next to another plugin's pack, no merging at all.

Troubleshooting merges

Symptom after merging	Cause → fix
Menus are squares/letters	Font providers lost — check `default.json` in the merged zip, fix merge priority
Menus render but scroll areas / clipping look wrong	Core shaders overwritten by another pack, or overlays dropped on a new MC version
Other plugin's emoji/HUD broke instead	Same shader fight, other direction — decide which pack's text shaders win; NxGui needs its own for clipped UI
Old visuals after redeploy	The merged pack was rebuilt but the client cached — the pack hash must change (re-run `/iazip` / re-upload)