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.

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!