minecraft-datapack-language 15.4.21__tar.gz → 15.4.23__tar.gz

{minecraft_datapack_language-15.4.21/minecraft_datapack_language.egg-info → minecraft_datapack_language-15.4.23}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: minecraft-datapack-language
-Version: 15.4.21
+Version: 15.4.23
 Summary: Compile JavaScript-style MDL language or Python API 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
@@ -477,6 +477,90 @@ This will create a datapack with:
 
 ---
 
+## 🎯 **Explicit Scope System**
+
+MDL features a powerful **explicit scope system** that makes variable access clear and unambiguous. Each variable access must specify its scope, eliminating hidden state and making code more readable.
+
+### **Variable Declaration Scopes**
+
+```mdl
+// Player-specific variable (defaults to @s in execution context)
+var num playerScore = 0;
+
+// Server-wide variable (stored on server armor stand)
+var num globalCounter scope<global> = 0;
+
+// Team-specific variable
+var num teamScore scope<@a[team=red]> = 0;
+
+// Custom entity variable
+var num entityData scope<@e[type=armor_stand,tag=special,limit=1]> = 0;
+```
+
+### **Variable Access with Explicit Scopes**
+
+```mdl
+// Each variable access must specify the scope
+playerScore<@s> = 42;                    // Player scope
+globalCounter<global> = 100;             // Global scope
+teamScore<@a[team=red]> = 5;            // Team scope
+entityData<@e[type=armor_stand,tag=special,limit=1]> = 10; // Custom entity
+```
+
+### **Explicit Scopes in Conditions**
+
+**NEW!** MDL now supports explicit scope selectors in if/while conditions, allowing you to override declared variable scopes:
+
+```mdl
+function "check_scores" {
+    // Check current player's score
+    if "$playerScore<@s>$ > 10" {
+        say "Your score is high!";
+    }
+    
+    // Check global counter
+    if "$globalCounter<global>$ > 100" {
+        say "Global milestone reached!";
+    }
+    
+    // Check another player's score
+    if "$playerScore<@p[name=Steve]>$ > 20" {
+        say "Steve has a good score!";
+    }
+    
+    // Check team score
+    if "$teamScore<@a[team=red]>$ > 50" {
+        say "Red team is winning!";
+    }
+    
+    // Use explicit scopes in while loops too
+    while "$globalCounter<global>$ < 10" {
+        globalCounter<global> = globalCounter<global> + 1;
+        say "Counter: $globalCounter$";
+    }
+}
+```
+
+**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 and debuggable
+
+### **Scope Mapping**
+
+MDL maps scopes to Minecraft selectors:
+
+| MDL Scope | Minecraft Selector | Description |
+|-----------|-------------------|-------------|
+| `scope<global>` | `@e[type=armor_stand,tag=mdl_server,limit=1]` | Server-wide storage |
+| `scope<@s>` | `@s` | Current player |
+| `scope<@a>` | `@a` | All players |
+| `scope<@a[team=red]>` | `@a[team=red]` | Red team players |
+| `scope<@e[type=armor_stand,tag=something,limit=1]>` | `@e[type=armor_stand,tag=something,limit=1]` | Custom entity |
+
+---
+
 ## 🎯 **Advanced Multi-File Examples with Namespaces**
 
 ### **Modern Namespace System**

{minecraft_datapack_language-15.4.21 → minecraft_datapack_language-15.4.23}/README.md

@@ -456,6 +456,90 @@ This will create a datapack with:
 
 ---
 
