MCreator 流体"斜坡寻找距离(Slope Find Distance)"参数深度解析:作用原理、界面配置与代码生成
MCreator 流体"斜坡寻找距离(Slope Find Distance)"参数深度解析:作用原理、界面配置与代码生成
本文以 MCreator 官方帮助文档《slope_find_distance.md》(并对照 英文默认版 与 中文版)为骨架,结合仓库源码与代码生成模板,系统讲解流体(Fluid)元素中"斜坡寻找距离"参数的含义、行为规律、取值边界,以及它如何被翻译进最终生成的 Minecraft 模组代码,帮助你精确控制自定义流体在地形起伏处的扩散表现。
1. 参数定位:一行话说清"斜坡寻找距离"
在 MCreator 的流体(Fluid)元素编辑器中,有一项名为 Slope find distance(斜坡寻找距离) 的数值参数。官方帮助文档用一句话给出了它的核心定义:
该参数决定斜坡对流体扩散的影响范围。流体不会均匀地向四周扩散,而是会试图流向斜坡;当取值较低时,流体通常会在崎岖不平的地表上覆盖更大的面积。
结合仓库证据可以进一步解读这句话:
- 行为模式改变:默认情况下,流体(如水)倾向于在水平方向上均匀铺开;开启/调整该参数后,流体在扩散过程中会优先"感知"附近存在的斜坡(即高度落差),并把斜坡方向作为扩散的优先目标;
- 搜索半径:参数值即流体寻找斜坡时向前探测的"距离尺度",值越大,流体越容易越过较远的地形起伏去追踪坡面,值越小则越"安于"就近铺平;
- 结果差异:正如文档所说,在不平整的地面上,较小的取值通常会让流体覆盖更广的区域,因为它不再执着于顺着远处的坡面流,而是就地扩散填平。
该参数与同一"流体属性"面板中的 flow_rate(流速)、level_decrease(每格下降高度)、flow_strength(流动强度)共同决定了流体的整体扩散行为,它们之间的取舍直接体现为你自定义液体在地形中的"水系"形态。
2. 界面位置与本地化标签
2.1 参数在编辑器中位于"流体属性"区
在 FluidGUI.java 中,slopeFindDistance 以一个 JSpinner 数字微调框的形式构建(FluidGUI.java 第 81 行),并被添加到 destal 网格面板中,最终归入标题为"流体属性(Fluid properties)"的分区(FluidGUI.java 第 265-267 行、第 337-340 行)。该分区同时包含 flowRate、flowStrength、levelDecrease、canMultiply、spawnParticles 等流体行为参数,因此调整斜坡寻找距离时,通常需要与这几个参数统筹考虑。
2.2 帮助按钮与多语言文案
在 UI 中,该参数行通过 HelpUtils.wrapWithHelpButton(this.withEntry("fluid/slope_find_distance"), ...) 挂接了一个"帮助"按钮(FluidGUI.java 第 265 行),点击后即可打开本文所依据的这份帮助文档;对应的界面标签文本则由本地化键 elementgui.fluid.slope_find_distance 提供,例如:
| 语言 | 界面文案 |
|---|---|
| 中文(zh_CN) | 斜坡寻找距离: |
| 英文(en_GB) | Slope find distance: |
| 德语(de_DE) | Neigungssuchdistanz: |
| 日语(ja_JP) | 傾斜の検索距離: |
| 法语(fr_FR) | Distance de recherche de pente: |
文案条目可在 texts.properties、texts_de_DE.properties 等语言文件中查证。
3. 取值边界、默认值与步进规则
参数的具体取值范围与默认值由流体元素的数据模型定义。在 Fluid.java 中可以看到:
@Numeric(init = 4, min = 1, max = 16, step = 1) public int slopeFindDistance;
关键信息整理如下:
| 属性 | 值 |
|---|---|
| 默认值(init) | 4 |
| 最小值(min) | 1 |
| 最大值(max) | 16 |
| 步进(step) | 1(整数) |
也就是说,这是一个整数型参数,取值范围 1 到 16,默认值为 4。@Numeric 注解同时驱动了编辑器 UI 中 JSpinner 的范围与步进约束(FluidGUI.java 第 81 行 通过 ComponentFromAnnotation.spinner(Fluid.class, "slopeFindDistance") 自动生成),并驱动了代码生成时的数值校验。
需要特别说明:默认值 4 同时也是 Minecraft 原版流体(如普通水源)使用的标准值。因此,只有当你把该值修改为非 4 时,生成器才会把自定义值写入代码——这一"默认值即省略"的优化逻辑在下一节展开。
4. 源码级原理:参数如何进入生成的模组代码
4.1 数据保存
在保存流体元素时,编辑器会把 JSpinner 的当前值写回模型对象:
fluid.slopeFindDistance = (int) slopeFindDistance.getValue();
随后该值随 .mcreator 工作区文件持久化;从源码结构看,它属于 GeneratableElement 的序列化数据,测试工程生成器也会随机赋予合法范围内的值来覆盖该路径(TestWorkspaceDataProvider.java 第 630 行 通过 getRandomInt(random, Fluid.class, "slopeFindDistance") 生成,说明它遵循 @Numeric 声明的 1~16 边界)。
4.2 FreeMarker 模板中的条件输出
真正决定"是否以及如何写入 Minecraft 代码"的,是各版本生成器的 FreeMarker 模板。以 NeoForge 1.21.1 生成器为例,fluid.java.ftl 第 39-48 行构建流体的 Properties 链式配置:
public static final BaseFlowingFluid.Properties PROPERTIES = new BaseFlowingFluid.Properties(
() -> ${JavaModName}FluidTypes.${REGISTRYNAME}_TYPE.get(),
() -> ${JavaModName}Fluids.${REGISTRYNAME}.get(),
() -> ${JavaModName}Fluids.FLOWING_${REGISTRYNAME}.get())
.explosionResistance(${data.resistance}f)
<#if data.flowRate != 5>.tickRate(${data.flowRate})</#if>
<#if data.levelDecrease != 1>.levelDecreasePerBlock(${data.levelDecrease})</#if>
<#if data.slopeFindDistance != 4>.slopeFindDistance(${data.slopeFindDistance})</#if>
<#if data.generateBucket>.bucket(() -> ${JavaModName}Items.${REGISTRYNAME}_BUCKET.get())</#if>
.block(() -> (LiquidBlock) ${JavaModName}Blocks.${REGISTRYNAME}.get());
注意第 46 行的关键逻辑:
<#if data.slopeFindDistance != 4>.slopeFindDistance(${data.slopeFindDistance})</#if>
这意味着:
- 当你保持默认值 4 时,生成的类不会出现
.slopeFindDistance(...)调用,从而继承 MinecraftBaseFlowingFluid的默认斜坡寻找距离(4),生成代码更精简; - 只有当你显式改成一个 1~16 之间、非 4 的值时,模板才会输出
.slopeFindDistance(N),将自定义值写入BaseFlowingFluid.Properties。
同一逻辑在 NeoForge 26.3(对应 MCreator 较新的生成器版本)的 fluid.java.ftl 第 46 行完全一致,因此这套规则跨生成器版本稳定适用。
4.3 生成的代码意味着什么
从生成的代码可以推断:slopeFindDistance 最终映射为 Minecraft/NeoForge 流体系统中 FlowingFluid 的斜坡寻找距离字段,它参与流体每次扩散 tick 时对相邻方块高度的探测逻辑——流体以此判断"附近是否存在可沿坡度流下的路径"。你设置的数值越大,流体探测坡面的扫描范围越广,也就越倾向于"追坡而下";数值越小,流体越少受远处地形干扰,更倾向于按自身重力规则就地铺开。这与帮助文档中"流体试图到达斜坡"以及"低值时在崎岖地表覆盖更大面积"的描述完全吻合。
5. 实战配置建议
结合文档描述与参数边界,在实际制作自定义流体(如岩浆、毒液、水银等)时可以参考以下规律:
| 场景 | 建议取值 | 效果说明 |
|---|---|---|
| 常规水体、希望在地形中自然蔓延 | 默认 4 | 与 Minecraft 原版水源一致,行为最"标准" |
| 希望液体在山区/悬崖地形覆盖更广面积 | 取低值(如 1~3) | 流体不过分追逐远处坡面,在高低不平的地表更容易就地铺开,覆盖面积更大 |
| 希望液体优先沿坡道、峡谷向下快速流窜 | 取较高值(如 8~16) | 流体能在更远距离上识别并追踪斜坡,形成沿坡度倾泻的效果 |
| 制作"爬墙/倒流"等特殊机制时 | 结合 flow_condition 流程 |
斜坡寻找距离只控制坡度感知,需要额外用 flow_condition 改变扩散条件才能实现非常规流动 |
需要注意:该参数只影响流体扩散时的坡度探测范围,不改变流体每 tick 的扩散速度(那是 flow_rate 的职责)、每经过一格下降的高度(level_decrease)或流动冲击力度(flow_strength)。在多参数联调时,建议先用小数值逐步试验,观察地形起伏处的覆盖形态。
6. 相关文件索引
如果你希望进一步深入源码,以下文件可作为起点:
- 参数模型与取值范围:src/main/java/net/mcreator/element/types/Fluid.java(第 67 行的
@Numeric注解定义了 1~16 与默认 4) - 编辑器 UI 与帮助按钮挂接:src/main/java/net/mcreator/ui/modgui/FluidGUI.java
- 代码生成模板(NeoForge 1.21.1):plugins/generator-1.21.1/neoforge-1.21.1/templates/fluid/fluid.java.ftl
- 代码生成模板(NeoForge 26.3):plugins/generator-26.3.x/neoforge-26.3/templates/fluid/fluid.java.ftl
- 集成测试中的参数覆盖:src/test/java/net/mcreator/integration/TestWorkspaceDataProvider.java
- 界面标签本地化:
plugins/mcreator-localization/lang/texts.properties及各国语言文件中的elementgui.fluid.slope_find_distance条目
结语
"斜坡寻找距离"虽然只是 MCreator 流体元素中一个不起眼的整数微调框,但它直接改变了自定义流体在真实地形中的"性格":默认值 4 继承原版行为,低值让液体在崎岖地面覆盖更广,高值让液体执着地追坡而下。理解其取值范围(1~16)、默认值(4)以及 fluid.java.ftl 中的条件生成逻辑,你就能在制作自定义流体时精准预判它的扩散形态,从而调出理想中的液体表现。