Skip to content

Enhance Folia scheduler support, update math utilities and more. #15

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
sun-mc-dev merged 3 commits into from
Jun 25, 2026
Merged

Enhance Folia scheduler support, update math utilities and more. #15

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
5bb7971
fix reflection package of folia scheduler and marked plugin module s…
sun-mc-dev Jun 25, 2026
0215204
release: v1.0.8 - add math package, remove provided plugin, and rewri…
sun-mc-dev Jun 25, 2026
3780080
workflow update
sun-mc-dev Jun 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/dev-build.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,6 @@ jobs:
- name: Publish Dev-Build Release
run: |
gh release delete dev-build --yes || true
gh release create dev-build oumlib-plugin/target/oumlib-plugin-*.jar --title "Development Build" --notes "Automated pre-release build of OumLib."
gh release create dev-build oumlib-core/target/oumlib-core-*.jar --title "Development Build" --notes "Automated pre-release build of OumLib."
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
4 changes: 1 addition & 3 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,4 @@
/example-plugin/example-plugin.iml
/example-plugin/target
/oumlib-core/oumlib-core.iml
/oumlib-core/target
/oumlib-plugin/target
/oumlib-plugin/oumlib-plugin.iml
/oumlib-core/target
220 changes: 122 additions & 98 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,21 +1,40 @@
# oumlib
# OumLib

