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).

File	Status	Description
`model.json`	Required	Bedrock/Blockbench geometry. Export from Blockbench as Bedrock Model
`texture.png`	Required	Main texture applied to the model
`animation.json`	Optional	GeckoLib animation file. Export from Blockbench as GeckoLib Animation. If absent, model uses fallback static `idle` animation
`texture.png.mcmeta`	Optional	Animated texture metadata (standard Minecraft `.mcmeta` format). Requires `texture.png` with all frames stacked vertically
`glowmask.png`	Optional	Glow/emissive overlay. Must be the same resolution as `texture.png`. Transparent pixels are treated as non-glowing areas

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

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

Problems Solved

Problem	Solution in BetterModel
Can't add custom models without code	Simply place files in `config/` - model is ready
Restart needed for model updates	Models are re-read on the fly when the GUI is opened
Static decorations in-world	Full GeckoLib animation support
No glow support without shaders	Built-in emissive layer with `glowmask.png`
Can't scale objects without code	Scale directly in the game using Shift + click

Installation

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

Usage

Place a Model Block from the Creative tab in BetterModel
Right-click the block (requires operator level 2+) - the model selection menu will open
Choose the desired model from the list
Adjust the scale: Shift + Right Click (larger) / Shift + Left Click (smaller)
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

Dependency	Version
Minecraft Forge	1.20.1-47.4.13+
GeckoLib	4.8.3 (forge-1.20.1)

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.