[Feat] Faction Vaults — restricted high-security territory chunks #35

Scope

1. Add Faction Vaults — specially designated chunks within a faction's claimed territory that have restricted access controls
2. Only the faction leader can access vault chunks by default (break, place, interact, open containers)
3. Leaders can optionally grant officers vault access via a faction permission toggle
4. Regular faction members, allies, and outsiders are fully blocked from interacting with vault chunks
5. Vault chunks should be visually distinguishable on the GUI territory map (unique color/icon)
6. Vault chunks have territorial overclaim protection — they can only be overclaimed if the attacker has a connected overclaim path from wilderness to the vault chunk's border (no skipping over defended territory)
7. Vault chunks must already be claimed faction territory before being designated as a vault
8. Configurable limit on how many vault chunks a faction can have (e.g., based on faction size or permission node)

Implementation Details

1. Data model: Add vault designation to the claim system

   // In Faction or ClaimManager data
   Set<ChunkKey> vaultChunks; // subset of claimed chunks marked as vault

2. Commands:

   • /f vault — toggle vault designation on the chunk you're standing in (must be own claimed territory)
   • /f vault list — list all vault chunks with coordinates
   • /f vault info — show vault status of current chunk
   • /f admin vault <faction> add/remove <x> <z> — admin vault management
   • /f admin vault <faction> list — admin view of faction's vaults
   • /f admin vault <faction> clear — remove all vault designations

3. Faction permission toggle (in faction settings):

   • officerVaultAccess (default: false) — when enabled, officers can access vault chunks alongside the leader
   • Configurable in the Faction Settings GUI under a "Vault" or "Security" section

4. Protection integration: Modify ProtectionChecker to add vault-aware access checks

   • When a chunk is a vault chunk, override normal faction territory permissions:
     • Leader: always allowed
     • Officers: allowed only if officerVaultAccess is enabled
     • Members: denied (with vault-specific denial message)
     • Allies/outsiders: denied (normal territory denial)
   • Applies to: block break, block place, block interact, container access, fluid placement/pickup
   • Admin bypass still works (hyperfactions.bypass.*)

5. Overclaim protection: Vault chunks use territorial adjacency for overclaim eligibility

   • A vault chunk can only be overclaimed if the attacking faction has already overclaimed (or the chunk is unclaimed) at least one directly adjacent chunk (N/S/E/W)
   • This means attackers must push a connected overclaim path from wilderness through the faction's outer territory to reach the vault — they can't just cherry-pick the vault chunk from anywhere
   • Non-vault chunks follow normal overclaim rules (unchanged)
   • This makes vaults harder to reach but not impossible — a determined attacker who pushes through the territory can still breach the vault
   • Vault status is removed when a chunk is overclaimed

6. GUI integration:

   • Territory map: vault chunks shown with a distinct color (e.g., gold/amber) or overlay pattern
   • Faction Settings: "Vault" section with officer access toggle and vault count display
   • Dashboard: vault count shown alongside claims count (e.g., "Claims: 12 (3 vaults)")
   • Admin faction detail: vault chunk list with remove buttons

7. Config in config.json:

   {
     "vaults": {
       "enabled": true,
       "maxVaultsPerFaction": 3,
       "maxVaultsPermissionScaling": true,
       "requireAdjacentOverclaim": true,
       "defaultOfficerAccess": false
     }
   }

8. Permission nodes:

   • hyperfactions.vault.designate — designate/undesignate vault chunks
   • hyperfactions.vault.list — view vault chunk list
   • hyperfactions.vault.limit.<n> — override max vault count (e.g., vault.limit.5 for VIP)
   • hyperfactions.admin.vault — admin vault management
   • hyperfactions.bypass.vault — bypass vault access restrictions

9. Denial messages:

   • Members: "This is a faction vault. Only the leader can access this area."
   • Members (with officer access on): "This is a faction vault. Only officers and the leader can access this area."
   • Overclaim attempt without adjacency: "This vault chunk can only be overclaimed from adjacent territory. Push through the faction's borders first."

Risks and Alternatives

1. Risk: Adding a vault layer to the protection checker increases complexity in an already multi-layered system (zones → faction territory → vault) — needs careful ordering so vault checks don't conflict with zone overrides or admin bypass
2. Challenge: Vault chunks that become unclaimed (faction loses power) need to have their vault status cleaned up properly
3. Challenge: If a leader goes inactive, vault contents become inaccessible to the rest of the faction — consider adding a "vault lockout timer" where officers gain access after the leader is offline for N days
4. Challenge: The adjacency check for overclaim needs to handle edge cases — what if the vault is on the faction's border already (adjacent to wilderness)? It should be overclaimable normally in that case since there's nothing to push through
5. Alternative: Instead of chunk-based vaults, could implement container-level locking (lock individual chests/storage) — more granular but much more complex to implement and track
6. Alternative: Could use the existing zone flag system with a new "vault" flag on specific chunks rather than a separate vault concept — simpler but less intuitive for players
7. Alternative: Could tie vault count to faction power level instead of a flat config cap — rewards stronger factions with more secure storage

References and Media

1. Similar concept in Factions plugins: "faction vaults" typically refer to shared storage GUIs, but this proposal is territory-based protection which is more aligned with real fortress/keep mechanics
2. Existing protection infrastructure: ProtectionChecker.canInteract(), ClaimManager, FactionPermissions
3. Existing territory map rendering: FactionMapPage, WorldMapOverlayProvider — vault chunks need a new color entry
4. Existing faction permissions model: FactionPermissions with boolean toggles — officerVaultAccess follows the same pattern
5. Overclaim logic: ClaimManager.overclaim() — adjacency check is a simple N/S/E/W neighbor lookup on ChunkKey

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