Marker 与 Gate 文件

基本信息

属性 值
实现类 net.sxmaa.headlessnh.IntegrationTestController
写入目录 headlessnh.markerdir，未设置时回落到 Minecraft.mcDataDir
轮询间隔 250 ms（GATE_POLL_INTERVAL_MILLIS）
配套工具 无（由外部 CI 编排器读写这些文件）

HeadlessNH 与外部 CI 之间唯一的通信手段就是磁盘上的文件，没有任何 socket / RCON / 控制台命令。

Marker 文件（进度信号）

流程每到一个关键阶段就 createNewFile() 写出一个标记文件，编排器监视其出现以判断进度。

常量 默认文件名 含义
MARKER_MAIN_MENU .mainmenu.headlessnh 客户端启动完成、主菜单已到达
MARKER_SERVER_LOADED .serverloaded.headlessnh 多人服务器世界已进入并稳定
MARKER_WORLD_LOADED .worldloaded.headlessnh 单人世界已进入并稳定

文件名可用 headlessnh.marker.mainmenu / .serverloaded / .worldloaded 逐个覆盖。

[!WARNING] writeMarker 在文件已存在时不会复用，而是直接抛 RuntimeException("Failed to create HeadlessNH marker ...")。这意味着同一份数据目录跑第二次集成测试时会因为 .mainmenu.headlessnh 已存在而失败，除非编排器在每轮前清理，或改用 headlessnh.marker.* 指向新名字。

Gate 文件（阶段闸门）

Gate 是反向信号：设置后，流程在写出该阶段 marker 之后会阻塞等待对应文件出现（每 250 ms 轮询一次），编排器可以据此把测试拆成一步步手动放行。

系统属性 对应阶段
headlessnh.gate.mainmenu 主菜单 marker 之后
headlessnh.gate.serverloaded 服务器加载 marker 之后
headlessnh.gate.worldloaded 单人世界加载 marker 之后

Gate 文件同样解析到 marker 目录下，文件名直接取属性值本身（没有附加后缀）。属性未设置或为空串（emptyToNull）时该阶段不设闸门，立即继续。

超时由 headlessnh.gate.timeout（Long.getLong(..., 0L)）控制：

  • 0 或负数 → deadline = Long.MAX_VALUE，无限等待
  • 正数 → 到期调用 fail(...)，在主线程抛 Failure

等待期间会在日志打印 Waiting for gate file {}，放行后打印 Gate file appeared, proceeding。

相关条目