Cobblemon Boss User Guide

pack.mcmeta
data/
└─ cobblemonboss/
   └─ bosses/
      ├─ blastoise.json
      ├─ charizard.json
      └─ venusaur.json

File Structure

This datapack includes the following files:

pack.mcmeta
data/cobblemonboss/bosses/blastoise.json
data/cobblemonboss/bosses/charizard.json
data/cobblemonboss/bosses/venusaur.json

Where:

pack.mcmeta: datapack metadata file
blastoise.json: Blastoise boss data
charizard.json: Charizard boss data
venusaur.json: Venusaur boss data

1. Beginner Guide to Boss Data Packs

1.1 What is this configuration for?

A Boss JSON defines the complete data for one Boss Pokémon.

It mainly controls the following:

Which Pokémon the Boss is
What its displayed name is
Where and when it can spawn
What rewards are given after defeating it
What punishments happen after losing
What moves, stats, and battle mode it uses in combat

1.2 Recommended way to understand it

When creating a Boss, the most important thing is to think about these 4 parts first:

1) Who it is

unique_id
species_id
display_name

2) How it spawns

spawn_rule

3) What happens when players win or lose

reward_rule
punish_rule

4) How it fights

random_configs
moves
custom_battle_stats
phase_skills
battle_mode
actions_per_turn

1.3 Most basic filling suggestions

Required

unique_id
species_id
random_configs

Optional, depending on your needs

spawn_rule
reward_rule
punish_rule
effort_values
custom_battle_stats
phase_skills
battle_mode
actions_per_turn
held_items
nature
ability
form

1.4 Standard template

{
  "unique_id": "blastoise_water_boss",
  "display_name": "§9Boss",
  "species_id": "cobblemon:blastoise",
  "spawn_rule": {
    "spawn_locations": ["cave"],
    "spawn_times": ["all_day"],
    "spawn_biomes": [
      "minecraft:dripstone_caves",
      "#minecraft:is_ocean"
    ],
    "spawn_weight": 4
  },
  "reward_rule": {
    "reward_items": [
      {
        "item_id": "cobblemon:rare_candy",
        "count": 10
      },
      {
        "item_id": "cobblemon:rare_candy",
        "count": 10,
        "chance": 0.1
      },
      {
        "command": "givepokemonother {player} squirtle",
        "chance": 0.1
      },
      {
        "command": "givepokemonother {player} squirtle"
      }
    ]
  },
  "punish_rule": {
    "punish_items": [
      {
        "level": 5,
        "chance": 1
      },
      {
        "evs": {
          "hp": 1,
          "attack": 1,
          "defense": 1,
          "special_attack": 1,
          "special_defense": 1,
          "speed": 1
        },
        "chance": 1
      },
      {
        "ivs": {
          "hp": 1,
          "attack": 1,
          "defense": 1,
          "special_attack": 1,
          "special_defense": 1,
          "speed": 1
        },
        "chance": 0.01
      },
      {
        "command": "effect give {player} minecraft:hunger 60 0 true",
        "chance": 1
      }
    ]
  },
  "random_configs": [
    {
      "shiny": false,
      "effort_values": {
        "hp": 252,
        "attack": 0,
        "defense": 252,
        "special_attack": 0,
        "special_defense": 4,
        "speed": 0
      },
      "custom_battle_stats": {
        "hp": {
          "value": 5000,
          "mode": "exact"
        },
        "attack": {
          "value": 1000,
          "mode": "maximum"
        },
        "defense": {
          "value": 1000,
          "mode": "maximum"
        },
        "special_attack": {
          "value": 1000,
          "mode": "maximum"
        },
        "special_defense": {
          "value": 1000,
          "mode": "maximum"
        },
        "speed": {
          "value": 1000,
          "mode": "minimum"
        }
      },
      "battle_mode": "6v1",
      "actions_per_turn": 6,
      "moves": ["scald", "icywind", "yawn", "protect"],
      "nature": "bold",
      "ability": "torrent",
      "form": "",
      "held_items": ["cobblemon:leftovers"],
      "phase_skills": [
        {
          "hp_percent": 90,
          "moves": ["scald", "icywind", "yawn", "toxic"]
        },
        {
          "hp_percent": 80,
          "moves": ["waterpulse", "flashcannon", "rest", "protect"]
        },
        {
          "hp_percent": 70,
          "moves": ["surf", "darkpulse", "irondefense", "amnesia"]
        },
        {
          "hp_percent": 60,
          "moves": ["hydropump", "aurasphere", "protect", "raindance"]
        },
        {
          "hp_percent": 50,
          "moves": ["hydrocannon", "blizzard", "shellsmash", "focusenergy"]
        }
      ]
    },
    {
      "shiny": false,
      "effort_values": {
        "hp": 252,
        "attack": 0,
        "defense": 252,
        "special_attack": 0,
        "special_defense": 4,
        "speed": 0
      },
      "custom_battle_stats": {
        "hp": {
          "value": 5000,
          "mode": "exact"
        },
        "attack": {
          "value": 1000,
          "mode": "maximum"
        },
        "defense": {
          "value": 1000,
          "mode": "maximum"
        },
        "special_attack": {
          "value": 1000,
          "mode": "maximum"
        },
        "special_defense": {
          "value": 1000,
          "mode": "maximum"
        },
        "speed": {
          "value": 1000,
          "mode": "minimum"
        }
      },
      "battle_mode": "5v1",
      "actions_per_turn": 5,
      "moves": ["rapidspin", "brine", "toxic", "yawn"],
      "nature": "bold",
      "ability": "torrent",
      "form": "",
      "held_items": ["cobblemon:leftovers"],
      "phase_skills": [
        {
          "hp_percent": 90,
          "moves": ["rapidspin", "brine", "toxic", "yawn"]
        },
        {
          "hp_percent": 80,
          "moves": ["waterpulse", "flashcannon", "rest", "protect"]
        },
        {
          "hp_percent": 70,
          "moves": ["surf", "dragonpulse", "raindance", "irondefense"]
        },
        {
          "hp_percent": 60,
          "moves": ["hydropump", "darkpulse", "protect", "haze"]
        },
        {
          "hp_percent": 50,
          "moves": ["hydrocannon", "focusblast", "shellsmash", "focusenergy"]
        }
      ]
    },
    {
      "shiny": false,
      "effort_values": {
        "hp": 252,
        "attack": 0,
        "defense": 0,
        "special_attack": 252,
        "special_defense": 4,
        "speed": 0
      },
      "custom_battle_stats": {
        "hp": {
          "value": 5000,
          "mode": "exact"
        },
        "attack": {
          "value": 1000,
          "mode": "maximum"
        },
        "defense": {
          "value": 1000,
          "mode": "maximum"
        },
        "special_attack": {
          "value": 1000,
          "mode": "maximum"
        },
        "special_defense": {
          "value": 1000,
          "mode": "maximum"
        },
        "speed": {
          "value": 1000,
          "mode": "minimum"
        }
      },
      "battle_mode": "4v1",
      "actions_per_turn": 4,
      "moves": ["hydropump", "flashcannon", "shellsmash", "focusenergy"],
      "nature": "modest",
      "ability": "torrent",
      "form": "",
      "held_items": ["cobblemon:wise_glasses"],
      "phase_skills": [
        {
          "hp_percent": 90,
          "moves": ["icywind", "darkpulse", "yawn", "taunt"]
        },
        {
          "hp_percent": 80,
          "moves": ["scald", "flashcannon", "rest", "protect"]
        },
        {
          "hp_percent": 70,
          "moves": ["surf", "icebeam", "shellsmash", "raindance"]
        },
        {
          "hp_percent": 60,
          "moves": ["hydropump", "dragonpulse", "protect", "focusenergy"]
        },
        {
          "hp_percent": 50,
          "moves": ["hydrocannon", "aurasphere", "blizzard", "nastyplot"]
        }
      ]
    }
  ]
}

