⚔️ Hyfaction - Complete Faction System for Hytale

A comprehensive faction management mod for Hytale servers featuring territory claims, alliances, strategic PvP, overclaiming, and extensive customization. Perfect for competitive servers seeking organized faction warfare.

Version: 1.0.552 - KOTH W.I.P - LEADERBOARD NOW - UI FIX

🌟 Overview

Hyfaction transforms your Hytale server into a dynamic faction-based environment where players create factions, claim territories, forge alliances, and engage in strategic PvP combat. With an intuitive GUI system, ECS integration, overclaiming mechanics, and extensive customization, Hyfaction provides everything needed for competitive faction gameplay.

Main Commands: /hf | /hyfaction | /faction | /f

✨ Key Features

🏰 Advanced Faction Management

Create & manage factions with unique names and random colors
Three-tier role hierarchy (Owner, Officer, Member) with distinct permissions
Smart invitation system with explicit acceptance
Comprehensive activity logs tracking the last 100 faction actions
Individual faction storage with isolated JSON files per faction
Complete dissolution removing all claims and data files
🆕 Member limit system - Configure maximum members per faction (default: 50)
🆕 Disband confirmation - New popup to prevent accidental faction deletion

🗺️ Intelligent Territory System

Chunk-based claiming protecting faction territories
Visual map integration displaying claimed chunks in faction colors
Integrated minimap in GUI for contextual awareness
15x15 chunk grid for easy territory management
Power-based limits ensuring balanced expansion
🆕 Adjacent claims system - Force factions to claim only connected territories
🆕 Anti-hole protection - Prevents disconnected chunk groups when unclaiming
🆕 Overclaiming system - Capture enemy territory when their power reaches 0!
🆕 Inactive faction decay - Auto-remove claims from inactive factions
Automatic decay system for inactive or low-power factions (configurable)
Dimension restrictions preventing claims in temporary or restricted areas

⚡ Dynamic Power System

Personal power for each player (configurable cap at 20)
Faction power calculation as sum of member power (capped per player)
Automatic regeneration every configurable interval (+1 power/player)
Strategic power loss on death (-1) or killing neutrals (-1)
🆕 Configurable power cost - Set power required per claim (default: 2)
🆕 No power loss in WarZones - Fight freely without penalties!
Real-time recalculation on member changes and power events
Power deficit penalties triggering automatic claim decay

🤝 Diplomatic Relations System

Alliances - Mutual protection, shared land access, no friendly fire
Enemies - Full PvP, bidirectional hostility, overclaiming enabled 🔥
Neutrals - PvP enabled with power penalties for aggression
Alliance request system with approval/rejection mechanics
Automatic enemy conversion when rejecting alliance requests
Color-coded displays (green allies, red enemies, white/gray neutrals)

🏠 Home & Teleportation

Faction home set by owner in claimed territory
Exact teleportation preserving position AND rotation (yaw/pitch)
Cross-dimension support using Hytale's native teleportation
Member-only access with permission checks
Configurable cooldown and delay system

⚔️ Advanced Combat System

Combat tagging preventing logout exploitation (15s default)
Relationship-based PvP rules (allies protected, enemies open)
Power penalties for attacking neutrals
Combat logs tracking all deaths with timestamps
🆕 Safe zones for admin-designated protection areas (Green)
🆕 WarZones for PvP combat without power loss penalties (Red)
Death detection via ECS DeathComponent and chat analysis

💬 Faction & Alliance Chat System - NEW!

🆕 Chat Toggle Mode - Switch between chat channels instantly
Faction Chat (/hf c) - Toggle faction chat mode
Alliance Chat (/hf a) - Toggle alliance chat mode
General Chat (/hf g) - Toggle back to general chat
Visual confirmation when switching chat modes
Distinct formatting with custom colors and prefixes
Secure messaging - Only faction/allied members can participate
No message duplication - Efficient message delivery
Permission-based control via LuckPerms integration

🎯 Special Zone System - NEW!

🟢 SafeZones (Green)

