Lattice

A developer framework for structured, Folia-aware Paper plugins on Java 21.

Lattice standardizes lifecycle, modules, services, configuration, commands, text, tasks, UI, storage, diagnostics, and optional integrations so Minecraft plugins can stay small, explicit, and production-ready.

What Is Lattice?

Lattice is the shared foundation for BerylStudios and BerylLabs Minecraft plugins. It is not a gameplay plugin and it does not add commands, worlds, mechanics, or player-facing features by itself.

Plugin authors use Lattice to build Paper/Folia plugins with a consistent runtime shape: explicit modules, predictable lifecycle phases, typed services, validated configuration, Folia-aware task routing, storage helpers, and diagnostics that are useful when something breaks in production.

Deployment Model

Since 0.8.0, the preferred deployment model is the standalone shared runtime:

| Mode | Use When | Runtime Behavior |
| --- | --- | --- |
| Standalone shared runtime | New Paper/Folia plugins that can depend on Lattice being installed on the server | The server installs the Lattice plugin once. Dependent plugins compile against Lattice without relocation and join the Lattice classpath through an explicit Paper dependency. |
| Legacy isolated library mode | Self-contained plugin jars or compatibility paths that still need shading | Each dependent plugin owns its own Lattice runtime, module graph, service registry, task tracking, storage handles, and diagnostics surface. |

The standalone runtime is the recommended path for new work because it avoids repeating shared infrastructure across every dependent plugin on the same server.

What It Provides

| Area | Built-in Support |
| --- | --- |
| Lifecycle | Load, enable, ready, disable, startup reports, and failure rollback |
| Modules | Explicit feature modules with dependency ordering and cycle detection |
| Services | Typed service registry without reflection-heavy dependency injection |
| Config | Configurate YAML, defaults, validation, schema versions, migrations, and optional Junction variable rendering |
| Commands | Backend-neutral command trees with Paper registration |
| Text | Adventure components, MiniMessage, and legacy input boundaries |
| Tasks | Folia-aware async, global, region, and entity scheduling |
| UI | Inventory menus, books, anvil input, and virtual sign input |
| Storage | SQLite, MySQL, MariaDB, PostgreSQL, HikariCP, migrations, JDBC helpers, and shared pool management in standalone mode |
| Diagnostics | Runtime snapshots for lifecycle, modules, services, commands, tasks, UI, storage, and integrations |
| Integrations | PlaceholderAPI, PacketEvents, Junction, Nexo, Oraxen, ItemsAdder, and CraftEngine |

Modules

Lattice is split into three Maven artifacts:

| Artifact | Purpose |
| --- | --- |
| io.github.hydr46605:lattice-api | Minimal API status markers and the first shared-runtime contract boundary. |
| io.github.hydr46605:lattice-core | Platform-neutral contracts and base implementations under dev.beryl.lattice. |
| io.github.hydr46605:lattice-paper | Paper/Folia bootstrap, scheduler, command, UI, diagnostics, storage, hook, integration, and standalone host adapters. |

lattice-core intentionally contains no Bukkit, Paper, or Folia classes. Server-specific behavior belongs in lattice-paper, keeping core APIs testable and stable for plugin authors.

Compatibility

• Java 21
• Modern Paper 1.21.x, currently targeting 1.21.11
• Folia-aware scheduling through explicit task contexts
• Adventure components and MiniMessage as the primary text format
• Pre-1.0 API status while the framework is hardened against real plugin integrations

Current Status

Lattice is in the 0.x beta line. Stable authoring paths exist, but breaking changes can still happen before 1.0.

The current focus is the shared-runtime architecture: one installed Lattice host, dependent plugins that register into that host cleanly, shared JDBC pool management, clearer diagnostics, and a smaller public API surface for long-term plugin authoring.