Skip to content
This repository was archived by the owner on Jul 5, 2026. It is now read-only.
BranchesTags

Repository files navigation

LoLib 3.0

Modern library for Minecraft plugin development on Paper and Folia servers.

Philosophy

  • Fluent API everywhere — builders, chaining, lambdas
  • Smart defaults — everything works out of the box
  • Explicit is better than implicit — no magic
  • Paper + Folia first — no legacy Bukkit-only code
  • Zero NullPointerException — Optional where needed, fail-fast where needed
  • Shade-friendly — library shades into each plugin
  • Kotlin-friendly — extension functions, DSL

What's New in 3.0

New Modules ✨

  • economy/ — Async economy API with multi-currency support
  • ratelimit/ — Rate limiting with sliding window algorithm
  • pipeline/ — Data processing chains (sync/async)
  • storage/ — Unified storage abstraction (Memory/Redis/MySQL)
  • event-bus/ — Internal event bus for Lo* plugins
  • i18n/ — Internationalization with auto-detect locale
  • teleportation/ — Safe teleportation with delays and history
  • permissions/ — Unified permission abstraction
  • serialization/ — JSON/YAML/NBT/Binary serialization
  • sound/ — Fluent sound API with presets
  • title/ — Title/ActionBar builder with sequences
  • debug/ — Visual debugging and performance profiling
  • cache/ — Fluent Caffeine cache wrapper (3.1.0)
  • async/ — CompletableFuture utilities with thread switching (3.1.0)
  • lazy/ — Lazy initialization wrapper (3.1.0)

Architecture Improvements

  • Modular structure organized by layers (platform/core/data/gameplay/world/ui/util/integration)
  • SOLID principles: SRP, OCP, LSP, ISP, DIP
  • Better separation of concerns
  • Improved Folia compatibility across all modules
  • Enhanced async/CompletableFuture support
  • CommandBuilder DSL for dynamic commands
  • Greedy args, nested subcommands, validation in commands
  • ISP-compliant storage interfaces (Readable, Writable, Expirable)

Module Structure

LoLib 3.0 consists of 52 independent modules organized by layers following SOLID principles:

Platform Layer

platform/common, platform/paper, platform/folia — Platform abstractions (IPaster, IScheduler, IPlatform)

Core Layer

core — LoPlugin, LoLogger, FeatureFlags, DependencyManager

Data Layer

data/config, data/nbt, data/playerdata, data/storage — Data storage and configuration
database — Database connections (HikariCP, Redis)

Gameplay Layer

gameplay/scheduler — Async/Sync tasks with Folia support
gameplay/commands — Annotation-based commands with DSL
gameplay/events — Custom Bukkit events
gameplay/cooldowns — Cooldown management
gameplay/items — ItemBuilder and custom items
gameplay/economy — Economy API (async, Folia-safe)
gameplay/ratelimit — Rate limiting with sliding window
gameplay/pipeline — Data processing chains

World Layer

world/schematics — .lpschem format, wand, paster
world/regions — World regions
world/worlds — WorldManager

UI Layer

ui/gui — InventoryGUI, PaginatedGUI, ScrollableGUI
ui/chat — MessageBuilder, chat formatting
ui/scoreboards — Sidebar, AnimatedTitle
ui/holograms — Holograms
ui/particles — Particle effects
ui/input — ChatInput, AnvilInput
ui/animation — Component animations
ui/sound — SoundBuilder with presets
ui/title — TitleBuilder, ActionBar

Util Layer

util/utils — Colors, MessageBuilder, BossBar, ActionBar
util/math — Mathematical utilities
util/physics — Vec3, AABB, physics
util/validation — Input validation
util/expressions — Expression evaluation
util/i18n — Internationalization
util/metrics — Metrics collection
util/performance — TPSMonitor, AsyncExecutor
util/serialization — JSON/YAML/NBT serialization
util/permissions — Permission abstraction
util/teleportation — Safe teleportation API

Integration Layer

integration/placeholders — PlaceholderAPI
integration/integrations — Other plugins
integration/packets — Packet API
integration/packet-entities — Packet entities
integration/npcs — NPC API
integration/leaderboards — Leaderboards
integration/event-bus — Internal event bus for Lo* plugins
integration/debug — Visual debugging and profiling

See docs/MODULES.md for dependency graph and TODO.md for detailed roadmap.

Quick Start

public class MyPlugin extends LoPlugin {

