Raid Wave Datapack Configuration

DifficultRaids allows you to fully customize Raid waves using Datapacks. This includes what raiders can spawn, what wave they spawn on, how many spawn per wave, and how many waves are in a Raid based on the Level difficulty.

Before jumping into the configuration options: If you're unfamiliar with the basics of datapacks, please check out the guide on the Minecraft wiki. The rest of this page will focus on the DifficultRaids-specific JSON files, and assumes you know how to create and load datapacks into a Minecraft world already.

Overall JSON Organization

Datapacks must be in a directory following this format: data/id/raids/, where id can be your datapack's ID, a mod ID, or difficultraids. Creating datapacks in the data/difficultraids/raids folder vs some other path has a special meaning, which will be touched on later.

The names of the individual JSON files can be whatever you want. Ideally, you'd include the name of your mod/datapack and the Raid Difficulty, to make it easier for others to understand what each file contains, and for debugging, but it's entirely up to you.

Note: If multiple datapacks are loaded, and some files share the same path and JSON name, they will be merged on launch. Merging will cause the file loaded later to overwrite previously-loaded files. This can cause unexpected behavior, so unless you are intending to overwrite another datapack/mod's JSON file, please try to use a unique path for your JSON files.

Example: Say I'm creating a Datapack called "Better Difficult Raids". I would store my JSON edit files in data/betterdifficultraids/raids/. An example path for one JSON file could be data/betterdifficultraids/raids/bdr_hero.json.

Creating a JSON

Here's an example of a JSON file:

{
  "difficulty": "HERO",
  "values": [
    {
      "raider_type": "VINDICATOR",
      "wave_counts": [0, 2, 1, 1, 2, 3, 1, 2]
    },
    {
      "raider_type": "PILLAGER",
      "wave_counts": [0, 4, 3, 3, 4, 5, 5, 3]
    }
  ]
}

Let's go through each field and what's going on.

First, the difficulty field sets the target Raid Difficulty for any edits you make in this file. In the example above, the changes are targeting Hero Raids. Valid values are HERO, LEGEND, MASTER and GRANDMASTER, for each of the Raid Difficulties.

Next up is the values field. This is a list of raider entry objects, containing all the raider types you'd like to make changes for. Each individual raider entry looks like this:

{
      "raider_type": "PILLAGER",
      "wave_counts": [0, 4, 3, 3, 4, 5, 5, 3]
}

The raider_type field is the Raider ID that a raider is registered as. Be careful, this is NOT THE REGISTRY ID! As shown above, the correct entry for the field is "PILLAGER", NOT "minecraft:pillager". A list of the raider types DifficultRaids has added implicitly can be found here. These can be copied directly if you want to edit one of those raiders.

THE RAIDER TYPE IS CASE SENSITIVE! Be sure that you are using the correct ID for the raider you are editing, including the case. If I had written "pillager" instead of "PILLAGER", then effectively the edit would be completely ignored because no raider is registered under the "pillager" raider type. It won't cause any crashes or issues in-game, but your edit won't be applied.

If you're a mod author, this is the ID (the first parameter) you use when adding your mobs to Raids. The line of code looks similar to:

Raid.RaiderType.create("PILLAGER", EntityType.PILLAGER, new int[]{0, 4, 3, 3, 4, 5, 5, 3});

If you're a datapack/modpack author, feel free to check out the DifficultRaids registry class here if the raider you're editing has been implicitly added, or look for the above line of code in the mod's source code. If the mod is not open source, then you'll have to contact the mod author for this information.

