CobbleBoss

CobbleBoss Boss User Guide

1. Data Pack Structure

CobbleBoss data packs use the `cobbleboss` namespace.

Normal Boss files are placed in:

```text data/cobbleboss/bosses/ ```

Paid multiplayer Boss team files are placed in:

```text data/cobbleboss/boss_teams/ ```

Main structure:

```text 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:

```json "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:

```json "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:

```json "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:

```json "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:

```text 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:

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

Example structure:

```text 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`:

```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:

```text 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:

```text /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:

```text 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:

```json "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:

```text /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.