Liang Zhu: Butterfly Lovers

There is a Chinese fairy tale about the two lovers Liang Shanbo (梁山伯) and Zhu Yingtai (祝英臺), doomed to never be together. Liang Shanbo dies of a broken heart, and Zhu Yingtai throws herself into his grave to join him. Their spirits rise as butterflies, and they fly away, together for all eternity.

I’ve always wanted the butterfly mod to have a bit more character and world building. I’m hoping to achieve this by bringing in real life myths to the game in various ways. Last week, I added the Féileacáin of Irish Folklore to Bok’s Banging Butterflies. This week I want to add something based on the story of the Butterfly Lovers. Known as Liang Zhu after the titular characters, it is a well known story in China.

This will be a new structure that will randomly spawn in forests: the grave of Liang Shanbo and Zhu Yingtai. If the player digs out the grave, they will find two Féileacáin, the souls of the doomed lovers. This provides a small bit of worldbuilding, and gives players something a little mysterious to discover as they explore their worlds. It also gives them another way to obtain these extremely rare butterflies.

Design

I wanted to keep the grave site simple, made from wood rather than stone. I also wanted it to use Chinese characters, but unfortunately they don’t render out correctly in non-Chinese versions of the game. So I made a simple wooden structure with their names written in pinyin, a method of writing Mandarin using the latin alphabet.

On the grave I placed a Lily of the Valley, since white flowers are used to symbolise death and mourning in China. Underneath the grave I hid the two bottles containing the Féileacáin, representing the spirits of the lovers.

The end result is a very simple structure that can appear at random as players explore the world. I use the structure blocks to save out an NBT file, and now it’s time to make it actually spawn in the world.

JSON Files

I found a great tutorial by TelepathicGrunt to help me set up the world generation so that the grave will appear in the world. You can actually add new structures to the games without writing a single line of Java – it’s all data driven.

The five files we need for this are as follows:

The NBT file, created using structure blocks.
A tag to specify the biomes the structure can spawn in.
A structure to set how the structure interacts with the terrain.
A structure set that specifies how often the structure appears.
A template pool with a list of structure pieces, which in our case is only one piece.

I won’t go into detail on every parameter in every JSON file, but I’ll link to the files in TelepathicGrunt’s tutorial that goes into detail. I’ll just highlight the important parts.

NBT File

The NBT file is created when you use a structure block. To find it, look under your game’s /saves/ folder for the map you built the structure inside and then under the /generated/ folder. Moving it to your mods /data/structures/ folder allows it to be used in the mod.

Biome Tag

The Biome Tag is just a list of biomes. You can put anything in here. I want the grave to appear in forests, so I just use the #minecraft:is_forest tag and nothing else here.

{
  "replace": false,
  "values": [
    "#minecraft:is_forest"
  ]
}

Structure

The structure file specifies what template pool to use (see below), and how it interacts with the surface of the world. I don’t need to change much about this file, except for removing the custom spawns, and changing the size to 1, since there will only be one piece in this structure.

{
  "type": "minecraft:jigsaw",
  "start_pool": "butterflies:liangshanbo_grave/start_pool",
  "size": 1,
  "max_distance_from_center": 80,
  "biomes": "#butterflies:has_structure/liangshanbo_grave",
  "step": "surface_structures",
  "terrain_adaptation": "beard_thin",
  "start_height": {
    "absolute": 0
  },
  "project_start_to_heightmap": "OCEAN_FLOOR_WG",
  "use_expansion_hack": false,
  "liquid_settings": "apply_waterlogging",
  "spawn_overrides": {},
  "pool_aliases": []
}

Structure Set

The structure set file tells the game how often to try and spawn the structure, and how far apart they need to be. I increase the spacing and separation from the example, since I want the grave to be a relatively rare spawn. It’s rarity will add to its mysterious nature, as players won’t come across it too often.

{
  "structures": [
    {
      "structure": "butterflies:liangshanbo_grave",
      "weight": 1
    }
  ],
  "placement": {

    "type": "minecraft:random_spread",
    "salt": 94425281,
    "spacing": 16,
    "separation": 12
  }
}

Template Pool

These can get complicated, but since this structure is simple I only need one file, the start pool. This file references the actual NBT so the game knows what structures to place. I use terrain_matching for the projection, since this isn’t a rigid building, and it looks nicer if it blends with the surrounding terrain. Blending it like this will make it seem like a natural part of the forest.

{
  "fallback": "minecraft:empty",

  "elements": [
    {
      "weight": 1,
      "element": {
        "location": "butterflies:grave/liangshanbo_grave",
        "processors": "minecraft:empty",
        "projection": "terrain_matching",
        "element_type": "minecraft:single_pool_element"
      }
    }
  ]
}

In-Game

Now I can run the game and test the new structure. Since it’s pretty rare and limited to specific biomes, it can be hard to find by just playing the game. Thankfully we can just use Minecraft’s /locate command to find the nearest grave.

Before I took some screenshots I set the time to night, hoping to get that eerie atmosphere as you come across the grave. That’s when I realised that the design of the grave made it glow in the dark, since stairs don’t block light.

I actually really liked this effect, so I decided to keep it that way to potentially create a new experience. Players wandering the forest at night may spot something glowing. Maybe they’ll assume it’s a lava pool. But as they get close they’ll stumble upon this mysterious glowing grave, a subtle reminder of love persisting even after death. Players may be torn between disturbing the grave to claim the butterflies or leaving it untouched—a choice that adds a new layer of player-driven storytelling.

In the same way myths give meaning to our world, this feature brings a layer of wonder and mystery to Minecraft, letting players uncover ancient tales amidst familiar landscapes