curseforge-description.html

<h2>⚔️<span style="color: #5b8def;">HyperFactions</span> - The Complete Faction System for Hytale</h2>
<p>Build empires. Claim territory. Forge alliances. Wage war. <strong>HyperFactions</strong> is a full-featured faction management system built from the ground up for Hytale servers, with an emphasis on <span style="color: #5b8def;">polished GUIs</span>, <span style="color: #5b8def;">deep configurability</span>, and <span style="color: #5b8def;">seamless integration</span> with the HyperSystems ecosystem.</p>
<p>Everything is accessible through an intuitive in-game GUI (<code>/f</code>) or commands. No wiki required to get started.</p>
<p>💬 <a href="https://discord.com/invite/aZaa5vcFYh" rel="nofollow">Join our Discord</a> | 📖 <a href="https://www.hypersystems.dev/plugins/hyperfactions/wiki" rel="nofollow">Documentation &amp; Wiki</a> | 🔗 <a href="https://github.com/HyperSystemsDev/HyperFactions" rel="nofollow">GitHub</a></p>
<p>&nbsp;</p>
<h2>✨ Why HyperFactions?</h2>
<ul>
    <li>🖥️ <strong><span style="color: #f0b232;">65+ Interactive GUI Pages</span></strong> - Every feature has a polished, interactive GUI. No command memorization needed.</li>
    <li>⚡ <strong><span style="color: #f0b232;">Real-Time GUI Updates</span></strong> - When a member joins, a chunk is claimed, or a relation changes, every open GUI refreshes automatically.</li>
    <li>🛡️ <strong><span style="color: #f0b232;">31 Zone Flags</span></strong> - The most granular territory protection available, from PvP and granular friendly fire to mob spawning, transport control, and F-key pickup.</li>
    <li>📦 <strong><span style="color: #f0b232;">Data Import</span></strong> - Migrating from ElbaphFactions or HyFactions? One command imports your factions, claims, and relations.</li>
    <li>⚙️ <strong><span style="color: #f0b232;">Deep Configurability</span></strong> - 11 modular config files covering every aspect of gameplay. Tune it to your server's style.</li>
    <li>🚀 <strong><span style="color: #f0b232;">Active Development</span></strong> - Regular updates with community-driven features. Open source on GitHub.</li>
</ul>
<p>&nbsp;</p>
<h2><span style="color: #f0b232;">🆕 What's New in v0.10.0</span></h2>
<ul>
    <li>🏆 <strong><span style="color: #61afef;">Faction Leaderboard</span></strong> - <code>/f leaderboard</code> with sortable rankings (K/D, Power, Territory, Balance, Members), pagination, and nav bar integration</li>
    <li>💰 <strong><span style="color: #61afef;">Faction Treasury System</span></strong> - Deposits, withdrawals, inter-faction transfers, transaction history, autopay settings, and admin adjustment tools</li>
    <li>🌍 <strong><span style="color: #61afef;">Per-World Settings</span></strong> - Enable/disable claiming, power loss, and friendly fire per world with wildcard pattern matching</li>
    <li>📋 <strong><span style="color: #61afef;">Activity Log</span></strong> - <code>/f logs</code> for faction events; admin-wide log aggregation with type/player/time filters</li>
    <li>💀 <strong><span style="color: #61afef;">Faction Power Hardcore Mode</span></strong> - Optional shared faction power pool where deaths and kills affect the faction total directly</li>
    <li>🛡️ <strong><span style="color: #61afef;">Capture Crate &amp; NPC Tame Protection</span></strong> - 5 new protection flags for crate pickup, crate placement, and NPC taming</li>
    <li>🔔 <strong><span style="color: #61afef;">Zone Notification Controls</span></strong> - Per-zone entry/leave title suppression with customizable text</li>
    <li>👑 <strong><span style="color: #61afef;">Configurable Role Names</span></strong> - Rename Leader/Officer/Member to anything (e.g., Boss/Underboss/Soldier)</li>
    <li>🔧 <strong><span style="color: #61afef;">Admin Version Page</span></strong> - View mod version, server version, and integration status for all 12 supported mods</li>
    <li>📊 <strong><span style="color: #61afef;">51 Placeholders</span></strong> - Expanded from 30+ with colored variants, treasury data, and relational placeholders</li>
    <li>📁 <strong><span style="color: #61afef;">11 Modular Config Files</span></strong> - Restructured from 8 for better organization (factions, server, worlds, economy, etc.)</li>
    <li>🔒 <strong><span style="color: #61afef;">Persistent Admin Bypass</span></strong> - Admin bypass state survives server restarts</li>
    <li>🛡️ <strong><span style="color: #61afef;">9 New Claim Protection Overrides</span></strong> - Granular explosion, fire spread, item pickup/drop, and entity damage control per relationship</li>
