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

minecraft_datapack_language/_embedded/docs/_docs/documentation.md

@@ -0,0 +1,135 @@
+---
+layout: page
+title: Documentation
+permalink: /docs/documentation/
+description: Complete documentation for the Minecraft Datapack Language (MDL)
+---
+
+Welcome to the complete documentation for the Minecraft Datapack Language (MDL). This guide will help you get started and master all aspects of MDL development.
+
+## Getting Started
+
+{% assign getting_started = site.nav | where: "title", "Getting Started" | first %}
+- **[Getting Started]({{ getting_started.url }})** - Learn the basics of MDL and set up your development environment
+
+## Core Documentation
+
+{% assign language_ref = site.nav | where: "title", "Language Reference" | first %}
+{% assign multi_file = site.nav | where: "title", "Multi-file Projects" | first %}
+{% assign cli_ref = site.nav | where: "title", "CLI Reference" | first %}
+{% assign python_api = site.nav | where: "title", "Python Bindings" | first %}
+
+- **[Language Reference]({{ language_ref.url }})** - Complete syntax and language features
+- **[Multi-file Projects]({{ multi_file.url }})** - How to organize and structure larger MDL projects
+- **[CLI Reference]({{ cli_ref.url }})** - Command-line interface usage and options
+- **[Python Bindings]({{ python_api.url }})** - Programmatic access to MDL functionality
+
+## Tools and Extensions
+
+{% assign vscode = site.nav | where: "title", "VS Code Extension" | first %}
+
+- **[VS Code Extension]({{ vscode.url }})** - Enhanced development experience with syntax highlighting and IntelliSense
+
+## Contributing
+
+{% assign contributing = site.nav | where: "title", "Contributing" | first %}
+
+- **[Contributing]({{ contributing.url }})** - How to contribute to the MDL project
+
+## Quick Navigation
+
+<div class="doc-grid">
+  <div class="doc-card">
+    <h3>🚀 Getting Started</h3>
+    <p>New to MDL? Start here to learn the fundamentals and set up your environment.</p>
+    <a href="{{ getting_started.url }}" class="doc-link">Get Started →</a>
+  </div>
+  
+  <div class="doc-card">
+    <h3>📚 Language Reference</h3>
+    <p>Complete syntax reference, data types, functions, and language features.</p>
+    <a href="{{ language_ref.url }}" class="doc-link">View Reference →</a>
+  </div>
+  
+  <div class="doc-card">
+    <h3>🔧 CLI Tools</h3>
+    <p>Command-line interface for building, testing, and managing MDL projects.</p>
+    <a href="{{ cli_ref.url }}" class="doc-link">CLI Guide →</a>
+  </div>
+  
+  <div class="doc-card">
+    <h3>📁 Multi-file Projects</h3>
+    <p>Learn how to organize and structure larger, more complex MDL projects.</p>
+    <a href="{{ multi_file.url }}" class="doc-link">Project Structure →</a>
+  </div>
+  
+  <div class="doc-card">
+    <h3>🐍 Python Bindings</h3>
+    <p>Programmatic access to MDL functionality for automation and integration.</p>
+    <a href="{{ python_api.url }}" class="doc-link">API Reference →</a>
+  </div>
+  
+  <div class="doc-card">
+    <h3>💻 VS Code Extension</h3>
+    <p>Enhanced development experience with syntax highlighting and IntelliSense.</p>
+    <a href="{{ vscode.url }}" class="doc-link">Extension Guide →</a>
+  </div>
+</div>
+
+<style>
+.doc-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
+  gap: 1.5rem;
+  margin: 2rem 0;
+}
+
+.doc-card {
+  background: #ffffff;
+  border: 1px solid #e1e4e8;
+  border-radius: 8px;
+  padding: 1.5rem;
+  box-shadow: 0 4px 12px rgba(0,0,0,0.15);
+  transition: transform 0.2s, box-shadow 0.2s;
+}
+
+.doc-card:hover {
+  transform: translateY(-2px);
+  box-shadow: 0 6px 20px rgba(0,0,0,0.2);
+}
+
+.doc-card h3 {
+  margin: 0 0 0.5rem 0;
+  color: #24292e;
+  font-size: 1.1rem;
+}
+
+.doc-card p {
+  margin: 0 0 1rem 0;
+  color: #586069;
+  line-height: 1.5;
+}
+
+.doc-link {
+  display: inline-block;
+  color: #0366d6;
+  text-decoration: none;
+  font-weight: 500;
+  padding: 0.5rem 1rem;
+  border: 1px solid #0366d6;
+  border-radius: 6px;
+  transition: background-color 0.2s, color 0.2s;
+}
+
+.doc-link:hover {
+  background: #0366d6;
+  color: #ffffff;
+  text-decoration: none;
+}
+
+@media (max-width: 768px) {
+  .doc-grid {
+    grid-template-columns: 1fr;
+  }
+}
+</style>

