生成标记检查器

生成标记检查器

用于Hytale生成标记的测试台,包含调试命令和测试标记。

实用

MarkerTest — Hytale 生成标记测试台

MarkerTest 是一个小型的 Hytale 服务器插件,用于在实践中学习 NPC 生成标记(spawn markers) 的工作原理。它附带五个测试标记,每个测试标记分别检验一项标记设置,并提供一个 /markertest 命令,用于显示每个标记的当前状态:它的 NPC 是否存活、距离重生还有多久、是否已被停用,以及手动触发失败的原因。

它旨在帮助模组作者将 NPC 生成从世界/环境生成规则迁移到生成标记,而生成标记在官方文档中只被部分覆盖。

  • Hytale 服务器:0.7.5 – 0.7.x(基于 0.7.5 构建,也可针对 0.7.6 编译)
  • Java:25
  • 许可证:MIT

这是一个非官方社区项目,与 Hypixel Studios 无关。


目录

  1. 模组内容
  2. 安装与使用
  3. 命令
  4. 测试标记
  5. 测试流程与结果
  6. 生成标记的工作原理
  7. 从源码构建
  8. 项目结构
  9. 已知不足
  10. 致谢

模组内容

部分 文件 用途
插件入口 MarkerTestPlugin.java 注册命令和监视系统
命令 MarkerTestCommand.java /markertest list, near, trigger, debug, flag, skiptime
标记检查 MarkerInfo.java 查找玩家周围的标记并格式化其状态
监视器 MarkerWatchSystem.java 每秒报告一次标记状态的每次变化
测试标记 src/main/resources/Server/NPC/Spawn/Markers/MT_*.json 五个标记,每个演示一个特性

该模组同时作为资源包(IncludesAssetPack: true)工作,因此测试标记会随插件一起加载。


安装与使用

  1. 从最新发布下载 MarkerTest-<version>.jar(或自行构建),并将其放入 %APPDATA%\Hytale\UserData\Mods。
  2. 创建一个新的测试世界,并在该世界的模组列表中启用 MarkerTest。请勿在你重视的世界中进行测试。
  3. 检查世界开关:
    /markertest flag
    
    IsSpawnMarkersEnabled 和 IsSpawningNPC 都必须为 true(参见世界开关)。如果不是:
    /world settings spawnmarkers set true
    /world settings spawningnpc set true
    
  4. 开启监视器:
    /markertest debug on
    
  5. 使用内置命令将测试标记放置为相隔几个方块:
    /spawning markers add MT_Fast_Respawn
    /spawning markers add MT_Weighted_Nothing
    /spawning markers add MT_Exclusion
    /spawning markers add MT_Manual
    /spawning markers add MT_Skeleton_GameTime
    
    标记在创造模式下可见,在冒险模式下对玩家隐藏。
  6. 观察聊天窗口(以及服务器日志,行以 [MarkerTest] 开头)。

如果标记已放置但完全没有生成任何东西,即使在检查开关后也是如此,请重启世界一次。在我们的第一次会话中,没有标记生成,甚至世界生成的标记也没有生成;重启后一切正常。我们未找到确切原因。


命令

所有命令都是 /markertest 下的玩家命令。

命令 作用
/markertest flag 显示当前世界的 IsSpawnMarkersEnabled 和 IsSpawningNPC,以及修复每个开关的命令
/markertest list [--radius=64] 列出你周围最多 15 个标记,最近的排在前面,并显示其状态
/markertest near [--radius=16] 仅显示最近的标记
/markertest trigger [--radius=16] 触发最近的 ManualTrigger 标记,并报告成功 / 失败以及生成了多少 NPC
/markertest debug on [filter] 报告 ID 以 filter 开头的标记的每次状态变化(默认为 MT_;使用 all 表示所有标记)
/markertest debug off 停止报告
/markertest skiptime <minutes> 将世界游戏时间向前推进,以便无需等待即可测试游戏时间重生

解读状态行

