CLI Reference

The MDL command-line interface provides tools for building and managing Minecraft datapacks.

Installation

Install MDL using pipx:

pipx install minecraft-datapack-language

Basic Commands

Build Command

Build MDL files into Minecraft datapacks:

mdl build --mdl <files> -o <output_dir>

Examples:

# Build single file
mdl build --mdl hello.mdl -o dist

# Build entire directory
mdl build --mdl myproject/ -o dist

# Build current directory
mdl build --mdl . -o dist

# Build with warnings suppressed
mdl build --mdl . -o dist --ignore-warnings

Options:

--mdl <files>: MDL files or directories to build
-o <output_dir>: Output directory for compiled datapack
--verbose: Show detailed build information
--wrapper <name>: Custom wrapper name for the datapack

Check Command

Validate MDL files without building:

mdl check <files>

Examples:

# Check single file
mdl check hello.mdl

# Check current directory
mdl check .

# Check entire directory
mdl check myproject/

# Check with warnings suppressed
mdl check myproject/ --ignore-warnings

Check Command

Validate MDL files for syntax and semantic errors:

mdl check <files>

Examples:

# Check single file
mdl check hello.mdl

# Check current directory
mdl check .

# Check entire directory
mdl check myproject/

# Check with warnings suppressed
mdl check myproject/ --ignore-warnings

Error Reporting: The check command provides comprehensive error reporting with:

Exact file location (line, column)
Context lines showing the problematic code
Helpful suggestions for fixing issues
Multiple error collection (reports all errors, not just the first)

Example Error Output:

Error 1: MDLSyntaxError in test.mdl:15:8
Missing closing brace for if statement
Context:
  13:   if (score > 10) {
  14:     say "High score!"
  15:     score = 0
  16:   }

Suggestion: Add closing brace '}' after line 15

Error 2: MDLLexerError in test.mdl:22:12
Unterminated string literal
Context:
  20:   say "Hello world
  21:   score = 10
  22:   say "Goodbye

Suggestion: Add closing quote '"' at the end of line 20

New Command

Create a new MDL project with template files:

mdl new <project_name>

Examples:

# Create a new project in current directory
mdl new my_awesome_pack

# Create a project with specific name
mdl new adventure_map

# Create a project in a subdirectory
mdl new projects/survival_plus

What it creates: The new command generates a complete project structure with:

README.md - Project documentation and setup instructions
main.mdl - Main MDL file with basic template structure
Proper pack declaration and namespace setup
Example functions and basic syntax

Generated project structure:

my_awesome_pack/
├── README.md
└── main.mdl

Template content includes:

Pack metadata (name, description, format)
Namespace declaration
Sample function definitions
Basic MDL syntax examples
Load function setup

Command Options

Build Options

Option	Description	Example
`--mdl <files>`	MDL files or directories to build	`--mdl "main.mdl ui.mdl"`
`-o <dir>`	Output directory	`-o dist`
`--verbose`	Show detailed output	`--verbose`
`--wrapper <name>`	Custom wrapper name	`--wrapper mypack`
`--ignore-warnings`	Suppress warning messages	`--ignore-warnings`

Check Options

Option	Description	Example
`--verbose`	Show detailed validation information	`--verbose`
`--ignore-warnings`	Suppress warning messages	`--ignore-warnings`

New Options

Option	Description	Example
`<project_name>`	Name of the new project to create	`mdl new my_pack`

Error Handling

MDL provides comprehensive error handling and reporting:

Error Types

MDLSyntaxError: Basic syntax violations (missing semicolons, braces)
MDLLexerError: Token recognition issues (unterminated strings, invalid characters)
MDLParserError: Parsing and structure problems (malformed statements)
MDLValidationError: Semantic validation failures (undefined variables, invalid references)
MDLFileError: File access and I/O issues
MDLBuildError: Build process failures
MDLCompilationError: Compilation and linking issues
MDLConfigurationError: CLI configuration and argument errors

Error Features

Exact Location: Errors include precise line and column numbers
Context Lines: Shows surrounding code for better debugging
Helpful Suggestions: Provides specific fix recommendations
Multiple Error Collection: Reports all errors, not just the first one
Error Summaries: Shows total error and warning counts
Verbose Mode: Detailed error information with additional context
Warning Suppression: Use --ignore-warnings to hide warning messages and show only errors

Example Error Output

🔍 Checking test.mdl...

