CobbleBoss Boss User Guide

1. Data Pack Structure

CobbleBoss data packs use the cobbleboss namespace.

Normal Boss files are placed in:

data/cobbleboss/bosses/

Paid multiplayer Boss team files are placed in:

data/cobbleboss/boss_teams/

Main structure:

pack.mcmeta
data/cobbleboss/bosses/
data/cobbleboss/boss_teams/

Recommended file naming:

Use lowercase English letters.
Use underscores instead of spaces.
Use clear names related to the Boss.
Keep each Boss file independent.

2. What A Boss JSON Controls

A Boss JSON controls:

Which Pokemon the Boss is
Boss display name
Boss glow color
Natural spawn rules
Rewards after victory
Punishments after defeat
Moves
EVs
Custom battle stats
Nature
Ability
Form
Held items
Battle mode
Actions per turn
Shield settings
Phase skills
Boss size

3. Recommended Reading Order

For beginners, understand these parts first:

Boss identity
Spawn rules
Rewards and punishments
Battle configuration
Visual settings
Advanced raid mechanics

Most important fields:

unique_id
species_id
random_configs

Recommended fields:

display_name
glow
moves
battle_mode
actions_per_turn
scale

Optional fields:

spawn_rule
reward_rule
punish_rule
effort_values
custom_battle_stats
phase_skills
held_items
nature
ability
form
shield_layers
shield_recover_per_turn
shield_weaken_turns

4. Top-Level Boss Fields

`unique_id`

Purpose:

The unique internal ID of the Boss.

Recommendation:

Required.

Notes:

Must be unique.
Commands use this ID.
Do not reuse the same ID in multiple Boss files.
Recommended format is lowercase English letters with underscores.

`display_name`

Purpose:

The name shown to players in game.

Recommendation:

Recommended.

Notes:

Supports Minecraft color codes.
Useful for making Boss names more obvious.
If omitted, the species name may be used instead.

`species_id`

Purpose:

Defines which Pokemon species the Boss is.

Recommendation:

Required.

Notes:

Usually uses the cobblemon namespace.
This determines the actual Pokemon created by the Boss system.

`glow`

Purpose:

Controls the Boss glowing outline color after it spawns.

Position:

Top-level field.

Recommendation:

Optional.

How it works:

If set, the Boss receives a glowing outline.
If missing or empty, the Boss does not glow.
Uses Minecraft color names.

Available colors:

black
dark_blue
dark_green
dark_aqua
dark_red
dark_purple
gold
gray
dark_gray
blue
green
aqua
red
light_purple
yellow
white

Notes:

Invalid colors can cause the Boss file to fail loading.
This only controls entity glow, not announcement color.

`spawn_rule`

Purpose:

Controls natural spawning rules.

Recommendation:

Optional.

Important:

For natural spawning, a Boss usually needs:

spawn_locations
spawn_times
spawn_biomes or spawn_structures
spawn_weight

Notes:

A Boss without usable spawn rules may not participate in natural spawning.
spawn_biomes and spawn_structures are checked as biome-or-structure matching.

`reward_rule`

Purpose:

Controls rewards after players defeat the Boss.

Recommendation:

Optional.

Can contain:

Direct item rewards
Direct command rewards
Reward pools that roll once and randomly choose one entry
Count
Chance
Weight
Rolls

`punish_rule`

Purpose:

Controls punishments after players lose to the Boss.

Recommendation:

Optional.

Can contain:

Level reduction
EV reduction
IV reduction
Command punishment
Chance

`random_configs`

Purpose:

Defines one or more possible battle configurations for this Boss.

Recommendation:

Required.

How it works:

A Boss can have multiple random configurations.
One configuration is selected when the Boss is created.
Different configurations can have different moves, stats, held items, battle modes, shield settings, and size.

5. Spawn Rule Fields

`spawn_locations`

Purpose:

Restricts where the Boss can spawn.

Available values:

land
water_surface
underwater
cave
sky
lava

Notes:

Natural spawning needs a valid spawn location type.
Use values that match the Boss theme.

`spawn_times`

Purpose:

Restricts the time period when the Boss can spawn.

Available values:

all_day
early_morning
morning
noon
afternoon
dusk
night
midnight

Time mapping:

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

Notes:

Minecraft has 24000 ticks per day.
Multiple time values can be used.
all_day means the Boss can spawn at any time.