Complete protection from all PvP combat
No block breaking or placement allowed
Admin-designated safe areas for spawns, hubs, or events
Displayed in green on the world map
Highest priority in map display

🔴 WarZones (Red)

🆕 Dedicated PvP combat zones
PvP enabled without power loss on death
No penalties for dying in WarZones
Ideal for events, arenas, and organized combat
Displayed in red on the world map
Automatic "WarZone" title notification on entry/exit
Visual indication in claim GUI: "PvP enabled - No power loss on death"
Admin-only creation and management

🛡️ Comprehensive Protection

Block placement/breaking protection in claimed chunks
Interaction protection for containers, doors, and mechanisms
Fluid placement protection (water, lava, etc.)
Item pickup protection in claimed areas
Allied access to friendly territories (configurable)
Creative mode bypass option for building (configurable)
Admin override system for server management
🆕 Multi-world support - Works correctly with multiple worlds and dimensions

👑 Professional Admin Tools

Consolidated admin menu with all management options
Unlimited claiming for server setup and events
Bypass mode toggle for modifying any territory
🆕 Enhanced admin unclaim - Can unclaim even if creates disconnected groups
🆕 Safe zone management (add/remove/list)
🆕 WarZone management - New dedicated menu for creating combat zones
Admin chunk GUI with unrestricted access
Override system for special permissions

🎨 Modern User Interface

Interactive main menu showing faction stats, members, and actions
Chunk management GUI with integrated minimap and 15x15 grid
🆕 Auto-updating alliance UI - Reflects changes in real-time
Alliance management with visual request handling
Faction browser listing all factions with click-to-view members
🆕 Disband confirmation popup - Prevents accidental faction deletion
Multi-page wiki with comprehensive in-game documentation
Help system with categorized command reference
Color-coded badges for roles and relationships
🆕 WarZone indicators in claim GUI with clear tooltips

📋 Complete Command Reference

Basic Faction Commands

Command	Permission	Description
`/hf` or `/hf list`	-	Open interactive faction menu (GUI)
`/hf create <n>`	`hyfaction.create`	Create a new faction with unique name
`/hf invite <player>`	`hyfaction.invite`	Invite player to faction (Owner/Officer)
`/hf accept`	-	Accept pending faction invitation
`/hf leave`	-	Leave current faction (not for Owner)
`/hf kick <player>`	`hyfaction.kick`	Remove player from faction
`/hf disband`	`hyfaction.disband`	Dissolve faction completely (Owner only)

Home & Teleportation

Command	Permission	Description
`/hf sethome`	`hyfaction.sethome`	Set faction home at current position (Owner only)
`/hf home`	`hyfaction.home`	Teleport to faction home with exact rotation

Member Management

Command	Permission	Description
`/hf promote <player>`	`hyfaction.promote`	Promote member to Officer (Owner only)
`/hf demote <player>`	`hyfaction.demote`	Demote Officer to Member (Owner only)

Territory Management

Command	Permission	Description
`/hf chunk`	`hyfaction.claim`/`hyfaction.unclaim`	Open chunk management GUI with minimap
`/hf overclaim`	`hyfaction.claim`	🆕 NEW - Capture enemy faction chunk (requires ≤0 power, enemy relation)

Note: Direct /hf claim and /hf unclaim commands are deprecated. All territory management now uses the /hf chunk GUI.

Diplomatic Relations

Command	Permission	Description
`/hf ally <faction>`	`hyfaction.ally`	Send alliance request (auto-accept if mutual)
`/hf enemy <faction>`	`hyfaction.enemy`	Declare faction as enemy (bidirectional, enables overclaiming)
`/hf neutral <faction>`	`hyfaction.enemy`	Set neutral relationship (unilateral)
`/hf faction`	-	View all factions with relations and stats

Information & Help

Command	Permission	Description
`/hf logs`	-	Display last 100 faction activity entries
`/hf help`	-	Open interactive help menu with all commands
`/hf wiki`	-	Access multi-page in-game documentation

Communication Commands - 🆕 NEW!

