Events - ClansPlus

Clan war events are scheduled competitive events where clans battle for supremacy, earning points through combat and claiming rewards.

War Event System

The war event system (WarEvent.java) provides automated, scheduled PvP competitions where clans compete for the top positions on leaderboards.

Event Overview

War events are time-limited competitions where clan members:

Fight other clans for points
Kill mobs for additional score
Compete for top rankings
Earn rewards based on performance

Event Configuration

War events have extensive configuration options:

Basic Settings

events:
  clan-war-event:
    enabled: true
    minimum-player-online: 10      # Minimum players to start event
    event-time: 3600               # Duration in seconds (1 hour)
    event-time-frame:              # When events can start
      - "14:00:00"
      - "20:00:00"

World Requirements

world-requirement:
  enabled: true
  worlds:
    - "world"
    - "world_nether"

When world requirements are enabled, score is only earned in the specified worlds. This prevents abuse in safe zones.

Boss Bar Display

event-boss-bar-settings:
  enabled: true
  title: "&c&lClan War Event &7- &f%timeLeft%"
  color: RED      # Boss bar color
  style: SOLID    # Boss bar style

The boss bar shows:

Time remaining in the event
Visual progress bar
Custom title with placeholders

Scoring System

Clans earn points through different actions during the event:

Player Kills

int SCORE_PLAYER;  // Points for killing enemy clan members

score-settings:
  player: 100  # Points per player kill

Rules:

Only kills against other clans count
Cannot kill your own clan members for points
Allied clans are protected from each other

if (killerClanData.getName().equals(victimClanData.getName())) return;

if (!killerClanData.getAllies().isEmpty())
    if (killerClanData.getAllies().contains(victimClanData.getName())) return;

Mob Kills

Vanilla Mobs

HashMap<String, Integer> SCORE_VANILLA_MOBS;

score-settings:
  vanilla-mobs:
    ZOMBIE: 5
    SKELETON: 5
    CREEPER: 10
    ENDERMAN: 15
    WITHER_SKELETON: 20

MythicMobs Integration

HashMap<String, Integer> SCORE_MYTHICMOBS_MOBS;

score-settings:
  mythicmobs-mobs:
    CustomBoss: 100
    EliteMob: 50
    RareMob: 25

MythicMobs support is automatic if the plugin is installed. Configure scores for your custom mob types.

Event Lifecycle

Starting the Event

Time Check

Event starts at configured time frames (e.g., 14:00, 20:00)

Player Count

Verifies minimum online player requirement is met

Notifications

Sends messages to all online players
Creates boss bars for participants
Plays starting sound effect
Sends Discord notification (if configured)

Timer Starts

Event countdown begins, updating boss bars every second

public void runEvent(boolean checkPlayerSize) {
    if (STARTING || !ENABLED) return;
    
    if (checkPlayerSize) {
        if (Bukkit.getOnlinePlayers().size() < MINIMUM_PLAYER_ONLINE) {
            // Send "not enough players" message
            return;
        }
    }
    
    TIMELEFT = EVENT_TIME;
    MAXTIMELEFT = TIMELEFT;
    STARTING = true;
    
    // Send messages, create boss bars, start timer
}

During the Event

The event tracks multiple statistics:

private HashMap<String, Long> playerDamagesCaused;      // Player -> Total damage dealt
private HashMap<String, Long> playerDamagesCollected;   // Player -> Total damage taken
private HashMap<String, Long> clanScoreCollected;       // Clan -> Points earned

Damage Tracking:

getPlayerDamagesCaused().put(damager.getName(), 
    getPlayerDamagesCaused(damager.getName()) + (long) event.getDamage());
    
getPlayerDamagesCollected().put(entityVictim.getName(), 
    getPlayerDamagesCollected(entityVictim.getName()) + (long) event.getDamage());

Ending the Event

Timer Expires

Event time reaches zero or admin manually ends it

Calculate Rankings

Sort all tracked statistics:

