BetterModel

BetterModel

BetterModel 是一个适用于 Minecraft Forge 1.20.1 的模组，可在游戏运行时从配置文件夹动态加载 Blockbench/Bedrock 格式的自定义动画 3D 模型并将其放置在世界中，无需重启游戏。

用途

在原版 Minecraft 和大多数模组中，要在世界中添加自定义动画模型，需要编写代码并重启服务器。BetterModel 解决了这个问题：只需将模型文件放入 config/bettermodel/ 文件夹，方块就会立即出现在游戏中。

该模组面向需要快速放置装饰性动画物件（雕像、传送门、装饰品等）的服务器管理员和内容创作者，无需修改代码，也不会导致服务器停机。

主要功能

• 运行时加载模型 – 模型、纹理和动画会在游戏运行时从 config/bettermodel/<name>/ 加载。只需添加一个包含文件的文件夹，即可立即选择其中的模型。
• 动画支持 – 支持动画纹理（.png.mcmeta）和 GeckoLib 动画（animation.json）。如果缺少 animation.json，模型仍会使用备用静态 idle 动画进行渲染。
• 发光 / 自发光 – 可选的 glowmask.png 文件可在主纹理上叠加发光遮罩，并能正确处理透明边缘（不会出现白色瑕疵）。
• 缩放 – 管理员可直接在游戏中调整模型大小：
  • Shift + 右键 – 放大模型
  • Shift + 左键 – 缩小模型
  • Shift + Alt + 右键 – 顺时针旋转
  • Shift + Alt + 左键 – 逆时针旋转
  • 无论模型尺寸如何，模型始终以方块为中心。
• 模型选择界面 – 管理员可右键点击方块打开模型选择菜单。模型列表会根据配置文件夹的当前内容生成。
• 热重载 – 每次打开界面时都会刷新模型列表，无需重启即可识别新文件夹。

模型文件夹结构

每个模型都应放在 config/bettermodel/ 下的独立子文件夹中。
文件夹名称会成为模型 ID，并显示在选择界面中。

config/
└── bettermodel/
    └── my_model/               ← 文件夹名称 = 模型 ID（可使用任意拉丁字母名称）
        ├── model.json          必需  — Bedrock/Blockbench 格式的几何数据
        ├── texture.png         必需  — 主漫反射纹理
        ├── animation.json      可选  — GeckoLib 动画文件（若缺少，则使用备用 `idle` 动画）
        ├── texture.png.mcmeta  可选  — 动画纹理帧数据
        └── glowmask.png        可选  — 自发光 / 发光遮罩叠加层

重要：文件名必须完全一致（在 Linux/Mac 服务器上区分大小写）。

粒子发射器方块

BetterModel 包含一个粒子发射器方块——一个可配置的粒子系统，可以发射从配置文件夹加载的自定义粒子。

主要功能

• 自定义粒子纹理——纹理在运行时从 config/bettermodel/particles/<name>/ 加载。支持多帧精灵图。
• 20 种内置粒子类型
• 5 种运动控制器
• 丰富的设置

GUI

右键点击粒子发射器方块（需要管理员等级 2+）以打开设置界面。
界面底部有一个设置文本框，显示所有当前设置序列化为 NBT 的内容。
你可以复制文本，粘贴到另一个发射器的文本框中，然后点击应用来传输完整配置。

用法

1. 从 BetterModel 的创造模式标签页中放置一个粒子发射器方块。
2. 右键点击打开设置 GUI。
3. 使用滑块和按钮调整类型、控制器、颜色、速度、扩散和其他参数。
4. 使用底部的复制 / 粘贴 / 应用按钮在方块之间共享配置。
5. 使用启用按钮切换发射状态。

解决的问题

安装

1. 安装 Minecraft Forge 1.20.1
2. 安装 GeckoLib 4.x for Forge 1.20.1
3. 将 BetterModel.jar 放入 mods/ 文件夹
4. 启动游戏 – config/bettermodel/ 文件夹将自动创建
5. 将你的模型添加到子文件夹并进入世界

用法

1. 从 BetterModel 的创造模式选项卡中放置一个模型方块
2. 右键点击方块（需要至少 2 级管理员权限）——将打开模型选择菜单
3. 从列表中选择所需的模型
4. 调整缩放：Shift + 右键（放大）/ Shift + 左键（缩小）
5. 旋转模型：Shift + Alt + 右键（顺时针）/ Shift + Alt + 左键（逆时针）

交互配置

你可以在 config/bettermodel/interaction.properties 中调整交互步长：

• rotation_step_degrees – Shift+Alt 点击操作的旋转步长。
• scale_step_percent – 仅按住 Shift 点击操作的缩放步长（百分比）。

依赖项

服务器安装

该模组可在独立服务器上完整运行：

• 方块设置保存在服务器上 – modelId 和缩放值会作为常规方块实体数据存储在区块的 NBT 数据中，并在服务器重启后保留。

• 模型文件必须位于服务器上 – 服务器只会读取 config/bettermodel/ 下的子文件夹名称，以生成 GUI 中的可用模型列表，并验证管理员选择是否有效。服务器不会加载或处理模型文件（model.json、texture.png 等）；这些文件仅供客户端渲染使用。

• 客户端也需要模型文件 – 要渲染模型，客户端的同一个 config/bettermodel/ 文件夹中也必须存在这些文件。文件不匹配时的行为如下：

  情况	结果
  服务器上有模型，但客户端没有	客户端看不到该方块，服务器数据不会损坏
  客户端上有模型，但服务器没有	该模型不会出现在 GUI 的可选列表中；如果 NBT 中已保存 modelId，客户端仍会显示该方块
  模型名称相同，但文件不同	服务器只保存名称——客户端会渲染自己的文件，因此视觉效果可能不同

• 权限 – 只有管理员（至少 2 级）才能选择和缩放模型；普通玩家无法更改方块设置。

• 模型首次渲染时会缓存在 GeckoLib 中；文件更改后会根据文件大小和修改时间自动更新。
• 动画纹理（.mcmeta）的处理独立于标准资源包。
• Glowmask 使用 RenderType.entityTranslucentEmissive，以正确处理 Alpha 通道。
• 方块数据保存在 NBT 中，并在服务器与客户端之间同步。