+## 🎯 **Explicit Scope System**
+
+MDL features a powerful **explicit scope system** that makes variable access clear and unambiguous. Each variable access must specify its scope, eliminating hidden state and making code more readable.
+
+### **Variable Declaration Scopes**
+
+```mdl
+// Player-specific variable (defaults to @s in execution context)
+var num playerScore = 0;
+
+// Server-wide variable (stored on server armor stand)
+var num globalCounter scope<global> = 0;
+
+// Team-specific variable
+var num teamScore scope<@a[team=red]> = 0;
+
+// Custom entity variable
+var num entityData scope<@e[type=armor_stand,tag=special,limit=1]> = 0;
+```
+
+### **Variable Access with Explicit Scopes**
+
+```mdl
+// Each variable access must specify the scope
+playerScore<@s> = 42;                    // Player scope
+globalCounter<global> = 100;             // Global scope
+teamScore<@a[team=red]> = 5;            // Team scope
+entityData<@e[type=armor_stand,tag=special,limit=1]> = 10; // Custom entity
+```
+
+### **Explicit Scopes in Conditions**
+
+**NEW!** MDL now supports explicit scope selectors in if/while conditions, allowing you to override declared variable scopes:
+
+```mdl
+function "check_scores" {
+    // Check current player's score
+    if "$playerScore<@s>$ > 10" {
+        say "Your score is high!";
+    }
+    
+    // Check global counter
+    if "$globalCounter<global>$ > 100" {
+        say "Global milestone reached!";
+    }
+    
+    // Check another player's score
+    if "$playerScore<@p[name=Steve]>$ > 20" {
+        say "Steve has a good score!";
+    }
+    
+    // Check team score
+    if "$teamScore<@a[team=red]>$ > 50" {
+        say "Red team is winning!";
+    }
+    
+    // Use explicit scopes in while loops too
+    while "$globalCounter<global>$ < 10" {
+        globalCounter<global> = globalCounter<global> + 1;
+        say "Counter: $globalCounter$";
+    }
+}
+```
+
+**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 and debuggable
+
+### **Scope Mapping**
+
+MDL maps scopes to Minecraft selectors:
+
+| MDL Scope | Minecraft Selector | Description |
+|-----------|-------------------|-------------|
+| `scope<global>` | `@e[type=armor_stand,tag=mdl_server,limit=1]` | Server-wide storage |
+| `scope<@s>` | `@s` | Current player |
+| `scope<@a>` | `@a` | All players |
+| `scope<@a[team=red]>` | `@a[team=red]` | Red team players |
+| `scope<@e[type=armor_stand,tag=something,limit=1]>` | `@e[type=armor_stand,tag=something,limit=1]` | Custom entity |
+
+---
+
 ## 🎯 **Advanced Multi-File Examples with Namespaces**
 
 ### **Modern Namespace System**

minecraft_datapack_language-15.4.23/data/test/function/main_if_0.mcfunction

@@ -0,0 +1 @@
+tellraw @a [{"text":"Player score is high!"}]

minecraft_datapack_language-15.4.23/data/test/function/main_if_1.mcfunction

@@ -0,0 +1 @@
+tellraw @a [{"text":"Steve has a good score!"}]

minecraft_datapack_language-15.4.23/data/test/function/main_if_2.mcfunction

@@ -0,0 +1 @@
+tellraw @a [{"text":"Global counter is high!"}]

minecraft_datapack_language-15.4.23/docs/_data/version.yml

@@ -0,0 +1,3 @@
+current: "15.4.22"
+tag: "v15.4.22"
+updated_at: "2025-09-02T04:22:04Z"

{minecraft_datapack_language-15.4.21 → minecraft_datapack_language-15.4.23}/docs/_docs/cli-reference.md

@@ -315,6 +315,43 @@ my_project/
 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:
+
+```mdl
+// 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:

{minecraft_datapack_language-15.4.21 → minecraft_datapack_language-15.4.23}/docs/_docs/examples.md

@@ -240,4 +240,78 @@ Build all files together:
 mdl build --mdl "main.mdl ui.mdl game.mdl" -o dist
 ```
 
+## Explicit Scopes in Conditions
+
+Demonstrates how to use explicit scope selectors in if/while conditions to override declared variable scopes:
+
+```mdl
+pack "scopes" "Explicit scope conditions example" 82;
+namespace "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" {
+    // Test explicit scope overrides in if 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!";
+    }
+    
+    // Check if any player has a high score
+    if "$playerScore<@a>$ > 20" {
+        say "Someone has a very high score!";
+    }
+    
+    // Use explicit scopes in while loops too
+    while "$globalCounter<global>$ < 10" {
+        globalCounter<global> = globalCounter<global> + 1;
+        say "Counter: $globalCounter$";
+    }
+}
+
+// Function to test different scopes
+function "test_scopes" {
+    // Set different values for different scopes
+    playerScore<@s> = 15;                    // Current player
+    globalCounter<global> = 150;             // Global
+    teamScore<@a[team=red]> = 75;           // Red team
+    
+    // Test conditions with explicit scopes
+    if "$playerScore<@s>$ > 10" {
+        say "Player score check passed!";
+    }
+    
+    if "$globalCounter<global>$ > 100" {
+        say "Global counter check passed!";
+    }
+    
+    if "$teamScore<@a[team=red]>$ > 50" {
+        say "Team score check passed!";
+    }
+}
+
+on_load "scopes:main";
+```
+
+**Key Features:**
+- **Override declared scopes**: Use `<@s>`, `<global>`, `<@a[team=red]>` in conditions
+- **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 and debuggable
+
 

{minecraft_datapack_language-15.4.21 → minecraft_datapack_language-15.4.23}/docs/_docs/getting-started.md

