Battle Configuration

Configure battle behavior in battle.yaml. Note that format-specific settings (team size, level cap, turn timer) are configured 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) and turnTimer (time per turn) are configured per-format in season_presets.

Battle Start Delays

Fine-grained delays during battle start, useful for high-latency or cross-server (Arclight) setups where clients need extra time to receive battle packets:

# battle.yaml
timers:
  startDelays:
    leadGuiCloseMs: 500              # wait for lead-selection GUI to close
    titleDisplayMs: 500              # hold the "battle start" title
    crossServerPacketSyncMs: 1000    # cross-server only: packet sync
    arclightInitMs: 500              # Arclight/Bukkit: wait for battle init
    battleMusicMs: 1000              # delay before battle music overrides Cobblemon's

Raise these if players see battle UI issues or get stuck at battle start; lower them for snappier starts on low-latency single-server setups.

Random Battle (Randbats)

Showdown-style Random Battle, where the server generates a balanced team for each player. See Random Battle for the full guide.

# battle.yaml
randomBattle:
  enabled: true
  teamSize: 6
  setsFile: "gen9randombattle.json"
  localSetsDir: "random_battle"     # local custom set files live under config/cobbleranked/<localSetsDir>/
  # statsMode: OPTIMIZED (252/252/4 + boosting nature) | OFFICIAL (flat EV85 + neutral, Showdown-accurate) | FLAT (IV31/EV0/neutral)
  statsMode: "OFFICIAL"
  maxPP: true                       # apply PP Max to every move (Showdown parity); false = Cobblemon default PP
  skipLeadSelection: false          # true = skip the lead-selection GUI and send out team[0] immediately
  weighting:
    enabled: true                   # team-composition constraints (Showdown parity)
    multipliers: {}                 # speciesId -> weight multiplier
    exclusions: []                  # speciesId list to exclude
    speciesDuplication:
      enabled: true
      maxSameBaseSpecies: 1
    typeDiversity:
      enabled: true
      maxPerType: 2
    resistanceDiversity:
      enabled: true
      maxWeaknesses: 3
      maxDoubleWeaknesses: 1
  autoUpdate:
    enabled: false                  # periodically fetch latest randbats data
    intervalHours: 24
    sourceUrl: "https://data.pkmn.cc/randbats"
    battleServerOnly: true          # cross-server: only battle server fetches
    backupDir: "randbats"           # downloaded data is backed up here

The legacy optimizeStats flag is still respected for backward compatibility: when statsMode is OPTIMIZED (the default), optimizeStats: false is treated as FLAT. Setting statsMode explicitly always takes precedence.

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)

Configure which gimmicks are allowed in ranked battles:

# season_presets/default.yml
singles:
  megaEvolution: true
  zMoves: true
  dynamax: false
  terastallize: false

Requirements:

⚠️ Important: Gimmick settings only work when Mega Showdown is installed. Cobblemon does not natively support these mechanics.

How Gimmick Restrictions Work:

When set to false:

• CobbleRanked removes key items from player data before battle
• Mega Showdown’s GimmickTurnCheck is prevented from re-adding them during battle
• Players cannot use the disabled gimmick during ranked matches

When set to true:

• Players with the required accessory items can use the gimmick
• Normal Mega Showdown behavior applies

Notes:

• Gimmick restrictions only apply during ranked battles
• Casual battles, wild battles, and PvP outside ranked are unaffected
• Players retain their accessory items; only key items are temporarily removed

Victory/Defeat Rewards

Commands executed after each match. All lists default to empty (disabled). Add commands to enable them.

# 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"
  casualVictoryCommands:
    - "cobblemon give {player} exp_candy_s 1"
  casualDefeatCommands: []

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

⚠️ Casual matches are high-frequency (no queue penalty, no rating at stake), so use lighter rewards than ranked.

# Impactor (Fabric)
rewards:
  victoryCommands:
    - "eco deposit 1000 {player}"

# Vault/Essentials (Arclight)
rewards:
  victoryCommands:
    - "eco give {player} 1000"

Flee & Forfeit Penalties

Penalize players who rage-quit, disconnect mid-battle, or forfeit, including alt-account ELO farming via repeated early forfeits. See Flee & Forfeit Penalties for the full feature overview.

# battle.yaml
competitive:
  fleePenalty:
    enabled: true
    tiers:
      - { minFlees: 1, maxFlees: 2, penaltyMinutes: 0 }       # 1st-2nd: warning
      - { minFlees: 3, maxFlees: 4, penaltyMinutes: 5 }       # 3rd-4th: 5 min
      - { minFlees: 5, maxFlees: 7, penaltyMinutes: 15 }      # 5th-7th: 15 min
      - { minFlees: 8, maxFlees: 999, penaltyMinutes: 60 }    # 8+: 1 hour

  earlyForfeit:
    enabled: true
    maxTurns: 6              # forfeits at turn < maxTurns are "early" (turn is 0-indexed)
    penaltyMultiplier: 1.5   # base fleePenalty minutes * this value

  forfeitBlock:
    enabled: false           # when true, forfeit is forbidden within the first maxTurns turns
    maxTurns: 3

  fleeDecay:
    enabled: true
    decayRate: 1
    decayIntervalHours: 24

  pendingMatchTimeoutMinutes: 5

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

Early-Forfeit Penalty

earlyForfeit applies a multiplier to the base penalty when a player forfeits within the first maxTurns turns (default: turns 0–5, ×1.5). Raise penaltyMultiplier if you need a harder stance against alt-account ELO farming (repeated turn-1 forfeits to feed rating).

Note: the base fleePenalty first tier is 0 min, so 0 × multiplier = 0 on the very first early forfeits. Raise the first tier above 0 if you want even the first early forfeit to hurt.

Forfeit Block

forfeitBlock (off by default) forbids forfeiting entirely within the first maxTurns turns. The forfeit is cancelled, the player is re-prompted to choose an action, and shown a message. Once maxTurns has passed, forfeiting works normally.

fleePenalty:
  tiers:
    - minFlees: 1
      maxFlees: 3
      penaltyMinutes: 5      # First 3 flees: 5 min
    - minFlees: 4
      maxFlees: 7
      penaltyMinutes: 15     # Next 4 flees: 15 min
    - minFlees: 8
      maxFlees: 999
      penaltyMinutes: 60     # 8+ flees: 1 hour

GUI Settings

# battle.yaml
gui:
  detailedTooltips: true            # show ability/nature/moves/IV/EV in Pokémon tooltips
  showOpponentDetails: false        # also show detailed tooltips for the opponent's Pokémon
  leaderboardPageSize: 25
  blacklistPageSize: 45
  statsRefreshCooldownMs: 5000

Cooldowns

# battle.yaml
cooldowns:
  matchCooldownSeconds: 10
  queueJoinCooldownSeconds: 3

Daily Elo Limits

The daily rating-gain cap lives in elo.yaml as dailyEloGainLimit. Losses are never capped. The reset time of day follows config.yaml -> timezone.

See ELO Configuration for details.

See Also

• Turn Timer Feature - Timer system details
• Announcements - Match broadcasts
• ELO Configuration - Rating system and daily limits