MT_Fast_Respawn @ -1029.5 123.0 361.6 (6.7m) spawnCount=1 alive=1/1 manual=false deactivateIn=0.0
despawnStarted=false storedFlock=true suppressedBy=0 spawnAfter=null exclusion=0.0 deactDist=40.0 realtime=true
字段 含义
spawnCount 标记认为已生成且尚未死亡的 NPC 数量
alive=a/b 标记持有的 b 个 NPC 引用中,a 个可解析为存活实体
manual 标记仅在触发时生成
deactivateIn 标记停用前剩余的秒数(范围内无玩家)
despawnStarted 标记因附近无玩家而正在存储其 NPC
storedFlock 标记有一个已存储的群体对象(所有标记上都存在,因此仅为 true 意义不大)
suppressedBy 当前阻止此标记的生成抑制器数量
spawnAfter 待处理的游戏时间重生:in 0h37m(game)、due(...) 或 null
exclusion、deactDist、realtime 来自标记资源的值

测试标记

所有测试标记都使用基础游戏中存在的 NPC 角色:Archaeopteryx(一种小型被动生物)和 Skeleton_Burnt_Soldier_Wander。

标记 设置 观察内容
MT_Fast_Respawn RealtimeRespawn: true、RealtimeRespawnTime: 10 杀死 NPC 后,10 现实秒后出现一个新的
MT_Weighted_Nothing 25% Archaeopteryx,75% 无 Name 的条目 大多数时候不会生成任何东西
MT_Exclusion ExclusionRadius: 8 当玩家距离小于 8 个方块时不生成
MT_Manual ManualTrigger: true 仅在 /markertest trigger 时生成
MT_Skeleton_GameTime SpawnAfterGameTime: "PT1H" 死亡后,在一个游戏小时后重生(使用 /markertest skiptime 61 跳过等待)

示例(MT_Fast_Respawn.json):

{
  "Model": "NPC_Spawn_Marker",
  "NPCs": [
    { "Name": "Archaeopteryx", "Weight": 100, "RealtimeRespawnTime": 10 }
  ],
  "RealtimeRespawn": true,
  "ExclusionRadius": 0,
  "DeactivationDistance": 40,
  "DeactivationTime": 5
}

测试流程与结果

在 Hytale 0.7.5 的创造模式测试世界中,与一个大型模组包一起测试。

检查项 结果
MT_Manual + /markertest trigger ✅ NPC 生成。在该 NPC 存活时再次触发会失败。即使自动标记不起作用也能工作
MT_Fast_Respawn ✅ 杀死后,下一个 NPC 恰好在 10 秒后出现(日志中 14:24:38 → 14:24:48)
MT_Weighted_Nothing ✅ 仅有时生成
MT_Exclusion ✅ 等到玩家离开后才生成
停用(走到 > 40 个方块外再返回) ✅ 标记设置 despawnStarted=true,存储其 NPC,并在玩家返回时恢复它们
MT_Skeleton_GameTime ✅ 死亡时,标记记录了游戏时间 spawnAfter。未验证一个游戏小时后的实际重生
/spawning markers add ✅ 在玩家的位置和旋转处放置一个标记

生成标记的工作原理

本节结合了官方文档(生成标记、SpawnMarkerEntity API)与通过阅读服务器公共 API 和测试所得的内容。标记为 (代码) 的项目不在文档中;它们来自 0.7.5/0.7.6 的服务器类,可能会发生变化。

标记资源

标记是位于 Server/NPC/Spawn/Markers/<Id>.json 的 JSON 资源。