`spawn_biomes`

Purpose:

Restricts which biomes the Boss can spawn in.

How it works:

A normal biome ID limits spawning to that biome.
A biome tag starting with # allows all biomes in that tag.

Notes:

Use biome IDs for precise control.
Use biome tags for broader biome groups.
This can be combined with spawn_structures.

`spawn_structures`

Purpose:

Allows Boss spawning when the player is inside specific structures.

How it works:

Uses structure IDs.
If the player is inside a matching structure, the Boss can match this rule.
This is checked together with biome rules as biome-or-structure matching.

Notes:

This is for structure IDs, not structure tags.
Useful for dungeon, temple, ruin, stronghold, or custom structure Bosses.

`spawn_weight`

Purpose:

Controls natural spawn selection weight.

How it works:

When multiple Bosses are valid, higher weight means higher selection chance.
It is not a direct percentage.

Notes:

Use positive values.
If all valid weights are 0, selection may fall back to random valid Boss selection.

6. Reward Rule Fields

`reward_items`

Purpose:

List of direct reward entries.

How it works:

Each entry rolls independently.
If three entries each have chance: 0.1, each one has its own 10% chance.
The player can receive multiple entries from the same reward_items list.

Each reward entry can contain:

item_id
count
command
chance
weight

weight is only used when the same reward entry is placed inside reward_pools.entries. It is harmless but unnecessary in direct reward_items.

`reward_pools`

Purpose:

List of reward pools.

How it works:

Each pool rolls once using its chance.
If the pool succeeds, the mod randomly chooses one entry from entries.
If rolls is greater than 1, the pool chooses that many entries.
Selection is weighted by each entry's weight.
Selection is with replacement, so the same entry can be selected more than once when rolls is greater than 1.

Each reward pool can contain:

chance
rolls
entries

Each pool entry can contain:

item_id
count
command
chance
weight

Important:

Pool-level chance controls whether the pool gives anything.
Entry-level chance is parsed for compatibility, but pool entries are selected by random weight after the pool succeeds.
If you want separate independent chances, use reward_items.
If you want "10% chance for one item from this list", use reward_pools.

`item_id`

Purpose:

The item given to the player.

Notes:

Use a valid item ID.
Can be Minecraft, Cobblemon, or another mod item.

`count`

Purpose:

The number of items given.

Notes:

If omitted, it usually acts as 1.
Count is only used for item rewards.
Must be greater than 0.

`command`

Purpose:

Executes a command as a reward.

Notes:

Useful for giving Pokemon, money, points, titles, permissions, or other server rewards.
Supports the {player} placeholder.
Write the command without a leading slash.

`chance`

Purpose:

Controls probability.

For direct reward_items:

If chance is greater than 0, that custom chance is used.
If chance is missing or 0, the reward uses the default drop rate from boss-reward.toml.

For reward_pools:

If pool chance is greater than 0, that custom chance is used.
If pool chance is missing or 0, the pool uses the default drop rate from boss-reward.toml.

Meaning:

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

`rolls`

Purpose:

Controls how many entries are selected from a successful reward pool.

Notes:

If omitted, it defaults to 1.
Must be greater than 0.
The same entry can be selected more than once.

`weight`

Purpose:

Controls selection chance inside a reward pool.

How it works:

Higher weight means higher chance inside that pool.
Default weight is 1.
Weight is not a direct percentage.

Example:

Entry A weight 1
Entry B weight 3
Entry B is three times as likely as Entry A inside that pool.

Reward Examples

Independent rewards:

"reward_rule": {
  "reward_items": [
    {
      "item_id": "cobblemon:poke_ball",
      "count": 3,
      "chance": 0.1
    },
    {
      "item_id": "cobblemon:great_ball",
      "count": 2,
      "chance": 0.1
    },
    {
      "item_id": "cobblemon:ultra_ball",
      "count": 1,
      "chance": 0.1
    }
  ]
}

One reward from a pool:

"reward_rule": {
  "reward_pools": [
    {
      "chance": 0.1,
      "rolls": 1,
      "entries": [
        {
          "item_id": "cobblemon:poke_ball",
          "count": 3
        },
        {
          "item_id": "cobblemon:great_ball",
          "count": 2
        },
        {
          "item_id": "cobblemon:ultra_ball",
          "count": 1
        }
      ]
    }
  ]
}