</ul>
<p>&nbsp;</p>
<h2><span style="color: #5b8def;">🏰 Core Features</span></h2>
<h3>👥 Faction Management</h3>
<ul>
    <li><strong>Create factions</strong> with custom names, tags, colors, and descriptions</li>
    <li><strong>Three-tier role hierarchy</strong> - Leader, Officer, Member with granular permissions per role</li>
    <li><strong>Territory permissions</strong> - Configure break, place, and interact access for outsiders, allies, and members independently. Server owners can <span style="color: #e06c75;">lock specific permissions</span> in <code>faction-permissions.json</code> to enforce server-wide rules that factions cannot override.</li>
    <li><strong>Invite system</strong> with expiring invitations and join requests for closed factions</li>
    <li><strong>Leadership transfer</strong> with automatic succession when leaders leave</li>
    <li><strong>Disband confirmation</strong> to prevent accidental faction deletion</li>
    <li><strong>Faction browser</strong> - Search and sort all factions, view details, and request to join</li>
    <li><strong>Activity logs</strong> - Track all faction events with timestamps</li>
</ul>
<h3>🗺️ Territory &amp; Claiming</h3>
<ul>
    <li><strong>Chunk-based claiming</strong> with interactive GUI map (click to claim/unclaim)</li>
    <li><strong>Terrain map mode</strong> - See actual terrain imagery behind claim overlays for easy orientation</li>
    <li><strong>World map integration</strong> - See all claims colored by faction on Hytale's world map (press M)</li>
    <li><strong>Power-based claim limits</strong> - More members means more territory</li>
    <li><strong>Overclaiming</strong> - Capture enemy territory when their power hits zero</li>
    <li><strong>Claim decay</strong> - Inactive factions automatically lose claims after a configurable period</li>
    <li><strong>5 world map refresh modes</strong> - From proximity-based to manual, pick what works for your server</li>
    <li><strong>Configurable map display</strong> - Toggle faction tags, player markers, and non-faction player visibility</li>
</ul>
<h3>⚡ Dynamic Power System</h3>
<ul>
    <li><strong>Personal power</strong> per player (configurable cap, default 20)</li>
    <li><strong>Automatic regeneration</strong> at configurable intervals</li>
    <li><strong>Power loss on death</strong> detected via Hytale's ECS system, with separate toggles for PvP, mob, and environmental deaths</li>
    <li><strong>Configurable power cost per claim</strong> (default: 2 power per chunk)</li>
    <li><strong>No power loss in WarZones</strong> - Fight freely in designated PvP arenas</li>
    <li><strong>Neutral kill penalty</strong> - Configurable power loss for attacking neutral players</li>
    <li><strong>Combat logout penalty</strong> - Separate configurable power loss for logging out during combat</li>
</ul>
<h3>🤝 Diplomatic Relations</h3>
<ul>
    <li>💚 <strong><span style="color: #98c379;">Alliances</span></strong> - Mutual protection, shared land access, no friendly fire</li>
    <li>❤️ <strong><span style="color: #e06c75;">Enemies</span></strong> - Full PvP enabled, overclaiming unlocked</li>
    <li>🤍 <strong><span style="color: #abb2bf;">Neutrals</span></strong> - PvP enabled with power penalties for aggression</li>
    <li><strong>GUI-based diplomacy</strong> - Browse factions, send ally/enemy/neutral requests from the GUI</li>
    <li><strong>Relation-based chat colors</strong> - <span style="color: #98c379;">Green</span> (same faction), <span style="color: #c678dd;">pink</span> (ally), <span style="color: #e06c75;">red</span> (enemy), <span style="color: #abb2bf;">gray</span> (neutral) in public chat</li>
</ul>
<h3>⚔️ Combat System</h3>
<ul>
    <li><strong>Combat tagging</strong> - Prevents logout exploitation (configurable duration, default 15s)</li>
    <li><strong>Spawn protection</strong> - Configurable invulnerability after respawn</li>
    <li><strong>Relationship-based PvP</strong> - Allies protected, enemies open, configurable per zone</li>
    <li><strong>Overclaim defender alerts</strong> - Faction members get real-time alerts when territory is being taken</li>
