MEP Mod (Minecraft Embedded Python) is a powerful Fabric mod that seamlessly integrates Python scripting into Minecraft, enabling players and developers to write and execute Python code directly within the game environment.

• 🐍 Full Python Integration - Execute Python scripts directly in Minecraft using JEP (Java Embedded Python)
• ⚡ Dual Execution Modes - Switch between embedded JEP interpreter and native Python execution
• 📝 In-Game Editor - Feature-rich Python code editor accessible via /pythoneditor command
• 🎨 Syntax Highlighting - Multiple color themes (Monokai, Solarized Dark, Dracula, VS Code Dark)
• 📂 Multi-Tab Support - Work on multiple Python scripts simultaneously with tab management
• 💾 Auto-Save & Persistence - Scripts are automatically saved and persist between sessions

• 🔄 Virtual Environment Support - Full integration with Python virtual environments
• 📦 Package Management - Install and manage Python packages directly from the game
• 🔍 System Diagnostics - Built-in diagnostics for Python installation and compiler detection
• 🧩 Java-Python Bridge - Seamlessly call Java methods from Python and vice versa
• 🛡️ Error Handling - Comprehensive error handling with detailed logging and user feedback
• 🎯 Thread-Safe Execution - Safe concurrent Python script execution

• Scrollable Editor - Handle large Python files with smooth scrolling
• Line Numbers - Clear line numbering for easier code navigation
• Keyboard Shortcuts - Intuitive keyboard controls for efficient editing
• Theme Customization - Multiple dark themes optimized for code readability
• Tab Management - Create, rename, and switch between multiple script tabs

For Experienced Users:

# Verify prerequisites
python3 --version  # Need 3.8+
java -version      # Need JDK 25
echo $JAVA_HOME    # Must be set

# Install JEP (Java Embedded Python)
pip install jep==4.3.1

# Build and install
git clone https://github.com/TheyCallMeAbstract/MEPmod.git
cd MEPmod
./gradlew build
cp build/libs/mep-mod-1.0.0.jar ~/.minecraft/mods/

# Launch Minecraft (Fabric profile) and use /pythoneditor

⚠️ Important: This mod requires specific prerequisites. If you encounter errors, see the detailed setup guide.

⚠️ Common Failure Point: Most installation issues are caused by missing C++ build tools or JAVA_HOME not being set. See SETUP.md for detailed platform-specific instructions.

Detailed Instructions: See SETUP.md for comprehensive step-by-step installation guide.

Quick Version (if you have all prerequisites):

1. Install Fabric Loader for Minecraft 26.1-snapshot-1
2. Download Fabric API 0.140.1+26.1 to your mods folder
3. Build or download MEP Mod
4. Copy mep-mod-1.0.0.jar to your Minecraft mods/ folder
5. Launch Minecraft with Fabric profile

After launching Minecraft for the first time:

1. Check logs for successful initialization:

   [MEPMod] Python detected: /usr/bin/python3 (version 3.11.x)
   [MEPMod] JEP installed: Yes (version 4.3.1)
   [MEPMod] MEP Mod initialized successfully!
   

2. If you see errors, consult the Troubleshooting Guide

3. Join a world and test the editor with /pythoneditor

In-game, open chat (T key) and type:

/pythoneditor

Press Enter to open the integrated Python editor GUI.

Screenshot coming soon - editor interface with syntax highlighting and multi-tab support

The Python Editor provides a feature-rich environment for writing and executing Python code within Minecraft:

Main Components:

• Menu Bar - File operations (Save, Load), Edit tools, Theme selection
• Tab System - Work on multiple scripts simultaneously
• Code Editor - Syntax highlighting, line numbers, auto-indentation
• Output Console - View script output, print statements, and errors
• Control Buttons - Run scripts, clear console, toggle execution modes

Key Features:

• 🎨 4 Syntax Themes: Monokai, Dracula, VS Code Dark, Solarized Dark
• 📑 Multi-Tab Support: Work on multiple scripts at once
• 💾 Auto-Save: Scripts save automatically every 30 seconds
• ⌨️ Keyboard Shortcuts: Ctrl+S (save), Ctrl+R (run), Ctrl+Shift+P (command palette)
• 📂 Script Management: Save, load, and organize your Python scripts
• 🔄 Execution Modes: Switch between Embedded (fast) and Native (compatible) modes

Example 1: Hello Minecraft

from com.mepmod.python import JavaInterface

# Get the server instance
server = JavaInterface.getMinecraftServer()

# Broadcast a message to all players
if server:
    JavaInterface.broadcastMessage("Hello from Python!")
    print("✅ Message sent successfully!")
else:
    print("⚠️ Server not available (normal in single-player)")

Example 2: Player Position

from com.mepmod.python import JavaInterface

# Get your current position
position = JavaInterface.getPlayerPosition()
print(f"Your coordinates: {position}")

# Get all online players
players = JavaInterface.getOnlinePlayers()
print(f"Online players: {len(players)}")

Example 3: Using Python Packages

