MC Looper Usage Guide

🚀 Getting Started

Installation & Controls

Key Bindings:

Right Shift - Open Loop Editor
P - Pause/Resume all loops

Basic Concepts

MC Looper works with Loops that contain:

Triggers - When the loop should run
Blocks - What actions to perform
Conditions - Logic for decision making
Variables - Store and manipulate data

Creating Your First Loop

Press Right Shift to open the editor
Click "Add Loop" to create a new loop
Set the loop name and configure the trigger
Add blocks to define what the loop does
Click "Save" to save your configuration

⚡ Triggers

Triggers determine when your loops execute. Each loop has one trigger.

📋 manual

Manually triggered from the UI

Parameters:

None - triggered by clicking "Run Loop"

Use cases: Testing, one-time actions, debug scripts

🌍 on_start

Triggers when you join a world

Parameters:

None - automatically triggers on world join

Use cases: Setup scripts, welcome messages, initialization

⏱️ interval

Triggers at regular intervals

Parameters:

interval - Time between triggers (number or [min-max] for random)
unit - "ticks" or "seconds" (default: ticks)

Examples:

Every 100 ticks: interval: 100, unit: ticks
Every 5 seconds: interval: 5, unit: seconds
Random 10-30 seconds: interval: [10-30], unit: seconds

Use cases: Farming, monitoring, periodic checks

💬 on_chat

Triggers when chat messages match a regex pattern

Parameters:

pattern - Regex pattern to match
var_prefix - Variable prefix for capture groups
verbose - Show captured variables (true/false)

Examples:

Death messages: pattern: "You died"
Player mentions: pattern: "@(\\w+)", var_prefix: "mention"
Server announcements: pattern: "\\[Server\\] (.*)"

Use cases: Auto-responses, death handling, server event reactions

🖼️ on_gui_item

Triggers when GUI items match a regex pattern

Parameters:

pattern - Regex pattern to match item names
var_prefix - Variable prefix for capture groups
verbose - Show captured variables (true/false)

Examples:

Shop items: pattern: "Buy (.*) for (\\d+)"
Quest items: pattern: "Complete Quest"

Use cases: Shop automation, quest completion, GUI interactions

🧱 Blocks (Actions)

Blocks are the actions your loops perform. They execute in sequence.

Communication Blocks

💬 chat

Sends messages or commands to the server

Parameters:

message - Text to send (prefix with / for commands)

Examples:

Chat: message: "Hello everyone!"
Command: message: "/tp spawn"
With variables: message: "My position: ${player_x}, ${player_y}, ${player_z}"

📱 client_message

Shows messages only to you (not sent to server)

Parameters:

message - Text to display locally

Examples:

Status: message: "Loop started successfully"
Debug: message: "Variable value: ${my_var}"

📝 comment

Documentation only - does nothing during execution

Parameters:

text - Comment text for documentation

Timing & Flow Control

⏳ wait

Pauses execution for a specified time

Parameters:

time - Duration (number or [min-max] for random)
unit - "ticks" or "seconds" (default: ticks)

Examples:

Wait 2 seconds: time: 2, unit: seconds
Random 50-100 ticks: time: [50-100], unit: ticks

🔄 call_loop

Executes another loop

Parameters:

loop - Name of the loop to call

🔀 if

Conditional execution - stops loop if condition fails

Parameters:

condition - Condition to evaluate
blocks - Blocks to execute if true
verbose - Show variable states (true/false)

🔁 loop

Repeats nested blocks multiple times

Parameters:

count - Number of repetitions
blocks - Blocks to repeat

🚪 exit

Immediately stops the current loop execution

Parameters:

None - this block has no configuration options

Use cases:

Emergency stops based on conditions
Early termination when goals are reached
Error handling and safe shutdown

⏰ wait_until

Waits until a condition becomes true

Parameters:

condition - Condition to wait for

🚫 prevent_execution

Prevents the current loop from running for a duration

Parameters:

time - Duration to prevent
unit - "ticks" or "seconds"

Interaction Blocks

🖱️ click_gui_item

Auto-clicks GUI items by name pattern (excludes inventory)