</ul>
<p>&nbsp;</p>
<h2><span style="color: #e06c75;">🛡️ Protection System</span></h2>
<p>HyperFactions provides comprehensive territory protection with <strong><span style="color: #f0b232;">31 configurable zone flags</span></strong> organized into categories:</p>
<ul>
    <li>⚔️ <strong><span style="color: #e06c75;">Combat</span></strong> - PvP enabled, friendly fire (with per-faction and per-ally sub-flags), projectile damage, mob damage</li>
    <li>🧱 <strong><span style="color: #d19a66;">Building</span></strong> - Build allowed (master), block place <em>(mixin)</em>, hammer use <em>(mixin)</em>, builder tools <em>(mixin)</em></li>
    <li>🚪 <strong><span style="color: #61afef;">Interaction</span></strong> - Block interaction (master), doors, containers, crafting benches, processing blocks, seats</li>
    <li>🎒 <strong><span style="color: #c678dd;">Items</span></strong> - Item drop, auto pickup, F-key pickup <em>(mixin)</em>, invincible items <em>(mixin)</em></li>
    <li>🐾 <strong><span style="color: #98c379;">Spawning</span></strong> - Mob spawning (master), hostile mobs, passive mobs, neutral mobs, NPC spawning</li>
    <li>💀 <strong><span style="color: #abb2bf;">Death</span></strong> - Keep inventory <em>(mixin)</em>, power loss</li>
    <li>💥 <strong><span style="color: #e5c07b;">Damage</span></strong> - Fall damage, environmental damage, explosion damage <em>(mixin)</em>, fire spread <em>(mixin)</em></li>
    <li>🚀 <strong><span style="color: #56b6c2;">Transport</span></strong> - Teleporter use <em>(mixin)</em>, portal use <em>(mixin)</em></li>
</ul>
<p>&nbsp;</p>
<h2><span style="color: #98c379;">🏟️ SafeZones</span> &amp; <span style="color: #e06c75;">WarZones</span></h2>
<p>Admins can designate special zones with independent flag configurations:</p>
<ul>
    <li>🟢 <strong><span style="color: #98c379;">SafeZones</span></strong> - No PvP, no mob spawning, keep inventory on death. Perfect for spawn areas and markets.</li>
    <li>🔴 <strong><span style="color: #e06c75;">WarZones</span></strong> - Full PvP with no power loss on death. Ideal for arenas and events.</li>
    <li>🗺️ <strong>Visual map indicators</strong> - SafeZones appear <span style="color: #56b6c2;">teal</span>, WarZones appear <span style="color: #c678dd;">purple</span> on all maps</li>
    <li>🔧 <strong>Per-flag customization</strong> - Override any default on a per-zone basis</li>
    <li>🐾 <strong>Mob spawn control</strong> - Integrated with Hytale's native spawn suppression system for reliable mob blocking</li>
    <li>✏️ <strong>Zone creation wizard</strong> - Create zones by claiming single chunks, circular radius, square radius, or using the visual map</li>
</ul>
<p>&nbsp;</p>
<h2><span style="color: #61afef;">💬 Faction &amp; Alliance Chat</span></h2>
<ul>
    <li>🔄 <strong>Toggle mode</strong> - <code>/f c</code> cycles between Public, Faction, and Ally chat</li>
    <li>🎯 <strong>Direct set</strong> - <code>/f c f</code> for faction, <code>/f c a</code> for ally, <code>/f c off</code> for public</li>
    <li>📜 <strong>Chat history GUI</strong> - Browse past faction and ally messages in a dedicated GUI page with tabs</li>
    <li>🎨 <strong>Custom formatting</strong> - Configurable colors and prefixes for each channel</li>
    <li>🔒 <strong>Secure messaging</strong> - Only faction/allied members can see private messages</li>
    <li>💾 <strong>Persistent history</strong> - Chat messages saved to disk, viewable even after restart</li>
</ul>
<p>&nbsp;</p>
<h2><span style="color: #d19a66;">📢 Server-Wide Announcements</span></h2>
<p>Major faction events are broadcast to all online players with configurable toggles:</p>
<ul>
    <li>🏗️ Faction created / disbanded</li>
    <li>👑 Leadership transferred</li>
    <li>⚔️ Territory overclaimed</li>
    <li>🔥 War declared</li>
    <li>🤝 Alliance formed / broken</li>