import math
import random

# Generate random coordinates
x = random.randint(-1000, 1000)
z = random.randint(-1000, 1000)
distance = math.sqrt(x**2 + z**2)

print(f"Random location: X={x}, Z={z}")
print(f"Distance from spawn: {distance:.2f} blocks")

Embedded Mode ✅ (Default - Recommended)

• Uses JEP (Java Embedded Python) for direct Java-Python integration
• Advantages:
  • Full access to Java classes and Minecraft API
  • Best performance for Minecraft interactions
  • Direct memory access to game objects
  • No inter-process communication overhead
• Use for: Minecraft-specific scripts, game manipulation, real-time operations

Native Mode (Fallback)

• Uses system Python interpreter in separate process
• Advantages:
  • Better compatibility with some Python packages
  • Easier debugging with standard Python tools
  • Independent from JVM limitations
• Use for: Testing scripts, using incompatible packages, development/debugging

Switch modes using the toggle button in the editor or programmatically:

# Check current mode
from com.mepmod.python import PythonRunner
runner = PythonRunner.getInstance()
print(f"Current mode: {runner.getCurrentMode()}")

Save Your Work:

1. Click File → Save (or press Ctrl+S)
2. For first-time save: File → Save As (or Ctrl+Shift+S)
3. Scripts are saved to: .minecraft/.mepmod/scripts/

Load Existing Scripts:

1. Click File → Load
2. Browse your scripts folder
3. Select a .py file to open in a new tab

Auto-Save Feature:

• Scripts automatically save every 30 seconds while editing
• Unsaved changes are preserved between sessions
• Look for the "●" indicator on modified tabs

Create isolated Python environments for different projects:

from com.mepmod.python import VEManager

# Get the VE manager instance
ve_manager = VEManager.getInstance()

# Create a new virtual environment
ve_manager.createVirtualEnvironment("myproject")

# Install packages
ve_manager.installPackage("myproject", "numpy")
ve_manager.installPackage("myproject", "pandas")

# Activate virtual environment
ve_manager.activateVirtualEnvironment("myproject")

# Now you can use installed packages
import numpy as np
print(f"NumPy version: {np.__version__}")

Virtual environments are stored at:

• Windows: %APPDATA%\.minecraft\.mepmod\venvs\
• Linux/macOS: ~/.minecraft/.mepmod/venvs/

src/main/java/com/mepmod/
├── MEPMod.java                    # Main mod entry point
├── commands/                      # Minecraft command implementations
│   └── PythonEditorCommand.java   # /pythoneditor command
├── gui/                           # GUI components
│   ├── PythonEditorGui.java       # Main editor interface (1200+ lines)
│   ├── PythonEditorGuiFactory.java # Factory for editor instances
│   ├── ScrollableTextEditor.java  # Scrollable text widget
│   ├── EditorMode.java            # Execution mode enum
│   ├── EditorTab.java             # Tab management
│   └── EditorTheme.java           # Syntax highlighting themes
├── mixin/                         # Minecraft mixins
│   └── ExampleMixin.java          # Server lifecycle mixin
└── python/                        # Python integration layer
    ├── PythonRunner.java          # Core execution engine (Singleton)
    ├── JEPLoader.java             # Native library loader (Singleton)
    ├── PythonMode.java            # Execution mode configuration
    ├── JavaInterface.java         # Java utilities for Python scripts
    ├── VEManager.java             # Virtual environment manager
    ├── VEPackageManager.java      # Package installation
    ├── VEConfig.java              # Configuration persistence
    └── diagnostic/                # System diagnostics
        ├── PythonDetector.java    # Python installation detection
        ├── CompilerDetector.java  # Compiler detection (MSVC, GCC)
        └── JEPDiagnostic.java     # JEP system diagnostics

• Singleton: PythonRunner, JEPLoader, VEManager (thread-safe, lazy initialization)
• Factory: PythonEditorGuiFactory for GUI instance creation
• Strategy: PythonMode enum for execution strategy selection
• Command: Fabric command registration pattern
• Observer: Minecraft event listeners for lifecycle management

# Clean build
./gradlew clean build

# Run Minecraft client with mod
./gradlew runClient

# Run Minecraft server with mod
./gradlew runServer

# Run tests
./gradlew test

# Generate IDE configurations
./gradlew vscode      # VS Code
./gradlew eclipse     # Eclipse
./gradlew idea        # IntelliJ IDEA (automatic)

This project follows strict code style guidelines. See CODE_STYLE.md for comprehensive style rules including:

• Naming conventions (PascalCase, camelCase, UPPER_SNAKE_CASE)
• Import organization (Java → Minecraft/Fabric → Third-party → Internal)
• Error handling patterns
• Logging conventions
• Minecraft-specific guidelines

For AI coding agents, see AGENTS.md.

# Run all tests
./gradlew test

# Run specific test class
./gradlew test --tests "com.mepmod.python.PythonRunnerTest"

# Run specific test method
./gradlew test --tests "com.mepmod.python.PythonRunnerTest.testExecutePython"

