Skip to main content

ResourcePackManager Setup

This page covers a single-server (standalone) setup. If you run a BungeeCord / 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 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 a proxied backend with no saved or seeded network key, 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.

With default settings, RSPM tries verified self-hosting first and falls back to remote hosting through magmaguy.com if verification fails or is unavailable. If both automatic paths fail, it cannot announce a new delivery URL. Check the final status and client download before treating setup as complete.

A successful hosting setup produces a console line such as:

[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/Created when a proxied backend has no saved or seeded network key. Contains a copy of the running ResourcePackManager.jar to put on the proxy. A retained folder does not prove that the backend is still unlinked.
geyser-extension/Exported when automatic extension installation is enabled, Floodgate is local and Geyser-Spigot is absent. Follow the exact console path, which may point inside update/, when copying the jar to external Geyser's extensions/ folder. The export does not configure external pack delivery.

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 applypluginupdate — registered by the shared Nightbreak command set, but RSPM always refuses it: ResourcePackManager updates need a server restart: its Geyser extension only loads when Geyser starts. Restart the server to apply a downloaded update.
  • /rspm reload — restarts plugin initialization and schedules pack preparation; an unchanged pack may reuse its existing hosted registration
  • /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 applypluginupdate, /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, requests pack regeneration, and waits for RSPM to merge the new export. 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 after 20 server ticks, then /iazip another 100 ticks later
  • waits for RSPM's watchdog to pick up the regenerated ItemsAdder export and finish the merge, then reports RSPM merged the regenerated ItemsAdder export. Use /rspm status to check hosting. If that merge fails, it reports that the export could not be merged and RSPM retries.

The helper does not reload ResourcePackManager. It refuses to start while an earlier configuration is still pending, and it stops without saving if ItemsAdder's config.yml changes while it is being edited. If ItemsAdder refuses /iareload or /iazip, run that command by hand. The merge message confirms the merge, not hosting: check /rspm status and a real client download afterwards.

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 can convert supported assets in the merged Java pack into a Bedrock pack for GeyserMC. It scans 1.21.4+ item definitions from any plugin, including supported 3D held items and equipment; this does not guarantee conversion of every item-model node, predicate or armor design. See the support limits in the conversion guide below.

bedrockConversionEnabled defaults to true. Conversion also requires a detected Bedrock target and supported source assets; startup registration may require the Geyser restart described below.

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 locally and geyserExtensionAutoInstall: true, RSPM installs or stages its universal jar under plugins/Geyser-Spigot/extensions/. Restart the server to load a newly installed or staged extension. Custom Bedrock entities also require a compatible producer to mark the Java entity through the bridge, registered definitions and the correct client pack. Setting geyserExtensionAutoInstall: false stops future installation and staging; it does not remove an installed jar or cancel an already staged update. See Geyser extension & custom entities.

See Bedrock / Geyser conversion for the full pipeline, output paths, and held-item poses.

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, and the result of the last self-host check with the reason it failed
  • 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

After status shows a delivery URL, join with a real client, accept the pack, and inspect a known custom item or model. For Bedrock, reconnect after a pack rebuild and restart Geyser when new mappings or entity definitions require registration. Status and hosting logs describe publication, not client rendering.

If anything looks wrong, see Troubleshooting.

Where to Go Next​