LMili（米粒）— 基于 Folia 的高性能 Minecraft 服务端核心

核心特性

在 Folia 区域多线程调度模型之上，提供稳定性修复、性能优化与 API 扩展

⚙

Folia 稳定性修复

系统性排查并修复 Folia 区域线程模型下的并发问题与崩溃风险

Region Balancer 共享线程池动态负载均衡
无锁滑动窗口统计区域 tick 耗时
Adaptive TPS 根据实时负载动态调整
全局 UUID 注册中心防止任务 ID 碰撞
catch(Exception) → catch(Throwable) 全面加固

🐛

Bug 修复

大量针对 Folia 区域线程模型的修复，覆盖关键游戏行为

玩家重生位置修正
实体传送跨区/末影珍珠/维度切换竞态修复
区域外寻路/拴绳/目标选择防护
POI 更新延迟、区块重载检测
RegionizedTaskQueue 并发引用修正

⚡

通用性能优化

来自 Gale / Lithium / Pufferfish / SparklyPaper / Kaiiju 等上游的通用优化

噪声生成、AI 属性集合、大脑映射优化
实体移动零位移跳过、canSee 检查优化
区块加载查找削减、寻路区域限制
网络与协议层优化、区块增量压缩
村民 lobotomize（发呆）优化

🔌

API 扩展

在 Folia/Paper API 之上提供更多能力，方便插件开发者

Tick Regions API（区域查询/操作）
ReplayMod 摄影师实体 API
Bytebuf 自定义数据包读写 API
实体传送异步事件
Waypoint 路径点追踪 API

线程安全加固

对全部 Java 源码进行系统性 bug 排查，覆盖致命级、资源泄漏级与并发竞态级问题

线程静默死亡修复

全项目 22+ 处 catch(Exception) → catch(Throwable)，防止 OOM/StackOverflow 等 Error 绕过捕获导致调度器线程永久死亡

致命级

ChunkHotness NaN 修复

SCORE_MASK 破坏 double 位布局产生 NaN，已删除 MASK

致命级

RegionLoadMonitor 索引溢出

writeIndex 溢出导致负索引 AIOOBE，改为 Math.floorMod

致命级

VillagerOptimizer 时间混淆

游戏世界时间与系统时间混存导致 elapsed 计算完全错误，已修正

致命级

RegionBalancer OOM

taskRecords 无限增长导致 OOM，已添加 TTL 清理

资源泄漏

MmapRegionStorage 句柄泄漏

旧条目失效时未关闭文件句柄，已添加 close() 调用

资源泄漏

ChunkDeltaCompressor native 泄漏

Deflater 的 end() 不在 finally 中，native 内存泄漏已修复

资源泄漏

volatile 无 CAS 竞态

MiliChunkSystem/SmartRegionManager 的 volatile boolean initialized 改为 AtomicBoolean.compareAndSet

并发竞态

Bukkit 集合 CME

ChunkRegionBridge 异步线程遍历 Bukkit 集合 CME，改为先快照 ArrayList

并发竞态

ConcurrentTable NPE

全部 .equals() 模式替换为 Objects.equals() 防 NPE

并发竞态

API 扩展

在 Folia/Paper API 之上提供更多能力，让插件开发更灵活，同时，我们弱检查mili-supported: true因为我们引入了一个区域多个线程，这和folia并不相同

API	说明	关键类/事件
Tick Regions API	查询/操作 tick 区域的 API	`ThreadedRegion` `RegionStats`
ReplayMod 摄影师	创建 ReplayMod 摄影师实体进行录像	`Photographer` `PhotographerManager`
Bytebuf API	面向插件的自定义数据包读写 API	`Bytebuf`
实体传送异步事件	异步实体传送与传送门事件	`EntityTeleportAsyncEvent` `PreEntityPortalEvent` `PostEntityPortalEvent`
Waypoint API	实体路径点追踪与恢复 API	`Waypoint`
ThreadedRegionizer	获取全局 ThreadedRegionizer 实例的 API	`ThreadedRegionizer`

快速开始

从源码构建 LMili 服务端核心

构建步骤

Gradle 依赖

Maven 依赖

环境要求：JDK 25+（Mili 26.2 分支需要 Java 25，不是 JDK 21）| Git 2.x（Windows 需启用长路径支持）

