HyperFactions

A comprehensive faction management mod for Hytale servers featuring territory claims, alliances, strategic PvP, economy, and extensive customization. Part of the HyperSystems plugin suite.

Overview

HyperFactions transforms your Hytale server into a dynamic faction-based environment where players create factions, claim territories, forge alliances, manage treasuries, and engage in strategic PvP combat. With 65+ interactive GUI pages, 44 commands, and deep integration with the HyperSystems ecosystem, it provides a complete faction experience out of the box.

Main Commands: /faction | /f | /hf

---

Features

Faction Management

Feature	Status
Create, disband, rename factions	Implemented
Customizable colors and descriptions	Implemented
Three-tier roles with customizable display names	Implemented
Smart invitation system with expiration	Implemented
Join requests for closed factions	Implemented
Configurable member limits	Implemented

Territory

Feature	Status
Chunk-based claiming with visual feedback	Implemented
World map overlays with faction colors	Implemented
Power-based claim limits	Implemented
Adjacent claims mode	Implemented
Overclaiming for strategic warfare	Implemented
Inactive faction claim decay	Implemented
Multi-world support	Implemented
Per-world settings (wildcard patterns)	Implemented
Terrain-based map mode	Implemented

Power System

Feature	Status
Per-player power with configurable cap	Implemented
Death penalty (configurable)	Implemented
Auto-regeneration at intervals	Implemented
Per-zone power loss flags	Implemented
Hardcore mode (shared faction pool)	Implemented
Per-world power loss control	Implemented
Admin power management	Implemented

Diplomacy

Feature	Status
Ally, enemy, neutral relations	Implemented
Alliance request/accept/reject workflow	Implemented
Color-coded displays in GUI and chat	Implemented

Combat

Feature	Status
Combat tagging with logout prevention	Implemented
Relationship-based PvP rules	Implemented
Spawn protection	Implemented

Communication

Feature	Status
Faction chat with history	Implemented
Alliance chat	Implemented
Public chat faction tags	Implemented

Economy

Feature	Status
Faction treasury with balance tracking	Implemented
Deposits, withdrawals, inter-faction transfers	Implemented
Transaction log	Implemented
VaultUnlocked integration	Implemented
Ecotale integration	Planned #20

Protection

Feature	Status
Block, item, PvP protection	Implemented
HyperProtect-Mixin (22 hooks, recommended)	Implemented
OrbisGuard-Mixins (11 hooks, alternative)	Implemented
Dual-provider auto-detection	Implemented
Mob spawn suppression	Implemented
Gravestones integration	Implemented
Zone flags (40)	Implemented
Command blocking in zones	Implemented

GUI

Feature	Status
60+ interactive pages across 3 registries	Implemented
Faction leaderboard	Implemented
Admin dashboard	Implemented
Faction browser with search	Implemented
Territory map with terrain imagery	Implemented
Real-time updates	Implemented

Admin

Feature	Status
Zone management (SafeZone, WarZone)	Implemented
Backup system (GFS rotation)	Implemented
Data import (ElbaphFactions, HyFactions)	Implemented
Config migration (v1-v6)	Implemented
Update checker	Implemented
Admin GUI: Config editor	Planned #40
Admin GUI: Backup manager	Planned #41
Admin GUI: Updates page	Planned #42

Integrations

Feature	Status
HyperPerms	Implemented
LuckPerms	Implemented
VaultUnlocked	Implemented
PlaceholderAPI (49 placeholders, incl. relational)	Implemented
WiFlow	Implemented
HyperProtect-Mixin (recommended)	Implemented
OrbisGuard / OrbisGuard-Mixins	Implemented
Gravestones	Implemented

Planned Features

Feature	Status
Database storage backend	Planned #45
Performance caching	Planned #44
Command aliases	Planned #43
Faction levels & progression	Planned #39
Raid system	Planned #38
War declarations	Planned #37
Faction vaults	Planned #35
Server-managed factions	Planned #33
Relational placeholders	Done in 0.10.0
NPC integrations	Considering #21
Localization	Planned #19
CurseForge updates	Planned #17

