LuckPerms - GashiStudios

Use LuckPerms to decide exactly which CobbleRanked commands each group can run.

How Permission Checks Work

Server setup	Who can use admin commands
LuckPerms is not installed	OP level 2+
LuckPerms is installed	Players with the required node
LuckPerms is installed and `opBypassAdminPermissions: true`	Players with the node, plus OP level 2+ when the node is not explicitly denied
Server console	Always allowed

📝 Since v2.1.10, /rankedadmin checks the permission for the selected subcommand directly. It no longer requires an extra OP level before LuckPerms is consulted.

Admin Command Access

For an admin group that should have every CobbleRanked admin command:

/lp group admin permission set cobbleranked.admin.* true

For a staff group that should only reload configuration:

/lp group staff permission set cobbleranked.admin.config.reload true

The reload command should then be available immediately:

/rankedadmin reload

If it is still unavailable, follow Admin command is missing or says no permission.

Permission Nodes

Player Permissions

Permission	Description
`cobbleranked.player.use`	Use /ranked command
`cobbleranked.player.casual.use`	Use /casual command
`cobbleranked.player.queue.join`	Join queue
`cobbleranked.player.queue.leave`	Leave queue
`cobbleranked.player.stats.view`	View own stats
`cobbleranked.player.leaderboard.view`	View leaderboard

Format Permissions

Permission	Description
`cobbleranked.player.format.singles`	Queue for Singles
`cobbleranked.player.format.doubles`	Queue for Doubles
`cobbleranked.player.format.triples`	Queue for Triples

Admin Permissions

Permission	Description
`cobbleranked.admin.*`	All admin commands
`cobbleranked.admin.arena.create`	Create arenas
`cobbleranked.admin.arena.edit`	Edit, enable, disable, and reset arenas
`cobbleranked.admin.arena.list`	View arena status
`cobbleranked.admin.arena.teleport`	Teleport to arenas
`cobbleranked.admin.config.reload`	Reload configuration
`cobbleranked.admin.player.setelo`	Set player ELO
`cobbleranked.admin.player.manage`	Manage ranked bans, flee counts, and penalties
`cobbleranked.admin.queue.clear`	Clear all queues
`cobbleranked.admin.season.view`	View current season info
`cobbleranked.admin.season.manage`	Rotate, pause, or resume a season
`cobbleranked.admin.usage.manage`	View, export, or clear usage data
`cobbleranked.admin.leaderboard.export`	Export leaderboard data
`cobbleranked.admin.placeholder.manage`	Manage placeholders
`cobbleranked.admin.migration`	Run migration commands
`cobbleranked.admin.api.manage`	Run Web API sync commands
`cobbleranked.admin.forceend`	View or force-end active matches

Bypass Permissions

Permission	Description
`cobbleranked.player.bypass.cooldown`	Bypass queue cooldown
`cobbleranked.player.bypass.queuelimit`	Bypass queue limit

LuckPerms Setup

Grant Player Permissions

/lp group default permission set cobbleranked.player.use true
/lp group default permission set cobbleranked.player.casual.use true

Grant Admin Permissions

/lp group admin permission set cobbleranked.admin.* true

Grant Specific Bypass

/lp group vip permission set cobbleranked.player.bypass.cooldown true

Rank Display Permissions

CobbleRanked automatically grants rank-based permissions and display features:

Permission	Description
`cobbleranked.rank.<tier>`	Current rank tier permission
`cobbleranked.rank.title.<tier>`	Persistent title permission (earned once, kept forever)

Example: When a player reaches Ultra Ball tier:

They get cobbleranked.rank.ULTRABALL permission (current rank)
They get cobbleranked.rank.title.ULTRABALL permission (permanent, kept even after tier loss)

Rank Display Settings

Configure in config/cobbleranked/integrations/luckperms.yaml:

# config/cobbleranked/integrations/luckperms.yaml
enabled: true
syncMode: SUFFIX          # PREFIX, SUFFIX, GROUP, or ALL
removeOnRankLoss: true   # Remove display when losing rank
opBypassAdminPermissions: true   # OPs (level 2+) can run admin commands without explicit nodes

tierMappings:
  POKEBALL:
    suffix: " &f[Poké Ball]&r"
    weight: 100
  GREATBALL:
    suffix: " &9[Great Ball]&r"
    weight: 101
  # ... other tiers

Setting	Description
`syncMode`	How rank display is applied (suffix, prefix, group)
`removeOnRankLoss`	Whether to remove display when player drops below tier
`permissionMode`	`ALLOW_BY_DEFAULT` lets players use normal player commands unless denied; `REQUIRE_PERMISSION` requires player nodes
`opBypassAdminPermissions`	When `true`, OP level 2+ may use admin commands without an explicit node. An explicit deny still wins.

Dynamic Contexts (Tier / ELO)

CobbleRanked can expose each player’s current tier and ELO as LuckPerms contexts. This lets you write permission rules that depend on a player’s rank — e.g. grant a permission only to Master Ball tier and above, or only above 1500 ELO. Works on both pure-Fabric and Arclight (LuckPerms is available as a Fabric mod too).

# config/cobbleranked/integrations/luckperms.yaml
context:
  enableServerContext: false    # apply per-server (cross-server)
  enableWorldContext: false     # apply per-world
  # Dynamic tier/elo contexts (Fabric and Arclight)
  enableTierContext: false      # expose the player's tier as a context
  enableEloContext: false       # expose the player's ELO as a context
  tierKey: "cobbleranked_tier"  # LuckPerms context key for the tier
  eloKey: "cobbleranked_elo"   # LuckPerms context key for the ELO

Example: permission rule for a tier

With enableTierContext: true, a player’s tier is exposed under the cobbleranked_tier context. In LuckPerms you can then create a context-based rule:

/lp group masterball permission set some.permission.true cobbleranked_tier=MASTERBALL

This grants some.permission only when the player’s CobbleRanked tier is MASTERBALL. Similarly, enableEloContext exposes the numeric ELO under cobbleranked_elo.

Ranked Bans

You can ban a player from ranked play through LuckPerms. The ban denies the cobbleranked.player.use permission, so the player can no longer open /ranked (Casual via /casual is still allowed).

/rankedadmin banranked <player>     # ban from ranked (requires LuckPerms)
/rankedadmin unbanranked <player>   # lift the ban (requires LuckPerms)

Cross-server sync: a ranked ban only carries across servers if LuckPerms uses shared storage (e.g. MySQL). If each server uses local storage (SQLite/H2/JSON), the ban applies per-server only. Make sure every linked server points at the same LuckPerms storage so the ban follows the player.

You can also set the denial node manually:

/lp user <player> permission set cobbleranked.player.use false

Without LuckPerms

If LuckPerms is not installed:

All players can use basic commands
Only OP Level 2+ can use admin commands
Bypass permissions are not available
Rank display features are disabled