Command	Permission	Description
`/hf c <message>`	`hyfaction.chat.faction`	🆕 Toggle faction chat mode - Switch to faction channel
`/hf a <message>`	`hyfaction.chat.ally`	🆕 Toggle alliance chat mode - Switch to alliance channel
`/hf g`	-	🆕 Toggle general chat - Return to global chat

Administrative Commands

Command	Permission	Description
`/hf admin`	`hyfaction.admin`	Open consolidated admin menu
`/hf admin-chunk`	`hyfaction.admin`	Open admin chunk GUI (unlimited)
`/hf admin-claim`	`hyfaction.admin`	Claim current chunk (unrestricted)
`/hf admin-unclaim`	`hyfaction.admin`	Unclaim current chunk (any owner)
`/hf admin safezone add`	`hyfaction.admin`	Add current chunk as safe zone
`/hf admin safezone remove`	`hyfaction.admin`	Remove safe zone from current chunk
`/hf admin safezone list`	`hyfaction.admin`	List all safe zones with coordinates
`/hf admin warzone add`	`hyfaction.admin`	🆕 NEW - Add current chunk as WarZone
`/hf admin warzone remove`	`hyfaction.admin`	🆕 NEW - Remove WarZone from current chunk
`/hf admin warzone list`	`hyfaction.admin`	🆕 NEW - List all WarZones with coordinates

🔑 Permissions & Integrations

Permission System Integration

Hyfaction supports multiple permission systems for maximum flexibility:

LuckPerms

Full integration with LuckPerms for granular permission control. Without LuckPerms, all permissions default to granted (permissive mode).

HyperPerms ⭐

Automatic integration with HyperPerms - Advanced permissions for Hytale!

Features:

🎨 Automatic faction prefix in chat - Shows faction name before player's group prefix
👑 Optional rank display - Include faction rank (Owner, Officer, Member) in chat
🔧 Chat placeholders - Use faction data anywhere in chat format
⚙️ Customizable formats - Full control over faction info display

Placeholders Available:

{hyfaction_faction_name} - Faction name (empty if none)

{hyfaction_faction_rank} - Player's rank (Leader / Officer / Member)

{hyfaction_faction_rank_raw} - Raw rank (OWNER / OFFICER / MEMBER)

{hyfaction_faction_power} - Total faction power

{hyfaction_faction_claims} - Number of chunks claimed

{hyfaction_faction_claims_max} - Maximum number of claims possible (based on config + power)

{hyfaction_player_power} - Player's personal power

{hyfaction_player_power_max} - Maximum power per player (according to config)

{hyfaction_display_name} - Display name (used in tracker)

{hyfaction_has_faction} - Boolean indicating if the player has a faction ("true" or "false")

{hyfaction_is_owner} - Boolean indicating if the player is owner ("true" or "false")

{hyfaction_is_officer} - Boolean indicating if the player is officer ("true" or "false")

Chat Examples:

in Hyfaction.json

"ChatFormat": "&7[&a{hyfaction_faction_name}&7] &f{hyfaction_display_name}&7: "       
"ChatFormat": "{prefix} &7| &f{username}&7: "         
"ChatFormat": ""

No configuration required! HyperPerms automatically detects Hyfaction. Just install both mods and they work together instantly.

Learn more: HyperPerms HyFactions Integration

Core Permissions

Permission	Function	Notes
`hyfaction.create`	Create factions	Required for `/hf create`
`hyfaction.invite`	Invite players	Also requires Officer+ role
`hyfaction.claim`	Claim chunks	Used in chunk GUI and overclaim
`hyfaction.unclaim`	Unclaim chunks	Used in chunk GUI
`hyfaction.home`	Use faction home	Teleport to home
`hyfaction.sethome`	Set faction home	Owner only + permission
`hyfaction.kick`	Kick members	Owner/Officer + permission
`hyfaction.promote`	Promote to Officer	Owner only + permission
`hyfaction.demote`	Demote to Member	Owner only + permission
`hyfaction.ally`	Manage alliances	Ally/enemy/neutral relations
`hyfaction.enemy`	Manage relations	Same as ally permission
`hyfaction.disband`	Dissolve faction	Owner only + permission
`hyfaction.admin`	Admin access	All admin commands + bypass
`hyfaction.chat.faction`	Faction chat	🆕 Use `/hf c` for faction chat
`hyfaction.chat.ally`	Alliance chat	🆕 Use `/hf a` for alliance chat

