MinersAdvantage

MinersAdvantage

概述

MinersAdvantage 是那种“我是来挖矿的，不是来填表格的”模组。

它是对 MC 1.20 时代旧版本的又一次完整重写：保留同样备受喜爱的便利性组件，消除历史遗留的痛点，并让整个模组在单人游戏和多人游戏中都更加合理。你依然能在挖矿、耕种和砍树时节省大量时间，但现在支持现代 Fabric 和 NeoForge，并且在服务器负载下行为更加干净。

如果你曾经想过“我只想要几组石头，为什么 45 分钟后我还在这里”，这个模组就是为你而生的。

功能

• Captivation：自动将附近的物品和经验拉向你（磁铁模式风格）。
• Cropination：用锄头右键收获/补种成熟作物。
• Cultivation：在有效的水源/湿润条件周围自动耕地，从而增强耕种行为。
• Excavation：在区域内挖掘相连的方块，而不是一次只挖一个方块。
• Pathanation：利用你的铲子工作流程快速铺设路径小径。
• Illumination：挖矿时放置火把，让黑暗不再伏击你。
• Lumbination：借助树干和树叶感知逻辑砍伐整棵树。
• Shaftanation：开凿可配置的条带矿井竖井。
• Substitution：根据情境和规则自动从快捷栏中挑选最佳工具。
• Veination：以可配置的控制方式挖掘完整的矿脉。
• Ventilation：挖掘垂直竖井（向上或向下），可选放置梯子。
• 服务器感知同步：游戏设置会同步，在多人游戏中可由服务端权威控制。
• 多加载器 + 多版本支持：Fabric 和 NeoForge 构建版本由同一套共享代码库生成。

工作原理

Captivation

Captivation 会监视你配置半径内的物品实体和经验球，并根据你的列表模式拉取允许的物品。你可以将其作为白名单或黑名单模式运行，它还可以应用无条件黑名单，让特定物品永远不会被吸入。

Cropination

Cropination 有两个主要的耕种便利功能：用锄头右键点击作物时收获并立即补种，以及可选的种子收获，让你选择是优化干净产出还是种子库存增长。

Cultivation

Cultivation 专注于自动耕地，并带有由湿润驱动的耕种检查，因此农田自动化只会在水源支持有效的地方发生。它的存在是为了让耕种自动化显得有意为之，而不是“莫名其妙地发怒”。

Excavation

Excavation 会在可配置的体积内破坏匹配的方块，带有每 tick 处理限制、方块变体处理和列表过滤逻辑。它支持按住/切换式使用，并在启用共享选项时与 Illumination 和 Veination 等其他系统协作。

Pathanation

Pathanation 将草/土路线转换为快速路径创建，宽度和长度可配置。它实际上就是你的“无需腕管综合征即可修路”按钮，适用于所有类型的泥土。

Illumination

Illumination 会监视局部光照，并在超过你的阈值时放置火把。你继续挖矿，它负责执行“防苦力怕拐角惊喜”预防程序。

Lumbination

Lumbination 会遍历树干和树叶空间以识别整棵树，并根据你的策略设置将其移除。你可以控制树叶处理、耐久度行为和树苗补种，使其符合你在速度与可持续性之间偏好的平衡。

Shaftanation

Shaftanation 使用可配置的宽度、高度、深度和每 tick 速度挖掘笔直的采矿走廊。你选择竖井形状预算，它执行重复性劳动。

Substitution

替换功能会评估方块/实体的上下文，并从快捷栏中切换到最合适的工具，之后还可选择切回原工具。规则配置支持根据动作匹配目标，也支持基于表达式的高级优先级设置，适合希望精细控制的玩家。

矿脉开采

Veination 将矿石开采扩展为整片矿脉挖掘，并提供距离限制和可选的计时修正。它还可以控制是否必须潜行，以及采掘后的矿石掉落物放置在哪里。

竖井

Ventilation 可以创建垂直通道，并可配置其尺寸和吞吐量。还可以选择放置梯子，让竖井成为真正实用的通道，而不只是一个好看的深坑。

多人游戏同步与强制执行

仅影响客户端视觉效果的设置仍保留在本地；多人游戏中，影响玩法的设置则会从服务器状态同步。简单来说：轮廓颜色由你决定，服务器玩法规则则由服务器决定。

安装

Fabric

1. 安装受支持的 Minecraft 版本和 Fabric Loader。
2. 为相同的游戏版本安装 Fabric API。
3. 下载适用于目标版本的 MinersAdvantage Fabric 模组文件。
4. 将模组文件放入你的 mods 文件夹。
5. 启动游戏。

NeoForge

