minecraft-datapack-language 15.4.21__py3-none-any.whl → 15.4.23__py3-none-any.whl

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 = None

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/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")

minecraft_datapack_language/mdl_parser_js.py

@@ -316,10 +316,15 @@ class MDLParser:
                     suggestion="Replace 'for' with 'while' and adjust the loop structure"
                 )
             
-            # Check if this is a variable assignment (identifier followed by =)
+            # Check if this is a variable assignment
+            # Pattern 1: identifier = (simple assignment)
             if (self.current + 1 < len(self.tokens) and 
                 self.tokens[self.current + 1].type == TokenType.ASSIGN):
                 return self._parse_variable_assignment()
+            
+            # Pattern 2: identifier<scope> = (explicit scope assignment)
+            elif self._is_explicit_scope_assignment():
+                return self._parse_explicit_scope_assignment()
             else:
                 # Assume it's a command
                 return self._parse_command()
@@ -386,6 +391,72 @@ class MDLParser:
         
         return {"type": "variable_assignment", "name": name, "value": value}
     
+    def _is_explicit_scope_assignment(self) -> bool:
+        """Check if current position is an explicit scope assignment pattern: var<scope> = value"""
+        if self.current >= len(self.tokens):
+            return False
+            
+        # Look for pattern: IDENTIFIER LANGLE ... RANGLE ASSIGN
+        idx = self.current + 1
+        
+        # Must have LANGLE after identifier
+        if idx >= len(self.tokens) or self.tokens[idx].type != TokenType.LANGLE:
+            return False
+        idx += 1
+        
+        # Skip tokens until we find RANGLE
+        while idx < len(self.tokens) and self.tokens[idx].type != TokenType.RANGLE:
+            idx += 1
+        
+        # Must find RANGLE
+        if idx >= len(self.tokens) or self.tokens[idx].type != TokenType.RANGLE:
+            return False
+        idx += 1
+        
+        # Must have ASSIGN after RANGLE
+        if idx >= len(self.tokens) or self.tokens[idx].type != TokenType.ASSIGN:
+            return False
+            
+        return True
+    
+    def _parse_explicit_scope_assignment(self) -> dict:
+        """Parse variable assignment with explicit scope: var<scope> = value"""
+        # Parse variable name
+        name_token = self._match(TokenType.IDENTIFIER)
+        name = name_token.value
+        
+        # Parse scope: <scope>
+        self._match(TokenType.LANGLE)
+        
+        # Parse scope selector content
+        scope_parts = []
+        while not self._is_at_end() and self._peek().type != TokenType.RANGLE:
+            scope_parts.append(self._peek().value)
+            self._advance()
+        
+        if self._is_at_end():
+            raise create_parser_error(
+                message="Unterminated scope selector in assignment",
+                file_path=self.source_file,
+                line=self._peek().line,
+                column=self._peek().column,
+                line_content=self._peek().value,
+                suggestion="Add a closing '>' to terminate the scope selector"
+            )
+        
+        self._match(TokenType.RANGLE)
+        scope = ''.join(scope_parts)
+        
+        # Parse assignment
+        self._match(TokenType.ASSIGN)
+        
+        # Parse the value
+        value = self._parse_expression()
+        
+        self._match(TokenType.SEMICOLON)
+        
+        return {"type": "explicit_scope_assignment", "name": name, "scope": scope, "value": value}
+    
     def _parse_if_statement(self) -> IfStatement:
         """Parse if statement."""
         self._match(TokenType.IF)
@@ -836,8 +907,34 @@ class MDLParser:
             identifier_name = token.value
             self._advance()  # consume the identifier
             
-            # Check if the identifier contains a scope selector
-            if '<' in identifier_name and identifier_name.endswith('>'):
+            # Check for explicit scope syntax: identifier<scope>
+            if not self._is_at_end() and self._peek().type == TokenType.LANGLE:
+                self._advance()  # consume <
+                
+                # Parse scope selector content
+                scope_parts = []
+                while not self._is_at_end() and self._peek().type != TokenType.RANGLE:
+                    scope_parts.append(self._peek().value)
+                    self._advance()
+                
+                if self._is_at_end():
+                    raise create_parser_error(
+                        message="Unterminated scope selector in expression",
+                        file_path=self.source_file,
+                        line=self._peek().line,
+                        column=self._peek().column,
+                        line_content=self._peek().value,
+                        suggestion="Add a closing '>' to terminate the scope selector"
+                    )
+                
+                self._advance()  # consume >
+                scope_selector = ''.join(scope_parts)
+                
+                # Return variable expression with explicit scope encoded in name
+                return VariableExpression(f"{identifier_name}<{scope_selector}>")
+            
+            # Check if the identifier contains a scope selector (legacy single-token format)
+            elif '<' in identifier_name and identifier_name.endswith('>'):
                 # Extract variable name and scope selector
                 parts = identifier_name.split('<', 1)
                 if len(parts) == 2:

{minecraft_datapack_language-15.4.21.dist-info → minecraft_datapack_language-15.4.23.dist-info}/METADATA

@@ -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.dist-info → minecraft_datapack_language-15.4.23.dist-info}/RECORD

