Cobblemon Boss: Complete Guide to Creating a Boss (Single Boss Configuration)

It is compatible with Cobblemon version 1.7+, allowing you to fully customize exclusive single Boss Pokémon via JSON configuration files in data packs.

{
  "unique_id": "blastoise_water_boss",
  "display_name": "§9水箭龟Boss",
  "species_id": "cobblemon:blastoise",
  "spawn_rule": {
    "spawn_locations": ["water_surface"],
    "spawn_times": ["night"],
    "spawn_biomes": ["minecraft:river"],
    "spawn_weight": 4
  },
  "reward_rule": {
    "reward_items": [
      {
        "item_id": "cobblemon:rare_candy",
        "count": 10
      }
    ]
  },
  "random_configs": [
    {
      "shiny": false,
      "effort_values": {
        "hp": 252,
        "attack": 0,
        "defense": 252,
        "special_attack": 0,
        "special_defense": 4,
        "speed": 0
      },
      "moves": ["hydropump", "icebeam", "darkpulse", "aurasphere"],
      "nature": "bold",
      "ability": "torrent",
      "form": "",
      "held_items": ["cobblemon:assault_vest"]
    },
    {
      "shiny": false,
      "effort_values": {
        "hp": 252,
        "attack": 0,
        "defense": 252,
        "special_attack": 0,
        "special_defense": 4,
        "speed": 0
      },
      "moves": ["scald", "rapidspin", "toxic", "protect"],
      "nature": "bold",
      "ability": "torrent",
      "form": "",
      "held_items": ["cobblemon:leftovers"]
    },
    {
      "shiny": false,
      "effort_values": {
        "hp": 252,
        "attack": 0,
        "defense": 0,
        "special_attack": 252,
        "special_defense": 4,
        "speed": 0
      },
      "moves": ["hydropump", "icebeam", "flashcannon", "aurasphere"],
      "nature": "modest",
      "ability": "torrent",
      "form": "",
      "held_items": ["cobblemon:wise_glasses"]
    }
  ]
}

Premium Sponsor-Exclusive Features

3.1 Core Exclusive Gameplay: Multiplayer Team 2v2 Ruins Battle

Unlocking Method: Sponsor the mod through official platforms (see Section 3.3 for links)
Gameplay Mechanics:

• Enter the exclusive in-game ruin structure to trigger the battle.
• Boss spawning rules dynamically adapt to player conditions:
  • If a player has only 1 Pokémon in their team: 1 Boss will spawn (1v1 Duel Mode).
  • If a player has 2 or more Pokémon in their team: 2 Bosses will spawn (1v2 Solo Challenge Mode).
  • If there are other players nearby (within a 10-block radius): Players will automatically form a team to fight against the 2 Bosses together (2v2 Team Co-op Mode).
• The Ruins Battle features an independent reward system (separate from regular Boss rewards) and supports full custom configurations (e.g., exclusive loot, Boss difficulty, ruin spawn locations, etc.).

3.3 How to Unlock Premium Features

Sponsor the mod through the following official platforms to gain access:

• Ko-fi: https://ko-fi.com/rainapricot
• Afdian: https://afdian.com/a/yaziy

Detailed Field Explanations & Configuration Tips

Required Fields

unique_id - Unique Boss Identifier

• Required field
• Description: Uniquely identifies the Boss to avoid configuration conflicts; the server relies on this ID to load and distinguish different Bosses.
• Rules: Only letters, numbers, and underscores are allowed. Recommended format: species_attribute_boss for easy management.
• Examples:

"unique_id": "blastoise_water_boss"
"unique_id": "charizard_fire_boss"
"unique_id": "gengar_ghost_boss"

1. Time Enumeration & Tick Ranges

Time Enum	Minecraft Tick Range	English Period
early_morning	0 ≤ ticks ＜ 3000	Early Morning
morning	3000 ≤ ticks ＜ 6000	Morning
noon	6000 ≤ ticks ＜ 12000	Noon
afternoon	12000 ≤ ticks ＜ 15000	Afternoon
dusk	15000 ≤ ticks ＜ 18000	Dusk
night	18000 ≤ ticks ＜ 21000	Night
midnight	21000 ≤ ticks ＜ 24000	Midnight

2. Spawn Location Enumeration

Location Enum	English Location
land	Land
water_surface	Water Surface
underwater	Underwater
sky	Sky
cave	Cave
lava	Lava Surface

display_name - Display Name

