Main Configuration - GashiStudios

Core server configuration for CobbleRanked. Advanced settings are organized in separate pages.

Configuration Files

CobbleRanked uses multiple YAML files in config/cobbleranked/:

File	Purpose
`config.yaml`	Core settings: language, database, cross-server, debug
`elo.yaml`	Rating system and rank tiers → ELO Settings
`battle.yaml`	Timers, penalties, rewards → Battle Settings
`matchmaking.yaml`	Recent opponent avoidance → Matchmaking Settings
`season.yaml`	Season schedule and reset behavior → Season Settings
`sounds.yaml`	All sound effects → Sounds
`arenas.yaml`	Battle arena positions → Arenas
`restrictions.yaml`	Player action restrictions → Restrictions
`rewards.yaml`	Season rewards → Rewards
`missions.yaml`	Daily/weekly missions → Missions
`integrations/luckperms.yaml`	LuckPerms integration → LuckPerms
`api.yaml`	Web API settings → API
`season_presets/*.yml`	Format rules per season → Battle Formats

Season Presets

Format-specific settings (team size, level cap, matchmaking rules, blacklists) are configured in season presets instead of the main config files. This keeps all format settings in one place.

# season_presets/default.yml
singles:
  enabled: true
  teamSize: 3
  selectCount: 3
  levelCap: 100
  # ... all format settings here

Language Settings

# config.yaml
language: "en-us"

Value	Language
`en-us`	English (default)
`ja-jp`	Japanese

📝 You can add ANY language! Create a custom language file in config/cobbleranked/language/ (e.g., fr-Fr.json5, zh-CN.json5) and set the language code to match. See Languages Configuration for details.

Reload with /rankedadmin reload after changing.

Discord Webhook Notifications

Send notifications to a Discord channel via Webhook when players rank up, when matches end, or when a season ends. Works on both pure-Fabric and Arclight servers (plain HTTP POST, no Bukkit dependency).

# config.yaml
discord:
  enabled: false
  webhookUrl: ""                 # Discord → Channel Settings → Integrations → Webhooks → New Webhook
  username: "CobbleRanked"       # Bot display name
  events:
    rankUp: true                 # Notify when a player ranks up (tier change, up only)
    seasonEnd: true              # Notify when a season ends
    matchResultRanked: true      # Notify on ranked match results (win/loss/draw)
    matchResultCasual: false     # Notify on casual match results

Event	Trigger
`rankUp`	A player’s tier goes up (e.g. Poké Ball → Great Ball). Down-ranks are silent.
`seasonEnd`	The active season ends and rewards are distributed.
`matchResultRanked`	A ranked match ends (victory / defeat / draw). Includes ELO change.
`matchResultCasual`	A casual match ends. Off by default to avoid spam.

Create a webhook in Discord: Channel Settings → Integrations → Webhooks → New Webhook, then paste the URL into webhookUrl.

On cross-server setups, only the battle server sends match-result and season-end notifications (the event originates there), so you will not get duplicate posts.

Database Settings

Configure data storage in config.yaml.

Type	Use Case
`sqlite`	Single server (default, zero config)
`mysql`	Cross-server setups
`mongodb`	Cross-server with MongoDB

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"

📝 See Database Configuration for detailed setup and migration guides.

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

Setting	Default	Description
`allowQueueOnBattleServer`	`false`	Allow players on battle server to join queue

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.

See Cross-Server Setup for detailed guide.

Timezone & Caching

# config.yaml
timezone: "Asia/Tokyo"          # Global timezone (IANA). Used for daily limits, missions, seasons.

leaderboard:
  cacheTtlMinutes: 15            # How long leaderboard results are cached
  profileCacheTtlMinutes: 1440   # Offline-player skull profile cache (24h)
  statsCacheTtlMinutes: 5        # Per-format player stats cache

Setting	Default	Description
`timezone`	server default	Global timezone for daily resets, missions, and seasons
`leaderboard.cacheTtlMinutes`	`15`	Leaderboard cache duration
`leaderboard.profileCacheTtlMinutes`	`1440`	Offline-player skull profile cache (avoids re-fetching skins)
`leaderboard.statsCacheTtlMinutes`	`5`	Per-format player stats cache

Background music is configured in sounds.yaml.

Debug Settings

Enable for troubleshooting:

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

Setting	Description
`enabled`	Master switch for debug mode
`logBattleEvents`	Log battle start, end, victor
`logMatchmaking`	Log queue joins, matches found
`logGuiInteractions`	Log button clicks, GUI opens
`logMusicEvents`	Log battle music triggers

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

Advanced Configuration Pages

Setting	Documentation
ELO Rating System	ELO Configuration
Matchmaking Rules	Matchmaking Configuration
Battle Timers & Penalties	Battle Configuration
Season Schedule	Season Configuration
Match Announcements	Announcements Configuration
Pokemon/Move Restrictions	Blacklist Configuration
Player Action Restrictions	Restrictions Configuration
Season End Rewards	Rewards Configuration
Daily/Weekly Missions	Missions Configuration
Battle Arenas	Arena Configuration
GUI Customization	GUI Configuration
Language Files	Languages Configuration
Sound Effects	Sounds Configuration
Web API	API Configuration
LuckPerms Integration	LuckPerms