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.

When I was porting the mod to NeoForge I was helped by modder calling themselves vadis365. When they learned what mod I was working on, they showed me a picture of a butterfly they had recently come across. It was a peacock butterfly, and I thought that it would be fun to add this species to Bok’s Butterflies.

It was also a good exercise to see how much work it is to add a new butterfly. I’ve already sped the process up a little using a simple python script, but I’m sure there are other ways the process could be improved. So here I am documenting all of the things I needed to do in order to implement all 933 changes for this new butterfly species.

GUI Textures

ButterflyTextures.java contains a list of all the textures used by the GUI when displaying butterfly scrolls. We need to add a reference to the new peacock texture to be used here, otherwise the screen will index out of bounds when a scroll is used.

Since we can just use the butterfly species name, this is screaming to be generated rather than hardcoded. There’s a new issue on the backlog to track this change.

Registries

We need to register new entities, items, and blocks to work with each new caterpillar species. Each new butterfly will need the following.

Block

• Bottled Butterfly
• Bottled Caterpillar

Entity

• Butterfly
• Caterpillar
• Chrysalis
• Egg
• Renderers
• Attributes
• Spawn Placements

Item

• Butterfly Net
• Bottled Butterfly
• Bottled Caterpillar
• Butterfly Scroll
• Egg
• Caterpillar
• Spawn Eggs (Butterfly and Caterpillar)
• Accessor Helpers
• Creative Tab Contents

It feels like this code could be made more generic, meaning we would have to write as much code manually when we add a new butterfly. This issue will track our progress improving this part of the mod.

Entity IDs

Each new block, entity, and item needs a unique entity ID. These are hardcoded constants in each class that represents these objects, and they all need an extra entry added for each new species.

• Bottled Butterfly Block
• Bottled Caterpillar Block
• Butterfly Entity
• Butterfly Egg Entity
• Caterpillar Entity
• Chrysalis Entity
• Bottled Butterfly Item
• Bottled Caterpillar Item
• Butterfly Egg Item
• Butterfly Net Item
• Butterfly Scroll Item
• Caterpillar Item

These all follow a basic pattern, so should be easy to generate. I’ve added a new issue to track progress with this improvement.

Creation Methods

Entities need creation methods added in order to help with their creation during registration.

• Butterfly Entity
• Butterfly Egg Entity
• Caterpillar Entity
• Chrysalis Entity

I’m not sure if these can be generic enough that we can remove these completely, but I’m going to try.

Filling the Butterfly Book

The total number of entries needed to fill a Butterfly Book needs to be increased, from 16 to 17 in this case. This is hardcoded, so needs to be changed manually.

This just shouldn’t be hardcoded at all. We can fix this one easily.

Generating Data

Butterflies use a lot of data. Thankfully, we can now generate most of this data by simply adding to our generate_butterfly_files.py and running the script. This saves us a lot of work, but unfortunately there is still a bit to do after this.

Localisation

Localisation strings are not generated so we have to add these manually. We just make sure all of the item names are there, and add an interesting fact that can be displayed in Butterfly Books for the new butterfly.

We can definitely make improvements here and reduce the amount of work we need to do.

Textures

Each species needs a specific set of textures. There is no getting around this, we need to manually create textures for each one.

• Butterfly Entity
• Caterpillar Entity
• Chrysalis Entity
• Butterfly Scroll GUI
• Bottled Butterfly
• Bottled Caterpillar
• Butterfly Egg
• Butterfly Scroll Item
• Caterpillar Item

Advancements

Many advancements involve collecting one or more butterfly, caterpillar, etc. For completeness we need to add our new species to each of these advancements manually, since they are not generated.

This is using JSON, so we should be able to generate these advancements.

Butterfly Data

We do get a butterfly data JSON file generated, however it should be edited to reflect the new species. This is the reason I made sure the script doesn’t overwrite files if they already exist – our changes will remain even if we were to run the generator again.

Biome Modifiers

If we want our butterflies to spawn, we need to add them to our biome modifiers. This is a fairly simple copy/paste job. It requires a bit too much thought to be automated, so even if we make some of the other changes in this blog, we will still have to write our spawn rules manually.

Frog Food

Finally we need to add our species to the list of food that frogs can eat.

This is so easy to autogenerate.

Next Steps

Having gone through this process, I’ve been able to identify areas where I could just generate a lot of this boiler plate code and data rather than having to implement it manually. Long term I’m planning to add several more species, so I’m going to work through some of the issues I talked about first.

Hopefully by the end it will be trivial to add a new species to the mod. But we’ll see!