GlymeraMobCustomizer

🐉 GlymeraMobCustomizer v1.2.0

使用任意外观、任意 AI，创建完全自定义的生物——生命值、体型、速度和无敌状态均可调整。将龙的外观与狼的行为混合？一切皆有可能！

当前版本仅适用于 Hytale stable 5！ 不要错过我的其他精彩项目——请访问 GlymeraCraft 的个人资料 Discord: https://discord.gg/s5NRFWfxgy

◆ 什么是 GlymeraMobCustomizer？ GlymeraMobCustomizer 是用于 Hytale 服务器的生物创建插件。它允许服务器管理员在简单的 JSON 配置文件中定义自定义生物——从数百个可用选项中独立选择外观和 AI。想要一个拥有鹰 AI 的小型喷火巨龙？一个像 Trork 战士一样战斗的巨型不朽奶牛？一个速度提升的老鼠？只需配置它，用命令生成，它就会出现在你的世界中。

生物原生支持服务器重启后保留。Hytale 会保存所有修改后的属性。无需 Tick 操作，无需自定义实体系统——仅使用 Hytale 内置的 NPC 框架，并叠加你的自定义属性。

◆ 工作原理 该插件提供了一个 JSON 配置文件，你可以在其中定义命名的生物条目。每个条目指定六个属性：外观、AI 行为、生命值、体型、速度和无敌状态。当你通过 /cm spawn <名称> 生成生物时，插件会：

1. 从配置中查找生物定义
2. 使用 Hytale 的原生 NPCPlugin 以指定的 AI 角色生成 NPC
3. 如果外观模型与 AI 角色不同，则覆盖外观模型
4. 通过反射机制应用体型、生命值、速度和无敌状态
5. 生物会出现在玩家前方 3 格处，面向玩家的视角方向

所有修改在生成时立即应用。Hytale 会自动保留具有修改属性的实体。

▸ 核心概念 外观和 AI 相互独立 - appearance 字段控制视觉模型（生物的外观）。ai 字段控制行为（生物如何行动、移动和攻击）。任何外观都可以与任何 AI 角色组合。像骷髅侦察兵一样战斗的奶牛？没问题。

基于配置的设计 - 所有生物都在单个 JSON 文件中定义。无需编码。编辑配置，使用 /cm reload 重新加载，然后生成你的作品。

模板槽位 - 默认配置包含 10 个预构建的示例生物和 50 个准备填写的空模板槽位。

参考文件自动生成 - 每次服务器启动时，插件都会直接从运行中的服务器生成一个 read this!.txt 文件，列出所有可用的外观模型和 AI 角色。无需猜测哪些值是有效的。

◆ 生物属性 配置中的每个自定义生物条目都有六个可配置属性：

▸ appearance 生物的视觉模型。决定生物在屏幕上的外观——它的网格、纹理和动画。插件在启动时从 Hytale 的 ModelAsset 注册表中读取所有可用模型，并将其列在 read this!.txt 中。示例："Horse", "Dragon_Fire", "Cow", "Skeleton_Scout", "Kweebec_Sapling", "Spider", "Golem_Crystal_Earth"。

▸ ai 生物的行为/AI 角色。决定生物的行为方式——它的移动模式、攻击行为、攻击性、空闲行为和战斗风格。插件在启动时从 Hytale 的 NPCPlugin 中读取所有可用角色。抽象模板角色（以 Template_ 为前缀）会单独列出，且无法生成。示例："Trork_Warrior", "Hawk", "Wolf_Black", "Horse", "Mouse"。

▸ health 最大生命值。范围：1-10000。默认值：100。生物生成时拥有等于此值的满生命值。当前和最大生命值均通过 EntityStatMap 的反射机制设置。

▸ scale 尺寸倍数。范围：0.1-10.0。默认值：1.0（正常尺寸）。2.0 的值使生物体型变为两倍，0.5 使其变为一半大小。通过反射应用于 Model 的 scale 字段，并带有网络同步标志，以确保所有玩家看到正确的尺寸。