</ul>
<p>Each event type can be individually enabled or disabled in <code>announcements.json</code>.</p>
<p>&nbsp;</p>
<h2><span style="color: #c678dd;">🖥️ Full GUI System</span></h2>
<p>HyperFactions features <strong><span style="color: #f0b232;">65+ interactive GUI pages</span></strong> covering every aspect of gameplay:</p>
<h3>🎮 Player GUI (<code>/f</code>)</h3>
<ul>
    <li>📊 <strong>Dashboard</strong> - Power, claims, members, relations, status, and invites at a glance</li>
    <li>🗺️ <strong>Territory Map</strong> - Interactive chunk map with click-to-claim and visual legend</li>
    <li>👥 <strong>Members</strong> - Expandable member list with promote, demote, kick, and transfer actions</li>
    <li>🤝 <strong>Relations</strong> - Browse factions and manage diplomacy with ally/enemy/neutral buttons</li>
    <li>⚙️ <strong>Settings</strong> - Two-column settings page with faction details, territory permissions, mob spawning controls, and appearance editing</li>
    <li>💬 <strong>Chat History</strong> - Faction and ally chat logs with tab switching</li>
    <li>✉️ <strong>Invites</strong> - Manage sent invitations and incoming join requests</li>
    <li>📋 <strong>Logs</strong> - View faction activity history</li>
    <li>💰 <strong>Treasury</strong> - Manage faction funds with deposits, withdrawals, transfers, and transaction history</li>
    <li>👤 <strong>Player Info</strong> - View any player's faction membership, power stats, combat record, and history</li>
    <li>❓ <strong>Help</strong> - Guide-first Help Center with 7 categories, sidebar navigation, and verified command reference</li>
</ul>
<h3>🆕 New Player GUI</h3>
<ul>
    <li>🔍 <strong>Faction Browser</strong> - Search, sort, and view all server factions</li>
    <li>✨ <strong>Create Faction Wizard</strong> - Single-page creation with preview, color picker, and permission defaults</li>
    <li>🗺️ <strong>World Map</strong> - See claimed territory before joining a faction</li>
</ul>
<h3>🔐 Admin GUI (<code>/f admin</code>)</h3>
<ul>
    <li>📊 <strong>Dashboard</strong> - Server statistics overview</li>
    <li>🏰 <strong>Faction Management</strong> - Browse, edit, and delete any faction</li>
    <li>🏟️ <strong>Zone Management</strong> - Create, configure, and map SafeZones and WarZones</li>
    <li>⚙️ <strong>Configuration</strong> - Runtime settings adjustment</li>
    <li>👥 <strong>Players</strong> - Browse all players with search, sort, power stats, and quick actions</li>
    <li>💰 <strong>Economy</strong> - Server economy overview, per-faction treasury adjustment, sortable faction balance list</li>
    <li>⚡ <strong>Power Management</strong> - Set, adjust, reset player power with bypass toggles and bulk operations</li>
    <li>📋 <strong>Activity Log</strong> - Server-wide faction activity browser with type, player, and time filters</li>
    <li>ℹ️ <strong>Version Info</strong> - Mod version, server version, and integration status for all 12 supported mods</li>
    <li>⚡ <strong>Actions</strong> - Global quick actions (K/D reset, bulk operations)</li>
    <li>🏟️ <strong>Zone Properties</strong> - Consolidated zone name, type, and notification editing</li>
    <li>💾 <strong>Backups</strong> - Backup management and restore</li>
    <li>🔄 <strong>Updates</strong> - Check and install updates from within the game</li>
</ul>
<h3>🧠 Smart GUI Behavior</h3>
<ul>
    <li><strong>Permission-based filtering</strong> - Buttons and nav tabs automatically hide when the player lacks permission</li>
    <li><strong>Real-time updates</strong> - All open GUIs refresh instantly when data changes</li>
    <li><strong>Role-based visibility</strong> - Officers and leaders see management options; members see read-only views</li>