Weighted pool:

"reward_rule": {
  "reward_pools": [
    {
      "chance": 0.25,
      "rolls": 1,
      "entries": [
        {
          "item_id": "minecraft:diamond",
          "count": 1,
          "weight": 1
        },
        {
          "item_id": "minecraft:emerald",
          "count": 3,
          "weight": 3
        },
        {
          "command": "give {player} minecraft:gold_ingot 8",
          "weight": 5
        }
      ]
    }
  ]
}

Direct rewards and pools can be used together:

"reward_rule": {
  "reward_items": [
    {
      "item_id": "minecraft:gold_ingot",
      "count": 2,
      "chance": 1.0
    }
  ],
  "reward_pools": [
    {
      "chance": 0.1,
      "entries": [
        {
          "item_id": "cobblemon:poke_ball",
          "count": 3
        },
        {
          "item_id": "cobblemon:great_ball",
          "count": 2
        },
        {
          "item_id": "cobblemon:ultra_ball",
          "count": 1
        }
      ]
    }
  ]
}

7. Punish Rule Fields

`punish_items`

Purpose:

List of punishment entries.

Each punishment entry can contain:

level
evs
ivs
command
chance

`level`

Purpose:

Reduces Pokemon level after losing.

Notes:

Level will not be reduced below 1.
Use carefully because level loss can feel severe.

`evs`

Purpose:

Reduces effort values.

Available stats:

hp
attack
defense
special_attack
special_defense
speed

Notes:

Only fill stats you want to reduce.
Missing stats are ignored.

`ivs`

Purpose:

Reduces individual values.

Available stats:

hp
attack
defense
special_attack
special_defense
speed

Notes:

IV punishment is very severe.
Recommended only for high-risk Boss designs.

`command`

Purpose:

Executes a command as punishment.

Notes:

Useful for applying effects, taking currency, teleporting, broadcasting, or triggering server systems.
Supports the {player} placeholder.
Write the command without a leading slash.

`chance`

Purpose:

Controls the probability of this punishment.

Important:

If chance is greater than 0, that custom chance is used.
If chance is missing or 0, the punishment uses the default penalty chance from boss-penalty.toml.

8. Random Config Fields

`shiny`

Purpose:

Controls whether the Boss is shiny.

Notes:

true makes the Boss shiny.
false makes it normal.
If omitted, it usually defaults to false.

`effort_values`

Purpose:

Sets the Boss EV spread.

Available stats:

hp
attack
defense
special_attack
special_defense
speed

Rules:

Each stat should be between 0 and 252.
Total EVs should not exceed 510.

`custom_battle_stats`

Purpose:

Overrides or limits Boss battle stats.

Available stats:

hp
attack
defense
special_attack
special_defense
speed

Each stat rule uses:

value
mode

`value`

Purpose:

The target stat value.

Notes:

Usually a positive number.
Useful for raid-style Bosses.

`mode`

Purpose:

Controls how the stat value is applied.

Available values:

exact
minimum
maximum

Meanings:

exact: use this value directly.
minimum: stat will be at least this value.
maximum: stat will be at most this value.

`moves`

Purpose:

Sets the Boss moves.

Notes:

Usually use up to 4 moves.
Move names should match Cobblemon move IDs.
Invalid move names can cause Boss creation failure.

`nature`

Purpose:

Sets the Boss nature.

Notes:

If omitted, the Boss uses a default nature.
Use Cobblemon nature names.

`ability`

Purpose:

Sets the Boss ability.

Notes:

If omitted, default ability behavior is used.
Invalid ability names can cause Boss creation failure.

`form`

Purpose:

Sets the Boss form.

Notes:

Use this for special forms.
Leave empty if not needed.
The value should match Cobblemon form or aspect behavior.

`held_items`

Purpose:

Sets possible held items for the Boss.

Notes:

Can contain one or more item IDs.
If multiple items are configured, the Boss may randomly use one.
Invalid item IDs can cause Boss creation failure.

`battle_mode`

Purpose:

Sets the Boss battle mode and battle layout.

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

Important:

battle_mode does not limit actions_per_turn.

Notes:

This field controls the battle mode and layout.
Boss action count is controlled separately by actions_per_turn.

`actions_per_turn`

