minecraft-datapack-language 17.0.10__py3-none-any.whl → 17.0.12__py3-none-any.whl

minecraft_datapack_language/_embedded/docs/_docs/multi-file-projects.md

@@ -0,0 +1,221 @@
+---
+layout: page
+title: Multi-File Projects
+permalink: /docs/multi-file-projects/
+---
+
+MDL supports organizing code across multiple files for better project structure.
+
+## Basic Multi-File Setup
+
+### Main File (with 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<global> = 0;
+
+function "init" {
+    playerCount<global> = 0;
+    say "Core system initialized!";
+}
+
+on_load core:init;
+```
+
+### Additional Files (no pack declaration)
+
+Other files don't need pack declarations:
+
+```mdl
+// ui.mdl
+namespace "ui";
+
+function ui:show_hud {
+    tellraw @a {"text":"Players: $playerCount<global>$","color":"green"};
+}
+
+function ui:update_hud {
+    exec ui:show_hud<@a>;
+}
+```
+
+```mdl
+// game.mdl
+namespace "game";
+
+function game:start {
+    say "Game started!";
+    exec ui:update_hud;
+}
+```
+
+## Building Multi-File Projects
+
+### Build All Files Together
+
+```bash
+mdl build --mdl . -o dist
+```
+
+### Build Entire Directory
+
+```bash
+mdl build --mdl myproject/ -o dist
+```
+
+### Build with Wildcards
+
+```bash
+mdl build --mdl "*.mdl" -o dist
+```
+
+## Namespace Organization
+
+Each file can have its own namespace to prevent conflicts:
+
+```mdl
+// combat.mdl
+namespace "combat";
+
+var num damage = 10;  // Defaults to player-specific scope
+
+function "attack" {
+    say Attack damage: $damage$;
+}
+```
+
+```mdl
+// magic.mdl
+namespace "magic";
+
+var num mana = 100;  // Defaults to player-specific scope
+
+function magic:cast_spell {
+    if $mana$ >= 20 {
+        mana = $mana$ - 20;
+        say "Spell cast! Mana: $mana$";
+    }
+}
+```
+
+## Variable Sharing
+
+Variables from all files are automatically merged:
+
+```mdl
+// core.mdl
+var num globalTimer<global> = 0;
+var num playerScore = 0;  // Defaults to player-specific scope
+```
+
+```mdl
+// ui.mdl
+namespace "ui";
+function ui:show_stats {
+    tellraw @a {"text":"Timer: $globalTimer<global>$, Score: $playerScore$","color":"gold"};
+}
+```
+
+<!-- Removed redundant Explicit Scopes in Conditions section as requested -->
+
+## Complete Multi-File Example
+
+Here's a complete example with multiple files:
+
+**`main.mdl`**:
+```mdl
+pack "adventure" "Adventure game" 82;
+namespace "core";
+
+var num gameState<@a> = 0;
+var num playerLevel = 1;  // Defaults to player-specific scope
+
+function "init" {
+    gameState<@a> = 0;
+    playerLevel<@s> = 1;
+    say Adventure game initialized!;
+}
+
+on_load "core:init";
+```
+
+**`combat.mdl`**:
+```mdl
+namespace "combat";
+
+var num playerHealth = 20;  // Defaults to player-specific scope
+
+function "attack" {
+    say Attacking! Health: $playerHealth$;
+}
+
+function "heal" {
+    if "$playerHealth$ < 20" {
+        playerHealth<@s> = playerHealth<@s> + 5;
+        say Healed! Health: $playerHealth$;
+    }
+}
+```
+
+**`ui.mdl`**:
+```mdl
+namespace "ui";
+
+function "show_status" {
+    tellraw @a {"text":"Level: $playerLevel$, Health: $playerHealth$","color":"aqua"};
+}
+
+function "update_ui" {
+    function "ui:show_status<@a>";
+}
+```
+
+**`game.mdl`**:
+```mdl
+namespace "game";
+
+function game:start {
+    gameState<global> = 1;
+    say "Game started!";
+    exec ui:update_ui;
+}
+
+function game:level_up {
+    if "$playerLevel$ < 10" {
+        playerLevel<@s> = playerLevel<@s> + 1;
+        say "Level up! New level: $playerLevel$";
+    }
+}
+```
+
+Build the project:
+```bash
+mdl build --mdl . -o dist
+```
+
+## Best Practices
+
+1. **One namespace per file**: Keep related functionality together
+2. **Main file first**: Put the file with pack declaration first
+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 `<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
+
+```
+my_project/
+├── main.mdl          # Pack declaration, core variables
+├── combat.mdl        # Combat system
+├── magic.mdl         # Magic system
+├── ui.mdl           # User interface
+├── game.mdl         # Game logic
+└── utils.mdl        # Utility functions
+```

