BetterModel

BetterModel is a Minecraft Forge 1.20.1 mod that allows placing custom animated 3D models in the world in Blockbench/Bedrock format, loaded dynamically from the config folder during runtime without restarting the game.

Purpose

In vanilla Minecraft and most mods, adding a custom animated model to the world requires writing code and restarting the server. BetterModel solves this problem: simply place model files in the config/bettermodel/ folder, and the block will appear in-game immediately.

This mod is aimed at server administrators and content creators who need to quickly place decorative animated objects (statues, portals, decorations, etc.) without editing code or causing server downtime.

Key Features

• Runtime model loading - models, textures, and animations are loaded from config/bettermodel/<name>/ during runtime. Simply add a folder with files, and the model is available for selection right away.
• Animation support - animated textures (.png.mcmeta) and GeckoLib animations (animation.json) are supported. If animation.json is missing, the model still renders using fallback static idle animation.
• Glow / Emissive - optional glowmask.png file provides a glow mask on top of the main texture, working correctly with transparent edges (no white artifacts).
• Scaling - operators can change the model size directly in the game:
  • Shift + Right Click - increase scale
  • Shift + Left Click - decrease scale
  • Shift + Alt + Right Click - rotate clockwise
  • Shift + Alt + Left Click - rotate counter-clockwise
  • The model remains centered on the block at any size.
• Model selection GUI - operators open the model selection menu by right-clicking the block. The list of models is pulled from the current state of the config folder.
• Hot-reloading - the model list is refreshed when opening the GUI, picking up new folders without restarting.

Model Folder Structure

Each model is a separate subfolder inside config/bettermodel/. The folder name becomes the model ID that is shown in the selection GUI.

config/
└── bettermodel/
    └── my_model/               ← folder name = model ID (any Latin name)
        ├── model.json          required  — geometry in Bedrock/Blockbench format
        ├── texture.png         required  — main diffuse texture
        ├── animation.json      optional  — GeckoLib animation file (if absent, fallback `idle` is used)
        ├── texture.png.mcmeta  optional  — animated texture frame data
        └── glowmask.png        optional  — emissive / glow-mask overlay

Important: file names must match exactly (case-sensitive on Linux/Mac servers).

Particle Emitter Block

BetterModel includes a Particle Emitter block — a configurable particle system that can emit custom particles loaded from the config folder.

Key capabilities

• Custom particle textures — textures are loaded from config/bettermodel/particles/<name>/ at runtime. Supports multi-frame sprite sheets.
• 20 built-in particle types
• 5 movement controllers
• Rich settings

GUI

Right-click the Particle Emitter block (requires operator level 2+) to open the settings screen.
At the bottom of the screen there is a settings text field that shows all current settings serialised as NBT.
You can copy the text, paste it into another emitter's field, and click Apply to transfer the full configuration.

Usage

1. Place a Particle Emitter block from the Creative tab in BetterModel.
2. Right-click to open the settings GUI.
3. Adjust type, controller, colour, speed, spread, and other parameters using the sliders and buttons.
4. Use the Copy / Paste / Apply buttons at the bottom to share configurations between blocks.
5. Toggle emission with the Enable button.

Problems Solved

Installation

1. Install Minecraft Forge 1.20.1
2. Install GeckoLib 4.x for Forge 1.20.1
3. Place BetterModel.jar in the mods/ folder
4. Launch the game - the config/bettermodel/ folder will be created automatically
5. Add your models to subfolders and enter the world

Usage

1. Place a Model Block from the Creative tab in BetterModel
2. Right-click the block (requires operator level 2+) - the model selection menu will open
3. Choose the desired model from the list
4. Adjust the scale: Shift + Right Click (larger) / Shift + Left Click (smaller)
5. Rotate the model: Shift + Alt + Right Click (clockwise) / Shift + Alt + Left Click (counter-clockwise)

Interaction Config

You can tune interaction steps in config/bettermodel/interaction.properties:

• rotation_step_degrees - rotation step for Shift+Alt click actions.
• scale_step_percent - scale step in percent for Shift-only click actions.

Dependencies

Server Installation

The mod works fully on dedicated servers:

• Block settings are saved on the server - modelId and scale are stored in the chunk's NBT data as regular BlockEntity data and survive server restarts.

• Model files must be on the server - the server only reads subfolder names from config/bettermodel/ to build the available models list for the GUI and verify correct operator selection. The server does not load or process model files (model.json, texture.png, etc.) - they are needed only by the client for rendering.

• Client needs models too - to render models, the files must be present on the client in the same config/bettermodel/ folder. Behavior in case of mismatch:

  Situation	Result
  Model is on the server, but not on the client	The block is invisible to the client, server data is not corrupted
  Model is on the client, but not on the server	The model is unavailable for selection in the GUI; if modelId is already saved in NBT — the block is displayed on the client
  Models are named the same, but files differ	The server stores only the name — the client renders its own files, the visual result may differ

• Permissions - model selection and scaling are only available to operators (level 2+), regular players cannot change block settings.

• Models are cached in GeckoLib upon first render and are automatically updated when files change (based on file size and modification time).
• Animated textures (.mcmeta) are processed independently from the standard resource pack.
• Glowmask uses RenderType.entityTranslucentEmissive for correct alpha channel handling.
• Block data is saved in NBT and synchronized between the server and client.