SourbyMods

SourbyMods is the first-party native mod loader for mods/*.jar. It is intentionally small: no dependency graph, no cross-mod classpath, and no claim of Fabric or Forge compatibility. It exists so server-side extensions can load early, reach NMS and Bukkit when appropriate, and participate in the runtime lifecycle.

What ML1 is

Descriptor

A mod jar contains sourbymod.yml at its root. The loader reads it with SnakeYAML’s safe constructor, so YAML gadget tags are blocked.

id: example-mod
name: Example Mod
version: 1.0.0
main: com.example.ExampleMod
api: 1

Lifecycle

onLoad runs at bootstrap, before world load and before Bukkit plugins enable. The SourbyCraft config, knobs, class initialization, andctx.registerModule(...) are safe here. Bukkit APIs, worlds, schedulers, and direct registry mutation are not.

onEnable runs when SourbyCraft’s plugin enables. Bukkit is fully available.onDisable runs in reverse order during module shutdown. A same-classloader reload re-enrolls modules; onLoad remains one-time, whileonEnable/onDisable fire once per reload cycle.

package com.example;

import dev.iyanz.sourbycraft.mod.ModContext;
import dev.iyanz.sourbycraft.mod.SourbyMod;

public class ExampleMod implements SourbyMod {
    @Override
    public void onLoad(ModContext ctx) {
        ctx.logger().info("loading " + ctx.modId());
    }

    @Override
    public void onEnable() {
        // Bukkit API is available here.
    }

    @Override
    public void onDisable() {
        // Reverse-order shutdown.
    }
}

ModContext

• modId() — the id from the descriptor.
• version() — the declared mod version.
• dataDirectory() — mods/<id>/, created lazily.
• logger() — a logger prefixed SourbyMod/<id>.
• registerModule(SourbyModule) — enroll a module into the runtime registry; use this instead of a direct add from onLoad.

Classloading

Each mod gets its own URLClassLoader with the server classloader as parent. A mod can see NMS, Bukkit/Paper, and all SourbyCraft first-party APIs. ML1 has no dependency graph: mod A cannot declare a dependency on mod B. If two mods share code, ship it in both jars or expose it through a Bukkit service.

Loader behavior

• Duplicate id: the second jar is skipped with a warning.
• api newer than the loader knows: skipped with a warning.
• onLoad throws: that mod is disabled; the server and other mods continue.
• Missing main class or wrong interface: skipped with a warning.
• No sourbymod.yml (Fabric, Forge, random jar): skipped with a warning.
• Zero mods: one informational line, no scanning beyond a directory listing.

Security

A SourbyMod is arbitrary code running in-process with full server privileges, the same trust level as a plugin. The loader adds no sandbox; an in-JVM sandbox is not a credible boundary. Deploy only mods from sources you trust.