2. Top-level field descriptions

`unique_id`

Purpose The unique ID of the Boss.

How to understand it This is the internal name used to distinguish this Boss from other Bosses.

Recommendation Required.

Example

"unique_id": "blastoise_dripstone_caves_boss"

Suggestions

Use lowercase English letters and underscores
Do not use the same ID as another Boss

`display_name`

Purpose The name displayed to players.

How to understand it This is the name players will see in-game.

Recommendation Recommended.

Example

"display_name": "§9Boss"

Notes

Color codes can be used
Useful for making the Boss name more eye-catching

`species_id`

Purpose The Pokémon species ID of the Boss.

How to understand it This determines which Pokémon species the Boss actually is.

Recommendation Required.

Example

"species_id": "cobblemon:blastoise"

`spawn_rule`

Purpose Defines the spawning rules of the Boss.

How to understand it Controls where, when, and in which biomes the Boss can spawn.

Recommendation Optional.

Example

"spawn_rule": { ... }

`reward_rule`

Purpose Defines the rewards after defeating the Boss.

Recommendation Optional.

Example

"reward_rule": { ... }

`punish_rule`

Purpose Defines the punishments after losing the challenge.

Recommendation Optional.

Example

"punish_rule": { ... }

`random_configs`

Purpose A list of random battle configurations for the Boss.

How to understand it The same Boss can have multiple variants, and one will be randomly chosen when it spawns.

Recommendation Required.

Example

"random_configs": [ ... ]

3. `spawn_rule` Spawn Rules

`spawn_locations`

Purpose Restricts the type of location where the Boss can spawn.

Recommendation Optional.

Example

"spawn_locations": ["cave"]

Available values

Value	Meaning
`land`	Land
`water_surface`	Water surface
`underwater`	Underwater
`cave`	Cave
`sky`	Sky
`lava`	Lava area

`spawn_times`

Purpose Restricts the time period when the Boss can spawn.

Recommendation Optional.

Example

"spawn_times": ["all_day"]

"spawn_times": ["night", "midnight"]

