Ladder Config
Ladder Configuration
Ladders (Battle Categories) define the competitive and casual matchmaking formats in Cobblemon BattleHUB. They control everything: team size, ban rules, level adjustments, and which battle mechanics (gimmicks) are allowed in the arena.
Each ladder is one .json file. Which ones are actually offered in the queue is decided by activeRankedLadders / activeCasualLadders in server_config.json — a ladder file that isn't listed there still loads but is never queueable.
Directory Path
The mod organizes ladders into two directories to keep defaults and custom creations separate:
- Root Directory (Default Ladders):
config/cobblemon_battlehub/ladders/ - Custom Directory (Player/Admin Creations):
config/cobblemon_battlehub/ladders/custom_ladders/
Auto-Generated Ladders
If the root folder is empty, the server generates a complete set of standard formats on first boot:
| Generated IDs | Type | Notes |
|---|---|---|
singles_50_casual, singles_100_casual, singles_ranked |
Singles | Casual at Lv. 50 and Lv. 100; ranked at Lv. 50 |
doubles_50_casual, doubles_100_casual, doubles_ranked |
Doubles | same pattern |
triples_50_casual, triples_100_casual, triples_ranked |
Triples | same pattern |
monotype_50_casual, monotype_100_casual |
Monotype (Singles) | Same Type Clause enforced by the monotype in the ID |
tourney_solo, tourney_duplas, tourney_trios, tourney_monotype |
Tournament | used by the tournament system, not the normal queue |
Every generated file is written with class defaults for the rules, and the ranked / tournament ones additionally get "banPresets": ["ou"] (monotype tournament gets ["monotype"]). So a freshly generated singles_ranked.json still has allowDynamax: true, allowRestrictedLegendary: true, maxSubLegendary: 6, etc. — if you want a strict ranked meta you must tighten those yourself.
How Ladders Reach the Players (Queue Screen)
The server sends the list of active ladders (the ones listed in activeRankedLadders / activeCasualLadders) to every player when they join, and again to everyone online every time you run /bh reload. The queue screen is built from that list:
- Ranked tab: only the formats (Singles / Doubles / Triples) that have an active ranked ladder are offered, and the Lv. 50 / Lv. 100 buttons are only enabled for levels where an active ranked ladder exists for the selected format. To offer ranked at Lv. 100, create a ladder with
"ranked": true, the rightbattleTypeIdand"adjustLevel": 100, then add itsidtoactiveRankedLaddersand run/bh reload. - If a format has several active ranked ladders, the one matching the selected level is used. If none matches exactly (for example
"adjustLevel": 0, which has no button), the first one listed for that format is used. - Casual tab: still offers the fixed formats Singles / Doubles / Triples / Monotype at Lv. 50 and Lv. 100, using the generated IDs from the table above (
<format>_<level>_casual). Keep those IDs inactiveCasualLadders— a casual format that isn't active is rejected by the server with an Invalid format message. - Removed or deactivated ladders can't be queued: the server only accepts a queue request for a ladder that is currently active, even if its file still exists in the folder.
Configuration Template
Below is a full JSON template for a Ladder, showing every field from the Ladder.java class. The values here are an illustrative strict ranked Singles example — not a copy of the auto-generated file. For reference, the class defaults (what you get if you omit a field) are: enforce*Clause: true, openTeamSheet: false, every allow*: true, every max*: 6, requiredTeamSize: 6, adjustLevel: 50.
{
"id": "singles_ranked",
"queueLabel": "Ranked Queue",
"displayName": "Ranked Singles Lv. 50",
"description": "Official Ranked Singles format.",
"ranked": true,
"battleTypeId": "singles",
"requiredTeamSize": 6,
"adjustLevel": 50,
"enforceSpeciesClause": true,
"enforceItemClause": true,
"openTeamSheet": false,
"banPresets": ["ou"],
"bannedSpeciesKeys": [],
"bannedItemKeys": [],
"bannedAbilityKeys": [],
"bannedMoveKeys": [],
"allowRestrictedLegendary": false,
"allowMythical": false,
"allowParadox": false,
"allowMega": true,
"allowZMove": true,
"allowDynamax": false,
"allowTera": true,
"maxSubLegendary": 1,
"maxRestricted": 1,
"maxMythical": 1,
"maxParadox": 1,
"maxCombinedSpecial": 1
}
Valid JSON
Every line except the last inside an object needs a trailing comma, and there is no comma after the closing }. Copy the block above exactly — a missing comma (a common mistake right after allowTera) makes the whole file fail to load and the ladder falls back to defaults.
Detailed Parameter Explanation
1. Identification and Display (Matchmaking UI)
id: The category's unique internal ID (must match the filename exactly without the .json extension).queueLabel: The queue name shown in network packets and interfaces (e.g. Ranked Queue, Quick Queue, Tournament).displayName: Friendly title displayed to players inside the mod menus.description: Brief description explaining the queue rules or purpose in the interface.ranked(true/false): Determines whether the category awards ranking points (Elo/Glicko-2) and updates the global leaderboard.
2. Combat Structural Rules
battleTypeId: The battle field format. Supported values:"singles"(1v1)"doubles"(2v2)"triples"(3v3)requiredTeamSize: Number of Pokémon the player must bring to enter the queue / accept a duel (Default: 6). Set it lower (e.g.3) for a bring-3-pick-3 style format.adjustLevel: Level all team Pokémon are temporarily set to for the battle (Default: 50). Use0to disable adjustment and fight at each Pokémon's real level.
3. Competitive Clauses
enforceSpeciesClause(true/false): Prevents the player from using two or more Pokémon of the same species on the same team.enforceItemClause(true/false): Prevents two or more Pokémon from holding the same equipped item.openTeamSheet(true/false, Default:false): What a player can see about the opponent's team on the pre-battle screen.false(standard formats — singles, ranked, casual…): hovering an opponent's Pokémon shows only its species, level and types; ability, held item, nature and moves stay hidden.true(Open Team Sheet, VGC-style): the tooltip also reveals the opponent's ability, held item, nature and moves. Your own team is always shown in full. Ladder files created before this field existed behave asfalse. This setting only affects the pre-battle screen: the Battle History screen always shows just the species and level of the opponent's team (never their items, abilities, natures or moves), in every format — so nobody can scout a tournament opponent's exact sets from past matches. Your own team is always shown in full there.
4. Meta Filters (Legendary, Mythical, and Paradox Pokémon)
BattleHUB reads Cobblemon's own labels for each species, so these filters stay accurate as Cobblemon adds new Pokémon — you never maintain a manual list.
Allow toggles — an allow* : false bans that whole category outright:
allowRestrictedLegendary(true/false): Restricted legendaries — the box-art / cover legendaries (Mewtwo, Rayquaza, Koraidon…) that official VGC restricts.allowMythical(true/false): Mythical Pokémon (Mew, Celebi, Jirachi, …).allowParadox(true/false): Paradox Pokémon (Great Tusk, Iron Valiant, …).
Max counts — used when the matching allow* is true, to cap how many of that category a team may bring (class default 6 = effectively unlimited):
maxSubLegendary: Max Pokémon carrying Cobblemon'slegendary/sub-legendarylabel that are not on the restricted list (Articuno, Zapdos, Regirock, the genies…). There is noallowSubLegendarytoggle; set this to0to ban them entirely.maxRestricted: Max restricted legendaries (only relevant ifallowRestrictedLegendaryistrue).maxMythical: Max mythical Pokémon.maxParadox: Max paradox Pokémon.maxCombinedSpecial: Max combined total across all of the special categories above — e.g.1means the team may bring one legendary or one mythical or one paradox, not one of each.
5. Arena Mechanics (Gimmicks)
allowMega(true/false): Allows or bans Mega Evolution in battle.allowZMove(true/false): Allows or bans the use of Z-Moves.allowDynamax(true/false): Allows or bans Dynamax and Gigantamax mechanics.allowTera(true/false): Allows or bans Terastal (Paldea phenomenon).
6. Ban Lists & Custom Rules (Showdown)
banPresets: A list containing the IDs of ban preset JSON files you want to inherit (e.g. ["ou"], ["lc"], ["legendaries"]).bannedSpeciesKeys: Manual list to ban specific Pokémon by ID (e.g. ["charizard", "mewtwo"]).bannedItemKeys: Manual list to ban specific items.bannedAbilityKeys: Manual list to ban specific abilities.bannedMoveKeys: Manual list to ban specific moves.
Dynamic Suffix Logic (Custom Duels)
The Ladder.java class includes an intelligent Dynamic Suffix system for when two players challenge each other to a direct duel and decide to disable certain mechanics on the fly (using the mod's invite UI).
If players choose to disable gimmicks in the menu, the mod generates an in-memory modified copy of the Ladder by adding the following invisible suffixes to the ID:
_nomega(Disables Mega Evolution)_noz(Disables Z-Moves)_nodyna(Disables Dynamax)_notera(Disables Terastal)
Example: If your base Ladder is singles_ranked and the player disables Tera on the invite screen, the mod temporarily creates a copy under the ID singles_ranked_notera with the option "allowTera": false applied automatically, ensuring the battle proceeds fairly and without rule desynchronization.