1. 安装受支持的 Minecraft 版本和 NeoForge。
2. 下载适用于目标版本的 MinersAdvantage NeoForge 模组文件。
3. 将模组文件放入你的 mods 文件夹。
4. 启动游戏。

多人游戏说明

为确保功能一致且行为稳定，请在客户端和服务器端都安装 MinersAdvantage。

配置

MinersAdvantage 使用 TOML 格式存储配置，并分别保存在以下位置：

• 客户端文件：minersadvantage-client-config.toml
• 服务器玩法文件：minersadvantage-server-config.toml

客户端选项保留在本地。多人游戏中的玩法选项由服务器控制。

客户端配置（minersadvantage-client-config.toml）

| 选项 | 类型 | 默认值 | 描述 |
| ——————————– | ——- | ————– | ——————————————————- |
| disable_particle_effects | boolean | false | 设为 true 时禁用功能粒子效果。 |
| outline_foreground_color_argb | color | 0xFF40D9C0 | 用于前景轮廓的 ARGB 颜色。 |
| outline_see_through_color_argb | color | 0x4B40D9C0 | 用于透视轮廓的 ARGB 颜色。 |

常用玩法设置（minersadvantage-server-config.toml）

| 选项 | 类型 | 默认值 | 范围 | 描述 |
| ————————- | ——- | ——- | ———– | ————————————————————- |
| common.tps_guard | boolean | true | – | 在 TPS 较低时减少激进行为。 |
| common.gather_drops | boolean | false | – | 在适用的情况下启用掉落物收集辅助功能。 |
| common.auto_illuminate | boolean | true | – | 允许兼容功能触发照明行为。 |
| common.mine_veins | boolean | true | – | 允许兼容功能触发矿脉化行为。 |
| common.blocks_per_tick | int | 1 | 1 to 1024 | 每刻共享的处理预算基准值。 |
| common.enable_tick_delay | boolean | true | – | 启用刻延迟节奏控制。 |
| common.tick_delay | int | 5 | 0 to 200 | 启用后，各处理周期之间的延迟。 |
| common.block_radius | int | 3 | 1 to 128 | 相关功能操作共用的搜索半径。 |
| common.block_limit | int | 64 | 1 to 8192 | 单次操作可处理方块数量的共享上限。 |

Captivation（minersadvantage-server-config.toml）

| 选项 | 类型 | 默认值 | 范围 | 描述 |
| ———————————– | ———— | ——————————– | ——— | ———————————————————————- |
| captivation.enabled | boolean | true | – | 启用或禁用 Captivation。 |
| captivation.allow_in_gui | boolean | false | – | 允许在 GUI 界面打开时执行捕获行为。 |
| captivation.radius_horizontal | int | 16 | 1 to 128 | 水平拾取半径。 |
| captivation.radius_vertical | int | 16 | 1 to 128 | 垂直拾取半径。 |
| captivation.is_whitelist | boolean | false | – | 启用时，将 blacklist 视为白名单。 |
| captivation.unconditional_blacklist | boolean | false | – | 即使启用了白名单逻辑，也始终排除列出的条目。 |
| captivation.blacklist | list | [“minecraft:rotten_flesh”, “minecraft:egg”] | – | 用于白名单/黑名单筛选的物品 ID。 |

Cropination（minersadvantage-server-config.toml）

| 选项 | 类型 | 默认值 | 描述 |
| ————————- | ——- | ——- | ————————————————— |
| cropination.enabled | boolean | true | 启用或禁用 Cropination。 |
| cropination.harvest_seeds | boolean | true | 启用时，自动收获会掉落种子。 |

Cultivation（minersadvantage-server-config.toml）

| 选项 | 类型 | 默认值 | 范围 | 描述 |
| ——————————- | ——- | ——- | ——– | —————————————————– |
| cultivation.enabled | boolean | true | – | 启用或禁用栽培功能。 |
| cultivation.hydration_distance | int | 4 | 1 to 16 | 水分逻辑使用的水源距离检测值。 |

挖掘（minersadvantage-server-config.toml）

| 选项 | 类型 | 默认值 | 范围 | 描述 |
| ——————————– | ———— | ——- | ———- | ———————————————————— |
| excavation.enabled | boolean | true | – | 启用或禁用挖掘功能。 |
| excavation.width | int | 3 | 1 to 127 | 挖掘宽度。 |
| excavation.height | int | 3 | 1 to 127 | 挖掘高度。 |
| excavation.depth | int | 3 | 1 to 64 | 挖掘深度。 |
| excavation.processes_per_tick | int | 10 | 1 to 512 | 每刻处理量。 |
| excavation.toggle_mode | boolean | false | – | 设为 true 时，使用切换模式而非按住模式。 |
| excavation.ignore_block_variants | boolean | false | – | 将方块变种视为相同，以进行匹配。 |
| excavation.is_block_whitelist | boolean | false | – | 设为 true 时，将 block_blacklist 视为白名单。 |
| excavation.block_blacklist | list | [] | – | 用于黑名单/白名单筛选的方块 ID。 |