</ul>
<p>&nbsp;</p>
<h2><span style="color: #56b6c2;">🔧 Admin Tools</span></h2>
<ul>
    <li>🖥️ <strong>Full admin GUI</strong> with dedicated navigation and management pages</li>
    <li>👁️ <strong>Bypass mode</strong> - Toggle admin bypass to modify any territory</li>
    <li>💾 <strong>Automatic backups</strong> - Configurable backup schedule with retention rotation</li>
    <li>🛡️ <strong>Pre-update backups</strong> - Data automatically backed up before installing updates</li>
    <li>⏪ <strong>Rollback support</strong> - <code>/f admin rollback</code> reverts to the previous version before restart</li>
    <li>🐛 <strong>Debug system</strong> - Toggle 7+ debug categories individually for targeted troubleshooting</li>
    <li>⏳ <strong>Claim decay management</strong> - Monitor and manually trigger inactive faction cleanup</li>
    <li>📦 <strong>Data import</strong> - Migrate from ElbaphFactions or HyFactions with validation reports</li>
    <li>⚡ <strong>Power management</strong> - Per-player power set, adjust, reset, bypass toggles, and bulk faction operations</li>
    <li>💰 <strong>Economy management</strong> - Server-wide treasury overview, per-faction balance adjustment</li>
    <li>👥 <strong>Player browser</strong> - Search and manage all server players with sort and quick actions</li>
    <li>🔃 <strong>Config hot-reload</strong> - <code>/f admin reload</code> reloads all configuration without restart</li>
    <li>🔒 <strong>Persistent admin bypass</strong> - Admin bypass state survives server restarts</li>
    <li>ℹ️ <strong>Version info</strong> - <code>/f admin version</code> to check mod version and integration status</li>
</ul>
<p>&nbsp;</p>
<h2><span style="color: #98c379;">📊 PlaceholderAPI Support</span></h2>
<p>HyperFactions provides <strong><span style="color: #f0b232;">49 placeholders</span></strong> for both PlaceholderAPI (PAPI) and WiFlow PlaceholderAPI, covering:</p>
<ul>
    <li>🏰 Faction info (name, tag, description, color, member count)</li>
    <li>👤 Player role and status (rank, is_owner, is_officer, has_faction)</li>
    <li>⚡ Power data (player power, max power, faction power, percentage)</li>
    <li>🗺️ Territory data (claims, max claims, territory owner, territory type)</li>
    <li>🏠 Home coordinates and status</li>
    <li>🤝 Relation counts and config values</li>
</ul>
<p>Use with any scoreboard, hologram, or menu plugin that supports PAPI or WiFlow.</p>
<p>&nbsp;</p>
<h2><span style="color: #61afef;">🔌 Integrations</span></h2>
<p><span style="color: #61afef;">⭐&nbsp;<span style="color: #b96ad9;">= Recommended Mod by HyperSystems Team</span></span></p>
<h3>🔑 Permission Systems</h3>
<p>HyperFactions supports multiple permission providers with automatic detection:</p>
<ul>
    <li>⭐ <strong><a href="https://www.curseforge.com/hytale/mods/hyperperms" rel="nofollow">HyperPerms</a></strong> - Full integration with faction chat prefixes, rank display, and contextual permissions <span style="color: #98c379;">(Recommended)</span></li>
    <li><strong><a href="https://www.curseforge.com/hytale/mods/luckperms" rel="nofollow">LuckPerms</a></strong> - Granular permission control</li>
    <li>⭐ <strong><a href="https://www.curseforge.com/hytale/mods/vaultunlocked" rel="nofollow">VaultUnlocked</a></strong> - Chat, economy, and permission compatibility</li>
    <li><strong>No permission mod</strong> - Works without any permission plugin (configurable allow/deny default)</li>
</ul>
<h3>🛡️ Protection Extensions</h3>
<ul>
    <li>⭐ <strong><a href="https://www.curseforge.com/hytale/mods/hyxin" rel="nofollow">Hyxin</a></strong> + <strong><a href="https://www.curseforge.com/hytale/bootstrap/hyperprotect-mixin" rel="nofollow">HyperProtect-Mixin</a></strong> - <span style="color: #98c379;">Recommended</span> &mdash; 20 protection hooks including F-key pickup, keep inventory, explosion/fire protection, block placement, transport control, entity damage, and more</li>
    <li><strong><a href="https://www.curseforge.com/hytale/mods/hyxin" rel="nofollow">Hyxin</a></strong> + <strong><a href="https://www.curseforge.com/hytale/mods/orbisguard-mixins" rel="nofollow">OrbisGuard-Mixins</a></strong> - Alternative &mdash; 11 protection hooks. Both can run simultaneously (HyperFactions auto-detects and routes hooks accordingly)</li>
</ul>
<h3>📊 Placeholder Systems</h3>
<ul>
    <li>⭐ <strong><a href="https://www.curseforge.com/hytale/mods/placeholder-api" rel="nofollow">PlaceholderAPI</a></strong> - 49 placeholders for scoreboards, chat, and menus</li>
    <li><strong><a href="https://www.curseforge.com/hytale/mods/wiflows-placeholderapi" rel="nofollow">WiFlow PlaceholderAPI</a></strong> - 47 placeholders in WiFlow format</li>
