Utilities - Refinery WIKI

Alongside the larger frameworks, RefineryCore ships a few small, self-contained utilities that almost every plugin eventually needs.

`TimeFormat`

xyz.refineryteam.refinerycore.api.time.TimeFormat produces the human-friendly duration strings every cooldown, ban, and timer UI needs — plus the inverse parse for command arguments like 7d12h.

BanCommand.java

TimeFormat.format(Duration.ofMinutes(135));     // "2h 15m"
TimeFormat.formatShort(Duration.ofSeconds(45)); // "45s"
TimeFormat.format(Duration.ofDays(400), 3);     // "1y 1mo 5d"

Duration parsed = TimeFormat.parse("1d6h30m");  // Duration
Duration bare = TimeFormat.parse("300");        // 300 seconds → 5 minutes
Duration strict = TimeFormat.parseOrThrow("7d"); // throws for invalid input

Method	Description
`format(Duration)`	Formats with up to two significant units: `"1y 3mo"`, `"4h 15m"`, `"45s"`, `"0s"`
`formatShort(Duration)`	Single significant unit: `"2h"`, `"15m"`, `"45s"`
`format(long millis, int maxUnits)`	Full control over unit count (1–7)
`parse(String input)`	Parses compact strings like `"90s"`, `"1d6h"`, `"2w"`, or plain seconds. Returns `null` when nothing parses
`parseOrThrow(String input)`	Same parsing rules, but throws `IllegalArgumentException` when the input is invalid

Supported units are y, mo, w, d, h, m, s, and ms; negative durations format as zero.

`InventorySnapshot`

xyz.refineryteam.refinerycore.api.inventory.InventorySnapshot captures a player’s complete inventory — storage contents, armor, and off hand — as an immutable object serializable to a single Base64 string. Useful for kits, backups, punishment rollbacks, and inventory viewers.

KitManager.java

// Capture and store
String saved = InventorySnapshot.capture(player).serialize();
String oneLiner = InventorySnapshot.captureToString(player);

// Restore later (replaces the current inventory entirely)
InventorySnapshot.deserialize(saved).restore(player);

// Merge into the current inventory instead of replacing it
InventorySnapshot.deserialize(saved).merge(player);

// One-liner restore
InventorySnapshot.restoreFromString(player, saved);

Method	Description
`capture(player)`	Snapshots the full inventory; items are cloned so later changes don’t affect the snapshot
`restore(player)`	Replaces the player’s entire inventory with the snapshot
`merge(player)`	Fills empty slots without clearing first; armor/off-hand only replace empty slots, overflow drops at the player’s feet
`serialize()` / `deserialize(data)`	Compact Base64 round-trip for database/config storage; corrupt data throws `IllegalArgumentException`
`captureToString(player)`	Convenience method combining `capture(player).serialize()`
`restoreFromString(player, data)`	Convenience method combining `deserialize(data).restore(player)`

`ProxyMessenger`

xyz.refineryteam.refinerycore.api.messaging.ProxyMessenger sends and receives plugin messages over the BungeeCord-compatible channel that Velocity also supports — the standard way for a backend Paper plugin to ask the proxy to move players between servers or broadcast custom payloads, with no proxy-side mod needed.

ServerSwitcher.java

ProxyMessenger messenger = new ProxyMessenger(plugin);

// Built-in subchannel: move a player to another backend server
messenger.connect(player, "survival-2");

// Custom payload delivered to your plugin on every backend server
messenger.forwardToAll("myplugin:sync", dataBytes);
messenger.forwardToServer("survival-2", "myplugin:sync", dataBytes);
messenger.forwardToAllIncludingSelf("myplugin:sync", dataBytes);

// Receive custom payloads
messenger.onMessage("myplugin:sync", (player, data) -> {
    String name = new String(data, StandardCharsets.UTF_8);
    handleRemoteJoin(name);
});

Method	Description
`new ProxyMessenger(plugin)`	Registers the proxy channel on the plugin’s behalf; call `shutdown()` from `onDisable()`
`connect(player, serverName)`	Asks the proxy to connect the player to another backend server
`connectOther(playerName, serverName)`	Same, for a named player who may not be online on this server
`forwardToAll(subchannel, bytes)`	Forwards a custom payload to every backend server
`forwardToServer(serverName, subchannel, bytes)`	Forwards a custom payload to one backend server
`forwardToAllIncludingSelf(subchannel, bytes)`	Forwards a custom payload to all servers, including this one
`requestPlayerCount(serverName)`	Requests a server’s player count; use an `onMessage("PlayerCount", ...)` handler for the reply. Pass `"ALL"` for the global count
`requestRealIp(playerName)`	Requests a player’s real IP; the reply arrives on the `"IP"` subchannel
`onMessage(subchannel, handler)` / `offMessage(subchannel)`	Registers/removes a handler for a custom subchannel; the handler receives the transport player and payload bytes

On modern Velocity setups this requires settings.toml → proxies.velocity.enable = true. Also note the receiving Player in onMessage is whoever the proxy used to deliver the message — often arbitrary — so treat it as transport context, not as the message subject.

​TimeFormat

​InventorySnapshot

​ProxyMessenger

`TimeFormat`

`InventorySnapshot`

`ProxyMessenger`