hClansPvPAddon is an addon for hClans that adds configurable PvP control inside clans.
The addon allows clans to control whether members can damage each other, provides a GUI for changing the PvP state, supports personal PvP rules between specific clan members and blocks friendly fire when clan PvP is disabled.
It also supports projectile and indirect damage checks, world restrictions, configurable messages, clan permission checks and persistent state storage through the hClans database system.
Main Features

• Clan-wide PvP toggle.
• Personal PvP state between specific clan members.
• Configurable /clan pvp subcommand.
• GUI for managing clan PvP.
• Member list inside the GUI.
• Page navigation for member entries.
• Configurable GUI layout, title, size and items.
• Custom materials, names, lore, actions and heads.
• Configurable enable and disable aliases.
• Optional clan permission check for toggling PvP.
• Owner bypass option.
• Friendly-fire blocking between clan members.
• Projectile damage support.
• Indirect source detection for pets, TNT and other supported sources.
• World blacklist or whitelist.
• Configurable attacker and victim notifications.
• Notification cooldown to prevent spam.
• Persistent PvP states stored through hClans database API.

How It Works
Players open the PvP menu with:
If the player is in a clan, the addon opens a configurable GUI. The menu shows the current clan PvP state and allows players with access to switch it.
The addon stores two types of PvP state:

• Clan state - global PvP state for the whole clan.
• Pair state - personal PvP state between two specific clan members.

When one clan member tries to damage another, hClansPvPAddon checks the clan state, checks the personal pair state and cancels the damage if PvP is disabled.
Clan PvP Toggle
The clan-wide toggle controls the default friendly-fire behavior for clan members.
Default config option:
If a clan has never changed its PvP setting, this value is used as the default state.
Personal Member Rules
The GUI can display clan members as player-head items.
A player can click a member item to toggle personal PvP state between themselves and that member.
This allows more precise control than only enabling or disabling PvP for the whole clan.
Available member placeholders include:
Damage Handling
The addon listens to damage events and checks whether the attacker and victim are in the same clan.
Supported damage handling includes:

• direct player damage
• projectile damage
• tamed entity ownership
• TNT source resolving
• area effect cloud source resolving
• Evoker Fangs owner resolving

If PvP is disabled for the clan or pair, the damage is cancelled.
World Restrictions
PvP control can be restricted by world.
Supported modes:

• blacklist - disable addon logic in listed worlds.
• whitelist - allow addon logic only in listed worlds.

Example:
Notifications
The addon can notify the attacker and optionally the victim when friendly fire is blocked.
Notification settings:
The cooldown prevents repeated messages from spamming players during combat.
GUI Configuration
The GUI is configured in:
You can configure:

• title
• size
• state text
• filler items
• enable button
• disable button
• member items
• empty member items
• previous and next page buttons
• back button
• materials
• slots and page slots
• priority
• CustomModelData
• display names
• lore
• actions

Default menu title:
GUI Placeholders
Placeholders available in GUI text and actions:
These placeholders can be used in item names, lore and configured actions.
Configuration
Main configuration file:
Default structure:
Actions
Configurable action sections:
These actions are used for command feedback, permission errors and blocked damage messages.
Commands
/clan pvp opens the PvP control GUI.
/clan pvp enable enables clan member damage.
/clan pvp disable disables clan member damage.
Enable and disable aliases are configurable in config.yml.
Permissions
hClansPvPAddon can use a clan permission from the hClans permission system.
Default configurable clan permission:
By default, clan permission checking is disabled and the clan owner is always allowed to toggle PvP.
Relevant settings:
Important: this is a clan permission used by hClans, not a standalone Bukkit command permission.
Requirements

• Java 17 or newer.
• Bukkit / Spigot / Paper compatible server.
• hClans plugin.

Important: hClansPvPAddon is an addon and requires hClans to work.
Installation

1. Install hClans.
2. Place hClansPvPAddon.jar into your server's plugins folder.
3. Start or restart the server.
4. Open the generated configuration files.
5. Configure config.yml and gui.yml if needed.
6. Restart the server or reload hClans/addons through your normal workflow.

Configuration files:
Notes

• The addon registers pvp as a clan subcommand.
• Clan PvP states are stored persistently.
• Personal pair states are stored separately from the clan-wide state.
• The GUI can be fully redesigned through gui.yml.
• World restrictions only affect the damage-control logic.
• Projectile handling can be disabled in the configuration.