企业官网建设流程全解析

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

导读

本文围绕 MCreator 开源仓库中弹射物（Projectile）元素帮助文档所讲解的"弹射物模型（Projectile model）"参数展开，说明该参数在远程武器/弹射物元素中的实际作用、与纹理参数之间的覆盖关系，并结合源码与代码生成模板揭示其底层实现机制。读完本文，你将清楚掌握"默认模型 vs 自定义 Java 模型"的选择逻辑、自定义模型必须配套纹理的校验规则，以及该参数如何最终生成模组渲染代码。

参数定位：弹射物元素属性面板中的"Projectile model"

在 MCreator 中，弹射物元素（Projectile）用于创建远程武器发射出的投射实体。其属性面板包含发射物物品、模型、模型纹理、包围盒尺寸、伤害、击退等多项配置，其中"Projectile model（弹射物模型）"一项直接决定发射出去的那个实体在游戏世界里长什么样。

该参数的官方说明（即本文所依托的关联文档）原文如下：

• 英文版（plugins/mcreator-localization/help/default/projectile/model.md）：

  Projectile model is the model of your ranged item. This parameter will override item for texture parameter when used.

• 中文版（plugins/mcreator-localization/help/zh_CN/projectile/model.md）：

  这将是您的远程物品发射出去的弹射物的模型。当勾选此参数时，此参数将覆盖纹理参数项。

• 德文版（plugins/mcreator-localization/help/de_DE/projectile/model.md）：

  Projektil-Modell ist das Modell deines Fernkampfelements. Bei Verwendung dieses Parameters wird das Element für den Texturparameter überschrieben.

归纳起来，这一参数传达了两个核心事实：① 它定义的是远程物品发射出的弹射物实体的模型；② 一旦选用了非默认模型，它会覆盖（override）原本用于表示弹射物的"物品纹理"参数。

参数在 GUI 中的位置与形态

从源码看，该参数对应属性面板中的一个下拉选择框。在 ProjectileGUI.java 中，属性面板按顺序排列了三个相互关联的控件：

propertiesPanel.add(HelpUtils.wrapWithHelpButton(this.withEntry("projectile/item_texture"), L10N.label("elementgui.projectile.item_texture"))); propertiesPanel.add(PanelUtils.totalCenterInPanel(projectileItem)); propertiesPanel.add(HelpUtils.wrapWithHelpButton(this.withEntry("projectile/model"), L10N.label("elementgui.projectile.model"))); propertiesPanel.add(model); propertiesPanel.add(HelpUtils.wrapWithHelpButton(this.withEntry("projectile/model_texture"), L10N.label("elementgui.projectile.model_texture"))); propertiesPanel.add(customModelTexture);

即界面依次呈现"发射物物品（item_texture）→ 弹射物模型（model）→ 弹射物模型纹理（model_texture）"。其中model是一个基于SearchableComboBox<Model>的可搜索下拉框（ProjectileGUI.java）：

private final Model modelDefault = new Model.BuiltInModel("Default"); private final SearchableComboBox<Model> model = new SearchableComboBox<>(new Model[] { modelDefault });

下拉框的初始选项只有一个内置项"Default"。切换元素或刷新工作区时，MCreator 会从工作区的模型目录中读取可用模型并追加到下拉列表中（ProjectileGUI.java）：

ComboBoxUtil.updateComboBoxContents(model, ListUtils.merge(Collections.singletonList(modelDefault), Model.getModels(mcreator.getWorkspace()).stream() .filter(el -> el.getType() == Model.Type.JAVA || el.getType() == Model.Type.MCREATOR) .collect(Collectors.toList())));

这里可以看到关键过滤条件：只有JAVA类型（.java模型类）与MCREATOR类型（.mcm模型）的模型才会出现在候选列表中；而界面文案也明确标注了支持范围（texts.properties）：

elementgui.projectile.model=<html>Projectile model:<br><small>Supported: JAVA

两种状态：默认模型与自定义模型

状态一：Default（默认模型）

保持下拉框为默认的"Default"时，弹射物实体不使用独立的自定义几何模型，而是直接以你在"发射物物品"参数中选择的那个物品的样式来渲染。这一点在相邻的帮助文档中也有印证（item_texture.md）：

The item texture representing the projectile. It will look the same as the item selected here. For custom shapes, use the model parameter.

即"发射物物品纹理"决定了弹射物的外观，它看起来与你选择的物品完全一样；若要使用自定义形状，才需要改用模型参数。这也是文档所说"模型参数覆盖纹理参数"的对偶表述：默认情况下物品（及其纹理）充当弹射物模型，而一旦指定了自定义模型，模型就取代物品成为弹射物外观的来源。

状态二：自定义 Java 模型

选择工作区中的 Java 模型（或 MCreator 模型）后，弹射物将使用该模型的几何形状进行渲染，此时渲染纹理不再来自物品，而是来自紧随其后的"弹射物模型纹理（model_texture）"参数。

这一选择在数据模型中被持久化为字符串字段entityModel（Projectile.java），读取元素时通过getEntityModel()还原为模型对象：

@Override @Nullable public Model getEntityModel() { Model.Type modelType = Model.Type.BUILTIN; if (!entityModel.equals("Default")) modelType = Model.Type.JAVA; return Model.getModelByParams(getModElement().getWorkspace(), entityModel, modelType); }

