
生成标记检查器
用于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 无关。
目录
模组内容
| 部分 | 文件 | 用途 |
|---|---|---|
| 插件入口 | 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)工作,因此测试标记会随插件一起加载。
安装与使用
- 从最新发布下载
MarkerTest-<version>.jar(或自行构建),并将其放入%APPDATA%\Hytale\UserData\Mods。 - 创建一个新的测试世界,并在该世界的模组列表中启用 MarkerTest。请勿在你重视的世界中进行测试。
- 检查世界开关:
/markertest flagIsSpawnMarkersEnabled和IsSpawningNPC都必须为true(参见世界开关)。如果不是:/world settings spawnmarkers set true /world settings spawningnpc set true - 开启监视器:
/markertest debug on - 使用内置命令将测试标记放置为相隔几个方块:
标记在创造模式下可见,在冒险模式下对玩家隐藏。/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 - 观察聊天窗口(以及服务器日志,行以
[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 运行一次:
- 范围内有玩家吗? 标记在
DeactivationDistance内查找玩家。- 有玩家且 NPC 已存储 → 已存储的 NPC 被放回世界。
- 无玩家 → 在
DeactivationTime秒后,标记存储其 NPC 并将它们从世界中移除(despawnStarted)。如果 NPC 的模型有Despawn动画,则首先播放它。已死亡的 NPC 或处于忙碌状态的 NPC 会推迟停用。
- 丢失 NPC。 如果标记在一段时间内找不到它生成的 NPC,它会放弃该 NPC(“Marker lost spawned NPC”)并变得可以再次生成。失去标记的 NPC 会消失(服务器日志中的“NPCEntity despawning due to lost marker”)。
- 重生。 如果世界开关允许且标记不是手动的:
RealtimeRespawn: true→ 运行现实时间倒计时(RealtimeRespawnTime),然后生成一个新 NPC;RealtimeRespawn: false→ 标记等待世界游戏时间超过spawnAfter,该值在 NPC 死亡时使用SpawnAfterGameTime作为延迟设置。
- 生成。 选择一个加权条目,在标记附近搜索位置,并创建 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交互仅根据服务器代码描述。为它们创建测试方块和测试物品是显而易见的下一步。- 未检查标记实体如何存储在预制件文件中。
- 标记为 (代码) 的标记内部结构不是官方文档,可能会在游戏版本之间发生变化。
致谢
- 项目模板:HytaleModding 插件模板,使用 AzureDoom 的 Hytale Gradle 插件。
- 官方文档:docs.hytale.com。
- 由 densnz 制作。MIT 许可证,参见 LICENSE。
正在加载版本记录…
正在加载评论…
评论在新手盒子客户端中发表,这里同步展示。