• Required field
• Description: The name displayed above the Boss's head in the game.
• Supports: Minecraft color codes (starting with §) and special symbols.
• Color Code Reference:
  §0 - Black, §1 - Dark Blue, §2 - Dark Green, §3 - Cyan, §4 - Dark Red,
  §5 - Purple, §6 - Gold, §7 - Gray, §8 - Dark Gray, §9 - Blue,
  §a - Green, §b - Light Blue, §c - Red, §d - Pink, §e - Yellow, §f - White
• Examples:

"display_name": "§9💧Blastoise Boss💧"
"display_name": "§c🔥Charizard Boss🔥"
"display_name": "§5👻Gengar Boss👻"

species_id - Pokémon Species

• Required field
• Description: The registered ID of the Pokémon species corresponding to the Boss.
• Format: cobblemon:pokemon_name (use the English name of the Pokémon).
• Examples:

"species_id": "cobblemon:blastoise"
"species_id": "cobblemon:charizard"
"species_id": "cobblemon:gengar"

Core Configuration Modules

1. spawn_rule - Spawn Rule Configuration

Controls the Boss's spawn location, time, and probability. All subfields are optional but recommended for precise control of encounter scenarios.

Subfield	Description	Optional Values/Format	Example
spawn_locations	Types of locations where the Boss can spawn	land, water_surface, underwater, cave, sky, lava_surface	["water_surface"]
spawn_times	Time periods when the Boss is allowed to spawn	day, night, dawn, dusk	["night"]
spawn_biomes	Biomes where the Boss can spawn (supports vanilla and modded biomes)	Format: minecraft:biome_name	["minecraft:river", "minecraft:ocean"]
spawn_weight	Relative spawn probability in allowed biomes (higher value = higher chance)	Integer (default: 1, recommended range: 3-8)	4

2. reward_rule - Reward Rule Configuration

Defines the items players obtain after defeating the Boss.

reward_items (Reward Item List)

• Format: An array of objects, each containing two subfields:
  • item_id: Item ID in the format modid:item_name (use cobblemon: for Cobblemon items, minecraft: for vanilla items).
  • count: Quantity of the item, range: 1-99.
• Examples:

"reward_items": [
  {"item_id": "cobblemon:rare_candy", "count": 10},
  {"item_id": "cobblemon:water_stone", "count": 2},
  {"item_id": "minecraft:experience_bottle", "count": 15}
]

3. random_configs - Random Battle Attribute Configuration

This is the core battle module. Each element in the array represents a set of battle attributes. The Boss randomly selects one set when spawning, which increases the diversity of battles. Each configuration set includes the following fields:

Subfield	Description	Key Rules & Examples
shiny	Whether the Boss is a shiny Pokémon	true/false (default: false; set a small number of sets to true for rarity)
effort_values (EVs)	Attribute distribution, covering six stats: hp, attack, defense, special_attack, special_defense, speed	Critical Rule: Max 252 EVs for a single stat; total EVs of all six stats ≤ 510. Example: {"hp":252, "defense":252, "special_defense":4} (total 508, compliant)
moves	A fixed set of 4 moves that the Boss can use	Fill in Cobblemon official move IDs (queryable in the data/cobblemon/moves/ directory of the mod). Example: ["hydropump", "icebeam", "darkpulse", "aurasphere"]
nature	Determines the Boss's attribute bonus/penalty	Common options: bold (+Defense, -Attack), modest (+Special Attack, -Attack), timid (+Speed, -Attack), calm (+Special Defense, -Attack). Match with EV distribution for optimized builds.
ability	The Boss's battle ability	Fill in Cobblemon official ability IDs (queryable in the data/cobblemon/abilities/ directory). Example: Blastoise uses torrent (boosts Water-type moves when HP is low)
form	Special form of the Pokémon	Leave blank ("") for the default form; fill in specific form IDs for variants, e.g., mega_x, alolan
held_items	The item held by the Boss during battle	Single-item array, format: cobblemon:item_name. Example: ["cobblemon:leftovers"] (tank build)、["cobblemon:life_orb"] (offensive build)

Critical Configuration Rules (Must Follow)

1. JSON Syntax Validity: JSON is case-sensitive. Ensure correct use of commas, quotation marks, and curly braces. It is recommended to use editors like VS Code or Notepad++ with JSON syntax checking enabled to avoid loading failures.
2. Filename Naming Rules: Configuration filenames must use lowercase letters, numbers, and underscores only (e.g., blastoise_boss.json). Avoid uppercase letters, spaces, or special symbols.
3. EV Distribution Limit: Violation of the "single stat ≤252, total ≤510" rule will cause the Boss to load abnormally or have incorrect attributes.
4. Import & Activation Method: Place the configuration file in the data/cobblemonboss/bosses/ directory of your data pack → package the data pack → put it into the datapacks folder of the target world → run the in-game command /reload to make the configuration take effect.

