格莱梅拉工人

⛏️ GlymeraWorker ⛏️

放置一个工人箱子，放入一种方块，工人NPC就会自动为你开采并收集该种方块。

当前版本仅适用于 Hytale stable 5！ 不要错过我其他精彩的项目——请查看 GlymeraCraft 的作品集 Discord: https://discord.gg/s5NRFWfxgy

什么是 GlymeraWorker？

GlymeraWorker 为你的 Hytale 服务器添加了一个自动资源收集系统。玩家放置一个特殊的工人箱子，然后放入任意方块物品。箱子会在其上方自动生成一个工人 NPC，它会四处走动，开采匹配类型的方块，并将它们存回箱子。当箱子满了，工人会停止并等待。当有空间被释放，它会自动恢复。破坏箱子会立即移除该工人。

工人 NPC 是一个外域苦工，它会跟随放置在目标方块上方的隐形标记物。它无敌，对玩家友好，且无法被伤害。每个工人在其箱子周围的可配置半径内独立运作。

玩家最多可以同时拥有 3 个活跃的工人箱子（可配置）。当已有 3 个箱子活跃时，放置第 4 个箱子会移除该箱子，并将其返还给玩家的背包，同时显示一条错误信息。服务器重启后，工人会自动清理——不会积累幽灵 NPC。

---

如何获得工人箱子

工人箱子可以通过两种方式获得：

• 合成配方：将一个 粗制箱子（小型） 与 铁矿石 结合，即可合成一个工人箱子。可以在插件配置中启用或禁用此配方。
• 命令：使用 /give Furniture_Worker_Chest 直接获取。

---

工作原理 - 分步说明

1. 玩家通过合成或 /give 命令获得一个 Furniture_Worker_Chest。
2. 玩家将工人箱子放在地上。它看起来像一个木箱子，行为类似于一个标准容器（可以打开，存储物品）。
3. 几秒钟内，箱子扫描器检测到新箱子，并在内部注册。箱子现在处于 WAITING_FOR_ITEM 状态。
4. 玩家打开箱子并放入任意方块物品（例如 Soil_Grass、Rock_Stone、Soil_Dirt、Wood_Oak_Trunk 等）。
5. 插件读取箱子中的第一个物品，解析其方块类型，并激活箱子。
6. 一个工人 NPC（外域苦工外观）直接在箱子顶部生成。
7. 工人开始工作循环：
   • SCANNING（扫描） - 工人在其扫描半径内扫描最近的匹配目标类型的方块。只考虑 NPC 物理上可达的方块（见下方“可达性”）。
   • MOVING_TO_BLOCK（前往方块） - 一个隐形标记物实体在目标方块上方生成。工人使用寻路系统向它走去。
   • MINING（开采） - 当足够接近时（3.5 格内），工人开采该方块。方块从世界中移除，并添加到工人的内部物品栏。
   • SCANNING again（再次扫描） - 工人寻找下一个方块。重复此过程，直到工人收集了 16 个方块（可配置的存款阈值）。
   • MOVING_TO_CHEST（返回箱子） - 在箱子上方生成一个标记物，工人走回去。
   • DEPOSITING（存放） - 工人将所有收集的物品作为 ItemStack 存入箱子。
8. 循环从 SCANNING 步骤重新开始。
9. 如果箱子满了，工人进入 CHEST_FULL 状态并停止工作。每 2 秒插件检查是否有空间被释放。当有空间时，工人自动恢复。
10. 如果在扫描范围内找不到更多匹配的方块，工人进入 IDLE 状态并定期重新扫描。
11. 如果玩家破坏箱子，工人和所有活跃的标记物会立即被移除。

---

方块可达性

工人只会开采他们物理上能触及的方块。NPC 有 2 格高，因此插件会检查目标方块旁边是否存在一个有效的站立位置。如果满足以下条件，则视为方块可达：

• NPC 可以站在其旁边（北、南、东或西），且在脚部高度、头部高度或下方一格处有 2 格高的垂直净空
• NPC 可以站在其顶部（目标方块上方有 2 格空气）
• NPC 可以直接站在其下方并向上够（头顶上方有方块）

这可以防止工人瞄准那些它们永远无法实际走到的埋藏或地下方块。完全被地形包围的方块会被跳过。工人可能会盯着技术上“可见”但无法寻路到达的方块，最多 30 秒，然后将其跳过（卡死超时）。

---

功能特点

• 全自动资源收集 - 放置一个箱子，放入一个方块，剩下的交给工人。无需命令。
• 可合成的工人箱子 - 使用粗制箱子（小型）和铁矿石合成工人箱子。配方可在配置中切换。
• 智能方块检测 - 箱子中的第一个物品决定了工人要开采什么。插件会解析物品的方块类型 ID 以进行精确匹配。
• 最多 3 个同时工作的工人 - 每个玩家可以同时拥有 3 个活跃的工人箱子。此上限可配置。尝试放置第 4 个箱子会立即将其移除，返还给玩家背包，并显示一条错误信息。
• 工人生成在箱子上 - 工人总是出现在其指定箱子的正上方，无论玩家站在何处。
• 可配置工作半径 - 工人只在其箱子周围可配置的半径（默认：32 格）内开采。防止它们走得太远。
• 自动检测箱子满 - 当箱子没有空位时，工人停止。当空间被释放时，自动恢复。
• 30 秒卡死超时 - 如果工人无法在 30 秒内到达目标方块，它会跳过该方块并扫描下一个。
• 60 秒返回超时 - 如果工人无法在 60 秒内返回箱子，它会被直接传送到箱子位置。
• 存款阈值 - 工人在返回存放之前最多收集 16 个方块。此数值可配置。
• 干净的重启行为 - 服务器重启后，当第一个玩家加入时，所有旧的工人和标记物实体会被自动清理。会为现有的箱子生成全新的工人。不会积累幽灵 NPC。
• 移除箱子 = 即时清理 - 破坏工人箱子会立即移除其工人和标记物。该槽位会被释放给新箱子。
• 大箱子保护 - 插件正确处理大箱子（Chest_Large 碰撞箱）。只有带有 ItemContainerState 的主半边会被注册。另一半会被忽略，以防浪费槽位。
• 方块状态变体匹配 - 工人箱子有多个内部方块状态 ID（base、OpenWindow、CloseWindow）。扫描器会匹配所有变体，以便可靠地检测任何状态下的箱子。
• 区块感知运行 - 工人仅在其区块被加载时运作（即附近有玩家）。当所有玩家离开该区域时，工人自然暂停。当玩家返回且区块重新加载时，他们恢复工作。

---

支持的方块类型

工人可以开采任何作为可放置物品存在的方块类型。只需将相应的物品放入工人箱子即可。常见示例：

• 土壤方块 - Soil_Grass、Soil_Dirt、Soil_Sand_White、Soil_Snow、Soil_Ash、Soil_Mud、Soil_Clay、Soil_Gravel
• 岩石方块 - Rock_Stone、Rock_Basalt、Rock_Volcanic、Rock_Slate、Rock_Marble、Rock_Quartzite、Rock_Sandstone、Rock_Ice、Rock_Calcite
• 木头方块 - Wood_Oak_Trunk、Wood_Birch_Trunk、Wood_Fir_Trunk、Wood_Maple_Trunk、Wood_Redwood_Trunk 及其他所有树干类型
• 任何其他可放置方块 - 只要该物品在资源映射中有有效的方块类型 ID，工人就可以开采它

注意：作物方块（小麦、土豆等）目前不受支持，因为它们使用了生长阶段特定的方块 ID。

---

命令

此插件没有命令。所有操作都通过放置工人箱子并放入物品来完成。工人是全自动的。

工人箱子可以合成，或通过 /give Furniture_Worker_Chest 获取。

---

配置

配置文件会在首次启动时自动创建在 plugins/GlymeraWorker/config.json。所有值都可以更改，并在服务器重启后生效。

参数	默认值	描述
scanRadius	16	工人扫描目标方块的距离，以格为单位。
chestScanRadius	48	插件围绕每个在线玩家扫描以检测工人箱子的水平距离，以格为单位。
workerTickMs	2000	工人状态更新的间隔时间，以毫秒为单位。
chestScanTickMs	5000	箱子检测扫描的间隔时间，以毫秒为单位。
miningDistance	3.5	工人必须距离目标方块多近才能开采，以格为单位。
maxActiveChests	3	每个玩家可以同时拥有的最大活跃工人箱子数量。
stuckTimeoutMs	30000	工人在尝试到达目标方块时等待多长时间后放弃（30 秒）。
returnTimeoutMs	60000	工人在尝试返回箱子时等待多长时间后被直接传送（60 秒）。
depositThreshold	16	工人在返回箱子存放之前收集的方块数量。
maxWorkRadius	32	工人允许离开其箱子的最大距离，以格为单位。

---

工人 NPC 详情

属性	值
外观	外域苦工模型
生命值	1000 HP，无敌（无法被杀死）
态度	对玩家友好，对其他 NPC 中立
伤害	无法造成或承受伤害
移动	行走速度 6，可以攀爬最高 1.2 格的方块
击退	免疫
寻路	跟随隐形标记物实体。范围：100 格。
空闲行为	当没有目标时，在一个 2 格范围的圆圈内缓慢游荡

---

技术细节

• 该插件运行两个定时任务：一个工人滴答（默认每 2 秒）用于处理工人状态，一个箱子扫描滴答（默认每 5 秒）用于检测新放置或移除的箱子。
• 所有方块和实体操作通过 world.execute() 在世界线程上运行，以确保线程安全和正确的客户端同步。
• 方块移除使用 world.setBlock("Empty")，这能正确同步到连接的客户端。
• 重启时的实体清理使用 store.forEachChunk() 迭代所有加载的实体原型区块，并移除匹配工人或标记物角色索引的实体。
• 工人箱子检测会匹配所有在启动时解析出的方块状态变体 ID。
• 箱子所有权持久化保存在 chests.json（位置、所有者 UUID、目标方块）。服务器重启时，已保存的箱子会被加载，并在玩家进入该区域时重新生成工人。

---

安装

1. 停止你的 Hytale 服务器。
2. 将 GlymeraWorker.jar 复制到你服务器的 mods/ 文件夹中。
3. 启动你的服务器。
4. 一个默认配置文件将创建在 plugins/GlymeraWorker/config.json。

无需额外的依赖或资源包——所有内容都包含在单个 JAR 文件中。

---

已知限制

• 不支持作物方块 - 作物使用生长阶段特定的方块 ID（StageFinal），这与基础物品方块 ID 不同。工人将找不到成熟的作物。
• 无物品掉落 - 工人使用 setBlock("Empty") 移除方块，这不会产生物品掉落或方块破碎粒子。方块会直接添加到工人的内部物品栏，并作为 ItemStack 存放。
• 无开采进度持久化 - 活跃的开采进度（内部物品栏、当前目标）在服务器重启后会丢失。工人会从头开始它们的工作循环。箱子的所有权和位置会被持久化。
• 寻路限制 - 工人使用 Hytale 内置的 NPC 寻路系统。它们在面对复杂地形、悬崖或水域时可能会遇到困难。卡死超时（30 秒）和返回超时（60 秒）可以缓解这个问题。

---

支持

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

由 GlymeraCraft 开发

GlymeraWorker 团队