Error 1: MDLSyntaxError in test.mdl:15:8
Missing closing brace for if statement
Context:
  13:   if "$score<@s>$ > 10" {
  14:     say "High score!"
  15:     score<@s> = 0
  16:   }

Suggestion: Add closing brace '}' after line 15

Error 2: MDLLexerError in test.mdl:22:12
Unterminated string literal
Context:
  20:   say "Hello world
  21:   score = 10
  22:   say "Goodbye

Suggestion: Add closing quote '"' at the end of line 20

Error 3: MDLValidationError in test.mdl:8:5
Undefined variable 'player_score'
Context:
   6:   score = 10
   7:   lives = 3
   8:   player_score = 5
   9:   say "Score: $score$"

Suggestion: Declare the variable first with 'variable player_score = 0'

Summary: 3 errors found

| --verbose | Show detailed output | --verbose |

Examples

Basic Workflow

Create a new project:
```
mdl new hello_world
```
Check the generated file:
```
mdl check hello_world/main.mdl
```

Build the datapack:

mdl build --mdl hello_world/main.mdl -o dist

Install in Minecraft:
- Copy dist/hello_world/ to your world’s datapacks/ folder
- Run /reload in-game

Alternative: Manual file creation If you prefer to create files manually, you can start with:

// hello.mdl
pack "hello" "My first datapack" 82;
namespace "hello";

function "main" {
    say Hello, Minecraft!;
}

on_load "hello:main";

Check the file:
```
mdl check hello.mdl
```
Build the datapack:
```
mdl build --mdl hello.mdl -o dist
```
Install in Minecraft:
- Copy dist/hello/ to your world’s datapacks/ folder
- Run /reload in-game

Multi-File Project

Project structure:

my_project/
├── main.mdl
├── ui.mdl
└── game.mdl

Build command:

mdl build --mdl . -o dist

Explicit Scopes in Conditions

MDL supports explicit scope selectors in if/while conditions, allowing you to override declared variable scopes:

// Variables with different scopes
var num playerScore = 0;                    // Defaults to @s
var num globalCounter scope<global> = 0;    // Global scope
var num teamScore scope<@a[team=red]> = 0;  // Team scope

function "main" {
    // Use explicit scope in conditions
    if "$playerScore<@s>$ > 10" {
        say "Current player score is high!";
    }
    
    if "$globalCounter<global>$ > 100" {
        say "Global counter reached milestone!";
    }
    
    if "$teamScore<@a[team=red]>$ > 50" {
        say "Red team is winning!";
    }
    
    // Check another player's score
    if "$playerScore<@p[name=Steve]>$ > 5" {
        say "Steve has a good score!";
    }
}

Benefits:

Override declared scopes: Use different scopes than what was declared
Check other entities: Compare scores across different players/teams
Flexible conditions: Mix and match scopes as needed
Clear intent: Explicit scope makes code more readable

Verbose Build

Get detailed information about the build process:

mdl build --mdl hello.mdl -o dist --verbose

Output includes:

Files being processed
Functions being generated
Variables being initialized
Any warnings or errors

Error Handling

Common Errors

“No .mdl files found”

# Make sure you're in the right directory
ls *.mdl

# Use explicit file paths
mdl build --mdl ./myfile.mdl -o dist

# or build the directory itself
mdl build --mdl . -o dist

“Failed to parse MDL files”

# Check syntax
mdl check myfile.mdl

# Look for missing semicolons, brackets, etc.

“Duplicate function name”

# Check for duplicate function names in the same namespace
mdl check myproject/

Debugging

Use verbose mode to get more information:

mdl build --mdl myfile.mdl -o dist --verbose
mdl check myfile.mdl --verbose

Output Structure

The build command creates a datapack with this structure:

dist/
└── pack_name/
    ├── pack.mcmeta
    └── data/
        └── namespace/
            ├── function/
            │   ├── main.mcfunction
            │   └── other.mcfunction
            └── tags/
                └── function/
                    ├── load.json
                    └── tick.json

Integration

With Build Tools

Makefile example:

.PHONY: build clean

build:
	mdl build --mdl . -o dist

clean:
	rm -rf dist/

check:
	mdl check .

npm scripts example:

{
  "scripts": {
    "build": "mdl build --mdl . -o dist",
    "check": "mdl check .",
    "clean": "rm -rf dist/"
  }
}

With CI/CD

GitHub Actions example:

name: Build Datapack
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
        with:
          python-version: '3.9'
      - run: pip install minecraft-datapack-language
      - run: mdl check .
      - run: mdl build --mdl . -o dist
      - run: mdl check .