HyperProtect-Mixin

HyperProtect-Mixin - Server-Level Event Interception for Hytale

Intercept. Protect. Extend. HyperProtect-Mixin injects 27 protection hooks into the Hytale server via Hyxin bytecode mixins, exposing them through a lock-free bridge API that any mod can consume — no compile-time dependency required.

Zero configuration. Fail-open safety. Drop it in and your protection mod handles the rest.

Why HyperProtect-Mixin?

• 27 Protection Hooks - Comprehensive coverage across building, combat, items, entities, containers, transport, world map, commands, and logging
• 30 Mixin Interceptors - Multiple injection points per hook for thorough event capture, with consolidated interaction gates covering 26 interaction types
• Lock-Free Bridge - AtomicReferenceArray with zero-contention reads — no ConcurrentHashMap overhead
• Fail-Open Safety - Errors, missing hooks, or negative verdicts always allow actions — never locks players out
• Zero Configuration - Auto-initializes on server startup. No config files needed.
• No Compile-Time Dependency - Consumer mods register hooks via System.getProperties() — works across classloader boundaries

Comparison with OrbisGuard-Mixins

Hook Coverage

Building (8 hooks)

• block_break (slot 0) — Block harvesting and interactive item pickup
• explosion (slot 1) — Explosion block damage
• fire_spread (slot 2) — Fire fluid spreading
• builder_tools (slot 3) — Builder tool paste operations
• block_place (slot 18) — Block placement
• hammer (slot 19) — Hammer block cycling (variant rotation)
• use (slot 20) — Block state changes, farming, capture crates, and NPC interactions
• fluid_spread (slot 25) — Non-fire fluid spreading (water, lava)

Items (3 hooks)

• item_pickup (slot 4) — Proximity and manual item pickup
• death_drop (slot 5) — Keep-inventory-on-death behavior
• durability (slot 6) — Item durability loss prevention

Containers (4 hooks)

• container_access (slot 7) — Crafting/workbench access
• container_open (slot 17) — Storage container opening
• crafting_resource (slot 23) — Crafting resource validation at recipe level
• barter_trade (slot 29) — Barter/trade NPC interaction filtering

Combat (2 hooks)

• entity_damage (slot 16) — Player-initiated damage (PvP and PvE)
• projectile_launch (slot 27) — Projectile launch interception

Entities (4 hooks)

• mob_spawn (slot 8) — NPC/mob spawning (4 interceptors: marker, chunk, NPC, entity load)
• respawn (slot 22) — Player respawn location override (returns coordinates, not verdict)
• prefab_spawn (slot 26) — Prefab entity spawning from save data
• mount (slot 28) — Mount/ride entity interactions

Transport (3 hooks)

• teleporter (slot 9) — Teleporter block use
• portal (slot 10) — All portal and instance interactions (6 interaction types)
• seat (slot 21) — Block seating (chairs, benches)

World Map (1 hook)

• map_marker (slot 24) — Per-player map marker visibility filtering (player markers + shared markers)

Commands & Logging (2 hooks)

• command (slot 11) — Command execution filtering
• interaction_log (slot 12) — Desync log suppression

Architecture

Bridge Design

The bridge is a 30-element AtomicReferenceArray<Object> stored in System.getProperties() under "hyperprotect.bridge". Consumer mods place hook objects at fixed slot indices; interceptors read from those slots at runtime via cached MethodHandle lookups.

Verdict Protocol

Feature Detection

Each interceptor sets a system property on load. Consumer mods can check exactly which hooks are available:

boolean loaded = "true".equals(System.getProperty("hyperprotect.bridge.active"));
boolean hasBlockBreak = "true".equals(System.getProperty("hyperprotect.intercept.block_break"));

For Server Admins

1. Create an earlyplugins/ folder in your server directory
2. Place Hyxin and HyperProtect-Mixin JARs in earlyplugins/ (NOT mods/)
3. Add --accept-early-plugins to your server start script
4. Place your protection mod (e.g., HyperFactions) in mods/

Linux:

DEFAULT_ARGS="--accept-early-plugins --assets ../Assets.zip"

Windows:

set DEFAULT_ARGS=--accept-early-plugins --assets ../Assets.zip

That's it. Zero configuration required. HyperProtect-Mixin auto-initializes and consumer mods register hooks automatically.

For Developers

Register hooks with no compile-time dependency:

@SuppressWarnings("unchecked")
AtomicReferenceArray<Object> bridge = (AtomicReferenceArray<Object>)
    System.getProperties().get("hyperprotect.bridge");

// Register a block break hook at slot 0
bridge.set(0, new Object() {
    public int evaluate(UUID playerUuid, String worldName, int x, int y, int z) {
        if (isProtected(worldName, x, y, z)) return 1; // DENY_WITH_MESSAGE
        return 0; // ALLOW
    }

    public String fetchDenyReason(UUID playerUuid, String worldName, int x, int y, int z) {
        return "&#FF5555You cannot break blocks here!";
    }
});

See the full documentation for all 27 hook signatures and integration patterns.

Integration

• HyperFactions — Primary consumer. Uses all 27 hooks for territory protection, PvP control, keep inventory, spawn blocking, map marker filtering, and more.
• Any mod — The bridge API is open. Any mod can register hooks at any slot to implement custom protection logic.

Requirements

• Hytale Server (Early Access)
• Hyxin (v0.0.11+) — Mixin framework for Hytale
• --accept-early-plugins server flag

Links

• HyperSystems Website
• GitHub Repository
• Documentation
• Issue Tracker
• Discord

Part of the HyperSystems suite — built for Hytale, open source, and actively maintained.