MineColonies 非官方 Fabric 移植版

MineColonies — Minecraft 26.2 Fabric 移植版

在 Minecraft 26.2 的 Fabric 加载器上建造并管理一个殖民地。 建造者、农民、守卫、研究、任务和数百名工人 —— 这是 LDTTeam 的 MineColonies 从 NeoForge 到 Fabric 的非官方社区移植版，以一个单独 JAR 文件发布，其三个库模组已捆绑在内。 在此之上还增加了这些内容： 会驾驶船只的市民、三种具有方块级精确殖民地边界的地契权杖、真正可用的前哨站、会自己整地耕作的农民 —— 以及修复了模组中存在多年的 Bug。

 

游戏内截图 · 下载 · 新增内容 · 修复的 Bug · 其他移植版 · 安装 · 从源码构建 · 已知限制 · 问题与 Bug 报告 · 移植工具包 · 致谢 · 许可协议

---

🖼️ 游戏内截图

来自正在运行世界的未编辑画面。每张截图都保留了 F3 调试界面，以便在角落直接看到版本、加载器和实际运行的 Java 环境：Minecraft 26.2 (Fabric 26.2/fabric)、Java 25，集成服务器在 50 毫秒的 tick 预算内运行良好。

一个画面中出现了四种仅存在于 26.2 版本中的生物，且都在一个正常运作的殖民地里 —— 铜傀儡、鹦鹉螺、“干渴者”和模特。这些生物都无法在 1.21.1 中生成。

沿海岸分布的小屋。 蓝图放置，建造者完成建造，已声明的区块随后被填充。	模组中的袭击者。 一个野蛮人和他的伙伴们，是特意生成的 —— 模组自己的实体、模型和装备都正常渲染。
小屋界面。 BlockUI 窗口、模块选项卡和工人分配均正常工作。	一个硫磺方块走进了牧场。 这个生物是 26.2 新增的 —— 它不存在于 1.21.1（本移植版的起始版本）中。

---

📦 下载

构建好的模组 JAR 文件位于 dist/。 只有一个文件，无需组装其他任何东西。

dist/minecolonies-26.2-0.0.12.jar          72 MB
dist/minecolonies-26.2-0.0.12.jar.sha256   sha256sum -c 校验

该 JAR 通过 Fabric 的 Jar-in-Jar 机制将三个依赖项捆绑在内，加载器会将它们作为普通模组加载：

嵌套模组	版本
blockui	0.0.1
domum_ornamentum	26.2-1.0.0
structurize	26.2-1.0.0

⚠️ 请勿同时将 blockui、structurize 或 domum_ornamentum 作为单独文件放入 mods/ 目录。 位于 mods/ 目录中的 JAR 文件会无论版本如何都优先于嵌套的 JAR —— isRoot() 是加载器候选排序中的第一个键 —— 并且在日志中不会出现任何相关信息。症状是崩溃，其堆栈跟踪指向当前源码中不存在的一行。详情请参阅 dist/README.md。

---

✨ 本移植版的新增内容

本节中的所有内容都是相对于上游 MineColonies 新增的。每项功能都在 26.2/ 目录中有一份对应文档，记录了在游戏中实测的内容、仅从代码中读取的内容以及尚未验证的内容 —— 链接指向这些文档。命令和设置汇总于 COMMANDS.md。

🛶 市民会乘船航行

市民可以乘船穿越水域，而不是绕湖行走或完全拒绝前往。一个殖民地船只实体已集成到模组自己的寻路器中：开阔水域被定价为市民可以选择的路线，并规划穿过水域的路径。市民会从岸边登船、掌舵并自行在远岸登陆；如果在航行途中替换路径、执行 stop() 或重新计算路径，都会让市民离开船只，而不是带着乘客漂向湖心。

该功能由专属的 Boats 研究控制，对应上游的 Rails 研究 —— 需要消耗船只，需要 3 级渔夫，并且当守卫处于战斗状态时会自动关闭。空船会被丢弃，且只有被指定使用某艘船的市民才能登船。

通过实际导航器进行了测量：一条 800 格的水路路径可在 7–11 毫秒内构建完整路径（2191 个节点）；同样的路线游泳则完全无法构建路径。完整的数值，包括硬性 900 格导航器限制对长路线的影响，请参阅 26.2/PATHFINDING-DISTANCE.md。

🗺️ 三种地契权杖，以及逐方块绘制的边界

权杖	功能
土地声明	右键点击可声明一个区块及其周围八个区块。无距离限制 —— 领土可以是不相连的多块区域
土地释放	模组从未有过这个方向：归还一个区块，潜行时归还九个，正好撤销一次声明点击
边界	将边界绘制为一个 16×16 的掩码，位于区块内部。点击添加一列，潜行点击削减一列，长按可连续绘制

绘制的边界是真实的，而非装饰性的：保护机制、市民是否将一个地方视为家、袭击生成器以及建造工具的预览都遵循绘制的线条，而不是区块网格。未被任何人绘制的区块在存储或发送时不会产生额外成本。三把权杖在手持时会显示殖民地边界，并在编辑时实时重绘。

🏘️ 前哨站与飞地

有三个地方仍然测量到市政厅的距离，因此殖民地无法真正远离其中心生活。现在这三处都改为询问土地的所有者是谁 —— 小屋在任意距离处认领自己的占地（maxoutlyingchunks），前哨站自行保持区块加载（maxforcedchunks），市民会住在靠近其工作地点而不是靠近中心的位置。此外还有 /mc colony rehouse 命令，可以将已经住在错误位置的市民迁移到正确位置。 → 26.2/ENCLAVE-FEATURES.md, 26.2/ENCLAVE-BUILD.md

🌾 会自己准备土地的农民

• 地形改造。 一块因表面有石头、砾石、道路或别人的地板而无法耕作的田地方格，不再被静默跳过：它会被清理干净，铺上泥土，并在同一轮中翻耕。水域是唯一硬性例外。农民会在聊天中告知它清理了什么，并附有数量和逐方块分类统计。
• 田地标记棒。 点击稻草人，用两次点击拖出一个矩形，然后立即将田地绑定到特定的农场 —— 无需打开小屋界面，也无需猜测哪个农场认领了哪块地。
• 任意形状的田地（自由模式）：规则是总面积（默认 4096 格，服务器配置），而不是上游的“四半径之和 ≤ 20”规则，后者将所有田地限制在 11×11。

→ 26.2/FARMER-TERRAFORM.md, 26.2/FIELD-ASSIGNMENT.md

⚔️ 按需袭击

/mc raid <colony> now 立即开始袭击，而不是等待长达三分钟的慢速 tick 和篝火计时器，并且接受 size 和 strength 参数 —— 例如一行命令即可生成 40 名拥有 2.5 倍生命值、伤害和护甲的袭击者。where 命令报告袭击者实际所在位置以及当前存在的实体数量；tp 将你传送到他们旁边；stop 结束所有袭击并清除那些在事件结束后仍然存活的袭击者。按名称请求的袭击不再因为周围区域加载距离不够而失败并报 NO_SPAWN_POINT 错误。自然发生的袭击不受影响。

🧰 自由模式

/mc colony freemode <colony> on —— 殖民地无需任何物品即可运作。一个开关，随殖民地保存，默认关闭，取代了四个分散的小屋复选框。两种机制：工人当场获得其缺少的物品（材料、工具、武器、种子、药物、食物），并且请求系统可以凭空生成任何小屋设置都无法触及的物品 —— 合成配方输入、熔炉燃料、冶炼厂矿石、学校纸张、守卫武器和盔甲。已经卡在 NEEDS_ITEM 状态的工人无需重新登录即可恢复工作。 → 26.2/FREEMODE.md

🩺 诊断与管理命令

/mc colony diagnose 报告哪些内容被卡住以及持续了多久 —— 每个工人：职业、AI 状态、该状态持续的时间，以及没有 AI 的市民、没有解析器接受的请求、没有建造者的工程订单。/mc citizens fill、maxstats 和 heal 可以填充、提升和解除殖民地的停滞状态；/mc colony research completeall 和 teachRecipes 可以完成研究树并教授所有工匠所有允许学习的配方。 → COMMANDS.md

⚙️ 配置

• maxcitizenpercolony 现在接受最高 1000（默认值保持 250 不变），研究阶梯的顶层也已相应提高 —— 否则 1000 的配置会被直接限制回 500。
• stuckrescueseconds（新增，默认 60 秒，0 表示禁用）当一个工人被其任务派往某处但长时间未接近目标时，会将之传送到目的地。

---

🐞 此处修复的 Bug

这些是上游的 Bug，并且在官方 NeoForge 构建中可复现。 每个 Bug 在被认定是上游问题而非移植版本自身问题之前，都已在1.21.1/ 目录下的快照中被逐行阅读验证 —— 其中四个中的三个代码与原文逐字符相同。

现象	实际原因
“建造者拒绝建造。”	订单是否在殖民地内的检查错误地遍历占地范围，导致一个 17×17 的小屋只检查了一个区块——而且是不正确的那一个：最小值角而非小屋本身。拒绝消息随后会指出小屋的坐标，而这些坐标本身没问题。现在会检查所有的区块，消息也会明确指出未认领的那个区块
1000 格外的农场偷走了隔壁的田地	田地自动认领完全未检查距离
市民一直走向一块已更换所有者的田地	指向田地的陈旧指针，按身份进行比较
工人永远站着不动	导航器的卡住处理程序只救援那些在行走但无法前进的工人。对于目标根本没有路径的工人，没有任何动静，没有日志，没有未处理的请求 —— 通常的修复方法是拆掉小屋再重新放置。stuckrescueseconds 现在监视的是目的地而非路径

还有两个不属于上游的问题，特意与表格分开列出：

• 农民从不锄地 —— 由玩家报告，由 26.2 本身引起：原版拆分了 #minecraft:dirt 标签，将草方块、灰化土、菌丝体和泥巴移出，而可锄地表面的检查直接沿用了旧标签。每个方块都返回空值，农民走完整个螺旋路径却什么也没做。通过切换到 #minecraft:substrate_overworld 标签修复，并与真实的 1.21.1 服务器 JAR 进行比对，确保恢复的是原有的方块集合而非扩大范围。在相同的草地场景下进行了测量：之前 121 格中 0 格被翻耕，之后三分钟内翻耕了 80 格。 | | 超大堆叠物品消失 到一个空市民槽位的问 题是上游的 Bug，上游也已有修复 —— 这里从 ldtteam/minecolonies#11772 进行了移植。 |

此移植版引入后又发现的回归问题，包括三条“此 API 在 Fabric 上无对应物”的注释被证明是错误的 —— 每条都在绿色构建背后静默禁用了正常工作的游戏逻辑 —— 已记录在 26.2/AI-FIXES.md 和 26.2/OPT-FIXES.md 中。已知并有意保留的内容，包括所有者选择发布的两个发现，详见 26.2/TODO.md。

⚡ 性能

在专用服务器上的一个拥有 1000 市民的实时殖民地上进行了性能分析，并通过 Attach API 对寻路线程池进行了检测 —— 测量过程未触及模组源码的一行。随后发布了一轮基于实测的修复：服务器 tick 不再为空回调遍历每个殖民地，市民列表的防御性复制已移出 tick 路径，GUI 列表不再刷新两次，A* 寻路不再为每个节点读取世界时钟，信使查找已哈希化，请求系统日志在标志位禁用后不再构建字符串。

仍然代价高昂的部分已公布而非总结为单一数字：8 倍市民数导致 11.5 倍的 tick 耗时，一个寻路线程占用 86% 并在四分之一秒内排队任务，该线程的 8% 时间耗费在共享 Random 的 CAS 争用上，而在该规模下 tick 中最大的单一开销是原版实体寻路，而非模组的 AI。 → 26.2/AI-SCALE-AUDIT.md，以及按优先级排序的待办事项列表在 26.2/TODO.md。用于测量的世界随 testworlds/ 目录一起提供。

---

🧩 其他移植版

MineColonies 是一个由四个模组组成的栈的顶层，而其他三个模组之所以被移植，完全是为了支持它。每个模组都有自己的仓库，也都捆绑在上述 JAR 文件中。

模组	Fabric 26.2 移植版	原始版本（上游）	在栈中的角色
BlockUI	unknown-wq/BlockUI	ldtteam/BlockUI	XML 驱动的 GUI 框架，以及共享的 com.ldtteam.common 层
Domum Ornamentum	unknown-wq/Domum-Ornamentum	ldtteam/Domum-Ornamentum	用于整个殖民地建筑图纸的可替换装饰方块
Structurize	unknown-wq/Structurize	ldtteam/Structurize	建筑图纸扫描与放置 —— 每座小屋的建造方式
MineColonies	你现在所在	ldtteam/minecolonies	殖民地模拟本身

BlockUI  ──┐
           ├──> Structurize ──> MineColonies
Domum Ornamentum ──────────────┘

这三个库是直接移植 —— 没有新功能，相同的 ID，相同的行为，只是从 NeoForge 迁移到 Fabric 并升级到 Minecraft 26.2。MineColonies 则是这次迁移加上上述新增内容。 无论哪种方式，其起点所基于的游戏玩法、内容和 ID 都是上游作者的作品；此处新增的内容是在他们的作品之上构建的，并明确标注为新增。

---

🚀 安装

1. 为 Minecraft 26.2 安装 Fabric Loader 0.19.3 或更高版本。
2. 将恰好两个文件放入 mods/ 目录：

mods/
├── fabric-api-0.154.2+26.2.jar
└── minecolonies-26.2-0.0.12.jar

1. 启动游戏。在已加载模组列表中，blockui、domum_ornamentum 和 structurize 必须缩进显示在 minecolonies 下方。如果其中任何一个出现在顶层，说明 mods/ 目录中有多余的 JAR 文件 —— 请将其移除。

该模组在客户端和专用服务器上都必须安装。Java 25 是 Minecraft 26.2 本身的硬性要求。

---

🔨 从源码构建

./gradle-dist/install.sh                       # 将 Gradle 9.6.1 安装到 /opt，并安装 OpenJDK 25
export JAVA_HOME=/usr/lib/jvm/java-25-openjdk-amd64

cd 26.2
/opt/gradle-9.6.1/bin/gradle build             # JAR 文件输出到 26.2/build/libs/

三个依赖 JAR 从 26.2/gradle.properties 中的路径获取；请先从各自的仓库构建它们，或者将这些属性指向它们 dist/ 文件夹中的 JAR。./gradlew 在此处无法工作 —— 包装器无法通过代理获取 GitHub 发布附件。

有用的任务：runClient、runServer、runDatagen、validateAccessWidener。Minecraft 26.1+ 以未混淆形式发布，因此构建不携带映射行。

---

🧭 移植过程是如何完成的

这是四个移植版中规模最大的一个：2051 个源文件，约 306,000 行代码，还有三个必须先移植的模组依赖，并且需要同时跨越两条轴 —— Minecraft 1.21.1 → 26.2 以及 NeoForge → Fabric。基础是上游的 version/1.21 分支（NeoForge 21.1.80，Java 21）。

• 三波共九个代理，严格按文件而非包划分，从 9650 个编译错误开始。每个代理首先阅读的简报是 26.2/AGENT-BRIEF.md。
• 数据生成针对上一版本的输出作为基准进行了验证 —— 逐文件比较了 5039 个文件，包括按像素比较了 3481 个生成的纹理。
• 测试的是生产制品，而非开发类路径。 将构建好的 JAR 安装到一个真实的 Fabric 服务器（fabric-installer，加载器 0.19.3，旁边只有 Fabric API）并启动：Done (4.421s)!，零条 [ERROR] 行，依赖项作为嵌套模组加载。
• 数据包真正加载：跨 16 个工匠的 161 个配方，4 个分支中的 208 项研究，103 个效果，任务，以及带 NBT 键的 1761 个物品。
• AI 子系统随后被单独审计 —— core/entity/ai、pathfinding、api/entity/ai —— 审计发现了一些值得知道的事情：三条“此 API 在 Fabric 上无对应物”的注释被证明是错误的，而每一条都在绿色构建背后静默禁用了正常工作的游戏逻辑。请参阅 26.2/AI-AUDIT.md 和 26.2/AI-FIXES.md。

完整记录在 26.2/PORT-STATUS.md 中，而针对此特定代码库测得的 API 差异 —— 每个破坏性重命名及其真实命中次数 —— 在 API-CHECKLIST-26.2.md 中。 本移植版新增内容 下的所有内容都是在移植本身通过之后添加的。

---

⚠️ 已知限制

一些 NeoForge 独有的钩子在 Fabric 或原版 26.2 中没有对应物。所有被移除的内容都保留在原位，并加以注释和日志记录，而非删除。