    @Override
    protected void enable() {
        loLogger().info("Plugin enabled!");

        // Commands with annotations
        CommandManager commands = new CommandManager(this);
        commands.register(new MyCommand());
        
        // Or CommandBuilder DSL
        CommandBuilder.of("give")
            .permission("myplugin.give")
            .playerOnly()
            .arg("item", String.class)
            .arg("amount", Integer.class, 1, 64)
            .greedyArg("reason")
            .executes((sender, args) -> {
                sender.sendMessage("Gave " + args.get("amount") + "x " + args.get("item"));
            })
            .register(commands);

        // Economy API (async, Folia-safe)
        EconomyAPI.deposit(player.getUniqueId(), 100.0)
            .thenAccept(result -> {
                if (result == TransactionResult.SUCCESS) {
                    player.sendMessage("You received $100!");
                }
            });

        // Storage abstraction
        StorageProvider<String, PlayerData> storage = new MemoryStorage<>();
        storage.set("player123", playerData)
            .thenCompose(v -> storage.expire("player123", Duration.ofMinutes(30)))
            .thenRun(() -> loLogger().info("Data saved with TTL"));

        // Pipeline processing
        Pipeline<String> pipeline = Pipeline.<String>create()
            .addStep("uppercase", String::toUpperCase)
            .addStep("trim", String::trim)
            .addStep("prefix", s -> "Hello, " + s);
        String result = pipeline.execute("  world  ");

        // Teleportation API
        Teleport.builder()
            .player(player)
            .destination(location)
            .delay(3, TimeUnit.SECONDS)
            .onMove(CancelBehavior.CANCEL)
            .onSuccess(p -> p.sendMessage("Teleported!"))
            .execute();

        // i18n
        Translator translator = new Translator(this, Locale.ENGLISH);
        translator.translate(player, "welcome.message", player.getName());
    }

    @Override
    protected void dependencies(DependencyManager manager) {
        manager.add("com.zaxxer", "HikariCP", "5.1.0");
    }
}

Project Status

Version: 3.0.0
Status: Production Ready ✅

Completed ✅

  • ✅ Version 3.0.0 released
  • ✅ 52 modules with SOLID architecture
  • ✅ All critical bugs fixed (SpotBugs, Checkstyle)
  • ✅ BUILD SUCCESSFUL: 1935 classes, 2.27 MB unified JAR
  • ✅ Commands: greedy args, validation, nested subcommands, DSL
  • ✅ Pipeline: sync/async processing chains
  • ✅ Storage: ISP-compliant abstraction (Memory/Cached)
  • ✅ Economy: fully async API with multi-currency
  • ✅ RateLimiter: sliding window algorithm
  • ✅ EventBus: internal event system
  • ✅ i18n: internationalization with auto-detect
  • ✅ Debug: visual debugging and profiling

Next Steps

  • Add more unit tests
  • Implement RedisStorage/MySQLStorage in plugins
  • Update documentation with examples
  • Create release artifacts

Документация

📚 Гайды по использованию

📖 Справочная документация

New features in 3.0:

  • ✨ Economy API — Async economy with multi-currency support
  • ✨ RateLimiter — Sliding window rate limiting
  • ✨ Pipeline API — Data processing chains (sync/async)
  • ✨ Storage API — Unified abstraction (Memory/Redis/MySQL)
  • ✨ EventBus — Internal event system for Lo* plugins
  • ✨ i18n — Internationalization with auto-detect locale
  • ✨ CommandBuilder DSL — Fluent command registration
  • ✨ Commands — Greedy args, nested subcommands, validation
  • ✨ Teleportation API — Safe teleports with delays and location history
  • ✨ Permissions API — Unified permission abstraction
  • ✨ Serialization API — JSON/YAML/NBT/Binary serialization
  • ✨ Sound API — Fluent sound builder with presets
  • ✨ Title API — Title/ActionBar sequences
  • ✨ Debug API — Visual debugging and profiling

Features from 2.0:

  • ✨ FoliaWorldManager — Safe world operations on Folia
  • ✨ ItemConfig — Create items from YAML configs
  • ✨ NumberFormatter — Format numbers (1K, 1M, 1B)
  • ✨ TimeFormatter — Format time (01:23:45, 1h 23m)
  • ✨ MultiServerSync — Cross-server data sync via Redis
  • ✨ PostgreSQL & Redis support
  • ✨ TPSMonitor & AsyncExecutor
  • ✨ VoidGenerator — Empty world generator
  • ✨ Colls — Functional collection utilities
  • ✨ GUITemplate & GUIValidator — GUI templates and validation
  • ✨ BossBarBuilder & BossBarManager — Fluent boss bar API
  • ✨ Gson integration — Built-in JSON support
  • ✨ Unified JAR — Single JAR with all modules (2.2 MB)

Paper 1.21+ Support:

  • DataComponent API (1.20.5+)
  • Dialog API (1.21.6+)
  • Folia Region Threading
  • Adventure Component API

Requirements

  • Java 21+
  • Paper 1.20.1+ or Folia
  • Gradle 8.0+

Build

# Build all modules
./gradlew build

# Build unified JAR with all modules (2+ MB)
./gradlew unifiedJar
# Result: build/libs/lolib-3.0.0.jar

License

MIT License

About

No description, website, or topics provided.

Resources

Readme

Code of conduct

Code of conduct

Contributing

Contributing

Security policy

Security policy
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages