Описание
# 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
```
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.