Permission Hierarchy

Owner: Automatic bypass for all faction permissions
Officer: Limited permissions based on role + LuckPerms
Member: Basic permissions via LuckPerms only
Admin: Full override with hyfaction.admin permission

⚙️ Configuration

Configuration file: plugins/Hyfaction/config/Hyfaction.json (auto-generated with defaults)

Configuration Options

Setting	Type	Default	Description
`DefaultFactionClaimsAmount`	Integer	25	Starting claims for new factions (legacy)
`MaxFactionClaims`	Integer	100	Absolute maximum chunks per faction
`MaxPlayerPower`	Integer	20	Power cap per player (faction contribution limit)
`PowerRegenerationHours`	Integer	1	Hours between +1 power regeneration
`CombatTagDurationSeconds`	Integer	15	Combat tag duration (logout penalty period)
`ClaimDecaySeconds`	Integer	600	Delay before auto-unclaiming excess chunks (10 min)
`EnableOverclaiming`	Boolean	true	🆕 Enable/disable overclaiming system
`PowerPerClaim`	Integer	2	🆕 Power cost per claim (customizable)
`MaxFactionMembers`	Integer	50	🆕 Maximum members per faction
`OnlyAdjacentClaims`	Boolean	false	🆕 Force adjacent claims only (connected territories)
`InactiveFactionDecayDays`	Integer	7	🆕 Days before auto-removing claims from inactive factions (0 to disable)
`NeutralKillPowerLoss`	Integer	1	🆕 Power loss when killing neutral players (configurable penalty)
`SafeZoneAllowDoors`	Boolean	false	🆕 Allow door interactions in SafeZones
`SafeZoneAllowChests`	Boolean	false	🆕 Allow chest access in SafeZones
`WarZoneAllowDoors`	Boolean	false	🆕 Allow door interactions in WarZones
`WarZoneAllowChests`	Boolean	false	🆕 Allow chest access in WarZones
`ShowClaimsOnMap`	Boolean	true	Display faction chunks on world map
`ShowFactionNameInChat`	Boolean	true	Prefix faction name in chat messages
`HidePlayersNotInSameFactionOnMap`	Boolean	false	Hide non-faction players on map
`HidePlayerNameTags`	Boolean	false	Hide player name tags in-game
`HidePlayerMarkersOnMap`	Boolean	false	Hide player markers on world map
`HomeTeleportDelaySeconds`	Integer	5	Delay before home teleportation
`HomeTeleportCooldownMinutes`	Integer	5	Cooldown between home teleports
`ForceHyfactionChunkWorldMap`	Boolean	true	Force Hyfaction map for compatible dimensions
`CreativeModeBypassProtection`	Boolean	false	Allow creative players to bypass protection
`DefaultFactionBlockPlaceEnabled`	Boolean	true	Allow allies to place blocks by default
`DefaultFactionBlockBreakEnabled`	Boolean	false	Allow allies to break blocks by default
`DefaultFactionBlockInteractEnabled`	Boolean	false	Allow allies to interact with blocks by default

Complete Configuration Example

{
  "DefaultFactionClaimsAmount": 25,
  "DefaultFactionBlockPlaceEnabled": true,
  "DefaultFactionBlockBreakEnabled": false,
  "DefaultFactionBlockInteractEnabled": false,
  "ForceHyfactionChunkWorldMap": true,
  "CreativeModeBypassProtection": false,
  "ShowClaimsOnMap": true,
  "CombatTagDurationSeconds": 15,
  "PowerRegenerationHours": 1,
  "MaxPlayerPower": 20,
  "ShowFactionNameInChat": true,
  "MaxFactionClaims": 100,
  "ClaimDecaySeconds": 600,
  "HidePlayersNotInSameFactionOnMap": false,
  "HomeTeleportDelaySeconds": 5,
  "HomeTeleportCooldownMinutes": 5,
  "HidePlayerNameTags": false,
  "HidePlayerMarkersOnMap": false,
  "EnableOverclaiming": true,
  "PowerPerClaim": 2,
  "MaxFactionMembers": 50,
  "OnlyAdjacentClaims": true,
  "InactiveFactionDecayDays": 7,
  "NeutralKillPowerLoss": 1,
  "SafeZoneAllowDoors": false,
  "SafeZoneAllowChests": false,
  "WarZoneAllowDoors": false,
  "WarZoneAllowChests": false
}