路径塑造（minersadvantage-server-config.toml）

| 选项 | 类型 | 默认值 | 范围 | 描述 |
| ———————— | ——- | ——- | ——– | ———————————————— |
| pathanation.enabled | boolean | true | – | 启用或禁用路径塑造功能。 |
| pathanation.path_length | int | 6 | 1 to 64 | 生成路径段的长度。 |
| pathanation.path_width | int | 3 | 1 to 9 | 生成路径段的宽度。 |

照明（minersadvantage-server-config.toml）

| 选项 | 类型 | 默认值 | 范围 | 描述 |
| ———————————- | ——- | ——- | ——– | ————————————————————— |
| illumination.enabled | boolean | true | – | 启用或禁用照明功能。 |
| illumination.radius_horizontal | int | 8 | 1 to 64 | 放置检查的水平搜索半径。 |
| illumination.radius_vertical | int | 4 | 1 to 64 | 放置检查的垂直搜索半径。 |
| illumination.lowest_light_level | int | 1 | 0 to 15 | 低亮度检测的放置阈值。 |
| illumination.use_block_light | boolean | true | – | 设为 true 时，使用方块亮度评估方式。 |

照明扩展（minersadvantage-server-config.toml）

| 选项 | 类型 | 默认值 | 范围 | 描述 |
| —————————————— | ———— | ——- | ———- | —————————————————————— |
| lumbination.enabled | boolean | true | – | 启用或禁用 Lumbination。 |
| lumbination.max_trunk_range | int | 32 | 1 to 128 | 树干搜索的最大范围。 |
| lumbination.max_leaf_range | int | 6 | 1 to 32 | 树叶搜索的最大范围。 |
| lumbination.processes_per_tick | int | 8 | 1 to 512 | 每刻的处理吞吐量。 |
| lumbination.chop_tree_below | boolean | true | – | 为 true 时，会继续砍伐起始点下方的方块。 |
| lumbination.destroy_leaves | boolean | true | – | 为 true 时，处理树木期间会移除树叶。 |
| lumbination.leaves_affect_durability | boolean | false | – | 为 true 时，砍伐树叶也会消耗工具耐久度。 |
| lumbination.replant_saplings | boolean | true | – | 尽可能重新种植树苗。 |
| lumbination.use_canopy_tool | boolean | true | – | 使用树冠检测与处理逻辑，以适应形状更复杂的树木。 |
| lumbination.ignore_player_placed_leaves | boolean | true | – | 识别天然树木时忽略玩家放置的树叶。 |
| lumbination.logs | list | [] | – | 额外的树干/原木方块 ID。 |
| lumbination.leaves | list | [] | – | 额外的树叶方块 ID。 |
| lumbination.axes | list | [] | – | 允许用于 Lumbination 功能的工具列表。 |

Shaftanation（minersadvantage-server-config.toml）

| 选项 | 类型 | 默认值 | 范围 | 描述 |
| ———————————– | ——- | ——- | ———- | —————————————————— |
| shaftanation.enabled | boolean | true | – | 启用或禁用 Shaftanation。 |
| shaftanation.depth | int | 16 | 1 to 256 | 竖井长度/深度。 |
| shaftanation.processes_per_tick | int | 10 | 1 to 512 | 每刻的处理吞吐量。 |
| shaftanation.width | int | 1 | 1 to 7 | 竖井宽度。 |
| shaftanation.height | int | 2 | 1 to 5 | 竖井高度。 |
| shaftanation.torch_placement | enum | FLOOR | 枚举值 | 火把放置模式（FLOOR及其他枚举值）。 |

替换（minersadvantage-server-config.toml）

| 选项 | 类型 | 默认值 | 描述 |
| ———————————– | ———— | ——- | ———————————————————————— |
| substitution.enabled | 布尔值 | true | 启用或禁用 Substitution。 |
| substitution.allow_mending | 布尔值 | false | 为 true 时，允许在候选选择中使用带有经验修补的工具。 |
| substitution.prioritize_silk_touch | 布尔值 | false | 为 true 时，优先选择精准采集类结果。 |
| substitution.switch_back | 布尔值 | true | 为 true 时，操作后切回之前的物品栏槽位。 |
| substitution.favour_fortune | 布尔值 | true | 在适用情况下优先选择时运效果。 |
| substitution.ignore_if_valid_tool | 布尔值 | true | 当前手持工具已有效时，跳过替换。 |
| substitution.ignore_passive_mobs | 布尔值 | true | 为 true 时，攻击被动型生物不会触发工具切换。 |
| substitution.blacklist | 列表 | [] | 从替换候选中排除的物品 ID。 |