</ul>
<h3>📦 Data Migration</h3>
<ul>
    <li><strong>ElbaphFactions</strong> - Full import of factions, members, claims, relations, and zones</li>
    <li><strong>HyFactions</strong> - Full import with validation reporting</li>
</ul>
<h3>🗺️ Region Protection</h3>
<ul>
    <li><strong><a href="https://www.curseforge.com/hytale/mods/orbisguard" rel="nofollow">OrbisGuard</a></strong> - Auto-blocks claims in OG-protected regions, renders OG regions on world map and territory GUI with colored overlays</li>
</ul>
<h3>🤝 Direct Mod Integrations</h3>
<ul>
    <li>⭐ <strong><a href="https://www.curseforge.com/hytale/mods/hybounty" rel="nofollow">HyBounty</a></strong> &mdash; Place bounties on other players with faction-aware protections against abuse</li>
    <li>🪦 <strong><a href="https://www.curseforge.com/hytale/mods/gravestones" rel="nofollow">Gravestones</a></strong> &mdash; Faction-aware gravestone protection with per-zone access control, configurable ally/member access, and death location announcements</li>
    <li>💰 <strong><a href="https://www.curseforge.com/hytale/mods/ecotale" rel="nofollow">Ecotale</a></strong> &mdash; Faction treasury system with deposits, withdrawals, inter-faction transfers, and admin economy tools via VaultUnlocked bridge</li>
</ul>
<h3>🔮 Upcoming Integrations</h3>
<ul>
    <li>📈 <strong><a href="https://www.curseforge.com/hytale/mods/rpg-leveling-and-stats" rel="nofollow">RPG Leveling</a></strong> - Faction bonuses and level-based perks for faction members <span style="color: #e5c07b;">(Planned)</span></li>
    <li>🗣️ <strong><a href="https://www.curseforge.com/hytale/mods/npc-dialog" rel="nofollow">NPC Dialog</a></strong> - Faction NPCs and dialog interactions in claimed territory <span style="color: #e5c07b;">(Planned)</span></li>
    <li>📝 <strong><a href="https://www.curseforge.com/hytale/mods/npc-dialog-npc-quests-maker" rel="nofollow">NPC Quests Maker</a></strong> - Faction quests and mission systems <span style="color: #e5c07b;">(Planned)</span></li>
    <li>📋 <strong><a href="https://www.curseforge.com/hytale/mods/better-scoreboard" rel="nofollow">BetterScoreBoard</a></strong> - Faction data on the scoreboard HUD <span style="color: #abb2bf;">(Waiting on BetterScoreBoard to support PlaceholderAPI or WiFlow)</span></li>
</ul>
<p>💡 <strong>Want HyperFactions to integrate with your plugin?</strong> Reach out to <strong>DMehaffy</strong> on <a href="https://discord.com/invite/aZaa5vcFYh" rel="nofollow">Discord</a> to discuss integration opportunities.</p>
<p>&nbsp;</p>
<h2><span style="color: #5b8def;">📥 Installation</span></h2>
<h3>Basic Install</h3>
<ol>
    <li>Drop <code>HyperFactions.jar</code> into your <code>mods/</code> folder</li>
    <li>Start your server</li>
    <li>Type <code>/f</code> to open the GUI</li>
</ol>
<h3>&nbsp;</h3>
<h3>For Full Protection (Recommended)</h3>
<ol>
    <li>Create an <code>earlyplugins/</code> folder in your server directory</li>
    <li>Place <a href="https://www.curseforge.com/hytale/mods/hyxin" rel="nofollow">Hyxin</a> and <a href="https://www.curseforge.com/hytale/bootstrap/hyperprotect-mixin" rel="nofollow">HyperProtect-Mixin</a> JARs in <code>earlyplugins/</code> (NOT mods/)</li>
    <li>Add the <code>--accept-early-plugins</code> flag to your server start script:</li>
</ol>
<p>&nbsp;</p>
<p><strong>Linux:</strong></p>
<pre>DEFAULT_ARGS="--accept-early-plugins --assets ../Assets.zip --backup --backup-dir backups --backup-frequency 30"</pre>
<p><strong>Windows:</strong></p>
<pre>set DEFAULT_ARGS=--accept-early-plugins --assets ../Assets.zip --backup --backup-dir backups --backup-frequency 30</pre>
<p><span style="color: #e03e2d;"><strong><em>HyperFactions works without a mixin system, but 11 zone flags (explosion, fire, block placement, transport, keep inventory, etc.) require <a href="https://www.curseforge.com/hytale/bootstrap/hyperprotect-mixin" style="color: #e03e2d;" rel="nofollow">HyperProtect-Mixin</a> or <a href="https://www.curseforge.com/hytale/mods/orbisguard-mixins" style="color: #e03e2d;" rel="nofollow">OrbisGuard-Mixins</a>.</em></strong></span></p>
<p><span style="color: #98c379;"><strong>💡 Tip:</strong> HyperFactions can auto-download HyperProtect-Mixin for you! Enable <code>autoDownload</code> in config or run <code>/f admin update mixin</code> in-game.</span></p>
<h3>🚀 Quick Start</h3>
<p><strong>1. Grant permissions</strong> (with <a href="https://www.curseforge.com/hytale/mods/hyperperms" rel="nofollow">HyperPerms</a>):</p>
<pre>/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.*</pre>
<p><strong>2. Start playing:</strong></p>
<ul>
    <li>🎮 Players: <code>/f</code> to open the GUI, or <code>/f create MyFaction</code></li>
    <li>🔐 Admins: <code>/f admin</code> to open the admin panel</li>
</ul>
<p>💡 <strong>No permission mod?</strong> Set <code>"allowWithoutPermissionMod": true</code> in config.json to allow all non-admin features by default.</p>
<p>&nbsp;</p>
<h2><span style="color: #d19a66;">📋 Essential Commands</span></h2>
<table>
    <thead>
    <tr>
        <th>Command</th>
        <th>Description</th>
    </tr>
    </thead>
    <tbody>
    <tr>
        <td><code>/f</code></td>
        <td>Open the faction GUI</td>
    </tr>
    <tr>
        <td><code>/f create &lt;name&gt;</code></td>
        <td>Create a new faction</td>
    </tr>
    <tr>
        <td><code>/f invite &lt;player&gt;</code></td>
        <td>Invite a player to your faction</td>
    </tr>
    <tr>
        <td><code>/f home</code></td>
        <td>Teleport to your faction home</td>
    </tr>
    <tr>
        <td><code>/f c</code></td>
        <td>Toggle faction/ally/public chat</td>
    </tr>
    <tr>
        <td><code>/f ally &lt;faction&gt;</code></td>
        <td>Send an alliance request</td>
    </tr>
    <tr>
        <td><code>/f enemy &lt;faction&gt;</code></td>
        <td>Declare a faction as your enemy</td>
    </tr>
    <tr>
        <td><code>/f overclaim</code></td>
        <td>Capture enemy territory (requires 0 or less power)</td>
    </tr>
    <tr>
        <td><code>/f stuck</code></td>
        <td>Teleport to safety when trapped in enemy territory</td>
    </tr>
    <tr>
        <td><code>/f admin</code></td>
        <td>Open the admin panel</td>
    </tr>
    </tbody>
</table>
<p>&nbsp;</p>
<p>HyperFactions includes&nbsp;<strong><span style="color: #f0b232;">44 commands</span></strong> across 10 categories. See the full list in the <a href="https://www.hypersystems.dev/plugins/hyperfactions/wiki" rel="nofollow">documentation</a> or use <code>/f help</code> in-game.</p>
<p>&nbsp;</p>
<h2><span style="color: #56b6c2;">⚙️ Configuration</span></h2>
<p>HyperFactions uses a modular configuration system with <strong><span style="color: #f0b232;">11 modular config files</span></strong>:</p>
<table>
    <thead>
    <tr>
        <th>Config File</th>
        <th>Purpose</th>
    </tr>
    </thead>
    <tbody>
    <tr>
        <td><code>config/factions.json</code></td>
        <td>Faction gameplay — power, claims, combat, relations, invites, stuck, roles</td>
    </tr>
    <tr>
        <td><code>config/server.json</code></td>
        <td>Server behavior — teleport, autoSave, messages, GUI, permissions, updates</td>
    </tr>
    <tr>
        <td><code>config/chat.json</code></td>
        <td>Chat formatting, prefixes, and channel settings</td>
    </tr>
    <tr>
        <td><code>config/announcements.json</code></td>
        <td>Server-wide announcement and notification toggles</td>
    </tr>
    <tr>
        <td><code>config/worldmap.json</code></td>
        <td>World map display, refresh modes, and performance tuning</td>
    </tr>
    <tr>
        <td><code>config/backup.json</code></td>
        <td>Backup scheduling, retention, and rotation</td>
    </tr>
    <tr>
        <td><code>config/debug.json</code></td>
        <td>Debug categories for targeted troubleshooting</td>
    </tr>
    <tr>
        <td><code>config/economy.json</code></td>
        <td>Economy and faction treasury settings</td>
    </tr>
    <tr>
        <td><code>config/faction-permissions.json</code></td>
        <td>Default territory permissions with server locks</td>
    </tr>
    <tr>
        <td><code>config/worlds.json</code></td>
        <td>Per-world claiming, power loss, and friendly fire overrides</td>
    </tr>
    <tr>
        <td><code>config/gravestones.json</code></td>
        <td>Gravestone integration settings</td>
    </tr>
    </tbody>