---

Quick Start

1. Download the latest release from GitHub Releases or CurseForge
2. Install by placing HyperFactions-<version>.jar in your server's mods/ directory
3. Configure by editing files in mods/com.hyperfactions_HyperFactions/config/ after first startup — factions.json for faction gameplay settings, server.json for server behavior settings
4. Create a faction with /f create MyFaction and claim territory with /f claim

Recommended: Install HyperProtect-Mixin in earlyplugins/ for full protection coverage (22 hook types including teleporter/portal blocking, entity damage, capture crate/NPC tame protection, and respawn override).

Optional: Install HyperPerms for enhanced permission control with groups, tracks, and contextual permissions.

---

Documentation

Comprehensive developer and admin documentation is available in the docs/ directory:

Core Architecture

Document	Description
architecture.md	9-layer design, package structure, dependency graph
managers.md	15 core managers with responsibilities and lifecycles

Systems

Document	Description
commands.md	52 subcommands across 10 categories with full syntax
permissions.md	60 permission nodes, chain-based resolution
config.md	ConfigManager, 10 config files, migration (v1-v6)
storage.md	Interface-based storage, JSON adapters, backup system
gui.md	59 pages, 3 registries, navigation flows
protection.md	ECS handlers, HyperProtect-Mixin / OrbisGuard-Mixins, zone flags

API & Integrations

Document	Description
api.md	HyperFactionsAPI, EconomyAPI, EventBus for third-party mods
integrations.md	HyperPerms, LuckPerms, PAPI, WiFlow, HyperProtect-Mixin, OrbisGuard, Gravestones
placeholders.md	All 49 PAPI & WiFlow placeholders with examples

Feature Documentation

Document	Description
announcements.md	Server-wide broadcasts, 7 event types
data-import.md	ElbaphFactions/HyFactions importers, config migration

---

For Developers

Maven Dependency (JitPack)

Add HyperFactions as a dependency to build integrations:

repositories {
    maven { url 'https://jitpack.io' }
}

dependencies {
    compileOnly 'com.github.HyperSystemsDev:HyperFactions:v0.10.0'
}

See the Developer API Reference for full API documentation.

Building from Source

Requirements

• Java 25
• Gradle 9.3.0+ (included via wrapper)

The Hytale Server API and all required dependencies are resolved automatically from Maven. Optional integrations (WiFlowPlaceholderAPI, GravestonePlugin) use reflection and are not required to compile.

For full functionality during local development, optionally download these JARs into libs/:

JAR	Download	Required?
WiFlowPlaceholderAPI	CurseForge	Optional
GravestonePlugin	CurseForge	Optional

Build

# From HyperSystems root (multi-project build):
./gradlew :HyperFactions:shadowJar

# Output: HyperFactions/build/libs/HyperFactions-<version>.jar

See CONTRIBUTING.md for full development setup and contribution guidelines.

---

Support

• Discord: Join our server
• GitHub Issues: Report bugs or request features

---

HyperSystems Suite

HyperFactions is part of the HyperSystems plugin ecosystem. All plugins integrate seamlessly when installed together.

Mod	Description	Status	Link
HyperPerms	Permissions management with groups, tracks, and web editor	Production	GitHub
HyperHomes	Personal home teleportation with sharing	Production	GitHub
HyperFactions	Faction management with territory, diplomacy, and economy	Production	GitHub
HyperWarp	Warps, spawns, TPA requests, and /back	Production	GitHub
HyperSpawns	Mob spawn zone control with advanced filtering	Production	GitHub
HyperGuard	Server-side anti-cheat	In Development	GitHub
HyperVerse	World management (Multiverse-like)	In Development	GitHub
HyperLogger	Activity logging and rollback	In Development	GitHub

---

License

HyperFactions is licensed under the GNU General Public License v3.0.

---

Developed by HyperSystemsDev — Forge Your Empire