HikariLib

A utility library extracted from Paper plugin development — so you don't rewrite the same boilerplate in every plugin.

Repository

<repository>
    <id>jitpack.io</id>
    <url>https://jitpack.io</url>
</repository>

Dependency

<dependency>
    <groupId>me.eventually</groupId>
    <artifactId>HikariLib</artifactId>
    <version>master-SNAPSHOT</version>
</dependency>

Requires Paper 1.21.1, Java 21.

What's inside

Menu system

Define menu layouts with a character matrix:

HikariMatrixDrawer drawer = new HikariMatrixDrawer(9)
    .addLine("XXX  XXXX")
    .addLine("  X  X  X")
    .addExplain('X', new ItemStack(Material.STONE), (event, slot, menu) -> {
        event.getWhoClicked().sendMessage("Clicked stone!");
    });

HikariMenu menu = new HikariMatrixDrawer.Builder()
    .withTitle("&6Example Menu")
    .withRows(3)
    .withDrawer(drawer)
    .build();

menu.open(player);

Implement HikariMenuDrawer if you need custom drawing logic.

Chat input

Ask a player a question and wait for their reply, with configurable timeout:

// Default 30-second timeout
ChatAsk.ask(player, "Enter your name:", name -> {
    player.sendMessage("Hello, " + name);
});

// 10-second timeout
ChatAsk.ask(player, "Enter the code:", code -> {
    // ...
}, 10000);

Database

Common DataBaseConnection interface. Both MySQL and SQLite come with HikariCP pooling built in:

DataBaseConnection db = new MySQLConnection("localhost", 3306, "mydb", "root", "pass", false);
// or new SQLiteConnection("plugins/xxx/data.db")

db.query("SELECT * FROM users WHERE age > ?", 18);
db.insert("users", null, "Alice", 25);

db.transaction(() -> {
    db.execute("UPDATE accounts SET balance = balance - 100 WHERE id = ?", 1);
    db.execute("UPDATE accounts SET balance = balance + 100 WHERE id = ?", 2);
    return null;
});

Scheduler

Write once, runs on both Bukkit and Folia:

HikariScheduler.addTimedTask(20, () -> player.sendMessage("Hello"), false);
HikariScheduler.addRepeatingTask(20, () -> player.sendMessage("Tick"), false);

ItemStack builder

Chainable item construction:

HikariItemStack item = new HikariItemStack(Material.DIAMOND_SWORD)
    .setName("&6Legendary Sword")
    .setLore(List.of("&7A sword of legend"))
    .setCustomModelData(1001);

player.getInventory().addItem(item.getItem());

Reflection

One-liner reflection calls:

ReflectionUtil.setField(obj, "someField", newValue);
String result = ReflectionUtil.callMethod(String.class, obj, "methodName", arg1, arg2);

Location & teleport

// Get the chunk a location belongs to
Chunk chunk = LocationUtils.getChunk(location);

// Get a block position within a chunk (0-15 offsets)
Location loc = LocationUtils.getChunkOffsetLocation(chunk, 5, 64, 5);

// Teleport a player (always async on Folia, configurable on Bukkit)
LocationUtils.teleportPlayer(player, targetLocation);       // sync
LocationUtils.teleportPlayer(player, targetLocation, true);  // async on Bukkit

Entity utilities

Run a task on an entity's scheduler. On Folia it goes through the entity scheduler automatically:

EntityUtil.runAsEntity(player, () -> {
    player.openInventory(menu);
});

Expiring HashMap

Entries auto-expire after the configured duration — no manual cleanup needed:

// 60-second TTL
ExpiringHashMap<UUID, String> cache = new ExpiringHashMap<>(60000);
cache.put(playerId, "some data");

String data = cache.get(playerId);  // not expired yet — returns the data

String gone = cache.get(playerId);  // 60 seconds later — returns null

// Shut down the background cleanup thread when done
cache.close();

Server environment

Detect the server platform so downstream code doesn't have to branch:

if (ServerEnvironment.isFolia()) {
    // use Folia-specific scheduling
} else {
    // use Bukkit scheduling
}

String version = ServerEnvironment.getMinecraftVersion();
String bukkitVersion = ServerEnvironment.getBukkitVersion();
String name = ServerEnvironment.getName();

// Full server metadata
ServerEnvironment.ServerMeta meta = ServerEnvironment.getMeta();
System.out.println(meta.getMotd());
System.out.println(meta.getMaxPlayers());

Build

mvn clean package

Install locally

mvn install

Then drop the jar into your Paper server's plugins/ directory.

License

MIT