Purpose:

Sets how many actions the Boss can take each turn.

Rules:

Must be at least 1.
Not limited by battle_mode.

Notes:

Higher values make the Boss much harder.
This is one of the main difficulty controls.

`scale`

Purpose:

Sets the Boss size.

Position:

Inside random_configs.

How it works:

If set, the Boss uses this custom size.
If omitted, the Boss size is calculated automatically from its level.

Rules:

Must be greater than 0.
The final value is clamped by the mod's allowed size range.

Notes:

Use this to create giant Bosses.
Leave it empty for automatic level-based size.

9. Boss Shield System

Purpose:

The Boss shield system gives a Boss extra protection during battle.

How it works:

A Boss can start battle with shield layers.
Certain attacks can consume shield layers.
Super-effective damaging moves can consume shield layers.
Special moves can consume configured shield layers.
While shield still exists, some shield interactions can reduce or block damage.
When shield reaches 0, the shield breaks.
After shield breaks, the Boss can enter a weakened state.
After weakened turns end, shield can recover each turn if recovery is configured.

Important:

The global shield switch in boss-shield.toml must be enabled.

The Boss also needs shield fields inside random_configs.

`shield_layers`

Purpose:

Sets the Boss initial shield layers.

Position:

Inside random_configs.

How it works:

0 means this Boss has no shield.
A value greater than 0 enables shield behavior for this Boss.
This value is also used as the maximum shield layer count.

Rules:

Must be 0 or higher.

Notes:

This is the main field that enables shield for a specific Boss.
If this value is 0, the other shield fields usually have no effect.

`shield_recover_per_turn`

Purpose:

Controls how many shield layers the Boss recovers each turn after shield break and weakened state.

Position:

Inside random_configs.

How it works:

0 means shield does not recover.
A value greater than 0 allows shield recovery.
Shield recovery cannot exceed maximum shield layers.

Rules:

Must be 0 or higher.

Notes:

Use 0 for one-time shield break behavior.
Use higher values for raid-style repeated shield breaking.

`shield_weaken_turns`

Purpose:

Controls how many turns the Boss stays weakened after shield breaks.

Position:

Inside random_configs.

How it works:

When shield reaches 0, the shield breaks.
The Boss enters weakened state for this many turns.
During weakened turns, shield recovery waits.
After weakened turns end, shield recovery can begin if configured.

Rules:

Must be 0 or higher.

Notes:

Use this to create a damage window after shield break.
Larger values give players more time to attack.
0 means no weakened delay.

10. Phase Skill System

`phase_skills`

Purpose:

Changes Boss moves based on HP percentage.

How it works:

Each phase has an HP percentage.
When Boss HP reaches that percentage, the Boss can switch to another moveset.

Notes:

Useful for multi-phase Boss fights.
Avoid duplicate HP thresholds.
Moves should be valid Cobblemon move names.

`hp_percent`

Purpose:

The HP percentage that triggers the phase.

Rules:

Usually 1 to 100.
Lower or equal HP enters that phase.

Notes:

Higher values trigger earlier.
Lower values trigger later.

`moves`

Purpose:

The moves used in this phase.

Notes:

Usually 1 to 4 moves.
Use this to make the Boss change strategy during battle.

11. Stat Key Reference

The following stat keys are used in effort_values, evs, ivs, and custom_battle_stats:

hp
attack
defense
special_attack
special_defense
speed

12. Configuration Files

All configuration files are placed under:

config/cobbleboss/

Unified config files:

level-mapping.json
pokemon-max-level.json
boss-spawn.toml
boss-level.toml
boss-reward.toml
boss-penalty.toml
boss-battle-check.toml
boss-capture.toml
boss-immune.toml
boss-music.toml
boss-shield.toml
player-level-limit.toml

Important:

Fabric and NeoForge use the same field names and top-level TOML structure.

If an old NeoForge config was generated before this unified version, delete the old config file or manually move values to the top level.

`level-mapping.json`

Purpose:

Maps player Pokemon level to Boss level.

Notes:

Used only when custom level mapping is enabled.
The left side is player level.
The right side is Boss level.
If no mapping is found, normal level calculation can be used.

`pokemon-max-level.json`

Purpose:

Controls Cobblemon's global maximum Pokemon level.

Fields:

configName
maxPokemonLevel
description

