Metadata

KDL is the recommended human-facing metadata format today, but it is replaceable. integrations/kdl turns nows.mod.kdl into the generic ModDescriptor model owned by core.

Nows looks for this file at the root of the mod jar:

nows.mod.kdl

The KDL reader requires a root mod node. id and version are required. name falls back to the id, minecraft falls back to *, and side falls back to both.

mod id="my_mod" name="My Mod" version="1.0.0" minecraft="26.2" side="client" {
    info {
        description "Short description shown to tools and companion UI."
        author "YourName"
        license "Apache-2.0"
        icon "assets/my_mod/icon.png"
    }

    links {
        homepage "https://example.com"
        sources "https://github.com/example/my-mod"
    }

    compatibility {
        requires "minecraft" version="26.2"
        depends "cloth-config" version=">=11.0.0"
        recommends "modmenu" version=">=1.0.0"
        incompatible-with "bad_mod" reason="Breaks the same screen"
    }

    load-order {
        after "cloth-config"
        before "late_mod"
    }

    properties {
        channel "stable"
    }

    runtime {
        network-channel "my_mod:main"
        listener "com.example.MyLifecycleListener"
        entrypoint "com.example.MyMod"
        transformer "com.example.MyTransformer"
        mixin "my_mod.mixins.json"
    }
}

Grouped KDL is the recommended style, but equivalent flat nodes remain supported. Runtime-provided ids such as minecraft, nows and nows-loader can be used in dependency declarations.

side accepts client, server, both or common. The current launcher runtime is client-side and rejects server-only mods before loading mod classes.

Parsed Descriptor Fields

The KDL reader normalizes metadata into ModDescriptor, so code that consumes metadata does not depend on KDL directly.

Dependency Semantics

Dependency nodes are validated by ModDependencyResolver before mods load. Required dependencies must be present and match the declared version range. Optional dependencies can influence order when the target mod is present. Conflict/incompatible declarations fail loading when the target version matches.

Load order declarations are edges in the same resolver:

• requires, depends, dependency and require make the target load before the current mod.
• recommends and suggests are optional by default.
• breaks, conflicts, conflict, incompatible and incompatible-with describe incompatible targets.
• before and load-before make the current mod load before the target when the target is loaded.
• after and load-after make the target load before the current mod when the target is loaded.

Version constraints support exact versions and range-style constraints through Nows’ core version constraint matcher. Use * when the relationship is not version-specific.

Runtime Declarations

Declarations are intentionally generic. Integrations decide which keys they care about:

Mods can query loaded metadata through NowsContext:

if (context.isModLoaded("other_mod")) {
    String name = context.requireModDescriptor("other_mod").name();
}

boolean clientRuntime = context.side() == NowsSide.CLIENT;

Use context.modDescriptors() for a snapshot of every loaded descriptor, context.mod(id) for the loaded container, and context.modsById() when a manager needs stable map lookup by mod id.