Summary

This configuration template focuses on single Boss customization, with a clear structure consisting of 3 required fields + 3 core functional modules. You can:

• Adjust spawn_rule to control where and when the Boss appears (e.g., set water-type Bosses to spawn in rivers at night).
• Optimize random_configs to design different battle builds (tank, offensive, speed) for diverse challenges.
• Modify reward_rule to set attractive loot matching the Boss's difficulty (e.g., rare candies, evolution stones).

The template can be directly copied and used, and you can replace the species ID, moves, and attributes to create custom Bosses for any Pokémon.

Complete Guide to Cobblemon Boss Mod - Configuration Files & Commands

1. Overview of Configuration Files

All configuration files are in toml format and are generated in the config/cobblemonboss/ directory of the server/world save. They support runtime modification (take effect by executing the /reload command after modification). Configuration files are managed uniformly by the ConfigManager class, and all configuration retrieval methods include fault tolerance to return default values when configurations are not loaded, preventing mod crashes.

1.1 Player Pokémon Level Limit Configuration (player-level-limit.toml)

Corresponding Class: PlayerLevelLimitConfig
Core Function: Limits the maximum level of Pokémon held by players to prevent level-based overpowering of Bosses.

Configuration Item	Type	Default Value	Value Range	Description
enablePlayerLevelLimit	Boolean	true	true/false	Whether to enable the player's Pokémon level limit
maxPlayerPokemonLevel	Integer	100	1~10000	Maximum allowed level for a player's Pokémon

1.2 Boss Battle Detection Configuration (boss-battle-check.toml)

Corresponding Class: PokemonBossBattleCheckConfig
Core Function: Regulates the fairness of Boss battles by prohibiting the use of unbalanced Pokémon, items, and moves.

Configuration Item	Type	Default Value	Description
# Basic Settings	-	-	-
enableBattleCheck	Boolean	false	Whether to enable the overall Boss battle detection feature
cancelBattle	Boolean	true	Whether to cancel the battle when banned content is detected (false = only log a warning)
# Banned Pokémon Settings	-	-	-
enablePokemonCheck	Boolean	true	Whether to check for banned Pokémon
bannedPokemonList	String List	["cobblemon:ditto"]	List of banned Pokémon IDs (fill in Cobblemon registered IDs)
# Banned Item Settings	-	-	-
enableItemCheck	Boolean	true	Whether to check for banned items
bannedItemsList	String List	["cobblemon:master_ball"]	List of banned item IDs (Master Ball is banned by default)
# Banned Move Settings	-	-	-
enableMoveCheck	Boolean	true	Whether to check for banned moves
bannedMovesList	String List	["endeavor"]	List of banned move IDs (Endeavor is banned by default to prevent instant KO of Bosses)

1.3 Boss Capture Restriction Configuration (boss-capture.toml)

Corresponding Class: PokemonBossCaptureConfig
Core Function: Controls whether Boss Pokémon can be captured to prevent rare Bosses from being easily caught.

Configuration Item	Type	Default Value	Description
preventBossCapture	Boolean	true	Whether to prevent Boss Pokémon from being captured
showCaptureMessage	Boolean	true	Whether to display a capture prevention message to the player

1.4 Boss Damage Immunity Configuration (boss-immune.toml)

Corresponding Class: PokemonBossImmuneConfig
Core Function: Globally controls whether Bosses are immune to all damage, used to create invincible Bosses or special gameplay.

Configuration Item	Type	Default Value	Description
enableBossImmune	Boolean	true	Whether to enable Boss damage immunity (Bosses become invincible when enabled)

1.5 Boss Level Configuration (boss-level.toml)

Corresponding Class: PokemonBossLevelConfig
Core Function: Dynamically calculates Boss levels to adapt to the player's team strength and ensure balanced battle difficulty.

