Peripheral

# Peripheral **Script Minecraft with Python.** Write `.py` scripts that read live game data, control your player, build custom GUIs, and render always-on HUD overlays — all without touching Java. Drop a script in a folder, hit run, and watch it go. --- ## What it does Peripheral runs a lightweight HTTP server inside Minecraft (`localhost:25585`) and injects a helper module called `mc` into every script. Scripts run in the background as you play — reading your health, sending chat messages, drawing on your screen, or moving with scripts. No extra dependencies. No config files to hand-edit. Everything is managed through a clean in-game GUI (press **G**). --- ## Features ### Python scripting - Scripts live in `config/peripheral/scripts/` — edit them in any text editor or in-game - The `mc` module is injected automatically. Just `from mc import *` and go. - Scripts run in the background — start several at once, stop them independently ### AI script builder Open the **Build** tab, type a script name, describe what you want, and the AI writes it directly to the file. Uses your own Claude or OpenAI API key. Chat history is saved so you can pick up where you left off, fix errors by sending logs back to the AI, and manage multiple scripts from the sessions menu. ### Player control `say()` · `look()` · `use_item()` · `equip()` · `jump()` · `sprint()` · `sneak()` · `move()` · `click_block()` · `attack()` · `drop_item()` ### Game data `state()` · `pos()` · `health()` · `inventory()` · `chat_log()` ### HUD overlays Render persistent elements directly on the game screen while you play: - **Labels** — text with color and shadow - **Bars** — progress bars (health, durability, XP, anything) - **Rects** — background panels with optional border - **Item sprites** — render any Minecraft item icon by ID - Anchored to any screen corner or center — positions scale with resolution ### Custom in-game screens `open_gui()` builds real Minecraft screens from Python — buttons, text fields, labels, sliders, checkboxes. Press **H** in-game to show/hide. Scripts keep data live while the screen is open. ` ### Navigation `goto(x, z)` · `nav_status()` ### HTTP API Every endpoint the `mc` module uses is also available externally on `localhost:25585`. Wire up a browser dashboard or a local tool — all without touching the game. --- ## Included example scripts  | Script | What it does | |---|---| | `hello_world.py` | Shows position, health, nearby entities — verify everything works | | `armor_hud.py` | Vertical item-icon + durability HUD on the right side of the screen | | `auto_eat.py` | Automatically eats food when hunger drops | | `auto_mine.py` | Scripts the player to mine a target ore automatically | | `welcome_bot.py` | Greets players when they join | | `follow_on_command.py` | Follows a player when they say "follow me" in chat | | `custom_gui.py` | Full interactive GUI example — buttons, inputs, live updates | | `api_server.py` | Starts a local HTTP server so external apps can read game state | | `openai_chat.py` | Players whisper questions to a configured AI API, it answers in chat | | `server_status.py` | Pings Minecraft servers and shows player counts and MOTD | | `weather_display.py` | Fetches real-world weather and displays it in-game | | `web_dashboard.py` | Browser dashboard — view game state from any tab on your local network | | `clickable_links.py` | Shows how to send rich messages with clickable URLs and hover text | --- ## Still in development This mod is actively being worked on. If you run into any bugs, issues, or have suggestions, please open an issue at **[github.com/Sl0oth/peripheral/issues](https://github.com/Sl0oth/peripheral/issues)**. --- ## Getting started 1. Install the mod (Fabric, 1.21.11 - 26.1) 2. Launch Minecraft — example scripts and `PERIPHERAL_API.md` are written to `config/peripheral/scripts/` automatically 3. Press **G** to open the Peripheral panel 4. Hit **Run** next to any example script 5. To build your own with AI: open the **Build** tab, type a script name, and start chatting --- ## External connections Peripheral's HTTP server only listens on `localhost` and never connects to any remote server on its own. The Build tab sends messages to the Anthropic or OpenAI API using your own key — nothing is sent without you initiating it. Some example scripts make outbound HTTP requests to third-party APIs; this only happens when you explicitly run them, and the endpoints are clearly visible in the script source. --- ## Multiplayer Peripheral gives you tools that can automate player actions. **It is your responsibility to ensure any scripts you run comply with the rules of the server you are playing on.** Many servers prohibit automation mods. When in doubt, check with the server owner before running automation scripts in multiplayer. --- ## Requirements - **Minecraft** 1.21.11 - 26.1 - **Fabric Loader** 0.18.4+ - **Fabric API** --- ## Client-side only Peripheral runs entirely on the client. No server installation needed. Works on singleplayer, multiplayer, and Realms. --- ## Disclaimer This mod is provided as-is with no warranty. The author is not liable for loss of items or game progress, save file corruption, server bans, damages caused by scripts you write or run, or any consequences from connecting the mod to external services. You are solely responsible for any scripts you create or execute. Use of this mod on multiplayer servers is at your own risk — always check server rules first. Full terms at [github.com/Sl0oth/peripheral](https://github.com/Sl0oth/peripheral/blob/main/TERMS.md). --- *100% of the mod code was written by [Claude Code](https://claude.ai/code) (Anthropic's AI coding assistant), directed by Sl0oth.*