Minecraft Datapack Language

MDL is a typed compiler for Minecraft Java Edition datapacks, implemented in Rust. It compiles a bounded typed source language through resolved HIR, verified Core SSA, Core optimization, target preflight, structured Minecraft lowering, target-cost analysis, and deterministic datapack emission. Generated packs are tested on the official vanilla Java 26.2 dedicated server; no client is required.

Quick start

Create example.mdl:

export fn choose(flag: Bool, left: Int32, right: Int32) -> Int32 {
    var selected: Int32;
    if (flag) {
        selected = left;
    } else {
        selected = right;
    }
    return selected;
}

Compile it with every CLI-exposed choice explicit:

cargo run -p mdl -- compile example.mdl \
  --output build/example-pack \
  --core-opt baseline \
  --minecraft-opt baseline \
  --namespace example \
  --register-objective mdl.example \
  --description "MDL example"

The CLI refuses to overwrite a nonempty output directory. On success it prints each exported source function’s generated entry resource, ordered typed scoreboard ABI homes, inferred behavior, generated entry requirement, and fork deployment contract.

Current source language

The first complete language slice includes:

• Bool, Int32, and Void function results (an omitted result annotation means Void);
• explicit positional parameter types and optional result annotations;
• immutable const and mutable var locals;
• forward calls and recursion at the frontend level;
• if, else if, else, assignment, and return;
• Boolean negation and typed equality/ordered comparisons;
• rooted in-memory packages, Zig-like named imports, visibility, and explicit datapack exports;
• literal-only unsafe minecraft("...") as a conservative opaque boundary;
• typed static entity queries and ordered run scopes with as, at, at_executor, positioned, rotated, in, anchored, and align;
• exact compiler-known absolute, relative (~), and local (^) spatial arguments;
• method-oriented Executor<ArmorStand>.say, teleport, and move_by operations; and
• exact source diagnostics, definite assignment, and return-completeness checking.

Arguments evaluate left to right. Types match exactly; there are no implicit conversions. The current Minecraft backend deliberately rejects recursive call graphs with a typed lowering error. General arithmetic, first-class strings, lists, structs, loops, entity handles, scheduling, and macros are not yet source features. String literals exist only in compiler-known contexts such as imports, query tags, unsafe commands, and typed messages.

For example, one captured executor can use an ordered frame and structured spatial commands:

export fn move_worker() {
    run.as(mc.entities(ArmorStand).with_tag("worker").limit(1))
        .at_executor()
        .positioned(~10, ~, ~) |worker| {
        worker.say("moving");
        worker.teleport(~, ~1, ~);
        worker.move_by(0, 2, 0);
    }
}

The query is an explicit possible fork; the capture proves the current executor only inside its lexical scope. teleport is relative to the current execution frame, while move_by deliberately re-establishes the receiver’s frame. Typed operations never fall back to raw command text. Spatial arguments are compiler-known attributes, not yet ordinary runtime values.

Verification

Fast checks do not launch Java:

cargo test --workspace

The source compiler’s four-policy differential runs all combinations of Core none|baseline and Minecraft none|baseline in one official-server startup:

MDL_SERVER_JAR=/path/to/minecraft-server-26.2.jar \
MDL_JAVA=/path/to/java25 \
cargo test -p mdl-test --test source_compilation \
  source_compilation_runs_all_four_policies_on_vanilla_26_2 \
  -- --ignored --exact --nocapture

The CLI process-boundary proof compiles through the actual mdl binary, installs the materialized directory in the server harness, and invokes the printed ABI:

MDL_SERVER_JAR=/path/to/minecraft-server-26.2.jar \
MDL_JAVA=/path/to/java25 \
cargo test -p mdl --test server \
  cli_materialized_pack_runs_on_vanilla_26_2 \
  -- --ignored --exact --nocapture

The Stage 7 typed-command proof compiles all four optimization combinations, summons a tagged armor stand in a force-loaded chunk, checks executor-attributed output and empty-query skipping, and measures the native result without a client:

MDL_SERVER_JAR=/path/to/minecraft-server-26.2.jar \
MDL_JAVA=/path/to/java25 \
cargo test -p mdl-test --test source_compilation \
  stage7_typed_say_runs_as_captured_executor_on_vanilla_26_2 \
  -- --ignored --exact --nocapture

The Stage 7.5 gate audits Mojang’s command tree, measures handwritten spatial semantics, and executes compiler-generated packs under all four policies:

MDL_SERVER_JAR=/path/to/minecraft-server-26.2.jar \
MDL_JAVA=/path/to/java25 \
cargo test -p mdl-test \
  --test official_command_report \
  --test spatial_command_semantics \
  --test stage75_server \
  -- --ignored --nocapture

Stage 7.5’s execution-frame and static spatial-semantics slice is complete; its verified boundary is recorded in the Stage 7.5 to Stage 8 handoff. Stage 8 is complete for scalar physical realizations, synchronous serial run contexts, and recursive-SCC-only typed spill frames. Its final evidence and downstream contract are in the Stage 8 completion audit and Stage 8 handoff.

Compiler architecture, pass proofs, semantic ambiguities, and the implementation roadmap live under notes/compiler. Backend command research lives under notes/mcfunction.