Notes:

Default max level is usually 900.
This affects the global Pokemon level limit used by Cobblemon.

`boss-spawn.toml`

Purpose:

Controls natural Boss spawning.

Fields:

enableBossSpawn
checkIntervalTicks
spawnChance
enableSpawnTimeRandom
randomValueMin
randomValueMax
spawnFrequency

Notes:

checkIntervalTicks range is 100 to 72000.
spawnChance range is 0 to 1.
randomValueMin and randomValueMax range is 1 to 10000.
spawnFrequency range is 0 to 100.

`boss-level.toml`

Purpose:

Controls Boss level calculation.

Fields:

bossLevelMultiplier
minBossLevel
maxBossLevel
includePCPokemon
scaleByMaxLevel
enableCustomLevelMapping
enableLevelRandom
randomMin
randomMax

Notes:

bossLevelMultiplier range is 1.0 to 10.0.
minBossLevel range is 1 to 100.
maxBossLevel range is 50 to 200.
enableCustomLevelMapping controls whether level-mapping.json is used.

`boss-reward.toml`

Purpose:

Controls default Boss reward chance.

Fields:

minDropRate
maxDropRate
levelScale

Important:

Direct reward entries and reward pools with chance greater than 0 use their own chance.

Direct reward entries and reward pools without chance, or with chance 0, use the default drop rate from this config.

Notes:

minDropRate and maxDropRate range is 0 to 1.
levelScale range is 1 to 1000.

`boss-penalty.toml`

Purpose:

Controls default punishment chance.

Fields:

enablePenalty
minPenaltyChance
maxPenaltyChance
penaltyLevelScale

Important:

Punish entries with chance greater than 0 use their own chance.

Punish entries without chance, or with chance 0, use the default penalty chance from this config.

Notes:

minPenaltyChance and maxPenaltyChance range is 0 to 1.
penaltyLevelScale range is 1 to 1000.

`boss-battle-check.toml`

Purpose:

Controls Boss battle restriction checks.

Fields:

enableBattleCheck
cancelBattle
enablePokemonCheck
bannedPokemonList
enableItemCheck
bannedItemsList
enableMoveCheck
bannedMovesList

Notes:

enableBattleCheck is the main switch.
cancelBattle controls whether battle is cancelled when banned content is detected.
bannedPokemonList uses Pokemon species IDs.
bannedItemsList uses item IDs.
bannedMovesList uses move IDs.

`boss-capture.toml`

Purpose:

Controls whether Boss Pokemon can be captured.

Fields:

preventBossCapture
showCaptureMessage

Notes:

preventBossCapture should usually stay enabled.
showCaptureMessage controls whether players see a message when capture is blocked.

`boss-immune.toml`

Purpose:

Controls whether Boss entities are invulnerable in the world.

Fields:

enableBossImmune

Important:

This mainly protects Boss entities outside normal battle damage.

It does not mean the Boss is immune to every move inside battle.

Notes:

Recommended to keep enabled.
Helps prevent players from killing Bosses with non-battle methods.

`boss-music.toml`

Purpose:

Controls Boss battle music.

Fields:

enableBossBattleMusic
stopOnBattleEnd

Important:

The music system no longer uses bossBattleMusicSoundId.

When a Boss battle starts, the mod randomly selects a music sound event from:

The mod's built-in assets/cobbleboss/sounds.json.
Enabled resource packs that define music in sounds.json.

Resource packs that are only placed in the resourcepacks folder but not enabled in the client resource pack menu are ignored.

Notes:

Default built-in sound event is cobbleboss:boss_battle_theme.
Custom music must be provided by a resource pack.
The sound file should be OGG format.
Players need the resource pack enabled to hear resource-pack music.
Old configs containing bossBattleMusicSoundId should be regenerated or cleaned up.

`boss-shield.toml`

Purpose:

Controls the global Boss shield system.

Fields:

enableBossShield
superEffectiveLayers
moveLayerOverrides

Meaning:

enableBossShield: enables or disables Boss shield behavior.
superEffectiveLayers: shield layers consumed by super-effective damaging moves.
moveLayerOverrides: special move-to-shield-layer rules.

Notes:

If enableBossShield is false, Boss JSON shield fields will not work.
moveLayerOverrides uses move IDs and shield layer values.

`player-level-limit.toml`

