automatic-resourcepack-sha1-spigot-plugin/README.md

RemotePackSync

Created by LexianDEV · Official website: https://lexian.dev

RemotePackSync is a lightweight Spigot 26.2 plugin that keeps Java Edition resource packs synchronized with a remotely hosted SHA-1 checksum and optionally serves a local Bedrock Edition pack to players connecting through GeyserMC. It uses only public Bukkit/Spigot and Geyser APIs, so it runs on Spigot, Paper, Purpur, Bukkit-compatible servers, and current GeyserMC.

No NMS, packet libraries, or server-fork-specific APIs are used.

Requirements

• Java 25 (Minecraft/Spigot 26.2 requires Java 25)
• A Minecraft/Spigot 26.2-compatible server

Build

mvn clean package

The ready-to-install plugin is written to:

target/RemotePackSync.jar

Installation

1. Copy RemotePackSync.jar into the server's plugins/ directory.
2. Start the server once. RemotePackSync writes plugins/RemotePackSync/config.yml automatically.
3. Configure the resource-pack and SHA-1 URLs.
4. Restart the server, or run /remotepacksync reload as an operator.

Configuration

# Direct URL to the .zip resource pack. Leave blank to disable pack delivery.
resourcePackUrl: "https://cdn.example.com/server-pack.zip"

# URL to a text file containing the pack's SHA-1 checksum.
sha1Url: "https://cdn.example.com/server-pack.zip.sha1"

# Seconds between Java SHA-1 and Bedrock pack checks. Minimum: 30.
refreshInterval: 300

# Preferred: remote Bedrock pack URL for GeyserMC players.
# Must be a direct .mcpack/.zip download with Content-Type: application/zip
# and an exact Content-Length.
bedrockResourcePackUrl: "https://example.com/packs/server-pack.mcpack"

# Optional local alternative; use only when bedrockResourcePackUrl is blank.
# Relative paths are resolved from plugins/RemotePackSync/.
bedrockResourcePack: "bedrock/server-pack.mcpack"

The SHA-1 response must contain a 40-character hexadecimal SHA-1. Both of these standard formats work:

0123456789abcdef0123456789abcdef01234567

0123456789abcdef0123456789abcdef01234567  server-pack.zip

Behaviour

Java Edition

• On startup and at every refresh interval, RemotePackSync fetches only the SHA-1 file asynchronously.
• When the SHA-1 changes, it sends the configured resource-pack URL and new hash to every online player.
• Players joining after a successful SHA-1 fetch receive the current resource pack.
• A failed request leaves the last known-good SHA-1 active, so a brief CDN outage does not interrupt existing pack delivery.
• If both URLs are blank, delivery is disabled without error. If only one is set, the configuration is rejected and delivery remains disabled.

Bedrock Edition through GeyserMC

• Preferred remote mode: set bedrockResourcePackUrl to a direct .mcpack or .zip download URL. RemotePackSync creates a Geyser UrlPackCodec and registers it through the public SessionLoadResourcePacksEvent API, so Geyser supplies the URL to connecting Bedrock clients.
• The remote server must return Content-Type: application/zip and an exact Content-Length. RemotePackSync verifies those headers (following redirects) before registering the URL; a provider that returns application/octet-stream is not compatible with Bedrock URL packs. Redirects are allowed only when they ultimately resolve to a valid direct download. The URL should be stable and should expose a changed ETag or URL when the pack changes.
• Geyser validates/downloads remote URL packs during its lifecycle. Use /remotepacksync reload after changing the URL or after replacing a pack at the same URL; players already connected must reconnect.
• Local alternative: set bedrockResourcePack to a .mcpack or .zip file. The source is checked asynchronously at refreshInterval; changes receive a deterministic manifest UUID and are managed under plugins/RemotePackSync/bedrock-managed/.
• The original configured local pack is never modified.
• Every new Geyser Bedrock connection receives the latest successfully registered pack.
• The pack must be a valid Bedrock pack containing manifest.json at the archive root. Geyser does not convert Java packs into Bedrock packs.
• Bedrock's protocol only negotiates packs while a client connects. Players already connected when the file changes must reconnect to receive the new version; RemotePackSync cannot hot-push a replacement to an active Bedrock session.
• If Geyser is absent, Java Edition resource-pack operation continues normally and Bedrock delivery stays disabled.

Commands and permissions

• /remotepacksync reload (alias: /rps reload) reloads config.yml and begins a fresh asynchronous SHA-1 refresh.
• Permission: remotepacksync.reload (default: op).

Compatibility

RemotePackSync compiles against org.spigotmc:spigot-api:26.2-R0.1-SNAPSHOT and Geyser API 2.11.0-SNAPSHOT, targeting Java 25 as required by Minecraft/Spigot 26.2. Java packs are sent through Bukkit's stable Player#setResourcePack(String, byte[]) API; Bedrock packs use Geyser's public UrlPackCodec/pack-session API. Geyser is a soft dependency, so Java-only servers remain supported.

License

MIT