Skip to main content

ResourcePackManager (RSPM)

ResourcePackManager discovers, merges, hosts, and distributes resource packs from supported plugins and from manually supplied packs. It can also convert the merged Java pack into a Bedrock resource pack so GeyserMC players see the same custom content as Java players, and it ships first-class support for BungeeCord, Waterfall, and Velocity proxy networks.

What It Does​

  • discovers supported plugin packs and merges them according to priorityOrder
  • runs its own built-in HTTP server so it can self-host the merged pack (no external file host required)
  • can fall back to MagmaGuy's free hosting (auto-host) when self-hosting isn't viable
  • can force or optionally prompt pack use
  • watches for pack changes and re-merges automatically when sources stabilize
  • converts the merged Java pack into a Bedrock resource pack for GeyserMC
  • registers true custom Bedrock entities with Geyser through a bundled Geyser extension, so modeled entities (e.g. FreeMinecraftModels, EliteMobs) render and animate for Bedrock players
  • works on proxy networks: every backend produces its own Bedrock pack, the proxy plugin pulls them, merges them, and serves the result through Geyser
  • links a network without any key to paste: the proxy owns the network key, saves it to its own network-key file, and pushes it to each backend automatically the first time a player connects there
  • can keep itself up to date across a network: backends offer the universal plugin jar over an authenticated route; the proxy validates its structure and version, refuses downgrades, verifies the transferred bytes by SHA-256, and stages it for the next shutdown

Architecture at a Glance​

RSPM v2 is a multi-module Maven build, but it ships as a single jar: ResourcePackManager.jar. That one jar contains the Bukkit/Paper plugin, the Velocity plugin, and the BungeeCord/Waterfall plugin all at once — Minecraft loads whichever entry point matches the platform it's running on. There are no longer separate ResourcePackManager-Velocity.jar / ResourcePackManager-BungeeCord.jar files to extract.

The proxy-extension/ folder still exists, but it means something different now: when a backend notices it is behind a proxy and has never been handed a network key, it stages a byte-identical copy of its own running jar at plugins/ResourcePackManager/proxy-extension/ResourcePackManager.jar and tells you to copy that one file onto the proxy. It is a convenience copy of the jar you already have, not a separate per-platform artifact.

The same jar plays two roles depending on where you drop it:

  • As a backend plugin (on each Paper/Spigot backend) — mixes Java packs, runs the Bedrock converter, hosts the pack, exposes a small HTTP server, and pushes packs to Java clients.
  • As a proxy plugin (on a Velocity or BungeeCord/Waterfall proxy) — pulls each backend's Bedrock pack and mappings, merges them into a single network-wide pack, and serves it to Bedrock clients via the proxy's Geyser.

A standalone server only needs the jar on the backend. A proxy network needs the same jar on every backend AND a copy on the proxy.

The same jar also doubles as a Geyser extension. When the backend detects a local Geyser-Spigot install, it installs the exact same universal ResourcePackManager.jar into Geyser-Spigot/extensions/ so Geyser can render RSPM's custom Bedrock entities; the proxy role does the same for the proxy's Geyser. (Older versions shipped a separate ResourcePackManager-GeyserBridge.jar — that file is retired and replaced automatically through Geyser's update queue.) See Geyser extension & custom entities.

Hosting Options​

Java-pack delivery uses this precedence:

  1. Forced self-host (selfHostForce: true) — overrides autoHost and selfHostEnabled, skips all probes and remote upload, and announces the local URL. Mainly for testing.
  2. Self-host first (autoHost: true, preferSelfHost: true, and selfHostEnabled: true, all defaults) — RSPM starts its own HTTP server, runs a chain of sanity checks (non-LAN address, localhost self-probe, magmaguy.com external-reachability probe), and announces the local URL to clients. Zero bandwidth cost to MagmaGuy. This "try self-host first" preference is skipped on a proxy backend, which goes straight to step 3; the backend's own HTTP server still runs there, because the proxy pulls the Bedrock artifacts from it.
  3. Remote auto-host fallback — if self-host is disabled or an actual self-host reachability check fails, RSPM uploads the pack to MagmaGuy's CDN at magmaguy.com/rsp/ and announces that URL instead. If the remote path fails, it can fall back to self-host when selfHostEnabled: true.

If both autoHost: false and selfHostForce: false, RSPM writes the merged zip to plugins/ResourcePackManager/output/ without pushing a URL.

See Self-hosting for the full delivery decision tree, port resolution, and external-host detection.

Java-to-Bedrock Conversion​

The Bedrock converter is no longer FreeMinecraftModels-only. It recursively walks every 1.21.4+ items definition file (assets/<namespace>/items/**/*.json) in the merged pack and produces Bedrock geometry, attachables, and inventory icons for whichever plugin shipped them:

  • Bedrock players see 3D items, custom armor, and modeled equipment for any plugin whose pack uses the 1.21.4+ items-definition format.
  • Custom armor textures render on Bedrock players using the vanilla armor geometry with the Java texture as the visible layer.
  • Inventory icons for 3D items are software-rendered from the Java model through the display.gui transform.
  • The Bedrock pack is served live per Bedrock session via Geyser's API, so texture and model tweaks reach the next joining Bedrock player without a server restart. Custom-item mappings still require a restart because Geyser registers them at boot.
  • Twelve user-tunable knobs for held-item display offsets (six first-person, six third-person) in bedrock_display_offsets.yml.

Current Integrations​

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

Each integration only activates if the plugin is installed and its configured local path or remote URL is usable. The plugin also detects Geyser (Geyser-Spigot on a backend, Geyser-Velocity / Geyser-BungeeCord on a proxy) at startup and wires Bedrock pack delivery into whichever one it finds.

Where to Go Next​