minecraft_datapack_language/_embedded/docs/_docs/examples.md

@@ -0,0 +1,194 @@
+---
+layout: page
+title: MDL Examples
+permalink: /docs/examples/
+---
+
+This page contains working examples of MDL features.
+
+## Basic Hello World
+
+A simple datapack that says hello when loaded:
+
+```mdl
+pack "hello" "A simple hello world datapack" 82;
+namespace "hello";
+
+function hello:main {
+    say "Hello, Minecraft!";
+    tellraw @a {"text":"Welcome to my datapack!","color":"green"};
+}
+
+on_load hello:main;
+```
+
+## Logical Operators and Precedence
+
+```mdl
+pack "logicalops" "Generated by MDL CLI" 82;
+namespace "logicalops";
+
+// Variables (default scope @s)
+var num a = 0;
+var num b = 0;
+
+// Main function
+function logicalops:main {
+    say "Hello from logicalops!";
+    exec logicalops:add<@a>;
+}
+
+function logicalops:init {
+    a = 1;
+    b = 2;
+}
+
+function logicalops:add {
+    var result = $a$ + $b$;
+    say "Result: $result$";
+}
+
+function logicalops:subtract {
+    var result = $a$ - $b$;
+    say "Result: $result$";
+}
+
+function logicalops:multiply {
+    var result = $a$ * $b$;
+    say "Result: $result$";
+}
+
+function logicalops:divide {
+    var result = $a$ / $b$;
+    say "Result: $result$";
+}
+
+function logicalops:andop {
+    if $a$ > 0 && $b$ > 0 {
+        say "Both are greater than 0";
+    } else {
+        say "At least one is not greater than 0";
+    }
+}
+
+function logicalops:orop {
+    if $a$ > 0 || $b$ > 0 {
+        say "At least one is greater than 0";
+    } else {
+        say "Both are not greater than 0";
+    }
+}
+
+function logicalops:notop {
+    if !$a$ > 0 {
+        say "a is not greater than 0";
+    } else {
+        say "a is greater than 0";
+    }
+}
+
+function logicalops:whileloop {
+    a = 0;
+    while $a$ < 10 {
+        say "a is less than 10";
+        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 = 0;
+    scheduledwhile $a$ < 10 {
+        say "a is less than 10";
+        a = $a$ + 1;
+    }
+}
+
+function logicalops:complexops {
+    var c = 5;
+    var d = 10;
+    var e = 15;
+    var f = 20;
+    var g = 2;
+    var h = 0;
+    h = $h$ - 1;
+
+    var result = ($c$ + $d$ - $e$ * $f$ / $g$) * $h$;
+
+    if !$result$ == 135 {
+        say "Result is not 135, there is an issue!";
+    } else {
+        say "Result is -135, everything is good!";
+    }
+}
+
+on_load logicalops:main;
+```
+
+<!-- Trimmed non-core examples to focus on core language concepts -->
+
+## Raw Commands
+
+Using raw Minecraft commands:
+
+```mdl
+pack "raw" "Raw command example" 82;
+namespace "raw";
+
+function raw:custom {
+    // 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;
+```
+
+## Function Macros
+
+Demonstrates macro lines and passing macro data to functions:
+
+```mdl
+pack "macros" "Function macro examples" 82;
+namespace "macros";
+
+// Target function using a macro line with $(name)
+function macros:greeter {
+    $say "Hello $(name)"
+    say "Done";
+}
+
+// Callers using inline JSON and with-clause
+function macros:callers {
+    // Inline JSON compound (prefer single quotes outside)
+    exec macros:greeter '{name:"Alex"}';
+
+    // Pull compound from a data source via with-clause
+    exec macros:greeter with storage macros:ctx player.info;
+}
+
+on_load macros:callers;
+```
+
+## Fan-out Execution Pattern
+
+Run a function once per matching entity using an outer exec scope, then use default `@s` inside:
+
+```mdl
+pack "fanout" "Fan-out example" 82;
+namespace "fanout";
+
+var num visits<@s> = 0;
+
+function fanout:increment {
+    // Runs per-entity; scope defaults to @s inside
+    visits = $visits$ + 1;
+    say "Visits: $visits$";
+}
+
+// Fan out to all players on load
+on_load fanout:increment<@a>;
+```
+
+

