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 76 interactive GUI pages, 46 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 |
| Faction upkeep system (flat/progressive tiered pricing) |
Implemented |
| VaultUnlocked integration |
Implemented |
| Ecotale integration |
Planned #20 |
Protection
| Feature |
Status |
| Block, item, PvP protection |
Implemented |
| HyperProtect-Mixin (27 hooks, recommended) |
Implemented |
| OrbisGuard-Mixins (11 hooks, alternative) |
Implemented |
| Dual-provider auto-detection |
Implemented |
| Mob spawn suppression |
Implemented |
| Mob clearing zone flags |
Implemented |
| Gravestones integration |
Implemented |
| Zone flags (50) |
Implemented |
| Command blocking in zones |
Implemented |
| Sentry error tracking |
Implemented |
GUI
| Feature |
Status |
| 76 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-v7) |
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 |
| KyuubiSoft Core (citizen NPC protection) |
Implemented |
| Sentry (error tracking) |
Implemented |
Planned Features
Quick Start
- Download the latest release from GitHub Releases or CurseForge
- Install by placing
HyperFactions-<version>.jar in your server's mods/ directory
- 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
- Create a faction with
/f create MyFaction and claim territory with /f claim
Recommended: Install HyperProtect-Mixin in earlyplugins/ for full protection coverage (27 hook types including teleporter/portal blocking, entity damage, capture crate/NPC protection, mount/barter/fluid/projectile control, 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 |
76 permission nodes, chain-based resolution |
| config.md |
ConfigManager, 10 config files, migration (v1-v7) |
| storage.md |
Interface-based storage, JSON adapters, backup system |
| gui.md |
76 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, KyuubiSoft |
| placeholders.md |
All 49 PAPI & WiFlow placeholders with examples |
Feature Documentation
For Developers
Maven Dependency (JitPack)
Add HyperFactions as a dependency to build integrations:
repositories {
maven { url 'https://jitpack.io' }
}
dependencies {
compileOnly 'com.github.HyperSystems-Development:HyperFactions:v0.11.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
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 |
| HyperFactions |
Faction management with territory, diplomacy, and economy |
Production |
GitHub |
| HyperEssentials |
Modular server essentials (homes, warps, spawns, TPA, kits, moderation) |
Production |
GitHub |
| HyperProtect-Mixin |
Server-level event interception for protection hooks |
Production |
CurseForge |
| Ecotale |
Economy system with balance HUD, admin GUI, multi-storage |
Production |
CurseForge |
| Werchat |
Channel-based chat system with moderation tools |
Production |
CurseForge |
| 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 HyperSystems-Development — Forge Your Empire
Gameplay
Quality of Life
Utility