Parameters:

name_pattern - Regex pattern to match item names
var_name - Variable to store matched text

Examples:

Click confirm: name_pattern: "Click to Confirm"
Buy items: name_pattern: "Buy (.*)", var_name: "item"

🌍 world_click

Clicks in the world - left (break/attack) or right (place/use)

Parameters:

click_type - "left" or "right"
target - "crosshair" or "x,y,z" coordinates (supports variables)
pause_on_gui - Pause clicking when GUI is open (true/false)

Examples:

Right-click: click_type: "right", target: "crosshair"
Break block: click_type: "left", target: "100,64,200"
Variable coords: target: "${x},${y},${z}"
Safe mining: pause_on_gui: true (stops when chests open)

Data & Network Blocks

🌐 post_request

Sends HTTP POST requests with timeout and response capture

Parameters:

url - Request URL
body - JSON request body
timeout - Timeout in milliseconds (default: 5000)
response_var - Variable prefix for response

Response Variables:

${response_var}_code - HTTP status code
${response_var}_body - Response body
${response_var}_success - Success boolean
${response_var}_error - Error message (if failed)

🔤 regex_replace

Performs regex find/replace on variables

Parameters:

source_var - Variable to read from
target_var - Variable to write to
pattern - Regex pattern to find
replacement - Replacement text
verbose - Show operation details

❓ Conditions

Conditions are used in if and wait_until blocks for decision making.

📊 variable_equals

Compares a variable to an expected value (string comparison)

Parameters:

variable - Variable name to check
value - Expected value

Example:

{
  "type": "variable_equals",
  "params": {
    "variable": "player_health",
    "value": "20"
  }
}

📈 variable_greater_than

Numeric comparison - checks if variable is greater than value

Parameters:

variable - Variable name to check
value - Numeric threshold

🎒 inventory_contains

Checks if inventory contains specific items

Parameters:

search_mode - "registry" or "regex"
item_name - Item to find (registry mode)
regex_pattern - Pattern to match (regex mode)
var_name - Variable to store found item info
verbose - Show found item details

Created Variables:

${var_name} - Display name
${var_name}_registry - Registry name
${var_name}_count - Item count

🖼️ gui_contains

Checks if current GUI contains specific items

Parameters:

Same as inventory_contains, plus:

${var_name}_slot - Slot index of found item

🔍 gui_item_exists

Checks if GUI item with matching name pattern exists

Parameters:

name_pattern - Regex pattern to match
var_name - Variable to store matched text
verbose - Show match details

Created Variables:

${var_name} - Matched text
${var_name}_1, ${var_name}_2... - Capture groups

📋 Variables

Variables store and manipulate data throughout your loops.

Variable Types

🔄 Runtime Variables

Temporary variables cleared when leaving world. Created by blocks and conditions.

⚙️ Config Variables

Persistent variables stored in configuration files.

🎮 Built-in Minecraft Variables

${player_name} - Your username
${player_x}, ${player_y}, ${player_z} - Your coordinates
${world_name} - Current world name
${server_name} - Server name (if on server)
${timestamp} - Current timestamp

Variable Usage

Variable Replacement:

Use ${variable_name} in any string parameter to insert variable values.

Examples:

"Hello ${player_name}!"
"Position: ${player_x}, ${player_y}, ${player_z}"
"Found item: ${found_item}"

Verbose Mode

Enable verbose mode in triggers and blocks to see variable states during execution. Useful for debugging.

💡 Example Configurations

🌱 Auto Farm Monitor

Checks crops every 30 seconds and sends status updates

{
  "name": "Farm Monitor",
  "trigger": {
    "type": "interval",
    "params": {
      "interval": 30,
      "unit": "seconds"
    }
  },
  "blocks": [
    {
      "type": "world_click",
      "params": {
        "click_type": "right",
        "target": "crosshair"
      }
    },
    {
      "type": "wait",
      "params": {
        "time": 1,
        "unit": "seconds"
      }
    },
    {
      "type": "chat",
      "params": {
        "message": "Farm check complete at ${timestamp}"
      }
    }
  ]
}

💀 Death Response

