[Feat] Command Blocking in Faction Claims and Admin Zones

[derrickmehaffy]

Scope

1. Server admins should be able to define a list of commands that are blocked (or allowed) within faction-claimed territory, based on the viewer's relationship to the owning faction (e.g., enemies can't use /home, /tpa, or /back in enemy territory)
2. The system should support both a blocklist (default allow, specific commands denied) and an allowlist (default deny, specific commands allowed) mode
3. Command blocking should apply to admin zones (SafeZones/WarZones) as well, configurable per-zone via the existing zone flags system
4. Command blocking should respect bypass permissions (hyperfactions.bypass.commandblock)
5. The feature should be configurable both via the config file and the GUI (TBD on exact GUI placement — see Risks section)
6. Command matching should support both exact commands (/home) and wildcard prefixes (/home * to block all subcommands)

Implementation Details

1. Event Interception: Use PlayerChatEvent (which fires for both chat and commands starting with /) to intercept and cancel blocked commands. Register at EventPriority.HIGH to intercept before command dispatch.

2. Suggested config structure (config.json territory section):

   {
     "commandBlocking": {
       "enabled": true,
       "mode": "BLOCKLIST",
       "territoryRules": {
         "ENEMY": {
           "blockedCommands": ["/home", "/tpa", "/back", "/warp", "/spawn"]
         },
         "NEUTRAL": {
           "blockedCommands": ["/home"]
         },
         "ALLY": {
           "blockedCommands": []
         },
         "OWN": {
           "blockedCommands": []
         },
         "WILDERNESS": {
           "blockedCommands": []
         }
       }
     }
   }

3. Zone flag integration: Add a new zone flag command_blocking (boolean toggle) to ZoneFlags.java under a new "Commands" category. When enabled on a zone, use the zone-specific blocked command list. Zone-level blocked commands would be stored as a List<String> in the Zone record (separate from boolean flags).

4. Suggested API methods:

   • CommandBlockingManager#isCommandBlocked(UUID player, String command, String world, int chunkX, int chunkZ) — main check method
   • CommandBlockingManager#getBlockedCommands(RelationType relation) — get blocked list for a relation
   • ConfigManager#getCommandBlockingConfig() — access config

5. Suggested permission nodes:

   • hyperfactions.bypass.commandblock — bypass all command blocking
   • hyperfactions.admin.commandblock — manage command blocking config via commands/GUI

6. Listener registration (in HyperFactionsPlugin.java):

   eventBus.register(EventPriority.HIGH, PlayerChatEvent.class, event -> {
       String content = event.getContent();
       if (content.startsWith("/")) {
           String command = content.split(" ")[0].toLowerCase();
           // Check player location, territory, relation, then cancel if blocked
           if (commandBlockingManager.isCommandBlocked(player, command, world, chunkX, chunkZ)) {
               event.setCancelled(true);
               // Send denial message
           }
       }
   });

Risks and Alternatives

1. Risk — GUI complexity: Adding per-relation command lists to the GUI is non-trivial. The Faction Settings page is already dense with two columns. Options include:

   • A dedicated "Command Rules" sub-page accessible from Settings
   • A modal dialog triggered from a "Command Blocking" button in Settings
   • An admin-only configuration (no faction leader GUI, only server config + admin GUI)
   • Recommendation: Start with config-file-only + admin GUI, add faction leader GUI later if needed

2. Risk — PlayerChatEvent ordering: Other plugins (chat formatters, etc.) also listen to PlayerChatEvent. Using EventPriority.HIGH ensures we intercept early, but if another plugin cancels the event first at a higher priority, our check won't fire. This is acceptable since cancelled events shouldn't execute commands anyway.

3. Challenge — Command aliases: Players may use command aliases (e.g., /h for /home). The blocklist should document that admins need to include all known aliases. A future enhancement could resolve aliases to canonical command names.

4. Alternative — Per-faction customizable blocklists: Instead of server-wide relation-based rules, allow faction leaders to customize which commands are blocked in their territory. This adds significant complexity but gives factions more control. Could be a Phase 2 enhancement.

5. Challenge — Zone command lists: Boolean flags are simple, but command lists require a different storage approach. The Zone record's flags map (Map<String, Boolean>) would need a parallel Map<String, List<String>> or similar for list-type zone properties.

References and Media

1. Minecraft Factions (FactionsUUID) has a similar feature with territoryDenyCommands and territoryDenyCommandsOnRelation: https://github.com/drtshock/Factions
2. Current HyperFactions zone flags system (ZoneFlags.java) provides the pattern for boolean zone flags — this feature extends the concept to command-level granularity
3. Hytale PlayerChatEvent documentation: commands are dispatched through chat, so intercepting at the chat event level is the correct approach (see HytaleServerDocs/docs/reference/events.md)