Skip to content

About

Hot-swap engine for Fabric mods. Load, unload, and update jars at runtime - no JVM restart.

Topics

Resources

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

Muto Runtime Logo

Muto Runtime

Runtime bytecode retransformation, classloader mutation, and live mod lifecycle engine for Fabric.

Minecraft Platform Version Java License

Documentation · Modrinth · Issues


Overview

Muto Runtime (me.fy2ne.muto) is a client-side developer engine library providing JVM-level hot-swap primitives for Fabric mods — allowing modules to be injected, toggled, unloaded, and updated at runtime without restarting the JVM.

It combines four coordinated runtime subsystems:

  1. Dynamic JVMTI Instrumentation & Live Mixin Retransformation (MutoAgentBootstrap, MutoClassFileTransformer, DynamicMixinEngine) — self-attaches a Java Instrumentation agent (Can-Retransform-Classes) to weave and unweave mixin bytecode directly inside already-loaded classes via Instrumentation.retransformClasses().
  2. Knot ClassLoader Topology & OS Handle Severance (KnotInjector, JarUnlocker) — injects jar/JiJ paths into Fabric's KnotClassLoader delegate and closes internal URLClassPath, ZipFileSystem, and JarFileFactory locks via Unsafe field-offset release.
  3. Registry Invariant Thawing & Namespace Isolation (RegistryFreezer, DiContainerGuard) — clears MappedRegistry freeze flags around isolated per-entrypoint lifecycles, prunes invalidated namespaces on teardown, and guarantees refreezing in finally invariants.
  4. Transactional Rollback & Render-Safe Remounting (ReloadEngine, ResourceHotMount, ReloadBoundaryManager) — snapshots directory hashes via SHA-256, rolls back failed swaps automatically, and guards shader/pack reloads against active overlay locks.

Integration (For Mod Developers)

Declare Muto Runtime as a compile-only soft dependency (modCompileOnly) and guard calls behind FabricLoader.getInstance().isModLoaded("muto").

Gradle

repositories {
    mavenLocal()
    maven {
        name = "Modrinth"
        url = "https://api.modrinth.com/maven"
    }
    maven {
        name = "GitHubPackages"
        url = uri("https://maven.pkg.github.com/fy2ne/Muto_runtime")
    }
}

dependencies {
    modCompileOnly "maven.modrinth:muto:0.1.0-beta+26.x"
}

Trigger a Reload

import net.fabricmc.loader.api.FabricLoader;
import me.fy2ne.muto.api.MutoApi;

public class DownloaderIntegration {
    public static void onModDownloaded(java.nio.file.Path jar) {
        if (!FabricLoader.getInstance().isModLoaded("muto")) return;

        if (MutoApi.isSafeToReload()) {
            MutoApi.reloadAsync(stage -> System.out.println(stage))
                .thenAccept(result -> {
                    if (result.success()) {
                        System.out.println("hot-swapped in " + result.durationMs() + "ms");
                    } else {
                        System.err.println("swap failed: " + result.error());
                    }
                });
        }
    }
}

Hook Lifecycle Events

import me.fy2ne.muto.api.MutoEvents;

MutoEvents.RELOAD_START.register((startMs, diff) -> {
    // close stale network connections, clear texture caches
});

MutoEvents.RELOAD_FINISH.register((endMs, diff, success, durationMs, error) -> {
    // refresh UI, re-bind resources, update lists
});

API Surface

Method Returns Notes
MutoApi.isAvailable() boolean Runtime engine initialized
MutoApi.isReloading() boolean Reload transaction currently active
MutoApi.isSafeToReload() boolean Title/boundary state, no active world
MutoApi.plan() ReloadPlan Non-mutating /mods SHA-256 diff
MutoApi.reloadAsync() CompletableFuture<ReloadResult> Asynchronous hot-swap execution
MutoApi.reloadAsync(notifier) CompletableFuture<ReloadResult> Asynchronous reload with stage callbacks
MutoApi.reloadWithBoundary(screen) void Safe world/server exit, swap, and reconnect
MutoApi.getHistory() List<ReloadHistoryEntry> Audited transaction history
MutoApi.getReloadableModIds() Set<String> Dynamic mods in active snapshot
MutoApi.getStubbornModIds() Set<String> Protected core mods requiring JVM restart

Building & Testing

./gradlew build
./gradlew test
./gradlew publishToMavenLocal
  • Target: Minecraft >=26.1 <27.0 (26.3), Fabric Loader >=0.16.0, Fabric API >=0.144.1, Java 25+ (client environment).
  • License: LGPL-3.0-only — see LICENSE.

About

Hot-swap engine for Fabric mods. Load, unload, and update jars at runtime - no JVM restart.

Topics

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages