Wiki Release: 2026.09.5 · UltimateClans: 9.1.4 · Documentation branch: 9 · ClanLeague

ClanLeague#

ClanLeague adds seasonal clan league progression with leagues, seasons, scheduled state changes, points, GUI, persistence and placeholders. The pages in this section explain what players see in-game, what administrators need to configure, the normal setup flow, and the most common problems you may need to diagnose.

Compatibility#

Component version: 2.0.2
Documentation release: 2026.09.5
Minimum UltimateClans version: 9.0.0

What you can do with it#

Define league tiers/requirements and season behavior before players begin earning points
Start or load a season, then add/earn points through the supported event/command integrations
Open the league GUI and verify clan placement/progression
Test season rollover/reset behavior on a copy of production data before using it live

How it works#

Seasons, points and ranking#

ClanLeague adds a persistent competitive layer on top of clan actions. Clans accumulate league points, are compared/ranked, and can participate in a season lifecycle managed by the season/scheduler code. Other addons can award league points through the integration API (FarmCoins can also define LEAGUEPOINT rewards).

Administrators should define the season/ranking rules first, test point additions/removals and GUI ordering, then enable automatic season scheduling. A season rollover is a state transition: verify rewards/reset policy on a staging clan before using it on production data.

First setup#

Before enabling the feature for players, review these installed files:

chat.yml
commands.yml
config.yml
gui.yml
language/Lang_EN.yml
polymart.yml

Recommended in-game workflow#

Define league tiers/requirements and season behavior before players begin earning points.
Start or load a season, then add/earn points through the supported event/command integrations.
Open the league GUI and verify clan placement/progression.
Test season rollover/reset behavior on a copy of production data before using it live.

Useful command entry points#

/clanleague help
/clanleague reload
/clanleague addevent
/clanleague adddiscount
/clanleague season create
/clanleague season delete
/clanleague season list (-old)
/clanleague season forcestart
/clanleague season forcestop
/clanleague season seticon
/clanleague season desc
/clanleague item add
/clanleague item remove
/clanleague item list
/clanleague command add
/clanleague command remove
/clanleague command list
/{_clan} {_league}

See Commands in the sidebar for the full command reference and configured aliases/permissions.

GUI areas#

The installed GUI configuration contains screens/sections such as:

League.home_league
League.home_allparticipants
League.home_previous_league
League.home_clan_events
League.home_season_rewards
League.home_season_unclaimed_rewards
League.home_player_claim_rewards

What administrators should configure#

Keep league IDs and season storage stable; renaming identifiers can orphan historical data.
Check timezone/date settings used by scheduler/season logic.
If another addon contributes league points, test that integration separately.

Configuration map#

config.yml — Config (date_format, timezone, League, Season, Icon, Permissions, logger); Storage (type, mysql, user, pass, databases)
chat.yml — Chat (commandunknownplayer, commandunknownadmin, leaguepointreceived, leagueclanwinner, leaguefinishwinner, leaguefinish_nowinner, leaguestarted)

The Configuration page lists the available paths and defaults from the installed configuration, with notes on what each area controls.

Before going live#

Back up the component data/configuration.
Start the server and confirm the component is detected without startup errors.
Test with a non-OP player and the lowest clan role that should have access.
Exercise the complete flow once, including the failure/deny path, not only the happy path.
Restart the server and verify that persistent state survives.
If the network is multiserver, repeat the test from a second node and verify storage/synchronization.

Troubleshooting quick reference#

Symptom	Likely cause	What to check
Clan points change but league does not update	League threshold/progression update has not run or configuration is invalid	Check tier thresholds and trigger/update logic; reload then test one controlled point change.
Season scheduler runs at wrong time	Timezone/date configuration differs from server expectation	Verify configured timezone and server clock.
GUI shows old season	Storage/cache still points to previous season	Check active season record and reload/reopen GUI.
Season reset removes unexpected data	Reset/clear action was broader than intended	Restore backup and test rollover with a staging database before retrying.

For a longer diagnostic flow, open the Troubleshooting page for this component.