Developers & API

Integrate your Hytale server plugins with HyPrison Core: economy (balance, withdraw, deposit), placeholders for scoreboards and UIs, and services for ranks, mines, plots, warps, and more.

Getting the plugin

Obtain the HyPrison Core plugin instance via the Hytale server/engine plugin API (e.g. by plugin ID or name). The plugin exposes HyPrisonCorePlugin.get() for use once you have a reference. Call API methods from the main/server thread unless your engine allows otherwise.

Feature toggles

HyPrison Core systems can be turned off in config.json. Before using a service, check that the feature is enabled:

EnableEconomy, EnableCrates, EnablePermissions, EnablePlots, EnableWarps, EnableKits, EnableTags, EnableHolograms, EnableMines, EnablePickaxe, EnableNpcs, EnableLeaderboards

All default to true. Set to false to disable a system or use another plugin for that feature. Use plugin.isEconomyEnabled(), plugin.isMinesEnabled(), etc. before calling the corresponding service.

Economy API

When EnableEconomy is true, use HyPrison Core’s economy for balances and transactions (e.g. shop purchase = withdraw, refund = deposit).

Check plugin.isEconomyEnabled().
Get the service: EconomyService economy = plugin.getEconomyService();

Method	Use case
`getBalance(UUID playerUuid)`	Show balance or check if player can afford a price.
`hasAtLeast(UUID playerUuid, long amount)`	Quick check before charging (returns true if balance ≥ amount).
`withdraw(UUID playerUuid, long amount, String reason)`	Charge the player (e.g. shop purchase). Returns false if insufficient balance.
`deposit(UUID playerUuid, long amount, String reason)`	Give money (e.g. refund, reward).
`setBalance(UUID playerUuid, long balance, String reason)`	Set balance directly (admin/setup).
`transfer(UUID sender, UUID target, long amount)`	Transfer between two players.
`topBalances(int limit)`	Get top balances (e.g. for custom baltop).
`formatCurrency(long amount)`	Format amount for display (e.g. "$1,234").

Notes: Use the player’s UUID from the Hytale API for all calls. Use a short reason string for withdraw/deposit (e.g. "Shop: Diamond Sword"); it may be stored in transaction logs.

Placeholder API

Other plugins (e.g. scoreboard or custom UI plugins) can resolve HyPrison Core placeholders in strings. Get PlaceholderService placeholders = plugin.getPlaceholderService(); then:

By UUID: placeholders.resolve(playerUuid, "Balance: {balance} | Rank: {rank}");
By Player (mine-aware): placeholders.resolve(player, "Mine: {mine} | Progress: {progress}%"); — use this when the player might be in a mine so {mine}, {progress}, {resetin}, {mineavg} are filled.
Map of all values: placeholders.buildPlaceholders(uuid, player) returns Map<String, String> for your own replacement logic.

Placeholder syntax: {name}. Names are case-insensitive.

Placeholder	Description	Example
`playername`	Player display name	Steve
`balance`	Formatted money balance	$1,234
`tokens`	Formatted token balance	500
`rank`	Rank display (prefix text)	[A] or [B] Steve
`prestige`	Prestige id with P prefix	P0, P1
`totalblocks`	Total blocks mined	12,345
`nextrankcost`	Cost to rank up (formatted)	$2,600
`sellmultiplier`	Sell multiplier for rank	1.5
`totalplaytime`	Playtime	1h 23m 45s
`pickaxelevel`	Pickaxe level	5
`pickaxexp`	Current XP toward next level	1200
`pickaxeprogress`	Progress to next level (0–100)	70
`pickaxeprogressbar`	Progress bar + percent	███████░░░ 70%
`fortunelevel`, `fortunemultiplier`	Fortune upgrade	3, 1.15
`sellupgrademultiplier`	Sell booster multiplier	1.2
`autosell`	Auto-sell on/off	ON or OFF
`mine`	Current mine name (Player only)	Coal Mine
`progress`	Mine progress % or — (Player only)	67.5 or —
`resetin`	Blocks until reset or countdown (Player only)	5000 blocks or 02:30
`mineavg`	Average sell value in mine (Player only)	$12

Leaderboard placeholders: {lb_balance_name_1} … {lb_balance_name_20} and {lb_balance_value_1} … {lb_balance_value_20} (and similarly for tokens, prestige, rank, blocks).

Other services

You can read and use data via the plugin’s services. There is no formal contract for mutating crates, plots, warps, etc. from other plugins; those are primarily controlled by config and in-game commands. Economy and placeholders are the main integration points for shops and scoreboards.

getRankService() — ranks, prestige, progress, prefix, sell multiplier, display name, next rank cost.
getMineService() — mine definitions, composition, prices, runtime snapshot, mine at player position, list of mines a player can access.
getPlotManager(), getPlotWorldManager() — plot claims and world.
getWarpService(), getCrateService(), getNpcManager(), getHologramManager() — warps, crates, NPCs, holograms.
getPickaxeService() — pickaxe level, tokens, upgrades.

Code examples

Short snippets are below. For more copy-paste examples (shop purchase, reward, baltop, transfer, scoreboard with mine context, rank cost, mine composition, feature checks), see API examples.

Economy: shop purchase

HyPrisonCorePlugin plugin = HyPrisonCorePlugin.get();
if (plugin == null || !plugin.isEconomyEnabled()) return;
EconomyService economy = plugin.getEconomyService();
long price = 500;
if (!economy.hasAtLeast(playerUuid, price)) {
    // Not enough money
    return;
}
if (economy.withdraw(playerUuid, price, "Shop: MyItem")) {
    // Give item to player
}

Placeholder: scoreboard line

PlaceholderService ph = plugin.getPlaceholderService();
String template = "Balance: {balance} | Rank: {rank} | Tokens: {tokens}";
String resolved = ph.resolve(player.getUuid(), template);
// Or, for mine-aware (mine, progress, resetin, mineavg):
// String resolved = ph.resolve(player, template);
setScoreboardLine(resolved);

Rank: prefix and sell multiplier

RankService rankService = plugin.getRankService();
String prefix = rankService.getPrefixText(playerUuid);
String rankId = rankService.getRankId(playerUuid);
double sellMultiplier = rankService.getSellMultiplier(playerUuid);

Mine: at player position and list accessible mines

MineService mineService = plugin.getMineService();
Optional<MineDefinition> mineAt = mineService.resolveMineAtPlayer(player);
List<String> names = mineService.getMineNames(
    rankService.getRankId(playerUuid),
    rankService.getPrestigeId(playerUuid)
);

Packages

HyPrisonCorePlugin — com.hyprisoncore.HyPrisonCorePlugin · EconomyService — com.hyprisoncore.economy.EconomyService · PlaceholderService — com.hyprisoncore.placeholder.PlaceholderService · RankService — com.hyprisoncore.rank.RankService · MineService — com.hyprisoncore.mine.MineService · MineDefinition — com.hyprisoncore.config.MineDefinition

HyPrison Core by DrSmoker / Highwater Studios LLC. Premium license — one key per server. For licensing: Discord — drsmokerttv.