当字段值不是"Default"时，模型类型即被判定为JAVA，并通过Model.getModelByParams(...)在工作区模型目录中查找对应文件（Projectile.java）。模型文件的查找逻辑见 Model.java：JAVA模型对应models/<name>.java（或按生成器兼容键放入子目录），MCREATOR模型对应models/<name>.mcm。

"覆盖纹理参数"的实质：生成链路中的证据

文档中"此参数将覆盖纹理参数项"这一描述，在代码生成链路中可以得到精确印证。查看 projectile.definition.yaml：

templates: - template: projectile/projectile.java.ftl name: "@SRCROOT/@BASEPACKAGEPATH/entity/@NAMEEntity.java" - template: projectile/projectile_renderer.java.ftl name: "@SRCROOT/@BASEPACKAGEPATH/client/renderer/@NAMERenderer.java" condition: isCustomModel()

只有元素处于"自定义模型"状态（isCustomModel()）时，才会额外生成专门的渲染器类（@NAMERenderer.java）；默认模型状态下不生成该渲染器，弹射物外观完全交由物品与物品渲染逻辑处理。这正是"自定义模型覆盖默认物品表现"的最直接代码证据。

而生成的渲染器正是把entityModel与customModelTexture两个字段拼接进代码（projectile_renderer.java.ftl）：

private static final ResourceLocation texture = ResourceLocation.parse("${modid}:textures/entities/${data.customModelTexture}"); private final ${data.entityModel} model; public ${name}Renderer(EntityRendererProvider.Context context) { super(context); model = new ${data.entityModel}(context.bakeLayer(${data.entityModel}.LAYER_LOCATION)); }

可见渲染器用${data.entityModel}作为模型类名进行实例化，并把${data.customModelTexture}作为纹理资源路径（位于textures/entities/目录下）绑定给该模型。因此：选择了自定义模型后，弹射物的几何形状来自模型字段，纹理来源则切换到 model_texture 字段，物品纹理不再参与弹射物渲染——这就是"覆盖纹理参数"在实现层面的含义。

与"弹射物模型纹理"参数的联动与校验

自定义模型并非选完就完事——它还要求必须配套纹理。紧跟模型参数之后的"Projectile model texture（弹射物模型纹理）"帮助文档（model_texture.md）说明：

This is the texture of the projectile model if custom model is used.

即该纹理仅在启用自定义模型时才生效。GUI 层面通过验证器强制保证两者配对（ProjectileGUI.java）：

customModelTexture.setValidator(() -> { if (!modelDefault.equals(model.getSelectedItem())) if (!customModelTexture.hasTexture()) return new ValidationResult(ValidationResult.Type.ERROR, L10N.t("elementgui.projectile.error_custom_model_needs_texture")); return ValidationResult.PASSED; });

• 当model选中的不是Default，且customModelTexture未指定纹理时，验证不通过并提示"Custom projectile model needs to have a texture"（自定义弹射物模型必须要有纹理）；
• 而纹理选择框本身被限定为实体类型纹理（TextureComboBox(mcreator, TextureType.ENTITY)，见 ProjectileGUI.java），对应数据字段customModelTexture上的@TextureReference(TextureType.ENTITY)注解（Projectile.java）。

这形成了完整的约束闭环：自定义模型 → 必须配实体纹理 → 纹理存放在textures/entities/下 → 渲染器按该路径加载。

默认值与初始化细节

entityModel与customModelTexture在元素默认初始化时均按"无自定义模型"处理：entityModel默认为"Default"，customModelTexture为空字符串。在集成测试中也可以看到两种分支的典型取值（TestWorkspaceDataProvider.java）：

projectile.entityModel = emptyLists ? "Default" : "ModelCustomJavaModel"; if (!emptyLists) { projectile.customModelTexture = "entity_texture_2.png"; } else { projectile.customModelTexture = ""; }

即默认分支为"Default"+ 空纹理，自定义分支为模型名 + 实体纹理文件名，与上述 UI 校验逻辑完全一致。

此外，旧版本 MCreator 中的"远程武器（RangedItem）"元素在迁移到新版弹射物元素时，也会把原bulletModel与customBulletModelTexture字段分别映射到entityModel与customModelTexture（RangedItemToProjectileAndItemConverter.java），说明该参数与纹理覆盖关系是一以贯之的设计。

实操建议与常见误区

1. 想让弹射物长得像某件物品（如箭、雪球）：保持"Projectile model"为 Default，只设置"发射物物品"即可，此时物品纹理自动充当弹射物外观。
2. 想让弹射物拥有独立的自定义外形：在"Projectile model"中选择工作区里的 Java 模型，并在"Projectile model texture"中指定对应的实体纹理，二者缺一不可，否则无法通过属性校验。
3. 纹理路径约定：自定义模型纹理需为实体类型纹理，生成后会落到textures/entities/<纹理名>.png，渲染器据此加载；模型文件则位于工作区models/目录。
4. 模型类型限制：弹射物模型下拉框只接受 Java（.java）与 MCreator（.mcm）模型，界面标注的支持类型为 JAVA；OBJ、JSON、Bedrock（.geo.json）等类型不适用于弹射物元素（相关模型类型定义见 Model.java）。

理解"Projectile model 覆盖物品纹理"这一规则，是配置弹射物外观的关键一步：它决定了你的弹射物究竟是"物品的化身"还是"独立建模的实体"，也决定了后续 model_texture 参数是否必须配置。

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