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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: minecraft-datapack-language
-Version: 17.0.3
+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.3 → 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.3 → 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.3 → minecraft_datapack_language-17.0.4}/docs/_docs/examples.md

@@ -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.3 → 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

{minecraft_datapack_language-17.0.3 → minecraft_datapack_language-17.0.4}/docs/_docs/multi-file-projects.md

@@ -1,6 +1,6 @@
 ---
 layout: page
-title: Multi File Projects
+title: Multi-File Projects
 permalink: /docs/multi-file-projects/
 ---
 
@@ -10,21 +10,21 @@ MDL supports organizing code across multiple files for better project structure.
 
 ### Main File (with pack declaration)
 
-Only the first file needs a pack declaration:
+Only the main entry file needs a pack declaration:
 
 ```mdl
 // main.mdl
 pack "my_project" "A multi-file project" 82;
 namespace "core";
 
-var num playerCount<@a> = 0;
+var num playerCount<global> = 0;
 
 function "init" {
     playerCount<global> = 0;
-    say Core system initialized!;
+    say "Core system initialized!";
 }
 
-on_load "core:init";
+on_load core:init;
 ```
 
 ### Additional Files (no pack declaration)
@@ -35,12 +35,12 @@ Other files don't need pack declarations:
 // ui.mdl
 namespace "ui";
 
-function "show_hud" {
-    tellraw @a {"text":"Players: $playerCount$","color":"green"};
+function ui:show_hud {
+    tellraw @a {"text":"Players: $playerCount<global>$","color":"green"};
 }
 
-function "update_hud" {
-    function "ui:show_hud<@a>";
+function ui:update_hud {
+    exec ui:show_hud<@a>;
 }
 ```
 
@@ -48,9 +48,9 @@ function "update_hud" {
 // game.mdl
 namespace "game";
 
-function "start" {
-    say Game started!;
-    function "ui:update_hud";
+function game:start {
+    say "Game started!";
+    exec ui:update_hud;
 }
 ```
 
@@ -59,7 +59,7 @@ function "start" {
 ### Build All Files Together
 
 ```bash
-mdl build --mdl "main.mdl ui.mdl game.mdl" -o dist
+mdl build --mdl . -o dist
 ```
 
 ### Build Entire Directory
@@ -95,10 +95,10 @@ namespace "magic";
 
 var num mana = 100;  // Defaults to player-specific scope
 
-function "cast_spell" {
-    if "$mana$ >= 20" {
-        mana<@s> = mana<@s> - 20;
-        say Spell cast! Mana: $mana$;
+function magic:cast_spell {
+    if $mana$ >= 20 {
+        mana = $mana$ - 20;
+        say "Spell cast! Mana: $mana$";
     }
 }
 ```
@@ -109,14 +109,15 @@ Variables from all files are automatically merged:
 
 ```mdl
 // core.mdl
-var num globalTimer<@a> = 0;
+var num globalTimer<global> = 0;
 var num playerScore = 0;  // Defaults to player-specific scope
 ```
 
 ```mdl
 // ui.mdl
-function "show_stats" {
-    tellraw @a {"text":"Timer: $globalTimer$, Score: $playerScore$","color":"gold"};
+namespace "ui";
+function ui:show_stats {
+    tellraw @a {"text":"Timer: $globalTimer<global>$, Score: $playerScore$","color":"gold"};
 }
 ```
 
@@ -126,22 +127,23 @@ When working with multiple files, you can use explicit scope selectors in condit
 
 ```mdl
 // core.mdl
-var num globalTimer<@a> = 0;
+namespace "core";
+var num globalTimer<global> = 0;
 var num playerScore = 0;  // Defaults to player-specific scope
 
-function "check_status" {
+function core:check_status {
     // Check global timer
-    if "$globalTimer<@a>$ > 1000" {
+    if $globalTimer<global>$ > 1000 {
         say "Game has been running for a while!";
     }
     
     // Check current player's score
-    if "$playerScore<@s>$ > 50" {
+    if $playerScore<@s>$ > 50 {
         say "You have a high score!";
     }
     
     // Check if any player has a very high score
-    if "$playerScore<@a>$ > 100" {
+    if $playerScore<@a>$ > 100 {
         say "Someone has an amazing score!";
     }
 }
@@ -149,9 +151,10 @@ function "check_status" {
 
 ```mdl
 // ui.mdl
-function "show_leaderboard" {
+namespace "ui";
+function ui:show_leaderboard {
     // Compare scores across different players
-    if "$playerScore<@p[name=Alice]>$ > $playerScore<@p[name=Bob]>$" {
+    if $playerScore<@p[name=Alice]>$ > $playerScore<@p[name=Bob]>$ {
         tellraw @a {"text":"Alice is winning!","color":"green"};
     } else {
         tellraw @a {"text":"Bob is winning!","color":"blue"};
@@ -217,23 +220,23 @@ function "update_ui" {
 ```mdl
 namespace "game";
 
-function "start" {
+function game:start {
     gameState<global> = 1;
-    say Game started!;
-    function "ui:update_ui";
+    say "Game started!";
+    exec ui:update_ui;
 }
 
-function "level_up" {
+function game:level_up {
     if "$playerLevel$ < 10" {
         playerLevel<@s> = playerLevel<@s> + 1;
-        say Level up! New level: $playerLevel$;
+        say "Level up! New level: $playerLevel$";
     }
 }
 ```
 
 Build the project:
 ```bash
-mdl build --mdl "main.mdl combat.mdl ui.mdl game.mdl" -o dist
+mdl build --mdl . -o dist
 ```
 
 ## Best Practices
@@ -243,8 +246,8 @@ mdl build --mdl "main.mdl combat.mdl ui.mdl game.mdl" -o dist
 3. **Clear naming**: Use descriptive file and namespace names
 4. **Shared variables**: Declare shared variables in the main file
 5. **Function organization**: Group related functions in the same file
-6. **Proper scoping**: Use `<@a>` for server-wide variables, no scope for player-specific variables
-7. **Explicit scope access**: Always access variables with their scope like `variable<scope>`
+6. **Proper scoping**: Use `<global>` for server-wide variables, omit scope for player-specific (defaults to @s)
+7. **Explicit scope access**: Omit scope for @s; use `<...>` only when you need a different selector
 
 ## File Structure Example