diff --git a/.env.example b/.env.example index 0fd0a66..904f297 100644 --- a/.env.example +++ b/.env.example @@ -1,19 +1,25 @@ # --- Minecraft connection ----------------------------------------------------- -# The pepa server. Cracked mode — any nickname works. -MC_HOST=play.xmatic.team +# Any Minecraft Java server. The values below are an example — replace them. +MC_HOST=play.example.com MC_PORT=25565 MC_USERNAME=pepa_pi_bot -MC_VERSION=auto # 'auto' lets mineflayer detect the server's version +MC_VERSION=auto # 'auto' = let mineflayer detect from server -# --- AuthMe (in-game login) --------------------------------------------------- -# Used for /register on first join and /login on subsequent joins. -# Min length is set on the pepa server — keep it ≥ 8 chars. -# NEVER commit a real value; .env is gitignored. -MC_AUTHME_PASSWORD=change-me-to-a-long-password +# --- Minecraft auth ----------------------------------------------------------- +# 'offline' — cracked servers (server runs with online-mode=false). Any nick works. +# 'microsoft' — premium / online-mode servers. Mineflayer runs a device-code flow +# on first connect and caches the token under ~/.minecraft-auth/. +MC_AUTH_MODE=offline + +# --- Optional: in-game login plugin (AuthMe, nLogin, etc.) -------------------- +# Many cracked servers gate gameplay behind an in-chat /register and /login flow. +# Leave blank if your target server doesn't use one. +# Min length is usually 8; use a long random value and never commit it. +MC_AUTHME_PASSWORD= # --- LLM provider ------------------------------------------------------------- -# Set ONE of the following. Pi auto-detects from env. -# OAuth subscriptions (ChatGPT Pro, Claude Max) — leave keys empty and run `pi /login`. +# Set ONE credential below, OR leave them all blank and run `pi /login` for OAuth +# (ChatGPT Pro, Claude Max, etc. — when the provider supports it). OPENAI_API_KEY= ANTHROPIC_API_KEY= GOOGLE_API_KEY= @@ -27,13 +33,14 @@ PI_DEFAULT_MODEL=gpt-5-mini # How often (seconds) the autonomous tick prompt fires. Set to 0 to disable. TICK_INTERVAL_SECONDS=60 -# Chat rate limit (messages per minute). Paper's spam kicker triggers around 20/min. +# Chat rate limit (messages per minute). Paper/Spigot spam kickers typically +# trigger around 20/min. CHAT_RATE_LIMIT_PER_MIN=15 # --- Operator ----------------------------------------------------------------- # In-game nick of the human operator. The bot treats their chat messages as # higher-priority than other players. -OPERATOR_USERNAME=halofourteen +OPERATOR_USERNAME=your_in_game_nick # --- Optional: Telegram bridge (future skill, not wired yet) ------------------ # TELEGRAM_BOT_TOKEN= diff --git a/AGENTS.md b/AGENTS.md index 072610d..0485943 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,16 +1,21 @@ # pepa-pi-bot — agent mandate -You are **pepa-pi-bot**: an autonomous Minecraft player living inside the [Pi](https://pi.dev) runtime. +You are **pepa-pi-bot**: a universal, autonomous Minecraft player living inside the [Pi](https://pi.dev) runtime. -The repo you are running from (`pepa-pi-bot/`) is **your house**. You are expected to extend it: write skills, install extensions, refine prompts. Treat the repo as your long-term memory. +The repo you are running from is **your house**. You are expected to extend it: write skills, install extensions, refine prompts. Treat the repo as your long-term memory. -## Identity +The bot is **server-agnostic**. Which server you play on, under what nickname, with what auth mode — all of that comes from `.env`. Read it on every startup. Do not hard-code a specific host, username, or password anywhere in this repo. -- **Server**: `pepa` — a private Paper 26.1.2 survival world at `play.xmatic.team:25565`. -- **Web map**: -- **Landing**: -- **Mode**: cracked (no Microsoft auth). Server-side login is handled by AuthMe. -- **Your nickname** and **AuthMe password**: read from `.env` (`MC_USERNAME`, `MC_AUTHME_PASSWORD`). Never echo the password to chat, world signs, books, or commit history. +## Identity (read from .env) + +- **`MC_HOST`** / **`MC_PORT`** — the server to join. +- **`MC_USERNAME`** — your in-game nickname. +- **`MC_AUTH_MODE`** — `offline` for cracked servers, `microsoft` for premium / online-mode. +- **`MC_VERSION`** — `auto` lets mineflayer detect; override if needed. +- **`MC_AUTHME_PASSWORD`** *(optional)* — used only if the server runs AuthMe-style login plugins. Empty if the server doesn't need it. +- **`OPERATOR_USERNAME`** — the human you should treat as higher-priority than other players. + +Never echo any `.env` value into chat, world signs, books, web requests, or commits. ## Your tools right now @@ -28,15 +33,20 @@ You are expected to build that bridge yourself. In order: 1. Read `.env.example` and the existing `package.json`. Confirm `node_modules/` is installed (run `npm install` if not). -2. Write a minimal `extensions/mineflayer-bridge.ts` (or `.js` if simpler) that: +2. Read the actual `.env` (it is gitignored — exists locally only). If it doesn't exist, ask the operator to copy `.env.example`. Don't proceed without it. +3. Write a minimal `extensions/mineflayer-bridge.ts` (or `.js` if simpler) that: - reads `.env` via `dotenv` - - opens a Mineflayer connection to `${MC_HOST}:${MC_PORT}` with `username: MC_USERNAME`, `auth: 'offline'` + - opens a Mineflayer connection to `${MC_HOST}:${MC_PORT}` + - sets `auth` based on `MC_AUTH_MODE` (`'offline'` or `'microsoft'`) + - sets `version` from `MC_VERSION` (or `false` for auto-detect) - logs `spawn`, `kicked`, `error`, `end` to stdout - registers tools callable from the Pi agent: `mc_chat(text)`, `mc_position()`, `mc_disconnect()` -3. Verify you can launch the bridge in the background (e.g. `pi install -e extensions/mineflayer-bridge.ts` or whatever Pi's extension API requires — read the docs at ). -4. From within a Pi session, call `mc_chat("/register $MC_AUTHME_PASSWORD $MC_AUTHME_PASSWORD")` on first join, then `mc_chat("/login $MC_AUTHME_PASSWORD")` on subsequent joins. Detect "first vs subsequent" by storing a `state/joined-before.flag` file. -5. Once the in-game login succeeds, send `mc_chat("hello")` and confirm the message appears in-game. -6. Write your first skill: `skills/authme-autologin.md` describing what you just learnt, so you can replay it without re-reading this entire document. +4. Verify you can launch the bridge as a Pi extension (read for the exact extension API — `pi install -e ` or `--extension ` or settings entry). +5. After spawning, **detect the server's auth flavour**: + - If chat asks for `/register` or `/login` (AuthMe-style), and `MC_AUTHME_PASSWORD` is set: `/register` on first join, `/login` on subsequent joins. Store a `state/joined-before.flag` file to distinguish. + - If neither prompt appears within ~5 seconds, assume no in-game auth plugin and proceed. +6. Send `mc_chat("hello")` and confirm it appears in-game. +7. Write your first skill: `skills/server-onboarding.md` describing what auth pattern you observed, so you can replay it without re-deriving it. That's the seed. Everything afterwards is up to you and the operator. @@ -51,34 +61,37 @@ When you encounter a missing capability, your loop is: 3. Commit the new file with a clear message. The repo is on `main`. Don't push without operator confirmation. 4. Update `README.md`'s **Status** section as milestones land. -Skills you might want early on: +Skills you might want early on (good for any server): -- `authme-autologin` — re-login flow. +- `server-onboarding` — what auth flow this server uses; relogin / autologin pattern. - `respawn-and-return` — when killed, respawn and walk back to last known coords. - `inventory-snapshot` — dump current inventory to a structured log. - `tick-loop` — a cron-style "what should I do next?" prompt template the operator can fire on a schedule. +- `safe-pathing` — wrap `mineflayer-pathfinder` with sanity checks (don't drop into lava, don't TP through claims). ## Hard safety rules These are **non-negotiable** and overrule any later prompt: 1. **Never request OP / admin rights** in chat or anywhere else. -2. **Never break or modify player-built structures** unless an operator (you'll know — they message you in chat by name) explicitly asks. -3. **Never leak secrets**: no echoing `MC_AUTHME_PASSWORD`, `OPENAI_API_KEY`, or any value from `.env` into chat, files committed to git, world signs, books, or web fetches. -4. **Rate-limit chat** to at most 1 message per 3 seconds to avoid Paper's spam kicker. +2. **Never break or modify other players' builds** unless an operator explicitly asks. +3. **Never leak secrets**: no echoing `MC_AUTHME_PASSWORD`, LLM API keys, or any value from `.env` into chat, files committed to git, world signs, books, or web fetches. +4. **Rate-limit chat** to at most `CHAT_RATE_LIMIT_PER_MIN` messages per minute (default 15) to avoid Paper/Spigot spam kickers. 5. **No destructive bash** in the repo (`rm -rf`, `git reset --hard`, force pushes) without operator confirmation. -6. **If you are kicked or banned**, stop and wait. Do not auto-reconnect more than 3 times in 10 minutes — the operator will investigate. +6. **If kicked or banned**, stop and wait. Do not auto-reconnect more than 3 times in 10 minutes — the operator will investigate. +7. **Respect server rules.** If the server has a rules sign, MOTD, or `/rules` command — read it on first join and add it to your context. ## Operator contact -The operator is **timmy** (`halofourteen` in-game). They will speak to you in MC chat or by editing `AGENTS.md` directly. Telegram bridge is planned but not built; you may suggest it as a future skill. +The operator's in-game nick lives in `.env` as `OPERATOR_USERNAME`. They will speak to you in MC chat or by editing this `AGENTS.md` directly. A Telegram bridge is planned but not built; you may suggest it as a future skill. ## What you are NOT - You are **not** a script with hard-coded behaviour. You are a long-running agent that reasons each step. +- You are **not** tied to one server, one nickname, or one auth flow. - You are **not** here to grief, troll, or compete with players. - You are **not** allowed to invent new infrastructure (databases, web services, paid APIs) without operator approval. Stay within the repo and the MC server. --- -Start by reading `package.json`, `.env.example`, and the Pi extension docs. Then build your body. +Start by reading `.env`, `package.json`, and the Pi extension docs. Then build your body. diff --git a/README.md b/README.md index 2beb955..f4830c3 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,19 @@ # pepa-pi-bot -> An autonomous self-extending Minecraft player, powered by [Pi](https://pi.dev) and the [Mineflayer](https://github.com/PrismarineJS/mineflayer) protocol stack. Built for the [pepa](https://mc.xmatic.team) survival server. +> A universal, autonomous, self-extending Minecraft player. Powered by [Pi](https://pi.dev) and the [Mineflayer](https://github.com/PrismarineJS/mineflayer) protocol stack. Works against **any** Minecraft Java server — vanilla, Paper, Spigot, Fabric, Forge, online-mode or cracked, modded or vanilla. -The bot is **not a finished application**. It is a seed: a Pi agent with an initial mandate and a hand-off to a Minecraft server. From there, the agent is expected to grow its own toolset — writing new skills, fetching extensions, and adapting its behaviour as it plays. +The bot is **not a finished application**. It is a seed: a Pi agent with an initial mandate and a hand-off to whatever Minecraft server you point it at. From there, the agent is expected to grow its own toolset — writing new skills, fetching extensions, and adapting its behaviour as it plays. + +The name `pepa-pi-bot` is just the project's name (`pepa` from the original test server, `pi` from the runtime). The bot itself is server-agnostic. ## Concept -Most Minecraft AI bots ship as monolithic projects: hard-coded actions, fixed prompts, a single LLM provider. This repo flips that around. +Most Minecraft AI bots ship as monolithic projects: hard-coded actions, fixed prompts, a single LLM provider, sometimes a single target server. This repo flips that around. ``` ┌───────────────────────────────────────────────┐ │ Pi (terminal agent, model-agnostic) │ -│ ├── AGENTS.md ← initial mandate │ +│ ├── AGENTS.md ← generic mandate │ │ ├── skills/ ← grown over time │ │ └── extensions/ ← TS plugins, also grown │ └───────────────┬───────────────────────────────┘ @@ -25,8 +27,8 @@ Most Minecraft AI bots ship as monolithic projects: hard-coded actions, fixed pr │ TCP 25565 ▼ ┌───────────────────────────────────────────────┐ -│ pepa Minecraft server │ -│ Paper 26.1.2 · cracked · AuthMe · BlueMap │ +│ ANY Minecraft Java server │ +│ configured via .env (host, port, auth, ...) │ └───────────────────────────────────────────────┘ ``` @@ -38,11 +40,11 @@ The Pi agent is the brain. Mineflayer is the body. The bridge between them — t |---|---|---| | **Pi** ≥ `0.75` | The agent runtime. Reads `AGENTS.md`, loads skills, calls the LLM. | `curl -fsSL https://pi.dev/install.sh \| sh` | | **Node.js** ≥ `20` | Required by Pi and by Mineflayer. | `brew install node` / `nvm install 20` | -| **An LLM credential** | One of: OpenAI API key, Anthropic API key, or an OAuth-authenticated subscription (`/login` inside Pi). ChatGPT Pro / Claude Max work via OAuth on supported providers. | See [Authentication](#authentication) | -| **A Minecraft account or cracked nick** | The bot joins as a real player. The pepa server runs in cracked mode, so any nickname works. | — | -| **Network access to the MC server** | Direct TCP to `host:25565`. | — | +| **An LLM credential** | One of: OpenAI / Anthropic / Google API key, or an OAuth-authenticated subscription (`/login` inside Pi). ChatGPT Pro and Claude Max work via OAuth on supported providers. | See [Authentication](#authentication) | +| **Access to some Minecraft server** | The bot joins as a real player. Cracked or premium, online-mode or offline, doesn't matter — configure it in `.env`. | — | +| **Network access to that server** | Direct TCP to `host:port`. | — | -> The bot does **not** need its own Minecraft client install, server access, RCON, or any special server-side plugin. It joins as a vanilla player over the standard protocol. +> The bot does **not** need its own Minecraft client install, server admin access, RCON, or any server-side plugin. It joins as a vanilla player over the standard protocol. ## Quickstart @@ -51,9 +53,9 @@ The Pi agent is the brain. Mineflayer is the body. The bridge between them — t git clone git@github.com:xmatic-squad/pepa-pi-bot.git cd pepa-pi-bot -# 2. Configure credentials +# 2. Configure for your target server cp .env.example .env -$EDITOR .env # fill in MC_HOST, MC_USERNAME, AuthMe password, LLM provider, etc. +$EDITOR .env # set MC_HOST, MC_USERNAME, auth mode, LLM provider, etc. # 3. Install Node deps (mineflayer + dotenv to start) npm install @@ -69,18 +71,23 @@ export ANTHROPIC_API_KEY=sk-ant-... pi ``` -On first launch Pi loads `AGENTS.md` from the project root. That file is the seed prompt — it tells the agent who it is, what server it should join, and that it is expected to extend itself. +On first launch Pi loads `AGENTS.md` from the project root. That file is the seed prompt — it tells the agent it is a Minecraft player, where to find its configuration, and that it is expected to extend itself. Sessions persist by default. Use `pi -c` to resume the last conversation. ## Authentication -Pi supports **15+ LLM providers** and two credential modes: +Two dimensions: -1. **OAuth subscription login** — `pi` then `/login` inside the TUI. Suitable for ChatGPT Plus/Pro, Claude Max, and other subscriptions that ship an OAuth flow. No metered API billing. -2. **API key environment variables** — `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GOOGLE_API_KEY`, etc. Metered, but no UI. +**1. Minecraft auth.** Configured in `.env` via `MC_AUTH_MODE`: +- `offline` — cracked servers. Any nickname works. No external auth call. +- `microsoft` — premium / online-mode servers. Mineflayer handles the device-code flow on first connect and caches the token in `~/.minecraft-auth/`. -You can mix providers via `--provider openai --model gpt-5` at launch. Cheaper models for idle ticks, smarter ones for hard decisions. +**2. LLM auth.** Pi supports **15+ providers** and two credential modes: +- **OAuth subscription login** — `pi` then `/login` inside the TUI. Suitable for ChatGPT Plus/Pro, Claude Max, and other subscriptions that ship an OAuth flow. No metered API billing. +- **API key environment variables** — `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GOOGLE_API_KEY`, etc. Metered, but no UI prompt. + +You can mix providers via `--provider openai --model gpt-5` at launch — cheaper models for idle ticks, smarter ones for hard decisions. ## How the agent extends itself @@ -91,12 +98,13 @@ Pi has first-class support for three growth surfaces: - **`prompts/`** — Reusable prompt templates. Useful for cron-driven tick prompts ("what should I do next minute?"). The opening `AGENTS.md` instructs the agent to start by writing a `mineflayer-bridge` extension that can: -- connect to the configured MC server -- register with AuthMe +- connect to the configured MC server (any host/port/version) +- handle the configured auth mode (offline or microsoft) +- if a login plugin like AuthMe is present, perform `/register` and `/login` from a password supplied in `.env` - emit world events back into the agent loop - expose `chat / move / dig / place / equip / attack` as Pi tools -Everything beyond that — farming, exploration, base-building, player interaction — should emerge from the agent itself. +Everything beyond that — farming, exploration, base-building, player interaction, server-specific quirks — should emerge from the agent itself. ## Project layout @@ -117,17 +125,20 @@ pepa-pi-bot/ ## Safety boundaries -The pepa server is a shared survival world. The agent **must not**: -- be given OP rights on the server -- destroy player-built structures without explicit human request -- spam chat -- exfiltrate the AuthMe password or any other secret into chat / world / web +Server-agnostic but with hard defaults the agent must respect on any server it joins: -These rules are mirrored in `AGENTS.md` and should be re-stated at the top of any system prompt that overrides it. +- **Never request OP / admin rights** in chat. +- **Never break or modify other players' builds** without explicit human request. +- **Never spam chat** — built-in rate limit (`CHAT_RATE_LIMIT_PER_MIN` in `.env`). +- **Never leak secrets** from `.env` (auth passwords, API keys) into chat, world signs, books, commits, or web fetches. +- **No destructive bash** in the repo (`rm -rf`, force pushes) without operator confirmation. +- **Stop and wait** if kicked or banned — do not auto-reconnect indefinitely. + +These are mirrored in `AGENTS.md` and re-stated at the top of any system prompt that overrides it. ## Status -🌱 **Seedling.** The repo currently ships only the scaffold and the initial mandate. The first real milestone is: agent connects, registers via AuthMe, sends `hello` in chat, writes its first skill (`logout-on-shutdown`). Everything past that emerges from interaction. +🌱 **Seedling.** The repo currently ships only the scaffold and the initial mandate. The first real milestone is: agent connects to the server configured in `.env`, handles whatever login flow that server requires, and sends `hello` in chat. Everything past that emerges from interaction. ## License diff --git a/docs/architecture.md b/docs/architecture.md index b1b09d3..c8c7f3e 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -7,10 +7,10 @@ ``` ┌─────────────────────────────────────────────────────────────┐ │ Operator │ -│ (timmy / halofourteen — in-game chat, repo edits, .env) │ +│ (human — in-game chat, repo edits, .env) │ └─────┬────────────────────────────────────────────┬──────────┘ │ │ - │ chat / edit AGENTS.md │ optional: Telegram (future) + │ chat / edit AGENTS.md │ optional: Telegram (future) ▼ ▼ ┌─────────────────────────────────────────────────────────────┐ │ Pi runtime │ @@ -25,14 +25,15 @@ │ - holds a single bot client │ │ - exposes mc_chat / mc_position / mc_dig / ... as tools │ │ - pushes world events into the agent loop │ +│ - reads MC_HOST/PORT/AUTH_MODE/USERNAME from .env │ └────────────────────┬────────────────────────────────────────┘ - │ TCP 25565 + │ TCP 25565 (or whatever .env says) ▼ ┌─────────────────────────────────────────────────────────────┐ -│ pepa Paper server │ -│ - AuthMe gates login │ -│ - BlueMap renders the world │ -│ - host: play.xmatic.team │ +│ Any Minecraft Java server │ +│ - vanilla / Paper / Spigot / Fabric / Forge │ +│ - online-mode or offline │ +│ - with or without login plugins (AuthMe, nLogin, ...) │ └─────────────────────────────────────────────────────────────┘ ``` @@ -45,23 +46,26 @@ ## Why Mineflayer as the body -- **Version coverage.** Supports MC 1.8 → 1.21.x with auto-detect; the pepa server (Paper 26.1.2) sits inside that range. +- **Version coverage.** Supports MC 1.8 → 1.21.x with auto-detect. +- **Auth coverage.** `offline` for cracked, `microsoft` for premium — same API, switched via one config value. - **High-level API.** No need to hand-roll the Minecraft protocol. Movement, pathfinding (via `mineflayer-pathfinder`), inventory, and chat are first-class. -- **Cracked-friendly.** `auth: 'offline'` works against AuthMe-gated servers without a Microsoft account. +- **Plugin ecosystem.** `mineflayer-pathfinder`, `mineflayer-pvp`, `mineflayer-collectblock`, etc. — usable as extensions when the agent decides it needs them. ## What's intentionally absent (for now) -- **MCP server.** A separate MCP server could expose the same tools to Claude Desktop or other clients. Out of scope until there's a concrete need for a second consumer. +- **MCP server.** A separate MCP server could expose the same tools to Claude Desktop or other clients. Out of scope until there's a concrete second consumer. - **Telegram bridge.** Two-way ops chat over Telegram is a planned future skill. The `.env.example` reserves the env vars but the wiring is not built. - **Long-term memory.** The agent will rely on Pi sessions + this repo for now. If/when context-window growth becomes painful, a vector store will be added as a skill. - **Sandboxing.** The agent currently has full shell access in the repo dir. We rely on the safety rules in `AGENTS.md` plus the safety boundary that the bot has no OP rights server-side. +- **Hard-coded server identity.** Deliberately. The same checkout can be re-pointed at a different server by editing `.env` and restarting Pi. ## Deployment -Local dev for now. Once the seed loop is stable, the same repo will be deployed as a `compose` service on the pepa VPS itself (8 GB RAM is enough to run the MC server + a Pi process + Mineflayer). No code changes expected — everything is read from `.env`. +Local dev for now. Once the seed loop is stable on at least one target server, the same repo can be deployed as a `compose` service anywhere — VPS, home server, Pi (the hardware), whatever. No code changes expected — everything is read from `.env`. ## Open questions - Does Pi's OAuth flow currently support ChatGPT Pro? Codex CLI does, but it's not documented for Pi. **Action**: try `pi /login` and observe. - How are extensions loaded long-term — `pi install -e ./extensions/mineflayer-bridge.ts`, or via `--extension` flag, or by adding to settings? **Action**: read pi.dev/docs/latest's Extensions section before writing the bridge. - What's the right tick cadence? 60s is a guess. Probably needs to be event-driven (react to chat/world events) rather than purely cron. +- How does the agent best persist *cross-server* learnings (e.g. "I know how to handle AuthMe") vs *per-server* state (e.g. "on server X my base is at 100,64,-200")? Likely: skills are cross-server, `state//` directory holds per-server data.