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:

1. The mod's built-in assets/cobbleboss/sounds.json.
2. 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.