Top scoring clans
Most damage dealt (players)
Most damage taken (players)

Distribute Rewards

Award war points and execute reward commands

Announcements

Send ending messages with rankings
Play ending sound effect
Remove boss bars
Send Discord notification

Cleanup

Clear all event data and prepare for next event

Leaderboards

The event tracks three separate leaderboards:

Top Scoring Clans

List<String> topClanScoreCollected = HashMapUtil.sortFromGreatestToLowestL(getClanScoreCollected());

Ranks clans by total points earned during the event.

Most Damage Caused

List<String> topPlayerDamagesCaused = HashMapUtil.sortFromGreatestToLowestL(getPlayerDamagesCaused());

Tracks individual players who dealt the most damage.

Most Damage Taken (Tank)

List<String> topPlayerDamagesCollected = HashMapUtil.sortFromGreatestToLowestL(getPlayerDamagesCollected());

Recognizes players who absorbed the most damage.

Rewards System

War Points

Clans and players earn war points based on their ranking:

ending-rewards:
  enabled: true
  top-score-clans:
    1:  # First place
      warpoint: 1000
      commands:
        - "broadcast &6Clan %clan% won the war event!"
    2:  # Second place
      warpoint: 500
      commands: []
    3:  # Third place
      warpoint: 250
      commands: []

long warPointRewarded = eventConfigFile.getLong(configPath + "." + top + ".warpoint");
PluginDataManager.getClanDatabase(clanName).setWarPoint(
    PluginDataManager.getClanDatabase(clanName).getWarPoint() + warPointRewarded
);

Reward Commands

Execute custom commands for winners:

top-score-clans:
  1:
    commands:
      - "give %player% diamond 64"
      - "broadcast %clan% is the champion!"
      - "eco give %player% 10000"
      
most-damage-caused-players:
  1:
    warpoint: 500
    commands:
      - "give %player% netherite_sword 1"

Commands execute from the console. Be careful with permissions and ensure commands are properly escaped.

Skill Integration

Clan skills significantly impact war events:

Boost Score Skill

Adds bonus points to every kill:

SkillData boostScoreSkillData = SkillManager.getSkillData().get(
    SkillManager.getSkillID(PluginSkill.BOOST_SCORE)
);

if (boostScoreSkillData != null) {
    boostScoreSkillData.onDie(boostScoreSkillData, killer.getName(), victimName, false);
    int clanBoostScoreSkillLevel = killerClanData.getSkillLevel().get(boostScoreSkillData.getId());
    if (clanBoostScoreSkillLevel > 0)
        checkBoostScore = MESSAGES_CLAN_BROADCAST_PLACEHOLDER_CHECKBOOSTSCORE
            .replace("%bonusScore%", String.valueOf(BoostScoreSkill.boostScoreLevel.get(clanBoostScoreSkillLevel)));
}

Combat Skills

All combat skills (Critical Hit, Life Steal, Dodge) are active during events:

for (int skillID : damagerClanData.getSkillLevel().keySet()) {
    SkillData skillData = SkillManager.getSkillData().get(skillID);
    if (skillData != null) {
        if (SkillManager.getSkillID(PluginSkill.DODGE) != skillData.getId())
            skillData.onDamage(skillData, event);
    }
}

Event Messages

Broadcast Messages

Clans receive notifications when members score:

messages:
  clan-broadcast:
    prefix: "&7[&cClan War&7] "
    gain-score-player: "&a%player% &7killed &c%target% &7(+%score% points%checkBoostScore%)"
    gain-score-mob: "&a%player% &7killed &e%target% &7(+%score% points%checkBoostScore%)"

alertClan(killerClanData.getName(), 
    MESSAGES_CLAN_BROADCAST_GAIN_SCORE_PLAYER
        .replace("%player%", killer.getName())
        .replace("%target%", entityVictim.getName())
        .replace("%score%", String.valueOf(SCORE_PLAYER))
        .replace("%checkBoostScore%", checkBoostScore)
);

