Resource Pack Manager FAQ

If your question is not answered here, check the other ResourcePackManager pages in the sidebar first.

What commands does ResourcePackManager currently expose?

On the backend (Paper / Spigot), the code-backed command surface is:

• /rspm setup — opens an in-game GUI setup menu (plugin update status, recommended plugins, automatic-updates toggle, links to wiki / Discord / Nightbreak account)
• /rspm recommendedplugins — shows the shared Nightbreak recommended-plugins menu (or a text list in console)
• /rspm downloadpluginupdate — downloads an available ResourcePackManager update for the next restart
• /rspm downloadall — downloads every available update exposed by this plugin (currently the ResourcePackManager update)
• /rspm applypluginupdate — part of the shared Nightbreak command set; RSPM always refuses it because its updates need a server restart (its Geyser extension only loads when Geyser starts)
• /rspm reload — rebuilds and re-hosts the merged pack
• /rspm status — full diagnostic dump (pack state, hosting mode, network key fingerprint, integrations)
• /rspm verbose [on|off] — turns detailed diagnostic logging on or off. No argument toggles it. The result is written back to verboseLogging in config.yml, so it persists across restarts. Also accepted as /rspm verboselogging.
• /rspm itemsadder configure — configures ItemsAdder for RSPM hosting
• /rspm itemsadder dismiss — permanently dismisses the ItemsAdder warning for your player UUID
• /rspm data_compliance_request — downloads all remotely stored data for this server

The root command is /resourcepackmanager, with /rspm as its alias. The update and recommended-plugin commands above are shared MagmaCore/Nightbreak commands registered by RSPM.

MagmaCore also registers these top-level commands, which are not /rspm subcommands:

• /nightbreaklogin <token> and /nightbreaklogout store or clear the server's shared Nightbreak account token. Both require nightbreak.login (default op). See Nightbreak account linking.
• /nightbreak plugins browses the Nightbreak plugin catalog and requires nightbreak.plugins (default op).
• /logify uploads the current server log to mclo.gs and requires logify.* (default op).
• /resourcepackmanagerchangelog [dismiss|disable] shows administrators the ResourcePackManager release notes they have not read. See Changelog notifications.

Whichever Nightbreak plugin loads first registers /nightbreaklogin, /nightbreaklogout, /nightbreak and /logify for the whole server.

Backend permissions:

• /rspm setup and /rspm recommendedplugins require resourcepackmanager.setup. /rspm setup is player-only because it opens an inventory GUI.
• /rspm downloadpluginupdate, /rspm downloadall, /rspm applypluginupdate, /rspm reload, /rspm status, /rspm verbose, /rspm itemsadder <configure|dismiss>, and /rspm data_compliance_request require resourcepackmanager.*.

On the proxy plugin (Velocity / BungeeCord), only diagnostic commands exist:

• /rspm status — proxy-side snapshot: backend list, per-backend fetch outcomes, merged pack state, Geyser/Floodgate detection
• /rspm debug bedrock [on|off] — Velocity and BungeeCord. Toggles verbose [RSPM-BedrockDebug] log lines from GeyserBinder for diagnosing "Bedrock player joined but didn't see the pack" cases. Resets to off on proxy restart. Running it with no argument prints the current state.

On Velocity, proxy commands accept resourcepackmanager.command.status or resourcepackmanager.*. BungeeCord registers the exact resourcepackmanager.command.status node; a permission plugin may still satisfy it through wildcard expansion. Console can run the commands. The output is safe to share — the network key appears only as a short one-way hash fingerprint, never the key itself, and no tokens are printed — so liberal grants are fine.

What plugins are currently supported?

ResourcePackManager ships with premade integration entries for these plugins:

• BackpackPlus
• BetterHUD
• BetterStructures
• CannonRTP
• EliteMobs
• EternalTD
• FreeMinecraftModels
• InfiniteVehicles
• ItemsAdder
• MegaBlockSurvivors
• MMOInventory
• ModelEngine
• Nexo
• Nova
• Oraxen
• RealisticSurvival
• ResurrectionChest
• ValhallaMMO
• vane-core

These integrations only take effect if the plugin is installed and its configured local path or remote URL is usable.

