MCreator 自定义属性(Attribute)最小/最大值参数解析:取值范围设置、界面校验与代码生成

原创2026-10-15 20:01:301,769 阅读
文章标签:低代码代码生成桌面应用游戏开发

MCreator 自定义属性(Attribute)最小/最大值参数解析:取值范围设置、界面校验与代码生成

本文围绕 MCreator 中「属性(Attribute)」元素的 Min/Max Value(最小/最大值) 参数展开。该参数用于划定一个自定义属性(如攻击伤害、移动速度、法力值)的取值边界,在属性编辑器界面中设置后,会在生成 Mod 代码时落地为 Minecraft 原版的 RangedAttribute。读完本文,你将掌握该参数的确切含义、它与默认基值(Default Base Value)的关系、界面中的校验规则,以及它在生成代码中的真实形态。

参数含义:属性值的取值边界

在 MCreator 的官方帮助文档中,min_max_value 参数的定义只有一句话(捷克语版原文为 "Tento parametr udává maximální a minimální hodnotu, kterou atribut může mít."),对应简体中文版本为:

此参数控制属性值的最小值和最大值。

也就是说,Min/Max Value 定义了「该属性最终可以被设置到的数值范围」。任何通过修饰符(Modifier)、流程(Procedure)或命令对该属性进行的修改,最终都不得越过这个闭区间 [最小值, 最大值]。

需要特别区分两个概念:

  • 默认基值(Default Base Value):属性注册时的初始数值,详见 default_value.md。该文档明确指出:「属性值是在对基值施加修饰符以及最小/最大限制之后计算得出的数值」——即基值是输入,范围限制是约束条件,最终属性值是输出。
  • 最小值/最大值(Min/Max Value):属性值在施加修饰符并结算之后被钳制(clamp)的上下限。

在数据模型层面,这两个概念分别对应 Attribute.java 中的三个 double 字段:

@Numeric(init = 0, min = -Double.MAX_VALUE, max = Double.MAX_VALUE, step = 1.0) public double minValue;
@Numeric(init = 1, min = -Double.MAX_VALUE, max = Double.MAX_VALUE, step = 1.0) public double maxValue;
@Numeric(init = 0, min = -Double.MAX_VALUE, max = Double.MAX_VALUE, step = 1.0) public double defaultValue;

由此可见默认状态:最小值初始为 0,最大值初始为 1,默认基值初始为 0,步进为 1;三者理论上都允许在 -Double.MAX_VALUE 到 Double.MAX_VALUE 的浮点范围内取值(即不设人为限制)。

参数在属性编辑器中的位置

该参数是 MCreator 属性元素编辑器(AttributeGUI)中的一个标准输入项。在 AttributeGUI.java 中,它被实现为一个「最小值 + 最大值」双微调框(JMinMaxSpinner),并配有帮助按钮,帮助内容正是本文所依据的文档:

pane1.add(HelpUtils.wrapWithHelpButton(this.withEntry("attribute/min_max_value"),
        L10N.label("elementgui.attribute.min_max_value")));
pane1.add(minMaxValue);

其中 withEntry("attribute/min_max_value") 就是帮助按钮指向的本地化帮助条目,即 plugins/mcreator-localization/help/ 目录下各语言版本的 attribute/min_max_value.md(仓库中提供了 default、en_GB、zh_CN、cs_CZ 等 17 种语言版本)。界面字段标签来自 texts_zh_CN.properties,为「属性值的范围:」。

在编辑器中,与 Min/Max 同属一页(pane1,7 行 2 列布局)的还有:属性名称、默认基值(Default Base Value)、属性倾向(Sentiment)、添加范围(添加到所有实体 / 玩家 / 指定实体列表)。编辑完成后,这些值通过 getElementFromGUI() 统一写回 Attribute 数据模型;打开已存在属性时则由 openInEditingMode() 回填,其中包括 minMaxValue.setMinValue(attribute.minValue) 与 setMaxValue(attribute.maxValue)。

与默认基值的联动校验