Purpose:

Controls player Pokemon level limit.

Fields:

enableLevelLimit
maxPlayerPokemonLevel

Notes:

enableLevelLimit enables the player Pokemon level cap.
maxPlayerPokemonLevel sets the maximum allowed player Pokemon level.

13. Resource Pack Music

Boss battle music can be customized through resource packs.

How it works:

The mod has built-in music in assets/cobbleboss/sounds.json.
Enabled resource packs can add more music events.
When a Boss battle starts, the mod randomly chooses one available music event.
There is no need to specify one sound ID in config.

Resource pack paths:

pack.mcmeta
assets/cobbleboss/sounds.json
assets/cobbleboss/sounds/music/

Example structure:

my_boss_music_pack.zip
pack.mcmeta
assets/cobbleboss/sounds.json
assets/cobbleboss/sounds/music/boss_1.ogg
assets/cobbleboss/sounds/music/boss_2.ogg
assets/cobbleboss/sounds/music/boss_3.ogg

Example sounds.json:

{
  "music.boss_1": {
    "category": "music",
    "sounds": [
      {
        "name": "cobbleboss:music/boss_1",
        "stream": true
      }
    ]
  },
  "music.boss_2": {
    "category": "music",
    "sounds": [
      {
        "name": "cobbleboss:music/boss_2",
        "stream": true
      }
    ]
  }
}

Matching files:

assets/cobbleboss/sounds/music/boss_1.ogg
assets/cobbleboss/sounds/music/boss_2.ogg

Sound ID examples:

music.boss_1 in assets/cobbleboss/sounds.json becomes cobbleboss:music.boss_1.
music.boss_2 in assets/cobbleboss/sounds.json becomes cobbleboss:music.boss_2.

Music detection:

The mod treats a sound event as Boss music if one of these is true:

The event key starts with music.
The event key contains .music.
The event has "category": "music".
One of its sound file paths is inside a music/ folder.

Notes:

Use OGG format.
Use stream: true for music.
Players need the resource pack enabled to hear custom music.
Use original or licensed music only.
If the resource pack is not enabled, the client will not register its sound events.

14. Fixed Spawn Point Commands

Main command:

/spawnpokemonbossat

Permission:

Requires administrator permission.

Functions:

create
addboss
removeboss
setweight
remove
list
info
trigger
settext
cleartext
announcement enable
announcement text
announcement color
announcement clear

`create`

Purpose:

Creates a fixed Boss spawn point.

Parameters:

Spawn point ID
Dimension
X coordinate
Y coordinate
Z coordinate
Boss level
Respawn seconds
Optional hologram text

Notes:

Spawn point ID must be unique.
Respawn time is in seconds.
Boss level range is 1 to 900.

`addboss`

Purpose:

Adds a Boss to a fixed spawn point pool.

Parameters:

Spawn point ID
Boss unique ID
Weight

Notes:

Boss unique ID must exist in loaded Boss data.
Higher weight means higher chance inside that fixed spawn point.

`removeboss`

Purpose:

Removes a Boss from a fixed spawn point pool.

`setweight`

Purpose:

Changes the weight of a Boss in a fixed spawn point pool.

`remove`

Purpose:

Deletes a fixed spawn point.

Notes:

Removes spawn point data.
Removes related hologram display.
Handles the currently active fixed Boss.

`list`

Purpose:

Lists all fixed spawn points.

Shows:

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

`info`

Purpose:

Shows detailed information for one spawn point.

Shows:

Dimension
Coordinates
Boss level
Respawn time
Next respawn tick
Current active Boss
Hologram text
Boss pool
Announcement status
Announcement text
Announcement color

`trigger`

Purpose:

Manually makes a spawn point ready to spawn again.

Notes:

Useful for testing.
Does not delete the spawn point.

`settext`

Purpose:

Sets fixed spawn point hologram text.

Supported placeholders:

{id}
{level}
{time}
{x}
{y}
{z}
{dimension}
{boss_count}
{boss_pool}
{active_boss_id}
{active_boss}
{active_weight}

Notes:

Use | to separate multiple hologram lines.
Hologram placeholders are different from announcement placeholders.

`cleartext`

Purpose:

Clears custom hologram text and restores default hologram behavior.

`announcement enable`

Purpose:

Enables or disables fixed spawn point announcement.