👥 Faction Role System

👑 Owner (Proprietor)

Unique faction leader with absolute control

Permissions:

Dissolve faction completely
Promote members to Officer
Demote Officers to Member
Kick any member (Officers and Members)
Set faction home location
Manage all diplomatic relations
Accept/reject alliance requests
Invite new players

Restrictions:

Cannot leave faction (must disband)
Cannot be kicked or demoted
Only one Owner per faction

⭐ Officer

Trusted member with management authority

Permissions:

Invite new players
Kick Members only (not other Officers)
Manage diplomatic relations (ally/enemy/neutral)
Accept/reject alliance requests
Claim/unclaim chunks (with LuckPerms permission)
Use overclaim on enemy territory

Restrictions:

Cannot promote/demote anyone
Cannot kick other Officers or Owner
Cannot dissolve faction
Cannot set faction home

🎖️ Member

Standard faction participant

Permissions:

Claim chunks (with hyfaction.claim)
Unclaim chunks (with hyfaction.unclaim)
Overclaim enemy chunks (with hyfaction.claim)
Teleport to faction home
View faction information
Access faction logs

Restrictions:

Cannot invite players
Cannot kick anyone
Cannot manage relations
Cannot promote/demote
Cannot set home
No management access

🎮 Advanced Systems

Power System Mechanics

Calculation:

Faction power = Sum of all member power (capped at MaxPlayerPower per player)
Example: With MaxPlayerPower = 20, a player with 25 power contributes only 20

Regeneration:

+1 power per player every PowerRegenerationHours
Individual timers (not simultaneous)
Automatic recalculation on completion

Power Loss:

-1 power on death (detected via DeathComponent or chat keywords)
-1 power for killing neutral players
🆕 No power loss when dying in WarZones
Tracked in CombatLogManager

Recalculation Triggers:

Member joins/leaves faction
Power regeneration completes
Death or kill events
Automatic every 5 minutes

Claim Limit Formula:

maxClaims = min(factionPower / PowerPerClaim, MaxFactionClaims)

Default: 1 claim requires 2 power (configurable via PowerPerClaim)

🆕 Adjacent Claims System - NEW!

Force connected territories for strategic gameplay!

How it works:

When OnlyAdjacentClaims: true, factions can only claim chunks next to existing claims
First claim in each dimension becomes the starting point
Anti-hole protection prevents creating disconnected groups when unclaiming
Admin bypass - Admins can still unclaim any chunk via admin commands

Benefits:

Encourages strategic territory planning
Prevents scattered, disconnected claims
Creates more cohesive faction territories
Easier to defend contiguous land

Configuration:

OnlyAdjacentClaims: true - Enable adjacent claims requirement
OnlyAdjacentClaims: false - Allow claiming anywhere (default)

🆕 Inactive Faction Decay - NEW!

Automatically clean up claims from inactive factions!

How it works:

Hourly check scans all factions for activity
If no members have been online for InactiveFactionDecayDays days, claims are removed
Factions themselves remain (members can rejoin and reclaim)
Configurable duration or disable entirely

Configuration:

InactiveFactionDecayDays: 7 - Auto-remove claims after 7 days of inactivity
InactiveFactionDecayDays: 0 - Disable inactive decay system

Benefits:

Keeps map clean from abandoned territories
Frees up land for active players
Prevents server bloat from inactive factions
Configurable to match your server's activity level

🔥 Overclaiming System