Configuration Item	Type	Default Value	Value Range	Description
bossLevelMultiplier	Floating-point	1.5	1.0~10.0	Boss level multiplier (default = player's highest level × 1.5)
minBossLevel	Integer	5	1~100	Minimum Boss level (prevents excessively low levels)
maxBossLevel	Integer	200	50~200	Maximum Boss level (Important Note: Do not set this value above 500, as exceeding this range will cause the mod to crash due to numerical overflow; it is recommended to keep it below 500)
includePCPokemon	Boolean	true	true/false	Whether to include Pokémon levels in the player's PC when calculating levels
scaleByMaxLevel	Boolean	true	true/false	true = calculate dynamically based on the player's highest level; false = use a fixed level (fixed value = minBossLevel)

1.6 Boss Reward Configuration (boss-reward.toml)

Corresponding Class: PokemonBossRewardConfig
Core Function: Controls the drop probability of Boss defeat rewards, supporting dynamic adjustment by level (Drop Probability = minDropRate + (maxDropRate - minDropRate) × (Boss Level / levelScale)).

Configuration Item	Type	Default Value	Value Range	Description
minDropRate	Floating-point	0.1	0.0~1.0	Minimum drop rate for Boss rewards (0 = no drop, 1 = guaranteed drop)
maxDropRate	Floating-point	1.0	0.0~1.0	Maximum drop rate for Boss rewards
levelScale	Integer	100	1~1000	Level scaling factor (higher values result in slower drop rate scaling with level)

1.7 Boss Spawn Configuration (boss-spawn.toml)

Corresponding Class: PokemonBossSpawnConfig
Core Function: Controls the frequency and probability of automatic Boss spawning, serving as the core configuration for automatic mob spawning.

Configuration Item	Type	Default Value	Value Range	Description
enableBossSpawn	Boolean	true	true/false	Whether to enable the automatic Boss spawn system
checkIntervalTicks	Integer	12000	100~72000	Spawn check interval (in game ticks; 20 ticks = 1 second; default 12000 ticks = 10 minutes)
spawnChance	Floating-point	0.1	0.0~1.0	Probability of spawning per check (default 0.1 = 10% spawn chance)

2. Core Command Instructions

The mod provides 2 custom commands for querying and manually spawning Bosses, adapting to the different needs of administrators and players.

2.1 Query Spawnable Bosses Command: /checkpokemonboss

Corresponding Class: CheckPokemonBossCommand

Item	Description
Permission Requirement	All players (permission level 0)
Usage	/checkpokemonboss (no parameters)
Core Function	Filters and displays the list of spawnable Bosses (including spawn weight) based on the player's current location, biome, and time
Output Examples	- No available Bosses: No spawnable Boss Pokémon at your current location - Available Bosses: Spawnable Boss Pokémon: §9💧Blastoise Boss💧 - Spawn Weight: 4 §c🔥Charizard Boss🔥 - Spawn Weight: 5
Notes	Only executable by players; executing via console/command block will prompt "This command can only be used by players"

2.2 Manually Spawn Boss Command: /spawnpokemonboss

Corresponding Class: SpawnPokemonBossCommand

Item	Description
Permission Requirement	Administrators (permission level 2)
Usage	1. Basic Usage: /spawnpokemonboss <bossUniqueId> (default level 1) 2. Usage with Level: /spawnpokemonboss <bossUniqueId> <level> (level range 1~900)
Core Function	Manually spawns a Boss of the specified level near the player via the Boss unique ID (unique_id) (spawned 5 blocks in front of the player)
Features	- Auto-Completion: Press Tab while entering the command to auto-complete all configured Boss unique IDs - Exact Match: Only supports Boss unique IDs (case-insensitive), not species IDs - Level Restriction: Level parameter is forced to the range 1~900; exceeding this range will prompt "Level must be between 1 and 900"; It is recommended to keep the level below 500 in actual use to avoid mod crashes
Output Examples	- Success: Boss Pokémon spawned: §9💧Blastoise Boss💧 (Unique ID: blastoise_water_boss, Level: 50) - Failure: No Boss found with the unique ID "charizard_fire"
Notes	Only executable by players; executing via console will prompt "This command can only be used by players"

3. Summary

1. Configuration System: 7 core configuration files cover all dimensions of Boss spawning, leveling, battle rules, rewards, capture, and immunity, supporting refined customization of mod gameplay. All configuration items have value range restrictions to avoid invalid configurations; it is recommended to set the maximum Boss level below 500 to prevent mod crashes due to numerical overflow.
2. Command System: The two commands have clear divisions of labor: /checkpokemonboss is for all players to query available Bosses, and /spawnpokemonboss is for administrators to manually spawn Bosses. Note that the level should not exceed 500 when manually spawning to adapt to different usage scenarios.