How it works:

true enables announcement.
false disables announcement.

Notes:

There is no separate announcement disable command.
Use announcement enable with true or false.

`announcement text`

Purpose:

Sets custom announcement text.

Supported placeholders:

{boss}
{boss_id}
{species}
{point}
{dimension}
{x}
{y}
{z}
{position}

`announcement color`

Purpose:

Sets announcement message color.

Available colors:

black
dark_blue
dark_green
dark_aqua
dark_red
dark_purple
gold
gray
dark_gray
blue
green
aqua
red
light_purple
yellow
white

Notes:

Default color is gold.
This changes announcement color, not Boss glow color.

`announcement clear`

Purpose:

Restores the default announcement text.

Notes:

Does not remove the spawn point.
Does not clear hologram text.
Only resets the fixed spawn announcement template.

Fixed Spawn Boss Pool Weight

Purpose:

Controls selection chance inside one fixed spawn point.

Rules:

Minimum weight: 1
Maximum weight: 1000000

Notes:

This is separate from natural spawn_rule.spawn_weight.
Higher weight means higher chance inside that fixed spawn point pool.

15. Basic Boss Commands

`checkpokemonboss`

Purpose:

Checks which Bosses can spawn at the player's current location.

Shows:

Time until next Boss refresh
Matching Bosses
Boss display names
Spawn weights

Permission:

Usually available to normal players.

`spawnpokemonboss`

Purpose:

Directly spawns a Boss near the player.

Parameters:

Boss unique ID
Optional level

Permission:

Requires administrator permission.

Notes:

Uses Boss unique ID, not species ID.
Level range is 1 to 900.
Useful for testing Boss configuration.

`spawnpokemonbossat`

Purpose:

Manages fixed Boss spawn points.

Permission:

Requires administrator permission.

16. Beginner Setup Suggestions

For the simplest setup:

Enable natural Boss spawning.
Use a reasonable spawn interval.
Use a low spawn chance at first.
Enable Boss capture prevention.
Enable Boss immunity.
Use level mapping or level multiplier.
Add rewards with reasonable chance values.
Add glow to make Bosses easier to find.
Leave scale empty unless you want giant Bosses.

For stricter Boss servers:

Enable battle checks.
Ban specific Pokemon if needed.
Ban specific items if needed.
Ban specific moves if needed.
Increase Boss stats through custom_battle_stats.
Use actions_per_turn carefully.
Add shield settings for raid-style fights.

For casual servers:

Keep punishments low or disabled.
Use visible Boss glow.
Use moderate Boss size.
Give guaranteed small rewards and rare special rewards.
Use reward pools for "one item from this group" rewards.
Avoid extremely high actions_per_turn.

17. Common Problems

Boss does not load

Possible reasons:

Duplicate unique_id.
Invalid species_id.
Invalid move name.
Invalid ability name.
Invalid item ID.
Invalid glow color.
Invalid scale value.
Broken JSON format.
Empty reward_pools.entries.
Invalid reward pool rolls.
Invalid reward pool entry weight.

Boss does not spawn naturally

Possible reasons:

Natural spawning is disabled.
Spawn chance is too low.
Spawn interval has not passed.
Current biome does not match.
Current structure does not match.
Current time does not match.
Current location type does not match.
spawn_weight is missing or too low.
Boss file is not loaded.

Boss music does not play

Possible reasons:

Boss music config is disabled.
The selected sound event is not registered on the client.
Resource pack is not enabled.
Sound file path is wrong.
Sound file is not OGG format.
Client does not have the resource pack.
The resource pack was placed in the folder but not moved to the enabled list.
Music volume is muted.

Important:

The mod randomly chooses from built-in music and enabled resource packs.

It does not use bossBattleMusicSoundId.

Boss shield does not work

Possible reasons:

Global Boss shield config is disabled.
shield_layers is 0 or missing.
The move used does not consume shield layers.
superEffectiveLayers is set to 0.
The move is not super-effective.
The move is not listed in moveLayerOverrides.
Boss was spawned from old or outdated data.

Boss is too small or too large

Possible reasons:

scale is set too low or too high.
Boss level causes automatic scale calculation.
Scale is clamped by the mod's allowed range.

Boss does not glow

Possible reasons:

glow is not set.
Glow color is invalid.
Boss was spawned from old data.
Another system removed the glow effect.