Time range rules used by the mod

The time ranges are determined by the server world time in Minecraft.

The current implementation uses this logic:

long dayTime = level.getDayTime() % 24000;

if (dayTime >= 0 && dayTime < 3000) {
    return early_morning;
} else if (dayTime >= 3000 && dayTime < 6000) {
    return morning;
} else if (dayTime >= 6000 && dayTime < 12000) {
    return noon;
} else if (dayTime >= 12000 && dayTime < 15000) {
    return afternoon;
} else if (dayTime >= 15000 && dayTime < 18000) {
    return dusk;
} else if (dayTime >= 18000 && dayTime < 21000) {
    return night;
} else {
    return midnight;
}

That means the actual time mapping is:

Value	Tick range	Meaning
`all_day`	special value	Can spawn at any time
`early_morning`	`0 - 2999`	Early morning
`morning`	`3000 - 5999`	Morning
`noon`	`6000 - 11999`	Noon / daytime
`afternoon`	`12000 - 14999`	Afternoon
`dusk`	`15000 - 17999`	Dusk
`night`	`18000 - 20999`	Night
`midnight`	`21000 - 23999`	Midnight

Important notes about `spawn_times`

A Minecraft day is 24000 ticks
The mod checks the current time by using level.getDayTime() % 24000
Writing multiple values means multiple time periods are allowed
all_day is a special value that means no time restriction
The code itself returns one of the real time segments such as morning, night, or midnight
all_day is usually handled inside the spawn rule check logic as “always allowed”

Examples

Only spawn at night:

"spawn_times": ["night"]

Only spawn late at night:

"spawn_times": ["midnight"]

Spawn during both dusk and night:

"spawn_times": ["dusk", "night"]

Spawn at any time:

"spawn_times": ["all_day"]

`spawn_biomes`

Purpose Restricts the biomes where the Boss can spawn.

Recommendation Optional.

Example

"spawn_biomes": [
  "minecraft:dripstone_caves",
  "#minecraft:is_ocean"
]

Two ways to write it

Normal biome:

"minecraft:dripstone_caves"

Biome tag:

"#minecraft:is_ocean"

Notes

Writing a biome ID means it only spawns in that biome
Writing a biome tag starting with # means it can spawn in all biomes under that tag

`spawn_weight`

Purpose Controls the spawn weight of this Boss.

Recommendation Optional.

Example

"spawn_weight": 4

Notes

Usually use a positive integer
When multiple Bosses are considered together, a larger value usually means a higher chance to be selected

4. `reward_rule` Reward Rules

`reward_items`

Purpose The list of reward entries.

Recommendation Fill this if you want rewards.

Example

"reward_items": [
  {
    "item_id": "cobblemon:rare_candy",
    "count": 10
  }
]

Fields of a single reward entry

`item_id`

Purpose The reward item.

Example

{
  "item_id": "cobblemon:rare_candy"
}

Notes

Use this when you want to give an item

`count`

Purpose The number of items.

Example

{
  "item_id": "cobblemon:rare_candy",
  "count": 10
}

Notes

Optional
If omitted, it is usually treated as 1

`command`

Purpose Executes a command as a reward.

Example

{
  "command": "givepokemonother {player} squirtle"
}

Notes

Useful for giving Pokémon, titles, points, currency, and more
Supports the {player} placeholder

`chance`

Purpose The trigger probability of the reward.

Example

{
  "item_id": "cobblemon:rare_candy",
  "count": 10,
  "chance": 0.1
}

Notes

1 means 100%
0.5 means 50%
0.1 means 10%

Common reward examples

Item reward:

{
  "item_id": "cobblemon:rare_candy",
  "count": 10
}

Chance-based item reward:

{
  "item_id": "cobblemon:rare_candy",
  "count": 10,
  "chance": 0.1
}

Command reward:

{
  "command": "givepokemonother {player} squirtle"
}

Chance-based command reward:

{
  "command": "givepokemonother {player} squirtle",
  "chance": 0.1
}

5. `punish_rule` Punishment Rules

`punish_items`

Purpose The list of punishment entries.

Recommendation Fill this if you want punishments.

Example

"punish_items": [
  {
    "level": 5,
    "chance": 1
  }
]

Fields of a single punishment entry

`level`

Purpose Reduces levels.

Example

{
  "level": 5,
  "chance": 1
}

`evs`

Purpose Reduces effort values.

Example

{
  "evs": {
    "hp": 1,
    "attack": 1
  },
  "chance": 1
}

Available keys

hp
attack
defense
special_attack
special_defense
speed

Notes

Only write the stats you want to reduce
You do not need to write all six stats

`ivs`

Purpose Reduces individual values.

Example

{
  "ivs": {
    "hp": 1,
    "speed": 1
  },
  "chance": 0.01
}

Available keys

hp
attack
defense
special_attack
special_defense
speed

Notes

Same here, only write the stats you want to reduce

`command`

Purpose Executes a command as a punishment.

Example

