minecraft-datapack-language 17.0.2__tar.gz → 17.0.4__tar.gz

{minecraft_datapack_language-17.0.2 → minecraft_datapack_language-17.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: minecraft-datapack-language
-Version: 17.0.2
+Version: 17.0.4
 Summary: Compile MDL language with explicit scoping into a Minecraft datapack (1.21+ ready). Features variables, control flow, error handling, and VS Code extension.
 Project-URL: Homepage, https://www.mcmdl.com
 Project-URL: Documentation, https://www.mcmdl.com/docs

minecraft_datapack_language-17.0.4/docs/_data/version.yml

@@ -0,0 +1,3 @@
+current: "17.0.3"
+tag: "v17.0.3"
+updated_at: "2025-09-10T07:51:06Z"

{minecraft_datapack_language-17.0.2 → minecraft_datapack_language-17.0.4}/docs/_docs/cli-reference.md

@@ -18,41 +18,46 @@ pipx install minecraft-datapack-language
 
 ### Build Command
 
-Build MDL files into Minecraft datapacks:
+Build MDL files into Minecraft datapacks. Defaults: `--mdl .` and `-o dist`.
 
 ```bash
-mdl build --mdl <files> -o <output_dir>
+# Simplest
+mdl build
+
+# Explicit
+mdl build --mdl <path> -o <output_dir>
 # Zips by default -> creates <output_dir>.zip
 # Use --no-zip to skip archive creation
 ```
 
 **Examples:**
 ```bash
-# Build single file
-mdl build --mdl hello.mdl -o dist
-
-# Build entire directory
-mdl build --mdl myproject/ -o dist
+# Build single file (output defaults to dist)
+mdl build --mdl hello.mdl
 
-# Build current directory
-mdl build --mdl . -o dist
+# Build entire directory (both default)
+mdl build
 
-# Build with warnings suppressed
-mdl build --mdl . -o dist --ignore-warnings
+# Build with custom output
+mdl build --mdl myproject/ -o out
 ```
 
 **Options:**
-- `--mdl <files>`: MDL files or directories to build
-- `-o <output_dir>`: Output directory for compiled datapack
+- `--mdl <path>`: Path to a single `.mdl` file or a directory to build (default: `.`)
+- `-o <output_dir>`: Output directory for compiled datapack (default: `dist`)
 - `--verbose`: Show detailed build information
 - `--wrapper <name>`: Custom wrapper name for the datapack
 
 ### Check Command
 
-Validate MDL files for syntax and semantic errors:
+Validate MDL files for syntax and semantic errors. If no paths are given, it scans the current directory for `**/*.mdl`.
 
 ```bash
-mdl check <files>
+# Simplest
+mdl check
+
+# Explicit
+mdl check <files_or_directories>
 ```
 
 **Examples:**
@@ -60,10 +65,10 @@ mdl check <files>
 # Check single file
 mdl check hello.mdl
 
-# Check current directory
-mdl check .
+# Check current directory (implicit)
+mdl check
 
-# Check entire directory
+# Check a specific directory
 mdl check myproject/
 
 # Check with warnings suppressed
@@ -120,11 +125,9 @@ 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
+The new command generates a minimal project structure with:
+- `README.md` - Quick start with build instructions
+- `main.mdl` - Hello world (pack, namespace, simple function, on_load)
 
 **Generated project structure:**
 ```
@@ -136,9 +139,8 @@ my_awesome_pack/
 **Template content includes:**
 - Pack metadata (name, description, format)
 - Namespace declaration
-- Sample function definitions
-- Basic MDL syntax examples
-- Load function setup
+- One function that says hello
+- on_load hook
 
 ## Command Options
 
@@ -146,8 +148,8 @@ my_awesome_pack/
 
 | Option | Description | Example |
 |--------|-------------|---------|
-| `--mdl <files>` | MDL files or directories to build | `--mdl "main.mdl ui.mdl"` |
-| `-o <dir>` | Output directory | `-o dist` |
+| `--mdl <path>` | .mdl file or directory to build (default: `.`) | `--mdl .` |
+| `-o <dir>` | Output directory (default: `dist`) | `-o dist` |
 | `--verbose` | Show detailed output | `--verbose` |
 | `--wrapper <name>` | Custom wrapper name | `--wrapper mypack` |
 | `--no-zip` | Skip creating zip archive (zip is default) | `--no-zip` |
@@ -245,7 +247,7 @@ mdl check hello_world/main.mdl
 
 3. **Build the datapack:**
 ```bash
-mdl build --mdl hello_world/main.mdl -o dist
+mdl build --mdl hello_world/main.mdl
 ```
 
 4. **Install in Minecraft:**
@@ -273,7 +275,7 @@ mdl check hello.mdl
 
 3. **Build the datapack:**
 ```bash
-mdl build --mdl hello.mdl -o dist
+mdl build --mdl hello.mdl
 ```
 
 4. **Install in Minecraft:**
@@ -292,7 +294,7 @@ my_project/
 
 **Build command:**
 ```bash
-mdl build --mdl . -o dist
+mdl build
 ```
 
 ### Explicit Scopes in Conditions
@@ -337,7 +339,7 @@ function hello:main {
 Get detailed information about the build process:
 
 ```bash
-mdl build --mdl hello.mdl -o dist --verbose
+mdl build --mdl hello.mdl --verbose
 ```
 
 Output includes:
@@ -356,10 +358,10 @@ Output includes:
 ls *.mdl
 
 # Use explicit file paths
-mdl build --mdl ./myfile.mdl -o dist
+mdl build --mdl ./myfile.mdl
 
 # or build the directory itself
-mdl build --mdl . -o dist
+mdl build
 ```
 
 **"Failed to parse MDL files"**
@@ -381,7 +383,7 @@ mdl check myproject/
 Use verbose mode to get more information:
 
 ```bash
-mdl build --mdl myfile.mdl -o dist --verbose
+mdl build --mdl myfile.mdl --verbose
 mdl check myfile.mdl --verbose
 ```
 
@@ -413,7 +415,7 @@ dist/
 .PHONY: build clean
 
 build:
-	mdl build --mdl . -o dist
+	mdl build
 
 clean:
 	rm -rf dist/
@@ -426,7 +428,7 @@ check:
 ```json
 {
   "scripts": {
-    "build": "mdl build --mdl . -o dist",
+    "build": "mdl build",
     "check": "mdl check .",
     "clean": "rm -rf dist/"
   }
@@ -450,6 +452,6 @@ jobs:
           python-version: '3.9'
       - run: pip install minecraft-datapack-language
       - run: mdl check .
-      - run: mdl build --mdl . -o dist
+      - run: mdl build
       - run: mdl check .
 ```

{minecraft_datapack_language-17.0.2 → minecraft_datapack_language-17.0.4}/docs/_docs/docs-hub.md

@@ -57,14 +57,14 @@ Search and browse all available documentation for the Minecraft Datapack Languag
     <a href="{{ site.baseurl }}/docs/multi-file-projects/" class="doc-link">Project Structure →</a>
   </div>
   
-  <div class="doc-card" data-categories="python api programming">
+  <div class="doc-card" data-categories="python bindings programming">
     <h3>🐍 Python Bindings</h3>
-    <p>Programmatic access to MDL functionality for automation and integration.</p>
+    <p>Programmatic access to MDL for automation and integration.</p>
     <div class="doc-meta">
-      <span class="category">API</span>
+      <span class="category">Bindings</span>
       <span class="category">Python</span>
     </div>
-    <a href="{{ site.baseurl }}/docs/python-api/" class="doc-link">API Reference →</a>
+    <a href="{{ site.baseurl }}/docs/python-bindings/" class="doc-link">Bindings Guide →</a>
   </div>
   
   <div class="doc-card" data-categories="vscode extension ide">

{minecraft_datapack_language-17.0.2 → minecraft_datapack_language-17.0.4}/docs/_docs/examples.md

@@ -28,9 +28,9 @@ on_load hello:main;
 pack "logicalops" "Generated by MDL CLI" 82;
 namespace "logicalops";
 
-// Variables
-var num a<@s> = 0;
-var num b<@s> = 0;
+// Variables (default scope @s)
+var num a = 0;
+var num b = 0;
 
 // Main function
 function logicalops:main {
@@ -39,32 +39,32 @@ function logicalops:main {
 }
 
 function logicalops:init {
-    a<@s> = 1;
-    b<@s> = 2;
+    a = 1;
+    b = 2;
 }
 
 function logicalops:add {
-    var result<@s> = $a<@s>$ + $b<@s>$;
+    var result = $a$ + $b$;
     say "Result: $result$";
 }
 
 function logicalops:subtract {
-    var result<@s> = $a<@s>$ - $b<@s>$;
+    var result = $a$ - $b$;
     say "Result: $result$";
 }
 
 function logicalops:multiply {
-    var result<@s> = $a<@s>$ * $b<@s>$;
+    var result = $a$ * $b$;
     say "Result: $result$";
 }
 
 function logicalops:divide {
-    var result<@s> = $a<@s>$ / $b<@s>$;
+    var result = $a$ / $b$;
     say "Result: $result$";
 }
 
 function logicalops:andop {
-    if $a<@s>$ > 0 && $b<@s>$ > 0 {
+    if $a$ > 0 && $b$ > 0 {
         say "Both are greater than 0";
     } else {
         say "At least one is not greater than 0";
@@ -72,7 +72,7 @@ function logicalops:andop {
 }
 
 function logicalops:orop {
-    if $a<@s>$ > 0 || $b<@s>$ > 0 {
+    if $a$ > 0 || $b$ > 0 {
         say "At least one is greater than 0";
     } else {
         say "Both are not greater than 0";
@@ -80,7 +80,7 @@ function logicalops:orop {
 }
 
 function logicalops:notop {
-    if !$a<@s>$ > 0 {
+    if !$a$ > 0 {
         say "a is not greater than 0";
     } else {
         say "a is greater than 0";
@@ -88,34 +88,34 @@ function logicalops:notop {
 }
 
 function logicalops:whileloop {
-    a<@s> = 0;
-    while $a<@s>$ < 10 {
+    a = 0;
+    while $a$ < 10 {
         say "a is less than 10";
-        a<@s> = $a<@s>$ + 1;
+        a = $a$ + 1;
     }
 }
 
 function logicalops:scheduledwhileloop {
     // the scheduledwhile is just like the while loop, but it is scheduled to run every tick. This is useful for large calculations that would exceed the command recursion limit.
-    a<@s> = 0;
-    scheduledwhile $a<@s>$ < 10 {
+    a = 0;
+    scheduledwhile $a$ < 10 {
         say "a is less than 10";
-        a<@s> = $a<@s>$ + 1;
+        a = $a$ + 1;
     }
 }
 
 function logicalops:complexops {
-    var c<@s> = 5;
-    var d<@s> = 10;
-    var e<@s> = 15;
-    var f<@s> = 20;
-    var g<@s> = 2;
-    var h<@s> = 0;
-    h<@s> = $h<@s>$ - 1;
+    var c = 5;
+    var d = 10;
+    var e = 15;
+    var f = 20;
+    var g = 2;
+    var h = 0;
+    h = $h$ - 1;
 
-    var result<@s> = ($c<@s>$ + $d<@s>$ - $e<@s>$ * $f<@s>$ / $g<@s>$) * $h<@s>$;
+    var result = ($c$ + $d$ - $e$ * $f$ / $g$) * $h$;
 
-    if !$result<@s>$ == 135 {
+    if !$result$ == 135 {
         say "Result is not 135, there is an issue!";
     } else {
         say "Result is -135, everything is good!";
@@ -136,10 +136,10 @@ pack "raw" "Raw command example" 82;
 namespace "raw";
 
 function raw:custom {
-    // Use raw Minecraft commands
-    effect give @s minecraft:speed 10 1;
-    particle minecraft:explosion ~ ~ ~ 1 1 1 0 10;
-    playsound minecraft:entity.player.levelup player @s ~ ~ ~ 1 1;
+    // Use raw Minecraft commands via single-line raw blocks
+    $!raw effect give @s minecraft:speed 10 1 raw!$
+    $!raw particle minecraft:explosion ~ ~ ~ 1 1 1 0 10 raw!$
+    $!raw playsound minecraft:entity.player.levelup player @s ~ ~ ~ 1 1 raw!$
 }
 
 on_load raw:custom;

{minecraft_datapack_language-17.0.2 → minecraft_datapack_language-17.0.4}/docs/_docs/getting-started.md

@@ -43,33 +43,33 @@ The compiled datapack will be in the `dist` folder. Copy it to your Minecraft wo
 
 ### Variables
 
-Variables store numbers and can be scoped to different entities. MDL uses an **explicit scope system** where you must specify the scope each time you access a variable:
+Variables store numbers and can be scoped to different entities. MDL uses an **explicit scope system** where scopes can be specified explicitly, but are optional; when omitted, the scope defaults to `@s` (current entity):
 
 ```mdl
-// Player-specific variable (default)
-var num playerScore<@s> = 0;
+// Player-specific variable (default @s)
+var num playerScore = 0;
 
-// Server-wide variable
-var num globalCounter<@a> = 0;
+// Server-wide/global variable (singleton armor stand)
+var num globalCounter<global> = 0;
 
 // Team-specific variable
 var num teamScore<@a[team=red]> = 0;
 
-// Access variables with explicit scopes
-playerScore<@s> = 42;                    // Player scope
-globalCounter<@a> = 100;                 // Global scope
-teamScore<@a[team=red]> = 5;            // Team scope
+// Access variables (explicit or default scopes)
+playerScore = 42;                         // Defaults to @s
+globalCounter<global> = 100;              // Global scope
+teamScore<@a[team=red]> = 5;              // Team scope
 ```
 
 ### Variable Substitution
 
-Use `$variable$` to read variable values. Variables automatically resolve to their declared scopes:
+Use `$variable$` or `$variable<scope>$` to read variable values. If the scope is omitted, it defaults to `@s`:
 
 ```mdl
-say "Your score: $playerScore<@s>$";
-tellraw @a {"text":"Global counter: $globalCounter<@a>$","color":"gold"};
+say "Your score: $playerScore$";
+tellraw @a {"text":"Global counter: $globalCounter<global>$","color":"gold"};
 
-if $playerScore<@s>$ > 100 {
+if $playerScore$ > 100 {
     say "High score!";
 }
 ```
@@ -97,54 +97,54 @@ MDL supports real if/else statements and while loops:
 
 ```mdl
 // If statement
-if $playerScore<@s>$ > 50 {
-    say Great job!;
+if $playerScore$ > 50 {
+    say "Great job!";
 } else {
-    say Keep trying!;
+    say "Keep trying!";
 }
 
 // While loop
-while "$counter$ < 5" {
-    say Counter: $counter$;
+while $counter$ < 5 {
+    say "Counter: $counter$";
     counter = counter + 1;
 }
 ```
 
-### Explicit Scopes in Conditions
+### Reading with Explicit Selectors
 
-You can override variable scopes in conditions using explicit scope selectors:
+You can read variables using explicit selectors in conditions without affecting how they were declared:
 
 ```mdl
 // Check current player's score
-if "$playerScore<@s>$ > 50" {
+if $playerScore<@s>$ > 50 {
     say "Your score is high!";
 }
 
 // Check global counter
-if "$globalCounter<global>$ > 100" {
+if $globalCounter<global>$ > 100 {
     say "Global milestone reached!";
 }
 
 // Check another player's score
-if "$playerScore<@p[name=Steve]>$ > 20" {
+if $playerScore<@p[name=Steve]>$ > 20 {
     say "Steve has a good score!";
 }
 
 // Check team score
-if "$teamScore<@a[team=red]>$ > 50" {
+if $teamScore<@a[team=red]>$ > 50 {
     say "Red team is winning!";
 }
 ```
 
-This allows you to check variables across different scopes without changing their declared scope.
+This allows you to read variables at different selectors without any special linkage to where they were declared.
 
 ### Hooks
 
 Automatically run functions:
 
 ```mdl
-on_load "hello:init";    // Runs when datapack loads
-on_tick "hello:update";  // Runs every tick
+on_load hello:init;    // Runs when datapack loads
+on_tick hello:update;  // Runs every tick
 ```
 
 ## Complete Example
@@ -156,40 +156,40 @@ pack "example" "Complete example" 82;
 namespace "example";
 
 // Variables
-var num playerScore = 0;  // Defaults to player-specific scope
-var num globalTimer<@a> = 0;
+var num playerScore = 0;  // Defaults to player-specific scope (@s)
+var num globalTimer<global> = 0;
 
 // Initialize function
 function "init" {
-    playerScore<@s> = 0;
+    playerScore = 0;
     globalTimer<global> = 0;
-    say Game initialized!;
+    say "Game initialized!";
 }
 
 // Update function
 function "update" {
     globalTimer<global> = globalTimer<global> + 1;
     
-    if "$playerScore$ > 100" {
-        say High score!;
+    if $playerScore$ > 100 {
+        say "High score!";
         tellraw @a {"text":"Player has a high score!","color":"gold"};
     }
     
-    if "$globalTimer$ >= 1200" {  // 60 seconds
+    if $globalTimer<global>$ >= 1200 {  // 60 seconds
         globalTimer<global> = 0;
-        say Time's up!;
+        say "Time's up!";
     }
 }
 
 // Score function
 function "add_score" {
-    playerScore<@s> = playerScore<@s> + 10;
-    say Score: $playerScore$;
+    playerScore = playerScore + 10;
+    say "Score: $playerScore$";
 }
 
 // Hooks
-on_load "example:init";
-on_tick "example:update";
+on_load example:init;
+on_tick example:update;
 ```
 
 ## Building and Testing