MCreator 属性全局生效指南:深入解析 "Add to all entities" 选项与 Attribute 元素
MCreator 属性全局生效指南:深入解析 "Add to all entities" 选项与 Attribute 元素
在 MCreator 中创建自定义属性(Attribute)时,"Add to all entities"(添加到所有实体)是一个看似简单却影响深远的功能开关:勾选后,世界中所有具备属性能力的实体都会在生成时自动携带该属性,并将其初始值设为默认值。本篇指南以 add_to_all_entities.md 帮助文档 为核心,结合仓库中 Attribute.java、AttributeGUI.java 与 NeoForge 生成模板 attributes.java.ftl 的实现细节,讲清该选项的界面交互、三种生效范围的区别、底层代码生成原理及实际使用注意事项。读完本文,你将能熟练设计全局属性、玩家专属属性或指定实体属性,并理解其背后的 Minecraft 属性机制。
一、"Add to all entities" 是什么
MCreator 官方帮助文档(default 与 en_GB 版本)对该选项的定义如下:
If enabled, all entities in the world that can have attributes will have this attribute present and set at its default value when spawned.
(如果启用,世界中所有能够拥有属性的实体,都会在生成时带有该属性,并将其设置为默认值。)
这句话包含两个关键限定:
- "all entities ... that can have attributes":并非所有实体都会被附加属性,只有具备属性能力的实体(如
LivingEntity派生实体,包括玩家、生物、部分动物等)才会生效。从生成模板event.getTypes().forEach(...)的写法可以推断,实际遍历的是EntityAttributeModificationEvent.getTypes()返回的实体类型集合,该集合本身已经过滤了那些没有属性系统的实体。 - "set at its default value when spawned":属性会被注册并作为该实体的基础属性存在,初始值为元素中配置的默认值(
defaultValue),之后可由游戏内的过程(procedure)、指令或修饰符(modifier)改变。
在 Attribute.java 中,该选项与另外两个生效范围字段并列存储:
public boolean addToAllEntities; // 添加到所有实体
public boolean addToPlayers; // 仅添加到玩家
@ModElementReference public List<EntityEntry> entities; // 添加到指定实体列表
三个字段互斥协作,共同决定属性的最终作用范围。
二、界面位置与交互逻辑(源码级)
"Add to all entities" 选项位于 Attribute 元素的编辑界面(ModElementGUI<Attribute>)中。查看 AttributeGUI.java 的界面构建代码:
private final JCheckBox addToAllEntities = L10N.checkbox("elementgui.common.enable");
private final JCheckBox addToPlayers = L10N.checkbox("elementgui.common.enable");
private final SpawnableEntityListField entities = new SpawnableEntityListField(mcreator);
在布局中,该选项与 "Add to players"(add_to_players 帮助文档)以及 "Entities"(entities 帮助文档)依次排列:
pane1.add(HelpUtils.wrapWithHelpButton(this.withEntry("attribute/add_to_all_entities"),
L10N.label("elementgui.attribute.add_to_all_entities")));
pane1.add(addToAllEntities);
pane1.add(HelpUtils.wrapWithHelpButton(this.withEntry("attribute/add_to_players"),
L10N.label("elementgui.attribute.add_to_players")));
pane1.add(addToPlayers);
这里有一个值得注意的联动行为——当勾选 "Add to all entities" 时,另外两个生效范围控件会被自动禁用:
addToAllEntities.addActionListener(_ -> {
addToPlayers.setEnabled(!addToAllEntities.isSelected());
entities.setEnabled(!addToAllEntities.isSelected());
});
原因很直观:一旦选择"所有实体",再单独指定玩家或实体列表就失去意义了,三者互斥。
同样,在编辑已有元素时也会根据保存的状态恢复控件可用性(AttributeGUI.java):
addToAllEntities.setSelected(attribute.addToAllEntities);
addToPlayers.setSelected(attribute.addToPlayers);
entities.setListElements(attribute.entities);
addToPlayers.setEnabled(!attribute.addToAllEntities);
entities.setEnabled(!attribute.addToAllEntities);
条件校验逻辑
界面还通过 ConditionalValidator 保证数据一致性(AttributeGUI.java):
entities.setValidator(
new ConditionalValidator(() -> !(addToAllEntities.isSelected() || addToPlayers.isSelected()),
new NonEmptyValidator(entities, L10N.t("elementgui.attribute.needs_entity"))));
也就是说:只有"所有实体"和"仅玩家"两个选项都未勾选时,才会强制要求实体列表非空;否则实体列表可以不填。这从 UI 层保证了"全局/玩家属性不必绑定具体实体"的合法场景。
三、三种生效范围的对比与选择
结合帮助文档与源码,Attribute 元素支持三种互斥的生效范围:
| 生效范围 | 界面配置方式 | 官方说明 | 典型用途 |
|---|---|---|---|
| 所有实体 | 勾选 Add to all entities | 所有可拥有属性的实体在生成时均附带该属性(add_to_all_entities.md) | 全局性数值体系,如通用体力值、速度系数 |
| 仅玩家 | 勾选 Add to players | 所有玩家在加入世界时附带该属性(add_to_players.md) | 玩家专属数值,如经验倍率、体力条 |
| 指定实体 | 在 Entities 列表中选择 | 选中的实体在生成时附带该属性(entities.md) | 仅特定生物生效的自定义属性 |
需要注意三种模式都会将属性初始化为默认值(defaultValue),差异只在于作用对象的范围。
四、底层生成原理:EntityAttributeModificationEvent
勾选 "Add to all entities" 后,MCreator 在代码生成阶段会将其映射到 NeoForge 的 EntityAttributeModificationEvent。以仓库中的 NeoForge 26.3 生成器为例,核心模板 attributes.java.ftl 中注册了全局属性,并通过 attribute.definition.yaml 声明输出到 @SRCROOT/@BASEPACKAGEPATH/init/@JavaModNameAttributes.java。
属性本身的注册逻辑(模板第 44-48 行):
<#list attributes as attribute>
public static final DeferredHolder<Attribute, Attribute> ${attribute.getModElement().getRegistryNameUpper()} = REGISTRY.register("${attribute.getModElement().getRegistryName()}",
() -> new RangedAttribute("attribute.${modid}.${attribute.getModElement().getRegistryName()}", ${attribute.defaultValue}d, ${attribute.minValue}d, ${attribute.maxValue}d).setSyncable(true)
<#if attribute.sentiment != "POSITIVE">.setSentiment(Attribute.Sentiment.${attribute.sentiment})</#if>);
</#list>
可见属性最终以 RangedAttribute 形式注册,其构造参数顺序为 默认值、最小值、最大值,对应界面上的 Default value 与 Min/Max value 参数。
而 "Add to all entities" 分支体现在模板的 addAttributes 事件处理器中(第 50-70 行):
@SubscribeEvent public static void addAttributes(EntityAttributeModificationEvent event) {
<#list attributes as attribute>
<#if attribute.addToAllEntities>
event.getTypes().forEach(entity -> event.add(entity, ${attribute.getModElement().getRegistryNameUpper()}));
<#else>
<#if attribute.entities?has_content>
List.of(
<#list attribute.entities as entity>
${generator.map(entity.getUnmappedValue(), "entities", 1)}<#sep>,
</#list>
).stream()
.filter(DefaultAttributes::hasSupplier)
.map(entityType -> (EntityType<? extends LivingEntity>) entityType)
.collect(Collectors.toList()).forEach(entity -> event.add(entity, ${attribute.getModElement().getRegistryNameUpper()}));
</#if>
<#if attribute.addToPlayers>
event.add(EntityTypes.PLAYER, ${attribute.getModElement().getRegistryNameUpper()});
</#if>
</#if>
</#list>
}
这段生成代码清晰揭示了三种模式的底层差异:
- Add to all entities:直接遍历
event.getTypes()(所有具备属性能力的实体类型),逐个event.add(...)附加属性,无需额外的hasSupplier过滤,因为该事件源集合天然只包含有属性系统的实体。 - 指定实体列表:对选中的实体类型先执行
DefaultAttributes::hasSupplier过滤,确保实体确实有默认属性供应商(否则附加属性会没有意义或引发运行时问题),再转成LivingEntity类型后附加。 - Add to players:单独对
EntityTypes.PLAYER调用event.add(...)。
从生成代码可以看出,"Add to all entities" 是三种模式中附加范围最广、生成逻辑最简单的一个分支——它不依赖任何实体筛选,直接作用于事件提供的全部实体类型。
五、与其他参数配合:默认值与范围约束
"所有实体生成时携带该属性"中的默认值,正是界面上的 Default value 参数。官方帮助文档 default_value.md 说明:
This is the attribute's default base value. The attribute will have this as its value until something in the game (procedure, command or modifier) changes it. The value of an attribute is the number that is calculated after modifiers and min/max restrictions are applied on its base value.
即默认值在游戏内没有任何机制修改它之前保持恒定;属性的实际生效值是在基础值上叠加修饰符并经过最小/最大限制约束后计算得出的。
与 "Add to all entities" 直接相关的是 Min/Max value 参数(min_max_value.md):该参数控制属性值可被设置的最小与最大值。由于全局属性会附加给所有实体,其默认值必须落在 <a href="https://link.gitcode.com/i/0bbafe84c22e2f23dfbfe340c8d92fd5" target="_blank">minValue, maxValue] 区间内,界面校验器对此有强制约束([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;
});
如果默认值小于最小值或大于最大值,MCreator 会直接拒绝保存该元素。
此外还有一个与数值语义相关的 Sentiment(倾向性)参数(sentiment.md):它决定属性被视为正面(POSITIVE)、负面(NEGATIVE)还是中性(NEUTRAL),并影响该属性修饰符在游戏界面中的颜色显示。在生成代码中,只有非 POSITIVE 的倾向才会显式调用 setSentiment(...)。数据结构层面,sentiment 字段通过 @LimitedOptions({ "POSITIVE", "NEUTRAL", "NEGATIVE" }) 注解限定取值(Attribute.java)。
六、实战建议与注意事项
综合帮助文档与源码实现,使用 "Add to all entities" 时有以下几点值得注意:
-
合理评估属性含义的普适性:全局属性会附加给世界中的一切有属性能力的实体(包括玩家、敌对生物、被动生物)。如果只想作用于特定生物,请优先使用 "Entities" 列表模式,避免属性系统数据无谓膨胀。
-
默认值必须落在范围内:全局属性的默认值必须处于 Min/Max 区间内,否则元素无法保存。设计时建议将默认值设置为中值,留出上下调整空间。
-
三个范围选项互斥:勾选 "Add to all entities" 后,"Add to players" 与 "Entities" 列表会被禁用并忽略;当两者都未勾选时,实体列表才被强制要求非空。
-
属性是"注册"而非"写入实体":从生成代码看,全局属性本质上是修改
EntityAttributeModificationEvent,为实体类型附加已注册的属性引用,而非在实体出生瞬间设置一个一次性数值。因此属性的后续变化应通过过程、指令或修饰符完成,这也与 default_value.md 的说明一致。 -
生成产物位置:开启该选项生成的代码位于
<基础包路径>/init/<Mod名>Attributes.java(由 attribute.definition.yaml 的global_templates声明决定),每次构建都会重新生成(模板头部注释明确标注 "This file will be REGENERATED on each build"),因此不建议手改生成产物,应回到 MCreator 界面修改元素配置。
七、总结
"Add to all entities" 是 MCreator Attribute 元素中最直接的"全局属性"开关:勾选后,attributes.java.ftl 会生成遍历 EntityAttributeModificationEvent.getTypes() 的注册代码,让所有具备属性能力的实体在生成时携带该属性并初始化为默认值。与之相对的 "Add to players" 与 "Entities" 列表则提供了更精细的玩家专属与指定实体范围。三者通过 AttributeGUI.java 中的联动禁用与条件校验保证互斥一致。理解这一选项的底层机制,能帮助你在设计模组数值体系时,准确选择属性的生效范围,避免"全局属性"带来的意外扩散。