{
  "command": "effect give {player} minecraft:hunger 60 0 true",
  "chance": 1
}

Notes

Useful for negative effects, taking money, teleporting, broadcasting messages, and more
Supports the {player} placeholder

`chance`

Purpose The trigger probability of the punishment.

Example

{
  "level": 5,
  "chance": 1
}

Notes

1 means it always triggers
0.01 means a 1% chance

6. A single `random_configs` battle configuration

`shiny`

Purpose Whether the Boss is shiny.

Example

"shiny": false

Recommendation Recommended.

`effort_values`

Purpose The EV spread of the Boss.

Example

"effort_values": {
  "hp": 252,
  "attack": 0,
  "defense": 252,
  "special_attack": 0,
  "special_defense": 4,
  "speed": 0
}

Available keys

hp
attack
defense
special_attack
special_defense
speed

Notes

Used to define whether the Boss is bulky, physical, special, and so on
Usually a single stat does not exceed 252, and the total does not exceed 510

`custom_battle_stats`

Purpose Custom battle stats for the Boss.

Example

"custom_battle_stats": {
  "hp": {
    "value": 5000,
    "mode": "exact"
  },
  "speed": {
    "value": 1000,
    "mode": "minimum"
  }
}

Notes

Useful for making true boss-level stats
You do not need to write all six stats
Only write the stats you want to modify

Available stat keys

hp
attack
defense
special_attack
special_defense
speed

`value`

Purpose The target stat value.

Example

"value": 5000

Notes

Usually a positive integer

`mode`

Purpose Defines how the stat value is applied.

Example

"mode": "exact"

Available values

exact
minimum
maximum

Meaning

exact: use this value directly
minimum: at least this value
maximum: at most this value

`battle_mode`

Purpose Defines the battle size mode.

Example

"battle_mode": "6v1"

"battle_mode": "six_vs_one"

Available values

1v1 / one_vs_one
2v1 / two_vs_one
3v1 / three_vs_one
4v1 / four_vs_one
5v1 / five_vs_one
6v1 / six_vs_one

Notes

Useful for multiplayer boss fights
“X v 1” means up to X players can fight 1 Boss together

`actions_per_turn`

Purpose The number of actions the Boss can take per turn.

Example

"actions_per_turn": 6

Notes

This means how many times the Boss can act in one turn
This value cannot exceed the player limit defined by the current battle_mode
In other words, if the battle mode is X v 1, then this value can be at most X

Limits by battle mode

1v1 / one_vs_one → max 1
2v1 / two_vs_one → max 2
3v1 / three_vs_one → max 3
4v1 / four_vs_one → max 4
5v1 / five_vs_one → max 5
6v1 / six_vs_one → max 6

Examples

If "battle_mode": "6v1", then "actions_per_turn" can be at most 6
If "battle_mode": "3v1", then "actions_per_turn" can be at most 3

Recommendation

Increase it when designing multiplayer Bosses
Do not set it far above the battle scale, or the fight will become very unbalanced

`moves`

Purpose The initial moveset of the Boss.

Example

"moves": ["scald", "icywind", "yawn", "protect"]

Recommendation Recommended.

Notes

Designing around 4 moves is usually the most intuitive

`nature`

Purpose The Boss nature.

Example

"nature": "bold"

Recommendation Optional.

`ability`

Purpose The Boss ability.

Example

"ability": "torrent"

Recommendation Optional.

`form`

Purpose The Boss form.

Example

"form": ""

"form": "mega"

Recommendation Optional.

`held_items`

Purpose The list of held items for the Boss.

Example

"held_items": ["cobblemon:leftovers"]

Recommendation Optional.

`phase_skills`

Purpose Moveset changes based on HP phases.

Example

"phase_skills": [
  {
    "hp_percent": 90,
    "moves": ["scald", "icywind", "yawn", "toxic"]
  },
  {
    "hp_percent": 80,
    "moves": ["waterpulse", "flashcannon", "rest", "protect"]
  }
]

Notes

Useful for multi-phase Boss fights
The Boss switches to another moveset after reaching a certain HP threshold

7. Single phase skill description

`hp_percent`

Purpose The HP percentage that triggers the phase.

Example

"hp_percent": 90

Notes

Usually written as a number from 1 to 100
Means the phase is entered when HP is less than or equal to this percentage

`moves`

Purpose The moveset used in this phase.

Example

"moves": ["scald", "icywind", "yawn", "toxic"]

Notes

Usually 1 to 4 moves

8. Full stat key list

The following keys appear repeatedly in effort_values, evs, ivs, and custom_battle_stats:

"hp"
"attack"
"defense"
"special_attack"
"special_defense"
"speed"

Their meanings are:

hp: HP
attack: Attack
defense: Defense
special_attack: Special Attack
special_defense: Special Defense
speed: Speed

9. Most common beginner design ideas

Making the most basic Boss

At minimum, think about:

unique_id
species_id
display_name
random_configs
moves

Making a naturally spawning Boss

Also add:

spawn_rule
spawn_locations
spawn_times
spawn_biomes
spawn_weight

Making a Boss with drops

Also add:

reward_rule
reward_items

Making a Boss with punishment on failure

Also add:

punish_rule
punish_items

Making a true raid-style Boss

Also add:

custom_battle_stats
phase_skills
battle_mode
actions_per_turn

10. One-sentence summary

This Boss data pack configuration is essentially:

Use unique_id and species_id to define the Boss identity
Use spawn_rule to define how it appears
Use reward_rule and punish_rule to define win/loss outcomes
Use random_configs to define its actual combat stats, moves, phases, and battle style

11. Configuration File Explanation

This part is divided into two categories:

JSON configurations
TOML configurations

11.1 JSON configuration files

`config/cobblemonboss/level-mapping.json`

This file is used to:

Map player level to Boss level.

For example:

Player level 1 → Boss level 2
Player level 50 → Boss level 65
Player level 100 → Boss level 155

How to modify it

The left side is the player level, and the right side is the corresponding Boss level.

Example:

{
  "1": 5,
  "2": 5,
  "3": 6,
  "4": 6,
  "5": 7
}

`config/cobblemonboss/pokemon-max-level.json`

This file is used to:

Modify Cobblemon's global maximum Pokémon level.

Default file:

{
  "configName": "Pokemon Max Level",
  "maxPokemonLevel": 900,
  "description": "Set the maximum level limit for Pokemon"
}

Field descriptions

configName Configuration name, only for description.

maxPokemonLevel The global maximum Pokémon level.

description Description text.

Common example

{
  "configName": "Pokemon Max Level",
  "maxPokemonLevel": 200,
  "description": "Set the maximum level limit for Pokemon"
}

11.2 TOML configuration files

`player-level-limit.toml`

[playerLevelLimit]
enablePlayerLevelLimit = true
maxPlayerPokemonLevel = 100

Field descriptions

enablePlayerLevelLimit: whether to enable the player Pokémon level cap
maxPlayerPokemonLevel: the maximum level player Pokémon are allowed to reach

`pokemon-boss-battle-check.toml`

[battle_check.basic]
enableBattleCheck = false
cancelBattle = true

[battle_check.pokemon]
enablePokemonCheck = true
bannedPokemonList = ["cobblemon:ditto"]

[battle_check.items]
enableItemCheck = true
bannedItemsList = ["cobblemon:master_ball"]

[battle_check.moves]
enableMoveCheck = true
bannedMovesList = ["endeavor"]

Field descriptions

enableBattleCheck: whether to enable pre-battle checks for Boss battles
cancelBattle: whether to cancel the battle directly if banned content is detected
enablePokemonCheck: whether to check banned Pokémon
bannedPokemonList: list of banned Pokémon
enableItemCheck: whether to check banned items
bannedItemsList: list of banned items
enableMoveCheck: whether to check banned moves
bannedMovesList: list of banned moves

`pokemon-boss-capture.toml`

["Boss Capture Settings"]
preventBossCapture = true
showCaptureMessage = true

Field descriptions

preventBossCapture: whether Boss Pokémon cannot be captured
showCaptureMessage: whether to show a message when capture is prevented

`pokemon-boss-immune.toml`

[immune]
enableBossImmune = true

Field descriptions

enableBossImmune: whether to enable the Boss immunity system

`pokemon-boss-level.toml`

[level]
bossLevelMultiplier = 1.5
minBossLevel = 5
maxBossLevel = 200
includePCPokemon = true
scaleByMaxLevel = true
enableCustomLevelMapping = true
enableLevelRandom = true
randomMin = -10
randomMax = 10

Field descriptions

bossLevelMultiplier: Boss level multiplier
minBossLevel: minimum Boss level
maxBossLevel: maximum Boss level
includePCPokemon: whether to include Pokémon stored in the PC when calculating level
scaleByMaxLevel: whether to scale Boss level based on the player's highest level
enableCustomLevelMapping: whether to enable level-mapping.json
enableLevelRandom: whether to enable random Boss level variation
randomMin: minimum random variation
randomMax: maximum random variation

Common ideas

Use the mapping table only:

[level]
bossLevelMultiplier = 1.5
minBossLevel = 5
maxBossLevel = 200
includePCPokemon = true
scaleByMaxLevel = true
enableCustomLevelMapping = true
enableLevelRandom = false
randomMin = -10
randomMax = 10

Do not use the mapping table, only use the multiplier:

[level]
bossLevelMultiplier = 2.0
minBossLevel = 10
maxBossLevel = 200
includePCPokemon = true
scaleByMaxLevel = true
enableCustomLevelMapping = false
enableLevelRandom = true
randomMin = -5
randomMax = 5

`pokemon-boss-penalty.toml`

enablePenalty = true

["Penalty Chance Settings (Level Scaling)"]
minPenaltyChance = 0.1
maxPenaltyChance = 1.0
penaltyLevelScale = 100

Field descriptions