The wave_counts field is the number of the raider you specified that will spawn in each wave of the Raid. The first number in the list must be 0. Minecraft does this such that the index of the wave count lines up with the wave number. The raiders that spawn in the 1st wave will use the number in index 1 of the list, for example (if you're not familiar with programming, list indices start at 0, so index 1 is the 2nd element in the list). If you put any other number, it'll just get ignored (like the 0 does).

In the Pillager example above, I've inputted this for the wave_counts: [0, 4, 3, 3, 4, 5, 5, 3]. This means 4 Pillagers will spawn on wave 1 of a Hero raid.

Another thing to note: the difficulty of the Level (Easy, Normal, Hard) is what determines the number of waves in a Raid. You can make the wave_counts list as long as you want, but the number will only be used if that number of waves spawns. The number of waves per difficulty can be edited in the general.toml config file for DifficultRaids. For example, if I started an Easy Raid (which spawns 3 waves by default), then wave counts in indices past 3 would not be read since the Raid ends at wave 3.

Along those lines, if the list is made to be shorter than the wave count (for example, you're on an Easy Raid, but the list only has 2 elements, meaning only an entry for wave 1), then one of two things can happen. The behavior for this can be edited in the general.toml config file.

• Overflow Mode ZERO: If a raider does not have an entry for the current wave, then it will be treated like there's a 0 in that spot, and the raider will not spawn.
• Overflow Mode REPEAT: If a raider does not have an entry for the current wave, then it will use the number for the last entry in the list, and spawn that many times.

This may sound complicated! Let's go through an example.

{
      "raider_type": "PILLAGER",
      "wave_counts": [0, 4, 3]
}

Given this raid entry, we can see that there's entries for Waves 1 and 2. If I were to start an Easy Raid, and the overflow mode config option was set to ZERO, then no Pillagers would spawn on Wave 3. If the config option was set to REPEAT, then 3 Pillagers would spawn on Wave 3 (as that is the last entry in the list).

Replacer vs Modifier JSON Files

The final bit of information is whether a JSON file is flagged to be a replacer or a modifier. I briefly hinted at this at the start of this page.

ALL JSON FILES in the data/difficultraids/raids/ directory are considered replacers. All JSON files in any other directory of the format data/id/raids/ (where id is not difficultraids) are considered modifiers.

So what's the difference?

Replacer files will replace the DifficultRaids wave counts for a given difficulty. For example, let's take the example of what DifficultRaids defines for Pillager spawns on Legend difficulty: [0, 4, 3, 3, 4, 5, 5, 3]. Given this datapack JSON (registered under data/difficultraids/raids/hero.json:

{
  "difficulty": "HERO",
  "values": [
    {
      "raider_type": "PILLAGER",
      "wave_counts": [0, 2]
    }
  ]
}

This would completely replace the internal spawn counts given for Pillagers on Legend, and make it [0, 2].

Modifier files will add or subtract the input wave counts from the default. This means negative numbers are supported. For example (registered under data/raids/epicdatapack/hero.json):

{
  "difficulty": "HERO",
  "values": [
    {
      "raider_type": "PILLAGER",
      "wave_counts": [0, 1, -1, 3]
    }
  ]
}

• On Wave 1, this would add 1 Pillager to the default spawn counts.
• On Wave 2, this would subtract 1 Pillager from the default spawn counts.
• On Wave 3, this would add 3 Pillagers to the default spawn counts.

And so on. DifficultRaids will clamp the final result to a positive number, so if datapacks manage to subtract a raider's spawn count enough such that it becomes negative, the mod will make that 0 to avoid any errors. Using a value of 0 will not influence the spawn counts (since you're adding 0).

You can create multiple JSON files, and use multiple directories if you want to separate out all your edits. Say you want to completely replace Vindicator spawns, but add a few Pillagers. All you would need to do is create a JSON for the Vindicator replacements (under data/difficultraids/raids/some_file_name.json), and place the Pillager modifier JSON under data/some_datapack_name/raids/another_file_name.json. If you want to edit multiple Raid Difficulties, make separate JSON files for each one. A single file can only edit one Raid Difficulty (as specified earlier in this page).

Edit to your heart's content! If you want to test to see if your changes were reflected in game, use the /difficultraids_dumpwaves command, and check the console.