minecraft_datapack_language/_embedded/docs/_docs/getting-started.md

@@ -0,0 +1,230 @@
+---
+layout: page
+title: Getting Started
+permalink: /docs/getting-started/
+---
+
+MDL (Minecraft Datapack Language) is a simple language that compiles to Minecraft datapack `.mcfunction` files.
+
+## Installation
+
+Install MDL using pipx:
+
+```bash
+pipx install minecraft-datapack-language
+```
+
+## Quick Start
+
+Create your first MDL file:
+
+```mdl
+// hello.mdl
+pack "hello" "My first datapack" 82;
+namespace "hello";
+
+function hello:main {
+    say "Hello, Minecraft!";
+    tellraw @a {"text":"Welcome to my datapack!","color":"green"};
+}
+
+on_load hello:main;
+```
+
+Compile it:
+
+```bash
+mdl build
+```
+
+The compiled datapack will be in the `dist` folder. Copy it to your Minecraft world's `datapacks` folder and run `/reload` in-game.
+
+## Basic Concepts
+
+### Variables
+
+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 @s)
+var num playerScore = 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 (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$` or `$variable<scope>$` to read variable values. If the scope is omitted, it defaults to `@s`:
+
+```mdl
+say "Your score: $playerScore$";
+tellraw @a {"text":"Global counter: $globalCounter<global>$","color":"gold"};
+
+if $playerScore$ > 100 {
+    say "High score!";
+}
+```
+
+### Functions
+
+Functions contain Minecraft commands:
+
+```mdl
+function hello:my_function {
+    say "This is my function!";
+    effect give @s minecraft:speed 10 1;
+}
+
+// Call a function
+exec hello:my_function<@s>;
+
+// Call a function for all players
+exec hello:my_function<@a>;
+```
+
+### Control Structures
+
+MDL supports real if/else statements and while loops:
+
+```mdl
+// If statement
+if $playerScore$ > 50 {
+    say "Great job!";
+} else {
+    say "Keep trying!";
+}
+
+// While loop
+while $counter$ < 5 {
+    say "Counter: $counter$";
+    counter = counter + 1;
+}
+```
+
+### Reading with Explicit 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 {
+    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 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
+```
+
+## Complete Example
+
+Here's a complete example that demonstrates all the basic features:
+
+```mdl
+pack "example" "Complete example" 82;
+namespace "example";
+
+// Variables
+var num playerScore = 0;  // Defaults to player-specific scope (@s)
+var num globalTimer<global> = 0;
+
+// Initialize function
+function "init" {
+    playerScore = 0;
+    globalTimer<global> = 0;
+    say "Game initialized!";
+}
+
+// Update function
+function "update" {
+    globalTimer<global> = globalTimer<global> + 1;
+    
+    if $playerScore$ > 100 {
+        say "High score!";
+        tellraw @a {"text":"Player has a high score!","color":"gold"};
+    }
+    
+    if $globalTimer<global>$ >= 1200 {  // 60 seconds
+        globalTimer<global> = 0;
+        say "Time's up!";
+    }
+}
+
+// Score function
+function "add_score" {
+    playerScore = playerScore + 10;
+    say "Score: $playerScore$";
+}
+
+// Hooks
+on_load example:init;
+on_tick example:update;
+```
+
+## Building and Testing
+
+### Single File
+```bash
+mdl build --mdl myfile.mdl
+```
+
+### Build a directory (multiple files)
+```bash
+mdl build
+```
+
+### Directory (explicit path)
+```bash
+mdl build --mdl myproject/
+```
+
+### Checking
+```bash
+# Check current directory
+mdl check
+
+# Check a specific directory
+mdl check myproject/
+```
+
+### Testing
+1. Copy the `dist` folder to your Minecraft world's `datapacks` folder
+2. Run `/reload` in-game
+3. Test your functions with `/function namespace:function_name`
+
+## Next Steps
+
+- Read the [Language Reference](https://www.mcmdl.com/docs/language-reference/) for complete syntax
+- Check out [Examples](https://www.mcmdl.com/docs/examples/) for more complex examples
+- Learn about [Multi-file Projects](https://www.mcmdl.com/docs/multi-file-projects/) for larger datapacks