Capture enemy territory through strategic warfare!

Requirements:

✅ Target faction must have ≤ 0 power
✅ Target faction must be declared as enemy (use /hf enemy <faction>)
✅ Chunk must already be claimed by the enemy faction
✅ Your faction must have enough available claims

How it works:

Declare a faction as enemy: /hf enemy <targetFaction>
Engage in combat to reduce their power to 0 or below
Stand in a chunk claimed by the enemy faction
Execute /hf overclaim to capture it

Configuration:

EnableOverclaiming: true - Overclaiming enabled, no automatic decay
EnableOverclaiming: false - Overclaiming disabled, normal decay system applies

Success Messages:

✅ "Successfully overclaimed chunk from [FactionName]!"

Error Messages:

❌ "You can only overclaim chunks from factions with ≤ 0 power"
❌ "You can only overclaim chunks from enemy factions"
❌ "This chunk is not claimed"

💬 Chat System - NEW!

Faction Chat:

Format: [FACTION] [FactionName] Player: Message
Custom colors based on your faction's RGB color
Private communication - Only faction members receive messages
Perfect for: Quick coordination during raids and PvP battles

Alliance Chat:

Format: [ALLY] [FactionName] Player: Message
Cyan color to distinguish from faction messages
Coordinate with allies - Messages sent to all allied factions
Requires: At least one allied faction
Perfect for: Large-scale attacks and strategic planning

Usage Examples:

/hf c Everyone online for the raid at 8pm!
/hf a Need backup at coordinates X:100 Z:200

Response Messages:

✅ "Message sent to faction" - Successfully sent
✅ "Message sent to X allied faction(s)" - Sent to allies
❌ "You don't have any allied factions" - No alliances
❌ "You must be in a faction to use faction chat" - Not in faction
❌ "You don't have permission to use this command" - Missing permission

PvP System

Damage Rules:

Same faction: Damage canceled
Allied factions: Damage canceled, shared land access
Enemy factions: Full PvP enabled, combat tag applied, overclaiming available
Neutral players: PvP enabled, combat tag applied, -1 power penalty for killer
Safe zones: All damage canceled
WarZones: PvP enabled, no power loss on death

Combat Tag:

Duration: CombatTagDurationSeconds (default: 15s)
Logout during tag: -1 power penalty
Tracked per player with expiration

📁 API

API Package: com.kaws.hyfaction.api

PlayerFactionInfo (DTO)

Data Transfer Object containing player and faction information.

Available Methods:

getPlayerUuid() - Returns UUID - Player's UUID
getPlayerName() - Returns String - Player's name (cached or "Unknown")
getFactionId() - Returns UUID - Faction's UUID, or null if no faction
getFactionName() - Returns String - Faction's name, or null
getRank() - Returns Rank - Player's rank (OWNER, OFFICER, MEMBER), or null
hasFaction() - Returns boolean - true if player has a faction

HyfactionApi (Utility Class)

Main Method:

PlayerFactionInfo HyfactionApi.getPlayerAndFaction(UUID playerUuid)

Description: Retrieves the player's information and their faction data.

Returns: A PlayerFactionInfo object containing player data and faction data (or null for all faction fields if player has no faction).

Usage Example:
UUID playerUuid = player.getUniqueId();
PlayerFactionInfo info = HyfactionApi.getPlayerAndFaction(playerUuid);

if (info.hasFaction()) {
System.out.println(info.getPlayerName() + " is in " + info.getFactionName());
} else {
System.out.println(info.getPlayerName() + " has no faction");
}

File Structure (v1.0.389+)

plugins/Hyfaction/config/
├── Hyfaction.json (configuration)
├── Parties.json
├── Claims.json
├── NameCache.json
├── AdminOverrides.json
├── SafeZones.json
├── WarZones.json
├── combatlogs.json
└── faction/
    ├── {UUID1}.json
    ├── {UUID2}.json
    └── ...

🎯 Perfect For

