Skip to main content

ResourcePackManager Setup

This page covers a single-server (standalone) setup. If you run a BungeeCord / Waterfall / Velocity network, follow Proxy networks instead — you install the same ResourcePackManager.jar on the proxy, but it generates its own config and plays a proxy-side role.

ResourcePackManager 2.x ships as a single universal jar. The exact same ResourcePackManager.jar runs on Bukkit/Paper backends and on Velocity / BungeeCord / Waterfall proxies — it auto-detects the platform from the loader it's running under. There are no longer separate resourcepackmanager-velocity-*.jar / resourcepackmanager-bungee-*.jar files to extract. (If RSPM detects that this backend sits behind a proxy that has never keyed it, it stages a copy of its own jar at plugins/ResourcePackManager/proxy-extension/ResourcePackManager.jar for you to copy onto the proxy — same file, just placed somewhere convenient.)

The backend plugin descriptor declares Bukkit API 1.21.4, so the Bukkit/Paper server must be Minecraft 1.21.4 or newer. The bundled Geyser custom-entity extension targets Geyser 2.11+.

  1. Drop ResourcePackManager.jar into your server's plugins/ folder. (This is the same jar you'd use on a Velocity / BungeeCord proxy — there are no separate proxy jars.)
  2. Start the server once so the config, mixer, blueprint, and output folders are generated.
  3. Decide whether you want:
    • self-hosting (default, on)
    • MagmaGuy's free auto-host fallback (default, on)
    • forced client acceptance
    • manual custom packs in the mixer folder
  4. Run /rspm reload after changing config or after adding custom packs manually.

That's it for the happy path. With default settings RSPM will try self-hosting first and fall back to MagmaGuy's CDN automatically if anything looks off.

You'll know it worked from a single console line:

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

RSPM keeps the console quiet on purpose — it reports the outcome, not every step, and it does not warn about conditions it recovers from by itself (a failed self-host probe followed by a successful fallback is a success, not a fault). If something needs diagnosing, run /rspm verbose on (or set verboseLogging: true in config.yml) and reload. See Troubleshooting.

Folders RSPM Generates​

Under plugins/ResourcePackManager/:

FolderWhat it's for
mixer/Drop finished .zip packs here to merge them in. Reference them in priorityOrder by their exact filename, including .zip.
resource_pack/Drop an unzipped pack here (a folder tree with assets/, pack.mcmeta, ...). RSPM zips it and merges it under the ResourcePackManager priority entry, which sits at the top of the default priorityOrder.
blueprint/Holds the default pack.png and pack.mcmeta that RSPM contributes to the merge. Edit these to change the merged pack's icon or its pack.mcmeta description; the folder is re-zipped into blueprint.zip on every startup.
output/The finished artifacts: ResourcePackManager_RSP.zip, plus ResourcePackManager_Bedrock.zip and rspm_geyser_mappings.json when Bedrock conversion produced them.
compatible_plugins/One YAML per supported plugin integration.
data_compliance/Where /rspm data_compliance_request writes its download.
proxy-extension/Only appears on a backend that is behind a proxy which has never keyed it. Contains a copy of the running ResourcePackManager.jar to put on the proxy.
geyser-extension/Only appears when Floodgate is local but Geyser is an external process. Contains a copy of the jar to put in that Geyser's extensions/ folder.

Core Commands​

  • /rspm setup — opens an in-game GUI setup menu (plugin update status, recommended plugins, an automatic-updates toggle, and an info button with clickable links to the wiki, Discord, and your Nightbreak account token)
  • /rspm recommendedplugins — shows the shared Nightbreak recommended-plugins menu
  • /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 reload — rebuilds and re-hosts the merged pack
  • /rspm status — prints a full diagnostic dump: pack state, hosting mode, network key fingerprint, integrations
  • /rspm verbose [on|off] — turns detailed diagnostic logging on or off without opening config.yml. With no argument it toggles. The choice is written back to verboseLogging in config.yml, so it survives restarts. Aliased as /rspm verboselogging.
  • /rspm itemsadder configure — auto-configures ItemsAdder for RSPM hosting (see below)
  • /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.

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 reload, /rspm status, /rspm verbose, /rspm itemsadder <configure|dismiss>, and /rspm data_compliance_request require resourcepackmanager.*.

ItemsAdder​

The current preferred ItemsAdder path is no longer manual-only.

Use:

/rspm itemsadder configure

That helper updates the relevant ItemsAdder settings, regenerates ItemsAdder's pack, then reloads ResourcePackManager. Specifically it:

  • sets resource-pack.hosting.no-host.enabled: true
  • disables protection_1, protection_2, and protection_3 in resource-pack.zip.protect-file-from-unzip
  • sets resource-pack.zip.compress-json-files: false (RSPM needs uncompressed, parseable model JSON for the mixer and the Bedrock converter)
  • dispatches /iareload, then /iazip
  • reloads ResourcePackManager about 15 seconds later, after ItemsAdder has had time to reload and regenerate

If ItemsAdder is already configured to host its own pack (self-host, external-host, or lobfile), the helper stops and tells you to disable ItemsAdder hosting manually first.

Bedrock / GeyserMC Support​

RSPM automatically converts the merged Java pack into a Bedrock pack for GeyserMC. Conversion handles any plugin's 1.21.4+ items-definition pack — not just FreeMinecraftModels — including 3D held items, custom armor, and modeled equipment.

bedrockConversionEnabled defaults to true, so a fresh install on a server that has GeyserMC will just work.

For a standalone server, conversion fires when any of these is true: Geyser-Spigot is installed on this server, Floodgate is installed on this server, or RSPM detected proxy mode (see Proxy networks).

If Geyser-Spigot is installed on this server, RSPM also installs itself into plugins/Geyser-Spigot/extensions/ as a Geyser extension, which is what makes custom Bedrock entities render instead of armor stands. It's the same ResourcePackManager.jar — nothing extra to download — but it needs one server restart to take effect. Set geyserExtensionAutoInstall: false in config.yml to stop RSPM installing and staging that extension. See Geyser extension & custom entities.

See Bedrock / Geyser conversion for the full pipeline, output paths, and display-offset tuning.

Verifying the Setup​

For a public HTTPS download address, keep automatic hosting enabled and set selfHostExternalUrl to your reverse proxy's complete pack URL. See HTTPS and reverse proxies for the listener and forwarding settings.

Run /rspm status in console or as an op. The output is split into sections:

  • Plugin meta — version + deploy mode (standalone vs network-backend). On a network backend it also prints a short, non-secret network key fingerprint and where that key came from (provided by the proxy / saved on this server / adopted from Floodgate's key / not set yet).
  • Java Pack — mixed yes/no, size, SHA1 prefix
  • Bedrock Pack — converted yes/no, mappings present, with diagnostic hints if conversion was skipped
  • Hosting — which delivery path is active (self-hosted / remote / not yet ready), the URL clients will see, resolved external host, auto-detected public IP
  • Proxy deployment — a reminder that the network proxy jar is the same ResourcePackManager.jar; on a network, copy it to the proxy's plugins/ folder
  • Integrations — Floodgate / Geyser-Spigot detection, online player count

If anything looks wrong, see Troubleshooting.

Where to Go Next​