enablePenalty: master switch for Boss battle failure punishments
minPenaltyChance: minimum punishment chance
maxPenaltyChance: maximum punishment chance
penaltyLevelScale: scaling factor for punishment chance based on level

`pokemon-boss-reward.toml`

["Boss Reward Settings"]
minDropRate = 0.1
maxDropRate = 1.0
levelScale = 100

Field descriptions

minDropRate: minimum drop rate
maxDropRate: maximum drop rate
levelScale: scaling factor for drop rate based on level

`pokemon-boss-spawn.toml`

["Boss Spawn Settings"]
enableBossSpawn = true
checkIntervalTicks = 12000
spawnChance = 0.1
enableSpawnTimeRandom = true
randomValueMin = 1000
randomValueMax = 3000
spawnFrequency = 1

Field descriptions

enableBossSpawn: whether to enable the natural Boss spawning system
checkIntervalTicks: spawn check interval, in ticks
spawnChance: spawn probability for each check
enableSpawnTimeRandom: whether to enable random variation for spawn timing
randomValueMin: minimum random variation
randomValueMax: maximum random variation
spawnFrequency: additional random spawn attempts during one check cycle

How to understand `spawnFrequency`

0: only one fixed spawn check at the end of the cycle
1: 1 extra random chance during the cycle, plus 1 check at the end
2: 2 extra random chances during the cycle, plus 1 check at the end

12. Configuration suggestions for beginners

12.1 The simplest usable setup

`pokemon-max-level.json`

{
  "configName": "Pokemon Max Level",
  "maxPokemonLevel": 200,
  "description": "Set the maximum level limit for Pokemon"
}

`level-mapping.json`

Use the default mapping first. Do not change it too early.

`pokemon-boss-level.toml`

[level]
bossLevelMultiplier = 1.5
minBossLevel = 5
maxBossLevel = 200
includePCPokemon = true
scaleByMaxLevel = true
enableCustomLevelMapping = true
enableLevelRandom = true
randomMin = -5
randomMax = 5

`pokemon-boss-spawn.toml`

["Boss Spawn Settings"]
enableBossSpawn = true
checkIntervalTicks = 12000
spawnChance = 0.1
enableSpawnTimeRandom = true
randomValueMin = 1000
randomValueMax = 3000
spawnFrequency = 1

`pokemon-boss-reward.toml`

["Boss Reward Settings"]
minDropRate = 0.1
maxDropRate = 1.0
levelScale = 100

`pokemon-boss-penalty.toml`

enablePenalty = true

["Penalty Chance Settings (Level Scaling)"]
minPenaltyChance = 0.1
maxPenaltyChance = 1.0
penaltyLevelScale = 100

12.2 If you want stricter Boss battles

It is recommended to enable:

[battle_check.basic]
enableBattleCheck = true
cancelBattle = true

Then add as needed:

Ban certain Pokémon
Ban certain items
Ban certain moves

12.3 If you want Bosses to be absolutely uncapturable

Keep:

["Boss Capture Settings"]
preventBossCapture = true
showCaptureMessage = true

13. One-sentence summary of configs

These configuration files can be understood as:

pokemon-max-level.json: global Pokémon max level
level-mapping.json: player level → Boss level mapping table
pokemon-boss-level.toml: Boss level calculation logic
pokemon-boss-spawn.toml: Boss spawn rules
pokemon-boss-reward.toml: Boss reward probability
pokemon-boss-penalty.toml: Boss punishment probability
pokemon-boss-battle-check.toml: Boss battle restriction checks
pokemon-boss-capture.toml: Boss capture prevention
pokemon-boss-immune.toml: Boss immunity switch
player-level-limit.toml: player Pokémon level cap

14. Boss Command Usage

This section introduces 3 commands:

/checkpokemonboss
/spawnpokemonboss
/spawnpokemonbossat

14.1 `/checkpokemonboss`

Purpose

Checks which Bosses can possibly spawn at the player's current location, and shows the countdown until the next Boss refresh.

Permission

All players can use it.

Usage

/checkpokemonboss

Description

After running it, it will display:

How many minutes remain until the next Boss refresh
A list of Bosses that match the current location
The display name of each Boss
The spawn weight of each Boss

When to use it

Players want to know what Bosses can spawn in their current location
Players want to know how long until the next refresh
Server owners want to test whether biome / time / spawn rules are working correctly

14.2 `/spawnpokemonboss`

Purpose

Directly spawns a specified Boss near the player.

Permission

Requires administrator permission.

Usage

Basic form:

/spawnpokemonboss <bossUniqueId>

With level specified:

/spawnpokemonboss <bossUniqueId> <level>

Parameter descriptions

`<bossUniqueId>`

The Boss unique ID, which is the value of:

"unique_id": "xxx"

For example:

blastoise_dripstone_caves_boss

`<level>`

The Boss level.

If omitted, the default level is 1
If provided, you can specify the level manually
Valid range: 1 ~ 900

Examples

Spawn a Boss with the default level:

/spawnpokemonboss blastoise_dripstone_caves_boss

Spawn a level 80 Boss:

/spawnpokemonboss blastoise_dripstone_caves_boss 80

Spawn a level 150 Boss:

/spawnpokemonboss blastoise_dripstone_caves_boss 150

Notes

This command can only summon by Boss unique ID
You cannot use the species ID directly
The command supports auto-completion and will suggest all loaded Boss unique IDs

14.3 `/spawnpokemonbossat`

Purpose

Manages fixed Boss spawn points.

You can use it to:

Create a fixed spawn point
Add Bosses to the spawn pool
Remove Bosses from the spawn pool
Modify Boss weights
Delete a spawn point
View spawn point information
Manually trigger a spawn point
Set or clear hologram text

Permission

Requires administrator permission.

14.3.1 Create a spawn point

Usage

Without custom text:

/spawnpokemonbossat create <id> <dimension> <x> <y> <z> <level> <respawnSeconds>

With custom text:

/spawnpokemonbossat create <id> <dimension> <x> <y> <z> <level> <respawnSeconds> <text>

Parameter descriptions

<id> The spawn point ID. Each spawn point should have its own unique name.

<dimension> The dimension, for example:

minecraft:overworld
minecraft:the_nether
minecraft:the_end

<x> <y> <z> The coordinates of the spawn point.

<level> The level of the Boss spawned at this point.

<respawnSeconds> The respawn time after the Boss is defeated, in seconds.

<text> Optional hologram text.

Examples

Create a spawn point in the Overworld:

/spawnpokemonbossat create boss_point_1 minecraft:overworld 100 64 100 80 600

Create a spawn point with custom text:

/spawnpokemonbossat create boss_point_2 minecraft:overworld 200 70 200 100 900 §cBlastoise Boss

14.3.2 Add a Boss to a spawn point

Usage

/spawnpokemonbossat addboss <id> <bossUniqueId> <weight>

Parameter descriptions

<id>: spawn point ID
<bossUniqueId>: the Boss unique ID to add to the pool
<weight>: weight, higher values usually mean a higher chance to be selected

Example

/spawnpokemonbossat addboss boss_point_1 blastoise_dripstone_caves_boss 10

14.3.3 Remove a Boss from a spawn point

Usage

/spawnpokemonbossat removeboss <id> <bossUniqueId>

Example

/spawnpokemonbossat removeboss boss_point_1 blastoise_dripstone_caves_boss

14.3.4 Change the weight of a Boss in a spawn point

Usage

/spawnpokemonbossat setweight <id> <bossUniqueId> <weight>

Example

/spawnpokemonbossat setweight boss_point_1 blastoise_dripstone_caves_boss 20

14.3.5 Remove a spawn point

Usage

/spawnpokemonbossat remove <id>

Example

/spawnpokemonbossat remove boss_point_1

Notes

After deletion, the following will also be handled:

Spawn point data
Hologram display
The currently active fixed Boss

14.3.6 List all spawn points

Usage

/spawnpokemonbossat list

Purpose

Displays information about all current fixed spawn points, including:

Spawn point ID
Dimension
Coordinates
Boss level
Respawn time
Boss pool
Current active Boss

14.3.7 View details of a single spawn point

Usage

/spawnpokemonbossat info <id>

Example

/spawnpokemonbossat info boss_point_1

Purpose

Displays complete information about a spawn point, including:

Dimension
Coordinates
Boss level
Respawn time
Next respawn time
Current active Boss
Current hologram text
Boss pool list

14.3.8 Manually trigger a spawn point

Usage

/spawnpokemonbossat trigger <id>

Example

/spawnpokemonbossat trigger boss_point_1

Purpose

Immediately makes this spawn point ready to spawn again, usually for testing.

14.3.9 Set spawn point hologram text

Usage

/spawnpokemonbossat settext <id> <text>

Example

/spawnpokemonbossat settext boss_point_1 §bDeep Sea Boss Spawn Point

Purpose

Changes the hologram text shown for this spawn point.

14.3.10 Clear spawn point hologram text

Usage

/spawnpokemonbossat cleartext <id>

Example

/spawnpokemonbossat cleartext boss_point_1

Purpose

Clears the custom hologram text and restores the default display.

15. Most commonly used command combinations

Directly test whether a Boss can be summoned:

/spawnpokemonboss blastoise_dripstone_caves_boss 100

Check which Bosses may spawn at the current location:

/checkpokemonboss

Create a fixed spawn point:

/spawnpokemonbossat create boss_point_1 minecraft:overworld 100 64 100 80 600

Add a Boss to this spawn point:

/spawnpokemonbossat addboss boss_point_1 blastoise_dripstone_caves_boss 10

View information about this spawn point:

/spawnpokemonbossat info boss_point_1

Manually trigger this spawn point:

/spawnpokemonbossat trigger boss_point_1

16. The simplest way for beginners to understand it

If you are just getting started:

To check what Bosses can spawn at your current location, use:

/checkpokemonboss

To directly summon a Boss for testing, use:

/spawnpokemonboss <bossUniqueId> <level>