✅ Competitive PvP servers with organized faction warfare
✅ Survival servers requiring territorial control
✅ RPG servers needing clan/guild systems
✅ Large-scale servers with structured player organizations
✅ Community servers fostering team-based gameplay
✅ Hardcore servers with strategic land management
✅ 🆕 Event servers with dedicated PvP arenas (WarZones)
✅ 🆕 Multi-world servers - Fully compatible with multiple dimensions

💡 Why Choose Hyfaction?

Modern Architecture

Native ECS integration for optimal performance
Asynchronous data handling preventing lag
Modular system design for extensibility
🆕 Multi-world thread safety - Proper synchronization across dimensions

Comprehensive Features

Every feature a faction mod needs
No external dependencies required
Optional integrations: LuckPerms & HyperPerms
Professional admin tools included
🆕 Overclaiming system for strategic territory control
🆕 WarZones for penalty-free PvP events

User-Friendly Design

Intuitive GUI for all major functions
In-game wiki and help system
Visual feedback and notifications
Clear zone indicators on map and in-game

Active Development

Regular updates and bug fixes
Community-driven improvements
Version 1.0.395+ tested and stable
Crash fixes for multi-world servers

🆘 Support & Documentation

In-Game Help:

/hf wiki - Complete multi-page documentation
/hf help - Command reference with descriptions

Configuration:

Auto-generated config with sensible defaults
Fully documented options
Examples included

Troubleshooting:

Check plugins/Hyfaction/config/ directory for data files
Verify LuckPerms installation (optional)
Review server logs for errors
Migration issues? Ensure all files were moved correctly from universe/Hyfaction/

🔗 Quick Links

Commands: Use /hf help in-game
Wiki: Access via /hf wiki in-game
Config: plugins/Hyfaction/config/Hyfaction.json
Data: plugins/Hyfaction/config/ directory
Permissions: LuckPerms & HyperPerms compatible
HyperPerms Integration: Documentation

📝 Technical Specifications

Hytale Version: Compatible with latest Hytale server
Mod Version: 1.0.509+
Dependencies: None (optional: LuckPerms, HyperPerms)
Permission Systems: LuckPerms, HyperPerms (auto-detection)
Languages: 🌍 Multi-language support (EN, FR, ES, DE)
Multi-World: ✅ Full support with crash fixes
ECS Systems: 11 registered systems
Storage: JSON-based with async saving
Data Location: plugins/Hyfaction/config/
Performance: Optimized map updates with chunk-specific queue system

🌐 Features at a Glance

Feature	Status	Details
Faction Creation	✅	Unique names, auto-owner assignment
Territory Claims	✅	Chunk-based with power limits
Overclaiming	✅	🆕 Capture enemy territory at 0 power
Alliance System	✅	Request/accept with mutual requirements
PvP Management	✅	Relationship-based damage control
Power System	✅	Regeneration, loss, decay mechanics
Protection	✅	Blocks, fluids, interactions, pickups
Admin Tools	✅	Unlimited claims, bypass, safe zones
WarZones	✅	🆕 PvP without power loss penalties
SafeZones	✅	Complete protection zones
Faction Chat	✅	🆕 Private faction communication (`/hf c`)
Alliance Chat	✅	🆕 Coordinate with allies (`/hf a`)
Multi-World	✅	🆕 Thread-safe operations across dimensions
Adjacent Claims	✅	🆕 Force connected territories (configurable)
Inactive Decay	✅	🆕 Auto-remove claims from inactive factions
Member Limits	✅	🆕 Configurable max members per faction
Multi-Language	✅	🆕 Support for EN, FR, ES, DE
Chat Toggle	✅	🆕 Switch between chat channels instantly
Zone Permissions	✅	🆕 Configure door/chest access in zones
GUI Interface	✅	Modern menus with minimap integration
World Map	✅	Colored faction territories + zones
Combat Logging	✅	Death tracking and power penalties
LuckPerms	✅	Full integration (optional)
HyperPerms	✅	Auto chat integration with placeholders
ECS Integration	✅	11 systems for optimal performance

🔄 Changelog Highlights

v1.0.509 - Major Overhaul Update 🚀