▸ speed 移动速度。范围：0.1-50.0。默认值：-1.0（使用 AI 角色的默认速度）。正常行走速度约为 3.0，马匹约为 10.0。通过反射应用于 MotionControllerBase 的 maxHorizontalSpeed 字段。

▸ immortal 无敌状态开关。默认值：false。当设置为 true 时，Invulnerable 组件会被添加到实体上，使其完全免疫所有伤害。适用于装饰性 NPC、任务给予者或永久世界居民。

◆ 命令（仅 OP） 所有命令都需要管理员权限（通过 PermissionsModule 通配符 * 权限检查）。基础命令为 /cm。

/cm spawn <名称> - 在玩家前方 3 格处生成一个自定义生物。名称是配置键（例如 battle_cow, mini_dragon）。不区分大小写。

/cm list - 列出所有已配置的自定义生物及其外观、AI、生命值、体型和无敌状态。

/cm remove <名称> - 移除最近的该类型生物。查找具有匹配 AI 角色名称的最近 NPC，并将其从世界中移除。

/cm removeall <名称> - 从所有已加载的区块中移除所有该类型的生物。遍历每个已加载区块，通过角色名称收集匹配的 NPC，然后将其移除。

/cm reload - 在不重启服务器的情况下重新加载配置文件并重新生成参考文件。新的生物定义立即可用于生成。

不带参数输入 /cm 会显示包含所有可用子命令的帮助菜单。

◆ 配置 首次启动时，配置文件会自动创建于：mods/Glymera_GlymeraMobCustomizer/config.json

配置包含一个指向参考文件的 _README 提示，后跟一个包含所有生物定义的 mobs 对象。编辑后，请停止服务器或使用 /cm reload。默认配置包含 10 个示例生物和 50 个空模板槽位：

{
  "_README": "appearance 和 ai 的所有可用值都列在文件中：read this!.txt",
  "mobs": {
    "giant_horse": {
      "appearance": "Horse",
      "ai": "Horse",
      "health": 500,
      "scale": 3.0,
      "speed": 12.0,
      "immortal": false
    },
    "battle_cow": {
      "appearance": "Cow",
      "ai": "Trork_Warrior",
      "health": 300,
      "scale": 2.0,
      "speed": 6.0,
      "immortal": false
    },
    "name_of_mob_1": {
      "appearance": "输入外观 - 请查看 read this!.txt",
      "ai": "输入 AI - 请查看 read this!.txt",
      "health": 100,
      "scale": 1.0,
      "speed": -1.0,
      "immortal": false
    }
  }
}

◆ 预构建示例生物（10 个） 默认配置附带 10 个可供立即生成的示例生物，展示了不同的组合：

名称	外观	AI	生命值	体型	速度	无敌
giant_horse	马	马	500	3.0x	12.0	否
tiny_wolf	黑狼	黑狼	50	0.3x	8.0	否
mega_trork	Trork 战士	Trork 战士	2000	5.0x	4.0	否
pet_kweebec	Kweebec 树苗	Kweebec 树苗	9999	1.0x	默认	是
battle_cow	牛	Trork 战士	300	2.0x	6.0	否
ghost_skeleton	骷髅侦察兵	骷髅侦察兵	100	1.5x	10.0	是
mini_dragon	喷火龙	鹰	5000	0.5x	默认	否
guard_golem	水晶大地魔像	水晶大地魔像	3000	2.0x	2.0	是
speed_mouse	老鼠	老鼠	10	0.5x	20.0	否
boss_spider	蜘蛛	蜘蛛	8000	8.0x	5.0	否

◆ 参考文件 (read this!.txt) 每次服务器启动时（以及执行 /cm reload 时），插件会自动在以下位置生成一个参考文件：mods/Glymera_GlymeraMobCustomizer/read this!.txt

该文件列出了 appearance 和 ai 字段的所有可用值，这些值直接从运行中服务器的资源和 NPC 注册表中读取。它分为三个部分：

