[Feat] Exclude BetterLootBox crates from container protection

[derrickmehaffy]

Scope

1. BetterLootBox (v2.6.0, by GilloDaby) places lootbox crates as regular blocks with a `container` state — HyperFactions' `BlockUseProtectionSystem` detects these as CONTAINER interactions and blocks them via the `ContainerUse` faction permission flag
2. BetterLootBox handles interaction via `UseBlockEvent.Post` — but HyperFactions cancels at `UseBlockEvent.Pre`, so the lootbox handler never fires
3. A server admin should be able to whitelist specific block IDs (or block ID patterns) to bypass the container protection check, allowing lootbox crates to work in claimed territory regardless of the ContainerUse flag
4. This should NOT bypass all protection — break/place protection should still apply. Only the "container use" interaction check should be skippable
5. This should be generic enough to work with any mod that uses container-state blocks for non-container purposes (not hardcoded to BetterLootBox)

Implementation Details

How BetterLootBox works (from decompiled v2.6.0 source):

• Lootboxes are defined with a `boxBlockId` (any block type, typically a chest/crate)
• `LootBoxUseSystem` listens on `UseBlockEvent.Post` — checks if the block at that position is a bound lootbox location via `service.getLootboxByLocation(world, pos)`
• Primary interaction (with key in hand) → opens the lootbox
• Secondary/Use interaction → opens preview UI
• `LootBoxBreakSystem` cancels `BreakBlockEvent` for bound lootbox blocks (non-Creative)
• Lootboxes are NOT actual containers — the mod intercepts the use event and opens a custom UI page instead
• The mod uses `InteractionManager.cancelChains()` to prevent the default container UI from opening

The conflict in `BlockUseProtectionSystem` (line 130):

// Block's stateId = "container" → detected as InteractionBlockType.CONTAINER
// → checks ContainerUse faction permission → denies if outsider/ally without permission
// → UseBlockEvent.Pre cancelled → BetterLootBox's Post handler never fires

Existing precedent — gravestone bypass (line 86-95):

if (isGravestoneBlock(blockId)) {
  var gsIntegration = hyperFactions.getProtectionChecker().getGravestoneIntegration();
  if (gsIntegration != null && gsIntegration.isAvailable()) {
    return;  // Let gravestone plugin handle via AccessChecker
  }
}

Suggested approach — configurable block ID whitelist:

Add a new config field in `factions.json` (or `server.json`):

{
  "claims": {
    "containerBypassBlockIds": [
      "Crate_*",
      "LootBox_*"
    ]
  }
}

In `BlockUseProtectionSystem.handle()`, after the gravestone check and before the zone/faction container check:

// Check if this block is whitelisted for container bypass
if (detectedBlockType == InteractionBlockType.CONTAINER
    && isContainerBypassed(blockId)) {
  Logger.debugProtection("Container bypass for whitelisted block %s at (%d,%d,%d)",
    blockId, pos.getX(), pos.getY(), pos.getZ());
  return;  // Allow interaction — let the owning mod handle access control
}

private boolean isContainerBypassed(String blockId) {
  if (blockId == null) return false;
  List<String> bypassList = ConfigManager.get().getContainerBypassBlockIds();
  for (String pattern : bypassList) {
    if (pattern.endsWith("*")) {
      if (blockId.startsWith(pattern.substring(0, pattern.length() - 1))) return true;
    } else {
      if (blockId.equalsIgnoreCase(pattern)) return true;
    }
  }
  return false;
}

Alternative approach — per-zone flag:

Instead of (or in addition to) a global whitelist, add a zone flag like `LOOTBOX_USE` that specifically controls lootbox/crate interactions. However, this couples HyperFactions to a specific mod, so the generic block ID whitelist is preferred.

Suggested permission node:

No new permission node needed — this is a config-level bypass. Admin controls which blocks skip the container check via config.

Risks and Alternatives

1. Risk: Bypassing container protection for whitelisted blocks means those blocks have NO use-interaction protection in claimed territory. If a mod uses the same block ID for both regular containers and lootboxes, all instances would be unprotected.

   • Mitigation: The whitelist is explicit and opt-in. Server admins must deliberately add block IDs. Documentation should warn about this.

2. Risk: Wildcard patterns could accidentally match too many blocks (e.g., `Chest_*` would bypass ALL chests).

   • Mitigation: Use specific patterns and document examples. Could also support exclusion patterns (`!Chest_Regular`).

3. Alternative: Instead of a block ID whitelist, detect BetterLootBox as a soft dependency and check if a block position is a bound lootbox location via reflection/API.

   • Downside: Couples HyperFactions to BetterLootBox specifically. The generic whitelist approach works with any mod.

4. Alternative: BetterLootBox could register an interaction handler at a higher priority — but the Hytale ECS system doesn't guarantee event system ordering between plugins, and `Pre` always fires before `Post`.

5. Challenge: Need to identify the correct block IDs that BetterLootBox uses. These are configured per-lootbox in BetterLootBox's config (`boxBlockId` field) and vary per server setup.

References and Media

1. BetterLootBox mod: https://www.curseforge.com/hytale/mods/better-lootbox-crates

Confirmation Checklist

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