Minecraft Modding Diaries

An ever growing list of mod diaries/tutorials. They focus mainly on the development of my personal mods, but you may learn a thing or two about modding along the way.

Butterfly Mod


A journey developing the butterflies mod, a mod that adds butterflies to the world. There will be some butterfly themed surprises as the mod grows.


Getting Started
The Forge website has a quick guide to getting started with modding. I’m just getting back into it, so I thought I’d walk through the steps to get a project set up with Forge.


Butterflies Part 1: Entities
I’m developing my own version of a Butterfly mod for Minecraft. Naturally, one of the first features I want to implement are the butterflies themselves. To do this we need to add new entities to the game, along with models and renderers for the entity, and define how the entities will spawn in the game.


Butterflies Part 2: The rest of the @!#$ Owl
In Part 1 we coded a butterfly entity. Now we need to put the rest of the pieces together, so we can model, render, register, and ultimately spawn butterflies in our Minecraft world!


Regional Variety in Butterflies
Adding new textures to our implementation of butterflies is an easy way to add variety. However, we can strive to do better. Our ultimate goal is to have achievements for catching all butterfly varieties, but this becomes too easy when butterflies of all varieties can spawn anywhere.


Butterfly Nets: Gotta Catch ‘Em All
I mentioned in my last article that I wanted to add a collectible element to my butterfly mod. In order to do that we need a way to catch said butterflies. So the next step is to implement a butterfly net. With the latest change we can now craft butterfly nets that can be used to catch (and release) ’em all.


How to Upgrade a Forge Mod
Minecraft version 1.20.1 has been out for a while now, and a stable version of Forge has been released for it. So it’s time to update our mod to run in the latest version of Minecraft. That way we’ll be able to use the Butterflies mod with the fancy new features of Minecraft.


Bottling Butterflies in a Jar
Butterfly nets can only hold one butterfly at a time, and we can’t do anything with them once caught. We will add a new way to interact with them: moving them to jars so they can be put on display. This adds something we can do with butterflies, as well as another “catch ’em all” element to the mod.


Laying Butterfly Eggs in Leaves
Butterflies lay eggs that eventually become caterpillars. Caterpillars then feed on leaves until they are fat enough to become a chrysalis. Finally, they morph into a butterfly before breaking out of the chrysalis. The next step for our mod is to implement butterfly eggs.


Modelling and Animating Caterpillars
Everyone knows that butterflies come from caterpillars. The next stage in the life cycle is for butterfly eggs to hatch into caterpillars. So we will add caterpillars to our mod that will hatch from the eggs we created last time.


Cleaning Out the Butterflies Backlog
During any development it’s inevitable that you introduce bugs or leave minor tasks behind. The Butterflies Mod is no exception. We have a list of small details that are incomplete, as well as some bugs we’ve picked up on while testing. This week we try to clear out that list.


Multi-Directional Caterpillars
Caterpillars will always spawn on top of a leaf block. We want to give a bit more variety in our caterpillar behaviour. So we modify caterpillars so that they can crawl on any side of a leaf block. It’s a small detail, but took a decent amount of time to develop.


Chrysalis: Completing the Cycle
We finally implement the chrysalis and complete the life cycle of the butterfly. Butterflies lay eggs. Eggs hatch into caterpillars. Caterpillars create a chrysalis. Butterflies hatch out of a chrysalis. The circle of life is complete.


Cats: The Butterfly’s Natural Enemy
I wanted to have some interaction between butterflies and vanilla entities to make them feel like part of the Minecraft world. An easy way to have an entity interact is to make butterflies the target of a predator. Our furry friends seemed like the best candidate for this.


Releasing the Butterflies
We are on the road to release! This week I finally finished the first version of the mod and have pushed an official version of my mod out to the world. It’s taken me a while, but I finally have this simple butterfly mod out in the wild.


Forks, Branches, and Scrolls
I’ve finally released the butterfly mod, but I’m still not done. Now I’m working on the next release which will have a few extra features. This week I’ve been working on Butterfly Scrolls – a new way to create a collection of butterflies.


Pinning Up Butterfly Corpses
I’ve always struggled to get my head around modern day rendering code. There’s a reason I became a network and server programmer. Still, I managed to get this working in the end. Though I’m sure my computer knows many more swear works now…


Screwing Up the Life Cycle
Well, I screwed up. It turns out a major selling point of Bok’s Butterflies wasn’t working at all. The life cycle of the butterflies wasn’t working at all. It all boils down to a misunderstanding on my part. So this week I have a new release that fixes this feature.