Each integration has its own YAML config file under plugins/ResourcePackManager/compatible_plugins/. You can customize isEnabled, pluginName, localPath, url, zips, cluster, additionalLocalPath, and reloadCommand per plugin there. The cluster option tells ResourcePackManager to treat the local path as a directory of multiple resource pack sub-folders that should all be merged together.

How do I exclude one automatic plugin integration?

Set isEnabled: false in that integration's file under plugins/ResourcePackManager/compatible_plugins/, then run /rspm reload (or restart). RSPM removes resource-pack inputs it generated or registered for that integration, including its generated mixer copies. Removing the plugin from priorityOrder does not exclude it; it only moves that pack to the lowest priority. To exclude a ZIP you added manually, remove or move the ZIP from the mixer folder.

Is ResourcePackManager compatible with ItemsAdder?

Yes. ResourcePackManager includes a built-in helper and warning flow for ItemsAdder.

If ItemsAdder is installed and still needs to be adjusted for ResourcePackManager hosting, OP players get a clickable warning a few seconds after joining. Players who permanently dismissed the warning do not see it again. From there you can:

• run /rspm itemsadder configure to set resource-pack.hosting.no-host.enabled: true, disable all three protect-file-from-unzip settings, set compress-json-files: false, run /iareload then /iazip, and wait for RSPM to merge the regenerated export (it reports when the merge succeeds or fails; it does not reload RSPM)
• run /rspm itemsadder dismiss to permanently dismiss that warning for your player UUID

If ItemsAdder is already configured to host its own pack through one of its hosting modes, the helper command does not override that automatically. It tells you to disable ItemsAdder hosting yourself first.

Can I add my own pack to the merge?

Yes, and there are two places to put it depending on what you have.

A finished .zip goes in:

plugins/ResourcePackManager/mixer

If you want to control which pack wins file conflicts, add the exact filename, including .zip, to priorityOrder in plugins/ResourcePackManager/config.yml.

An unzipped pack folder (an assets/ tree plus pack.mcmeta) goes in:

plugins/ResourcePackManager/resource_pack

RSPM zips that folder itself and merges it under the ResourcePackManager entry in priorityOrder, which is at the top of the default list — so by default its files win conflicts against every plugin pack. Move ResourcePackManager further down the list if you'd rather it lose.

The related plugins/ResourcePackManager/blueprint folder holds the pack.png and pack.mcmeta RSPM contributes to every merge. Edit those two files to change the merged pack's icon or its in-menu description; the folder is re-zipped into blueprint.zip on every startup.

Example:

priorityOrder:
  - ResourcePackManager
  - EliteMobs
  - MyCustomPack.zip

How does priority work?

priorityOrder is highest priority at the top and lowest priority at the bottom.

For non-mergeable files, the higher-priority pack replaces the lower-priority file. For mergeable JSON files, ResourcePackManager merges the contents instead of blindly replacing them.

The code currently treats these as mergeable:

• sounds.json
• language files under lang or languages
• vanilla item model JSON under minecraft/models/item (these get a non-recursive merge: only the overrides array is combined across packs, while the rest of the file follows highest-priority-wins)
• atlas files
• font files
• 1.21.4+ item model definitions under items/ (format-aware merging: leaves predicate trees intact, doesn't blindly recurse into different node types)

pack.mcmeta is merged specially: the highest pack_format wins and declared pack-format ranges are combined. Overlay entries for distinct directories are combined; when directories match, the higher-priority entry wins. Each overlay keeps its author's formats, min_format, max_format and extra metadata. The one addition: Minecraft 1.21.9+ rejects an overlay list where some overlay reaches pack format 64 or lower and another declares no formats, so when a merged list contains such an overlay, RSPM gives each entry that declares only min_format/max_format an equivalent formats range. RSPM does not otherwise rewrite overlay ranges. Additional fields in pack, overlays and the top-level object are preserved when they do not conflict with a higher-priority value.

After all packs are merged, ResourcePackManager merges base atlas sources into overlay atlas files. This prevents overlays from accidentally shadowing base atlas entries when Minecraft activates an overlay (e.g. ItemsAdder's ia_overlay_modern_atlas / ia_overlay_legacy_atlas).

Other JSON files are replaced instead of merged.

Packs that are not listed in priorityOrder are still included in the merge but receive the lowest priority.

Byte-identical complete ZIP inputs are deduplicated before merging, keeping the first (highest-priority) copy. After the merge, RSPM also repairs two common Java model defects: it adds a missing particle texture from the model's first concrete texture where possible, and clamps invalid model UV coordinates to Minecraft's 0..16 range.

Does ResourcePackManager rebuild automatically when packs change?

Yes. It watches supported pack sources for changes.

When a watched pack stops changing for 3 seconds, ResourcePackManager marks it as stable. Once all watched packs are stable, the remix happens immediately. During that transition, online OP players are notified: "All resource packs are stable. Mixing and sending now."

A remix whose inputs are byte-for-byte identical to the last one does not re-merge. RSPM fingerprints the ordered list of source packs (name, size, content hash) and stores it next to the output as .rspm_mix_fingerprint; when the fingerprint matches and every expected output file is still present, it republishes the existing zip instead of rebuilding it. Anything doubtful — a missing output, an unreadable fingerprint, a merged ZIP whose SHA-1 no longer matches — falls through to a full mix. This is also why a /rspm reload that changes nothing can finish almost instantly and reuse the existing hosted registration.

When the Java inputs are unchanged but the Bedrock side must be redone (Bedrock conversion enabled with no Bedrock pack on disk, bedrockConversionEnabled or the Bedrock target changing, or a converter update that changes the Bedrock output), RSPM keeps the verified Java ZIP and redoes only the Bedrock step, so the Java pack's bytes and SHA-1 stay the same.

On startup, RSPM checks the saved fingerprint and the merged ZIP's SHA-1 before the monitored plugins finish initializing. If they match, Java hosting starts from the saved pack straight away. The watchdog still remixes if a source pack changes afterwards.

Does the watchdog account for plugin initialization?

Yes. The watchdog is aware of Magmacore plugin initialization states.

• It waits for all monitored plugins to finish their Magmacore initialization before starting stability checks.
• If a plugin enters INITIALIZING while the watchdog is running, the watchdog pauses and resets stability tracking until initialization finishes. Failed or uninitialized optional integrations do not hold the entire mixer indefinitely.
• This prevents false "unstable" detections that would otherwise occur during normal plugin startup or reload sequences.

How do players receive the final pack?

When autoHost is enabled (default), or when selfHostForce explicitly overrides it, RSPM picks a delivery path and pushes that URL to every joining Java player. The decision tree is:

1. If selfHostForce: true, attempt self-hosting without probes — mainly for testing. URL validation and listener startup must still succeed.
2. Otherwise if preferSelfHost: true (default) and selfHostEnabled: true, check the host address, compare pack samples downloaded through localhost and the exact player URL, and require external reachability via magmaguy.com. Select self-hosting only if all checks pass.
3. If self-host fails or is disabled, reuse or upload the pack to magmaguy.com/rsp/ and announce that URL. Remote failure can fall back to self-hosting when enabled, but must pass the same checks. An unavailable external probe rejects automatic self-hosting; if both paths fail, no new delivery URL is announced.

Once a URL is in hand, RSPM uses the multi-pack API so it coexists with other server-sent packs. The current Bukkit plugin descriptor requires Minecraft 1.21.4 or newer.

The join offer is deferred by about one second. A FAILED_DOWNLOAD or DISCARDED response is retried automatically, up to three attempts for that player session; a declined pack, an invalid URL or a FAILED_RELOAD (the client's own resource reload failed; check that client's latest.log) is not retried. Floodgate players are skipped here because their Bedrock pack is delivered through Geyser instead.

If autoHost: false and selfHostForce: false, RSPM does not push any URL — you're expected to take the zip from plugins/ResourcePackManager/output/ and serve it through your own pipeline.

See Self-hosting for the full delivery decision tree.

Can I self-host instead of using the built-in auto-host?

Yes — and as of RSPM v2, the built-in HTTP server is the recommended self-host path. selfHostEnabled: true and preferSelfHost: true are both on by default.

If you want to host the zip through your own existing web server instead of either built-in path:

• Set autoHost: false.
• Optionally set resourcePackRerouting to an existing folder path relative to the plugins directory.
• Take the merged pack from plugins/ResourcePackManager/output/ResourcePackManager_RSP.zip and serve it yourself.

If resourcePackRerouting is set, RSPM also writes a copy of that zip to the reroute folder. That reroute path is resolved relative to the plugins directory, and the target folder must already exist.

Is there a command to request stored host data?

Yes. Use:

/rspm data_compliance_request

If the magmaguy.com remote auto-host has an active session, ResourcePackManager downloads the response into:

plugins/ResourcePackManager/data_compliance/data.zip

RSPM also writes ReadMe.md in the same data_compliance folder.

If there is no active remote session (e.g. you're self-hosting), the command tells you there is no remote data to request.

What config options are available?

plugins/ResourcePackManager/config.yml exposes the following:

General

• priorityOrder — list controlling which packs win file conflicts (highest priority first)
• autoHost — whether ResourcePackManager auto-hosts and sends the merged pack (boolean, default true)
• forceResourcePack — whether to force players to accept the pack (boolean, default false)
• resourcePackPrompt — the prompt shown when the pack is offered (default "Use recommended resource pack?")
• resourcePackRerouting — optional folder path (relative to plugins) to write an extra copy of the merged zip
• verboseLogging — print every step of pack preparation and the hosting handshake (boolean, default false). Off by default so the console shows only the final outcome; turn it on when diagnosing a merging or hosting problem. /rspm verbose on|off flips this same key at runtime and saves it. Separate from bedrockConverterDebug, which covers the Bedrock pipeline.
• nightbreak.autoDownloadPluginUpdates — whether RSPM downloads its own plugin updates automatically on startup (boolean, default false; a restart is still required to apply a downloaded update). This is a nested key under the nightbreak: section, not a top-level key — searching config.yml for a bare autoDownloadPluginUpdates line will only find it indented beneath nightbreak:. This is the same toggle exposed in the /rspm setup GUI. Automatic plugin downloads need a valid Nightbreak account token and an active supporter Patreon membership. RSPM does not write the shared nightbreak.applyPluginUpdatesWithoutRestart key and never applies a downloaded update without a restart, because its Geyser extension only loads when Geyser starts.

Self-hosting

• selfHostEnabled — whether the built-in HTTP server may be used (boolean, default true)
• selfHostPort — port for the self-host HTTP server. -1 (default) auto-derives as mcPort + networkHttpOffset-v2. Explicit and derived ports must be between 1 and 65535.
• networkHttpOffset-v2 — fallback offset added to the Minecraft server port when selfHostPort = -1. Default 1 (e.g. MC 25565 → HTTP 25566). On a network you no longer have to keep this in sync with the proxy: the backend auto-announces the exact HTTP port it actually bound to the proxy, and the proxy only uses its own network-http-offset-v2 as a guess before that announcement arrives.
• selfHostExternalHost — public hostname or IP that clients use to reach your self-host server. Empty (default) = automatic host detection.
• selfHostExternalUrl — complete public HTTP/HTTPS pack URL, including its path, for a reverse proxy. Empty by default. This overrides the advertised URL, not the local listener; embedded credentials and fragments are rejected.
• selfHostForce — skips all sanity checks AND the remote upload, always self-hosts (boolean, default false — for testing).
• preferSelfHost — try self-hosting first with sanity checks before falling back to remote upload (boolean, default true).

Bedrock

• bedrockConversionEnabled — convert the merged Java pack into a Bedrock pack for GeyserMC (default true)
• bedrockAutoDeployToGeyser — copy the Geyser custom mappings file into the detected Geyser folder (default true)
• bedrockGeyserFolder — manual path override for the Geyser folder; empty = auto-detect
• bedrockConverterDebug — verbose per-item / per-bone log lines from the Bedrock pipeline (default false)
• geyserExtensionAutoInstall — install and update the universal ResourcePackManager.jar as a Geyser extension so custom Bedrock entities render (default true). Setting it to false stops future installation and update staging; it does not delete an extension jar that is already there — remove that by hand while Geyser is stopped. The proxy plugin has the same switch under a different name, geyser-extension-auto-install.

Earlier versions also had plugins/ResourcePackManager/bedrock_display_offsets.yml with held-item offset settings. It is no longer read: Bedrock held-item poses now come from the Java model's display transforms. See Held-item poses.

There is intentionally no network-key config option, on either the backend or the proxy. Pasting a key by hand was the single largest source of misconfiguration — a typo silently broke the proxy↔backend link with no error anywhere.

Instead, the proxy owns the network key and hands it out:

• The proxy first reads a valid saved network-key, then tries deriving a key from plugins/floodgate/key.pem, then generates a random key if neither is available. It saves the result in its data folder. Later boots reuse the saved key while valid; losing it repeats this resolution and can recreate the same Floodgate-derived key. See network-key recovery.
• Each backend receives that key over the rspm:network plugin channel the first time a player connects to it, then persists it in its own data.yml. A backend that already holds a key ignores later grants — re-pointing a backend at a different network is an operator action, not something a message can do.
• Floodgate is not required for RSPM linking. Bedrock authentication belongs to Geyser's chosen authentication mode; see Floodgate and online authentication.
• A standalone (unproxied) server mints and keeps its own key, because it is its own one-server network.

/rspm status on either side prints a short one-way hash fingerprint of the key, never the key itself. Matching fingerprints indicate a shared network identity; inspect fetch outcomes separately to verify connectivity and pack delivery.

Why is the console so quiet? Is it even doing anything?

By design. Preparing a pack is a long pipeline — stage each contributing plugin's pack, merge clusters, wait for them to stop changing, mix, convert for Bedrock, hand the result to a host. Narrating all of that produced roughly sixty console lines per startup and buried the only two things anyone reads: whether players are going to get the pack, and what to do if they are not.

So a normal boot prints one line:

[ResourcePackManager] Resource pack is live via self-hosting — http://play.example.com:25566/rspm.zip

That line confirms publication of a delivery URL. Join with a client and inspect known custom content to verify download and rendering.

RSPM also deliberately does not warn about conditions it fixes by itself. If a self-host probe fails and RSPM falls back to remote hosting, that is a success — the console reports the outcome, not the detour. Warning about something already handled reads as a fault and sends people chasing a non-problem.

To see the full narration, run /rspm verbose on (or set verboseLogging: true in config.yml) and then /rspm reload. For the Bedrock converter specifically, use bedrockConverterDebug: true instead.

Can other plugins register their packs through code?

Yes. ResourcePackManager exposes a Java API for programmatic pack registration. See the API page for details.

Does the Bedrock conversion only work for FreeMinecraftModels?

No, not anymore. The current converter recursively handles any plugin whose pack ships 1.21.4+ items definitions under assets/<namespace>/items/**/*.json. That covers FreeMinecraftModels bone models, EliteMobs gear, Oraxen/Nexo custom items, custom armor sets, and any pack you assemble yourself in that format. Plain 2D custom items are emitted as flat Bedrock icons; 3D custom items emit Bedrock geometry/attachables and a software-rendered inventory icon.

Do I need to restart the server every time the Bedrock pack changes?

Texture and model tweaks to existing custom items take effect for the next Bedrock player to join — RSPM serves the Bedrock pack live per-session via Geyser's API. Restart the process hosting Geyser when custom-item mappings change, or when new custom-entity identifiers or property types must be registered. Those registrations happen at startup. Repeated exports of already registered entity identifiers with unchanged property types do not by themselves require another restart.

Does ResourcePackManager work on BungeeCord / Velocity?

Yes. Put the same ResourcePackManager.jar on the proxy and on each backend that supplies resource packs. The jar includes the Bukkit, Velocity and BungeeCord entry points. A proxied backend stages a copy at plugins/ResourcePackManager/proxy-extension/ResourcePackManager.jar when it has not received a network key. Other registered servers can run without RSPM; backend discovery keeps them from delaying pack synchronization.

Running as a proxy plugin, it merges every backend's converted Bedrock pack and serves it to Bedrock clients via the proxy's Geyser. Java pack delivery is still handled by each backend directly — Java clients see per-backend packs.

Setup, troubleshooting, and verification steps are in Proxy networks.