🌍 Multi-Language System - JSON-based translations (EN, FR, ES, DE)
💬 Chat Toggle Mode - Switch between faction/alliance/general chat with /hf c, /hf a, /hf g
🔧 Enhanced LuckPerms Integration - Improved prefix/suffix support with placeholder resolution
⚡ Optimized Map Updates - Chunk-specific queue system for better performance
🛡️ Zone Permissions - Configure door/chest access in SafeZones and WarZones
⚙️ Configurable Power Loss - NeutralKillPowerLoss setting for killing neutral players
🗑️ UI Cleanup - Removed wiki button and faction descriptions for cleaner interface
🔒 Thread Safety - Fixed volatile flags and race conditions
📊 Performance Boost - Only modified chunks are updated instead of entire map
🎨 Better Chat Formatting - LuckPerms prefix/suffix with color code conversion

New Configuration Options:

{
  "NeutralKillPowerLoss": 1,
  "SafeZoneAllowDoors": false,
  "SafeZoneAllowChests": false,
  "WarZoneAllowDoors": false,
  "WarZoneAllowChests": false
}

Language Files: Auto-generated in config/lang/ (en-US.json, fr-FR.json, es-ES.json, de-DE.json)

v1.0.430 - Adjacent Claims & Configuration Update ⚙️

🆕 Adjacent Claims System - Force factions to claim only connected territories
🆕 Anti-hole protection - Prevents disconnected chunk groups when unclaiming
🆕 Inactive Faction Decay - Auto-remove claims after X days of inactivity (configurable)
🆕 PowerPerClaim - Customizable power cost per claim (default: 2)
🆕 MaxFactionMembers - Limit maximum members per faction (default: 50)
🆕 Auto-updating Alliance UI - Alliance interface updates in real-time
🆕 Disband confirmation popup - Prevents accidental faction deletion
🔧 Thread safety fixes - Fixed volatile flags and race conditions
🔧 Enhanced admin powers - Admins can unclaim even if creates disconnected groups
⚙️ Decay system improvements - Now respects adjacency rules

Configuration Example:

{
  "PowerPerClaim": 2,
  "MaxFactionMembers": 50,
  "OnlyAdjacentClaims": false,
  "InactiveFactionDecayDays": 7
}

v1.0.395 - Crash Fix Update 🛠️

🔧 CRITICAL FIX - Resolved server crashes on multi-world servers
✅ Stability restored - Plugin now works correctly with multiple worlds
🔒 Thread safety - All player access executed in correct world thread
🚫 No more crashes - Fixed synchronization issues in map, chat, and notification systems
Hotfix release - Immediate update recommended for multi-world servers

v1.0.389 - Data Migration Update 📁

🆕 NEW DATA LOCATION - Moved from universe/Hyfaction/ to plugins/Hyfaction/config/
🆕 Parties.json - New party system data file
📁 Better organization - All data files in one location with configuration
🔧 Multi-world support - Fixed threading issues for servers with multiple worlds
✅ Thread safety - All player access now executed in correct world thread
🛡️ Stability improvements - Better synchronization for map, chat, and notification systems
⚙️ Code improvements - Fixed Java deprecation warnings
Migration guide included for seamless upgrade
⚠️ REQUIRES MANUAL MIGRATION - See migration guide above

v1.0.370 - Communication Update 💬

🆕 Faction Chat - Private communication with /hf c
🆕 Alliance Chat - Coordinate with allies via /hf a
🆕 Chat Permissions - Control access with LuckPerms
Custom color formatting based on faction colors
Efficient message delivery without duplication
Bug fixes and performance improvements

v1.0.365 - WarZone Update 🔥

🆕 WarZones System - Dedicated PvP zones without power loss
🆕 Overclaiming - Capture enemy territory at 0 power
🆕 SafeZones - Complete protection for spawn areas
Enhanced map display with priority zones
Improved combat logging and tracking
HyperPerms integration support
Performance optimizations and bug fixes

Transform your Hytale server into an epic faction battlefield! ⚔️🏰

Hyfaction - Where strategy meets survival