字段 默认值 含义
Model 服务器默认值 在创造模式下为标记显示的模型(NPC_Spawn_Marker)
NPCs — 生成条目的加权列表
NPCs[].Name — 要生成的 NPC 角色。没有 Name 的条目不会生成任何东西,从而提供了“空”生成的机会
NPCs[].Weight 0 在列表中的相对权重
NPCs[].RealtimeRespawnTime 0 以现实秒为单位的重生延迟(与 RealtimeRespawn: true 一起使用)
NPCs[].SpawnAfterGameTime — 以游戏时间为单位的重生延迟,ISO-8601 时长,如 PT1H 或 P1D(与 RealtimeRespawn: false 一起使用)
NPCs[].Flock — 在 NPC 周围生成的可选群体
RealtimeRespawn false 使用两种重生延迟中的哪一种
ManualTrigger false 仅在触发时生成
ExclusionRadius 0 当冒险模式玩家在此半径内时不生成
DeactivationDistance 40 此距离内没有玩家时,标记停用
DeactivationTime 5 停用发生前的秒数
MaxDropHeight 2 生成地面 NPC 时高出地面的最大高度
ValidatePosition、ValidateBelowPosition true 拒绝位于方块内 / 空地上方的标记位置
RequireFitAtMarkerHeight false NPC 必须能在标记自身高度处容纳
MaxHorizontalSpawnOffset 0 沿标记朝向搜索生成点的距离
SpawnPositionSearch Line Line 或 Range
BlockOverlapHeightCompensation 1 卡在方块中的标记可以向上校正的距离

加权条目在每次生成时都会重新滚动 (代码):spawnNPC 每次使用随机数从加权列表中选择。

世界开关

(代码) 标记的自动生成仅在以下所有条件均为真时发生:

  • 世界设置 IsSpawningNPC 为 true(/world settings spawningnpc set true);
  • 世界设置 IsSpawnMarkersEnabled 为 true(/world settings spawnmarkers set true,或 /spawning markers enable);
  • 标记不是 ManualTrigger;
  • 当前没有生成抑制器抑制该标记。

手动触发忽略两个世界设置。这就是为什么在我们的第一次会话中 MT_Manual 能工作而其他都不能。

单个标记的生命周期

(代码),从 SpawnMarkerSystems.Ticking 简化而来,它对每个标记每个 tick 运行一次:

  1. 范围内有玩家吗? 标记在 DeactivationDistance 内查找玩家。
    • 有玩家且 NPC 已存储 → 已存储的 NPC 被放回世界。
    • 无玩家 → 在 DeactivationTime 秒后,标记存储其 NPC 并将它们从世界中移除(despawnStarted)。如果 NPC 的模型有 Despawn 动画,则首先播放它。已死亡的 NPC 或处于忙碌状态的 NPC 会推迟停用。
  2. 丢失 NPC。 如果标记在一段时间内找不到它生成的 NPC,它会放弃该 NPC(“Marker lost spawned NPC”)并变得可以再次生成。失去标记的 NPC 会消失(服务器日志中的“NPCEntity despawning due to lost marker”)。
  3. 重生。 如果世界开关允许且标记不是手动的:
    • RealtimeRespawn: true → 运行现实时间倒计时(RealtimeRespawnTime),然后生成一个新 NPC;
    • RealtimeRespawn: false → 标记等待世界游戏时间超过 spawnAfter,该值在 NPC 死亡时使用 SpawnAfterGameTime 作为延迟设置。
  4. 生成。 选择一个加权条目,在标记附近搜索位置,并创建 NPC(及其群体)。生成失败有原因 (代码):INVALID_ROLE、NONEXISTENT_ROLE、FAILED_ROLE_VALIDATION、NO_ROOM、NO_VALID_SPAWN_POSITION、NO_MOVEMENT_MODES、MOVEMENT_MODE_REJECTED、TOO_HIGH、INVALID_SPAWN_INPUT。

一个标记保持一个存活 NPC(加上其群体)。触发其 NPC 已存活的手动标记会失败。

放置标记的方法