# 1. 克隆仓库
git clone https://github.com/xucy10/Mili.git
cd Mili

# 2. Windows 需启用长路径
git config --global core.longpaths true

# 3. 应用补丁（首次构建必须执行）
./gradlew applyAllPatches --no-configuration-cache --no-build-cache

# 4. 注入 Kotlin 支持
python scripts/inject_kotlin.py

# 5. 构建 Paperclip JAR
./gradlew :mili-server:createPaperclipJar

构建产物：mili-server/build/libs/mili-26.2-paperclip.jar — 可直接运行的 Paperclip JAR

repositories {
    maven {
        url = "https://repo.menthamc.org/repository/maven-public/"
    }
}

dependencies {
    compileOnly("fun.bm.mili:mili-api:26.2-R0.1-SNAPSHOT")
}

<repositories>
  <repository>
    <id>menthamc</id>
    <url>https://repo.menthamc.org/repository/maven-public/</url>
  </repository>
</repositories>

<dependencies>
  <dependency>
    <groupId>fun.bm.mili</groupId>
    <artifactId>lmili-api</artifactId>
    <version>26.2-R0.1-SNAPSHOT</version>
    <scope>provided</scope>
  </dependency>
</dependencies>

项目结构

模块化设计，职责清晰分离

LMili/
├── leaves-api/                  # Leaves API 模块
│   └── src/main/java/         #   事件 API、Photographer、Bytebuf
├── lmili-server/               # LMili 服务端核心
│   ├── minecraft-patches/     #   97 个特征补丁（features/）
│   ├── paper-patches/         #   Paper API/Server 层补丁
│   └── src/main/
│       └── java/fun/bm/mili/  #   Java 源码
│           ├── bridge/        #     区块-区域桥接
│           ├── chunk/         #     区块系统
│           ├── command/       #     命令系统
│           ├── config/        #     配置模块（TOML，纯 Java 实现）
│           ├── metrics/       #     bStats 统计
│           ├── portal/        #     传送门管理
│           ├── utils/         #     工具类（区域调度、网络优化、内存管理等）
│           └── villager/      #     村民优化器
├── lmili-api/                 # LMili 附加 API 源（真正实现新调度器和对外api的地方）
├── folia-server/              # Folia 子模块（上游，不直接修改）
├── paper-server/              # Paper 服务器（补丁应用目标）
├── paper-api/                 # Paper API（补丁应用目标）
├── docs/                      # 文档
├── build.gradle.kts           # 根构建脚本
└── gradle.properties          # 版本与上游 ref 配置

配置系统

TOML 配置文件（纯 Java 解析实现），覆盖功能开关、实验功能、修复与优化

function

游戏机制与实用功能

游戏内行为开关与实用工具

LanguageConfig, TpsBarConfig, RegionBarConfig

experiment

实验性功能

实验性性能/并发功能，建议测试环境验证

RegionBalancerConfig, CrossDimensionTeleportQueueConfig

optimizations

性能优化

通用性能优化开关

NetworkOptimizerConfig, MmapRegionStorageConfig, VillagerOptimizerConfig

fixes

崩溃/行为修复

针对崩溃与异常行为的修复开关

PortalLinkFixConfig, CollisionBehaviorConfig

misc

杂项

自动更新、统计等杂项配置

AutoUpdateConfig, BStatsConfig, ServerModNameConfig

客户端协议支持

兼容主流 Minecraft 客户端 Mod 的服务端协议

Carpet

TPS/mobcaps/counter HUD、规则同步

TISCM

MSPT 广播、握手

XaeroMap

Xaero 地图通道支持

Jade

Jade 服务端数据提供

Syncmatica

Litematic 同步

Servux

Servux 客户端服务

REI

Roughly Enough Items 协议

BBOR

Bounding Box Outline Reloaded

AppleSkin

饥饿/饱和度同步

Alt Block Placement

Accurate/Carpet/Litematica 放置协议

LMili（米粒）

继承链

核心特性

Folia 稳定性修复

Bug 修复

通用性能优化

API 扩展

线程安全加固

API 扩展

快速开始

项目结构

配置系统

游戏机制与实用功能

实验性功能

性能优化

崩溃/行为修复

杂项

客户端协议支持

相关链接

LMili GitHub

Folia

Paper

Maven 仓库

贡献指南

项目 Wiki