Lattice
一个用于在 Java 21 上构建结构化、感知 Folia 的 Paper 插件的开发框架。
Lattice 标准化了生命周期、模块、服务、配置、命令、文本、任务、UI、存储、诊断以及可选集成,使 Minecraft 插件能够保持精简、显式且具备生产就绪状态。
什么是 Lattice?
Lattice 是 BerylStudios 和 BerylLabs Minecraft 插件的共同基础。它不是一个玩法插件,本身不会添加命令、世界、机制或面向玩家的功能。
插件作者使用 Lattice 来构建具有统一运行时形态的 Paper/Folia 插件:包括显式的模块、可预测的生命周期阶段、类型化的服务、经过验证的配置、感知 Folia 的任务路由、存储辅助工具以及在生产环境中出现问题时很有用的诊断功能。
部署模型
自 0.8.0 版本起,推荐的部署模型是独立共享运行时:
| 模式 | 适用场景 | 运行时行为 |
|---|---|---|
| 独立共享运行时 | 可以依赖服务器上已安装 Lattice 的新 Paper/Folia 插件 | 服务器只需安装一次 Lattice 插件。依赖插件在不进行重定位的情况下针对 Lattice 进行编译,并通过明确的 Paper 依赖加入 Lattice 类路径。 |
| 传统隔离库模式 | 需要自包含插件 jar 包或仍需阴影处理(shading)的兼容路径 | 每个依赖插件都拥有自己的 Lattice 运行时、模块图、服务注册表、任务跟踪、存储句柄和诊断接口。 |
独立运行时是新开发的首选路径,因为它避免了在同一服务器的每个依赖插件中重复构建共享基础设施。
提供的内容
| 领域 | 内置支持 |
|---|---|
| 生命周期 | 加载、启用、就绪、禁用、启动报告以及失败回滚 |
| 模块 | 具有依赖排序和循环检测功能的显式功能模块 |
| 服务 | 无需重度反射依赖注入的类型化服务注册表 |
| 配置 | Configurate YAML、默认值、验证、架构版本、迁移以及可选的 Junction 变量渲染 |
| 命令 | 后端无关的命令树,配合 Paper 注册 |
| 文本 | Adventure 组件、MiniMessage 以及遗留输入边界 |
| 任务 | 感知 Folia 的异步、全局、区域和实体调度 |
| UI | 库存菜单、书籍、铁砧输入和虚拟告示牌输入 |
| 存储 | SQLite、MySQL、MariaDB、PostgreSQL、HikariCP、迁移、JDBC 辅助工具,以及在独立模式下的共享连接池管理 |
| 诊断 | 针对生命周期、模块、服务、命令、任务、UI、存储和集成的运行时快照 |
| 集成 | PlaceholderAPI、PacketEvents、Junction、Nexo、Oraxen、ItemsAdder 和 CraftEngine |
模块
Lattice 分为三个 Maven 工件:
| 工件 | 用途 |
|---|---|
io.github.hydr46605:lattice-api |
最小的 API 状态标记和首个共享运行时契约边界。 |
io.github.hydr46605:lattice-core |
平台中立的契约和位于 dev.beryl.lattice 下的基础实现。 |
io.github.hydr46605:lattice-paper |
Paper/Folia 引导程序、调度器、命令、UI、诊断、存储、钩子、集成以及独立主机适配器。 |
lattice-core 故意不包含任何 Bukkit、Paper 或 Folia 类。服务器特定行为属于 lattice-paper,从而保持核心 API 可测试且对插件作者稳定。
兼容性
- Java 21
- 现代 Paper
1.21.x,当前目标版本为1.21.11 - 通过显式任务上下文实现感知 Folia 的调度
- 以 Adventure 组件和 MiniMessage 作为主要文本格式
- 在框架针对真实插件集成加固之前,处于 1.0 之前的 API 状态
当前状态
Lattice 处于 0.x 测试版阶段。虽然存在稳定的开发路径,但在 1.0 发布之前仍可能发生破坏性更改。
当前的重点是共享运行时架构:一个已安装的 Lattice 主机、干净地注册到该主机的依赖插件、共享 JDBC 连接池管理、更清晰的诊断功能,以及面向长期插件开发的更小公共 API 表面。
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 targeting1.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.
下载 Lattice
下载 Lattice
下载 Lattice
下载 Lattice
下载 Lattice
下载 Lattice
下载 Lattice
下载 Lattice
下载 Lattice
下载 Lattice
Lattice 0.8.9 - 可测试性、诊断清晰度与发布文档
新增
PaperDiagnosticContributor快照详情键现在已在 Javadoc 中记录:plugin、version、dataFolder、enabled、currentThread。直接阅读该贡献者类的插件作者无需查阅源码即可了解快照结构。PaperIntegrationBootstrap.failureMessage(Throwable)和failureDetails(Throwable)现已设为static包私有,以便通过单元测试锁定格式化契约,而无需经过反射桥接。PaperDiagnosticContributor.detailsFor(Path, String, String, boolean)现已成为包私有辅助方法,带有参数验证,使得快照详情映射的结构可以在不实例化JavaPlugin(其构造函数在 Bukkit 加载器之外不受支持)的情况下进行单元测试。PaperIntegrationBootstrapFailureLoggingTest锁定了针对 7 条反射集成引导路径的失败日志记录契约。PaperDiagnosticContributorTest锁定了currentThread快照详情,防止其意外漂移为硬编码值。
更改
PaperDiagnosticContributor.detailsFor(...)的参数顺序现改为(Path dataFolder, String pluginName, String pluginVersion, boolean enabled)。将Path置于首位是为了在视觉上区分两个含义不同的相邻String参数,并消除调用点参数错位这一隐患。唯一的调用方 (snapshot()) 已相应更新。可观察的输出(快照详情映射的键和值)保持不变。docs/api-guide.md#diagnostics现详细说明了paper贡献者的快照详情键,以及集成details映射的结构(失败时的reason/message,AVAILABLE状态的PacketEvents绑定时的apiClass/version)。docs/build-and-release.md澄清了 同时GitHub Release和Modrinth Release工作流会在推送匹配v*标签模式的事件时自动触发。因此,普通的git push origin v<version>会并行发布至 Maven Central、GitHub Packages 镜像、GitHub Release 和 Modrinth。手动执行gh workflow run "Modrinth Release"仅用于恢复;该工作流在发布前已针对 Modrinth API 执行自身的幂等性检查。PaperIntegrationBootstrapFailureLoggingTest.failureDetailsMapIsImmutable现使用assertThrows(UnsupportedOperationException.class, ...)来实际验证Map.of不可变性声明(替换了之前恒成立的containsKey断言)。
修复
- 修复了
PaperDiagnosticContributor.detailsFor(...)中的参数错位隐患:之前的(String, String, Path, boolean)参数列表将两个含义不同的字符串相邻放置。重新排序消除了这一风险,且不改变可观察的行为。
兼容性
- 无插件编写 API 变更。
- 未修改任何稳定的
@StableApi类型。 - 无新的传递依赖项。
- 测试仅为新增;未更改或删除现有测试。
failureDetails和failureMessage此前为private static,仍保留为@InternalApi;现改为static包私有,以满足相同的内部专用契约。
仍处于实验阶段(状态未变)
dev.beryl.lattice.updatedev.beryl.lattice.hookdev.beryl.lattice.template及注解处理器
关于这个资源的讨论、问题反馈与使用心得
还没有讨论,来发第一帖吧
你是这个资源的作者?登录后可认领此资源。
相似资源
插件
PacketEvents 是一款专为 Minecraft Java 版打造的协议库,旨在简化数据包的处理与传输。
插件
ExyliaPlugins 的库。
插件
通过对话框或铁砧界面帮助你的 Anthme
插件
重新定义服务器上的生物运输方式。使用高度可定制的口袋道具,安全地捕获、存储和释放任何实体。
插件
为基于 Spigot/Paper/Folia 的服务器添加对 Vivecraft 的支持
插件
用于绘制游戏内地图或在浏览器中随探索实时进行地图绘制的实时地图。
评论 0
登录后参与评分
还没有评论,来抢沙发吧