方法 方式 备注
命令 (代码) /spawning markers add <MarkerId> [--flip](别名 /sp) 在玩家的位置和旋转处创建标记实体。--flip 绕垂直轴翻转其旋转。其他子命令:enable、disable、autoremoveinvalid、debuginvalid
方块 (代码) 带有 SpawnMarkerBlock 组件的方块类型 该方块创建并保持一个标记实体,见下文。这是将标记放入建筑和预制件的方法
世界生成 / 预制件 保存在生成结构中的标记实体 服务器有“从预制件或世界生成添加”的标记系统;原版世界包含许多此类标记(哥布林、骷髅)
伴随方块生成器 Server/NPC/Spawn/CompanionBlockSpawners/*.json 一个生成器方块加上所需的附近方块使标记的 NPC 保持存活;破坏该设置会使其消失

标记方块(代码)。 方块组件在方块类型的 BlockEntity.Components 下声明。注册为 SpawnMarkerBlock 的组件具有以下结构:

"BlockEntity": {
  "Components": {
    "SpawnMarkerBlock": {
      "Config": {
        "SpawnMarker": "MT_Fast_Respawn",
        "MarkerOffset": { "X": 0, "Y": 1, "Z": 0 }
      }
    }
  }
}

SpawnMarker 是要使用的标记资源;MarkerOffset 是标记实体相对于方块创建的位置。此结构取自服务器的编解码器。尚未在游戏中测试。

触发交互(代码)。 交互类型 TriggerSpawnMarkers 触发附近的 ManualTrigger 标记:

字段 含义
MarkerType 要触发哪种手动标记类型(如果省略则为所有手动标记)
Range 搜索范围
Count 要触发的最大标记数

附加到方块或物品交互(例如打开容器),这自然适用于“玩家打开容器时出现 NPC”。尚未在游戏中测试。

注意事项

  • 如果没有任何生成,首先检查 /markertest flag。如果两个开关都开启,重启世界。
  • 高于地面超过 MaxDropHeight 的标记不会生成地面 NPC。
  • 每个条目都需要与 RealtimeRespawn 匹配的延迟。
  • 不存在的角色名称会使生成失败并显示 NONEXISTENT_ROLE。
  • 由标记生成的 NPC 会像任何其他 NPC 一样缩放其模型。缩放比例不为 1 的模型与非零粒子 PositionOffset 结合,可能会使偏移量增长直到溢出,然后服务器会以 PositionOffset ... is not finite 断开玩家连接。标记不会改变这一点,因此请将缩放模型上的粒子偏移保持为零。

从源码构建

要求:JDK 25。Gradle 作为包装器包含在内。Hytale 服务器 API 由 Gradle 插件自动下载;无需复制游戏文件。

./gradlew build          # Windows: gradlew.bat build

jar 输出到 build/libs/MarkerTest-<version>.jar。

目标游戏版本在 gradle.properties 中设置(hytale_version、manifestServerVersion)。模板的 ./gradlew runServer 任务可以启动带有插件的本地服务器(首次启动时可能会要求你授权服务器)。

发布版本

发布由 GitHub Actions(.github/workflows/release.yml)构建。在 gradle.properties 中设置 version,提交,然后推送具有相同版本的标签:

git tag v0.2.0
git push origin v0.2.0

工作流构建项目并为该标签创建 GitHub 发布,附带 MarkerTest-<version>.jar。如果标签与 version 不匹配,则会报错停止。


项目结构

.
├── build.gradle.kts            Gradle 构建(AzureDoom hytale-tools 插件)
├── settings.gradle.kts
├── gradle.properties           模组 ID、版本、目标 Hytale 版本
├── src/main/java/dev/markertest/
│   ├── MarkerTestPlugin.java
│   ├── MarkerTestCommand.java
│   ├── MarkerInfo.java
│   └── MarkerWatchSystem.java
├── src/main/resources/
│   ├── manifest.json           由构建从 gradle.properties 生成/更新
│   └── Server/NPC/Spawn/Markers/MT_*.json
├── .github/workflows/gradle.yml  CI:检查项目是否能编译
├── .github/workflows/release.yml 构建 jar 并为 v* 标签发布版本
└── LICENSE

已知不足

  • 第一次会话中为何没有标记生成尚不清楚;重启世界解决了问题。
  • MT_Skeleton_GameTime 的游戏时间重生未被等待验证。
  • SpawnMarkerBlock 组件和 TriggerSpawnMarkers 交互仅根据服务器代码描述。为它们创建测试方块和测试物品是显而易见的下一步。
  • 未检查标记实体如何存储在预制件文件中。
  • 标记为 (代码) 的标记内部结构不是官方文档,可能会在游戏版本之间发生变化。

致谢