[Feat] Server-managed factions (RP/lore factions with admin-only creation)

[derrickmehaffy]

Scope

1. Add a Server Faction mode where only admins can create special factions designed for roleplay/lore-driven servers
2. Server factions operate without a traditional player leader — they are admin-managed entities (e.g., "The Coalition", "The Empire", "The Order")
3. Admins can optionally assign a player as the faction leader, but leadership is admin-controlled (not transferable by players)
4. Server factions should support whitelist-only membership — admins control who can join
5. Server factions should support whitelist-only claims — territory that only whitelisted members can interact with
6. Support a hybrid mode where both regular player-created factions and server factions coexist on the same server
7. Optionally support a server-only mode where player faction creation is disabled entirely and only server factions exist
8. Server factions should be visually distinguishable in the GUI (icon, badge, or color indicator)
9. Server factions should be exempt from power decay, claim decay, and disbanding mechanics

Implementation Details

1. Faction type flag: Add FactionType enum (PLAYER, SERVER) to the Faction data model

   enum FactionType { PLAYER, SERVER }

2. Config options in config.json:

   {
     "serverFactions": {
       "enabled": true,
       "mode": "hybrid",
       "allowPlayerCreation": true,
       "serverFactionPrefix": "\u00265[\u0026d%s\u00265] ",
       "exemptFromDecay": true,
       "exemptFromPowerLoss": true
     }
   }

   • mode: "hybrid" (both player + server factions), "server-only" (no player creation)
   • allowPlayerCreation: redundant with mode but explicit toggle

3. Admin commands:

   • /f admin faction create <name> --server — create a server faction
   • /f admin faction settype <faction> <player|server> — convert between types
   • /f admin faction setleader <faction> <player|none> — assign/remove leader
   • /f admin faction whitelist <faction> add/remove <player> — manage membership whitelist
   • /f admin faction whitelist <faction> claims on/off — toggle whitelist-only claims

4. Admin GUI: Add server faction controls to the Admin Factions page

   • "Create Server Faction" button in admin dashboard
   • Server faction badge/indicator in faction list
   • Whitelist management sub-page

5. Behavioral differences for server factions:

   • Cannot be disbanded by players (admin only)
   • Leader cannot transfer leadership (admin only)
   • Exempt from power decay and claim decay
   • Optional: exempt from power loss on death
   • Optional: whitelist-only membership (players cannot /f join)
   • Members cannot /f leave if whitelist-only (admin must remove them)

6. Permission nodes:

   • hyperfactions.admin.serverfaction — manage server factions
   • hyperfactions.admin.serverfaction.create — create server factions
   • hyperfactions.admin.serverfaction.whitelist — manage whitelist

Risks and Alternatives

1. Risk: Adding a faction type introduces branching logic throughout the codebase (creation, disbanding, power, decay, leave/kick) — need careful audit of all faction operations
2. Risk: Whitelist-only claims add complexity to the protection system — need to distinguish between "faction territory protection" and "whitelist-only protection"
3. Challenge: Converting between player and server faction types mid-game could cause edge cases (what happens to the current leader, power balance, etc.)
4. Alternative: Instead of a separate faction type, could implement "admin flags" on existing factions (immortal, no-decay, whitelist) — simpler but less cohesive
5. Alternative: Could be a separate plugin (e.g., "HyperGuilds") but that loses the benefit of shared territory/relations/protection systems
6. Challenge: The hybrid mode needs clear visual distinction so players understand which factions are server-managed vs player-created

References and Media

1. Community request from player "NOTHING" (February 12, 2026):

   Only admins can create special server factions (without a predefined leader — only admins can assign the leader).
   For example: The Coalition, The Empire, The Order
   For example, The Empire could be set to whitelist-only.
   Admins would also be able to create claims for these special factions and even set those claims as whitelist-only.
   However, regular players would still be able to create their own normal factions as usual.

2. Similar concept in MMO guild systems where developer-created factions serve as story/lore elements that players can join

3. Minecraft Towny's "nation" system provides a similar admin-managed tier above player guilds

4. Existing admin infrastructure: AdminFactionsPage, AdminSubCommand, admin faction settings

---

• I have checked the existing issues for duplicates.
• I agree to follow this project's Code of Conduct.