PlugBox

Dynamic runtime plugin and mod loader for Minecraft Fabric servers — no restart required.

Overview

PlugBox allows you to load, unload, and reload Fabric mods and custom plugins at runtime without restarting the Minecraft server. It features a built-in Mixin transformation pipeline with automatic compatibility detection, a ghost protection system for blocks, entities, and items, and a full server-side command suite.

Features

• Dynamic Mod Loading — Drop a .jar into plugins/ and load it with /plugbox load <file>.
• Mixin Support — Automatically discovers and registers mixins.json configs from Fabric mods.
• Compatibility Detection — Three-level safety system:
  • FULL — Target classes not yet loaded; standard Mixin transformation.
  • RETRANSFORM — Targets already loaded, but JVM Instrumentation.retransformClasses() can safely apply changes.
  • RESTART_REQUIRED — Structural modifications detected or Instrumentation unavailable; mod is queued for next restart.
• Ghost System — When a mod is unloaded, its blocks, entities, and items are transparently replaced with ghost placeholders and fully restored on reload.
• Hot Reload — /plugbox reload <id> and /plugbox reloadall for rapid development.
• File Watcher — Optional directory monitoring for automatic unload on file deletion.
• Client GUI — In-game plugin manager accessible from the Options screen.
• Network Sync — Connected players receive plugin-list updates and reconnection notifications.

Architecture

     Plugin JAR
         │
         ▼
┌─────────────────┐
│  Mod Discovery  │  ← fabric.mod.json + MANIFEST.MF parsing
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Mixin Discovery│  ← .mixins.json discovery + @Mixin target extraction (ASM)
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Compatibility  │  ← TargetIndex + loaded-class check
│    Checker      │
└────────┬────────┘
         │
    ┌────┴────┐
    │         │
  Early     Late
    │         │
    ▼         ▼
  Mixin     Instrumentation
  Pipeline   + Retransform
    │         │
    └────┬────┘
         ▼
    ┌──────────┐
    │ Activate │  ← onLoad → onEnable
    └──────────┘

Key Components

Component	Responsibility
InstrumentationAgent	Acquires java.lang.instrument.Instrumentation via premain or dynamic attach
LateMixinTransformer	ClassFileTransformer that delegates retransform calls to the internal Mixin engine
MixinConfigDiscovery	Parses fabric.mod.json and .mixins.json; extracts @Mixin targets via ASM
TargetIndex	Maps mixin configs → target classes for fast lookup
TransformationManager	Orchestrates early/late transformation and compatibility reporting
FabricClassPathInjector	Injects mod JARs into the Fabric/Knot classpath so Mixin can resolve classes
GhostBlockRegistry / GhostEntityRegistry / GhostItemRegistry	Serializes, ghostifies, and resurrects mod content

Requirements

• Minecraft 1.21.4
• Fabric Loader >= 0.16.0
• Fabric API any version
• Java >= 21

Note: For RETRANSFORM (late Mixin) support, the server must be started with the PlugBox agent:

java -javaagent:plugbox.jar -jar fabric-server-launch.jar

If the agent is not attached, mods targeting already-loaded classes will be marked RESTART_REQUIRED instead of crashing.

Installation

1. Build the mod with Gradle:

   ./gradlew build

2. Copy build/libs/plugbox-1.2.6.jar into your server's mods/ folder.
3. (Optional but recommended) Start the server with the agent flag for late-transformation support:

   java -javaagent:mods/plugbox-1.2.6.jar -jar fabric-server-launch.jar

4. The plugins/ directory will be created automatically on first run.

Commands

All commands require permission level 2 (OP).

Command	Description
/plugbox list	List loaded plugins with status
/plugbox load <file.jar>	Load a plugin from the plugins/ directory
/plugbox unload <id>	Unload a plugin (ghostifies its content)
/plugbox reload <id>	Reload a single plugin
/plugbox reloadall	Reload all active plugins
/plugbox info <id>	Show detailed plugin metadata
/plugbox install <path>	Copy a JAR into plugins/ and load it

Plugin API

Plugins can implement the com.example.plugbox.api.Plugin interface or ship a standard fabric.mod.json — PlugBox adapts Fabric mods automatically.

public interface Plugin {
    String getId();
    String getName();
    String getVersion();
    String[] getAuthors();
    default String getDescription() { return ""; }

    void onLoad(PluginContext context);
    void onEnable(MinecraftServer server);
    void onDisable(MinecraftServer server);
    void onUnload();

    default void onPlayerJoin(ServerPlayerEntity player) {}
    default void onPlayerLeave(ServerPlayerEntity player) {}
}

Provided Context

Each plugin receives a PluginContext with:

• DynamicCommandRegistry — Register Brigadier commands at runtime
• DynamicEventBus — Subscribe to Fabric events
• DynamicScheduler — Tick-based task scheduler
• PluginConfig — Per-plugin JSON configuration

Ghost System

When a mod is unloaded, PlugBox preserves its world state:

• Blocks → Replaced with indestructible Ghost Blocks; restored when the mod reloads.
• Entities → Serialized and removed; respawned on reload.
• Items → Replaced with Ghost Items in inventories and dropped items; restored on reload.

Ghost data is persisted in chunk NBT (PlugBoxBlockGhosts, PlugBoxEntityGhosts) and survives server restarts.

Configuration

Global config is stored at plugbox.json in the server root:

{
  "activePlugins": ["MyPlugin.jar", "AnotherMod.jar"]
}

Active plugins are auto-loaded on server start.

Safety & Limitations

• No bytecode rollback on unload. Disabling a plugin stops its lifecycle but does not revert JVM classes. The ghost system compensates by hiding mod content.
• Late Mixin requires the agent. Without -javaagent, structural changes to already-loaded Minecraft classes cannot be applied dynamically.
• Registry freeze. Mods that register blocks, items, or entities during onInitialize() still require a full JVM restart because Minecraft registries are immutable after startup. PlugBox detects this and warns accordingly.