⚔️HyperFactions - The Complete Faction System for Hytale
Build empires. Claim territory. Forge alliances. Wage war. HyperFactions is a full-featured faction management system built from the ground up for Hytale servers, with an emphasis on polished GUIs, deep configurability, and seamless integration with the HyperSystems ecosystem.
Everything is accessible through an intuitive in-game GUI (/f) or commands. No wiki required to get started.
💬 Join our Discord | 📖 Documentation & Wiki | 🔗 GitHub
✨ Why HyperFactions?
- 70+ Interactive GUI Pages - Every feature has a polished, interactive GUI. No command memorization needed.
- Real-Time GUI Updates - When a member joins, a chunk is claimed, or a relation changes, every open GUI refreshes automatically.
- 51 Zone Flags - The most granular territory protection available, from PvP and granular friendly fire to mob spawning, transport control, and F-key pickup.
- Data Import - Migrating from ElbaphFactions, HyFactions, SimpleClaims, or FactionsX? One command imports your factions, claims, and relations.
- Deep Configurability - 11 modular config files covering every aspect of gameplay. Tune it to your server's style.
- Active Development - Regular updates with community-driven features. Open source on GitHub.
🆕 What's New in v0.12.0
- Built-in Localization (i18n) - 10 languages out of the box: English, German, Spanish, French, Italian, Dutch, Polish, Portuguese, Russian, Filipino. Player language auto-detection with configurable default.
- Admin GUI: Config Editor - Edit all HyperFactions settings in-game with 11 tabs, size-adaptive layouts, boolean toggles, steppers, color pickers, dropdowns, and input validation
- Admin GUI: Backup Manager - Paginated backup list with create, restore, and delete operations, plus type filtering
- Admin GUI: Updates Page - Check for HyperFactions and HyperProtect-Mixin updates, download, and rollback — all from the GUI
- SimpleClaims & FactionsX Importers - Two new data importers: migrate from SimpleClaims (SQLite or JSON) or FactionsX with full claim, member, and relation import
- BetterMap Compatibility - Per-world WorldMap enable/disable config, claims and zones render correctly on BetterMap-managed worlds
- Ocean Claim Visibility Fix - Faction claims in water/ocean are now clearly visible on the world map
🏰 Core Features
👥 Faction Management
- Create factions with custom names, tags, colors, and descriptions
- Three-tier role hierarchy - Leader, Officer, Member with granular permissions per role
- Territory permissions - Configure break, place, and interact access for outsiders, allies, and members independently. Server owners can lock specific permissions in
faction-permissions.json to enforce server-wide rules that factions cannot override.
- Invite system with expiring invitations and join requests for closed factions
- Leadership transfer with automatic succession when leaders leave
- Disband confirmation to prevent accidental faction deletion
- Faction browser - Search and sort all factions, view details, and request to join
- Activity logs - Track all faction events with timestamps
🗺️ Territory & Claiming
- Chunk-based claiming with interactive GUI map (click to claim/unclaim)
- Terrain map mode - See actual terrain imagery behind claim overlays for easy orientation
- World map integration - See all claims colored by faction on Hytale's world map (press M)
- Power-based claim limits - More members means more territory
- Overclaiming - Capture enemy territory when their power hits zero
- Claim decay - Inactive factions automatically lose claims after a configurable period
- 5 world map refresh modes - From proximity-based to manual, pick what works for your server
- Configurable map display - Toggle faction tags, player markers, and non-faction player visibility
⚡ Dynamic Power System
- Personal power per player (configurable cap, default 20)
- Automatic regeneration at configurable intervals
- Power loss on death detected via Hytale's ECS system, with separate toggles for PvP, mob, and environmental deaths
- Configurable power cost per claim (default: 2 power per chunk)
- No power loss in WarZones - Fight freely in designated PvP arenas
- Neutral kill penalty - Configurable power loss for attacking neutral players
- Combat logout penalty - Separate configurable power loss for logging out during combat
🤝 Diplomatic Relations
- 💚 Alliances - Mutual protection, shared land access, no friendly fire
- ❤️ Enemies - Full PvP enabled, overclaiming unlocked
- 🤍 Neutrals - PvP enabled with power penalties for aggression
- GUI-based diplomacy - Browse factions, send ally/enemy/neutral requests from the GUI
- Relation-based chat colors - Green (same faction), pink (ally), red (enemy), gray (neutral) in public chat
⚔️ Combat System
- Combat tagging - Prevents logout exploitation (configurable duration, default 15s)
- Spawn protection - Configurable invulnerability after respawn
- Relationship-based PvP - Allies protected, enemies open, configurable per zone
- Overclaim defender alerts - Faction members get real-time alerts when territory is being taken
💰 Faction Economy
- Faction treasury with deposits, withdrawals, inter-faction transfers, and transaction history
- Upkeep system - Automated territory maintenance costs with flat or progressive tiered pricing, grace periods, and auto-pay
- VaultUnlocked integration - Works with any economy plugin via the standard economy API
🌍 Localization
- 10 languages built in: English, German, Spanish, French, Italian, Dutch, Polish, Portuguese, Russian, Filipino
- Player language auto-detection with configurable default and per-player override
- ~467 translation entries per locale covering all commands, GUI labels, and help content
🛡️ Protection System
HyperFactions provides comprehensive territory protection with 51 configurable zone flags organized into 10 categories:
- ⚔️ Combat (7) - PvP, friendly fire (per-faction/per-ally), projectile damage, PvE damage, mob damage
- 🧱 Building (4) - Build allowed, block place (mixin), hammer use (mixin), builder tools (mixin)
- 🚪 Interaction (13) - Block interaction, doors, containers, crafting, processing, seats, light use, NPC use/tame/interact, mount use, crate pickup/place
- 🎒 Items (4) - Item drop, auto pickup, F-key pickup (mixin), invincible items (mixin)
- 🐾 Spawning (5) - Mob spawning (master), hostile/passive/neutral mobs, NPC spawning
- 🧹 Mob Clearing (4) - Mob clear (master), hostile/passive/neutral mob clearing
- 💀 Death (2) - Keep inventory (mixin), power loss
- 💥 Damage (4) - Fall damage, environmental damage, explosion damage (mixin), fire spread (mixin)
- 🚀 Transport (3) - Teleporter use (mixin), portal use (mixin), mount entry
- 🔗 Integration (5) - Gravestone access, show on map, essentials homes, essentials warps, essentials kits
🏟️ SafeZones & WarZones
Admins can designate special zones with independent flag configurations:
- 🟢 SafeZones - No PvP, no mob spawning, keep inventory on death. Perfect for spawn areas and markets.
- 🔴 WarZones - Full PvP with no power loss on death. Ideal for arenas and events.
- Visual map indicators - SafeZones appear teal, WarZones appear purple on all maps
- Per-flag customization - Override any default on a per-zone basis
- Mob spawn control - Integrated with Hytale's native spawn suppression system for reliable mob blocking
- Zone creation wizard - Create zones by claiming single chunks, circular radius, square radius, or using the visual map
💬 Faction & Alliance Chat
- Toggle mode -
/f c cycles between Public, Faction, and Ally chat
- Direct set -
/f c f for faction, /f c a for ally, /f c off for public
- Chat history GUI - Browse past faction and ally messages in a dedicated GUI page with tabs
- Custom formatting - Configurable colors and prefixes for each channel
- Secure messaging - Only faction/allied members can see private messages
- Persistent history - Chat messages saved to disk, viewable even after restart
📢 Server-Wide Announcements
Major faction events are broadcast to all online players with configurable toggles:
- Faction created / disbanded
- Leadership transferred
- Territory overclaimed
- War declared
- Alliance formed / broken
Each event type can be individually enabled or disabled in announcements.json.
🖥️ Full GUI System
HyperFactions features 70+ interactive GUI pages covering every aspect of gameplay:
🎮 Player GUI (/f)
- Dashboard - Power, claims, members, relations, status, and invites at a glance
- Territory Map - Interactive chunk map with click-to-claim and visual legend
- Members - Expandable member list with promote, demote, kick, and transfer actions
- Relations - Browse factions and manage diplomacy with ally/enemy/neutral buttons
- Settings - Two-column settings page with faction details, territory permissions, mob spawning controls, and appearance editing
- Chat History - Faction and ally chat logs with tab switching
- Invites - Manage sent invitations and incoming join requests
- Logs - View faction activity history
- Treasury - Manage faction funds with deposits, withdrawals, transfers, and transaction history
- Player Info - View any player's faction membership, power stats, combat record, and history
- Help - Guide-first Help Center with 7 categories, sidebar navigation, and verified command reference
🆕 New Player GUI
- Faction Browser - Search, sort, and view all server factions
- Create Faction Wizard - Single-page creation with preview, color picker, and permission defaults
- World Map - See claimed territory before joining a faction
🔐 Admin GUI (/f admin)
- Dashboard - Server statistics overview
- Faction Management - Browse, edit, and delete any faction
- Zone Management - Create, configure, and map SafeZones and WarZones
- Configuration - Runtime settings adjustment
- Players - Browse all players with search, sort, power stats, and quick actions
- Economy - Server economy overview, per-faction treasury adjustment, sortable faction balance list
- Power Management - Set, adjust, reset player power with bypass toggles and bulk operations
- Activity Log - Server-wide faction activity browser with type, player, and time filters
- Version Info - Mod version, server version, and integration status for all 12 supported mods
- Actions - Global quick actions (K/D reset, bulk operations)
- Zone Properties - Consolidated zone name, type, and notification editing
- Backups - Backup management and restore
- Updates - Check and install updates from within the game
🧠 Smart GUI Behavior
- Permission-based filtering - Buttons and nav tabs automatically hide when the player lacks permission
- Real-time updates - All open GUIs refresh instantly when data changes
- Role-based visibility - Officers and leaders see management options; members see read-only views
🔧 Admin Tools
- Full admin GUI with dedicated navigation and management pages
- Bypass mode - Toggle admin bypass to modify any territory
- Automatic backups - Configurable backup schedule with retention rotation
- Pre-update backups - Data automatically backed up before installing updates
- Rollback support -
/f admin rollback reverts to the previous version before restart
- Debug system - Toggle 7+ debug categories individually for targeted troubleshooting
- Claim decay management - Monitor and manually trigger inactive faction cleanup
- Data import - Migrate from ElbaphFactions, HyFactions, SimpleClaims, or FactionsX with validation reports
- Power management - Per-player power set, adjust, reset, bypass toggles, and bulk faction operations
- Economy management - Server-wide treasury overview, per-faction balance adjustment
- Player browser - Search and manage all server players with sort and quick actions
- Config hot-reload -
/f admin reload reloads all configuration without restart
- Persistent admin bypass - Admin bypass state survives server restarts
- Version info -
/f admin version to check mod version and integration status
📊 PlaceholderAPI Support
HyperFactions provides 49 placeholders for both PlaceholderAPI (PAPI) and WiFlow PlaceholderAPI, covering:
- Faction info (name, tag, description, color, member count)
- Player role and status (rank, is_owner, is_officer, has_faction)
- Power data (player power, max power, faction power, percentage)
- Territory data (claims, max claims, territory owner, territory type)
- Home coordinates and status
- Relation counts and config values
Use with any scoreboard, hologram, or menu plugin that supports PAPI or WiFlow.
🔌 Integrations
All integrations use automatic detection and fail-open design. ⭐ = Recommended
| Mod |
Category |
Description |
| ⭐ HyperPerms |
Permissions |
Faction chat prefixes, rank display, and contextual permissions |
| LuckPerms |
Permissions |
Granular permission control |
| ⭐ VaultUnlocked |
Economy |
Chat, economy, and permission compatibility layer |
| ⭐ HyperProtect-Mixin |
Protection |
28 mixin hooks — F-key pickup, keep inventory, explosions, fire, fluid, transport, mount, barter, projectile, map markers, and more |
| OrbisGuard-Mixins |
Protection |
11 mixin hooks (alternative). Both can run simultaneously — auto-detected |
| OrbisGuard |
Regions |
Blocks claims in OG regions, renders OG regions on world map and territory GUI |
| ⭐ PlaceholderAPI |
Placeholders |
49 placeholders for scoreboards, chat, and menus |
| WiFlow PlaceholderAPI |
Placeholders |
47 placeholders in WiFlow format |
| ⭐ HyBounty |
Gameplay |
Player bounties with faction-aware protections against abuse |
| Gravestones |
Gameplay |
Faction-aware gravestone protection, per-zone access, death location announcements |
| Ecotale |
Economy |
Faction treasury via VaultUnlocked — deposits, withdrawals, transfers, admin tools |
| KyuubiSoft Core |
NPC |
Citizen NPC zone protection with auto-detection |
📦 Data Import
| Source |
What’s Imported |
| ElbaphFactions |
Factions, members, claims, relations, and zones |
| HyFactions |
Factions, members, claims, relations, zones, and power |
| SimpleClaims |
Parties, claims (SQLite or JSON), and mutual alliances |
| FactionsX |
Factions, claims, zones, player power, and per-role permissions |
🔮 Upcoming Integrations
💡 Want HyperFactions to integrate with your plugin? Reach out to DMehaffy on Discord to discuss integration opportunities.
📥 Installation
Basic Install
- Drop
HyperFactions.jar into your mods/ folder
- Start your server
- Type
/f to open the GUI
For Full Protection (Recommended)
- Create an
earlyplugins/ folder in your server directory
- Place Hyxin and HyperProtect-Mixin JARs in
earlyplugins/ (NOT mods/)
- Add the
--accept-early-plugins flag to your server start script:
Linux:
DEFAULT_ARGS="--accept-early-plugins --assets ../Assets.zip --backup --backup-dir backups --backup-frequency 30"
Windows:
set DEFAULT_ARGS=--accept-early-plugins --assets ../Assets.zip --backup --backup-dir backups --backup-frequency 30
HyperFactions works without a mixin system, but 11 zone flags (explosion, fire, block placement, transport, keep inventory, etc.) require HyperProtect-Mixin or OrbisGuard-Mixins.
💡 Tip: HyperFactions can auto-download HyperProtect-Mixin for you! Enable autoDownload in config or run /f admin update mixin in-game.
🚀 Quick Start
1. Grant permissions (with HyperPerms):
/hp group setperm default hyperfactions.use
/hp group setperm default hyperfactions.faction.*
/hp group setperm default hyperfactions.member.*
/hp group setperm default hyperfactions.territory.*
/hp group setperm default hyperfactions.teleport.*
/hp group setperm default hyperfactions.relation.*
/hp group setperm default hyperfactions.chat.*
/hp group setperm default hyperfactions.info.*
2. Start playing:
- 🎮 Players:
/f to open the GUI, or /f create MyFaction
- 🔐 Admins:
/f admin to open the admin panel
💡 No permission mod? Set "allowWithoutPermissionMod": true in config.json to allow all non-admin features by default.
📋 Essential Commands
| Command |
Description |
/f |
Open the faction GUI |
/f create <name> |
Create a new faction |
/f invite <player> |
Invite a player to your faction |
/f home |
Teleport to your faction home |
/f c |
Toggle faction/ally/public chat |
/f ally <faction> |
Send an alliance request |
/f enemy <faction> |
Declare a faction as your enemy |
/f overclaim |
Capture enemy territory (requires 0 or less power) |
/f stuck |
Teleport to safety when trapped in enemy territory |
/f admin |
Open the admin panel |
HyperFactions includes 46 commands across 10 categories. See the full list in the documentation or use /f help in-game.
⚙️ Configuration
HyperFactions uses a modular configuration system with 11 modular config files:
| Config File |
Purpose |
config/factions.json |
Faction gameplay — power, claims, combat, relations, invites, stuck, roles |
config/server.json |
Server behavior — teleport, autoSave, messages, GUI, permissions, updates |
config/chat.json |
Chat formatting, prefixes, and channel settings |
config/announcements.json |
Server-wide announcement and notification toggles |
config/worldmap.json |
World map display, refresh modes, and performance tuning |
config/backup.json |
Backup scheduling, retention, and rotation |
config/debug.json |
Debug categories for targeted troubleshooting |
config/economy.json |
Economy and faction treasury settings |
config/faction-permissions.json |
Default territory permissions with server locks |
config/worlds.json |
Per-world claiming, power loss, and friendly fire overrides |
config/gravestones.json |
Gravestone integration settings |
All settings include sensible defaults. Missing keys are automatically added on startup without overwriting existing values.
🧑💻 For Developers
Want to build integrations with HyperFactions? We publish to JitPack so you can add HyperFactions as a Maven dependency with no authentication required:
repositories {
maven { url 'https://jitpack.io' }
}
dependencies {
compileOnly 'com.github.HyperSystems-Development:HyperFactions:v0.12.0'
}
See the full Developer API Reference on GitHub for API usage, event listeners, economy integration, and more.
🧩 The HyperSystems Suite
| Mod |
Description |
| ⭐ HyperPerms |
Advanced permissions management with groups, inheritance, and web editor |
| ⚔️ HyperFactions |
Complete faction system with territory, diplomacy, economy, and 70+ GUI pages |
| 🛡️ HyperProtect-Mixin |
Mixin-based protection hooks for HyperFactions zone flags |
| 💰 Ecotale |
Economy system with balance HUD, admin GUI, and VaultUnlocked integration |
| 💬 Werchat |
Channel-based chat with private messaging, nicknames, and moderation |
| 🌐 HyperBorder |
World border management (Coming Soon) |
| 🔧 HyperEssentials |
Essential server tools — homes, warps, TPA, spawns, and more (Coming Soon) |
🔗 Links
Part of the HyperSystems suite — built for Hytale, open source, and actively maintained.
