RegionVisualer 是一个面向 Folia 的只读 tick-region 性能监控工具：

• server-plugin：安装 ByteBuddy hook、采样 Folia 原生 tick report、通过 raw TCP 发布遥测。
• client：Java Dear ImGui 桌面端，显示加载区块/region 拓扑、utilization、MSPT、TPS 和实体计数。
• protocol：protobuf 消息、CRC32C framing、Zstd 压缩及严格输入校验。
• instrumentation-bridge：由 system classloader 加载的无依赖 hook bridge。

首版没有认证和加密，因此严格为只读：

• 命令输入、发送按钮和停止服务端按钮在客户端中可见但禁用。
• 服务端收到 CONTROL_COMMAND / CONTROL_STOP 时只返回 ERROR_CODE_CONTROL_DISABLED。
• 服务端默认只监听 127.0.0.1:9274。远程使用请通过管理员维护的 SSH/VPN 隧道；不要把端口直接暴露到网络。

CRC32C 用于检测传输损坏，不提供认证能力。

当前 compatibility profile 锁定：

• Java 25
• Minecraft/Folia 26.2
• Shiroha 26.2 dev bundle
• Paperweight userdev 2.0.0-beta.21

NMS 发生任何变化都应新建并验证 profile，不能假定兼容。

在 E:\Projects\neo\Shiroha 中：

.\gradlew.bat :shiroha-api:publishToMavenLocal -PpublishDevBundle
.\gradlew.bat :shiroha-server:publishDevBundlePublicationToMavenLocal -PpublishDevBundle

这会发布：

io.nanachiyo0721:shiroha-api:26.2.local-SNAPSHOT
io.nanachiyo0721:dev-bundle:26.2.local-SNAPSHOT

若使用另一个明确验证过的 26.2 bundle，可通过 -PfoliaDevBundle=<group:artifact:version> 覆盖。

.\gradlew.bat clean test verifyNmsCompatibility build

主要产物：

• 插件：server-plugin/build/libs/
• 客户端 fat JAR：client/build/libs/client-*-all.jar

把 shaded 插件 JAR 放入 plugins/。在普通完整 Java 25 JDK 上无需额外 JVM 参数：Byte Buddy 会启动一个短生命周期的外部 helper JVM，attach 回服务端进程。

首次动态加载 agent 时 Java 可能在标准错误流打印 JEP 451 警告；这是预期行为。可选的 -XX:+EnableDynamicAgentLoading 只用于显式允许并抑制该警告，不是默认运行的必需参数。

以下环境无法进行纯插件动态注入：裁剪掉 jdk.attach 的 jlink/JRE 风格 runtime、-XX:+DisableAttachMechanism、-XX:-EnableDynamicAgentLoading、禁止创建子进程、不可写/不可执行临时目录、容器 PID/UID 或系统安全软件阻止 attach。此时只能改用启动期 -javaagent 或 Shiroha 源码 patch。

若 attach、retransform、brand、MC 版本或 NMS 结构检查失败，插件会 fail closed：不绑定 TCP 端口，不发布部分/错误遥测。

不支持 /reload 或热替换插件；修改/升级后完整重启服务端。

服务端配置首次运行生成于 plugins/RegionVisualer/config.yml。

java --enable-native-access=ALL-UNNAMED -jar client/build/libs/client-0.1.0-SNAPSHOT-all.jar

默认连接 127.0.0.1:9274。地图支持：

• 世界选择
• 滚轮按鼠标位置缩放
• 中键拖拽平移
• hover 性能提示
• 点击选择 region；点击空白取消
• 近距离按真实加载 chunk run 绘制，远距离按包围盒 LOD

右侧在选中时显示 region 详情；未选中时显示 live region 聚合与独立 GlobalRegion 状态。

• ByteBuddy advice 只发出有界 dirty/lifecycle 信号，不枚举区块、不压缩、不做网络 I/O。
• sampler 默认每秒获取 Folia 原生 getTickReport5s，并构建拓扑快照。
• TCP 使用独立 selector 线程和有界输出队列，慢客户端会被断开，绝不阻塞 tick 线程。
• render 线程独占 ImGui/OpenGL；网络只把不可变事件交给 UI。

.\gradlew.bat :protocol:test :instrumentation-bridge:test :client:test
.\gradlew.bat :server-plugin:compileJava verifyNmsCompatibility

协议测试覆盖：分片/粘包、CRC 损坏、未知类型/flags、长度上限、Zstd 截断及解压长度不符、protobuf 语义错误。客户端测试覆盖历史容量、聚合及 topology 更新后的选择行为。