To create a Boss that spawns at a fixed location, the main commands are:

/spawnpokemonbossat create ...
/spawnpokemonbossat addboss ...
/spawnpokemonbossat info ...
/spawnpokemonbossat trigger ...

17. Time logic reference for developers

If you want to match the exact spawn-time behavior in code, use the following logic:

public static PokemonBossDefinition.SpawnTime getCurrentSpawnTime(ServerLevel level) {
    long dayTime = level.getDayTime() % 24000;

    if (dayTime >= 0 && dayTime < 3000) {
        return PokemonBossDefinition.SpawnTime.early_morning;
    } else if (dayTime >= 3000 && dayTime < 6000) {
        return PokemonBossDefinition.SpawnTime.morning;
    } else if (dayTime >= 6000 && dayTime < 12000) {
        return PokemonBossDefinition.SpawnTime.noon;
    } else if (dayTime >= 12000 && dayTime < 15000) {
        return PokemonBossDefinition.SpawnTime.afternoon;
    } else if (dayTime >= 15000 && dayTime < 18000) {
        return PokemonBossDefinition.SpawnTime.dusk;
    } else if (dayTime >= 18000 && dayTime < 21000) {
        return PokemonBossDefinition.SpawnTime.night;
    } else {
        return PokemonBossDefinition.SpawnTime.midnight;
    }
}

This means your spawn_times documentation should always match these tick intervals:

early_morning: 0 - 2999
morning: 3000 - 5999
noon: 6000 - 11999
afternoon: 12000 - 14999
dusk: 15000 - 17999
night: 18000 - 20999
midnight: 21000 - 23999

all_day is a special configuration value and should be treated as:

no time restriction
always allowed regardless of the current tick range

Cobblemon Boss

Cobblemon Boss User Guide

File Structure

1. Beginner Guide to Boss Data Packs

1.1 What is this configuration for?

1.2 Recommended way to understand it

1) Who it is

2) How it spawns

3) What happens when players win or lose

4) How it fights

1.3 Most basic filling suggestions

Required

Recommended

Optional, depending on your needs

1.4 Standard template

2. Top-level field descriptions

unique_id

display_name

species_id

spawn_rule

reward_rule

punish_rule

random_configs

3. spawn_rule Spawn Rules

spawn_locations

spawn_times

Time range rules used by the mod

Important notes about spawn_times

Examples

spawn_biomes

spawn_weight

4. reward_rule Reward Rules

reward_items

Fields of a single reward entry

item_id

count

command

chance

Common reward examples

5. punish_rule Punishment Rules

punish_items

Fields of a single punishment entry

level

evs

ivs

command

chance

6. A single random_configs battle configuration

shiny

effort_values

custom_battle_stats

value

mode

battle_mode

actions_per_turn

moves

nature

ability

form

held_items

phase_skills

7. Single phase skill description

hp_percent

moves

8. Full stat key list

9. Most common beginner design ideas

Making the most basic Boss

Making a naturally spawning Boss

Making a Boss with drops

Making a Boss with punishment on failure

Making a true raid-style Boss

10. One-sentence summary

11. Configuration File Explanation

11.1 JSON configuration files

config/cobblemonboss/level-mapping.json

config/cobblemonboss/pokemon-max-level.json

Field descriptions

Common example

11.2 TOML configuration files

player-level-limit.toml

`unique_id`

`display_name`

`species_id`

`spawn_rule`

`reward_rule`

`punish_rule`

`random_configs`

3. `spawn_rule` Spawn Rules

`spawn_locations`

`spawn_times`

Important notes about `spawn_times`

`spawn_biomes`

`spawn_weight`

4. `reward_rule` Reward Rules

`reward_items`

`item_id`

`count`

`command`

`chance`

5. `punish_rule` Punishment Rules

`punish_items`

`level`

`evs`

`ivs`

`command`

`chance`

6. A single `random_configs` battle configuration

`shiny`

`effort_values`

`custom_battle_stats`

`value`

`mode`

`battle_mode`

`actions_per_turn`

`moves`

`nature`

`ability`

`form`

`held_items`

`phase_skills`

`hp_percent`

`moves`

`config/cobblemonboss/level-mapping.json`

`config/cobblemonboss/pokemon-max-level.json`

`player-level-limit.toml`

`pokemon-boss-battle-check.toml`

`pokemon-boss-capture.toml`

`pokemon-boss-immune.toml`

`pokemon-boss-level.toml`

`pokemon-boss-penalty.toml`

`pokemon-boss-reward.toml`

`pokemon-boss-spawn.toml`

How to understand `spawnFrequency`

`pokemon-max-level.json`

`level-mapping.json`

`pokemon-boss-level.toml`

`pokemon-boss-spawn.toml`

`pokemon-boss-reward.toml`

`pokemon-boss-penalty.toml`

14.1 `/checkpokemonboss`

14.2 `/spawnpokemonboss`

`<bossUniqueId>`

`<level>`

14.3 `/spawnpokemonbossat`