[![](https://jitpack.io/v/sun-mc-dev/oumlib.svg)](https://jitpack.io/#sun-mc-dev/oumlib)
[![](https://img.shields.io/github/v/release/sun-mc-dev/oumlib?color=orange&style=for-the-badge)](https://github.com/sun-mc-dev/oumlib/releases)
[![](https://img.shields.io/jitpack/v/github/sun-mc-dev/oumlib?color=yellow&style=for-the-badge)](https://jitpack.io/#sun-mc-dev/oumlib)
[![](https://img.shields.io/badge/Java-21+-orange?style=for-the-badge&logo=openjdk)](https://adoptium.net/)
[![](https://img.shields.io/badge/Folia-Compatible-gold?style=for-the-badge)](https://github.com/PaperMC/Folia)

A lightweight, multi-platform library for Paper (Minecraft servers) and Velocity (proxies) built for Java 21. It helps developers write clean, boilerplate-free code.
OumLib is a lightweight, utility-centric library designed for Minecraft servers (Paper/Spigot) and proxy networks (Velocity). Built around Java 21 virtual threads, it provides modern, compile-safe, and thread-safe abstractions to eliminate boilerplate code.

## Requirements & Compatibility
OumLib is designed to be shaded and relocated directly into your plugin JAR.

- **Java**: Java 21 or higher (utilizes Virtual Threads).
- **Paper**: Version 1.21.4 or newer.
- **Velocity**: Version 3.5.x or newer.
- **Folia**: Fully compatible. Tasks run on safe async scheduler structures, and it supports Folia's multi-threaded tick environment.
---

## Quick Navigation

| Module | Description | Documentation |
|:---------------------|:-------------------------------------------------------------|:-------------------------------------------|
| **Setup & Platform** | Shaded setup lifecycle and platform detection utilities | **[Setup Guide](docs/setup.md)** |
| **Commands** | Fluent Brigadier command builders with cooldown support | **[Commands](docs/commands.md)** |
| **Configuration** | Automatic-reloading record configurations with comments | **[Configuration](docs/configuration.md)** |
| **Menus & GUIs** | Easy chest-layouts, button binding, paginated interfaces | **[Inventories](docs/inventories.md)** |
| **Scheduler** | Virtual-thread loops, TaskGroups, and Folia adaptors | **[Scheduler](docs/scheduler.md)** |
| **Events** | Chainable context-aware event registers with filters | **[Events](docs/events.md)** |
| **Math Utilities** | FastMath shortcuts, Vector3D, Volume3D, MathEval expressions | **[Math](docs/math.md)** |
| **Visual Effects** | Particle pathways: bezier curves, lines, helices | **[Visual Effects](docs/effects.md)** |
| **Display Entities** | Fluent transforms and DisplayBuilder controls | **[Display Entities](docs/entities.md)** |
| **Text & PAPI** | Kyori MiniMessage presets, placeholder hooks | **[Text & Placeholders](docs/text.md)** |
| **Database** | Non-blocking database connectors for SQLite and MySQL | **[Database](docs/database.md)** |
| **Plugin Bridges** | Auto-hooks for Economy, Permissions, Nexo and CustomItems | **[Bridges](docs/bridges.md)** |
| **General Utils** | PDC wrappers, duration parses, location serializing | **[Utilities](docs/utilities.md)** |
| **Web Hookers** | Asynchronous HTTP requests and Discord webhook builders | **[Web & Discord](docs/web.md)** |

---

## Installation

Add the JitPack repository and the library dependency to your `pom.xml`.
Declare the JitPack repository and OumLib dependency in your `pom.xml`.

### 1. Add Repository
```xml
Expand All @@ -26,9 +45,6 @@ Add the JitPack repository and the library dependency to your `pom.xml`.
```

### 2. Add Dependency
If you are shading the library into your plugin, declare the compile-scope dependency below.
Look for "VERSION" at our github releases page: [Releases](https://github.com/sun-mc-dev/oumlib/releases)

```xml
<dependency>
<groupId>com.github.sun-mc-dev.oumlib</groupId>
Expand All @@ -38,12 +54,10 @@ Look for "VERSION" at our github releases page: [Releases](https://github.com/su
</dependency>
```

### 3. Shade and Relocate the Dependency
To prevent classpath conflicts with other plugins running different versions of OumLib on the same server, you must **relocate** the library packages into your own plugin's package space.
### 3. Shading & Relocation
You must relocate OumLib inside your package space to prevent classpath conflicts with other plugins running different versions of OumLib on the same server.

Also, exclude dependency security signatures to avoid runtime validation errors.

Add this `maven-shade-plugin` configuration to your plugin's `pom.xml`:
Add this configured `maven-shade-plugin` to your `pom.xml`:

```xml
<build>
Expand All @@ -55,14 +69,12 @@ Add this `maven-shade-plugin` configuration to your plugin's `pom.xml`:
<configuration>
<createDependencyReducedPom>false</createDependencyReducedPom>
<relocations>
<!-- Relocate oumlib into your own plugin package (nested dependencies like Hikari are already auto-relocated internally) -->
<relocation>
<pattern>dev.oum.oumlib</pattern>
<shadedPattern>your.plugin.package.libs.oumlib</shadedPattern>
</relocation>
</relocations>
<filters>
<!-- Exclude security signature files that break shaded JARs -->
<filter>
<artifact>*:*</artifact>
<excludes>
Expand Down Expand Up @@ -91,86 +103,98 @@ Add this `maven-shade-plugin` configuration to your plugin's `pom.xml`:

## Quick Start Example

Here is a short preview showing how clean it is to set up a configuration, a command, and a chest GUI on Paper:
Here is a real-world scenario showing how to load a player profile asynchronously from a SQLite database, register a command to open a GUI shop, and play custom leveling sound/particle effects upon purchase:

```java
// 1. Declare config as a Java Record
public record MyConfig(
@Comment("Default broadcast message") String broadcastMessage
) implements ConfigSection {}

// 2. Load the configuration
ConfigManager<MyConfig> config = ConfigManager.of(MyConfig.class, "config.yml",
() -> new MyConfig("<yellow>Default broadcast message!</yellow>")
).enableAutoReload();

// 3. Declare permission and register a command to open a GUI
Permission adminPermission = Permission.builder("myplugin.admin").build();

Commands.literal("admin")
.permission(adminPermission)
.subcommand(sub -> sub
.label("menu")
.executes(context -> {
if (!context.isPlayer()) return;

// Build and open a GUI
ChestMenu.builder()
.title("<gold>Dashboard</gold>")
.rows(3)
.pattern(
"#########",
"# B #",
"#########"
)
.bind('B', ItemBuilder.of(Material.BOOK).name("<yellow>Broadcast</yellow>").build())
.onClick('B', click -> {
// Send message and close menu
Text.send(click.player(), config.get().broadcastMessage());
import dev.oum.oumlib.OumLib;
import dev.oum.oumlib.command.Commands;
import dev.oum.oumlib.config.ConfigManager;
import dev.oum.oumlib.config.ConfigSection;
import dev.oum.oumlib.database.Database;
import dev.oum.oumlib.effect.Effects;
import dev.oum.oumlib.inventory.ChestMenu;
import dev.oum.oumlib.inventory.ItemBuilder;
import dev.oum.oumlib.scheduler.Scheduler;
import dev.oum.oumlib.text.Text;
import dev.oum.oumlib.util.Permission;
import org.bukkit.Material;
import org.bukkit.Particle;
import org.bukkit.Sound;
import org.bukkit.entity.Player;
import org.bukkit.plugin.java.JavaPlugin;
import java.io.File;

public record ShopConfig(String itemTitle, int itemPrice) implements ConfigSection {}

public final class ProfileShopPlugin extends JavaPlugin {
private ConfigManager<ShopConfig> config;
private Database db;

@Override
public void onEnable() {
OumLib.init(this);

config = ConfigManager.of(ShopConfig.class, "shop.yml",
() -> new ShopConfig("<gold>Super Star</gold>", 100)
).enableAutoReload();

db = Database.sqlite(new File(getDataFolder(), "profiles.db"));
db.executeUpdate("CREATE TABLE IF NOT EXISTS economy (uuid VARCHAR(36) PRIMARY KEY, balance INT)");

Commands.literal("shop")
.permission(Permission.builder("myplugin.shop").build())
.executes(context -> {
if (!context.isPlayer()) {
return;
}
Player player = context.playerOrThrow();

db.executeQuery("SELECT balance FROM economy WHERE uuid = ?", player.getUniqueId().toString())
.thenAcceptSync(rows -> {
int balance = rows.isEmpty() ? 500 : (int) rows.getFirst().get("balance");
openShopMenu(player, balance);
});
}).register();
}

private void openShopMenu(Player player, int balance) {
ChestMenu.builder()
.title("<dark_gray>Server Shop | Balance: " + balance + "</dark_gray>")
.rows(3)
.pattern(
"#########",
"# P #",
"#########"
)
.bind('#', ItemBuilder.of(Material.GRAY_STAINED_GLASS_PANE).name(" ").build())
.bind('P', ItemBuilder.of(Material.NETHER_STAR).name(config.get().itemTitle()).lore("<yellow>Price: " + config.get().itemPrice() + "</yellow>").build())
.onClick('P', click -> {
if (balance < config.get().itemPrice()) {
Text.send(click.player(), "<red>Insufficient balance!</red>");
click.player().closeInventory();
})
.build()
.open(context.playerOrThrow());
})
).register();
return;
}

int newBalance = balance - config.get().itemPrice();
db.executeUpdate("INSERT INTO economy (uuid, balance) VALUES (?, ?) ON DUPLICATE KEY UPDATE balance = ?",
click.player().getUniqueId().toString(), newBalance, newBalance);

Text.send(click.player(), "<green>Purchased successfully!</green>");
click.player().closeInventory();

Effects.sound(Sound.ENTITY_PLAYER_LEVELUP).volume(1.0F).pitch(1.2F).play(click.player());
Effects.particle(Particle.HAPPY_VILLAGER).count(15).offset(0.5, 0.5, 0.5).spawn(click.player().getLocation());
})
.build()
.open(player);
}

@Override
public void onDisable() {
if (db != null) {
db.close();
}
OumLib.shutdown();
}
}
```

---

## Local Compilation & Fallback

If you want to build the library yourself, or if you prefer to install it locally instead of using JitPack:

1. Clone this repository.
2. Open a terminal in the root directory.
3. Run the Maven installation command:
```bash
mvn clean install
```
4. You can now reference the library in your local projects without declaring the JitPack repository:
```xml
<dependency>
<groupId>dev.oum</groupId>
<artifactId>oumlib-core</artifactId>
<version>VERSION</version>
<scope>compile</scope>
</dependency>
```

---

## Features & Documentation

Detailed guides for each package:

- **[Main Setup & Initialization](docs/setup.md)**: How to initialize OumLib on Paper and Velocity.
- **[Commands](docs/commands.md)**: A simple Brigadier-based command system with cooldowns.
- **[Configurations](docs/configuration.md)**: Auto-reloading record-based configurations.
- **[Database](docs/database.md)**: Non-blocking asynchronous SQLite and MySQL database helpers.
- **[Events](docs/events.md)**: Dynamic, fluent event listeners for Paper and Velocity.
- **[GUI & Chest Menus](docs/inventories.md)**: Easy chest menus with layouts and click actions.
- **[Scheduler](docs/scheduler.md)**: Platform-agnostic scheduler for delayed and repeating tasks.
- **[Text & Placeholders](docs/text.md)**: MiniMessage text presets and custom placeholders.
- **[Plugin Bridges](docs/bridges.md)**: Economy, Custom Items, Nexo, and LuckPerms Permission Bridges.
- **[General Utilities](docs/utilities.md)**: PDC wrappers, duration formatting, and location serialization.
- **[Web & Discord Webhooks](docs/web.md)**: Asynchronous Discord Webhook client and embed builder.
Loading
Loading