配置选项 - 解释所有六个生物属性，包括有效范围和默认值。 外观 - 来自 Hytale 的 ModelAsset 注册表的所有视觉模型（437+ 个模型），按字母顺序排序。 AI 角色 - 来自 Hytale 的 NPCPlugin 的所有 NPC 行为角色，分为可生成角色（888+ 个）和抽象模板（不可生成，以 Template_ 为前缀）。

该文件在每次启动时都会重新生成，因此它始终反映当前服务器状态，包括任何添加了新模型或角色的资源包或模组。

◆ 技术细节

• 通过 NPCPlugin.spawnEntity() 生成 NPC - 使用 Hytale 的原生 NPC 框架创建实体，确保与实体系统完全兼容
• 通过 NPCEntity.setAppearance() 覆盖外观 - 仅在外观与 AI 角色不同时应用，避免不必要的操作
• 通过 Model.scale + ModelComponent 网络同步标志的反射机制调整体型 - 确保所有连接的客户端立即看到正确的尺寸
• 通过 EntityStatValue（value + max 字段）+ EntityStatMap.setStatValue() 的反射机制设置生命值 - 同时设置当前和最大生命值
• 通过 MotionControllerBase.maxHorizontalSpeed 的反射机制设置速度 - 修改 NPC 角色的活动运动控制器
• 通过 Invulnerable 组件（ECS）实现无敌 - 使用 Hytale 内置的无敌系统
• 根据玩家偏航角计算生成位置 - 使用偏航角的正弦/余弦，生物出现在玩家前方 3 格处
• 通过 world.execute() 将方块操作延迟到世界线程执行 - 所有实体修改和移除都是线程安全的
• 通过角色名称匹配移除生物 - 通过 store.forEachChunk() 遍历区块级别的 NPC 组件
• 通过 PermissionsModule 通配符 (*) 进行 OP 权限检查 - 所有命令均为管理员专用
• 反射字段在启动时缓存 - ModelComponent、MotionControllerBase 和 EntityStatValue 的字段被解析一次后重复使用

◆ 服务器日志输出 日志消息示例：

[GlymeraMobCustomizer] Config loaded: 60 custom mobs.
[GlymeraMobCustomizer] Health stat index: 3
[GlymeraMobCustomizer] Reflection fields cached successfully.
[GlymeraMobCustomizer] Reference file generated: .../read this!.txt (437 appearances, 888 roles)
[GlymeraMobCustomizer] GlymeraMobCustomizer v1.2.0 started!
[GlymeraMobCustomizer] Setup complete. 60 custom mobs configured.
[GlymeraMobCustomizer] GlymeraMobCustomizer stopped.

◆ 安装

1. 停止你的 Hytale 服务器
2. 将 GlymeraMobCustomizer-1.2.0.jar 复制到服务器的 mods/ 文件夹中
3. 启动服务器
4. 配置文件和参考文件会自动创建
5. 检查服务器日志中是否有：[GlymeraMobCustomizer] GlymeraMobCustomizer v1.2.0 started!

server/
└── mods/
    └── GlymeraMobCustomizer-1.2.0.jar

无需资源包。无依赖项。仅需一个 JAR 文件。

◆ 总结

• 完全自定义生物 - 独立定义外观、AI、生命值、体型、速度和无敌状态
• 混合搭配 - 任意视觉模型与任何 AI 行为，各有数百种选择
• 10 个预构建示例 - 开箱即用，可供生成和游玩
• 50 个模板槽位 - 准备填写的空配置条目
• 自动生成的参考文件 - 每次服务器启动时列出所有有效的外观和 AI 值
• 热重载 - 编辑配置并使用 /cm reload 应用更改，无需重启服务器
• 持久化生物 - 通过 Hytale 的实体系统原生支持服务器重启后保留
• 轻松移除 - 使用简单命令移除单个生物或全部某类型生物
• 仅 OP 命令 - 所有命令需要管理员权限
• 零依赖 - 一个 JAR 文件，无需资源包，无需外部库

◆ 支持 遇到问题或有疑问？在此处留言或访问我们的 Discord！

由 GlymeraCraft 开发

GlymeraMobCustomizer 团队