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），用于其他需要小数数值的属性场景；而实体变量的新增对话框中仅开放上述三种类型。

配置步骤：在生物编辑器中新增实体变量

1. 打开生物（Living Entity）编辑器，找到「实体数据」（Entity Data / 实体数据条目）面板；
2. 点击添加条目按钮（源码中对应JEntityDataList的「Add entry」按钮，JEntityDataList.java），弹出「新增实体属性」对话框；
3. 在Name（名称）输入框中填写变量名。该名称会经过校验器实时校验（AddEntityPropertyDialog.java）：
   • 必须是合法的 Java 成员名（JavaMemberNameValidator）；
   • 不能与当前实体已有的变量重名（UniqueNameValidator）；
   • 名称将直接参与生成DATA_<NAME>这样的 Java 字段名，因此建议使用大写字母开头的标识符，例如Angry、KillCount；
4. 在Type（类型）下拉框中选择Integer、Logic或String（AddEntityPropertyDialog.java）；
5. 点击确定后，条目会出现在实体数据列表中，此时可在Default value（默认值）处设置该变量初始值（JEntityDataEntry.java）；
6. 变量定义保存在生物元素的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 代码：

1. 声明同步数据访问器：根据条目值的运行时类型（Integer/Boolean/String），生成对应的EntityDataAccessor常量，例如：

   public static final EntityDataAccessor<Integer> DATA_KillCount = SynchedEntityData.defineId(XxxEntity.class, EntityDataSerializers.INT);

   布尔值对应EntityDataSerializers.BOOLEAN，字符串对应EntityDataSerializers.STRING（livingentity.java.ftl）。

2. 注册默认值：在defineSynchedData中把你在编辑器中设置的默认值绑定到对应的DATA_<NAME>上，从而保证客户端与服务端在实体初始化时拥有一致的初值（livingentity.java.ftl）。

3. 提供过程块读写入口：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。

• 低代码
• 代码生成
• 桌面应用
• 游戏开发