Main Configuration

Fine-tune every aspect of your competitive battles. From ELO calculations to matchmaking rules, you control the experience.

Configuration Files

CobbleRanked v2.0.21+ uses multiple YAML files in config/cobbleranked/:

GUI Layouts

GUI appearance is configured separately in JSON5 files:

📝 Note: GUI layouts (slots, materials, borders) are in gui/*.json5 files, while GUI behavior (page sizes, cooldowns) is in battle.yaml under the gui: section.

Important: As of v2.0.13, format-specific settings (team size, level cap, matchmaking rules, blacklists) are configured in season_presets instead of battle.yaml or matchmaking.yaml. This keeps all format settings in one place.

ELO Rating System

The heart of competitive ranking. Configure how player ratings change after each battle.

Rating System Selection

# elo.yaml
ratingSystem: POKEMON_SHOWDOWN  # or GLICKO2
startingElo: 1000
floorElo: 0

Pokemon Showdown Mode (Default)

Uses the classic Elo formula with K-Factor adjustments. This is the same system used by Pokemon Showdown and chess.

# elo.yaml
pokemonShowdown:
  newPlayerGames: 10
  newPlayerKFactor: 35
  kFactorBands:
    - maxElo: 1100
      kFactor: 30
    - maxElo: 1300
      kFactor: 25
    - maxElo: 1600
      kFactor: 20
    - maxElo: 2000
      kFactor: 16
    - maxElo: 999999
      kFactor: 12
  streakBonus:
    enabled: true
    threshold3Wins: 3
    threshold5Wins: 5

streakBonus:
  enabled: true
  threshold3Wins: 3   # +3 K-Factor after 3 wins
  threshold5Wins: 5   # +5 K-Factor after 5+ wins

kFactorBands:
  - maxElo: 1100    # Players below 1100 use K=30
    kFactor: 30
  - maxElo: 1300    # Players 1100-1299 use K=25
    kFactor: 25
  - maxElo: 1600    # Players 1300-1599 use K=20
    kFactor: 20
  - maxElo: 2000    # Players 1600-1999 use K=16
    kFactor: 16
  - maxElo: 999999  # Players 2000+ use K=12
    kFactor: 12

Glicko-2 Mode (Advanced)

More sophisticated system that tracks rating uncertainty. Better for infrequent players.

# elo.yaml
ratingSystem: GLICKO2

glicko2:
  startingRD: 150.0
  startingVolatility: 0.06
  systemConstant: 0.5
  rdDecayDays: 30
  maxRatingChange: 100

Rank Tiers

Cosmetic ranks displayed in GUI and leaderboard:

# elo.yaml
rankTiers:
  - name: "POKEBALL"
    displayName: "Poké Ball"
    minElo: 0
  - name: "GREATBALL"
    displayName: "Great Ball"
    minElo: 1300
  - name: "ULTRABALL"
    displayName: "Ultra Ball"
    minElo: 1500
  - name: "MASTERBALL"
    displayName: "Master Ball"
    minElo: 1700
  - name: "BEASTBALL"
    displayName: "Beast Ball"
    minElo: 1900
  - name: "CHERISH"
    displayName: "Cherish Ball"
    minElo: 2100

📝 These are display only - they don’t affect matchmaking or rewards. Use LuckPerms Integration for rank-based permissions.

Matchmaking Settings

Matchmaking is split into two locations:

• Global settings (matchmaking.yaml) - Recent opponent avoidance
• Per-format settings (season_presets/*.yml) - ELO range rules per format

Recent Opponent Avoidance (Global)

Prevent the same players from battling repeatedly. This applies to all formats:

# matchmaking.yaml
recentOpponentAvoidance:
  enabled: true
  avoidCount: 3
  expirationSeconds: 300
  relaxAfterSeconds: 120
  minimumQueueSize: 4

Per-Format Matchmaking (Season Presets)

ELO range settings are configured per-format in season presets:

# season_presets/default.yml
singles:
  matchmaking:
    enforceEloRange: true
    initialRange: 200
    expansionDelay: 30
    expansionRate: 50
    maxMultiplier: 3.0
    immediateMatchRange: 100

Battle Settings

Configure battle behavior in battle.yaml. Note that format-specific settings (team size, level cap, turn timer) are now in season_presets.

Timers (Global)

# battle.yaml
timers:
  teamSelectionSeconds: 60
  leadSelectionSeconds: 30
  matchReadySeconds: 17
  countdownSeconds: 5
  battleTimeWarningSeconds:
    - 300
    - 60
    - 30

Note: matchDuration (total match time) is now configured per-format in season_presets.

Format Settings (Season Presets)

Format-specific settings are configured in season presets:

# season_presets/default.yml
singles:
  enabled: true
  teamSize: 3
  selectCount: 3
  levelCap: 100
  turnTimer: 90           # seconds per turn
  matchDuration: 15       # minutes total
  megaEvolution: true
  zMoves: true
  dynamax: false
  terastallize: false

Battle Gimmicks (Mega Evolution, Z-Moves, Dynamax, Terastallize)

⚠️ Important: The gimmick settings (megaEvolution, zMoves, dynamax, terastallize) are placeholder settings only. Cobblemon does not natively support these battle mechanics. They require the Mega Showdown mod to function.

Current Status

• CobbleRanked does not enforce these settings
• Gimmick availability is entirely controlled by Mega Showdown
• These settings are preserved for future Cobblemon API support

Workaround: Banning Gimmick Items

If you want to prevent certain gimmicks in ranked battles, ban the items required to use them via the blacklist:

# season_presets/default.yml
singles:
  blacklist:
    items:
      # Ban Mega Stones (prevents Mega Evolution)
      - "megashowdown:mega_stone_charizard_x"
      - "megashowdown:mega_stone_charizard_y"
      # ... add all mega stones you want to ban

      # Ban Tera Orb (prevents Terastallization)
      - "megashowdown:tera_orb"

      # Ban Dynamax Band (prevents Dynamax)
      - "megashowdown:dynamax_band"

      # Ban Z-Crystals (prevents Z-Moves)
      - "megashowdown:z_crystal_normal"
      # ... add all z-crystals you want to ban

    # Or ban items in player inventory/accessories
    inventoryItems:
      - "megashowdown:omni_ring"  # Bans the all-gimmick item

📝 Check Mega Showdown’s item IDs for the exact names. Use /megashowdown items or check JEI/REI for item IDs.

Victory/Defeat Rewards

Commands executed after each ranked match:

# battle.yaml
rewards:
  victoryCommands:
    - "cobblemon give {player} exp_candy_m 1"
    - "cobblemon give {player} rare_candy 1"
  defeatCommands:
    - "cobblemon give {player} exp_candy_s 1"

📝 Placeholders: {player} = player name, {uuid} = player UUID

Flee Penalties

Punish players who disconnect during battles:

# battle.yaml
competitive:
  fleePenalty:
    enabled: true
    tiers:
      - minFlees: 1
        maxFlees: 5
        penaltyMinutes: 5
      - minFlees: 6
        maxFlees: 10
        penaltyMinutes: 15
      - minFlees: 11
        maxFlees: 999
        penaltyMinutes: 30

  fleeDecay:
    enabled: true
    decayRate: 1
    decayIntervalHours: 24

  pendingMatchTimeoutMinutes: 5

Flee count decreases by 1 every 24 hours (configurable).

Season Settings

Configure season behavior in season.yaml.

# season.yaml
checkIntervalMinutes: 1
timezone: "Asia/Tokyo"

schedule:
  - name: "Season 1"
    startDate: "2025-01-01"
    endDate: "2025-03-31 23:59:59"
    preset: "default"

onSeasonEnd:
  resetElo: false
  softResetElo: true
  softResetFactor: 0.5
  resetWinLoss: true
  resetStreak: true

archive:
  enabled: true
  keepAllPlayers: false
  topPlayersCount: 100
  includeStatistics: true

Database Settings

Configure data storage in config.yaml.

SQLite (Default)

# config.yaml
database:
  type: "sqlite"
  sqlite:
    path: "config/cobbleranked/data.db"

MySQL

# config.yaml
database:
  type: "mysql"
  mysql:
    host: "localhost"
    port: 3306
    database: "cobbleranked"
    username: "root"
    password: ""
    pool:
      maxSize: 10
      minIdle: 2

MongoDB

# config.yaml
database:
  type: "mongodb"
  mongodb:
    connectionString: "mongodb://localhost:27017"
    database: "cobbleranked"

Restriction Settings

Prevent actions during queue/battle in restrictions.yaml.

Two phases:

• queue: While waiting for match (prevents item manipulation)
• arena: From teleport until battle ends (full lockdown)

# restrictions.yaml
queue:
  blockItemPickup: true
  blockEquipmentChange: true
  blockContainerAccess: true
  blockEntityInteract: true
  blockTeleport: true
  blockPortalUse: true
  blockPcAccess: true
  blockMoveSwap: true
  blockedCommands:
    - "tp"
    - "spawn"
    - "home"

arena:
  blockItemUse: true
  blockItemDrop: true
  blockItemPickup: true
  blockBlockBreak: true
  blockBlockInteract: true
  blockContainerAccess: true
  blockWorkstationAccess: true
  blockEntityInteract: true
  blockPvp: true
  # ... see full list below

📝 v2.0.17+: Queue phase now blocks item pickup, container access, and entity interactions to prevent obtaining banned items after joining queue.

Cross-Server Settings

For multi-server setups with shared rankings:

# config.yaml
crossServer:
  enabled: false
  serverId: "server1"
  battleServer: ""

  # Allow players on battle server to join queue directly (NOT RECOMMENDED)
  # Default: false - battle servers should only handle matched battles
  allowQueueOnBattleServer: false

  redis:
    host: "localhost"
    port: 6379
    password: ""
    database: 0
    useSsl: false

  timing:
    matchFoundDelaySeconds: 5
    battleStartDelaySeconds: 10
    playerArrivalTimeoutSeconds: 30

Battle Server Queue Behavior

When disabled (default), players on the battle server cannot join the queue. This is recommended because the battle server is dedicated to handling matched battles from lobby servers.

⚠️ Warning: Enabling allowQueueOnBattleServer can cause unexpected behavior. Only enable if you understand the implications and have a specific use case.

See Cross-Server Setup for detailed guide.

Debug Settings

Enable for troubleshooting:

# config.yaml
debug:
  enabled: false
  logBattleEvents: false
  logMatchmaking: false
  logGuiInteractions: false
  logMusicEvents: false

⚠️ Debug mode generates verbose logs. Disable in production.

See Also

• Arenas - Battle arena setup
• Blacklist - Pokemon restrictions
• Rewards - Season rewards
• Cross-Server - Multi-server setup
• FAQ - Common questions and troubleshooting