Overview

Computing packs

AstralPack#loadConfiguration loads config.yml, clears the Set<ComputedPack> computedPacks, and then for every configured pack blueprint:

1. Derives the pack id UUID.nameUUIDFromBytes(blueprint.url().getBytes()).

2. Generates a fresh cache key.

3. Builds ResourcePackInfo.resourcePackInfo().id(...).uri(URI.create(url + "?cacheKey=" + cacheKey)) .computeHashAndBuild().

4. On completion, adds a ComputedPack(blueprint, info, hash, cacheKey) to computedPacks.

computeHashAndBuild() downloads the ZIP from the proxy in order to hash it, so every pack URL must be reachable from the proxy host, not just from clients. Step 4 runs asynchronously in the future's whenComplete; if it fails, the proxy logs Failed to compute resource pack hash and that pack is simply never added — it is never sent, and findComputed returns null for it.

Cache busting

generateCacheKey() returns Long.toHexString(Double.doubleToLongBits(Math.random())). It is appended to the pack URL as a ?cacheKey=<hex> query string and regenerated on every configuration load and every /pack update. Clients cache resource packs by URL, so changing the query string forces clients (and intermediate caches) to re-download even when the file name on the CDN is unchanged. The key is stored on the ComputedPack record.

The ?cacheKey= is part of the URI used both to hash the pack proxy-side and to hand to the client, so both sides see the same bytes.

Sending

sendPack(Player, PackBlueprint) resolves the ComputedPack whose blueprint().id() matches; if there is none it logs the warning No computed pack found for blueprint id: {} and sends nothing.

sendPack(Player, ComputedPack, boolean force) first calls player.removeResourcePacks(info.info().id()) when force is set, then sends a ResourcePackRequest with .required(true), the single pack, and .prompt(info.blueprint().prompt()). All packs are sent as required.

The ComputedPack's byte[] hash is the hex-decoded form of the computed ResourcePackInfo#hash(); that byte array is what the listener compares against the client's applied and pending packs.

Configuration-phase flow

PackListener subscribes to Velocity's PlayerConfigurationEvent. That event is used rather than PlayerEnterConfigurationEvent because the latter is not fired for the initial configuration after login; PlayerConfigurationEvent fires on the initial join and on server switches for modern clients.

1. Resolve the group — AstralVelocityAPI.servers().findById(<velocity server name>).map(MinecraftServer::group).orElse(null). If it is null (the server is not registered in AstralCore's ServerService, or the lookup by Velocity server name misses), the listener returns immediately and AstralPack does nothing for that connection.

2. Update packs — for every computed pack, matches = blueprint.groups().contains(group).

   • Matches and not already loaded → queued to send.

   • Does not match, unload-on-group-change is true, and the pack is loaded → player.removeResourcePacks(pack.info().id()) immediately. Removals are fire-and-forget and are never awaited.

   "Loaded" means the pack's hash matches one in player.getAppliedResourcePacks() or player.getPendingResourcePacks() (Arrays.equals on the raw hash), so a pack shared across groups is never re-prompted and a still-downloading pack is never re-sent.

3. Nothing to send → the listener returns and configuration is not held.

4. Otherwise, before sending, the pending pack ids and a fresh CompletableFuture are registered (awaiting/waiters, both ConcurrentHashMap) so a fast client response cannot race past the waiter. Each queued pack is then sent through the non-forced sendPack path.

5. The subscriber returns EventTask.resumeWhenComplete(...) on that waiter with a 20-second timeout; the configuration phase stays suspended until the client answers or the timeout elapses, and either way the player's awaiting/waiters entries are removed.

Without this hold, Velocity ends configuration immediately, the client switches to the level-loading screen and tears down the confirm dialog before the player sees it — the pack then silently never loads.

PROMPT_TIMEOUT_SECONDS = 20L is a private static final constant and is not configurable. It is kept below the proxy's 30-second read timeout so a player who walks away does not take the backend connection down with them.

Feature map

Requirements