@@ -1,11 +1,11 @@
 minecraft_datapack_language/__init__.py,sha256=i-qCchbe5b2Fshgc6yCU9mddOLs2UBt9SAcLqfUIrT0,606
-minecraft_datapack_language/_version.py,sha256=UOCaFCMuBKEzZuLZKqrQpMf_Fgz3oXnIRu-he6qYSek,708
+minecraft_datapack_language/_version.py,sha256=2M9DVfO2B0gW3xckA3jnSFVOsLpE1n8q1owBMbxNoIU,708
 minecraft_datapack_language/ast_nodes.py,sha256=pgjI2Nlap3ixFPgWqGSkqncG9zB91h5BKgRjtcJqMew,2118
 minecraft_datapack_language/cli.py,sha256=p5A_tEEXugN2NhQFbbgfwi4FxbWYD91RWeKR_A3Vuec,6263
-minecraft_datapack_language/cli_build.py,sha256=u0XIOH_zTARPC6dvWf-411OqrF7RjT7Z9Hkp6hTeZsI,47990
+minecraft_datapack_language/cli_build.py,sha256=hid5hdIwd3NVppBoatkij_OeH9HsBjKTT1WseRdSUs0,48510
 minecraft_datapack_language/cli_check.py,sha256=bPq9gHsxQ1CIiftkrAtRCifWkVAyjp5c8Oay2NNQ1qs,6277
 minecraft_datapack_language/cli_colors.py,sha256=Hr8awY966bGSnVdXL3WnmRhSP1wH56vTQKGt5z-kIQM,7878
-minecraft_datapack_language/cli_help.py,sha256=170MePwG9dV9IowG02SwiRT04fbrEo8FBuREZNwDhXY,20051
+minecraft_datapack_language/cli_help.py,sha256=Rc-v9E2kctsdN_lMunqdKuZ8EZ8rcZIjBCOPrXLBQeE,21363
 minecraft_datapack_language/cli_new.py,sha256=_pj5EeXESAG00C80_os9jONIXAMcsu2eoR8xVJWDw6g,9347
 minecraft_datapack_language/cli_utils.py,sha256=qzba7BRHFK9AliSgSLGtxA0p2_Y-Rm20ysDzLLz_KD4,10632
 minecraft_datapack_language/dir_map.py,sha256=HmxFkuvWGkzHF8o_GFb4BpuMCRc6QMw8UbmcAI8JVdY,1788
@@ -14,12 +14,12 @@ minecraft_datapack_language/linter.py,sha256=7UqbygC5JPCGg-BSOq65NB2xEJBu_OUOYII
 minecraft_datapack_language/mdl_errors.py,sha256=mz6uyPkeBpbMHj4PiAyVecEVJ9_hdSfR45QAjG6oYf0,15690
 minecraft_datapack_language/mdl_lexer_js.py,sha256=VvbhKm727khdSAABxa03hoIIA7H3hWi3RLp9BSXbhY0,28277
 minecraft_datapack_language/mdl_linter.py,sha256=z85xoAglENurCh30bR7kEHZ_JeMxcYaLDcGNRAl-RAI,17253
-minecraft_datapack_language/mdl_parser_js.py,sha256=SQzc67pKls3NVnQaT0xIILGqpZYAmcZn78TQ0KIM4TE,40216
+minecraft_datapack_language/mdl_parser_js.py,sha256=ttnxvZCHKwRu51IL9U0w7WIX1q19qXNJJYt0D4f4a8M,44149
 minecraft_datapack_language/pack.py,sha256=nYiXQ3jgJlDfc4m-65f7C2LFhDRioaUU_XVy6Na4SJI,34625
 minecraft_datapack_language/utils.py,sha256=Aq0HAGlXqj9BUTEjaEilpvzEW0EtZYYMMwOqG9db6dE,684
-minecraft_datapack_language-15.4.21.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
-minecraft_datapack_language-15.4.21.dist-info/METADATA,sha256=mgbuo3_xIVmGi54rRh0IGeS1Oh4aLfbAjtM2b87KUEI,35230
-minecraft_datapack_language-15.4.21.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-minecraft_datapack_language-15.4.21.dist-info/entry_points.txt,sha256=c6vjBeCiyQflvPHBRyBk2nJCSfYt3Oc7Sc9V87ySi_U,108
-minecraft_datapack_language-15.4.21.dist-info/top_level.txt,sha256=ADtFI476tbKLLxEAA-aJQAfg53MA3k_DOb0KTFiggfw,28
-minecraft_datapack_language-15.4.21.dist-info/RECORD,,
+minecraft_datapack_language-15.4.23.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
+minecraft_datapack_language-15.4.23.dist-info/METADATA,sha256=dnH_xWsKU808MSG335P3esNgF5C7H8ujM-O-7hs6nb4,37917
+minecraft_datapack_language-15.4.23.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+minecraft_datapack_language-15.4.23.dist-info/entry_points.txt,sha256=c6vjBeCiyQflvPHBRyBk2nJCSfYt3Oc7Sc9V87ySi_U,108
+minecraft_datapack_language-15.4.23.dist-info/top_level.txt,sha256=ADtFI476tbKLLxEAA-aJQAfg53MA3k_DOb0KTFiggfw,28
+minecraft_datapack_language-15.4.23.dist-info/RECORD,,