Why I Built NilLoaderSDK — A Classic "Scratch Your Own Itch" Story
Why I Built NilLoaderSDK — A Classic “Scratch Your Own Itch” Story
A utility SDK for NilLoader-based Minecraft mods, born out of frustration and necessity.
The Problem With NilLoader (And Why That’s Also Its Superpower)
If you’ve ever worked with NilLoader, you already know what makes it special: it’s version-agnostic. It doesn’t tie itself to any specific version of Minecraft. As a Java agent, it simply injects your code into the game’s runtime — no strings attached.
That flexibility is genuinely powerful. But it comes with a cost.
Because NilLoader doesn’t bind to any particular Minecraft version, there’s no abstraction layer waiting for you. No event system. No registry helpers. Nothing pre-built the way Forge or Fabric hand things to you. You’re writing directly against Minecraft’s internals — and that means you’d better have a solid grasp of Java fundamentals, bytecode, and reflection before you even get started.
For seasoned modders, that’s fine. For anyone newer to the space, it’s a steep cliff.
That’s exactly why I built NilLoaderSDK.
What NilLoaderSDK Actually Is
NilLoaderSDK isn’t trying to be a new mod loader. It’s not competing with Forge or Fabric. It’s a small utility layer that sits on top of NilLoader and smooths out the rough edges — most of which I ran into myself while working on NilLoader-based projects.
Here’s what it bundles:
Reflection Helpers — Working with private fields and methods in Minecraft’s obfuscated codebase is tedious. ReflectHelper wraps the boilerplate so you’re not writing the same try-catch reflection blocks over and over. ProxyHelper extends this for dynamic proxy use cases.
Structured Logging — A consistent logging standard built around NilLoader’s NilLogger. There’s a root SDK logger (NilLoaderSDK) and a class-scoped variant (NilLoaderSDK/<ClassName>). Small thing, but it keeps logs readable across a whole project.
Entrypoint Dispatcher — NilLoader has premain and hijack phases, and coordinating those across a larger project gets messy fast. EntrypointDispatcher resolves entrypoints in a defined order — JVM properties first, then a properties file, then ServiceLoader — with built-in recursion guards so you don’t accidentally send the loader into an infinite loop.
Java NIO Networking — A full non-blocking networking layer: NioServer, NioClient, PacketCodec, PacketRegistry, and a MinecraftAutoNetworkBridge that can be wired up purely through JVM properties. Useful for mods that need to talk to external services or other game instances.
Utilities — CooldownTracker for rate-limiting logic and TargetFinder for locating entities or objects in the world.
Most of these features exist because I needed them. That’s the honest origin story.
The Elephant in the Room: Mappings
If you’re modding old Minecraft — pre-1.7 especially — one of the biggest headaches is mappings. Modern toolchains make this almost invisible: configure Gradle, pick a mapping set, done. Back then, it was a whole ordeal.
The historical go-to was Mod Coder Pack (MCP), which handled remapping Notch’s obfuscated names to human-readable Searge mappings all the way back to Minecraft Alpha 1.1.2_01. But MCP is largely inaccessible today. The tooling has fragmented, mirrors are gone, and finding the original sources is genuinely difficult.
NilLoaderSDK includes a SimpleRemap utility — but I want to be clear about what it doesn’t do. It doesn’t ship bundled mappings, and it won’t. The reason is simple: licensing. I couldn’t reliably trace the license terms for existing mapping files, even when digging through documentation and original sources. Without clear licensing, I can’t ship them — and I’m not willing to guess.
So the approach here is intentional: developers bring their own mappings locally. You wire them into your project yourself. It’s one more manual step, but it keeps everything legally clean and gives you full control over what you’re working with.
Who Is This For?
Realistically, NilLoaderSDK isn’t going to change the Minecraft modding ecosystem. It’s a niche tool for a niche loader used by a small community of modders who prefer working close to the metal.
But if you’re in that space — if you’re building NilLoader mods and finding yourself rewriting the same reflection utilities or struggling to wire up consistent logging — this SDK might save you some time.
It’s a small thing. But small things add up.
Getting Started
Add the SDK to your project via Maven:
repositories {
maven { url = uri("https://repo.tamkungz.me") }
}
dependencies {
implementation("me.tamkungz.nilloadersdk:nilloadersdk:2.0.1")
}
The source is available on GitHub, licensed under LGPL-3.0-or-later.
- GitHub: TamKungZ/NilLoaderSDK
- Maven Repository: repo.tamkungz.me
- NilLoader upstream: git.sleeping.town/Nil/NilLoader
Built by TamKungZ_ — mostly because I needed it.