Status Messages

Players can check event status:

public void sendEventStatusMessage(Player player, boolean playSound) {
    if (!isStarting()) {
        // Show next event time and requirements
    } else {
        // Show time remaining and active worlds
    }
}

Combat Cooldown

Prevent players from using certain commands during combat:

combat-command-cooldown:
  enabled: true
  seconds: 10  # Cooldown duration

This prevents exploits like teleporting away during PvP.

Discord Integration

Send event notifications to Discord:

if (ClansPlus.support.getDiscordSupport() != null)
    ClansPlus.support.getDiscordSupport().sendMessage(
        ClansPlus.support.getDiscordSupport().getWarEventStartingMessage(
            ClansPlus.plugin.getDataFolder() + "/discordsrv-warevent-starting.json", 
            EventManager.getWarEvent()
        )
    );

Configure Discord webhooks and message formats in separate configuration files.

Event Statistics

Access total statistics:

public long getTotalDamageCaused() {
    long totalDamageCaused = 0;
    for (String player : playerDamagesCaused.keySet()) {
        totalDamageCaused += playerDamagesCaused.get(player);
    }
    return totalDamageCaused;
}

public long getTotalScoreCollected() {
    long totalScoreCollected = 0;
    for (String clan : clanScoreCollected.keySet()) {
        totalScoreCollected += clanScoreCollected.get(clan);
    }
    return totalScoreCollected;
}

Use these in ending messages:

event-ending:
  messages: |
    &7Total Damage: &c%totalDamagesCaused%
    &7Total Score: &e%totalScoreCollected%

Admin Commands

Administrators can control events:

Start Event: Manually trigger an event
End Event: Stop the current event
Set Time: Adjust remaining time
Toggle: Enable/disable events

Best Practices

Scheduling

Schedule events at peak player times
Avoid conflicting with other server events
Test time zones for international servers
Announce schedule to players

Balance

Test scoring values thoroughly
Balance player vs mob kill rewards
Adjust for server size
Consider skill impacts

Rewards

Make rewards worthwhile but not overpowered
Reward top 3-5 positions
Include participation rewards
Vary rewards to keep interest

Communication

Clear event rules and requirements
Notify players before events start
Show countdown timers
Explain scoring system

Next Steps

Skills

Optimize your clan’s skills for events

Configuration

Configure event settings

Clans

Build a strong clan foundation

Commands

Admin event commands

Get Started

Core Concepts

Configuration

Commands

Features

​War Event System

Event Overview

​Event Configuration

​Basic Settings

​World Requirements

​Boss Bar Display

​Scoring System

​Player Kills

​Mob Kills

​Vanilla Mobs

​MythicMobs Integration

​Event Lifecycle

​Starting the Event

​During the Event

​Ending the Event

​Leaderboards

​Top Scoring Clans

​Most Damage Caused

​Most Damage Taken (Tank)

​Rewards System

​War Points

​Reward Commands

​Skill Integration

​Boost Score Skill

​Combat Skills

​Event Messages

​Broadcast Messages

​Status Messages

​Combat Cooldown

​Discord Integration

​Event Statistics

​Admin Commands

​Best Practices

Scheduling

Balance

Rewards

Communication

​Next Steps

Skills

Configuration

Clans

Commands

Build docs developers (and LLMs) love

War Event System

Event Configuration

Basic Settings

World Requirements

Boss Bar Display

Scoring System

Player Kills

Mob Kills

Vanilla Mobs

MythicMobs Integration

Event Lifecycle

Starting the Event

During the Event

Ending the Event

Leaderboards

Top Scoring Clans

Most Damage Caused

Most Damage Taken (Tank)

Rewards System

War Points

Reward Commands

Skill Integration

Boost Score Skill

Combat Skills

Event Messages

Broadcast Messages

Status Messages

Combat Cooldown

Discord Integration

Event Statistics

Admin Commands

Best Practices

Next Steps