BetterItem

BetterItem is a Minecraft Forge mod for Minecraft 1.20.1 that lets you add custom items to the game without writing a single line of code - just drop texture files into a config folder and launch the game.

All items are registered dynamically at startup, appear in a dedicated BetterItem creative tab, and support custom display names and tooltips via standard language files.

How It Works

On every game launch BetterItem scans the folder

.minecraft/config/betteritem/textures/

Every .png file found there becomes a registered item. The item's registry name is derived directly from the file name (lowercased, special characters replaced with _).

If the textures folder is empty on the first launch, a placeholder dummy item is created automatically so the mod can start without errors.

Config Folder Structure

.minecraft/ └── config/ └── betteritem/ ├── textures/ ← item textures (required) │ ├── my_item.png │ └── my_item.png.mcmeta ← optional animation metadata ├── models/ ← optional custom item models │ └── my_item.json └── lang/ ← optional display names & tooltips ├── en_us.json └── ru_ru.json

Supported Files

textures/ - Item Textures (required)

File Description <item_name>.png The item texture. The file name (without .png) becomes the item's registry ID. <item_name>.png.mcmeta (Optional) Animation metadata for animated textures (standard Minecraft .mcmeta format).

Rules for file names:

• Only lowercase Latin letters, digits, ., _, /, and - are allowed.
• Other characters are automatically replaced with _.
• File names must be unique - duplicate names (after sanitisation) will cause a startup error.

models/ - Item Models (optional)

File Description <item_name>.json A custom item model JSON. If absent, a standard item/generated model is generated automatically, using the texture from textures/.

Auto-generated model (used when no .json is provided):

{ "parent": "minecraft:item/generated", "textures": { "layer0": "betteritem:item/<item_name>" } }

lang/ - Translations (optional)

File Description en_us.json English display names and tooltips. ru_ru.json Russian display names and tooltips (or any other locale).

Format:

{ "item.betteritem.<item_name>": "Display Name", "tooltip.item.betteritem.<item_name>": "Tooltip text shown on hover" }

Minecraft color/formatting codes (§c, §6, §7, etc.) are supported inside the strings.

Example:

{ "item.betteritem.ancient_rune": "§6Ancient Rune", "tooltip.item.betteritem.ancient_rune": "§7Older than time itself..." }

If no translation is provided for an item, Minecraft displays the raw translation key as a fallback.

Adding a New Item - Step by Step

1. Prepare a texture - create a PNG image (recommended 16×16 or 32×32 pixels).

2. Name the file using only lowercase letters, digits, and underscores, e.g. solar_crystal.png.

3. Place the texture in:

.minecraft/config/betteritem/textures/solar_crystal.png

1. (Optional) Add a custom model to:

.minecraft/config/betteritem/models/solar_crystal.json

Skip this step to use the auto-generated flat 2D model.

1. (Optional) Add display names and a tooltip to the appropriate language file(s):

.minecraft/config/betteritem/lang/en_us.json { "item.betteritem.solar_crystal": "Solar Crystal", "tooltip.item.betteritem.solar_crystal": "§7Radiates warm light." }

1. (Optional) Add animation - place an .mcmeta file next to the texture:

.minecraft/config/betteritem/textures/solar_crystal.png.mcmeta { "animation": { "frametime": 4 } }

1. Launch (or restart) Minecraft. The item will appear in the BetterItem creative tab.

Multiplayer / Server

BetterItem synchronises item lists between the server and the client on login. Both sides must have identical textures, otherwise the connection is rejected with a detailed mismatch message listing exactly which items are missing on the client or the server.

Notes

• Items are display-only by default - they have no special functionality beyond appearing in inventories and being obtainable via creative mode or commands (/give @s betteritem:<item_name>).
• The mod creates the textures/ folder automatically on first launch if it does not exist.
• Removing a texture file and restarting the game will unregister that item.