It’s All About the Little Things
It’s always worth taking some time to focus on the details. Small things can make a huge difference to a mod. I spent some time this week working on small features and little improvements. In the long run, these things will make a huge difference.


Updating the Butterfly Stats
I’ve been playing a game with the mod installed for a while now, and there are a few things I want to improve upon. First, I wanted to tweak the butterflies a bit to add some extra variety. Second, I’ve noticed that butterflies tend to grow in population exponentially.


Books With Butterflies In Them
I’ve finished the last feature and released version 2 of the mod. The last feature I implemented was a book where you can store butterflies and gain information about them. The book has dynamically generated content, depending on which butterflies you store inside it.


Backporting for Pain and Profit
I spent this week tidying up some little issues with the mod here and there. I had a couple of small requests and bug reports over Christmas which I added to my backlog.


ItemCraftedEvent Doesn’t Do What You Think
I got a bug reported near the beginning of the month about recipes not working properly. Shift-clicking on one of the custom recipes would cause a whole bunch of useless items to be created.


Small Eggs and Better Buckeyes
I’ve talked about how details matter before. So this week I’ve focused on a couple of things that have been bugging me for a while now. These aren’t major features, but they do help to make the mod feel like it’s been crafted by someone who cares.


Data Driving the Butterflies
Finally! Butterfly data can now be loaded or modified via a JSON file. Now if we decide to change how butterflies work we don’t need to change any code. Even a data pack could be used to change butterfly behaviour.


Improving Caterpillar Interaction
This week I’ve been focusing on improving caterpillars. Right now they are very hard for players to come across. However, with a few extra features and tweaks, caterpillars will be just a little bit more interesting.


Naturally Spawning Caterpillars
Originally the butterfly mod was supposed to be a simple mod that adds butterflies to the world. It’s growing a little beyond that, with the butterflies actually having a complete life cycle. Unfortunately it’s actually pretty rare that a player will stumble upon a caterpillar right now.


Let’s Bottle Caterpillars!
I’ve been focusing a lot on caterpillars these last few weeks, and a thought occurred to me. Wouldn’t it be cool to have bottles with caterpillars in as well.


Syncing the Butterfly Data
After releasing version 3.0.0 of the mod, I got a bug report in very quickly. Butterflies were no longer spawning in server games. I hadn’t really been testing servers up to that point, but as it turns out that didn’t mean people weren’t using the mod on servers.


Keeping Their Numbers Down
Butterflies have been taking over. There have been reports that thousands have been spawning, overwhelming servers and lagging out game worlds. So I have spent a large portion of this week working to reduce the butterfly population and ensure that Minecraft servers remain safe.


Butterfly Eggs Done Right
Early on in the mod’s development I made a couple of missteps. I was less experienced and didn’t fully understand how Minecraft works, so I made some design choices that have proven to be problematic.


200 Files and Nothing New
This week I merged a change consisting of over 200 files. It’s probably the largest change I’ve made since the project began, and yet it doesn’t actually introduce anything new. Instead, it fixes a mistake I made when I first created the mod.


Improving Quality of Life
This week I add a lot of quality of life improvements to the mod, as well as a bug fix. There aren’t really any major new features, but the mod is now a little easier to use, and is now compatible with mods that add custom biomes to Minecraft.


Upgrading Butterflies to NeoForge
Changes are on the horizon for the Minecraft Modding community. While I don’t fully understand all the drama, Forge may be on its way out, making NeoForge the new way of making mods. In order to prepare for this new world, I’ve decided to create a 1.20.4 version.


Adding the Peacock Butterfly
I plan to add more butterflies in the future, so I wanted to gauge how much work that would be. This can also serve as a step-by-step to adding new butterfly species to the mod. So I’m adding a 17th variant: the Peacock Butterfly.


Generating More Butterfly Data
This week I focused on improving data generation for the mod. This doesn’t add any new features to the mod, however it does mean that adding new features to the mod will be much easier in the future. And being able to iterate new features faster is always a bonus.

Older Diaries


These are older diaries and tutorials that aren’t part of the main series I’m working on. You might still find these useful, however.


How to Learn Minecraft Modding
Some advice on how to go about learning how to mod minecraft (or learn anything, really).


Setting up a Development Environment for Forge Modding
An older tutorial on how to set up a development environment.


Data Driving Minecraft
Some old ideas on how to add more data driven assets to Minecraft.


Data Driven Donuts
How I used data to add donuts to Minecraft.