Skip to content

MinecraftDatapackLanguage

⭐ 1 stars | 🔱 1 forks

📊 Project Details

  • Primary Language: Python
  • Languages Used: Python, HTML, mcfunction, Shell, TypeScript, PowerShell, CSS, Ruby, Makefile
  • License: GNU General Public License v3.0
  • Created: August 26, 2025
  • Last Updated: May 25, 2026

📝 About

MDL Icon Minecraft Datapack Language (MDL)

A modern, scope-aware language that lets you write Minecraft datapacks with explicit scoping, variables, control structures, and expressions that actually work.

📖 View Full Documentation - Complete guides, examples, and API reference
📦 View on PyPI - Download and install from PyPI
🔧 VS Code Extension - Syntax highlighting, IntelliSense, and snippets

CI Documentation PyPI Release

🎯 MODERN MDL Language with Explicit Scoping

MDL uses a modern, scope-aware language format with explicit scoping, control structures, variables, and expressions:

✨ MODERN Features

  • 🎯 Explicit scoping with angle brackets <@s>, <@a[team=red]> for all operations
  • 📝 Modern comments using // and /* */
  • 🔢 Number variables with var num type (stored in scoreboards)
  • 🔄 Full control structures including if/else, while loops
  • 💲 Variable substitution with $variable<scope>$ syntax
  • 🧮 Expressions with arithmetic operations (+, -, *, /)
  • 📦 Namespace system for modular code organization
  • 🏷️ Tag system for all datapack resources (recipes, loot tables, advancements, etc.)
  • 🎨 VS Code extension with full IntelliSense and snippets
  • 🧪 Comprehensive testing with E2E validation
  • 📚 Extensive documentation with examples for every feature

🏗️ Core Features

  • ✅ Default pack_format 82 for latest Minecraft features
  • ✅ Explicit scoping - every variable operation specifies its scope
  • ✅ Real control structures - if/else, while loops
  • ✅ Number variables stored in scoreboards with $variable<scope>$ substitution
  • ✅ Expressions with arithmetic operations and variable substitution
  • ✅ Multi-file projects with automatic merging and dependency resolution
  • ✅ Variable optimization - automatic load function generation for initialization
  • ✅ Selector optimization - proper @a usage for system commands
  • ✅ Easy hooks into minecraft:tick and minecraft:load via function tags
  • ✅ Tag support for recipe, loot_table, advancement, item_modifier, predicate, and structure
  • ✅ Raw blocks for direct Minecraft command injection
  • ✅ Say commands that auto-convert to tellraw with JSON formatting

Note: Version 1.0+ uses pack_format 82 by default for the modern MDL syntax.

🚀 Install

Global, isolated CLI via pipx: 

python3 -m pip install --user pipx
python3 -m pipx ensurepath    # reopen terminal
pipx install minecraft-datapack-language

mdl --help

Virtualenv (if you prefer): 

python3 -m venv .venv
source .venv/bin/activate      # Windows: .\.venv\Scripts\Activate.ps1
pip install minecraft-datapack-language

Option B — from source (for contributors)

# inside the repo
python -m pip install -e .

🔄 Update

  • pipx: pipx upgrade minecraft-datapack-language
  • pip (venv): pip install -U minecraft-datapack-language
  • Pin a version: pipx install "minecraft-datapack-language==<version>" (replace <version> with desired version)

💻 CLI

Modern MDL (v1.0+)

# Build (defaults: --mdl . and -o dist)
mdl build

# Check (scans current directory)
mdl check

# Build single file (output still defaults to dist)
mdl build --mdl my_pack/mypack.mdl

# Custom output directory
mdl build -o out

# Optional wrapper directory for output
mdl build --wrapper mypack

# Create new projects
mdl new my_awesome_pack

Quick Start

# Create a new project
mdl new my_first_pack

# Build it
cd my_first_pack
mdl build

# Check for errors
mdl check

📝 Language Examples

Basic Structure

pack "MyPack" "My awesome datapack" 15;
namespace "game";

var num player_score<@s> = 0;
var num team_score<@a[team=red]> = 0;

function game:start {
    player_score<@s> = 100;
    say "Welcome! Your score is $player_score<@s>$";
}

on_load game:start;

Control Structures

function game:check_score {
    if $player_score<@s>$ > 10 {
        say "Great score!";
        player_score<@s> = $player_score<@s>$ + 5;
    } else {
        say "Keep trying!";
    }

    while $player_score<@s>$ < 100 {
        player_score<@s> = $player_score<@s>$ + 1;
    }
}

Tags and Resources

// Recipe tags
tag recipe "diamond_sword" "recipes/diamond_sword.json";
tag loot_table "epic_loot" "loot_tables/epic_loot.json";
tag advancement "first_spell" "advancements/first_spell.json";

// Item modifiers and predicates
tag item_modifier "enchanted_tool" "item_modifiers/enchanted_tool.json";
tag predicate "has_mana" "predicates/has_mana.json";
tag structure "wizard_tower" "structures/wizard_tower.json";

Raw Blocks and Say Commands

function game:special_effect {
    $!raw
    execute as @s run particle minecraft:explosion ~ ~ ~ 1 1 1 0 10
    execute as @s run playsound minecraft:entity.player.levelup player @s ~ ~ ~ 1 1
    raw!$

    say "Special effect triggered! Score: $player_score<@s>$";
}

🔧 Development

Building from Source

git clone https://github.com/aaron777collins/MinecraftDatapackLanguage.git
cd MinecraftDatapackLanguage
python -m pip install -e .

Running Tests

# Run all tests
python -m pytest

# Run specific test file
python -m pytest test_comprehensive_end_to_end.py

# Run with coverage
python -m pytest --cov=minecraft_datapack_language

Building the Extension

cd vscode-extension
npm install
npm run compile

📚 Documentation

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests for new functionality
  5. Submit a pull request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

  • Minecraft community for inspiration
  • Contributors and testers
  • VS Code team for the excellent extension API

Happy coding with MDL! 🎮