MCreator 实体变量类型详解:Logic、Number/Integer、String 的选择与底层实现
MCreator 实体变量类型详解:Logic、Number/Integer、String 的选择与底层实现
在 MCreator 中为自定义生物(Living Entity)添加实体变量时,「数据类型」是决定变量行为的关键选项。本文围绕 data_type 帮助文档展开,系统讲解实体变量的三种受支持类型(Logic 逻辑、Number 数值、String 字符串)的语义区别、默认值规则、实际配置步骤,并结合仓库源码剖析变量从 UI 配置到 SynchedEntityData 同步、再到过程块读写调用的完整实现链路,帮助你准确选择类型并理解其在客户端/服务端同步中的工作原理。
实体变量与 data_type 选项
在 MCreator 的生物(Living Entity)编辑界面中,「实体数据」(Entity Data)面板允许你给自定义实体添加独立变量,帮助文档 entity_data.md 的说明是:这些变量会在客户端(Client)与服务端(Server)之间同步,例如可以用一个变量来控制实体纹理的切换(entity_data.md)。
data_type(数据类型)选项控制的正是这个实体变量的类型。官方帮助文档原文指出,受支持的类型是 Logic(逻辑)、Number(数值)和 String(字符串)三类(data_type.md)。
值得注意的是,帮助文档中所说的「Number / Zahl(数值)」,在实际配置对话框中对应的是 Integer(整数) 类型。这一点可以从新增变量对话框的源码得到印证:AddEntityPropertyDialog 中下拉框提供的选项是 Integer、Logic、String 三种(AddEntityPropertyDialog.java),而条目显示层同样会把类型字符串映射为 Logic、String、Integer(JEntityDataEntry.java)。因此,在为生物实体新增变量时,你实际面对的是「整数 / 逻辑 / 字符串」三选一。
三种类型详解:默认值、输入控件与适用场景
data_type 与另外两个参数共同构成一条完整的实体变量定义:data_name(变量名)、data_type(类型)、data_default_value(默认值)。其中默认值规则(data_default_value.md)与类型一一对应,具体如下。
Logic(逻辑型)
- 取值:只有
true或false两个布尔值; - 默认值:
false; - 配置控件:复选框(
JCheckBox),勾选显示true,取消勾选显示false; - 适用场景:开关类状态,例如「该实体是否处于愤怒状态」「是否已生成巢穴」「是否允许某种行为」等二值标志。
Integer(整数型,即帮助文档中的 Number/Zahl)
- 取值:整数,源码中
IntegerType的默认取值范围为从Integer.MIN_VALUE到Integer.MAX_VALUE的整个 int 区间(也可在特定属性上指定更小的min/max限制); - 默认值:
0; - 配置控件:数字微调框(
JSpinner,步进为 1); - 适用场景:计数、等级、阶段、冷却时间等需要整数的状态,例如「实体当前怒气值」「已拾取物品数量」。
String(字符串型)
- 取值:任意文本/字符串值;
- 默认值:空字符串
""; - 配置控件:文本框(
JTextField);如果属性定义了允许值列表,则会使用下拉框(JComboBox)供选择; - 适用场景:纹理路径、标签、自定义名称等文本类状态,例如根据字符串值切换实体纹理。
上述默认值与控件的实现集中在 PropertyData.java 的 LogicType、IntegerType、StringType 三个内部类中(分别对应第 153–185 行、第 190–233 行、第 291–337 行)。需要说明的是,引擎底层还额外定义了 NumberType(浮点数,默认 0.0,步进最小 0.000000001),用于其他需要小数数值的属性场景;而实体变量的新增对话框中仅开放上述三种类型。
配置步骤:在生物编辑器中新增实体变量
- 打开生物(Living Entity)编辑器,找到「实体数据」(Entity Data / 实体数据条目)面板;
- 点击添加条目按钮(源码中对应
JEntityDataList的「Add entry」按钮,JEntityDataList.java),弹出「新增实体属性」对话框; - 在 Name(名称) 输入框中填写变量名。该名称会经过校验器实时校验(AddEntityPropertyDialog.java):
- 必须是合法的 Java 成员名(
JavaMemberNameValidator); - 不能与当前实体已有的变量重名(
UniqueNameValidator); - 名称将直接参与生成
DATA_<NAME>这样的 Java 字段名,因此建议使用大写字母开头的标识符,例如Angry、KillCount;
- 必须是合法的 Java 成员名(
- 在 Type(类型) 下拉框中选择
Integer、Logic或String(AddEntityPropertyDialog.java); - 点击确定后,条目会出现在实体数据列表中,此时可在 Default value(默认值) 处设置该变量初始值(JEntityDataEntry.java);
- 变量定义保存在生物元素的
entityDataEntries字段中,该字段在数据模型中被声明为List<PropertyDataWithValue<?>>(LivingEntity.java),随工作区文件一同持久化。
类型在底层如何被存储与识别
PropertyData 采用基于 Gson 的自定义序列化适配器,在 JSON 中以 type 字段标记属性类型,内置映射为 logic、integer、number、string 四个标识(PropertyData.java)。序列化与反序列化时,适配器会根据 type 字符串恢复对应的 PropertyData 子类实例,并连同 value 一起打包成 PropertyDataWithValue 记录(PropertyDataWithValue.java)。这意味着:
- 类型信息与值一同持久化,工作区文件可完整还原每一条实体变量的类型;
registerType(String id, Class<? extends PropertyData<?>> type)提供了扩展点,未来可注册新的属性类型(PropertyData.java)。
从配置到代码生成:类型如何变成 Minecraft 代码
实体变量的真正威力在于代码生成阶段。以 NeoForge 1.21.1 的生成模板 livingentity.java.ftl 为例,每一条实体数据条目都会被翻译成一组 Java 代码:
-
声明同步数据访问器:根据条目值的运行时类型(
Integer/Boolean/String),生成对应的EntityDataAccessor常量,例如:public static final EntityDataAccessor<Integer> DATA_KillCount = SynchedEntityData.defineId(XxxEntity.class, EntityDataSerializers.INT);布尔值对应
EntityDataSerializers.BOOLEAN,字符串对应EntityDataSerializers.STRING(livingentity.java.ftl)。 -
注册默认值:在
defineSynchedData中把你在编辑器中设置的默认值绑定到对应的DATA_<NAME>上,从而保证客户端与服务端在实体初始化时拥有一致的初值(livingentity.java.ftl)。 -
提供过程块读写入口:MCreator 的过程(Procedure)系统为实体数据提供了专门的获取/设置过程块,它们通过
getEntityData().get(...)与getEntityData().set(...)读写同步数据。以整数为例(entity_data_integer_get.java.ftl):(entity instanceof XxxEntity _datEntI ? _datEntI.getEntityData().get(XxxEntity.DATA_KillCount) : 0)逻辑型与字符串型的过程块(如
entity_data_logic_set.java.ftl、entity_data_string_get.java.ftl)结构完全一致,仅序列化器与取值类型不同(entity_data_logic_set.java.ftl)。
这套机制正是 SynchedEntityData(同步实体数据)的典型用法:服务端修改后,数据会自动同步到所有客户端,因此帮助文档中「可用实体变量驱动客户端纹理切换」的场景由此实现——例如在 on tick update 过程中根据字符串变量值设置实体的渲染纹理。
类型选择的实战建议
- 只需表示两种状态时,选 Logic:布尔值语义最清晰,生成的代码最简洁,且默认值
false通常就能满足多数开关场景; - 需要计数或数值区间时,选 Integer:注意它只能存整数,小数需求(如百分比、速度倍率)在实体变量中不可用,应改用数值类过程块或另行设计;
- 需要文本内容时,选 String:纹理名、对话标签等场景,但要注意字符串在同步数据中的传输开销通常大于整数与布尔值,不宜存放大段文本;
- 命名规范:变量名必须为合法 Java 成员名且全局唯一,因为名称会直接拼接为
DATA_<NAME>静态字段,并成为过程块中field$accessor的取值来源。
小结
data_type 虽然只是实体变量配置中的一个小选项,却决定了变量在 JSON 工作区文件中的持久化形式、在 SynchedEntityData 中使用的序列化器(INT/BOOLEAN/STRING),以及过程块读写时的取值语义。理解「Logic / Integer / String」三者的区别,配合默认值设置,就能为自定义生物设计出可靠、可同步的客户端/服务端状态体系。更多相关帮助文档可参阅 data_name.md(变量命名)与 data_default_value.md(默认值规则),实现代码可继续阅读 PropertyData.java 与 livingentity.java.ftl。