StoneLib

The parts every Paper plugin ends up writing, written once.

StoneLib is a Java library for Paper Minecraft plugins. It is not a plugin you install on a server: you add it as a dependency, shade it into your own jar, and construct only the pieces you need. There is no framework, no service locator, and no annotation scanning. Every module is a plain class you create with new in onEnable.

It is the common base for Anchorlight's plugins, and grew out of the code that kept being copied between them: sub-command routing, messages files, config migration, storage, cooldowns, menus, and, for networks, a cross-server message bus.

What is in it

Area	Package	What it gives you
Commands	command	CommandRouter and SubCommand, for /root <sub> [args] dispatch with permission checks and tab completion.
Configuration	config	ConfigManager, MultiConfigManager, and ConfigUpdater, which merges new keys into server configs and applies versioned renames. Plus ConfigValidator for field checks.
Messages	message	MessageService for a MiniMessage messages.yml, MiniMessages for named placeholders, and UntrustedText for sanitising player input.
Storage	storage	The Repository contract with YAML and SQLite implementations, plus LocationCodec.
MySQL	storage.sql	A HikariCP ConnectionPool, SchemaMigrator for ordered migrations, and MySqlRepository for state shared across servers.
Scheduler	scheduler	SchedulerService, which tracks every task so one call cancels them all, and runs async work with a main-thread callback.
Cooldowns	cooldown	CooldownService, per-player keyed cooldowns with a bypass permission.
Menus	menu	MenuHolder and MenuListener for read-only inventory menus, plus ItemBuilder.
Dialogs	dialog	FormDialog and FormResponse, a form builder over Paper's Dialog API that clamps what the client sends back.
Holograms	hologram	HologramService, floating text on native TextDisplay entities.
Loot Tables	loot	LootTable, weighted item rolls read from a config list.
Durations	time	Durations, player-facing time formatting in clock, prose, and compact shapes.
Permissions	permission	PermissionService, cached LuckPerms lookups and self-expiring temporary grants.
Cross-Server Messaging	messaging	MessageBus for Paper backends and ProxyMessageRelay for Velocity.
Render Loop	render	RenderLoop, one async loop that draws every per-player effect with distance culling.

Design principles

• Construct what you use. Nothing is wired for you and nothing starts on its own. A plugin that only needs messages and cooldowns never touches the rest.
• The database is the source of truth. Caches, messages between servers, and render snapshots are all allowed to be stale or lost. Persisted state never is.
• Never trust the client. Placeholder values cannot inject MiniMessage tags, dialog values are clamped, and menu clicks are cancelled before anything else happens.
• Fail soft on configuration, loud on programming errors. A typo in a loot table is logged and skipped. A blank server id or a duplicate dialog key throws immediately.
• Blocking calls are labelled. Every method that waits on a database says so, and the Threading Rules page lists them in one place.

Who uses it

StoneLib is the base for Anchorlight plugins such as EdenEffects, which uses the MySQL repository, the message bus, the render loop, permissions, dialogs, and untrusted-text sanitising across a Velocity network.

Where to go next

• Adding it to a project? Start with Installation.
• Wiring your first plugin? Getting Started walks through onEnable and onDisable.
• Unsure what can run off the main thread? Read Threading Rules.
• Looking for a specific class? The Modules section has a page per package.
• Build failing or something not behaving? Troubleshooting & FAQ.