领域	与上游的差异	影响
殖民地保护	六项权限依赖 Fabric 没有对应物的 NeoForge 事件	PLACE_BLOCKS/PLACE_HUTS、EXPLODE、TOSS_ITEM、PICKUP_ITEM、FILL_BUCKET 和 SHOOT_ARROW 未被强制执行。其他十一项，包括 BREAK_BLOCKS、ACCESS_HUTS 和 ATTACK_CITIZEN，均正常工作
手持与物品栏中的长矛	BlockEntityWithoutLevelRenderer 已从原版中移除	渲染为平面物品模型
稻草人灯笼、殖民地旗帜占位	renderSingleBlock / renderStatic 已消失	稻草人绘制时没有灯笼；手持旗帜时无预览
市民默认模型	Model#renderToBuffer 在 26.2 中是 final 方法并绘制整个根节点	默认市民会显示 1.21.1 中没有的玩家覆盖层（夹克、袖子）。模组自己的职业模型不受影响
TravellingManager 保存格式	迁移至 BlockPos.CODEC	旧世界读取该字段时会得到 BlockPos.ZERO
餐厅菜单食材	Level#getRecipeManager 在客户端不存在	仅解析 MineColonies 自有的配方以获取食材
殖民地创建粒子	原版粒子类型在 26.2 中改变了形态	播放不同的效果

每项都记录在 26.2/PORT-STATUS.md → 已禁用内容 中，包括其在游戏中的表现以及如何修复。一些损失已在其中恢复 —— 原版战利品表中的殖民地作物、补给箱、堆肥物品、地图和石板物品覆盖层，以及骑兵马匹渲染器都在第一轮之后恢复。

---

🐞 问题与 Bug 报告

发现问题了？打开一个 issue —— 请务必这样做。 Bug 报告是非常受欢迎的；这是发现剩余缺陷的方式。

• 请将此构建版的Bug 报告给这里，而不是 LDTTeam。任何由迁移到 Fabric 26.2 引起的问题，以及 本移植版新增内容 下的所有内容，都是本仓库的责任。
• 有用的信息包括：Minecraft / Fabric Loader / Fabric API 版本、完整日志（logs/latest.log 或崩溃报告）、安装的其他模组，以及复现步骤。
• 如果启动时崩溃，请先检查 mods/ 目录：多余的 blockui、structurize 或 domum_ornamentum JAR 会静默遮蔽捆绑的副本，并且生成的堆栈跟踪会具有误导性。
• 如果同样的 Bug 在上游的 NeoForge 构建中也能复现，应该报告给上游。

---

🙏 致谢

MineColonies 是 LDTTeam (Let's Dev Together) 及其众多贡献者的作品 —— 一个拥有十余年历史的模组。本仓库中的每个工人、小屋、研究分支、建筑图纸和游戏逻辑代码行都源自他们。所有功劳归于原作者：

• 上游源码： https://github.com/ldtteam/minecolonies
• 网站：minecolonies.com · CurseForge：MineColonies
• Discord：LDTTeam · 在 Patreon 上支持他们

本仓库是一个非官方、社区维护的 Fabric 加载器移植版，并在此基础上构建了 本移植版新增内容 中的功能。它与 LDTTeam 无关联、未经其认可，也得不到其支持 —— 请勿就本构建向他们发送支持请求，也不要将其中的任何问题报告为上游 Bug，除非能在他们的 NeoForge 构建上复现。

---

📄 许可协议

MineColonies 根据 GNU 通用公共许可证第 3 版（仅限该版本） 授权，本移植版也基于相同的许可证及其条款分发。许可证全文随源码提供，位于 26.2/LICENSE 和 1.21.1/LICENSE。

MineColonies — 一个适用于 Minecraft 的殖民地模拟器
Copyright (C) LDTTeam (Let's Dev Together) 及 MineColonies 贡献者
Copyright (C) unknown-wq — Fabric / Minecraft 26.2 移植版

本程序是自由软件：您可以根据自由软件基金会发布的 GNU 通用公共许可证
第 3 版的条款重新分发和/或修改它。

本程序的发布是希望它有用，但不提供任何保证；甚至没有对适销性或
特定用途适用性的暗示保证。详情请参阅 GNU 通用公共许可证。

您应该已经随本程序收到一份 GNU 通用公共许可证的副本。如果没有，
请参阅 <https://www.gnu.org/licenses/>。

模组本身的版权归 LDTTeam 及其贡献者所有；移植版是在他们的作品之上增加内容，而非替换，而 GPL 正是使这种再分发成为可能的原因。捆绑的三个库模组 —— Structurize、BlockUI 和 Domum Ornamentum —— 也属于 LDTTeam，并附带各自的许可证，随 JAR 文件一同分发。