minecraft_datapack_language/_embedded/docs/_docs/python-bindings.md

@@ -0,0 +1,446 @@
+---
+layout: page
+title: Python Bindings
+permalink: /docs/python-bindings/
+---
+
+The MDL Python bindings provide a clean, programmatic way to create Minecraft datapacks. They're fully compatible with the MDL language and support variables, control flow, nested functions, and MDL's scope system (default `@s`, explicit selectors, and `<global>`).
+
+## Quick Start
+
+```python
+from minecraft_datapack_language import Pack
+
+# Create a datapack
+p = Pack("My Pack", "A cool datapack", 82)
+
+# Add a namespace
+ns = p.namespace("example")
+
+# Add functions
+ns.function("hello", "say Hello World!")
+ns.function("welcome", "tellraw @a {\"text\":\"Welcome!\",\"color\":\"green\"}")
+
+# Hook into Minecraft lifecycle
+p.on_load("example:hello")
+p.on_tick("example:welcome")
+
+# Build the datapack
+p.build("dist")
+```
+
+## Core Classes
+
+### Pack
+
+The main class for creating datapacks.
+
+```python
+from minecraft_datapack_language import Pack
+
+# Create a pack
+p = Pack(
+    name="My Pack",           # Pack name
+    description="Description", # Optional description
+    pack_format=82            # Minecraft pack format
+)
+```
+
+**Methods:**
+- `namespace(name)` - Create a namespace
+- `on_load(function_id)` - Hook function to world load
+- `on_tick(function_id)` - Hook function to tick
+- `tag(registry, name, values=[], replace=False)` - Create tags
+- `build(output_dir)` - Build the datapack
+
+### Namespace
+
+Represents a namespace for organizing functions.
+
+```python
+ns = p.namespace("example")
+
+# Add functions to the namespace
+ns.function("function_name", "command1", "command2", ...)
+```
+
+**Methods:**
+- `function(name, *commands)` - Add a function with commands
+
+### Control Flow and Expressions (Bindings)
+
+Bindings include helpers to compose expressions and control flow identical to MDL:
+
+```python
+from minecraft_datapack_language import Pack
+from minecraft_datapack_language.python_api import num, var_read, binop
+
+p = Pack("Control Flow", "desc", 82)
+ns = p.namespace("game")
+
+def build_logic(fb):
+    # declare variable
+    fb.declare_var("counter", "<@s>", 0)
+
+    # counter<@s> = $counter<@s>$ + 1
+    fb.set("counter", "<@s>", binop(var_read("counter", "<@s>"), "PLUS", num(1)))
+
+    # if $counter<@s>$ > 5 { say "hi" } else { say "low" }
+    cond = binop(var_read("counter", "<@s>"), "GREATER", num(5))
+    fb.if_(cond, lambda t: t.say("hi"), lambda e: e.say("low"))
+
+    # while $counter<@s>$ < 10 { counter<@s> = $counter<@s>$ + 1 }
+    wcond = binop(var_read("counter", "<@s>"), "LESS", num(10))
+    fb.while_(wcond, lambda b: b.set("counter", "<@s>", binop(var_read("counter", "<@s>"), "PLUS", num(1))))
+
+ns.function("main", build_logic)
+p.build("dist")
+```
+
+## Basic Examples
+
+### Hello World
+
+```python
+from minecraft_datapack_language import Pack
+
+def create_hello_world():
+    p = Pack("Hello World", "A simple hello world datapack", 82)
+    
+    ns = p.namespace("example")
+    ns.function("hello", 
+        "say Hello, Minecraft!",
+        "tellraw @a {\"text\":\"Welcome to my datapack!\",\"color\":\"green\"}"
+    )
+    
+    # Hook into world load
+    p.on_load("example:hello")
+    
+    return p
+
+# Create and build
+pack = create_hello_world()
+pack.build("dist")
+```
+
+### Particle Effects
+
+```python
+from minecraft_datapack_language import Pack
+
+def create_particle_pack():
+    p = Pack("Particle Effects", "Creates particle effects around players", 82)
+    
+    ns = p.namespace("particles")
+    
+    ns.function("tick",
+        "execute as @a run particle minecraft:end_rod ~ ~ ~ 0.1 0.1 0.1 0.01 1",
+        "execute as @a run particle minecraft:firework ~ ~ ~ 0.2 0.2 0.2 0.02 2"
+    )
+    
+    ns.function("init", "say Particle effects enabled!")
+    
+    # Hook into lifecycle
+    p.on_load("particles:init")
+    p.on_tick("particles:tick")
+    
+    return p
+```
+
+## Advanced Features
+
+### Variables and Control Flow
+The bindings support MDL's scope model (default @s and explicit selectors):
+
+```python
+from minecraft_datapack_language import Pack
+
+def create_advanced_pack():
+    p = Pack("Advanced Features", "Demonstrates advanced features", 82)
+    
+    ns = p.namespace("advanced")
+    
+    # Functions with variables and control flow
+    ns.function("variable_demo",
+        "var num counter<global> = 0",
+        "counter<global> = 10",
+        "counter<global> = counter<global> + 5",
+        "if $counter<global>$ >= 15 {",
+        "    say Counter is 15!",
+        "    counter<global> = counter<global> - 5",
+        "}"
+    )
+    
+    ns.function("control_flow_demo",
+        "var num playerHealth = 20",
+        "if $playerHealth$ < 10 {",
+        "    say Health is low!",
+        "    playerHealth = playerHealth + 5",
+        "} else {",
+        "    say Health is good",
+        "}"
+    )
+    
+    ns.function("loop_demo",
+        "var num countdown<global> = 5",
+        "while $countdown<global>$ > 0 {",
+        "    say Countdown: $countdown<global>$",
+        "    countdown<global> = countdown<global> - 1",
+        "}",
+        "say Blast off!"
+    )
+    
+    p.on_tick("advanced:variable_demo")
+    p.on_tick("advanced:control_flow_demo")
+    p.on_tick("advanced:loop_demo")
+    
+    return p
+```
+
+### Function Calls and Cross-Namespace References
+
+```python
+from minecraft_datapack_language import Pack
+
+def create_function_pack():
+    p = Pack("Function Calls", "Demonstrates function calls", 82)
+    
+    # Core namespace
+    core = p.namespace("core")
+    core.function("init", "say Initializing...")
+    core.function("tick", "say Tick...")
+    
+    # Utility namespace
+    util = p.namespace("util")
+    util.function("helper", "say Helper function")
+    util.function("helper2", "say Another helper")
+    
+    # Main namespace with cross-namespace calls
+    main = p.namespace("main")
+    main.function("start",
+        "say Starting...",
+        "function core:init",
+        "function util:helper"
+    )
+    
+    main.function("update",
+        "function core:tick",
+        "function util:helper2"
+    )
+    
+    # Lifecycle hooks
+    p.on_load("main:start")
+    p.on_tick("main:update")
+    
+    return p
+```
+
+### Tags and Data
+
+```python
+from minecraft_datapack_language import Pack
+
+def create_tag_pack():
+    p = Pack("Tags and Data", "Demonstrates tags and data", 82)
+    
+    ns = p.namespace("example")
+    ns.function("init", "say Tags initialized!")
+    
+    # Function tags
+    p.tag("function", "minecraft:load", values=["example:init"])
+    p.tag("function", "minecraft:tick", values=["example:tick"])
+    
+    # Item tags
+    p.tag("item", "example:swords", values=[
+        "minecraft:diamond_sword",
+        "minecraft:netherite_sword"
+    ])
+    
+    # Block tags
+    p.tag("block", "example:glassy", values=[
+        "minecraft:glass",
+        "minecraft:tinted_glass"
+    ])
+    
+    return p
+```
+
+## Integration with MDL Files
+You can use the Python bindings alongside MDL files:
+
+```python
+from minecraft_datapack_language import Pack
+from minecraft_datapack_language.mdl_parser import MDLParser
+
+def create_hybrid_pack():
+    # Parse MDL file
+    with open("my_functions.mdl", "r") as f:
+        mdl_content = f.read()
+    
+    ast = MDLParser().parse(mdl_content)
+    
+    # Create pack via Python bindings
+    p = Pack("Hybrid Pack", "Combines MDL and Python", 82)
+    
+    # Add functions from MDL (placeholder emission; compile MDL separately when mixing)
+    for func in ast.functions:
+        ns = p.namespace(func.namespace)
+        ns.function(func.name, "say Imported from MDL via parser")
+    
+    # Add additional functions via Python bindings
+    ns = p.namespace("python")
+    ns.function("python_func", "say Created via Python API!")
+    
+    return p
+```
+
+## Best Practices
+
+### 1. Organize by Namespace
+
+```python
+def create_organized_pack():
+    p = Pack("Organized Pack", "Well-organized datapack", 82)
+    
+    # Core systems
+    core = p.namespace("core")
+    core.function("init", "say Initializing...")
+    core.function("tick", "say Tick...")
+    
+    # Feature modules
+    combat = p.namespace("combat")
+    ui = p.namespace("ui")
+    data = p.namespace("data")
+    
+    # Each namespace handles its own functionality
+    return p
+```
+
+### 2. Use Function Composition
+
+```python
+def create_composable_pack():
+    p = Pack("Composable Pack", "Uses function composition", 82)
+    
+    ns = p.namespace("example")
+    
+    # Small, focused functions
+    ns.function("check_player", "execute if entity @s[type=minecraft:player]")
+    ns.function("give_effect", "effect give @s minecraft:speed 10 1")
+    ns.function("send_message", "tellraw @s {\"text\":\"Effect applied!\",\"color\":\"green\"}")
+    
+    # Compose functions
+    ns.function("player_effects",
+        "function example:check_player run function example:give_effect",
+        "function example:check_player run function example:send_message"
+    )
+    
+    return p
+```
+
+### 3. Error Handling
+
+```python
+def create_robust_pack():
+    p = Pack("Robust Pack", "Handles errors gracefully", 82)
+    
+    ns = p.namespace("robust")
+    
+    # Always check conditions before operations
+    ns.function("safe_operation",
+        "execute if entity @a run say Players found",
+        "execute unless entity @a run say No players found",
+        "execute if entity @a run effect give @a minecraft:speed 5 1"
+    )
+    
+    return p
+```
+
+## Complete Example
+Here's a complete example that demonstrates all features including the explicit scope system:
+
+```python
+from minecraft_datapack_language import Pack
+
+def create_complete_pack():
+    """Create a complete datapack demonstrating all features."""
+    
+    # Create the pack
+    p = Pack("Complete Example", "Demonstrates all MDL features", 82)
+    
+    # Core namespace
+    core = p.namespace("core")
+    core.function("init",
+        "var num gameState<global> = 0",
+        "var num playerLevel = 1",
+        "gameState<global> = 0",
+        "playerLevel = 1",
+        "say [core:init] Initializing Complete Example...",
+        "tellraw @a {\"text\":\"Complete Example loaded!\",\"color\":\"green\"}",
+        "scoreboard objectives add example_counter dummy \"Example Counter\""
+    )
+    
+    core.function("tick",
+        "gameState<global> = gameState<global> + 1",
+        "say [core:tick] Core systems running... Game state: $gameState<global>$",
+        "execute as @a run particle minecraft:end_rod ~ ~ ~ 0.1 0.1 0.1 0.01 1"
+    )
+    
+    # Combat namespace
+    combat = p.namespace("combat")
+    combat.function("weapon_effects",
+        "execute as @a[nbt={SelectedItem:{id:\"minecraft:diamond_sword\"}}] run effect give @s minecraft:strength 1 0 true",
+        "execute as @a[nbt={SelectedItem:{id:\"minecraft:golden_sword\"}}] run effect give @s minecraft:speed 1 0 true"
+    )
+    
+    combat.function("update_combat",
+        "function core:tick",
+        "function combat:weapon_effects"
+    )
+    
+    # UI namespace
+    ui = p.namespace("ui")
+    ui.function("hud",
+        "title @a actionbar {\"text\":\"Complete Example Active - Level: $playerLevel$\",\"color\":\"gold\"}"
+    )
+    
+    ui.function("update_ui",
+        "function ui:hud",
+        "function combat:update_combat"
+    )
+    
+    # Data namespace
+    data = p.namespace("data")
+    data.function("setup_data",
+        "say Setting up data..."
+    )
+    
+    # Lifecycle hooks
+    p.on_load("core:init")
+    p.on_tick("ui:update_ui")
+    
+    # Function tags
+    p.tag("function", "minecraft:load", values=["core:init"])
+    p.tag("function", "minecraft:tick", values=["ui:update_ui"])
+    
+    # Data tags
+    p.tag("item", "example:swords", values=[
+        "minecraft:diamond_sword",
+        "minecraft:netherite_sword"
+    ])
+    
+    p.tag("block", "example:glassy", values=[
+        "minecraft:glass",
+        "minecraft:tinted_glass"
+    ])
+    
+    return p
+
+# Create and build the pack
+if __name__ == "__main__":
+    pack = create_complete_pack()
+    pack.build("dist")
+    print("Complete example pack built successfully!")
+```
+
+The Python bindings provide a powerful, flexible way to create Minecraft datapacks with full support for the MDL language features including scopes and control flow.