矿脉连采（minersadvantage-server-config.toml）

| 选项 | 类型 | 默认值 | 范围 | 描述 |
| ——————————————- | ———— | ——- | ———— | ————————————————————– |
| veination.enabled | 布尔值 | true | – | 启用或禁用矿脉连采。 |
| veination.max_vein_distance | 整数 | 12 | 1 to 64 | 相连矿脉的最大距离。 |
| veination.ores | 列表 | [] | – | 明确指定允许处理的矿石方块列表或目标。 |
| veination.ore_harvest_without_sneak | 布尔值 | true | – | 无需潜行即可采集矿石。 |
| veination.drop_ores_at_first_block | 布尔值 | true | – | 将掉落物放在最先破坏的矿石方块附近。 |
| veination.increase_harvest_time_per_ore | 布尔值 | true | – | 为 true 时，挖掘时间会随矿脉规模增加。 |
| veination.harvest_time_modifier | 双精度浮点数 | 0.2 | 0.01 to 10.0 | 应用于缩放后采集时间的修正系数。 |
| veination.pickaxe_blacklist | 列表 | [] | – | 禁止用于矿脉连采的镐。 |

通风（minersadvantage-server-config.toml）

| 选项 | 类型 | 默认值 | 范围 | 描述 |
| ———————————– | ——- | ——- | ———- | ————————————————- |
| ventilation.enabled | 布尔值 | true | – | 启用或禁用通风系统。 |
| ventilation.width | 整数 | 1 | 1 到 32 | 通风井宽度。 |
| ventilation.height | 整数 | 16 | 1 到 64 | 通风井高度范围。 |
| ventilation.depth | 整数 | 1 | 1 到 64 | 通风井深度/长度。 |
| ventilation.processes_per_tick | 整数 | 8 | 1 到 512 | 每刻处理吞吐量。 |
| ventilation.place_ladders | 布尔值 | true | – | 启用后，在开凿通风井时放置梯子。 |

高级替换规则配置（运行时数据）

替换功能在运行时配置默认值中包含高级 selectionRules 配置。它支持根据操作和表达式进行判断，每条规则可包含以下字段。

| 字段 | 类型 | 描述 |
| —————— | ——- | ————————————————————————— |
| action | 枚举 | BREAK、INTERACT、ATTACK、STAT_CHANGE 或 ANY。 |
| targetKind | 枚举 | BLOCK_TAG、ENTITY_TYPE 或 ANY。 |
| targetId | 字符串 | 所选目标类型对应的标签/实体标识符。 |
| requiredToolKind | 字符串 | 工具类别提示（例如 pickaxe、axe、shovel、hoe）。 |
| targetPriority | 整数 | 在多个匹配目标中进行选择时的优先级。 |
| toolPriority | 整数 | 在多个候选工具中进行选择时的优先级。 |
| preferSilkTouch | 布尔值 | 为此规则优先选择精准采集类结果。 |
| preferFortune | 布尔值 | 为此规则优先选择时运类结果。 |
| targetExpression | 字符串 | 可选的目标表达式，可使用 AND/OR/NOT 和括号。 |
| toolExpression | 字符串 | 可选的工具表达式，可使用 AND/OR/NOT 和括号。 |
| minSilkTouch | 整数 | 所需的精准采集最低等级。 |
| minFortune | 整数 | 所需的时运最低等级。 |
| requireMending | 布尔值 | 为 true 时，所选工具必须拥有经验修补。 |
| denyMending | 布尔值 | 为 true 时，不允许使用带有经验修补的工具（若两者均为 true，则 requireMending 优先）。 |

兼容性

| 主题 | 状态 |
| ——————– | ———————————————————————- |
| Minecraft 版本 | 1.21.11 和 26.1.2 节点均在维护中。 |
| 加载器 | Fabric 和 NeoForge 均为一等支持目标。 |
| 已知冲突 | 目前未记录任何严重冲突。如果你发现冲突，请提交问题反馈。 |

| 技术文档

完整技术详情请参阅 TECHNICAL.md。

许可证

MIT——完整文本请参阅 LICENSE.md。

致谢

• 原版模组及现代重制版 DuelMonster。
• Stonecutter、Modstitch、Fabric、NeoForge、Cloth Config 和 ModMenu 的维护者。