Announcement color does not change

Possible reasons:

The color name is invalid.
The wrong spawn point ID was used.
Announcement is disabled.
The message being checked is not the fixed spawn announcement.

Old NeoForge config does not work

Possible reasons:

The config was generated before unified config fields.
Old grouped TOML sections are still present.
Old shield snake_case fields are still present.
Old bossBattleMusicSoundId is still present.

Fix:

Delete the old config file and let the mod regenerate it.
Or move the old values to the new top-level fields.
Remove old music sound ID configuration.

18. Summary

CobbleBoss configuration can be understood like this:

Use unique_id, species_id, display_name, and glow to define Boss identity and appearance.
Use spawn_rule to define where and when it appears.
Use reward_rule and punish_rule to define win and loss results.
Use reward_items for independent reward rolls.
Use reward_pools for "roll once, then choose one reward from this list".
Use random_configs to define stats, moves, battle mode, action count, shield, phase skills, held items, form, ability, shiny state, and size.
Use config files to control global Boss behavior.
Use resource packs to add random Boss battle music.
Use fixed spawn point commands to create controlled Boss spawn locations.

19. Paid Feature: Multiplayer Team Boss Battles

This is an advanced paid feature.

Data pack path:

data/cobbleboss/boss_teams/

A Boss team file defines a group Boss battle.

Fields:

team_id
pokemon_unique_ids
spawn_structures
defeat_rewards
punish_rule

`team_id`

Purpose:

The unique ID of the Boss team.

Notes:

If no namespace is written, cobbleboss is used.
Commands can use this ID.

`pokemon_unique_ids`

Purpose:

The Boss Pokemon unique IDs used by this team.

Notes:

These IDs must match normal Boss JSON unique_id values.
The team system creates Boss Pokemon from existing Boss definitions.

`spawn_structures`

Purpose:

Controls which structures can trigger this Boss team.

Notes:

Uses structure IDs.
When a player is inside a matching structure and sends out a Pokemon, the team battle can be triggered.
Structure instances are recorded so the same structure is not repeatedly triggered.

`defeat_rewards`

Purpose:

Rewards after defeating the Boss team.

Fields:

reward_items
reward_pools
item_id
count
command
chance
rolls
weight

How it works:

reward_items behave as independent reward rolls.
reward_pools roll once, then randomly choose entries from the pool.
Team reward pools use the same format as normal Boss reward pools.

Chance note:

If chance is greater than 0, that custom chance is used.

If chance is missing or 0, the default reward chance can be used.

Example:

"defeat_rewards": {
  "reward_items": [
    {
      "item_id": "minecraft:gold_ingot",
      "count": 4,
      "chance": 1.0
    }
  ],
  "reward_pools": [
    {
      "chance": 0.1,
      "rolls": 1,
      "entries": [
        {
          "item_id": "cobblemon:poke_ball",
          "count": 3
        },
        {
          "item_id": "cobblemon:great_ball",
          "count": 2
        },
        {
          "item_id": "cobblemon:ultra_ball",
          "count": 1
        }
      ]
    }
  ]
}

`punish_rule`

Purpose:

Punishments after losing to the Boss team.

Fields:

punish_items
level
evs
ivs
command
chance

Chance note:

If chance is greater than 0, that custom chance is used.

If chance is missing or 0, the default penalty chance can be used.

`spawnpokemonbossteam`

Purpose:

Manually starts a Boss team battle for a player.

Command meaning:

/spawnpokemonbossteam <player> <bossTeamId>

Permission:

Requires administrator permission.

Notes:

bossTeamId can be written with or without namespace.
If no namespace is written, cobbleboss is used.
This command is mainly for testing and admin-controlled events.

Multiplayer Team Battle Behavior

How it works:

The system scans nearby valid players.
Nearby players must not already be in battle.
Spectators and removed players are ignored.
The current team battle system is designed around up to 2 players.
The current Boss team battle system uses up to 2 Boss Pokemon.
This creates a 2v2 raid-style battle when enough players and Bosses are available.
If multiplayer conditions are not met, it can fall back to a single-player team Boss battle.

Notes:

This feature is best explained after normal Boss configuration.
It is intended for servers that want raid-style gameplay.
Boss stats, rewards, shield, and actions_per_turn should be balanced carefully for team battles.