Systems

Allies and rivals

Alliances are mutual and asked for; rivalries are one-sided and declared. What each one changes.

Both live in the same table, clan_relations, and both are stored directionally — one row means "clan A regards clan B this way". Alliances need both rows; rivalries need one.

Alliances

An alliance is a request and an answer.

/clan ally add <clan>        needs SEND_ALLIANCE_REQUEST
/clan ally accept <clan>     needs ACCEPT_ALLIANCE
/clan ally decline <clan>    needs ACCEPT_ALLIANCE
/clan ally remove <clan>     needs REMOVE_ALLY

The request is held in memory, not in the database, and expires after settings.invite-expire-seconds (60 s), at which point the requesting clan is told. A server restart drops pending requests.

Accepting writes both rows at once. Removing deletes both — an alliance cannot be one-sided, so leaving one ends it for the other clan too.

Refused when	Message
Either clan is at its alliance cap	`errors.max-allies` / `errors.target-max-allies`
The clans are already allied	`errors.already-allies`
A request is already pending	`errors.alliance-request-already-sent`
Accepting with nothing pending	`errors.alliance-request-not-found`

The cap is settings.max-alliances (5) plus the level bonus, so a level 10 clan can hold ten.

What an alliance changes

Friendly fire. Allies cannot hurt each other unless both clans have friendly fire on.
Colour. Allies are painted according to visibility-mode — see below.
Client team. Every clan reachable through alliances is put on one client-side team, so allies show as teammates on a modified client's map. Two allied clans make one team, not three.
Home waypoint. An ally's clan home appears as a waypoint for your members.
Ally chat. /clan chat cycles to a channel that reaches your clan and every ally, and @ sends a single line there.
Placeholders. clan_allies, clan_allies_total_members, clan_allies_total_online, clan_allies_total_max_members and the whole clan_online_ally_<n> roster.

Rivals

A rivalry is a declaration. There is nothing to accept.

/clan rival add <clan>       needs MANAGE_RIVALS
/clan rival remove <clan>    needs MANAGE_RIVALS

One row is written, from your clan to theirs. They are your rival whether they like it or not, and they do not automatically become rivals with you — if notify-target-on-declare is on they simply get told.

Refused when	Message
At the rival cap	`errors.max-rivals`
Already declared	`errors.already-rivals`
The target is an ally	`errors.cannot-rival-ally`

rivals:
  kill-exp-multiplier: 2.0
  kill-stat-multiplier: 1.0
  notify-target-on-declare: true

What a rivalry changes

Setting	Effect
`kill-exp-multiplier`	Kill EXP — base plus streak bonus — is multiplied by this when the victim was in a rival clan. `1.0` disables the lookup entirely.
`kill-stat-multiplier`	The clan's recorded kill count is multiplied by this for a rival kill. It is rounded half up, so `2.0` records two kills and `1.5` records two as well.
`notify-target-on-declare`	Whether the declared clan is told.

Rivals are also what /clan camp reads, and what makes a player show as an enemy to the relational placeholders.

`kill-stat-multiplier` inflates the leaderboard, not the player

It only touches clan_stats, which is what the kills leaderboard sorts on. The per-player row in player_stats still records one kill. Leaving it at 1.0 keeps the two in step.

How a player is coloured

settings:
  visibility-mode: DISABLED

Mode	Who is painted
`DISABLED`	Nobody. The shipped default. Names are exactly what TAB or your own plugin draws.
`CLAN_ONLY`	Clanmates and yourself, green. Allies look like strangers.
`ALLY_ONLY`	Allies and yourself, aqua. Clanmates look like strangers.
`CLAN_AND_ALLY_MIXED`	Clanmates and yourself green; allies aqua and glowing, so the two are told apart.
`UNIFIED`	Clanmates, allies and yourself, all in one colour.

An unknown value falls back to CLAN_AND_ALLY_MIXED.

The colour is per viewer, not a scoreboard team the whole server shares, so two players can see the same third player differently. Where TAB is installed its own team handling is paused for a player while this plugin is colouring them, and resumed when they leave a clan.

`DISABLED` ships as the default, and it turns more off than colour

Out of the box this plugin paints nothing at all: no nametags are touched, no scoreboard team is created, and TAB's team handling is never paused. A focus still makes the target glow, because glow rides on the entity itself — but it is not red, because red needs the scoreboard team that DISABLED never creates. Set one of the four other modes to get the colours back.

The whole feature is packet-level and needs PacketEvents. Without it, every mode behaves as DISABLED.

Friendly fire

settings:
  forced-ff-worlds: []

Pair	Damage lands when
Same clan	The clan has friendly fire on, or the world is in `forced-ff-worlds`
Mutual allies	Both clans have it on, or the world is forced
Anyone else	Always, unless a kick truce is running

The truce after a kick

kick-protection:
  enabled: true
  duration-seconds: 120

Kicking or banning a player arms a two-minute truce between them and the clan they just left. While it runs, no damage passes in either direction between that player and anybody still in the clan, or in a clan mutually allied with it. The attacker is told why, with the seconds remaining, at most once every three seconds.

It is armed from every route out: the kick and ban buttons in the members menu, /clan kick, /clan ban and /clanadmin forcekick.

The truce beats `forced-ff-worlds`

It is checked before the friendly-fire rules, so a kicked player cannot be finished off in an arena world either. Two minutes is the shipped value; enabled: false turns the whole thing off and a kicked player is fair game immediately.

/clan ff toggles it and needs TOGGLE_FRIENDLY_FIRE. Projectiles are resolved to whoever fired them, so an arrow follows the same rules as a sword. A player not in a clan is never protected by any of this.

forced-ff-worlds overrides every clan's setting — the arena world where everyone fights everyone regardless.

Admin

/clanadmin addally <clanA> <clanB>
/clanadmin removeally <clanA> <clanB>
/clanadmin addrival <clanA> <clanB>
/clanadmin removerival <clanA> <clanB>

These write the rows directly, with no request, no cap check and no permission check inside the clan.

Something missing on this page? Tell us on Discord