</table>
<p>&nbsp;</p>
<p>All settings include sensible defaults. Missing keys are automatically added on startup without overwriting existing values.</p>
<p>&nbsp;</p>
<h2><span style="color: #c678dd;">🧑‍💻 For Developers</span></h2>
<p>Want to build integrations with HyperFactions? We publish to <strong>JitPack</strong> so you can add HyperFactions as a Maven dependency with no authentication required:</p>
<pre>repositories {
    maven { url 'https://jitpack.io' }
}

dependencies {
    compileOnly 'com.github.HyperSystemsDev:HyperFactions:v0.10.0'
}</pre>
<p>See the full <a href="https://github.com/HyperSystemsDev/HyperFactions/blob/main/docs/api.md" rel="nofollow">Developer API Reference</a> on GitHub for API usage, event listeners, economy integration, and more.</p>
<p>&nbsp;</p>
<h2><span style="color: #5b8def;">🧩 The HyperSystems Suite</span></h2>
<table>
    <thead>
    <tr>
        <th>Mod</th>
        <th>Description</th>
    </tr>
    </thead>
    <tbody>
    <tr>
        <td>⭐ <strong><a href="https://www.curseforge.com/hytale/mods/hyperperms">HyperPerms</a></strong></td>
        <td>Advanced permissions management with groups, inheritance, and web editor</td>
    </tr>
    <tr>
        <td>⚔️ <strong><a href="https://www.curseforge.com/hytale/mods/hyperfactions">HyperFactions</a></strong></td>
        <td>Complete faction system with territory, diplomacy, economy, and 65+ GUI pages</td>
    </tr>
    <tr>
        <td>🛡️ <strong><a href="https://www.curseforge.com/hytale/bootstrap/hyperprotect-mixin">HyperProtect-Mixin</a></strong></td>
        <td>Mixin-based protection hooks for HyperFactions zone flags</td>
    </tr>
    <tr>
        <td>💰 <strong><a href="https://www.curseforge.com/hytale/mods/ecotale">Ecotale</a></strong></td>
        <td>Economy system with balance HUD, admin GUI, and VaultUnlocked integration</td>
    </tr>
    <tr>
        <td>💬 <strong><a href="https://www.curseforge.com/hytale/mods/werchat">Werchat</a></strong></td>
        <td>Channel-based chat with private messaging, nicknames, and moderation</td>
    </tr>
    <tr>
        <td>🌐 <strong>HyperBorder</strong></td>
        <td>World border management <span style="color: #e5c07b;">(Coming Soon)</span></td>
    </tr>
    <tr>
        <td>🔧 <strong>HyperEssentials</strong></td>
        <td>Essential server tools — homes, warps, TPA, spawns, and more <span style="color: #e5c07b;">(Coming Soon)</span></td>
    </tr>
    </tbody>
</table>
<p>&nbsp;</p>
<h2>🔗 Links</h2>
<ul>
    <li>🌐 <a href="https://www.hypersystems.dev/" rel="nofollow">HyperSystems Website</a></li>
    <li>📖 <a href="https://www.hypersystems.dev/plugins/hyperfactions/wiki" rel="nofollow">Documentation &amp; Wiki</a></li>
    <li>💻 <a href="https://github.com/HyperSystemsDev/HyperFactions" rel="nofollow">GitHub Repository</a></li>
    <li>🐛 <a href="https://github.com/HyperSystemsDev/HyperFactions/issues" rel="nofollow">Issue Tracker</a></li>
    <li>💬 <a href="https://discord.com/invite/aZaa5vcFYh" rel="nofollow">Discord</a></li>
</ul>
<p>&nbsp;</p>
<p><em>Part of the <a href="https://www.hypersystems.dev/" rel="nofollow">HyperSystems</a> suite &mdash; built for Hytale, open source, and actively maintained. ⚡</em></p>