Automatically responds when player dies

{
  "name": "Death Handler",
  "trigger": {
    "type": "on_chat",
    "params": {
      "pattern": "You died",
      "verbose": true
    }
  },
  "blocks": [
    {
      "type": "wait",
      "params": {
        "time": [2-5],
        "unit": "seconds"
      }
    },
    {
      "type": "chat",
      "params": {
        "message": "Respawning..."
      }
    },
    {
      "type": "chat",
      "params": {
        "message": "/spawn"
      }
    }
  ]
}

🏪 Shop Automation

Automatically buys items when GUI appears

{
  "name": "Auto Shop",
  "trigger": {
    "type": "on_gui_item",
    "params": {
      "pattern": "Buy (.*) for (\\d+)",
      "var_prefix": "shop",
      "verbose": true
    }
  },
  "blocks": [
    {
      "type": "if",
      "params": {
        "condition": {
          "type": "inventory_contains",
          "params": {
            "search_mode": "registry",
            "item_name": "emerald",
            "var_name": "emeralds"
          }
        },
        "blocks": [
          {
            "type": "click_gui_item",
            "params": {
              "name_pattern": "Buy.*",
              "var_name": "purchased_item"
            }
          },
          {
            "type": "client_message",
            "params": {
              "message": "Purchased: ${purchased_item}"
            }
          }
        ]
      }
    }
  ]
}

📊 Server Status Monitor

Monitors server status with HTTP requests

{
  "name": "Status Monitor",
  "trigger": {
    "type": "interval",
    "params": {
      "interval": 60,
      "unit": "seconds"
    }
  },
  "blocks": [
    {
      "type": "post_request",
      "params": {
        "url": "https://api.example.com/server/status",
        "body": "{\"server\": \"${server_name}\"}",
        "timeout": 5000,
        "response_var": "status"
      }
    },
    {
      "type": "wait",
      "params": {
        "time": 2,
        "unit": "seconds"
      }
    },
    {
      "type": "if",
      "params": {
        "condition": {
          "type": "variable_equals",
          "params": {
            "variable": "status_success",
            "value": "true"
          }
        },
        "blocks": [
          {
            "type": "client_message",
            "params": {
              "message": "Server status: ${status_body}"
            }
          }
        ]
      }
    }
  ]
}

🚀 Advanced Techniques

Random Timing

Use random ranges to make your automation less predictable:

interval: [10-30] - Random 10-30 units
time: [1-5] - Random 1-5 units wait

Regex Patterns

Powerful pattern matching for chat, GUI items, and variables:

.* - Match anything
\\d+ - Match numbers
(.*) - Capture groups for variables
^Start.*End$ - Line anchors

Variable Capture

Many blocks and conditions can capture data into variables:

Chat triggers: var_prefix parameter
Inventory/GUI conditions: var_name parameter
Regex operations: Automatic capture groups

Loop Prevention

Use prevent_execution to avoid spam or conflicts:

Prevent loop after completion
Cooldown periods between actions
Temporary disabling based on conditions

Startup Delay

Configure loops to wait before first execution:

startupDelay - Delay in loop configuration (seconds)
Useful for initialization or sequential timing
Prevents all loops from starting simultaneously
Set via Loop Editor UI or JSON: "startupDelay": 5

Global Verbose Logging

Control debug output for the entire mod:

Toggle button in top-right of Loop Editor screen
When disabled, saves 99.9% of log space
Overrides individual block verbose settings
Essential for performance in production use

Enhanced Number Support

Full support for decimal numbers and variables:

Decimal wait times: time: 2.5, unit: seconds
Variable substitution in all numeric fields
Randomizer support: [1.5-3.0] for decimal ranges
Works in wait blocks, interval triggers, and world_click coordinates

Debugging Tips

Enable verbose mode to see variable states
Use client_message blocks to display debug info
Test with manual triggers first
Use comment blocks for documentation
Start with simple loops and add complexity gradually

Performance Considerations

Use appropriate intervals - avoid too frequent triggers
HTTP requests are async - don't block game performance
Use conditions to avoid unnecessary processing
Clear runtime variables when no longer needed