@@ -110,6 +110,34 @@ while "$counter$ < 5" {
 }
 ```
 
+### Explicit Scopes in Conditions
+
+You can override variable scopes in conditions using explicit scope selectors:
+
+```mdl
+// Check current player's score
+if "$playerScore<@s>$ > 50" {
+    say "Your score is high!";
+}
+
+// Check global counter
+if "$globalCounter<global>$ > 100" {
+    say "Global milestone reached!";
+}
+
+// Check another player's score
+if "$playerScore<@p[name=Steve]>$ > 20" {
+    say "Steve has a good score!";
+}
+
+// Check team score
+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.
+
 ### Hooks
 
 Automatically run functions:

{minecraft_datapack_language-15.4.21 → minecraft_datapack_language-15.4.23}/docs/_docs/multi-file-projects.md

@@ -120,6 +120,47 @@ function "show_stats" {
 }
 ```
 
+## Explicit Scopes in Conditions
+
+When working with multiple files, you can use explicit scope selectors in conditions to check variables across different scopes:
+
+```mdl
+// core.mdl
+var num globalTimer scope<global> = 0;
+var num playerScore = 0;  // Defaults to player-specific scope
+
+function "check_status" {
+    // Check global timer
+    if "$globalTimer<global>$ > 1000" {
+        say "Game has been running for a while!";
+    }
+    
+    // Check current player's score
+    if "$playerScore<@s>$ > 50" {
+        say "You have a high score!";
+    }
+    
+    // Check if any player has a very high score
+    if "$playerScore<@a>$ > 100" {
+        say "Someone has an amazing score!";
+    }
+}
+```
+
+```mdl
+// ui.mdl
+function "show_leaderboard" {
+    // Compare scores across different players
+    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"};
+    }
+}
+```
+
+This feature is especially useful in multi-file projects where you need to check variables across different scopes without changing their declared scope.
+
 ## Complete Multi-File Example
 
 Here's a complete example with multiple files:

{minecraft_datapack_language-15.4.21 → minecraft_datapack_language-15.4.23}/minecraft_datapack_language/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '15.4.21'
-__version_tuple__ = version_tuple = (15, 4, 21)
+__version__ = version = '15.4.23'
+__version_tuple__ = version_tuple = (15, 4, 23)
 
-__commit_id__ = commit_id = 'gd8f708315'
+__commit_id__ = commit_id = 'g21ed7334d'

{minecraft_datapack_language-15.4.21 → minecraft_datapack_language-15.4.23}/minecraft_datapack_language/cli_build.py

@@ -176,7 +176,7 @@ def _generate_scoreboard_objectives(ast: Dict[str, Any], output_dir: Path) -> Li
             if 'body' in func:
                 for statement in func['body']:
                     # Look for variable assignments and usage
-                    if statement['type'] == 'variable_assignment':
+                    if statement['type'] in ['variable_assignment', 'explicit_scope_assignment']:
                         if statement['name'] not in seen_variables:
                             variables.append(statement['name'])
                             seen_variables.add(statement['name'])
@@ -280,8 +280,7 @@ def _process_say_command_with_variables(content: str, selector: str, variable_sc
                 var_selector = var_parts[1][:-1]  # Remove trailing >
                 components.append(f'{{"score":{{"name":"{var_selector}","objective":"{base_var}"}}}}')
             else:
-                # Simple variable: $variable$ - determine selector based on declared scope
-                var_selector = "@e[type=armor_stand,tag=mdl_server,limit=1]"  # Default to global
+                # Simple variable: $variable$ - use declared scope if available, otherwise default to current selector
                 if variable_scopes and var_name in variable_scopes:
                     declared_scope = variable_scopes[var_name]
                     if declared_scope == 'global':
@@ -290,7 +289,8 @@ def _process_say_command_with_variables(content: str, selector: str, variable_sc
                         var_selector = declared_scope
                     print(f"DEBUG: Variable {var_name} using declared scope {declared_scope} -> selector {var_selector}")
                 else:
-                    print(f"DEBUG: Variable {var_name} has no declared scope, using default global selector")
+                    var_selector = selector  # Use current selector (@s)
+                    print(f"DEBUG: Variable {var_name} has no declared scope, using default selector {var_selector}")
                 
                 components.append(f'{{"score":{{"name":"{var_selector}","objective":"{var_name}"}}}}')
     
@@ -336,16 +336,25 @@ def _process_statement(statement: Any, namespace: str, function_name: str, state
         var_name = statement['name']
         value = statement['value']
         
-        # Determine the correct selector for this variable based on its declared scope
-        var_selector = selector  # Default to current selector
-        if variable_scopes and var_name in variable_scopes:
-            declared_scope = variable_scopes[var_name]
-            if declared_scope == 'global':
-                var_selector = "@e[type=armor_stand,tag=mdl_server,limit=1]"
-            else:
-                var_selector = declared_scope
-        print(f"DEBUG: Variable {var_name} assignment using selector: {var_selector} (declared scope: {variable_scopes.get(var_name, 'none')})")
+        # For implicit assignments, always default to @s (current entity)
+        # Declared scopes only affect variable substitutions, not assignments
+        var_selector = selector  # Default to current selector (@s)
+        print(f"DEBUG: Variable {var_name} assignment using selector: {var_selector} (implicit scope, ignoring declared scope: {variable_scopes.get(var_name, 'none')})")
+    
+    elif statement['type'] == 'explicit_scope_assignment':
+        var_name = statement['name']
+        value = statement['value']
+        explicit_scope = statement['scope']
         
+        # For explicit scope assignments, use the specified scope
+        if explicit_scope == 'global':
+            var_selector = "@e[type=armor_stand,tag=mdl_server,limit=1]"
+        else:
+            var_selector = explicit_scope
+        print(f"DEBUG: Variable {var_name} assignment using explicit selector: {var_selector}")
+    
+    # Handle assignment value processing for both types
+    if statement['type'] in ['variable_assignment', 'explicit_scope_assignment']:
         # Handle different value types
         if isinstance(value, int):
             commands.append(f"scoreboard players set {var_selector} {var_name} {value}")
@@ -841,22 +850,22 @@ def _ast_to_pack(ast: Dict[str, Any], mdl_files: List[Path]) -> Pack:
                             else:
                                 # Simple function call without scope
                                 function.commands.append(f"function {func_namespace}:{func_name}")
-                        elif statement.get('type') == 'variable_assignment':
+                        elif statement.get('type') in ['variable_assignment', 'explicit_scope_assignment']:
                             # Handle variable assignments
                             var_name = statement['name']
                             value = statement['value']
                             
-                            # Determine selector based on variable scope
-                            var_selector = "@s"  # Default
-                            if 'variables' in ast:
-                                for var_decl in ast['variables']:
-                                    if var_decl.get('name') == var_name:
-                                        var_scope = var_decl.get('scope')
-                                        if var_scope == 'global':
-                                            var_selector = "@e[type=armor_stand,tag=mdl_server,limit=1]"
-                                        elif var_scope:
-                                            var_selector = var_scope
-                                        break
+                            # Determine selector based on assignment type
+                            if statement.get('type') == 'explicit_scope_assignment':
+                                # Explicit scope assignment - use specified scope
+                                explicit_scope = statement['scope']
+                                if explicit_scope == 'global':
+                                    var_selector = "@e[type=armor_stand,tag=mdl_server,limit=1]"
+                                else:
+                                    var_selector = explicit_scope
+                            else:
+                                # Implicit assignment - always default to @s
+                                var_selector = "@s"
                             
                             if hasattr(value, 'value'):
                                 # Simple literal value

{minecraft_datapack_language-15.4.21 → minecraft_datapack_language-15.4.23}/minecraft_datapack_language/cli_help.py

@@ -142,6 +142,32 @@ def show_build_help():
     print(f"5. Build multiple files in a directory:")
     print(f"   {color.code('mdl build --mdl examples/ -o output --verbose')}")
     print()
+
+    # Advanced Features
+    print_section("Advanced Features")
+    print()
+    print(color.info("MDL supports advanced features including explicit scopes in conditions:"))
+    print()
+    print(f"  {color.code('// Variables with different scopes')}")
+    print(f"  {color.code('var num playerScore = 0;                    // Defaults to @s')}")
+    print(f"  {color.code('var num globalCounter scope<global> = 0;    // Global scope')}")
+    print(f"  {color.code('var num teamScore scope<@a[team=red]> = 0;  // Team scope')}")
+    print()
+    print(f"  {color.code('// Use explicit scopes in conditions')}")
+    print(f"  {color.code('if \"$playerScore<@s>$ > 10\" {{')}")
+    print(f"  {color.code('    say \"Current player score is high!\";')}")
+    print(f"  {color.code('}')}")
+    print()
+    print(f"  {color.code('if \"$globalCounter<global>$ > 100\" {{')}")
+    print(f"  {color.code('    say \"Global counter reached milestone!\";')}")
+    print(f"  {color.code('}')}")
+    print()
+    print(f"  {color.code('if \"$teamScore<@a[team=red]>$ > 50\" {{')}")
+    print(f"  {color.code('    say \"Red team is winning!\";')}")
+    print(f"  {color.code('}')}")
+    print()
+    print(color.info("This allows you to check variables across different scopes without changing their declared scope."))
+    print()
     
     # Output Structure
     print_section("Output Structure")