虽然 Min/Max 与 Default Base Value 是独立输入项,但三者之间存在强约束:默认基值必须落在 最小值, 最大值] 区间内。这一规则由 [AttributeGUI.java 中的校验器强制执行:

minMaxValue.setValidator(() -> {
    if (minMaxValue.getMinValue() > (double) defaultValue.getValue())
        return new ValidationResult(ValidationResult.Type.ERROR,
                L10N.t("elementgui.attribute.default_lower_than_min"));
    else if (minMaxValue.getMaxValue() < (double) defaultValue.getValue())
        return new ValidationResult(ValidationResult.Type.ERROR,
                L10N.t("elementgui.attribute.default_higher_than_max"));
    return ValidationResult.PASSED;
});

对应的错误提示(简体中文)为:

  • 默认基值不能小于最小值。(default_lower_than_min)
  • 默认基值不能大于最大值。(default_higher_than_max)

逻辑上等价于:最小值 <= 默认基值 <= 最大值。一旦校验失败,控件边框会以错误色标红(见 JMinMaxSpinner.getValidationStatus() 的渲染逻辑),阻止该属性元素通过验证并进入代码生成阶段。

界面控件行为细节:JMinMaxSpinner

Min/Max 输入使用的 JMinMaxSpinner 并非两个独立微调框的简单拼装,其内部封装了多项防呆行为,源码见 JMinMaxSpinner.java:

  • 最小值不能大于最大值:当用户把最小值调得比最大值还大时,最大值会被自动同步为当前最小值;反过来把最大值调得比最小值还小时,最小值会被自动同步为当前最大值。
  • 默认不允许最小值等于最大值(除非调用 allowEqualValues() 显式放开),当两者相同时会回滚上一次的修改。
  • 小数精度自适应:当步进值很小时,编辑器会自动增加小数点显示位数(步进小于 0.001 时最多显示 6 位小数),保证精细取值时可读。

该组件由 ComponentFromAnnotation.minMaxSpinner(...) 依据 Attribute 类上的 @Numeric 注解自动构造,见 ComponentFromAnnotation.java。构造时会校验最小字段与最大字段的步进、上下界注解必须一致,否则直接抛出 IllegalArgumentException,从框架层面保证两个输入框的行为对称。

生成代码:落地为 RangedAttribute

属性元素的代码生成定义位于 attribute.definition.yaml,它声明了全局模板 elementinits/attributes.java.ftl,输出到 @SRCROOT/@BASEPACKAGEPATH/init/@JavaModNameAttributes.java。在 NeoForge 1.21.1 的模板 attributes.java.ftl 中,Min/Max 与默认基值一同被写入属性注册语句:

public static final DeferredHolder<Attribute, Attribute> EXAMPLE = REGISTRY.register("example",
    () -> new RangedAttribute("attribute.modid.example", 10d, 0d, 100d).setSyncable(true));

其中三个数值参数依次为 defaultValue、minValue、maxValue,与界面填写顺序完全对应。RangedAttribute 是 Minecraft 原版提供的「有范围约束的属性」实现,属性值在计算时会被限制在 <a href="https://link.gitcode.com/i/2d883065334c7978dbdebf2a50732a07" target="_blank">min, max] 区间内;setSyncable(true) 使该属性在服务端与客户端之间同步。NeoForge 26.3(对应新版本 Minecraft)的模板 [attributes.java.ftl 使用了完全相同的生成方式。

模板还根据「添加范围」配置生成属性挂载逻辑:勾选「添加到所有实体」时对所有实体类型调用 event.add;否则按实体列表(attribute.entities,经 generator.map(..., "entities", 1) 映射)逐一挂载,并在勾选「添加到玩家」时额外挂载 EntityType.PLAYER。也就是说,Min/Max 决定属性的取值空间,而实体挂载决定哪些生物拥有该属性。

实战示例与使用建议

以「自定义法力值属性」为例,在属性元素编辑器中建议配置:

字段 建议值 说明
属性名称 Mana 显示名称
默认基值(Default Base Value) 10 必须落在 [0, 100] 内
最小值(Min Value) 0 法力值下限
最大值(Max Value) 100 法力值上限
添加到玩家 勾选 让玩家实体拥有该属性

生成后,可在 Mod 的流程(Procedure)中配合 plugins/mcreator-core/procedures/ 下的相关积木使用,例如 entity_get_attribute_value.json(读取属性当前值)、entity_get_attribute_base_value.json(读取基值)、entity_add_modifier.json(对属性施加修饰符)。修饰符结算后的结果会被钳制在 [0, 100] 内,从而实现「法力值不会跌破 0、不会超过 100」的玩法逻辑。

实际使用中还需注意:

  • 最小值/最大值只影响注册后属性值的结算;若后续编辑属性元素修改了范围,对已生成存档中实体的既有属性实例的影响取决于游戏运行时的重新加载机制,因此在设计阶段就应确定好范围,避免后期频繁调整。
  • 属性倾向(Sentiment,POSITIVE/NEUTRAL/NEGATIVE)与 Min/Max 相互配合:例如 NEGATIVE 倾向通常配合较小的取值范围使用,而 POSITIVE 配合正向修饰符。该字段的本地化帮助见 sentiment.md。
  • 若希望属性对所有生物生效,请优先勾选「添加到所有实体」(addToAllEntities),而不是逐个选择实体,后者会与「添加到玩家」互斥,且需要在 entities.md 所述的选择器中手动挑选。

小结

Min/Max Value 虽只是属性元素编辑器中的一个输入项,但它在 MCreator 中贯穿「界面输入 → 数据模型 → 校验约束 → 代码生成」四个环节:界面由 JMinMaxSpinner 提供双端输入与防呆逻辑;数据模型由 Attribute.java 的 minValue/maxValue 字段承载;校验规则保证默认基值落在范围内;最终由 attributes.java.ftl 生成带范围约束的 RangedAttribute。理解这条链路,你就掌握了自定义属性取值范围从配置到成品的完整机理。

登录后查看全文
MCreator