• SETUP.md - Detailed setup and installation guide
• CODE_STYLE.md - Comprehensive coding standards (467 lines)
• ARCHITECTURE.md - Complete architecture overview
• AGENTS.md - Guidelines for AI coding agents
• docs/JEP-Testing-Guide.md - JEP integration testing guide
• docs/JEP-Integration-Changes.md - JEP integration history

Edit gradle.properties to configure mod versions:

minecraft_version=26.1-snapshot-1
loader_version=0.18.3
fabric_version=0.140.1+26.1
mod_version=1.0.0

Virtual environment configurations are stored in .mepmod/venv_config.json in your Minecraft directory.

❌ "Python not found" / "No Python executable found"

# Verify Python installation
python3 --version  # Must show 3.8 or newer

# Check if Python is in PATH
which python3  # Linux/macOS
where python3  # Windows

Solution: Install Python 3.8+ and ensure it's added to PATH. See SETUP.md - Python Installation

❌ "JEP not installed" / "JEP package not found"

[MEPMod] WARN: JEP is not installed for Python
[MEPMod] ERROR: JEP native library not found

Solution: Install JEP with pip install jep==4.3.1. If this fails, you're likely missing prerequisites. See SETUP.md - JEP Installation

❌ "JAVA_HOME not set" (during JEP installation)

Error: Please set the environment variable JAVA_HOME to a path containing the JDK.

Solution: Set JAVA_HOME environment variable to point to your JDK 25 installation. See SETUP.md - JAVA_HOME Setup

❌ "Microsoft Visual C++ 14.0 is required" (Windows)

error: Microsoft Visual C++ 14.0 or greater is required.

Solution: Install Visual Studio with C++ workload. See SETUP.md - Visual C++ Setup

❌ "Python.h: No such file or directory" (Linux)

fatal error: Python.h: No such file or directory

Solution: Install Python development headers:

sudo apt install python3-dev      # Ubuntu/Debian
sudo dnf install python3-devel    # Fedora/RHEL

❌ "UnsatisfiedLinkError: no jep in java.library.path"

java.lang.UnsatisfiedLinkError: no jep in java.library.path

Solution: JEP native library not in library path. Platform-specific fixes in SETUP.md - Library Path Configuration

❌ Script Execution Issues

• No output: Check execution mode (try Native mode), verify script syntax
• Import errors: Install required packages with pip install package_name
• Crashes: Check Minecraft logs at .minecraft/logs/latest.log

1. Check Comprehensive Troubleshooting: See SETUP.md Troubleshooting Section for detailed solutions

2. Run Diagnostic Tool (in-game):

   from com.mepmod.python.diagnostic import JEPDiagnostic
   JEPDiagnostic.runFullDiagnostic()

3. Check Minecraft Logs:

   # Linux/macOS
   tail -f ~/.minecraft/logs/latest.log
   
   # Windows
   type %APPDATA%\.minecraft\logs\latest.log | more

4. Report Issues:

   • GitHub Issues: https://github.com/TheyCallMeAbstract/MEPmod/issues
   • Include: OS, Python version, Java version, error logs, steps to reproduce

Contributions are welcome! This is an open-source project under CC0 1.0 Universal.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Follow code style guidelines in CODE_STYLE.md
4. Commit your changes (git commit -m 'feat: add amazing feature')
5. Push to the branch (git push origin feature/amazing-feature)
6. Open a Pull Request

Follow conventional commits:

• feat: - New features
• fix: - Bug fixes
• refactor: - Code refactoring
• docs: - Documentation updates
• test: - Test additions or modifications
• chore: - Maintenance tasks

• JEP 4.3.1 - Java Embedded Python interpreter
• Fabric Loader 0.18.3 - Mod loader
• Fabric API 0.140.1+26.1 - Fabric API for Minecraft 26.1
• Log4j2 - Logging framework (provided by Minecraft)

• Gradle 8.x - Build automation
• Fabric Loom 1.14-SNAPSHOT - Gradle plugin for Fabric mods
• Java 25 - Java Development Kit

This project is licensed under CC0 1.0 Universal (Creative Commons Public Domain).

This means you can:

• ✅ Use commercially
• ✅ Modify
• ✅ Distribute
• ✅ Use privately
• ✅ No attribution required (but appreciated!)

See LICENSE for details.

• JEP (Java Embedded Python) - ninia/jep
• Fabric - FabricMC
• Minecraft - Mojang Studios

• Repository: https://github.com/TheyCallMeAbstract/MEPmod
• Issues: https://github.com/TheyCallMeAbstract/MEPmod/issues
• Fabric Documentation: https://fabricmc.net/wiki/
• JEP Documentation: https://github.com/ninia/jep/wiki

Version: 1.0.0-alpha Status: Active Development
Minecraft Version: 26.1-snapshot-1
Last Updated: January 2026

Made with ❤️ by TheyCallMeAbstract

Bringing Python to Minecraft, one script at a time.